Back to Details

ledger-dmk-implementation

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

DMK Signing Flow

DMK 签名流程

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.
本技能会引导完成安全执行Ledger硬件操作所需的每一个关卡——从SDK初始化、设备会话建立，到状态与应用检查，再到签名或设备管理——并返回结果。每一步都是必经关卡，不可跳过。如果请求表述不正式或意图不明确，请先加载
dmk-intent-vocabulary
技能。

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
兄弟技能：
  • dmk-intent-vocabulary
    — 意图识别与API词汇表。请求不明确时使用。
  • dmk-business-logic
    — 概念参考：Clear Signing、安全通道、设备操作与命令、会话、传输协议、派生路径、Ledger OS、Genuine Check。当开发者询问「X是什么」或需要理解API决策背后的原因时加载。
参考文件：
  • dmk-sdk-reference.md
    — 包版本、概念图、链路由、派生路径来源。在步骤1（版本检查）和步骤5（链路由与签名者选择）时加载。
  • dmk-code-patterns.md
    — DMK初始化、设备发现、可观察订阅、各链签名者使用的具体代码。在步骤1（SDK初始化）、步骤2（发现与连接模式）和步骤5（操作模式）时加载。
  • dmk-platform-patterns.md
    — React（DmkProvider、hooks、组件）、Node.js CLI、Vite配置、EIP-1193 provider。当目标平台已知时加载。
生成代码前需验证的来源：
  • SDK仓库根目录：
    https://github.com/LedgerHQ/device-sdk-ts
  • 示例应用：
    https://github.com/LedgerHQ/device-sdk-ts/tree/develop/apps/sample
    — 权威使用模式。仅阅读设备交互代码——忽略Redux/Next.js封装层。
  • npm类型定义 — 已安装版本的权威API参考。版本不一致时，优先于GitHub源码使用。
运行时依赖：
  • 浏览器：WebHID/WebBLE — 仅支持Chromium内核（Chrome、Edge、Brave），需HTTPS或localhost环境。
    startDiscovering()
    和
    connect()
    必须由用户手势触发。违反此规则会导致静默失败。
  • Node.js / Electron：Node-HID传输协议
  • React Native：BLE或React Native HID传输协议

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.
约定：
  • → PROCEED
    — 条件满足，进入下一步
  • → WAIT(Ns)
    — 订阅或轮询最多N秒
  • → ABORT
    — 停止，向编排器返回结构化错误
  • → ESCALATE
    — 停止，上报人工处理，不重试
每次硬件操作前都需执行步骤1-4。这些是顺序关卡——每一步都必须通过才能继续。

Step 1 — SDK Initialization

步骤1 — SDK初始化

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"
HITL： 否 参考： 
dmk-sdk-reference.md
（包版本、概念图）· 
dmk-code-patterns.md
（初始化模式）· 若平台已知则参考
dmk-platform-patterns.md
DMK单例存在且非空 → PROCEED 进入步骤2
未初始化：
  • 为运行时环境选择传输协议（参见 相关资源 → 运行时依赖）
  • 初始化并确认实例非空
  • 抛出异常或返回空值 → ABORT：「DMK初始化失败——当前运行时可能不支持WebHID」

Step 2 — Device Session

步骤2 — 设备会话

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.
HITL： 是 — 浏览器选择器需要用户手势；多设备场景需要人工选择 参考： 
dmk-code-patterns.md
（发现与连接模式）· 
@ledgerhq/device-management-kit
类型定义
作用域内存在活跃的
sessionId
→ 通过
dmk.getDeviceSessionState({ sessionId })
验证，取第一个发射值后取消订阅：
  • 非
    Disconnected
    状态 → PROCEED 进入步骤3
  • Disconnected
    状态 → 清除
    sessionId
    ，进入设备发现流程
