Gas Costs - x402r Documentation

Overview

x402r adds escrow, refund windows, and dispute resolution on top of the Commerce Payments Protocol. Below you’ll find the measured gas cost of every on-chain operation so you can weigh the overhead. All numbers come from Foundry simulations (forge test --gas-report) with optimizer enabled (200 runs, via IR), pinned to x402r-contracts @ bb188db (snapshot: 2026-05-20). The benchmark lives at test/gas/GasBenchmark.t.sol. Numbers are per-transaction and warm where the test measures warm (so they reflect typical second-and-beyond payments on the same operator); cold-vs-warm splits are reported alongside the warm number where relevant.

The buyer never pays gas. They only sign an off-chain ERC-3009 or Permit2 authorization. The facilitator, merchant, or another party submits every on-chain transaction.

What you’ll pay on Base

Role	Operations	Gas	Cost on Base
Facilitator	`authorize()`	182,440	< $0.005
Merchant	`capture()`	150,049	< $0.005
Happy path total	authorize + capture	332,489	< $0.01

Disputes are rare and add < $0.005 with off-chain resolution, see Dispute Path below.

Happy Path

The happy path has 2 on-chain transactions: authorize (at checkout) and capture (after the escrow period expires). With operator fees enabled, the distributeFees() call adds a third settle-time write to claim accumulated protocol fees, batched across many payments.

Operation	Gas	vs transfer	Who Calls	When
`authorize()`	182,440	17.8x	Facilitator	At checkout (HTTP 402 settlement)
`capture()`	150,049	14.6x	Anyone	After escrow period expires
`distributeFees()`	57,007	5.6x	Owner	Periodically, batched across payments

The vs transfer column shows multiples of a cold ERC-20 transfer() (10,263 gas), the absolute floor for moving tokens on-chain. In production, the merchant typically calls capture(), but the function has no caller restriction beyond the configured capture condition (EscrowPeriod + Freeze). After the escrow period passes and the payment isn’t frozen, anyone can trigger it. 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.

Facilitators: set a gas limit. The facilitator pays gas for authorize(), but the operator chooses which conditions and hooks to run. 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 (for example, 300,000 gas). The full x402r configuration uses around 182,000 gas; anything well above that warrants investigation.

Per-Plugin Gas Costs

The PaymentOperator runs with pluggable conditions (checked before an action) and hooks (called after). You choose which plugins to use. Here’s the marginal cost of each, measured by diffing adjacent configurations through the PaymentOperator entry point.

authorize()

Configuration	Gas	Marginal Cost	Plugin
PaymentOperator, no plugins	119,018	:	`bareOperator.authorize()`: operator dispatch, plugin slot checks, escrow `authorize()` call
+ Fee calculation	146,738	+27,720	`StaticFeeCalculator`: calculates protocol + operator fees, validates bounds, locks fees in `authorizedFees[hash]`
+ EscrowPeriod hook	182,440	+35,702	`EscrowPeriod.run()`: stores `authorizationTime[hash] = block.timestamp` (cold SSTORE to cross-contract slot)

The EscrowPeriod hook is the single most expensive plugin on authorize because it writes to a new storage slot in the EscrowPeriod contract.

capture()

Configuration	Gas	Marginal Cost	Plugin
PaymentOperator, no plugins	78,074	:	`bareOperator.capture()`: operator dispatch + escrow `capture()` call
+ Fee retrieval and distribution	117,033	+38,959	Reads locked fees from `authorizedFees[hash]`, calculates protocol share, accumulates in `accumulatedProtocolFees[token]`
+ ReceiverCondition	121,529	+4,496	Pure calldata comparison: `caller == paymentInfo.receiver`, no storage reads
+ EscrowPeriod condition	126,888	+5,359	Cross-contract SLOAD: reads `authorizationTime[hash]`, compares against `block.timestamp`
+ Freeze + AndCondition	147,298	+20,410	AndCondition combinator loop + `Freeze.check()` reads `frozenUntil[hash]` + internal `isDuringEscrowPeriod()`

Simple conditions are close to free. ReceiverCondition and PayerCondition cost around 4,500 gas; they only compare calldata fields. Cross-contract conditions like EscrowPeriod cost around 5,400 because of a cold SLOAD. The Freeze condition is the most expensive single condition (+20,410) because of the AndCondition combinator overhead, its own frozenUntil storage read, and an internal escrow period check.

Dispute Path

