@exodus/headless

The platform-agnostic Exodus wallet SDK, including core features such as seed phrase management, transaction signing, blockchain metadata, balances and others.

Table of Contents

• Quick Start
• Lifecycle
• Port
• Adapters
• Config
• Headless API

Quick Start

import createExodus from '@exodus/headless'
import referrals from '@exodus/headless/src/modules/referrals'
import Emitter from '@exodus/wild-emitter'

// 1. Create port. Acts as an event bus between headless wallet and client
const port = new Emitter()

// 2. Instantiate client-specific adapters and config. More details below
const adapters = {}
const config = {}

// 3. Create Exodus container
const exodusContainer = createExodus({ port, adapters, config })

// 4. Register external modules. Does not support overriding modules at the moment.
exodusContainer.register({
  definition: {
    id: 'remoteConfig',
    factory: createRemoteConfig,
    dependencies: ['config', 'fetch', 'logger'],
  },
})

// see an example feature definition:
// ../../features/geolocation/index.js
exodusContainer.use(referrals())
exodusContainer.use(myCustomFeature({ id: 'myCustomFeature', ... }))

// 5. Resolve exodus instance
const exodus = exodusContainer.resolve()

// 6. Start exodus instance
await exodus.wallet.start()

// 7. Use it!
await exodus.wallet.create({ passphrase: 'my-super-secure-passphrase' })

// 8. Use your custom feature API, if any
exodus.myCustomFeature.doThatThingYouDo()

Lifecycle

The headless wallet instance transitions through different states during his life. When moving from one another, there are two things that are triggered:

• Fires hook call: Allows modules to subscribe and halt transition until listener resolves.
• Fires event call: Emitted after all hooks had been executed and resolved.

For more information about lifecycle hooks, please refer to the application feature documentation.

Port

Event bus between headless wallet and client

Method	Type	Description
subscribe	({ type: string, payload: any }) => void	Subscribe to receive events.
unsubscribe	({ type: string, payload: any }) => void	Unsubscribe handler from receiving events.
emit	(type: string, payload: any) => void	Emit an event.

Adapters

Adapters are client-specific implementations of defined APIs needed for the wallet to function.

New adapters will be required by this module as we migrate more modules into it. Below are explained the ones that this module requires at the date.

assetsModule

AssetsModule implementation. Currently being injected as each of our clients have different implementations.

createLogger

A function that returns an instance of the Logger class with the given namespace.

Parameter	Type	Description
namespace	string	The namespace for the logger.

The returned Logger instance has the following methods:

Method	Type	Description
trace	(...args: any[]) => void	Log a message with the trace level.
debug	(...args: any[]) => void	Log a message with the debug level.
log	(...args: any[]) => void	Log a message with the log level.
info	(...args: any[]) => void	Log a message with the info level.
warn	(...args: any[]) => void	Log a message with the warn level.
error	(...args: any[]) => void	Log a message with the error level.

Each method takes any number of arguments, which will be logged as a message with the corresponding log level. The message will be prefixed with the logger's namespace.

legacyPrivToPub

Legacy private to public key transformation function.

An object where each key is an asset name and the value is a function that takes a Buffer and returns a Buffer.

unsafeStorage

Unsafe (raw text) storage instance. Used internally by modules to persist data in client underlying storage layer.

In most cases you probably want to use encrypted storage instead (not yet migrated).

Check storage-spec for more details about Storage API

seedStorage

Storage instance used unquely by wallet module to store seed and autogenerated passphrase (if present).

Check storage-spec for more details about Storage API

Note: Because Browser Extension needs the passphrase to encrypt/decrypt seed, it get's passed as a 3rd parameter to get/set

passphraseCache

An instance of the PassphraseCache class.

Method	Type	Description
set	(passphrase: string) => void	Set the passphrase with the given value.
get	() => string	Get the current passphrase value.
changeTtl	(ttl: number) => void	Change the time-to-live (TTL) value of the passphrase cache.
clear	() => void	Clear the passphrase cache.
scheduleClear	() => void

Config

An object with additional configuration options for the Exodus instance.

Currently not used.

Debugging

Some features expose APIs for easy debugging, troubleshooting, and PR testing. You can access these APIs under exodus.debug. To enable them, simply pass debug: true to the headless factory function:

