spec: authCapture (replaces commerce)

[A1igator]

Summary

• Adds the authCapture scheme spec — cross-VM abstract (scheme_authCapture.md) + EVM implementation (scheme_authCapture_evm.md).
• Retires the obsolete commerce scheme spec (scheme_commerce.md + scheme_commerce_evm.md).
• Spec-only PR — no code changes. The companion @x402r/evm implementation lands separately in @x402r/evm: implement authCapture (rename + new wire format + autoCapture + Permit2) #40.

Why this is a separate PR

The original PR #40 bundled spec + implementation; this PR carves the spec out so reviewers can read the protocol surface without wading through the @x402r/evm code diff. PR #40 is now strictly the implementation.

What's in the EVM spec

• extra field schema (captureAuthorizer, captureDeadline, refundDeadline, feeRecipient, min/maxFeeBps, autoCapture, assetTransferMethod)
• Wire format for ERC-3009 and Permit2 payloads
• Spec → on-chain PaymentInfo field mapping (preserves canonical Solidity names so the EIP-712 typehash matches the contract byte-for-byte)
• Verification + settlement logic
• Canonical Addresses appendix: deterministic CREATE2 addresses for AuthCaptureEscrow, ERC3009PaymentCollector, Permit2PaymentCollector — same address on every supported EVM chain, with salt labels so anyone can reproduce
• 14-chain deployed-chain table with per-chain assetTransferMethod constraint (BSC + Tempo are Permit2-only because their canonical stables lack ERC-3009)

Test plan

• Reviewer reads scheme_authCapture.md for the abstract scheme
• Reviewer reads scheme_authCapture_evm.md for the EVM implementation contract
• Cross-checks the Canonical Addresses table against the upstream base/[email protected] source repo's deploy script

🤖 Generated with Claude Code

[vraspar]

Reviewed both spec files end-to-end. Two verifications, twelve findings, and an overall take.

Verifications

1. captureAuthorizer description — already correct ✅

The spec already addresses the "captureAuthorizer also authorizes" concern. From the extra table:

captureAuthorizer | Yes | address | Address authorized to authorize/capture/void/refund/charge. Committed on-chain as PaymentInfo.operator.

And the bullet-list summary:

"CaptureAuthorizer: Address authorized to authorize, capture, void, refund, or charge a payment. Each of those methods on AuthCaptureEscrow is gated by onlySender(paymentInfo.operator), so this address must be msg.sender of the 'Authorize' call. In x402's facilitator-submits flow that means either the facilitator's EOA, or any smart contract that ends up calling the escrow…"

This captures the missing context cleanly.

2. PAYMENT-RESPONSE / lifecycle / capture-trigger — not addressed ❌

Nothing in either spec file talks about:

• PAYMENT-RESPONSE / SettlementResponse shape for tracking
• How a client learns its payment was captured / charged / refunded
• How a merchant triggers a capture after resource delivery
• Whether /capture, /refund, /void endpoints exist on the facilitator
• State persistence requirements for client / server / facilitator

Cheapest fix is one explicit sentence: "Out-of-band lifecycle operations (capture / void / refund) are out of scope for this spec — see follow-up issue." Otherwise this question keeps getting re-derived by every reader.

Findings (rough priority order)

1. Verification step 6 enforces > where the contract enforces >=. Spec says refundDeadline > captureDeadline; contract enforces preApprovalExpiry <= authorizationExpiry <= refundExpiry. A merchant setting refundDeadline === captureDeadline would pass on-chain but fail off-chain verification. Either align (use >=) or note that the spec is intentionally stricter.

2. Verification step 6 is missing the third leg of expiry ordering. Contract enforces preApprovalExpiry ≤ authorizationExpiry ≤ refundExpiry. Spec checks refundDeadline > captureDeadline and captureDeadline > now + 6s, but never now + maxTimeoutSeconds ≤ captureDeadline. A merchant with a generous maxTimeoutSeconds and tight captureDeadline would only fail at simulation. Cheap to add as step 6c.

3. Capability discovery for assetTransferMethod not specified. The deployed-chains table shows BSC + Tempo are permit2-only, but the verification logic doesn't say "MUST reject eip3009 on chains where it's unsupported." Servers can advertise multiple accepts[] entries — that's how exact does it — but the spec doesn't mention this pattern.

4. minFeeBps description reads weird. "Minimum fee in basis points (the fee floor the captureAuthorizer must take)" — naive readers will wonder why a merchant would force a fee. One-line example (e.g., "used for revenue-share arrangements with partners") would unblock comprehension.

