Router
This document specifies the design of the Router, the on-chain dispatching component of the Trustless Messaging Protocol.
What is it: The Router is the on-chain entry point for relayer submissions and the dispatcher for verified messages. It owns two registries: one mapping each source chain to its light client, and one mapping incoming messages to the destination applications that should receive them. The Router itself does no cryptographic work; it routes submissions to the right light client for verification, and routes verified messages to the right application for consumption.
Features
Role in the system. The Router sits at the boundary between the off-chain Relayer and the on-chain light-clients and applications. It is the only on-chain component that holds direct trust relationships with both the relayer (auth) and the destination applications (delivery).
Functionalities:
| Function | Description |
|---|---|
Authentication | Authenticate incoming submissions from the relayer |
Routing | Route each submission to the correct light client based on the source chain identifier |
Delivery | After successful verification, deliver the verified message to the registered destination application |
Light-client registry | Maintain the registry of light clients (one per supported source chain) |
Application registry | Maintain the registry of applications and their subscription patterns |
Exposed APIs:
| API | Description |
|---|---|
Submit | Called by the relayer to submit a (message, proof) or (consensus state, proof) bundle |
RegisterLightClient | Admin operation to register a light client for a new source chain |
RegisterApplication | Application-side operation to subscribe to messages matching a pattern |
UnregisterApplication | Application-side operation to unsubscribe |
Stateless verification. The Router does no proof checking itself; it delegates to the light client. This keeps the Router thin and lets it be reused across heterogeneous source chains.
Permissioned submission. Only Security-Admin-authorized relayers can call Submit. See Security Model.
Mechanism
The Router is a thin dispatching layer with two lookup tables. When a relayer submits a proof, the Router:
- Authenticates the caller (must be an authorized relayer).
- Reads the source chain identifier from the submission and looks up the corresponding light-client in
LightClientRegistry. - Forwards the submission to that light client (
VerifyMessageorUpdateConsensusState). - If the submission was a
VerifyMessage, the Router takes the one destination application named in the bundle, looks up its registered filter inApplicationRegistry, and calls the light client with that app's registered descriptor. The light client verifies the proof the first time it sees the leaf and caches it, or serves it straight from the verified-leaf cache otherwise. On success the Router checks the returned extracted item against the app's match predicates before invoking itsOnMessagecallback. See § "Filter enforcement" and § "One delivery per submission". - If the call was
UpdateConsensusState, the Router returns success without further dispatch (state updates have no application-level destination).
Detailed design
Data structures
LightClientRegistry entry
Maps a source chain identifier to the address of its on-chain light-client contract.
| Field | Type | Description |
|---|---|---|
chain_id | string | Identifier of the source chain (e.g., ethereum-mainnet, cosmos-hub) |
light_client | address | Address of the light-client contract that verifies this chain's messages |
enabled | bool | Whether this light client is active. The Security Admin can pause a chain without removing it |
verification_mode | enum | (optional, informational) direct or zk-proof. The Router never reads it (proof is opaque to it), but it is the one on-chain place that tells operators and relayers which payload this light client expects |
ApplicationRegistry entry
Maps an incoming-message pattern to the application that should receive matching messages.
| Field | Type | Description | |
|---|---|---|---|
chain_id | string | The source chain whose messages this entry subscribes to | |
match_pattern | bytes | The application's filter: a descriptor (encoding/prefix/schema — how to decode the leaf), an extract pattern (the target_field path, possibly with [*] — which element), and match predicates (field constraints on the decoded item, e.g. source contract address, event signature). Derived from the Relayer's registered filter | |
application | address | Address of the destination application contract | |
callback | string | Function selector or method name to invoke on the application (e.g., onMessage(bytes)) |
A single item can be delivered to several subscribers when they subscribe to the same element (same target_field): one extracted item, delivered to each matching app. Multi-subscriber delivery happens across separate submissions, one per application — not one transaction delivering to all of them (see § "One delivery per submission"). Because all those submissions share the same leaf, only the first pays for the proof; the rest are served from the light client's verified-leaf cache. Applications subscribing to different elements of the same leaf have different target_fields, hence different MessageIDs: distinct deliveries that still share the one leaf proof.
Submission bundle
The payload sent by the relayer in a Submit call.
| Field | Type | Description | |
|---|---|---|---|
chain_id | string | Source chain identifier, used to route to the correct light client | |
op | enum | VerifyMessage or UpdateConsensusState | |
message / consensus_state | bytes | The data item being submitted (only one of these depending on op) | |
application | string | The single destination application this submission delivers to. One submission → one delivery, so gas stays bounded no matter how many apps subscribe to the same item (see § "One delivery per submission"). VerifyMessage only | |
block_hash | string | Hash of the source-chain block containing the item | |
height | uint64 | Block height | |
proof | bytes | The verification payload, interpreted by the light client: the consensus data in direct mode, the zk proof bundle in zk-proof mode. Required only the first time a leaf is verified; omitted when the leaf is already in the light client's verified-leaf cache, and reduced to the inclusion part when the block hash is already stored (light-client § Cost amortization). The light client decides which shape it expects and reverts with LeafNotCached / BlockNotVerified when the payload is too thin (caches may be pruned) | |
compatible_checkpoint | string | Identifier of the stored checkpoint to verify against (see light-client) |
State
Stores:
| Store | Description |
|---|---|
Map<ChainID, LightClientRegistryEntry> | Light clients per source chain |
Map<PatternHash, ApplicationRegistryEntry> | Application subscriptions, indexed for efficient pattern lookup |
Map<MessageID, bool> | Delivered-message log, used to enforce exactly-once delivery (see below) |
Config:
| Parameter | Description |
|---|---|
maintainer | The Security Admin (security council); authorized to register/deregister light clients and rotate relayers |
authorized_relayers | Set of addresses permitted to call Submit. Mirrors (and is the source of truth for) the relayer permissioning that protects against long-range attacks (see Security Model) |
Logic
The Router operates in four phases for each submission:
- Authentication.
msg.sender ∈ authorized_relayers. Reverts otherwise. This is the single trust boundary that enforces permissioned relaying. - Application lookup. Read the single destination
applicationnamed in the bundle and load its registered filter (descriptor+ match predicates) fromApplicationRegistry. - Verification & extraction. Look up the light client for
chain_id, and callVerifyMessagewith the registereddescriptor(from the application's registered filter, not any descriptor the relayer supplied). The light client verifies finality + inclusion of the raw leaf and returns the on-chain-decoded extracted item. Reverts on a bad proof. - Filter enforcement & dispatch. Only on verification success:
- Evaluate the application's match predicates against the extracted item. If they fail, revert
PredicateMismatch: a submission carries exactly one candidate, so reverting blocks no other message, and it rolls back the light client's cache writes of this call. The relayer evaluates the same predicates before submitting, so a mismatch on-chain is a relayer bug, never a normal outcome (decided 2026-10-06). - Check the delivered-message log for replay. If already delivered, skip (exactly-once enforcement).
- Invoke the application's
callbackwith the extracted item. - Mark it delivered in the log.
- Evaluate the application's match predicates against the extracted item. If they fail, revert
Submit
The single entry point used by the Relayer.
API Parameters: see Submission bundle above.
Preconditions:
- Caller is an authorized relayer
- Light client for
chain_idis registered and enabled - For
VerifyMessage: theMessageIDhas not been previously delivered (exactly-once) - For
UpdateConsensusState: the new state's height is greater than any currently stored checkpoint
Effects:
- Forwards to the correct light client for verification, using the named application's registered descriptor
- On
VerifyMessagesuccess: delivers the extracted item to the bundle's named application if the item satisfies its match predicates, marking the delivery in the log (see § "Filter enforcement") - On
UpdateConsensusStatesuccess: no further dispatch. The light client's store is updated as a side effect
RegisterLightClient
Admin operation to onboard a new source chain.
API Parameters:
| Parameter | Description |
|---|---|
chain_id | Identifier of the new source chain |
light_client | Address of the deployed light-client for that chain |
Preconditions:
- Caller is the Security Admin
- The light client at
light_clienthas been initialized (itsInitializeLightClientwas called)
Effects:
- Adds the registry entry, marks
enabled = true
RegisterApplication
Application-side operation. Applications self-register the patterns they want to receive.
API Parameters:
| Parameter | Description |
|---|---|
chain_id | Source chain to subscribe to |
match_pattern | The application's filter: a descriptor (encoding/prefix/schema), an extract pattern (target_field, possibly with [*]), and match predicates on the decoded item; the same filter the Relayer extracts on. The Router passes the descriptor to VerifyMessage as authoritative, accepts the relayer's concrete target_field only as an instance of the pattern, and enforces the predicates before dispatch (see § "Filter enforcement") |
callback | Method on the calling contract to invoke on each matched verified message |
Preconditions:
- The light client for
chain_idis registered and enabled msg.senderis the application contract (or an authorized signer for it)
Effects:
- Inserts an
ApplicationRegistryEntrykeyed by(chain_id, match_pattern) - The application now receives
callback(message)for every verified message matching the pattern
Filter enforcement
"No one can tamper with which data an application receives" requires three on-chain checks, all owned by the Router because the Router owns the application registry:
- Authoritative descriptor (read-recipe). The Router passes the light client the
descriptor(encoding/prefix/schema) the application registered, as an explicitVerifyMessageparameter. The relayer never names a descriptor at all (it isn't carried in the submission), so there is nothing to substitute. Decode/extract runs in the light client (see light-client § VerifyMessage). - Locator instance check (which element).
target_fieldis relayer-supplied (the resolved[*]→index), and it lives in theMessageID. The Router accepts it only if it is an instance of the app's registered extract pattern: byte-equal when the pattern has no[*], otherwise a concrete index substitution. This stops a relayer pointing at an element the app's pattern doesn't cover. - Match predicates on the extracted item. The light client returns the extracted item as raw encoded bytes, still in the leaf's source encoding (light-client § VerifyMessage return value). The Router re-decodes those bytes against the registered schema (the sub-schema rooted at
target_field) and evaluates the application's registered predicates against the resulting decoded field values (e.g.,log.address == USDT,topics[0] == Transfer-sig). The predicate language (operators, typing, the descendant-of-target_fieldconstraint, and[*]index unification) is defined normatively in Common-types § "Match predicates"; the Router evaluates it identically to how the relayer selected the leaf. An item that fails makes the submission revert withPredicateMismatch; nothing is delivered and nothing is cached. This stops a relayer relaying a genuinely-included but off-target leaf (wrong source contract/event).
Together: the proof fixes which bytes, the registered descriptor fixes how they are read, the instance check fixes which element, and the predicates fix whether that element is the one the app subscribed to. None is relayer-controlled. The application's own re-checks (see app-developers) become optional defense-in-depth rather than load-bearing.
The cost is on-chain gas: the light client pays for schema parsing (heaviest for protobuf/borsh), and the Router pays for predicate evaluation against the decoded fields. This is the deliberate trade for trustless extraction. The alternative (decode in the app SDK) is cheaper on-chain but reopens the tampering surface.
One delivery per submission
Each VerifyMessage submission delivers to exactly one application — the one named in the bundle. The Router does not loop over every matching application inside a single transaction.
Why not deliver to all subscribers in one transaction. The set of applications subscribed to an item is open — anyone can RegisterApplication for the same element. A single transaction that delivered to all of them would do work (predicate check + callback) that grows with the number of subscribers, so its gas grows without bound. Past the block gas limit the transaction can no longer be included at all. One popular item would become permanently undeliverable, and one expensive or reverting callback would block every other recipient in the batch.
How multi-subscriber delivery works instead. When several applications want the same item, the relayer sends one submission per application. Cost stays low because the expensive work is never paid per recipient: block verification (the consensus check in direct mode, the zk proof in zk-proof mode) once per block, and the leaf's inclusion proof once per leaf:
- The first submission that touches a leaf carries the
proof. The light client verifies it and caches the verified leaf (keyed by(commitment_path, root); see light-client § Cost amortization). - Later submissions for the same leaf (whether for another application, or for a different element of the same leaf) carry no proof. The light client serves them from the cache: it just re-checks the supplied leaf bytes against the stored commitment, decodes, and extracts.
So each transaction's gas is bounded and independent of how many applications subscribe, while the verification payload is submitted and verified once per leaf rather than once per recipient. This is the same prove-once goal as block- and leaf-level amortization, applied to multi-subscriber delivery.
A cache hit short-circuits verification only — never the per-delivery checks. Skipping the proof skips nothing else. Every delivery, cached or not, still runs the full filter enforcement (descriptor extraction + match predicates, § "Filter enforcement") and the exactly-once delivered-log check on (application, commitment_path, target_field, root) before the callback fires. So a no-proof submission cannot re-deliver an element to an application that already received it, nor reach an application whose predicates the item fails. The cache saves the proof, not the authorization. This is why application lives in the delivery key, not in MessageID: the leaf proof is shared, but the replay check is always per-recipient.
Exactly-once delivery
The Router enforces that a given source item is delivered to a given application at most once, via the delivered-message log: before dispatching, the Router checks whether this delivery has already been processed; if so, it skips. This shields applications from replay even if the relayer submits the same proof twice.
The dedup key is (application, commitment_path, target_field, root): the full MessageID locator plus the recipient. (commitment_path, root) pins one leaf in one finalized block; target_field distinguishes distinct elements within that leaf (so log[0] and log[1] don't collide); and application lets the same element reach every subscriber, each delivered once. The descriptor is not in the key — it is how-to-read, not which-item (see Common-types § "Identity vs. description").
Two keys, two jobs — don't confuse them. The delivery key above is not the same as the light client's verified-leaf cache key, which is just (commitment_path, root), the leaf without target_field (light-client § Cost amortization):
| Key | Question it answers | Granularity |
|---|---|---|
(commitment_path, root) — verified-leaf cache | "Has this leaf's proof already been checked?" | per leaf, shared by every element and every application |
(application, commitment_path, target_field, root) — delivery log | "Has this exact element already been delivered to this app?" | per element, per application |
One leaf proof can back many deliveries; each of those deliveries is still logged — and so replay-protected — once.
The delivered-log is durable — never age-pruned. Because TMP messages stay verifiable at any age (the light client retains all checkpoints and has no expiry; see light-client § Checkpoint compatibility), an old message can always be re-submitted and re-verified. So forgetting a past delivery would reopen replay: the delivered-log must persist every entry indefinitely, growing monotonically with lifetime delivery count. This is the deliberate trade for any-age verifiability, and it is the opposite rule from the verification caches above (block-hash and verified-leaf), which are freely prunable because a miss costs only a re-proof, never correctness. (If on-chain footprint ever becomes a concern, the per-entry log can be replaced by a cryptographic accumulator, with only its root stored on-chain and the relayer supplying non-membership proofs on submit, without weakening exactly-once.)
Cost considerations
The Router itself is cheap: it's a few table lookups and one delegated call. The bulk of the on-chain cost lies in the light client's verification: in zk-proof mode a single pairing_check for Groth16 (or equivalent for other proof systems); in direct mode the consensus check itself (e.g. an aggregate-signature verification). Either is paid once per block, the inclusion proof once per leaf, both amortized across deliveries (light-client § Cost amortization).
A few optimizations are possible but optional:
- Batch dispatch. If a single relayer submission contains multiple messages from the same block, the Router can amortize the block-finality verification (this requires light client cooperation; see light-client § Cost amortization).
- Lazy registry. Applications can register lazily on first use rather than upfront, trading slightly higher first-message gas for cheaper deployment.
Security considerations
| Surface | Risk | Mitigation |
|---|---|---|
Unauthorized Submit calls | Anyone could submit forged proofs, reaching the light client | authorized_relayers whitelist. Without permissioned relaying, the long-range-attack mitigation in Security Model does not hold. |
Malicious application contract reverting on OnMessage | A buggy or malicious application could cause the entire Submit call to revert, blocking valid messages | Wrap each application callback in a try/catch (or equivalent). A failed callback should not revert the verification path; it should just log and skip. The MessageID is still marked delivered. |
| Replay of a previously delivered proof | Application processes the same message twice | Delivered-message log (exactly-once). Reverts on duplicate MessageID. |
| Relayer-chosen descriptor / off-target leaf | Relayer substitutes a descriptor pointing at a different element, or relays a genuinely-included but off-target leaf (wrong source contract/event), so the app acts on data it never subscribed to | Router feeds the light client the app-registered descriptor (not the relayer's) and enforces the app's match predicates against the decoded extracted item before dispatch; a mismatch reverts the submission. See § "Filter enforcement". |
| Light client returning a false success | Forged message gets delivered to applications | The Router cannot defend against this. It trusts the light client's verification result. This is exactly the Security Model's argument for defense in depth: the permissioned relayer adds a second trust boundary so a light client soundness bug alone is not catastrophic. |
| Compromised Security Admin (registers a malicious light client) | Attacker can route a chain's submissions to a fraudulent verifier | Multi-sig Security Admin; timelock on RegisterLightClient; progressive decentralization. See light-client § Security Admin. |
Trust model
The Router itself holds minimal trust. Its correctness reduces to:
- The
authorized_relayersset is correctly managed (Security Admin's responsibility). - The light clients in
LightClientRegistryare correctly deployed and configured (Security Admin + per-chain initialization). - The dispatch logic does not skip the verification step, i.e., the Router never delivers a message without a successful light client return.
- Filter enforcement is not bypassed: the Router always calls the light client with the app-registered descriptor and always checks the extracted item against the app's match predicates before invoking a callback.
Items (3) and (4) are the purely-Router invariants; both are enforced by the implementation and straightforward to audit (no path from Submit to application.callback that bypasses either the light client call or the filter check).
Failure modes
| Failure | Effect | Mitigation |
|---|---|---|
| Light client for a chain is paused / removed | All messages from that chain are blocked at Submit | Operational; Security Admin re-enables when the chain is recovered |
Application's callback reverts | Without a try/catch, blocks legitimate verification | Implementation must wrap callbacks in try/catch; failures are logged but don't fail the submission |
| Authorized relayer is compromised | Attacker can submit forged proofs (but proofs must still be valid — defense in depth) | Security Admin rotates authorized_relayers. See Security Model § "Why Permissioned + Cryptographically Verifiable" |
| Registry corruption (wrong light client address) | Submissions for that chain go to the wrong verifier | Timelock + multi-sig on registry mutations |
Related documents
- messenger: high-level overview of the three components
- Relayer: the off-chain caller of
Submit - light-client: the verifier the Router delegates to
- Common-types: shared
Message/MessageIDdefinitions - Security Model: full trust assumptions and threat analysis
- Trustless-messaging-protocol: the protocol this layer implements