ERC-7303 Token Controlled Token Circulation (TCTC) (Token-Controlled Token Circulation)

Draft · Signatures & auth · created 2023-07-09

An access control standard that represents privileges such as minting or burning as an ERC-721 or ERC-1155 token (a control token), so that roles can be granted and revoked simply by issuing and burning that token.

Why it is needed

Privileged operations such as minting or destroying tokens in a contract are commonly managed with role based access control (ERC-5982). However, this approach requires going through an off chain management tool's interface to grant or revoke roles. Also, most wallets have no screen showing permissions granted via roles, so users have a hard time telling what permissions they have just from their wallet. The problem grows worse when the permission structure is hidden only inside the contract. Autonomous agents or external tools acting with delegated authority are not the party who designed the permission structure, so they have no mechanical way to determine what qualifications a given role requires. This standard solves these problems by turning the permission itself into a token visible in the wallet and by giving the contract an interface through which the role structure can be queried.

What to implement

In depth

Authority is represented as a control token

Contracts implementing this standard MUST represent the authority required for a role as an ERC-721 or ERC-1155 token. This token is called a control token. When linking a role to a control token, the address of a pre-deployed control token contract must be used. A control token can be any kind of token, and the transfer of that token itself can in turn be recursively controlled by another control token. The use cases cited in the source text are mint/burn authority for ticket, coupon, and membership tokens, transfer authority restricted to a specific institution, proof of address verification to prevent misdelivery, and delegation of authority to autonomous agents.

Role verification uses balanceOf, and role names use keccak256

Whether an account holds a role SHOULD be verified by checking whether the balanceOf value defined in ERC-721 or ERC-1155 exceeds 0. When using an ERC-1155 token, the typeId must also be specified in balanceOf. A role is represented in bytes32 format, and it is recommended to compute it as the keccak256 hash of the role name string, for example in the form bytes32 role = keccak256("MINTER").

Granting is minting, revoking is burning

To grant a role, the control token representing the authority SHOULD be minted to the account using the safeMint method defined in ERC-5679. To revoke a role, that token is burned using the burn method of the same standard. Instead of placing a separate authority-management function on the target contract, the act of minting and burning tokens on a separately deployed control token contract itself becomes the authority management. In agent use cases, burning becomes an on-chain kill switch that works without an off-chain authorization server, and anyone can verify an agent's authority via balanceOf.

The role structure must be exposed through the IERC7303 interface

Contracts conforming to the specification MUST implement the IERC7303 interface so that third parties and tools can query the link between roles and control tokens on-chain. hasRole returns whether a role is held, and getERC721ControlTokens and getERC1155ControlTokens return the list of control tokens linked to a role. When a control token is linked to a role, an ERC721ControlTokenAdded or ERC1155ControlTokenAdded event must be emitted so indexers can track the role structure. The contract must also implement ERC-165 and return true for the IERC7303 interface identifier. According to the Test Cases section, this identifier is 0x4ee69337, the XOR of the three function selectors.

The reasoning behind the interface design

The initial version deliberately did not define an interface, on the assumption that whoever set up the role already knew its structure. However, because an autonomous agent acting under delegated authority is not the designer of the authority structure it follows, IERC7303 was added so that a contract can describe its own role structure in a machine-readable way. The hasRole(bytes32, address) signature was deliberately matched to the same-named function in widely deployed implementations such as OpenZeppelin AccessControl, so callers can query it without knowing whether the answer comes from an internal mapping or a token balance. grantRole and revokeRole, on the other hand, were intentionally left out, because granting and revoking are mint/burn operations that happen on a separately deployed control token contract, and are not authority the target contract should hold. The enumeration functions were split by standard because the ERC-721 entry has no typeId, and any placeholder value used for it would be indistinguishable from a legitimate ERC-1155 typeId.

Behavior of the reference implementation

The reference implementation provides an onlyHasToken(role, account) modifier. The internal function _checkHasToken iterates through the ERC-721 list and the ERC-1155 list registered to the role in turn, and passes if even one entry has a balanceOf greater than 0. Linking a role to a control token is done through the internal functions _grantRoleByERC721 and _grantRoleByERC1155, which use require to confirm, before registration, that the address supports the IERC721 or IERC1155 interface via ERC-165, and then emit an event. Calling this multiple times for the same role creates an OR condition, where holding just one of the registered tokens is sufficient. The example MyToken defines MINTER_ROLE and BURNER_ROLE with keccak256 and attaches the modifier to its safeMint and burn functions.

Why ERC-721/1155, and transferability is optional

Choosing ERC-721 or ERC-1155 for control tokens makes authority visible within the wallet, easing authority management for users. When turning authority into a token, standards such as soulbound tokens (e.g., ERC-5192) are typically used, and since ERC-5192 inherits from ERC-721, this standard also requires ERC-721. Making a control token transferable allows delegation, for instance passing authority to another member of an organization when a person in charge is replaced or on leave. Whether a control token is transferable is left to the needs of the application.

Compatibility and proposal status

This standard is designed to be compatible with ERC-721, ERC-1155, and ERC-5679 respectively. However, this proposal is currently in Draft status. Because it is still under review and the specification and interfaces may change, implementers should check the latest source text.

Things to watch out for

Original ERC · ← ERCs