> 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/movement-types.md). # Movement types Not every cross-chain operation changes ownership, and the protocol treats those that do differently from those that do not. The governing principle is simple. * **An operation that changes who owns a position on a satellite** is authorized first and is recorded on the reference chain only when the satellite has reported its execution. * **An operation that changes only where a position is active**, without changing who owns it, needs no authorization of ownership. It needs only that the position is never live in two places at once. Three kinds of movement are described here. Two more paths start on the reference chain and deliver to a satellite wallet in one step: see "Which movement for which need" at the end of this page. | Movement | Changes ownership | Direction | Completes on the reference chain | | ------------------ | ----------------------------------------------- | ---------------------------------- | ------------------------------------------ | | **Delegation-out** | No | Reference chain to a satellite | At once, in the transaction that delegates | | **Transfer** | Yes, unless both wallets belong to one identity | Out of a satellite wallet | When the satellite's report is settled | | **Recall** | No | A satellite to the reference chain | When the proof of the burn is received | ## Delegation-out Delegation-out makes a position active on a satellite. The same holder owns the same tokens before and after. Only the form changes, from free to bridged, and the place where the position can move shifts to the satellite. ```mermaid sequenceDiagram participant H as Holder participant T as Token on the reference chain participant G as ERC-7786 gateway participant L as T-REX Lite H->>T: delegate an amount to a wallet on a satellite T->>T: free balance down, bridged position up Note over T: final on the reference chain T->>G: mint instruction, one-way G->>L: deliver L->>L: mint to the wallet Note over L: usable on the satellite ``` | Property | Value | | -------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Destination** | A wallet on a satellite that belongs to the holder's own identity. | | **On the reference chain** | The holder's free balance goes down and the bridged position of the satellite wallet goes up, in one transaction. `balanceOf` drops. `totalSupply` does not move. | | **Message** | A mint instruction to T-REX Lite. One-way. | | **Reconciliation** | None. The reference chain is not waiting to learn an outcome. It is the outcome. | | **Events** | `Transfer(holder, 0x0)` and `DelegatedOut`. | Because nothing about ownership changes, the operation is atomic and final on the reference chain at the instant it executes. If the mint on the satellite is delayed, the position is not yet usable there. That is a delay on the satellite, never an inconsistency in the register: the register already shows the position as bridged to that wallet, and it cannot be used anywhere else in the meantime. A delegation-out burns on the reference chain before it instructs the satellite. This order is what makes it safe without any confirmation. ## Transfer A transfer moves tokens out of a satellite wallet to another address. It follows the three steps of [Authorization before execution](/cross-chain-the-distributed-register/authorization-before-execution.md): authorize on the reference chain, execute on the satellite, settle back. The reference chain does not record the change of ownership until it has learned that the satellite executed it. A transfer has three shapes, by where the recipient is. ### On one satellite ```mermaid sequenceDiagram participant RC as Register participant A as T-REX Lite on satellite A RC->>A: validation A->>A: sender's balance down, recipient's balance up A->>RC: settlement: both wallets, amount RC->>RC: sender's bridged position down, recipient's up ``` One chain does the whole movement and sends one report. The register moves the bridged position from the sender's wallet to the recipient's wallet, and the position of one identity to the other. Event `BridgedTransfer`. ### Between two satellites ```mermaid sequenceDiagram participant A as T-REX Lite on satellite A participant RC as Register participant B as T-REX Lite on satellite B RC->>A: validation RC->>B: validation A->>A: consume the validation, burn the sender's balance A->>B: proof of burn A->>RC: settlement: the burn RC->>RC: amount held in transit B->>B: mint the same amount to the recipient B->>RC: settlement: the mint RC->>RC: recipient's bridged position up, ownership moves ``` Two chains each do half, and they cannot act atomically. The burn comes first: the sending chain consumes the validation, burns, and sends a proof of burn to the receiving chain, which mints the same amount against that proof. Each chain reports its half to the reference chain. The register completes the transfer when both reports have arrived with the same amount, in whichever order they are delivered. Between the two, the amount the sender's chain burned is held in transit on the register: no wallet holds it, and it still belongs to the sender. Events `HeldInTransit`, then `BridgedTransfer`. ### From a satellite to the reference chain ```mermaid sequenceDiagram participant A as T-REX Lite on satellite A participant RC as Register RC->>A: validation A->>A: burn the sender's balance A->>RC: settlement: both wallets, amount RC->>RC: sender's bridged position down, recipient's free balance up ``` The recipient is an address on the reference chain, an ONCHAINID or a linked wallet. The satellite burns and reports. The register debits the sender's bridged position and credits the recipient's free balance. Events `Transfer(0x0, recipient)` and `SettledToNative`. ### Between two wallets of one identity A holder can move its own tokens from one of its wallets to another, on the same satellite or across satellites. The path is the same as any transfer: a validation, an execution, a settlement. What differs is what the register checks and records. * No rule about distribution is asked, and nothing is reserved against the identity. Moving one's own tokens changes no position. * The sending wallet's limit and the spender policy still apply. * At settlement, the bridged positions of the two wallets change. The position of the identity does not. It is a movement of where the position is active, not of who owns it. ## Recall Recall returns a delegated position to the reference chain. It is the mirror of delegation-out with one difference: it is not atomic on the reference chain. ```mermaid sequenceDiagram participant H as Holder participant A as Agent participant L as T-REX Lite participant G as ERC-7786 gateway participant T as Token on the reference chain alt the holder recalls H->>L: recall an amount else an agent orders the recall A->>T: order the recall T->>G: recall instruction G->>L: deliver end L->>L: burn L->>G: burn proof G->>T: deliver Note over T: the reference chain waits for this proof T->>T: bridged position down, free balance up ``` | Property | Value | | -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ | | **Trigger** | A burn on the satellite: the holder recalls its own position on T-REX Lite, or a recall instruction from the reference chain forces it. | | **Message** | A burn proof: the wallet that was burned, the amount, and the address on the reference chain to credit. | | **On the reference chain** | Only when the proof is received: the bridged position of the satellite wallet goes down and the free balance of the named address goes up. | | **Condition** | The address credited belongs to the same identity as the wallet that was burned. A recall moves location and never ownership. | | **Events** | `Transfer(0x0, holder)` and `Recalled`. | The reference chain must consume the confirmed burn before it converts the position from bridged back to free. Acting earlier would leave the position live on both chains at once. ### A recall ordered by an agent An agent who needs to bring a delegated position back follows the same path. It cannot reach across and move a position that is active on a satellite. It sends a recall instruction to the satellite, T-REX Lite burns and answers with the burn proof, and the position returns to the reference chain for the same identity. The agent then applies the control it needs there. See [Lifecycle controls](/token-and-register/lifecycle-controls.md). A forced recall can fail. If the holder executed a validated transfer before the instruction arrived, the tokens are no longer in the wallet. T-REX Lite then reports that the recall failed, and the reference chain receives the settlement of the transfer that did execute. ### A recall and an open validation Recalls and validations are independent. A recall can burn tokens that an open validation was issued for. The transfer that validation authorized can then no longer execute: the validation expires and is discarded, and nothing else has to be undone. ## Why delegation and recall are not symmetric | | Delegation-out | Recall | | ----------------- | ---------------------------------------------------------------------- | -------------------------------------------------------------------------- | | **Starts on** | The reference chain | The satellite, or the reference chain when an agent orders it | | **Who decides** | The reference chain dictates | The satellite originates, and the reference chain consumes a proof | | **First effect** | The position leaves the free balance | The position is destroyed on the satellite | | **Second effect** | The representation is created on the satellite | The position returns to the free balance | | **Safe because** | The tokens are gone from the free balance before the satellite is told | The tokens are gone from the satellite before the free balance is restored | In both directions the position is removed from where it was before it appears where it goes. At no moment is it usable in two places. ## Which movement for which need A validation always moves tokens out of a satellite wallet, so a sender on the reference chain does not obtain one. Tokens held on the reference chain reach a satellite by a path that starts on the reference chain. | To move tokens | Path | | --------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | From the reference chain to **one's own** wallet on a satellite | Delegation-out | | From the reference chain to **someone else** on a satellite | In one step: the position lands on the recipient's satellite wallet with no action from the recipient. `[[TBC: the function for a transfer from the reference chain to a recipient on a satellite]]` | | Newly issued tokens to an investor's wallet on a satellite | An agent mints directly to the satellite wallet, with no action from the investor. `[[TBC: the function for a mint to a wallet on a satellite]]` | | From a satellite to someone on the reference chain | A transfer from the satellite to the reference chain | | From a satellite back to **oneself** on the reference chain | Recall | The same result can always be obtained by combining two movements: a transfer on the reference chain after which the recipient delegates out, or a delegation-out to one's own satellite wallet followed by a transfer on the satellite. ## Summary | | Delegation-out | Transfer | Recall | | --------------------------------- | ----------------------------- | ------------------------------------------- | ------------------------------------------- | | **Owner changes** | No | Yes, unless both wallets are one identity's | No | | **Eligibility and rules checked** | For the holder's own position | At issuance of the validation | Not applicable: same owner | | **Message out** | Mint instruction | Compliance validation | Recall instruction, when an agent orders it | | **Message back** | None | Settlement notification | Burn proof | | **Final on the reference chain** | At once | At settlement | On receipt of the proof | | **`totalSupply`** | Unchanged | Unchanged | Unchanged | | **Position of the identity** | Unchanged | Changes, if the owner changes | Unchanged | --- # 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/movement-types.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.