ERC-7508 Dynamic On-Chain Token Attribute Repository (Dynamic On-Chain Token Attributes Repository)
Draft · NFTs & multi-token · created 2023-08-15
Records attributes of ERC-721 and ERC-1155 tokens on-chain in a shared repository contract that uses the same address on every network, so any external contract can query and use those attributes.
Why it is needed
NFTs commonly store attributes such as images or stats on off-chain metadata servers. With this approach, if the server goes down the attributes disappear forever, and for another game or service to use these attributes it has to trust and fetch from an unreliable external URL. Attribute storage also differs from token contract to token contract, making it hard for one collection's character stats to be reused as-is by another collection or game. Even when developers want to build features where a token evolves or changes state based on the owner's actions, without a standardized on-chain repository each collection has to build its own attribute management and access control code from scratch, which increases deployment cost and contract complexity.
In depth
Access control structure (AccessType)
The repository can assign one of five access types to each attribute key. Owner means only the collection owner can change the value, Collaborator means only a designated collaborator can, OwnerOrCollaborator means either one can, TokenOwner means only that token's owner can, and SpecificAddress means only a separately designated address can. After registering a collection with registerAccessControl, you set the type per key with manageAccessControl and manage the collaborator list with manageCollaborators.
Attribute types and key-value storage
Attributes are divided into six types: address, bool, bytes, int256, string, and uint256, each represented as a {key, value} struct. For any type, one value is mapped based on the collection address, token ID, and string key, and whenever the value changes, a type-specific Updated event is emitted.
Single and batch queries and settings
For each type, both getX/setX functions for handling a single attribute on a single token and getXs/setXs batch functions for processing multiple collections and multiple tokens at once are provided. If every item in the collections and tokenIds arrays is the same collection or the same token, you only need to supply a single element. getAttributes/setAttributes query and set all six types in a single call.
Proxy setting via presigned signatures
You obtain the raw message to sign with the prepareMessageToPresignXAttribute function, and once the user signs this message with ECDSA, another address can call presignedSetXAttribute (which includes v, r, s) to set the attribute on their behalf. The message is constructed by combining DOMAIN_SEPARATOR, a method-specific TYPEHASH, collection, tokenId, key, value, and deadline with keccak256, and signatures past their deadline are rejected.
Collection-level attributes and schema
Attributes shared by an entire collection rather than individual tokens are queried and set using the maximum value of uint256 as the token ID. A collection owner can define a schema for each attribute with the fields name, description, type, display_name, display_type, decimals, min_value, max_value, conditional_value, modifiers, and multi_storage, of which only name and type are required.
String indexing and a predetermined address for gas savings
Because strings are expensive to store, the repository is designed so that only the first person to store a given string key or value pays the full cost, while subsequent users only store an index to that string. This savings mechanism applies across the entire repository, so if one collection has already registered a string, another collection using it does not pay the cost again. The repository contract is designed to be deployed at the same address on every network, starting with 0xA77B75 (evoking 'ATTBTS'), though the exact address has not yet been finalized.
Standard status
This proposal is in Draft status: it has not been finalized, and its details may change or progress may stall.
Things to watch out for
- No asset risk: The repository does not hold user assets directly, so interacting with the attributes repository does not put your assets at risk.
- Replay prevention through chain-specific signature separation: The DOMAIN_SEPARATOR included in a signed message incorporates the chain ID and repository address, so it differs by chain, and a signature created on one chain is rejected if reused on another.
- Presigned message reuse: Until its deadline passes, the same presigned message can be submitted multiple times, so when combined with logic that reverts or resets attributes, a value could be unintentionally reapplied. Services are recommended to set short deadlines.
- Beware of unaudited contracts: Caution is needed when integrating with unaudited contracts.