RelayGuard

Security Mode

Security Mode extends RelayGuard from availability failover into RPC integrity protection — verifying that the data your app receives is consistent across independent providers before it acts on it.

Core principle

For security-critical reads, fail closed when independent providers cannot agree. Never silently fall back to a single provider when quorum is unavailable.

When to use it

  • Verifying deposits, withdrawals, or bridge messages from chain state
  • Reading receipts or logs before signing or broadcasting transactions
  • Protecting sensitive contract reads — token balances, governance votes, price feeds
  • Any workflow where a poisoned or lagging RPC response could cause financial loss

How it works

  1. Configure at least three providers in distinct independence groups.
  2. Enable Security Mode per chain in the dashboard. Choose which methods and contracts require quorum using the method policy and contract policy panels.
  3. Call your normal RPC endpoint — POST /rpc/:chain. The gateway decides proxy vs. quorum automatically based on your policy. No separate endpoint or client change needed.
  4. For quorum methods, the gateway fans out to multiple providers in parallel and requires agreement (default 2-of-3) on the response payload.
  5. If providers disagree or too few are healthy, the gateway returns an error — your app should not proceed.

Method policy

Configure which JSON-RPC methods require quorum in the Security Mode section of the dashboard. Methods not in your policy route normally via proxy.

Recommended defaults: eth_getTransactionReceipt (confirming a TX landed), eth_getStorageAt (raw contract storage), eth_getLogs(event logs — forged or missing logs can hide deposits and exploits), and eth_getCode(contract bytecode — detect a provider lying about whether an address is a contract). These are the calls where a wrong answer causes direct harm.

You can add any other method — eth_getBalance, eth_getTransactionByHash, custom methods — depending on your app's security requirements.

Contract-level policy

For finer control, import a contract ABI and set quorum or deny rules per function. This lets you say:

  • "Require quorum on balanceOf for this USDC contract."
  • "Deny any eth_call to applyRampUpdates on this CCIP Router."
  • "Apply quorum to all reads on this vault contract, proxy everything else."

Contract rules take priority over method policy. Import ABIs directly from Etherscan (where Etherscan V2 coverage exists) or upload manually for any contract.

Policy rule format

Rules resolve from most specific to least specific:

  1. eth_call + specific contract + specific function — exact match
  2. eth_call + specific contract + wildcard — all functions on that contract
  3. Method-level rule — applies to all eth_call regardless of target
  4. Built-in defaults

Read finality (reorg-safe reads)

By default, quorum reads run against the latest block. Because providers sit at slightly different chain tips, a latest read can both (a) return state that later reverts in a reorg, and (b) look like a disagreement when providers are simply one block apart.

Set a chain's read finality to safe or finalizedin the dashboard and RelayGuard rewrites a moving block tag (latest/pending) to that finalized tag before fanning out — so every provider queries the same finalized block. Verified reads become reorg-safe, and tip-skew false-divergence disappears. Explicit block numbers, earliest, and blockHash-pinned eth_getLogsqueries are left untouched. The trade-off is slightly staler data (finalized lags the tip), so it is opt-in per chain; latest remains the default.

Reorg & fork detection

Alongside quorum on reads, RelayGuard continuously samples block hashes from your providers at a confirmation depth and watches for two things:

  • Provider forks — independent providers reporting different hashes for the same block height, meaning one is serving a minority or forged chain.
  • Chain reorgs — a block hash you previously observed changing, so data your app may have acted on was reverted.

Both surface as events in your dashboard and can alert Slack, email, or a signed webhook. Detection is monitoring-only — it never changes which provider serves your traffic.

Provider trust score

RelayGuard continuously runs honesty canaries — it asks every provider for the hash of a deep, finalized block (one whose answer is fixed and known) and checks it against the cross-provider consensus. A provider that returns the wrong answer is serving bad data.

