ERC-5727 Semi-fungible soulbound token
Draft · NFTs & multi-token · created 2022-09-28
Issues transferable...
Why it is needed
Today's Web3 ecosystem leans heavily toward financialized tokens that can be bought and sold. But attributes that only make sense when attached to a person, such as credentials, membership, and reputation, should be represented as non-transferable tokens. The Ethereum community has attempted this before, but those attempts lacked flexibility and extensibility. It was hard to handle one-of-a-kind tokens like membership cards and quantity-counted tokens like points under a single standard, and there was no standard way to revoke or expire issued credentials, recover tokens after losing a wallet, or let a community decide issuance by vote or delegate issuance authority. ERC-5727 proposes a common interface covering issuance, revocation, verification, expiration, recovery, and governance to fill this gap.
What to implement
event Revoked(address indexed from, uint256 indexed tokenId);: An event that must be emitted when a token is revoked.event Verified(address indexed by, uint256 indexed tokenId, bool result);: An event that announces the verifier and the result when token verification is performed.function verifierOf(uint256 tokenId) external view returns (address);: Looks up the verifier address of a token. Must revert for a nonexistent tokenId.function issuerOf(uint256 tokenId) external view returns (address);: Looks up the issuer address of a token. Must revert for a nonexistent tokenId.function revoke(uint256 tokenId, bytes calldata data) external payable;: Revokes a token from an address.function slotCountOfOwner(address owner) external view returns (uint256);: Looks up the number of slots an owner holds.function removeApprovalRequest(uint256 approvalId) external;: Removes an approval request. Only the request's author can do this, and it must revert if the request has already been processed.event Delegate(address indexed operator, uint256 indexed slot);: An event emitted when issuance authority for a specific slot is delegated to an operator.event UnDelegate(address indexed operator, uint256 indexed slot);: An event emitted when authority delegated to an operator is revoked.function delegate(address operator, uint256 slot) external;: Delegates authority over a specific slot to an operator.function undelegate(address operator, uint256 slot) external;: Revokes slot authority previously delegated to an operator.event Recovered(address indexed from, address indexed to);: An event emitted when an owner's tokens are recovered to a new address.function recover(address owner, bytes memory signature) external;: Recovers an owner's tokens by presenting that owner's signature. Must revert if the signature is invalid.
In depth
Token and slot structure
A token is identified by tokenId, a 256-bit unsigned integer, and may carry a value representing its face value. A slot is identified by slotId, a 256-bit integer, and is the unit that groups fungible and non-fungible tokens together, making the token semi-fungible. A single token can belong to only one slot at a time. For example, a DAO could split membership SBTs, role badges, and reputation scores into separate slots within a single SBT collection.
Core methods and events
The core interface IERC5727 inherits from IERC3525, IERC5192, IERC5484, and IERC4906, and every implementation must support it. issue comes in two forms. One issues a token by specifying to, tokenId, slot, burnAuth, and verifier, and must revert if to or verifier is the zero address. The other issues additional credits of amount to an existing token. revoke likewise has a form that reclaims the token itself and a form that reclaims part of its credits, and must emit a Revoked event on revocation. verify checks token validity, returns a boolean, and emits a Verified event. verifierOf and issuerOf look up a token's verifier and issuer addresses, and must revert if the tokenId does not exist.
Enumeration and metadata extensions
All extensions are OPTIONAL, and implementing only some of them is fine. The Enumerable extension provides slotCountOfOwner to count an owner's slots, slotOfOwnerByIndex to find a slot by index, and ownerBalanceInSlot to view the balance in a given slot, and is recommended for implementation alongside the core interface. The Metadata extension inherits IERC3525Metadata to query metadata for tokens, slots, and the contract itself, and is recommended when the appearance and attributes of tokens and collections need to be specified.
Governance and delegation
The Governance extension manages issuance and revocation authority through voting. requestApproval creates an issuance approval request, voters indicate for or against via voteApproval, and the request's author can remove a not-yet-processed request with removeApprovalRequest. Approval status is one of four states: Pending, Approved, Rejected, or Removed, and approvalURI looks up the request's URI. The Delegate extension delegates issuance authority for a specific slot to an operator via delegate, withdraws it via undelegate, and checks authority with isOperatorFor. It must revert for a caller without delegation authority, a zero-address operator, or an invalid slot.
Recovery and expiration
The Recovery extension provides a recover function that lets an owner reclaim their tokens by presenting a signature, and it must revert if the signature is invalid. The signing scheme must be compatible with EIP-712 for readability and usability, and a Recovered event is emitted once recovery completes. Implementing this extension is recommended so tokens can be recovered from compromised or outdated wallets. The Expirable extension inherits IERC5643 and uses setExpiration to set a token's expiration date (uint64 expiration) and whether it is renewable (isRenewable). It must revert if the token does not exist or if a past date is specified.
Rationale and backwards compatibility
The storage model draws inspiration from semi-fungible token standards. In ERC-1155, every unit of a fungible token is completely identical, but this standard distinguishes that even similar tokens in the same slot may differ in value, effect, validity period, or origin. This is meant to represent cases where credit scores issued by different institutions share the same slot while differing in character. The recovery mechanism draws inspiration from ERC-1271, and since an SBT represents an identity bound to an address and cannot be split, recovery is treated as moving all of the owner's tokens at once. That is why a recover function is used instead of transferFrom or safeTransferFrom. This standard is compatible with ERC-721, ERC-3525, ERC-4906, ERC-5192, and ERC-5484, and also with ERC-165.
Proposal status
This proposal is in Draft status per the source. The interface and detailed rules may still change, so it is best to check the latest source before implementing.
Things to watch out for
- Risk of total theft on private key loss: When using the recovery mechanism, if a user loses their private key, an attacker can craft a signature and recover all of the victim's SBTs to their own address. Private keys must therefore always be kept secure.
- Multi-signature recovery recommended: The source recommends that developers implement the recovery mechanism by requiring multiple signatures for SBT recovery. It also states that since this standard does not involve ordinary token transfers, it has no general transfer-related security concerns.