feat: hardware wallet emulators

.github/workflows/build-speculos.yml

@@ -0,0 +1,84 @@
+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:
+    runs-on: ubuntu-latest
+
+    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__)')"
+
+      - name: Verify binary architecture
+        run: |
+          file dist/speculos | tee /tmp/speculos-file.txt
+          grep -Fq 'ELF' /tmp/speculos-file.txt
+          grep -Fq 'x86-64' /tmp/speculos-file.txt
+
+      - name: Package archive
+        run: |
+          VERSION="${{ github.event.inputs.version || '0.25.13' }}"
+          cd dist
+          tar -czf speculos-v${VERSION}-linux-amd64.tar.gz speculos
+
+      - name: Upload build artifact
+        uses: actions/upload-artifact@v4
+        with:
+          name: speculos-linux-amd64
+          path: dist/speculos-v*-linux-amd64.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

.gitignore

@@ -1,5 +1,6 @@
 .DS_Store
 dist/
+dist-build/
 coverage/
 
 # Logs
@@ -77,4 +78,7 @@ node_modules/
 !.yarn/versions
 
 # Cursor rules
-.cursorrules
+.cursorrules
+
+# Git worktrees
+.worktrees/

README.md

@@ -26,6 +26,7 @@ This repository contains the following packages [^fn1]:
 - [`@metamask/eth-simple-keyring`](packages/keyring-eth-simple)
 - [`@metamask/eth-snap-keyring`](packages/keyring-snap-bridge)
 - [`@metamask/eth-trezor-keyring`](packages/keyring-eth-trezor)
+- [`@metamask/hw-emulator`](packages/hw-emulator)
 - [`@metamask/hw-wallet-sdk`](packages/hw-wallet-sdk)
 - [`@metamask/keyring-api`](packages/keyring-api)
 - [`@metamask/keyring-internal-api`](packages/keyring-internal-api)
@@ -34,6 +35,7 @@ This repository contains the following packages [^fn1]:
 - [`@metamask/keyring-snap-client`](packages/keyring-snap-client)
 - [`@metamask/keyring-snap-sdk`](packages/keyring-snap-sdk)
 - [`@metamask/keyring-utils`](packages/keyring-utils)
+- [`@metamask/speculos-up`](packages/speculos-up)
 
 <!-- end package list -->
 
@@ -46,6 +48,7 @@ Or, in graph form [^fn1]:
 graph LR;
 linkStyle default opacity:0.5
   account_api(["@metamask/account-api"]);
+  hw_emulator(["@metamask/hw-emulator"]);
   hw_wallet_sdk(["@metamask/hw-wallet-sdk"]);
   keyring_api(["@metamask/keyring-api"]);
   eth_hd_keyring(["@metamask/eth-hd-keyring"]);
@@ -61,6 +64,7 @@ linkStyle default opacity:0.5
   keyring_snap_client(["@metamask/keyring-snap-client"]);
   keyring_snap_sdk(["@metamask/keyring-snap-sdk"]);
   keyring_utils(["@metamask/keyring-utils"]);
+  speculos_up(["@metamask/speculos-up"]);
   account_api --> keyring_api;
   account_api --> keyring_utils;
   keyring_api --> keyring_utils;

packages/hw-emulator/CHANGELOG.md

@@ -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/speculos-up` 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/

packages/hw-emulator/LICENSE

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

packages/hw-emulator/README.md

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

packages/hw-emulator/docker-compose.yml

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

packages/hw-emulator/jest.config.js

@@ -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 },
+  },
+});