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

Network Type Description

evm

Ethereum Virtual Machine compatible networks. Supports any EVM chain by configuring chain ID, RPC URLs, and network-specific parameters.

solana

Solana blockchain networks. Supports all Solana clusters and custom RPC endpoints.

stellar

Stellar blockchain networks. Supports Stellar Public Network and Testnet.

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"
}
Once you specify a networks field in your configuration, the default ./config/networks directory will not be loaded automatically. If you want to use files from that directory, you must explicitly specify the path "./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
}
This is the same as the default behavior, but explicitly specified. You can also point to a different directory or file path.

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:

Field Type Required Description

type

string

Yes

Network type: "evm", "solana", or "stellar"

network

string

Yes

Unique network identifier (e.g., "ethereum-mainnet", "polygon-mumbai")

from

string

No

Name of parent network to inherit from (same type only)

rpc_urls

array[string]

Yes*

List of RPC endpoint URLs (*Required for base networks, optional for inherited)

explorer_urls

array[string]

No

List of blockchain explorer URLs

average_blocktime_ms

number

No

Estimated average time between blocks in milliseconds

is_testnet

boolean

No

Whether this is a testnet (affects behavior and validation)

tags

array[string]

No

Arbitrary tags for categorization and filtering

Special Network Tags

Some tags have special meaning and affect relayer behavior:

Tag Description and Behavior

rollup

Identifies Layer 2 rollup networks (e.g., Arbitrum, Optimism, Base)

optimism

Identifies Optimism-based networks using the OP Stack (e.g., Optimism, Base, World Chain)

arbitrum-based

Identifies Arbitrum-based networks using the Arbitrum Stack

no-mempool

Indicates networks that lack a traditional mempool (e.g., Arbitrum)

deprecated

Marks networks that are deprecated and may be removed in future versions

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

The OpenZeppelin Relayer supports any EVM-based L1 blockchain, as long as it doesn’t deviate significantly from standard EVM behavior. Some L2 networks may also work, depending on how closely they follow EVM conventions. Users are encouraged to add the networks they need via the JSON configuration and test them thoroughly on testnets before deploying to production.
Field Type Required Description

chain_id

number

Yes*

Unique chain identifier (e.g., 1 for Ethereum mainnet, 137 for Polygon) (*Required for base networks, optional for inherited)

required_confirmations

number

Yes*

Number of block confirmations before considering a transaction final (*Required for base networks, optional for inherited)

symbol

string

Yes*

Native currency symbol (e.g., "ETH", "MATIC", "BNB") (*Required for base networks, optional for inherited)

features

array[string]

No

Supported features (e.g., ["eip1559", "london"])

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

Field Type Required Description

passphrase

string

No

Network passphrase for transaction signing and network identification (optional for all networks, including base networks)

Example: Stellar Network Configuration

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

{
  "type": "stellar",
  "network": "pubnet",
  "rpc_urls": ["https://mainnet.sorobanrpc.com"],
  "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://mainnet.sorobanrpc.com"],
  "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

← Signers
Storage Configuration →