跳转至

x402 集成

LedgerFlow 被设计为 x402 支付协议的纯扩展。它在不改变任何 x402 语义的情况下添加授权。

黄金法则

商户服务器只说 x402。 LedgerFlow 数据严格作为 x402 扩展传输。 结算轨道细节保留在 Facilitator 内部。

x402 职责边界

x402 处理什么

  • 支付挑战和响应流程
  • 传输头部和负载结构
  • 支付验证和结算合约
  • 商户-代理互操作接口

LedgerFlow 处理什么

  • 授权令格式定义
  • 授权证明格式
  • 签名身份和授权令签名验证
  • 对 x402 报价和请求上下文的授权约束
  • 可缓存的授权令摘要和本地重放保护
  • 面向 x402 中间件的规范化授权决策

Facilitator 处理什么

  • 将 x402 支付要求映射到实际结算轨道
  • 与区块链、交易所、托管人或传统网关交互
  • 支付验证和结算执行
  • 向商户返回规范化 x402 结算结果

扩展键

LedgerFlow 数据位于 x402 扩展命名空间下：

extensions["ledgerflow"]

这是 LedgerFlow 接触 x402 的唯一接口。核心的 PaymentRequired、PaymentPayload 和 HTTP 头部保持标准 x402。

挑战扩展

当商户返回 402 Payment Required 时，它在 x402 响应体中包含 LedgerFlow 挑战扩展。

{
  "extensions": {
    "ledgerflow": {
      "version": "lfx402/v1",
      "challenge_id": "01HV7W8M7BX3Q6P0WJ7T5QK1V2",
      "proof_binding": "accepted+request",
      "warrant_transport": "inline_or_digest_ref",
      "required_subject_kinds": ["signer", "payment_subject"],
      "nonce_bytes": 16
    }
  }
}

这不改变 x402 语义。它告诉客户端如何满足额外的授权要求。

响应扩展

当代理发送支付响应时，它保持标准 x402 负载，并在同一扩展键下添加 LedgerFlow 数据。

{
  "accepted": { "...": "标准 x402 接受的支付要求" },
  "payload": { "...": "标准 x402 支付负载" },
  "extensions": {
    "ledgerflow": {
      "version": "lfx402/v1",
      "challenge_id": "01HV7W8M7BX3Q6P0WJ7T5QK1V2",
      "warrant": {
        "encoding": "lfw1+cbor",
        "digest": "sha256:8a5a...",
        "inline_b64": "base64url..."
      },
      "proof": {
        "encoding": "lfpop1",
        "created_at_ms": 1774502400123,
        "nonce_b64": "tR4Q7Y3qZ9GxwY6l9cYkQQ==",
        "request_hash": "sha256:5d2d...",
        "accepted_hash": "sha256:f321...",
        "signature": {
          "alg": "ed25519",
          "value_b64": "..."
        }
      },
      "subject": {
        "signer": {
          "alg": "ed25519",
          "key_b64": "..."
        },
        "payment_subject": {
          "kind": "facilitator_account",
          "value": "binance:uid:12345678"
        }
      }
    }
  }
}

验证流程

1. 商户收到带有 x402 PaymentRequired 响应的请求
2. 商户 x402 中间件提取 extensions["ledgerflow"]
3. LedgerFlow 验证器：
   a. 验证授权令签名
   b. 验证证明签名
   c. 检查授权令有效期
   d. 检查受众范围
   e. 对照请求上下文检查所有约束
   f. 验证证明绑定到精确的选中 accepted 对象
   g. 验证证明绑定到当前 HTTP 请求
   h. 检查重放保护
4. 返回规范化授权决策
5. x402 中间件在授权后继续结算

商户永远不需要知道的

商户永远不需要知道：

  • 结算是在以太坊、Solana 还是通过币安进行的
  • 支付主体标识符的含义
  • 代理钱包在哪条链上
  • Facilitator 如何路由支付
  • 底层轨道的任何细节

商户看到 x402。商户验证 x402 + LedgerFlow 授权。Facilitator 完成其余工作。

多轨道结算

相同的商户 API、相同的 x402 流程、不同的结算轨道：

代理 结算轨道 商户体验
代理 A Base USDC 标准 x402
代理 B 币安内部 标准 x402
代理 C OKX 标准 x402
代理 D Stripe（未来） 标准 x402

商户永远不需要修改代码。Facilitator 抽象了所有轨道复杂性。

参见