TrustlessProtocol specRelayer

Syncing Relayer

How a Relayer instance reaches (and regains) sync: bootstrap trust, catch-up, and request sync. Resolves Relayer-challenges § 3.2–3.3; the state it rebuilds is classified in Stateful relayer.

Three sync problems

ProblemQuestion it answers
BootstrapWhere does the first trusted consensus state come from?
Catch-upHow does a restarted or lagging relayer regain currency?
Request syncHow does the relayer learn what to relay?

Bootstrap

The first trusted checkpoint is a weak-subjectivity root: obtained out-of-band by the operator, the same trust act as initializing the on-chain light client (the genesis checkpoint registered at RegisterLightClient / AddSourceChain). The relayer and the light client should bootstrap from the same checkpoint so the mirror and the on-chain state never disagree about ancestry.

Invariant: the bootstrap checkpoint must lie within the source chain's weak-subjectivity / slashability window at the time it is used. Whether this is enforced programmatically (reject checkpoints older than the window) or left as operator discipline is an open security decision (Relayer-challenges § 1.3).

Bootstrap sequence:

  1. Operator supplies the trusted checkpoint (AddSourceChain.consensus_params).
  2. Ingest walks forward from the checkpoint, building the consensus mirror.
  3. CheckpointManager pushes the initial UpdateConsensusState so the light client has a verifiable starting point.
  4. Normal operation begins; the mirror snapshots periodically (Stateful relayer § State classification).

Catch-up / recovery paths

ScenarioPath
Crash restart (short gap)Reopen the op queue (WAL replay); resume leased proving jobs; restore mirror from latest snapshot + replay forward
Extended downtimeSnapshot + replay if the gap is within block-cache retention; beyond that, re-bootstrap from a fresh weak-subjectivity checkpoint
New instance joining (same operator)Bootstrap from a fresh checkpoint, or copy a snapshot from a running peer. Peers are same-operator or Security-Admin-authorized, so a snapshot copy adds no new trust
Mirror ahead of the on-chain clientNormal and safe: the optional-update policy (Consensus state update) means the light client lags by design; the relayer only needs a compatible stored checkpoint, not the newest

Request sync

Applications register what to relay at the relayer, via RegisterRelayRequest (Relayer § APIs); the persisted request store is the system of record (Stateful relayer § State classification). The destination Router's ApplicationRegistry is the on-chain cross-check: a request is only valid while its application is the registered subscriber for (chain_id, match_pattern) — the RegisterRelayRequest precondition.

RuleMechanism
RegistrationValidate the Router-subscription precondition via DestQuery before accepting. Otherwise messages would be relayed but never dispatched
Mode checkAt AddSourceChain and at startup, read the LightClientRegistry entry's verification_mode via DestQuery (when the Router publishes one) and compare with the configured verification_mode for that pair; on mismatch fail closed (refuse the chain / Pause it), since every submission would otherwise be rejected on-chain
StartupReload the request store; re-validate each request against the Router's ApplicationRegistry
Steady statePeriodic re-validation; requests whose application has unregistered on the Router are expired (dormant-request policy, Relayer § Security Considerations)
Reorg safetyValidate the precondition against finalized destination state (or after N confirmations on probabilistic-finality chains). Never start proving against a subscription that may be reorged away

A bug in request sync is a liveness failure only: a stale or wrong local request can cause missed messages or wasted prover cycles, never an unauthorized delivery — the Router dispatches only to applications registered in its ApplicationRegistry (Router § RegisterApplication).

Open questions

QuestionLinked challenge
Enforce a programmatic max checkpoint age (weak-subjectivity bound)?Relayer-challenges § 1.3
Backfill semantics: does a new request relay only from registration time, or from an earlier height on request?Relayer-challenges § 3.3
Does explicit RegisterRelayRequest opt-in stay, or should the relayer auto-serve every Router subscription?Relayer-challenges § 2.5

Related documents

On this page