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

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

Original ERC · ← ERCs