@exodus/hardware-wallets 1.0.0

package/README.md

@@ -0,0 +1,158 @@
+# @exodus/hardware-wallets
+
+This feature is a high level abstraction for interacting with hardware wallet devices.
+
+|       Feature        | Supported |
+| :------------------: | :-------: |
+| Syncing Public Keys  |    ✅     |
+| Signing Transactions |    ✅     |
+|   Signing Messages   |    ✅     |
+| Firmware Management  |    ❌     |
+
+## Device Support Matrix
+
+| Manufacturer | Device Model | Supported |
+| :----------: | :----------: | :-------: |
+|    Ledger    |    Nano S    |    ✅     |
+|    Ledger    |   Nano S+    |    ✅     |
+|    Ledger    |    Nano X    |    ✅     |
+|    Ledger    |     Stax     |    ✅     |
+|    Trezor    |     One      |    ❌     |
+|    Trezor    |      T       |    ❌     |
+|    Trezor    |    Safe 3    |    ❌     |
+|    Trezor    |    Safe 5    |    ❌     |
+
+## Usage
+
+### With IoC
+
+```typescript
+import hardwareWallets from '@exodus/hardware-wallets'
+
+ioc.use(hardwareWallets())
+```
+
+## Architecture
+
+### Terminology
+
+A bit of terminology might be required to properly understand the distinctions between the various "states" of an asset.
+
+- **supported** assets: All assets supported by our implementation for the device.
+- **installed** assets: All assets supported by our implementation AND installed on the device by the user.
+- **useable** assets: All assets supported by our implementation, installed on the device AND opened on the device (ledger).
+- **synced** assets: All assets for which the public keys have been synced to the wallet account fusion channel.
+
+### `scan({ assetName, accountIndexes, addressLimit, addressOffset })`
+
+The `scan` functions is used during onboarding to retrieve the addresses (n=2) starting at `addressOffset` for each account index in `accountIndexes` from the hardware wallet device. It retrieves the corresponding balance using an network API call. Calling this function does not make any permanent state changes and all its state is ephemeral. This function serves to allow the user to "scan" the accounts, their addresses and balances without having to commit to an account index & syncing it completely yet.
+
+> [!CAUTION]
+> This function must only be used during onboarding of a hardware wallet device.
+
+```mermaid
+sequenceDiagram
+    Consumer->>+HardwareWallets: scan({ assetName, accountIndexes, addressOffset })
+    HardwareWallets->>+HardwareWalletDevice: getAddress({ assetName, derivationPath })
+    HardwareWalletDevice-->>-HardwareWallets: address0
+    HardwareWallets->>+HardwareWalletDevice: getAddress({ assetName, derivationPath })
+    HardwareWalletDevice-->>-HardwareWallets: address1
+    HardwareWallets->>+Asset: api.getBalanceForAddress(address0)
+    Asset-->>-HardwareWallets: balance0
+    HardwareWallets->>+Asset: api.getBalanceForAddress(address1)
+    Asset-->>-HardwareWallets: balance1
+    HardwareWallets-->>-Consumer: First N addresses with balance <br> for given account indexes
+
+```
+
+### `sync({ accountIndex })`
+
+Synchronizes public keys (XPUBs / public keys) for all useable assets for a given `accountIndex` from a hardware wallet device and stores them temporarily for future use. The hardware wallet device may disconnect after this method has been called and onboarding would still be possible.
+
+> [!CAUTION]
+> Only a subset of the supported assets may be synced. Some hardware wallet devices like Ledger do not support multiple assets at the same time because the asset-specific application must be installed and opened on the device.
+
+```mermaid
+sequenceDiagram
+    participant Consumer
+    participant HardwareWallets
+    participant Device
+    participant BaseAsset
+
+    Consumer->>HardwareWallets: sync({ accountIndex })
+    activate HardwareWallets
+
+    HardwareWallets->>Device: listUseableAssetNames()
+    activate Device
+    Device-->>HardwareWallets: [assetName0, assetName1, ...]
+    deactivate Device
+
+    loop for each assetName
+        HardwareWallets->>BaseAsset: getSupportedPurposes({ compatibilityMode: 'ledger' })
+        activate BaseAsset
+        BaseAsset-->>HardwareWallets: [purpose0, purpose1, ...]
+        deactivate BaseAsset
+
+        loop for each purpose
+            alt getXPub is supported
+                HardwareWallets->>Device: getXPub({ assetName, derivationPath })
+                activate Device
+                Device-->>HardwareWallets: xpub
+                deactivate Device
+                HardwareWallets->>HardwareWallets: Store keyIdentifier and xpub
+            else getPublicKey instead
+                HardwareWallets->>Device: getPublicKey({ assetName, derivationPath })
+                activate Device
+                Device-->>HardwareWallets: publicKey
+                deactivate Device
+                HardwareWallets->>HardwareWallets: Store keyIdentifier and publicKey
+            end
+        end
+    end
+
+    HardwareWallets->>HardwareWallets: Generate random ID
+    HardwareWallets->>HardwareWallets: Store keys in syncedKeysMap with ID
+
+    HardwareWallets-->>Consumer: SyncedKeysId
+    deactivate HardwareWallets
+
+```
+
+### `addPublicKeysToWalletAccount({ walletAccountName, syncedKeysId })`
+
+Adds public keys (XPUBS / public keys) to an existing wallet account.
+
+- Moves the synchronized public keys (XPUBs / public keys) for `syncedKeysId` identifier from the temporary in-memory objectmap to a `walletAccounts`'s public key store which will store it in fusion.
+- Start a restore procedure for the assets & trigger a refresh of the `txLogMonitor`
+
+```mermaid
+sequenceDiagram
+    participant Consumer
+    participant HardwareWallets
+    participant PublicKeyStore
+    participant RestoreProgressTracker
+    participant TxLogMonitors
+
+    Consumer->>HardwareWallets: addPublicKeysToWalletAccount({ walletAccountName, syncedKeysId })
+    activate HardwareWallets
+
+    HardwareWallets->>HardwareWallets: Retrieve keys from syncedKeysMap using syncedKeysId
+    Note right of HardwareWallets: Retrieves assetNames and keysToSync
+
+    loop for each key in keysToSync
+        HardwareWallets->>PublicKeyStore: add({ walletAccountName, keyIdentifier, xpub, publicKey })
+
+    end
+
+    loop for each assetName in assetNames
+        HardwareWallets->>RestoreProgressTracker: restoreAsset(assetName)
+        HardwareWallets->>TxLogMonitors: update({ assetName, refresh: true })
+    end
+
+    deactivate HardwareWallets
+    HardwareWallets-->>Consumer: void
+```
+
+### `create({ syncedKeysId })`
+
+Creates a new hardware wallet account and calls `addPublicKeysToWalletAccount()` to synchronize public keys to the newly created wallet account.