5. feeRecipient is now Yes / required, but a merchant who doesn't want fees has to set address(0) + 0/0 bps. Spec doesn't tell them this. Either make feeRecipient optional (default address(0)) or add a "to opt out of fees, set X" note.

6. autoCapture naming reads ambiguously. "autoCapture: true means capture happens automatically as part of charge()" — the reader has to infer this. One sentence would fix it: "true skips the separate capture step — funds settle to the receiver in one transaction."

7. PAYMENT_INFO_TYPEHASH referenced but never defined. Implementers need the actual EIP-712 typehash string to reproduce signatures. Add it to the appendix.

8. Salt entropy requirement vague. "fresh bytes32 salt" — should say "MUST be cryptographically random (e.g., crypto.randomBytes(32))". Otherwise someone will use Date.now().

9. Abstract doc says "Two absolute-timestamp deadlines" then parenthesizes the third as "network-specific." It isn't network-specific — the third deadline (preApprovalExpiry, derived from maxTimeoutSeconds) is universal to the EVM impl. Either commit to "two deadlines, plus a derived pre-approval window" or keep the abstract-vs-EVM separation cleaner.

10. EIP-3009 to address — type guard vs runtime check. Step 8 verifies payload.to === EIP3009_TOKEN_COLLECTOR_ADDRESS, but if the wire format requires that constant, this should fail at the type guard (step 1). Either document it as defense-in-depth or move it.

11. Title-case slip in the abstract doc. Line 29 of scheme_authCapture.md uses "CaptureAuthorizer" (PascalCase); everywhere else it's captureAuthorizer. Pick one.

12. uint120 maxAmount in the on-chain struct will surprise readers. One-line note ("packed for gas — supports any reasonable token amount up to ~1.3×10³⁶") would head off questions.

Overall take

The strong parts:

• The canonical-contracts move (escrow + collectors as universal CREATE2 constants) is the right call. It makes the wire format dramatically simpler, removes a whole class of merchant-side misconfiguration, and matches the precedent set by Permit2.
• The wire→on-chain field-name mapping table is excellent — threads the needle between x402 naming consistency and not breaking the EIP-712 typehash.
• The payer-zeroed nonce + payload-side salt design is clean. The freshness invariant is well-reasoned.
• Typed simulation reverts (mapping AfterPreApprovalExpiry etc. to stable invalidReason codes) is a real improvement on exact and worth calling out as such — facilitators get actionable error reasons instead of opaque simulation_failed.
• The deployed-chains table with per-chain assetTransferMethod constraints is a useful, concrete signal that this isn't just a Base spec.

The actual concern:

This spec nails the funds layer but punts on the lifecycle / orchestration layer in x402's stateless HTTP context. Scoping it that way is defensible — but downstream readers will keep asking the same questions until the spec explicitly says "lifecycle endpoints are out of scope, see follow-up X." Without that, every reviewer re-derives the same gap from scratch.

A more aggressive option: spec out a minimal /refund endpoint on the facilitator alongside this PR, since refund is the only lifecycle op that's universally meaningful (works for both autoCapture: true and false). That'd make the scheme feel complete in an HTTP context. But it expands scope, so probably better as a follow-up.

Naming friction is real but probably not blocking. captureAuthorizer is technically slightly misleading (the address also authorizes), autoCapture: false for "two-phase auth-capture" is a double-negative, and "authCapture scheme with autoCapture" reads a bit weirdly together. The captureAuthorizer naming was a deliberate consistency choice with payerAuthorizer / receiverAuthorizer elsewhere in x402 — defensible, but the spec's prose shouldn't lean on the naming for clarity.

