本页目录

标识符（Identifiers）

connectId 用于路由请求，deviceId 将请求绑定到设备当前种子，passphraseState 将请求绑定到隐藏钱包。这些值不能互相替代。

标识符参考

字段	用途	获取位置	使用方式
`connectId`	传输路由标识	成功的 `searchDevices().payload` 条目	设备和钱包方法的第一个参数；重连后重新枚举。
`serialNo`	可用时表示物理设备身份	初始化后的发现结果，或 `getDeviceState().payload.identity.serialNo`	跨 USB/BLE 展示或关联同一台设备，不作为路由标识。
`deviceId`	当前种子生命周期内的身份	`getDeviceState().payload.identity.deviceId`，或成功的 `openWalletSession`	钱包方法的第二个参数，用于发现重置、恢复或钱包变化。
`passphraseState`	隐藏钱包指纹	成功打开隐藏钱包后的 `openWalletSession` 结果	每次隐藏钱包地址/签名请求都传入，与 `deviceId` 一起保存。
`uuid`	已废弃的兼容标识	部分设备或搜索结果	物理身份优先用 `serialNo`，路由用 `connectId`；初始化前可能为空。
固件 `session_id`	内部解锁句柄	由 SDK Core 管理	不读取、不记录、不持久化，也不在公开调用中传入。
`name`、`label`、`deviceType`	显示与能力信息	发现结果或设备状态	不是唯一标识，也不能证明协议或钱包身份。

`connectId` —— 路由用的 key

同一台物理设备在 USB 与 BLE 下有不同的 connectId。按传输分别保存连接记录。连接标识不保证等于物理序列号：硬件身份尚不可用时，USB 描述符可能先提供路由路径。

将它视为不透明值。BLE 格式取决于宿主平台，例如 Android 地址或 iOS 外设 UUID；不要将其转换为另一种传输的格式，也不要把它当作设备真实性证明。

searchDevices 可能返回 connectId: null。先选择具有可用连接标识的候选设备，再调用设备方法。

`deviceId` —— 钱包身份检查


const state = await HardwareSDK.getDeviceState(connectId);
if (!state.success) throw new Error(state.payload.error);
const deviceId = state.payload.identity.deviceId;
if (!deviceId) throw new Error('Device has no wallet identity');
 
const address = await HardwareSDK.evmGetAddress(connectId, deviceId, {
  path: "m/44'/60'/0'/0/0",
  useEmptyPassphrase: true,
  showOnOneKey: true,
});
if (!address.success) throw new Error(address.payload.error);

同一种子上的标准钱包与隐藏钱包共享种子生命周期内的 deviceId。隐藏钱包还需要自己的 passphraseState。

遇到 DeviceCheckDeviceIdError 时，停止操作并刷新设备状态。更新已有绑定前，应让用户确认目标钱包；静默替换缓存 ID 可能让后续请求进入另一个钱包。

`device_id`（蛇形）vs `deviceId`（驼峰）

device_id 是 Protocol V1 getFeatures() 结果中的旧字段。新代码应读取支持两个协议族的 getDeviceState() 中的规范化字段 identity.deviceId。初始化前的发现结果可能包含 deviceId: null。

隐藏钱包绑定


const opened = await HardwareSDK.openWalletSession(connectId, {
  mode: 'select-hidden',
});
if (!opened.success) throw new Error(opened.payload.error);
if (opened.payload.walletType !== 'hidden' || !opened.payload.passphraseState) {
  throw new Error('A hidden wallet was not opened');
}
 
const address = await HardwareSDK.evmGetAddress(connectId, opened.payload.deviceId, {
  path: "m/44'/60'/0'/0/0",
  passphraseState: opened.payload.passphraseState,
  showOnOneKey: true,
});
if (!address.success) throw new Error(address.payload.error);

只有响应成功后才保存绑定。将它作为与钱包相关的应用数据妥善保护；不要保存密码短语本身或固件会话句柄。

省略 passphraseState 不会把调用绑定到目标隐藏钱包。隐藏钱包使用验证过的指纹，标准钱包使用 useEmptyPassphrase: true，两者不能同时传入。

绑定不匹配时停止操作，让用户重新选择目标钱包。不要覆盖绑定后自动重放签名请求。

各方法的 ID 要求

调用形态	示例
SDK 生命周期，不接收连接位置参数	`init`、`searchDevices`、`on`/`off`、`dispose`
设备操作或钱包选择，传 `connectId`	`getDeviceState`、`openWalletSession`、`deviceSettings`、`deviceVerify`
钱包操作，传 `connectId` + `deviceId`	`evmGetAddress`、`btcSignTransaction`、`solSignTransaction`
隐藏钱包操作	钱包操作的参数中额外传入 `passphraseState`

部分方法为了兼容允许省略标识符，请遵循具体方法的公开签名。多设备应用应明确选择设备。UI 响应使用独立的请求关联身份；按 UI 事件说明转发事件中的 responseCorrelation。