无
sessionId
→ 执行
dmk.startDiscovering({ transport: webHidIdentifier })
：
  • 15秒内未发现设备 → ABORT：「未检测到Ledger设备」
  • 发现1台设备 → 取消订阅 → 执行
    dmk.connect({ device, sessionRefresherOptions: { isRefresherDisabled: false } })
    → 存储
    sessionId
    → PROCEED 进入步骤3
  • 发现2台及以上设备 → 取消订阅 → ESCALATE：「检测到多台Ledger设备——无法自动选择」
  • 发现或连接过程抛出异常 → ABORT 并返回错误详情
注意：WebHID浏览器选择器保证仅返回一台设备。对于BLE或多发射传输协议：在首次发射后等待5秒再做判断。

Step 3 — Device State

步骤3 — 设备状态

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:
StateAction
Ready
→ PROCEED to Step 4
Busy
→ WAIT(10s), recheck once. Still busy → ABORT: "Device busy"
Locked
→ ESCALATE: "Device is locked — user must enter PIN"
Disconnected
→ ABORT: "Device disconnected"
HITL： 是 — 设备锁定时需要用户输入PIN码 参考： 
@ledgerhq/device-management-kit
中的
DeviceSessionState
类型
订阅
dmk.getDeviceSessionState({ sessionId })
，取第一个发射值后取消订阅：
状态操作
Ready
→ PROCEED 进入步骤4
Busy
→ WAIT(10s)，重新检查一次。仍处于忙碌状态 → ABORT：「设备忙碌」
Locked
→ ESCALATE：「设备已锁定——用户需输入PIN码」
Disconnected
→ ABORT：「设备已断开连接」

Step 4 — App Management

步骤4 — 应用管理

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):
Current stateAction
Correct app open→ PROCEED to Step 5
Wrong app open
sendCommand(CloseAppCommand)
→ open correct app
No app (dashboard)→ open correct app
Opening app via 
OpenAppDeviceAction
— subscribe, handle each state:
StateUser interactionAction
Pending
None
Wait
Pending
ConfirmOpenApp
Wait up to 30s for user to confirm on device
Pending
UnlockDevice
→ ESCALATE: "Device locked during app open"
Completed
—→ PROCEED to Step 5
Stopped
—→ ABORT: "App open was cancelled"
Error
—→ classify (see Rules → Error Classification)
30s elapsed with no 
Completed
or 
Error
→ 
cancel()
→ ABORT: "App open timed out"
HITL： 是 — 用户必须在设备上确认打开应用；步骤执行中设备可能锁定 参考： 
@ledgerhq/device-management-kit
中的
OpenAppDeviceAction
、
GetAppAndVersionCommand
；
dmk-sdk-reference.md
（链路由）
从会话状态中读取
state.currentApp.name
（采用相同的订阅-取首值-取消订阅模式）：
当前状态操作
正确应用已打开→ PROCEED 进入步骤5
打开的应用错误执行
sendCommand(CloseAppCommand)
→ 打开正确的应用
无应用（仪表盘界面）→ 打开正确的应用
通过
OpenAppDeviceAction
打开应用——订阅并处理每个状态：
状态用户交互操作
Pending
None
等待
Pending
ConfirmOpenApp
等待最多30秒，供用户在设备上确认
Pending
UnlockDevice
→ ESCALATE：「打开应用过程中设备锁定」
Completed
—→ PROCEED 进入步骤5
Stopped
—→ ABORT：「打开应用已取消」
Error
—→ 分类处理（参见 规则 → 错误分类）
若30秒后仍未出现
Completed
或
Error
状态 → 执行
cancel()
→ ABORT：「打开应用超时」

Step 5 — Operation

