跳到主要内容

口令要点

Passphrase 用于在同一套助记词之上派生不同的钱包。对集成应用来说，关键不是“自动处理”，而是清楚地区分：当前请求是使用标准钱包，还是让用户输入 Passphrase 进入隐藏钱包。

关键要点​

  • 标准钱包等于“助记词 + 空 Passphrase”。
  • 隐藏钱包等于“助记词 + 非空 Passphrase”，并且区分大小写。
  • Passphrase 无法找回，用户必须准确备份；多一个空格、大小写不同，都会进入不同钱包。
  • 如果某个请求明确要走标准钱包，请设置 useEmptyPassphrase: true。

应用行为​

应用通常有两种处理方式：

明确使用标准钱包​

当业务流程不需要隐藏钱包时，直接在请求参数中声明使用空 Passphrase：

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

响应 Passphrase 事件​

当 SDK 发送 UI_REQUEST.REQUEST_PASSPHRASE 时，应用需要给用户一个明确选择：改在设备上输入，或在当前界面输入。

// 让 Passphrase 直接在设备上完成，宿主应用不碰它。
ukeySdk.uiResponse({
  type: UI_RESPONSE.RECEIVE_PASSPHRASE,
  payload: { passphraseOnDevice: true, value: "" },
});

// 也可以在软件界面里填写，并按需要缓存到本次会话。
ukeySdk.uiResponse({
  type: UI_RESPONSE.RECEIVE_PASSPHRASE,
  payload: { value, passphraseOnDevice: false, save: true },
});

缓存与会话​

  • 可通过 获取 Passphrase 状态 读取 passphraseState，再配合通用参数传入后续请求。
  • keepSession / initSession 可以减少同一流程内的重复确认，但不要把它当作长期保存 Passphrase 的机制。

关键说明​

  • 不要打印、上传、同步或长期保存 Passphrase。
  • 软件输入框必须掩码显示，并让用户清楚知道是否启用会话缓存。
  • 如果用户不希望宿主应用接触 Passphrase，请优先提供设备端输入。
  • PIN 与 Passphrase 是两类交互：UKey Core 26 的 PIN 必须改在设备上输入，但 Passphrase 仍可根据 UX 选择设备端或软件端输入。

另请参阅：常见入参（CommonParams），事件说明。