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

Original ERC · ← ERCs