dmk-intent-vocabulary

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

DMK Intent Vocabulary

DMK 意图词汇表

This skill translates informal developer requests into the correct DMK components and operations, so the right API is identified before any implementation begins. It is also loaded as a connector by

ledger-dmk-implementation/SKILL.md

when intent is unclear before execution.

本技能将非正式的开发者请求转换为正确的DMK组件与操作，以便在开展任何实现工作前确定合适的API。当执行前意图不明确时，

ledger-dmk-implementation/SKILL.md

也会将本技能作为连接器加载。

Conventions

约定

Derivation paths are developer-set constants — never user input, never inferred by the agent. They must appear as literals in the application code (e.g.

"44'/501'/0'/0'"

). If a derivation path is missing from the calling context, stop and ask the developer — do not substitute, default, or guess one. An incorrect path produces a valid-looking result from a different key with no runtime error.

派生路径（Derivation Path）是开发者设置的常量——绝不能来自用户输入，也绝不能由Agent推断。 它们必须以字面量形式出现在应用代码中（例如

"44'/501'/0'/0'"

）。如果调用上下文中缺少派生路径，应停止并询问开发者——不要替换、使用默认值或猜测。错误的路径会从不同的密钥生成看似有效的结果，且不会产生运行时错误。

Vocabulary

词汇表

Device Discovery

设备发现

Phrasings: "find my Ledger", "detect the hardware wallet", "scan for devices", "Ledger not showing up", "device not found", "USB not detecting", "WebHID not finding anything"

Maps to:

dmk.startDiscovering()

— returns

Observable<DiscoveredDevice>

Note: First step before connecting. The developer must subscribe and wait for emissions before connecting.

常见表述： "find my Ledger", "detect the hardware wallet", "scan for devices", "Ledger not showing up", "device not found", "USB not detecting", "WebHID not finding anything"

映射到：

dmk.startDiscovering()

— 返回

Observable<DiscoveredDevice>

说明： 这是连接前的第一步。开发者必须先订阅并等待事件触发，然后再进行连接。

Device Connection and Session Management

设备连接与会话管理

Phrasings: "connect to the Ledger", "open a session", "establish connection", "reconnect after disconnect", "get a session ID", "device connected but can't send commands", "how do I disconnect?"

Maps to:

dmk.connect({ device, sessionRefresherOptions: { isRefresherDisabled: false } })

— returns

Promise<DeviceSessionId>

```
dmk.disconnect({ sessionId })
```
```
dmk.getConnectedDevice({ sessionId })
```
— device model and name, informational only

Note: The

sessionId

is required for all subsequent interactions.

常见表述： "connect to the Ledger", "open a session", "establish connection", "reconnect after disconnect", "get a session ID", "device connected but can't send commands", "how do I disconnect?"

映射到：

dmk.connect({ device, sessionRefresherOptions: { isRefresherDisabled: false } })

— 返回

Promise<DeviceSessionId>

```
dmk.disconnect({ sessionId })
```
```
dmk.getConnectedDevice({ sessionId })
```
— 仅用于获取设备型号和名称等信息

说明： 所有后续交互都需要使用

sessionId

。

Device State and Status

设备状态

Phrasings: "is the device locked?", "waiting for PIN", "what app is open?", "device is busy", "observe the device", "listen to device state changes", "battery level", "firmware version without sending a command", "device just disconnected"

Maps to:

dmk.getDeviceSessionState({ sessionId })

— returns

Observable<DeviceSessionState>

Note: Emits continuously. Includes device status (

ready

busy

locked

disconnected

), device name, OS info, battery, and currently open app. Prefer this over polling with commands.

常见表述： "is the device locked?", "waiting for PIN", "what app is open?", "device is busy", "observe the device", "listen to device state changes", "battery level", "firmware version without sending a command", "device just disconnected"

映射到：

dmk.getDeviceSessionState({ sessionId })

— 返回

Observable<DeviceSessionState>

说明： 会持续发射数据。包含设备状态（

ready

、

busy

、

locked

、

disconnected

）、设备名称、操作系统信息、电池电量以及当前打开的应用。优先使用此接口，而非通过命令轮询。

App Management

应用管理

Phrasings: "open the Bitcoin app", "launch the Ethereum app", "switch apps", "app not opening", "waiting for user to confirm app launch", "make sure the right app is open before signing", "close the app", "detect which app is running"

