教程三:为能力收费

这一页把教程二里那条免费能力变成收费能力,并把钱的整条路径走完:标价、报价、 签授权、结算、双方上链、看余额、对账、审计 hub 的发放链、兑付。

付费在 ANet 里是一个可插拔模块(ANet/module/x402)。它不是内核的一部分, 也不是"一个可以在运行时关掉的开关"—— -tags no_x402 编出来的二进制里, module/x402 的符号数是 0。

前提

一、这个构建里有没有 x402

anet version

第二行是从二进制里实际链接进来的模块注册表读出来的:

anet 0.1.7 (commit 642f970, built 2026-09-03T…)
modules: anetlink,blackboard,cas,mcp,org,p2p,service,taskboard,x402

有 x402 就能收费。GitHub release 的默认二进制、以及一行安装装到的二进制, 都是完整减法模块集,所以本来就带 x402;paid 档是自己按 -tags no_mcp,no_taskboard,no_cas,no_org,no_blackboard,no_p2p,no_anetlink 裁出来的一个名字(scripts/onboard.sh 里的 PROFILE[paid]),不是 release 里的一个文件。

买卖双方都需要 x402:卖方要报价和结算,买方要签授权。任何一侧缺了, 这条路径都走不完(见本页最后一节)。

二、要注册在一个 hub 上

credit 记在 hub 的账本里,hub:<hub-aid> 就是账本的名字。没有 hub 就没有账本, anet balance、anet redeem 之类会直接回答"没有配 hub"。

闭环:标价 → 报价 → 付款 → 结算 → 上链

{"modules": {"service": {
  "capabilities": [
    {"id": "text.digest",      "url": "http://127.0.0.1:8080/digest"},
    {"id": "text.digest.paid", "url": "http://127.0.0.1:8080/digest", "price": 25}
  ],
  "timeout_ms": 30000
}}}

anet stop && anet up

anet hub-register https://hub.agentnetwork.org.cn --name my-node

anet delegate <provider-aid> --capability text.digest.paid --args '{"text":"hi"}'
anet results

{
  "capability": "text.digest.paid",
  "status": "PAYMENT_REQUIRED",
  "message": "text.digest.paid costs 25 credits on hub:bafyrei…",
  "payment_required": {
    "x402Version": 2,
    "resource": {"url": "anet:capability/text.digest.paid", "description": "text.digest.paid"},
    "accepts": [
      {
        "scheme": "anet-credit",
        "network": "hub:bafyrei…",
        "amount": "25",
        "asset": "credit",
        "payTo": "bafyrei…",
        "maxTimeoutSeconds": 300
      }
    ]
  }
}

anet delegate <provider-aid> --capability text.digest.paid --args '{"text":"hi"}' --pay

anet x402-authorize --pay-to <payee-aid> --amount 25 --network hub:<hub-aid> --interaction gw-1

anet evidence --type anet.payment.authorized
anet evidence --type anet.payment.settled

anet balance

{
  "aid": "bafyrei…",
  "hub": "https://hub.agentnetwork.org.cn",
  "network": "hub:bafyrei…",
  "asset": "credit",
  "balance": 75,
  "entries": [ … ]
}

anet-hub -data <hub 数据目录> -grant <aid> -amount 500 -reason "top-up"

对账与审计:节点自己查 hub 的账

余额是 hub 的,记录是双方的 —— 那么"双方的记录"就得真的被拿出来比一次, 否则它只是一句设计上的说法。两条命令,都不需要任何人的许可。

anet reconcile:本节点的付款记录 vs hub 的流水

anet reconcile

它拉 /agents/<aid>/balance 和 /agents/<aid>/ledger?limit=500,再读本节点链上的 anet.payment.authorized / anet.payment.settled / anet.credit.redeemed,按交易 id 比对。

输出里值得看的字段:

限制要说准:它只查这一个账户。 它对发给别人的 credit 一无所知 —— 那正是发放链 和见证要单独存在的原因。

anet audit-hub:验 hub 的发放链

anet audit-hub

它拉 GET /x402/issuance?from=0,对每一条记录:

• 用 hub 公布的密钥历史验签(密钥历史本身在被采信前先验过重放)
• 验前后哈希链接
• 与本节点此前记录过的链头比对

issued / retired 的合计是从签名记录自己的事件类型和载荷重算的,不读 hub 摆在 旁边的 JSON 列。那些列是 hub 渲染的,不是它签的;两者不一致恰恰是审计该暴露的东西, 而不是该采信的东西。

