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.

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.

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.

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.