From 05448788c949c130be62ae1be7cd5a3492186d38 Mon Sep 17 00:00:00 2001 From: Cursor Agent Date: Mon, 18 May 2026 16:03:38 +0000 Subject: [PATCH] docs: align package names and add Ledger connector notes Co-authored-by: Leon --- README.md | 5 +- docs/architecture.md | 56 ++++++++++++++++++++-- packages/hd-transport-web-device/README.md | 29 ++++------- 3 files changed, 66 insertions(+), 24 deletions(-) diff --git a/README.md b/README.md index ca9b9fedc..adc2b428d 100644 --- a/README.md +++ b/README.md @@ -6,14 +6,14 @@ 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) | The core process of hardware wallet connection. | | [@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-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) | device transport entrypoints for web runtimes | | [@onekeyfe/hd-shared](./packages/shared) | Tools, error definitions, constants | | [@onekeyfe/hardware-cli](./packages/hd-cli) | CLI for AI agent integration (Claude Code, Cursor, etc.) | @@ -36,6 +36,7 @@ Run a dev build: - `yarn dev:ble` (react-native sdk) - `yarn dev:core` (core package) - `yarn dev:transport-http` (transport-http package) +- `yarn dev:transport-web-device` (web device transport package) - `yarn dev:shared` (shared package) ### Development with example desktop app (Recommend) diff --git a/docs/architecture.md b/docs/architecture.md index a0f1544f0..2f15671e3 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`** - Web 设备传输入口（WebUSB / Electron BLE） - **`@onekeyfe/hd-transport-usb`** - Node.js USB传输（CLI/服务端，基于 libusb） - **`@onekeyfe/hd-transport-http`** - HTTP Bridge传输 - **`@onekeyfe/hd-transport-lowlevel`** - 低层传输（BLE 插件模式） @@ -32,6 +32,12 @@ SDK接口层 (@onekeyfe/core) - **`@onekeyfe/hd-web-sdk`** - Web平台SDK - **`@onekeyfe/hd-ble-sdk`** - 移动端BLE SDK +### Ledger 集成（HWK） +- **`@onekeyfe/hwk-adapter-core`** - Connector 抽象、桥接接口与通用类型 +- **`@onekeyfe/hwk-ledger-adapter`** - Ledger 链适配与 signer 封装 +- **`@onekeyfe/hwk-ledger-connector-webhid`** - 基于 WebHID 的 Ledger `IConnector` 实现 +- **`@onekeyfe/hwk-ledger-connector-ble`** - 基于 React Native BLE 的 Ledger `IConnector` 实现 + ### 示例应用 - **`@onekeyfe/connect-examples`** - 集成示例 - `expo-example` - Web集成示例 @@ -106,12 +112,56 @@ switch(env) { │ └── @onekeyfe/hd-transport │ └── 传输层实现 - ├── @onekeyfe/hd-transport-webusb (浏览器) + ├── @onekeyfe/hd-transport-web-device (WebUSB / Electron BLE) ├── @onekeyfe/hd-transport-usb (Node.js CLI) ├── @onekeyfe/hd-transport-lowlevel (BLE 插件) └── @onekeyfe/hd-transport-http (Bridge) ``` +## 🔌 Ledger Connector 接口 + +HWK 包统一实现 `IConnector` 接口，公共调用面如下： + +```typescript +interface IConnector { + searchDevices(): Promise; + connect(deviceId?: string): Promise; + disconnect(sessionId: string): Promise; + call(sessionId: string, method: string, params: unknown): Promise; + cancel(sessionId: string): Promise; + uiResponse(response: UiResponseEvent): void; + on(event, handler): void; + off(event, handler): void; + reset(): void; +} +``` + +典型接入方式： + +```typescript +import { createLedgerWebHidConnector } from '@onekeyfe/hwk-ledger-connector-webhid'; + +const connector = createLedgerWebHidConnector(); +const [device] = await connector.searchDevices(); + +if (!device) { + throw new Error('No Ledger device found'); +} + +const session = await connector.connect(device.deviceId); +``` + +已实现的交互事件（`ui-event`）包括： +- `searching` +- `confirm-open-app` +- `unlock-device` +- `confirm-on-device` +- `interaction-complete` + +使用约束： +- WebHID Connector 面向浏览器 / 桌面 WebHID 场景。 +- BLE Connector 面向 React Native，包本身声明了 `react-native` peer dependency。 + ## 🔧 开发工具 - **Lerna** - Monorepo管理 diff --git a/packages/hd-transport-web-device/README.md b/packages/hd-transport-web-device/README.md index ce474b64c..bffaf4aeb 100644 --- a/packages/hd-transport-web-device/README.md +++ b/packages/hd-transport-web-device/README.md @@ -1,28 +1,19 @@ -# `@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` provides device-facing transport entrypoints for web runtimes. -## What is the purpose +## Exports -- translate JSON payloads to binary messages using protobuf definitions comprehensible to OneKey devices -- chunking and reading chunked messages according to the [OneKey protocol](./protocol.md) -- exposing single API for various transport methods: - - Http Transport - - React Native Transport - - WebUSB -- Create and expose typescript definitions based on protobuf definitions. +- `WebUsbTransport` - browser transport implemented in `src/webusb.ts` +- `ElectronBleTransport` - Electron BLE transport implemented in `src/electron-ble-transport.ts` -### The short version +## Development -In order to be able to use new features of onekey-firmware you need to update protobuf definitions. +Run the package in watch mode from the repository root: -1. `git submodule update --init --recursive` to initialize git submodules. -1. `yarn update-submodules` to update firmware submodule -1. `yarn update:protobuf` to generate new `./messages.json` and `./src/types/messages.ts` - -git submodule update --init --recursive to initialize firmware submodule -yarn update-submodules to update firmware submodule -yar update:protobuf to generate new ./messages.json and ./src/types/messages.ts +```bash +yarn dev:transport-web-device +``` ## Docs