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	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	@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	@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

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:

// 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:

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.

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

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.

npm add @t-rex-network/t-rex @t-rex-network/onchainid

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
Deploy an asset on a network	J1 Issuer journey: launch an asset
Integrate a wallet or a custody platform	Integrate a wallet or a custodian
See every operation and its checks	About the guides