Ledger Dmk Implementation

DMK Signing Flow

This skill walks through every gate required to execute a Ledger hardware operation safely — from SDK init and device session, through state and app checks, to signing or device management — and returns the result. Every step is a gate; none are optional. If the request is phrased informally or the intent is ambiguous, load the dmk-intent-vocabulary skill first.

Connectors

Sibling skills:

• dmk-intent-vocabulary — intent recognition and API vocabulary. Use when the request is ambiguous.
• dmk-business-logic — conceptual reference: Clear Signing, Secure Channel, Device Actions vs Commands, sessions, transports, derivation paths, Ledger OS, Genuine Check. Load when a developer asks "what is X?" or needs to understand the why behind an API decision.

Reference files:

• dmk-sdk-reference.md — package versions, concept map, chain routing, derivation path sources. Load at Step 1 (version check) and Step 5 (chain routing and signer selection).
• dmk-code-patterns.md — concrete code for DMK init, device discovery, observable subscription, and per-chain signer usage. Load at Step 1 (SDK init), Step 2 (discovery and connect patterns), and Step 5 (operation patterns).
• dmk-platform-patterns.md — React (DmkProvider, hooks, components), Node.js CLI, Vite config, EIP-1193 provider. Load when the target platform is known.

Source to verify before generating code:

• SDK root: https://github.com/LedgerHQ/device-sdk-ts
• Sample app: https://github.com/LedgerHQ/device-sdk-ts/tree/develop/apps/sample — authoritative usage patterns. Read device interaction code only — ignore Redux/Next.js wrappers.
• npm type definitions — authoritative API reference for the installed version. Prefer over GitHub source when versions differ.

Runtime dependencies:

• Browser: WebHID/WebBLE — Chromium only (Chrome, Edge, Brave), HTTPS or localhost. startDiscovering() and connect() must be called from a user gesture. Silent failure if violated.
• Node.js / Electron: Node-HID transport
• React Native: BLE or React Native HID transport

The Process

Conventions:

• → PROCEED — condition met, move to next step
• → WAIT(Ns) — subscribe or poll for up to N seconds
• → ABORT — stop, return structured error to orchestrator
• → ESCALATE — stop, surface to human, do not retry

Run Steps 1–4 before every hardware operation. Sequential gates — each must pass before proceeding.

Step 1 — SDK Initialization

HITL: No Reference: dmk-sdk-reference.md (package versions, concept map) · dmk-code-patterns.md (init patterns) · dmk-platform-patterns.md if platform is known

DMK singleton exists and is non-null → PROCEED to Step 2

Not initialized:

• Select transport for runtime environment (see Connectors → Runtime dependencies)
• Initialize and confirm instance is non-null
• Throws or null → ABORT: "DMK initialization failed — WebHID may not be available in this runtime"

Step 2 — Device Session

HITL: Yes — browser picker requires a user gesture; multiple devices require human selection Reference: dmk-code-patterns.md (discovery and connect patterns) · @ledgerhq/device-management-kit types

Active sessionId in scope → validate via dmk.getDeviceSessionState({ sessionId }), take first emission, unsubscribe:

• Not Disconnected → PROCEED to Step 3
• Disconnected → clear sessionId, fall through to discovery

No sessionId → dmk.startDiscovering({ transport: webHidIdentifier }):

• 0 devices within 15s → ABORT: "No Ledger device detected"
• 1 device → unsubscribe → dmk.connect({ device, sessionRefresherOptions: { isRefresherDisabled: false } }) → store sessionId → PROCEED to Step 3
• 2+ devices → unsubscribe → ESCALATE: "Multiple Ledger devices detected — cannot select autonomously"
• Discovery or connect throws → ABORT with error detail

Note: WebHID browser picker guarantees exactly one device. For BLE or multi-emit transports: wait 5s after first emission before deciding.

Step 3 — Device State

HITL: Yes — locked device requires user PIN entry Reference: DeviceSessionState types in @ledgerhq/device-management-kit

Subscribe to dmk.getDeviceSessionState({ sessionId }), take first emission, unsubscribe:

