> 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/reference/token-suite/access-manager-and-roles.md). # Access manager and roles Every restricted function of a suite asks one contract whether the caller may call it: the suite's `TREXAccessManager`. This page lists the manager's own functions, how role identifiers are built, which role gates which function, and who administers each role. The concept is in [Access management: roles and domains](/governance-and-infrastructure/access-management-roles-and-domains.md). ### At a glance | | | | ------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Source** | `contracts/utils/TREXAccessManager.sol`, `contracts/libraries/RolesLib.sol`, `contracts/libraries/AccessManagerSetupLib.sol` | | **Base** | OpenZeppelin's `AccessManagerUpgradeable`: `grantRole`, `revokeRole`, `renounceRole`, `hasRole`, `setRoleAdmin`, `setTargetFunctionRole`, execution delays and scheduled operations work as documented by OpenZeppelin | | **Added by T-REX** | Domains: a manager can serve several suites, each with its own set of role holders | | **Deployed as** | A beacon proxy. One per suite when the factory deploys it, or one supplied by the Issuer and shared by several suites | ### Domains A domain is a number that scopes the roles of one asset. The contracts of a suite are assigned to a domain, and a role granted in that domain applies to every contract assigned to it. | Function | Access | Behavior | | ----------------------------------------------------------- | ------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------- | | `createDomain(name)` | `ADMIN_ROLE` | Creates the next domain, numbered from 1, and returns its id. Emits `DomainCreated(uint32 indexed domainId, string name)` | | `assign(domainId, target)` | `ADMIN_ROLE` | Assigns a contract to a domain. Reverts with `DomainNotFound`, `ZeroAddress`. Emits `DomainAssigned(uint32 indexed domainId, address indexed target)` | | `domainOf(target)`, `domainName(domainId)`, `domainCount()` | Anyone, read | The domain of a contract (0 when it has none), the name of a domain, the number of domains | ### Role identifiers A role is a `uint64`: the domain id in the upper 32 bits, a role number in the lower 32 bits. | Builder in `RolesLib` | Result | | --------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `forDomain(domainId, role)` | A suite role in a domain. The role number is the index of the role in the enum `Role`, plus one | | `forDomain(domainId, customName)` | A custom role in a domain. The role number is derived from the hash of a `bytes32` name and carries the flag `0x80000000`, so it never collides with a standard role | | `platform(role)` | A platform role. The domain is `type(uint32).max` | `ADMIN_ROLE` is OpenZeppelin's root role of the manager, with the value 0. It belongs to no domain. ### Suite roles The number is the index in `RolesLib.Role`. | # | Role | Functions it gates | Administered by | | -- | ------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------- | | 0 | `OWNER` | `TREXRegistry`: `addClaimTopic`, `removeClaimTopic`, `addClaimTopicForIdentityType`, `removeClaimTopicForIdentityType`, `addTrustedIssuer`, `removeTrustedIssuer`, `updateIssuerClaimTopics`, `disableEligibilityChecks`, `enableEligibilityChecks`, `setIdentityRegistryStorage`. `ModularCompliance`: `addModule`, `addAndSetModule`, `callModuleFunction`, `removeModule`, `forceRemoveModule`, `resyncModuleTypes`, `fixPosition`, `bindToken`, `unbindToken`. `IdentityRegistryStorage`: `unbindIdentityRegistry` | `ADMIN_ROLE` | | 1 | `AGENT` | `TREXRegistry`: `registerIdentity`, `batchRegisterIdentity`, `updateIdentity`, `deleteIdentity`. `Token`: `dispatchMintInstruction`, `dispatchRecallInstruction`. `ModularCompliance`: `requestTransferValidation` on behalf of a holder | `AGENT_ADMIN` | | 2 | `AGENT_MINTER` | `Token`: `mint`, `batchMint` | `AGENT_ADMIN` | | 3 | `AGENT_BURNER` | `Token`: `burn`, `batchBurn` | `AGENT_ADMIN` | | 4 | `AGENT_PARTIAL_FREEZER` | `Token`: `freezePartialTokens`, `unfreezePartialTokens` and their batch forms | `AGENT_ADMIN` | | 5 | `AGENT_ADDRESS_FREEZER` | `Token`: `setAddressFrozen`, `batchSetAddressFrozen` | `AGENT_ADMIN` | | 6 | `AGENT_RECOVERY_ADDRESS` | `Token`: `recoveryAddress` | `AGENT_ADMIN` | | 7 | `AGENT_FORCED_TRANSFER` | `Token`: `forcedTransfer`, `batchForcedTransfer` | `AGENT_ADMIN` | | 8 | `AGENT_PAUSER` | `Token`: `pause`, `unpause` | `AGENT_ADMIN` | | 9 | `TOKEN_MANAGER` | `Token`: `setName`, `setSymbol` | `SUITE_ADMIN` | | 10 | `IDENTITY_MANAGER` | `Token`: `setOnchainID`, `setIdentityRegistry`, `setCompliance`, `setRoute`, `setPeer` | `SUITE_ADMIN` | | 11 | `AGENT_ADMIN` | Grants and revokes the agent roles, `IRS_BINDER` and `VALIDATION_KEEPER` | `ADMIN_ROLE` | | 12 | `SUITE_ADMIN` | Grants and revokes `TOKEN_MANAGER`, `IDENTITY_MANAGER` and `COMPLIANCE_MANAGER` | `ADMIN_ROLE` | | 13 | `IRS_BINDER` | `IdentityRegistryStorage`: `bindIdentityRegistry` | `AGENT_ADMIN` | | 14 | `IRS_WRITER` | `IdentityRegistryStorage`: `addIdentityToStorage`, `modifyStoredIdentity`, `removeIdentityFromStorage` | `ADMIN_ROLE` | | 15 | `COMPLIANCE_MANAGER` | `ModularCompliance`: `setDefaultValidityWindow`, `setReconciliationWindow`, `setIssuancePaused` | `SUITE_ADMIN` | | 16 | `VALIDATION_KEEPER` | `ModularCompliance`: `discardExpiredValidations`, `resolveStuckValidation` | `AGENT_ADMIN` | * **A batch function has no mapping of its own.** It is authorized by the role of its single-item counterpart, unless a role is mapped to the batch function itself. * **A function with no mapping falls to `ADMIN_ROLE`.** This is the behavior of OpenZeppelin's manager for an unconfigured function. * **Two contracts hold roles.** Commissioning a suite grants `AGENT` to the token in its domain, and `IRS_WRITER` to the registry in the domain of its storage. Who holds each role in practice is in [Actors and roles](/start-here/actors-and-roles.md). ### Platform roles Platform roles live in the access manager of the network, not in the manager of a suite. | Role | Functions it gates | | ----------------- | -------------------------------------------------------------------------------------------------------------------------- | | `OWNER` | `TREXFactory`: `setImplementationAuthority`, `setIdFactory`, `setTrustedGatewayRegistry` | | `VERSION_MANAGER` | `TREXImplementationAuthority`: `publish`, `upgrade`, `publishAndUpgrade` | | `ASSET_DEPLOYER` | `TREXFactory`: `deployTREXSuite`, `deployTREXSuiteIsolated`. `IdentityFactory`: the creation of identities of type `ASSET` | | `INTEROP_MANAGER` | `TrustedGatewayRegistry`: `setTrustedGateway` | ### Setting a suite up `AccessManagerSetupLib` holds the tables above and applies them. | Function | What it does | | --------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------- | | `setupTokenRoles`, `setupTREXRegistryRoles`, `setupIdentityRegistryStorageRoles`, `setupModularComplianceRoles` | Map each function of one contract to its role in a domain, with `setTargetFunctionRole` | | `setupRoleAdmins(accessManager, domainId)` | Set the administrator of each role of a domain, as in the table | | `commissionSuite(accessManager, token)` | Do all of the above for a suite, and grant the two roles the contracts hold | The factory calls `commissionSuite` when it deploys the manager. For a manager the Issuer supplies, the Issuer makes the call: see [25 Commission a suite and grant roles](/guides/issuer/25.-commission-a-suite-and-grant-roles.md). ### Ownership of a suite contract Each suite contract exposes ERC-173 on top of its access manager. | Function | Behavior | | --------------------------------- | -------------------------------------------------------------------------------------------------------------- | | `authority()`, `owner()` | The access manager of the contract | | `setAuthority(newAuthority)` | OpenZeppelin's function: callable by the current manager only. Emits `AuthorityUpdated(address authority)` | | `transferOwnership(newAuthority)` | Calls `setAuthority` and emits `OwnershipTransferred(address indexed previousOwner, address indexed newOwner)` | Replacing the access manager of a suite is not a supported operation: the manager is a beacon proxy that is upgraded in place. --- # 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/reference/token-suite/access-manager-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.