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

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

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:

State	Action
`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

@ledgerhq/device-management-kit

;

dmk-sdk-reference.md

(chain routing)

Read

state.currentApp.name

from session state (same subscribe/take-first/unsubscribe pattern):

Current state	Action
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:

State	User interaction	Action
`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

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:

State	User interaction	Action
`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:

State	User interaction	Action
`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

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.

Outcome	User-facing message	UI state	Action
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

/ 状态字

，并将其作为单独的「已拒绝」结果呈现——使用中性或琥珀色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

超时设置

Step	Default	Acceptable range
Device discovery	15s	5s – 300s
App open — user confirmation	30s	5s – 300s
Signing — user confirmation	60s	5s – 300s
Busy device recheck	10s (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:

Device locked
App not installed
Multiple devices detected during discovery
User rejected on device
Browser USB permission denied
Custom BTC wallet policy not registered
Any unclassified error
User did not approve Ledger Manager (
```
AllowSecureConnection
```
timeout)

无条件停止——不支持自动恢复：

设备锁定
应用未安装
发现过程中检测到多台设备
用户在设备上拒绝
浏览器USB权限被拒绝
自定义BTC钱包策略未注册
任何未分类错误
用户未批准Ledger Manager（
```
AllowSecureConnection
```
超时）