package/lib/api/index.d.ts

@@ -0,0 +1,21 @@
+import type { HardwareWallets } from '../module/hardware-wallets.js';
+declare const hardwareWalletsApiDefinition: {
+    readonly id: "hardwareWalletsApi";
+    readonly type: "api";
+    readonly factory: ({ hardwareWallets }: {
+        hardwareWallets: HardwareWallets;
+    }) => {
+        hardwareWallets: {
+            isDeviceConnected: () => Promise<boolean>;
+            listUseableAssetNames: () => Promise<string[]>;
+            canAccessAsset: ({ assetName }: import("../module/interfaces.js").CanAccessAssetParams) => Promise<boolean>;
+            ensureApplicationIsOpened: ({ assetName }: import("../module/interfaces.js").EnsureApplicationIsOpenedParams) => Promise<void>;
+            scan: ({ assetName, accountIndexes, addressLimit, addressOffset, }: import("../module/interfaces.js").ScanParams) => Promise<import("../module/interfaces.js").ScanResult>;
+            sync: ({ accountIndex }: import("../module/interfaces.js").SyncParams) => Promise<import("../module/interfaces.js").SyncedKeysId>;
+            addPublicKeysToWalletAccount: ({ walletAccountName, syncedKeysId, }: import("../module/interfaces.js").StoreSyncedKeysParams) => Promise<void>;
+            create: ({ syncedKeysId }: import("../module/interfaces.js").CreateParams) => Promise<void>;
+        };
+    };
+    readonly dependencies: readonly ["hardwareWallets"];
+};
+export default hardwareWalletsApiDefinition;

package/lib/api/index.js

