Ledger device SDK for Rust Applications

Crate that allows developing Ledger device applications in Rust.

Contains:

• Safe wrappers over common syscalls and C SDK functions
• IO abstractions (io and seph modules)
• Cryptographic abstractions (ecc, hash and hmac modules)
• Arithmetic (simple and modular) abstraction (math module)
• Persistent data storage (nvm module)
• UI/UX libraries (nbgl module)
• Swap support (libcallmodule)

Supported devices

Usage

Building requires adding rust-src to your Rust installation, and both Clang and arm-none-eabi-gcc. On Ubuntu, gcc-multilib might also be required.

Using rustc nightly builds is mandatory as some unstable features are required.

• rustup default nightly-2025-12-05 (or use the version specified in rust-toolchain.toml)
• rustup component add rust-src
• install Clang.
• install an ARM gcc toolchain

If you wish to install the ARM gcc toolchain using your distribution's packages, these commands should work:

# On Debian and Ubuntu
sudo apt install clang gcc-arm-none-eabi gcc-multilib

# On Fedora or Red Hat Entreprise Linux
sudo dnf install clang arm-none-eabi-gcc arm-none-eabi-newlib

# On ArchLinux
sudo pacman -S clang arm-none-eabi-gcc arm-none-eabi-newlib

This SDK provides custom target files. One for each supported device.

We also provide a Docker container to build Rust applications for Ledger devices (recommended for reproducibility):

docker pull ghcr.io/ledgerhq/ledger-app-builder/ledger-app-builder:latest

# Build using Docker
docker run --rm -v "$(pwd):/app" ghcr.io/ledgerhq/ledger-app-builder/ledger-app-builder:latest \
  cargo ledger build stax

Building your app

Using cargo-ledger (recommended):

# Install cargo-ledger
cargo install cargo-ledger

# Setup custom targets (one-time)
cargo ledger setup

# Build for your target device
cargo ledger build nanox       # Nano X
cargo ledger build nanosplus   # Nano S+
cargo ledger build stax        # Stax
cargo ledger build flex        # Flex
cargo ledger build apex_p      # Apex P

# Build and load to device
cargo ledger build nanosplus --load

Alternatively, using plain cargo:

cargo build --release --target=nanox       # Nano X
cargo build --release --target=nanosplus   # Nano S+
cargo build --release --target=stax        # Stax
cargo build --release --target=flex        # Flex
cargo build --release --target=apex_p      # Apex P

App metadata and build variants

cargo-ledger and the SDK build script read your app's install parameters (name, icon, flags, allowed curves and derivation paths) from the [package.metadata.ledger] table of your app's Cargo.toml:

[package.metadata.ledger]
curve = ["secp256k1"]            # curves the app is allowed to use
flags = "0x000"                  # application flags (hex string)
path  = ["44'/0'"]               # allowed BIP32 derivation-path prefixes
name  = "MyApp"                  # name shown on the device dashboard
# one icon table per supported device
nanox     = { icon = "icons/app_nanox.gif" }
nanosplus = { icon = "icons/app_nanosplus.gif" }
stax      = { icon = "icons/app_stax.gif" }
flex      = { icon = "icons/app_flex.gif" }
apex_p    = { icon = "icons/app_apexp.png" }

Build variants (e.g. testnet)

A single source tree can produce several installable apps that differ only in a few metadata fields — typically a testnet build with a different name, icon, and derivation path. The SDK supports up to 10 variants per app.

How it works — the variant slot number (0 … 9) is the channel between your app and the SDK build script. A build script only sees CARGO_FEATURE_* for features on its own crate, so the SDK cannot observe your app's feature name — only which numbered slot you switched on. Three things must therefore agree on the same number:

1. the SDK feature you forward to — ledger_device_sdk/variant_<N>;
2. the metadata table — [package.metadata.ledger.variants.<N>];
3. (implicitly) the app feature you give a human name to.

The app feature name is the human-readable label; the number is just a slot index. Wire it up in your app's Cargo.toml:

[features]
# Human-named app features forward to numbered SDK slots (variant_0 … variant_9).
variant_testnet = ["ledger_device_sdk/variant_0"]
variant_betanet = ["ledger_device_sdk/variant_1"]

# Declare only the differing keys; every key you omit is inherited from the
# base [package.metadata.ledger] table. The table key MUST match the slot
# number forwarded above.
[package.metadata.ledger.variants.0]
name = "MyApp Testnet"
path = ["44'/1'"]                # standard testnet coin type
nanox = { icon = "icons/app_testnet_nanox.gif" }
# flags, curve, and any non-overridden icon are inherited from the base table

[package.metadata.ledger.variants.1]
name = "MyApp Betanet"

Select a variant at build time with its app feature:

cargo ledger build nanosplus -- --features variant_testnet

The same app feature also gates your app's runtime code, so a variant can change behaviour as well as metadata:

#[cfg(feature = "variant_testnet")]
const COIN_TYPE: u32 = 1; // testnet
#[cfg(not(feature = "variant_testnet"))]
const COIN_TYPE: u32 = 0; // mainnet

Note the split of responsibilities: the SDK's variant_<N> feature is metadata-only (it tells build.rs which overlay to apply); your app's own variant_<name> feature is what gates Rust code via #[cfg(feature = …)].

Notes:

• Variant resolution is fail-closed: selecting a slot whose [package.metadata.ledger.variants.<N>] table is absent aborts the build instead of silently using the base values. This prevents shipping a "Testnet"-labelled binary that carries mainnet paths or curves.
• Enabling more than one variant_<N> feature at once is a hard error — the build aborts rather than silently picking one of several conflicting variants.
• Unspecified per-device icons fall back to the base table's icon (icons are cosmetic).

Getting Started

For a complete application example, see the Rust Boilerplate App.

Key concepts for Ledger app development:

• #![no_std] environment: No standard library, use core:: and alloc:: types
• Panic handler required: Every app must define a panic handler with set_panic! macro
• Device-specific UI: Use nbgl module for touchscreen devices (Stax/Flex/Apex P), ui module or nbgl with nano_nbgl feature for Nano devices
• Testing: Examples can be run with Speculos emulator

Examples

The examples/ directory contains various demonstrations. Build and run with:

# Touchscreen devices (Stax, Flex, Apex P)
cargo run --example nbgl_home_and_settings --target stax --release \
  --config examples/config.toml

# Nano devices (S+, X) - requires nano_nbgl feature for NBGL UI
cargo run --example nbgl_home_and_settings --target nanosplus --release \
  --features nano_nbgl --config examples/config.toml

# View all available examples
ls examples/*.rs

Note: Running examples requires Speculos emulator. The config.toml automatically invokes Speculos as the target runner.

Contributing

You can submit an issue or even a pull request if you wish to contribute.

Make sure you've followed the installation steps above. In order for your PR to be accepted, it will have to pass the CI, which performs the following checks:

• Check if the code builds on nightly
• Check that clippy does not emit any warnings
• check that your code follows rustfmt's format (using cargo fmt)