Operate a Third-Party Relay Oracle

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

Relay Oracle attests to onchain facts used in Relay Protocol settlement and serves as:

An operationally stateless oracle service.
A Dockerized oracle service that exposes an HTTP API.
A signer that produces authenticated messages and execution signatures.
A verifier that reads chain state from RPC endpoints and chain-specific APIs.

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:

Deposits into depository contracts.
Withdrawals from depository contracts.
Solver fills.
Solver refunds.
Withdrawal-address flows used during withdrawal handling.

When a client asks the oracle to attest an event:

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

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

What the oracle service actually does

The oracle service exposes HTTP endpoints for:

Health checks.
Chain discovery.
Status and observability.
Attestation requests.
Swagger-based API documentation.

The main utility routes are:

GET /lives/v1
GET /status/v1
GET /chains/v1
GET /documentation

The attestation routes are:

POST /attestations/depository-deposits/v1
POST /attestations/depository-withdrawals/v1
POST /attestations/solver-fills/v1
POST /attestations/solver-refunds/v1
POST /attestations/withdrawal-initiation/v1
POST /attestations/withdrawal-initiated/v1

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:

ethereum-vm
solana-vm
bitcoin-vm
hyperliquid-vm
lighter-vm
tron-vm

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

configs/chains.<ENVIRONMENT>.json
configs/chains.hub.<ENVIRONMENT>.json

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 oracle service supports two signing modes:

raw-private-key
aws-kms

The signer is used for:

Message signatures returned by attestation endpoints.
Execution signatures used in settlement flows.

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 oracle service also supports peering across multiple oracle instances to collect signatures. When an incoming request sets requestPeerSignatures=true and PEERS is configured, the oracle starts its local attestation and every configured peer request concurrently. When ORACLE_SIGNERS is also configured, the oracle service returns early when a response group reaches the configured threshold of unique allowlisted signatures. The local oracle is not privileged on that path, so a quorum can be satisfied entirely by remote peers. The oracle service combines responses only when their attestation payloads, signing domains, and non-signature array order match. It skips responses that fail the endpoint schema. During aggregation, the oracle service excludes duplicate signatures, signatures from non-allowlisted signers when ORACLE_SIGNERS is configured, and signers missing from any signature array in a multi-message response. To enable quorum aggregation, define an allowlist of trusted signer addresses and an early-return signature target:

ORACLE_SIGNERS is a semicolon-separated allowlist of authorized signer addresses.
ORACLE_SIGNERS_THRESHOLD is the target number of unique allowlisted signatures for early return (defaults to 1). It does not prevent the oracle service from returning fewer signatures.

Each instance applies its own ORACLE_SIGNERS list, so operators are not required to configure identical lists. A signature counts only at instances that list its signer, and the signer authorized onchain decides which signatures settlement accepts. ORACLE_SIGNERS_THRESHOLD counts the local oracle’s signature along with peer signatures. A threshold of 1 can be met by the local oracle alone, so a 2-of-3 configuration uses 2.

ORACLE_SIGNERS_THRESHOLD controls early return but does not enforce quorum. During peer aggregation, Relay Oracle can return the strongest valid partial group with a success response when no group reaches the threshold, and logs the matched and required counts. Callers must verify the unique allowlisted signature count before relying on the response, and operators should alert on quorum-shortfall warnings.

For example, a 2-of-3 configuration looks like this:

ORACLE_SIGNERS=0x1111111111111111111111111111111111111111;0x2222222222222222222222222222222222222222;0x3333333333333333333333333333333333333333
ORACLE_SIGNERS_THRESHOLD=2

The oracle service fails at startup when ORACLE_SIGNERS_THRESHOLD is not an integer or is less than 1. When ORACLE_SIGNERS is configured, the oracle service also fails at startup when:

ORACLE_SIGNERS_THRESHOLD exceeds the number of unique entries in ORACLE_SIGNERS.
Any entry in ORACLE_SIGNERS is not a valid nonzero address.
The local signer address is not included in ORACLE_SIGNERS.

When ORACLE_SIGNERS is omitted, the threshold is ignored for quorum purposes, so a threshold set without an allowlist doesn’t enforce anything. The oracle service logs a startup warning when a threshold is set without the allowlist. Without the allowlist, the oracle service waits for the local operation and every configured peer, bounded by PEER_REQUEST_TIMEOUT_MS, instead of completing early at a threshold. Only peer responses that match the local unsigned payload are aggregated, and the request fails if the local attestation fails. With an allowlist, a failed local attestation is logged but does not by itself fail the request. The oracle service can return a full or partial response using only allowlisted peer signatures. If the local attestation fails, the request fails only when no valid allowlisted group is available. Peer calls are best-effort attempts. If a peer times out, errors, fails response validation, or returns a payload that does not match any signable group, it is skipped and a warning is emitted.

