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

English
,
26

@xingtianchunyan Thanks for the feedback. Point 1 is update to Github Fiber-checkout/docs/nextjs-guide.md at main · salmansarwarr/Fiber-checkout · GitHub

fiber-checkout — Spark Program Completion Report

A Developer Retrospective

Introduction

Hi CKB community, this is Salman from the fiber-checkout project. This report reflects on the fiber-checkout project from a developer’s perspective — what was planned, what changed, what was hard, and what I learned. My hope is that this is useful not just as a grant accountability document, but as a reference for anyone building developer tooling on Fiber Network in the future.

What Was the Problem I Was Solving

When I started this project, Fiber Network was live on mainnet and @nervosnetwork/fiber-js had just been published. The protocol worked. The JavaScript bridge worked. But there was still no way for a web developer to drop a payment button into their app.

To accept a Fiber payment at that point, a developer had to manually call new_invoice with raw hex-encoded u128 amounts, render the payment request string into a QR code themselves, poll get_payment on a timer, and manage all success, failure, and expiry states with no type safety and no examples. That is a significant amount of work that has nothing to do with the product the developer is actually building.

fiber-checkout was my attempt to make that entire flow disappear behind a single React component.

Comparison of Original Plan with Actual Completion

The project was completed within the 4-week timeline with one architectural deviation, which I’ll explain below.

What was delivered as planned:

  • useFiberInvoice hook — invoice generation, correct hex encoding, UDT type script handling

  • useFiberPayment hook — 2-second polling, all 5 status mappings, feePaid populated via get_payment on success

  • component — full payment UI with QR code, status display, expiry countdown, copy button

  • FiberError typed error class with factory methods and type guard

  • Dual CJS + ESM build, TypeScript strict mode, zero styling dependencies

  • Next.js proxy reference for both App Router and Pages Router

  • 12/12 testnet integration tests passing against live Fiber nodes

  • npm published, live demo on Vercel, demo video recorded

What changed:

  • SEAL assets are included in the registry marked supported: false. Public Fiber testnet nodes do not currently whitelist SEAL in their udt_whitelist. The type script entry is in place and will be activated once SEAL is deployed on public testnet.

  • The asset registry was refactored to support a customAssets prop, allowing developers to add any RGB++ UDT without waiting for a library release.

Key Decisions and the Reasoning Behind Them

1. Direct JSON-RPC fetch and fiber-js

I also use direct fetch calls as the default transport, with fiber-js supported as an aded WASM backend via FiberWasmBackend.

The reason for the decision is fiber-checkout is a checkout component — its job is to talk to a remote Fiber node via a proxy, not to run a node in the browser. @nervosnetwork/fiber-js is a WASM wrapper that initializes a node client in memory. For the proxy use case, that is significant bundle overhead for zero benefit. The raw JSON-RPC 2.0 interface the library exposes is stable and well-defined.

Rather than abandon the fiber-js commitment entirely, I introduced a FiberBackend interface that both transports implement. Developers who want to use fiber-js WASM directly can pass a FiberWasmBackend instance. Developers who just want to connect to a remote node — the vast majority — get a lightweight fetch-based client by default. @nervosnetwork/fiber-js is included as a peer dependency and re-exported for convenience.

2. Server-side proxy as the production deployment pattern

Early in development it became clear that direct browser → Fiber node connections are not viable in production for three reasons: Fiber nodes don’t serve CORS headers, public apps run on HTTPS while nodes run on HTTP (mixed content), and exposing a node’s RPC port publicly is a security risk.

The proxy pattern — a Next.js API route that forwards only new_invoice and get_invoice to the node — solves all three problems cleanly. The dangerouslyAllowDirectRpc prop was added for local development where none of these constraints apply.

