[Proposal] On-chain settlement-side mandate binding for AP2

[hilarl]

On-chain settlement-side mandate binding for AP2

Acknowledgment of repo scope

Per CONTRIBUTING.md, the AP2 core specification has been donated to FIDO; this repo's scope is samples and SDK only. The core proposal below is intended for the FIDO working group; I'm filing here to:

1. Surface the on-chain reference implementation to AP2 sample/SDK maintainers and contributors who may want to consume it,
2. Get an early read on whether the envelope shape aligns with what the SDK currently emits, so the FIDO submission can land with concrete sample/SDK alignment evidence.

Happy to redirect this discussion to the FIDO working group if that's the appropriate venue.

Context

AP2 specifies the off-chain agent-payment authorization protocol — verifiable agent credentials, intent mandates, payment mandates. The gap, when AP2 lands on a public chain, is that the on-chain settlement layer typically doesn't verify the mandate; it trusts the wallet client or the relaying facilitator to honor the constraints.

We've shipped a stablecoin (RIVR) where the AP2-compatible mandate envelope is verified at the token contract. Every transferring path runs the full constraint chain: principal+agent EIP-712 signatures (EIP-1271 fall-through for smart accounts), per-tx cap, cumulative cap, asset allowlist, expiry, sanctions, KYA, Travel Rule attestation. The token reverts with a typed RefusalReason if any check fails.

Proposal

A reference on-chain implementation of the AP2 IntentMandate / PaymentMandate constraints, with a normative MandateEnvelope EIP-712 typehash so AP2-emitting agents can target multiple compliant chains without re-shaping the mandate per-chain.

The constraint envelope is rail-agnostic. The same shape applies to card-network mandates and ACH/SEPA/FedNow agent-bound authorizations. Rivier — the platform shipping this — is an agentic commerce + finance platform spanning fiat and crypto rails; RIVR is the crypto-side reference settler. Submissions to fiat-rail venues are happening in parallel.

Reference implementation

MIT, at https://github.com/rivier-ai/rivr.

• Token contract: contracts/src/rivier-token/RivierTokenCCT.sol (transferWithMandate entry point)
• Mandate type: contracts/src/rivier-token/types/MandateEnvelope.sol
• Test suite: contracts/test/rivier-token/ — 113 forge tests covering the dryRun byte-equivalence invariant (off-chain simulation byte-equivalent to on-chain revert), namespace sum-preservation under fuzzing, replay protection, and reentrancy safety.

Audit: not yet commissioned. Independent contributor, pre-funding; engagement is planned post-launch.

What I'm asking for

1. Sample/SDK maintainer feedback on whether the envelope shape aligns with what the AP2 SDK currently emits.
2. Pointer to the right FIDO working-group venue for the normative submission.
3. Whether the AgentAttestation v1 extensionData shape (model id, version, confidence, reasoning hash, prompt hash, MCP server DID, TEE attestation hash, policy compliance proof) aligns with FIDO's existing attestation taxonomy.

FIDO Alliance Liaison membership is on the roadmap once the project's legal entity is formed; for now I'm contributing as an individual.

---

Disclosure: parts of this issue body were drafted with assistance from an AI model and reviewed before submission. The reference implementation, test suite, and design decisions are human-authored.

[Ectsang]

The envelope shape makes sense — especially the typed RefusalReason reverts. On-chain enforcement at the token level is the cleanest way to guarantee constraints aren't bypassed.

The part I'd push on: the cumulative cap counter lives in contract storage, so it only sees spend on that chain. An agent operating across RIVR on Base and a card rail via Stripe has two independent counters. I hit the same problem from the off-chain side (#207) — ended up building an external authority with authorize/commit/refund/query verbs that tracks spend across rails. Got a sample approved here (#252) showing the pattern.

Might be worth adding an optional attestation field to the MandateEnvelope — a pointer to an off-chain authority's signed budget state. Then on-chain and off-chain enforcement compose instead of competing.

[chopmob-cloud]

