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

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

Original ERC · ← ERCs