Openloop SDK
仕様書
バージョン v0.8.1 ｜ 最終更新 2026-10-11
株式会社ハウディ・クリプト 代表取締役社長 浅田 一憲
アーキテクチャ概要
Openloop SDK とは
Openloop SDK は、Openloop ハードウェアウォレットとの通信を行う 多言語ライブラリ です。
| 言語 / 形式 | 主な配布物 | 用途 |
|---|---|---|
| TypeScript / npm | @openloop/sdk-core,
@openloop/transport-* |
Web dApp、Node.js / Electron、React Native |
| Swift / SPM (計画中) | — | iOS Native アプリ |
| Kotlin / Maven (計画中) | — | Android Native |
| C# / NuGet (計画中) | — | Windows Native |
ライセンスについて: Openloop SDK の使用には、株式会社ハウディ・クリプトとのライセンス契約が必要です。ご要望に応じて SDK のカスタマイズも可能ですので、お気軽に info@crypto.haudi.jp までお問い合わせください。
最も重要な原則: 秘密鍵はデバイス内に保持され、外部に出ることはありません。SDK は APDU（Application Protocol Data Unit）コマンドの送受信と、署名に渡す前後のデータの組み立て・検証だけを行います。署名はすべてデバイス内のセキュアエレメントで実行されます。
レイヤー構成
各レイヤーの役割
| レイヤー | 役割 |
|---|---|
| dApp | ユーザーインターフェース、トランザクション構築 |
| App Class | チェーン固有の APDU コマンド構築・レスポンス解析 |
| Bitcoin の出口 | （任意）アドレスの導出と検証、UTXO の選択、PSBT の組み立てなど。デバイスとは通信しない（下記） |
| ITransport | デバイスとの物理的通信（USB/BLE/WebSocket 等） |
| Device | 秘密鍵管理、署名実行、ユーザー承認 |
セキュリティモデル
SDK が行うこと
- APDU コマンドの構築と送信
- レスポンスの解析（アドレス、署名等）
- Transport の接続・切断管理
- Bitcoin
の出口（
@openloop/sdk-core/bitcoin）での、アドレスの導出と検証・UTXO の選択・PSBT の組み立て・署名済み取引の取り出し・放送（呼ぶ側が渡した端点への HTTP 要求）
SDK が行わないこと
- 秘密鍵の生成・保持・操作
- 署名の実行
- シードフレーズの管理
デバイス側のセキュリティ
- 秘密鍵はデバイス内に生成・保存され、外部に出ることはない
- すべての署名はデバイス内で実行される
- トランザクション内容はデバイスの画面に表示され、ユーザーが物理ボタンで承認する
- 拒否または使用中のとき、デバイスはステータスワード
0x6985を返し、署名は実行されない
対応チェーン
| チェーン | App クラス | 楕円曲線 | BIP44 coin_type |
|---|---|---|---|
| Bitcoin | BitcoinApp |
secp256k1 | 0' (mainnet), 1' (testnet) |
| Ethereum (EVM) | EthereumApp |
secp256k1 | 60' |
| XRP Ledger | XrpApp |
Ed25519 / secp256k1 | 144' |
| Solana | SolanaApp |
Ed25519 | 501' |
| TRON | TronApp |
secp256k1 | 195' |
Bitcoin のアドレスは 3 型（Legacy P2PKH = 44'、Nested
SegWit P2SH-P2WPKH = 49'、Native SegWit P2WPKH =
84'）に対応します。
EVM 互換チェーン
EthereumApp は Ethereum だけでなく、EVM
互換チェーンで使用できます。signPersonalMessage と
signTypedData の chainId
パラメータでチェーンを指定します。
Transport 接続方式
SDK は 6 種類の Transport
パッケージと、@openloop/sdk-core に内蔵の WalletConnect
を提供し、幅広いプラットフォームをカバーします。
| Transport | パッケージ | ユースケース |
|---|---|---|
| WebHID (USB) | @openloop/transport-webhid |
Chrome/Edge デスクトップ |
| Web Bluetooth | @openloop/transport-webble |
Chrome/Edge + Android |
| LocalWS | @openloop/transport-local |
全ブラウザ（Connect 経由） |
| Safari Extension | @openloop/transport-safari |
iOS Safari |
| USB HID (native) | @openloop/transport-usb |
Node.js / Electron |
| BLE (native) | @openloop/transport-ble |
Node.js / Electron |
| WalletConnect | @openloop/sdk-core 内蔵 |
全ブラウザ（リモート署名） |
詳細は Transport 選択ガイド を参照してください。
パッケージ一覧
npm パッケージ (TypeScript)
| パッケージ | 説明 | 依存関係 |
|---|---|---|
@openloop/sdk-core |
コアライブラリ（OpenloopSDK, App, Types, Errors,
Constants, WcTransport）。サブパス ./verify（署名の検証）と
./bitcoin（Bitcoin の出口）を持つ |
@noble/curves,
@noble/hashes（./verify は加えて
viem, @scure/base） |
@openloop/transport-webhid |
WebHID (USB) Transport | sdk-core |
@openloop/transport-webble |
Web Bluetooth Transport | sdk-core |
@openloop/transport-local |
LocalWS Transport | sdk-core |
@openloop/transport-safari |
Safari Extension Transport | sdk-core (peer) |
@openloop/transport-usb |
Native USB HID Transport | sdk-core (peer), node-hid |
@openloop/transport-ble |
Native BLE Transport (Node.js / Electron) | sdk-core (peer), noble |
依存関係の図
sdk-core はブラウザ API
やネイティブモジュールに依存しない TypeScript
パッケージです（./bitcoin が呼ぶ fetch
だけは実行環境のものを使います。引数 fetchImpl
で差し替えられます）。各 Transport
パッケージがプラットフォーム固有の実装を提供します。ネイティブアプリ向けの
Swift / Kotlin / C# ライブラリは計画中です。
@openloop/sdk-core
の入口
| import 先 | 内容 |
|---|---|
@openloop/sdk-core |
OpenloopSDK、各チェーンの App
クラス、ITransport、WcTransport、エラー（OpenloopError・ApduError・TransportError）、定数、ユーティリティ |
@openloop/sdk-core/verify |
デバイスが返した署名の検証（viem を読み込みます） |
@openloop/sdk-core/bitcoin |
Bitcoin の出口。アドレス・UTXO・手数料・PSBT・放送の関数と
BtcError。viem を読み込みません |
Bitcoin の出口
BitcoinApp
はデバイスと話す層です。これに対して、サブパス
@openloop/sdk-core/bitcoin は、デバイスの外側で済む Bitcoin
の仕事を、状態を持たない関数として提供します。
- 口座の拡張公開鍵から受け取りアドレスを導く、宛先のアドレスを検証する、路を組み立てる
- 端点（Esplora 互換）に訊いて、残高の走査・UTXO・料率・前の取引を取る
- UTXO を選び、PSBT を組み、署名済み PSBT から生の取引を取り出して、放送する
網・端点・時間切れ・路・口座・キャッシュは、すべて引数で渡します。モジュールの中に既定値も状態も持たないので、複数の網や口座を同時に扱えます。誤りは
BtcError（code
で分類）で返します。デバイスに署名させる段だけが BitcoinApp
です。
典型的な流れ: BitcoinApp.getExtendedPubkey で口座の xpub
を取る → scanAccount で残高と UTXO を取る →
selectUtxos と buildPsbt で PSBT を組む →
BitcoinApp.signPsbtWithPaths でデバイスに署名させる →
extractRawTx と broadcastTx で放送する。API は
API リファレンス
を参照してください。
APDU プロトコル概要
SDK とデバイス間の通信は APDU（Application Protocol Data Unit）コマンドで行われます。
コマンド構造
[CLA] [INS] [P1] [P2] [Lc] [Data...]| フィールド | サイズ | 説明 |
|---|---|---|
| CLA | 1 byte | クラスバイト（0xE0: Ledger 互換, 0xF0:
Openloop 独自） |
| INS | 1 byte | 命令コード |
| P1 | 1 byte | パラメータ 1（チャンキング制御等） |
| P2 | 1 byte | パラメータ 2（曲線選択等） |
| Lc | 1 byte（長いときは 3 bytes） | データ長。データが 255 bytes を超えるときは、0x00 +
長さ 2 bytes の拡張形式（SDK が自動で選ぶ） |
| Data | Lc bytes | コマンドデータ |
レスポンス構造
[Data...] [SW1] [SW2]| フィールド | サイズ | 説明 |
|---|---|---|
| Data | 可変 | レスポンスデータ |
| SW1-SW2 | 2 bytes | ステータスワード（0x9000 = 成功） |
CLA バイト
| CLA | 用途 |
|---|---|
0xE0 |
Ledger 互換コマンド（BTC getAddress, ETH, XRP, SOL, TRON） |
0xE1 |
Openloop の拡張コマンド（任意の路の拡張公開鍵
GET_EXTENDED_PUBKEY） |
0xF0 |
Openloop 独自コマンド（chain_id 対応署名, PSBT, BTC xpub・メッセージ署名, EIP-712 ストリーミング, デバイス情報） |
詳細な APDU ステータスワードは エラー処理 を参照してください。
次のステップ
- クイックスタート — 開発者向け導入ガイド
- Transport 選択ガイド — プラットフォーム対応表
- API リファレンス — 全型定義・インターフェース一覧