diff --git a/README.md b/README.md index ca9b9fedc..8474d524f 100644 --- a/README.md +++ b/README.md @@ -6,16 +6,20 @@ Hardware-js-sdk is designed to allow third-party developers to quickly access th | package | description | | --------------------------------------------------------------------------- | --------------------------------------------------------------------- | -| [@onekeyfe/core](./packages/core) | The core process of hardware wallet connection. | +| [@onekeyfe/hd-core](./packages/core) | Core connection flows and chain APIs for OneKey hardware devices. | | [@onekeyfe/hd-web-sdk](./packages/hd-web-sdk) | Using the sdk in the web platform. | | [@onekeyfe/hd-ble-sdk](./packages/hd-ble-sdk) | Using the SDK in BLE communication environment. e.g: iOS / Android | -| [@onekeyfe/hd-common-sdk](./packages/hd-common-connect-sdk) | Using the SDK in a node or web-usb environment | +| [@onekeyfe/hd-common-connect-sdk](./packages/hd-common-connect-sdk) | Shared SDK runtime for Node.js and browser transports. | | [@onekeyfe/hd-transport](./packages/hd-transport) | Data serialization and deserialization of hardware communication data | | [@onekeyfe/hd-transport-http](./packages/hd-transport-http) | communication lib for http | | [@onekeyfe/hd-transport-react-native](./packages/hd-transport-react-native) | communication lib for React Native | -| [@onekeyfe/hd-transport-webusb](./packages/hd-transport-webusb) | communication lib for WebUSB | +| [@onekeyfe/hd-transport-web-device](./packages/hd-transport-web-device) | communication lib for WebUSB/WebHID browser environments | | [@onekeyfe/hd-shared](./packages/shared) | Tools, error definitions, constants | | [@onekeyfe/hardware-cli](./packages/hd-cli) | CLI for AI agent integration (Claude Code, Cursor, etc.) | +| [@onekeyfe/hwk-adapter-core](./packages/hwk-adapter-core) | Shared types, events, and error contracts for hardware adapters | +| [@onekeyfe/hwk-ledger-adapter](./packages/hwk-ledger-adapter) | Vendor-neutral Ledger adapter with chain methods and retry handling | +| [@onekeyfe/hwk-ledger-connector-webhid](./packages/hwk-ledger-connector-webhid) | WebHID connector for Ledger devices in browser environments | +| [@onekeyfe/hwk-ledger-connector-ble](./packages/hwk-ledger-connector-ble) | React Native BLE connector for Ledger devices | ## Documentation diff --git a/docs/architecture.md b/docs/architecture.md index a0f1544f0..1e9630869 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -7,7 +7,7 @@ OneKey Hardware SDK 采用三层架构设计： ``` 应用层 (DApps) ↓ -SDK接口层 (@onekeyfe/core) +SDK接口层 (@onekeyfe/hd-core) ↓ 传输抽象层 (@onekeyfe/hd-transport) ↓ @@ -23,7 +23,7 @@ SDK接口层 (@onekeyfe/core) - **`@onekeyfe/hd-transport`** - 传输层抽象 ### 传输层 -- **`@onekeyfe/hd-transport-webusb`** - WebUSB传输（浏览器） +- **`@onekeyfe/hd-transport-web-device`** - WebUSB / WebHID 传输（浏览器） - **`@onekeyfe/hd-transport-usb`** - Node.js USB传输（CLI/服务端，基于 libusb） - **`@onekeyfe/hd-transport-http`** - HTTP Bridge传输 - **`@onekeyfe/hd-transport-lowlevel`** - 低层传输（BLE 插件模式） @@ -32,6 +32,14 @@ SDK接口层 (@onekeyfe/core) - **`@onekeyfe/hd-web-sdk`** - Web平台SDK - **`@onekeyfe/hd-ble-sdk`** - 移动端BLE SDK +### Ledger 适配层（`hwk-*`） +- **`@onekeyfe/hwk-adapter-core`** - 多厂商硬件适配层的共享类型、事件、错误码与 connector contract +- **`@onekeyfe/hwk-ledger-adapter`** - Ledger 的统一钱包接口实现，封装设备发现、链方法调用、重试与指纹校验 +- **`@onekeyfe/hwk-ledger-connector-webhid`** - 浏览器 WebHID 连接器 +- **`@onekeyfe/hwk-ledger-connector-ble`** - React Native BLE 连接器 + +这套 `hwk-*` 栈与 `@onekeyfe/hd-core` 主 SDK 并行存在，主要用于接入 Ledger 等多厂商设备；它不是 `hd-core` 的 transport 插件。宿主应用通常先选择 connector（WebHID 或 BLE），再创建 `LedgerAdapter`，并处理 `ui-request-device-permission`、`ui-request-device-connect`、`ui-request-install-app` 等交互事件。 + ### 示例应用 - **`@onekeyfe/connect-examples`** - 集成示例 - `expo-example` - Web集成示例 @@ -88,7 +96,7 @@ abstract class BaseMethod { ```typescript // 根据环境选择传输方式 switch(env) { - case 'webusb': return new WebUsbTransport(); // 浏览器 WebUSB + case 'web-device': return new WebUsbTransport(); // 浏览器 WebUSB / WebHID case 'node-usb': return new NodeUsbTransport(); // Node.js libusb (CLI) case 'lowlevel': return new LowlevelTransport(); // BLE 插件模式 case 'http': return new HttpTransport(); // HTTP Bridge @@ -106,12 +114,24 @@ switch(env) { │ └── @onekeyfe/hd-transport │ └── 传输层实现 - ├── @onekeyfe/hd-transport-webusb (浏览器) + ├── @onekeyfe/hd-transport-web-device (浏览器) ├── @onekeyfe/hd-transport-usb (Node.js CLI) ├── @onekeyfe/hd-transport-lowlevel (BLE 插件) └── @onekeyfe/hd-transport-http (Bridge) ``` +Ledger 适配层（并行架构）： + +```text +宿主应用 +├── @onekeyfe/hwk-ledger-adapter +│ └── @onekeyfe/hwk-adapter-core +│ +└── 连接器实现 + ├── @onekeyfe/hwk-ledger-connector-webhid (Browser WebHID) + └── @onekeyfe/hwk-ledger-connector-ble (React Native BLE) +``` + ## 🔧 开发工具 - **Lerna** - Monorepo管理 diff --git a/packages/hd-transport-web-device/README.md b/packages/hd-transport-web-device/README.md index ce474b64c..f5d412e1a 100644 --- a/packages/hd-transport-web-device/README.md +++ b/packages/hd-transport-web-device/README.md @@ -1,6 +1,6 @@ -# `@onekeyfe/hd-transport-webusb` +# `@onekeyfe/hd-transport-web-device` -`@onekeyfe/hd-transport-webusb` is a library that implements transport communication by WebUSB. +`@onekeyfe/hd-transport-web-device` is a library that implements browser transport communication over WebUSB/WebHID. ## What is the purpose diff --git a/packages/hwk-ledger-adapter/README.md b/packages/hwk-ledger-adapter/README.md new file mode 100644 index 000000000..2249aeb41 --- /dev/null +++ b/packages/hwk-ledger-adapter/README.md @@ -0,0 +1,116 @@ +# `@onekeyfe/hwk-ledger-adapter` + +`@onekeyfe/hwk-ledger-adapter` exposes a vendor-neutral hardware wallet interface for Ledger devices. It sits on top of a transport-specific connector and handles device discovery, request/response UI events, chain-method dispatch, retry logic, and device fingerprint checks. + +## Related packages + +- `@onekeyfe/hwk-adapter-core` - shared types, event constants, and error codes +- `@onekeyfe/hwk-ledger-connector-webhid` - browser connector for WebHID +- `@onekeyfe/hwk-ledger-connector-ble` - React Native connector for BLE + +## Installation + +```bash +npm install @onekeyfe/hwk-adapter-core @onekeyfe/hwk-ledger-adapter @onekeyfe/hwk-ledger-connector-webhid +``` + +Use `@onekeyfe/hwk-ledger-connector-ble` instead of the WebHID connector when you integrate in React Native over BLE. + +## Quick start + +```ts +import { UI_REQUEST, UI_RESPONSE } from '@onekeyfe/hwk-adapter-core'; +import { LedgerAdapter } from '@onekeyfe/hwk-ledger-adapter'; +import { createLedgerWebHidConnector } from '@onekeyfe/hwk-ledger-connector-webhid'; + +const connector = createLedgerWebHidConnector(); +const hw = new LedgerAdapter(connector, { + autoInstallApp: true, +}); + +hw.on(UI_REQUEST.REQUEST_DEVICE_PERMISSION, () => { + // Reply only after your browser or native permission flow succeeds. + hw.uiResponse({ + type: UI_RESPONSE.RECEIVE_DEVICE_PERMISSION, + payload: { granted: true }, + }); +}); + +hw.on(UI_REQUEST.REQUEST_INSTALL_APP, () => { + // Replace this with a real user confirmation in your app UI. + hw.uiResponse({ + type: UI_RESPONSE.RECEIVE_INSTALL_APP, + payload: { confirmed: true }, + }); +}); + +const devices = await hw.searchDevices(); +if (!devices.length) { + throw new Error('No Ledger device found'); +} + +const [{ connectId, deviceId = '' }] = devices; + +await hw.connectDevice(connectId); + +const result = await hw.evmGetAddress(connectId, deviceId, { + path: "m/44'/60'/0'/0/0", + showOnDevice: false, +}); + +if (!result.success) { + throw new Error(result.payload.error); +} + +console.log(result.payload.address); + +await hw.dispose(); +``` + +## What the adapter provides + +- Transport-agnostic `IHardwareWallet` methods for `evm`, `btc`, `sol`, and `tron` +- Automatic permission and reconnect request events +- Optional app installation flow through `autoInstallApp` +- Batched `allNetworkGetAddress(...)` calls with fingerprint verification +- `cancel(connectId?)` for aborting the active operation + +## Integration notes + +### UI request / response flow is required + +The adapter emits request events such as: + +- `ui-request-device-permission` +- `ui-request-device-connect` +- `ui-request-install-app` + +Your host app must answer them through `hw.uiResponse(...)`. If `ui-request-device-permission` is never answered, the request times out instead of waiting forever. + +### Pick the connector for the host platform + +- Use `createLedgerWebHidConnector()` in browser environments. +- Use `createLedgerBleConnector()` in React Native BLE environments. +- BLE flows require an explicit `connectId` returned by discovery. The adapter does not auto-pick a BLE device. + +### Do not persist `connectId` + +`connectId` is a transport-session identifier. It can change after USB replug or WebHID rediscovery. If you need a stable identity for later verification, derive and persist a chain fingerprint with `getChainFingerprint(...)` after the first successful device call. + +## Troubleshooting + +### No device found + +Listen for `ui-request-device-connect` and prompt the user to connect and unlock the Ledger device before retrying. + +### Multiple USB devices connected + +The adapter refuses to auto-pick between multiple Ledger USB devices and returns `DeviceOneDeviceOnly`. Ask the user to leave a single device connected or add an explicit device selection step in your host app. + +### Wrong app open or app missing + +Chain calls can fail with `WrongApp` or `AppNotInstalled`. If you enable `autoInstallApp`, also handle `ui-request-install-app` and the forwarded `ui-event` progress updates. + +### Permission request keeps failing + +The permission response must reflect the real browser or native permission result. Reply with `granted: false` when the platform denies access so your app can surface the correct failure reason.