12 KiB
| eip | title | description | author | discussions-to | status | type | category | created | requires |
|---|---|---|---|---|---|---|---|---|---|
| 4973 | Account-bound Tokens | An interface for non-transferrable NFTs binding to an Ethereum account like a legendary World of Warcraft item binds to a character. | Tim Daubenschütz (@TimDaub) | https://ethereum-magicians.org/t/eip-4973-non-transferrable-non-fungible-tokens-soulbound-tokens-or-badges/8825 | Review | Standards Track | ERC | 2022-04-01 | 165, 712, 721, 1271 |
Abstract
Proposes a standard API for account-bound Tokens (ABT) within smart contracts. An ABT is a non-fungible token bound to a single account. ABTs don't implement a canonical interface for transfers. This EIP defines basic functionality to mint, assign, revoke and track ABTs.
Motivation
In the popular MMORPG World of Warcraft, its game designers intentionally took some items out of the world's auction house market system to prevent them from having a publicly-discovered price and limit their accessibility.
Vanilla WoW's "Thunderfury, Blessed Blade of the Windseeker" was one such legendary item, and it required a forty-person raid, among other sub-tasks, to slay the firelord "Ragnaros" to gain the "Essence of the Firelord," a material needed to craft the sword once.
Upon voluntary pickup, the sword permanently binds to a character's "soul," making it impossible to trade, sell or even swap it between a player's characters.
In other words, "Thunderfury"'s price was the aggregate of all social costs related to completing the difficult quest line with friends and guild members. Other players spotting Thunderfuries could be sure their owner had slain "Ragnaros," the blistering firelord.
World of Warcraft players could trash legendary and soulbound items like the Thunderfury to permanently remove them from their account. It was their choice to visibly equip or unequip an item and hence show their achievements to everyone.
The Ethereum community has expressed a need for non-transferrable, non-fungible, and socially-priced tokens similar to WoW's soulbound items. Popular contracts implicitly implement account-bound interaction rights today. A principled standardization helps interoperability and improves on-chain data indexing.
The purpose of this document is to make ABTs a reality on Ethereum by creating consensus around a maximally backward-compatible but otherwise minimal interface definition.
Specification
Solidity Interface
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC 2119.
ABTs must implement the interfaces:
ABTs must not implement the interfaces:
- EIP-721's
ERC721(0x80ac58cd)
An ABT receiver must be able to always call function unequip(address _tokenId) to take their ABT off-chain.
// SPDX-License-Identifier: CC0-1.0
pragma solidity ^0.8.6;
/// @title Account-bound tokens
/// @dev See https://eips.ethereum.org/EIPS/eip-4973
/// Note: the ERC-165 identifier for this interface is 0xeb72bb7c
interface IERC4973 {
/// @dev This emits when ownership of any ABT changes by any mechanism.
/// This event emits when ABTs are given or equipped and unequipped
/// (`to` == 0).
event Transfer(
address indexed from, address indexed to, uint256 indexed tokenId
);
/// @notice Count all ABTs assigned to an owner
/// @dev ABTs assigned to the zero address are considered invalid, and this
/// function throws for queries about the zero address.
/// @param owner An address for whom to query the balance
/// @return The number of ABTs owned by `address owner`, possibly zero
function balanceOf(address owner) external view returns (uint256);
/// @notice Find the address bound to an ERC4973 account-bound token
/// @dev ABTs assigned to zero address are considered invalid, and queries
/// about them do throw.
/// @param tokenId The identifier for an ABT.
/// @return The address of the owner bound to the ABT.
function ownerOf(uint256 tokenId) external view returns (address);
/// @notice Removes the `uint256 tokenId` from an account. At any time, an
/// ABT receiver must be able to disassociate themselves from an ABT
/// publicly through calling this function. After successfully executing this
/// function, given the parameters for calling `function give` or
/// `function take` a token must be re-equipable.
/// @dev Must emit a `event Transfer` with the `address to` field pointing to
/// the zero address.
/// @param tokenId The identifier for an ABT.
function unequip(uint256 tokenId) external;
/// @notice Creates and transfers the ownership of an ABT from the
/// transaction's `msg.sender` to `address to`.
/// @dev Throws unless `bytes signature` represents a signature of the
// EIP-712 structured data hash
/// `Agreement(address active,address passive,bytes metadata)` expressing
/// `address to`'s explicit agreement to be publicly associated with
/// `msg.sender` and `bytes metadata`. A unique `uint256 tokenId` must be
/// generated by type-casting the `bytes32` EIP-712 structured data hash to a
/// `uint256`. If `bytes signature` is empty or `address to` is a contract,
/// an EIP-1271-compatible call to `function isValidSignatureNow(...)` must
/// be made to `address to`. A successful execution must result in the
/// `event Transfer(msg.sender, to, tokenId)`. Once an ABT exists as an
/// `uint256 tokenId` in the contract, `function give(...)` must throw.
/// @param to The receiver of the ABT.
/// @param metadata The metadata that will be associated to the ABT.
/// @param signature A signature of the EIP-712 structured data hash
/// `Agreement(address active,address passive,bytes metadata)` signed by
/// `address to`.
/// @return A unique `uint256 tokenId` generated by type-casting the `bytes32`
/// EIP-712 structured data hash to a `uint256`.
function give(address to, bytes calldata metadata, bytes calldata signature)
external
returns (uint256);
/// @notice Creates and transfers the ownership of an ABT from an
/// `address from` to the transaction's `msg.sender`.
/// @dev Throws unless `bytes signature` represents a signature of the
/// EIP-712 structured data hash
/// `Agreement(address active,address passive,bytes metadata)` expressing
/// `address from`'s explicit agreement to be publicly associated with
/// `msg.sender` and `bytes metadata`. A unique `uint256 tokenId` must be
/// generated by type-casting the `bytes32` EIP-712 structured data hash to a
/// `uint256`. If `bytes signature` is empty or `address from` is a contract,
/// an EIP-1271-compatible call to `function isValidSignatureNow(...)` must
/// be made to `address from`. A successful execution must result in the
/// emission of an `event Transfer(from, msg.sender, tokenId)`. Once an ABT
/// exists as an `uint256 tokenId` in the contract, `function take(...)` must
/// throw.
/// @param from The origin of the ABT.
/// @param metadata The metadata that will be associated to the ABT.
/// @param signature A signature of the EIP-712 structured data hash
/// `Agreement(address active,address passive,bytes metadata)` signed by
/// `address from`.
/// @return A unique `uint256 tokenId` generated by type-casting the `bytes32`
/// EIP-712 structured data hash to a `uint256`.
function take(address from, bytes calldata metadata, bytes calldata signature)
external
returns (uint256);
/// @notice Decodes the opaque metadata bytestring of an ABT into the token
/// URI that will be associated with it once it is created on chain.
/// @param metadata The metadata that will be associated to an ABT.
/// @return A URI that represents the metadata.
function decodeURI(bytes calldata metadata) external returns (string memory);
}
See EIP-721 for a definition of its metadata JSON Schema.
EIP-712 Typed Structured Data Hashing and Bytearray Signature Creation
To invoke function give(...) and function take(...) a bytearray signature must be created using EIP-712. A tested reference implementation in Node.js is attached at ../assets/eip-4973/sdk/src/index.mjs, ../assets/eip-4973/sdk/test/index_test.mjs and ../assets/eip-4973/package.json. In Solidity, this bytearray signature can be created as follows:
bytes32 r = 0x68a020a209d3d56c46f38cc50a33f704f4a9a10a59377f8dd762ac66910e9b90;
bytes32 s = 0x7e865ad05c4035ab5792787d4a0297a43617ae897930a6fe4d822b8faea52064;
uint8 v = 27;
bytes memory signature = abi.encodePacked(r, s, v);
Rationale
Interface
ABTs shall be maximally backward-compatible but still only expose a minimal and simple to implement interface definition.
As EIP-721 tokens have seen widespread adoption with wallet providers and marketplaces, using its ERC721Metadata interface with EIP-165 for feature-detection potentially allows implementers to support ABTs out of the box.
If an implementer of EIP-721 properly built EIP-165's function supportsInterface(bytes4 interfaceID) function, already by recognizing that EIP-721's track and transfer interface component with the identifier 0x80ac58cd is not implemented, transferring of a token should not be suggested as a user interface option.
Still, since ABTs support EIP-721's ERC721Metadata extension, wallets and marketplaces should display an account-bound token with no changes needed.
Although other implementations of account-bound tokens are possible, e.g., by having all transfer functions revert, ABTs are superior as it supports feature detection through EIP-165.
We expose function unequip(address _tokenId) and require it to be callable at any time by an ABT's owner as it ensures an owner's right to publicly disassociate themselves from what has been issued towards their account.
Exception handling
Given the non-transferable between accounts property of ABTs, if a user's keys to an account or a contract get compromised or rotated, a user may lose the ability to associate themselves with the token. In some cases, this can be the desired effect. Therefore, ABT implementers should build re-issuance and revocation processes to enable recourse. We recommend implementing strictly decentralized, permissionless, and censorship-resistant re-issuance processes.
But this document is deliberately abstaining from offering a standardized form of exception handling in cases where user keys are compromised or rotated.
In cases where implementers want to make account-bound tokens shareable among different accounts, e.g., to avoid losing access when keys get compromised, we suggest issuing the account-bound token towards a contract's account that implements a multi-signature functionality.
Provenance Indexing
ABTs can be indexed by tracking the emission of event Transfer(address indexed from, address indexed to, uint256 indexed tokenId). As with EIP-721, transfers between two accounts are represented by address from and address to being non-zero addresses. Unequipping a token is represented through emitting a transfer with address to being set to the zero address. Mint operations where address from is set to zero don't exist. To avoid being spoofed by maliciously-implemented event Transfer emitting contracts, an indexer should ensure that the transaction's sender is equal to event Transfer's from value.
Backwards Compatibility
We have adopted the EIP-165 and ERC721Metadata functions purposefully to create a high degree of backward compatibility with EIP-721. We have deliberately used EIP-721 terminology such as function ownerOf(...), function balanceOf(...) to minimize the effort of familiarization for ABT implementers already familiar with, e.g., EIP-20 or EIP-721. For indexers, we've re-used the widely-implemented event Transfer event signature.
Reference Implementation
You can find an implementation of this standard in ../assets/eip-4973.
Security Considerations
There are no security considerations related directly to the implementation of this standard.
Copyright
Copyright and related rights waived via CC0.