@@ -0,0 +1,21 @@
+const createHardwareWalletsApi = ({ hardwareWallets }) => {
+    return {
+        hardwareWallets: {
+            isDeviceConnected: hardwareWallets.isDeviceConnected,
+            listUseableAssetNames: hardwareWallets.listUseableAssetNames,
+            canAccessAsset: hardwareWallets.canAccessAsset,
+            ensureApplicationIsOpened: hardwareWallets.ensureApplicationIsOpened,
+            scan: hardwareWallets.scan,
+            sync: hardwareWallets.sync,
+            addPublicKeysToWalletAccount: hardwareWallets.addPublicKeysToWalletAccount,
+            create: hardwareWallets.create,
+        },
+    };
+};
+const hardwareWalletsApiDefinition = {
+    id: 'hardwareWalletsApi',
+    type: 'api',
+    factory: createHardwareWalletsApi,
+    dependencies: ['hardwareWallets'],
+};
+export default hardwareWalletsApiDefinition;

package/lib/index.d.ts

@@ -0,0 +1,32 @@
+declare const hardwareWallets: () => {
+    readonly id: "hardwareWallets";
+    readonly definitions: readonly [{
+        readonly definition: {
+            readonly id: "hardwareWalletsApi";
+            readonly type: "api";
+            readonly factory: ({ hardwareWallets }: {
+                hardwareWallets: import("./module/hardware-wallets.js").HardwareWallets;
+            }) => {
+                hardwareWallets: {
+                    isDeviceConnected: () => Promise<boolean>;
+                    listUseableAssetNames: () => Promise<string[]>;
+                    canAccessAsset: ({ assetName }: import("./module/interfaces.js").CanAccessAssetParams) => Promise<boolean>;
+                    ensureApplicationIsOpened: ({ assetName }: import("./module/interfaces.js").EnsureApplicationIsOpenedParams) => Promise<void>;
+                    scan: ({ assetName, accountIndexes, addressLimit, addressOffset, }: import("./module/interfaces.js").ScanParams) => Promise<import("./module/interfaces.js").ScanResult>;
+                    sync: ({ accountIndex }: import("./module/interfaces.js").SyncParams) => Promise<import("./module/interfaces.js").SyncedKeysId>;
+                    addPublicKeysToWalletAccount: ({ walletAccountName, syncedKeysId, }: import("./module/interfaces.js").StoreSyncedKeysParams) => Promise<void>;
+                    create: ({ syncedKeysId }: import("./module/interfaces.js").CreateParams) => Promise<void>;
+                };
+            };
+            readonly dependencies: readonly ["hardwareWallets"];
+        };
+    }, {
+        readonly definition: {
+            readonly id: "hardwareWallets";
+            readonly type: "module";
+            readonly factory: (opts: import("./module/hardware-wallets.js").Dependencies) => import("./module/hardware-wallets.js").HardwareWallets;
+            readonly dependencies: readonly ["assetsModule", "logger", "ledgerDiscovery", "userInterface", "publicKeyStore", "wallet", "walletAccountsAtom", "walletAccounts", "txLogMonitors", "restoreProgressTracker"];
+        };
+    }];
+};
+export default hardwareWallets;

package/lib/index.js

@@ -0,0 +1,16 @@
+import hardwareWalletsApiDefinition from './api/index.js';
+import hardwareWalletsModuleDefinition from './module/hardware-wallets.js';
+const hardwareWallets = () => {
+    return {
+        id: 'hardwareWallets',
+        definitions: [
+            {
+                definition: hardwareWalletsApiDefinition,
+            },
+            {
+                definition: hardwareWalletsModuleDefinition,
+            },
+        ],
+    };
+};
+export default hardwareWallets;

package/lib/module/errors.d.ts

@@ -0,0 +1,4 @@
+export declare class UserCancelledError extends Error {
+    name: string;
+    constructor();
+}

package/lib/module/errors.js

@@ -0,0 +1,6 @@
+export class UserCancelledError extends Error {
+    name = 'UserCancelledError';
+    constructor() {
+        super('User cancelled action');
+    }
+}

package/lib/module/hardware-wallets.d.ts

