Spark Program | fiber-checkout — A "Stripe-Style" React Payment Library for Fiber Network

English
,
15

@xingtianchunyan
Completion report:

fiber-checkout — Spark Program Completion Report

Project: fiber-checkout — React component library for Fiber Network payments Grant: $1,000 USD (paid in CKB) Developer: SalmanDev Repo: GitHub - salmansarwarr/Fiber-checkout · GitHub npm: npmjs.com/package/fiber-checkout Demo: https://fiber-checkout.vercel.app/ Companion guide: [Nervos Talk link] Demo video: https://www.youtube.com/watch?v=Jexw2F-P7fM NPM Published: https://www.npmjs.com/package/fiber-checkout

Summary

fiber-checkout is complete and published. Web developers can now add a full Fiber Network payment flow to any React or Next.js app with a single component — no raw RPC knowledge, no hex encoding, no Rust required. The library handles invoice generation, QR code rendering, payment status polling, expiry detection, and error handling out of the box.

Deliverables

1. npm package — fiber-checkout v0.1.0

Published at npmjs.com/package/fiber-checkout React 18+ peer dependency Dual CJS + ESM build output Full TypeScript strict mode, 100% typed exports Under 50kb gzipped MIT licensed @nervosnetwork/fiber-js ^0.7.0 as peer dependency

Exported API:

  • — full payment UI component accepting amount, asset (“CKB” | “RUSD” | “SEAL”), nodeUrl, onSuccess, onExpired, onError, dangerouslyAllowDirectRpc

  • useFiberInvoice(options) — returns { invoiceAddress, invoice, paymentHash, expiresAt, isLoading, error, regenerate }

  • useFiberPayment(options) — returns { status, feePaid, isLoading, error, poll } where status is idle | pending | processing | success | failed | expired

  • FiberError — typed error class with code, message, rpcCode fields

  • FiberWasmBackend — adapter for using @nervosnetwork/fiber-js WASM instance directly

  • FiberBackend — interface for custom backend implementations

  • Hex utilities: ckbToShannonHex, shannonHexToCkb, formatAmount and others

2. GitHub repository

Full TypeScript source with JSDoc on every export 80%+ unit test coverage enforced via vitest Integration test script verified against live Fiber testnet Next.js proxy reference for both App Router and Pages Router MIT license

3. Testnet verification

npm run test:testnet — 12/12 tests passed against live Fiber testnet nodes:

  • Local node connectivity — Fiber v0.7.1 ✓

  • CKB invoice generation — payment hash 0x85864acf13f531eb88c76dc030ee457e33f84a5e4e00a0252a4b05aef9085317 ✓

  • RUSD invoice generation — payment hash 0xc807df441a97451974eb22312cd849ff7796eefa18d8328459378d84a52dc8c0 ✓

  • Invoice status polling — Open → Paid confirmed ✓

  • End-to-end payment — local node → bootnode → node2, payment hash 0x5da735c80877e8bc5948808e927f0f37be4886156a0ea3efd45efe3089752ed7, confirmed Paid ✓

Testnet explorer link: 0x5da735c80877e8bc5948808e927f0f37be4886156a0ea3efd45efe3089752ed7

4. Assets supported

CKB — native, fully supported and testnet verified RUSD — UDT type script 0x1142755a… verified from live node, testnet verified

5. Next.js proxy reference

Two reference implementations included:

  • App Router: examples/nextjs-proxy/app/api/fiber-rpc/route.ts

  • Pages Router: examples/nextjs-proxy/pages/api/fiber-rpc.ts

Both whitelist only new_invoice and get_invoice, keeping the node URL server-side and the browser protected from direct node exposure.

6. Live demo page

Hosted on Vercel, auto-deployed from GitHub main. Full flow: asset select → QR renders → wallet scans → status updates → success/expiry. URL: https://fiber-checkout.vercel.app/ Example testnet transaction: 0x5da735c80877e8bc5948808e927f0f37be4886156a0ea3efd45efe3089752ed7

7. Companion guide

End-to-end Next.js integration walkthrough posted on Nervos Talk covering:

  • Server-side proxy setup

  • Component integration

  • Hook-level usage

  • Local development with direct RPC

  • Error handling

8. Demo video

Under 10 minutes: npm install → component renders → testnet payment confirmed. Link: https://www.youtube.com/watch?v=Jexw2F-P7fM

