openzeppelin/openzeppelin-relayer repository overview

⁠OpenZeppelin Relayer

This relayer service enables interaction with blockchain networks through transaction submissions. It offers multi-chain support and an extensible architecture for adding new chains.

User Docs⁠ | Quickstart⁠

⁠Pre-requisites

• Docker installed on your machine
• Sodium⁠. See install sodium section⁠ for more information.
• .env file with the required environment variables & config/config.json file with the required configuration. See how to set it up in config files section⁠ for more information.
• Create signers and add them to the config/config.json file. See how to set it up in signers section⁠ for more information.
• Configure webook url in config/config.json file. See how to set it up in webhook section⁠ for more information.
• Configure webhook signing key in config/config.json file. See how to set it up in webhook section⁠ for more information.
• Configure Api key in config/config.json file. See how to set it up in api key section⁠ for more information.
• Redis server running. See how to set it up in redis section⁠ for more information.

⁠How to use images pushed to DockerHub

• These images are automatically pulled when you use docker compose. See using docker compose⁠ for more information.
• If you are not using docker compose and you want to use these images, follow the steps below.

⁠1. Pull the image

You can pull the latest image using the following command:

docker pull openzeppelin/openzeppelin-relayer:latest

⁠2. Run the image

You can run the image using the following command:

docker run --env-file .env -d \
  --name relayer \
  --network relayer-net \
  -p 8080:8080 \
  -v ./config:/app/config:ro \
  openzeppelin/openzeppelin-relayer:latest

⁠3. Access the service

Once the container is running, you can access the service at http://localhost:8080.

You can test the relayer by sending a request using a curl call. See testing relayer section⁠ for more information.

⁠4. Stop the container

You can stop the container using the following command:

docker stop relayer

⁠5. Remove the container

You can remove the container using the following command:

docker rm relayer

⁠6. Remove the image

You can remove the image using the following command:

docker rmi openzeppelin/openzeppelin-relayer:latest

⁠Contributing

We welcome contributions to the OpenZeppelin Relayer. Please read our contributing section⁠ for more information.

⁠Runtime worker sizing (CPU)

The relayer runs its HTTP server on actix workers and its background transaction pipeline on a separate multi-thread tokio runtime. Size both to the container's vCPU quota with these env vars:

ACTIX_WORKERS + TOKIO_WORKER_THREADS should be ≤ the allocated vCPU. At startup the relayer logs the resolved vcpu, actix_workers, and tokio_worker_threads, and WARNs if the budget exceeds the quota.

Auto-detection (available_parallelism) returns host cores, not the cgroup quota, on AWS Fargate (cpu.shares) — so on Fargate you must pin these explicitly.

Per-platform:

• AWS Fargate: set TOKIO_WORKER_THREADS/ACTIX_WORKERS in the task definition to match the task vCPU; watch CloudWatch CPU throttling.
• GCP Cloud Run: use the gen2 execution environment with --no-cpu-throttling (run.googleapis.com/cpu-throttling: false) and min-instances >= 1, otherwise the background pipeline is starved of CPU between HTTP requests. Set the worker counts to the configured CPU.
• GKE: pin to the CPU request and alert on container_cpu_cfs_throttled_seconds_total.

When using AWS KMS signers, set an explicit region in the signer config so region resolution never falls back to the IMDS metadata endpoint.

⁠Observability

See the observability section⁠ for more information on how to set up observability for the relayer.

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