Each provider gets a rolling trust score (0–100, graded A–F) combining that honesty signal with live reliability — health, latency, and block lag — shown per provider on your Insights dashboard. It answers a question single-provider setups can't: is this provider actually telling me the truth over time?

The honesty record also protects your routing: a provider that fails canaries is automatically deprioritized in weighted selection, so traffic shifts toward the providers proving themselves trustworthy. It's floored — trust alone never fully removes a provider (availability is still governed by health checks) — and has no effect until enough canary data accumulates.

Deny rules

Set a function's policy to Deny to block that call at the gateway before it reaches any provider. The gateway returns 403 policy_denied. Useful for preventing privileged contract operations from being called through the gateway at all.

What Security Mode helps with

  • RPC poisoning and manipulated responses
  • Provider divergence and data inconsistency
  • Unsafe silent fallback to one degraded provider
  • Block lag on security-critical reads
  • Acting on reorg-able state — with safe/finalized read finality
  • Unauthorised calls to sensitive contract functions (via deny rules)

What it does not solve

  • Compromised private keys or application servers
  • Smart contract bugs or flawed verifier logic
  • All providers sharing the same bad upstream or colluding
  • Write operations — eth_sendRawTransaction is never quorum-checked or retried

Verifiable receipts

Every Security Mode response carries a set of X-RelayGuard-* headers describing the quorum outcome, so your application — or an autonomous agent — can verify the read was checked rather than trusting it blindly. The metadata is delivered as headers, not inside the JSON-RPC body, so strict clients (ethers, viem, cast) are unaffected.

X-RelayGuard-Verified: true            // independent providers agreed
X-RelayGuard-Outcome: met              // met | absent | divergence | not_converged | unavailable
X-RelayGuard-Confidence: high          // high | medium | none
X-RelayGuard-Quorum: 3/3               // matched / compared
X-RelayGuard-Required: 2               // groups required to agree
X-RelayGuard-Independent-Groups: 3

For high-assurance flows — bridges, payments, agent-driven transactions — assert on X-RelayGuard-Verified: true (or a minimum Confidence) before acting on a read.

Signed receipts

Plain headers can be forged by anything between you and the gateway. For tamper-evident proof, each Security Mode response also carries a signed receipt — a compact, canonical attestation signed with RelayGuard's Ed25519 key:

X-RelayGuard-Receipt: <base64url canonical receipt>
X-RelayGuard-Signature: ed25519=<base64url signature>

The receipt binds the request id, chain, method, outcome, quorum counts, a hash of the returned result, and a timestamp. Fetch the public key once from GET /receipts/public-key and verify the signature over the receipt bytes — anyone, including a third-party auditor, can prove RelayGuard actually verified a given read. This turns "verified" from a claim you trust into one you can check.

Exportable audit log (Team)

For compliance and post-incident disputes, RelayGuard keeps a tamper-evident transparency log. Receipts are batched and committed as a signed Merkle root; the control plane stores compact leaves (a hash + metadata — never your result data) and the signed roots. From the dashboard you can export your receipt log over any time range, and request a Merkle inclusion proof for any single receipt — a short path that proves that exact read was committed under a signed root, verifiable against the public key. (Team plan.)

Events & alerts

Divergence, quorum-unavailable, and unsafe-degradation-blocked events are recorded per workspace and visible in the dashboard — both as a 30-day integrity summary (reads verified, bad data caught) and a notable-event timeline. You can route these alerts to Slack, email, or a signed webhook (PagerDuty, Opsgenie, or your own endpoint — each delivery carries an X-RelayGuard-Signature HMAC you can verify).

Setup checklist

  1. Add 3+ providers in 3 independent groups — see Quickstart
  2. Enable Security Mode in the dashboard for your chain
  3. Configure method policy — at minimum enable eth_getTransactionReceipt
  4. Optionally: import contract ABIs and set per-function quorum or deny rules
  5. Test: send a quorum method request and check the dashboard for a security_quorum_met event