Settlement Plans

Settlement plans let a Cortex quote describe multi-merchant splits, tax reserves, tips, and fees without forcing every payment rail through one settlement contract. The plan is hash-bound into the quote through termsHash.

Canonical Plan

{
  "schema": "cortex.settlement-plan.v1",
  "network": "base-sepolia",
  "registry": "0xc4c014d9eb2d07ff6f7d2b8625e8cf3bc1150574",
  "quote": {
    "merchant_id": "1",
    "service_numeric_id": "1",
    "agent": "0x...",
    "token": "0x...",
    "payment_rail": "transfer",
    "gross_amount": "1000000"
  },
  "terms": {
    "summary": "One company enrichment response.",
    "refund_policy": "Refunds available when fulfillment does not match accepted quote terms."
  },
  "fulfillment": {
    "encrypted_payload_uri": "https://cortex-api.projectaegis.ai/fulfillment/0x...",
    "encrypted_payload_hash": "0x...",
    "encryption": "x25519-xsalsa20-poly1305",
    "merchant_key_id": "did:key:z6MkMerchantFulfillmentKey",
    "plaintext_not_onchain": true
  },
  "lines": [
    { "kind": "merchant", "recipient": "0x...", "amount": "830000", "basis_points": 8300 },
    { "kind": "supplier", "recipient": "0x...", "amount": "100000", "basis_points": 1000 },
    { "kind": "tax", "jurisdiction": "state-or-county", "recipient": "0x...", "amount": "40000", "basis_points": 400 },
    { "kind": "tip", "optional": true, "recipient": "0x...", "amount": "10000", "basis_points": 100 },
    { "kind": "shipping", "method": "merchant-selected ground", "recipient": "0x...", "amount": "15000", "basis_points": 150 },
    { "kind": "handling", "recipient": "0x...", "amount": "5000", "basis_points": 50 }
  ],
  "verification": {
    "line_total": "1000000",
    "matches_quote_amount": true,
    "hash_algorithm": "keccak256(utf8(canonical_settlement_plan_json))"
  }
}

How Agents Verify It

1. Fetch the merchant quote response.
2. Extract the exact settlement_plan JSON.
3. Recompute keccak256 over the canonical JSON bytes.
4. Confirm the hash equals the quote termsHash.
5. Confirm the line total equals the quote amount.
6. Confirm recipients, tax lines, tips, fees, rail, token, and facilitator are allowed by policy.

Line Kinds

Tax lines should be treated conservatively. Cortex should not assume government wallets exist; use merchant reserve wallets, verified tax providers, or independently validated public-sector wallets.

Encrypted Shipping Address

Shipping names, street addresses, phone numbers, and delivery instructions should not be public. Merchants publish a fulfillment encryption key in merchant metadata. Agents encrypt the buyer fulfillment payload to that key, store it offchain, and bind only the encrypted payload URI/hash into the settlement plan.

Settlement Adapter

The settlement adapter turns a verified plan into direct native-token or ERC-20 split execution. It uses deterministic line data derived from the canonical JSON plan and keeps encrypted fulfillment payloads offchain.

function executeSettlement(SettlementInstruction calldata instruction)
    external
    payable
    returns (bytes32 executionHash);

Version One Scope

• Native-token split when token is address(0).
• ERC-20 split when token is not address(0).
• One token per execution.
• Line-total validation against gross amount.
• Merchant, supplier, tax, tip, shipping, handling, fee, and escrow line kinds.

Deferred

• DEX routing and cross-token settlement.
• Tax calculation.
• Address decryption.
• x402 facilitator reconciliation.
• Refund arbitration.