EVM Integration

Overview

OpenZeppelin Relayer provides comprehensive support for EVM (Ethereum Virtual Machine) networks, enabling secure transaction relaying, advanced gas management, EIP-1559 support, and robust fee estimation. This page covers everything you need to get started and make the most of EVM-specific features.

Features

Advanced gas price management with EIP-1559 support
Dynamic gas limit estimation with fallback mechanisms
Transaction replacement and acceleration
Multi-network support (Ethereum, Arbitrum, Optimism, BSC, Polygon, etc.)
Custom RPC endpoints with load balancing and failover
Secure transaction signing with multiple signer backends
Transaction status monitoring and confirmation tracking
Whitelist-based security policies
Metrics and observability

Supported Networks

EVM networks are defined via JSON configuration files, providing flexibility to:

Configure any EVM-compatible network (Ethereum, Polygon, BSC, Arbitrum, Optimism, etc.)
Set up custom EVM-compatible networks with specific RPC endpoints
Create network variants using inheritance from base configurations
Support both Layer 1 and Layer 2 networks

For detailed network configuration options, see the Network Configuration guide.

Supported Signers

local (local keystore files)
vault (HashiCorp Vault secret storage)
vault_cloud (hosted HashiCorp Vault)
turnkey (hosted Turnkey signer)
google_cloud_kms (Google Cloud KMS)
aws_kms (Amazon AWS KMS)

For detailed signer configuration options, see the Signers guide.

In production systems, hosted signers (AWS KMS, Google Cloud KMS, Turnkey) are recommended for the best security model.

Quickstart

For a step-by-step setup, see Quick Start Guide. Key prerequisites:

Rust 2021, version 1.86 or later
Redis
Docker (optional)

Example configuration for an EVM relayer:


  "id": "sepolia-example",
  "name": "Sepolia Example",
  "network": "sepolia",
  "paused": false,
  "notification_id": "notification-example",
  "signer_id": "local-signer",
  "network_type": "evm",
  "custom_rpc_urls": [
    {
      "url": "https://primary-rpc.example.com",
      "weight": 100
    ,

      "url": "https://backup-rpc.example.com",
      "weight": 100

  ],
  "policies":
     "gas_price_cap": 100000000000,
      "eip1559_pricing": true,
      "gas_limit_estimation": true,
      "whitelist_receivers": [
        "0x1234567890123456789012345678901234567890",
        "0xabcdefabcdefabcdefabcdefabcdefabcdefabcd"
      ],
      "min_balance": 1000000000000000000

},

For more configuration examples, visit the OpenZeppelin Relayer examples repository, window=_blank.

Configuration

Relayer Policies

In addition to standard relayer configuration and policies, EVM relayers support additional options:

gas_price_cap: Maximum gas price limit (in wei) for transactions
gas_limit_estimation: Enable/disable automatic gas limit estimation
whitelist_receivers: List of authorized contract addresses for transactions
min_balance: Minimum balance required for the relayer to operate (in wei)
eip1559_pricing: Enable/disable EIP-1559 pricing methodology for transaction fees

You can check all options in User Documentation - Relayers.

Gas Management Configuration

Gas Price Cap

Set a maximum gas price to protect against extreme network congestion:


  "policies": {
    "gas_price_cap": 100000000000  // 100 Gwei maximum

}

Gas Limit Estimation

Enable or disable automatic gas limit estimation:


  "policies": {
    "gas_limit_estimation": true  // Enable automatic estimation

}

When disabled, gas limits must be provided explicitly in transaction requests.

The relayer uses a two-tier approach for gas limit estimation:

Primary Method: Uses the RPC estimate_gas method to calculate gas requirements
- The estimated value is increased by 10% as a safety buffer
- Provides accurate estimates for most transaction types
Fallback Method: When RPC estimation fails, default gas limits are applied based on transaction type:
- Simple ETH transfer (no data): 21,000 gas
- ERC20 transfer (0xa9059cbb): 65,000 gas
- ERC721/ERC20 transferFrom (0x23b872dd): 80,000 gas
- Complex contracts (all other function calls): 200,000 gas

For advanced users working with complex transactions or custom contracts, it is recommended to include an explicit gas_limit parameter in the transaction request to ensure optimal gas usage and avoid estimation errors.

Whitelist Receivers

Restrict transactions to specific contract addresses:


  "policies": {
    "whitelist_receivers": [
      "0x1234567890123456789012345678901234567890",
      "0xabcdefabcdefabcdefabcdefabcdefabcdefabcd"
    ]

}

API Reference

The EVM API provides comprehensive transaction management capabilities.

Common endpoints:

POST /api/v1/relayers/<relayer_id>/transactions send transaction
GET /api/v1/relayers/<relayer_id>/transactions list transactions
GET /api/v1/relayers/<relayer_id>/transactions/<transaction_id> get transaction by id

Send Transaction - Speed params

curl --location --request POST 'http://localhost:8080/api/v1/relayers/solana-example/transactions' \
--header 'Authorization: Bearer <api_key>' \
--header 'Content-Type: application/json' \
--data-raw '
 {
    "value": 1,
    "data": "0x",
    "to": "0xd9b55a2ba539031e3c18c9528b0dc3a7f603a93b",
    "speed": "average"

}'

Send Transaction - Speed params with gas limit included

curl --location --request POST 'http://localhost:8080/api/v1/relayers/solana-example/transactions' \
--header 'Authorization: Bearer <api_key>' \
--header 'Content-Type: application/json' \
--data-raw '
 {
    "value": 1,
    "data": "0x",
    "to": "0xd9b55a2ba539031e3c18c9528b0dc3a7f603a93b",
    "speed": "average",
    "gas_limit": 21000

}'

Transaction with EIP-1559 Pricing

curl --location --request POST 'http://localhost:8080/api/v1/relayers/solana-example/transactions' \
--header 'Authorization: Bearer <api_key>' \
--header 'Content-Type: application/json' \
--data-raw '
 {
    "value": 1,
    "data": "0x",
    "to": "0xd9b55a2ba539031e3c18c9528b0dc3a7f603a93b",
    "max_fee_per_gas": 30000000000,
    "max_priority_fee_per_gas": 20000000000,

}'

Transaction with Legacy Pricing - gas estimation included

curl --location --request POST 'http://localhost:8080/api/v1/relayers/solana-example/transactions' \
--header 'Authorization: Bearer <api_key>' \
--header 'Content-Type: application/json' \
--data-raw '
 {
    "value": 1,
    "data": "0x",
    "to": "0xd9b55a2ba539031e3c18c9528b0dc3a7f603a93b",
    "gas_price": "12312313123"

}'

Get Transaction Status

curl --location --request GET 'http://localhost:8080/api/v1/relayers/solana-example/transactions/<transaction_id>' \
--header 'Authorization: Bearer <api_key>'

See API Reference for full details and examples.