Maps to:

```
OpenAppDeviceAction
```
— full flow including user confirmation on device (preferred for user-facing flows)
```
OpenAppCommand
```
— lower-level direct command
```
CloseAppCommand
```
```
GetAppAndVersionCommand
```
— returns name and version of the running app

常见表述： "open the Bitcoin app", "launch the Ethereum app", "switch apps", "app not opening", "waiting for user to confirm app launch", "make sure the right app is open before signing", "close the app", "detect which app is running"

映射到：

```
OpenAppDeviceAction
```
— 包含设备端用户确认的完整流程（面向用户的流程优先使用此方式）
```
OpenAppCommand
```
— 更低层级的直接命令
```
CloseAppCommand
```
```
GetAppAndVersionCommand
```
— 返回当前运行应用的名称和版本

Firmware and OS Information

固件与操作系统信息

Phrasings: "get firmware version", "what OS is on the device?", "MCU version", "bootloader version", "SE version", "is the firmware up to date?"

Maps to:

GetOsVersionCommand

— returns

seVersion

mcuSephVersion

mcuBootloaderVersion

Or from session state:
```
dmk.getDeviceSessionState
```
already includes OS info without an extra command

常见表述： "get firmware version", "what OS is on the device?", "MCU version", "bootloader version", "SE version", "is the firmware up to date?"

映射到：

GetOsVersionCommand

— 返回

seVersion

、

mcuSephVersion

、

mcuBootloaderVersion

或从会话状态获取：
```
dmk.getDeviceSessionState
```
已包含操作系统信息，无需额外发送命令

Raw APDU Commands

原始APDU命令

Phrasings: "send a raw APDU", "low-level command", "custom CLA/INS", "APDU bytes", "the pre-built commands don't cover my use case"

Maps to:

ApduBuilder

dmk.sendApdu({ sessionId, apdu })

Or extend
```
Command
```
class and use
```
dmk.sendCommand
```
(recommended over raw APDU)

Do not use raw APDU for signing operations. If the goal is signing and a signer package exists for the chain, use it. Raw APDU bypasses the pre-flight, observable confirmation states, and error classification logic. Only appropriate for non-signing commands or genuinely unsupported chains.

常见表述： "send a raw APDU", "low-level command", "custom CLA/INS", "APDU bytes", "the pre-built commands don't cover my use case"

映射到：

ApduBuilder

dmk.sendApdu({ sessionId, apdu })

或继承
```
Command
```
类并使用
```
dmk.sendCommand
```
（推荐优先使用此方式，而非原始APDU）

切勿使用原始APDU进行签名操作。 如果目标是签名且对应链已有签名器包，请使用该包。原始APDU会绕过前置检查、可观察的确认状态以及错误分类逻辑。仅适用于非签名命令或确实不受支持的链。

Get Crypto Address

获取加密货币地址

Phrasings: "get my Ethereum address", "derive wallet address", "show address on device", "verify address on screen", "public key from Ledger", "get Bitcoin address", "get Solana public key"

Maps to (by chain):

ETH:

signerEth.getAddress(derivationPath, options)

BTC: Bitcoin signer equivalent
Solana: Solana signer equivalent

Note: Returns an observable. Use

checkOnDevice: true

for any flow where users are given a receiving address — skipping it means users never see the address on the device screen, the only place they can verify it against a compromised host display.

常见表述： "get my Ethereum address", "derive wallet address", "show address on device", "verify address on screen", "public key from Ledger", "get Bitcoin address", "get Solana public key"

映射到（按链划分）：

ETH：

signerEth.getAddress(derivationPath, options)

BTC：对应比特币签名器
Solana：对应Solana签名器

说明： 返回一个observable。对于任何向用户提供收款地址的流程，请设置

checkOnDevice: true

——跳过此步骤意味着用户永远无法在设备屏幕上看到地址，而设备屏幕是他们能对照被入侵的主机显示验证地址的唯一途径。

Sign a Transaction

签名交易

Phrasings: "sign a transaction", "sign ETH tx", "sign and broadcast", "clear signing", "user confirms transaction details on screen", "sign a Bitcoin transaction", "sign Solana transaction", "hardware wallet signing flow", "user rejected the transaction"

Maps to (by chain):