These operations only happen when a buyer disputes a payment. Most payments never touch this path.

Off-chain resolution

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 void() (to return funds). The arbiter never submits a transaction; their approval is an EIP-712 signature that anyone can relay.

On-chain step	Gas	vs transfer	Who Calls
`freeze()`	45,831	4.5x	Buyer
`void()`	68,947	6.7x	Anyone
Total	114,778	11.2x

Total dispute cost on Base with off-chain resolution: < $0.005.

Fully on-chain fallback

If the parties choose to handle the dispute fully on-chain instead:

Operation	Gas	vs transfer	Who Calls	Notes
`authorize()`	182,445	17.8x	Facilitator	Already paid during happy path
`freeze()`	45,818	4.5x	Buyer	Locks payment during escrow window
`capture()`	145,549	14.2x	Anyone	Already paid during happy path
`requestRefund()`	418,174	40.7x	Buyer	Creates refund request with multi-index storage
`submitEvidence()`	132,431	12.9x	Any party	Stores IPFS CID on-chain
`deny()`	11,096	1.1x	Arbiter	Terminal status update on the request
`refund()`	57,482	5.6x	Anyone	Pulls funds from merchant wallet via ReceiverRefundCollector
Total	992,995	96.7x

This total includes the happy path steps (authorize + capture) since those already ran. The dispute-only overhead is 665,001 gas (< $0.02 on Base).

Why is requestRefund so expensive?

requestRefund() at 418,174 gas is the most expensive operation because it writes to five storage mappings for indexing:

Refund request data (status, amount, payment hash)
Payer index (payerRefundRequests[payer][n])
Receiver index (receiverRefundRequests[receiver][n])
Operator index (operatorRefundRequests[operator][n])
Counter increments for each index

This indexing enables efficient off-chain queries but costs more gas upfront. On Base, this is still < $0.01.

Summary

Scenario	Gas	vs transfer	Cost on Base
ERC-20 transfer (cold baseline)	10,263	1x	< $0.001
PaymentOperator, no plugins (`authorize` + `capture`)	197,092	19.2x	< $0.005
+ fees	263,771	25.7x	< $0.005
+ fees + simple condition	268,267	26.1x	< $0.005
+ fees + EscrowPeriod + Freeze (x402r full)	332,489	32.4x	< $0.01
x402r dispute (off-chain optimized)	114,778	11.2x	< $0.005
x402r dispute (fully on-chain, 7 txns)	992,995	96.7x	< $0.05

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.

All numbers above assume one payment per transaction. Batching operations in a single transaction (via a multicall contract) can reduce per-payment costs by 37 to 80 percent thanks to warm EVM access; contract addresses and shared storage only load once. The benchmark test includes warm measurements for reference.

Reproducing these numbers

git clone https://github.com/BackTrackCo/x402r-contracts
cd x402r-contracts
git checkout bb188dbc0251f9a3af7da57906d5c59e2b2a14d0
forge test --match-path test/gas/GasBenchmark.t.sol -vv

Each test logs its measured gas via console.log and the --gas-report summary tables list aggregate per-function statistics.

A scheduled CI job in x402r-contracts re-runs GasBenchmark.t.sol and flags drift past threshold, so the numbers on this page are checked against the live benchmark rather than left to manual regen. When the benchmark moves, the pinned commit and figures above are refreshed.

Reference: upstream escrow costs

The escrow layer these numbers build on is Base’s audited Commerce Payments Protocol. For the baseline cost of the underlying AuthCaptureEscrow lifecycle (authorize, capture, void, refund) independent of x402r’s condition and hook plugins, see the upstream contracts and their own benchmarks in the commerce-payments repository. The x402r figures above are the upstream escrow cost plus the per-plugin overhead detailed in the breakdown.

Fee System

How the operator calculates and distributes protocol and operator fees

Architecture

How conditions, hooks, and escrow fit together

​Overview

​What you’ll pay on Base

​Happy Path

​Per-Plugin Gas Costs

​authorize()

​capture()

​Dispute Path

​Off-chain resolution

​Fully on-chain fallback

​Summary

​Reproducing these numbers

​Reference: upstream escrow costs

Fee System

Architecture

Overview

What you’ll pay on Base

Happy Path

Per-Plugin Gas Costs

authorize()

capture()

Dispute Path

Off-chain resolution

Fully on-chain fallback

Summary

Reproducing these numbers

Reference: upstream escrow costs