> 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/guides/cross-chain/33.-open-an-asset-on-a-satellite.md).
# 33. Open an asset on a satellite
Opening an asset on a satellite makes the token on the reference chain and its T-REX Lite on that chain able to exchange messages, and makes the compliance able to authorize transfers there. A token opens no chain by default. The Issuer opens each satellite explicitly, with a route, a peer when one is needed, the two time windows that govern validations, and the deployment of T-REX Lite on the satellite. Until this is done, no position can be delegated to that chain and no transfer can be authorized on it.
## At a glance
| | |
| ----------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Triggered by** | Issuer |
| **Actors** | Issuer, Network governance, Platform |
| **Contracts** | `Token`, `ModularCompliance`, `TrustedGatewayRegistry` (read only), the T-REX Lite factory of the satellite |
| **Preconditions** | The token suite is deployed and commissioned (see [01](/guides/issuer/01.-deploy-a-token-suite.md) and [25](/guides/issuer/25.-commission-a-suite-and-grant-roles.md)); the callers hold `IDENTITY_MANAGER` and `COMPLIANCE_MANAGER` in the asset's domain; a gateway that reaches the satellite is in the `TrustedGatewayRegistry`; a T-REX Lite factory exists on the satellite |
| **Result** | `Token.isChainOpen(chainKey)` is true, T-REX Lite exists on the satellite, and the compliance can issue validations for that chain |
## Actors and roles
| Actor | Role in this flow | What they hold |
| ------------------ | ------------------------------------------------------------------------- | ---------------------------------------------------------------------------------- |
| Issuer | Chooses the gateway, registers the peer and sets the windows. | `IDENTITY_MANAGER` on the `Token`. `COMPLIANCE_MANAGER` on the `ModularCompliance` |
| Network governance | Has vetted the gateway beforehand. Does not transact in this flow. | `INTEROP_MANAGER` on the `TrustedGatewayRegistry` |
| Platform | Prepares the chain identifiers, relays the calls and confirms the result. | Whatever keys the Issuer has authorized |
## Sequence
```mermaid
sequenceDiagram
participant Platform
participant Issuer
participant Token
participant TGR as TrustedGatewayRegistry
participant MC as ModularCompliance
Platform->>TGR: isTrusted(gateway) (read)
Platform->>Issuer: settings prepared, submit
Issuer->>Token: setRoute(chainType, chainReference, gateway)
Token->>TGR: isTrusted(gateway)
Token-->>Platform: ChainRegistered, RouteSet(chainKey, gateway)
opt T-REX Lite is not at the token's own address
Issuer->>Token: setPeer(chainKey, peer)
Token-->>Platform: PeerSet(chainKey, peer)
end
opt not already set for the asset
Issuer->>MC: setDefaultValidityWindow(duration)
MC-->>Platform: DefaultValidityWindowSet(duration)
end
Issuer->>MC: setReconciliationWindow(chainKey, duration)
MC-->>Platform: ReconciliationWindowSet(chainKey, duration)
Note over Issuer,Token: step 5, the Issuer has T-REX Lite deployed on the satellite,
by a message the gateway carries to the T-REX Lite factory there
Platform->>Token: isChainOpen(chainKey) (read)
```
## Step by step
### Step 1. Prepare the settings
**Who:** Platform, on behalf of the Issuer
**Call:** Off-chain, using read calls
**Before the call:** The Issuer has chosen the satellite and the messaging provider that carries the asset's traffic to it.
**What happens:** The Platform gathers four things.
| Setting | How it is obtained |
| ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| The chain | Its ERC-7930 chain type and chain reference. For an EVM chain, the type is `0x0000` and the reference is the chain id in its shortest big-endian form, with no leading zero byte. |
| The gateway | The address, on the reference chain, of the ERC-7786 gateway of the chosen provider for that chain. `TrustedGatewayRegistry.isTrusted(gateway)` must be true. |
| The peer | The address of the asset's T-REX Lite on the satellite. On an EVM satellite where T-REX Lite sits at the token's own address, nothing is needed. |
| The windows | The validity window of the asset, and the reconciliation window for this chain: the longest time that chain takes to finalize a transaction and for its message to reach the reference chain, with a margin. |
**What changes:** Nothing on-chain.
### Step 2. Set the route
**Who:** Issuer (`IDENTITY_MANAGER`)
**Call:** `Token.setRoute(chainType, chainReference, gateway)`
**Before the call:** Step 1 is done.
**What the contract checks:**
1. The caller holds `IDENTITY_MANAGER` in the asset's domain. Otherwise the call reverts with `AccessManagedUnauthorized`.
2. The gateway is trusted by the network at this moment. Otherwise `GatewayNotTrusted`.
3. The chain reference is not empty and, for an EVM chain, has no leading zero byte. Otherwise `InvalidChainReference`.
**What changes:** The first time the token sees this chain, it records the chain type and reference behind the chain key and emits `ChainRegistered(chainKey, chainType, chainReference)`. It records the gateway as the route for that chain and emits `RouteSet(chainKey, gateway)`. The `chainKey` in these events is the identifier used in every later call for this chain.
### Step 3. Register the peer
Only when T-REX Lite is not at the token's own address: on a non-EVM satellite, or when the addresses differ.
**Who:** Issuer (`IDENTITY_MANAGER`)
**Call:** `Token.setPeer(chainKey, peer)`
**Before the call:** The Platform has encoded the address of T-REX Lite as an ERC-7930 interoperable address of that chain.
**What the contract checks:**
1. The caller holds `IDENTITY_MANAGER` in the asset's domain. Otherwise `AccessManagedUnauthorized`.
2. The peer is a canonical ERC-7930 address with an account part and no trailing bytes. Otherwise `InvalidPeer`.
3. The chain of the peer is the chain named by `chainKey`. Otherwise `PeerChainMismatch`.
**What changes:** The token records the peer for that chain and emits `PeerSet(chainKey, peer)`. The peer is the only recipient the token sends to on that chain and the only author it accepts messages from.
### Step 4. Set the windows
**Who:** Issuer (`COMPLIANCE_MANAGER`)
**Call:** `ModularCompliance.setDefaultValidityWindow(duration)`, once for the asset, and `ModularCompliance.setReconciliationWindow(chainKey, duration)`, for this chain
**Before the call:** The durations are decided, in seconds.
**What the contract checks:**
1. The caller holds `COMPLIANCE_MANAGER` in the asset's domain. Otherwise `AccessManagedUnauthorized`.
2. The duration is not zero. Otherwise `ZeroDuration`.
**What changes:** The compliance records the validity window and emits `DefaultValidityWindowSet(duration)`. It records the reconciliation window of the chain and emits `ReconciliationWindowSet(chainKey, duration)`. A validation issued from now on expires one validity window after its issuance, and its reservation is kept one reconciliation window longer.
### Step 5. Deploy T-REX Lite on the satellite
**Who:** Issuer
**Call:** `[[TBC: the call on the reference chain that has T-REX Lite deployed on a satellite]]`
**Before the call:** The route is set, so that a message can reach the satellite.
**What happens:** A message goes through the ERC-7786 gateway to the T-REX Lite factory of the satellite. The factory deploys T-REX Lite for the asset, with the token on the reference chain as its peer. On an EVM satellite, T-REX Lite is deployed at the token's own address. The Issuer does not deploy anything on the satellite itself.
**What changes:** On the satellite, T-REX Lite and its compliance contract exist for the asset, with no supply. On the reference chain, nothing.
### Step 6. Confirm the chain is open
**Who:** Platform
**Call:** Off-chain, using read calls
**Before the call:** Steps 2 to 5 are confirmed.
**What happens:** The Platform reads `Token.isChainOpen(chainKey)`, which must be true, and `Token.peerFor(chainKey)`, which must be the address of T-REX Lite. It reads `ModularCompliance.reconciliationWindowOf(chainKey)` and `ModularCompliance.defaultValidityWindow()`, which must not be zero, and `ModularCompliance.isIssuancePaused(chainKey)`, which must be false. It confirms on the satellite that T-REX Lite exists at the address of the peer.
**What changes:** Nothing on-chain.
## State after the flow
* `Token.routeFor(chainKey)` returns the gateway, and `Token.chainOf(chainKey)` returns the chain type and reference.
* `Token.peerFor(chainKey)` returns the registered peer, or the token's own address on an EVM chain where none was registered.
* `Token.isChainOpen(chainKey)` is true.
* `ModularCompliance.defaultValidityWindow()` and `ModularCompliance.reconciliationWindowOf(chainKey)` are set.
* T-REX Lite is deployed on the satellite, with the token as its peer.
* No position has moved. Nothing is bridged yet.
## Failure modes
| Symptom | Cause | Fix |
| -------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------ |
| Reverts with `AccessManagedUnauthorized` | The caller does not hold the role of the function: `IDENTITY_MANAGER` for the route and the peer, `COMPLIANCE_MANAGER` for the windows (check 1 of steps 2 to 4) | Grant the role: [25](/guides/issuer/25.-commission-a-suite-and-grant-roles.md) |
| `setRoute` reverts with `GatewayNotTrusted` | The gateway is not in the `TrustedGatewayRegistry` (step 2, check 2) | Use a gateway the network has vetted. Adding one is a decision of Network governance |
| `setRoute` reverts with `InvalidChainReference` | The chain reference is empty, or has a leading zero byte for an EVM chain (step 2, check 3) | Encode the chain id in its shortest form |
| `setPeer` reverts with `InvalidPeer`, or on the address encoding | The peer is not a canonical ERC-7930 address, has no account part, or has trailing bytes (step 3, check 2) | Encode the chain and the address in canonical form |
| `setPeer` reverts with `PeerChainMismatch` | The peer is on another chain than the one `chainKey` names (step 3, check 3) | Take `chainKey` from the `RouteSet` event of that chain |
| `setPeer` with an empty value reverts with `ChainNotRegistered` | Restoring the default peer on a chain the token has never seen | Set the route first |
| A window call reverts with `ZeroDuration` | The duration is zero (step 4, check 2) | Pass a positive duration |
| `isChainOpen` is false after step 2 | No peer is known: the satellite is not an EVM chain, and none was registered | Register the peer (step 3) |
| `isChainOpen` was true and is now false | The network removed the gateway from the registry | Set a route through another trusted gateway |
| The chain is open and a validation request reverts with `ReconciliationWindowNotSet` or `ValidityWindowNotSet` | A window was not set | Do step 4 |
| The chain is open and validations are never executed | T-REX Lite is not deployed on the satellite, or not at the address of the peer | Do step 5. On a chain where the address differs, register the peer (step 3) |
## Common misunderstandings
> **Wrong:** "Once the network supports a chain, every asset is available there."
>
> **Right:** The network vets gateways. Each Issuer opens its own asset, chain by chain. A token sends nothing to, and accepts nothing from, a chain it was not opened for.
> **Wrong:** "The Issuer can route through any bridge it likes."
>
> **Right:** A route can only name a gateway in the network's `TrustedGatewayRegistry`. The Issuer chooses among vetted gateways. It cannot point its token at a list of its own.
> **Wrong:** "Opening a satellite moves tokens there."
>
> **Right:** Opening a chain moves nothing. Positions reach a satellite by a movement that starts on the reference chain: a delegation-out by the holder, a transfer in one step to a recipient's satellite wallet, or a mint by an agent directly to a satellite wallet. Until then nothing is bridged and nothing can be transferred there. See [Movement types](/cross-chain-the-distributed-register/movement-types.md).
> **Wrong:** "The reconciliation window is how long a transfer has to execute."
>
> **Right:** That is the validity window. The reconciliation window is the extra time the register waits, after a validation expires, for the report of a transfer that executed just in time. It is sized on the satellite's finality and on the message latency, with a margin.
## Integration notes
* Take `chainKey` from the `ChainRegistered` or `RouteSet` event. It is the hash of the ERC-7930 chain identifier, and every per-chain call uses it.
* Choose the reconciliation window conservatively. A window that is too short turns ordinary settlements into late reconciliations.
* The windows are read when a validation is issued. Changing them later affects new validations only.
* Changing the route later is safe. A validation already sent is settled through the gateway it went out by, as long as the network still trusts that gateway.
* To close a satellite, set its route to the zero address. The token then sends nothing to the chain and refuses burn proofs from it. Settlements of validations already sent are still accepted through the gateway that carried them. To stop authorizing new transfers there while still recording those already executed, call `ModularCompliance.setIssuancePaused(chainKey, true)`.
* Grant `VALIDATION_KEEPER` to the keeper before the first transfer is authorized: [25](/guides/issuer/25.-commission-a-suite-and-grant-roles.md). The T-REX Network operates the keeper that discards expired validations.
* The caller of a transaction that sends a cross-chain message pays for the message, directly or through a paymaster. Opening a chain costs the Issuer its own transactions and the deployment message.
* Holders link their wallets on the satellite to their ONCHAINID before they delegate out: [07](/guides/identity/07.-link-a-wallet-to-an-onchainid.md).
## Related flows
* [30 Delegate a position out to a satellite](/guides/cross-chain/30.-delegate-a-position-out-to-a-satellite.md) : how a holder takes its own position to the satellite once it is open
* [31 Transfer on a satellite](/guides/cross-chain/31.-transfer-on-a-satellite.md) : what the windows govern
* [35 Discard or resolve a validation](/guides/cross-chain/35.-discard-or-resolve-a-validation.md) : the keeper's work once transfers are authorized
* [36 Handle a late reconciliation or a halt](/guides/cross-chain/36.-handle-a-late-reconciliation-or-a-halt.md) : pausing and closing a chain
* [26 Authorize spenders](/guides/issuer/26.-authorize-spenders.md) : listing the venues of the satellite
* [07 Link a wallet to an ONCHAINID](/guides/identity/07.-link-a-wallet-to-an-onchainid.md) : linking a wallet that lives on the satellite
---
# 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/guides/cross-chain/33.-open-an-asset-on-a-satellite.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.