Skip to content

Commit beaa7f4

Browse files
A1igatorclaude
A1igator
and
claude
authored
Add gas costs documentation page (#13)
## Summary - Adds `contracts/gas-costs.mdx` with simulated gas measurements for every on-chain operation - All numbers from Foundry benchmarks (`test/gas/GasBenchmark.t.sol` in x402r-contracts) - Adds nav entry in `docs.json` under Smart Contracts > Overview ## Page contents - **Role-based summary** at the top (facilitator vs merchant costs on Base) - **Happy path** — authorize, release, distributeFees with vs-transfer multiples - **Per-plugin breakdown** — marginal cost of each condition/recorder for authorize and release - **Dispute path** — freeze, requestRefund, submitEvidence, approveWithSignature, refundInEscrow, refundPostEscrow - **Off-chain operations** — zero-gas ERC-3009/EIP-712 signatures - **Summary table** — all configurations from bare Commerce Payments to full x402r dispute path - Batching disclaimer noting warm EVM access can reduce costs 37–80% ## Test plan - [ ] Preview with `npx mint dev` and verify page renders - [ ] Verify all internal links work - [ ] Cross-check gas numbers against `forge test --match-contract GasBenchmark -vv` 🤖 Generated with [Claude Code](https://claude.com/claude-code) --------- Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>
1 parent 28dadad commit beaa7f4

2 files changed

Lines changed: 148 additions & 0 deletions

File tree

‎contracts/gas-costs.mdx‎

Lines changed: 147 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,147 @@
1+
---
2+
title: "Gas Costs"
3+
description: "Simulated gas measurements for every on-chain operation, with per-plugin overhead breakdown"
4+
icon: "gas-pump"
5+
---
6+
7+
## Overview
8+
9+
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.
10+
11+
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).
12+
13+
<Note>
14+
The buyer never pays gas. They only sign an off-chain ERC-3009 authorization. All on-chain transactions are submitted by the facilitator, merchant, or other parties.
15+
</Note>
16+
17+
## What you'll pay on Base
18+
19+
| Role | Operations | Gas | Cost on Base |
20+
|------|-----------|-----|-------------|
21+
| **Facilitator** | `authorize()` | 181,544 | < $0.005 |
22+
| **Merchant** | `release()` | 150,262 | < $0.005 |
23+
| **Happy path total** | authorize + release | 331,806 | **< $0.01** |
24+
25+
Disputes are rare and add < $0.005 with off-chain resolution — see [Dispute Path](#dispute-path) below.
26+
27+
## Happy Path
28+
29+
The happy path has **2 on-chain transactions**: `authorize` (at purchase time) and `release` (after the escrow period expires).
30+
31+
| Operation | Gas | vs transfer | Who Calls | When |
32+
|-----------|-----|------------|-----------|------|
33+
| `authorize()` | 181,544 | 17.6x | Facilitator | At purchase (HTTP 402 settlement) |
34+
| `release()` | 150,262 | 14.6x | Anyone | After escrow period expires |
35+
36+
The **vs transfer** column shows multiples of a cold ERC-20 `transfer()` (10,305 gas) — the absolute floor for moving tokens on-chain.
37+
38+
In production, the merchant typically calls `release()`, but the function has no caller restriction beyond the configured release condition (EscrowPeriod + Freeze). After the escrow period passes and the payment isn't frozen, anyone can trigger it.
39+
40+
An escrow authorization is inherently more work than a raw ERC-20 transfer: it validates payment info, checks fee bounds, locks fees, transfers tokens into escrow, and records state. The per-plugin section below shows exactly where the gas goes.
41+
42+
<Warning>
43+
**Facilitators: set a gas limit.** The facilitator pays gas for `authorize()`, but the operator chooses which conditions and recorders are configured. Each plugin slot adds cost, and custom plugins can run arbitrary computation. Simulate the transaction with `eth_estimateGas` before submitting and reject operators whose `authorize()` exceeds a reasonable threshold (e.g., 300,000 gas). The full x402r configuration uses ~181,000 — anything significantly above that warrants investigation.
44+
</Warning>
45+
46+
## Per-Plugin Gas Costs
47+
48+
The PaymentOperator is configured with pluggable conditions (checked before an action) and recorders (called after). You choose which plugins to use. Here's the marginal cost of each, measured by diffing adjacent configurations.
49+
50+
### authorize()
51+
52+
| Configuration | Gas | Marginal Cost | Plugin |
53+
|---------------|-----|---------------|--------|
54+
| Commerce Payments escrow (no operator) | 78,353 | — | Raw `AuthCaptureEscrow.authorize()` — validates payment, escrows tokens via `PreApprovalPaymentCollector` |
55+
| + PaymentOperator layer | 117,250 | **+38,897** | Operator dispatch, plugin slot checks, access control — all conditions, recorders, and fee calculator set to `address(0)` |
56+
| + Fee calculation | 135,961 | **+18,711** | `StaticFeeCalculator` — calculates protocol + operator fees, validates bounds, locks fees in `authorizedFees[hash]` |
57+
| + EscrowPeriod recorder | 162,744 | **+26,783** | `EscrowPeriod.record()` — stores `authorizationTime[hash] = block.timestamp` (cold SSTORE to cross-contract slot) |
58+
59+
The EscrowPeriod recorder is the single most expensive plugin on `authorize` because it writes to a new storage slot in the EscrowPeriod contract.
60+
61+
### release()
62+
63+
| Configuration | Gas | Marginal Cost | Plugin |
64+
|---------------|-----|---------------|--------|
65+
| Commerce Payments escrow (no operator) | 66,365 | — | Raw `AuthCaptureEscrow.capture()` — validates authorization, distributes tokens to receiver |
66+
| + PaymentOperator layer | 77,926 | **+11,561** | Operator dispatch, plugin slot checks, access control — all conditions, recorders, and fee calculator set to `address(0)` |
67+
| + Fee retrieval | 116,980 | **+39,054** | Reads locked fees from `authorizedFees[hash]`, calculates protocol share, accumulates in `accumulatedProtocolFees[token]` |
68+
| + ReceiverCondition | 121,430 | **+4,450** | Pure calldata comparison: `caller == paymentInfo.receiver` — no storage reads |
69+
| + EscrowPeriod condition | 122,520 | **+5,540** | Cross-contract SLOAD: reads `authorizationTime[hash]`, compares against `block.timestamp` |
70+
| + Freeze + AndCondition | 142,961 | **+20,441** | AndCondition combinator loop + `Freeze.check()` reads `frozenUntil[hash]` + internal `isDuringEscrowPeriod()` |
71+
72+
<Tip>
73+
**Simple conditions are nearly free.** `ReceiverCondition` and `PayerCondition` cost ~4,500 gas — they only compare calldata fields. Cross-contract conditions like `EscrowPeriod` cost ~5,500 due to a cold SLOAD. The `Freeze` condition is the most expensive single condition (+20,441) because of the AndCondition combinator overhead, its own `frozenUntil` storage read, and an internal escrow period check.
74+
</Tip>
75+
76+
## Dispute Path
77+
78+
These operations only happen when a payment is disputed. Most payments never touch this path.
79+
80+
### Off-chain resolution
81+
82+
The refund request, evidence submission, and arbiter approval can all happen off-chain. The only on-chain steps are `freeze()` (to lock the payment during the escrow window) and `refundInEscrow()` (to return funds). The arbiter never submits a transaction — their approval is an EIP-712 signature that anyone can relay.
83+
84+
| On-chain step | Gas | vs transfer | Who Calls |
85+
|--------------|-----|------------|-----------|
86+
| `freeze()` | 44,651 | 4.3x | Buyer |
87+
| `refundInEscrow()` | 65,924 | 6.4x | Anyone |
88+
| **Total** | **110,575** | **10.7x** | |
89+
90+
Total dispute cost on Base with off-chain resolution: **< $0.005**.
91+
92+
### Fully on-chain fallback
93+
94+
If the parties choose to handle the dispute fully on-chain instead:
95+
96+
| Operation | Gas | vs transfer | Who Calls | Notes |
97+
|-----------|-----|------------|-----------|-------|
98+
| `authorize()` | 181,544 | 17.6x | Facilitator | Already paid during happy path |
99+
| `freeze()` | 44,651 | 4.3x | Buyer | Locks payment during escrow window |
100+
| `release()` | 150,262 | 14.6x | Anyone | Already paid during happy path |
101+
| `requestRefund()` | 421,689 | 40.9x | Buyer | Creates refund request with multi-index storage |
102+
| `submitEvidence()` | 135,597 | 13.2x | Any party | Stores IPFS CID on-chain |
103+
| `approveWithSignature()` | 89,935 | 8.7x | Anyone | Relays arbiter's off-chain EIP-712 signature |
104+
| `refundPostEscrow()` | 54,467 | 5.3x | Anyone | Pulls funds from merchant wallet via ReceiverRefundCollector |
105+
| **Total** | **1,078,145** | **104.6x** | | |
106+
107+
This total includes the happy path steps (`authorize` + `release`) since those have already been paid. The dispute-only overhead is 746,339 gas (< $0.02 on Base).
108+
109+
<Accordion title="Why is requestRefund so expensive?">
110+
`requestRefund()` at 421,689 gas is the most expensive operation because it writes to **multiple storage mappings** for indexing:
111+
112+
- Refund request data (status, amount, payment hash)
113+
- Payer index (`payerRefundRequests[payer][n]`)
114+
- Receiver index (`receiverRefundRequests[receiver][n]`)
115+
- Operator index (`operatorRefundRequests[operator][n]`)
116+
- Counter increments for each index
117+
118+
This indexing enables efficient off-chain queries but costs more gas upfront. On Base, this is still < $0.01.
119+
</Accordion>
120+
121+
## Summary
122+
123+
| Scenario | Gas | vs transfer | Cost on Base |
124+
|----------|-----|------------|-------------|
125+
| ERC-20 transfer (baseline) | 10,305 | 1x | < $0.001 |
126+
| Commerce Payments escrow, no operator (authorize + capture) | 144,718 | 14.0x | < $0.005 |
127+
| + PaymentOperator layer, no plugins | 195,176 | 18.9x | < $0.005 |
128+
| + fees | 252,941 | 24.5x | < $0.005 |
129+
| + fees + simple condition | 257,391 | 25.0x | < $0.005 |
130+
| **+ fees + EscrowPeriod + Freeze (x402r full)** | **331,806** | **32.2x** | **< $0.01** |
131+
| x402r dispute (off-chain optimized) | 110,575 | 10.7x | < $0.005 |
132+
| x402r dispute (fully on-chain, 7 txns) | 1,078,145 | 104.6x | < $0.05 |
133+
134+
The full x402r happy path uses ~32x the gas of a single ERC-20 transfer — but on Base L2, the absolute cost stays under a penny. The overhead comes from escrow validation, fee locking, cross-contract storage writes, and condition checks, all detailed in the per-plugin breakdown above.
135+
136+
<Info>
137+
All numbers above assume one payment per transaction. Batching multiple operations in a single transaction (via a multicall contract) can reduce per-payment costs by 37–80% due to warm EVM access — contract addresses and shared storage only need to be loaded once. The benchmark test includes warm measurements for reference.
138+
</Info>
139+
140+
<CardGroup cols={2}>
141+
<Card title="Fee System" icon="coins" href="./fees">
142+
How protocol and operator fees are calculated and distributed
143+
</Card>
144+
<Card title="Architecture" icon="diagram-project" href="./architecture">
145+
How conditions, recorders, and escrow fit together
146+
</Card>
147+
</CardGroup>

‎docs.json‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -41,6 +41,7 @@
4141
"contracts/core-contracts",
4242
"contracts/factories",
4343
"contracts/fees",
44+
"contracts/gas-costs",
4445
"contracts/examples",
4546
"contracts/audits",
4647
"contracts/license"

0 commit comments

Comments
 (0)