> 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/start-here/protocol-at-a-glance.md).

# Protocol at a glance

This page describes the whole protocol in one read: the layers, what happens on a transfer, what a holder owns, and how an asset reaches other chains. Every topic has its own page under Concepts.

## The idea in four statements

1. **The register lives on-chain.** The token contract on the reference chain holds the complete record of ownership of the asset and enforces it. It is designed to be the book of record itself. Where the legal register of an asset has to be kept elsewhere, that register replicates what happens here.
2. **Ownership belongs to identities.** A holder is an ONCHAINID, a smart account. It holds tokens directly, in wallets linked to it on any chain, or both.
3. **Every change of ownership passes two gates before it is recorded.** Eligibility: may this identity hold the asset? Compliance: may this movement happen now? A movement that fails either gate is not recorded.
4. **One chain decides, the others execute.** The reference chain holds the complete register and authorizes every movement. Satellite chains run T-REX Lite, which executes only what the reference chain has authorized.

## Architecture

```mermaid
flowchart TB
    subgraph REF["Reference chain: the T-REX Ledger, golden copy"]
        direction TB
        subgraph IDL["Identity layer: ONCHAINID"]
            IDF["IdentityFactory<br/>deploys identities, links wallets"]
            OID["Identity<br/>smart account: keys, claims, assets"]
            REP["ReputationRegistry<br/>standing of Claim Issuers"]
        end
        subgraph SUITE["Token suite, one per asset"]
            TOK["Token<br/>ERC-3643 register"]
            REG["TREXRegistry<br/>eligibility"]
            IRS["IdentityRegistryStorage"]
            MC["ModularCompliance<br/>rules, positions, validations"]
            AM["TREXAccessManager<br/>roles"]
        end
        subgraph NET["Network-level contracts"]
            FAC["TREXFactory"]
            IA["TREXImplementationAuthority"]
            TGR["TrustedGatewayRegistry"]
        end
        TOK -->|"isVerified"| REG
        TOK -->|"canTransfer"| MC
        REG --> IRS
        REG -->|"address to identity, identity type"| IDF
        REG -->|"claims"| OID
        AM -.->|"authorizes"| TOK
    end
    GW["ERC-7786 gateways<br/>pluggable messaging providers"]
    subgraph SAT["Satellite chains, EVM and non-EVM"]
        L1["T-REX Lite"]
        L2["T-REX Lite"]
    end
    TOK <-->|"validations out, settlements in"| GW
    GW <--> L1
    GW <--> L2
    TGR -.->|"vets"| GW
```

## The layers

| Layer                             | Contracts                                                                                      | Responsibility                                                                                                                                                                                                                                                                                                                             |
| --------------------------------- | ---------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **Identity**                      | `IdentityFactory`, `Identity`, `ERC734Validator`, `ReputationRegistry`                         | Who a participant is. An `Identity` is an ERC-7579 smart account. It holds keys and claims, both stored by the `ERC734Validator` module, and it can hold tokens and transact like any account. The `IdentityFactory` deploys identities and keeps the global link between wallets and identities, keyed by ERC-7930 interoperable address. |
| **Token and register**            | `Token`, `TREXRegistry`, `IdentityRegistryStorage`, `ModularCompliance`, compliance modules    | Who owns what, and who may. The `Token` is an ERC-3643 token. The `TREXRegistry` decides eligibility. `ModularCompliance` applies the asset's rules, keeps each identity's total position and issues cross-chain validations.                                                                                                              |
| **Cross-chain**                   | The messaging endpoint inside `Token`, `TrustedGatewayRegistry`, ERC-7786 gateways, T-REX Lite | How the register reaches other chains. The token on the reference chain sends validations and receives settlements through ERC-7786 gateways.                                                                                                                                                                                              |
| **Governance and infrastructure** | `TREXAccessManager`, `TREXFactory`, `TREXImplementationAuthority`                              | Who may do what, how suites are deployed at deterministic addresses, and how they are upgraded.                                                                                                                                                                                                                                            |

A **token suite** is the set of contracts deployed for one asset: a `Token`, a `TREXRegistry`, an `IdentityRegistryStorage` (its own or a shared one), a `ModularCompliance` and a `TREXAccessManager`.

## What happens on a transfer

On the reference chain, `Token.transfer(to, amount)` runs these checks in this order. The first one that fails reverts the transaction, and nothing is recorded.

