[DIS] Fiber Python SDK — Native Python Library for Fiber Network Payments

CKB Community Fund DAO
1

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:

    1. Invoice creation and payment-status polling

    2. Channel open → invoice → pay → list_payments (full lifecycle)

    3. Agent pay-per-call (server returns Fiber invoice on 402, client pays and retries automatically)

    4. 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

  1. 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.

  2. 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

[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，修补破坏性变更，并在问题出现时予以解决。

支持链接

6 Likes
CKB Ecosystem Biweekly Update
2

One design decision worth clarifying: The SDK will wrap settle_invoice, which enables hold-invoice patterns — pay now, release on condition. This is what makes escrow flows like PactAgent’s milestone releases possible without a third party custodying funds.

1 Like