ERC-8049 Contract onchain metadata (Contract-Level Onchain Metadata)

Draft · Names & metadata · created 2025-10-10

A standard that lets any contract store information about itself directly onchain as key-value pairs, so wallets and explorers can read those values without an external service.

Why it is needed

Until now, descriptive information (metadata) about contracts has mostly been placed in offchain storage such as URLs or IPFS. This approach creates trust and availability problems. If a server goes down or a domain expires, the information disappears, and a malicious operator could change the content without leaving an onchain record. Wallets and block explorers can only display contract information by trusting an external service. This standard lets metadata be stored directly in the contract as key-value pairs, making contract information censorship-resistant and verifiable by anyone without relying on external services. All changes are recorded as events and can be tracked.

What to implement

In depth

Required interface and interface ID

An implementing contract must implement metadata(string) and the MetadataSet(string indexed indexedKey, string key, bytes value) event, and must emit the event whenever metadata is set. The setMetadata(string calldata key, bytes calldata value) function for updates is optional, and the write policy is determined by the contract. The interface ID is 0x80a6dfa0, the selector for metadata(string). Keys are of type string and values of type bytes; unless a standard governing the value is specified separately, clients may assume a UTF-8 string. Keys can carry ERC-8119-style parameters to express variants or instances, such as "registration: 1".

Name sharing with ERC-8048 (per-token metadata)

The function name is shared with ERC-8048, the per-token metadata standard, whose version takes tokenId first in the form metadata(uint256,string) and setMetadata(uint256,string,bytes). The two forms are Solidity overloads with different selectors, so a single contract can implement both. Some libraries cannot distinguish overloads by arguments alone, so when both forms are present in the ABI, clients are recommended to call them with the full signature, such as metadata(string) or metadata(uint256,string). The events also differ: MetadataSet(string,string,bytes) and ERC-8048's MetadataSet(uint256,string,string,bytes) have different topic0 values, so indexers can distinguish and filter them.

AI Agent Metadata Profile (ERC-20Agent)

A set of reserved keys that links an ERC-20 token contract to a single AI agent, using the existing metadata(string) function and MetadataSet event without adding any new interfaces, functions, or events. The reserved keys are context (the agent's context, UTF-8 text, markdown recommended), endpoint[<type>] (protocol-specific access address), address[<chain-id>] (the primary account on that chain), and account[<chain-id>][<index>] (optional, additional accounts). Keys are case-sensitive, and the reserved endpoint types are the lowercase mcp, a2a, web, x402, and ens. The agent belongs to the token contract as a whole and not to any specific holder or balance. Clients must send funds to address[<chain-id>] and must not assume that accounts under the account key receive deposits.

Chain-keyed address notation (ERC-7930)

In the address[<chain-id>] key, <chain-id> is the ERC-7930 chain identifier (an interoperable address with an address portion of length 0) written as a lowercase 0x-prefixed hex string. The value stored is only the address component of the ERC-7930 interoperable address for that chain, which is a 20-byte address for EVM chains. For example, the chain identifier for Ethereum mainnet (chain ID 1) is 0x00010000010100, so an agent's mainnet account is stored as a 20-byte address under the key "address[0x00010000010100]". Additional accounts are distinguished with a decimal index with no leading zeros, such as "account[0x00010000010100][0]".

Optional metadata authority extension

An extension that lets a separate metadata authority write a contract's metadata. The authority can be an account or a contract, and a contract authority can apply its own rules, such as allowing different writers per key. An implementation must implement this ERC together with ERC-165, and supportsInterface must return true for 0xa3703af1. If metadataAuthority() is not the zero address, setMetadata must allow only that exact authority. If it is the zero address, the contract's own write policy applies, and updates may not be possible at all. Calls that fail authorization must revert and must not emit MetadataSet. MetadataAuthoritySet must be emitted whenever the authority is set, changed, or cleared.

The metadata_contract extension for already-deployed contracts

An optional extension for contracts that are already deployed without a metadata function and are difficult to upgrade. It places a top-level string attribute "metadata_contract" in the JSON document returned by a contract-level URI function such as contractURI, pointing to the address of a separate metadata contract on the same chain that implements metadata(string). The value must be 0x followed by 40 hex characters, and clients must accept both cases but ignore it if it does not match this format. A contract that uses only this extension does not need to implement IERC8049, but the referenced contract must implement metadata(string). Clients may ignore a metadata_contract they do not trust.

Incompatibility with the previous revision

An earlier revision of this Draft defined the function as contractMetadata(string) and setContractMetadata(string,bytes), the event as ContractMetadataUpdated, and the interface ID as 0x8ec3f882. Implementations of that revision are incompatible with the current version and must be redeployed or upgraded. Aside from that, it is fully compatible with existing smart contracts, and clients that do not support it can simply ignore this scheme.

Proposal status

This document is a proposal in Draft status, created on October 10, 2025. It has not yet been finalized, so the interface or reserved keys may change going forward. In fact, the function names and interface ID were changed once in a previous revision.

Things to watch out for

Original ERC · ← ERCs