dmk-intent-vocabulary

DMK の意図に関する用語集

このスキルは、開発者の曖昧なリクエストを適切な DMK コンポーネントと操作に変換し、実装を始める前に正しい API を特定できるようにします。また、実行前に意図が不明確な場合は、ledger-dmk-implementation/SKILL.md によってコネクターとして読み込まれます。

---

規約

導出パスは開発者が設定する定数であり、ユーザー入力ではなく、エージェントが推測するものでもありません。 アプリケーションコード内にリテラルとして記述する必要があります（例："44'/501'/0'/0'"）。呼び出し元のコンテキストに導出パスがない場合は、処理を中止して開発者に確認してください。代わりの値を指定したり、デフォルト値を設定したり、推測したりしてはいけません。誤ったパスを使うと、実行時エラーが発生しないまま、別の鍵から生成された、一見正しい結果が返されます。

---

用語集

デバイスの検出

表現例： 「Ledger を探す」「ハードウェアウォレットを検出する」「デバイスをスキャンする」「Ledger が表示されない」「デバイスが見つからない」「USB が検出されない」「WebHID で何も見つからない」

対応先： dmk.startDiscovering() — Observable<DiscoveredDevice> を返します

注記： 接続前に行う最初の手順です。接続する前に、開発者は購読して通知を待つ必要があります。

---

デバイスの接続とセッション管理

表現例： 「Ledger に接続する」「セッションを開く」「接続を確立する」「切断後に再接続する」「セッション ID を取得する」「デバイスは接続されているがコマンドを送信できない」「切断するにはどうすればよいか」

対応先：

• dmk.connect({ device, sessionRefresherOptions: { isRefresherDisabled: false } }) — Promise<DeviceSessionId> を返します
• dmk.disconnect({ sessionId })
• dmk.getConnectedDevice({ sessionId }) — デバイスのモデル名と名前を返します。情報の取得のみを目的とします

注記： 以降のすべての操作には sessionId が必要です。

---

デバイスの状態とステータス

表現例： 「デバイスはロックされているか」「PIN の入力待ち」「どのアプリが開いているか」「デバイスがビジー状態」「デバイスを監視する」「デバイスの状態変化を監視する」「バッテリー残量」「コマンドを送信せずにファームウェアのバージョンを確認する」「デバイスが切断されたばかり」

対応先： dmk.getDeviceSessionState({ sessionId }) — Observable<DeviceSessionState> を返します

注記： 継続的に通知を出します。デバイスのステータス（ready、busy、locked、disconnected）、デバイス名、OS 情報、バッテリー残量、現在開いているアプリが含まれます。コマンドを使ったポーリングよりも、この方法を優先してください。

---

アプリの管理

表現例： 「Bitcoin アプリを開く」「Ethereum アプリを起動する」「アプリを切り替える」「アプリが開かない」「ユーザーがデバイス上でアプリの起動を確認するのを待つ」「署名する前に正しいアプリが開いていることを確認する」「アプリを閉じる」「実行中のアプリを検出する」

対応先：

• OpenAppDeviceAction — デバイス上でのユーザー確認を含む一連の処理です（ユーザー向けのフローに推奨）
• OpenAppCommand — 低レベルの直接コマンドです
• CloseAppCommand
• GetAppAndVersionCommand — 実行中のアプリの名前とバージョンを返します

---

ファームウェアと OS の情報

表現例： 「ファームウェアのバージョンを取得する」「デバイスにどの OS が入っているか」「MCU のバージョン」「ブートローダーのバージョン」「SE のバージョン」「ファームウェアは最新か」

対応先：

• GetOsVersionCommand — seVersion、mcuSephVersion、mcuBootloaderVersion を返します
• またはセッション状態から取得します。dmk.getDeviceSessionState には追加のコマンドなしで OS 情報がすでに含まれています

---

生の APDU コマンド

表現例： 「生の APDU を送信する」「低レベルのコマンド」「カスタムの CLA/INS」「APDU バイト」「ビルド済みのコマンドではユースケースに対応できない」

対応先：

• ApduBuilder + dmk.sendApdu({ sessionId, apdu })
• または Command クラスを拡張し、dmk.sendCommand を使います（生の APDU より推奨）

署名操作に生の APDU を使わないでください。 目的が署名で、そのチェーン用の署名パッケージがある場合は、それを使ってください。生の APDU を使うと、事前チェック、通知可能な確認状態、エラー分類のロジックを迂回します。署名を伴わないコマンド、または実際にサポートされていないチェーンに限り適切です。

暗号資産アドレスを取得する

言い回し: 「自分の Ethereum アドレスを取得する」「ウォレットアドレスを導出する」「デバイスにアドレスを表示する」「画面上でアドレスを確認する」「Ledger から公開鍵を取得する」「Bitcoin アドレスを取得する」「Solana の公開鍵を取得する」

対応するメソッド（チェーン別）：

• ETH：signerEth.getAddress(derivationPath, options)
• BTC：Bitcoin の署名メソッドに相当するもの
• Solana：Solana の署名メソッドに相当するもの

注： Observable を返します。受取用アドレスをユーザーに提示するフローでは、必ず checkOnDevice: true を使用してください。これを省略すると、侵害されたホストの画面に表示されたアドレスと照合するための唯一の場所であるデバイス画面に、ユーザーがアドレスを表示できません。

---

トランザクションに署名する

言い回し: 「トランザクションに署名する」「ETH のトランザクションに署名する」「署名してブロードキャストする」「クリア署名」「ユーザーが画面上でトランザクションの詳細を確認する」「Bitcoin のトランザクションに署名する」「Solana のトランザクションに署名する」「ハードウェアウォレットでの署名フロー」「ユーザーがトランザクションを拒否した」

