TrustlessGuides

For Chain Integrators

Implement a ChainModule to onboard a new source chain.

This guide is for teams making a new blockchain available as a source chain in TMP, so that data committed on it can be verified and consumed on destination chains. The core protocol never changes for a new chain; like IBC's client types, all chain-specific knowledge lives behind a plug-in boundary.

An integration has three deliverables:

  1. A ChainModule: the relayer plug-in that knows how to ingest, finalize, and extract from your chain (Relayer spec § Per-chain modules).
  2. A consensus verifier: the code that runs your chain's consensus verification for the light client: on-chain light-client code in direct mode, or zk circuits (zkVM programs) plus a proof verifier in zk-proof mode (Light Client § Verification mode).
  3. A Light Client deployment on each destination chain, registered with that chain's Router.

Prerequisites

Your chain is integrable if it has:

  • A deterministic finality rule. A predicate that decides, from chain data alone, whether a block is finalized (Casper FFG justification, ⅔+ Tendermint pre-commits, etc.). Probabilistic-only finality needs a chain-specific policy decision first.
  • A block-level commitment structure. Header-committed roots over the data to be transported (receipts trie, app_hash, state commitments).
  • A provable consensus-state transition. Validator-set / sync-committee updates that can be extracted from finalized blocks, so the light client's view can advance (Consensus Verification).
  • Canonical-fork node access. Reliable RPC/p2p endpoints; the relayer's canonical-fork connection is a load-bearing security assumption (Messenger § Security model).

The five ChainModule slots

Each ChainModule fills five slots; everything else (request store, proof queues, signing, retry, metrics) is shared relayer infrastructure (Relayer spec § Per-chain modules).

SlotYou provideKey decisions
IngestHow to pull finalized blocks, headers, attestations, validator-set updates from canonical nodesWhich APIs (e.g., Beacon API + execution RPC vs Tendermint RPC); cross-checking across multiple endpoints
Finality ruleThe predicate deciding a block is finalizedMust match exactly what the verifier checks: this is the ground truth replayed on-chain (direct) or in-circuit (zk-proof)
Commitment subtree mapWhich subtrees of a block carry which kinds of leavesDefines what is messageable: each mapped subtree becomes addressable via commitment_path
Consensus state extractorHow to compute the next ConsensusState from a finalized blockWhat goes in the state (validator set + weights, checkpoint roots, params); when checkpoints stop being compatible with new blocks
Verifier bindingThe consensus verifier for your chain, in the mode each destination needsMode per destination: direct where the destination has the primitives for your signature scheme at acceptable cost, zk-proof otherwise; in zk-proof mode also the backend (SP1, RISC Zero, gnark, …) and merged vs separated composition (below)

Define your chain's protocol surface

Beyond the module itself, an integration fixes three chain-specific definitions that applications and the Router will depend on:

  • chain_id. A stable string identifier (e.g., ethereum-mainnet), used by the Router's light-client registry and carried with every message.
  • commitment_path format. How a leaf is addressed within your block's commitment structure, encoding both subtree and position (e.g., receipts_trie/42). It is part of the MessageID (Common-types § Message), so it must be unambiguous: one path, one leaf.
  • Leaf schemas. The documented encoding and structure of each leaf type your subtrees commit (e.g., the EIP-2718 receipt layout under RLP, a Cosmos transaction under Protobuf). Applications write their MatchPatterns and read their EncodingDescriptors against these schemas (Common-types § EncodingDescriptor), and the on-chain verifier decodes the proven bytes against them. So publish them precisely, version them, and keep the set minimal: every encoding and schema the verifier accepts is audit surface.

Verifier: what must be verified

Choosing the mode. Decide per (source, destination) pair. Direct mode needs the destination to verify your validators' signature scheme natively at acceptable gas, e.g. BLS12-381 aggregate signatures on an EVM with EIP-2537, or on a Cosmos chain with native BLS. Where it cannot — e.g. Ed25519 validator signatures on the EVM, which has no Ed25519 precompile — use zk-proof mode. The two operations below are the same in both modes; only where the check runs differs.

Your verifier implements the two operations the light client exposes (Light Client § Mechanism):

VerifyMessage. The two-step claim:

  1. Block Verification. The block is finalized under your finality rule, anchored at a stored checkpoint (CompatibleConsensusState).
  2. Block Inclusion Verification. The raw leaf bytes at commitment_path exist under the root committed in the verified block's header. The verification stops at the raw bytes; the descriptor-driven extraction (strip prefix, decode via schema, read out target_field) runs on-chain in the verifier contract afterwards, not inside your consensus verifier. See Light Client § VerifyMessage (step 3) and Common-types § "Schema language & path expressions" for the normative decode/reject rules. So your verifier only needs to establish inclusion of opaque bytes.

UpdateConsensusState. Finality of a block, plus correct extraction of the new consensus state from it.