@@ -0,0 +1,39 @@
+import { WalletAccount } from '@exodus/models';
+import type { HardwareSignerProvider, CanAccessAssetParams, CreateParams, StoreSyncedKeysParams, ScanParams, SyncParams, EnsureApplicationIsOpenedParams, SignTransactionParams, ScanResult, SyncedKeysId } from './interfaces.js';
+import type { HardwareWalletDiscovery, SignMessageParams } from '@exodus/hw-common';
+import type { Atom } from '@exodus/atoms';
+import type { IPublicKeyStore } from '@exodus/public-key-store';
+import type { Logger } from '@exodus/logger';
+export type Dependencies = {
+    assetsModule: any;
+    ledgerDiscovery: HardwareWalletDiscovery;
+    logger: Logger;
+    userInterface: any;
+    publicKeyStore: IPublicKeyStore;
+    wallet: any;
+    walletAccountsAtom: Atom<WalletAccount>;
+    walletAccounts: any;
+    txLogMonitors: any;
+    restoreProgressTracker: any;
+};
+export declare class HardwareWallets implements HardwareSignerProvider {
+    #private;
+    constructor({ assetsModule, ledgerDiscovery, logger, userInterface, publicKeyStore, wallet, walletAccountsAtom, walletAccounts, txLogMonitors, restoreProgressTracker, }: Dependencies);
+    signTransaction: ({ baseAssetName, unsignedTx, walletAccount }: SignTransactionParams) => Promise<any>;
+    signMessage: ({ assetName, derivationPath, message }: SignMessageParams) => Promise<any>;
+    isDeviceConnected: () => Promise<boolean>;
+    canAccessAsset: ({ assetName }: CanAccessAssetParams) => Promise<boolean>;
+    listUseableAssetNames: () => Promise<string[]>;
+    ensureApplicationIsOpened: ({ assetName }: EnsureApplicationIsOpenedParams) => Promise<void>;
+    scan: ({ assetName, accountIndexes, addressLimit, addressOffset, }: ScanParams) => Promise<ScanResult>;
+    sync: ({ accountIndex }: SyncParams) => Promise<SyncedKeysId>;
+    addPublicKeysToWalletAccount: ({ walletAccountName, syncedKeysId, }: StoreSyncedKeysParams) => Promise<void>;
+    create: ({ syncedKeysId }: CreateParams) => Promise<void>;
+}
+declare const hardwareWalletsModuleDefinition: {
+    readonly id: "hardwareWallets";
+    readonly type: "module";
+    readonly factory: (opts: Dependencies) => HardwareWallets;
+    readonly dependencies: readonly ["assetsModule", "logger", "ledgerDiscovery", "userInterface", "publicKeyStore", "wallet", "walletAccountsAtom", "walletAccounts", "txLogMonitors", "restoreProgressTracker"];
+};
+export default hardwareWalletsModuleDefinition;

package/lib/module/hardware-wallets.js