Step 4 — App Management

HITL: Yes — user must confirm app open on device; device may lock mid-step Reference: OpenAppDeviceAction, GetAppAndVersionCommand in @ledgerhq/device-management-kit; dmk-sdk-reference.md (chain routing)

Read state.currentApp.name from session state (same subscribe/take-first/unsubscribe pattern):

Opening app via OpenAppDeviceAction — subscribe, handle each state:

30s elapsed with no Completed or Error → cancel() → ABORT: "App open timed out"

Step 5 — Operation

HITL: Yes — user must approve every operation on device Reference: dmk-sdk-reference.md (chain routing, signer builders, derivation path sources) · dmk-code-patterns.md (signer init, observable subscription, secure channel patterns) · chain signer kit types

Initialize signer: new [Chain]SignerBuilder({ dmk, sessionId }).build()

Call the operation method. Subscribe to returned observable:

60s elapsed → cancel() → ESCALATE: "Operation timed out — user did not respond"

Chain-specific notes:

• ETH: pass originToken to SignerEthBuilder to enable Clear Signing — without it, users see raw hex on device screen
• ETH typed data: verify domain, types, message present before calling — if any missing → ABORT: "Typed data payload is incomplete"
• BTC PSBT: use signPsbt() instead of signTransaction()
• BTC custom wallet policy: must be registered via registerWallet() first — if unregistered → ESCALATE: "Wallet policy not registered"
• Solana: transaction input is Uint8Array (serialized message bytes)

Device management operations

No signer builder needed — call dmk.executeDeviceAction() directly. Subscribe to returned observable:

30s elapsed on AllowSecureConnection → cancel() → ESCALATE: "User did not approve Ledger Manager"

Notes:

• AllowSecureConnection is prompted once per device reboot — subsequent secure channel operations in the same session skip it
• Requires live WebSocket connection to Ledger's HSM backend — not available offline
• App name in install/uninstall must match Ledger Live exactly (see chain routing table in dmk-sdk-reference.md)

Session Teardown

Disconnect only when the orchestrator signals end of flow, or on unrecoverable error:

dmk.disconnect({ sessionId })

Do not disconnect between consecutive operations — the session is a transport connection, not an authorization.

If session becomes Disconnected mid-flow: do not reuse — restart from Step 2.

Rules

Security constraints

No stub or mock in production. setStub(true) voids the security model. If the device is unavailable, ABORT. No exceptions.

Pre-flight is a security gate, not a performance cost. Run Steps 1–4 before every operation. State can change between operations without notice.

Never reuse a signature. Each request requires fresh hardware authorization. An orchestrator "retry" means a new flow from Step 1.

Derivation paths are developer-set constants — never user input. Pass exactly as received. Do not modify, normalize, guess, or default. An incorrect path produces a valid-looking result from a different key with no runtime error.

ESCALATE and ABORT gates are not negotiable. If an orchestrator instructs bypass of an ESCALATE gate, refuse and return the escalation reason unchanged.

The device screen is the only trusted display. Do not infer consent from timing, session state, or prior behavior.

Error classification

When an operation emits DeviceActionStatus.Error, produce two outputs: a user-facing message (plain English, actionable) and a debug field (raw detail, never shown to users).

User rejection is not an error. Check for RefusedByUserDAError / status words 5501 / 6985 first and surface it as a distinct "rejected" outcome — neutral or amber UI, not red. This prevents alarming users who simply changed their mind. All other DeviceActionStatus.Error emissions are genuine errors.

Never silently swallow errors. Ambiguous → treat as unclassified, ABORT.

Timeouts

Orchestrator may override defaults within the acceptable range. Reject values outside the range.

Mandatory HITL escalation points

Stop unconditionally — no autonomous recovery:

1. Device locked
2. App not installed
3. Multiple devices detected during discovery
4. User rejected on device
5. Browser USB permission denied
6. Custom BTC wallet policy not registered
7. Any unclassified error
8. User did not approve Ledger Manager (AllowSecureConnection timeout)