> 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/token-and-register/the-balance-model.md). # The balance model A register records what each holder owns. In T-REX a position has three parts, held at two kinds of address, and the token presents two views of it. Distinguishing them is what lets one register serve ERC-20 tooling on the reference chain, compliance rules over the whole distribution, and executions on other chains at the same time. ## The three parts of a position | Part | Meaning | Movable by its holder on the reference chain | | ----------- | ------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------ | | **Free** | Held on the reference chain, unencumbered. | Yes | | **Frozen** | Held on the reference chain, immobilized by an agent under the asset's controls. | No | | **Bridged** | Owned by the same holder, with its movement delegated to a satellite chain where the holder transacts. | No. It moves on the satellite, and returns through a recall. | All three are owned by the holder. Freezing or bridging a position changes what can be done with it and where. It does not change whose it is. ```mermaid flowchart TB subgraph POS["What one identity owns"] direction TB subgraph NAT["On the reference chain: balanceOf"] direction LR FR["Free"] FZ["Frozen"] end subgraph BR["On satellite chains: bridged"] direction LR B1["Wallet on satellite A"] B2["Wallet on satellite B"] end end FR <-->|"freeze, unfreeze"| FZ FR -->|"delegation-out"| BR BR -->|"recall"| FR ``` ## Two kinds of address | | On the reference chain | On a satellite chain | | ----------------- | ---------------------------------------------- | ---------------------------------------------- | | **Holds** | Free and frozen tokens | Bridged tokens | | **Address** | The ONCHAINID itself, or a wallet linked to it | A wallet linked to the identity, on that chain | | **Identified by** | An address | An ERC-7930 interoperable address | | **Recorded in** | The standard ERC-20 balances of the token | The bridged ledger of the token | The bridged ledger is separate for a structural reason. `balanceOf` is defined over the address space of one chain. A position on a non-EVM satellite cannot be expressed as an address of the reference chain. The bridged ledger therefore uses a format that spans every chain the asset reaches: it is keyed by the hash of the wallet's interoperable address, in its canonical encoding, so one wallet has exactly one entry. The reference chain records bridged positions. It does not hold them in an escrow address. There is no address on the reference chain whose balance is the bridged supply. ## Reading a position | Function | On | Returns | | -------------------------- | ------------------- | ---------------------------------------------------------------------------------------------- | | `balanceOf(address)` | `Token` | Free plus frozen at that address. | | `freeBalanceOf(address)` | `Token` | Free at that address. | | `getFrozenTokens(address)` | `Token` | Frozen at that address. | | `bridgedBalanceOf(wallet)` | `Token` | The position recorded for a satellite wallet. | | `availableOf(wallet)` | `Token` | What a satellite wallet can still send: its bridged position less what is reserved. | | `reservedOf(wallet)` | `Token` | What open validations may still draw from a satellite wallet. | | `positionOf(identity)` | `ModularCompliance` | Everything the identity owns: free, frozen and bridged, over all its addresses and all chains. | Functions that take a satellite wallet take its interoperable address and revert on an encoding that is not canonical. ### Two views, by design * **`balanceOf`** is the standard, chain-local view. It answers exactly as every ERC-20 wallet, venue and indexer expects, for what is present on the reference chain. An application that lends against a position reads it, because it reflects what is movable there. * **`positionOf`** is the global view. Rules that depend on the distribution of the asset read it, and so does any action that has to reach a holder's entire position wherever it is active. Moving tokens between two addresses of the same identity, on one chain or across chains, changes `balanceOf` and bridged balances. It does not change `positionOf`, because the owner is the same. ## Inside the bridged part A bridged position is one number per satellite wallet. While a cross-chain movement is in progress, part of it is set aside. | State | Meaning | Still owned by | | -------------- | ---------------------------------------------------------------------------------------------------------------- | -------------------------------------- | | **Available** | Bridged and free to be sent on the satellite. | The holder | | **Reserved** | Promised to a validation that has been issued and not yet settled. It cannot be promised to a second validation. | The holder, until the transfer settles | | **In transit** | Burned on one satellite for a transfer to another satellite whose mint is not yet confirmed. No wallet holds it. | The sender, until the transfer settles | The reservation is what prevents a wallet from obtaining two validations against the same tokens. The in-transit hold is what prevents tokens already burned on a satellite from being validated or recalled again while the second half of a movement is in flight. `inTransitOf(validationId)` returns the amount held for one validation. ## Supply | Quantity | Read with | Meaning | | -------------- | -------------------------------- | ------------------------------------------------------------------- | | Total supply | `totalSupply()` | The whole issuance of the asset, wherever it is active. | | Bridged supply | `totalBridged()` | The part active on satellites, in-transit amounts included. | | In transit | `totalInTransit()` | The part of the bridged supply that no wallet holds at this moment. | | Native supply | `totalSupply() - totalBridged()` | What the balances on the reference chain add up to. | Two identities always hold: * `totalSupply` = the sum of every `balanceOf` + `totalBridged` * `totalBridged` = the sum of every bridged position + `totalInTransit` Only a mint or a burn changes `totalSupply`. ## What each movement does | Movement | Free | Frozen | Bridged | Total supply | | ------------------------------------------------ | ------------------------- | -------------------------- | ----------------------------------------------------------------- | ------------ | | Mint | Recipient up | | | Up | | Burn | Holder down | Down, if the burn needs it | | Down | | Transfer on the reference chain | Sender down, recipient up | | | Unchanged | | Freeze, unfreeze | Down, up | Up, down | | Unchanged | | Delegation-out | Holder down | | Holder's satellite wallet up | Unchanged | | Recall | Holder up | | Holder's satellite wallet down | Unchanged | | Transfer on one satellite | | | Sender's wallet down, recipient's wallet up | Unchanged | | Transfer between two satellites | | | Sender's wallet down, then in transit, then recipient's wallet up | Unchanged | | Transfer from a satellite to the reference chain | Recipient up | | Sender's wallet down | Unchanged | Freezes apply to what an address holds on the reference chain. A bridged position is recalled before it can be frozen. ## An example An investor's identity holds 1,000 units of an asset. | Where | Amount | | ----------------------------------------- | ------ | | In the ONCHAINID, free | 500 | | In the ONCHAINID, frozen | 100 | | In a linked wallet on the reference chain | 150 | | In a linked wallet on satellite A | 250 | | Read | Returns | | --------------------------- | ------- | | `balanceOf(identity)` | 600 | | `freeBalanceOf(identity)` | 500 | | `getFrozenTokens(identity)` | 100 | | `balanceOf(wallet)` | 150 | | `bridgedBalanceOf(walletA)` | 250 | | `positionOf(identity)` | 1,000 | The investor requests a validation to sell up to 100 units on satellite A. Until it settles, `reservedOf(walletA)` is 100 and `availableOf(walletA)` is 150. `bridgedBalanceOf(walletA)` is still 250 and `positionOf(identity)` is still 1,000, because nothing has changed hands yet. ## For indexers A delegation-out debits the holder's balance on the reference chain, and the token emits `Transfer(holder, 0x0)` for it. A recall, or a transfer from a satellite to the reference chain, credits a balance and emits `Transfer(0x0, recipient)`. This keeps every ERC-20 balance indexer correct without special handling. The cost is on supply: an indexer that derives the supply by summing `Transfer` events under-reports it by the bridged supply. Read `totalSupply()`, or reconcile with the events that name these movements. | Event | Movement | | ------------------------------------------------- | ------------------------------------------------------------------- | | `DelegatedOut` | Free to bridged, same owner | | `Recalled` | Bridged to free, same owner | | `SettledToNative` | A satellite wallet's position to a recipient on the reference chain | | `BridgedTransfer` | One satellite wallet to another | | `HeldInTransit`, `ReturnedInTransit` | Into and out of the in-transit state | | `ReservedForValidation`, `ReleasedFromValidation` | A reservation taken and given back | --- # 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/token-and-register/the-balance-model.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.