EIP: 821
Title: Distinguishable Assets Registry
Author: Esteban Ordano <esteban@decentraland.org>
Type: Standard Track
Category: ERC
Status: Draft
Created: 2018-01-05
A Distinguishable Assets Registry is a contract that tracks ownership of, and information about a set of assets.
See https://github.com/decentraland/erc821 for a reference implementation.
See the "Revisions" section for a history of this ERC.
Tracking the ownership of physical or digital distinguishable items on a blockchain has a broad range of applications, from virtual collectibles to physical art pieces. This proposal aims at standardizing a way to reference distinguishable assets along with the foreseeable required operations and interfaces for effective management of those assets on a blockchain.
The number of virtual collectibles tracked on the Ethereum blockchain is rapidly growing, creating a demand for a more robust standard for distinguishable digital assets. This proposal suggests improvements to the vocabulary used to refer to such assets, and attempts to provide a solid and future-proof reference implementation of the basic functionality needed. This EIP also proposes better naming conventions and vocabulary for the different components of the NFT economy: the assets, the NFTs (representations of those assets on the blockchain), the DARs (the contracts registering such assets), distinguishing ownership from holding addresses, and more.
See also: ERC #721, ERC #20, ERC #223, and ERC #777.
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.
A non-fungible token (NFT) is a distinguishable asset that has a unique representation as a register in a smart contract. This proposal specifies such contracts, referenced as Distinguishable Asset Registries, or DARs.
DARs can be identified by the blockchain in which they were deployed, and the 160-bit address of the contract instance. NFTs are identified by an ID, a 256 bit number, which MAY correspond to some cryptographic hash of the non-fungible's natural key.
NFTs SHOULD be referenced by a URI that follows this schema:
nft://<chain's common name>/<DAR's address>/<NFT's ID>
The NFT's ID SHOULD have a hint that helps to decode it. For instance, if the encoding of the number is in hexadecimal, the NFT’s ID SHOULD start with 0x. The DAR's address SHOULD follow the checksum by casing as proposed on #55.
Some common names for Ethereum blockchains are:
ethereum,livenet, ormainnetropsten,testnetkovanrinkeby
Some examples of NFT URIs follow:
- nft://ethereum/0xF87E31492Faf9A91B02Ee0dEAAd50d51d56D5d4d/0
- nft://ropsten/0xF87E31492Faf9A91B02Ee0dEAAd50d51d56D5d4d/0xfaa5be24e996feadf4c96b905af2c77c456e2debd075bab4d8fd5f70f209de44
Every NFT MUST have a owner address associated with it. NFTs associated with the null address are assumed non-existent or destroyed.
An owner MAY assign one or multiple operator addresses. These addresses will be able to transfer any asset of the owner.
DARs MAY trigger Update events, signaling that associated data has changed.
DARs MUST trigger Transfer events every time a NFT's owner changes. This might happen under three circumstances:
- A NFT is created. In this case, the
fromvalue of theTransferevent MUST be the zero address. - A NFT is transferred to a different owner.
- A NFT is destroyed. In this case, the
tovalue of theTransferevent MUST be the zero address.
Transfer events MUST NOT simultaneously have a zero value in both the from and to fields (this means, the same Transfer event can't both create and destroy a token).
Any NFT MAY have a string value associated with it, named data, or metadata. This associated data MAY contain a URL to fetch information related to the NFT. This URL SHOULD point to a folder with the following subpaths:
nameimagedescription
This is intended to provide any NFT-capable dApp with enough information to display the NFT in its UI. For example, if the data associated with an NFT is https://example.com/my_asset, it's expected that https://example.com/my_asset/name contains a short file with the name of the asset, and https://example.com/my_asset/image a ICO or PNG image that represents the asset.
When the associated data's first bit is on, the first byte should be interpreted as the two's complement of the version of the metadata. Version 1 of the protocol (0xff) allows the NFT's name and a short description to be stored on-chain, by using a solidity-style-packed structure with the following fields:
struct Metadata {
uint8 versionBits;
string name;
string description;
string url;
}
By doing this, NFT wallets are allowed to display information associated with the NFT independently of any additional HTTPS/IPFS requests, at the cost of some extra gas spenditure.
name:stringsymbol:stringdescription:stringdecimals:uint256, always zerototalSupply:uint256
These properties follow the standards of #20 and introduces a description. These are all view functions.
This method returns true. This method MUST NOT throw.
This method returns a boolean value, true if the asset identified with the given assetId exists under this DAR. This method MUST NOT throw.
This method returns the address of the owner of the NFT. This method MUST NOT throw. If the assetId does not exist, the return value MUST be the null address.
This method returns the address of the owner of the NFT. This method MUST throw if the assetId does not exist.
This method returns data associated with the NFT. This method MUST NOT throw. This method MAY return an empty string if the NFT has no associated data with it. This method MUST return an empty string if the NFT does not exist.
This method returns data associated with the NFT. This method MUST throw if the NFT associated with assetId does not exist. This method MAY return an empty string if the NFT has no associated data with it.
This method returns the amount of NFTs held by the owner address under this DAR. This method MUST not throw.
Alias of assetCount so older ERC20 wallets can display a balance.
This method returns the ID of the indexth NFT held by the owner address under this DAR, when all the IDs of the NFTs held by such address are stored as an array.
This method MUST throw if assetCount(owner) >= index. This method MUST throw if index >= 2^128.
The DAR MAY change the order assigned to any NFT held by a particular address.
This method is expected to be used by other contracts to iterate through an owner's assets. Contracts implementing such iterations SHOULD be aware of race conditions that might occur, if this iteration happens over multiple transactions.
This method returns an array of IDs of the NFTs held by owner. This method MUST NOT throw.
This method returns true if owner has called the method authorizeOperator with parameters (operator, true) and has not called authorizeOperator(operator, false) afterwards. This method returns false otherwise.
This method MUST return true if operator == owner.
This method MUST NOT throw.
This method returns true if owner has called the method approve with parameters (operator, assetId) and has not called it with a different operator value afterwards. This method returns false otherwise.
This method MUST return true if operator == owner.
This method MUST NOT throw.
Transfers holding of the NFT referenced by assetId from ownerOf(assetId) to the address to.
to MUST NOT be the zero address. If to is the zero address, the call MUST throw.
to MUST NOT be ownerOf(assetId). If this condition is met, the call MUST throw.
isOperatorAuthorizedBy(msg.sender, ownerOf(assetId)) MUST return true as a precondition.
This means that the msg.sender MUST be ownerOf(assetId) or an authorized operator.
If the NFT referenced by assetId does not exist, then the call MUST throw.
If there was any single authorized operator (see the approve() method below), this authorization MUST be cleared.
If the call doesn't throw, it triggers the event Transfer with the following parameters:
- from: value of
ownerOf(assetId)before the call - to: the
toargument - assetId: the
assetIdargument - operator:
msg.sender - userData: the
userDataargument - operatorData: the
operatorDataargument
If to is a contract's address, this call MUST verify that the contract can receive the tokens. Two methods are proposed for this.
If doing a lookup for the manager of the DAR registry's address for the interface erc821 returns a value different from zero, see the next section.
If the receiving contract has implemented IAssetHolder as described in the section Events, then the method onAssetReceived MUST be invoked with the corresponding information, after the NFT has been transferred.
If doing a lookup for the manager of the DAR registry's address for the interface erc821 returns zero, the transfer is managed as in the previous section.
If doing a lookup for the erc821 interface of the DAR registry's address returns a value different from the same DAR registry's address, then the DAR contract should be considered abandoned and the transaction should fail.
If to is a contract, and an ERC820 lookup for IAssetHolder does not return an address, this call MUST throw.
Independently of whether to is a contract or account, when an ERC820 lookup for IAssetHolder for the address returns a non-zero value, the transfer must be done to the registered manager, unless msg.sender is the same manager.
| DAR registration on ERC820 Contract | to address |
msg.sender |
transfer result |
||
|---|---|---|---|---|---|
| type | Implements IAssetHolder | Has ERC820 IAssetHolder Manager | |||
| No registration of erc821 interface | Account | * | Accept | ||
| Contract | Yes | No | Accept | ||
| No | No | ⛔️Throw | |||
| No | Yes | ⛔️Throw | |||
| Registered itself for erc821 | Account | No | * | Accept | |
| Yes | Manager | Accept | |||
| Yes | * | Accept, send to manager | |||
| Contract | Yes | No | * | Accept | |
| No | No | ⛔️Throw | |||
| * | Yes | Manager | Accept | ||
| * | Yes | * | Accept, send to manager | ||
Shorthand method that MUST be equivalent to calling transfer(to, assetId, userData, EMPTY_BYTES).
Shorthand method that MUST be equivalent to calling transfer(to, assetId, EMPTY_BYTES, EMPTY_BYTES).
If authorized is true, allows operator to transfer any NFT held by msg.sender.
This method MUST throw if operator is the zero address. This method MUST throw if authorized is true and operator is already authorized by the sender. This method MUST throw if authorized is false and operator is unauthorized.
This method MUST throw if msg.sender == operator.
This method MUST trigger an AuthorizeOperator event if it doesn't throw.
Allow operator to transfer an asset without delegating full access to all assets.
This method MUST trigger an Approve event if it doesn't throw.
interface AssetRegistryEvents {
event Transfer(
address indexed from,
address indexed to,
uint256 indexed assetId,
address operator,
bytes userData,
bytes operatorData
);
event Update(
uint256 indexed assetId,
address indexed holder,
address indexed operator,
string data
);
event AuthorizeOperator(
address indexed operator,
address indexed holder,
bool authorized
);
event Approve(
address indexed owner,
address indexed operator,
uint256 indexed assetId
);
}
interface IAssetRegistry {
function name() public view returns (string);
function symbol() public view returns (string);
function description() public view returns (string);
function totalSupply() public view returns (uint256);
function decimals() public view returns (uint256);
function isERC821() public view returns (bool);
function exists(uint256 assetId) public view returns (bool);
function holderOf(uint256 assetId) public view returns (address);
function ownerOf(uint256 assetId) public view returns (address);
function safeHolderOf(uint256 assetId) public view returns (address);
function safeOwnerOf(uint256 assetId) public view returns (address);
function assetData(uint256 assetId) public view returns (string);
function safeAssetData(uint256 assetId) public view returns (string);
function assetCount(address holder) public view returns (uint256);
function balaceOf(address holder) public view returns (uint256);
function assetByIndex(address holder, uint256 index) public view returns (uint256);
function assetsOf(address holder) external view returns (uint256[]);
function transfer(address to, uint256 assetId) public;
function transfer(address to, uint256 assetId, bytes userData) public;
function transfer(address to, uint256 assetId, bytes userData, bytes operatorData) public;
function authorizeOperator(address operator, bool authorized) public;
function approve(address operator, uint256 assetId) public;
function isOperatorAuthorizedBy(address operator, address assetHolder) public view returns (bool);
function isApprovedFor(address operator, uint256 assetId) public view returns (bool);
function approvedFor(uint256 assetId) public view returns (address);
}
interface IAssetHolder {
function onAssetReceived(
/* address _assetRegistry == msg.sender */
uint256 _assetId,
address _previousOwner,
address _currentOwner,
bytes _userData,
address _operator,
bytes _operatorData
) public;
}
https://github.com/decentraland/erc821
Standards like ERC #820 and ERC #777 represent the latest best practices on token standards. #777 introduces better vocabulary surrounding the approve method and accommodates the fact that successful contracts using approve end up asking the user to "approve any transfer", by calling approve(2^256-1).
ERC #820 is the latest iteration of #672, a standard that allows contracts to upgrade in a non-disruptive way, but without enforcing ENS to achieve this goal.
The ERC #20 introduced a new vocabulary (owner, approve, supply, transfer, transferFrom) and we should try to reuse as much of that vocabulary and those patterns as possible , but only when they apply. For instance, transferFrom doesn't make sense for a NFT; it's intended to allow an approved agent (after approve) to move someone else's token, but with an NFT as described in this standard, the "owner" is known beforehand.
ERC #777 introduces the name operator to replace the functionality previously provided by approve. We believe this is a good change, given that widely used contracts (EtherDelta, 0x) have adopted the use of a call to approve(2^256-1).
#20 failed to provide a reference implementation right away -- which made for the standard to be written and rewritten on multiple occasions. We provide a reference implementation from day one, along with guidance on how to extend the contract to suit the policy according to each NFT class.
Our implementation tries to follow the UNIX principle of providing mechanisms, not policy. That's why we included functions to create, update, and destroy tokens, but marked them as internal.
Whenever possible, the gas costs should be kept at a minimum.
- 2018/02/03: Add
approveto approve individual assets to be transferred - 2018/01/27: Add exception for
msg.senderbeing the manager - 2018/01/27: Add table for
ERC820andIAssetHolderinterface check - 2018/01/27: Change
IAssetOwnerforIAssetHolderto reflect that another contract might hold tokens for one - 2018/01/27: Errata on
transfertext - 2018/01/26: Alias "balanceOf" to "assetCount" for ERC20 compatibility
- 2018/01/26: Add
decimalsfor more ERC20 compatibility - 2018/01/26: Propose more metadata to be stored on-chain.
- 2018/01/26: Make EIP820 compatibility optional to receive tokens if
onAssetReceived(...)is implemented. - 2018/01/26: Add
isERC821flag to detect support. - 2018/01/26: Revert
holdertoowner. - 2018/01/18:
transfer:toMUST NOT beholderOf(assetId) - 2018/01/17: Added
safeAssetDatamethod - 2018/01/17: Clarification to
transfer: it MUST throw if the asset does not exist. - 2018/01/17: Published first version of the specification
- 2018/01/16: Published implementation
- 2018/01/05: Initial draft
Copyright and related rights waived via CC0.