Week Scope Amount
Week 1 useFiberInvoice hook + testnet verification (CKB + RUSD) $200
Week 2 useFiberPayment hook + <FiberCheckout /> + Next.js proxy $500
Week 3 Cross-browser QA + mobile testing + live demo page $200
Week 4 npm publish + companion guide + demo video + completion report $100
Total $1,000

Fiber version compatibility

Built and tested against:

  • Fiber node v0.7.1 (local) and v0.8.0 (public testnet) — both confirmed working

  • @nervosnetwork/fiber-js ^0.7.0 — included as peer dependency, re-exported for convenience

The library supports two backend modes:

  • RPC mode (default) — direct JSON-RPC 2.0 fetch calls to a Fiber node via proxy. Lightweight, no WASM, works in all browsers

  • WASM mode — wraps a Fiber instance from @nervosnetwork/fiber-js via FiberWasmBackend. For developers who want to run a node client-side

Both modes use the same hooks and component API — switching requires only passing a backend prop.

If the Fiber RPC API changes in a future version, a patch will be released and documented in the CHANGELOG within the maintenance window.

Additional information

Dual backend architecture — The original proposal specified building exclusively on @nervosnetwork/fiber-js. The delivered library supports fiber-js via FiberWasmBackend as specified, but also provides a lightweight fetch-based RPC path as the default. This was added because WASM is not always appropriate for browser-based checkout components — it adds bundle weight and requires a running node instance rather than a remote endpoint. The fiber-js dependency is included as a peer dependency and re-exported. Developers who want WASM can use FiberWasmBackend directly.

Post-grant maintenance

Each release documents Fiber node version compatibility in the CHANGELOG Repository is MIT licensed and publicly forkable If adoption warrants it, a Community Fund DAO follow-up proposal will be submitted for v2 development.

fiber-checkout — Spark 计划完成报告

项目：fiber-checkout — Fiber Network 支付 React 组件库 资助：$1,000 美元（以 CKB 支付） 开发者：SalmanDev 代码仓库：GitHub - salmansarwarr/Fiber-checkout · GitHub npm：npmjs.com/package/fiber-checkout 演示：https://fiber-checkout.vercel.app/ 配套指南：[Nervos Talk 链接] 演示视频：https://www.youtube.com/watch?v=Jexw2F-P7fM NPM 已发布：https://www.npmjs.com/package/fiber-checkout

概述

fiber-checkout 已完成并发布。Web 开发者现在可以通过单个组件将完整的 Fiber Network 支付流程添加到任何 React 或 Next.js 应用中——无需了解底层 RPC、无需十六进制编码、无需 Rust。该库开箱即用，支持发票生成、二维码渲染、支付状态轮询、到期检测和错误处理。

交付成果

1. npm 包 — fiber-checkout v0.1.0

发布于 npmjs.com/package/fiber-checkout React 18+ 对等依赖 双 CJS + ESM 构建输出 完整 TypeScript 严格模式，100% 类型化导出 gzip 压缩后不超过 50kb MIT 许可证 @nervosnetwork/fiber-js ^0.7.0 作为对等依赖

导出 API：

  • <FiberCheckout /> — 完整支付 UI 组件，接受 amount、asset（“CKB” | “RUSD” | “SEAL”）、nodeUrl、onSuccess、onExpired、onError、dangerouslyAllowDirectRpc

  • useFiberInvoice(options) — 返回 { invoiceAddress, invoice, paymentHash, expiresAt, isLoading, error, regenerate }

  • useFiberPayment(options) — 返回 { status, feePaid, isLoading, error, poll }，其中 status 为 idle | pending | processing | success | failed | expired

  • FiberError — 带有 code、message、rpcCode 字段的类型化错误类

  • FiberWasmBackend — 直接使用 @nervosnetwork/fiber-js WASM 实例的适配器

  • FiberBackend — 自定义后端实现的接口

  • 十六进制工具函数：ckbToShannonHex、shannonHexToCkb、formatAmount 等

2. GitHub 代码仓库

所有导出均附有 JSDoc 的完整 TypeScript 源码 通过 vitest 强制执行 80%+ 单元测试覆盖率 针对 Fiber 测试网节点验证的集成测试脚本 支持 App Router 和 Pages Router 的 Next.js 代理参考实现 MIT 许可证

3. 测试网验证