@@ -0,0 +1,326 @@
+import assert from 'minimalistic-assert';
+import { WalletAccount } from '@exodus/models';
+import randomBytes from 'randombytes';
+import delay from 'delay';
+import { UserCancelledError } from './errors.js';
+export class HardwareWallets {
+    #assetsModule;
+    #ledgerDiscovery;
+    #logger;
+    #userInterface;
+    #publicKeyStore;
+    #wallet;
+    #walletAccountsAtom;
+    #walletAccounts;
+    #txLogMonitors;
+    #restoreProgressTracker;
+    #syncedKeysMap = new Map();
+    constructor({ assetsModule, ledgerDiscovery, logger, userInterface, publicKeyStore, wallet, walletAccountsAtom, walletAccounts, txLogMonitors, restoreProgressTracker, }) {
+        this.#assetsModule = assetsModule;
+        this.#ledgerDiscovery = ledgerDiscovery;
+        this.#logger = logger;
+        this.#userInterface = userInterface;
+        this.#publicKeyStore = publicKeyStore;
+        this.#wallet = wallet;
+        this.#walletAccountsAtom = walletAccountsAtom;
+        this.#walletAccounts = walletAccounts;
+        this.#txLogMonitors = txLogMonitors;
+        this.#restoreProgressTracker = restoreProgressTracker;
+    }
+    #requestUserAction = async (params) => {
+        const rpc = this.#userInterface.getRPC();
+        return rpc.callMethod('handle-hardware-wallet', params);
+    };
+    #signGeneric = async ({ baseAssetName, scenario, sign }) => {
+        let needUserApproval = true;
+        let attempts = 0;
+        const MAX_ATTEMPTS = 50;
+        while (attempts < MAX_ATTEMPTS) {
+            try {
+                if (needUserApproval) {
+                    this.#requestUserAction({
+                        scenario,
+                        baseAssetName,
+                    });
+                    needUserApproval = false;
+                }
+                const hardwareDevice = await this.#ledgerDiscovery.getFirstDevice();
+                await hardwareDevice.ensureApplicationIsOpened(baseAssetName);
+                const result = await sign({ hardwareDevice });
+                this.#requestUserAction({ scenario: 'completed' });
+                return result;
+            }
+            catch (error) {
+                if (error.message.includes('timeout')) {
+                    break;
+                }
+                if (error.name === 'DisconnectedDeviceDuringOperation') {
+                    await this.#requestUserAction({
+                        scenario,
+                        baseAssetName,
+                    });
+                    continue;
+                }
+                try {
+                    const { tryAgain } = await this.#requestUserAction({
+                        error,
+                        baseAssetName,
+                    });
+                    if (!tryAgain) {
+                        this.#logger.warn(error);
+                        break;
+                    }
+                }
+                catch (_error) {
+                    this.#logger.error(_error);
+                    break;
+                }
+            }
+            finally {
+                attempts++;
+                await delay(200);
+            }
+        }
+        this.#requestUserAction({ scenario: 'completed' });
+        throw new UserCancelledError();
+    };
+    signTransaction = async ({ baseAssetName, unsignedTx, walletAccount }) => {
+        const baseAsset = this.#assetsModule.getAsset(baseAssetName);
+        const accountIndex = walletAccount.index;
+        const sign = async ({ hardwareDevice }) => {
+            return baseAsset.api.signHardware({
+                unsignedTx,
+                hardwareDevice,
+                accountIndex,
+            });
+        };
+        return this.#signGeneric({ baseAssetName, scenario: 'signTransaction', sign });
+    };
+    signMessage = async ({ assetName, derivationPath, message }) => {
+        const baseAssetName = this.#assetsModule.getAsset(assetName).baseAsset.name;
+        const sign = async ({ hardwareDevice }) => {
+            return hardwareDevice.signMessage({
+                assetName: baseAssetName,
+                derivationPath,
+                message,
+            });
+        };
+        return this.#signGeneric({ baseAssetName, scenario: 'signMessage', sign });
+    };
+    isDeviceConnected = async () => {
+        try {
+            const devices = await this.#ledgerDiscovery.list();
+            return devices.length > 0;
+        }
+        catch {
+            return false;
+        }
+    };
+    canAccessAsset = async ({ assetName }) => {
+        const asset = this.#assetsModule.getAsset(assetName);
+        const device = await this.#ledgerDiscovery.getFirstDevice();
+        const useableAssetNames = new Set(await device.listUseableAssetNames());
+        return useableAssetNames.has(asset.baseAsset.name);
+    };
+    listUseableAssetNames = async () => {
+        const device = await this.#ledgerDiscovery.getFirstDevice();
+        return device.listUseableAssetNames();
+    };
+    ensureApplicationIsOpened = async ({ assetName }) => {
+        const asset = this.#assetsModule.getAsset(assetName);
+        let i = 0;
+        while (i < 3) {
+            try {
+                const hardwareDevice = await this.#ledgerDiscovery.getFirstDevice();
+                await hardwareDevice.ensureApplicationIsOpened(asset.baseAsset.name);
+            }
+            catch (error) {
+                this.#logger.log(error);
+            }
+            finally {
+                await delay(1000);
+                i++;
+            }
+        }
+    };
+    #getAddress = async ({ assetName, accountIndex, addressIndex }) => {
+        const asset = this.#assetsModule.getAsset(assetName);
+        const supportedPurposes = asset.baseAsset.api.getSupportedPurposes({
+            compatibilityMode: 'ledger',
+        });
+        const { derivationPath } = asset.baseAsset.api.getKeyIdentifier({
+            compatibilityMode: 'ledger',
+            purpose: supportedPurposes[0],
+            accountIndex,
+            chainIndex: 0,
+            addressIndex,
+        });
+        const device = await this.#ledgerDiscovery.getFirstDevice();
+        return device.getAddress({
+            assetName,
+            derivationPath,
+        });
+    };
+    #getXPUB = async ({ device, baseAsset, purpose, accountIndex, }) => {
+        const keyIdentifier = baseAsset.api.getKeyIdentifier({
+            compatibilityMode: 'ledger',
+            purpose,
+            accountIndex,
+            chainIndex: undefined,
+            addressIndex: undefined,
+        });
+        const { derivationPath } = keyIdentifier;
+        const xpub = await device
+            .getXPub({
+            assetName: baseAsset.name,
+            derivationPath,
+        })
+            .catch((error) => {
+            if (error.name === 'XPubUnsupportedError') {
+                this.#logger.warn(`Retrieving XPUBs for ${baseAsset.name} is not supported`, error);
+            }
+            else {
+                throw error;
+            }
+        });
+        return xpub ? { keyIdentifier, xpub } : null;
+    };
+    #getPublicKey = async ({ device, baseAsset, purpose, accountIndex, }) => {
+        const keyIdentifier = baseAsset.api.getKeyIdentifier({
+            compatibilityMode: 'ledger',
+            purpose,
+            accountIndex,
+        });
+        const { derivationPath } = keyIdentifier;
+        const publicKey = await device.getPublicKey({
+            assetName: baseAsset.name,
+            derivationPath,
+        });
+        return { keyIdentifier, publicKey };
+    };
+    #fetchBalance = async ({ asset, address }) => {
+        try {
+            return await asset.api.getBalanceForAddress(address);
+        }
+        catch {
+            return null;
+        }
+    };
+    #getFirstNAddresses = async ({ assetName, accountIndex, n, offsetBy, }) => {
+        const asset = this.#assetsModule.getAsset(assetName);
+        const startIndex = offsetBy;
+        const addresses = [];
+        for (let idx = startIndex; idx < startIndex + n; idx++) {
+            addresses.push(await this.#getAddress({ assetName, accountIndex, addressIndex: idx }));
+        }
+        const fetchedBalances = await Promise.all(addresses.map(async (address) => ({
+            address,
+            balance: await this.#fetchBalance({ asset, address }),
+        })));
+        const addressToBalanceMap = Object.create(null);
+        fetchedBalances.forEach(({ address, balance }) => {
+            addressToBalanceMap[address] = balance;
+        });
+        return addressToBalanceMap;
+    };
+    scan = async ({ assetName, accountIndexes, addressLimit = 2, addressOffset = 0, }) => {
+        let usedAccountIndexes = [];
+        if (await this.#wallet.exists()) {
+            const walletAccounts = Object.values(await this.#walletAccountsAtom.get());
+            usedAccountIndexes = walletAccounts
+                .filter(({ source }) => source === WalletAccount.LEDGER_SRC)
+                .map(({ index }) => index);
+        }
+        const accounts = accountIndexes.map((accountIndex) => ({ accountIndex }));
+        for (const account of accounts) {
+            const addressToBalanceMap = await this.#getFirstNAddresses({
+                assetName,
+                accountIndex: account.accountIndex,
+                n: addressLimit,
+                offsetBy: addressOffset,
+            });
+            account.addressToBalanceMap = addressToBalanceMap;
+            account.mayAlreadyBeSynced = usedAccountIndexes.includes(account.accountIndex);
+        }
+        return accounts;
+    };
+    sync = async ({ accountIndex }) => {
+        const keysToSync = [];
+        const device = await this.#ledgerDiscovery.getFirstDevice();
+        const useableAssetNames = new Set(await device.listUseableAssetNames());
+        for (const assetName of useableAssetNames) {
+            const asset = this.#assetsModule.getAsset(assetName);
+            assert(asset, `asset with ${assetName} was not found`);
+            const baseAsset = asset.baseAsset;
+            const supportedPurposes = baseAsset.api.getSupportedPurposes({
+                compatibilityMode: 'ledger',
+            });
+            for (const purpose of supportedPurposes) {
+                const { keyIdentifier, xpub, publicKey, } = (await this.#getXPUB({ device, baseAsset, purpose, accountIndex })) ||
+                    (await this.#getPublicKey({ device, baseAsset, purpose, accountIndex }));
+                keysToSync.push([keyIdentifier, { xpub, publicKey }]);
+            }
+        }
+        const id = randomBytes(16).toString('hex');
+        this.#syncedKeysMap.set(id, {
+            accountIndex,
+            assetNames: useableAssetNames,
+            keysToSync,
+        });
+        return id;
+    };
+    addPublicKeysToWalletAccount = async ({ walletAccountName, syncedKeysId, }) => {
+        assert(this.#syncedKeysMap.has(syncedKeysId), `no synchronized keys found for id ${syncedKeysId}`);
+        const { assetNames, keysToSync } = this.#syncedKeysMap.get(syncedKeysId);
+        for (const [keyIdentifier, keys] of keysToSync) {
+            const { xpub, publicKey } = keys;
+            await this.#publicKeyStore.add({ walletAccountName, keyIdentifier, xpub, publicKey });
+        }
+        for (const assetName of assetNames) {
+            if (assetName === 'ethereum' || assetName === 'matic') {
+                this.#restoreProgressTracker.restoreAsset('ethereum');
+                this.#restoreProgressTracker.restoreAsset('matic');
+                this.#txLogMonitors.update({ assetName: 'ethereum', refresh: true });
+                this.#txLogMonitors.update({ assetName: 'matic', refresh: true });
+            }
+            else {
+                this.#restoreProgressTracker.restoreAsset(assetName);
+                this.#txLogMonitors.update({ assetName, refresh: true });
+            }
+        }
+    };
+    create = async ({ syncedKeysId }) => {
+        assert(this.#syncedKeysMap.has(syncedKeysId), `no synchronized keys found for id ${syncedKeysId}`);
+        const { accountIndex } = this.#syncedKeysMap.get(syncedKeysId);
+        const walletAccount = new WalletAccount({
+            label: `Ledger${accountIndex === 0 ? '' : ' ' + accountIndex}`,
+            icon: 'ledger',
+            source: WalletAccount.LEDGER_SRC,
+            index: accountIndex,
+            id: randomBytes(32).toString('hex'),
+        });
+        const walletAccountName = walletAccount.toString();
+        await this.#walletAccounts.create(walletAccount);
+        await this.#walletAccounts.setActive(walletAccountName);
+        await this.addPublicKeysToWalletAccount({ walletAccountName, syncedKeysId });
+    };
+}
+const createHardwareWalletsModule = (opts) => new HardwareWallets(opts);
+const hardwareWalletsModuleDefinition = {
+    id: 'hardwareWallets',
+    type: 'module',
+    factory: createHardwareWalletsModule,
+    dependencies: [
+        'assetsModule',
+        'logger',
+        'ledgerDiscovery',
+        'userInterface',
+        'publicKeyStore',
+        'wallet',
+        'walletAccountsAtom',
+        'walletAccounts',
+        'txLogMonitors',
+        'restoreProgressTracker',
+    ],
+};
+export default hardwareWalletsModuleDefinition;

package/lib/module/index.d.ts

@@ -0,0 +1,2 @@
+export * from './interfaces.js';
+export { default } from './hardware-wallets.js';

package/lib/module/index.js

@@ -0,0 +1,2 @@
+export * from './interfaces.js';
+export { default } from './hardware-wallets.js';

package/lib/module/interfaces.d.ts

@@ -0,0 +1,121 @@
+import type { WalletAccount } from '@exodus/models';
+import type { HardwareWalletDevice, SignMessageParams } from '@exodus/hw-common';
+import type KeyIdentifier from '@exodus/key-identifier';
+export interface HardwareSignerProvider {
+    isDeviceConnected: () => Promise<boolean>;
+    canAccessAsset: ({ assetName }: CanAccessAssetParams) => Promise<boolean>;
+    listUseableAssetNames: () => Promise<string[]>;
+    ensureApplicationIsOpened: ({ assetName }: EnsureApplicationIsOpenedParams) => Promise<void>;
+    scan: ({ assetName, accountIndexes, addressOffset }: ScanParams) => Promise<ScanResult>;
+    sync: ({ accountIndex }: SyncParams) => Promise<SyncedKeysId>;
+    addPublicKeysToWalletAccount: ({ walletAccountName, syncedKeysId, }: StoreSyncedKeysParams) => Promise<void>;
+    create: ({ syncedKeysId }: CreateParams) => Promise<void>;
+    signTransaction: ({ baseAssetName, unsignedTx, walletAccount, }: SignTransactionParams) => Promise<any>;
+    signMessage: ({ assetName, derivationPath, message }: SignMessageParams) => Promise<any>;
+}
+type Asset = {
+    name: string;
+    baseAsset: Asset;
+    api: {
+        getKeyIdentifier(params: {
+            purpose: number;
+            accountIndex: number;
+            chainIndex?: number;
+            addressIndex?: number;
+            compatibilityMode?: string;
+        }): KeyIdentifier;
+    };
+};
+export interface CanAccessAssetParams {
+    assetName: string;
+}
+export interface EnsureApplicationIsOpenedParams {
+    assetName: string;
+}
+export interface GetFirstNAddressesParams {
+    assetName: string;
+    accountIndex: number;
+    n: number;
+    offsetBy: number;
+}
+export type GetFirstNAddressesResult = Record<string, any>;
+export interface ScanParams {
+    assetName: string;
+    accountIndexes: number[];
+    addressLimit?: number;
+    addressOffset: number;
+}
+export type ScannedAccount = {
+    accountIndex: number;
+    addressToBalanceMap: GetFirstNAddressesResult;
+    mayAlreadyBeSynced: boolean;
+};
+export type ScanResult = ScannedAccount[];
+export interface SyncParams {
+    accountIndex: number;
+}
+export type SyncedKeysId = string;
+export interface SyncedKeysData {
+    accountIndex: number;
+    assetNames: Set<string>;
+    keysToSync: KeyToSyncData[];
+}
+export type KeyToSyncData = [KeyIdentifier, {
+    xpub?: string;
+    publicKey?: Readonly<Uint8Array>;
+}];
+export interface StoreSyncedKeysParams {
+    walletAccountName: string;
+    syncedKeysId: SyncedKeysId;
+}
+export interface CreateParams {
+    syncedKeysId: SyncedKeysId;
+}
+export type GenericSignCallback = ({ hardwareDevice, }: {
+    hardwareDevice: HardwareWalletDevice;
+}) => Promise<any>;
+export interface GenericSignParams {
+    baseAssetName: string;
+    scenario: string;
+    sign: GenericSignCallback;
+}
+export interface SignTransactionParams {
+    baseAssetName: string;
+    unsignedTx: UnsignedTransaction;
+    walletAccount: WalletAccount;
+}
+export interface UnsignedTransaction {
+    txData: any;
+    txMeta: any;
+}
+export interface GetAddressParams {
+    assetName: string;
+    accountIndex: number;
+    addressIndex: number;
+}
+export interface GetXPUBParams {
+    device: HardwareWalletDevice;
+    baseAsset: Asset;
+    purpose: number;
+    accountIndex: number;
+}
+export type GetXPUBResult = {
+    keyIdentifier: KeyIdentifier;
+    xpub: string;
+};
+export interface GetPublicKeyParams {
+    device: HardwareWalletDevice;
+    baseAsset: Asset;
+    purpose: number;
+    accountIndex: number;
+}
+export type GetPublicKeyResult = {
+    keyIdentifier: KeyIdentifier;
+    publicKey: Readonly<Uint8Array>;
+};
+export interface FetchBalanceParams {
+    asset: any;
+    address: string;
+}
+export type FetchBalanceResult = any | null;
+export {};

package/lib/module/interfaces.js

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "@exodus/hardware-wallets",
+  "version": "1.0.0",
+  "description": "An Exodus SDK feature that provides a high level abstraction for interacting with hardware wallet devices",
+  "author": "Exodus Movement, Inc.",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ExodusMovement/exodus-hydra.git"
+  },
+  "homepage": "https://github.com/ExodusMovement/exodus-hydra/tree/master/features/hardware-wallets",
+  "license": "UNLICENSED",
+  "bugs": {
+    "url": "https://github.com/ExodusMovement/exodus-hydra/issues?q=is%3Aissue+is%3Aopen+label%3Ahardware-wallets"
+  },
+  "main": "lib/index.js",
+  "type": "module",
+  "files": [
+    "lib/",
+    "CHANGELOG.md",
+    "!**/__tests__/**"
+  ],
+  "scripts": {
+    "build": "run -T tsc --build tsconfig.build.json",
+    "clean": "run -T tsc --build --clean",
+    "lint": "run -T eslint . --ignore-path ../../.gitignore",
+    "lint:fix": "yarn lint --fix",
+    "test": "run -T jest",
+    "prepublishOnly": "yarn run -T build --scope @exodus/hardware-wallets"
+  },
+  "dependencies": {
+    "@exodus/models": "^11.7.0",
+    "delay": "^5.0.0",
+    "minimalistic-assert": "^1.0.1",
+    "randombytes": "^2.1.0"
+  },
+  "devDependencies": {
+    "@exodus/atoms": "^8.0.0",
+    "@exodus/hw-common": "^2.2.1",
+    "@exodus/logger": "^1.2.2",
+    "@exodus/public-key-store": "^1.2.2"
+  },
+  "gitHead": "73cd1e81c69bd252bf1bdef0862223b9660a7fdf"
+}