> For the complete documentation index, see [llms.txt](https://docs.t-rex.network/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.t-rex.network/cross-chain-the-distributed-register/messaging-erc-7786-gateways-routes-and-peers.md).
# Messaging: ERC-7786 gateways, routes and peers
Every message between the reference chain and a satellite passes through ERC-7786, a standard interface over cross-chain messaging. The protocol does not bind itself to a messaging provider. It depends on one guarantee, that a message is delivered and that its author is who the gateway says it is, and not on the mechanism that provides it.
This page describes the three elements of messaging (gateways, routes and peers), the two levels of trust that govern them, and what the token checks when it sends and when it receives.
## ERC-7786 in brief
ERC-7786 defines a gateway: a contract on each chain that sends messages to, and delivers messages from, other chains.
| Side | What the standard defines |
| ------------- | ------------------------------------------------------------------------------------------------------------------------------- |
| **Sending** | A contract asks a gateway to send a payload to a recipient on another chain. The gateway returns an identifier for the message. |
| **Receiving** | A gateway delivers a payload to the recipient contract, together with the sender of the message and an identifier. |
| **Addresses** | The sender and the recipient are ERC-7930 interoperable addresses, so a message can name an account on any chain, EVM or not. |
The essential service of a gateway is attribution. When it delivers a message, it attests which account, on which chain, sent it.
## Gateway, route, peer
```mermaid
flowchart LR
subgraph REF["Reference chain"]
T["Token"]
GR["Gateway"]
TGR["TrustedGatewayRegistry"]
end
subgraph SAT["Satellite chain"]
GS["Gateway"]
L["T-REX Lite"]
end
T -->|"route: which gateway
for this chain"| GR
GR <-->|"messaging provider"| GS
GS <--> L
T -.->|"peer: which contract
on that chain"| L
TGR -.->|"vets"| GR
```
| Element | What it is | Set by |
| ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------- |
| **Gateway** | An ERC-7786 contract that carries messages over one messaging provider. | The provider's adapter. Vetted by the network. |
| **Route** | For one asset and one satellite: the gateway that carries the asset's messages to and from that chain. One route per chain. | The Issuer |
| **Peer** | For one asset and one satellite: the T-REX Lite contract there. It is the only recipient the token sends to on that chain, and the only author it accepts messages from. | The Issuer. On an EVM satellite it defaults to the token's own address. |
A token and its T-REX Lite talk to each other directly. There is no shared intermediary contract per chain on either side.
## Two levels of trust
| | Network governance | The Issuer |
| ----------- | ------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------- |
| **Decides** | Which gateways are sound enough to attest who sent a message | Which of those gateways carries its asset's traffic to a given chain, and which contract it talks to there |
| **Where** | `TrustedGatewayRegistry` | The token: `setRoute`, `setPeer` |
| **Role** | `INTEROP_MANAGER`, a platform role | `IDENTITY_MANAGER`, in the Issuer's domain |
| **Scope** | Every asset | One asset |
### The trusted gateway registry
The `TrustedGatewayRegistry` is the network's list of vetted gateways. It is one contract, shared by every token, and it holds nothing but the list.
| Function | Effect |
| ----------------------------------- | ------------------------------------------------------------------------------------------------------- |
| `setTrustedGateway(gateway, true)` | Adds a gateway. A deliberate governance act, after review of the gateway and of the protocol behind it. |
| `setTrustedGateway(gateway, false)` | Removes a gateway. An emergency lever. |
| `isTrusted(gateway)` | Reads the list. |
A token is wired to the registry when it is deployed, and no role on the token can change that afterward. An Issuer cannot point its token at a list of its own.
Tokens do not copy the list. They read it each time they send or receive. Removing a gateway therefore severs every route through it at once, for every asset, without any call on any token.
> **Trust statement.** A gateway in the registry attests the authorship of every message a token acts on through it. A gateway that is malicious or broken could attribute a message to an account that did not send it. This risk is the trust assumption of the interoperability solution behind the gateway: while that solution works as designed, it does not arise. That is why adding a gateway is a governance decision of the network, and why the protocol limits what a single message can do.
### Routes and peers
| Function | Effect |
| -------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------- |
| `setRoute(chainType, chainReference, gateway)` | Routes the asset's traffic for that chain through a trusted gateway. A zero gateway closes the chain. |
| `setPeer(chainKey, peer)` | Registers the T-REX Lite of the asset on that chain. An empty value restores the default. |
| `routeFor(chainKey)`, `peerFor(chainKey)`, `chainOf(chainKey)` | Read the route, the peer and the chain behind a chain key. |
| `isChainOpen(chainKey)` | Tells whether the chain can carry traffic now: a route, a gateway still trusted, a known peer. |
A route can only name a gateway the network trusts at that moment. A peer must be a well-formed interoperable address of the chain it is registered for.
## Sending
On the reference chain, the token is the only author of protocol messages. The compliance issues validations, and sends them through the token. T-REX Lite therefore has one address to trust on the reference chain.
Before anything leaves, the token checks:
1. The chain has a route.
2. The routed gateway is trusted by the network at this instant.
3. The peer on that chain is known.
If any of these fails, the send reverts with `ChainNotOpen`. The token emits `ProtocolMessageSent` with the type of the message, the chain and the identifier the gateway returned.
## Receiving
A message delivered to the token passes these checks, in order.
| Check | Refused with |
| ------------------------------------------------------------------------------------------- | ------------------------------------- |
| The delivering gateway is trusted by the network. | `ERC7786RecipientUnauthorizedGateway` |
| The author of the message is the asset's peer on the chain it comes from. | `SenderNotPeer` |
| The envelope has a supported version and a known type. | `UnsupportedMessageVersion` |
| This gateway has not already delivered this message. | `MessageAlreadyReceived` |
| The type is one a satellite sends: a settlement notification or a burn proof. | `MessageTypeNotInbound` |
| For a settlement: the gateway is the one the validation went out through toward that chain. | `GatewayNotPinned` |
| For a burn proof: the gateway is the chain's current route. | `GatewayNotRouted` |
Only then is the content handed to the part of the protocol that acts on it, which applies its own checks. A settlement is classified by the compliance against the validation it issued. See [The dual-state lifecycle](/cross-chain-the-distributed-register/the-dual-state-lifecycle.md).
The token emits `ProtocolMessageReceived` for each message it accepts.
## Between two satellites
One message does not pass through the token: in a transfer between two satellites, the T-REX Lite of the sending chain sends a proof of burn to the T-REX Lite of the receiving chain, through ERC-7786, and the receiving chain mints against it. Both satellites still report their half to the token on the reference chain, which is where the transfer is recorded. See [T-REX Lite](/cross-chain-the-distributed-register/t-rex-lite.md).
## The envelope
Every protocol message has the same outer form: a type, a version and a body.
| Part | Meaning |
| ------- | -------------------------------------------------------------------------------------------------------------- |
| Type | One of five: compliance validation, mint instruction, recall instruction, settlement notification, burn proof. |
| Version | The version of the envelope. A message with another version is refused. |
| Body | The content, whose structure depends on the type. |
New types are added at the end of the list, so existing types keep their codes.
## Pinned routes
When a validation is sent toward a chain, the token records the gateway it went out through. The settlement of that validation from that chain is accepted from that gateway only.
This is what makes a change of route safe.
* **A switch affects new validations only.** The Issuer sets a new gateway for a chain, and every validation issued from then on uses it.
* **Nothing in flight is orphaned.** A validation that went out through the previous gateway is still settled through it, as long as the network still trusts that gateway.
* **A gateway cannot settle what it did not carry.** A settlement arriving through another gateway, trusted or not, is refused.
## Everything fails closed
| Situation | Outcome |
| ---------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| The Issuer has not opened a chain | The token does not send to it and accepts nothing from it. |
| The route is set to zero | The token sends nothing to the chain and refuses burn proofs from it. A settlement of a validation already sent is still accepted through the gateway that carried it. |
| The network removes the routed gateway | The chain is closed for this asset until the Issuer sets another route. |
| A message comes from a contract that is not the peer | Refused. |
| A message is delivered twice by the same gateway | Refused the second time. |
## What the protocol asks of messaging
| Property | Asked of the transport | If it fails |
| ---------------- | ---------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Authenticity** | The sender of a delivered message is who the gateway says. | This is the trust placed in a gateway. The registry, the peer check and the settlement checks limit the consequences, and the token halts on a message the register cannot account for. |
| **Delivery** | A message sent is eventually delivered. | A validation that is never delivered expires. A settlement that is slow is handled as a late reconciliation. |
| **Order** | Not required. | The two reports of a transfer between satellites are accepted in either order. |
| **Timeliness** | Within the reconciliation window of the chain. | Beyond it, the keeper may discard, and a settlement that still arrives is applied late and flagged. |
## Two separate lists
The identity layer uses ERC-7786 too, for a different purpose: a wallet on another chain proves control of itself by sending a link proposal to the `IdentityFactory`. The factory keeps its own list of trusted gateways, per origin chain. Both lists are administered by Network governance, under different roles. See [Wallet linking and the global identity registry](/identity-onchainid/wallet-linking-and-the-global-identity-registry.md).
| | Token messaging | Wallet linking |
| ------------------- | ------------------------ | ----------------------------------------------- |
| **List** | `TrustedGatewayRegistry` | `IdentityFactory` |
| **Granularity** | Per gateway | Per gateway and origin chain |
| **Administered by** | `INTEROP_MANAGER` | The role that administers the `IdentityFactory` |
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.
Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:
```
GET https://docs.t-rex.network/cross-chain-the-distributed-register/messaging-erc-7786-gateways-routes-and-peers.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.