Solana Signer

Solana 硬件签名全链路指南，覆盖地址确认与交易/消息签名，强调固定硬化路径、序列化消息签名与设备可验证。

工作原理

通过 HardwareSDK 与设备 App 通信，设备会展示序列化 rawTx（仅接受十六进制字符串，0x 可选）中的来源/目标/金额/费用摘要，确认后返回签名；应用端将签名附加到交易（@solana/web3.js）并验证公钥。

关键点：

路径固定为全硬化、长度 4：m/44'/501'/account'/0'（如 m/44'/501'/0'/0'）。
rawTx 只接受十六进制字符串，若拿到 Transaction/VersionedTransaction，请先 Buffer.from(tx.serialize()).toString('hex')。
需要应用端自行构造并序列化消息/交易（含 recent blockhash）；若为 Versioned Tx，固件需 Classic1s ≥ 3.1.0、Touch ≥ 4.3.0。

安装


npm i @onekeyfe/hd-core @onekeyfe/hd-common-connect-sdk

初始化


import HardwareSDK from '@onekeyfe/hd-common-connect-sdk';
await HardwareSDK.init({ env: 'webusb', fetchConfig: true, debug: false });
const [{ connectId }] = await HardwareSDK.searchDevices();
const deviceId = (await HardwareSDK.getFeatures(connectId)).payload?.device_id;

适用场景

场景 1：获取地址


const path = "m/44'/501'/0'/0'";
const res = await HardwareSDK.solGetAddress(connectId, deviceId, {
  path,
  showOnOneKey: true,
});
// res.payload.address, publicKey?, path

参数

path: 必填，必须满足 44'/501'/account'/0' 的全硬化结构。
showOnOneKey?: 可选，是否在设备上展示并确认。


Promise<{ success, payload: { address, path, publicKey? } }>

场景 2：签名交易


const res = await HardwareSDK.solSignTransaction(connectId, deviceId, {
  path: "m/44'/501'/0'/0'",
  rawTx,
  keepSession: true,
});
// res.payload.signature

参数

path: 必填，同上。
rawTx: 必填，序列化消息/交易（十六进制字符串，0x 可选；如原始值为 Transaction.serialize() 的 Uint8Array，需自行转 hex）。
keepSession?: 可选，多次签名复用会话。


Promise<{ success, payload: { signature } }>

可附加到 Transaction 后广播。

交互与状态

接口以 Promise 结束；用户提示通过 UI_REQUEST 事件触发（解锁设备、打开 Solana App、确认交易）。
同一设备串行调用；多次签名可用 keepSession 减少重复提示。

示例

示例：交易签名


import HardwareSDK from '@onekeyfe/hd-common-connect-sdk';
 
await HardwareSDK.init({ env: 'webusb', debug: false });
 
const [{ connectId }] = await HardwareSDK.searchDevices();
const deviceId = (await HardwareSDK.getFeatures(connectId)).payload?.device_id;
 
const path = "m/44'/501'/0'/0'";
await HardwareSDK.solGetAddress(connectId, deviceId, { path, showOnOneKey: true });
 
// 已有 Transaction / VersionedTransaction 时，需先转为十六进制：
// const rawTx = Buffer.from(transaction.serialize()).toString('hex');
// 下方示例为已序列化好的 rawTx hex，可直接用于设备确认
const rawTx =
  '4301355cc18d85809872bcbd63cb6ea5ac3c2814a1bacf2e50d8ec62367211917b79ecd1f1a98fa0d793d7cb92ebd9a479dc6aba0ae8570253aa87c0da32db5ed2bd401f3bbee52c2bc55761fd8486fae2e28f46499282f4267b8b90fc8c1cc97bb659b6cc927f2ec1701ef2928ddb84759ba5c557f549db';
 
const { success, payload } = await HardwareSDK.solSignTransaction(connectId, deviceId, {
  path,
  rawTx,
  keepSession: true,
});
 
if (success) {
  console.info('signature:', payload.signature);
}

验签与排障

路径：必须遵循 44'/501'/account'/0' 全硬化；其他路径会被拒。
消息/交易：确保包含最新 recentBlockhash、正确的账户列表和指令顺序。
设备核对：路径/账户、公链币金额、目标账户、费用摘要需与前端一致。
验签：用 @solana/web3.js 将签名附加到 Transaction，验证签名公钥等于 solGetAddress 返回值。
常见问题：
- 超大消息或不支持的指令：精简指令或拆分交易。
- 会话交互：同一设备串行调用，多次签名可启用 keepSession。
- 拒签/超时：提供重试/取消，不要自动重播。

参见方法文档：solSignTransaction。