Descriptor Walkthrough
Descriptor Walkthrough — Eth<>Cosmos
How an EncodingDescriptor flows end-to-end, traced once Ethereum→Cosmos and once Cosmos→Ethereum.
This guide answers one question concretely: what does the descriptor actually do, and where does it run, when a message crosses a chain boundary? It traces a real message both ways. The two directions are deliberately mirror images: they make the one rule that governs the descriptor impossible to miss.
The one rule
The descriptor is source-chain-shaped but destination-chain-evaluated.
- Its shape (
encoding/prefix/schema) describes how the source chain committed the leaf. Ethereum commits receipts as RLP; Cosmos commits transactions as protobuf. That never changes with the destination. - Where it is evaluated is the destination chain's native execution environment: an EVM contract or a Cosmos SDK module. The light client establishes finality + inclusion of the raw bytes (natively in direct mode, via a zk proof in zk-proof mode); the prefix-strip / schema-decode /
target_fieldextraction runs on-chain after that step, outside the consensus verifier (and, in zk-proof mode, outside the circuit), in whatever runtime the destination chain uses (see Common-types § "Where descriptor evaluation runs").
So an Ethereum RLP recipe gets decoded inside a Cosmos module written in Go, and a Cosmos protobuf recipe gets decoded inside an EVM contract. Nothing about the descriptor type changes because of the destination — only the runtime that executes it does.
Two more invariants hold in both directions (router § "Filter enforcement"):
- The descriptor is registry-resident, not transported. The authoritative copy lives in the destination Router's
ApplicationRegistry; the Router hands it toVerifyMessageas an explicit parameter. The relayer never names a descriptor. Only the(commitment_path, target_field, root)locator crosses the wire. - The inclusion proof fixes which bytes; then three on-chain checks make delivery tamper-proof: the registered descriptor fixes how they are read, the locator instance check fixes which element, and the match predicates fix whether that element is the one the app subscribed to. None is relayer-controlled.
Direction A — Ethereum → Cosmos
Scenario. USDT (0xdAC17F958D2ee523a2206206994597C13D831ec7) emits a Transfer log on Ethereum. A module on a Cosmos chain (osmosis-1) wants to act on every such transfer.
| Determined by | Concretely | |
|---|---|---|
| Descriptor shape | source = Ethereum | rlp, EIP-2718 0x02 prefix, receipt schema |
| Verifier runtime | destination = Cosmos | a Cosmos SDK light-client module (Go) decoding RLP on-chain |
1. App registers the filter (on the Cosmos Router module)
The Cosmos app calls RegisterApplication on the Cosmos Router. Its match_pattern carries the RLP read-recipe, the extract pattern, and the predicates:
{
"chain_id": "ethereum-mainnet",
"descriptor": {
"encoding": "rlp",
"prefix": "0x02",
"schema": [
{ "type": "uint8" }, // [0] status
{ "type": "uint64" }, // [1] cumulativeGasUsed
{ "type": "bytes256" }, // [2] logsBloom
{ "type": "list", "items": // [3] logs
{ "type": "list", "items": [
{ "type": "address" }, // [0] contract address
{ "type": "list", "items": { "type": "bytes32" } }, // [1] topics
{ "type": "bytes" } // [2] data
]}
}
]
},
"extract": "[3][*]",
"match": [
{ "path": "[3][*][0]", "op": "equals", "value": "0xdAC17F958D2ee523a2206206994597C13D831ec7" },
{ "path": "[3][*][1][0]", "op": "equals", "value": "0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef" }
],
"application": "osmo1app...", // bech32 — the destination is Cosmos
"callback": "on_message"
}This is the authoritative copy of the descriptor. It lives in the Cosmos Router's ApplicationRegistry and never moves.
2. Relayer extracts off-chain (Ethereum side)
The relayer ingests finalized Ethereum blocks, applies the mirror RelayFilter, finds the USDT log at receipt 42, log 0, and produces:
MessageID.commitment_path = "receipts_trie/42"MessageID.target_field = "[3][0]"([*]resolved to matched index 0)MessageID.root = 0x1a2b3c…(thereceiptsRoot)Message.payload = <raw RLP receipt leaf bytes>
The descriptor is not packed in. Only the locator travels.
3. Relayer submits to the Cosmos Router
A Submit bundle (op: VerifyMessage, chain_id: ethereum-mainnet, the Message, the finality+inclusion proof, the compatible_checkpoint) is broadcast to the Cosmos Router module, signed with the relayer's authorized key.
4. Router → Cosmos light-client module, with the registered descriptor
The Cosmos Router authenticates the relayer, looks up the Ethereum light-client module, and calls VerifyMessage passing the descriptor from the registry (step 1) — not anything from the relayer. The module:
- verifies Casper FFG finality + receipts-trie Merkle-Patricia inclusion of leaf 42 (the proof), then
- on-chain, in Go inside the Cosmos SDK module: strips the
0x02prefix, RLP-decodes perschema, navigatestarget_field = [3][0], and returns the extracted log tuple[address, topics, data].
This is exactly the case the EVM-only wording used to miss: there is no EVM here. "Verified by the destination chain's consensus" still holds: it's the Tendermint deterministic state machine doing the decode.
5. Router enforces predicates and delivers
The Router checks the returned tuple against match (address == USDT, topics[0] == Transfer-sig), confirms [3][0] is an instance of the registered [3][*], checks the exactly-once log on (osmo1app…, receipts_trie/42, [3][0], 0x1a2b3c…), and invokes on_message with the extracted log. The Cosmos app decodes only the log's inner fields (from, to, amount) for its own logic.
Direction B — Cosmos → Ethereum
Scenario. A Cosmos chain (cosmoshub-4) commits a MsgSend transferring uatom to a bridge-escrow address. An app on Ethereum wants to react to every such deposit.
This is the mirror image of Direction A, and the more demanding one: a protobuf source recipe decoded inside an EVM contract, the gas-heaviest decode path (tracked separately for a gas estimate: GitHub decentrio/tmp#6).
| Determined by | Concretely | |
|---|---|---|
| Descriptor shape | source = Cosmos | protobuf, no prefix, Cosmos Tx schema |
| Verifier runtime | destination = Ethereum | an EVM contract decoding protobuf on-chain |
1. App registers the filter (on the Ethereum Router contract)
The Ethereum app calls RegisterApplication on the Ethereum Router. The descriptor is the protobuf read-recipe for a Cosmos transaction:
{
"chain_id": "cosmoshub-4",
"descriptor": {
"encoding": "protobuf",
"schema": {
"1": { "name": "body", "type": "message", "fields": {
"1": { "name": "messages", "type": "repeated message", "fields": {
"1": { "name": "from_address", "type": "string" },
"2": { "name": "to_address", "type": "string" },
"3": { "name": "amount", "type": "repeated message", "fields": {
"1": { "name": "denom", "type": "string" },
"2": { "name": "amount", "type": "string" }
}}
}},
"2": { "name": "memo", "type": "string" },
"3": { "name": "timeout_height", "type": "uint64" }
}},
"2": { "name": "auth_info", "type": "message" },
"3": { "name": "signatures", "type": "repeated bytes" }
}
},
"extract": "1.1[*]",
"match": [
{ "path": "1.1[*].2", "op": "equals", "value": "cosmos1bridgeescrow..." },
{ "path": "1.1[*].3[0].1", "op": "equals", "value": "uatom" }
],
"application": "0xApp...", // bytes20 — the destination is Ethereum
"callback": "onMessage(bytes)"
}Note the tagged dialect: fields are protobuf field numbers, paths are f.f[i] steps (vs. Direction A's positional [i] segments). extract: "1.1[*]" selects a message in body.messages; the predicates pin its to_address (field 2) and first coin's denom (field 3[0].1), both descendants of the extracted node, as required (Common-types § "Predicate paths must sit inside the extracted item").
Simplification: real Cosmos
Tx.body.messagesareAny-wrapped (type_url+valuebytes), so a production descriptor decodes theAnythen the innerMsgSend. The inlinedMsgSendfields above keep the focus on descriptor mechanics, not protobufAnyplumbing.
2. Relayer extracts off-chain (Cosmos side)
The relayer ingests finalized Tendermint blocks, applies the mirror filter, finds the matching MsgSend in transaction 7, message index 0, and produces:
MessageID.commitment_path = "txs/7"MessageID.target_field = "1.1[0]"([*]resolved to matched message index 0)MessageID.root = 0x9f8e…(the block'stxsroot / data hash)Message.payload = <raw protobuf Tx leaf bytes>
Again: only the locator travels; the protobuf descriptor stays in the Ethereum registry.
3. Relayer submits to the Ethereum Router
A Submit bundle (op: VerifyMessage, chain_id: cosmoshub-4, the Message, the Tendermint finality+inclusion proof, the compatible_checkpoint) is broadcast to the Ethereum Router contract, signed with the relayer's authorized key.
4. Router → Ethereum light-client contract, with the registered descriptor
The Ethereum Router calls the Cosmos light-client contract's VerifyMessage with the registered protobuf descriptor. The contract:
- verifies the Tendermint ⅔+ pre-commit finality + the inclusion proof of tx 7 against the committed
txsroot (the proof), then - on-chain, in EVM bytecode: protobuf-decodes the Tx per
schema, navigatestarget_field = 1.1[0], and returns the extractedMsgSendmessage.
Mirror of Direction A's step 4: the source recipe is now protobuf and the runtime is now the EVM. This is the expensive direction: on-chain protobuf parsing in EVM gas is the cost the design knowingly accepts for trustless extraction (
decentrio/tmp#6).
5. Router enforces predicates and delivers
The Router checks the extracted MsgSend against match (to_address == bridge escrow, amount[0].denom == uatom), confirms 1.1[0] is an instance of registered 1.1[*], checks exactly-once on (0xApp…, txs/7, 1.1[0], 0x9f8e…), and invokes onMessage with the extracted message. The Ethereum app decodes the inner fields (from_address, amount) for its logic.
Side by side
| Stage | A: Eth → Cosmos | B: Cosmos → Eth |
|---|---|---|
| Source leaf | RLP receipt (EIP-2718, 0x02 prefix) | protobuf Tx (no prefix) |
| Dialect / path style | positional: [3][0] | tagged: 1.1[0] |
| Descriptor lives in | Cosmos Router ApplicationRegistry | Ethereum Router ApplicationRegistry |
VerifyMessage runs in | Cosmos SDK module (Go) | EVM contract (bytecode) |
| Finality verified | Casper FFG | Tendermint ⅔+ pre-commits |
| Verification mode | direct feasible (BLS12-381 native on Cosmos) | zk-proof (no Ed25519 precompile on the EVM) |
| Decode cost | cheap (RLP) | heavy (protobuf-on-EVM, tmp#6) |
| What crosses the wire | (commitment_path, target_field, root) + raw bytes + proof, never the descriptor | (identical) |
application encoding | bech32 (osmo1…) | bytes20 (0x…) |
The columns differ only in source recipe, destination runtime, and verification mode. Every protocol mechanic (registry-resident descriptor, locator-only transport, the three on-chain checks, exactly-once) is identical. That symmetry is the takeaway: the descriptor mechanism is chain-pair-agnostic.
Related documents
- Common-types:
EncodingDescriptor,MessageID, the schema/path grammar, and "Where descriptor evaluation runs" - Light Client:
VerifyMessageand the on-chain decode/extract step - Router: filter enforcement (the three checks) and exactly-once delivery
- Relayer: off-chain extraction that produces the
MessageID - For App Developers: registering a filter and a callback
- For Chain Integrators: adding a new source chain