Passphrase（核心指南）

处理 OneKey 设备 Passphrase（隐藏钱包）的基本规则。

关键要点

• 标准钱包 vs 隐藏钱包：
  • 标准钱包 = 助记词 + 空 Passphrase
  • 隐藏钱包 = 助记词 + 非空 Passphrase（区分大小写；任何改动都会生成不同的钱包）
• 重要提示：Passphrase 遗忘后无法恢复，请妥善备份。输入时必须完全一致（区分大小写）。
• 相关：要在调用中强制使用标准钱包，请设置 useEmptyPassphrase: true

应用行为

使用 Passphrase 的两种方式：

1. 主动意图（推荐）

• 为单次调用强制使用标准钱包：

await HardwareSDK.evmGetAddress(connectId, deviceId, {
  path: "m/44'/60'/0'",
  useEmptyPassphrase: true,
});

2. 响应式事件处理

• 在 UI_REQUEST.REQUEST_PASSPHRASE 时，显示单个提示，包含两个操作：
  • 在设备上输入（首选）：

    HardwareSDK.uiResponse({
      type: UI_RESPONSE.RECEIVE_PASSPHRASE,
      payload: { passphraseOnDevice: true, value: '' },
    });

  • 在此屏幕上输入（软件输入；可选择为会话缓存）：

    HardwareSDK.uiResponse({
      type: UI_RESPONSE.RECEIVE_PASSPHRASE,
      payload: { value, passphraseOnDevice: false, save: true },
    });

缓存与会话

• passphraseState：通过 获取 Passphrase 状态 获取一次，并在 通用参数 中传入，以减少重复提示。
• 结合 keepSession / initSession 使用，可减少流程中的交互次数。

注意事项

• 不要记录或持久化 Passphrase；掩码输入。
• 建议在设备上输入以获得更好的安全性。
• Pro/Touch：PIN 必须在设备上输入；Passphrase 仍可在设备或软件中输入（建议使用设备）。

另请参阅：通用参数，事件配置。