ERC-8048 On-chain metadata for token registries (Onchain Metadata for Token Registries)
Draft · Names & metadata · created 2025-09-30
A standard that adds a string-key, byte-value store to ERC-721, ERC-1155, and ERC-6909 tokens, allowing metadata to be stored and read directly on the blockchain without an external server.
Why it is needed
There has long been demand for storing NFT or multi-token metadata directly on the blockchain, but there has been no unified method until now. Some projects packed the entire metadata as a Data URL into the token's address field, tokenURI, but this approach is gas-inefficient and has side effects such as complicating storage proofs. Also, since storage methods differ from project to project, wallets or apps cannot read the metadata of multiple tokens using a single method. This standard solves this problem by providing a unified key-value storage interface compatible with existing ERC-721, ERC-1155, and ERC-6909 tokens.
What to implement
function metadata(uint256 tokenId, string calldata key) external view returns (bytes memory);: Returns the metadata value corresponding to a given token ID and key as bytes.event MetadataSet(uint256 indexed tokenId, string indexed indexedKey, string key, bytes value);: An event that must be emitted whenever a token's metadata is set, serving as an audit record of the change history.setMetadata(uint256 tokenId, string calldata key, bytes calldata value): An optional write function that may be provided. The contract's write policy determines who can write to it.function tokenMetadataAuthority() external view returns (address);: A function of the optional extension that returns the current metadata authority address for all tokens in the collection.event TokenMetadataAuthoritySet(address indexed authority);: Emitted when the collection's metadata authority is set, changed, or cleared; the zero address is used when cleared.
In depth
Core interface: string keys, byte values
Implementing contracts must provide a metadata(tokenId, key) function. Since the key is a string type and the value is a bytes type, any data such as strings, numbers, or hashes can be stored under an intuitive key. The write function setMetadata(uint256, string, bytes) is optional, and the write policy is determined by the contract. When metadata is set, a MetadataSet(tokenId, indexedKey, key, value) event must be emitted, and this event serves as an on-chain audit record. This standard is an optional extension that ERC-721, ERC-1155, and ERC-6909 compatible registries can attach, and it is backward compatible with existing standards. Keys can carry parameters like "registration[1]" or "name[maria]" to represent variants or instances of one type of metadata, and the parameterized key format follows ERC-8119.
ERC-165 interface detection
The interface ID for this standard is 0xdf670be1. Contracts implementing IERC8048Metadata must implement ERC-165 and must return true for both 0xdf670be1 (this interface) and 0x01ffc9a7 (ERC-165 itself) when supportsInterface is called. This lets a caller first check whether a given contract supports on-chain metadata before reading records. If the metadata authority extension is implemented, it must also return true for that extension's interface ID, 0x04f90b41.
Agent Metadata Profile (ERC-721T)
A profile that defines a set of reserved keys for ERC-721 tokens representing agents, reusing the existing metadata function and MetadataSet event without adding a new Solidity interface, ERC-165 ID, or event. The reserved keys are context (UTF-8 text, markdown recommended), endpoint[<type>] (the standard types are mcp, a2a, web, x402, and ens, and keys are case-sensitive with lowercase being the norm), address[<chain-id>] (the default account), and account[<chain-id>][<index>] (additional accounts, where index is a base-10 integer with no leading zeros). <chain-id> is an ERC-7930 chain identifier; Ethereum mainnet is 0x00010000010100 and Base is 0x0001000002210500. The value is the address bytes for that chain, 20 bytes for EVM chains. Clients must send funds to address[<chain-id>] and must not assume that the account in an account key receives payments. tokenURI is kept unchanged for existing marketplaces, and agent-aware clients should read keys from this standard's records while treating endpoints and context as untrusted input.
Metadata authority extension
An optional extension that lets a single metadata authority (an account or contract) write metadata for all tokens in a collection instead of each holder. It standardizes only the read function tokenMetadataAuthority() and the event TokenMetadataAuthoritySet. If tokenMetadataAuthority() is non-zero, setMetadata must allow only that address for every token with no exceptions; if it is zero, who can write is left to the contract's own write policy. Calls that fail the authority check must revert without emitting MetadataSet. How the authority is set, changed, or cleared is left to each implementation, but an event must be emitted whenever the returned address changes, including at deployment if the authority is non-zero at that time. The reason for having a single authority per collection rather than per token is that a per-token authority would require an event for every token on an authority change; if multiple parties need to use different keys, a policy contract is set as the authority. In the original example, a housing token's policy contract lets the housing authority write only the size, the appraiser write only the appraised value, and the owner write only usr.* keys.
Metadata contract reference for already deployed contracts
Registries that are already deployed cannot add a metadata function or storage if there is no upgrade path. This optional extension places a top-level string attribute "metadata_contract" in the JSON document returned by tokenURI or uri, pointing to a separate metadata contract address on the same chain. The value must be a 20-byte address string consisting of 0x followed by 40 hex digits, and clients accept it case-insensitively. If the format does not match, it is ignored. Clients read that contract's metadata(uint256,string) with the same tokenId, and the result is the same as if the token contract had stored it directly. A registry that uses only this extension does not need to implement IERC8048Metadata on the token contract, but the referenced contract must implement that function. A malicious or incorrect address could return attacker-controlled bytes, so it is recommended to call only trusted contracts.
Draft status
This proposal was created on September 30, 2025 and is currently in Draft status. This means the content may still change during review, so it is advisable to check the latest original text before implementing or depending on it. This proposal references ERC-165 (interface detection), ERC-7930 (interoperable addresses), and ERC-8119 (parameter key format) as prerequisites.
Things to watch out for
- Possibility of replacing the authority contract: A contract set as the metadata authority can be replaced unless the implementation prevents it. A policy contract's rules are valid only while that contract remains the authority.