@exodus/headless 1.1.0

package/CHANGELOG.md

@@ -0,0 +1,10 @@
+# Change Log
+
+All notable changes to this project will be documented in this file.
+See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
+
+## 1.1.0 (2023-03-28)
+
+### Features
+
+- add headless module ([#996](https://github.com/ExodusMovement/exodus-hydra/issues/996)) ([0ea954e](https://github.com/ExodusMovement/exodus-hydra/commit/0ea954e378f1afd1881ddcdde63546772157327e))

package/README.md

@@ -0,0 +1,150 @@
+# @exodus/headless
+
+The headless Exodus wallet SDK
+
+## Quick Start
+
+```js
+import createExodus from '@exodus/headless'
+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 container = createExodus({ port, adapters, config })
+
+// 4. Register external modules. Does not support overriding modules at the moment.
+container.register({
+  definition: {
+    id: 'remoteConfig',
+    factory: createRemoteConfig,
+    dependencies: ['config', 'fetch', 'logger'],
+  },
+})
+
+// 5. Resolve exodus instance
+const exodus = container.resolve()
+
+// 6. Use it!
+await exodus.wallet.create({ passphrase: 'my-super-secure-passphrase' })
+```
+
+## Port
+
+Event bus between headless wallet and client
+
+| Method               | Type                                       | Description                                |
+| -------------------- | ------------------------------------------ | ------------------------------------------ |
+| subscribe            | `({ type: string, payload: any }) => void` | Subscribe to receive events.               |
+| unsubscribe(handler) | `({ 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](https://github.com/ExodusMovement/exodus-hydra/tree/master/modules/storage-spec) for more details about Storage API
+
+### seco
+
+An object with methods to encrypt and decrypt strings.
+
+| Method        | Type                                                           | Description     |
+| ------------- | -------------------------------------------------------------- | --------------- |
+| encryptString | `({ data: string, key: string, encoding?: string }) => string` | Encrypt string. |
+| decryptString | `({ data: string, key: string, encoding?: string }) => string` | Decrypt string. |
+
+### 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.
+
+## 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 }) => 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`)                                                |
+
+## isMnemonicValid
+
+> Type: function
+
+| Argument | Type       | Description                  |
+| -------- | ---------- | ---------------------------- |
+| mnemonic | `string`   | Mnemonic to check validity.  |
+| wordlist | `string[]` | Words list to check against. |
+
+**Returns**: `boolean`

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "@exodus/headless",
+  "version": "1.1.0",
+  "description": "The headless Exodus wallet SDK",
+  "author": "Exodus Movement Inc",
+  "main": "src/index.js",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ExodusMovement/exodus-hydra.git"
+  },
+  "homepage": "https://github.com/ExodusMovement/exodus-hydra/tree/master/modules/headless",
+  "license": "UNLICENSED",
+  "bugs": {
+    "url": "https://github.com/ExodusMovement/exodus-hydra/issues?q=is%3Aissue+is%3Aopen+label%3Aheadless"
+  },
+  "files": [
+    "src",
+    "README.md",
+    "CHANGELOG.md",
+    "!**/__tests__",
+    "!**/*.test.js"
+  ],
+  "scripts": {
+    "lint": "eslint . --ignore-path ../../.gitignore",
+    "lint:fix": "yarn lint --fix",
+    "test": "jest"
+  },
+  "dependencies": {
+    "@exodus/atoms": "^2.9.0",
+    "@exodus/dependency-injection": "^1.2.0",
+    "@exodus/dependency-preprocessors": "^2.0.2",
+    "@exodus/fetch": "^1.2.1",
+    "@exodus/key-identifier-provider": "^1.1.1",
+    "@exodus/keychain": "^3.2.1",
+    "@exodus/module": "^1.0.0",
+    "@exodus/wallet": "4.1.0",
+    "@exodus/wallet-compatibility-modes": "1.0.1",
+    "bip39": "2.6.0",
+    "lodash": "https://registry.yarnpkg.com/@exodus/lodash/-/lodash-4.17.21-exodus.2.tgz",
+    "minimalistic-assert": "^1.0.1"
+  },
+  "devDependencies": {
+    "@exodus/ethereum-lib": "^2.22.2",
+    "@exodus/solana-lib": "^1.3.11",
+    "@exodus/storage-memory": "^1.1.0",
+    "@exodus/wild-emitter": "^1.0.0",
+    "eslint": "^8.33.0",
+    "jest": "^29.1.2"
+  },
+  "gitHead": "e5126f0fa052ef08113c4eb66c450172dbfa3012"
+}