ETH:

signerEth.signTransaction(derivationPath, transaction, options)

BTC: Bitcoin signer equivalent
Solana: Solana signer equivalent

Note: Returns an observable. Handle

Pending

states (user action on device) and

Completed

to get the signature. User rejection surfaces as an error state.

常见表述： "sign a transaction", "sign ETH tx", "sign and broadcast", "clear signing", "user confirms transaction details on screen", "sign a Bitcoin transaction", "sign Solana transaction", "hardware wallet signing flow", "user rejected the transaction"

映射到（按链划分）：

ETH：

signerEth.signTransaction(derivationPath, transaction, options)

BTC：对应比特币签名器
Solana：对应Solana签名器

说明： 返回一个observable。需要处理

Pending

状态（用户需在设备上操作）和

Completed

状态以获取签名。用户拒绝会以错误状态的形式呈现。

Sign a Message (personal_sign)

签名消息（personal_sign）

Phrasings: "sign a message", "personal_sign", "prove wallet ownership", "sign to authenticate", "wallet auth flow", "sign text with Ledger"

Maps to:

signerEth.signMessage(derivationPath, message)

Note: Prepends

\x19Ethereum Signed Message:\n

before hashing — this prefix is what makes it safe. Different from typed data signing.

Do not map
eth_sign
to this method.

eth_sign

signs a raw hash without the safety prefix and is a known phishing vector. If a developer asks for

eth_sign

behavior, flag the security risk before proceeding.

常见表述： "sign a message", "personal_sign", "prove wallet ownership", "sign to authenticate", "wallet auth flow", "sign text with Ledger"

映射到：

signerEth.signMessage(derivationPath, message)

说明： 哈希前会添加前缀

\x19Ethereum Signed Message:\n

——正是这个前缀保证了安全性。与类型化数据签名不同。

切勿将
eth_sign
映射到此方法。

eth_sign

直接对原始哈希签名，没有安全前缀，是已知的钓鱼攻击向量。如果开发者要求实现

eth_sign

行为，在继续操作前请先标记安全风险。

Sign Typed Data (EIP-712)

签名类型化数据（EIP-712）

Phrasings: "sign typed data", "EIP-712", "signTypedData_v4", "domain separator", "MetaMask-style signature", "permit signature", "off-chain order"

Maps to:

signerEth.signTypedData(derivationPath, typedData)

Note: Requires the typed data object in full (domain + types + message). Used for DeFi permits, off-chain orders, delegation.

常见表述： "sign typed data", "EIP-712", "signTypedData_v4", "domain separator", "MetaMask-style signature", "permit signature", "off-chain order"

映射到：

signerEth.signTypedData(derivationPath, typedData)

说明： 需要完整的类型化数据对象（域 + 类型 + 消息）。用于DeFi permit、链下订单、授权委托等场景。

Delegation Authorization (EIP-7702)

委托授权（EIP-7702）

Phrasings: "EIP-7702", "delegation authorization", "sign delegation", "account abstraction signing", "delegate authority to contract"

Maps to:

signerEth.signDelegationAuthorization(derivationPath, delegationAuthorization)

常见表述： "EIP-7702", "delegation authorization", "sign delegation", "account abstraction signing", "delegate authority to contract"

映射到：

signerEth.signDelegationAuthorization(derivationPath, delegationAuthorization)

Testing and Debugging

测试与调试

Phrasings: "simulate a device", "test without a real Ledger", "mock the hardware wallet", "Speculos", "emulator", "CI testing with Ledger", "device logs", "debug APDU", "unit test DMK"

Maps to:

Speculos transport:
```
@ledgerhq/device-transport-kit-speculos
```
Developer tools:
```
DevToolsLogger
```
,
```
DevToolsDmkInspector
```
, WebSocket connector or Rozenite
React Native: Rozenite connector

For testing and CI only. Never configure Speculos, mock transports, or

setStub(true)

in production. They bypass real device interaction — the security model is void.

常见表述： "simulate a device", "test without a real Ledger", "mock the hardware wallet", "Speculos", "emulator", "CI testing with Ledger", "device logs", "debug APDU", "unit test DMK"

映射到：

Speculos传输层：
```
@ledgerhq/device-transport-kit-speculos
```
开发者工具：
```
DevToolsLogger
```
、
```
DevToolsDmkInspector
```
、WebSocket连接器或Rozenite
React Native：Rozenite连接器