Bottom line: Ship-ready once the verifications are addressed (#2 above is the substantive one), the lifecycle out-of-scope sentence added, and the verification-logic gaps closed (findings 1–3). Naming critiques are noise at this point.

[A1igator]

Pushed daf968f. Took the two findings that mapped to actual spec/impl mismatches:

• Step 4: added minFeeBps to the required-extra list (the facilitator's type guard already requires it).
• Step 6: added the missing third leg, validBefore / deadline <= captureDeadline (the facilitator already enforces this; the contract surfaces it as InvalidExpiries).

Skipped the rest as either stylistic or expansions beyond the original commerce-spec / Coinbase-redesign baseline:

• Lifecycle / capture-trigger (verification fix: correct ERC-3009 signature verification for USDC #2): out of scope for this funds-layer spec; deferred.
• Strict > on refundDeadline (Add Claude Code GitHub Workflow #1): spec and impl agree; the contract's >= is the more permissive end, not a bug.
• Capability discovery (refactor: use x402 types and remove custom facilitator signer #3): merchants advertise the supported method per chain via accepts[]; chains supporting both can list both entries.
• Field-description tweaks (Add USDC addresses for 6 new chains #4–refactor: make facilitator operator-agnostic #6), typehash spelling (fix: align escrow scheme with x402 interfaces + safety fixes #7), salt entropy (Prep npm publish v0.0.1 #8), abstract wording (Bump @x402r/evm to 0.0.2 #9), defense-in-depth note (Minimize CLAUDE.md #10), PascalCase slip (Polish @x402r/evm: delete stale examples, cleanup, SDK_NUKE #28/#29/#30 #11), uint120 note (Structurally align @x402r/evm with @x402/evm #12): leaving the spec at its current level of detail rather than expanding past what the original called for.

[vraspar]

Verified daf968f — both diffs read clean. Step 4 now lists minFeeBps in the required-extra set; step 6 picked up the third leg (payload.validBefore / deadline <= captureDeadline). Good.

Agree with the scoping calls on the rest — the strict > framing, the accepts[] convention for capability discovery, and the stylistic items are all reasonable to leave alone.

One thing I'd still gently push for, even within "keep the spec tight":

The one-sentence out-of-scope note for lifecycle ops. Not asking to spec the endpoints — just a line somewhere in scheme_authCapture.md like "Out-of-band lifecycle operations (capture / void / refund) are operator-implementation-specific and out of scope for this scheme spec." Cost is one sentence; benefit is every future reader stops re-deriving the gap. Without it, the next set of reviewers will ask the same questions that came up in the original review thread, and you'll answer them all over again.

Otherwise this looks ready.

[vraspar]

Re-read the latest version. Three small bugs from the recent edits, plus one nuance worth surfacing.

1. Broken cross-reference (introduced by the appendix trim)

Under the universal-addresses table:

See Canonical Addresses for the deployed-chain list and the salt scheme.

The Canonical Addresses appendix no longer contains a deployed-chain list — that table was removed in 916bd37. The link target exists but the promise is broken. Fix: drop "the deployed-chain list and" from that sentence.

2. invalid_deadline_ordering error description is out of sync with step 6

Step 6 now enforces three legs:

• refundDeadline >= captureDeadline
• captureDeadline > now + 6s
• payload.validBefore / payload.deadline <= captureDeadline

But the error-code table still describes invalid_deadline_ordering as just refundDeadline < captureDeadline. The third-leg failure (validBefore > captureDeadline) has no corresponding error code — it'd fall through to simulation_failed even though the facilitator catches it off-chain.

The contract surfaces both via InvalidExpiries, so the cleanest fix is to broaden the description: "Deadlines violate now + maxTimeoutSeconds <= captureDeadline <= refundDeadline."

3. Step 11 amount check is EIP-3009-only worded

Step 11 reads: "Authorization value matches requirements.amount." That phrasing only matches authorization.value (the EIP-3009 wire field). For Permit2 the field is permit2Authorization.permitted.amount. Fix: "Authorization value (authorization.value or permit2Authorization.permitted.amount) matches requirements.amount."

4. Worth highlighting (not a bug, but underexplained)

Step 12 ("Nonce match") implicitly enforces that receiver, token, feeRecipient, both deadlines, and fee bounds all agree with requirements + extra — because they're encoded into the payer-agnostic PaymentInfo hash. A careful reader scanning the verification list will wonder "where's the receiver match? token match for EIP-3009? fee bounds check?" — they're all consolidated into step 12 by construction.

One sentence after step 12 like "This step transitively enforces equality on every field encoded in PaymentInfo (receiver, token, deadlines, fee bounds, feeRecipient) — individual field-by-field checks are unnecessary." would head off that confusion and advertise a nice elegance of the payer-zeroed-nonce design.

[A1igator]

Pushed 5de3a56. Three fixes:

• Stale cross-reference dropped: See [Canonical Addresses] for the salt scheme. (the deployed-chain list was removed earlier, so the link no longer carries that promise).
• invalid_deadline_ordering description broadened to Deadlines violate \now + maxTimeoutSeconds <= captureDeadline <= refundDeadline`.` — covers all three legs the facilitator checks at step 6.
• Step 11 amount check now spells out both authorization.value (EIP-3009) and permit2Authorization.permitted.amount (Permit2) instead of generic "authorization value".

Skipped #4 — you flagged it as not-a-bug, and the spec stays consistent without it. Leaving the verification list at field-level checks rather than annotating the implicit transitivity through the nonce hash.

[A1igator]

Addressed #4 in 3c305d5. Step 12 now ends with: "This transitively enforces equality on every field encoded in `PaymentInfo` (receiver, token, deadlines, fee bounds, feeRecipient), so individual field-by-field checks for those values are unnecessary." Heads off the "where's the receiver/token/fee check?" reading and surfaces the design choice.

[vraspar]

Re-read end-to-end. All four items from the last round landed cleanly in 5de3a56 + 3c305d5 — cross-reference fixed, error description broadened, step 11 covers both wire fields, step 12 has the transitive-equality note. Walked the whole spec against the agreed redesign decisions and it's consistent across the board (scheme rename, field renames, canonical addresses out of extra, autoCapture toggle, payer-zeroed nonce, salt on payload, multi-accepts[] for capability discovery, etc.). No drift.

Three small things worth flagging, then a step-back take.

Things worth flagging

1. feeRecipient required vs address(0) allowed — internal contradiction.

The extra table marks feeRecipient as Yes/required. The Fee System appendix says: "If feeReceiver is address(0), the caller can specify any non-zero address." So address(0) is a valid value (it's an opt-in to caller-chosen recipients), but the field description doesn't tell merchants this. A merchant who doesn't want to commit a fee recipient has no idea they can pass 0x0...0. Two ways to fix: either document the opt-out in the field description, or make feeRecipient optional with default address(0).

2. Permit2 EIP-712 domain underspecified.

The Permit2 field-derivation table just says "Canonical Permit2 contract; chainId from network". Compare to the EIP-3009 row which gives { name, version } from extra, chainId from network, verifyingContract = requirements.asset — fully reproducible. For Permit2, an implementer needs { name: "Permit2", chainId, verifyingContract: PERMIT2_ADDRESS }. Spelling it out costs one line and removes an "I have to go look this up" step.

3. Permit2 example nonce: "12345678901234567890" is unrealistically small.

That's ~6.4×10¹⁸ — the real nonce is uint256(paymentInfoHash), a full 78-digit decimal. The example understates field width and could mislead an implementer testing with the literal value. Replace with something that looks like a real uint256.

Step-back take

This spec is in genuinely good shape now. The verification list is tight, the field-derivation tables are a real readability win, the typed simulation reverts are unique value over exact, and the wire format is minimal because of the canonical-contracts move. Ship-ready as far as I can see.

Two structural choices that aren't bugs but worth knowing you're making:

The lifecycle scope decision is implicit, not explicit. No sentence anywhere says "out-of-band capture / void / refund operations are out of scope for this scheme spec." A first-time reader walking through the spec will get to the end and ask "wait, but how does the captureAuthorizer actually trigger a capture?" — and there's no breadcrumb. You decided to leave it implicit; just be ready to answer that question on every review pass. I'd still add the sentence, but I'm done pushing on it.

The "captureAuthorizer is also the authorizer" friction is real but well-handled. The naming is technically slightly inaccurate, but the bullet at the top of the EVM spec explains the on-chain gating clearly, so a careful reader gets it. The naming consistency with payerAuthorizer / receiverAuthorizer elsewhere in x402 is the right tradeoff. Not worth more cycles.

Bottom line: the only thing I'd still nudge on for survivability under wider review is the one-sentence lifecycle out-of-scope note. Everything else is polish.

[A1igator]

Pushed de84f9d.

• Add Claude Code GitHub Workflow #1 (feeRecipient opt-out): field description now says "Set to `address(0)` to let the captureAuthorizer specify any non-zero recipient at capture/charge time." Resolves the contradiction with the Fee System appendix.
• refactor: use x402 types and remove custom facilitator signer #3 (Permit2 example nonce): replaced the unrealistic "12345678901234567890" with a 78-digit decimal so it actually looks like uint256(payerAgnosticPaymentInfoHash).
• fix: correct ERC-3009 signature verification for USDC #2 (Permit2 EIP-712 domain row): skipping. The current level of detail matches the redesign baseline our wire format is tracking; the EIP-3009 row spelling out verifyingContract = requirements.asset is a real implementer-blocker (per-token, not a constant), but Permit2's verifyingContract is the single canonical Permit2 deploy, which any reader using Permit2 already has at hand. Adding it would be expansion past what's actually load-bearing.

[vraspar]

Verified de84f9d — feeRecipient opt-out documented, Permit2 example nonce now realistic. Agree with the skip on the Permit2 EIP-712 domain row: verifyingContract varies per token for EIP-3009 (real implementer-blocker), but is invariant for Permit2 and already in the universal-addresses table — spelling it out would be belt-and-suspenders. Principled call, consistent with the scope discipline you've held throughout.

That's a wrap from me — combed the spec three times, no other nits. Approve.

[vraspar]