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
| Problem | Question it answers |
|---|---|
| Bootstrap | Where does the first trusted consensus state come from? |
| Catch-up | How does a restarted or lagging relayer regain currency? |
| Request sync | How 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:
- Operator supplies the trusted checkpoint (
AddSourceChain.consensus_params). Ingestwalks forward from the checkpoint, building the consensus mirror.CheckpointManagerpushes the initialUpdateConsensusStateso the light client has a verifiable starting point.- Normal operation begins; the mirror snapshots periodically (Stateful relayer § State classification).
Catch-up / recovery paths
| Scenario | Path |
|---|---|
| Crash restart (short gap) | Reopen the op queue (WAL replay); resume leased proving jobs; restore mirror from latest snapshot + replay forward |
| Extended downtime | Snapshot + 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 client | Normal 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.
| Rule | Mechanism |
|---|---|
| Registration | Validate the Router-subscription precondition via DestQuery before accepting. Otherwise messages would be relayed but never dispatched |
| Mode check | At 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 |
| Startup | Reload the request store; re-validate each request against the Router's ApplicationRegistry |
| Steady state | Periodic re-validation; requests whose application has unregistered on the Router are expired (dormant-request policy, Relayer § Security Considerations) |
| Reorg safety | Validate 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
| Question | Linked 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
- Relayer-architecture: the plugins (
RequestRegistry,CheckpointManager) that execute these flows - Stateful relayer: what is persisted vs rebuilt
- Consensus state update: the update policy that makes a lagging light client safe
- Messenger § Security model: why bootstrap trust mirrors the light client's own initialization