约束模型¶

约束是限制 LedgerFlow 授权令授权内容的类型化规则。与通用策略语言不同，LedgerFlow 使用封闭的约束类型集合——每种都有清晰的语义，无需外部状态即可验证。

设计原理¶

通用策略引擎（OPA、Cedar、CEL）功能强大，但引入了复杂性：

Schema 编译和求值开销
策略配置错误的风险
静态分析和审计的困难

LedgerFlow v1 使用类型化约束——一组固定结构，验证器可以通过简单的字段比较进行检查。这保持验证快速、审计友好且安全。

约束类型¶

商户约束¶

限制哪些商户可以接受授权令。

pub struct MerchantConstraint {
    pub merchant_ids: Vec<String>,    // 稳定的商户标识符
    pub host_suffixes: Vec<String>,   // 主机名后缀（如 "api.example.com"）
}

空的 merchant_ids 和 host_suffixes 表示任何商户
两个字段都存在：商户必须匹配任一字段中的至少一个条目
主机后缀支持类似通配符的匹配：".example.com" 匹配 "api.example.com"

资源约束¶

限制代理可以访问的 HTTP 资源。

pub struct ResourceConstraint {
    pub http_methods: Vec<String>,   // 如 ["GET", "POST"]
    pub path_prefixes: Vec<String>,  // 如 ["/api/v1/data", "/v2/query"]
}

空的 http_methods 允许所有方法
空的 path_prefixes 允许所有路径
路径前缀匹配是前缀匹配：/api/v1 匹配 /api/v1/resource

工具约束¶

限制代理可以调用的 AI 工具、模型或操作。这是 AI 原生约束。

pub struct ToolConstraint {
    pub tool_names: Vec<String>,         // 如 ["web_search", "code_execution"]
    pub model_providers: Vec<String>,    // 如 ["openai", "anthropic"]
    pub action_labels: Vec<String>,      // 如 ["read", "generate"]
}

商户在验证前将请求上下文映射到这些标签。LedgerFlow 不需要理解模型内部——它只检查标签。

支付约束¶

限制授权支付的财务参数。

pub struct PaymentConstraint {
    pub max_per_request: AmountLimit,
    pub period_limit: Option<PeriodLimit>,
    pub allowed_assets: Vec<AssetRef>,
    pub allowed_rails: Vec<PaymentRail>,
    pub allowed_schemes: Vec<String>,
    pub payee_ids: Vec<String>,
}

字段	描述
`max_per_request`	单次支付的最大金额
`period_limit`	可选的滚动窗口限制（如每天 $100）
`allowed_assets`	允许的资产（如 USDC、USDT）
`allowed_rails`	高级轨道：`Onchain`、`Exchange`、`Custodial`、`TraditionalGateway`
`allowed_schemes`	特定的 x402 结算方案
`payee_ids`	绑定到特定商户端支付身份

赞助约束¶

控制代理是否可以使用赞助执行（如 Gas 赞助、Paymaster）。

pub struct SponsorshipConstraint {
    pub allow_sponsored_execution: bool,
    pub sponsor_ids: Vec<String>,
}

这授权赞助执行，而不将 Paymaster 或合约逻辑推入 LedgerFlow 核心。

约束组合¶

授权令中的所有约束都是 AND 组合。只有当每个约束都通过时，授权令才能授权支付。

授权令授权 = 商户通过 AND 资源通过 AND 工具通过 AND 支付通过 AND 赞助通过

要授予更广泛的权限，签发多个授权令或使用更少的约束。

递减规则¶

委托授权令时，约束只能被缩小，不能被扩大：

父约束	委托规则
`merchant_ids: [A, B]`	子授权令：`[A, B]` 的子集或相同
`max_per_request: 100`	子授权令：`<= 100`
`tool_names: [T1, T2]`	子授权令：`[T1, T2]` 的子集
`expires_at: T`	子授权令：`<= T`
`max_depth: 3`	子授权令：`< 3`

这种单调属性在授权令签发时强制执行，而非在验证时。

约束示例¶

示例 1：研究代理¶

授权代理查询数据 API，每次请求限制 $5：

{
  "constraints": [
    {
      "kind": "merchant",
      "host_suffixes": [".data-provider.io"]
    },
    {
      "kind": "resource",
      "http_methods": ["GET"],
      "path_prefixes": ["/api/v1/query"]
    },
    {
      "kind": "payment",
      "max_per_request": { "amount": "5000000", "asset": "USDC" },
      "allowed_rails": ["Onchain"]
    }
  ]
}

示例 2：带工具范围的代码代理¶

授权代理在单个商户上使用特定 AI 工具：

{
  "constraints": [
    {
      "kind": "merchant",
      "merchant_ids": ["code-execution-platform"]
    },
    {
      "kind": "tool",
      "tool_names": ["sandbox_run", "lint_check"],
      "model_providers": ["anthropic"]
    },
    {
      "kind": "payment",
      "max_per_request": { "amount": "1000000", "asset": "USDC" },
      "period_limit": { "amount": "10000000", "period_seconds": 86400 }
    }
  ]
}

示例 3：委托子代理¶

父授权令持有者委托给范围缩小的子代理：

{
  "constraints": [
    {
      "kind": "merchant",
      "merchant_ids": ["data-provider-1"]
    },
    {
      "kind": "payment",
      "max_per_request": { "amount": "100000", "asset": "USDC" }
    }
  ],
  "delegation": { "can_delegate": false, "max_depth": 0 }
}

未来扩展¶

LedgerFlow v2 可能添加：

基于 ZedToken 的一致性期间约束
使用类型化上下文求值的条件约束
多租户授权令的约束集
常见授权模式的约束模板

参见¶

协议 — 线路格式和证明模型
核心概念 — 授权令、委托和身份
安全 — 约束如何被强制执行