ERC-7496 Dynamic NFT Traits (NFT Dynamic Traits)
Draft · NFTs & multi-token · created 2023-07-28
Adds a standard interface for recording, querying, and modifying traits on ERC-721 and ERC-1155 NFTs that can change on-chain. Other contracts can read and write these values to work with properties that change.
Why it is needed
An NFT's trait values are typically stored off-chain. This makes it hard to query or change those values from within smart contract code, and there is no reliable way to record on-chain that a benefit like a redeemable voucher has changed state once it has been used. Transaction safety is a bigger problem. If a marketplace relies on off-chain state, a buyer who places an offer based on a particular trait is exposed to a frontrunning attack in which that trait changes right before the transaction settles. This proposal aims to put traits on-chain and allow them to be read and written through a standard method, so that bids and settlement-time verification based on trait values become possible. In fact, the motivation behind this proposal is to protect users so that, when an NFT is bought or sold conditioned on a specific trait, that condition holds true up until the point of settlement.
What to implement
event TraitUpdated(bytes32 indexed traitKey, uint256 tokenId, bytes32 traitValue);: Announces that a trait value of a single token has changed.event TraitUpdatedRange(bytes32 indexed traitKey, uint256 fromTokenId, uint256 toTokenId);: Announces that a trait has changed for a contiguous range of token IDs (inclusive of both ends).event TraitUpdatedRangeUniformValue(bytes32 indexed traitKey, uint256 fromTokenId, uint256 toTokenId, bytes32 traitValue);: Announces, along with the value, when all tokens in a contiguous range changed to the same value.event TraitUpdatedList(bytes32 indexed traitKey, uint256[] tokenIds);: Announces that the trait has changed for the tokens specified in a list. The order is unrestricted.event TraitUpdatedListUniformValue(bytes32 indexed traitKey, uint256[] tokenIds, bytes32 traitValue);: Announces, along with the value, when all tokens in the list changed to the same value.event TraitMetadataURIUpdated();: Announces that the trait metadata has changed and should be re-queried.function getTraitValue(uint256 tokenId, bytes32 traitKey) external view returns (bytes32 traitValue);: Reads a specific trait value of a single token.function getTraitValues(uint256 tokenId, bytes32[] calldata traitKeys) external view returns (bytes32[] traitValues);: Reads multiple trait values of a single token at once.function getTraitMetadataURI() external view returns (string memory uri);: Returns the URI of the metadata containing trait names, display methods, and validation rules.function setTrait(uint256 tokenId, bytes32 traitKey, bytes32 newValue) external;: Changes a trait value of a token to a new value. Must fail if the value is invalid.
In depth
Interface requirements and identifier
This standard defines the IERC7496 interface, which extends ERC-721 and ERC-1155. Implementing contracts must include all the events, getters, and setters defined in the specification, and must return true for this ERC's 4-byte interfaceId, 0xaf332f3e, in ERC-165 supportsInterface. Queries are accessed via getTraitValue and getTraitValues, setting via setTrait, and metadata via getTraitMetadataURI. Both values and keys are a key-value structure each represented as a single bytes32.
traitKey rules and error handling
traitKey must be a unique bytes32 value identifying a single trait, and using the keccak256 hash of a human-readable trait name is recommended (SHOULD). Handling a traitKey not defined in the metadata schema must revert with TraitDoesNotExist(traitKey). On the other hand, if the trait is defined but no value has been set for that token, it must return the default value bytes32(0) rather than reverting. This distinction allows batch-querying all trait keys defined across multiple tokens without failures. A nonexistent tokenId must revert with TokenDoesNotExist(tokenId), and if the token contract already uses a custom error, that may be used instead (MAY).
Trait metadata schema
Trait metadata must follow the specified schema, and the URI can be a data URI or point to an offchain resource. The keys of the traits object must be unique trait names; if a name is a 32-byte hex string starting with 0x, it is interpreted as the traitKey itself, otherwise the traitKey is the keccak256 hash of the name. A directly written traitKey must not collide with the hash of another trait name. displayName values must also not overlap. There are four dataTypes: string (minLength, maxLength, valueMappings allowed), decimal (signed, decimals, minValue, maxValue allowed; decimals is a nonnegative integer), boolean (if valueMappings is absent, bytes32(0) is false and bytes32(uint256(1)) is true), and epochSeconds (seconds since the Unix epoch). valueMappings can map bytes32 values to human-readable values, and setting a value to null is expected to cause offchain indexers to remove that trait.
validateOnSale sale verification
validateOnSale is a signal telling the marketplace how to verify trait values when a token is sold. If the criteria are not met, the marketplace contract must not allow the sale. The value is one of none (no verification required), requireEq (must equal the value at offer time), requireNeq (must not equal it), requireUintLt / requireUintLte / requireUintGt / requireUintGte (interpreting bytes32 as uint256, must be less than / less than or equal to / greater than / greater than or equal to the value at offer time), and if unspecified it is treated as none. However, the specification adds that buyers and sellers should not rely solely on the marketplace's verification and should investigate the current trait value themselves before trading.
Events and indexing rules
Updating a trait must fire one of TraitUpdated, TraitUpdatedRange, TraitUpdatedRangeUniformValue, TraitUpdatedList, or TraitUpdatedListUniformValue. The fromTokenId and toTokenId of a Range event must be a contiguous token ID range, treated as inclusive of both ends. The tokenIds of a List event can be in any order. If all tokens have the same value, using a UniformValue-family event is recommended, since it lets indexers process bulk updates quickly without querying each value individually. Changing the metadata must fire TraitMetadataURIUpdated. Trait values must also not be based on time-dependent factors like block timestamps or implicit state changes; every change must be the result of an explicit onchain action that leaves an event. This lets indexers stay synchronized with current values purely by processing events, without having to keep recomputing them.
setTrait and token owner updates
If tokenOwnerCanUpdateValue is defined as true in the trait metadata, the token owner must be able to change that trait value by calling setTrait. If the value the owner tries to set is invalid, the transaction must revert; if valid, the value must be updated and one of the TraitUpdated-family events must fire. If a valueMappings entry is defined for the desired value, setTrait must be called with the corresponding traitValue.
Rationale and backwards compatibility
This specification is designed as a key-value mapping for maximum flexibility. Having a dedicated function pair like getFoo()/setFoo() for each trait would require callers to know the function selectors and parameters of every getter and setter, whereas explicitly defining generic get/set functions fixes the function signatures so that querying and setting only require knowing the trait key and value. New traits can be added later without modifying contract code. On compatibility, there are no issues beyond the requirement that onchain traits must override any conflicting values specified in the ERC-721 or ERC-1155 metadata URI. Reference Foundry tests and a reference implementation are included in the assets folder.
Proposal status
This proposal is in Draft status. Implementation should account for the fact that it is not yet finalized and the content may change.
Things to watch out for
- Setter access restriction: Externally exposed set-family methods must have access control so that not anyone can call them, restricting calls to selected roles or addresses only.
- Distrust of offchain trait state: Because frontrunning is possible, marketplaces must not trust the offchain state of traits and must check the current onchain state of traits at the time of transfer. As with validateOnSale, this can be done by checking traits that change NFT value (e.g. whether a redemption has been used), or by hashing all trait values to guarantee the state matches the time the order was created.