TrustlessGuides

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_field extraction 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 to VerifyMessage as 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 byConcretely
Descriptor shapesource = Ethereumrlp, EIP-2718 0x02 prefix, receipt schema
Verifier runtimedestination = Cosmosa 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… (the receiptsRoot)
  • 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 0x02 prefix, RLP-decodes per schema, navigates target_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 byConcretely
Descriptor shapesource = Cosmosprotobuf, no prefix, Cosmos Tx schema
Verifier runtimedestination = Ethereuman 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.messages are Any-wrapped (type_url + value bytes), so a production descriptor decodes the Any then the inner MsgSend. The inlined MsgSend fields above keep the focus on descriptor mechanics, not protobuf Any plumbing.

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's txs root / 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 txs root (the proof), then
  • on-chain, in EVM bytecode: protobuf-decodes the Tx per schema, navigates target_field = 1.1[0], and returns the extracted MsgSend message.

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

StageA: Eth → CosmosB: Cosmos → Eth
Source leafRLP receipt (EIP-2718, 0x02 prefix)protobuf Tx (no prefix)
Dialect / path stylepositional: [3][0]tagged: 1.1[0]
Descriptor lives inCosmos Router ApplicationRegistryEthereum Router ApplicationRegistry
VerifyMessage runs inCosmos SDK module (Go)EVM contract (bytecode)
Finality verifiedCasper FFGTendermint ⅔+ pre-commits
Verification modedirect feasible (BLS12-381 native on Cosmos)zk-proof (no Ed25519 precompile on the EVM)
Decode costcheap (RLP)heavy (protobuf-on-EVM, tmp#6)
What crosses the wire(commitment_path, target_field, root) + raw bytes + proof, never the descriptor(identical)
application encodingbech32 (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.

  • Common-types: EncodingDescriptor, MessageID, the schema/path grammar, and "Where descriptor evaluation runs"
  • Light Client: VerifyMessage and 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

On this page