Network Configuration

The OpenZeppelin Relayer supports multiple blockchain networks through a flexible JSON-based configuration system. This guide covers everything you need to know about configuring networks for your relayer instances.

Overview

Networks are defined in JSON configuration files, allowing you to:

• Configure any EVM-compatible network (Ethereum, Polygon, BSC, Arbitrum, Optimism, etc.)
• Set up Solana networks (mainnet-beta, devnet, testnet, custom RPC endpoints)
• Configure Stellar networks (Pubnet, Testnet, custom networks)
• Create custom network configurations with specific RPC endpoints, chain IDs, and network parameters
• Use inheritance to create network variants without duplicating configuration

Network Types

Configuration Methods

Default Network Configuration

If no networks field is specified in your config.json, the relayer will automatically load network configurations from the ./config/networks directory. This is the default behavior.

{
  "relayers": [...],
  "notifications": [...],
  "signers": [...]
  // No "networks" field - defaults to "./config/networks"
}

You can configure networks in two ways:

Method 1: Separate JSON Files

Specify the path to network configuration files in your main config.json:

{
  "relayers": [...],
  "notifications": [...],
  "signers": [...],
  "networks": "./config/networks"  // Path to directory or file
}

Each JSON file must contain a top-level networks array:

{
  "networks": [
    // ... network definitions ...
  ]
}

When using a directory structure:

networks/
├── evm.json        # {"networks": [...]}
├── solana.json     # {"networks": [...]}
└── stellar.json    # {"networks": [...]}

Method 2: Direct Configuration

Define networks directly in your main config.json instead of using separate files:

{
  "relayers": [...],
  "notifications": [...],
  "signers": [...],
  "networks": [
    {
      "type": "evm",
      "network": "ethereum-mainnet",
      "chain_id": 1,
      // ... other fields
    }
  ]
}

When using this method, the default ./config/networks directory is ignored, and only the networks defined in this array will be available.

Network Field Reference

Common Fields

All network types support these configuration fields:

Special Network Tags

Some tags have special meaning and affect relayer behavior:

Example: Using Special Tags

Here’s an example showing how special tags are used in practice:

{
  "type": "evm",
  "network": "arbitrum-one",
  "chain_id": 42161,
  "required_confirmations": 1,
  "symbol": "ETH",
  "rpc_urls": ["https://arb1.arbitrum.io/rpc"],
  "tags": ["rollup", "no-mempool"],  // Arbitrum is a rollup without mempool
  "is_testnet": false
}

These tags help the relayer:

• Apply specific transaction handling for rollups
• Use optimized fee calculation for OP Stack chains
• Skip mempool-related operations for networks without mempools
• Warn users about deprecated networks

EVM-Specific Fields

Example: EVM Network Configuration

Here’s an example showing an EVM network configuration:

{
  "type": "evm",
  "network": "ethereum-mainnet",
  "chain_id": 1,                    // Ethereum mainnet chain ID
  "required_confirmations": 12,     // High security: 12 confirmations
  "symbol": "ETH",                  // Native currency symbol
  "features": ["eip1559"],          // Supports EIP-1559 fee market
  "rpc_urls": ["https://mainnet.infura.io/v3/YOUR_KEY"],
  "is_testnet": false
}

Solana-Specific Fields

Currently, Solana networks use only the common fields. Additional Solana-specific configuration options may be added in future versions.

Stellar-Specific Fields

Example: Stellar Network Configuration

Here’s an example showing a Stellar network configuration with passphrase:

{
  "type": "stellar",
  "network": "pubnet",
  "rpc_urls": ["https://horizon.stellar.org"],
  "explorer_urls": ["https://stellar.expert/explorer/public"],
  "passphrase": "Public Global Stellar Network ; September 2015",  // Official mainnet passphrase
  "average_blocktime_ms": 5000,
  "is_testnet": false
}

Configuration Examples

Basic EVM Network

