# @ckb-keyway/react 中文文档

规范地址：https://npmcn.com/package/%40ckb-keyway/react/

版本：0\.2\.12
npm 元数据更新时间：2026-11-09T13:24:35.486Z
中文译文更新时间：2026-11-09T23:14:44.756Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40ckb-keyway/react
原文对照：https://npmcn.com/package/%40ckb-keyway/react/?lang=original
项目主页：https://ckbkeyway.dev/
源码仓库：https://github.com/officialcmg/ckb-keyway

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：379 kB，5 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：7 个
- peer 依赖：react \>=18\.2\.0
- 首次发布：2026-07-14T22:16:10.138Z
- 最新版本发布：2026-11-09T13:24:35.199Z
- 近 30 天下载量：1924（2026-10-10 至 2026-11-08，npm 官方下载统计）
- 已发布版本数：21（近 12 个月 21 个）

## 中文简介

电子邮件认证的 CKB 钱包和纤维支付基础设施

## 安装

```sh
npm install @ckb-keyway/react
```

也可以使用：`pnpm add @ckb-keyway/react`、`yarn add @ckb-keyway/react`、`bun add @ckb-keyway/react`

## README

# CKB 键瓦

> KeyWay仅在CKB测试网运行.

CKB KeyWay是用于Fiber Network的可重用电子邮件认证的钱包基础设施. 它结合了更好的Auth电子邮件OTP和Resend送货,一个Lit Chipotle PKP,CCC交易构建,以及一个主机或浏览器Fiber节点,这样应用程序就可以恢复稳定的CKB身份并外部为Fiber通道提供资金而无需输出PKP的私人密钥.

该存放处载有两项独立的交付品:

-   公众反应 SDK在 `src/sdk`,包括其框架独立的浏览器客户端.
-   一个独立的节点/后端和一个Next.js参考钱包,显示登录、恢复、频道激活、发票和付款.

