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:
- A
ChainModule: the relayer plug-in that knows how to ingest, finalize, and extract from your chain (Relayer spec § Per-chain modules). - 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).
- 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).
| Slot | You provide | Key decisions |
|---|---|---|
| Ingest | How to pull finalized blocks, headers, attestations, validator-set updates from canonical nodes | Which APIs (e.g., Beacon API + execution RPC vs Tendermint RPC); cross-checking across multiple endpoints |
| Finality rule | The predicate deciding a block is finalized | Must match exactly what the verifier checks: this is the ground truth replayed on-chain (direct) or in-circuit (zk-proof) |
| Commitment subtree map | Which subtrees of a block carry which kinds of leaves | Defines what is messageable: each mapped subtree becomes addressable via commitment_path |
| Consensus state extractor | How to compute the next ConsensusState from a finalized block | What goes in the state (validator set + weights, checkpoint roots, params); when checkpoints stop being compatible with new blocks |
| Verifier binding | The consensus verifier for your chain, in the mode each destination needs | Mode 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_pathformat. 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 theMessageID(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 theirEncodingDescriptors 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:
- Block Verification. The block is finalized under your finality rule, anchored at a stored checkpoint (
CompatibleConsensusState). - Block Inclusion Verification. The raw leaf bytes at
commitment_pathexist under the root committed in the verified block's header. The verification stops at the raw bytes; the descriptor-driven extraction (stripprefix, decode viaschema, read outtarget_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.
- You: choose the verification mode per destination (§ Verifier), implement the
ChainModuleagainst 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). - 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").
- 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. - Security Admin: call
RegisterLightClient(chain_id, light_client)on the destination Router (precondition: the light client is initialized). - Relayer operator: call
AddSourceChain(chain_id, consensus_params, endpoints)on the relayer (precondition: the light client is registered on the Router), and configureverification_modefor the (source, destination) pair to match the deployed light client (plusprover_backendin zk-proof mode). Ingestion starts; the consensus mirror fills. - Relayer: submit the first
UpdateConsensusStateto seed checkpoints beyond the genesis checkpoint. - End-to-end check: register a test application with a simple filter, emit matching data on the source chain, and confirm
QueryStatusreachesdeliveredand 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
UpdateConsensusStatebefore 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_fieldread 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
-
UpdateConsensusStateacross 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_backendverifies against the deployed on-chain proof verifier
Related documents
- Descriptor Walkthrough: a leaf schema traced end-to-end as both a source (Eth→Cosmos) and a destination decode (Cosmos→Eth)
- Relayer: the
ChainModuleboundary 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