import createExodus from '@exodus/headless'

const exodusContainer = createExodus({ port, adapters, config, debug: true })

exodusContainer.debug.geolocation.merge({ countryCode: 'US' })

Headless API

wallet

Type: object

Method	Type	Description
exists	async () => boolean	Checks if a wallet exists on the device.
create	async ({ passphrase?: string }) => void	Creates new wallet
import	async ({ mnemonic: string, passphrase?: string, forceRestart?: boolean }) => void	Imports existing wallet
delete	async ({ passphrase?: string }) => void	Deletes wallet. Passphrase is mandatory if wallet was created with one
lock	async () => void	Locks wallet
unlock	async ({ passphrase?: string }) => void	Unlocks wallet. Passphrase is mandatory if wallet was created with one
isLocked	async () => boolean	Checks if wallet is locked
getMnemonic	async () => void	Sets wallet as backed up
changePassphrase	async ({ currentPassphrase?: string. newPassphrase: string }) => void	Change passphrase. Current passphrase is mandatory if wallet was created with one
restoreFromCurrentPhrase	async ({ passphrase?: string }) => void	Restore current wallet. Passphrase is mandatory if wallet was created with one
load	async () => void	Loads UI by rehydratating data through port (BE Only)
unload	async () => void	Unloads UI by rehydratating data through port (BE Only)
changeLockTimer	async ({ ttl: number }) => void	Change auto unlock ttl (BE Only)

walletAccounts

Type: object

Method	Type	Description
create	async (walletAccountFields) => void	Creates a new WalletAccount with the provided fields.
update	async (name, walletAccountFields) => void	Updates an existing WalletAccount with the provided fields.
enable	async (name) => void	Enables an existing WalletAccount.
disable	async (name) => void	Disables an existing WalletAccount.
getEnabled	async () => object	Returns enabled walletAccounts as { [name]: WalletAccount }.

blockchainMetadata

Type: object

Method	Type	Description
getTxLog	async ({ assetName, walletAccount }) => TxSet	Get the TxSet for the provided assetName/walletAccount combination (AssetSource)
getLoadedTxLogs	async () => object	Get the all loaded TxSets as a { [walletAccount]: { [assetName]: TxSet } } object
updateTxs	async ({ assetName: string, walletAccount: string, txs: object[] }) => void	Add or update txs with updates provided in txs
overwriteTxs	async ({ assetName: string, walletAccount: string, txs: object[], notifyReceivedTxs: ?boolean }) => void	Overwrite specified txs.
clearTxs	async ({ assetName: string, walletAccount: string }) => void	Remove txs for AssetSource.
removeTxs	async ({ assetName: string, walletAccount: string, txs: object[] }) => void	Remove provided txs.
getAccountState	async ({ assetName, walletAccount }) => AccountState	Get the AccountState for the provided AssetSource
getLoadedAccountStates	async () => object	Get the all loaded AccountStates as a { [walletAccount]: { [assetName]: AccountState } } object
updateAccountState	async ({ assetName: string, walletAccount: string, newData: object }) => void	Update accountState for AssetSource.
removeAccountState	async ({ assetName: string, walletAccount: string }) => void	Remove accountState for AssetSource.
batch	() => Batch	Create a batch of updates. See blockchainMetadata README for batching details.

assets

Type: object

Method	Type	Description
enable	async (assetNames: string[]) => void	Enables assets.
disable	async (assetNames: string[]) => void	Disables assets.
addAndEnableToken	async (assetId: string, baseAssetName: string) => string	Adds and enables a custom token. Returns the created asset's .name

locale

Type: object

Method	Type	Description
setCurrency	async (currency: string) => void	Changes current currency.
setLanguage	async (language: string) => void	Changes current language.

subscribe

Type: function

Argument	Type	Description
subscribe	({ type: string, payload: any }) => void	Subscribe to receive events.
unsubscribe	({ type: string, payload: any }) => void	Unsubscribe handler from receiving events.

featureFlags

Type: object

Method	Type	Description
enable	async (featureName: string) => void	Enables a feature-flag gated feature.
disable	async (featureName: string) => void	Disables a feature-flag gated feature.

See more details.