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.
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
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
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.
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
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:
The chain has a route.
The routed gateway is trusted by the network at this instant.
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.
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.
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.
The envelope
Every protocol message has the same outer form: a type, a version and a body.
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
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
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.
List
TrustedGatewayRegistry
IdentityFactory
Granularity
Per gateway
Per gateway and origin chain
Administered by
INTEROP_MANAGER
The role that administers the IdentityFactory
Last updated