x402-chain-eip155

EIP-155 (EVM) chain support for the x402 payment protocol.

This crate provides implementations of the x402 payment protocol for EVM-compatible blockchains using the EIP-155 chain ID standard. It supports both V1 and V2 protocol versions with the "exact" payment scheme based on ERC-3009 transferWithAuthorization.

Features

V1 and V2 Protocol Support: Implements both protocol versions with network name (V1) and CAIP-2 chain ID (V2) addressing
ERC-3009 Payments: Gasless token transfers using transferWithAuthorization
Permit2 Payments (V2 only): Universal gasless token transfers using Uniswap's Permit2 contract
Dual Transfer Methods (V2): Support for both EIP-3009 and Permit2 asset transfer methods
Smart Wallet Support:
- EIP-1271 for deployed smart wallets
- EIP-6492 for counterfactual (not-yet-deployed) smart wallets
- EOA (Externally Owned Account) signatures
Multiple Signers: Round-robin signer selection for load distribution
Nonce Management: Automatic nonce tracking with pending transaction awareness
Gas Management: Automatic gas estimation with EIP-1559 and legacy support

Architecture

The crate is organized into several modules:

chain - Core EVM chain types, providers, and configuration
v1_eip155_exact - V1 protocol implementation with network names
v2_eip155_exact - V2 protocol implementation with CAIP-2 chain IDs

Feature Flags

server - Server-side price tag generation
client - Client-side payment signing
facilitator - Facilitator-side payment verification and settlement
telemetry - OpenTelemetry tracing support

Usage

Server: Creating a Price Tag

use x402_chain_eip155::{V1Eip155Exact, KnownNetworkEip155};
use x402_types::networks::USDC;

// Get USDC deployment on Base
let usdc = USDC::base();

// Create a price tag for 1 USDC
let price_tag = V1Eip155Exact::price_tag(
"0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb",
usdc.amount(1_000_000u64),
);

Client: Signing a Payment

use x402_chain_eip155::V1Eip155ExactClient;
use alloy_signer_local::PrivateKeySigner;

let signer = PrivateKeySigner::random();
let client = V1Eip155ExactClient::new(signer);

// Use client to sign payment candidates
let candidates = client.accept( & payment_required);

Facilitator: Verifying and Settling

use x402_chain_eip155::{V1Eip155Exact, Eip155ChainProvider};
use x402_types::scheme::X402SchemeFacilitatorBuilder;

let provider = Eip155ChainProvider::from_config( & config).await?;
let facilitator = V1Eip155Exact.build(provider, None) ?;

// Verify payment
let verify_response = facilitator.verify( & verify_request).await?;

// Settle payment
let settle_response = facilitator.settle( & settle_request).await?;

Supported Networks

The crate includes built-in support for many EVM networks through the KnownNetworkEip155 trait:

Base (mainnet and Sepolia testnet)
Polygon (mainnet and Amoy testnet)
Avalanche (C-Chain and Fuji testnet)
Sei (mainnet and testnet)
XDC Network
XRPL EVM
Peaq
IoTeX
Celo (mainnet and Sepolia testnet)

Each network includes USDC token deployment information with proper EIP-712 domain parameters.

ERC-3009 and Signature Handling

The facilitator intelligently dispatches to different transferWithAuthorization contract functions or other onchain functions based on the signature format:

EOA signatures (64-65 bytes): Parsed as (r, s, v) components and dispatched to the standard EIP-3009 function
EIP-1271 signatures: Passed as full signature bytes for contract wallet verification
EIP-6492 signatures: Detected by the 32-byte magic suffix and validated via the universal EIP-6492 validator contract

For EIP-6492 counterfactual signatures, the facilitator can deploy the smart wallet on-chain if needed before settling the payment.

Permit2 Support (V2 Protocol Only)

The V2 protocol adds support for Permit2, a universal token approval system from Uniswap that enables gasless transfers for any ERC-20 token. This provides a fallback payment method for tokens that don't natively support EIP-3009.

Asset Transfer Methods

V2 payment requirements can specify an assetTransferMethod:

eip3009: Direct transferWithAuthorization for tokens with native support (e.g., USDC)
permit2: Universal proxy using Uniswap's canonical Permit2 contract

Permit2 Flow

Client checks if user has Permit2 allowance for the token
If insufficient allowance, returns 412 Precondition Failed
Client generates EIP-712 signature with witness data
Facilitator verifies signature (supports EIP-6492 and EIP-1271)
Facilitator validates allowance, balance, and constraints
Facilitator settles via X402ExactPermit2Proxy contract

Contract Addresses

Permit2 (Canonical): 0x000000000022D473030F116dDEE9F6B43aC78BA3
X402ExactPermit2Proxy: 0x4020615294c913F045dc10f0a5cdEbd86c280001

Future Extensions

The Permit2 implementation is designed to support gasless approval extensions:

EIP-2612 Gas Sponsoring: Facilitator accepts permit signatures for approval
ERC-20 Approval Gas Sponsoring: Facilitator sponsors approval transactions

Configuration

Facilitator Configuration Example

{
  "eip155:8453": {
    "eip1559": true,
    "flashblocks": false,
    "receipt_timeout_secs": 30,
    "signers": [
      "$FACILITATOR_PRIVATE_KEY"
    ],
    "rpc": [
      {
        "http": "https://mainnet.base.org",
        "rate_limit": 100
      }
    ]
  }
}

Dependencies

This crate uses the Alloy library for Ethereum interactions, providing:

Type-safe contract bindings
EIP-712 typed data signing
Transaction building and signing
RPC provider with fallback and rate limiting

License

Apache 2.0

x402-chain-eip155 1.3.0