ERC-7572 Contract-level metadata standard (Contract-level metadata via `contractURI()`)
Draft · Names & metadata · created 2023-12-06
A standard that lets a contract expose descriptive information such as its name, description, and image through a single contractURI() function, and announce via an event when that information changes.
Why it is needed
Ethereum contracts had no common way to hold descriptive information such as a name, description, or representative image. As a result, blockchain apps (dapps) or off-chain indexers that aggregate data had to manually enter such information contract by contract, service by service, in order to display richer information about contracts. In fact, many dapps had already supported a function called contractURI() for years, but there was no official standard (ERC) to reference. There was also no common signal to announce when metadata changed, making it hard for off-chain services to know when to refetch information. This standard solves the problem by defining the contractURI() function, the format of the returned JSON, and the ContractURIUpdated() event that announces updates.
What to implement
function contractURI() external view returns (string memory);: Returns a string pointing to contract-level metadata. This may be the address of an off-chain resource, or an on-chain data string containing the JSON directly.event ContractURIUpdated();: An event announcing that a contract's metadata has been updated. Off-chain indexers watch for this to refetch information.
In depth
Required interface and return value format
A contract MUST implement the IERC7572 interface. The interface consists of two components: the view function contractURI(), which returns a string, and the event ContractURIUpdated(). The string returned by contractURI() MAY be an address pointing to an off-chain resource, or it MAY be an on-chain data string containing the JSON directly in the form data:application/json;utf8,{}. In other words, where the metadata is stored is up to the implementer, but readers always access it through the same function.
The role of the ContractURIUpdated() event
It is RECOMMENDED to emit the ContractURIUpdated() event when a contract's metadata is updated. Off-chain indexers can use this event to know when to refetch that contract's metadata. The source Rationale also explains that this event was specified to signal to indexers when to refetch. The function name contractURI() was chosen based on existing implementations across dapps.
Priority when conflicting with name()/symbol()
If a contract already provides methods such as name() or symbol() that overlap with the contractURI schema, it is RECOMMENDED that the metadata returned by contractURI() take priority. This allows the contract creator to update contract information even after deployment and announce the update via the event.
JSON schema structure
The JSON returned by contractURI() MUST follow a defined schema. The only required field is name (the contract's name). Optional fields include symbol, description, image (a representative image URI used like a profile picture), banner_image (a banner image URI), featured_image (a representative image URI used in a highlight section), external_link, and collaborators (an array of Ethereum addresses representing the contract's authorized editors). Later ERCs MAY inherit this standard and standardize additional attributes in the schema.
Reference implementation and setter function
The reference implementation keeps a _contractURI string variable and shows an example of either returning it directly from contractURI(), or returning it on-chain by appending the JSON string after data:application/json;utf8,. The setContractURI(string memory newURI) function, which changes the metadata by storing the new URI and emitting the ContractURIUpdated() event, is merely a suggested setter function and is not explicitly included in the specification of this ERC.
Proposal status
This document was created on December 6, 2023, and its current status is Draft. As it is not yet a finalized standard, its content may change.
Things to watch out for
- Permissions of collaborators addresses: An address designated as a collaborator should be expected to receive admin-level capabilities to modify contract information in dapps implementing this standard.