--- eip: 7496 title: NFT Dynamic Traits description: Extension to ERC-721 and ERC-1155 for dynamic onchain traits author: Adam Montgomery (@montasaurus), Ryan Ghods (@ryanio), 0age (@0age), James Wenzel (@emo-eth), Stephan Min (@stephankmin) discussions-to: https://ethereum-magicians.org/t/erc-7496-nft-dynamic-traits/15484 status: Draft type: Standards Track category: ERC created: 2023-07-28 requires: 165, 721, 1155 --- ## Abstract This specification introduces a new interface that extends [ERC-721](./eip-721.md) and [ERC-1155](./eip-1155.md) that defines methods for setting and getting dynamic onchain traits associated with non-fungible tokens. These dynamic traits can be used to represent properties, characteristics, redeemable entitlements, or other attributes that can change over time. By defining these traits onchain, they can be used and modified by other onchain contracts. ## Motivation Trait values for non-fungible tokens are often stored offchain. This makes it difficult to query and mutate these values in contract code. Specifying the ability to set and get traits onchain allows for new use cases like redeeming onchain entitlements and transacting based on a token's traits. Onchain traits can be used by contracts in a variety of different scenarios. For example, a contract that wants to entitle a token to a consumable benefit (e.g. a redeemable) can robustly reflect that onchain. Marketplaces can allow bidding on these tokens based on the trait value without having to rely on offchain state and exposing users to frontrunning attacks. The motivating use case behind this proposal is to protect users from frontrunning attacks on marketplaces where users can list NFTs with certain traits where they are expected to be upheld during fulfillment. ## Specification The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC 2119 and RFC 8174. Contracts implementing this EIP MUST include the events, getters, and setters as defined below, and MUST return `true` for [ERC-165](./eip-165.md) `supportsInterface` for `0xaf332f3e`, the 4 byte `interfaceId` for this ERC. ```solidity interface IERC7496 { /* Errors */ /// @notice Thrown when trying to set a trait that does not exist. error TraitDoesNotExist(bytes32 traitKey); /// @notice Thrown when the token does not exist. error TokenDoesNotExist(uint256 tokenId); /* Events */ event TraitUpdated(bytes32 indexed traitKey, uint256 tokenId, bytes32 traitValue); event TraitUpdatedRange(bytes32 indexed traitKey, uint256 fromTokenId, uint256 toTokenId); event TraitUpdatedRangeUniformValue(bytes32 indexed traitKey, uint256 fromTokenId, uint256 toTokenId, bytes32 traitValue); event TraitUpdatedList(bytes32 indexed traitKey, uint256[] tokenIds); event TraitUpdatedListUniformValue(bytes32 indexed traitKey, uint256[] tokenIds, bytes32 traitValue); event TraitMetadataURIUpdated(); /* Getters */ function getTraitValue(uint256 tokenId, bytes32 traitKey) external view returns (bytes32 traitValue); function getTraitValues(uint256 tokenId, bytes32[] calldata traitKeys) external view returns (bytes32[] traitValues); function getTraitMetadataURI() external view returns (string memory uri); /* Setters */ function setTrait(uint256 tokenId, bytes32 traitKey, bytes32 newValue) external; } ``` ### Keys & Names The `traitKey` is used to identify a trait. The `traitKey` MUST be a unique `bytes32` value identifying a single trait. The `traitKey` SHOULD be a `keccak256` hash of a human readable trait name. ### Errors If a `traitKey` is not defined in the contract (i.e., not present in the trait metadata schema), the contract MUST revert with `TraitDoesNotExist(traitKey)`. This allows applications to detect when they have queried an invalid or unsupported trait key. If a `traitKey` is defined in the contract but a specific token does not have a value set for that trait, the contract MUST return `bytes32(0)` as the default value instead of reverting. This enables batch querying of all defined trait keys across multiple tokens without failures due to unset values. If a `tokenId` does not exist, the contract MUST revert with `TokenDoesNotExist(tokenId)`. If the token contract already defines a custom error for non-existent tokens (e.g. from [ERC-721](./eip-721.md) or [ERC-1155](./eip-1155.md)), that error MAY be used instead. ### Metadata Trait metadata is necessary to provide information about which traits are present in a contract, how to display trait names and values, and other optional features. The trait metadata must be compliant with the [specified schema](../assets/eip-7496/DynamicTraitsSchema.json). The trait metadata URI MAY be a data URI or point to an offchain resource. The keys in the `traits` object MUST be unique trait names. If the trait name is 32 byte hex string starting with `0x` then it is interpreted as a literal `traitKey`. Otherwise, the `traitKey` is defined as the `keccak256` hash of the trait name. A literal `traitKey` MUST NOT collide with the `keccak256` hash of any other traits defined in the metadata. The `displayName` values MUST be unique and MUST NOT collide with the `displayName` of any other traits defined in the metadata. The `validateOnSale` value provides a signal to marketplaces on how to validate the trait value when a token is being sold. If the validation criteria is not met, the sale MUST not be permitted by the marketplace contract. If specified, the value of `validateOnSale` MUST be one of the following (or it is assumed to be `none`): - `none`: No validation is necessary. - `requireEq`: The `bytes32` `traitValue` MUST be equal to the value at the time the offer to purchase was made. - `requireNeq`: The `bytes32` `traitValue` MUST NOT be equal to the value at the time the offer to purchase was made. - `requireUintLt`: The `bytes32` `traitValue` MUST be less than the value at the time the offer to purchase was made. This comparison is made using the `uint256` representation of the `bytes32` value. - `requireUintLte`: The `bytes32` `traitValue` MUST be less than or equal to the value at the time the offer to purchase was made. This comparison is made using the `uint256` representation of the `bytes32` value. - `requireUintGt`: The `bytes32` `traitValue` MUST be greater than the value at the time the offer to purchase was made. This comparison is made using the `uint256` representation of the `bytes32` value. - `requireUintGte`: The `bytes32` `traitValue` MUST be greater than or equal to the value at the time the offer to purchase was made. This comparison is made using the `uint256` representation of the `bytes32` value. Note that even though this specification requires marketplaces to validate the required trait values, buyers and sellers cannot fully rely on marketplaces to do this and must also take their own precautions to research the current trait values prior to initiating the transaction. Here is an example of the specified schema: ```json { "traits": { "color": { "displayName": "Color", "dataType": { "type": "string" } }, "points": { "displayName": "Total Score", "dataType": { "type": "decimal", "signed": false, "decimals": 0 }, "validateOnSale": "requireUintGte" }, "name": { "displayName": "Name", "dataType": { "type": "string", "minLength": 1, "maxLength": 32, "valueMappings": { "0x0000000000000000000000000000000000000000000000000000000000000000": "Unnamed", "0x92e75d5e42b80de937d204558acf69c8ea586a244fe88bc0181323fe3b9e3ebf": "🙂" } }, "tokenOwnerCanUpdateValue": true }, "birthday": { "displayName": "Birthday", "dataType": { "type": "epochSeconds", "valueMappings": { "0x0000000000000000000000000000000000000000000000000000000000000000": null } } }, "0x77c2fd45bd8bdef5b5bc773f46759bb8d169f3468caab64d7d5f2db16bb867a8": { "displayName": "🚢 📅", "dataType": { "type": "epochSeconds", "valueMappings": { "0x0000000000000000000000000000000000000000000000000000000000000000": 1696702201 } } } } } ``` #### `string` Metadata Type The `string` metadata type allows for a string value to be set for a trait. The `dataType` object MAY have a `minLength` and `maxLength` value defined. If `minLength` is not specified, it is assumed to be 0. If `maxLength` is not specified, it is assumed to be a reasonable length. The `dataType` object MAY have a `valueMappings` object defined. If the `valueMappings` object is defined, the `valueMappings` object MUST be a mapping of `bytes32` values to `string` or unset `null` values. The `bytes32` values SHOULD be the `keccak256` hash of the `string` value. The `string` values MUST be unique. If the trait for a token is updated to `null`, it is expected that offchain indexers will delete the trait for the token. #### `decimal` Metadata Type The `decimal` metadata type allows for a numeric value to be set for a trait in decimal form. The `dataType` object MAY have a `signed` value defined. If `signed` is not specified, it is assumed to be `false`. This determines whether the `traitValue` returned is interpreted as a signed or unsigned integer. The `dataType` object MAY have `minValue` and `maxValue` values defined. These should be formatted with the decimals specified. If `minValue` is not specified, it is assumed to be the minimum value of `signed` and `decimals`. If `maxValue` is not specified, it is assumed to be the maximum value of the `signed` and `decimals`. The `dataType` object MAY have a `decimals` value defined. The `decimals` value MUST be a non-negative integer. The `decimals` value determines the number of decimal places included in the `traitValue` returned onchain. If `decimals` is not specified, it is assumed to be 0. The `dataType` object MAY have a `valueMappings` object defined. If the `valueMappings` object is defined, the `valueMappings` object MUST be a mapping of `bytes32` values to numeric or unset `null` values. #### `boolean` Metadata Type The `boolean` metadata type allows for a boolean value to be set for a trait. The `dataType` object MAY have a `valueMappings` object defined. If the `valueMappings` object is defined, the `valueMappings` object MUST be a mapping of `bytes32` values to `boolean` or unset `null` values. The `boolean` values MUST be unique. If `valueMappings` is not used, the default trait values for `boolean` should be `bytes32(0)` for `false` and `bytes32(uint256(1))` (`0x0000000000000000000000000000000000000000000000000000000000000001`) for `true`. #### `epochSeconds` Metadata Type The `epochSeconds` metadata type allows for a numeric value to be set for a trait in seconds since the Unix epoch. The `dataType` object MAY have a `valueMappings` object defined. If the `valueMappings` object is defined, the `valueMappings` object MUST be a mapping of `bytes32` values to integer or unset `null` values. ### Events Updating traits MUST emit one of: - `TraitUpdated` - `TraitUpdatedRange` - `TraitUpdatedRangeUniformValue` - `TraitUpdatedList` - `TraitUpdatedListUniformValue` For the `Range` events, the `fromTokenId` and `toTokenId` MUST be a consecutive range of tokens IDs and MUST be treated as an inclusive range. For the `List` events, the `tokenIds` MAY be in any order. It is RECOMMENDED to use the `UniformValue` events when the trait value is uniform across all token ids, so offchain indexers can more quickly process bulk updates rather than fetching each trait value individually. Updating the trait metadata MUST emit the event `TraitMetadataURIUpdated` so offchain indexers can be notified to query the contract for the latest changes via `getTraitMetadataURI()`. Note that dynamic trait values MUST NOT be based on time-dependent factors (e.g. block timestamp) or other implicit state changes. All trait changes MUST be the result of an explicit onchain action that emits a corresponding `TraitUpdated` event. This requirement ensures that offchain indexers can remain synchronized with the current trait values by processing emitted events, rather than needing to continuously poll or re-evaluate trait values. ### `setTrait` If a trait defines `tokenOwnerCanUpdateValue` as `true`, then the trait value MUST be updatable by the token owner by calling `setTrait`. If the value the token owner is attempting to set is not valid, the transaction MUST revert. If the value is valid, the trait value MUST be updated and one of the `TraitUpdated` events MUST be emitted. If the trait has a `valueMappings` entry defined for the desired value being set, `setTrait` MUST be called with the corresponding `traitValue`. ## Rationale The design of this specification is primarily a key-value mapping for maximum flexibility. This interface for traits was chosen instead of relying on using regular `getFoo()` and `setFoo()` style functions to allow for brevity in defining, setting, and getting traits. Otherwise, contracts would need to know both the getter and setter function selectors including the parameters that go along with it. In defining general but explicit get and set functions, the function signatures are known and only the trait key and values are needed to query and set the values. Contracts can also add new traits in the future without needing to modify contract code. The traits metadata allows for customizability of both display and behavior. The `valueMappings` property can define human-readable values to enhance the traits, for example, the default label of the `0` value (e.g. if the key was "redeemed", "0" could be mapped to "No", and "1" to "Yes"). The `validateOnSale` property lets the token creator define which traits should be protected on order creation and fulfillment, to protect end users against frontrunning. ## Backwards Compatibility As a new EIP, no backwards compatibility issues are present, except for the point in the specification above that it is explicitly required that the onchain traits MUST override any conflicting values specified by the ERC-721 or ERC-1155 metadata URIs. ## Test Cases Authors have included Foundry tests covering functionality of the specification in the [assets folder](../assets/eip-7496/ERC721DynamicTraits.t.sol). ## Reference Implementation Authors have included reference implementations of the specification in the [assets folder](../assets/eip-7496/DynamicTraits.sol). ## Security Considerations The set\* methods exposed externally MUST be permissioned so they are not callable by everyone but only by select roles or addresses. Marketplaces SHOULD NOT trust offchain state of traits as they can be frontrunned. Marketplaces SHOULD check the current state of onchain traits at the time of transfer. Marketplaces MAY check certain traits that change the value of the NFT (e.g. redemption status, defined by metadata values with `validateOnSale` property) or they MAY hash all the trait values to guarantee the same state at the time of order creation. ## Copyright Copyright and related rights waived via [CC0](../LICENSE.md).