结算架构¶

Facilitator 是结算轨道汇聚的地方。它扩展了标准 x402 Facilitator，增加了轨道无关的路由能力，允许单一商户 API 接受来自任何结算后端的支付。

设计哲学¶

商户永远不知道轨道。 Facilitator 抽象了所有轨道复杂性。 无论代理如何支付，都呈现相同的接口。

轨道适配器接口¶

pub trait RailAdapter {
    fn kind(&self) -> PaymentRail;
    async fn quote(&self, request: &SettlementIntent) -> Result<RailQuote>;
    async fn settle(&self, request: &SettlementIntent) -> Result<SettlementReceipt>;
    async fn verify(&self, receipt: &SettlementReceipt) -> Result<VerificationResult>;
}

每个轨道适配器实现相同的接口。Facilitator 根据以下因素选择适配器：

• 授权令的 allowed_rails 约束
• 支付主体类型
• 商户结算偏好
• 当前轨道可用性和费用

支持的轨道¶

链上¶

通过智能合约或原生转账的直接区块链结算。

交易所¶

通过交易所内部余额结算，无需链上交易。

托管¶

通过 Facilitator 管理的托管账本账户结算。

传统网关（未来）¶

通过传统支付处理器结算。

结算路由¶

Facilitator 接收：

• 标准 x402 支付要求和负载
• 规范化的 LedgerFlow 授权结果
• 解析的支付主体
• 商户结算偏好

它不需要商户理解底层轨道。

路由算法¶

1. 从 LedgerFlow 扩展中提取支付主体
2. 确定主体类型（Caip10、ExchangeAccount 等）
3. 按授权令的 allowed_rails 约束过滤可用轨道
4. 按商户偏好轨道过滤
5. 选择成本最低且流动性充足的轨道
6. 执行报价和结算
7. 返回规范化 x402 结算结果

示例：同一商户，不同轨道¶

商户："为此 API 调用支付 $5"

代理 A（Base 钱包）：
  → payment_subject: caip10:eip155:8453:0xabc...
  → 轨道：链上（Base USDC via x402 合约）

代理 B（币安用户）：
  → payment_subject: binance:uid:12345678
  → 轨道：交易所（币安内部转账）

代理 C（OKX 用户）：
  → payment_subject: okx:subacct:agent-alpha
  → 轨道：交易所（OKX 子账户转账）

三者：相同的 x402 流程，相同的商户代码，不同的轨道。

支付主体解析¶

Facilitator 将支付主体解析为具体的结算身份：

pub struct PaymentSubjectRef {
    pub kind: PaymentSubjectKind,
    pub value: String,
}

可扩展性¶

新轨道可以通过实现 RailAdapter trait 添加：

1. 在 crates/ledgerflow-facilitator/src/rails/ 中创建新模块
2. 为新轨道实现 RailAdapter
3. 在 Facilitator 路由表中注册适配器
4. 在 PaymentRail 枚举中添加轨道

不需要修改 x402、LedgerFlow 核心或商户代码。

参见¶

• 协议 — 授权令和证明格式
• x402 集成 — LedgerFlow 如何扩展 x402
• 安全 — 结算验证保证