Operate a Third-Party Relay Oracle - Relay

Overview

The Relay Oracle attests to the onchain facts that drive Relay Protocol settlement. This guide covers how it fits into the protocol and how to deploy and operate an external oracle outside Relay’s internal infrastructure.

What the Relay Oracle is

The Relay Oracle is the service that attests to onchain facts used by the Relay Protocol settlement flow. It is:

Its job is to inspect chain state, determine whether a specific protocol-relevant event happened, and sign the corresponding result for downstream settlement flows.

How the oracle fits into the protocol

At a high level, the Relay Protocol needs reliable confirmation that key lifecycle steps actually happened onchain before downstream settlement actions are accepted. The oracle is responsible for attesting these core actions:

When a client asks the oracle to attest an event:

  1. The oracle fetches the relevant chain configuration.
  2. It reads chain state from the configured RPC endpoint or chain-specific service.
  3. It builds a protocol message that describes what happened.
  4. It signs the message with its configured signer.
  5. For endpoints that produce execution payloads, it may also collect corroborating signatures from peer oracles.
  6. The caller can then use those signatures in the wider settlement flow.

The service can be run as a single instance or as multiple cooperating instances.

What the service actually does

The service exposes HTTP endpoints for:

The main utility routes are:

The attestation routes are:

The built-in Swagger UI at /documentation is the best reference for exact request and response schemas.

Supported chains and data sources

The oracle supports multiple VM families, with chain-specific attestation logic behind a unified API. The current VM attestor implementation supports:

Which chains are enabled is controlled by the selected environment config:

These config files do not hardcode every endpoint. Instead, many values are placeholders that are resolved from environment variables at runtime. That means your real deployment depends on the quality of the RPC and service endpoints you provide.

Signing model

Each running instance uses one configured signer. The service supports two signing modes:

The signer is used for:

If your instance is meant to participate in active production signing, coordinate signer onboarding with Relay before expecting its signatures to be used downstream. If you are just getting started, run the instance first in shadow mode: it signs requests and proves operational readiness, but its signatures are not yet relied on for quorum.

Peer oracles and quorum

A single oracle can answer requests on its own, and the code also supports peering across multiple oracle instances. For execution-producing endpoints, an oracle can fan out the same request to configured peer oracles and aggregate their signatures when:

Important operational behavior:

This allows a new oracle to be introduced in shadow mode without turning peer availability into a hard dependency for each request.

Security and trust model

If you operate a third-party oracle, you are expected to treat it as production infrastructure. Minimum security expectations:

The oracle is stateless, but its signer is security-critical. If the signing key is compromised, the instance should be treated as compromised immediately.

Infrastructure requirements

You should run the oracle as a Dockerized service on a platform that can run a Docker container and expose an HTTP service. For most third-party operators, Railway should be treated as the preferred starting point. It is the recommended default when you want the simplest path to running a single external oracle instance. Typical Docker-hosting options:

You need:

Because the service is stateless, scaling horizontally is possible. In practice, the biggest operational constraints are uptime, RPC quality, and signer security. If you already operate production container infrastructure, another platform can be a valid choice. If not, default to Railway.

Configuration model

The runtime configuration is mostly environment-variable driven. For a recommended raw-key mainnet deployment, define:

ENVIRONMENT=mainnets.prod
ECDSA_PRIVATE_KEY=0x...
API_KEYS=your-api-key:your-name

SIGNING_MODULE=raw-private-key is optional because raw-key signing is the default code path, but setting it explicitly is clearer for operators. You can also set:

HTTP_PORT=3000
PEERS=https://peer-one.example.com|peer-api-key;https://peer-two.example.com|peer-api-key
PEER_REQUEST_TIMEOUT_MS=5000

Notes:

If you use AWS KMS instead of a raw key:

SIGNING_MODULE=aws-kms
AWS_KMS_SIGNER_KEY_ID=...
AWS_KMS_SIGNER_KEY_REGION=...

