Skip to content

Update protocol and contracts docs to match current state #14

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
A1igator merged 1 commit into from
Mar 19, 2026
Merged

Update protocol and contracts docs to match current state #14

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
21 changes: 12 additions & 9 deletions contracts/architecture.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
}
```

Expand Down Expand Up @@ -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.
Expand Down
2 changes: 1 addition & 1 deletion contracts/examples.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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">
Expand Down
21 changes: 9 additions & 12 deletions contracts/factories.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down Expand Up @@ -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

Expand Down Expand Up @@ -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

Expand Down Expand Up @@ -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

Expand Down
2 changes: 1 addition & 1 deletion contracts/fees.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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">
Expand Down
2 changes: 1 addition & 1 deletion contracts/gas-costs.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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).

Expand Down
28 changes: 19 additions & 9 deletions contracts/overview.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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 |
Comment thread
A1igator marked this conversation as resolved.
| **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

Expand Down Expand Up @@ -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).

Expand All @@ -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.
Expand Down
Loading