> 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/the-t-rex-ledger-and-its-satellites.md).
# The T-REX Ledger and its satellites
The architecture has two kinds of chain. One reference chain, the T-REX Ledger, holds the register. Any number of satellite chains serve as execution layers, where positions are made active for trading and settlement. This page describes what lives on each, how the two are connected, and how an Issuer opens its asset on a satellite.
## Two kinds of chain
```mermaid
flowchart TB
subgraph REF["Reference chain: the T-REX Ledger"]
direction LR
ID["Identities
and wallet links"]
TS["Token suite of each asset
eligibility, rules, complete record of ownership"]
APP["Applications on the register"]
end
GW["ERC-7786 gateways
pluggable messaging providers"]
subgraph SATS["Satellite chains"]
direction LR
S1["EVM satellite
T-REX Lite"]
S2["EVM satellite
T-REX Lite"]
S3["Non-EVM satellite
T-REX Lite"]
end
TS <-->|"authorizations out, settlements in"| GW
GW <--> S1
GW <--> S2
GW <--> S3
```
| | Reference chain | Satellite chain |
| ----------------------------------------- | ------------------------------ | --------------------------- |
| **Role** | Holds the register and decides | Executes |
| **Identities and wallet links** | Yes | No |
| **Eligibility configuration** | Yes | No |
| **Compliance rules and positions** | Yes | No |
| **Record of ownership** | Complete, for every chain | Balances of that chain only |
| **Token** | `Token`, an ERC-3643 token | T-REX Lite |
| **Decides whether a transfer is allowed** | Always | Never |
| **Number** | One | Any number, EVM or not |
### The T-REX Ledger is defined by its role
The T-REX Ledger is the chain on which the full protocol is deployed and which holds the golden copy of every asset and every identity. These docs define it by what it holds and by nothing else. They do not depend on its consensus, its operators or its fee model, and nothing in the protocol does.
## Not a bridge between peers
The relationship between the reference chain and a satellite is not that of two peers connected by a bridge.
| | A token bridged between peers | T-REX |
| --------------------------------------- | -------------------------------------------------------- | --------------------------------------------------------------------------------------- |
| **On the source chain** | Tokens are locked in an escrow contract, or burned. | The position is recorded as bridged. It stays on the register, attributed to its owner. |
| **On the destination chain** | A wrapped token circulates under that chain's own logic. | T-REX Lite holds an executable representation of the position. |
| **Who applies the rules** | Each chain, separately, if at all. | The reference chain, for every chain. |
| **Knowledge of the whole distribution** | None. Each chain sees its own side. | Complete. The positions of every satellite are recorded on the reference chain. |
| **Transfers on the destination chain** | Free, within that chain's logic. | Executed only against an authorization issued by the reference chain. |
A position that is active on a satellite has not left the register. The register knows at all times how much of the asset is active on each chain and whose it is.
## What stays on the reference chain
Everything that requires knowledge of the holder or of the distribution.
* **Identity.** ONCHAINIDs, their claims, and the links between wallets and identities, including the wallets that live on satellite chains.
* **Eligibility.** The required claim topics and the trusted Claim Issuers of each asset.
* **Compliance.** The rule modules, and the position of each identity over all chains.
* **The record.** Free, frozen and bridged balances, and the supply.
* **The servicing operations.** Issuance, redemption, freezes, forced transfers, recovery.
* **Applications that act on ownership.** They run against the complete record.
Concentrating the complexity here is what lets the satellite side be small. T-REX Lite needs no registry, no rules and no identity logic. The compliance contract linked to it only stores the validations it receives. It can therefore be implemented on chains with limited smart-contract capabilities.
## How the two are connected
A token and its T-REX Lite on each satellite are messaging peers. Nothing sits between them except the transport.
* **One author on each side.** On the reference chain, the token is the only contract that sends and receives. The compliance sends through it. On the satellite, T-REX Lite is the only contract the token listens to.
* **A standard interface.** Every message goes through an ERC-7786 gateway. The transport behind the gateway is pluggable.
* **Two levels of trust.** Network governance decides which gateways are sound, in the `TrustedGatewayRegistry`. The Issuer decides which of those gateways carries its asset's traffic to a given chain.
Five kinds of message cross the boundary.
| Message | Direction | Purpose |
| ----------------------- | ---------------------- | --------------------------------------------------------------------------------------------------------------------------- |
| Compliance validation | To the satellite | Authorizes one transfer. |
| Mint instruction | To the satellite | Tells T-REX Lite to create the balance of a position that the reference chain records as bridged to a wallet on that chain. |
| Recall instruction | To the satellite | Tells T-REX Lite to destroy a position so that it returns to the reference chain. |
| Settlement notification | To the reference chain | Reports that a transfer was executed. |
| Burn proof | To the reference chain | Proves that a position was destroyed on the satellite, so that it can be restored on the reference chain. |
One more message stays between satellites: in a transfer from one satellite to another, the sending chain sends a proof of burn to the receiving chain, which mints against it. Both chains report to the reference chain.
A forced recall that fails is also reported to the reference chain. `[[TBC: the message that reports a failed recall]]`
Gateways, routes and providers are described in [Messaging: ERC-7786 gateways, routes and peers](/cross-chain-the-distributed-register/messaging-erc-7786-gateways-routes-and-peers.md).
## Opening an asset on a satellite
A token opens no chain by default. It refuses to send to a chain it was not explicitly opened for. The Issuer opens each satellite with four settings.
| Setting | Function | Role | Meaning |
| ------------------------- | --------------------------------------------------------------- | -------------------- | --------------------------------------------------------------------------------------------- |
| The route | `Token.setRoute(chainType, chainReference, gateway)` | `IDENTITY_MANAGER` | The trusted gateway that carries this asset's messages to and from that chain. |
| The peer | `Token.setPeer(chainKey, peer)` | `IDENTITY_MANAGER` | The T-REX Lite contract on that chain. Only needed when it is not at the token's own address. |
| The reconciliation window | `ModularCompliance.setReconciliationWindow(chainKey, duration)` | `COMPLIANCE_MANAGER` | How long the register waits for a settlement from that chain after a validation expires. |
| The validity window | `ModularCompliance.setDefaultValidityWindow(duration)` | `COMPLIANCE_MANAGER` | How long a validation can be executed. One value for the asset. |
`Token.isChainOpen(chainKey)` tells whether a chain can carry traffic at this moment: a route is set, its gateway is still trusted by the network, and a peer is known.
A chain is identified by its **chain key**, the hash of its ERC-7930 chain identifier. One key covers a chain whatever address it is paired with.
T-REX Lite is deployed on the satellite by the T-REX Lite factory of that chain, on a message that arrives through the ERC-7786 gateway. On an EVM satellite, it is deployed at the same address as the token on the reference chain, so the peer is known without being set. On a non-EVM satellite, or when the addresses differ, the Issuer registers the peer.
### Closing a satellite
| Action | By | Effect |
| ----------------------------------------------- | ------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Set the route to zero | The Issuer | The asset stops sending to that chain and refuses burn proofs from it. Settlements of validations already sent are still accepted through the gateway that carried them. |
| Pause the issuance of validations for the chain | The Issuer, with `setIssuancePaused` | No new transfer is authorized on that chain. Settlements of transfers already executed are still recorded. |
| Remove a gateway from the trusted registry | Network governance | Every route through that gateway is severed at once, for every asset, with no action on any token. |
Everything fails closed. A message is sent only if the chain is routed, the gateway is trusted at that instant and the peer is addressable. A message is accepted only from a trusted gateway and only when its author is the asset's peer on that chain.
## What a satellite is trusted for
| Trusted for | Not trusted for |
| ---------------------------------------------------- | ------------------------------------- |
| Executing a transfer only against a validation, once | Deciding eligibility or compliance |
| Reporting what it executed | Knowing the distribution of the asset |
| Finalizing its own transactions | Recording ownership |
The messaging layer is trusted for the authenticity and the delivery of messages. The reference chain is where trust is concentrated.
---
# 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/the-t-rex-ledger-and-its-satellites.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.