Composition is an implementation choice (Light Client § VerifyMessage): a merged verifier yields one check per message; separated Block/Inclusion verifiers allow modular design and independent upgrades. Rung 1 of the light client's cost amortization requires separated composition; a merged circuit pays one proof per leaf. Either way the verifier establishes only finality + raw-byte inclusion; descriptor-driven decoding is on-chain verifier-contract code, never part of the consensus verifier. Support the light client's cost amortization: when a block hash is already stored, the finality check can be skipped. Design the verifier so inclusion can be verified against a stored block hash alone, and the relayer can batch same-block messages (Light Client § Cost amortization).

The full consensus state is the private witness in zk-proof mode: on-chain only its commitment is stored, so the prover must accept the off-chain mirror as input (Relayer spec § Mechanism). In direct mode the light client also stores only commitments plus a small working set (e.g. the current and next validator set); the relayer re-supplies older state inside the payload, checked against the stored commitment (Light Client § State).

Onboarding sequence

Roles: you (integrator), the Security Admin (security council for the destination deployment), the relayer operator.

  1. You: choose the verification mode per destination (§ Verifier), implement the ChainModule against the shared relayer interfaces, and build the verifier for that mode (light-client code in direct mode, circuits plus the proof verifier in zk-proof mode).
  2. You + auditors: audit the verifier: the finality check, the inclusion proof per mapped subtree (raw-byte inclusion only), and the state extractor. Light-client bugs (direct mode) and under-constrained circuits (zk-proof mode) are the dominant failure modes; the soundness of the whole chain's integration rests here — which is exactly why descriptor-driven decoding is kept out of the consensus verifier and audited separately as on-chain verifier-contract code (per supported encoding; see Common-types § "Schema language & path expressions").
  3. Security Admin: deploy the light client on the destination and call InitializeLightClient(InitialConsensusState, Height) with a trusted checkpoint — exactly once; this is the root of trust for your chain (Light Client § InitializeLightClient). In zk-proof mode, deploy the proof-verifier contract (verifying key) the light client calls alongside it.
  4. Security Admin: call RegisterLightClient(chain_id, light_client) on the destination Router (precondition: the light client is initialized).
  5. Relayer operator: call AddSourceChain(chain_id, consensus_params, endpoints) on the relayer (precondition: the light client is registered on the Router), and configure verification_mode for the (source, destination) pair to match the deployed light client (plus prover_backend in zk-proof mode). Ingestion starts; the consensus mirror fills.
  6. Relayer: submit the first UpdateConsensusState to seed checkpoints beyond the genesis checkpoint.
  7. End-to-end check: register a test application with a simple filter, emit matching data on the source chain, and confirm QueryStatus reaches delivered and the callback fires.

Operational responsibilities

  • Canonical-fork endpoints. Run/contract multiple independent nodes and cross-check; endpoint poisoning is the realistic attack on a relayer (Relayer spec § Failure modes).
  • Checkpoint cadence. The relayer must push UpdateConsensusState before stored checkpoints stop being compatible with new blocks (sync-committee rotation, validator-set churn). Otherwise message verification stalls until a state update lands. The frequency/security tradeoff is configured per chain (Consensus state update).
  • Hard forks. A consensus change on your chain means verifier upgrades (light-client code or circuits), deployed by the Security Admin (timelocked). Plan verifier versioning from day one.
  • Pause path. The Security Admin can disable your chain's light client on the Router (enabled = false) without removing it — the incident-response mechanism if your chain halts or forks unexpectedly.

Testing checklist

  • Finality predicate agrees with the verifier on the same inputs (differential test)
  • Inclusion proofs for every mapped subtree, including edge leaves (index 0, last index, single-leaf trees)
  • On-chain descriptor extraction per supported encoding: correct target_field read out; prefix stripped; every reject reason in Common-types § "Evaluation & rejection semantics" reverts (malformed descriptor, dialect/path mismatch, prefix mismatch, decode failure, type mismatch, out-of-range path, absent target)
  • Wrong/incompatible checkpoint rejected; stored-block-hash amortization path verified
  • UpdateConsensusState across a validator-set / sync-committee rotation boundary
  • Replayed submission reverts at the Router (exactly-once on MessageID)
  • Endpoint divergence detected (one endpoint serving a non-canonical fork)
  • Direct mode: the on-chain consensus check fits the destination's gas/compute budget at the largest validator-set / participation size the finality rule allows
  • zk-proof mode: every constraint has a negative test that fails without it; a proof from the configured prover_backend verifies against the deployed on-chain proof verifier
  • Descriptor Walkthrough: a leaf schema traced end-to-end as both a source (Eth→Cosmos) and a destination decode (Cosmos→Eth)
  • Relayer: the ChainModule boundary and relayer pipeline
  • Light Client: the verification layer your verifier plugs into
  • Router: light-client registry and dispatch
  • Common-types: MessageID, commitment_path, EncodingDescriptor
  • Consensus state update: checkpoint advancement
  • Messenger: architecture overview, trust model, Security Admin, permissioned relaying

On this page