package/src/api.js

@@ -0,0 +1,34 @@
+import { validateMnemonic as isMnemonicValid } from 'bip39'
+
+const createApi = ({ ioc }) => {
+  const { passphraseCache } = ioc.getByType('adapter')
+
+  const { application, wallet } = ioc.getByType('module')
+
+  return {
+    wallet: {
+      exists: () => wallet.exists(),
+      load: application.load,
+      unload: application.unload,
+      create: application.create,
+      lock: application.lock,
+      unlock: application.unlock,
+      import: application.import,
+      delete: application.delete,
+      getMnemonic: application.getMnemonic,
+      setBackedUp: application.setBackedUp,
+      changePassphrase: application.changePassphrase,
+      restoreFromCurrentPhrase: async ({ passphrase } = {}) => {
+        if (!passphrase) passphrase = await passphraseCache.get()
+        const mnemonic = await application.getMnemonic({ passphrase })
+
+        await application.import({ passphrase, mnemonic })
+      },
+      changeLockTimer: application.changeLockTimer,
+      isLocked: () => wallet.isLocked(),
+    },
+    isMnemonicValid,
+  }
+}
+
+export default createApi

package/src/application.js

@@ -0,0 +1,246 @@
+/* eslint-disable unicorn/no-for-loop */
+
+import ExodusModule from '@exodus/module'
+import assert from 'minimalistic-assert'
+
+// Because we are forced to restart wallet after deleting/importing, we need to store certain flags to persist state between executions
+
+// Triggers deletetion logic when wallet starts.
+// Set as true on delete method is called, and set to false when wallet is restarted
+const DELETE_FLAG = 'deleteFlag'
+
+// Triggers import logic when wallet starts. Used when overwriting existing wallet (not importing one from scratch)
+// Set as true on import method is called, and set to false when wallet is restarted
+const IMPORT_FLAG = 'importFlag'
+
+// Triggers restore logic. We need to do it after any import, no matter if there was a previous wallet or not
+// Set as true on import method is called, and set to false after restore is completed
+const RESTORE_FLAG = 'restoreFlag'
+
+const HOOKS = Object.freeze({
+  lock: 'lock',
+  unlock: 'unlock',
+  clear: 'clear',
+  import: 'import',
+  migrate: 'migrate',
+  start: 'start',
+  load: 'load',
+  unload: 'unload',
+  create: 'create',
+  backup: 'backup',
+  restore: 'restore',
+  'restore-completed': 'restore-completed',
+  'assets-synced': 'assets-synced',
+  'change-passphrase': 'change-passphrase',
+})
+
+class Application extends ExodusModule {
+  #hooks = {}
+  #wallet = null
+  #storage = null
+  #passphraseCache = null
+  #applicationStarted = null
+  #resolveStart = null
+
+  constructor({ wallet, unsafeStorage, passphraseCache, logger }) {
+    super({ name: 'Application', logger })
+
+    this.#wallet = wallet
+    this.#passphraseCache = passphraseCache
+    this.#storage = unsafeStorage.namespace('flags')
+
+    this.#applicationStarted = new Promise((resolve) => (this.#resolveStart = resolve))
+  }
+
+  start = async () => {
+    const [deleteFlag, importFlag] = await this.#storage.batchGet([DELETE_FLAG, IMPORT_FLAG])
+
+    const isDeleting = !!deleteFlag
+    const isImporting = !!importFlag
+
+    if (isDeleting) await this.#wallet.clear()
+
+    if (isDeleting || isImporting) {
+      await this.#storage.batchDelete([DELETE_FLAG, IMPORT_FLAG])
+      await this.#passphraseCache.clear()
+      await this.fire(HOOKS.clear)
+    }
+
+    if (isImporting) await this.fire(HOOKS.import)
+
+    await this.fire(HOOKS.start)
+    await this.#autoUnlock()
+
+    const locked = await this.#wallet.isLocked()
+    this._logger.log('wallet is locked', locked)
+
+    this.#resolveStart()
+  }
+
+  load = async () => {
+    await this.#applicationStarted
+
+    const [walletExists, hasPassphraseSet, isLocked, isBackedUp] = await Promise.all([
+      this.#wallet.exists(),
+      this.#wallet.hasPassphraseSet(),
+      this.#wallet.isLocked(),
+      this.#wallet.isBackedUp(),
+    ])
+
+    await this.fire(HOOKS.load, { walletExists, hasPassphraseSet, isLocked, isBackedUp })
+  }
+
+  unload = async () => {
+    await this.#applicationStarted
+    await this.#passphraseCache.scheduleClear()
+    await this.fire(HOOKS.unload)
+  }
+
+  hook = (hookName, listener) => {
+    assert(HOOKS[hookName], `no such hook: ${hookName}`)
+
+    if (!this.#hooks[hookName]) {
+      this.#hooks[hookName] = []
+    }
+
+    this.#hooks[hookName].push(listener)
+  }
+
+  fire = async (hookName, params) => {
+    assert(HOOKS[hookName], `no such hook: ${hookName}`)
+    this._logger.debug('firing hooks', hookName)
+
+    const hooks = this.#hooks[hookName] || []
+
+    for (let i = 0; i < hooks.length; i++) {
+      await hooks[i](params)
+    }
+
+    this.emit(hookName, params)
+  }
+
+  create = async (opts) => {
+    this._logger.log('creating wallet')
+
+    await this.#applicationStarted
+    await this.#wallet.create(opts)
+
+    await this.fire(HOOKS.create, { hasPassphraseSet: !!opts?.passphrase })
+  }
+
+  import = async (opts) => {
+    this._logger.log('importing wallet')
+
+    await this.#storage.set(RESTORE_FLAG, true)
+
+    await this.#applicationStarted
+
+    if (await this.#wallet.exists()) {
+      await this.#wallet.import(opts)
+      await this.#storage.set(IMPORT_FLAG, true)
+
+      this.emit('restart')
+
+      return
+    }
+
+    await this.#wallet.import(opts)
+    await this.fire(HOOKS.import)
+
+    this._logger.log('wallet imported')
+  }
+
+  getMnemonic = async (opts) => this.#wallet.getMnemonic(opts)
+
+  setBackedUp = async () => {
+    await this.#wallet.setBackedUp()
+    await this.fire(HOOKS.backup)
+  }
+
+  lock = async (opts) => {
+    this._logger.log('locking')
+
+    await this.#applicationStarted
+    await this.#wallet.lock(opts)
+    await this.#passphraseCache.clear()
+    await this.fire(HOOKS.lock)
+
+    this._logger.log('locked')
+  }
+
+  #restoreIfNeeded = async () => {
+    const isRestoring = await this.isRestoring()
+
+    if (isRestoring) {
+      await this.fire(HOOKS.restore)
+      await this.#storage.delete(RESTORE_FLAG)
+      await this.fire(HOOKS['restore-completed'])
+    }
+
+    this.fire(HOOKS['assets-synced'])
+  }
+
+  #autoUnlock = async () => {
+    const walletLocked = await this.#wallet.isLocked()
+    const passphrase = await this.#passphraseCache.get()
+
+    if (!walletLocked || !passphrase) return
+
+    try {
+      this._logger.log('unlocking with cache')
+
+      await this.#wallet.unlock({ passphrase })
+      await this.fire(HOOKS.unlock)
+
+      this.#restoreIfNeeded()
+
+      this._logger.log('unlocked with cache')
+    } catch (err) {
+      this._logger.error('failed to unlock, outdated cached passphrase?', err)
+    }
+  }
+
+  unlock = async ({ passphrase } = {}) => {
+    this._logger.log('unlocking')
+
+    await this.#applicationStarted
+    await this.#wallet.unlock({ passphrase })
+
+    await this.fire(HOOKS.migrate)
+    await this.fire(HOOKS.unlock)
+
+    this.#restoreIfNeeded()
+
+    if (passphrase) this.#passphraseCache.set(passphrase)
+
+    this._logger.log('unlocked')
+  }
+
+  changePassphrase = async ({ currentPassphrase, newPassphrase }) => {
+    this._logger.log('changing passphrase')
+
+    await this.#applicationStarted
+    await this.#wallet.changePassphrase({ currentPassphrase, newPassphrase })
+    await this.#passphraseCache.set(newPassphrase)
+    await this.fire(HOOKS['change-passphrase'])
+
+    this._logger.log('passphrase changed')
+  }
+
+  delete = async () => {
+    await this.#storage.set(DELETE_FLAG, true)
+    this.emit('restart')
+  }
+
+  changeLockTimer = async ({ ttl }) => {
+    await this.#passphraseCache.changeTtl(ttl)
+  }
+
+  isRestoring = async () => {
+    return this.#storage.get(RESTORE_FLAG)
+  }
+}
+
+const createApplication = (args = {}) => new Application({ ...args })
+
+export default createApplication