npm run test:testnet — 针对 Fiber 测试网节点 12/12 测试全部通过：

  • 本地节点连接 — Fiber v0.7.1 ✓

  • CKB 发票生成 — 支付哈希 0x85864acf13f531eb88c76dc030ee457e33f84a5e4e00a0252a4b05aef9085317 ✓

  • RUSD 发票生成 — 支付哈希 0xc807df441a97451974eb22312cd849ff7796eefa18d8328459378d84a52dc8c0 ✓

  • 发票状态轮询 — Open → Paid 已确认 ✓

  • 端到端支付 — 本地节点 → 引导节点 → node2，支付哈希 0x5da735c80877e8bc5948808e927f0f37be4886156a0ea3efd45efe3089752ed7，已确认 Paid ✓

测试网浏览器链接：0x5da735c80877e8bc5948808e927f0f37be4886156a0ea3efd45efe3089752ed7

4. 支持的资产

CKB — 原生资产，完全支持并经测试网验证 RUSD — UDT 类型脚本 0x1142755a… 已通过实时节点验证，经测试网验证

5. Next.js 代理参考实现

包含两个参考实现：

  • App Router：examples/nextjs-proxy/app/api/fiber-rpc/route.ts

  • Pages Router：examples/nextjs-proxy/pages/api/fiber-rpc.ts

两者均仅白名单 new_invoice 和 get_invoice，将节点 URL 保留在服务端，保护浏览器免受直接节点暴露。

6. 在线演示页面

托管于 Vercel，从 GitHub main 分支自动部署。完整流程：选择资产 → 渲染二维码 → 钱包扫描 → 状态更新 → 成功/到期。 URL：https://fiber-checkout.vercel.app/ 测试网交易示例：0x5da735c80877e8bc5948808e927f0f37be4886156a0ea3efd45efe3089752ed7

7. 配套指南

发布于 Nervos Talk 的端到端 Next.js 集成教程，内容涵盖：

  • 服务端代理配置

  • 组件集成

  • Hook 级别使用

  • 使用直接 RPC 进行本地开发

  • 错误处理

链接：[Nervos Talk 链接]

8. 演示视频

时长不超过 10 分钟：npm install → 组件渲染 → 测试网支付确认。 链接：https://www.youtube.com/watch?v=Jexw2F-P7fM

资金使用明细

周次 范围 金额
第 1 周 useFiberInvoice hook + 测试网验证（CKB + RUSD） $200
第 2 周 useFiberPayment hook + + Next.js 代理 $500
第 3 周 跨浏览器 QA + 移动端测试 + 在线演示页面 $200
第 4 周 npm 发布 + 配套指南 + 演示视频 + 完成报告 $100
合计 $1,000

Fiber 版本兼容性

构建并测试环境：

  • Fiber 节点 v0.7.1（本地）和 v0.8.0（公共测试网）— 均已确认可用

  • @nervosnetwork/fiber-js ^0.7.0 — 作为对等依赖包含并重新导出

该库支持两种后端模式：

  • RPC 模式（默认） — 通过代理直接向 Fiber 节点发起 JSON-RPC 2.0 fetch 调用。轻量级，无需 WASM，适用于所有浏览器

  • WASM 模式 — 通过 FiberWasmBackend 封装来自 @nervosnetwork/fiber-js 的 Fiber 实例。适用于希望在客户端运行节点的开发者

两种模式使用相同的 hooks 和组件 API——切换只需传入 backend prop 即可。

如果 Fiber RPC API 在未来版本中发生变化，将在维护窗口内发布补丁并在 CHANGELOG 中记录。

补充说明

双后端架构 — 原始提案指定完全基于 @nervosnetwork/fiber-js 构建。交付的库按规范通过 FiberWasmBackend 支持 fiber-js，同时也提供了轻量级的基于 fetch 的 RPC 路径作为默认选项。这样设计是因为 WASM 并不总是适合基于浏览器的结账组件——它会增加打包体积，且需要运行节点实例而非远程端点。fiber-js 依赖作为对等依赖包含并重新导出。需要 WASM 的开发者可以直接使用 FiberWasmBackend。

资助后维护

每个版本均在 CHANGELOG 中记录 Fiber 节点版本兼容性 代码仓库采用 MIT 许可证，可公开 fork 如果社区采用情况良好，将提交 Community Fund DAO 后续提案用于 v2 开发。

2 Likes