Configuration

Overview

Most configuration files should live under ./config, including the signer configurations, under ./config/keys. Please ensure appropriate access permissions on all configuration files (for ./config/keys/*, we recommend 0500.

The OpenZeppelin Relayer supports two configuration approaches:

File-based Configuration:

config.json: Contains relayer definitions, signer configurations, and network policies
.env file: Contains environment variables like API keys and connection strings

API-based Configuration:

Full CRUD operations for relayers, signers, and notifications via REST API
Changes take effect immediately (no container restart required)
See the API Reference page for detailed endpoints documentation

See Storage Configuration for detailed information about how file-based and API-based configurations work together, storage behavior, and best practices.

For quick setup examples with pre-configured files, see the examples directory in our GitHub repository.

Environment configuration (.env)

This defines some base configurations for the Relayer application:

Copy the example environment file and update values according to your needs

cp .env.example .env

This table lists the environment variables and their default values.

Environment Variable	Default Value	Accepted Values	Description
`RUST_LOG`	`info`	`info, debug, warn, error, trace`	Log level.
`REPOSITORY_STORAGE_TYPE`	`in-memory`	`in-memory, redis`	Type of storage used for storing repository config and resources. See Storage Configuration for detailed information.
`RESET_STORAGE_ON_START`	`false`	`bool`	Clears all resources from storage on startup and reloads entries from the config file. See Storage Configuration for usage details.
`TRANSACTION_EXPIRATION_HOURS`	`4`	`number`	Number of hours after which transactions in a final state are removed from storage. See Storage Configuration for more information.
`CONFIG_DIR`	`./config`	`<any relative file path where config.json is located>`	Relative path of directory where config files reside
`CONFIG_FILE_NAME`	`config.json`	`<any file name>`	File Name of the configuration file.
`RATE_LIMIT_RPS`	`100`	`<any value>`	Rate limit for the API in requests per second.
`RATE_LIMIT_BURST_SIZE`	`300`	`<any value>`	Rate limit burst size.
`API_KEY`	``	`string`,	API key to use for authentication to the relayer server. Minimum length 32 characters.
`WEBHOOK_SIGNING_KEY`	``	`string`	Signing key to use for webhook notifications. Minimum length 32 characters.
`LOG_MODE`	`stdout`	`stdout, file`	Write logs either to console or to file.
`LOG_DATA_DIR`	`./logs`	`<any file path>`	Directory to persist log files on host.
`LOG_MAX_SIZE (in bytes)`	`1073741824`	`<any value in bytes>`	Size after which logs needs to be rolled.
`METRICS_ENABLED`	`false`	`bool`	Enable metrics server for external tools to scrape metrics.
`METRICS_PORT`	`8081`	`<any tcp port (preferably choose non-privileged ports i.e. (1024-65535))>`	Port to use for metrics server.
`REDIS_URL`	`redis://localhost:6379`	`<redis connection string>`	Redis connection URL for the relayer. See Storage Configuration for Redis setup details.
`REDIS_CONNECTION_TIMEOUT_MS`	`10000`	`<timeout in milliseconds>`	Connection timeout for Redis in milliseconds. See Storage Configuration for Redis configuration.
`REDIS_KEY_PREFIX`	`oz-relayer`	`string`	Redis key prefix for namespacing. See Storage Configuration for more information.
`STORAGE_ENCRYPTION_KEY`	``	`string`	Encryption key used to encrypt data at rest in Redis storage. See Storage Configuration for security details.
`RPC_TIMEOUT_MS`	`10000`	`<timeout in milliseconds>`	Sets the maximum time to wait for RPC connections before timing out.
`PROVIDER_MAX_RETRIES`	`3`	`<number of retries>`	Maximum number of retry attempts for provider operations.
`PROVIDER_RETRY_BASE_DELAY_MS`	`100`	`<delay in milliseconds>`	Base delay between retry attempts in milliseconds.
`PROVIDER_RETRY_MAX_DELAY_MS`	`2000`	`<delay in milliseconds>`	Maximum delay between retry attempts in milliseconds.
`PROVIDER_MAX_FAILOVERS`	`3`	`<number of failovers>`	Maximum number of failovers (switching to different providers).
`ENABLE_SWAGGER`	`false`	`true, false`	Enable or disable Swagger UI for API documentation.
`KEYSTORE_PASSPHRASE`	``	`<keystore passphrase>`	Passphrase for the keystore file used for signing transactions.

Environment configuration example

.env file config example:

RUST_LOG=DEBUG
CONFIG_DIR=./config
CONFIG_FILE_NAME=config.json
WEBHOOK_SIGNING_KEY=e1d42480-6f74-4d0b-85f4-b7f0bb690fae
API_KEY=5eefd216-0e44-4ca7-b421-2925f90d30d5
RATE_LIMIT_RPS=100
RATE_LIMIT_BURST_SIZE=300
METRICS_ENABLED=true
METRICS_PORT=8081
REDIS_URL=redis://localhost:6379
REDIS_CONNECTION_TIMEOUT_MS=10000
REDIS_KEY_PREFIX=oz-relayer
RPC_TIMEOUT_MS=10000
PROVIDER_MAX_RETRIES=3
PROVIDER_RETRY_BASE_DELAY_MS=100
PROVIDER_RETRY_MAX_DELAY_MS=2000
PROVIDER_MAX_FAILOVERS=3
ENABLE_SWAGGER=false
KEYSTORE_PASSPHRASE=your_keystore_passphrase
STORAGE_ENCRYPTION_KEY=X67aXacJB+krEldv9i2w7NCSFwwOzVV/1ELM2KJJjQw=
REPOSITORY_STORAGE_TYPE=redis
RESET_STORAGE_ON_START=false
TRANSACTION_EXPIRATION_HOURS=8

Main configuration file (config.json)

This file can exist in any directory, but the default location is ./config/config.json.

All components defined in config.json can also be managed via REST API endpoints. This provides runtime flexibility for adding, updating, or removing relayers, signers, and notifications without restarting the service. See the API Reference page for detailed endpoints documentation.

Key sections in this file include:

Signers: Defines transaction signing methods.
Notifications: Sets up status alerts
Relayers: Configures networks, notifications channels, policies & singers.
Networks: Defines blockchain network configurations.
Plugins: Configures plugins.

1. Signers

Transaction signers are responsible for cryptographically signing transactions before they are submitted to blockchain networks.

For comprehensive details on configuring all supported signer types including:

Local keystore file signers
HashiCorp Vault (secret and transit)
Cloud KMS providers (Google Cloud, AWS)
Turnkey signers
Security best practices and troubleshooting

See the dedicated Signers Configuration guide.

Signers can also be managed via API endpoints.

See the API Reference page for detailed endpoints documentation.

2. Notifications

notifications array containing notification entries:

"notifications": [

    "id": "notification-test",
    "type": "webhook",
    "url": "https://webhook.site/f95cf78d-742d-4b21-88b7-d683e6fd147b",
    "signing_key": {
      "type": "env",
      "value": "WEBHOOK_SIGNING_KEY"

  }
]

Available configuration fields

Field	Type	Description
id	String	Unique id for the notification
type	String	Type of notification (only `webhook` available, for now)
url	String	Notification URL
signing_key.type	String	Type of key used in signing the notification (`env` or `plain`)
signing_key.value	String	Signing key value, env variable name, ...

Notifications can also be managed via API endpoints.

See the API Reference page for detailed endpoints documentation.

3. Relayers

relayers array, containing relayer entries:

"relayers": [

    "id": "solana-testnet",
    "name": "Solana Testnet",
    "paused": false,
    "notification_id": "notification-test",
    "signer_id": "local-signer",
    "network_type": "solana",
    "network": "testnet",
    "custom_rpc_urls": [
      {
        "url": "https://primary-rpc.example.com",
        "weight": 2  // Higher weight routes more requests to this endpoint. The value must be an integer between 0 and 100 (inclusive).
      ,

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

    ],
    "policies":
      "allowed_programs": [
          "11111111111111111111111111111111",
          "TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA",
          "BPFLoaderUpgradeab1e11111111111111111111111"
        ]

  }
]

Available configuration fields

Field	Type	Description
id	String	Unique id for the relayer
name	String	Human readable name for the relayer
paused	Boolean	Whether or not the relayer is paused (`true`, `false`)
notification_id	String	ID of a configured notification object
signer_id	String	ID of a configured signer
network_type	String	Type of network the relayer will connect to (`evm`, `solana`)
network	String	Network the relayer will connect to. Must match a network identifier defined in your network configuration files. See Network Configuration for details on defining networks.
custom_rpc_urls	list	Optional custom RPC URLs for the network. If provided, this will be used instead of the public RPC URLs. This is useful for using your own RPC node or a paid service provider. The first url of the list is going to be used as the default
policies	list	Overrides default policies. Please refer to the `Policies` table

Policies

Network type	Policy	Type	Description
solana, evm	min_balance	unsigned 128	Minimum balance (in lamports or wei) required for the relayer to operate. Optional.
solana	fee_payment_strategy	enum(user,relayer)	Specifies who pays the fee. "user" (default) means the sender pays; "relayer" means the relayer pays. For "user", RPC methods add an instruction to transfer SPL tokens (calculated from the current SOL price plus a configurable margin) from the user to the relayer, ensuring fees are sustainably covered in tokens rather than SOL.
solana	swap_config	SwapConfig	Optional object configuring automated token‐swaps on Solana.
solana	fee_margin_percentage	f32	Additional margin percentage added to estimated transaction fees to account for price fluctuations. For example, a value of 10 will add 10% to estimated fees. Optional.
solana	max_allowed_fee_lamports	unsigned 64	Maximum allowed fee (in lamports) for a transaction. Optional.
solana	allowed_tokens	`Vector<AllowedToken>`	List of allowed tokens. Only these tokens are supported if provided. Optional.
solana	allowed_programs	`Vector<String>`	List of allowed programs by their identifiers. Only these programs are supported if provided. Optional.
solana	allowed_accounts	`Vector<String>`	List of allowed accounts by their public keys. The relayer will only operate with these accounts if provided.
solana	disallowed_accounts	`Vector<String>`	List of disallowed accounts by their public keys. These accounts will be explicitly blocked.
solana	max_tx_data_size	unsigned 16	Maximum transaction size. Optional.
solana	max_signatures	unsigned 8	Maximum supported signatures. Optional.
evm	gas_price_cap	unsigned 128	Specify a maximum gas price for every transaction sent with the Relayer. When enabled, any transaction exceeding the cap will have its gasPrice or maxFeePerGas overwritten. (Optional)
evm	gas_limit_estimation	bool	Automatic gas_limit calculation. Enabled by default. (Optional)
evm	whitelist_receivers	`Vector<String>`	A list of authorized contracts for each transaction sent using the Relayer. Transactions will be rejected if the destination address is not on the list. (Optional)

RPC URL Configuration

The relayer supports two ways to configure RPC URLs:

Public RPC URLs: These are the default RPC endpoints provided by the network. They are automatically selected based on the network configuration.
Custom RPC URLs: You can specify custom RPC URLs using the custom_rpc_urls field in the relayer configuration. Each URL can be configured with an optional weight for high availability:

"custom_rpc_urls": [

    "url": "https://primary-rpc.example.com",
    "weight": 2  // Higher weight routes more requests to this endpoint. The value must be an integer between 0 and 100 (inclusive).
  ,

    "url": "https://secondary-rpc.example.com",
    "weight": 100, // Max allowed weight
  ,

    "url": "https://backup-rpc.example.com"  // No weight specified, defaults to 100
  ,

    "url": "https://backup2-rpc.example.com",
    "weight": 0, //  A value of 0 disables the endpoint.

]

This is useful when you want to:

Use your own RPC nodes with load balancing
Use a paid service provider for better reliability and performance
Override the default public RPC URLs
Access custom network endpoints
Configure primary and backup endpoints with different weights

When both are available, the relayer will:

First attempt to use the custom_rpc_urls if configured.
Fall back to the public RPC URLs if no custom URL is configured.

For backward compatibility, string arrays are still supported:

"custom_rpc_urls": ["https://your-rpc.example.com"]

When using custom RPC URLs:

Ensure the URLs are secure (HTTPS) when accessing over public networks
Keep your API keys and authentication tokens secure
Test the RPC endpoints' reliability and performance before using it in production
Configure weights to prioritize endpoints, assigning higher values to more reliable or performant ones.
The weight must be an integer between 0 and 100 (inclusive).
A weight of 0 disables the endpoint.
If a weight is not specified for an endpoint, it defaults to 100.

Relayers could also be managed via API endpoints.

See the API Reference page for detailed endpoints documentation.

4. Plugins

For more information on how to write a plugin, please refer to the Plugins page.

plugins array, containing plugin configurations:

"plugins": [

    "id": "my-plugin",
    "path": "my-plugin.ts"

]

Available configuration fields

Field	Type	Description
id	String	Unique id for the plugin
path	String	Path to the plugin file

5. Networks

You can configure networks either:

In separate JSON files (recommended for better organization)
Directly in your main config.json

For comprehensive network configuration details, including:

Network field reference
Configuration examples for all network types
Network inheritance
Special tags and their behavior
Best practices and troubleshooting

See the dedicated Network Configuration guide.

Configuration File Example

Full config/config.json example with evm and solana relayers definitions using keystore signer:


  "relayers": [
    {
      "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": 2
        ,

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

      ],
      "policies":
        "gas_price_cap": 30000000000000,
        "eip1559_pricing": true

    },

      "id": "solana-example",
      "name": "Solana Example",
      "network": "devnet",
      "paused": false,
      "notification_id": "notification-example",
      "signer_id": "local-signer",
      "network_type": "solana",
      "custom_rpc_urls": [
        {
          "url": "https://primary-solana-rpc.example.com",
          "weight": 2
        ,

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

      ],
      "policies":
        "fee_payment_strategy": "user",
        "min_balance": 0,
        "allowed_tokens": [
          {
            "mint": "Gh9ZwEmdLJ8DscKNTkTqPbNwLNNBjuSzaG9Vp2KGtKJr",
            "max_allowed_fee": 100000000
          ,

            "mint": "So11111111111111111111111111111111111111112"

        ]
      }
    },

      "id": "solana-mainnet-example",
      "name": "Solana Mainnet Example",
      "network": "mainnet-beta",
      "paused": false,
      "notification_id": "notification-example",
      "signer_id": "local-signer",
      "network_type": "solana",
      "custom_rpc_urls": ["https://your-private-solana-rpc.example.com"],
      "policies": {
        "fee_payment_strategy": "user",
        "min_balance": 0,
        "swap_config": {
          "cron_schedule": "0 0 * * * *",
          "min_balance_threshold": 0,
          "strategy": "jupiter-ultra"
        ,
        "allowed_tokens": [

            "mint": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",
            "max_allowed_fee": 100000000,
            "swap_config": {
              "min_amount": 0,
              "max_amount": 0,
              "retain_min_amount": 0

          },

            "mint": "So11111111111111111111111111111111111111112"

        ]
      }
    }
  ],
  "notifications": [

      "id": "notification-example",
      "type": "webhook",
      "url": "https://webhook.site/1384d4d9-21b1-40a0-bcd1-d3f3b66be955",
      "signing_key": {
        "type": "env",
        "value": "WEBHOOK_SIGNING_KEY"

    }
  ],
  "signers": [

      "id": "local-signer",
      "type": "local",
      "config": {
        "path": "config/keys/local-signer.json",
        "passphrase": {
          "type": "env",
          "value": "KEYSTORE_PASSPHRASE"

      }
    }
  ],
  "networks": [

      "average_blocktime_ms": 12000,
      "chain_id": 11155111,
      "explorer_urls": [
        "https://api-sepolia.etherscan.io/api",
        "https://sepolia.etherscan.io"
      ],
      "features": [
        "eip1559"
      ],
      "is_testnet": true,
      "network": "sepolia",
      "required_confirmations": 6,
      "rpc_urls": [
        "https://sepolia.drpc.org",
        "https://1rpc.io/sepolia",
        "https://ethereum-sepolia-rpc.publicnode.com",
        "https://ethereum-sepolia-public.nodies.app"
      ],
      "symbol": "ETH",
      "tags": [
        "deprecated"
      ],
      "type": "evm"
    ,

      "type": "solana",
      "network": "devnet",
      "rpc_urls": ["https://api.devnet.solana.com"],
      "explorer_urls": ["https://explorer.solana.com?cluster=devnet"],
      "average_blocktime_ms": 400,
      "is_testnet": true
    ,

      "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

  ]
}

Configuration Management Approaches

The OpenZeppelin Relayer supports two complementary approaches for configuration management:

File-based Configuration

Ideal for initial setup and deployment
Configuration persists across restarts
Requires container restart for changes to take effect
Suitable for infrastructure-as-code workflows

API-based Configuration

Enables runtime configuration changes
No service restarts required
Perfect for dynamic environments
Supports automated configuration management

See Storage Configuration for detailed information about how file-based and API-based configurations work together, storage behavior, and best practices.

Configuration

On this page