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

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

Original ERC · ← ERCs