OpenZeppelin Relayer

Overview

This software is in alpha stage. Use in production environments at your own risk.

OpenZeppelin Relayer is a service that provides infrastructure to relay transactions to the EVM & Non-EVM networks. It is designed to be used as a backend for dApps that need to interact with these networks.

Features

Multi-Chain Support: Interact with multiple blockchain networks, including Solana and EVM-based chains.
Transaction Relaying: Submit transactions to supported blockchain networks efficiently.
Transaction Signing: Securely sign transactions using configurable key management.
Transaction Fee Estimation: Estimate transaction fees for better cost management.
Solana Gasless Transactions: Support for gasless transactions on Solana, enabling users to interact without transaction fees.
Transaction Nonce Management: Handle nonce management to ensure transaction order.
Transaction Status Monitoring: Track the status of submitted transactions.
SDK Integration: Easily interact with the relayer through our companion JavaScript/TypeScript SDK.
Extensible Architecture: Easily add support for new blockchain networks.
Configurable Network Policies: Define and enforce network-specific policies for transaction processing.
Metrics and Observability: Monitor application performance using Prometheus and Grafana.
Docker Support: Deploy the relayer using Docker for both development and production environments.
Plugins: Extend the functionality of the relayer with custom logic using TypeScript functions.

Supported Networks

OpenZeppelin Relayer supports multiple blockchain networks through a flexible JSON-based configuration system. Networks are defined in configuration files, allowing you to configure:

Any EVM-compatible network (Ethereum, Polygon, BSC, Arbitrum, Optimism, etc.)
Solana networks (mainnet-beta, devnet, testnet, custom RPC endpoints)
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 that inherit from base configurations

Network Types

Network Type Description

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 (Partial support). Supports Stellar Public Network and Testnet.

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 (Partial support). Supports Stellar Public Network and Testnet.

Networks can be loaded from:

JSON arrays: Direct network definitions in configuration files
Directory of files: Multiple JSON files each containing network definitions

For detailed network configuration options and examples, see the Network Configuration page.

For information about our development plans and upcoming features, see Project Roadmap.

To get started immediately, see Quickstart.

Technical Overview

Project Structure

The project follows a standard Rust project layout:

openzeppelin-relayer/
├── src/
│   ├── api/              # Route and controllers logic
│   ├── bootstrap/        # Service initialization logic
│   ├── config/           # Configuration logic
│   ├── constants/        # Constant values used in the system
│   ├── domain/           # Domain logic
│   ├── jobs/             # Asynchronous processing logic (queueing)
│   ├── logging/          # Logs File rotation logic
│   ├── metrics/          # Metrics logic
│   ├── models/           # Data structures and types
│   ├── repositories/     # Configuration storage
│   ├── services/         # Services logic
│   └── utils/            # Helper functions
│
├── config/               # Configuration files
├── tests/                # Integration tests
├── docs/                 # Documentation
├── scripts/              # Utility scripts
├── examples/             # Configuration examples
├── helpers/              # Rust helper scripts
├── plugins/              # Plugins directory
└── ... other root files (Cargo.toml, README.md, etc.)

For detailed information about each directory and its contents, see Project Structure Details.

Getting Started

Prerequisites

Rust 2021 edition
Docker (optional, for containerized deployment)
Node.js, typescript and ts-node (optional, for plugins)

Ready-to-Use Example Configurations

For quick setup with various configurations, check the examples directory in our GitHub repository:

basic-example: Simple setup with Redis
basic-example-logging: Configuration with file-based logging
basic-example-metrics: Setup with Prometheus and Grafana metrics
vault-secret-signer: Using HashiCorp Vault for key management
vault-transit-signer: Using Vault Transit for secure signing
evm-gcp-kms-signer: Using Google Cloud KMS for EVM secure signing
evm-turnkey-signer: Using Turnkey for EVM secure signing
solana-turnkey-signer: Using Turnkey for Solana secure signing

Each example includes a README with step-by-step instructions and Docker Compose configuration.

Install Locally

Clone the repository:

git clone https://github.com/openzeppelin/openzeppelin-relayer
cd openzeppelin-relayer

Verify you have sodium libs installed. If not, follow these instructions:
- Install a stable libsodium version from here.
- Follow the steps in the libsodium installation guide.
Install dependencies:
```
cargo build
```

Running the Relayer

Option 1: Run Locally

cargo run

Before executing the command, ensure that the .env and config.json files are configured as detailed in the Configuration References section.

Option 2: Run with Docker

The Relayer can be run as either a development or production container using the corresponding Dockerfile (Dockerfile.development or Dockerfile.production).

Step 1: Configure Environment

Edit .env at the root of the repository to adjust environment variables
The appropriate .env file will be included during image build

Step 2: Build the Image

You can build using Docker Compose (v2).

# Default build
docker compose build

# Or, for a leaner image (and using Dockerfile.production)
DOCKERFILE=Dockerfile.production docker compose build

Step 3: Run the Container

Use Docker Compose to run the container:

docker compose up -d

For production runs, you can use:

DOCKERFILE=Dockerfile.production docker compose up -d

Configuration

OpenZeppelin Relayer requires proper configuration before starting. The configuration system uses two main files:

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

Both configuration files must be properly set up before starting the application. Changes to either file require restarting the container to take effect.

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

For comprehensive configuration details, including:

Environment variables and their settings
Main configuration file structure
Signer configurations (local, vault, cloud KMS, etc.)
Notification setup
Relayer policies and network settings
Plugin configuration
Complete configuration examples

See the dedicated Configuration Guide.

Important Considerations

This software is in alpha stage. Use in production environments at your own risk.

Deployment Considerations

The OpenZeppelin Relayer is designed to function as a backend service and is not meant to be directly exposed to the public internet. To protect the service from unauthorized access, deploy it behind your own secure backend infrastructure—such as a reverse proxy or firewall—and restrict access to trusted internal components only. Direct exposure can increase the risk of exploitation and security breaches.

Support

For support or inquiries, contact us on Telegram.

License

This project is licensed under the GNU Affero General Public License v3.0 - see the LICENSE file for details.

Security

For security concerns, please refer to our Security Policy.