Operational notes on the envelope-shape question from someone who shipped JCS-canonical mandate binding for AP2 samples (PR #253). The on-chain-side proposal here is the natural next layer above what the SDK currently emits, and the alignment story is genuinely tractable.

On the envelope-shape alignment question (your direct ask)

Yes, the MandateEnvelope EIP-712 typehash you describe is consumable with minor SDK-side changes. The current AP2 PaymentMandate that the SDK emits (and that #253 canonicalises via JCS) carries:

• The cart-mandate hash binding (off-chain commitment)
• The agent EIP-712 signature
• The principal EIP-712 signature (or EIP-1271 fall-through for smart accounts)
• Per-tx cap + cumulative cap + asset allowlist + expiry

This maps directly onto your on-chain MandateEnvelope structure. The only structural delta we'd need on the SDK side is:

1. A RefusalReason enum mapping — the typed revert path on RIVR is informationally richer than what the SDK currently emits for off-chain refusals. Worth lifting that enum into the SDK so off-chain and on-chain refusals share one taxonomy.
2. JCS canonicalisation of the constraint-chain inputs before EIP-712 encoding. This is the alignment point with x402-foundation/x402 #2322 — every payment-decision artefact in the wider ecosystem is converging on SHA-256(JCS(...)) lowercase hex. Your EIP-712 typehash is rail-specific, but the inputs to it should canonicalise under the same rule so cross-rail aggregators dedupe cleanly.

Cross-rail cumulative-cap counter

Picking up @Ectsang's point from #207 / their reply above: the cumulative counter living in contract storage is correct for the on-chain settlement layer but doesn't see spend on parallel rails. We hit this operationally on AlgoVoi's APM (Agentic Payment Mandate) implementation — a single human can have a mandate that spends across 7 chains, and the £-denominated cumulative cap is enforced at the platform balance layer, not per-chain.

Two patterns we've found work:

Pattern A — Platform-side authority of truth (what we do for APM): the cumulative counter lives in a single Postgres row keyed on (account_id, period_key); on-chain settlement is the side-effect, not the source of truth. Every payment-decision path holds an advisory lock on hashtext(mandate_id) to prevent TOCTOU. The on-chain transfer can fail or reorg, but the platform-side counter has already been decremented and is the audit-trail anchor.

Pattern B — On-chain authority of truth (what RIVR does): the counter is in contract storage, the canonical refusal happens on-chain, and the off-chain layer is advisory. Strong for single-chain merchants but breaks for cross-rail spend.

The right answer probably depends on whether the merchant is multi-rail or single-rail. Worth a spec note non-normatively that the constraint-envelope shape SHOULD remain rail-portable (your point) but the cumulative-cap source of truth is implementor-defined. A merchant on RIVR-only treats the contract as source of truth; an agentic-commerce platform spanning fiat + crypto rails treats their internal ledger as source of truth, with on-chain settlement events as second-confirmation receipts.

Alignment with the wider spec convergence

Today's spec activity across the agentic-payments ecosystem is converging on one canonicalisation rule (SHA-256(JCS(...)) lowercase hex) and one envelope grammar (*_pointer block + off_vm_anchor block + verification_recipe) across four evidence classes. See x402-foundation/x402#2322 (Compliance category + content_hash JCS rule) and #2334 (privacy_class).

Your MandateEnvelope typehash sits naturally inside the cryptographic-class evidence shape from #2334 (cryptographic × public-settlement cell): the typed RefusalReason revert is the on-chain-anchored proof-of-determination. Worth a coordination note in the FIDO submission that the constraint-envelope hash should compute the same way on AP2-emitting agents whether the rail is RIVR / x402-on-Base / Solana Pay / Algorand USDC — single canonicalisation rule, single verifier code path, multiple settlement rails.

On RIVR specifically

The full constraint chain enforced at the token contract (principal+agent EIP-712, EIP-1271 fall-through, caps, expiry, sanctions, KYA, Travel Rule) is exactly the policy surface we'd want for AP2 settlement compliance. The fact that you've shipped it on a live stablecoin gives this proposal real operational weight that a vapourware spec wouldn't carry.

One concrete question: the Travel Rule attestation at the token-contract layer — how does that compose with off-chain Travel Rule providers (TRP / OpenVASP) that operate before the on-chain settlement? Our compliance flow runs Travel Rule pre-settlement via off-chain attestation under EU TFR; running the same attestation as a token-contract refusal check is interesting but creates a second policy enforcement point. Worth thinking through whether they're complementary or whether one of them should be canonical.

Sample / SDK alignment plan

If you'd like a concrete next-step PR to align our existing AP2 samples with your envelope shape:

1. Update PR #218 (Algorand scenario) and #228 (Solana scenario) to emit the constraint-chain inputs in JCS-canonical form before signing, so the same canonical bytes hash under both the off-chain JCS_hash rule and the on-chain MandateEnvelope typehash
2. Lift RefusalReason enum into the shared schema so the AP2 sample for "refusal" returns the same enum value whether the refusal happened at the off-chain validator or the on-chain settler
3. Coordinate the typehash domain string with the FIDO core working group so an eth_signTypedData_v4 call hashes the same bytes the on-chain check verifies

Happy to do (1) and (2) in a follow-up PR if useful — alignment work is small and surfaces the cross-protocol consistency story. (3) is FIDO-side per your acknowledgement of repo scope.

PR reads ready for early-read feedback from our side; will follow the FIDO submission discussion when it surfaces.

[evidai]

Adding a data point from a production x402 implementation in case the comparison is useful.

We've been running LemonCake (https://lemoncake.xyz) as an x402 gateway since early 2026. Some notes on the AP2/x402 composition question:

Mandate-equivalent at our layer is the Buyer Key:

• bk_… is long-lived (hashed at rest), carries hard caps (per_mint_max, daily_max, monthly_max), and is scoped to one seller. It's effectively a pre-authorized mandate — "agent may spend up to X for this seller without further human approval".
• AP2-style mandate verification would slot in at mint-time (when the gateway issues the Pay Token JWT), not at request-time. The gateway already commits the charge before the JWT issues, so a mandate check is just one more pre-condition on lc_agent_charges.

Settlement side:

• Stripe off-session adapter (USD): server-side PaymentIntent with idempotency via charge_ref (unique column). Direct Charge + 3% application_fee.
• USDC-on-Base: agent's own key as the transfer subject (custody-free; FSA-cleared).
• Either rail returns the same Pay Token JWT shape — agents don't care which one settled.

Receipts: charges land in lc_agent_charges with the charge_ref as the canonical identifier; we surface them on the public /api/<slug> page and via the agent's wallet endpoint. AP2's settlement-side mandate binding would map cleanly onto that charge_ref.

Production: $1 off-session card charge through the full loop verified 2026-06-02.
30-second demo (no signup): https://lemoncake.xyz/demo

(Disclosure: I'm working on LemonCake — sharing as a reference implementation that already runs both x402 and Stripe Direct Charge in production, not pitching.)

[chopmob-cloud]

Following on from @evidai's LemonCake data point — adding the crypto-rail side.

AlgoVoi runs the same cross-chain cap problem from the other direction: crypto settlement across 8 chains (Base, Algorand, Solana, Stellar, Hedera, Tempo, VOI, ARC testnet). The problem @Ectsang identified — "cumulative cap counter lives in contract storage, only sees spend on that chain" — is real and we hit it directly.

Our fix is gateway-level, not chain-level: the spend cap lives in the agent session JWT, not in any on-chain counter. Settlement attestations (SETTLED / PENDING_FINALITY / REVERSED) flow back to the same session and decrement the same cap regardless of which chain settled. Cross-chain audit trail: prev_hash + content_hash links all settlement events for a session, so a verifier can reconstruct cumulative spend across chains from the audit chain alone.

The settled_payment_ref field ties each settlement back to the original mandate by content address — so the on-chain side proposal here slots in as a verifiable anchor for what the gateway-level cap is tracking.

AlgoVoi (chopmob-cloud) — docs.algovoi.co.uk/settlement-attestation

[Ram9199]

I am collecting real-world incidents around agent mandates, payments, and high-risk tool authorization.

Was settlement-side mandate binding driven by actual incidents, near misses, or customer requirements where an agent payment/action could not be tied to a specific mandate and policy? What changed afterward - signed mandates, proof-of-possession, audit logs, manual approval, split credentials, or no change?

Not asking about any product. I am trying to understand whether agent authorization/provenance pain is already operational in commerce/payment flows.

[chopmob-cloud]

@Ram9199 Honest answer: design driven, not a customer incident or an external near miss. The binding came out of our own cross-chain settlement work early in AlgoVoi, before it was ever a problem reported from the field.

The concrete thing that surfaced it: a cumulative spend cap held in per-chain contract storage only ever sees spend on its own chain, so an agent settling across several chains can stay under the cap on each one while exceeding it in aggregate. We hit that directly while building multi-chain settlement.

So the design we evolved keeps the cap off-chain. The cap value rides the agent session token rather than any single chain's contract storage, and each successful settlement, on whichever rail it lands, records spend against that one per-session counter, so the accounting is chain agnostic by construction. Settlement outcomes are attested as SETTLED, PENDING_FINALITY, or REVERSED, and the records are hash chained, each row carrying prev_hash and content_hash, so a verifier can reconstruct cumulative spend across chains from the audit chain alone. The result was not signed mandates or manual approval added after the fact, but a cap location and accounting design we chose up front, because the per-chain version could not express a cross-chain limit.