package/src/dependencies/adapters.js

@@ -0,0 +1,6 @@
+import { wrapConstant } from './utils'
+
+const createAdapterDependencies = ({ adapters }) =>
+  Object.entries(adapters).map(([id, value]) => wrapConstant({ id, type: 'adapter', value }))
+
+export default createAdapterDependencies

package/src/dependencies/atoms.js

@@ -0,0 +1,15 @@
+import { createInMemoryAtom } from '@exodus/atoms'
+import { withType } from './utils'
+
+const createAtomDependencies = () =>
+  [
+    {
+      definition: {
+        id: 'lockedAtom',
+        factory: () => createInMemoryAtom({ defaultValue: true }),
+        dependencies: [],
+      },
+    },
+  ].map(withType('atom'))
+
+export default createAtomDependencies

package/src/dependencies/configs.js

@@ -0,0 +1,14 @@
+import { withType } from './utils'
+
+const createConfigDependencies = ({ config }) => {
+  return [
+    {
+      definition: {
+        id: 'config',
+        factory: () => config,
+      },
+    },
+  ].map(withType('config'))
+}
+
+export default createConfigDependencies

package/src/dependencies/index.js

@@ -0,0 +1,44 @@
+/* eslint-disable unicorn/prefer-array-flat */
+/* eslint-disable unicorn/prefer-spread */
+
+import assert from 'minimalistic-assert'
+
+import createConfigDependencies from './configs'
+import createAdapterDependencies from './adapters'
+import createAtomDependencies from './atoms'
+import createModuleDependencies from './modules'
+import { wrapConstant } from './utils'
+
+const adapterKeys = [
+  // ...
+  'assetsModule',
+  'createLogger',
+  'legacyPrivToPub',
+  'seco',
+  'unsafeStorage',
+]
+
+const createDependencies = ({ adapters, config }) => {
+  assert(config, 'expected config object')
+
+  adapterKeys.forEach((key) => assert(adapters[key], `expected adapter "${key}"`))
+
+  const logger = adapters.createLogger('exodus')
+
+  const configs = createConfigDependencies({ adapters, config })
+
+  const modules = createModuleDependencies({ adapters, config })
+
+  const atoms = createAtomDependencies({ adapters, config })
+
+  const adaptersTree = createAdapterDependencies({ adapters, config })
+
+  return []
+    .concat(adaptersTree)
+    .concat(configs)
+    .concat(modules)
+    .concat(atoms)
+    .concat(wrapConstant({ id: 'logger', type: 'module', value: logger }))
+}
+
+export default createDependencies

