Common Types
Shared data structures used across the Trustless Messaging Protocol components (Light Client, Relayer, Router).
Consensus state
The consensus state captures the source chain's consensus configuration at a given point in time, e.g., the validator set with corresponding stake weights, the finalized checkpoint root, and any consensus-specific parameters.
Message
The message is the data item being transported from the source chain, identified by a MessageID that uniquely locates it within a specific block.
Message
| Field | Type | Description |
|---|---|---|
metadata | Metadata | The message's identity, routing, and type information |
payload | bytes | At submission, the raw leaf bytes committed on the source chain; at delivery, the element the verifier extracted from them per the descriptor and target_field. The application decodes only the extracted item's inner fields for its own logic |
Metadata. Information attached to the message, used to verify and route the message
| Field | Type | Description |
|---|---|---|
id | MessageID | The unique identifier and locator for this message |
type | string | The type of the message, if it conforms to a commonly used format (e.g., contract_event, transaction, state_entry). A convenience hint for picking the decoder for the extracted item's inner fields |
from | string | The source chain the message originated from (chain identifier) |
to | string | The destination contract the message is addressed to (target application address) |
MessageID. Uniquely locates the message within a block's commitment structure.
| Field | Type | Description |
|---|---|---|
commitment_path | string | The full commitment path of the leaf containing the message. The format is chain-specific. |
target_field | string | A path expression locating the target element within the decoded leaf. Together with commitment_path + root, completes the locator. Grammar: § "Schema language & path expressions" |
root | string | The root hash of the specified subtree as committed in the block header. Used to anchor the inclusion proof |
Identity vs. description. The locator (commitment_path + target_field + root) is the message's identity. commitment_path + root pin one leaf in one finalized block; target_field pins which element within that decoded leaf. Replay protection keys on exactly these three — the full MessageID — and the Router adds application per recipient, so that several subscribers can each receive the same item (see router § "Exactly-once delivery"). target_field is required in the key: drop it and two distinct elements of one leaf (e.g. two logs in one receipt) collide, silently dropping the second.
The descriptor is not part of identity — it only says how to read the bytes, and the same leaf can be read by more than one descriptor (e.g. a receipt-status byte as uint8 or bool; a log's data blob as opaque bytes or as uint256). Identity is about which item, not how it is read.
Locator and descriptor are not relayer-free at delivery. Neither the relayer's resolved target_field nor the descriptor is trusted blindly. The Router enforces both against the application's registration before delivery (see § "Where descriptor evaluation runs" below and router § "Filter enforcement"):
- the
descriptor(encoding/prefix/schema) is taken directly from the registry (the relayer never supplies one), so it is registered by construction; and - the
target_fieldinMessageIDmust be an instance of the app's registered extract pattern (byte-equal when the pattern has no[*], otherwise a concrete[*]→index instantiation, per § "Wildcards and index unification"), with the app's match predicates satisfied.
EncodingDescriptor. The read-recipe for a leaf: how to decode its bytes. It carries no locator; which element to extract is MessageID.target_field, a separate top-level field.
| Field | Type | Description |
|---|---|---|
encoding | string | The encoding scheme used to serialize the leaf data (e.g., rlp, protobuf, borsh, abi) |
prefix | string | Optional byte prefix before the encoded payload (e.g., EIP-2718 transaction type byte). If present, must be stripped before decoding |
schema | Schema | The structure of the encoded leaf. For positional encodings (RLP), fields are unnamed and identified by index. For tagged encodings (Protobuf), fields are identified by field number. Normative grammar in § "Schema language & path expressions" below |
Where descriptor evaluation runs. The proof attests finality and inclusion of the committed raw bytes only. Decoding per the descriptor (prefix-stripping, schema decoding, target_field extraction) runs on-chain in the destination's native execution environment (EVM contract / Cosmos SDK module) — not in the consensus verifier (light-client check or zk circuit), and not delegated to the receiving application's SDK. The verifier delivers the already-extracted target item, so neither the relayer nor the application can choose a different element than the one the proof covers.
Two properties make this tamper-proof, and both are required:
- Decode the proven bytes, on-chain. The verifier strips the
prefix, decodes perencoding/schema, and navigatestarget_fieldagainst the exact bytes whose inclusion the proof attests. This is deterministic execution on the destination chain, verified by its consensus. A malicious relayer cannot substitute a decoded payload. - Pin the read-recipe and the locator to the application's filter. Neither is relayer-chosen at delivery. The
descriptor(encoding/prefix/schema) is taken directly from the app's registration (the relayer never names one), so it is registered by construction. Thetarget_fieldis relayer-supplied (the resolved[*]→index), but 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 instantiation, per § "Wildcards and index unification") and the match predicates hold. Without this, a relayer could keep the proven bytes but pointtarget_fieldat a different validly-included element (e.g., a different log in the same receipt) and still pass verification.
Keeping decoding in the verifier's host environment (rather than the consensus verifier) still avoids the dominant class of under-constrained circuit bugs and keeps new-encoding support a library concern, not a circuit concern, independent of whether that host is an EVM contract or a Cosmos module. The cost it accepts is on-chain compute for schema parsing — cheap for rlp, heavy for protobuf/borsh — and the verifier must ship a parser for every supported encoding.
Schema examples by encoding. These show the EncodingDescriptor (the read-recipe); the paired MessageID.target_field that locates the element is shown alongside.
RLP (Ethereum receipt) — positional, unnamed fields:
{
"encoding": "rlp",
"prefix": "0x02", // EIP-2718 transaction type byte (type 2 = EIP-1559)
"schema": [
{ "type": "uint8" }, // [0] status
{ "type": "uint64" }, // [1] cumulativeGasUsed
{ "type": "bytes256" }, // [2] logsBloom
{ "type": "list", "items": // [3] logs — list of log entries
{ "type": "list", "items": [ // each log entry is a positional list:
{ "type": "address" }, // [0] contract address
{ "type": "list", "items": { "type": "bytes32" } }, // [1] topics
{ "type": "bytes" } // [2] data
]
}
}
]
}Paired locator: MessageID.target_field = "[3][0]" → logs (element 3) → first log (element 0).
Protobuf (Cosmos transaction) — tagged, named fields:
{
"encoding": "protobuf",
"schema": {
"1": { "name": "body", "type": "message", "fields": {
"1": { "name": "messages", "type": "repeated message" },
"2": { "name": "memo", "type": "string" },
"3": { "name": "timeout_height", "type": "uint64" }
}
},
"2": { "name": "auth_info", "type": "message" },
"3": { "name": "signatures", "type": "repeated bytes" }
}
}Paired locator: MessageID.target_field = "1.1[2]" → body (field 1) → messages (field 1) → 3rd element.
Schema language & path expressions
schema and target_field are shown by example above; this section is their normative definition. The grammar comes in two dialects keyed by encoding:
| Encoding | Dialect | Fields identified by | Path style |
|---|---|---|---|
rlp | positional | order (index) | [i] segments |
abi | positional | order (index) | [i] segments |
borsh | positional | order (index) | [i] segments |
protobuf | tagged | field number | f / f.f / f[i] |
Type system
A scalar type is one of:
| Type | Meaning |
|---|---|
uintN | Unsigned big-endian integer; N ∈ {8,16,…,256}, multiple of 8 |
intN | Signed (two's-complement) integer; N as above |
bool | Single byte, 0x00 / 0x01 |
bytesN | Fixed-length byte string of exactly N bytes; N ≥ 1 (e.g. bytes32, bytes256) |
address | Chain-specific account alias (EVM: bytes20) |
bytes | Variable-length byte string |
string | Variable-length UTF-8 text |
Composite types: list (positional dialect) and message (tagged dialect).
Schema grammar (EBNF)
Positional dialect (rlp, abi, borsh). Fields are unnamed, identified by index:
Schema = Node ;
Node = Scalar | List ;
Scalar = '{' '"type"' ':' ScalarType '}' ;
List = '{' '"type"' ':' '"list"' ',' '"items"' ':' Items '}' ;
Items = Node (* homogeneous, variable-length list *)
| '[' Node { ',' Node } ']' ; (* positional tuple, fixed arity *)The top-level schema of a positional encoding is itself a positional tuple (an array of Node), matching the receipt example [status, cumulativeGasUsed, logsBloom, logs].
Tagged dialect (protobuf). Fields identified by field number:
Schema = FieldMap ;
FieldMap = '{' Entry { ',' Entry } '}' ;
Entry = FieldNum ':' Field ;
FieldNum = '"' Digit { Digit } '"' ; (* decimal string key *)
Field = '{' '"name"' ':' Name ','
'"type"' ':' FieldType
[ ',' '"fields"' ':' FieldMap ] '}' ; (* "fields" required iff type is message *)
FieldType = ScalarType | '"message"' | '"repeated " ScalarType' | '"repeated message"' ;Path-expression grammar (EBNF)
target_field selects one element of the decoded schema.
Positional path (rlp, abi, borsh):
Path = Index { Index } ;
Index = '[' Uint ']' ;e.g. [3][0] → element 3 of the tuple, then element 0 of that list.
Tagged path (protobuf):
Path = Step { '.' Step } ;
Step = FieldNum { Index } ;
Index = '[' Uint ']' ;e.g. 1.1[2] → field 1, then its field 1 (a repeated), then element 2 of that repeated. An Index is only valid on a list/repeated/tuple node.
Evaluation & rejection semantics
The verifier evaluates prefix → schema → target_field against the proven leaf bytes on-chain, and reverts (no partial or default-valued delivery) on any of:
| Reject reason | Condition |
|---|---|
| Malformed descriptor | schema/target_field not well-formed per the dialect grammar; unknown encoding or type; prefix not a hex byte string |
| Dialect/path mismatch | Positional path used with a tagged schema or vice-versa |
| Prefix mismatch | Declared prefix is not the actual leading bytes of the leaf |
| Decode failure | Leaf bytes don't conform to schema under encoding (structure mismatch, wrong protobuf wire type, length overrun, trailing bytes) |
| Type mismatch | Decoded field can't fit the declared scalar type (e.g. uint8 but 2 bytes present) |
| Out-of-range path | An Index ≥ list/repeated length, or a FieldNum/tuple index absent in the decoded structure |
| Absent target | target_field resolves to an absent optional (protobuf) field: the app subscribed to data not present; deliver nothing rather than a default |
| Predicate mismatch | The extracted item fails one of the application's registered match predicates (§ "Match predicates"). Reverted by the router as PredicateMismatch, not skipped: the relayer selected the leaf with the same predicates, so an on-chain mismatch is a relayer bug |
Because the descriptor is app-registered (not relayer-chosen; see router § "Filter enforcement"), a revert here signals an integration/registration bug, not adversarial input. The behaviour is nonetheless deterministic and total: every leaf either yields exactly the extracted item or reverts.
Match predicates
A filter's match predicates are the content constraints that decide whether an extracted item is the one an application subscribed to. They are evaluated in two places that must agree: the Relayer applies them off-chain to select which leaves to relay; the Router re-applies them on-chain to enforce delivery. Both must compute the identical result, so the language is deterministic and side-effect-free. The two implementations are kept in lockstep by a shared vector set that both execute; an on-chain PredicateMismatch revert is treated as an extractor bug on the relayer side (Relayer § Message Delivery).
Predicate structure
Predicate = '{' '"path"' ':' PathExpr ','
'"op"' ':' Op ','
'"value"' ':' Value
[ ',' '"values"' ':' '[' Value { ',' Value } ']' ] '}' ;
Op = '"equals"' | '"notEquals"' | '"in"' | '"prefix"'
| '"gt"' | '"gte"' | '"lt"' | '"lte"' ;A filter carries a list of predicates; they are combined with logical AND only (conjunction). For disjunction, register multiple filters. This keeps on-chain evaluation a flat, bounded loop.
| Op | Applies to declared type | True when |
|---|---|---|
equals | any | operands up to 32 bytes: equal as big-endian magnitudes, regardless of the width either side was encoded at (so an address, a uint or a bytes32-shaped field matches a value given at any width); either operand over 32 bytes: exact raw-byte equality |
notEquals | any | not equals |
in | any | field equals one of values (same rule) |
prefix | bytes / string / bytesN | field's leading bytes equal value |
gt gte lt lte | uintN / intN | numeric comparison of field vs value as big-endian magnitudes; either operand over 32 bytes is malformed (reverts) |
Typing rule. value/values must be coercible to the declared schema type of the addressed field, and the op must be legal for that type (e.g. gt on a bytes field is malformed). A type violation is a malformed descriptor → rejected (see § "Evaluation & rejection semantics"); on-chain it reverts, off-chain the relayer refuses to register the filter.
Predicate paths must sit inside the extracted item
Every predicate path must be a descendant of target_field — it addresses a field within the extracted item. The Router evaluates it relative to the returned item: the light client hands back that item as raw encoded bytes, and the Router re-decodes its inner fields against the sub-schema rooted at target_field (light-client § VerifyMessage return value). This is why the USDT example pins [3][*][0] (the log's address) and [3][*][1][0] (its first topic) while extracting [3][*] (the log): both predicate paths are sub-paths of the extracted element. To pin a sibling field outside the extracted node, extract a higher node that contains both.
Wildcards and index unification
A [*] in target_field and in predicate paths binds to a single list/repeated index, and all [*] at the same position unify to the same index. The filter matches index k iff substituting [*] = k makes every predicate true; the extracted item is then the element at target_field with [*] = k.
- The relayer resolves
[*]to the concrete matching indexkand emits a concreteMessageID.target_field(withksubstituted) — one message per matching index. - The Router treats the registered extract pattern + predicates as the authority: it accepts the relayer's concrete
target_fieldonly if it is an instance of the registered pattern (same path with[*]→ some index) and every predicate holds on the extracted item. A relayer that picks an index whose item fails a predicate (e.g. a non-USDT log) is rejected.
Because the dedup key includes the resolved target_field (router § "Exactly-once delivery"), distinct matching indices in one leaf are distinct deliveries; the same index cannot be delivered twice.
Related documents
- light-client: the verifier that consumes these types (
VerifyMessage,UpdateConsensusState); decodes + extracts the target item on-chain - Relayer: produces
Message/MessageIDfrom extracted leaves - router: feeds the registered descriptor to the verifier and enforces match predicates; routes and enforces exactly-once delivery
- Consensus-verification: the verification technique behind
ConsensusStatecheckpoints