ERC-5773: Context-Dependent Multi-Asset Tokens
An interface for Multi-Asset tokens with context dependent asset type output controlled by owner's preference.
| Authors | Bruno Škvorc (@Swader), Cicada (@CicadaNCR), Steven Pineda (@steven2308), Stevan Bogosavljevic (@stevyhacker), Jan Turk (@ThunderDeliverer) |
|---|---|
| Created | 2022-10-10 |
| Requires | EIP-165, EIP-721 |
Table of Contents
Abstract
The Multi-Asset NFT standard allows for the construction of a new primitive: context-dependent output of information per single NFT.
The context-dependent output of information means that the asset in an appropriate format is displayed based on how the token is being accessed. I.e. if the token is being opened in an e-book reader, the PDF asset is displayed, if the token is opened in the marketplace, the PNG or the SVG asset is displayed, if the token is accessed from within a game, the 3D model asset is accessed and if the token is accessed by the (Internet of Things) IoT hub, the asset providing the necessary addressing and specification information is accessed.
An NFT can have multiple assets (outputs), which can be any kind of file to be served to the consumer, and orders them by priority. They do not have to match in mimetype or tokenURI, nor do they depend on one another. Assets are not standalone entities, but should be thought of as “namespaced tokenURIs” that can be ordered at will by the NFT owner, but only modified, updated, added, or removed if agreed on by both the owner of the token and the issuer of the token.
Motivation
With NFTs being a widespread form of tokens in the Ethereum ecosystem and being used for a variety of use cases, it is time to standardize additional utility for them. Having multiple assets associated with a single NFT allows for greater utility, usability and forward compatibility.
In the four years since ERC-721 was published, the need for additional functionality has resulted in countless extensions. This EIP improves upon ERC-721 in the following areas:
Cross-metaverse compatibility
At the time of writing this proposal, the metaverse is still a fledgling, not full defined, term. No matter how the definition of metaverse evolves, the proposal can support any number of different implementations.
Cross-metaverse compatibility could also be referred to as cross-engine compatibility. An example of this is where a cosmetic item for game A is not available in game B because the frameworks are incompatible.
Such NFT can be given further utility by means of new additional assets: more games, more cosmetic items, appended to the same NFT. Thus, a game cosmetic item as an NFT becomes an ever-evolving NFT of infinite utility.
The following is a more concrete example. One asset is a cosmetic item for game A, a file containing the cosmetic assets. Another is a cosmetic asset file for game B. A third is a generic asset intended to be shown in catalogs, marketplaces, portfolio trackers, or other generalized NFT viewers, containing a representation, stylized thumbnail, and animated demo/trailer of the cosmetic item.
This EIP adds a layer of abstraction, allowing game developers to directly pull asset data from a user’s NFTs instead of hard-coding it.
Multi-media output
An NFT of an eBook can be represented as a PDF, MP3, or some other format, depending on what software loads it. If loaded into an eBook reader, a PDF should be displayed, and if loaded into an audiobook application, the MP3 representation should be used. Other metadata could be present in the NFT (perhaps the book’s cover image) for identification on various marketplaces, Search Engine Result Pages (SERPs), or portfolio trackers.
Media redundancy
Many NFTs are minted hastily without best practices in mind - specifically, many NFTs are minted with metadata centralized on a server somewhere or, in some cases, a hardcoded IPFS gateway which can also go down, instead of just an IPFS hash.
By adding the same metadata file as different assets, e.g., one asset of a metadata and its linked image on Arweave, one asset of this same combination on Sia, another of the same combination on IPFS, etc., the resilience of the metadata and its referenced information increases exponentially as the chances of all the protocols going down at once become less likely.
NFT evolution
Many NFTs, particularly game related ones, require evolution. This is especially the case in modern metaverses where no metaverse is actually a metaverse - it is just a multiplayer game hosted on someone’s server which replaces username/password logins with reading an account’s NFT balance.
When the server goes down or the game shuts down, the player ends up with nothing (loss of experience) or something unrelated (assets or accessories unrelated to the game experience, spamming the wallet, incompatible with other “verses” - see cross-metaverse compatibility above).
With Multi-Asset NFTs, a minter or another pre-approved entity is allowed to suggest a new asset to the NFT owner who can then accept it or reject it. The asset can even target an existing asset which is to be replaced.
Replacing an asset could, to some extent, be similar to replacing an ERC-721 token’s URI. When an asset is replaced a clear line of traceability remains; the old asset is still reachable and verifiable. Replacing an asset’s metadata URI obscures this lineage. It also gives more trust to the token owner if the issuer cannot replace the asset of the NFT at will. The propose-accept asset replacement mechanic of this proposal provides this assurance.
This allows level-up mechanics where, once enough experience has been collected, a user can accept the level-up. The level-up consists of a new asset being added to the NFT, and once accepted, this new asset replaces the old one.
As a concrete example, think of Pokemon™️ evolving - once enough experience has been attained, a trainer can choose to evolve their monster. With Multi-Asset NFTs, it is not necessary to have centralized control over metadata to replace it, nor is it necessary to airdrop another NFT into the user’s wallet - instead, a new Raichu asset is minted onto Pikachu, and if accepted, the Pikachu asset is gone, replaced by Raichu, which now has its own attributes, values, etc.
Alternative example of this, could be version control of an IoT device’s firmware. An asset could represent its current firmware and once an update becomes available, the current asset could be replaced with the one containing the updated firmware.
Specification
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.
/// @title ERC-5773 Context-Dependent Multi-Asset Tokens
/// @dev See https://eips.ethereum.org/EIPS/eip-5773
/// @dev Note: the ERC-165 identifier for this interface is 0x06b4329a.
pragma solidity ^0.8.16;
interface IERC5773 /* is ERC165 */ {
/**
* @notice Used to notify listeners that an asset object is initialised at `assetId`.
* @param assetId ID of the asset that was initialised
*/
event AssetSet(uint64 assetId);
/**
* @notice Used to notify listeners that an asset object at `assetId` is added to token's pending asset
* array.
* @param tokenIds An array of IDs of the tokens that received a new pending asset
* @param assetId ID of the asset that has been added to the token's pending assets array
* @param replacesId ID of the asset that would be replaced
*/
event AssetAddedToTokens(
uint256[] tokenIds,
uint64 indexed assetId,
uint64 indexed replacesId
);
/**
* @notice Used to notify listeners that an asset object at `assetId` is accepted by the token and migrated
* from token's pending assets array to active assets array of the token.
* @param tokenId ID of the token that had a new asset accepted
* @param assetId ID of the asset that was accepted
* @param replacesId ID of the asset that was replaced
*/
event AssetAccepted(
uint256 indexed tokenId,
uint64 indexed assetId,
uint64 indexed replacesId
);
/**
* @notice Used to notify listeners that an asset object at `assetId` is rejected from token and is dropped
* from the pending assets array of the token.
* @param tokenId ID of the token that had an asset rejected
* @param assetId ID of the asset that was rejected
*/
event AssetRejected(uint256 indexed tokenId, uint64 indexed assetId);
/**
* @notice Used to notify listeners that token's priority array is reordered.
* @param tokenId ID of the token that had the asset priority array updated
*/
event AssetPrioritySet(uint256 indexed tokenId);
/**
* @notice Used to notify listeners that owner has granted an approval to the user to manage the assets of a
* given token.
* @dev Approvals must be cleared on transfer
* @param owner Address of the account that has granted the approval for all token's assets
* @param approved Address of the account that has been granted approval to manage the token's assets
* @param tokenId ID of the token on which the approval was granted
*/
event ApprovalForAssets(
address indexed owner,
address indexed approved,
uint256 indexed tokenId
);
/**
* @notice Used to notify listeners that owner has granted approval to the user to manage assets of all of their
* tokens.
* @param owner Address of the account that has granted the approval for all assets on all of their tokens
* @param operator Address of the account that has been granted the approval to manage the token's assets on all of the
* tokens
* @param approved Boolean value signifying whether the permission has been granted (`true`) or revoked (`false`)
*/
event ApprovalForAllForAssets(
address indexed owner,
address indexed operator,
bool approved
);
/**
* @notice Accepts an asset at from the pending array of given token.
* @dev Migrates the asset from the token's pending asset array to the token's active asset array.
* @dev Active assets cannot be removed by anyone, but can be replaced by a new asset.
* @dev Requirements:
*
* - The caller must own the token or be approved to manage the token's assets
* - `tokenId` must exist.
* - `index` must be in range of the length of the pending asset array.
* @dev Emits an {AssetAccepted} event.
* @param tokenId ID of the token for which to accept the pending asset
* @param index Index of the asset in the pending array to accept
* @param assetId Id of the asset expected to be in the index
*/
function acceptAsset(
uint256 tokenId,
uint256 index,
uint64 assetId
) external;
/**
* @notice Rejects an asset from the pending array of given token.
* @dev Removes the asset from the token's pending asset array.
* @dev Requirements:
*
* - The caller must own the token or be approved to manage the token's assets
* - `tokenId` must exist.
* - `index` must be in range of the length of the pending asset array.
* @dev Emits a {AssetRejected} event.
* @param tokenId ID of the token that the asset is being rejected from
* @param index Index of the asset in the pending array to be rejected
* @param assetId Id of the asset expected to be in the index
*/
function rejectAsset(
uint256 tokenId,
uint256 index,
uint64 assetId
) external;
/**
* @notice Rejects all assets from the pending array of a given token.
* @dev Effectively deletes the pending array.
* @dev Requirements:
*
* - The caller must own the token or be approved to manage the token's assets
* - `tokenId` must exist.
* @dev Emits a {AssetRejected} event with assetId = 0.
* @param tokenId ID of the token of which to clear the pending array
* @param maxRejections to prevent from rejecting assets which arrive just before this operation.
*/
function rejectAllAssets(uint256 tokenId, uint256 maxRejections) external;
/**
* @notice Sets a new priority array for a given token.
* @dev The priority array is a non-sequential list of `uint16`s, where the lowest value is considered highest
* priority.
* @dev Value `0` of a priority is a special case equivalent to uninitialised.
* @dev Requirements:
*
* - The caller must own the token or be approved to manage the token's assets
* - `tokenId` must exist.
* - The length of `priorities` must be equal the length of the active assets array.
* @dev Emits a {AssetPrioritySet} event.
* @param tokenId ID of the token to set the priorities for
* @param priorities An array of priorities of active assets. The succession of items in the priorities array
* matches that of the succession of items in the active array
*/
function setPriority(uint256 tokenId, uint64[] calldata priorities)
external;
/**
* @notice Used to retrieve IDs of the active assets of given token.
* @dev Asset data is stored by reference, in order to access the data corresponding to the ID, call
* `getAssetMetadata(tokenId, assetId)`.
* @dev You can safely get 10k
* @param tokenId ID of the token to retrieve the IDs of the active assets
* @return uint64[] An array of active asset IDs of the given token
*/
function getActiveAssets(uint256 tokenId)
external
view
returns (uint64[] memory);
/**
* @notice Used to retrieve IDs of the pending assets of given token.
* @dev Asset data is stored by reference, in order to access the data corresponding to the ID, call
* `getAssetMetadata(tokenId, assetId)`.
* @param tokenId ID of the token to retrieve the IDs of the pending assets
* @return uint64[] An array of pending asset IDs of the given token
*/
function getPendingAssets(uint256 tokenId)
external
view
returns (uint64[] memory);
/**
* @notice Used to retrieve the priorities of the active assets of a given token.
* @dev Asset priorities are a non-sequential array of uint16 values with an array size equal to active asset
* priorites.
* @param tokenId ID of the token for which to retrieve the priorities of the active assets
* @return uint16[] An array of priorities of the active assets of the given token
*/
function getActiveAssetPriorities(uint256 tokenId)
external
view
returns (uint64[] memory);
/**
* @notice Used to retrieve the asset that will be replaced if a given asset from the token's pending array
* is accepted.
* @dev Asset data is stored by reference, in order to access the data corresponding to the ID, call
* `getAssetMetadata(tokenId, assetId)`.
* @param tokenId ID of the token to check
* @param newAssetId ID of the pending asset which will be accepted
* @return uint64 ID of the asset which will be replaced
*/
function getAssetReplacements(uint256 tokenId, uint64 newAssetId)
external
view
returns (uint64);
/**
* @notice Used to fetch the asset metadata of the specified token's active asset with the given index.
* @dev Can be overridden to implement enumerate, fallback or other custom logic.
* @param tokenId ID of the token from which to retrieve the asset metadata
* @param assetId Asset Id, must be in the active assets array
* @return string The metadata of the asset belonging to the specified index in the token's active assets
* array
*/
function getAssetMetadata(uint256 tokenId, uint64 assetId)
external
view
returns (string memory);
/**
* @notice Used to grant permission to the user to manage token's assets.
* @dev This differs from transfer approvals, as approvals are not cleared when the approved party accepts or
* rejects an asset, or sets asset priorities. This approval is cleared on token transfer.
* @dev Only a single account can be approved at a time, so approving the `0x0` address clears previous approvals.
* @dev Requirements:
*
* - The caller must own the token or be an approved operator.
* - `tokenId` must exist.
* @dev Emits an {ApprovalForAssets} event.
* @param to Address of the account to grant the approval to
* @param tokenId ID of the token for which the approval to manage the assets is granted
*/
function approveForAssets(address to, uint256 tokenId) external;
/**
* @notice Used to retrieve the address of the account approved to manage assets of a given token.
* @dev Requirements:
*
* - `tokenId` must exist.
* @param tokenId ID of the token for which to retrieve the approved address
* @return address Address of the account that is approved to manage the specified token's assets
*/
function getApprovedForAssets(uint256 tokenId)
external
view
returns (address);
/**
* @notice Used to add or remove an operator of assets for the caller.
* @dev Operators can call {acceptAsset}, {rejectAsset}, {rejectAllAssets} or {setPriority} for any token
* owned by the caller.
* @dev Requirements:
*
* - The `operator` cannot be the caller.
* @dev Emits an {ApprovalForAllForAssets} event.
* @param operator Address of the account to which the operator role is granted or revoked from
* @param approved The boolean value indicating whether the operator role is being granted (`true`) or revoked
* (`false`)
*/
function setApprovalForAllForAssets(address operator, bool approved)
external;
/**
* @notice Used to check whether the address has been granted the operator role by a given address or not.
* @dev See {setApprovalForAllForAssets}.
* @param owner Address of the account that we are checking for whether it has granted the operator role
* @param operator Address of the account that we are checking whether it has the operator role or not
* @return bool The boolean value indicating whether the account we are checking has been granted the operator role
*/
function isApprovedForAllForAssets(address owner, address operator)
external
view
returns (bool);
}
The getAssetMetadata function returns the asset’s metadata URI. The metadata, to which the metadata URI of the asset points, MAY contain a JSON response with the following fields:
{
"name": "Asset Name",
"description": "The description of the token or asset",
"mediaUri": "ipfs://mediaOfTheAssetOrToken",
"thumbnailUri": "ipfs://thumbnailOfTheAssetOrToken",
"externalUri": "https://uriToTheProjectWebsite",
"license": "License name",
"licenseUri": "https://uriToTheLicense",
"tags": ["tags", "used", "to", "help", "marketplaces", "categorize", "the", "asset", "or", "token"],
"preferThumb": false, // A boolean flag indicating to UIs to prefer thumbnailUri instead of mediaUri wherever applicable
"attributes": [
{
"label": "rarity",
"type": "string",
"value": "epic",
// For backward compatibility
"trait_type": "rarity"
},
{
"label": "color",
"type": "string",
"value": "red",
// For backward compatibility
"trait_type": "color"
},
{
"label": "height",
"type": "float",
"value": 192.4,
// For backward compatibility
"trait_type": "height",
"display_type": "number"
}
]
}
While this is the suggested JSON schema for the asset metadata, it is not enforced and MAY be structured completely differently based on implementer’s preference.
Rationale
Designing the proposal, we considered the following questions:
- Should we use Asset or Resource when referring to the structure that comprises the token?
The original idea was to call the proposal Multi-Resource, but while this denoted the broadness of the structures that could be held by a single token, the term asset represents it better.
An asset is defined as something that is owned by a person, company, or organization, such as money, property, or land. This is the best representation of what an asset of this proposal can be. An asset in this proposal can be a multimedia file, technical information, a land deed, or anything that the implementer has decided to be an asset of the token they are implementing. - Why are EIP-712 permit-style signatures to manage approvals not used?
For consistency. This proposal extends ERC-721 which already uses 1 transaction for approving operations with tokens. It would be inconsistent to have this and also support signing messages for operations with assets. - Why use indexes?
To reduce the gas consumption. If the asset ID was used to find which asset to accept or reject, iteration over arrays would be required and the cost of the operation would depend on the size of the active or pending assets arrays. With the index, the cost is fixed. A list of active and pending assets arrays per token need to be maintained, since methods to get them are part of the proposed interface.
To avoid race conditions in which the index of an asset changes, the expected asset ID is included in operations requiring asset index, to verify that the asset being accessed using the index is the expected asset.
Implementation that would internally keep track of indices using mapping was attempted. The average cost of adding an asset to a token increased by over 25%, costs of accepting and rejecting assets also increased 4.6% and 7.1% respectively. We concluded that it is not necessary for this proposal and can be implemented as an extension for use cases willing to accept this cost. In the sample implementation provided, there are several hooks which make this possible. - Why is a method to get all the assets not included?
Getting all assets might not be an operation necessary for all implementers. Additionally, it can be added either as an extension, doable with hooks, or can be emulated using an indexer. - Why is pagination not included?
Asset IDs useuint64, testing has confirmed that the limit of IDs you can read before reaching the gas limit is around 30.000. This is not expected to be a common use case so it is not a part of the interface. However, an implementer can create an extension for this use case if needed. - How does this proposal differ from the other proposals trying to address a similar problem?
After reviewing them, we concluded that each contains at least one of these limitations:- Using a single URI which is replaced as new assets are needed, this introduces a trust issue for the token owner.
- Focusing only on a type of asset, while this proposal is asset type agnostic.
- Having a different token for each new use case, this means that the token is not forward-compatible.
Multi-Asset Storage Schema
Assets are stored within a token as an array of uint64 identifiers.
In order to reduce redundant on-chain string storage, multi asset tokens store assets by reference via inner storage. An asset entry on the storage is stored via a uint64 mapping to asset data.
An asset array is an array of these uint64 asset ID references.
Such a structure allows that, a generic asset can be added to the storage one time, and a reference to it can be added to the token contract as many times as we desire. Implementers can then use string concatenation to procedurally generate a link to a content-addressed archive based on the base SRC in the asset and the token ID. Storing the asset in a new token will only take 16 bytes of storage in the asset array per token for recurrent as well as tokenId dependent assets.
Structuring token’s assets in such a way allows for URIs to be derived programmatically through concatenation, especially when they differ only by tokenId.
Propose-Commit pattern for asset addition
Adding assets to an existing token MUST be done in the form of a propose-commit pattern to allow for limited mutability by a 3rd party. When adding an asset to a token, it is first placed in the “Pending” array, and MUST be migrated to the “Active” array by the token’s owner. The “Pending” assets array SHOULD be limited to 128 slots to prevent spam and griefing.
Asset management
Several functions for asset management are included. In addition to permissioned migration from “Pending” to “Active”, the owner of a token MAY also drop assets from both the active and the pending array – an emergency function to clear all entries from the pending array MUST also be included.
Backwards Compatibility
The MultiAsset token standard has been made compatible with ERC-721 in order to take advantage of the robust tooling available for implementations of ERC-721 and to ensure compatibility with existing ERC-721 infrastructure.
Test Cases
Tests are included in multiasset.ts.
To run them in terminal, you can use the following commands:
cd ../assets/eip-5773
npm install
npx hardhat test
Reference Implementation
See MultiAssetToken.sol.
Security Considerations
The same security considerations as with ERC-721 apply: hidden logic may be present in any of the functions, including burn, add asset, accept asset, and more.
Caution is advised when dealing with non-audited contracts.
Copyright
Copyright and related rights waived via CC0.
Citation
Please cite this document as:
Bruno Škvorc (@Swader), Cicada (@CicadaNCR), Steven Pineda (@steven2308), Stevan Bogosavljevic (@stevyhacker), Jan Turk (@ThunderDeliverer), "ERC-5773: Context-Dependent Multi-Asset Tokens," Ethereum Improvement Proposals, no. 5773, October 2022. [Online serial]. Available: https://eips.ethereum.org/EIPS/eip-5773.