package/src/dependencies/modules.js

@@ -0,0 +1,46 @@
+import { createKeychain } from '@exodus/keychain'
+import walletDefinition from '@exodus/wallet/module'
+import createKeyIdentifierProvider from '@exodus/key-identifier-provider'
+import walletCompatibilityModesDefinition from '@exodus/wallet-compatibility-modes/module'
+
+import createApplication from '../application'
+import { withType } from './utils'
+
+const createModuleDependencies = () =>
+  [
+    {
+      definition: {
+        id: 'application',
+        factory: createApplication,
+        dependencies: ['unsafeStorage', 'passphraseCache', 'wallet', 'logger'],
+      },
+    },
+    {
+      definition: {
+        id: 'keyIdentifierProvider',
+        factory: createKeyIdentifierProvider,
+        dependencies: [],
+      },
+    },
+    {
+      definition: {
+        id: 'keychain',
+        factory: createKeychain,
+        dependencies: ['legacyPrivToPub'],
+      },
+    },
+    {
+      definition: walletDefinition,
+      aliases: [
+        {
+          implementationId: 'unsafeStorage',
+          interfaceId: 'storage',
+        },
+      ],
+    },
+    {
+      definition: walletCompatibilityModesDefinition,
+    },
+  ].map(withType('module'))
+
+export default createModuleDependencies

