TrustlessProtocol spec

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:

FunctionDescription
AuthenticationAuthenticate incoming submissions from the relayer
RoutingRoute each submission to the correct light client based on the source chain identifier
DeliveryAfter successful verification, deliver the verified message to the registered destination application
Light-client registryMaintain the registry of light clients (one per supported source chain)
Application registryMaintain the registry of applications and their subscription patterns

Exposed APIs:

APIDescription
SubmitCalled by the relayer to submit a (message, proof) or (consensus state, proof) bundle
RegisterLightClientAdmin operation to register a light client for a new source chain
RegisterApplicationApplication-side operation to subscribe to messages matching a pattern
UnregisterApplicationApplication-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:

  1. Authenticates the caller (must be an authorized relayer).
  2. Reads the source chain identifier from the submission and looks up the corresponding light-client in LightClientRegistry.
  3. Forwards the submission to that light client (VerifyMessage or UpdateConsensusState).
  4. If the submission was a VerifyMessage, the Router takes the one destination application named in the bundle, looks up its registered filter in ApplicationRegistry, 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 its OnMessage callback. See § "Filter enforcement" and § "One delivery per submission".
  5. 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.

FieldTypeDescription
chain_idstringIdentifier of the source chain (e.g., ethereum-mainnet, cosmos-hub)
light_clientaddressAddress of the light-client contract that verifies this chain's messages
enabledboolWhether this light client is active. The Security Admin can pause a chain without removing it
verification_modeenum(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.

FieldTypeDescription
chain_idstringThe source chain whose messages this entry subscribes to
match_patternbytesThe 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
applicationaddressAddress of the destination application contract
callbackstringFunction 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.

FieldTypeDescription
chain_idstringSource chain identifier, used to route to the correct light client
openumVerifyMessage or UpdateConsensusState
message / consensus_statebytesThe data item being submitted (only one of these depending on op)
applicationstringThe 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_hashstringHash of the source-chain block containing the item
heightuint64Block height
proofbytesThe 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_checkpointstringIdentifier of the stored checkpoint to verify against (see light-client)

State

Stores:

StoreDescription
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:

ParameterDescription
maintainerThe Security Admin (security council); authorized to register/deregister light clients and rotate relayers
authorized_relayersSet 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:

  1. Authentication. msg.sender ∈ authorized_relayers. Reverts otherwise. This is the single trust boundary that enforces permissioned relaying.
  2. Application lookup. Read the single destination application named in the bundle and load its registered filter (descriptor + match predicates) from ApplicationRegistry.
  3. Verification & extraction. Look up the light client for chain_id, and call VerifyMessage with the registered descriptor (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.
  4. 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 callback with the extracted item.
    • Mark it delivered in the log.

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_id is registered and enabled
  • For VerifyMessage: the MessageID has 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 VerifyMessage success: 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 UpdateConsensusState success: 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:

ParameterDescription
chain_idIdentifier of the new source chain
light_clientAddress of the deployed light-client for that chain

Preconditions:

  • Caller is the Security Admin
  • The light client at light_client has been initialized (its InitializeLightClient was called)

Effects:

  • Adds the registry entry, marks enabled = true

RegisterApplication

Application-side operation. Applications self-register the patterns they want to receive.

API Parameters:

ParameterDescription
chain_idSource chain to subscribe to
match_patternThe 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")
callbackMethod on the calling contract to invoke on each matched verified message

Preconditions:

  • The light client for chain_id is registered and enabled
  • msg.sender is the application contract (or an authorized signer for it)

Effects:

  • Inserts an ApplicationRegistryEntry keyed 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:

  1. Authoritative descriptor (read-recipe). The Router passes the light client the descriptor (encoding/prefix/schema) the application registered, as an explicit VerifyMessage parameter. 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).
  2. Locator instance check (which element). target_field is relayer-supplied (the resolved [*]→index), and it lives in the MessageID. 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.
  3. 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_field constraint, 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 with PredicateMismatch; 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):

KeyQuestion it answersGranularity
(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

SurfaceRiskMitigation
Unauthorized Submit callsAnyone could submit forged proofs, reaching the light clientauthorized_relayers whitelist. Without permissioned relaying, the long-range-attack mitigation in Security Model does not hold.
Malicious application contract reverting on OnMessageA buggy or malicious application could cause the entire Submit call to revert, blocking valid messagesWrap 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 proofApplication processes the same message twiceDelivered-message log (exactly-once). Reverts on duplicate MessageID.
Relayer-chosen descriptor / off-target leafRelayer 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 toRouter 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 successForged message gets delivered to applicationsThe 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 verifierMulti-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:

  1. The authorized_relayers set is correctly managed (Security Admin's responsibility).
  2. The light clients in LightClientRegistry are correctly deployed and configured (Security Admin + per-chain initialization).
  3. The dispatch logic does not skip the verification step, i.e., the Router never delivers a message without a successful light client return.
  4. 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

FailureEffectMitigation
Light client for a chain is paused / removedAll messages from that chain are blocked at SubmitOperational; Security Admin re-enables when the chain is recovered
Application's callback revertsWithout a try/catch, blocks legitimate verificationImplementation must wrap callbacks in try/catch; failures are logged but don't fail the submission
Authorized relayer is compromisedAttacker 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 verifierTimelock + multi-sig on registry mutations

Related documents

On this page