@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

``js
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.

$3

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

$3

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.

$3

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.

$3

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

$3

duplicated storage but to be used only for migrations. so that we can unlock storage but other parts of app still can't access it.

$3

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

$3

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:

`js
import createExodus from '@exodus/headless'

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

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

Headless API

$3

> 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) |

$3

> 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 }. |

$3

> 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. |

$3

> 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 |

$3

> Type: object

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

$3

> 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. |

$3

> 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.