対応するメソッド（チェーン別）：

• ETH：signerEth.signTransaction(derivationPath, transaction, options)
• BTC：Bitcoin の署名メソッドに相当するもの
• Solana：Solana の署名メソッドに相当するもの

注： Observable を返します。Pending 状態（デバイスでのユーザー操作）と、署名を取得するための Completed を処理してください。ユーザーによる拒否はエラー状態として通知されます。

---

メッセージに署名する（personal_sign）

言い回し: 「メッセージに署名する」「personal_sign」「ウォレットの所有権を証明する」「認証のために署名する」「ウォレット認証フロー」「Ledger でテキストに署名する」

対応するメソッド： signerEth.signMessage(derivationPath, message)

注： ハッシュ化の前に \x19Ethereum Signed Message:\n を先頭に付加します。このプレフィックスによって安全性が確保されます。型付きデータの署名とは異なります。

eth_sign をこのメソッドに対応付けないでください。 eth_sign は安全性を確保するプレフィックスなしで生のハッシュに署名するため、既知のフィッシング手段です。開発者が eth_sign の動作を求めた場合は、処理を進める前にセキュリティリスクを指摘してください。

---

型付きデータに署名する（EIP-712）

言い回し: 「型付きデータに署名する」「EIP-712」「signTypedData_v4」「ドメインセパレーター」「MetaMask 形式の署名」「permit 署名」「オフチェーン注文」

対応するメソッド： signerEth.signTypedData(derivationPath, typedData)

注： 型付きデータオブジェクト全体（domain + types + message）が必要です。DeFi の permit、オフチェーン注文、委任で使用されます。

---

委任認証（EIP-7702）

言い回し: 「EIP-7702」「委任認証」「委任に署名する」「アカウント抽象化の署名」「コントラクトに権限を委任する」

対応するメソッド： signerEth.signDelegationAuthorization(derivationPath, delegationAuthorization)

---

テストとデバッグ

言い回し: 「デバイスをシミュレートする」「実際の Ledger なしでテストする」「ハードウェアウォレットをモックする」「Speculos」「エミュレーター」「Ledger を使った CI テスト」「デバイスログ」「APDU をデバッグする」「DMK の単体テスト」

対応するもの：

• Speculos トランスポート：@ledgerhq/device-transport-kit-speculos
• 開発者ツール：DevToolsLogger、DevToolsDmkInspector、WebSocket コネクターまたは Rozenite
• React Native：Rozenite コネクター

テストと CI 専用です。 Speculos、モックトランスポート、または setStub(true) を本番環境で設定しないでください。実際のデバイスとのやり取りが迂回され、セキュリティモデルが無効になります。

---

よくあるエラー状態

言い回し: 「デバイスがロックされている」「間違ったアプリが開いている」「アプリがインストールされていない」「ユーザーが拒否した」「ユーザーがデバイス上でキャンセルした」「フローの途中でデバイスが切断された」「ステータスワードが 9000 ではない」「Observable が完了しない」「アクションが保留中のまま停止している」「HID エラー」「USB のアクセス許可が拒否された」

注： デバイスがロックされていると、ほとんどのコマンドは拒否されます。まず DeviceSessionState を確認してください。ステータスワードのエラー（!= 0x9000）は、コマンドの解析ロジックを通じて通知されます。ユーザーによる拒否は DeviceActionStatus.Error として通知されます。USB のアクセス許可が拒否されるのはブラウザーのセキュリティ上の制約です。デバイスへのアクセスはユーザー操作を契機として開始する必要があります。

→ エラーの完全な分類と ABORT／ESCALATE のルーティングについては、ledger-dmk-implementation/SKILL.md を読み込んでください。

---

本物かどうかの確認

表現例：「デバイスが本物か確認して」「本物かどうか確認」「これは Ledger の本物ですか？」「デバイスの真正性を確認」「デバイスを認証して」「これは本物の Ledger ですか？」

対応先：dmk.executeDeviceAction() 経由の GenuineCheckDeviceAction

**注：**セキュアチャネル（HSM バックエンド）が必要です。output.isGenuine: boolean を返します。デバイスの再起動後、初回使用時に AllowSecureConnection が表示されます。

---

インストール済みアプリの一覧表示

表現例：「デバイスにはどのアプリが入っていますか？」「アプリを一覧表示して」「どのアプリがインストールされていますか？」「インストール済みアプリケーションを表示して」「Ethereum アプリがインストールされているか確認して」

対応先：dmk.executeDeviceAction() 経由の ListInstalledAppsDeviceAction

注：output.installedApps: InstalledApp[] を返します。セキュアチャネルが必要です。

---

アプリのインストール／アンインストール

表現例：「Ethereum アプリをインストールして」「Ledger にアプリを追加して」「アプリを削除して」「Bitcoin アプリをアンインストールして」「アプリがインストールされていないのでインストールして」「アプリをデバイスにデプロイして」

対応先：

• インストール：dmk.executeDeviceAction() 経由の InstallAppDeviceAction
• アンインストール：dmk.executeDeviceAction() 経由の UninstallAppDeviceAction

**注：**インストールでは、intermediateValue.progress で進捗状況（0～100）が通知されます。アプリ名は Ledger Live で使われているものと完全に一致している必要があります。セキュアチャネルが必要です。

→ セキュアチャネルのコードパターンについては、ledger-dmk-implementation/SKILL.md を読み込んでください。