Summary
This proposal requests a grant of $5,000 USD equivalent in CKB to build and publish a native Python SDK for the Fiber Network.
The SDK will give Python developers and AI agents a typed, installable library for interacting with a Fiber Network Node — covering the full payment lifecycle: channels, peers, invoices, payments, routing, network graph, and Bitcoin cross-chain interop.
Grant Amount Requested: ($5,000 equivalent in CKB)
ETA to Completion: 8 weeks from grant approval
CKB Wallet or Funding Address: ckb1qyqvaj4pmuw9vxurdlg8lx3sv7ywmcge33vsvrvu39
Project Introduction
The gap
Developer tooling and SDK work on Fiber is TypeScript-first — the official RPC wrapper and most application-layer projects are TypeScript or JavaScript:
-
@nervosnetwork/fiber-js — the official RPC wrapper, JS only (confirmed on npm)
-
fiber-checkout — React payment component, TypeScript (Spark-funded, my prior work)
-
AgentPay, Fiber402 — Node.js (confirmed)
The only Python presence in the ecosystem, verified against the Fiber showcase (docs.fiber.world/showcase):
-
A step-by-step testnet tutorial (not a library)
-
An integration test suite (a test harness, not an installable package)
-
CKB Alpha Agent — a Python agent application that accepts Fiber payments (not a reusable library)
There is no pip install fiber-sdk. There is no typed Python client. Python developers and AI agent frameworks have nothing to install.
Why Python matters for Fiber right now
Most major AI agent frameworks are Python-first — LangChain, CrewAI, the MCP Python SDK, and AutoGPT are all Python. A Python developer today has to write raw JSON-RPC from scratch to interact with a Fiber node. There is no library to install, no typed client, no examples.
Prior Work and Credentials
I built fiber-checkout — a Stripe-style React payment component for Fiber — under the Nervos Spark Program. The committee’s evaluation is public.
The Python SDK is the natural second step: the JS/React layer for web frontends exists (fiber-checkout), the Python layer for agents and backend developers does not.
What This Grant Builds
A Python package (fiber-sdk, published to PyPI) wrapping the Fiber Network Node JSON-RPC interface with:
-
Typed request and response models (Pydantic)
-
Async support (asyncio / httpx)
-
Synchronous convenience wrapper for simple scripts
-
Typed exceptions for RPC errors, node-down, and timeout
-
Examples: invoice flow, payment polling, agent pay-per-call, BTC cross-chain
| Category | Methods |
|---|---|
| Channels | open_channel, accept_channel, list_channels, update_channel, shutdown_channel, abandon_channel |
| TLC | add_tlc, remove_tlc |
| Peers | connect_peer, disconnect_peer, list_peers |
| Invoices | new_invoice, parse_invoice, get_invoice, cancel_invoice, settle_invoice |
| Payments | send_payment, send_payment_with_router, build_router, get_payment, list_payments |
| Network | graph_nodes, graph_channels |
| Node | node_info |
| BTC / CCH | send_btc, receive_btc, get_cch_order |
| Watchtower | remove_watch_channel |
Deliverables
Milestone 1 — Core SDK (Weeks 1–4)
-
Python package published to PyPI as fiber-sdk
-
Async JSON-RPC client (httpx-based)
-
Typed Pydantic models for all 28 SDK methods
-
Typed exceptions for RPC errors, node-down, timeout
-
README with install and quickstart
Verification: pip install fiber-sdk, connect to public testnet node, create an invoice, poll payment status — full flow works and types pass mypy.
Milestone 2 — Examples and Documentation (Weeks 5–8)
-
Four documented examples:
-
Invoice creation and payment-status polling
-
Channel open → invoice → pay → list_payments (full lifecycle)
-
Agent pay-per-call (server returns Fiber invoice on 402, client pays and retries automatically)
-
BTC cross-chain: receive_btc → get_cch_order → confirm settlement
-
-
Full API reference (Generated from Pydantic models + docstrings)
-
CHANGELOG and versioning policy
-
Forum announcement post with usage examples
Verification: All four examples run against the public testnet node. PyPI package installable with no extra steps.
| Week | Work |
|---|---|
| 1 | Package scaffold, async RPC client, error types, CI setup |
| 2 | Typed models and methods — channels, peers, node_info |
| 3 | Typed models and methods — invoices, payments, routing |
| 4 | BTC/CCH methods, PyPI publish, M1 verification |
| 5 | Example 1 + 2 (invoice lifecycle, full channel flow) |
| 6 | Example 3 (agent pay-per-call) |
| 7 | Example 4 (BTC cross-chain) |
| 8 | API docs, CHANGELOG, forum post, M2 verification |
Why This Is the Right Time
-
fnn v0.8.1 is a stable tagged release (April 15, 2026). Building against a tagged release means the SDK ships against a settled API surface, not a moving target.
-
AI-agent demand on Fiber is real. Agent frameworks are Python-first. The ecosystem is ready for a Python SDK — it just doesn’t have one yet.
| Risk | Mitigation |
|---|---|
| fnn v0.9 ships breaking RPC changes | v0.9 is at rc7 as of July 2. I am monitoring it and will flag any breaking changes to the 28 SDK methods before M2 closes. CHANGELOG will document any delta. |
| PyPI name fiber-sdk taken at submission | Check at submission — fallback name ckb-fiber-sdk is also available (confirmed). |
Post-Delivery
The package will be actively maintained — CHANGELOG updated per fnn release, breaking changes patched, issues addressed as they arise.
Supporting Links
-
Fiber-checkout (Spark grant) prior work: Spark Program | fiber-checkout — A "Stripe-Style" React Payment Library for Fiber Network
-
Official fnn repo: GitHub - nervosnetwork/fiber: A scalable, privacy-by-default payment & swap network · GitHub
-
fnn v0.8.1 release: Release v0.8.1 · nervosnetwork/fiber · GitHub
-
Fiber showcase: https://docs.fiber.world/showcase
[DIS] Fiber Python SDK — Fiber Network Payments 原生 Python 库
摘要
本提案申请 5,000 美元等值的 CKB 资助，用于构建并发布一个 Fiber Network 原生 Python SDK。
该 SDK 将为 Python 开发者和 AI 智能体提供一个类型化、可安装的库，用于与 Fiber Network 节点进行交互，涵盖完整的支付生命周期：通道、节点、发票、支付、路由、网络图以及比特币跨链互操作。
-
申请资助金额： 5,000 美元等值 CKB
-
预计完成时间： 获批后 8 周
-
CKB 钱包或资金接收地址：
ckb1qyqvaj4pmuw9vxurdlg8lx3sv7ywmcge33vsvrvu39
项目介绍
现状差距
目前 Fiber 的开发者工具和 SDK 开发以 TypeScript 为主——官方 RPC 封装及大多数应用层项目均基于 TypeScript 或 JavaScript：
-
@nervosnetwork/fiber-js— 官方 RPC 封装，仅限 JS (已在 npm 确认) -
fiber-checkout— React 支付组件，TypeScript (Spark 资助，本人先前项目) -
AgentPay,Fiber402— Node.js (已确认)
生态系统中仅有的 Python 存在（根据 Fiber 展示页面 docs.fiber.world/showcase 核实）：
-
一份分步测试网教程（非库）
-
一套集成测试套件（测试工具，非可安装包）
-
CKB Alpha Agent— 一个接受 Fiber 支付的 Python 智能体应用（非可复用库）
目前没有 pip install fiber-sdk，没有类型化的 Python 客户端。Python 开发者和 AI 智能体框架目前无可安装的库。
为何 Python 对现在的 Fiber 至关重要
大多数主流 AI 智能体框架均为 Python 优先——LangChain、CrewAI、MCP Python SDK 和 AutoGPT 均为 Python 编写。当前的 Python 开发者若要与 Fiber 节点交互，必须从零开始编写原始 JSON-RPC。目前没有可供安装的库、没有类型化客户端、没有示例。
先前工作与资历
我曾通过 Nervos Spark 项目构建了 fiber-checkout（一款 Fiber 的 Stripe 风格 React 支付组件）。委员会的评估结果是公开的。
Python SDK 是自然的第二步：Web 前端的 JS/React 层已经存在 (fiber-checkout)，而用于智能体和后端开发者的 Python 层尚缺。
资助内容
一个 Python 包 (fiber-sdk，发布至 PyPI)，封装 Fiber Network 节点 JSON-RPC 接口，具备：
-
类型化请求与响应模型 (Pydantic)
-
异步支持 (asyncio / httpx)
-
适用于简单脚本的同步便利包装器
-
针对 RPC 错误、节点掉线和超时的类型化异常
-
示例：发票流程、支付轮询、智能体按调用付费 (pay-per-call)、BTC 跨链
范围 — fnn v0.8.1 (直接从源码核实)
SDK 封装了 v0.8.1 版本中 41 个官方 RPC 方法中的 28 个，涵盖了所有用户侧功能。其余 13 个为低级通道状态签名内部方法，非普通 SDK 用户调用，未包含在 v0.1 范围内。
SDK 方法 (28) — 直接从 v0.8.1 源码标签核实
| 类别 | 方法 |
|---|---|
| 通道 (Channels) | open_channel, accept_channel, list_channels, update_channel, shutdown_channel, abandon_channel |
| TLC | add_tlc, remove_tlc |
| 节点 (Peers) | connect_peer, disconnect_peer, list_peers |
| 发票 (Invoices) | new_invoice, parse_invoice, get_invoice, cancel_invoice, settle_invoice |
| 支付 (Payments) | send_payment, send_payment_with_router, build_router, get_payment, list_payments |
| 网络 (Network) | graph_nodes, graph_channels |
| 节点 (Node) | node_info |
| BTC / CCH | send_btc, receive_btc, get_cch_order |
| 瞭望塔 (Watchtower) | remove_watch_channel |
交付物
里程碑 1 — 核心 SDK (第 1–4 周)
-
Python 包发布至 PyPI，命名为
fiber-sdk -
异步 JSON-RPC 客户端 (基于 httpx)
-
针对所有 28 个 SDK 方法的类型化 Pydantic 模型
-
针对 RPC 错误、节点掉线、超时的类型化异常
-
包含安装与快速入门的 README
-
验证：
pip install fiber-sdk，连接公共测试网节点，创建发票，轮询支付状态 —— 全流程通过，且类型通过mypy检查。
里程碑 2 — 示例与文档 (第 5–8 周)
-
四个记录在案的示例：
-
发票创建与支付状态轮询
-
通道开启 → 发票 → 支付 → 列出支付（全生命周期）
-
智能体按调用付费（服务器在 402 时返回 Fiber 发票，客户端支付并自动重试）
-
BTC 跨链：接收 BTC → 获取 CCH 订单 → 确认结算
-
-
完整的 API 参考文档（由 Pydantic 模型 + 文档字符串生成）
-
CHANGELOG 与版本控制策略
-
包含使用示例的论坛公告贴
-
验证：所有四个示例均在公共测试网上运行通过。PyPI 包无需额外步骤即可安装。
时间表
| 周 | 工作内容 |
|---|---|
| 1 | 包脚手架、异步 RPC 客户端、错误类型、CI 设置 |
| 2 | 类型化模型与方法 — 通道、节点、node_info |
| 3 | 类型化模型与方法 — 发票、支付、路由 |
| 4 | BTC/CCH 方法、PyPI 发布、M1 验证 |
| 5 | 示例 1 + 2 (发票生命周期、完整通道流程) |
| 6 | 示例 3 (智能体按调用付费) |
| 7 | 示例 4 (BTC 跨链) |
| 8 | API 文档、CHANGELOG、论坛帖、M2 验证 |
预算
总计：(提交时约 5,000 美元)
| 里程碑 | 金额 |
|---|---|
| 里程碑 1：核心 SDK + PyPI 发布 | (约 2,500 美元) |
| 里程碑 2：示例 + 文档 | [CKB 等值] (约 2,500 美元) |
为何此时是最佳时机
-
fnn v0.8.1 是一个稳定的标签版本（2026 年 4 月 15 日）。基于标签版本构建意味着 SDK 是针对已固定的 API 表面进行发布，而非不断变化的目标。
-
Fiber 上的 AI 智能体需求是真实的。智能体框架均为 Python 优先。生态系统已为 Python SDK 做好准备 —— 只是目前尚无此类库。
风险与缓解
| 风险 | 缓解措施 |
|---|---|
| fnn v0.9 发布破坏性 RPC 变更 | 截至 7 月 2 日，v0.9 处于 rc7 阶段。我正在监控，并在 M2 结束前标记 28 个 SDK 方法中的任何破坏性变更。CHANGELOG 将记录所有差异。 |
提交时 PyPI 名称 fiber-sdk 已被占用 |
提交时检查 — 备用名称 ckb-fiber-sdk 也可用 (已确认)。 |
交付后计划
该软件包将得到积极维护 —— 根据 fnn 发布更新 CHANGELOG，修补破坏性变更，并在问题出现时予以解决。
支持链接
-
Fiber-checkout (Spark 资助) 先前工作：https://talk.nervos.org/t/spark-program-fiber-checkout-a-stripe-style-react-payment-library-for-fiber-network/10045/1
-
官方 fnn 仓库：https://github.com/nervosnetwork/fiber
-
fnn v0.8.1 发布：https://github.com/nervosnetwork/fiber/releases/tag/v0.8.1
-
Fiber 展示页面：https://docs.fiber.world/showcase