1. **Pause.** The token is not paused.
2. **Freeze.** Neither the sender's address nor the recipient's address is frozen.
3. **Balance.** The sender's free balance covers `amount`.
4. **Eligibility.** `TREXRegistry.isVerified(to)` returns true. The registry resolves the recipient address to an identity: a linked wallet resolves to the identity it is linked to, and an identity resolves to itself. It refuses a wallet whose link has been revoked, reads the claim topics required for that identity's type, and requires for each topic a valid claim signed by a Claim Issuer the Issuer trusts for that topic.
5. **Compliance.** `ModularCompliance.canTransfer(from, to, amount)` returns true. Every rule module states the largest amount it allows for this movement. The compliance keeps the smallest answer, and `amount` must not exceed it.
6. **Record.** The balances move. The compliance updates the positions of both identities and notifies its tracker modules.

Three variations:

* **`transferFrom`.** Before the allowance is spent, the compliance asks its spender modules whether the caller may execute this transfer. The spender is checked, not only the sender and the recipient.
* **Mint.** There is no sender. The eligibility and compliance gates apply to the recipient.
* **Burn.** There is no recipient. Neither gate applies.

> **Eligibility and compliance are separate gates.** Eligibility is about the identity: claims, trusted issuers, required topics. It lives in the `TREXRegistry`. Compliance is about the movement: amounts, caps, positions. It lives in `ModularCompliance` and its modules.

## What a holder owns

A position has three parts.

| Part        | Meaning                                                                                                                         | Where it is read                 |
| ----------- | ------------------------------------------------------------------------------------------------------------------------------- | -------------------------------- |
| **Free**    | Held on the reference chain and movable there.                                                                                  | `Token.freeBalanceOf(address)`   |
| **Frozen**  | Held on the reference chain, immobilized by an agent.                                                                           | `Token.getFrozenTokens(address)` |
| **Bridged** | Owned by the same holder, active on a satellite chain. Accounted per satellite wallet, keyed by ERC-7930 interoperable address. | `Token.bridgedBalanceOf(wallet)` |

On the reference chain, the address that holds a free or frozen balance is either the identity itself or a wallet linked to it. The register treats both the same way.

Two views follow from this:

* **`Token.balanceOf(address)`** returns free plus frozen. It is the standard ERC-20 view of what sits on the reference chain, and every ERC-20 tool reads it correctly.
* **`ModularCompliance.positionOf(identity)`** returns what the identity owns in total: free, frozen and bridged, over the identity's own address and every wallet linked to it, on every chain. Rules about distribution read this view.

`Token.totalSupply()` counts the whole issuance, bridged positions included. Moving a position to a satellite or back does not change it. Only a mint or a burn does.

Moving tokens between two wallets of the same identity, or between an identity and one of its wallets, is not a change of ownership. The position of the identity does not move, and rules that key on the identity do not count it.

## How an asset reaches other chains

On a satellite chain the asset is a T-REX Lite token. T-REX Lite carries no identity registry, no eligibility configuration and no compliance engine. It holds balances and executes transfers against authorizations issued by the reference chain. This keeps the satellite side small enough to implement on chains with limited smart-contract capabilities, EVM or not.

There are three kinds of movement.

| Movement                                                                                                                | Changes ownership | How it completes                                                                                                                      |
| ----------------------------------------------------------------------------------------------------------------------- | ----------------- | ------------------------------------------------------------------------------------------------------------------------------------- |
| **Delegation-out**: a holder makes part of a position active on a satellite                                             | No                | Final on the reference chain at once: the position moves from free to bridged, and a one-way instruction tells the satellite to mint. |
| **Transfer** from a satellite wallet, to a wallet on the same satellite, on another satellite or on the reference chain | Yes               | Authorize on the reference chain, execute on the satellite, reconcile back to the reference chain.                                    |
| **Recall**: a bridged position returns to the reference chain                                                           | No                | The satellite burns first. The reference chain converts the position from bridged to free only when it receives the burn proof.       |

Tokens on the reference chain can also be delivered in one step to another holder's wallet on a satellite, by a transfer or by an agent's mint, with nothing for the recipient to do. See [Movement types](/cross-chain-the-distributed-register/movement-types.md).

A transfer on a satellite runs in three movements:

```mermaid
sequenceDiagram
    participant H as Holder
    participant MC as ModularCompliance
    participant T as Token
    participant G as ERC-7786 gateway
    participant L as T-REX Lite

    Note over MC,T: reference chain
    Note over L: satellite chain
    H->>MC: requestTransferValidation(from, to, min, max, spender)
    MC->>MC: eligibility of recipient, rules, reserve
    MC->>T: dispatchComplianceValidation
    T->>G: send validation
    G->>L: deliver validation
    H->>L: transfer
    L->>L: consume validation, execute
    L->>G: settlement notification
    G->>T: deliver settlement
    T->>MC: handleSettlement
    MC->>T: settleValidation
    Note over MC,T: ownership recorded
```

1. **Authorize.** The sender's identity, or an agent acting for it, asks `ModularCompliance` for a validation. The compliance checks the recipient's eligibility and the asset's rules against the global position set, then issues a single-use `ComplianceValidation` for that exact movement: sender, recipient, optional spender, an amount range, an expiry.
2. **Execute.** The validation travels to the satellite. T-REX Lite executes the transfer against it and consumes it, so it cannot be used twice.
3. **Reconcile.** T-REX Lite notifies the reference chain, which records the change of ownership in the register.

Between steps 1 and 3 the protocol advances two kinds of state at different times. At authorization, the compliance **reserves** the movement: it counts it as executed at its maximum amount for every distribution rule, so two concurrent validations cannot jointly breach a cap. **Ownership** moves only at reconciliation, so the register records only what has happened. A validation that is never executed expires. Its reservation is released once a per-chain reconciliation window has passed. That window covers the satellite's worst-case finality and message latency, so a transfer executed just before expiry is always reconciled before the reference chain gives up on it.

> **Two senses of finality.** A transfer executed on a satellite is final as a transaction on that chain. The change of ownership is recorded when it reaches the reference chain, because that is where the register is. Where that register is the legal record of the asset, this is also the moment of legal finality.

Messages between the reference chain and the satellites go through ERC-7786, a transport-agnostic interface. The network vets gateways in the `TrustedGatewayRegistry`. For each satellite, the Issuer chooses one vetted gateway as the route and registers the T-REX Lite contract as the token's peer. Chainlink's interoperability stack, CCIP and CRE, is the default transport. Other providers plug in as adapters behind the same interface, so no messaging provider is a protocol-level dependency.

## Applications on the register

The reference chain is not a passive vault. Because it holds the register, applications that act on ownership run directly against it: primary issuance and redemption, secondary trading, lending against positions, settlement, corporate actions. They act on the complete record, with no reconciliation lag. The register serves them both views: `balanceOf` for what is movable on the reference chain, and the identity's total position for what must reach every holder wherever its tokens are active.

An application is an eligible participant like any other. It holds an ONCHAINID and passes the same gates. The applications available in the ecosystem are listed in the [T-REX AppStore](/appstore.md).

## Who controls what

* **On a token suite**, every privileged function is gated by a role held in the suite's `TREXAccessManager`. Roles are granular (a minter is not a pauser) and scoped to a domain, so an agent of one issuer has no power over another issuer's tokens.
* **On an identity**, authority comes from keys with purposes: a management key controls the identity, an action key acts for it (including moving the tokens it holds), a claim key adds or signs claims.
* **Upgrades** go through beacon proxies. The `TREXImplementationAuthority` owns the shared beacons and moves every suite that follows it to a new version in one transaction. An Issuer that does not accept shared upgrades deploys an isolated suite with its own beacons.
* **At network level**, a small set of platform roles governs the factory, the published versions and the trusted gateways.

## Where next

* [The primary register](/the-primary-register.md), for the reasoning behind the golden copy and how it relates to the legal register of an asset.
* [Eligibility and compliance: the two gates](/the-primary-register/eligibility-and-compliance-the-two-gates.md), for what each gate checks and which operations pass through it.
* [Technical finality and legal finality](/the-primary-register/technical-finality-and-legal-finality.md), for what is final, where and when.
* [Standards foundation](/start-here/standards-foundation.md), for the standards each layer is built from.
* [Actors and roles](/start-here/actors-and-roles.md), for who holds which power.
* Guides, for step-by-step operations.


---

# 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/start-here/protocol-at-a-glance.md?ask=<question>&goal=<user_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.