From 72c331e25bfe35cb681e5e5eaeb7371c8a29dc44 Mon Sep 17 00:00:00 2001
From: Cursor Agent <cursoragent@cursor.com>
Date: Mon, 11 May 2026 16:03:56 +0000
Subject: [PATCH] docs: clarify TON signData support boundaries

Co-authored-by: Leon <lixiao.dev@gmail.com>
---
 docs/chain.md                 | 50 +++++++++++++++++++++++++++++++++++
 docs/device-method-support.md |  4 ++-
 2 files changed, 53 insertions(+), 1 deletion(-)

diff --git a/docs/chain.md b/docs/chain.md
index 61ad0d79c..429752356 100644
--- a/docs/chain.md
+++ b/docs/chain.md
@@ -178,6 +178,56 @@ OneKey硬件钱包通过统一的密码学原语支持80+区块链：
 - **TON (Telegram Open Network):** SLIP-44: 607, 路径: m/44'/607'/0', 地址格式: Base64URL
 - **NEM:** SLIP-44: 43, 路径: m/44'/43'/0'/0'/0', 特殊: 使用Keccak哈希变种
 
+### 3.3 TON 签名接口补充
+
+近期源码新增了 `tonSignData`，用于承接 TON Connect v2 的 `signData` 流程。该方法目前已接入 SDK 公开类型、调用注入层，以及 `expo-example` 的 playground 示例。
+
+#### `tonSignData` 的请求形状
+
+| 字段 | 是否必填 | 说明 |
+|------|----------|------|
+| `path` | 是 | HD 路径。SDK 会做 `validatePath(path, 3)` 校验，现有 TON 示例使用 `m/44'/607'/0'`。 |
+| `type` | 是 | `TonSignDataType` 枚举：`0 = TEXT`、`1 = BINARY`、`2 = CELL`。 |
+| `payload` | 是 | 十六进制字符串。SDK 会在发送到底层协议前做十六进制格式化。 |
+| `appdomain` | 是 | TON Connect 请求来源域名。 |
+| `timestamp` | 是 | 时间戳字段；现有示例使用 Unix 秒级时间戳。 |
+| `schema` | 否 | `CELL` 类型的 TL-B schema。`expo-example` 的 `CELL` 示例会显式传入它。 |
+| `fromAddress` | 否 | 调用方提供的 TON 地址字符串。 |
+| `walletVersion` | 否 | TON wallet version，和 `tonGetAddress` / `tonSignMessage` / `tonSignProof` 复用同一套地址派生参数。 |
+| `walletId` | 否 | wallet id。 |
+| `workchain` | 否 | workchain 标识。 |
+| `isBounceable` | 否 | 地址格式开关。 |
+| `isTestnetOnly` | 否 | 是否使用测试网地址格式。 |
+
+#### 返回值
+
+设备成功响应后，SDK 返回 `TonSignedData`，当前结构包含以下可选字段：
+
+- `signature`
+- `digest`
+
+#### 示例
+
+```typescript
+await HardwareSDK.tonSignData(connectId, deviceId, {
+  path: "m/44'/607'/0'",
+  type: 0, // TonSignDataType.TEXT
+  payload: '48656c6c6f204f6e654b6579',
+  appdomain: 'onekey.so',
+  timestamp: Math.floor(Date.now() / 1000),
+  fromAddress: 'UQBYkuShkZzRYAWX_HrK3kFpeAixiRKd-K7QBXYxl9OBXM0_',
+  walletVersion: 3,
+  isBounceable: false,
+  isTestnetOnly: false,
+});
+```
+
+#### 当前约束
+
+- `tonSignData` 内部调用的是设备协议层的 `TonSignData -> TonSignedData` typed call。
+- 该方法当前把 `strictCheckDeviceSupport` 设为 `false`，原因是支持它的固件最小版本还未在源码中定版；这意味着 SDK 不会像成熟方法那样先按版本矩阵拦截。
+- 如果你要接入 `CELL` 类型，请同时准备 BoC 十六进制 `payload` 和对应 `schema`，并优先参考 `packages/connect-examples/expo-example/src/data/ton.ts` 的现成示例。
+
 ## 4. Substrate系列
 
 ### 4.1 技术规范
diff --git a/docs/device-method-support.md b/docs/device-method-support.md
index 975abf487..7fcce1a7f 100644
--- a/docs/device-method-support.md
+++ b/docs/device-method-support.md
@@ -1,8 +1,10 @@
 # OneKey 硬件设备方法支持列表
 
-> 更新日期: 2026-02-28
+> 更新日期: 2026-05-11
 > 说明：测试用例层面不再通过 skip 隐藏结果，统一按真实返回做 expected 覆盖。
 > 说明：`expected = false` 的用例按“任意失败即通过”判定，同时在结果区展示设备实际错误信息。
+> 说明：本页只汇总 `packages/connect-examples/expo-example/src/testTools/deviceCompatibility/plugins/*.ts` 中已经声明的设备差异。未出现在这些 overrides 里的新方法，不代表已经完成全设备验证。
+> 说明：截至当前源码，`tonSignData` 已接入 `packages/core/src/api/ton/TonSignData.ts` 和 `expo-example` playground 示例，但还没有进入 device-compatibility overrides，因此本页暂不把它列为已验证支持矩阵。
 
 ## 设备型号