Architecture

System Overview

Host App (OKX / MetaMask)
        ↕ BLE (Ledger GATT profile)
Android Phone (IRON Vault)
        ├── BLE Peripheral (Kotlin GattServer)
        ├── APDU Handler (@iron-vault/apdu)
        ├── HD Crypto (@iron-vault/crypto)
        └── Wallet Storage (@iron-vault/wallet)

BLE Transport Layer

The Android app advertises as "Nano X" and implements the Ledger GATT profile:

APDU commands are chunked into BLE frames with sequence numbers. The first chunk includes the total payload length; subsequent chunks carry continuation data.

APDU Layer

Commands follow the ISO 7816-4 format: CLA INS P1 P2 [Lc Data]. Responses end with a 2-byte status word (9000 = success).

See the APDU Protocol section for the full command reference.

Crypto Layer

All key derivation is stateless and pure:

• Ethereum: BIP-32 via @scure/bip32, BIP-39 via @scure/bip39, secp256k1 via @noble/curves
• Solana: SLIP-10 Ed25519 with HMAC-SHA512 key "ed25519 seed" — all path components hardened

Deferred Signing

When a SIGN_* command arrives, the APDU handler pauses and calls setSignRequestHandler, which lets the UI navigate to a confirmation screen. The user approves or rejects; only then does the handler sign and respond.