项目概况: [ckbkeyway.dev (英语)](https://ckbkeyway.dev/)

现场测试网钱包 : [ckbkeyway.dev/app (英语)](https://ckbkeyway.dev/app)

反应 SDK 文档 : [ckbkeyway.dev (英语)](https://docs.ckbkeyway.dev/)

npm 软件包 : [@ cockb- keyway/ 反应](https://www.npmjs.com/package/@ckb-keyway/react)

独立的 API : [(原始内容存档于2018-10-21). keyway-api- production.up.railway.app](https://keyway-api-production.up.railway.app/healthz)

## 工作流程

1.  SDK向管理中的 KeyWay API 发送电子邮件 OTP 请求; 更好的 Auth 验证应用程序特定代码并创建应用程序绑定会话; KeyWay 提供永久应用程序账户ID .
2.  后端提供或回收一个Lit PKP及其CKB测试网地址.
3.  一个主机节点是用户在KeyWay服务器上持续的本土纤维节点. 一个可选的浏览器节点恢复其单独的纤维特性并加载一个WASM节点.
4.  选中的节点连接到 Fiber 测试网对等点 .
5.  纤维和同行合作构建未署名的资金交易.
6.  后端验证了完整的交易,只计算出KeyWay锁组的CKB sighash.
7.  一个被钉住的Lit动作标志 消化。 KeyWay 验证找到的公用钥匙,并插入其证人.
8.  Fiber 提交签名的交易, 等待 `ChannelReady`,并可以发送或接收发票.
9.  带有主机节点的登录清除SDK会话,而本地节点则保持在线. 浏览器登录停止了Fiber,并在释放设备所有权前上传一个加密的钱包扫描索引DB备份.

KeyWay将每个浏览器节点连接到官方测试网中继器,用于网络可及性和八卦. 其便利活化流量随后更倾向于浏览器可访问的瓶子或Bracer信道供应商,倒回从Fiber图中发现的合格节点. 400 CKB 值为 `channel-peers.ts` 是 KeyWay 发送给这些提供者的最小请求,而不是他们的贡献。 在下面经过核实的1,250 CKB测试网通道中,KeyWay要求1,000 CKB,接受的对等方贡献了剩余的250 CKB;应用程序应读取谈判的 `local_balance` 财务报告和审定财务报表 `remote_balance` 而不是假设每个频道都分开.

## 本地运行

要求:Node.js 20或更新,一个经过验证的Resend发件人,一个已配置的Lit Chipotle账户,以及Postgres.

```sh
npm install
cp .env.example .env.local
npm run build:api
npm run api
# In another terminal:
npm run dev
```

使用配置更好的 Auth、 Postgres 和经过验证的 Resend 发送器 `.env.example`运行 `npm run migrate` 在生产开始前明确。 消费者在开发者控制台上登记确切的出处;演示使用 `NEXT_PUBLIC_KEYWAY_APP_ID`保存数据库、 更好的 Auth、 Resend 和 Lit 证书服务器.

## 反应 SDK

公共软件包拥有电子邮件OTP,登录模式,钱包提供,一个CC签名器,以及一个提供者背后的用户纤维节点. 节点默认由 KeyWay 托管(`fiberNode="hosted"`); 浏览器节点(`fiberNode="browser"`)是一个明确的选择.

在 [ckbkeyway.dev/dashboard (英语)](https://ckbkeyway.dev/dashboard)并复制其公共应用程序ID.

```sh
npm install @ckb-keyway/react
```

```tsx
import { KeyWayLoginButton, KeyWayProvider, useKeyWay, useCkbWallet } from "@ckb-keyway/react";

function Wallet() {
  return (
    <KeyWayProvider appId="keyway_..." appName="My Fiber App" theme="light">
      <KeyWayLoginButton />
      <Balance />
    </KeyWayProvider>
  );
}

function Balance() {
  const { ready, authenticated } = useKeyWay();
  const { balance } = useCkbWallet();
  if (!ready) return <p>Loading KeyWay...</p>;
  if (!authenticated) return null;
  return balance === undefined ? <p>Loading balance...</p> : <p>{balance.toString()} shannons</p>;
}
```

`KeyWayLoginButton` 打开内置的电子邮件 OTP 模式。 登录恢复 CKB 身份而不启动纤维 。 使用 `start()` 从 `useFiber()` 或者说 `KeyWayFiberButton` 需要的时候。 打开频道使用内置审批对话框. 使用 `login()` 财务报告和审定财务报表 `logout()` 从 `useKeyWay()` 用于自定义按钮.

### 反应 API

| API 密码 | 目的 |
| --- | --- |
| `KeyWayProvider` | 拥有电子邮件 OTP、钱包回收、纤维启动和批准对话框 |
| `KeyWayLoginButton` | 打开电子邮件 OTP 模式并登录认证用户 |
| `KeyWayFiberButton` | 当纤维开始或停止时 `autoStartFiber` 关闭 |
| `useKeyWay()` | 认证准备、用户、登录和登录 |
| `useCkbWallet()` | 状态、CCC签名人、地址、公用钥匙、独立余额、刷新、错误和选择入帐收回(`recovery`(中文(简体) ) |
| `useFiber()` | 开始和停止,用户的纤维节点(`node`)渠道、发票、付款估计和结算付款 |

SDK使用KeyWay管理后端. `appId` 识别已注册的申请并强制执行来源. `appName` 标记对话框; `theme` 接受光或暗; `approveFiberChannelOpen`, (中文(简体) ), `approveFiberChannelClose`, (中文(简体) ), `approveFiberPeerConnect`, (中文(简体) ), `approveFiberChannelSettings`, (中文(简体) ), `approveCkbTransaction`, (中文(简体) ), `approveCkbMessage`, (中文(简体) ), `approveRecovery` 财务报告和审定财务报表 `approveBackupChange` 可替换内置对话框,以及 `approveFiberPayment` 增加付款确认. `autoStartFiber` 默认为虚假. `fiberNode` 默认主机; 使用浏览器运行页面中的节点。 认证,账户恢复,和纤维准备都有单独的钩子. 后端 URL 和 证书 在提供者配置中缺失 .

`appName` 更改模式。 电子邮件通过Resend使用已注册应用程序的名称和已存在的中性模板. OTP记录和会话是通过应用程序隔离的;另一个应用程序中的同一电子邮件会得到不同的永久KeyWay账户和钱包. 服务器使用更好的 Auth 绑定会话范围 `databaseHooks.session.create.before` 钩.

成功检察官办公室在没有节点的情况下收回CKB账户. `useCkbWallet()` 独立读取其平衡. `useFiber().start()` 启动浏览器节点或连接主机节点。 浏览器节点在 WASM 启动前恢复任何声称的备份 。 选择自动启动 `autoStartFiber`。 。 。 . `stop()` 不停止主机节点.

在浏览器模式下, 明确 `logout()` 已存在 Fiber 连接后为交易 : KeyWay 在保留设备租赁的同时停止了节点, 仅抓取钱包的索引DB 数据库, 从 Lit 回收的 Fiber 密钥中获取 AES-256-GCM 备份密钥, 用 HKDF- SHA256 , 并将密码文本上传到管理的后端 。 只有在后端独立验证并存储密码文本后,才能清除认证和所有权。 一个新设备在Fiber开始前声称并恢复了一次性备份. 如果备份或还原失败, KeyWay 不释放或消耗唯一可恢复状态 。 日志不停止主机节点 .

`useFiber().node` 是用户的有纤维-js官方方法名称和参数的纤维节点,对主机和浏览器节点来说是相同的:

```ts
const { node } = useFiber();
if (!node) throw new Error("Start Fiber first");

const { channels } = await node.listChannels({});
const { invoice_address } = await node.newInvoice({ amount: "0x5f5e100", description: "Coffee" });
await node.sendPayment({ invoice: fiberInvoice }); // no dialog; may ask for the emailed code
const { payments } = await node.listPayments({});
```

每一种方法都是保密的。 阅读和发票是免费的. `sendPayment` 财务报告和审定财务报表 `sendPaymentWithRouter` 没有内置对话框( 应用程序可以通过) `approveFiberPayment`在主机节点上, 开放和关闭渠道,连接和连接同行 `updateChannel` 显示应用程序可以替换的对话框 . `openChannel`, (中文(简体) ), `acceptChannel` 财务报告和审定财务报表 `abandonChannel` 被封锁,任何没有保密的 都被拒绝 `UNSUPPORTED_METHOD`. 主机节点在 KeyWay 后端执行此功能;浏览器节点在 SDK 中执行此功能. 见 [纤维节点文件](https://docs.ckbkeyway.dev/fiber-node)。 。 。 .

较高层次的帮助者覆盖了共同流量:

```ts
const fiber = useFiber();
await fiber.start();

await fiber.openChannel({ fundingAmount: 500n * 100_000_000n, public: true });

const estimate = await fiber.estimatePayment({ invoice: fiberInvoice, max_fee_amount: "0x5f5e100" });
if (estimate.routable) await fiber.payInvoice(fiberInvoice, { max_fee_amount: "0x5f5e100" });
```

`openChannel()` 默认为1,000 CKB, 接受 `peer`,并打开一个符号频道(例如RUSD) `udtTypeScript` 财务报告和审定财务报表 `fundingAmount`频道资金与其它转账一样. `estimatePayment()` 执行 Fiber 的干线并返回 `{ routable, fee }` 或打入,可重试 `KeyWayError`。 。 。 . `fiber.channels` 列出每个频道的 `canSend`, (中文(简体) ), `canReceive`, (中文(简体) ), `capacity` 财务报告和审定财务报表 `asset`。 。 。 . `closeChannel()` 用户批准后关闭.

一个主机节点运行在KeyWay的服务器上,这些服务器持有它的密钥,在一个孤立的持久本地纤维过程和每个用户的数据目录中,但受主机容量限制. 选择 `<KeyWayProvider fiberNode="browser">` 运行页面中的节点;演示保留在 `/app?mode=browser`。切换模式不会迁移频道:主机和浏览器节点具有单独的特性和状态。 保留现有的专用节点任务.

`fiber.channels` 报告每个频道的链外分配,而不是钱包的链上CKB平衡. 参考应用提供了现成频道的总和 `canSend` 作为主要纤维平衡,保持链上CKB的松散,并列出每个非封闭信道,并有明确的用户端和对等端平衡.

SDK也暴露了Fiber的低水平近距离操作. 合作贴近需要同行参与,并向用户一方支付自己的地址. `force: true` 在频道承诺延迟后关闭, 大约4小时。 在Fiber 0.9.1中,一个被强制关闭的信道被固定在节点自己的密钥上,而不是该信道的关闭脚本上,并且只有在该密钥持有一些CKB以支付费用时. 作为在Fiber向关闭地址支付结算之前的临时措施,用户的第一个通道打开后也会向他们的节点键发送一次性的62 CKB费用储备,KeyWay将结算扫描到用户的地址: Fiber的浏览器构建没有监视器,因此一个浏览器节点的SDK在页面中运行一个,它声称用户分享从Fiber密钥衍生出来的密钥(没有飞行中付款的通道),并在节点开始时和运行时每10分钟扫描一次;一个主机节点的结算在用户下次使用Fiber时被KeyWay所覆盖. 预备队在每个频道关闭后返回用户. 更喜欢合作关闭.

```ts
await fiber.closeChannel(channelId, { force: true });
```

关闭会消耗频道的链上供资单元格,并将最后的频道分配回正常的CKB单元格. 这个 `channel_outpoint` 诊断表明,资助细胞独特的CKB参考:资助交易散列加其产出指数. 它是频道的链上主播,而不是频道ID或平衡.

耗用反应应用程序不需要 Next.js 或后端配置 。 应用程序的使用 `KeyWayProvider` 从不处理会话符号.

开发者控制台支持禁用应用程序,去除来源,设定OTP限制,查看消毒用法并检查API健康. 其会场范围与SDK应用会分开. 消费者不需要认证提供者证书.

以 :

```sh
npm run build:package
```

私人独立后端运行 `npm run api` 和要求 `DATABASE_URL`, (中文(简体) ), `KEYWAY_ALLOWED_ORIGINS`, (中文(简体) ), `KEYWAY_RATE_LIMIT_SECRET`,更好的 Auth/Resend 服务器证书,以及来自 Lit 服务器证书 `.env.example`。它由CKB KeyWay部署,不由公众SDK输出。 Next.js 参考应用没有 API 路由: 它导入已发布 `@ckb-keyway/react` 包,它和外部消费者都使用相同的由SDK管理的铁路终点.

寄存器包为私有. `npm run pack:sdk` 只有阶段和包 `package.sdk.json`,反应/浏览器构建,REDME,和许可证. 仅限服务器 `postgres`, (中文(简体) ), `pg`, (中文(简体) ), `better-auth`,以及 `resend` 依赖性,铁路代码,和Lit Action被排除在外. 发行版本使用 npm 信任的出版: 明文 `v<package-version>` 标签触发器 `.github/workflows/publish.yml`使用一次性邮递、检查类型、构建公共软件包并通过国际开发部出版。 普通承诺不发布 npm 版本 .

公共软件包将它经过测试的Fiber WASM版本接上. 节点升级需要明确的相容性和恢复性核查;在依赖性解析期间不得默默地进行.

## 安保模式

-   Lit PKP 私人密钥不由 KeyWay 动作返回到浏览器或 KeyWay 后端 。 Lit Chipotle是一个单一认证的TEE:在KeyWay Lit组中的任何允许的动作可以读取其中的密钥,而KeyWay的Lit管理证书控制可以读取允许列表.
-   后端接受完整的CKB交易,执行测试网供资和收费限制,计算CCC精确的叹息,并只引用被绑定的Lit Action:后端拒绝发送由所配置的IPFS CID所不同的Action代码,而Lit只运行CID允许在KeyWay集团中上市.
-   存储的纤维身份密钥在休息时被加密. 对于浏览器节点,Lit创建了密钥并重新加密到用户浏览器中生成的一次性密钥上,因此KeyWay的后端中继器只能是密码文本,在正常操作中从未收到密钥;后端仍然信任Lit授权发布. 一个主机节点运行在KeyWay的服务器上,这些服务器持有该节点的操作密钥和频道状态.
-   网页锁定, `BroadcastChannel`,而原子 Postgres 租赁则执行一个活动浏览器节点.
-   纤维状态备份被加密在浏览器中并被存储为密码文本. 明确登出附件为一不可变的一代;只有最出名的才能自动登出,更年长的一代留下来回滚,恢复时拒绝覆盖设备上已经存在的纤维状态.
-   会话无记名符號活在嵌入式应用程序中 `localStorage`,所以应用程序中的 XSS 错误可以读取它们.
-   `useCkbWallet().signer` 是 CCC 签名符。 后端只标出用户自锁,仅标出其在审批对话框中解码并显示的确切交易,并有大小收费上限和费率限制. 发送限制是默认的:在账户第一次发送之前,“保护你的账户”对话框提供每天10万个CKB的限制,用户可以改变,24小时内任何超过它的东西都需要电子邮件代码;主机-节点Fiber支付算在它前面. 有了政策签名器,KeyWay的Lit Action从一个链上发送限制单元格中强制执行每个发送链上的金额本身,所以服务器单靠它不能超过(C[研究/期货限制](https://npmcn.com/package/%40ckb-keyway/react/research/send-limits/README.md)) (中文(简体) ). 对话框运行在嵌入式app的页面中,因此一个被损坏的页面可以批准低于该金额的交易,而app可以替换对话框(包括默默批准).
-   Opt- in 账户恢复允许用户名备份(一个 EVM 钱包或一个 JoyID 密码) 通过 Omnilock 管理员路径和 [救援页面](https://ckbkeyway.dev/rescue) (单位:千美元)`app/rescue`, (中文(简体) ), `src/rescue`) (中文(简体) ). 在一次更改账户地址时将其转至一个Omnilock地址,命名用户的管理员;备份更改再也不会更改. 打开它 每一个备份更改 总是需要电子邮件代码 并且,为了添加一个, 备份自己的签名。 Omnilock 被数据散列所粘住,没有公共审计;备份列表单独锁定在Lit键上;备份通过签署一个可读文本来批准一个动作,该文本命名目的地和金额,这是KeyWay的验证者(`contracts/`连锁重建。 见 [账户地址回收](https://docs.ckbkeyway.dev/account-recovery)。 。 。 .
-   电子邮件妥协可以授权追回。 这个测试网原型是实验性的,未经审计,而不是生产保管软件.

## 验证测试网结果

2026年7月13日,一个一次性的KeyWay钱包在登录后被回收,恢复了持续状态 `ChannelReady` 并结清了一张独立的CKB纤维发票.

-   供资交易: [`0x6cbe309c362fca8df9d9d57359ccedb5f31691e265abbfc32d3a4c5e5527c319`](https://testnet.explorer.nervos.org/transaction/0x6cbe309c362fca8df9d9d57359ccedb5f31691e265abbfc32d3a4c5e5527c319)
-   频道编号 : `0xfb2ed16a558fd89565c6b3d14596eff90228e11c91a579c25a58c5ae8d4a0ed9`
-   供资产出:指数 `0x0`1,250 CKB 合作频道能力
-   纤维支付散列 : `0x705dae6371d3b2b10e417bf18b9cac0235e654eb59ffd8a1432e0cf3250d472b`
-   发件人结果: 已解决
-   独立接收结果:已确认付款

见 [`docs/TESTNET_EVIDENCE.md`](https://npmcn.com/package/%40ckb-keyway/react/docs/TESTNET_EVIDENCE.md) 关于可复制的证据和 [`docs/ARCHITECTURE.md`](https://npmcn.com/package/%40ckb-keyway/react/docs/ARCHITECTURE.md) 用于组件边界.

## 核查

```sh
npm run typecheck
npm test
npm run build
```

生产部署也发出 `Cross-Origin-Opener-Policy: same-origin` 财务报告和审定财务报表 `Cross-Origin-Embedder-Policy: require-corp`费伯的多行WASM运行时间要求的.

## 目前的限制

-   只测试网( 纤维货币) `Fibt`CKB和指使符(xUDT,包括RUSD)被支持;互换,商检出站,主网已超出范围.
-   交叉设备 Fiber状态迁移目前需要明确的登录。 崩溃,丢失的设备,强制关闭标签,或被中断的浏览器无法创建出新的检查点,因此背景快照仍然需要一个上游安全的数据库冲出边界.
-   频道余额和频道关闭可通过 `useFiber()`. 参考钱包使每个频道的两侧都形成一个,在明确确认后可以关闭一个频道;合作关闭后在CKB上结算最新的余额.
-   后端被信任来授权Lit操作,包括Lit向被签名的用户放出浏览器节点的Fiber密钥. 它从不看到这把钥匙:Lit创建并封入一次性浏览器钥匙,后端只接发密码文本. 它持有主机节点的密钥.
-   浏览器-节点纤维支付不会通过KeyWay的后端,所以它们不会算入每日的电子邮件确认金额,方法规则只在SDK中执行.
-   参考钱包对可预见演示使用固定活化和最高付费限制;SDK消费者可以配置通道资金并估算付费.
-   CKB平衡是活细胞的索引出自总和,不是账户字段. 参考钱包每10秒就进行一次投票,所以在索引器延迟后,新出矿或由水龙头所创建的单元格仍然可以出现.
-   Lit, Fiber WASM, 公共同辈,Resend, CKB测试网 RPC 仍然是外部可用性依赖.
-   托管的节点仍然是实验测试网基础设施. 每个账户都被映射到一个持续体积的专用本土节点上,并有主机节点容量限制. 经认证的运算符可以快取并恢复状态;目前的备份共享主机的音量,而不是出量的灾难恢复. 单独的中试证书被推迟到主网准备. 见 [`docs/ARCHITECTURE.md`](https://npmcn.com/package/%40ckb-keyway/react/docs/ARCHITECTURE.md) 和资金回收证据.

## 上游基金会

-   `@nervosnetwork/fiber-js` `0.9.1`
-   `@fiber-pay/sdk` `0.2.7`
-   `@ckb-ccc/core` `1.16.1`
-   更好的认证 `1.7.7` 重新发送 `6.32.1` (仅私人后端)
-   Lit Chipotle Actions 由 IPFS CID 控股 (通过后端检查并被允许列入 KeyWay Lit 组)

CKB KeyWay是独立的实验性基础设施,不隶属于这些项目或得到这些项目的认可.

## 许可证

CKB KeyWay 发布于 [MIT 许可证](https://npmcn.com/package/%40ckb-keyway/react/LICENSE)。 。 。 .

## 常见问题

### @ckb-keyway/react 是什么？

电子邮件认证的 CKB 钱包和纤维支付基础设施

### 如何安装 @ckb-keyway/react？

在项目目录运行 npm install @ckb-keyway/react，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：react（\>=18\.2\.0）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @ckb-keyway/react 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @ckb-keyway/react 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @ckb-keyway/react 可以商用吗？

@ckb-keyway/react 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @ckb-keyway/react 的下载量有多少？

根据 npm 官方下载统计，@ckb-keyway/react 在 2026/10/10 – 2026/11/08 这 30 天内被下载 1,924 次，日均约 64 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @ckb-keyway/react 还在维护吗？

最新版本 0\.2\.12 发布于 2026/11/09（今天）；至今共发布 21 个版本，其中过去 12 个月发布了 21 个；首次发布于 2026/07/15。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。