Update protocol and contracts docs to match current state (#14)

## Summary

- **Escrow scheme spec rewritten** to align with [coinbase/x402 PR
#1425](https://github.com/coinbase/x402/pull/1425) and [issue
#1011](https://github.com/coinbase/x402/issues/1011) — adds settlement
methods (authorize/charge), nonce derivation, 11-step verification
logic, settlement logic, error codes, PaymentInfo struct with all
fields, and expiry ordering
- **All contract addresses updated** to unified CREATE3 addresses (same
on every chain)
- **Missing contracts added**: ArbiterRegistry, RefundRequestEvidence,
ReceiverRefundCollector, SignatureCondition/SignatureRefundRequest
factories, and all condition/combinator factories
- **Supported chains expanded** from 2 (Base + Base Sepolia) to 11
chains
- **PaymentInfo struct fixed** in architecture docs (was missing
`preApprovalExpiry`, `refundExpiry`, `salt`, had wrong field ordering)
- **Payment flow diagrams fixed** to route through operator (not escrow
directly)
- **Roadmap updated** with escrow scheme spec submission status and
multi-chain deployment

## Test plan

- [ ] Preview with `npx mint dev` and verify all pages render
- [ ] Verify all contract addresses match `@x402r/core` config
- [ ] Verify escrow scheme spec matches PR #1425 content
- [ ] Check all internal links work

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-authored-by: Claude Opus 4.6 (1M context) <[email protected]>

Author: A1igator

contracts/architecture.mdx

@@ -158,15 +158,18 @@ This example shows marketplace configuration. For subscriptions, you might use `
 // PaymentInfo is from base commerce-payments (AuthCaptureEscrow)
 // Passed as calldata to operator methods - not stored in operator
 struct PaymentInfo {
-    address payer;
-    address receiver;
     address operator;           // The PaymentOperator address
-    uint256 amount;
-    address token;
-    uint48 authorizationExpiry; // When authorization expires
-    uint16 minFeeBps;           // Minimum fee in basis points
-    uint16 maxFeeBps;           // Maximum fee in basis points
+    address payer;              // Client wallet
+    address receiver;           // Fund recipient
+    address token;              // ERC-20 token address
+    uint120 maxAmount;          // Maximum authorized amount
+    uint48  preApprovalExpiry;  // ERC-3009 validBefore / pre-approval deadline
+    uint48  authorizationExpiry;// Capture deadline (authorize path only)
+    uint48  refundExpiry;       // Refund request deadline
+    uint16  minFeeBps;          // Minimum fee in basis points
+    uint16  maxFeeBps;          // Maximum fee in basis points
     address feeReceiver;        // Who receives fees (operator itself)
+    uint256 salt;               // Client-provided entropy
 }
 ```
 
@@ -306,8 +309,8 @@ These events enable off-chain monitoring and indexing.
 ## Next Steps
 
 <CardGroup cols={2}>
-  <Card title="Core Contracts" icon="file-contract" href="/contracts/core-contracts">
-    Learn about individual contract implementations.
+  <Card title="PaymentOperator" icon="file-contract" href="/contracts/payment-operator">
+    Learn about the core operator contract.
   </Card>
   <Card title="Conditions" icon="filter" href="/contracts/conditions/overview">
     Explore the condition system and combinators.

contracts/examples.mdx

@@ -851,7 +851,7 @@ Keep records of deployed configurations:
 ## Next Steps
 
 <CardGroup cols={2}>
-  <Card title="Core Contracts" icon="file-contract" href="/contracts/core-contracts">
+  <Card title="PaymentOperator" icon="file-contract" href="/contracts/payment-operator">
     Review contract methods and security features.
   </Card>
   <Card title="Conditions" icon="filter" href="/contracts/conditions/overview">

contracts/factories.mdx

@@ -46,9 +46,9 @@ Deploys PaymentOperator instances with deterministic addresses.
 
 ### Contract Address
 
-**Base Sepolia:** `0xe01CEd771A30A23a7A4C9c1db604C74D4Dc4ebe8`
+All factories use unified CREATE3 addresses (same on every chain).
 
-**Base Mainnet:** `0xA50F51254E8B08899EdB76Bd24b4DC6A61ba7dE7`
+**PaymentOperatorFactory:** `0x4D9BC2Ba2D0d9AFb6B63E3afBbfC95143E6E8Da9`
 
 ### Configuration Structure
 
@@ -208,9 +208,7 @@ Deploys `EscrowPeriod` contracts - combined recorder and condition for time-base
 
 ### Contract Address
 
-**Base Sepolia:** `0x206D4DbB6E7b876e4B5EFAAD2a04e7d7813FB6ba`
-
-**Base Mainnet:** `0x2714EA3e839Ac50F52B2e2a5788F614cACeE5316`
+**EscrowPeriodFactory:** `0x15DB06aADEB3a39D47756Bf864a173cc48bafe24`
 
 ### Deployment Method
 
@@ -299,8 +297,7 @@ Deploys `Freeze` condition contracts that block release when a payment is frozen
 
 ### Contract Address
 
-**Base Sepolia:** `0x199fed16577773Bb6b2D76CC3cD1c76c22D28835`
-**Base Mainnet:** `0xCAEd9474c06bf9139AC36C874dED838e1Bcb9310`
+**FreezeFactory:** `0xdf129EFFE040c3403aca597c0F0bb704859a78Fd`
 
 ### Deployment Method
 
@@ -355,11 +352,11 @@ const config = {
 
 Use these pre-deployed condition contracts:
 
-| Condition | Address (Base Sepolia) | Address (Base Mainnet) | Description |
-|-----------|------------------------|------------------------|-------------|
-| PayerCondition | `0xBAF68176FF94CAdD403EF7FbB776bbca548AC09D` | `0xb33D6502EdBbC47201cd1E53C49d703EC0a660b8` | Only payer can call |
-| ReceiverCondition | `0x12EDefd4549c53497689067f165c0f101796Eb6D` | `0xed02d3E5167BCc9582D851885A89b050AB816a56` | Only receiver can call |
-| AlwaysTrueCondition | `0x785cC83DEa3d46D5509f3bf7496EAb26D42EE610` | `0xc9BbA6A2CF9838e7Dd8c19BC8B3BAC620B9D8178` | Anyone can call |
+| Condition | Address (all chains) | Description |
+|-----------|---------------------|-------------|
+| PayerCondition | `0x33F5F1154A02d0839266EFd23Fd3b85a3505bB4B` | Only payer can call |
+| ReceiverCondition | `0xF41974A853940Ff4c18d46B6565f973c1180E171` | Only receiver can call |
+| AlwaysTrueCondition | `0xb295df7E7f786fd84D614AB26b1f2e86026C3483` | Anyone can call |
 
 ### Example Deployments
 

contracts/fees.mdx

@@ -234,7 +234,7 @@ The operator's `FEE_RECIPIENT` varies by use case:
 ## Next Steps
 
 <CardGroup cols={2}>
-  <Card title="Core Contracts" icon="file-contract" href="/contracts/core-contracts">
+  <Card title="PaymentOperator" icon="file-contract" href="/contracts/payment-operator">
     See how fees integrate with PaymentOperator.
   </Card>
   <Card title="Factories" icon="industry" href="/contracts/factories">

contracts/gas-costs.mdx

@@ -6,7 +6,7 @@ icon: "gas-pump"
 
 ## Overview
 
-x402r adds escrow, refund windows, and dispute resolution on top of [Base Commerce Payments](https://github.com/base/commerce-payments). Here you'll find the **measured gas cost** of every on-chain operation so you can evaluate the overhead.
+x402r adds escrow, refund windows, and dispute resolution on top of the [Commerce Payments Protocol](https://github.com/base/commerce-payments). Here you'll find the **measured gas cost** of every on-chain operation so you can evaluate the overhead.
 
 All numbers are from Foundry simulations (`forge test`) with optimizer enabled (200 runs, via IR). The benchmark test is at [`test/gas/GasBenchmark.t.sol`](https://github.com/BackTrackCo/x402r-contracts/blob/main/test/gas/GasBenchmark.t.sol).
 

contracts/overview.mdx

@@ -106,16 +106,25 @@ x402r extends commerce-payments with flexible payment capabilities:
 - MEV protection via private mempool support
 - Composable via `AndCondition([escrowPeriod, freeze])`
 
-### 4. Factory Pattern
+### 4. Arbiter & Evidence System
 
-**PaymentOperatorFactory** - Deploys operators with deterministic CREATE2 addresses
+**RefundRequestEvidence** - On-chain evidence submission with IPFS CIDs and arbiter EIP-712 signature approval
+
+### 5. Factory Pattern
+
+**PaymentOperatorFactory** - Deploys operators with deterministic CREATE3 addresses
 
 **EscrowPeriodFactory** - Deploys EscrowPeriod contracts
 
 **FreezeFactory** - Deploys Freeze condition contracts
 
+Plus factories for: StaticFeeCalculator, StaticAddressCondition, AndCondition, OrCondition, NotCondition, RecorderCombinator.
+
+All factories use **unified CREATE3 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
@@ -126,11 +135,12 @@ x402r extends commerce-payments with flexible payment capabilities:
 |---------|------------------|-------|
 | **Refunds** | Manual void/reclaim | Structured refund requests with configurable approval |
 | **Escrow Period** | Not enforced | Configurable time-lock before release |
-| **Dispute Resolution** | Not built-in | Optional arbiter workflow via conditions |
-| **Authorization** | Operator-based only | Pluggable conditions (access, time, combinators) |
+| **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 CREATE2 |
-| **Fees** | Not enforced | Configurable protocol and operator fees |
+| **Deployment** | Direct deployment | Factory pattern with unified CREATE3 (same address every chain) |
+| **Fees** | Not enforced | Additive protocol + operator fees with 7-day timelock |
+| **Multi-chain** | Per-chain deployment | Unified CREATE3 addresses across 11 chains |
 
 ## Use Cases
 
@@ -184,7 +194,7 @@ Protocol fee configuration is mutable via `ProtocolFeeConfig` (with 7-day timelo
 
 For a detailed view of how all contracts interact, see [Architecture](/contracts/architecture).
 
-To understand individual contracts, see [Core Contracts](/contracts/core-contracts).
+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).
 
@@ -194,8 +204,8 @@ For factory deployment patterns, see [Factories](/contracts/factories).
   <Card title="Architecture" icon="diagram-project" href="/contracts/architecture">
     View system architecture diagrams and payment flows.
   </Card>
-  <Card title="Core Contracts" icon="file-contract" href="/contracts/core-contracts">
-    Learn about PaymentOperator, RefundRequest, and other core contracts.
+  <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.