仅用于测试和CI环境。 切勿在生产环境中配置Speculos、模拟传输层或使用

setStub(true)

。它们会绕过真实的设备交互——安全模型将失效。

Common Error States

常见错误状态

Phrasings: "device locked", "wrong app open", "app not installed", "user rejected", "user cancelled on device", "device disconnected mid-flow", "status word not 9000", "observable never completes", "action stuck in pending", "HID error", "USB permission denied"

Note: Most commands reject if the device is locked — check

DeviceSessionState

first. Status word errors (

!= 0x9000

) surface via command parse logic. User rejection surfaces as

DeviceActionStatus.Error

. USB permission denied is a browser security constraint — device access must be triggered from a user gesture.

→ For full error classification and ABORT/ESCALATE routing, load

ledger-dmk-implementation/SKILL.md

常见表述： "device locked", "wrong app open", "app not installed", "user rejected", "user cancelled on device", "device disconnected mid-flow", "status word not 9000", "observable never completes", "action stuck in pending", "HID error", "USB permission denied"

说明： 如果设备已锁定，大多数命令都会被拒绝——请先检查

DeviceSessionState

。状态字错误（

!= 0x9000

）会通过命令解析逻辑呈现。用户拒绝会以

DeviceActionStatus.Error

的形式呈现。USB权限被拒绝是浏览器的安全限制——设备访问必须由用户手势触发。

→ 完整的错误分类以及ABORT/ESCALATE路由，请加载

ledger-dmk-implementation/SKILL.md

。

Genuine Check

正品校验

Phrasings: "verify the device is authentic", "genuine check", "is this Ledger real?", "check device authenticity", "certify device", "is this a real Ledger?"

Maps to:

GenuineCheckDeviceAction

via

dmk.executeDeviceAction()

Note: Requires secure channel (HSM backend). Returns

output.isGenuine: boolean

. Prompts

AllowSecureConnection

on first use per device reboot.

常见表述： "verify the device is authentic", "genuine check", "is this Ledger real?", "check device authenticity", "certify device", "is this a real Ledger?"

映射到： 通过

dmk.executeDeviceAction()

调用

GenuineCheckDeviceAction

说明： 需要安全通道（HSM后端）。返回

output.isGenuine: boolean

。每次设备重启后首次使用时会提示

AllowSecureConnection

。

List Installed Apps

列出已安装应用

Phrasings: "what apps are on the device?", "list apps", "which apps are installed?", "show installed applications", "check if Ethereum app is installed"

Maps to:

ListInstalledAppsDeviceAction

via

dmk.executeDeviceAction()

Note: Returns

output.installedApps: InstalledApp[]

. Requires secure channel.

常见表述： "what apps are on the device?", "list apps", "which apps are installed?", "show installed applications", "check if Ethereum app is installed"

映射到： 通过

dmk.executeDeviceAction()

调用

ListInstalledAppsDeviceAction

说明： 返回

output.installedApps: InstalledApp[]

。需要安全通道。

Install / Uninstall App

安装/卸载应用

Phrasings: "install the Ethereum app", "add an app to the Ledger", "remove an app", "uninstall Bitcoin app", "app not installed — install it", "deploy app to device"

Maps to:

Install:

InstallAppDeviceAction

via

dmk.executeDeviceAction()

Uninstall:

UninstallAppDeviceAction

via

dmk.executeDeviceAction()

Note: Install emits progress (0–100) in

intermediateValue.progress

. App name must match exactly what Ledger Live uses. Requires secure channel.

→ For secure channel code patterns, load

ledger-dmk-implementation/SKILL.md

常见表述： "install the Ethereum app", "add an app to the Ledger", "remove an app", "uninstall Bitcoin app", "app not installed — install it", "deploy app to device"

映射到：

安装：通过

dmk.executeDeviceAction()

调用

InstallAppDeviceAction

卸载：通过

dmk.executeDeviceAction()

调用

UninstallAppDeviceAction

说明： 安装过程会通过

intermediateValue.progress

发射进度（0–100）。应用名称必须与Ledger Live中使用的完全一致。需要安全通道。

→ 安全通道的代码模式，请加载

ledger-dmk-implementation/SKILL.md

。