# Handshake Ledger app Hardware-wallet app for [Handshake](https://handshake.org) (HNS). Lets a Ledger Stax / Flex / Nano S+ / Nano X derive Handshake addresses and sign Handshake transactions, including name-auction covenants. > ⚠️ **Status:** v0.1, pre-audit. Do **not** use with mainnet keys yet. Forked from [LedgerHQ/app-boilerplate-rust](https://github.com/LedgerHQ/app-boilerplate-rust) (Apache-2.0). ## Devices Stax (primary target), Flex, Nano S+, Nano X, Apex+. All five compile; only Stax has been exercised on real hardware. ## What the app does (v0.1) | INS | Command | Behavior | | ------ | -------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `0x03` | `GET_VERSION` | Returns app version (major.minor.patch). | | `0x04` | `GET_APP_NAME` | Returns `Handshake`. | | `0x05` | `GET_PUBKEY` | Derives a secp256k1 pubkey from a BIP-32 path under `m/44'/5353'/...`, encodes as bech32 (`hs…` mainnet / `ts…` testnet). With `P1=1`, shows the address and its derivation path on-device to confirm. | | `0x06` | `SIGN_TX` | PSBT-style state machine selected by `P1`: `BEGIN` / `ADD_INPUT` / `ADD_OUTPUT` / `REVIEW` / `SIGN_INPUT`. The host streams the tx as structured records, the device sums values itself, shows one review, then signs each input on demand. See `src/handlers/sign_tx.rs`. | | `0x07` | `SIGN_MESSAGE` | Prepends `"handshake signed message:\n"`, BLAKE2b-256 hashes, shows signer address, path and preview, returns `recovery_id ‖ sig ‖ pubkey`. | CLA: `0xe0`. Status words live in `src/main.rs::AppSW`. ## What the device refuses A hardware wallet's job is to be correct when the host lies, so the app rejects anything its review screen cannot represent honestly. `tests/standalone/test_sign_tx_policy.py` covers each of these. - **Sighash types other than `ALL` (`0x01`).** The review lists concrete outputs and a concrete fee, which is only what the signature commits to under `ALL`. `NONE` commits to no outputs, `SINGLE`/`SINGLEREVERSE` to one, `ANYONECANPAY` drops the other inputs and `NOINPUT` drops the outpoint. Checked per input, not once for the session. - **Derivation paths outside `m/44'/{5353..5356}'/account'[/change/index]`.** The install manifest whitelists the same prefixes, but BOLOS terminates the app on a path outside them instead of returning an error, so the app checks first. All inputs in one session must share a coin type, since the review renders every address under a single HRP. - **Sessions larger than 16 inputs / 8 outputs, or 1 KB of covenant items in total.** Sized to the configured heap. The counts no longer drive an up-front allocation, so a single `BEGIN` cannot exhaust it. - **Covenant kinds above `REVOKE` (11), and kind `0` carrying items.** Either would put bytes into the sighash under a label that does not describe them. - **Declared input values that sum past `u64`, or outputs exceeding inputs.** The fee is computed in `u128` and the session refused rather than truncated into a plausible-looking number. ## Building (no Docker) Native Rust + ARM toolchain: no Docker, no `ledger-app-builder`. ### Prerequisites ```sh # Rust nightly is pinned in rust-toolchain.toml; rustup will install it on demand. rustup show # ARM bare-metal toolchain + LLVM (macOS) brew install --cask gcc-arm-embedded brew install llvm # Ledger Cargo subcommand + sideload tool + emulator cargo install --git https://github.com/LedgerHQ/cargo-ledger pip install ledgerwallet speculos ``` `scripts/build` has the full one-time setup in its header comment, including the BOLOS Secure SDK clone and the API level that must match your device firmware. ### Build ```sh ./scripts/build stax # or: flex / nanox / nanosplus / apex_p ``` Use `scripts/build` rather than `cargo ledger build` directly: on macOS the latter writes neither the Intel HEX nor the `ledgerctl` manifest, and it cannot compile the Nano NBGL sources without a `uint` define. The script handles all three. The manifest is **generated from the built ELF** by `scripts/gen-manifest`, never hand-written: `dataSize` has to match the binary, and an undersized one installs cleanly and then refuses to launch. Binary and manifest land under `target//release/`. ## Testing ### Speculos emulator ```sh speculos --apdu-port 9999 --api-port 5001 --model stax \ target/stax/release/app-handshake ``` ### Ragger functional tests ```sh ./scripts/test # stax ./scripts/test flex # or nanosp / nanox / apex_p ./scripts/test stax -k policy -v ``` Speculos does not run natively on macOS, so `scripts/test` runs it and ragger in a container built from Ledger's dev-tools image (`tests/Dockerfile`). The image is multi-arch, so this runs natively on Apple silicon. The first invocation builds the image, which takes a few minutes; after that a full device run is about 30 seconds. Tests that drive the UI compare against golden snapshots under `tests/standalone/snapshots//`. Regenerate them with `./scripts/test --golden_run`, and look at the diff before committing: those images are the record of what the review screen shows, which is the whole point of the device. `test_sign_tx_policy.py` needs no snapshots, because every case in it is refused before anything is drawn. ## Installing on a real device Unlock the device and stay on the dashboard (not inside an app): ```sh ledgerctl install -f target/stax/release/app_stax.json ``` ## Architecture - `src/main.rs`: APDU dispatcher and app entry. - `src/handlers/`: one file per APDU command. - `src/app_ui/`: NBGL UI screens (menu, address confirm, tx review, message review). - `src/handshake/`: protocol primitives (addresses, covenants, sighash, BLAKE2b). - `src/swap.rs`: Ledger Exchange integration, a stub. `handler_sign_review` refuses outright when swap parameters are present rather than auto-approving, so wiring Exchange up requires adding the validation deliberately. ## Spec / signing The app mirrors `shd`: - Curve: **secp256k1**, compressed public keys (33 B). - BIP-32 path: `m/44'/5353'/account'/change/index`. Handshake assigns one SLIP-44 coin type per network (**5353'** mainnet, **5354'** testnet, **5355'** regtest, **5356'** simnet), and the coin type is what selects the HRP on-device (`Network::from_coin_type`). - Address: bech32 (BIP-173, never bech32m) with HRPs `hs` / `ts` / `rs` / `ss`, witness version 0, P2WPKH = `BLAKE2b-160(compressed_pubkey)`. - Sighash: BIP-143-style preimage, hashed with **BLAKE2b-256** (not SHA256d). The preimage builder handles `ALL`, `NONE`, `SINGLE`, `SINGLEREVERSE` and the `NOINPUT` / `ANYONECANPAY` flags so it matches `shd` byte for byte, but `SIGN_TX` only signs `ALL`. `tests/application_client/handshake_sighash.py` is an independent reimplementation used to cross-check the device's signatures. - Signature: 64-byte compact r‖s with a 1-byte sighash type appended. Low-S comes from BOLOS itself: `cx_ecdsa_sign` canonicalizes unless `CX_NO_CANONICAL` is set, and the SDK's `deterministic_sign` does not set it. - Outputs carry a `covenant` field (name auctions). Items are re-serialized verbatim into the sighash preimage, and the review decodes them: the operation label for every kind, the plaintext name for OPEN/BID/FINALIZE once checked against the hash the covenant commits to, the name hash otherwise, and for TRANSFER the destination address, which decides who ends up owning the name and appears nowhere else on screen. Authoritative source: `shd/Sources/Script/SigHash.swift`, `shd/Sources/Protocol/Transaction.swift`, `shd/Sources/Covenants/CovenantData.swift`. ## License Apache-2.0, see `LICENSE.md`. Original boilerplate © Ledger SAS.