> 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/build/quickstart.md). # Quickstart This page gets the protocol running on your machine: the code of the token suite and of the identity layer, built and tested, and a first test of your own against a complete local suite. It assumes you know Solidity and Foundry. It does not deploy anything on a public network. ## What you need | Tool | Used for | | --------------------------------- | ---------------------------------------------------------------------------------------------------------------- | | [Foundry](https://getfoundry.sh/) | Building and testing. Both repositories are Foundry projects, with Solidity 0.8.30 and the `cancun` EVM version. | | Git | Cloning the repositories. Dependencies are fetched with Soldeer, which ships with Foundry. | | Node.js and npm | Optional. The `package.json` scripts wrap the Foundry commands and install the Git hooks. | ## The two repositories | Repository | Package | Contains | | --------------------------------------------------------------------- | -------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | [T-REX-Network/T-REX](https://github.com/T-REX-Network/T-REX) | `@t-rex-network/t-rex` | The token suite: `Token`, `TREXRegistry`, `IdentityRegistryStorage`, `ModularCompliance` and its modules, `TREXFactory`, `TREXImplementationAuthority`, `TREXAccessManager`, the cross-chain endpoint and `UtilityChecker`. | | [T-REX-Network/ONCHAINID](https://github.com/T-REX-Network/ONCHAINID) | `@t-rex-network/onchainid` | The identity layer: `Identity`, `IdentityFactory`, `ERC734Validator`, `KeyApprovalModule`, `RecoveryModule`, `ReputationRegistry`, `EASClaimIssuer`. | Version 5 of T-REX and version 3 of ONCHAINID are on the `develop` branch of each repository. T-REX pulls ONCHAINID in as a dependency, so the T-REX repository alone is enough to run a complete suite. ## Build and test T-REX ```bash git clone https://github.com/T-REX-Network/T-REX.git cd T-REX git checkout develop forge soldeer install # fetch the dependencies forge build # compile forge test # run the tests ``` The build uses the IR pipeline of the compiler, which keeps `ModularCompliance` under the contract size limit. A full build takes minutes, not seconds. The same commands through npm, with a few more: | Command | What it runs | | ------------------- | ------------------------------------------------------------ | | `npm run build` | `forge build` | | `npm test` | `forge test --gas-report` | | `npm run test:core` | The tests without the fuzz suites and the tests of the mocks | | `npm run coverage` | A coverage summary in the terminal | | `npm run format` | `forge fmt --check` | ### What is in the repository | Folder | Content | | ------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `contracts/` | The contracts. `ERC-3643/` holds the standard interfaces and bases, the other folders the T-REX implementation: `token/`, `registry/`, `compliance/`, `factory/`, `proxy/`, `interop/`, `utils/`, `libraries/`. | | `test/` | Foundry tests: `unit/`, `integration/`, `fuzz/`, `invariant/` and `standard/`. | | `scripts/` | Deployment scripts for the compliance modules and for `UtilityChecker`. | | `certora/` | The specifications for formal verification. | | `mutation/` | The configuration of the mutation tests. | | `docs/` | Design notes, including the guide for module authors. | ## A first test against a local suite The integration tests share a base contract, `TREXSuiteTest`, in `test/integration/helpers/TREXSuiteTest.sol`. Its `setUp` deploys everything a suite needs, in one test environment: * an access manager, with the test contract as its administrator; * the identity layer: `IdentityFactory`, the key and claim registry module, the execution queue module, the reputation registry and the identity implementation; * the implementations of the suite, the `TREXImplementationAuthority` and the `TREXFactory`; * one token, available as `token`, deployed through the factory with no required claim topic and no compliance module; * an account that holds every agent role, `agent`, and an account that holds the owner and manager roles, `deployer`; * three holders with an ONCHAINID each, `alice`, `bob` and `charlie`, registered for the token, and an address with no identity, `another`. The token is paused and has no supply, as after any deployment. Create `test/Quickstart.t.sol`: ```solidity // SPDX-License-Identifier: GPL-3.0 pragma solidity 0.8.30; import { ErrorsLib } from "contracts/libraries/ErrorsLib.sol"; import { TREXSuiteTest } from "test/integration/helpers/TREXSuiteTest.sol"; contract QuickstartTest is TREXSuiteTest { function setUp() public override { super.setUp(); // The agent issues a first position, then opens the asset. vm.startPrank(agent); token.mint(alice, 1000); token.unpause(); vm.stopPrank(); } function test_transferBetweenEligibleHolders() public { vm.prank(alice); token.transfer(bob, 100); assertEq(token.balanceOf(alice), 900); assertEq(token.balanceOf(bob), 100); } function test_transferToAnAddressWithNoIdentityReverts() public { vm.prank(alice); vm.expectRevert(ErrorsLib.UnverifiedIdentity.selector); token.transfer(another, 100); } } ``` Run it: ```bash forge test --match-contract QuickstartTest -vvv ``` What the two tests show: * **The transfer to `bob` succeeds.** `bob` resolves to an identity, and this token requires no claim, so the identity is eligible. No compliance module is bound, so every amount is allowed. * **The transfer to `another` reverts with `UnverifiedIdentity`.** The address resolves to no identity. The token refuses the recipient before anything moves. This is the eligibility gate, described in [Eligibility and compliance: the two gates](/the-primary-register/eligibility-and-compliance-the-two-gates.md). ### Going further with the helpers | Helper | What it gives | | ------------------------------------------------------------- | ---------------------------------------------------------------------------------------------- | | `_deployToken(salt, name, symbol)` | Another token, through the factory, with its roles wired. | | `_deployTokenWithClaimTopic(salt, name, symbol)` | A token that requires the claim topic `CLAIM_TOPIC_1`. | | `_deployTokenWithClaimedHolders(salt, name, symbol)` | The same, with `alice`, `bob` and `charlie` registered and holding a claim from `claimIssuer`. | | `_deployIdentity(wallet, salt)` | An ONCHAINID for a wallet. | | `_addClaim(identity, topic, data, signerKey, issuer, caller)` | A signed claim added to an identity. | | `_removeClaim(identity, topic, caller)` | The removal of that claim, to see a holder stop being eligible. | `InteropSuiteTest`, in the same folder, extends the suite with the cross-chain setup. The tests under `test/integration/` are the best examples of every operation documented in the Guides. ## Build and test ONCHAINID ```bash git clone https://github.com/T-REX-Network/ONCHAINID.git cd ONCHAINID git checkout develop npm ci # installs the Git hooks and runs forge soldeer install npm run build # forge build npm test # forge test ``` > **Access required.** The `RecoveryModule` wraps a contract from OpenZeppelin's `openzeppelin-accounts` repository, which is private. `forge soldeer install` clones it, so building the ONCHAINID repository requires read access to that repository and an authenticated Git. Building the T-REX repository does not. ## Use the contracts in your own project Both packages ship the Solidity sources in `contracts/` and the compiled artifacts, ABI and bytecode, in `out/`, one JSON file per contract. ```bash npm add @t-rex-network/t-rex @t-rex-network/onchainid ``` ```solidity import { IToken } from "@t-rex-network/t-rex/contracts/token/IToken.sol"; import { IIdentity } from "@t-rex-network/onchainid/contracts/interface/IIdentity.sol"; import { IClaimIssuer } from "@t-rex-network/onchainid/contracts/interface/IClaimIssuer.sol"; ``` The T-REX sources import ONCHAINID under the prefix `@onchain-id/solidity/` and OpenZeppelin under `@openzeppelin/contracts/` and `@openzeppelin/contracts-upgradeable/`, version 5.7.0. A project that compiles them maps these three prefixes to the installed packages in its remappings. An application that only reads and calls deployed contracts needs the ABIs from `out/`, and no remapping. ## Where to go next | You want to | Read | | ----------------------------------------- | -------------------------------------------------------------------------------------------- | | Understand what the tests above exercised | [Protocol at a glance](/start-here/protocol-at-a-glance.md) | | Deploy an asset on a network | [J1 Issuer journey: launch an asset](/guides/journeys/j1.-issuer-journey-launch-an-asset.md) | | Integrate a wallet or a custody platform | [Integrate a wallet or a custodian](/build/integrate-a-wallet-or-a-custodian.md) | | See every operation and its checks | [About the guides](/guides/about-the-guides.md) | --- # 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/build/quickstart.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.