This ERC defines a standard for storing contract-level metadata onchain. It extends ERC-7572's contract-level metadata concept by providing onchain storage. Contracts MAY optionally use ERC-8042's Diamond Storage pattern for predictable storage locations, enabling cross-chain compatibility and supporting upgradable contracts.
ERC-7572 standardizes contract-level metadata via contractURI(), but it typically relies on offchain storage, which introduces trust and availability risks. This ERC enables fully onchain, verifiable contract metadata for trustless discovery in wallets and explorers, while preserving a familiar interface. Diamond Storage is optionally supported to provide predictable storage locations, making it easier to create inclusion proofs of individual metadata values for cross-chain verification and supporting upgradable contract deployments.
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 ERC MUST implement the following interface:
interface IERCXXXX {
/// @notice Get contract metadata value for a key.
function getContractMetadata(string calldata key) external view returns (bytes memory);
/// @notice Emitted when contract metadata is updated.
event ContractMetadataUpdated(string indexed indexedKey, string key, bytes value);
}
getContractMetadata(key): Returns the contract metadata value for the given key as bytesContracts implementing this ERC MAY also expose a setContractMetadata(string calldata key, bytes calldata value) function to allow metadata updates, with write policy determined by the contract.
Contracts implementing this ERC MUST emit the following event when metadata is set:
event ContractMetadataUpdated(string indexed indexedKey, string key, bytes value);
This ERC specifies that the key is a string type and the value is bytes type. This provides flexibility for storing any type of data while maintaining an intuitive string-based key interface.
Keys MAY include parameters to represent variations or instances of a metadata type, such as "registration: 1" or "name: Maria"; see ERC-8119: Key Parameters.
Contracts implementing this ERC MAY use Diamond Storage pattern for predictable storage locations. If implemented, contracts MUST use the namespace ID "erc8049.contract.metadata.storage".
The Diamond Storage pattern provides predictable storage locations for data, which is useful for cross-chain applications using inclusion proofs and for upgradable contracts. For more details on Diamond Storage, see ERC-8042.
If no standard is specified for a metadata value, clients MAY assume the value is a UTF-8 encoded string (bytes(string)) unless otherwise specified by the implementing contract or protocol.
A contract can store basic information about itself:
"name" → Value: bytes("MyToken")"description" → Value: bytes("A decentralized exchange")"collaborators" → Value: bytes(abi.encodePacked(address1, address2, address3))A contract can specify its ENS name using this standard:
"ens_name" → Value: bytes("mycontract.eth")This allows clients to discover the contract's ENS name and resolve it to get additional information about the contract.
Contracts implementing this ERC MAY use hooks to redirect metadata resolution to a different contract, enabling secure resolution from known contracts with verifiable security properties. This is particularly useful for credentials such as KYC, Proof-of-Personhood (PoP), and other verifiable credentials stored in singleton registries. For the full specification, see ERC-8121.
This design prioritizes simplicity and flexibility by using a string-key, bytes-value store that provides an intuitive interface for any type of contract metadata. The minimal interface with a single getContractMetadata function provides all necessary functionality. The optional setContractMetadata function enables flexible access control for metadata updates. The required ContractMetadataUpdated event provides transparent audit trails with indexed key for efficient filtering. Contracts that need predictable storage locations can optionally use Diamond Storage pattern. This makes the standard suitable for diverse use cases including contract identification, collaboration tracking, and custom metadata storage.
The interface is defined in the Required Metadata Function and Event section above. Here are reference implementations:
pragma solidity ^0.8.25;
import "./IERCXXXX.sol";
contract BasicContractMetadata is IERCXXXX {
// Simple mapping for contract-level metadata
mapping(string key => bytes value) private _metadata;
function getContractMetadata(string calldata key) external view override returns (bytes memory) {
return _metadata[key];
}
function setContractMetadata(string calldata key, bytes calldata value) external {
_metadata[key] = value;
emit ContractMetadataUpdated(key, key, value);
}
}
pragma solidity ^0.8.25;
import "./IERCXXXX.sol";
contract DiamondContractMetadata is IERCXXXX {
struct ContractMetadataStorage {
mapping(string key => bytes value) metadata;
}
// keccak256("erc8049.contract.metadata.storage")
bytes32 private constant CONTRACT_METADATA_STORAGE_LOCATION =
keccak256("erc8049.contract.metadata.storage");
function _getContractMetadataStorage() private pure returns (ContractMetadataStorage storage $) {
bytes32 location = CONTRACT_METADATA_STORAGE_LOCATION;
assembly {
$.slot := location
}
}
function getContractMetadata(string calldata key) external view override returns (bytes memory) {
ContractMetadataStorage storage $ = _getContractMetadataStorage();
return $.metadata[key];
}
function setContractMetadata(string calldata key, bytes calldata value) external {
ContractMetadataStorage storage $ = _getContractMetadataStorage();
$.metadata[key] = value;
emit ContractMetadataUpdated(key, key, value);
}
}
This ERC is designed to put metadata onchain, providing security benefits through onchain storage.
Implementations that choose to use the optional Diamond Storage pattern should consider the security considerations of ERC-8042.
Copyright and related rights waived via CC0.