@exodus/hw-ledger 1.0.0

package/README.md

@@ -0,0 +1,92 @@
+# @exodus/hw-ledger
+
+```mermaid
+flowchart LR
+    AA[TransportFactory] --> A
+    A[LedgerDiscovery] -->|"list()"| B(HardwareWalletDescriptor)
+    B --> |"get()"| C(LedgerDevice)
+    C --> |"getAddress()"| D{Pick by \nasset}
+    D -->|bitcoin| E[BitcoinHandlers]
+    D -->|ethereum| F[EthereumHandlers]
+    D -->|solana| G[SolanaHandlers]
+```
+
+## Usage
+
+```typescript
+import createLedgerDiscover from '@exodus/hw-ledger'
+import Transport from '@ledgerhq/hw-transport-node-speculos'
+
+// Initialize transport factories depending on the platform
+const ledgerDiscovery = createLedgerDiscover({
+  logger,
+  transports: {
+    tcp: Transport, // emulator transport over tcp
+  },
+})
+
+const ledgerDescriptors = await ledgerDiscovery.list()
+// [
+//   {
+//       manufacturer: 'ledger',
+//       transportType: 'tcp',
+//       get: function () => { ... }
+//   }
+// ]
+
+let ledgerDevice = null
+try {
+  ledgerDevice = await ledgerDescriptors[0].get()
+} catch (err) {
+  // Instantiating the device may fail, deal with this.
+  // e.g unplugged, udev issues, no networking
+  logger.error(`Unable to connect to device.`, err)
+}
+
+if (ledgerDevice) {
+  const address = await ledgerDevice.getAddress({
+    assetName: 'bitcoin',
+    derivationPath: `m/86'/0'/0'/0/0`,
+  })
+  logger.log(`bitcoin address is ${address}`)
+  // bc1p5cyxnuxmeuwuvkwfem96lqzszd02n6xdcjrs20cac6yqjjwudpxqkedrcr
+}
+```
+
+## Development
+
+If you're on Linux then it's highly likely that you'll want to setup your udev rules.
+
+### Installing Ledger Emulator (Recommended)
+
+Get the Docker images
+
+```bash
+docker pull ghcr.io/ledgerhq/speculos
+docker image tag ghcr.io/ledgerhq/speculos speculos
+```
+
+Clone the speculos repository & change your current working directory
+
+```bash
+git clone https://github.com/LedgerHQ/speculos.git
+cd speculos
+```
+
+Launch the emulator while within the `speculos` directory
+
+```bash
+docker run --rm -it -v "$(pwd)"/apps:/speculos/apps \
+-p 1234:1234 -p 5000:5000 -p 40000:40000 -p 41000:41000 speculos \
+--model nanos ./apps/btc.elf --sdk 2.0 --seed "secret" --display headless --apdu-port 40000 --vnc-port 41000
+```
+
+Now visit http://127.0.0.1:5000 to interact with the emulator.
+
+### Install udev rules for real devices (Linux only)
+
+If you want to talk with real devices then you might require setting up udev rules.
+
+```bash
+sudo ./scripts/setup_udev.sh
+```

package/lib/assets/bitcoin.d.ts

@@ -0,0 +1,3 @@
+import type Transport from '@ledgerhq/hw-transport';
+import type { HardwareWalletDevice } from '@exodus/hw-common';
+export default function (transport: Transport): Promise<HardwareWalletDevice>;

package/lib/assets/bitcoin.js

@@ -0,0 +1,21 @@
+import AppBtc from '@ledgerhq/hw-app-btc';
+export default async function (transport) {
+    const app = new AppBtc({ transport });
+    return {
+        getAddress: async (params) => {
+            throw new Error('implement me');
+        },
+        getXPub: async (params) => {
+            throw new Error('implement me');
+        },
+        getPublicKey: async (params) => {
+            throw new Error('implement me');
+        },
+        signTransaction: async (params) => {
+            throw new Error('implement me');
+        },
+        signMessage: async (params) => {
+            throw new Error('implement me');
+        },
+    };
+}

package/lib/assets/index.d.ts

@@ -0,0 +1,5 @@
+import type Transport from '@ledgerhq/hw-transport';
+import type { HardwareWalletDevice } from '@exodus/hw-common';
+type HandlerFactory = (transport: Transport) => Promise<HardwareWalletDevice>;
+export declare const assetHandlerFactories: Record<string, HandlerFactory>;
+export {};

package/lib/assets/index.js

@@ -0,0 +1,4 @@
+import bitcoin from './bitcoin';
+export const assetHandlerFactories = {
+    bitcoin,
+};

package/lib/constants.d.ts

@@ -0,0 +1 @@
+export declare const APDU_PORT = 40000;

package/lib/constants.js

@@ -0,0 +1 @@
+export const APDU_PORT = 40000;

package/lib/device.d.ts

@@ -0,0 +1,13 @@
+import type { GetAddressParams, GetPublicKeyParams, GetXPubParams, HardwareWalletDevice, SignMessageParams, SignTransactionParams } from '@exodus/hw-common';
+import type Transport from '@ledgerhq/hw-transport';
+export declare class LedgerDevice implements HardwareWalletDevice {
+    #private;
+    constructor({ transport }: {
+        transport: Transport;
+    });
+    getAddress: (params: GetAddressParams) => Promise<string>;
+    getXPub: (params: GetXPubParams) => Promise<string>;
+    getPublicKey: (params: GetPublicKeyParams) => Promise<Readonly<Uint8Array>>;
+    signTransaction: (params: SignTransactionParams) => Promise<Readonly<Uint8Array>>;
+    signMessage: (params: SignMessageParams) => Promise<Readonly<Uint8Array>>;
+}

package/lib/device.js

@@ -0,0 +1,33 @@
+import assert from 'minimalistic-assert';
+import { assetHandlerFactories } from './assets';
+export class LedgerDevice {
+    #transport;
+    constructor({ transport }) {
+        this.#transport = transport;
+    }
+    #getAssetHandler = async (assetName) => {
+        const handlerFactory = assetHandlerFactories[assetName];
+        assert(handlerFactory, `ledger does not support ${assetName}`);
+        return handlerFactory(this.#transport);
+    };
+    getAddress = async (params) => {
+        const handler = await this.#getAssetHandler(params.assetName);
+        return handler.getAddress(params);
+    };
+    getXPub = async (params) => {
+        const handler = await this.#getAssetHandler(params.assetName);
+        return handler.getXPub(params);
+    };
+    getPublicKey = async (params) => {
+        const handler = await this.#getAssetHandler(params.assetName);
+        return handler.getPublicKey(params);
+    };
+    signTransaction = async (params) => {
+        const handler = await this.#getAssetHandler(params.assetName);
+        return handler.signTransaction(params);
+    };
+    signMessage = async (params) => {
+        const handler = await this.#getAssetHandler(params.assetName);
+        return handler.signMessage(params);
+    };
+}

package/lib/discovery.d.ts

@@ -0,0 +1,25 @@
+import ExodusModule from '@exodus/module';
+import type Transport from '@ledgerhq/hw-transport';
+import { Logger } from '~/shared/types';
+import type { HardwareWalletDescriptor, HardwareWalletDiscovery } from '@exodus/hw-common';
+type TransportFactory = typeof Transport;
+export type Dependencies = {
+    logger: Logger;
+    transportsFactories: {
+        usb: TransportFactory;
+        bluetooth: TransportFactory;
+        tcp: TransportFactory;
+    };
+};
+export declare class LedgerDiscovery extends ExodusModule implements HardwareWalletDiscovery {
+    #private;
+    constructor({ logger, transportsFactories }: Dependencies);
+    list: () => Promise<HardwareWalletDescriptor[]>;
+}
+declare const _default: {
+    id: string;
+    type: string;
+    factory: (deps: Dependencies) => LedgerDiscovery;
+    dependencies: string[];
+};
+export default _default;

package/lib/discovery.js

@@ -0,0 +1,52 @@
+import ExodusModule from '@exodus/module';
+import assert from 'minimalistic-assert';
+import { APDU_PORT } from './constants';
+import { LedgerDevice } from './device';
+const MODULE_ID = 'hardwareWalletLedger';
+export class LedgerDiscovery extends ExodusModule {
+    #transportsFactories;
+    constructor({ logger, transportsFactories }) {
+        super({ name: MODULE_ID, logger });
+        assert(typeof transportsFactories === 'object' &&
+            Object.keys(transportsFactories).length > 0 &&
+            Object.entries(transportsFactories).every(([transportName, transportFactory]) => ['usb', 'bluetooth', 'tcp'].includes(transportName) &&
+                typeof transportFactory === 'object'), `invalid transports`);
+        this.#transportsFactories = transportsFactories;
+    }
+    list = async () => {
+        const descriptors = [];
+        for (const [transportName, transportFactory] of Object.entries(this.#transportsFactories)) {
+            const deviceList = await transportFactory.list();
+            switch (transportName) {
+                case 'usb':
+                    const usbDeviceList = deviceList.map((hidDevice) => ({
+                        manufacturer: 'ledger',
+                        transport: 'usb',
+                        get: async () => new LedgerDevice({ transport: await transportFactory.open(hidDevice) }),
+                    }));
+                    descriptors.push(...usbDeviceList);
+                    break;
+                case 'bluetooth':
+                    this._logger.error(`bluetooth is not supported yet!`);
+                    break;
+                case 'tcp':
+                    descriptors.push({
+                        manufacturer: 'ledger',
+                        transport: 'tcp',
+                        get: async () => new LedgerDevice({ transport: await transportFactory.open({ apduPort: APDU_PORT }) }),
+                    });
+                    break;
+                default:
+                    throw new Error(`unknown transport type ${transportName}`);
+            }
+        }
+        return descriptors;
+    };
+}
+const createLedgerDiscovery = (deps) => new LedgerDiscovery({ ...deps });
+export default {
+    id: MODULE_ID,
+    type: 'module',
+    factory: createLedgerDiscovery,
+    dependencies: ['logger'],
+};

package/lib/index.d.ts

@@ -0,0 +1,2 @@
+export * from './discovery';
+export { default } from './discovery';

package/lib/index.js

@@ -0,0 +1,2 @@
+export * from './discovery';
+export { default } from './discovery';

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "@exodus/hw-ledger",
+  "version": "1.0.0",
+  "description": "The ledger module",
+  "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/modules/hw-ledger",
+  "license": "UNLICENSED",
+  "bugs": {
+    "url": "https://github.com/ExodusMovement/exodus-hydra/issues?q=is%3Aissue+is%3Aopen+label%3Ahw-ledger"
+  },
+  "files": [
+    "lib",
+    "README.md",
+    "CHANGELOG.md"
+  ],
+  "scripts": {
+    "build": "tsc --build tsconfig.build.json",
+    "build:watch": "tsc --build tsconfig.build.json && (concurrently 'tsc --build -w tsconfig.build.json')",
+    "clean": "tsc --build --clean",
+    "test": "jest --runInBand",
+    "lint": "eslint . --ignore-path ../../.gitignore",
+    "lint:fix": "yarn lint --fix"
+  },
+  "dependencies": {
+    "@ledgerhq/hw-app-btc": "^10.0.5",
+    "@ledgerhq/hw-transport": "^6.28.5",
+    "minimalistic-assert": "^1.0.1"
+  },
+  "devDependencies": {
+    "@exodus/hw-common": "^1.0.0",
+    "@exodus/module": "^1.2.0",
+    "@ledgerhq/hw-transport-node-hid": "^6.27.16",
+    "@ledgerhq/hw-transport-node-speculos": "^6.27.16",
+    "@types/jest-when": "^3.5.2",
+    "@types/minimalistic-assert": "^1.0.1",
+    "concurrently": "^7.6.0",
+    "eslint": "^8.33.0",
+    "jest": "^29.1.2",
+    "jest-when": "^3.5.2"
+  },
+  "gitHead": "3772b0c9e6727aa1ed14f0a3d703e93c08b65c8a"
+}