One design gap was identified by a committee member after submission: the original IP detection logic was too aggressive and would flag legitimate cross-domain HTTPS proxy setups (e.g. https://api.yourdomain.com/fiber-rpc) as unsafe. This was corrected — the updated logic only requires dangerouslyAllowDirectRpc for raw IP addresses, not for HTTPS URLs on named domains.

3. Polling get_invoice instead of get_payment for status

The spec said to poll get_payment. In practice, get_invoice is the correct method for checking whether a specific invoice has been paid — it returns the invoice status (Open, Received, Paid, Cancelled, Expired) directly from the invoice record. get_payment is used after a payment is confirmed to retrieve fee information, which is why feePaid is populated by a single get_payment call on success rather than on every poll cycle. This is more efficient and matches how the Fiber RPC is designed to be used.

Challenges

The HTTPS/HTTP mixed content problem was the most significant deployment challenge. The demo was hosted on Vercel (HTTPS) while Fiber nodes run on HTTP. The solution — the Next.js API proxy — was already part of the design, but wiring it up correctly on the deployed demo took longer than expected because the Vercel environment variables needed to be configured separately from the local .env.local file.

Project Outcomes and Value

fiber-checkout delivers three things to the CKB ecosystem:

1. A working payment component — npm install fiber-checkout and four props gives any React or Next.js developer a complete Fiber payment flow. This lowers the integration barrier from “deep CKB stack knowledge required” to “copy this snippet.”

2. Established patterns — The proxy architecture, the two-backend abstraction, the typed error class, the customAssets extensibility model — these are patterns that any future Fiber developer tooling can build on or extend.

3. Documentation of real constraints — The off-chain payment model, the CORS/mixed content problem — these are real things that any developer building on Fiber will encounter. Having them documented in one place saves the next developer from discovering them independently.

Week Scope Amount
Week 1 useFiberInvoice hook + testnet verification (CKB + RUSD) $200
Week 2 useFiberPayment hook + <FiberCheckout /> + Next.js proxy reference $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

First installment (20%, 132,890 CKB) received at project start. Remaining 80% to be received at completion.

Post-Grant Maintenance

The library intentionally wraps only two RPC methods — new_invoice and get_invoice. This narrow scope keeps the ongoing maintenance surface small. Each npm release will pin the Fiber node version range it was tested against in the CHANGELOG.

Free breaking change patches for the current scope are committed for 6 months post-delivery. The repository is MIT licensed and publicly forkable from day one.I will consider, a Community Fund DAO follow-up proposal will be for v2 development — expanded asset support, a mobile-optimized layout, and deeper wallet integration as the Fiber wallet ecosystem matures.

Acknowledgements

Thanks to the Spark Program committee — xingtian, Hanssen, and the broader review team — for thorough and technically substantive feedback throughout the process. The questions raised about the proxy design, the fiber-js integration, the asset extensibility model, and the deployment architecture all made the library meaningfully better than the first submission.

Salman — fiber-checkout npm: https://www.npmjs.com/package/fiber-checkout GitHub: GitHub - salmansarwarr/Fiber-checkout · GitHub Demo: https://fiber-checkout.vercel.app Demo video: https://www.youtube.com/watch?v=bWKslRFl-98

谢谢你的反馈。第 1 点已更新到 GitHub：
https://github.com/salmansarwarr/Fiber-checkout/blob/main/docs/nextjs-guide.md

fiber-checkout — Spark 项目完成报告

开发者回顾

引言

大家好，CKB 社区的朋友们，我是 fiber-checkout 项目的 Salman。本报告从开发者的视角回顾了 fiber-checkout 项目——最初的计划、过程中发生的变化、遇到的挑战，以及我从中获得的经验。希望这不仅是一份资助项目的交付报告，也能为未来在 Fiber Network 上构建开发者工具的人提供参考。

我要解决的问题

当我开始这个项目时，Fiber Network 已经在主网上线，@nervosnetwork/fiber-js 刚刚发布。协议本身是可用的，JavaScript 桥接也已经存在，但仍然缺少一个关键能力：Web 开发者无法直接在应用中嵌入一个支付按钮。

在当时，如果开发者想接入 Fiber 支付，需要：

  • 手动调用 new_invoice（使用原始 hex 编码的 u128 数值）

  • 自行将支付请求字符串渲染为二维码

  • 使用定时器轮询 get_payment

  • 手动处理成功、失败、过期等所有状态

  • 没有类型安全，也没有示例代码

这些工作量巨大，而且与开发者实际要构建的产品无关。

fiber-checkout 的目标，就是将整个流程封装在一个 React 组件中，让这些复杂性对开发者“消失”。

原始计划 vs 实际完成情况

项目在 4 周内完成，只有一个架构上的调整（后文说明）。

按计划交付的内容：

  • useFiberInvoice hook

    • 发票生成

    • 正确的 hex 编码

    • UDT 类型脚本处理

  • useFiberPayment hook

    • 2 秒轮询

    • 覆盖全部 5 种状态

    • 成功后通过 get_payment 填充 feePaid

  • <FiberCheckout /> 组件

    • 完整支付 UI

    • 二维码

    • 状态显示

    • 过期倒计时

    • 复制按钮

  • FiberError 类型化错误类

    • 工厂方法

    • 类型守卫

  • 双构建（CJS + ESM）

  • TypeScript 严格模式

  • 无样式依赖

  • Next.js 代理参考实现（App Router + Pages Router）

  • 12/12 测试网集成测试通过（真实 Fiber 节点）

  • npm 发布

  • Vercel 在线演示

  • 演示视频

发生的变化：

  • SEAL 资产已加入 registry，但标记为 supported: false

    • 当前公共 Fiber 测试网未在 udt_whitelist 中启用 SEAL

    • 类型脚本已预置，待测试网上线后可直接启用

  • 资产注册系统重构

    • 新增 customAssets 属性

    • 开发者可自行添加 RGB++ UDT，无需等待库更新

关键技术决策及原因

1. 直接 JSON-RPC + fiber-js

默认使用 fetch + JSON-RPC 作为传输方式，同时支持 fiber-js 作为 WASM 后端（FiberWasmBackend）。

原因：

fiber-checkout 是一个 checkout 组件，目标是连接远程 Fiber 节点，而不是在浏览器中运行节点。

fiber-js 本质是一个 WASM 节点客户端，会引入较大的 bundle 体积，但在代理模式下没有实际收益。

因此：

  • 默认：轻量 fetch 客户端

  • 可选：FiberWasmBackend（给需要 WASM 的开发者）

同时：

  • 定义了 FiberBackend 接口

  • 两种实现可互换

  • fiber-js 作为 peer dependency 提供

2. 生产环境使用服务端代理

开发过程中很快发现：浏览器直连 Fiber 节点不可行，原因：

  • 无 CORS 头

  • HTTPS 页面调用 HTTP 节点（mixed content）

  • 暴露 RPC 端口存在安全风险

解决方案：

Next.js API 代理

  • 仅转发 new_invoice 和 get_invoice

  • 避免所有上述问题

同时：

  • 添加 dangerouslyAllowDirectRpc（仅用于本地开发）

设计修正：

评审指出：

原 IP 检测逻辑过于激进，会误判合法 HTTPS 代理（如 https://api.xxx.com）

修正后：

  • 仅对“裸 IP 地址”要求 dangerouslyAllowDirectRpc

  • 正常 HTTPS 域名完全允许

3. 使用 get_invoice 而不是 get_payment 轮询

规范建议使用 get_payment，但实践中更合理的是：

  • get_invoice → 查询发票状态（Open / Paid / Expired 等）

  • get_payment → 在成功后获取费用信息

因此：

  • 轮询：get_invoice

  • 成功后：单次调用 get_payment 填充 feePaid

优点：

  • 更高效

  • 更符合 Fiber RPC 设计

挑战

最大问题是：

HTTPS / HTTP mixed content

  • 演示部署在 Vercel（HTTPS）

  • Fiber 节点是 HTTP

解决方案：

  • 使用 Next.js API 代理（已在设计中）

实际困难：

  • Vercel 环境变量需单独配置

  • 与本地 .env.local 不同步

导致部署调试时间超出预期

项目成果与价值

fiber-checkout 为 CKB 生态带来三点核心价值：

1. 可直接使用的支付组件

  • npm install 即可使用

  • 4 个 props 完整支付流程

将接入门槛从：

:backhand_index_pointing_right: “需要深入理解 CKB”
降低到：
:backhand_index_pointing_right: “复制代码即可”

2. 标准化开发模式

包括：

  • 代理架构

  • 双后端抽象

  • 类型化错误系统

  • customAssets 扩展模型

这些都可以作为后续工具的基础

3. 真实问题文档化

例如：

  • Off-chain 支付模型

  • CORS / mixed content

这些是所有开发者都会遇到的问题

现在已有集中说明，避免重复踩坑

资金使用透明说明

周 工作内容 金额
第 1 周 useFiberInvoice + 测试网验证 $200
第 2 周 useFiberPayment + UI + Next.js 代理 $500
第 3 周 跨浏览器 + 移动测试 + Demo 页面 $200
第 4 周 npm 发布 + 文档 + 视频 + 报告 $100

总计：$1,000

  • 首笔 20%（132,890 CKB）已发放

  • 剩余 80% 在完成后发放

资助后维护计划

库仅封装两个 RPC：

  • new_invoice

  • get_invoice

优势：

  • 维护范围小

  • 稳定性高

策略：

  • 每次发布在 CHANGELOG 标注兼容的 Fiber 版本

  • 提供 6 个月免费 breaking change 修复

开源情况：

  • MIT 许可证

  • 可自由 fork

未来计划：

  • 提交 v2 提案（Community Fund DAO）

    • 更多资产支持

    • 移动端优化

    • 更深度的钱包集成

致谢

感谢 Spark Program 评审委员会：

  • xingtian

  • Hanssen

  • 以及所有评审成员

你们在以下方面的反馈极具价值：

  • 代理设计

  • fiber-js 集成

  • 资产扩展模型

  • 部署架构

这些反馈让项目比初版显著提升。

项目信息

Salman — fiber-checkout

npm: https://www.npmjs.com/package/fiber-checkout
GitHub: https://github.com/salmansarwarr/Fiber-checkout
Demo: https://fiber-checkout.vercel.app
Demo 视频: https://www.youtube.com/watch?v=bWKslRFl-98

7 Likes
CKB Ecosystem Biweekly Update