feat: hardware wallet emulators #560
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,95 @@ | ||
| name: Build Speculos Binary | ||
|
|
||
| on: | ||
| workflow_dispatch: | ||
| inputs: | ||
| version: | ||
| description: 'Speculos version to build' | ||
| required: true | ||
| default: '0.25.13' | ||
| push: | ||
| tags: | ||
| - 'speculos-v*' | ||
|
|
||
| permissions: | ||
| contents: write | ||
|
|
||
| jobs: | ||
| build: | ||
| strategy: | ||
| fail-fast: false | ||
| matrix: | ||
| include: | ||
| - arch: amd64 | ||
| runner: ubuntu-latest | ||
| file_arch: x86-64 | ||
| - arch: arm64 | ||
| # PyInstaller bundles the host arch; arm64 must build on arm64. | ||
| runner: ubuntu-24.04-arm | ||
| file_arch: 'ARM aarch64' | ||
|
There was a problem hiding this comment. CI arm64 job uses wrong runner platformHigh Severity The arm64 build job uses Additional Locations (1)  Reviewed by Cursor Bugbot for commit 0ab7c8c. Configure here. |
||
|
|
||
| runs-on: ${{ matrix.runner }} | ||
|
|
||
| steps: | ||
| - uses: actions/checkout@v4 | ||
|
|
||
| - name: Set up Python | ||
| uses: actions/setup-python@v5 | ||
| with: | ||
| python-version: '3.11' | ||
|
|
||
| - name: Install dependencies | ||
| run: | | ||
| python -m pip install --upgrade pip | ||
| pip install pyinstaller | ||
|
|
||
| - name: Install speculos | ||
| run: pip install speculos==${{ github.event.inputs.version || '0.25.13' }} | ||
|
|
||
| - name: Build standalone binary | ||
| run: | | ||
| mkdir -p dist | ||
| pyinstaller \ | ||
| --onefile \ | ||
| --name speculos \ | ||
| --distpath dist \ | ||
| --workpath build \ | ||
| --noupx \ | ||
| --collect-all speculos \ | ||
| $(python -c 'import speculos; print(speculos.__file__)') | ||
|
|
||
|
cursor[bot] marked this conversation as resolved.
|
||
| - name: Verify binary architecture | ||
| run: | | ||
| file dist/speculos | tee /tmp/speculos-file.txt | ||
| grep -Fq '${{ matrix.file_arch }}' /tmp/speculos-file.txt | ||
|
|
||
| - name: Package archive | ||
| run: | | ||
| VERSION="${{ github.event.inputs.version || '0.25.13' }}" | ||
| cd dist | ||
| tar -czf speculos-v${VERSION}-linux-${{ matrix.arch }}.tar.gz speculos | ||
|
|
||
| - name: Upload build artifact | ||
| uses: actions/upload-artifact@v4 | ||
| with: | ||
| name: speculos-linux-${{ matrix.arch }} | ||
| path: dist/speculos-v*-linux-${{ matrix.arch }}.tar.gz | ||
| if-no-files-found: error | ||
|
|
||
| release: | ||
| needs: build | ||
| runs-on: ubuntu-latest | ||
|
|
||
| steps: | ||
| - name: Download build artifacts | ||
| uses: actions/download-artifact@v4 | ||
| with: | ||
| pattern: speculos-linux-* | ||
| path: dist | ||
| merge-multiple: true | ||
|
|
||
| - name: Upload release assets | ||
| uses: softprops/action-gh-release@v2 | ||
| with: | ||
| tag_name: speculos-v${{ github.event.inputs.version || '0.25.13' }} | ||
| files: dist/*.tar.gz | ||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,34 @@ | ||
| # Changelog | ||
|
|
||
| All notable changes to this project will be documented in this file. | ||
|
|
||
| The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/), | ||
| and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). | ||
|
|
||
| ## [Unreleased] | ||
|
|
||
| ### Added | ||
|
|
||
| - Initial release of `@metamask/hw-emulator` ([#TODO](https://github.com/MetaMask/accounts/pull/TODO)) | ||
| - Hardware wallet emulator lifecycle, transport, and device interaction for E2E testing | ||
| - Ledger emulator via Speculos with support for Nano S+, Nano X, Stax, and Flex devices | ||
| - Docker and native run modes | ||
| - `SpeculosClient` for APDU exchange and screen events | ||
| - `ApduBridge` for WebSocket-to-APDU bridge (WebHID mocking) | ||
| - `DockerManager` for Docker Compose lifecycle management | ||
| - `ProcessManager` for native Speculos process spawning | ||
| - Device interaction automation (button presses, touch gestures) | ||
| - Resilience utilities (`withRetry`, `ExponentialBackoff`) | ||
| - Ledger HID framing session utilities | ||
| - WebHID mock script generation for E2E tests | ||
| - Deterministic accounts with pre-configured seed | ||
| - Bundled ELF app binaries for all supported devices | ||
| - Docker Compose configuration for Speculos | ||
| - JSDoc documentation on all public types, classes, methods, and constants | ||
| - `getElfFilePath` utility for resolving ELF binary paths (native mode) | ||
| - `startNative()` defaults to `@metamask/speculosup` managed binary when no `binary` option is provided | ||
| - Fix Docker mode ignoring custom `apduPort` / `apiPort` by passing host ports to `docker-compose` | ||
| - Fix Docker mode ignoring the `seed` option by wiring `SPECULOS_SEED` through `docker-compose.yml` | ||
| - Fix Docker mode ignoring the `display` option by wiring `SPECULOS_DISPLAY` through `docker-compose.yml` | ||
|
|
||
| [Unreleased]: https://github.com/MetaMask/accounts/ |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,21 @@ | ||
| MIT License | ||
|
|
||
| Copyright (c) 2026 MetaMask | ||
|
|
||
| Permission is hereby granted, free of charge, to any person obtaining a copy | ||
| of this software and associated documentation files (the "Software"), to deal | ||
| in the Software without restriction, including without limitation the rights | ||
| to use, copy, modify, merge, publish, distribute, sublicense, and/or sell | ||
| copies of the Software, and to permit persons to whom the Software is | ||
| furnished to do so, subject to the following conditions: | ||
|
|
||
| The above copyright notice and this permission notice shall be included in all | ||
| copies or substantial portions of the Software. | ||
|
|
||
| THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR | ||
| IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, | ||
| FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE | ||
| AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER | ||
| LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, | ||
| OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE | ||
| SOFTWARE. |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,140 @@ | ||
| # `@metamask/hw-emulator` | ||
|
|
||
| Hardware wallet emulator lifecycle, transport, and device interaction for E2E testing. | ||
|
|
||
| Provides a programmatic interface for launching and controlling hardware wallet emulators (Ledger via [Speculos](https://github.com/LedgerHQ/speculos)), sending APDU commands, and automating device screen interactions (button presses, touch gestures) — all without physical hardware. | ||
|
|
||
| ## Installation | ||
|
|
||
| `yarn add @metamask/hw-emulator` | ||
|
|
||
| or | ||
|
|
||
| `npm install @metamask/hw-emulator` | ||
|
|
||
| ## Supported Devices | ||
|
|
||
| | Device | Model ID | Interaction Type | | ||
| | ------- | -------- | ---------------- | | ||
| | Nano S+ | `nanosp` | Button | | ||
| | Nano X | `nanox` | Button | | ||
| | Stax | `stax` | Touch | | ||
| | Flex | `flex` | Touch | | ||
|
|
||
| ## Quick Start | ||
|
|
||
| ### Docker Mode (recommended for macOS / CI) | ||
|
|
||
| ```typescript | ||
| import { createEmulator, EmulatorType } from '@metamask/hw-emulator'; | ||
|
|
||
| const emulator = createEmulator(EmulatorType.Ledger, { | ||
| device: 'flex', | ||
| mode: 'docker', | ||
| }); | ||
|
|
||
| await emulator.start(); | ||
| await emulator.approveTransaction(); | ||
| await emulator.stop(); | ||
| ``` | ||
|
|
||
| ### Native Mode (Linux only) | ||
|
|
||
| Requires the Speculos binary to be installed and available on `PATH`, or passed via the `binary` option. | ||
|
|
||
| ```typescript | ||
| import { createEmulator, EmulatorType } from '@metamask/hw-emulator'; | ||
|
|
||
| const emulator = createEmulator(EmulatorType.Ledger, { | ||
| device: 'nanosp', | ||
| mode: 'native', | ||
| binary: '/usr/local/bin/speculos', | ||
| }); | ||
|
|
||
| await emulator.start(); | ||
| await emulator.approveSigning(); | ||
| await emulator.stop(); | ||
| ``` | ||
|
|
||
| ## API | ||
|
|
||
| ### `createEmulator(type, options?)` | ||
|
|
||
| Factory function that creates a `HardwareWalletEmulator` instance. | ||
|
|
||
| - **`type`** — `'ledger'` (via `EmulatorType.Ledger`). Trezor support is not yet implemented. | ||
| - **`options`** — See [`SpeculosOptions`](#speculosoptions). | ||
|
|
||
| ### `HardwareWalletEmulator` | ||
|
|
||
| | Method | Description | | ||
| | ---------------------- | ------------------------------------------ | | ||
| | `start()` | Start the emulator (Docker or native). | | ||
| | `stop()` | Stop the emulator and clean up resources. | | ||
| | `isRunning()` | Returns whether the emulator is active. | | ||
| | `approveTransaction()` | Approve the current transaction on screen. | | ||
| | `approveSigning()` | Approve the current signing request. | | ||
| | `rejectTransaction()` | Reject the current transaction on screen. | | ||
| | `navigateToMainMenu()` | Navigate back to the device main menu. | | ||
| | `getInteraction()` | Get the low-level device interaction API. | | ||
|
|
||
| ### `SpeculosOptions` | ||
|
|
||
| | Option | Type | Default | Description | | ||
| | -------------- | --------- | ------------ | ---------------------------------------------------- | | ||
| | `device` | `string` | `'flex'` | Device model ID (`nanosp`, `nanox`, `stax`, `flex`). | | ||
| | `seed` | `string` | Built-in | Mnemonic seed for deterministic accounts. | | ||
| | `apduPort` | `number` | `9998` | APDU communication port. | | ||
| | `apiPort` | `number` | `5001` | Speculos REST API port. | | ||
| | `wsBridgePort` | `number` | `9876` | WebSocket bridge port for WebHID mock. | | ||
| | `mode` | `string` | Auto | Run mode: `'docker'` or `'native'`. Auto-detected. | | ||
| | `binary` | `string` | — | Path to Speculos binary (native mode only). | | ||
| | `display` | `string` | `'headless'` | Display mode. | | ||
| | `loadNvram` | `boolean` | `true` | Load persisted NVRAM state. | | ||
| | `startTimeout` | `number` | `60000` | Startup timeout in ms. | | ||
|
|
||
| ### Low-Level APIs | ||
|
|
||
| The package also exports granular components for advanced use cases: | ||
|
|
||
| - **`SpeculosClient`** — HTTP client for the Speculos REST API (APDU exchange, screen events). | ||
| - **`ApduBridge`** — WebSocket-to-APDU bridge for browser-based WebHID mocking. | ||
| - **`DockerManager`** — Direct Docker Compose lifecycle management. | ||
| - **`createProcessManager()`** — Native Speculos process spawning and monitoring. | ||
| - **`createDeviceInteraction()`** — Screen automation (button presses, touch coordinates). | ||
| - **`withRetry()` / `ExponentialBackoff`** — Resilience utilities for flaky device communication. | ||
| - **`createLedgerHidFramingSession()`** — Low-level Ledger HID frame encoding/decoding. | ||
| - **`getWebHidMockScript()`** — Generates a browser script to mock WebHID for E2E tests. | ||
|
|
||
| ## Docker Setup | ||
|
|
||
| The package includes a `docker-compose.yml` for running Speculos via Docker: | ||
|
|
||
| ```bash | ||
| # Start with default device (Flex) | ||
| docker compose up -d | ||
|
|
||
| # Start with a specific device | ||
| SPECULOS_DEVICE=nanosp docker compose up -d | ||
|
|
||
| # Start with custom host ports (must match apduPort / apiPort in createEmulator options) | ||
| SPECULOS_APDU_PORT=9997 SPECULOS_API_PORT=5002 docker compose up -d | ||
| ``` | ||
|
|
||
| The ELF app binaries for all supported devices are bundled in the `apps/` directory. | ||
|
|
||
| ## Deterministic Accounts | ||
|
|
||
| The default seed produces these pre-funded Ethereum accounts: | ||
|
|
||
| | Index | Address | | ||
| | ----- | -------------------------------------------- | | ||
| | 0 | `0x24fC293546A31F5Ce73bAfecE37969A95CCd1aBf` | | ||
| | 1 | `0x730A5c73bC3ACcf56daba2D5D897bEb10F852865` | | ||
| | 2 | `0x805c2797CCBa57887F5fA0DD95C017145d67604a` | | ||
| | 3 | `0x2Bf9972F600D8C3B3f0AEe8f1e17Fc4631242fF4` | | ||
| | 4 | `0xDc660e6D52F6f774d0879f99929711155Bc03902` | | ||
|
|
||
| ## Contributing | ||
|
|
||
| This package is part of a monorepo. Instructions for contributing can be found in the [monorepo README](https://github.com/MetaMask/accounts#readme). |
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,38 @@ | ||
| version: '3.8' | ||
| services: | ||
| speculos: | ||
| image: ghcr.io/ledgerhq/speculos:latest | ||
| container_name: metamask-speculos | ||
| ports: | ||
| - '${SPECULOS_APDU_PORT:-9998}:9999' | ||
| - '${SPECULOS_API_PORT:-5001}:5000' | ||
| volumes: | ||
| - ./apps:/speculos/apps | ||
| - ./nvram/main_nvram.bin:/speculos/main_nvram.bin | ||
| environment: | ||
| - DISPLAY=:99 | ||
| command: > | ||
| --model ${SPECULOS_DEVICE:-nanosp} | ||
| /speculos/apps/${SPECULOS_ELF_FILENAME:-ethereum-nanosp.elf} | ||
| --seed "${SPECULOS_SEED:-grit essence story volume tip entry situate found february olympic monitor hybrid}" | ||
| --display ${SPECULOS_DISPLAY:-headless} | ||
| --apdu-port 9999 | ||
| --api-port 5000 | ||
| --load-nvram | ||
| healthcheck: | ||
| test: | ||
| - CMD-SHELL | ||
| - python3 -c "import urllib.request; urllib.request.urlopen('http://localhost:5000/')" | ||
| interval: 2s | ||
| timeout: 3s | ||
| retries: 10 | ||
|
|
||
| --- | ||
| # Note: | ||
| # - SPECULOS_APDU_PORT / SPECULOS_API_PORT are host-side ports (defaults 9998 / 5001) | ||
| # - Container listens on 9999 (APDU) and 5000 (API) internally | ||
| # - SPECULOS_DEVICE selects the device model (nanosp, nanox, stax, flex) | ||
| # - SPECULOS_ELF_FILENAME is the ELF filename inside /speculos/apps/ (NOT the host path) | ||
| # - SPECULOS_SEED sets the mnemonic for deterministic accounts (DockerManager / Speculos seed option) | ||
| # - SPECULOS_DISPLAY sets the Speculos display backend (DockerManager display option, default headless) | ||
| # - Defaults to Nano S+ (nanosp) for local development without SPECULOS_DEVICE set |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,10 @@ | ||
| const merge = require('deepmerge'); | ||
| const path = require('path'); | ||
| const baseConfig = require('../../jest.config.packages'); | ||
|
|
||
| module.exports = merge(baseConfig, { | ||
| displayName: path.basename(__dirname), | ||
| coverageThreshold: { | ||
| global: { branches: 10, functions: 20, lines: 20, statements: 20 }, | ||
| }, | ||
| }); |
Binary file not shown.
Oops, something went wrong.
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
CI workflow arm64 build uses wrong runner platform
Medium Severity
The arm64 matrix entry uses
macos-12.0as the runner, butmacos-12runners are no longer available on GitHub Actions (they were x86_64 Intel when they existed). Even with a valid ARM macOS runner, PyInstaller on macOS produces Mach-O binaries, not Linux ELF binaries. The archive is then namedlinux-arm64on line 70, which is incorrect for any macOS-built binary. The verification step would always fail sincefileoutput won't contain'ARM aarch64'for a macOS binary. This workflow can never successfully produce arm64 artifacts.Additional Locations (1)
.github/workflows/build-speculos.yml#L69-L70Reviewed by Cursor Bugbot for commit 08e9687. Configure here.