> 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/start-here/actors-and-roles.md). # Actors and roles This page lists who takes part in the protocol and what each participant holds. Authority comes from three places: * **Roles** in an AccessManager gate every privileged function on a token suite and on the network-level contracts. * **Keys** with purposes gate what can be done with an identity. * **Trust in Claim Issuers** decides whose attestations count, per asset and at network level. The docs use the actor names below everywhere. They never write "admin", "user" or "KYC provider". ## Actors | Actor | What it is | What it holds | | ------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Issuer** | The legal entity that brings an asset onto the register. Decides the claim topics Investors must satisfy, the Claim Issuers it trusts, the compliance rules, and the satellites the asset reaches. | `ADMIN_ROLE` on the suite's `TREXAccessManager`, and through it the `OWNER`, `SUITE_ADMIN` and `AGENT_ADMIN` roles of its domain. Delegates operational roles to agents. | | **Compliance Owner** | Whoever configures the asset's compliance rules. Usually the Issuer. | `OWNER` role on `ModularCompliance`. | | **Token Agent** | An operator acting for the Issuer on the token: the transfer-agent function. Often the Issuer's platform provider. | One or more agent roles on the `Token`: minter, burner, freezer, forced transfer, recovery, pauser. | | **Registry Agent** | An operator maintaining local wallet registrations for the asset. Often the same organization as the Token Agent. | `AGENT` role on the `TREXRegistry`. | | **Investor** | A natural or legal person holding or acquiring the asset. | An ONCHAINID it controls. The Investor holds the asset in the identity itself, in wallets linked to it, or both. | | **Identity Owner** | Any participant in its capacity as controller of an ONCHAINID: an Investor, an Issuer, a Claim Issuer. Used when a step is about the identity itself (keys, claims, wallet links, recovery). | A `MANAGEMENT` key on the identity. | | **Claim Issuer** | A trusted third party that verifies a participant off-chain and signs claims about it: a KYC or AML provider, an accreditation verifier, the Issuer's own compliance function. | An ONCHAINID of type `CLAIM_ISSUER` with `CLAIM_SIGNER` keys. Listed by Issuers as trusted for specific claim topics. | | **Venue or application** | An exchange, a market maker, a lending protocol, a settlement contract: anything through which the asset is traded or used. Applications available in the ecosystem are listed in the [T-REX AppStore](/appstore.md). | An ONCHAINID of its own, of type `SMART_CONTRACT` when it is a contract, with the claims the asset requires. A venue that holds tokens in escrow is a holder and passes the same eligibility checks as any holder. A venue that only moves tokens for holders through `transferFrom` is a spender, and the asset's spender rules apply to it. | | **Platform** | The integrator's application, front end and back end, orchestrating calls for Issuers, agents or Investors. | No protocol role of its own. It holds whatever keys or roles it has been granted. | | **Validation Keeper** | An operator that discards cross-chain validations that expired without being executed. The T-REX Network runs it. | `VALIDATION_KEEPER` role on `ModularCompliance`, granted by the Issuer. | | **Guardian** | A party an Identity Owner has chosen to help recover the identity if its keys are lost. | A guardian entry in the identity's `RecoveryModule`. Guardians act together, by weighted quorum. | | **Deployer** | Whoever deploys token suites through the `TREXFactory`: an Issuer that was granted access, or a tokenization provider that deploys on behalf of its customers. | The platform `ASSET_DEPLOYER` role. | | **Network governance** | The parties that operate the shared contracts: the factory, the published versions, the trusted gateways, the identity factory, the shared modules and adapters. | Roles in the access manager of the network. Each role is held by a separate multisig, with its own members and threshold. | When one organization plays two roles, the docs keep both names. The Token Agent and the Registry Agent are typically the same operator. The Issuer is typically its own Compliance Owner. ## Roles on a token suite Every privileged function on a suite is gated by a role held in the suite's `TREXAccessManager`, which follows OpenZeppelin's AccessManager. A contract asks one question: does the caller hold the role mapped to this function? How the role is held (a single key, a multisig, an institution's governance process, an automated system) is a policy decision outside the contract. Roles are scoped to a **domain**. A domain is an issuer, or a fund: one team across every token in it. A role identifier packs the domain and the role number together, so the minter of one domain cannot mint a token of another, even when both domains share one AccessManager. | Role | What it gates | Administered by | | ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------- | | `OWNER` | On `TREXRegistry`: trusted issuers, required claim topics (default and per identity type), the eligibility switch, the identity storage. On `ModularCompliance`: adding, configuring and removing modules, binding the token, repairing a position. On `IdentityRegistryStorage`: unbinding a registry. | `ADMIN_ROLE` | | `SUITE_ADMIN` | Grants and revokes `TOKEN_MANAGER`, `IDENTITY_MANAGER` and `COMPLIANCE_MANAGER`. | `ADMIN_ROLE` | | `AGENT_ADMIN` | Grants and revokes every agent role, `IRS_BINDER` and `VALIDATION_KEEPER`. | `ADMIN_ROLE` | | `TOKEN_MANAGER` | `setName`, `setSymbol`. | `SUITE_ADMIN` | | `IDENTITY_MANAGER` | `setOnchainID`, `setIdentityRegistry`, `setCompliance`, and the cross-chain routes: `setRoute`, `setPeer`. | `SUITE_ADMIN` | | `COMPLIANCE_MANAGER` | Cross-chain validation settings: `setDefaultValidityWindow`, `setReconciliationWindow`, `setIssuancePaused`. | `SUITE_ADMIN` | | `AGENT` | On `TREXRegistry`: `registerIdentity`, `updateIdentity`, `deleteIdentity`. On `Token`: sending a mint instruction or a forced-recall instruction to a satellite. On `ModularCompliance`: requesting a transfer validation on behalf of a holder. | `AGENT_ADMIN` | | `AGENT_MINTER` | `mint` | `AGENT_ADMIN` | | `AGENT_BURNER` | `burn` | `AGENT_ADMIN` | | `AGENT_PARTIAL_FREEZER` | `freezePartialTokens`, `unfreezePartialTokens` | `AGENT_ADMIN` | | `AGENT_ADDRESS_FREEZER` | `setAddressFrozen` | `AGENT_ADMIN` | | `AGENT_FORCED_TRANSFER` | `forcedTransfer` | `AGENT_ADMIN` | | `AGENT_RECOVERY_ADDRESS` | `recoveryAddress` | `AGENT_ADMIN` | | `AGENT_PAUSER` | `pause`, `unpause` | `AGENT_ADMIN` | | `VALIDATION_KEEPER` | `discardExpiredValidations`, `resolveStuckValidation` | `AGENT_ADMIN` | | `IRS_BINDER` | Binding a registry to an `IdentityRegistryStorage`. | `AGENT_ADMIN` | | `IRS_WRITER` | Writing to an `IdentityRegistryStorage`. Held by registries only, never by a person. | `ADMIN_ROLE` | `ADMIN_ROLE` is the root role of the AccessManager. It administers `OWNER`, `SUITE_ADMIN`, `AGENT_ADMIN` and `IRS_WRITER`, and it commissions suites. When the `TREXFactory` deploys the manager for a new suite, it hands `ADMIN_ROLE` to the account the Issuer named and renounces its own. How to read the table: * **Batch functions follow the single operation.** `batchMint` requires the role that gates `mint`, and so on for every batch variant. * **Two contracts hold roles themselves.** The `Token` holds `AGENT`, so that a recovery can update the registry. The `TREXRegistry` holds `IRS_WRITER` on its storage. Agents edit investor records through a registry, never in the storage directly. * **Holder operations need no role.** `transfer`, `approve`, `transferFrom`, `permit` and `identityTransfer` are open to holders and are gated by eligibility and compliance, not by roles. An identity transfers the tokens it holds with `transfer`, and the tokens held in its linked wallets with `identityTransfer`. A holder's own identity can also request a transfer validation for its satellite wallets without any role. * **Some functions belong to a contract, not to a role.** The calls by which the compliance and the token settle a cross-chain validation between them are callable only by the bound counterpart. No role opens them. ## Platform roles Platform roles govern the contracts that all suites share. They live in a reserved domain that no suite role can reach. Network governance holds `OWNER`, `VERSION_MANAGER` and `INTEROP_MANAGER`, and grants `ASSET_DEPLOYER` to the Issuers and tokenization providers that deploy suites. | Role | What it gates | | ----------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `OWNER` | On `TREXFactory`: the references every new suite is wired to (`setImplementationAuthority`, `setIdFactory`, `setTrustedGatewayRegistry`). Held by Network governance. | | `VERSION_MANAGER` | On `TREXImplementationAuthority`: publishing a version and upgrading the shared beacons (`publish`, `upgrade`, `publishAndUpgrade`). | | `ASSET_DEPLOYER` | Deploying an asset. On `TREXFactory`: deploying suites (`deployTREXSuite`, `deployTREXSuiteIsolated`). On `IdentityFactory`: creating the ONCHAINID of a token, of type `ASSET`. Granted to Issuers once they are given access, and to tokenization providers that deploy for their customers. Also held by the `TREXFactory`, which creates the identity of each token as it deploys it. Creating an asset identity apart from a token deployment takes the same role and is uncommon. | | `INTEROP_MANAGER` | On `TrustedGatewayRegistry`: adding and removing a trusted ERC-7786 gateway. Removing a gateway severs every route through it at once. | > **Trust statement.** `VERSION_MANAGER` can replace the code behind every suite that follows the shared beacons. A version upgrade is voted by Network governance and executes after a delay. An Issuer that does not accept that deploys an isolated suite, whose beacons belong to its own AccessManager. ## Roles in the identity layer The identity layer is governed through the access manager of the network, like the platform roles, and separately from any token suite. Its roles are distinct from the platform roles and are held by different multisigs. | Authority | What it gates | | ----------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Identity layer administration | The policy of each identity type (who may create it, whether it can be self-deployed, whether it is bound to a single wallet), the modules each type is deployed with, the trusted gateways for cross-chain wallet links, the trusted ERC-7913 verifiers. | | Identity-type creation roles | `createIdentityFor` for a given type: deploying an identity on behalf of another account. | | Beacon upgrader | Upgrading the implementation behind every identity. A dedicated role with an execution delay, so an upgrade is scheduled and visible before it takes effect. | | `REPUTATION_MANAGER` | On `ReputationRegistry`: the reputation score of an identity, the default score per identity type, and the threshold a Claim Issuer must meet. | ## Keys on an identity An ONCHAINID is a smart account controlled by keys, each holding one or more purposes. A key is a signer: an ECDSA account, a smart-contract wallet, a passkey, or any scheme that has an ERC-7913 verifier. Because the identity is an account, it holds tokens itself and transacts directly. Wallets are optional: an Investor can keep its whole position in its identity and sign with a passkey, link existing wallets to the identity, or do both. | Purpose | Value | What the key can do | | -------------- | ----- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `MANAGEMENT` | 1 | Control the identity: add and remove keys, install and remove modules, link and revoke wallets. | | `ACTION` | 2 | Act for the identity toward external contracts, which includes transferring the tokens the identity holds. It cannot change the identity itself, its keys or its wallet links. | | `CLAIM_SIGNER` | 3 | Sign claims as this identity, and add or remove claims on it. This is the key a Claim Issuer signs with. | | `ENCRYPTION` | 4 | Hold encryption material. | | `CLAIM_ADDER` | 5 | Add claims to the identity. It cannot remove them. | | `PROPOSER` | 6 | Queue an execution. It cannot run or approve one on its own. | ## Identity types Every identity has a type, recorded by the `IdentityFactory` when the identity is created and never changed afterward. The type is a trust signal: the rest of the protocol reads it from the factory, not from the identity, so an identity cannot lie about what it is. | Type | Value | Represents | Created by | | ------------------ | ----- | ------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `ASSET` | 1 | A token. | The `TREXFactory`, when it deploys a token, with the `ASSET_DEPLOYER` role. A Deployer holds the same role and can create one apart from a deployment. Self-deployment is closed. Bound to a single address: the token. | | `INDIVIDUAL` | 2 | A natural person. | Self-deployment. Or an operator on the person's behalf, for a wallet that has no identity yet: an Issuer's onboarding agent, a Claim Issuer. | | `CORPORATE` | 3 | A legal entity. | Self-deployment, or an operator on the entity's behalf, as for an individual. | | `IOT` | 4 | A device. | Self-deployment, or an operator holding the creation role. | | `CLAIM_ISSUER` | 5 | A Claim Issuer. | An authorized party only. Self-deployment is closed. | | `SMART_CONTRACT` | 6 | A venue, a protocol, a vault, an escrow. | A role granted by Network governance. Self-deployment is closed. Bound to a single address: the contract. | | `PUBLIC_AUTHORITY` | 7 | A regulator, a court, a government issuer. | An authorized party only. Self-deployment is closed. | | `AI_AGENT` | 8 | An autonomous agent. | Self-deployment, or an operator holding the creation role. | The "Created by" column is the reference configuration. The policy of each type is set by Network governance. Self-deployment means the caller deploys an identity for itself and is linked as its first wallet. An Issuer can require a different set of claim topics per identity type, so that an asset asks one thing of an `INDIVIDUAL` and another of a `CORPORATE`. ## How Claim Issuers are trusted The protocol never issues or attests a claim. Claim Issuers do. Trust in them works at two levels, and the two are independent. **Per asset: whose claims make an investor eligible.** Each Issuer lists, in its `TREXRegistry`, the Claim Issuers it trusts and the topics it trusts each of them for. For eligibility, only a claim from a Claim Issuer trusted for that topic counts. A claim from any other issuer is ignored. **At network level: who may write a claim onto an identity.** A claim reaches an identity in one of two ways: * The Identity Owner adds it, or has granted the Claim Issuer a `CLAIM_SIGNER` or `CLAIM_ADDER` key on the identity. * The Claim Issuer adds it directly, with no key grant. This is accepted only when the issuer's identity is of type `CLAIM_ISSUER` and its reputation score meets the network's threshold. The reputation score is a number kept in the `ReputationRegistry`. Identities of type `CLAIM_ISSUER` created through the factory start with the default score for that type. The `REPUTATION_MANAGER` raises the score of an issuer after review, or sets it to zero for an issuer found to be compromised. Granting, vetting and revoking standing are the same operation: setting a score. A Claim Issuer's standing covers only the claims it signs itself. It never lets one issuer write a claim attributed to another. How a claim is evaluated when an investor receives a position is described in [Eligibility and compliance: the two gates](/the-primary-register/eligibility-and-compliance-the-two-gates.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/start-here/actors-and-roles.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.