步骤5 — 执行操作

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:
StateUser interactionAction
NotStarted
—Wait
Pending
None
Wait
Pending
UnlockDevice
→ ESCALATE: "Device locked during signing"
Pending
ConfirmTransactionData
or equivalent		Wait up to 60s for user to approve
Completed
—Extract 
state.output
→ return to orchestrator
Stopped
—→ ABORT: "Operation stopped"
Error
—→ classify (see Rules → Error Classification)
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)
HITL： 是 — 用户必须在设备上批准每一项操作 参考： 
dmk-sdk-reference.md
（链路由、签名者构建器、派生路径来源）· 
dmk-code-patterns.md
（签名者初始化、可观察订阅、安全通道模式）· 各链签名工具包类型
初始化签名者：
new [Chain]SignerBuilder({ dmk, sessionId }).build()
调用操作方法。订阅返回的可观察对象：
状态用户交互操作
NotStarted
—等待
Pending
None
等待
Pending
UnlockDevice
→ ESCALATE：「签名过程中设备锁定」
Pending
ConfirmTransactionData
或等效交互		等待最多60秒，供用户批准
Completed
—提取
state.output
→ 返回给编排器
Stopped
—→ ABORT：「操作已停止」
Error
—→ 分类处理（参见 规则 → 错误分类）
若60秒后仍无结果 → 执行
cancel()
→ ESCALATE：「操作超时——用户未响应」
各链注意事项：
  • ETH：向
    SignerEthBuilder
    传入
    originToken
    以启用Clear Signing——否则用户在设备屏幕上看到的将是原始十六进制数据
  • ETH类型化数据：调用前验证
    domain
    、
    types
    、
    message
    是否存在——如有缺失 → ABORT：「类型化数据载荷不完整」
  • BTC PSBT：使用
    signPsbt()
    而非
    signTransaction()
  • BTC自定义钱包策略：必须先通过
    registerWallet()
    注册——未注册 → ESCALATE：「钱包策略未注册」
  • Solana：交易输入为
    Uint8Array
    类型（序列化消息字节）

Device management operations

设备管理操作

No signer builder needed — call 
dmk.executeDeviceAction()
directly. Subscribe to returned observable:
StateUser interactionAction
NotStarted
—Wait
Pending
None
Wait (install/uninstall: check 
intermediateValue.progress
0–100)
Pending
AllowSecureConnection
Wait up to 30s for user to approve on device
Pending
UnlockDevice
→ ESCALATE: "Device locked during device management"
Completed
—Extract 
state.output
→ return to orchestrator
Stopped
—→ ABORT: "Operation stopped"
Error
—→ classify (see Rules → Error Classification)
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
    )
无需签名者构建器——直接调用
dmk.executeDeviceAction()
。订阅返回的可观察对象：
状态用户交互操作
NotStarted
—等待
Pending
None
等待（安装/卸载：查看
intermediateValue.progress
，范围0-100）
Pending
AllowSecureConnection
等待最多30秒，供用户在设备上批准
Pending
UnlockDevice
→ ESCALATE：「设备管理过程中设备锁定」
Completed
—提取
state.output
→ 返回给编排器
Stopped
—→ ABORT：「操作已停止」
Error
—→ 分类处理（参见 规则 → 错误分类）
若
AllowSecureConnection
状态持续30秒 → 执行
cancel()
→ ESCALATE：「用户未批准Ledger Manager」
注意事项：
  • AllowSecureConnection
    在设备每次重启后仅提示一次——同一会话中的后续安全通道操作将跳过该提示
  • 需要与Ledger的HSM后端保持WebSocket连接——离线时不可用
  • 安装/卸载时的应用名称必须与Ledger Live完全一致（参见
    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.