Status and observability

GET /status/v1 returns the instance’s status, build identifiers (version, image, gitCommit), uptimeSeconds, lowercase oracleSigner address, peerCount, and quorum configuration. Unavailable information is null. peerCount includes all configured peers, including unreachable ones. status is ok when the signer lookup succeeds, or partial when it fails or exceeds five seconds. It describes the local signer check, not a test signature or overall peer health. Without a configured signer allowlist, quorum is { "signers": [], "threshold": null }. Build identifiers use the first available value in these sequences:

version: VERSION, build manifest version, package version, IMAGE_TAG, then the resolved gitCommit.
image: IMAGE_DIGEST, IMAGE_TAG, then the build manifest image.
gitCommit: GIT_COMMIT, then the build manifest commit.

GET /lives/v1?withReport=true uses the same version resolution. Add withPeers=true to /status/v1 or /chains/v1 to check every configured peer. The response includes one peers entry per peer, including failed checks. Without this option, the peers field is omitted. In /status/v1?withPeers=true, each peer entry contains the same status fields plus url, checkResult, latencyMs, retryCount, and httpStatus. Unavailable fields are null, including quorum when the peer’s configuration is unknown. Peer URLs omit credentials, query parameters, and fragments, and invalid URLs are omitted entirely. checkResult is success when a valid report is collected, or a failure reason such as timeout, authentication-error, or invalid-response. latencyMs measures the successful request, and httpStatus records the final request’s HTTP status when available. retryCount counts retries after transient failures, excluding fallback requests. For older peers, status checks fall back to /lives/v1?withReport=true, then /lives/v1. Legacy reports supply limited information, with their old version value treated as image metadata. In /chains/v1?withPeers=true, peer entries contain only url, checkResult, and chainDifferences, relative to the top-level local chains list:

local-only: the chain exists locally but not on the peer. Includes only id and status.
peer-mismatch: the chain exists on both sides. Includes id, status, and only changed peer values for vmType or depository. depository: null means the peer has no depository configured.
peer-only: the chain exists only on the peer. Includes id, status, vmType, and depository when present.

chainDifferences: [] means the chain sets match, while null means the comparison failed. A successful comparison can still report differences. Peer checks run concurrently, honor PEER_REQUEST_TIMEOUT_MS and PEER_RESPONSE_MAX_BYTES, retry transient failures, and stop when the caller disconnects. Status responses and chain responses with withPeers=true set cache-control: no-store.

Security and trust model

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

Use a dedicated signing key that is not shared with any other oracle.
Prefer a hardened key-management approach. aws-kms is supported; if you use raw keys, store them in a real secret manager.
Enforce access control at an API gateway or reverse proxy when public access is not intended.
Use HTTPS for any publicly reachable deployment.
Use dedicated peer API keys to authenticate requests between oracle instances.
Restrict management access to the host platform and secret storage.

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 service on a platform that can run a Docker container and expose it over HTTP. 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:

Railway
ECS
Kubernetes
Fly.io
A VM running Docker

You need:

A long-running Docker runtime.
Stable outbound access to all configured RPC and chain service endpoints.
Stable inbound access from callers and peer oracles.
Secure secret storage for signing material and API keys.

Because the oracle 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=10000
ORACLE_SIGNERS=0x1111111111111111111111111111111111111111;0x2222222222222222222222222222222222222222;0x3333333333333333333333333333333333333333
ORACLE_SIGNERS_THRESHOLD=2

Notes:

HTTP_PORT is optional if your platform injects PORT. The server resolves ports in this order: HTTP_PORT, then PORT, then 3000.
API_KEYS defines the keys accepted on status, chains, and attestation routes. At least one key must be configured for the oracle to start.
PEER_REQUEST_TIMEOUT_MS defaults to 10000.
ORACLE_SIGNERS is the semicolon-separated allowlist used to count unique oracle signatures during quorum aggregation.
ORACLE_SIGNERS_THRESHOLD sets the target number of unique allowlisted signatures for early return. It defaults to 1, must be an integer of at least 1, and is validated against the size of ORACLE_SIGNERS when that allowlist is configured. It does not prevent a successful response with fewer signatures.

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:

