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.
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
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 Appthat 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
CorRustbecause 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.mddescribing 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.
References
- https://developers.ledger.com/docs/device-app/integration/how-to/app-boilerplate
- https://developers.ledger.com/docs/device-app/beginner/vscode-extension
- https://developers.ledger.com/docs/device-app/submission-process/submission-form
- https://developers.ledger.com/docs/device-interaction/integration/how_to/transports
- https://www.cashbackisl.com/ledger-cold-wallet-guide-hk/
- https://en.wikipedia.org/wiki/Smart_card_application_protocol_data_unit