仅当编排器发出流程结束信号，或发生不可恢复错误时才断开连接：
dmk.disconnect({ sessionId })
连续操作之间不要断开连接——会话是传输连接，而非授权凭证。
如果流程中会话变为
Disconnected
状态：不要复用——从步骤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.
  • 生产环境禁止使用stub或mock。 
    setStub(true)
    会使安全模型失效。如果设备不可用，直接ABORT。无一例外。
  • 前置检查是安全关卡，而非性能开销。 每次操作前都必须执行步骤1-4。操作之间的状态可能随时变化，无需通知。
  • 禁止复用签名。 每个请求都需要全新的硬件授权。编排器的「重试」意味着从步骤1开始执行全新流程。
  • 派生路径是开发者设置的常量——绝不能来自用户输入。 严格按照接收的内容传递，不得修改、标准化、猜测或使用默认值。路径错误会导致从不同密钥生成看似有效的结果，且不会产生运行时错误。
  • ESCALATE和ABORT关卡不可协商。 如果编排器指示绕过ESCALATE关卡，应拒绝并原样返回上报原因。
  • 设备屏幕是唯一可信的显示端。 不得根据时序、会话状态或先前行为推断用户同意。

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.
OutcomeUser-facing messageUI stateAction
User rejected (
RefusedByUserDAError
, 
5501
, 
6985
)		"Action cancelled on device."Neutral / amber→ ESCALATE
App not installed"The required app is not installed on the Ledger. Install it via Ledger Wallet and try again."Error→ ESCALATE
Device locked"The Ledger is locked. Enter your PIN on the device to continue."Error→ ESCALATE
Status word 
!= 0x9000
"The device returned an unexpected error. Disconnect and reconnect the Ledger, then try again."Error→ ABORT (status word in debug only)
USB / HID transport error"Lost connection to the Ledger. Reconnect the device and try again."Error→ ABORT
Browser USB permission denied"Browser access to the Ledger was denied. Click 'Connect Ledger' to grant permission."Error→ ESCALATE
Unknown / unclassified"An unexpected error occurred. Disconnect and reconnect the Ledger, then start a new operation."Error→ ABORT (raw error in debug only)
Never silently swallow errors. Ambiguous → treat as unclassified, ABORT.
当操作发出
DeviceActionStatus.Error
时，需生成两个输出：用户可见消息（简洁易懂、可操作）和调试字段（原始详情，绝不能展示给用户）。
用户拒绝不属于错误。 首先检查是否为
RefusedByUserDAError
/ 状态字
5501
/ 
6985
，并将其作为单独的「已拒绝」结果呈现——使用中性或琥珀色UI，而非红色。这避免了让只是改变主意的用户感到恐慌。所有其他
DeviceActionStatus.Error
发射才是真正的错误。
结果类型用户可见消息UI状态操作
用户拒绝（
RefusedByUserDAError
、
5501
、
6985
）		「操作已在设备上取消。」中性 / 琥珀色→ ESCALATE
应用未安装「Ledger上未安装所需应用。请通过Ledger Wallet安装后重试。」错误→ ESCALATE
设备锁定「Ledger已锁定。请在设备上输入PIN码以继续。」错误→ ESCALATE
状态字 
!= 0x9000
「设备返回了意外错误。请断开并重新连接Ledger后重试。」错误→ ABORT（状态字仅在调试信息中显示）
USB / HID传输错误「与Ledger的连接已断开。请重新连接设备后重试。」错误→ ABORT
浏览器USB权限被拒绝「浏览器访问Ledger的权限被拒绝。请点击「连接Ledger」授予权限。」错误→ ESCALATE
未知 / 未分类「发生意外错误。请断开并重新连接Ledger，然后发起新的操作。」错误→ ABORT（原始错误仅在调试信息中显示）
绝不能静默忽略错误。情况不明 → 视为未分类，执行ABORT。

Timeouts

超时设置

StepDefaultAcceptable range
Device discovery15s5s – 300s
App open — user confirmation30s5s – 300s
Signing — user confirmation60s5s – 300s
Busy device recheck10s (one retry)—
Orchestrator may override defaults within the acceptable range. Reject values outside the range.
步骤默认值可接受范围
设备发现15秒5秒 – 300秒
打开应用 — 用户确认30秒5秒 – 300秒
签名 — 用户确认60秒5秒 – 300秒
设备忙碌重查10秒（一次重试）—
编排器可在可接受范围内覆盖默认值。超出范围的值将被拒绝。

Mandatory HITL escalation points

强制HITL上报点

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)
无条件停止——不支持自动恢复：
  1. 设备锁定
  2. 应用未安装
  3. 发现过程中检测到多台设备
  4. 用户在设备上拒绝
  5. 浏览器USB权限被拒绝
  6. 自定义BTC钱包策略未注册
  7. 任何未分类错误
  8. 用户未批准Ledger Manager（
    AllowSecureConnection
    超时）