Issues Encountered When Sideloading Ledger Device Apps on Emulator and Real Device

Wed, 15 Apr 2026 10:54:59 +0800

Ledger is arguably the No.1 in the hardware wallet niche, but I still ran into quite a few issues during actual use - through Discord, Twitter, email, official docs, and direct communication. I hit many pitfalls along the way, so here is a summary to help other developers avoid the same traps.

Notes

The models I actually used are the Nano S Plus and Nano X. Note that the X does not support sideloading.
For a comprehensive introduction to Ledger, see Ledger Device App Development Guide. I won’t repeat that here.

Real Device Sideloading

Sideloading Device Compatibility

Not all Ledger models support real device sideloading, as mentioned above. How can you check which models are supported?

Check the official website.
Use the official VS Code extension - Ledger Dev Tools. If you select a specific device, you can tell from whether the sideload button is enabled or disabled.

Sideloading Runtime Environment

Official VS Code extension - Ledger Dev Tools
- There are many extensions matching the “ledger” keyword, so make sure you install the right one.
Docker must be installed and kept running.
- Follow the official guide to install Docker. On Mac, the desktop app installation is recommended.
When you first open the extension, it will pull the ledger-app-dev-tools image and start the container. The image size is approximately 8.51GB.

docker pull ghcr.io/ledgerhq/ledger-app-builder/ledger-app-dev-tools

Sideloading Test Operating Systems

Ubuntu and other Linux distributions
macOS
Windows - this is probably the hardest to set up.

On Ubuntu, do not use the snap-installed version of Docker. Install it directly from the official website instead, otherwise you will run into permission issues that prevent sideloading from working properly.

macOS

If you just want to verify connectivity, run the following:

pip install ledgerblue

from ledgerblue.comm import getDongle
from ledgerblue.commException import CommException

try:
 dongle = getDongle(debug=True)
 # GET VERSION APDU on the dashboard
 result = dongle.exchange(bytes.fromhex("e001000000"))
 print("Connected! Response:", result.hex())
 dongle.close()
except CommException as e:
 print(f"APDU error (SW=0x{e.sw:04X}): {e.message}")
except Exception as e:
 print(f"Unable to connect: {e}")

Final Thoughts

Overall, while Ledger Device App sideloading provides a great testing environment, there are still some issues and limitations in practice. I hope this article helps developers better understand and resolve these problems, improving both development efficiency and user experience.

Understanding Ledger Hardware Wallets

Fri, 20 Mar 2026 09:42:15 +0800

Ledger /'ledʒər/ is a hardware wallet brand. I recently needed to verify the signing flow for a new blockchain, so I tested it with a Ledger Nano X device.

This post records the process and the main technical points.

Buying a Ledger

The one I have was purchased by my company. If you want to get your own, the official store is the simplest option: Ledger Shop

What It Is

A Ledger device stores private keys securely through physical isolation and a secure element chip.

What It Does

Private key storage without exposing the key to the computer or phone
Transaction signing with the signing action completed on the device itself

Example: Ethereum Signing Flow

sequenceDiagram box Client participant U as User participant D as dApp participant M as MetaMask end box External Signing Device participant L as Ledger Device (Ethereum App) end box Blockchain Infrastructure participant R as RPC / Ethereum Network end U->>D: Start transfer / approve / swap D->>M: Ask wallet to create a transaction M->>R: Fetch nonce / gas / fee / chainId R-->>M: Return on-chain parameters M->>U: Show transaction details U->>M: Confirm in MetaMask M->>L: Send unsigned transaction data L->>U: Show key details on the device screen U->>L: Confirm or reject with hardware buttons alt User confirms L-->>M: Return signature M->>R: Broadcast signed transaction R-->>M: Return tx hash / pending / confirmed M-->>U: Show transaction status else User rejects L-->>M: Reject signing M-->>U: Transaction canceled / failed end

Supporting a Custom Blockchain

If you want a custom chain to use Ledger for secure key storage and signing, there are two main parts:

Build a Ledger Device App that runs on the hardware device and knows how to sign transactions for your chain.
Build a plugin or integration layer that connects MetaMask or another wallet to that device app. If your stack uses libraries such as web3.js, you may also need to extend those libraries to support signing through the Ledger device app.

Call Chain / Data Flow

Your code
 ↓
Ledger SDK (wraps APDU)
 ↓
WebHID (transport)
 ↓
Ledger device
 ↓
Your ChainMaker App (parses APDU)

HID means human interface device, and APDU means application protocol data unit.

Ledger Device App Requirements

The device app is typically written in C or Rust because device resources are limited.
- Rust template: https://github.com/LedgerHQ/app-boilerplate-rust
- C template: https://github.com/LedgerHQ/app-boilerplate
Install the official VS Code extension for development and debugging.
Building the device app requires Docker because Ledger provides a containerized toolchain.
For simulator-based testing, install Speculos.

VS Code Extension

The extension provides a solid development, build, and debug workflow, which helps a lot when iterating on a device app.

Real Device vs Simulator

Item	Real Device (WebHID)	Simulator (Speculos)
Connection	`TransportWebHID.create()` with browser HID picker	`SpeculosHttpTransport.open(url)` over local HTTP
Protocol	USB HID frames via the browser WebHID API	HTTP JSON such as `{ data: "hex..." }`
User confirmation	Physical button confirmation is required	Manual confirmation in Speculos
Signer setup	Usually pass `signDigest` and `fetchPublicKey` explicitly	Defaults are often enough
Later flow	`isReady()` -> `fetchPublicKey()` -> `signMessage()` -> submit on-chain	Same overall flow

Submission and Release

What you submit is not a binary package. You submit the app source repository plus the required deliverables. Ledger then forks your app repository and manages deployment in their own release flow.

Typical process:

Contact the Ledger team and submit the project form: https://developers.ledger.com/docs/device-app/submission-process/submission-form
Make sure the code meets Ledger’s security and cryptography requirements.
Prepare deliverables:
- The app source repository
- docs/apdu.md describing APDU commands and status words
- User documentation
- Device compatibility information for Nano S Plus, Nano X, Stax, and Flex
- Legal entity information and contact details
Submit the official device app or plugin form.
Pass the security audit before Ledger publishes the app.

This review process is heavy and can take weeks or even months.

How End Users Use It

The user installs Ledger software and sets up the device.
The user installs the target app onto the Ledger device.
- If the app has not been officially published yet, you usually sideload it through the official VS Code tools.

Other Notes

Why are there so many models, and why are they expensive?

A hardware wallet is more than just a security chip.
Different models trade off security level, user experience, storage capacity, and use case, so the pricing differs naturally.

About `navigator.hid`

navigator.hid (WebHID) connects to physical USB HID devices. Speculos is only a simulator that exposes TCP sockets and an HTTP API. It is not a real HID device, so the browser cannot discover it through WebHID scanning.

Contact Ledger

Discord
Email: hello@ledger.fr

Ledger | Attack on Life