> 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/the-primary-register/t-rex-and-erc-3643.md).
# T-REX and ERC-3643
T-REX is not a revision of a token standard. It is a protocol that adopts ERC-3643, the open standard for permissioned tokens, as the token layer of its register, and builds the rest around it: smart-account identities, a global identity registry, a position ledger, cross-chain settlement. This page draws the line between the two.
Throughout these docs, "the token layer" means an implementation of ERC-3643. "The protocol" means the system of which that token is one component.
## What ERC-3643 defines
ERC-3643 defines how a token conditions its transfers on the approval of on-chain validators. The standard is maintained by the ERC-3643 Association, independently of any implementation. It specifies six interfaces.
| Interface | What it standardizes |
| --------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
| `IERC3643` | The token: the ERC-20 surface, plus pause, freeze, forced transfer, recovery, mint and burn, and the links to its registry and its compliance. |
| `IERC3643IdentityRegistry` | The eligibility check, `isVerified`, and the registration of holders. |
| `IERC3643IdentityRegistryStorage` | The storage of the bindings between addresses and identities, shareable between tokens. |
| `IERC3643TrustedIssuersRegistry` | The Claim Issuers an asset trusts, and for which claim topics. |
| `IERC3643ClaimTopicsRegistry` | The claim topics an asset requires. |
| `IERC3643Compliance` | The compliance check, `canTransfer`, and the hooks the token calls after a mint, a burn or a transfer. |
The core of the standard is the rule these interfaces express together: a transfer executes only if the recipient is verified and the compliance allows it. The checks are inside the token itself, not in a wrapper around another token.
## What ERC-3643 leaves open
The standard says what a permissioned token checks. It does not say:
* how an identity is built and controlled;
* who may call the privileged functions, and how that authority is administered;
* which compliance rules exist and how they keep their state;
* how contracts are deployed and upgraded;
* anything beyond a single chain.
These are the areas where T-REX adds its own architecture.
## How the code is layered
The T-REX repository keeps the standard and the protocol apart, in three layers.
```mermaid
flowchart TB
subgraph L1["Layer 1: the standard interfaces"]
I["IERC3643 and the five registry and compliance interfaces"]
end
subgraph L2["Layer 2: the standard bases"]
B["One abstract contract per interface
implements that interface and nothing else"]
end
subgraph L3["Layer 3: the T-REX contracts"]
T["Token · TREXRegistry · IdentityRegistryStorage · ModularCompliance"]
end
L1 --> L2
L2 -->|"extended through internal hooks"| L3
```
* **Layer 1** is the set of standard interfaces, in `contracts/ERC-3643/`.
* **Layer 2** is one abstract base per interface, in `contracts/ERC-3643/base/`. Each base implements exactly its interface, over its own ERC-7201 storage namespace.
* **Layer 3** is the T-REX contracts. They inherit the bases and add everything specific to T-REX through internal hooks.
Two rules keep the layers clean. No base refers to anything in the T-REX layer. No T-REX extension writes into the storage of a base directly. A dedicated test suite exercises the standard surface alone, so the behavior of the standard layer is pinned independently of the extensions.
The bases follow the hook names of the ERC-3643 token base that OpenZeppelin is preparing for OpenZeppelin Contracts, so that the standard layer can be replaced by OpenZeppelin's once it is released. The bases derive from Tokeny's original implementation of the standard, and keep its copyright notice.
## What T-REX adds to each contract
| Contract | Standard base | What T-REX adds |
| ------------------------- | ---------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `Token` | `ERC3643Token` | Authorization through an AccessManager. The spender check on `transferFrom`. `identityTransfer`, by which an identity moves tokens held in its linked wallets. ERC-2612 permit. The bridged ledger: positions on satellites, in transit and reserved. The ERC-7786 messaging endpoint. The rule that the compliance and the registry of a circulating token are not replaced. |
| `TREXRegistry` | `ERC3643IdentityRegistry`, `ERC3643TrustedIssuersRegistry`, `ERC3643ClaimTopicsRegistry` | The three registries at one address. Required claim topics per identity type. Resolution of addresses through the global identity registry. Refusal of a revoked wallet. Eligibility of wallets on other chains, by ERC-7930 interoperable address. The eligibility switch. |
| `IdentityRegistryStorage` | `ERC3643IdentityRegistryStorage` | The fallback to the global identity registry when an address has no local binding, and events that signal when a local binding overrides the global one. |
| `ModularCompliance` | `ERC3643Compliance` | Typed modules: `RULE`, `SPENDER`, `TRACKER`. The compliance ledger: the total position of each identity, and what open validations promise to it and from it. The issuance and lifecycle of cross-chain validations. |
Around these four contracts, T-REX adds what the standard does not cover at all: ONCHAINID as a smart account, the `IdentityFactory` as the global identity registry, the `TREXAccessManager`, the `TREXFactory`, the `TREXImplementationAuthority`, the `TrustedGatewayRegistry`, and T-REX Lite.
## Where T-REX narrows the standard
An extension does not change the meaning of a standard function, with a small number of deliberate exceptions.
| Standard function | Behavior in T-REX | Reason |
| ----------------------------------------------------- | --------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------- |
| `setClaimTopicsRegistry`, `setTrustedIssuersRegistry` | Revert with `Deprecated`. | The `TREXRegistry` is its own topics and issuers registry. There is nothing else to point at. |
| `updateCountry` | Reverts with `Deprecated`. | The registry stores no country. Country is a compliance concern, owned by a compliance module. |
| `investorCountry` | Returns zero. | Same reason. |
| The `country` argument of `registerIdentity` | Ignored. | Same reason. |
| `setCompliance`, `setIdentityRegistry` | Revert with `TokenCirculating` once the token has supply. | The compliance has counted every movement since the first mint. A replacement would start every position at zero. |
T-REX also sets limits the standard leaves unbounded: at most 15 required claim topics and 50 trusted issuers per registry. They bound the work `isVerified` does on every transfer.
## What this means for an integrator
* **An ERC-3643 integration works against T-REX.** Code that holds an `IERC3643` token reference, or an `IERC3643IdentityRegistry` reference, calls the same functions with the same arguments. From the registry, `issuersRegistry()` and `topicsRegistry()` return the registry itself, so code that hops from one to the others lands on the same contract.
* **Interface detection works.** Each contract answers `supportsInterface` for the standard interface it implements. The `TREXRegistry` answers for all three registry interfaces.
* **An ERC-20 integration works too.** Wallets, venues and indexers that know only ERC-20 read balances and transfer without special knowledge. A transfer that the gates refuse reverts.
* **The holder of a position can be an identity.** An ONCHAINID is a smart account and holds tokens itself. Do not assume that a holding address is a wallet distinct from its identity.
## Two statements to avoid
**"ERC-3643 is a compliance module that can be added to any ERC-20."** It is not. ERC-3643 is the token standard itself: eligibility and compliance are inside the transfer logic of the token. They cannot be attached to an arbitrary ERC-20 from outside.
**"T-REX Lite is an ERC-3643 token."** It is not. T-REX Lite is an ERC-20 on a satellite chain with one rule: a transfer executes only by consuming a single-use validation issued by the reference chain. It carries no registry and no rules of its own: the compliance contract linked to it only stores the validations it receives. The ERC-3643 token, with its two gates, is on the reference chain, and its decisions are what T-REX Lite executes.
---
# 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/the-primary-register/t-rex-and-erc-3643.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.