For App Developers
Register a filter, receive verified messages.
This guide is for teams building a destination-chain application that consumes data from another chain: an oracle, a bridge, a deposit handler, a DID registry. You write one callback and two registrations; the protocol delivers source-chain data to your contract with consensus-level verification already done.
What you get per delivery: a payload that is authentic (committed on the source chain), final (in a finalized block), and extracted as you specified (the light client decodes the verified leaf on-chain against your registered descriptor and hands you exactly the item it read out), delivered exactly once per MessageID. You never verify source-chain consensus yourself.
What you don't get: anything flowing back. TMP is one-way: there is no protocol-level ack, timeout, or rollback; those are application-layer responsibilities (see One-way messaging below).
Integration at a glance
1. Design a filter what source-chain data you want (a MatchPattern)
2. Implement a callback your contract's onMessage handler
3. RegisterApplication on the destination Router (on-chain)
4. RegisterRelayRequest with a relayer (off-chain)
5. Receive + decode verified messages arrive at your callbackStep 1: Design your filter
A RelayFilter (Relayer spec § RelayFilter) declares which messages you want extracted from the source chain: a chain_id plus a MatchPattern. The pattern describes the committed leaf's encoding and schema, pins the values a leaf must contain (match), and names which element to extract as your payload (extract).
Example — every USDT Transfer log on Ethereum, extracted from EIP-2718 typed receipts:
{
"encoding": "rlp",
"prefix": "0x02",
"schema": [
{ "type": "uint8" },
{ "type": "uint64" },
{ "type": "bytes256" },
{ "type": "list", "items":
{ "type": "list", "items": [
{ "type": "address" },
{ "type": "list", "items": { "type": "bytes32" } },
{ "type": "bytes" }
]
}
}
],
"match": [
{ "path": "[3][*][0]", "op": "equals", "value": "0xdAC17F958D2ee523a2206206994597C13D831ec7" },
{ "path": "[3][*][1][0]", "op": "equals", "value": "0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef" }
],
"extract": "[3][*]"
}The schema mirrors the receipt layout [status, cumulativeGasUsed, logsBloom, logs]; the match clauses pin a log's address and event signature; extract selects the matched log itself as your payload. See Relayer spec § MatchPattern for the schema language, and ask your chain's integrator docs for the leaf schemas the chain exposes.
equals/notEquals/in compare by numeric magnitude for any field ≤32 bytes, not just fields your schema declares as a numeric type: a value of 0x01 matches a field decoded as 0x0001. This is deliberate: it's what lets you write a value at its natural byte-width (a raw 20-byte address, as in the example above) and have it match a field the schema widens into a 32-byte word, without you having to zero-pad by hand. It also means a leading-zero-byte distinction is never significant for these ops. If your predicate depends on it (rare), compare on prefix instead, which is raw-byte, not numeric.
Step 2: Implement your callback
The Router invokes your registered callback (e.g., onMessage(bytes)) with the verified Message — metadata plus payload (Common-types § Message). The payload is the extracted element from your pattern: for the example above, one log as an [address, topics, data] tuple, not the whole receipt. Your handler is responsible for:
-
Decoding the payload. The
prefix-strip, schema-decode, andtarget_fieldextraction are performed on-chain by the light client verifier against the proven bytes and your registered descriptor (see light-client § VerifyMessage), so the element you receive is exactly the one the proof covers; the relayer cannot re-interpret it. Your handler only needs to decode the inner fields of that extracted item for business logic (e.g., parse a log'sdatainto amounts).metadata.typeis a convenience hint for picking that inner decoder. -
Application semantics. Amount limits, sender allowlists, business-logic idempotency: the protocol proves authenticity and correct extraction, not meaning.
-
Defense-in-depth re-checks (optional). Both correct extraction and your filter's match predicates (e.g., the emitting contract address, event signature) are enforced on-chain before your callback runs: the light client extracts against your registered descriptor, and the Router rejects any item that fails your predicates (router § "Filter enforcement"). Re-verifying them in your handler is now belt-and-suspenders, not required.
One hard rule: don't rely on reverting to get a retry. The Router wraps callbacks in try/catch: a failed callback is logged, skipped, and the message is still marked delivered. Make your handler total: accept the message, then gate your own logic internally.
Your callback runs on a fixed gas stipend that you choose when you register (registerApplication's callbackGasLimit), not the relayer's full remaining gas. Pick it based on what your handler actually does. If it just emits an event, a small value is fine; if it persists a large extracted payload to your own storage, budget for that up front. There's no separate "raise it later" call — running out of gas here has the same "marked delivered, no retry" consequence as any other callback failure, so size it before real traffic arrives.
Step 3: Register on the Router
Call RegisterApplication on the destination Router (Router spec § RegisterApplication):
| Parameter | What to pass |
|---|---|
chain_id | The source chain (must have a registered, enabled light client) |
match_pattern | A pattern matched against incoming MessageIDs. Derive it from your Step 1 filter |
callback | The method to invoke on your contract, e.g. onMessage(bytes) |
The Router matches each verified message against registered patterns — the locator (commitment_path, target_field, root) and the match predicates on the decoded item — and invokes every matching application's callback. Your Router pattern and your relayer filter must correspond: the filter decides what gets extracted and relayed; the pattern decides what gets dispatched to you. A message relayed with no matching subscription is wasted; a subscription with no relaying filter never fires.
Step 4: Register with a relayer
Subscriptions don't relay themselves; ask a relayer to serve you via RegisterRelayRequest (Relayer spec § RegisterRelayRequest):
| Parameter | What to pass |
|---|---|
filter | Your RelayFilter from Step 1 (chain_id + pattern) |
destination | The Router address on your destination chain |
application | Your contract address (identifies your subscription) |
request_id | A unique id you choose, used to query and unregister |
The relayer checks that your application is a registered subscriber on the destination Router before accepting, so complete Step 3 first.
Step 5: Track delivery
QueryStatus(request_id | message_id) on the relayer returns: queued → proving → submitted → delivered, or failed (with reason, after the retry budget is exhausted).
Delivery guarantees on-chain:
- Exactly-once per
MessageID. The Router keeps a delivered-message log and reverts on duplicates, so a replayed proof can never reach your callback twice (Router spec § "Exactly-once delivery"). - One item can go to several subscribers. When several applications subscribe to the same item, each receives its own callback. Each delivery is a separate, independent transaction, so one app's heavy or failing callback never blocks another, and gas can't blow up no matter how many subscribe; the source-chain proof is paid once per leaf and reused across them (Router spec § "One delivery per submission").
One-way messaging: acks and reverts are yours
TMP is one-way, fire-and-forget. The protocol proves that source-chain data arrived at your destination contract — nothing flows back. There is no protocol-level acknowledgment, no delivery receipt on the source chain, no timeout, and no rollback: once your callback is invoked (or fails — it is still marked delivered), the protocol's job is done. If your application needs the source side to react to delivery (release escrow, finalize a transfer, retry, refund), you must build that loop at the application layer.
The guideline:
- An ack is just another TMP message, in the other direction. Have your destination contract emit a result event (e.g.,
Processed(message_id, success)), and have your source-side contract hold its own subscription on the destination chain's events. The ack then arrives with the same guarantees as the original message. Each direction is an independent integration (its own filter, Router registration, and relay request). - Never make source-side state depend on assumed delivery. Structure flows as two-phase: lock/escrow on the source first, act on the destination upon delivery, settle on the source only when the ack message arrives.
- Implement timeouts yourself. Pair every pending action with an app-level expiry, e.g., escrow reclaimable by the sender after N blocks if no ack has been verified. Use block heights or timestamps your own contract reads, not relayer status.
- Reverts are compensating actions, not rollbacks. Delivered state cannot be undone by the protocol. A "revert" is your application processing a nack (or hitting a timeout) and executing a compensating transaction.
- Track a per-message state machine. Key it on
MessageID:pending → delivered → acked / timed-out → settled / compensated. Remember the "delivered but not processed" case: if your destination callback reverted internally, the message is still marked delivered, so your ack event (not the Router's delivery log) is the only signal the business logic actually ran.
Unsubscribing and updating
UnregisterRelayRequest(request_id)stops the relayer serving you; in-flight on-chain submissions still complete.UnregisterApplicationon the Router removes the subscription itself.- To change a filter, update both sides: the relayer request (what gets extracted) and the Router subscription (what gets dispatched). Keeping them in sync is your responsibility.
Common pitfalls
| Pitfall | Reality |
|---|---|
| Updating the relayer filter but not the Router pattern (or vice versa) | The two must correspond: a mismatch silently drops messages (relayed-but-not-dispatched or never relayed) |
Trusting metadata.type for security | It is a decoding hint; validate against the verified payload and metadata.id |
| Reverting in the callback to retry later | The message is marked delivered anyway; you lose it |
| Assuming delivery ordering | Exactly-once is guaranteed; ordering across blocks/messages is not. Key your logic on MessageID |
| Waiting for a protocol-level ack or timeout | There is none: TMP is one-way; build ack, timeout, and compensation flows at the application layer (see above) |
Related documents
- Descriptor Walkthrough: your filter traced end-to-end, both Eth→Cosmos and Cosmos→Eth
- Common-types:
Message,MessageID,EncodingDescriptordefinitions - Router: registration, dispatch, exactly-once delivery
- Relayer: filters, relay requests, delivery status
- Light Client: what is actually proven per delivery
- Messenger: architecture overview and security model