Skip to main content

​
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:
  • An operationally stateless HTTP service.
  • A Dockerized 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:
  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:
  • Health checks.
  • Chain discovery.
  • Attestation requests.
  • Swagger-based API documentation.
The main utility routes are:
  • GET /lives/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
  • sui-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 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 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:
  • The incoming request sets requestPeerSignatures=true.
  • Peer URLs are configured in PEERS.
  • A peer agrees with the local oracle’s assessment for that request.
Important operational behavior:
  • Peer calls are best-effort.
  • If a peer times out, returns an error, or does not agree with the local result, that peer is skipped.
  • One bad peer does not fail the whole request path.
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:
  • 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.
  • Require API keys on your public endpoints.
  • Use HTTPS for any publicly reachable deployment.
  • Use dedicated peer API keys when exchanging traffic with other oracle operators.
  • 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 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:
  • 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 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:
  • HTTP_PORT is optional if your platform injects PORT. The server resolves ports in this order: HTTP_PORT, then PORT, then 3000.
  • API_KEYS is optional in code, but strongly recommended for any deployment that is reachable over a network.
  • PEER_REQUEST_TIMEOUT_MS defaults to 5000.
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

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:
  • /documentation
  • /lives/v1
/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:
  • 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:
  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.
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:
  • GET /lives/v1 returns {"status":"ok"}.
  • GET /chains/v1 returns the chains expected for your selected ENVIRONMENT when called with a valid x-api-key if API_KEYS is configured.
  • GET /documentation loads the Swagger UI.
  • Your logs show the service started successfully.
  • Your logs show the signer address you expect.
Then test at least one real attestation flow, using a valid x-api-key if API_KEYS is configured.

​
Operational monitoring

At minimum, monitor:
  • Container restarts.
  • Request latency.
  • Error rate by endpoint.
  • Peer timeout and peer mismatch warnings.
  • 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.