Chain RPC and additional service variables

The chain config files reference environment variables dynamically. Your deployment is only as reliable as the endpoints and credentials you provide there. There are two categories to think about:

Core RPC variables

For a mainnet deployment, the most important RPC variables to populate first are:

ETHEREUM_RPC_URL=
BASE_RPC_URL=
ARBITRUM_RPC_URL=
BNB_RPC_URL=
POLYGON_RPC_URL=
SOLANA_RPC_URL=
BITCOIN_RPC_URL=
HYPERLIQUID_RPC_URL=

Why these matter:

You may also need additional chain RPC variables beyond the list above, depending on which chains remain enabled in your selected ENVIRONMENT. The chain config files are the source of truth for the full required set.

Supplemental non-RPC variables

Some chains and integrations need service-specific URLs or credentials in addition to a raw RPC endpoint. Common examples are:

HYPERLIQUID_HUB_API_URL=
HYPERLIQUID_HUB_API_KEY=
HYPERLIQUID_PROXY_API_URL=
HYPERLIQUID_PROXY_API_KEY=
BITCOIN_ESPLORA_COMPATIBLE_API_URL=
BITCOIN_BLOCKSTREAM_CLIENT_ID=
BITCOIN_BLOCKSTREAM_CLIENT_SECRET=
BITCOIN_MAESTRO_API_KEY=
LIGHTER_RPC_API_KEY=

Why these matter:

You do not need to expose internal provider choices publicly. You only need to ensure the variables required by your chosen providers are present, valid, and managed like any other production secret.

Practical guidance

Authentication

When API_KEYS is set, the service requires a valid x-api-key header for all protected routes. These routes remain accessible without an API key:

/chains/v1 and all attestation endpoints should be treated as protected endpoints in a real deployment. API_KEYS uses this format:

API_KEYS=key-one:partner-a;key-two:partner-b

The right-hand label is stored as metadata for that key.

Peering with other oracle operators

Use PEERS to define other oracle instances this oracle should call when peer signatures are requested. Format:

PEERS=https://peer-a.example.com|peer-a-key;https://peer-b.example.com|peer-b-key

Each entry is:

pass-through is also supported as a peer credential, which forwards the incoming x-api-key instead of a dedicated peer key. That is generally better suited to tightly controlled internal environments. For separate organizations, use dedicated peer keys. If Relay-managed oracles need to call your instance, the usual pattern is:

  1. You expose a stable public HTTPS URL.
  2. You create a dedicated incoming API key for peer traffic.
  3. Relay adds your URL and that key to the PEERS list used by its oracle instances.

Recommended deployment sequence

The safest way to bring up a new third-party oracle is:

  1. Create a new signer dedicated to this oracle.
  2. Provision RPC and chain-service endpoints.
  3. Deploy the container on Railway first unless you already have an established alternative platform.
  4. Verify health and chain loading.
  5. Protect the service with API keys.
  6. Expose the service over HTTPS.
  7. Configure peering and receive live requests in shadow mode.
  8. Run long enough to observe stability, latency, and RPC usage.
  9. Only then consider onboarding the signer for active participation.

This order lets you validate the infrastructure and chain dependencies before your signer becomes operationally important.

Running the service

Build and run the service as a Docker container:

docker build -t relay-protocol-oracle .
docker run --rm -p 3000:3000 --env-file .env relay-protocol-oracle

The container entrypoint also loads secrets from /vault/secrets when present, which is useful for secret-injection systems. If your platform builds from source automatically, the important requirement is still the same: the service should be deployed and run as the repository’s Docker image, with the required environment variables injected at runtime.

First-run verification checklist

After deployment, verify:

Then test at least one real attestation flow, using a valid x-api-key if API_KEYS is configured.

Operational monitoring

At minimum, monitor:

A healthy process can still be operationally unusable if its RPC dependencies are degraded, so RPC observability matters as much as container health.