> 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/governance-and-infrastructure/deterministic-deployment-create3.md).

# Deterministic deployment (CREATE3)

Token suites and identities are deployed through factories that use CREATE3. Under CREATE3, the address of a contract depends only on who deploys it and on a salt. It does not depend on the contract's code or on its constructor arguments. This property is used in three ways: an asset has one address on every EVM chain it reaches, a participant has one identity address across chains, and a factory can know an address before the contract exists.

## What CREATE3 changes

| Deployment method | The address depends on                     |
| ----------------- | ------------------------------------------ |
| CREATE            | The deployer and its transaction count     |
| CREATE2           | The deployer, a salt and the creation code |
| CREATE3           | The deployer and a salt                    |

With CREATE2, two contracts with different code land at different addresses even with the same salt. The token on the reference chain and T-REX Lite on a satellite are different contracts, so CREATE2 could never give them one address. CREATE3 removes the code from the derivation.

## Token suites

The `TREXFactory` deploys every contract of a suite through CREATE3.

* **One salt, one suite.** The Deployer chooses a salt, a string, for each suite. A salt can be used once on a given factory. `getToken(salt)` returns the token deployed with it.
* **One slot per contract.** Each contract of the suite takes its own address, derived from the factory's address, the salt and the kind of contract. The contracts of one suite never collide, and two suites never collide.
* **Nothing else enters the derivation.** The name, the symbol, the modules, the claim configuration, the beacons and the version of the implementations do not move any address.

### Addresses known in advance

Because an address does not depend on the contract deployed there, the factory computes every address of a suite before it deploys anything. It uses them to wire the contracts to one another in a single transaction.

```mermaid
flowchart TB
    P["Compute the address the token will have"] --> AM["Deploy the access manager,<br/>unless one is supplied"]
    AM --> ST["Deploy the identity storage,<br/>already bound to the future registry"]
    ST --> RG["Deploy the registry,<br/>with its claim topics and trusted issuers"]
    RG --> MC["Deploy the compliance,<br/>already bound to the future token"]
    MC --> ID["Create the token's ONCHAINID,<br/>for the future token address"]
    ID --> TK["Deploy the token at the computed address"]
    TK --> H["Commission the suite and hand over the admin role"]
```

The compliance is bound to its token from its first moment, the storage to its registry, and the token's identity to the token. There is no intermediate state in which a contract of the suite points at nothing, and no follow-up transaction that could be forgotten.

### One address on every EVM chain

A suite's addresses are a function of the factory's address and the salt. Where the factory sits at the same address on two EVM chains, the same salt gives the same addresses on both.

This is what lets T-REX Lite sit at the token's address on an EVM satellite, although it is a different contract. T-REX Lite is deployed there by the T-REX Lite factory of the satellite, on a message that arrives through the ERC-7786 gateway. An asset has a single, recognizable address across the EVM chains it reaches, and the token finds its peer on a satellite without being told where it is. See [The T-REX Ledger and its satellites](/cross-chain-the-distributed-register/the-t-rex-ledger-and-its-satellites.md).

### Who may claim an address

An address that can be computed in advance can also be taken in advance. Two controls prevent it.

* **Deployment is role-gated.** Deploying a suite requires the platform `ASSET_DEPLOYER` role. The right to deploy at a deterministic address, and so to claim the address of an asset across chains, is controlled.
* **The token's identity cannot be pre-empted.** When the Deployer supplies an existing ONCHAINID for the token, the factory checks that the `IdentityFactory` does not already bind the future token address to a different identity. Otherwise the token would answer to one identity while the identity layer answered another.

## Identities

The `IdentityFactory` deploys each ONCHAINID through CREATE3 as well.

| The address of an identity depends on | It does not depend on              |
| ------------------------------------- | ---------------------------------- |
| The factory's address                 | The implementation of the identity |
| The identity type                     | The modules of its type            |
| The salt chosen at creation           |                                    |
| The first account of the identity     |                                    |
| Its keys                              |                                    |

* **The same inputs give the same address** on every EVM chain where the factory sits at the same address. A participant has one identity address across chains.
* **The first account is part of the address.** Somebody who replays another party's creation with a different account does not obtain the identity address that party expected.
* **The modules are not.** Network governance can change the modules of a type without moving the address of any identity created afterward.

The beacon that every identity points to is itself deployed at a CREATE3 address fixed when the factory is constructed.

## Limits

* **EVM chains with a non-standard derivation.** Some chains compute contract addresses differently. On such a chain the same factory and salt give different addresses. The `IdentityFactory` detects this when its beacon is initialized and refuses to proceed, so it never ends up pointing at an empty address.
* **The factory must be at the same address.** Address equality across chains is inherited from the factory. A factory deployed at a different address on another chain produces different addresses.
* **Non-EVM chains.** Addresses there have another format. T-REX Lite on a non-EVM satellite has an address of that chain, registered by the Issuer as the token's peer. See [Non-EVM satellites](/cross-chain-the-distributed-register/non-evm-satellites.md).

## Reading deployments

| Read or event                                                         | Gives                                                |
| --------------------------------------------------------------------- | ---------------------------------------------------- |
| `TREXFactory.getToken(salt)`                                          | The token deployed with a salt                       |
| `TREXSuiteDeployed(token, registry, storage, compliance, salt)`       | The addresses of a new suite                         |
| `IsolatedSuiteDeployed(token, beacons)`                               | The same for an isolated suite, with its own beacons |
| `Deployed(address)`                                                   | Each contract the factory deploys                    |
| `IdentityDeployed` and `IdentityTypeRecorded(identity, identityType)` | A new identity and its type                          |


---

# 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/governance-and-infrastructure/deterministic-deployment-create3.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.