{
  "type": "evm",
  "network": "ethereum-mainnet",
  "chain_id": 1,
  "required_confirmations": 12,
  "symbol": "ETH",
  "rpc_urls": ["https://mainnet.infura.io/v3/YOUR_KEY"],
  "explorer_urls": ["https://etherscan.io"],
  "average_blocktime_ms": 12000,
  "is_testnet": false,
  "tags": ["mainnet", "ethereum"]
}

Layer 2 EVM Network with Tags

{
  "type": "evm",
  "network": "optimism",
  "chain_id": 10,
  "required_confirmations": 1,
  "symbol": "ETH",
  "rpc_urls": [
    "https://mainnet.optimism.io",
    "https://optimism.drpc.org"
  ],
  "features": ["eip1559"],
  "tags": ["rollup", "optimism"],
  "average_blocktime_ms": 2000,
  "is_testnet": false
}

Solana Network

{
  "type": "solana",
  "network": "mainnet-beta",
  "rpc_urls": ["https://api.mainnet-beta.solana.com"],
  "explorer_urls": ["https://explorer.solana.com"],
  "average_blocktime_ms": 400,
  "is_testnet": false,
  "tags": ["mainnet", "solana"]
}

Stellar Network

{
  "type": "stellar",
  "network": "pubnet",
  "rpc_urls": ["https://horizon.stellar.org"],
  "passphrase": "Public Global Stellar Network ; September 2015",
  "explorer_urls": ["https://stellar.expert/explorer/public"],
  "average_blocktime_ms": 5000,
  "is_testnet": false,
  "tags": ["mainnet", "stellar"]
}

Network Inheritance

Networks can inherit from other networks of the same type, allowing you to create variants without duplicating configuration:

{
  "networks": [
    {
      "type": "evm",
      "network": "ethereum-base",
      "chain_id": 1,
      "required_confirmations": 12,
      "symbol": "ETH",
      "rpc_urls": ["https://mainnet.infura.io/v3/YOUR_KEY"]
    },
    {
      "from": "ethereum-base",
      "type": "evm",
      "network": "ethereum-sepolia",
      "chain_id": 11155111,
      "required_confirmations": 3,
      "rpc_urls": ["https://sepolia.infura.io/v3/YOUR_KEY"],
      "is_testnet": true
    }
  ]
}

When using inheritance:

• The child network inherits all fields from the parent
• Fields specified in the child override parent values
• The from field must reference a network of the same type

Using Networks in Relayer Configuration

Once networks are defined, reference them in your relayer configurations:

{
  "relayers": [
    {
      "id": "my-evm-relayer",
      "name": "My EVM Relayer",
      "network": "ethereum-mainnet",  // References network ID
      "network_type": "evm",
      "signer_id": "my-signer"
    }
  ]
}

Best Practices

1. Network Organization

• Group related networks in separate files (e.g., ethereum.json, polygon.json)
• Use consistent naming conventions for network identifiers
• Include both mainnet and testnet configurations

2. RPC URLs

• Always configure multiple RPC URLs for redundancy
• Use private/dedicated RPC endpoints for production
• Ensure URLs are secure (HTTPS) when accessing over public networks

3. Confirmation Requirements

• Set appropriate required_confirmations based on network security
• Higher values for mainnet, lower for testnets
• Consider network-specific finality characteristics

4. Tags and Features

• Use tags to categorize networks (e.g., "mainnet", "testnet", "rollup")
• Enable appropriate features (e.g., "eip1559" for supported networks)
• Document custom tags used in your organization

5. Inheritance

• Create base configurations for common settings
• Use inheritance to reduce duplication
• Override only necessary fields in child networks

Troubleshooting

Common Issues

Network not found:

• Ensure the network identifier in relayer config matches exactly
• Check that network configuration files are in the correct location
• Verify JSON syntax is valid

RPC connection failures:

• Test RPC URLs independently before configuring
• Ensure firewall/network allows outbound HTTPS connections
• Check API keys are included in RPC URLs where required

Invalid configuration:

• Validate required fields are present for network type
• Ensure numeric fields (chain_id, confirmations) are numbers, not strings
• Check that inherited networks reference existing parent networks

See Also

• Relayer Configuration
• Quickstart Guide
• Solana Integration
• API Reference