Skip to main content

​
What is x402r

x402r builds on the canonical Commerce Payments Protocol to add dispute resolution, escrow periods, and refund capabilities. For the protocol-level introduction and the payer/merchant/arbiter model, see What is x402r. This page covers the contract layer.

​
Architecture Layers

See the system architecture diagrams in the x402r-contracts repository.

​
Commerce Payments (Base Layer)

The audited Commerce Payments Protocol provides the foundational payment infrastructure. x402r uses the canonical contracts directly (no fork) at their universal CREATE2 addresses.

​
AuthCaptureEscrow

Core escrow contract for holding ERC-20 tokens during payments. Features:
  • Authorization-based deposits (no direct transfers)
  • Per-payment state queried via paymentState(hash) → (hasCollected, capturableAmount, ...)
  • Void/reclaim for failed authorizations
  • CaptureAuthorizer-based access control
Key Methods: 
authorize(paymentInfo, amount, tokenCollector, collectorData)
charge(paymentInfo, amount, tokenCollector, collectorData)
capture(paymentInfo, amount, data)
void(paymentInfo, data)
reclaim(paymentInfo, data)

​
ERC3009PaymentCollector

Payment collection with ERC-3009 transferWithAuthorization support. Features:
  • Gasless payments via meta-transactions
  • Nonce-based replay protection
  • Deadline-based expiry
  • Integration with Multicall3 for batching

​
TokenStore

Safe token storage and transfer utilities. Features:
  • Reentrancy-safe transfers
  • Balance tracking
  • Integration with OpenZeppelin SafeERC20

​
What x402r Adds

x402r extends commerce-payments with flexible payment capabilities:

​
1. Generic Payment Operator

PaymentOperator - Flexible payment operator with pluggable conditions RefundRequest - Structured refund request workflow Key additions:
  • Fee recipient for protocol and operator fee distribution
  • Configurable authorization via conditions (not hardcoded roles)
  • Refund request states: Pending → Approved/Denied/Cancelled
  • Voids (during escrow period)
  • Refunds (after capture)
  • Support for marketplace, subscription, streaming, and custom flows

​
2. Pluggable Condition System

Conditions (ICondition) - Authorization checks before actions Hooks (IHook) - State updates after actions 10-slot configuration per operator:
  • 5 condition slots (before action): authorize, charge, capture, void, refund
  • 5 hook slots (after action): state tracking for each action
Benefits:
  • Configure operator behavior without redeploying
  • Compose complex authorization logic with combinators
  • Reuse condition contracts across operators
  • Gas-efficient with shared singletons

​
3. Time-Based Escrow & Freeze Policies

EscrowPeriod - Combined hook and condition that tracks authorization time and enforces escrow period Freeze - Standalone condition that blocks capture while a freeze remains active (with configurable freeze/unfreeze authorization) Key features:
  • Configurable escrow periods (for example, 7 days or 14 days)
  • Payer-initiated freezes to stop suspicious releases
  • Time-limited freeze durations (for example, 3 days)
  • MEV protection via private mempool support
  • Composable via AndCondition([escrowPeriod, freeze])

​
4. Arbiter & Evidence System

RefundRequestEvidence - On-chain evidence submission with IPFS CIDs and arbiter EIP-712 signature approval

​
5. Factory Pattern

PaymentOperatorFactory - Deploys operators with deterministic CREATE2 addresses EscrowPeriodFactory - Deploys EscrowPeriod contracts FreezeFactory - Deploys Freeze condition contracts Plus factories for: StaticFeeCalculator, StaticAddressCondition, AndCondition, OrCondition, NotCondition, HookCombinator. All factories use universal CREATE2 addresses: same address on every supported chain. Benefits:
  • Predictable addresses for off-chain address generation
  • Cross-chain address consistency (same config = same address on every chain)
  • Shared configuration reduces deployment costs
  • Idempotent deployments (same config = same address)
  • Owner controls all deployed instances via factory

​
Key Differences from Commerce Payments

FeatureCommerce Paymentsx402r
RefundsManual void/reclaimStructured refund requests with configurable approval
Escrow PeriodNot enforcedConfigurable time-lock before capture
Dispute ResolutionNot built-inArbiter workflow via conditions, signatures, and evidence
AuthorizationOperator-based onlyPluggable conditions (access, time, signature, combinators)
Freeze MechanismNot availableConfigurable freeze during escrow period
DeploymentDirect deploymentFactory pattern with universal CREATE2 (same address every chain)
FeesNot enforcedAdditive protocol + operator fees with 7-day timelock
Multi-chainPer-chain deploymentUniversal CREATE2 addresses on supported chains

​
Use Cases

​
Commerce Payments (Base) Suitable For:

  • Simple payment escrow
  • Trusted operator scenarios
  • No refund requirements
  • Direct integrations

​
x402r (Extension) Suitable For:

  • Marketplaces - Buyer protection with time-based escrow and disputes
  • Subscriptions - Time-limited authorizations with charge capability
  • Streaming - Time-proportional payments with custom conditions
  • Grants/DAO - Multisig-controlled releases and refunds
  • Escrow Services - Professional escrow with freeze protection
  • API Payments - Service provider controlled charge flows

​
Design Principles

Most contracts are immutable to prevent rug pulls and ensure trustlessness:
  • PaymentOperator - Cannot pause or upgrade
  • EscrowPeriod - Cannot change escrow period
  • Freeze - Cannot change freeze rules after deployment
Protocol fee configuration is mutable via ProtocolFeeConfig (with 7-day timelock). Operator fees are immutable.
  • Condition singletons deployed once, reused everywhere
  • CREATE2 for deterministic addresses (no registry lookups)
  • Minimal storage in operators (conditions are stateless)
  • Hook pattern separates state from logic
  • Conditions compose with And/Or/Not logic
  • Operators can share condition implementations
  • Factories enable on-demand instance deployment
  • Stateless conditions work across many operators
  • Reentrancy guards on all state changes
  • 7-day timelock on protocol fee changes
  • Two-step ownership transfers
  • Detailed event logging for monitoring

​
Architecture Overview

For a detailed view of how all contracts interact, see Architecture. To understand the core operator, see PaymentOperator. For supporting contracts, see Periphery. For factory deployment patterns, see Factories.

​
Next Steps

Architecture

View system architecture diagrams and payment flows.

PaymentOperator

Learn about the core operator contract.

Deploy an Operator

Deploy a PaymentOperator using the SDK.

SDK Overview

Build with the TypeScript SDK.