Standard RPC URLs for the chains the oracle reads.
Supplemental service variables for chains that need more than a plain RPC endpoint.

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:

The oracle validates chain state in real time, so weak or rate-limited RPCs directly reduce reliability.
If a configured chain does not have a working RPC endpoint, any attestation that depends on that chain will fail.

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:

Some ecosystems expose critical settlement-related data more reliably through companion APIs than through a single generic RPC method.
Some providers require API credentials even when the underlying access pattern still looks like a chain read.
These variables improve reliability and coverage for chain-specific reads without changing the public API of the oracle itself.

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

Public RPC endpoints may work for lower-volume or non-critical traffic, but are typically less predictable.
Hyperliquid and Bitcoin commonly need supplemental services, not just a single RPC URL.
When adding or removing supported chains, recheck the required environment variables before deploying.

Authentication

Status, chains, and attestation routes require a valid x-api-key. Requests to these routes without a valid key return 401 Unauthorized. The health and documentation routes do not require an API key:

/
/documentation and its subpaths
/lives/v1, including withReport=true

Registered peers have no automatic exemption. Each peer request must carry a key accepted by the receiving oracle. 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:

A base URL.
A per-peer API key, separated by |.

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:

You expose a stable public HTTPS URL.
You create a dedicated incoming API key to authenticate peer requests.
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:

Create a new signer dedicated to this oracle.
Provision RPC and chain-service endpoints.
Deploy the container on Railway first unless you already have an established alternative platform.
Verify health and chain loading.
Configure API keys for trusted callers and any additional edge access controls.
Expose the oracle service over HTTPS.
Configure peering and receive live requests in shadow mode.
Run long enough to observe stability, latency, and RPC usage.
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 oracle service

Build and run the oracle 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 oracle 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 the following. Include a valid x-api-key for status, chains, and attestation requests:

GET /lives/v1 returns {"status":"ok"}.
GET /status/v1 returns status: "ok", the expected version, image, and gitCommit for the running build, and your local oracleSigner address.
GET /chains/v1 returns the chains expected for your selected ENVIRONMENT.
GET /documentation loads the Swagger UI.
Your logs show the oracle service started successfully.
Your logs show the signer address you expect, and that address matches one of the entries in ORACLE_SIGNERS if the allowlist is configured.

Then test at least one real attestation flow with a valid x-api-key.

Operational monitoring

At minimum, monitor:

Container restarts.
GET /status/v1 reporting status: "partial" and oracleSigner: null.
Request latency.
Error rate by endpoint.
Unexpected 401 Unauthorized responses.
Peer timeout, peer mismatch, and quorum-shortfall warnings.
Peer checkResult drift over time via GET /status/v1?withPeers=true and GET /chains/v1?withPeers=true.
RPC provider failures and rate limits.
Memory and CPU consumption.
Signer address correctness after deploys.

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

Settlement

Vaults

Operate a Third-Party Relay Oracle

Overview

What the Relay Oracle is

How the oracle fits into the protocol

What the oracle service actually does

Supported chains and data sources

Signing model

Peer oracles and quorum

Status and observability

Security and trust model

Infrastructure requirements

Configuration model

Chain RPC and additional service variables

Core RPC variables

Supplemental non-RPC variables

Practical guidance

Authentication

Peering with other oracle operators

Recommended deployment sequence

Running the oracle service

First-run verification checklist

Operational monitoring

​Overview

​What the Relay Oracle is

​How the oracle fits into the protocol

​What the oracle service actually does

​Supported chains and data sources

​Signing model

​Peer oracles and quorum

​Status and observability

​Security and trust model

​Infrastructure requirements

​Configuration model

​Chain RPC and additional service variables

​Core RPC variables

​Supplemental non-RPC variables

​Practical guidance

​Authentication

​Peering with other oracle operators

​Recommended deployment sequence

​Running the oracle service

​First-run verification checklist

​Operational monitoring

Overview

What the Relay Oracle is

How the oracle fits into the protocol

What the oracle service actually does

Supported chains and data sources

Signing model

Peer oracles and quorum

Status and observability

Security and trust model

Infrastructure requirements

Configuration model

Chain RPC and additional service variables

Core RPC variables

Supplemental non-RPC variables

Practical guidance

Authentication

Peering with other oracle operators

Recommended deployment sequence

Running the oracle service

First-run verification checklist

Operational monitoring