ERC-7589 Semi-fungible token role management (Semi-Fungible Token Roles)
Draft · NFTs & multi-token · created 2023-12-28
This standard allows the right to use (role) an ERC-1155 semi-fungible token (SFT) to be entrusted to another account for a limited time, while leaving ownership unchanged. Once the deadline passes, the permission automatically disappears.
Why it is needed
ERC-1155 made it possible to issue fungible and non-fungible tokens together from a single contract, but it only tracks who holds how many (balance) and does not address who can use the token and how. However, usage rights are a crucial part of a token's utility. Sometimes the owner exercises all rights directly, but often, as with game items, people want to keep ownership while lending only the usage rights to someone else. Without a standardized method, the token itself must be transferred wholesale, or services must each use their own inconsistent approach, and it is hard to guarantee when and how a lent right will be returned. This standard solves the problem by defining a common interface for depositing (committing) a token and granting a role with an expiration date.
What to implement
event RoleRevoked(uint256 indexed _commitmentId, bytes32 indexed _role, address indexed _grantee);: Event emitted when a role is revoked.event TokensReleased(uint256 indexed _commitmentId);: Event emitted when a committed token is returned to its owner.event RoleApprovalForAll(address indexed _tokenAddress, address indexed _operator, bool _isApproved);: Event emitted when an operator's approval status to manage roles on behalf of another user changes.function revokeRole(uint256 _commitmentId, bytes32 _role, address _grantee) external;: Revokes a granted role.function releaseTokens(uint256 _commitmentId) external;: Returns a committed token to its owner.function setRoleApprovalForAll(address _tokenAddress, address _operator, bool _approved) external;: Approves or removes an operator's ability to grant and revoke roles on one's behalf.function grantorOf(uint256 _commitmentId) external view returns (address grantor_);: Returns the owner (grantor) of a commitment.function tokenAddressOf(uint256 _commitmentId) external view returns (address tokenAddress_);: Returns the contract address of a committed token.function tokenIdOf(uint256 _commitmentId) external view returns (uint256 tokenId_);: Returns the identifier of a committed token.function tokenAmountOf(uint256 _commitmentId) external view returns (uint256 tokenAmount_);: Returns the amount of a committed token.
In depth
The token commitment abstraction
The central concept of this standard is the token commitment. A commitment refers to a token deposited into the contract or a frozen balance, and commitTokens(_grantor, _tokenAddress, _tokenId, _tokenAmount) returns a unique commitmentId. It must revert if _tokenAmount is 0 or if msg.sender is not approved by _grantor. The contents of a commitment are queried via grantorOf, tokenAddressOf, tokenIdOf, and tokenAmountOf, and these query functions must each return the owner, address, identifier, and amount of the committed token respectively.
Role identifiers and automatic expiration
Roles are represented as bytes32 identifiers, and it is recommended to use the keccak256 hash of the role name and arguments (e.g. keccak256("Player(uint256)")). The expiration date is a uint64, and grantRole must revert if _expirationDate is in the past or if the caller is not approved. Instead of calling revokeRole every time to end a role, the app is designed to compare roleExpirationDate against the current time to determine validity, saving gas. Since the maximum UNIX timestamp representable by a uint64 is roughly 584 billion years in the future, using type(uint64).max effectively represents a permanent role.
Revocability and revokeRole rules
The _revocable parameter of grantRole determines whether the owner can withdraw the role before it expires. This is a mechanism for situations where a guarantee against early revocation is needed, such as when the recipient has paid a price. On the other hand, the recipient can always revoke the role regardless of the _revocable value, allowing them to remove an unwanted grant. revokeRole must revert when the role grant does not exist, when msg.sender is not approved by the owner or recipient, and when the call is made on behalf of the owner but the role is irrevocable or already expired.
Token recovery and role approvals
releaseTokens must revert when the commitment does not exist, when msg.sender is not the owner and not approved, and when even one unexpired, irrevocable role remains. Meanwhile, setRoleApprovalForAll and isRoleApprovedForAll are mandatory functions included in the core interface, allowing an operator to be delegated the ability to grant and revoke roles on a per token address basis. This approval lets third-party apps manage roles without custody-level permissions over the tokens, and should not be confused with ERC-1155's transfer approval, which is a different thing.
Custom data _data
SFTs are used in so many ways that it is difficult to define every case in a Solidity interface. For this reason, grantRole includes a bytes-type _data parameter to carry arbitrary information alongside a role grant. For example, a profit-share value common in web3 games can be represented as a single uint256, which can be encoded as bytes and passed to grantRole. This data can be validated either on-chain or off-chain, and other contracts can query this information via the roleData function.
An independent standard, not an ERC-1155 extension
This standard is deliberately not an extension of ERC-1155. This is to remain implementation-neutral, allowing it to be implemented either directly inside an SFT contract or as a separate external contract. The problem that many SFTs are deployed as unmodifiable, immutable contracts is solved by having commitTokens accept a tokenAddress parameter. Even an already deployed SFT can have role management attached by using an external, independent contract as the authoritative source of roles. The ERC-165 identifier for the core interface is 0xc4c8a71d.
Three optional extensions
First, the single-transaction extension (identifier 0x5c3d7d74) handles the two steps of committing and granting a role in a single call to commitTokensAndGrantRole. Second, the role balance extension's (identifier 0x2f35b73f) roleBalanceOf filters out expired roles and returns the sum of amounts granted to a recipient for a specific role, but it is optional since it can complicate the implementation and increase contract risk. Third, the metadata extension adds a roles array (id, name, description, inputs) to ERC-1155's JSON metadata, where inputs describes the parameter format to be encoded and passed to grantRole. A DApp using this extension must also implement the ERC-1155 metadata extension.
Proposal status
This document was created on December 28, 2023, and is currently in Draft status. Since it is not yet a finalized standard, keep in mind that the interface and rules may change going forward.
Things to watch out for
- Checking access control: Proper access control must be in place to prevent roles from being granted or revoked without authorization. This is especially important because commitTokens and releaseTokens can freeze or move balances.
- Guarding against attack vectors such as reentrancy: Potential attack vectors such as reentrancy must be considered and appropriate safeguards put in place.
- Check the expiration date: The expiration date must always be checked before allowing a user to use a role grant.