输出:hub、chain_did、entries、head_seq、head_id、issued、retired、 verified,以及非空时才出现的 problems。任何一条 seq 的 id 与本节点此前记过的不同, problems 里会直接写出 "hub 改写了它的发放历史",带上本节点当初看到它的时间。

它防不住什么:发放。 hub 是发行方,可以随时创造 credit —— 那就是"发行方"的意思。 变的是它无法追溯地或无声地做这件事,前提是有人看过。

见证:让"有人看过"这件事对陌生人也成立

链只对"已经持有旧副本"的人可验分叉。从未被观察过的 hub 可以出示任意一条链。 所以节点可以定期把链头钉下来:

{"modules": {"x402": {"witness_hub": true, "witness_every_seconds": 3600}}}

witness_hub 默认关。打开后,节点每隔 witness_every_seconds(缺省 3600 秒; 启动后 30 秒先跑一次)取一次 GET /x402/issuance/head,先把它记进自己的链 (anet.issuance.head_seen),再签一份见证投给 POST /x402/witness。先记自己那份, 因为那一份是 hub 够不着的,也是这件事值得做的全部理由。

默认关是有理由的:一个精简版节点可能什么都不提供、只和自己的 hub 说话, 要求它为网络干活不是它答应过的事。打开的节点收益最直接 —— 它拿到了关于自己余额 所在账本的独立证据。

任何人都可以核一份见证:

anet verify --attestation <base64> --hub https://hub.agentnetwork.org.cn

hub 侧四个公开只读端点,不需要认证:

/x402/supply 里 outstanding == balances 是任何人都能自己重算的等式; chain_opening 单独列出而不并入 chain_issued,因为前者是 hub 关于自己过去的自述, 后者每一条都有签名记录可被钉住。

兑付:把 credit 拿出来

anet redeem 100 --ref invoice-2026-08

它签一张"付给 hub"的授权 —— 提现本来就是这件事。hub 那边 credit 真的离开流通 (未清偿负债降低),hub 签字说明取走了多少、对着哪个外部凭据。节点验过那个签名之后 记 anet.credit.redeemed,带 verified 字段:

anet evidence --type anet.credit.redeemed

兑付前后 GET /x402/supply 的 outstanding 应当正好降低你取走的数, 且 outstanding == balances 仍然成立。这两条是 scripts/scenario.sh 6.7 节的断言。

可选的公开兑付口:在 hub 付钱,到节点取货

前面那条路(委派 + --pay)全程经 hub 中继,不需要任何公开端口。 这一节是另一条路:hub 替提供方开一个 x402 资源服务器,收 402、结算, 然后把一张凭证交给买家,买家自己拿凭证去找提供方取货。 hub 因此从头到尾没见过请求,也没见过结果。

配置:

{"modules": {"x402": {
  "voucher_addr": "0.0.0.0:8402",
  "voucher_url":  "https://your-node.example/x402/redeem"
}}}

两个字段必须同时给,只给一个会在 daemon 启动时被拒。那是会在很久以后才安静失败的 形状:要么监听了但没人知道地址,要么卡片指向一个从未打开的端口,两种都在卖收不到的货。

两个字段分开,是因为监听地址常常是 0.0.0.0 或容器内端口,把那种地址签进卡片 等于公布一个谁也到不了的门牌 —— 世界看到的是什么,只有运维知道。

voucher_url 要写成买家真正能 POST 到的那个地址,也就是带上兑付路径 (scripts/scenario.sh 与 scripts/prodtest.sh 里都是 …/x402/redeem 形式)。 它会被签进本节点卡片的 x402-redeem endpoint。

监听口上有三条路由:GET /x402/redeem(自我说明,给撞见这个端口的人看)、 POST /x402/redeem(真正的兑付)、GET /healthz。

走一遍

GET  https://<hub>/x402/resource/<aid>/<capability>
  → 402,PAYMENT-REQUIRED 头 + body:accepts / resource / redeem_at / how

GET  同一个 URL,带 PAYMENT-SIGNATURE: <anet x402-authorize 打印的值>
  → 200,PAYMENT-RESPONSE 头 + body 里一张 voucher

POST <redeem_at>
  {"voucher": "…", "capability": "…", "args": { … }}
  → 200,活真的在提供方那里跑了,带状态、证据、metrics

凭证窗口是 10 分钟(hub 的 voucherWindow)。

hub 在这条路上能做和不能做的

一次性由卖方把关