package/src/dependencies/utils.js

@@ -0,0 +1,14 @@
+export const wrapConstant = ({ id, type, value }) => ({
+  definition: { id, type, factory: () => value },
+})
+
+export const insertIf = (module, enabled) => {
+  return enabled ? [module] : []
+}
+
+export const withType =
+  (type) =>
+  ({ definition, ...rest }) => ({
+    ...rest,
+    definition: { type, ...definition },
+  })

package/src/index.js

@@ -0,0 +1,38 @@
+import createIOC from './ioc'
+import createApi from './api'
+
+const createExodus = ({ adapters, config, port }) => {
+  const ioc = createIOC({ adapters, config })
+
+  const resolve = () => {
+    ioc.resolve()
+
+    const { assetsModule } = ioc.getByType('adapter')
+
+    const { application } = ioc.getByType('module')
+
+    application.hook('start', () => {
+      port.emit('start')
+    })
+
+    application.hook('unlock', async () => {
+      await assetsModule.load()
+    })
+
+    application.hook('clear', async () => {
+      await Promise.all([assetsModule.clear()])
+    })
+
+    application.on('restart', () => {
+      port.emit('restart')
+    })
+
+    application.start()
+
+    return createApi({ ioc })
+  }
+
+  return { ...ioc, resolve }
+}
+
+export default createExodus

package/src/ioc.js

@@ -0,0 +1,23 @@
+import createIocContainer from '@exodus/dependency-injection'
+import preprocess from '@exodus/dependency-preprocessors'
+import alias from '@exodus/dependency-preprocessors/src/preprocessors/alias'
+import logify from '@exodus/dependency-preprocessors/src/preprocessors/logify'
+import namespaceConfig from '@exodus/dependency-preprocessors/src/preprocessors/namespace-config'
+
+import createDependencies from './dependencies'
+
+const createIOC = ({ adapters, config }) => {
+  const { createLogger } = adapters
+
+  const logger = createLogger('exodus:ioc')
+  const dependencies = createDependencies({ adapters, config })
+  const preprocessors = [logify({ createLogger }), namespaceConfig(), alias()]
+  const definitions = preprocess({ dependencies, preprocessors })
+  const ioc = createIocContainer({ logger })
+
+  ioc.registerMultiple(definitions)
+
+  return ioc
+}
+
+export default createIOC