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)

  • cdp (hosted Coinbase Developer Platform signer)

For detailed signer configuration options, see the Signers guide.

In production systems, hosted signers (AWS KMS, Google Cloud KMS, Turnkey, CDP) 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.

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:

  1. 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

  2. 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/sepolia-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/sepolia-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/sepolia-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/sepolia-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/sepolia-example/transactions/<transaction_id>' \
--header 'Authorization: Bearer <api_key>'

See API Reference for full details and examples.

Transaction Lifecycle

1. Transaction Submission

  • Validate transaction parameters

  • Check whitelist policies (if enabled)

  • Estimate gas limit (if not provided)

  • Calculate gas price based on network conditions

2. Transaction Signing

  • Sign transaction using configured signer

  • Generate appropriate signature format

3. Transaction Broadcasting

  • Submit to network via RPC endpoints

  • Handle RPC failures with automatic retries

  • Switch to backup RPC endpoints if needed

4. Transaction Monitoring

  • Track transaction status and confirmations

  • Handle transaction replacements if needed

  • Send notifications on status changes

5. Transaction Confirmation

  • Wait for required number of confirmations

  • Mark transaction as confirmed or failed

  • Clean up resources

Security Best Practices

Network Security

  • Use private RPC endpoints in production

  • Configure appropriate gas_price_cap to prevent excessive fees

  • Enable whitelist_receivers for controlled environments

  • Monitor relayer balance and set appropriate min_balance

Signer Security

  • Use hosted signers (AWS KMS, Google Cloud KMS, Turnkey) in production

  • Rotate signer keys regularly

  • Implement proper access controls and audit logging

  • Never store private keys in plain text

Operational Security

  • Deploy behind a secure reverse proxy

  • Use HTTPS for all communications

  • Implement proper rate limiting

  • Monitor for unusual transaction patterns

Monitoring and Observability

Enable metrics and monitor:

  • Transaction success rates

  • Gas price trends

  • RPC endpoint performance

  • Relayer balance levels

  • Failed transaction patterns

Support

For help with EVM integration:

License

This project is licensed under the GNU Affero General Public License v3.0.

← Storage Configuration
Solana Integration →