• 已兑付的凭证 id 记在卖方链上的 anet.voucher.redeemed,启动时从链回读, 所以重启不会让一张旧凭证复活。回读深度 10000 条;更深处会打印一行日志说明 集合被截断,而不是假装它完整。
• 先记链,后干活:崩在中间不会留下一张"看起来没兑过"的已兑凭证。
• 同一张凭证第二次来 → 409,this voucher has already been redeemed。
• 本节点根本不提供这条能力 → 404,并且释放占用 —— 买家应该能拿这张票去找 hub, 一张被我们吃掉却没干活的凭证是他们没法证明未使用的。
• 被拒绝的兑付也上链(anet.voucher.refused,带原因)。一次拒绝也是证据: 没有它,付了钱被挡回去的买家只拿到本节点的沉默,运维也无从发现自己在拒绝所有人。

anet evidence --type anet.voucher.redeemed

兑付跑出来的效果记的是 anet.capability.effect,和经中继委派的活同一个事件类型, 只是多一个 via: voucher。不同的门,同样的证据。

没有付费构建时:答 UNAVAILABLE,不会免费干

判据是符号数,不是"运行时禁用",而且两个方向都要验 —— 只验裁剪版为 0, 会让一个从未被链接进去的模块看起来"可插拔":

go build -o /tmp/anet-full ./cmd/anet
go build -tags no_x402 -o /tmp/anet-lean ./cmd/anet
go tool nm /tmp/anet-full | grep -cE 'module/x402'   # 必须 > 0
go tool nm /tmp/anet-lean | grep -cE 'module/x402'   # 必须 == 0

这两条就是 CI 的 pluggable job 对每个减法 tag 跑的检查 (.github/workflows/ci.yml)。这里用裸 go build 而不是 scripts/build.sh: 后者带 -ldflags "-s -w",-s 会把符号表一起去掉,go tool nm 于是查不了它的产物。 release 二进制刻意只用 -w(deploy/release/build-release.sh 里写明了理由), 所以对装好的二进制可以直接 go tool nm "$(command -v anet)" | grep -cE 'module/x402'。

这样的节点遇到一条标价的能力时:

status:  UNAVAILABLE
message: anet: this build has no payment support
         (built with -tags no_x402, or the x402 module is not configured)

它不会免费把活干了。"我收不了你的钱,所以我不干"是真话;"给你,不要钱" 是没人做过的决定。这条是拆模块时发现的:内核若直接跳过付费逻辑,一条标价 25 credits 的能力在无付费构建上会照干不误,而且全套测试全绿。

同一个构建上,anet balance、anet redeem、anet reconcile、anet audit-hub 也都明确回答本构建没有付费支持,而不是返回一个空结果。 scripts/onboard.sh 在 min 档上逐条断言了这些行为。

买方侧同理:没有 x402 的构建执行 anet delegate … --pay 会直接报同一句话, 因为签授权需要的那个接缝(module.PaymentSeam)在这个二进制里不存在。

出错时读什么

这里要说准一件事:x402 的原因常量和 hub 实际吐出的字符串不是一回事。 ANetCore/payment 定义了一套原因词汇 —— insufficient_funds、invalid_signature、 expired、unknown_payer、network_mismatch、malformed_payment —— 但当前的 ANetHub 只有两个是照常量原样发出的:结算路径上的 insufficient_funds,以及 hub 网关与 POST /x402/redeem 入口上的 malformed_payment。其余几种情况答的是 上表里那些散句。想按常量分支的客户端现在只能靠这两个;别的要读文本。

已知边界

• 托管:余额在 hub 手里。上面所有工具改变的是"能不能被查出来",不是"能不能发生"。
• anet reconcile 只查本账户,对发给别人的 credit 一无所知。
• anet audit-hub 拦不住增发,只拦追溯改写与无声改写。
• 见证品要在见证者手里才有意义。只由被审计方保管的证据不是证据;hub 也公布收到的 见证,那是给读者一个起点 —— 它可以扣着不发,但伪造不了。
• 跨 hub:一次付款只造一份 credit。付款方 hub 的 payee 不在本地时,它销毁 credit 并在 hub_due 里记欠款;收款方 hub 凭收据创造 credit。两侧都把这次变动 写进各自的发放链。引入的信任要说明白:B 给自己用户入账,是因为 A 说它扣了自己用户的钱。 收据让这个说法可追责,但不能让它变真 —— 所以 peer 是白名单,欠款是记着而不是抹平的。 运营面:anet-hub -due 列出对外负债, anet-hub -clear <peer-aid> -amount <n> -payee <aid> -peer-endpoint <url> 签一份 清偿声明投给对端。减记发生在投递之后,对端拒收的清偿仍然是欠着的。
• NAT 后面的节点不能用 hub 网关卖东西,只能走中继委派路径。
• 凭证的一次性由卖方把关。不记的卖方等于同意"一份钱两份活"。

接下来