From 1a25cb76f64efd46ce69fb222c7cb5fb0934c1ce Mon Sep 17 00:00:00 2001 From: jizhen181-dot Date: Mon, 12 Oct 2026 17:20:34 +0800 Subject: [PATCH 1/5] docs: add TRC-20 approval resource sponsoring best practice MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Port "TRON 上的 x402 支付：首次授权与资源赞助" from boboliu-1010/trc20-resource-approve-article as the second Best Practices article, with an English translation and English diagram variants. Co-Authored-By: Claude Opus 5.5 (1M context) --- devnotes/index.md | 1 + .../trc20-approval-resource-sponsoring.md | 150 ++++++++++++++++++ .../current/index.md | 1 + .../trc20-approval-resource-sponsoring.md | 150 ++++++++++++++++++ sidebarsDevnotes.js | 1 + .../trc20-sponsoring-before-after-en.svg | 1 + .../trc20-sponsoring-before-after.svg | 1 + .../trc20-sponsoring-payment-flow-en.svg | 1 + .../trc20-sponsoring-payment-flow.svg | 1 + ...c20-sponsoring-runtime-architecture-en.svg | 1 + .../trc20-sponsoring-runtime-architecture.svg | 1 + 11 files changed, 309 insertions(+) create mode 100644 devnotes/trc20-approval-resource-sponsoring.md create mode 100644 i18n/zh-Hans/docusaurus-plugin-content-docs-devnotes/current/trc20-approval-resource-sponsoring.md create mode 100644 static/img/devnotes/trc20-sponsoring-before-after-en.svg create mode 100644 static/img/devnotes/trc20-sponsoring-before-after.svg create mode 100644 static/img/devnotes/trc20-sponsoring-payment-flow-en.svg create mode 100644 static/img/devnotes/trc20-sponsoring-payment-flow.svg create mode 100644 static/img/devnotes/trc20-sponsoring-runtime-architecture-en.svg create mode 100644 static/img/devnotes/trc20-sponsoring-runtime-architecture.svg diff --git a/devnotes/index.md b/devnotes/index.md index 76b3e1b2..1d81c215 100644 --- a/devnotes/index.md +++ b/devnotes/index.md @@ -10,3 +10,4 @@ Practical, battle-tested guidance from the BANK OF AI team — hands-on walkthro ## Practices - [**BANK OF AI x402: Stablecoin Payments for AI Agents**](./x402-stablecoin-payments-for-agents/) — how the HTTP 402 challenge–response works, when to choose `exact` / `exact_gasfree` / `upto` / `batch-settlement`, and an end-to-end paid-inference case study on TRON. +- [**x402 Payments on TRON: First-Time Approval and Resource Sponsoring**](./trc20-approval-resource-sponsoring/) — how a Facilitator can sponsor the Energy and Bandwidth for a USDT-only wallet's first Permit2 `approve`, a 0.05 USDT payment walkthrough, and how to wire the sponsoring runtime into your own Facilitator. diff --git a/devnotes/trc20-approval-resource-sponsoring.md b/devnotes/trc20-approval-resource-sponsoring.md new file mode 100644 index 00000000..890109bf --- /dev/null +++ b/devnotes/trc20-approval-resource-sponsoring.md @@ -0,0 +1,150 @@ +--- +title: 'x402 Payments on TRON: First-Time Approval and Resource Sponsoring' +description: 'How a Facilitator can sponsor the Energy and Bandwidth for the first Permit2 approve of a USDT-only agent wallet, and how to implement the extension in your own Facilitator.' +--- + +# x402 Payments on TRON: First-Time Approval and Resource Sponsoring + +When you pay in USDT on TRON, the first step may be an on-chain approval for Permit2. That transaction needs Energy and Bandwidth. For an agent wallet that holds only USDT, payment often gets stuck right here. + +TRC-20 approval resource sponsoring lets the service side cover the resources this approval needs, so the paying wallet does not have to hold TRX in advance. This works only when the account is already activated, the token and payment scheme are supported, the resource server and Facilitator have sponsoring enabled, and the sponsor has enough resources and quota. Account activation still has to be done separately. + +This article starts with the first payment, then looks at how the Facilitator implements resource sponsoring. It does not cover production deployment or security assessment. For those, see [Security considerations](https://github.com/BofAI/x402/blob/v1.2.0/specs/extensions/trc20_approval_resource_sponsoring.md#security-considerations). + +## 1. Preparing resources before the first payment + +Suppose a research agent wants to buy a dataset priced at 0.05 USDT. Its wallet is activated, holds 10 USDT and 0 TRX, and has never approved Permit2. The quote is within budget, but the wallet lacks the Energy and Bandwidth needed to run `approve`, so it cannot pay yet. + +There are two different costs here. Buying the data costs USDT. Running the on-chain approval consumes Energy and Bandwidth. Having enough USDT does not solve the resource problem of the approval transaction. + +If the user has to prepare TRX or top up resources by hand, the agent has to stop and wait. With resource sponsoring enabled, the Facilitator can arrange the resources during the payment flow, while the wallet still signs the approval transaction and the payment credential. + +## 2. From Permit2 approval to actual payment + +To pay through Permit2, the wallet first calls the token contract's `approve` to set a spending allowance for the designated Permit2 contract. For every payment after that, the wallet also signs a separate payment credential that fixes the amount, recipient, and other terms. + +When reading the flow, keep these concepts apart: + +| Concept | Meaning in the flow | +| --- | --- | +| TRC-20 approval `approve` | An on-chain transaction that sets a token spending allowance for the designated Permit2 contract | +| Allowance `allowance` | The approved amount recorded by the token contract, used to decide whether another approve is needed | +| Payment credential | The wallet's signature over the terms of this payment, such as amount, recipient, and validity window | +| Settlement | Executing the on-chain payment or channel deposit based on a valid payment credential | + +A successful approve does not move any tokens yet. The payment succeeds only once settlement completes. For later calls to the service, as long as the allowance is sufficient, there is no need to approve again. + +## 3. Sponsoring and reclaiming approval resources + +In the SDK this extension is called `trc20ApprovalResourceSponsoring`. The resource server uses the x402 payment requirements to tell the client that this approval can be sponsored. When the client finds that an approve is needed, it signs the approval transaction and hands it to the Facilitator together with the payment credential, instead of broadcasting it itself. + +The Facilitator checks the approval transaction and the payment credential, then coordinates the **Resource Owner** (the resource account) to temporarily delegate Energy to the paying account, adding Bandwidth when needed. Once the resources are available, it broadcasts the raw approve signed by the wallet. Only after confirming the allowance has taken effect does it continue to settlement. + +![First Permit2 payment compared: preparing approval resources yourself vs. the Facilitator coordinating resource sponsoring](/img/devnotes/trc20-sponsoring-before-after-en.svg) + +*Figure 1: The Facilitator coordinates resources; the paying wallet signs the approval transaction and the payment credential.* + +The Resource Owner's resources come from Stake 2.0 staking. It delegates the right to use those resources to the paying account, while the staked principal stays in its own name. Here, Resource Owner means the account that provides on-chain resources. The business server that provides data or model services is called the Resource Server. + +After the approval completes, the Facilitator starts reclaiming the resources. Any unfinished reclaim and recovery work continues in the background, and payment settlement does not wait for it. Because the sponsor bears the resource cost, it sets its own conditions, such as which assets it supports and how much it will sponsor. + +## 4. A complete 0.05 USDT payment + +Back to the data purchase example. With an `exact` fixed-amount payment, the flow from the agent's request to receiving the data looks like this: + +![Five steps of a first payment: get a quote, wallet signs, verify and provide resources, settle after approval, return the service result](/img/devnotes/trc20-sponsoring-payment-flow-en.svg) + +*Figure 2: The client keeps the standard x402 request flow and does not need to call a separate resource-preparation API.* + +The agent accepts the 0.05 USDT quote, and the service side sponsors the resources for the first approval as agreed. Assuming no extra token fees and no other concurrent transactions, after a successful payment the wallet and request state change as follows: + +| Item | Before payment | After approval and settlement succeed | +| --- | --- | --- | +| Paying account USDT | 10 USDT | 9.95 USDT | +| Paying account TRX | 0 TRX | 0 TRX; approval resources provided by the sponsor | +| Permit2 allowance | 0; approve required | Established; later payments only check the remaining allowance | +| Payment credential | Not yet signed for this call | Signed and used for this 0.05 USDT settlement | +| Data result | Not yet received | Returned; the agent continues its task | + +*The table above illustrates the flow and has not been measured in practice. Actual costs are as stated by the service provider.* + +## 5. Scope and integration requirements + +This extension applies to the approve step in the following three TRON Permit2 payment schemes: + +| Payment scheme | Where resource sponsoring applies | +| --- | --- | +| `exact` | When a fixed-amount payment needs an approve | +| `upto` | When the path that authorizes a payment cap and later settles the actual amount needs an approve | +| `batch-settlement` | When a Permit2 channel deposit or top-up needs an approve; later operations such as Voucher and Claim do not use this extension again | + +Currently the supported paying account is an activated, single-signature regular account using the default owner permission. To integrate, the client must be able to sign the transactions the extension requires, and the resource server and Facilitator must support the same set of networks, assets, and payment schemes. `exact_gasfree` uses a separate GasFree account and relay flow and is out of scope here. + +In SDK v1.2.0, approve grants a `MaxUint256` allowance to the designated canonical Permit2, and every payment or deposit still needs its own signature. The default `zero-first` strategy applies to accounts whose allowance is zero. If an account already has some allowance but not enough to pay, it must be handled separately according to the token's approval rules. See the [extension specification](https://github.com/BofAI/x402/blob/v1.2.0/specs/extensions/trc20_approval_resource_sponsoring.md) for details. + +## 6. Implementing and extending the Facilitator + +Inside the Facilitator, the protocol layer checks the approval transaction and the payment credential, and hands the actual sponsoring work to the runtime. The runtime arranges resources, broadcasts the approve, and tracks the outcome. The Resource Owner provides resources and signs the delegate and undelegate transactions. Once the approval is complete, the corresponding payment scheme performs settlement. + +![Runtime architecture inside the Facilitator: verify, sponsor, reconcile, and how they relate to the Resource Owner and background jobs](/img/devnotes/trc20-sponsoring-runtime-architecture-en.svg) + +*Figure 3: The runtime connects the payment flow, the resource account, and background recovery jobs.* + +| Runtime entry point | Responsibility | +| --- | --- | +| `verify()` | Read-only checks of the account, allowance, resource needs, and sponsoring conditions; does not delegate resources or broadcast transactions | +| `sponsor()` | Reserves and delegates resources, broadcasts the raw approve, confirms the approval took effect, then records and starts the reclaim | +| `reconcile()` | Called by a background job to handle transactions with unknown outcomes and unfinished resource reclaims and recoveries | + +The **integration example** below shows how the runtime is registered with the Facilitator. Before it can run, you still need to fill in `network`, the signers, the coordinator, the asset address, and the permission configuration: + +```typescript +import { x402Facilitator } from "@bankofai/x402-core/facilitator"; +import { createTrc20ApprovalResourceSponsoringExtension } from "@bankofai/x402-extensions"; +import { createTrc20ResourceSponsoringRuntime } from "@bankofai/x402-tron"; +import { ExactTronScheme } from "@bankofai/x402-tron/exact/facilitator"; + +const runtime = await createTrc20ResourceSponsoringRuntime({ + network, resourceOwnerSigner, coordinator, + allowedAssets: [usdtAddress], permissionId, +}); +const facilitator = new x402Facilitator() + .register(network, new ExactTronScheme(settlementSigner)) + .registerExtension( + createTrc20ApprovalResourceSponsoringExtension(runtime), + ); +// A separate background job keeps calling runtime.reconcile(). +``` + +Here `permissionId` is the Resource Owner's non-zero Active Permission ID, and it must authorize resource delegate and undelegate operations. It is unrelated to the default owner permission used by the paying account. + +When self-hosting, you can replace the sponsoring policy `policy`, the resource coordinator `coordinator`, the chain interaction layer `chain`, and the resource account signer `resourceOwnerSigner` as needed. The high-level factory above accepts a custom `coordinator` and `resourceOwnerSigner`. To provide a custom `policy` or `chain`, use the lower-level `createTrc20ApprovalResourceSponsoringRuntime()`. For persistence, recovery, remote signing, and HSM integration, see the [SDK Facilitator integration guide](https://github.com/BofAI/x402/blob/v1.2.0/typescript/packages/extensions/src/trc20-approval-resource-sponsoring/README.md#facilitator) and the [module interfaces](https://github.com/BofAI/x402/blob/v1.2.0/typescript/packages/mechanisms/tron/src/resource-sponsoring/types.ts). Multi-pool scheduling and third-party Energy provider integration must be implemented yourself. + +## 7. Trying it on Nile and self-hosted development + +BANK OF AI will later support first-time Permit2 approval resource sponsoring on TRON Nile in the Official Facilitator it operates. Once available, you can connect directly to the official service and try a complete payment. The Official Facilitator provides the approval resources, so you do not need your own resource account or runtime deployment. + +### Connecting to the official Nile service + +See the [Official Facilitator documentation](/x402/core-concepts/OfficialFacilitator/) for how to connect. Once Nile sponsoring is available, you can try it with these steps: + +1. Prepare an activated Nile wallet that has not yet approved Permit2, and transfer in a test token supported by the official service. +2. Connect your resource server to the Official Facilitator, declare the resource sponsoring extension on a supported TRON Permit2 route, and use an SDK on the client that supports the extension. +3. Send a request and sign it, then watch the approve take effect, the payment settle, and the service return its result. + +When the sponsoring conditions are met, the paying wallet does not need to hold TRX in advance. The launch date, supported test tokens, and sponsoring quota are as stated by the official service. + +### Running your own Facilitator + +If you want to manage the resource account and sponsoring policy yourself, follow the [SDK Facilitator integration guide](https://github.com/BofAI/x402/blob/v1.2.0/typescript/packages/extensions/src/trc20-approval-resource-sponsoring/README.md#facilitator) to configure the Resource Owner and runtime on Nile. + +For how to verify the first approval, the payment, and the resource reclaim, refer to the [public Nile integration test source](https://github.com/BofAI/x402/blob/v1.2.0/typescript/packages/mechanisms/tron/test/integrations/trc20-approval-resource-sponsoring.nile.test.ts) and run the checks in your own environment. + +## 8. References + +This article is based on BANK OF AI x402 SDK **v1.2.0**, corresponding to `@bankofai/x402-tron@1.2.0` and `@bankofai/x402-extensions@1.2.0`. For interfaces and supported scope, see the [v1.2.0 release notes](https://github.com/BofAI/x402/releases/tag/v1.2.0). + +- [BANK OF AI x402: Stablecoin Payments for AI Agents](./x402-stablecoin-payments-for-agents.md): protocol background and payment schemes. +- [TRC-20 Approval Resource Sponsoring specification](https://github.com/BofAI/x402/blob/v1.2.0/specs/extensions/trc20_approval_resource_sponsoring.md): supported scope and approval constraints. +- [SDK integration guide](https://github.com/BofAI/x402/blob/v1.2.0/typescript/packages/extensions/src/trc20-approval-resource-sponsoring/README.md): client, resource server, and Facilitator integration. +- [Security considerations](https://github.com/BofAI/x402/blob/v1.2.0/specs/extensions/trc20_approval_resource_sponsoring.md#security-considerations): protocol boundaries to consider in a production security assessment. diff --git a/i18n/zh-Hans/docusaurus-plugin-content-docs-devnotes/current/index.md b/i18n/zh-Hans/docusaurus-plugin-content-docs-devnotes/current/index.md index cf8fd8be..0f1d7441 100644 --- a/i18n/zh-Hans/docusaurus-plugin-content-docs-devnotes/current/index.md +++ b/i18n/zh-Hans/docusaurus-plugin-content-docs-devnotes/current/index.md @@ -10,3 +10,4 @@ BANK OF AI 团队沉淀的实战经验——动手演练，以及让 AI 上链 ## 实践列表 - [**BANK OF AI x402：面向 AI 智能体的稳定币支付方案**](./x402-stablecoin-payments-for-agents/) —— HTTP 402 挑战—响应流程如何运作、`exact` / `exact_gasfree` / `upto` / `batch-settlement` 四种方案怎么选，以及一个基于 TRON 的端到端付费推理案例。 +- [**TRON 上的 x402 支付：首次授权与资源赞助**](./trc20-approval-resource-sponsoring/) —— 只持有 USDT 的钱包首次授权 Permit2 时，如何由 Facilitator 赞助 `approve` 所需的能量和带宽，一笔 0.05 USDT 支付的完整过程，以及如何在自己的 Facilitator 中接入赞助 runtime。 diff --git a/i18n/zh-Hans/docusaurus-plugin-content-docs-devnotes/current/trc20-approval-resource-sponsoring.md b/i18n/zh-Hans/docusaurus-plugin-content-docs-devnotes/current/trc20-approval-resource-sponsoring.md new file mode 100644 index 00000000..c3be267d --- /dev/null +++ b/i18n/zh-Hans/docusaurus-plugin-content-docs-devnotes/current/trc20-approval-resource-sponsoring.md @@ -0,0 +1,150 @@ +--- +title: 'TRON 上的 x402 支付：首次授权与资源赞助' +description: '只持有 USDT 的 Agent 钱包首次通过 Permit2 付款时，如何由 Facilitator 赞助 approve 所需的能量和带宽，以及如何在 Facilitator 中实现这项扩展。' +--- + +# TRON 上的 x402 支付：首次授权与资源赞助 + +在 TRON 上用 USDT 付款，第一步可能是先给 Permit2 做一次链上授权。这笔交易需要能量和带宽。对于只持有 USDT 的 Agent 钱包，支付往往就卡在这里。 + +TRC-20 授权资源赞助让服务方承担这次授权所需的资源，付款钱包无需预先持有 TRX。前提是账户已经激活，使用的代币和支付方案受支持，服务端与 Facilitator 已开启赞助，赞助方也有足够的资源和额度。账户激活仍需单独完成。 + +下面从首次支付讲起，再看 Facilitator 如何实现资源赞助。本文不涉及生产部署和安全评估，这部分请参阅 [Security considerations](https://github.com/BofAI/x402/blob/v1.2.0/specs/extensions/trc20_approval_resource_sponsoring.md#security-considerations)。 + +## 1. 首次支付前的资源准备 + +假设一个研究 Agent 要购买一份 0.05 USDT 的数据。它的钱包已经激活，有 10 USDT、0 TRX，也从未授权过 Permit2。报价在预算内，但钱包缺少执行 approve 所需的能量和带宽，暂时还付不了款。 + +这里有两笔不同的开销：买数据花的是 USDT，执行链上授权消耗的是能量（Energy）和带宽（Bandwidth）。USDT 余额够用，并不能解决授权交易的资源问题。 + +如果由用户手动准备 TRX 或补充资源，Agent 就得停下来等。开启资源赞助后，Facilitator 可以在支付过程中安排资源，钱包仍负责签署授权交易和付款凭证。 + +## 2. 从 Permit2 授权到实际付款 + +要通过 Permit2 支付，钱包需要先调用代币合约的 `approve`，给指定的 Permit2 合约设置代币使用额度。之后每次付款，钱包还要签署单独的付款凭证，约定金额、收款方等条件。 + +读流程时，需要区分以下几个概念： + +| 概念 | 在流程中的含义 | +| --- | --- | +| TRC-20 授权 `approve` | 一笔链上交易，为指定的 Permit2 合约设置代币使用额度 | +| 授权额度 `allowance` | 代币合约记录的可用授权额度，用来判断是否还需要 approve | +| 付款凭证 | 钱包对本次支付条件的签名，例如金额、收款方与有效期 | +| 结算 | 根据有效的付款凭证执行链上付款或通道存款 | + +approve 成功后，代币还没有付出去，要等结算完成才算付款成功。以后再调用服务，只要 allowance 足够，就不必重复 approve。 + +## 3. 授权资源的赞助与回收 + +这项扩展在 SDK 中叫 `trc20ApprovalResourceSponsoring`。服务端通过 x402 支付要求告诉客户端：这次授权可以获得资源赞助。客户端发现需要 approve 时，会签好授权交易，连同付款凭证一起交给 Facilitator，不自行广播。 + +Facilitator 检查授权交易和付款凭证，再协调 **Resource Owner**（资源账户）向付款账户临时委托能量，必要时补充带宽。等资源可用，就广播钱包签好的原始 approve。确认 allowance 生效后，才继续结算。 + +![首次 Permit2 支付对比：自行准备授权资源，与由 Facilitator 协调资源赞助](/img/devnotes/trc20-sponsoring-before-after.svg) + +*图 1：Facilitator 负责协调资源，付款钱包负责签署授权交易和付款凭证。* + +Resource Owner 的资源来自 Stake 2.0 质押。它把资源使用额度委托给付款账户，质押本金仍留在自己名下。这里的 Resource Owner 指提供链上资源的账户，提供数据或模型服务的业务服务端则叫 Resource Server。 + +授权完成后，Facilitator 会发起资源撤回，尚未完成的撤回和恢复由后台继续处理，付款结算不必等它结束。赞助方承担了资源成本，因此会自行设定支持哪些资产、赞助多少额度等条件。 + +## 4. 一笔 0.05 USDT 支付的完整过程 + +回到前面购买数据的例子。使用 `exact` 固定金额付款时，从 Agent 发起请求到拿到数据，流程如下： + +![首次支付五步流程：获取报价、钱包签名、校验并提供资源、授权后结算、返回服务结果](/img/devnotes/trc20-sponsoring-payment-flow.svg) + +*图 2：客户端沿用 x402 请求流程，不需要另行调用资源准备接口。* + +Agent 接受 0.05 USDT 的报价，服务方按约定赞助首次授权所需的资源。假设没有额外代币费用，也没有其他并发交易，成功付款后，钱包和请求的状态会这样变化： + +| 项目 | 支付前 | 授权与结算成功后 | +| --- | --- | --- | +| 付款账户 USDT | 10 USDT | 9.95 USDT | +| 付款账户 TRX | 0 TRX | 0 TRX，授权资源由赞助方提供 | +| Permit2 allowance | 0，需要 approve | 已建立，后续付款时检查剩余额度即可 | +| 付款凭证 | 本次调用尚未签署 | 已签署，并用于本次 0.05 USDT 结算 | +| 数据结果 | 尚未取得 | 已返回，Agent 继续任务 | + +*上表为流程示例，未经实测；实际费用以服务方说明为准。* + +## 5. 适用范围与接入条件 + +这个扩展用于以下三种 TRON Permit2 支付方案中的 approve： + +| 支付方案 | 资源赞助作用的位置 | +| --- | --- | +| `exact` | 固定金额付款需要 approve 时 | +| `upto` | 授权支付上限、后续按实际金额结算的路径需要 approve 时 | +| `batch-settlement` | Permit2 通道存款或补款需要 approve 时；后续 Voucher、Claim 等操作不重复使用本扩展 | + +目前支持的付款账户是已激活、使用默认 owner 权限的单签普通账户。接入时，客户端要能签署扩展要求的交易，服务端和 Facilitator 也要支持同一组网络、资产和支付方案。`exact_gasfree` 使用另外的 GasFree 账户与中继流程，不在这里讨论的范围内。 + +SDK v1.2.0 的 approve 会向指定的 canonical Permit2 授予 `MaxUint256` 额度，每笔付款或存款仍需单独签名。默认的 `zero-first` 策略适用于 allowance 为零的账户。如果已有额度但不足以支付，需要按代币的授权规则另行处理，详见[扩展规范](https://github.com/BofAI/x402/blob/v1.2.0/specs/extensions/trc20_approval_resource_sponsoring.md)。 + +## 6. Facilitator 的实现与扩展 + +在 Facilitator 内，协议层负责检查授权交易和付款凭证，资源赞助的具体执行交给 runtime。runtime 负责安排资源、广播 approve、跟踪执行结果；Resource Owner 提供资源，并签署委托和撤回交易。授权完成后，再由对应的支付方案执行结算。 + +![Facilitator 内的 runtime 架构：verify、sponsor、reconcile，与 Resource Owner 和后台任务的关系](/img/devnotes/trc20-sponsoring-runtime-architecture.svg) + +*图 3：runtime 连接支付流程、资源账户和后台恢复任务。* + +| runtime 入口 | 职责 | +| --- | --- | +| `verify()` | 只读检查账户、allowance、资源需求与赞助条件，不委托资源、不广播交易 | +| `sponsor()` | 预留并委托资源，广播原始 approve，确认授权生效，记录并发起回收 | +| `reconcile()` | 由后台任务调用，处理结果未知的交易以及未完成的资源撤回与恢复 | + +下面的**接入示例**展示了 runtime 如何注册到 Facilitator。运行前还需要补齐 `network`、签名器、协调器、资产地址和权限配置： + +```typescript +import { x402Facilitator } from "@bankofai/x402-core/facilitator"; +import { createTrc20ApprovalResourceSponsoringExtension } from "@bankofai/x402-extensions"; +import { createTrc20ResourceSponsoringRuntime } from "@bankofai/x402-tron"; +import { ExactTronScheme } from "@bankofai/x402-tron/exact/facilitator"; + +const runtime = await createTrc20ResourceSponsoringRuntime({ + network, resourceOwnerSigner, coordinator, + allowedAssets: [usdtAddress], permissionId, +}); +const facilitator = new x402Facilitator() + .register(network, new ExactTronScheme(settlementSigner)) + .registerExtension( + createTrc20ApprovalResourceSponsoringExtension(runtime), + ); +// 另由后台任务持续调用 runtime.reconcile()。 +``` + +这里的 `permissionId` 是 Resource Owner 的非零 Active Permission ID，须允许资源委托与撤回操作。它与付款账户使用的默认 owner 权限无关。 + +自托管时，可以按需要替换赞助策略 `policy`、资源协调器 `coordinator`、链交互层 `chain` 和资源账户签名器 `resourceOwnerSigner`。上述高层工厂支持配置 `coordinator` 和 `resourceOwnerSigner`；如需自定义 `policy` 或 `chain`，请使用底层的 `createTrc20ApprovalResourceSponsoringRuntime()`。持久化、恢复、远程签名与 HSM 接入见 [SDK Facilitator 接入文档](https://github.com/BofAI/x402/blob/v1.2.0/typescript/packages/extensions/src/trc20-approval-resource-sponsoring/README.md#facilitator)与[模块接口](https://github.com/BofAI/x402/blob/v1.2.0/typescript/packages/mechanisms/tron/src/resource-sponsoring/types.ts)。多资源池调度和第三方能量供应商接入则需要自行实现。 + +## 7. Nile 体验与自托管开发 + +BANK OF AI 后续会在其运营的 Official Facilitator 上支持 TRON Nile 首次 Permit2 授权资源赞助。开放后，可以直接接入官方服务试一次完整支付，由官方准备授权资源，无需自己准备资源账户或部署 runtime。 + +### 接入官方 Nile 服务 + +接入方式见 [Official Facilitator 文档](/x402/core-concepts/OfficialFacilitator/)。Nile 赞助开放后，可以按以下步骤体验： + +1. 准备一个已激活、尚未授权 Permit2 的 Nile 钱包，转入官方支持的测试代币。 +2. 将业务服务端接入 Official Facilitator，在支持的 TRON Permit2 路由上声明资源赞助扩展，客户端使用支持该扩展的 SDK。 +3. 发起请求并签名，观察 approve 生效、付款结算和服务返回结果的过程。 + +满足赞助条件时，付款钱包无需预先准备 TRX。开放时间、支持的测试代币和赞助额度，以官方服务说明为准。 + +### 搭建自己的 Facilitator + +如果要自己管理资源账户和赞助策略，可以按 [SDK Facilitator 接入说明](https://github.com/BofAI/x402/blob/v1.2.0/typescript/packages/extensions/src/trc20-approval-resource-sponsoring/README.md#facilitator)，在 Nile 配置 Resource Owner 和 runtime。 + +首次授权、付款和资源回收该怎么验证，可以参考[公开的 Nile 集成测试源码](https://github.com/BofAI/x402/blob/v1.2.0/typescript/packages/mechanisms/tron/test/integrations/trc20-approval-resource-sponsoring.nile.test.ts)，在自己的环境中运行检查。 + +## 8. 参考文档 + +本文基于 BANK OF AI x402 SDK **v1.2.0**，对应 `@bankofai/x402-tron@1.2.0` 与 `@bankofai/x402-extensions@1.2.0`。接口与支持范围见 [v1.2.0 发布说明](https://github.com/BofAI/x402/releases/tag/v1.2.0)。 + +- [BANK OF AI x402：面向 AI 智能体的稳定币支付方案](./x402-stablecoin-payments-for-agents.md)：协议背景与支付方案。 +- [TRC-20 Approval Resource Sponsoring 规范](https://github.com/BofAI/x402/blob/v1.2.0/specs/extensions/trc20_approval_resource_sponsoring.md)：支持范围与授权约束。 +- [SDK 接入说明](https://github.com/BofAI/x402/blob/v1.2.0/typescript/packages/extensions/src/trc20-approval-resource-sponsoring/README.md)：客户端、服务端和 Facilitator 接入。 +- [Security considerations](https://github.com/BofAI/x402/blob/v1.2.0/specs/extensions/trc20_approval_resource_sponsoring.md#security-considerations)：生产安全评估需要考虑的协议边界。 diff --git a/sidebarsDevnotes.js b/sidebarsDevnotes.js index 0840ad18..698b4803 100644 --- a/sidebarsDevnotes.js +++ b/sidebarsDevnotes.js @@ -7,6 +7,7 @@ const sidebars = { label: 'Overview', }, 'x402-stablecoin-payments-for-agents', + 'trc20-approval-resource-sponsoring', // 'first-onchain-swap', // 暂时隐藏（文件保留） ], } diff --git a/static/img/devnotes/trc20-sponsoring-before-after-en.svg b/static/img/devnotes/trc20-sponsoring-before-after-en.svg new file mode 100644 index 00000000..c315f3d2 --- /dev/null +++ b/static/img/devnotes/trc20-sponsoring-before-after-en.svg @@ -0,0 +1 @@ +First Permit2 payment: who covers approval resources?Without sponsoring, missing resources must be topped up first. With sponsoring, the wallet signs and the payment infrastructure prepares approval resources and moves the payment forward.BANK OF AI / x402First Permit2 payment: who covers approval resources?Assumes: account activated, service and asset supported, sponsor has enough resources.Without sponsoring: you prepare missing resources yourselfHolds USDTReady to call a serviceTop up resourcesGet TRX or EnergySign and approveapprove on-chainPay, get resultAgent continuesWith sponsoring: wallet signs, infrastructure provides resourcesHolds USDTReady to call a serviceWallet signsapprove tx + credentialInfra handles itResources + approvePay, get resultAgent continuesOnly resource preparation changes. The wallet still signs the approval and the payment. \ No newline at end of file diff --git a/static/img/devnotes/trc20-sponsoring-before-after.svg b/static/img/devnotes/trc20-sponsoring-before-after.svg new file mode 100644 index 00000000..e143d951 --- /dev/null +++ b/static/img/devnotes/trc20-sponsoring-before-after.svg @@ -0,0 +1 @@ +首次 Permit2 支付：授权资源由谁准备？未启用赞助时，资源不足需要先补充资源。启用赞助后，钱包签名，由支付基础设施准备授权资源并推进付款。BANK OF AI / x402首次 Permit2 支付：授权资源由谁准备？前提：账户已激活，服务与资产受支持，赞助资源充足。未启用资源赞助：资源不足时，需要自己准备持有 USDT准备调用服务补充网络资源准备 TRX 或能量签署并完成授权approve 上链付款并取得结果继续 Agent 任务启用资源赞助：钱包签名，基础设施准备资源持有 USDT准备调用服务钱包签名授权交易 + 付款凭证基础设施处理提供资源，完成授权付款并取得结果继续 Agent 任务变化的是资源准备方式；授权和付款仍由钱包签名确认。 \ No newline at end of file diff --git a/static/img/devnotes/trc20-sponsoring-payment-flow-en.svg b/static/img/devnotes/trc20-sponsoring-payment-flow-en.svg new file mode 100644 index 00000000..ad30c1eb --- /dev/null +++ b/static/img/devnotes/trc20-sponsoring-payment-flow-en.svg @@ -0,0 +1 @@ +Five steps of a first Permit2 paymentThe Agent gets a quote and signs; the server hands the credentials to the Facilitator for verification. The Facilitator provides resources, broadcasts the approval, continues payment once it takes effect, and reclaims resources asynchronously.BANK OF AI / x402Five steps of a first Permit2 paymentExample: fixed-price exact payment. With enough allowance, sponsoring and approve are skipped.01Agent ↔ ServerGet a quote for the serviceThe server returns 402 with the price and payment options.02Agent walletSign the approval tx and payment credentialThe wallet signs but does not broadcast approve itself.03Server → FacilitatorVerify, then prepare approval resourcesTemporarily delegates Energy; adds Bandwidth if short.04Facilitator → TRONBroadcast approve, confirm allowance, then settleBroadcasts the wallet-signed approve, then settles the payment.05Server → AgentReturn the result; the Agent continuesResource reclaim and recovery are tracked in the background.Wallet consents and signs · Facilitator handles resources and on-chain execution \ No newline at end of file diff --git a/static/img/devnotes/trc20-sponsoring-payment-flow.svg b/static/img/devnotes/trc20-sponsoring-payment-flow.svg new file mode 100644 index 00000000..b9e1b26d --- /dev/null +++ b/static/img/devnotes/trc20-sponsoring-payment-flow.svg @@ -0,0 +1 @@ +首次 Permit2 支付的五个步骤Agent 获取报价并签名，服务端将凭证交给 Facilitator 验证。Facilitator 提供资源、广播授权，授权生效后继续付款，并异步回收资源。BANK OF AI / x402首次 Permit2 支付的五个步骤以固定价格 exact 支付为例；已有足够授权时，跳过资源赞助和 approve。01Agent ↔ 服务端获取报价，确认要购买的服务服务端返回 402，告知价格与可用的支付方式。02Agent 钱包签署授权交易和付款凭证钱包先签名，暂不自行广播 approve。03服务端 → Facilitator校验凭证，准备授权所需资源临时提供 Energy；Bandwidth 不足时一并补充。04Facilitator → TRON广播授权，确认生效后继续结算广播钱包签署的原始 approve，再执行支付结算。05服务端 → Agent返回服务结果，Agent 继续任务基础设施在后台跟踪资源撤回与恢复。钱包负责同意与签名 · Facilitator 负责资源与链上执行 \ No newline at end of file diff --git a/static/img/devnotes/trc20-sponsoring-runtime-architecture-en.svg b/static/img/devnotes/trc20-sponsoring-runtime-architecture-en.svg new file mode 100644 index 00000000..ff72881b --- /dev/null +++ b/static/img/devnotes/trc20-sponsoring-runtime-architecture-en.svg @@ -0,0 +1 @@ +Approval resource sponsoring inside the FacilitatorThe protocol implementation verifies the request and calls the runtime; the runtime manages sponsoring through verify, sponsor and reconcile, and the Resource Owner provides resources and signs resource operations.BANK OF AI / x402Approval resource sponsoring inside the FacilitatorProtocol verification → Resource sponsoring → SettlementFacilitator protocol implementationVerifies the approval tx and payment credential, calls the runtime, then settles.Resource Sponsoring Runtimeverify()Read-only checksAccount, allowance, policysponsor()Run sponsoringDelegate, approve, reclaimreconcile()Finish pending workLookup, reclaim, recoverPluggable: policy / coordinator / chain / resourceOwnerSignercalls reconcile()requests resource signaturesBackground jobKeeps calling the recovery entryScheduled by your applicationResource OwnerProvides Stake 2.0 Energy and BandwidthSigns delegate and undelegate operationsThe payer wallet signs approval and payment; the resource account signs resource ops. \ No newline at end of file diff --git a/static/img/devnotes/trc20-sponsoring-runtime-architecture.svg b/static/img/devnotes/trc20-sponsoring-runtime-architecture.svg new file mode 100644 index 00000000..73b45c8b --- /dev/null +++ b/static/img/devnotes/trc20-sponsoring-runtime-architecture.svg @@ -0,0 +1 @@ +Facilitator 中的授权资源赞助架构协议实现验证请求后调用 runtime；runtime 通过 verify、sponsor、reconcile 管理赞助，Resource Owner 提供资源并签署资源操作。BANK OF AI / x402Facilitator 中的授权资源赞助架构协议验证 → 资源赞助 → 支付结算Facilitator 协议实现验证 TRC-20 授权交易与付款凭证，调用 runtime；授权就绪后继续结算。Resource Sponsoring Runtimeverify()只读检查账户、授权、资源与策略sponsor()执行资源赞助委托、approve、发起回收reconcile()推进未完成操作交易查询、撤回与恢复可扩展接口：policy / coordinator / chain / resourceOwnerSigner调用 reconcile()请求资源操作签名后台任务持续调用恢复入口由应用接入自己的调度机制Resource Owner · 资源账户提供 Stake 2.0 能量与带宽签署资源委托与撤回操作付款钱包签署代币授权与付款凭证；资源账户签署资源操作。 \ No newline at end of file From 20cb78e784bde221cb223397d0650d57170af99c Mon Sep 17 00:00:00 2001 From: jizhen181-dot Date: Mon, 12 Oct 2026 17:20:34 +0800 Subject: [PATCH 2/5] chore: bump version to 1.4.16 Co-Authored-By: Claude Opus 5.5 (1M context) --- package.json | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/package.json b/package.json index e2701317..ca21a3fc 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "@x402-tron/docs", - "version": "1.4.15", + "version": "1.4.16", "description": "x402-tron documentation", "license": "MIT", "resolutions": { From a2cc98a895edb86ce088396105327ab22ab20585 Mon Sep 17 00:00:00 2001 From: jizhen181-dot Date: Fri, 16 Oct 2026 14:01:10 +0800 Subject: [PATCH 3/5] bump version --- package.json | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/package.json b/package.json index ca21a3fc..b5c4d575 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "@x402-tron/docs", - "version": "1.4.16", + "version": "1.4.17", "description": "x402-tron documentation", "license": "MIT", "resolutions": { From 6daacf83c6d6faf760b7e8ed13dc9426682a46e6 Mon Sep 17 00:00:00 2001 From: jizhen181-dot Date: Mon, 19 Oct 2026 17:03:57 +0800 Subject: [PATCH 4/5] chore: bump version to 1.4.18 Co-Authored-By: Claude Opus 5.5 (1M context) --- package.json | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/package.json b/package.json index b5c4d575..4c11617b 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "@x402-tron/docs", - "version": "1.4.17", + "version": "1.4.18", "description": "x402-tron documentation", "license": "MIT", "resolutions": { From a598269b569ca2da758bd434ffc3c1462831bdea Mon Sep 17 00:00:00 2001 From: jizhen181-dot Date: Thu, 22 Oct 2026 17:14:33 +0800 Subject: [PATCH 5/5] update nodejs version --- Dockerfile | 2 +- package.json | 4 ++-- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/Dockerfile b/Dockerfile index db6fb8f7..a72cb240 100644 --- a/Dockerfile +++ b/Dockerfile @@ -1,5 +1,5 @@ # Stage 1: Build the Docusaurus application -FROM node:20.18.1 AS build +FROM node:22.23.4 AS build ARG APP_ENV diff --git a/package.json b/package.json index 4c11617b..b2a8f0d4 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "@x402-tron/docs", - "version": "1.4.18", + "version": "1.4.20", "description": "x402-tron documentation", "license": "MIT", "resolutions": { @@ -56,7 +56,7 @@ "typescript": "^4.8.4" }, "engines": { - "node": ">=18", + "node": "^22.23.4 || ^24.22.1 || >=26.12.1", "yarn": ">=1.22" } }