Skip to main content

​
What is x402r?

x402r is a smart contract extension for HTTP-native refundable payments. It builds on commerce-payments to add dispute resolution, escrow periods, and flexible refund capabilities.

​
Architecture Layers

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

​
Commerce Payments (Base Layer)

Commerce Payments provides the foundational payment infrastructure.
x402r uses a fork of commerce-payments that adds partial void support for handling partially completed orders and partial refunds.

​
AuthCaptureEscrow

Core escrow contract for holding ERC-20 tokens during payments. Features:
  • Authorization-based deposits (no direct transfers)
  • Payment state machine: NonExistent → InEscrow → Released → Settled
  • Void/reclaim for failed authorizations
  • Partial void support (x402r addition) - Refund partial amounts during escrow
  • Operator-based access control
Key Methods: 
authorize(paymentId, payer, receiver, amount, token, operator)
charge(paymentId, amount)
release(paymentId)
void(paymentId)
reclaim(paymentId, receiver, amount)

​
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
  • In-escrow refunds (during escrow period)
  • Post-escrow refunds (after release)
  • Support for marketplace, subscription, streaming, and custom flows

​
2. Pluggable Condition System

Conditions (ICondition) - Authorization checks before actions Recorders (IRecorder) - State updates after actions 10-slot configuration per operator:
  • 5 condition slots (before action): authorize, charge, release, refundInEscrow, refundPostEscrow
  • 5 recorder 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 recorder and condition that tracks authorization time and enforces escrow period Freeze - Standalone condition that blocks release when payment is frozen (with configurable freeze/unfreeze authorization) Key features:
  • Configurable escrow periods (e.g., 7 days, 14 days)
  • Payer-initiated freezes to stop suspicious releases
  • Time-limited freeze durations (e.g., 3 days)
  • MEV protection via private mempool support
  • Composable via AndCondition([escrowPeriod, freeze])

​
4. Factory Pattern

PaymentOperatorFactory - Deploys operators with deterministic CREATE2 addresses EscrowPeriodFactory - Deploys EscrowPeriod contracts FreezeFactory - Deploys Freeze condition contracts Benefits:
  • Predictable addresses for off-chain address generation
  • 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 release
Dispute ResolutionNot built-inOptional arbiter workflow via conditions
AuthorizationOperator-based onlyPluggable conditions (access, time, combinators)
Freeze MechanismNot availableConfigurable freeze during escrow period
DeploymentDirect deploymentFactory pattern with CREATE2
FeesNot enforcedConfigurable protocol and operator fees

​
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 modify 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)
  • Recorder pattern separates state from logic
  • Conditions can be combined with And/Or/Not logic
  • Operators can share condition implementations
  • Factories enable on-demand instance deployment
  • Stateless conditions work across multiple operators
  • Reentrancy guards on all state changes
  • 7-day timelock on protocol fee changes
  • Two-step ownership transfers
  • Comprehensive event logging for monitoring

​
Architecture Overview

For a detailed view of how all contracts interact, see Architecture. To understand individual contracts, see Core Contracts. For factory deployment patterns, see Factories.

​
Next Steps

Architecture

View system architecture diagrams and payment flows.

Core Contracts

Learn about PaymentOperator, RefundRequest, and other core contracts.

Deploy an Operator

Deploy a PaymentOperator using the SDK.

SDK Overview

Build with the TypeScript SDK.