Gas Costs

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

x402r adds escrow, refund windows, and dispute resolution on top of the Commerce Payments Protocol. 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.

​

What you’ll pay on Base

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 purchase time) and release (after the escrow period expires). The vs transfer column shows multiples of a cold ERC-20 transfer() (10,305 gas) — the absolute floor for moving tokens on-chain. 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. 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.

​

Per-Plugin Gas Costs

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.

​

authorize()

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

​

release()

​

Dispute Path

These operations only happen when a payment is disputed. 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 refundInEscrow() (to return funds). The arbiter never submits a transaction — their approval is an EIP-712 signature that anyone can relay. 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: 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).

Why is requestRefund so expensive?

requestRefund() at 421,689 gas is the most expensive operation because it writes to multiple 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

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.