> ## Documentation Index
> Fetch the complete documentation index at: https://docs.x402r.org/llms.txt
> Use this file to discover all available pages before exploring further.

# Overview

> Introduction to x402r smart contracts and their relationship to commerce-payments

## What is x402r

x402r builds on the canonical [Commerce Payments Protocol](https://github.com/base/commerce-payments) 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](https://github.com/BackTrackCo/x402r-contracts#architecture) in the x402r-contracts repository.

## Commerce Payments (Base Layer)

The audited [Commerce Payments Protocol](https://github.com/base/commerce-payments) 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:**

```solidity theme={null}
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

| Feature                | Commerce Payments    | x402r                                                             |
| ---------------------- | -------------------- | ----------------------------------------------------------------- |
| **Refunds**            | Manual void/reclaim  | Structured refund requests with configurable approval             |
| **Escrow Period**      | Not enforced         | Configurable time-lock before capture                             |
| **Dispute Resolution** | Not built-in         | Arbiter workflow via conditions, signatures, and evidence         |
| **Authorization**      | Operator-based only  | Pluggable conditions (access, time, signature, combinators)       |
| **Freeze Mechanism**   | Not available        | Configurable freeze during escrow period                          |
| **Deployment**         | Direct deployment    | Factory pattern with universal CREATE2 (same address every chain) |
| **Fees**               | Not enforced         | Additive protocol + operator fees with 7-day timelock             |
| **Multi-chain**        | Per-chain deployment | Universal 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

<Accordion title="Immutability by Default">
  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.
</Accordion>

<Accordion title="Gas Optimization">
  * 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
</Accordion>

<Accordion title="Composability">
  * Conditions compose with And/Or/Not logic
  * Operators can share condition implementations
  * Factories enable on-demand instance deployment
  * Stateless conditions work across many operators
</Accordion>

<Accordion title="Security First">
  * Reentrancy guards on all state changes
  * 7-day timelock on protocol fee changes
  * Two-step ownership transfers
  * Detailed event logging for monitoring
</Accordion>

## Architecture Overview

For a detailed view of how all contracts interact, see [Architecture](/contracts/architecture).

To understand the core operator, see [PaymentOperator](/contracts/payment-operator). For supporting contracts, see [Periphery](/contracts/periphery/overview).

For factory deployment patterns, see [Factories](/contracts/factories).

## Next Steps

<CardGroup cols={2}>
  <Card title="Architecture" icon="diagram-project" href="/contracts/architecture">
    View system architecture diagrams and payment flows.
  </Card>

  <Card title="PaymentOperator" icon="file-contract" href="/contracts/payment-operator">
    Learn about the core operator contract.
  </Card>

  <Card title="Deploy an Operator" icon="rocket" href="/sdk/deploy-operator">
    Deploy a PaymentOperator using the SDK.
  </Card>

  <Card title="SDK Overview" icon="cube" href="/sdk/overview">
    Build with the TypeScript SDK.
  </Card>
</CardGroup>