TrustlessProtocol spec

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

FieldTypeDescription
metadataMetadataThe message's identity, routing, and type information
payloadbytesAt 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

FieldTypeDescription
idMessageIDThe unique identifier and locator for this message
typestringThe 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
fromstringThe source chain the message originated from (chain identifier)
tostringThe destination contract the message is addressed to (target application address)

MessageID. Uniquely locates the message within a block's commitment structure.

FieldTypeDescription
commitment_pathstringThe full commitment path of the leaf containing the message. The format is chain-specific.
target_fieldstringA path expression locating the target element within the decoded leaf. Together with commitment_path + root, completes the locator. Grammar: § "Schema language & path expressions"
rootstringThe 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_field in MessageID must 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.

FieldTypeDescription
encodingstringThe encoding scheme used to serialize the leaf data (e.g., rlp, protobuf, borsh, abi)
prefixstringOptional byte prefix before the encoded payload (e.g., EIP-2718 transaction type byte). If present, must be stripped before decoding
schemaSchemaThe 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:

  1. Decode the proven bytes, on-chain. The verifier strips the prefix, decodes per encoding/schema, and navigates target_field against 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.
  2. 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. The target_field is 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 point target_field at 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:

EncodingDialectFields identified byPath style
rlppositionalorder (index)[i] segments
abipositionalorder (index)[i] segments
borshpositionalorder (index)[i] segments
protobuftaggedfield numberf / f.f / f[i]

Type system

A scalar type is one of:

TypeMeaning
uintNUnsigned big-endian integer; N ∈ {8,16,…,256}, multiple of 8
intNSigned (two's-complement) integer; N as above
boolSingle byte, 0x00 / 0x01
bytesNFixed-length byte string of exactly N bytes; N ≥ 1 (e.g. bytes32, bytes256)
addressChain-specific account alias (EVM: bytes20)
bytesVariable-length byte string
stringVariable-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 reasonCondition
Malformed descriptorschema/target_field not well-formed per the dialect grammar; unknown encoding or type; prefix not a hex byte string
Dialect/path mismatchPositional path used with a tagged schema or vice-versa
Prefix mismatchDeclared prefix is not the actual leading bytes of the leaf
Decode failureLeaf bytes don't conform to schema under encoding (structure mismatch, wrong protobuf wire type, length overrun, trailing bytes)
Type mismatchDecoded field can't fit the declared scalar type (e.g. uint8 but 2 bytes present)
Out-of-range pathAn Index ≥ list/repeated length, or a FieldNum/tuple index absent in the decoded structure
Absent targettarget_field resolves to an absent optional (protobuf) field: the app subscribed to data not present; deliver nothing rather than a default
Predicate mismatchThe 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.

OpApplies to declared typeTrue when
equalsanyoperands 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
notEqualsanynot equals
inanyfield equals one of values (same rule)
prefixbytes / string / bytesNfield's leading bytes equal value
gt gte lt lteuintN / intNnumeric 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 index k and emits a concrete MessageID.target_field (with k substituted) — one message per matching index.
  • The Router treats the registered extract pattern + predicates as the authority: it accepts the relayer's concrete target_field only 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 / MessageID from 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 ConsensusState checkpoints

On this page