Abstract

This ERC lets a contract store metadata about itself onchain as key-value pairs, with arbitrary bytes as values. Every update emits an event, and clients read the records directly from the contract.

Motivation

Contract metadata today typically relies on offchain storage such as URLs or IPFS, creating trust and availability risks—servers go down, domains expire, and malicious actors can modify data without onchain record. Storing metadata onchain makes contract identity censorship-resistant and enables wallets and block explorers to display verifiable information without trusting external services.

Specification

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.

Required Metadata Function and Event

Contracts implementing this ERC MUST implement the following interface:

interface IERC8049 {
    /// @notice Get the contract-level metadata value for a key.
    function metadata(string calldata key) external view returns (bytes memory);

    /// @notice Emitted when contract-level metadata is set.
    event MetadataSet(string indexed indexedKey, string key, bytes value);
}

Contracts implementing this ERC MAY also expose a setMetadata(string calldata key, bytes calldata value) function to allow metadata updates, with write policy determined by the contract.

The function names are shared with ERC-8048, whose per-token functions take a tokenId first, metadata(uint256,string) and setMetadata(uint256,string,bytes). The contract-level and per-token forms are Solidity overloads with distinct selectors, and a contract MAY implement both. When an ABI carries both forms, clients SHOULD call by full signature, metadata(string) for the contract-level record and metadata(uint256,string) for the per-token record, because some libraries do not resolve an overloaded name from the arguments.

Contracts implementing this ERC MUST emit the following event when metadata is set:

event MetadataSet(string indexed indexedKey, string key, bytes value);

MetadataSet(string,string,bytes) is distinct from ERC-8048’s MetadataSet(uint256,string,string,bytes), the two have different topic0 values, so indexers filter them apart.

Interface ID

The interface ID is 0x80a6dfa0, the selector of metadata(string).

Key/Value Pairs

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.

Optional Key Parameters

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.

Value Interpretation

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.

Examples

Example: Basic Contract Information

A contract can store basic information about itself:

  • Key: "name" → Value: bytes("MyToken")
  • Key: "description" → Value: bytes("A decentralized exchange")
  • Key: "collaborators" → Value: bytes(abi.encodePacked(address1, address2, address3))

Example: ENS Name for Contract

A contract can specify its ENS name using this standard:

  • Key: "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.

AI Agent Metadata Profile

This profile defines a reserved set of this ERC’s contract-level metadata keys that associate an ERC-20 token contract with a single AI agent, and is nicknamed ERC-20Agent. It is a standard use of this ERC’s existing key-value interface; it does not define a new Solidity interface, a new ERC-165 interface ID, new functions, or new events. Consumers read and write these records through metadata(string) and rely on the MetadataSet event for change notifications, exactly as for any other key under this ERC.

Because this ERC’s records are contract-level, that agent belongs to the token contract as a whole, not to any holder or balance. What that agent is used for is left to the issuer. It might provide information about the token through agent-user or agent-UI chat, represent token-based governance, or serve any other mechanism the issuer intends.

A contract implementing this profile MUST implement ERC-20 and this ERC. The profile reserves the following keys:

Key Meaning Value (bytes)
context Agent context for the contract. UTF-8 text. Markdown is RECOMMENDED; issuers MAY embed a fenced JSON block for machine-readable fields.
endpoint[<type>] Endpoint for the named protocol <type>. UTF-8 text. For endpoint[web], an https URI is RECOMMENDED.
address[<chain-id>] The agent’s account on the chain identified by <chain-id>, where <chain-id> is the ERC-7930 Chain Identifier (see “Chain-keyed addresses” below). The Address component of an ERC-7930 Interoperable Address for the chain named by <chain-id>. For an EVM chain, the 20-byte address.
account[<chain-id>][<index>] OPTIONAL. An additional account of the agent on the chain identified by <chain-id>, distinguished by <index>. See “Additional accounts” below. The Address component of an ERC-7930 Interoperable Address for the chain named by <chain-id>. For an EVM chain, the 20-byte address.

Endpoint types

Keys are case-sensitive (the value of key is compared as exact bytes). Endpoint types in this profile are therefore lowercase: endpoint[mcp] and endpoint[MCP] are distinct keys, and only the lowercase spelling carries the meaning reserved here. Implementations MUST write the canonical lowercase spelling for the types this profile reserves.

The canonical endpoint types are:

  • mcp: Model Context Protocol endpoint URI.
  • a2a: Agent-to-Agent endpoint URI.
  • web: general web endpoint. The value MAY be any URI, with https RECOMMENDED.
  • x402: payment-enabled endpoint URI.
  • ens: the agent’s ENS name, for example agent.eth. The value is the name as UTF-8 text.

Additional endpoint types MAY be used without changing this profile, provided they use the endpoint[<type>] form. Standards that reserve new types SHOULD define their exact canonical (lowercase) spelling.

Chain-keyed addresses

In address[<chain-id>], <chain-id> is the ERC-7930 Chain Identifier, an Interoperable Address with a zero-length address part, encoded as a lowercase 0x-prefixed hex string. The stored value is the Address component of an ERC-7930 Interoperable Address for that chain, the chain’s native address bytes. It is the Address component alone, not a full Interoperable Address.

For example, the Chain Identifier for Ethereum mainnet (chain ID 1) is 0x00010000010100. The agent’s mainnet account would be stored as:

  • Key: "address[0x00010000010100]" → Value: the 20 bytes of the EVM address.

Additional accounts

An issuer MAY list additional accounts for the contract’s agent under the OPTIONAL key account[<chain-id>][<index>]. The accounts are contract-level and belong to the token contract’s agent as a whole, not to any holder or balance. Any account qualifies, for example a token-bound account or a smart contract wallet.

address[<chain-id>] is the agent’s primary account on that chain. Clients SHOULD send funds to address[<chain-id>] and SHOULD NOT assume an account listed under account[<chain-id>][<index>] accepts payments.

<chain-id> is the ERC-7930 Chain Identifier and the stored value is the ERC-7930 Address component for that chain, both exactly as in address[<chain-id>].

<index>, an unsigned base-10 integer with no leading zeros, distinguishes multiple accounts on the same chain.

For example, the agent’s additional account at index 0 on Ethereum mainnet would be stored as:

  • Key: "account[0x00010000010100][0]" → Value: the 20 bytes of the EVM address.

Client expectations

The keys of this profile MUST be stored onchain, on this contract or the metadata_contract sidecar, and MUST NOT appear in contractURI or equivalent JSON. Clients MUST read them with metadata(string) and MUST ignore JSON members with these names. Clients SHOULD treat context and endpoints as untrusted input.

Optional Metadata Authority Extension

This optional extension lets a contract’s metadata be written by a metadata authority. The authority can be an account or a contract, and a contract authority can apply its own rules, for example letting different parties write different keys. An implementation MUST also implement this ERC and ERC-165, and MUST return true from supportsInterface for 0xa3703af1.

interface IERC8049MetadataAuthority {
    /// @notice The current metadata authority for this contract.
    function metadataAuthority() external view returns (address);

    /// @notice Emitted whenever the metadata authority is set, changed, or cleared.
    event MetadataAuthoritySet(address indexed authority);
}

When metadataAuthority() is not the zero address, setMetadata MUST authorize only that exact authority. When it is the zero address, the contract’s own write policy applies, and the metadata may not be updatable at all. A call that fails authorization MUST revert and MUST NOT emit MetadataSet. How the authority is set is implementation-defined, and the implementation MUST emit MetadataAuthoritySet whenever it is set, changed, or cleared, with the zero address when cleared.

Onchain Metadata Contract Reference (Optional Extension)

Many contracts are already deployed without the metadata function, and adding it is often impossible without an upgrade path. This optional extension directs clients to a separate metadata contract that implements metadata(string), on the same chain.

When contractURI or an equivalent contract-level URI function returns a string that resolves to a JSON document, the document MAY include a top-level string property named "metadata_contract". Its value MUST be the address of the metadata contract, a 0x prefix followed by 40 hexadecimal characters. Clients MUST accept any letter case, and MUST ignore a value that is not in this form.

Clients that support this extension read metadata(string key) from that contract. Contracts using only this extension are NOT required to implement IERC8049. The referenced contract MUST implement metadata(string). Clients MAY ignore a metadata_contract they do not trust.

Rationale

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 metadata function provides all necessary functionality. The optional setMetadata function enables flexible access control for metadata updates. The required MetadataSet event provides transparent audit trails with indexed key for efficient filtering. The names match ERC-8048 so that per-token and contract-level metadata read as one family, metadata(tokenId, key) and metadata(key), in the way name() is shared by ERC-20 and ERC-721. Overloads keep the selectors distinct, and the cost falls only on clients whose library resolves overloaded names poorly, which the Specification addresses. This makes the standard suitable for diverse use cases including contract identification, collaboration tracking, and custom metadata storage. AI Agent Metadata Profile keys are onchain only because JSON can change without a MetadataSet event, and clients act on these values, for example by sending funds to address[<chain-id>].

Backwards Compatibility

  • Fully compatible with existing smart contracts.
  • Non-supporting clients can ignore the scheme.
  • An earlier revision of this Draft named the functions contractMetadata(string) and setContractMetadata(string,bytes), the event ContractMetadataUpdated, and the interface ID 0x8ec3f882. Implementations of that revision are not compatible with this one and should be redeployed or upgraded.

Reference Implementation

The interface is defined in the Required Metadata Function and Event section above. Here are reference implementations:

Basic Implementation

pragma solidity ^0.8.25;

import "./IERC8049.sol";

contract BasicContractMetadata is IERC8049 {
    // Simple mapping for contract-level metadata
    mapping(string key => bytes value) private _metadata;

    function metadata(string calldata key) external view override returns (bytes memory) {
        return _metadata[key];
    }

    function setMetadata(string calldata key, bytes calldata value) external {
        _metadata[key] = value;
        emit MetadataSet(key, key, value);
    }
}

ERC-20Agent Implementation

This example applies the AI Agent Metadata Profile to an ERC-20 token. The owner sets the agent’s records at deployment and can update them later.

pragma solidity ^0.8.25;

import {ERC20} from "@openzeppelin/contracts/token/ERC20/ERC20.sol";
import {Ownable} from "@openzeppelin/contracts/access/Ownable.sol";
import "./IERC8049.sol";

contract ERC20Agent is ERC20, Ownable, IERC8049 {
    mapping(string key => bytes value) private _metadata;

    constructor(string memory context, string memory mcpEndpoint, address agent)
        ERC20("Agent Token", "AGENT")
        Ownable(msg.sender)
    {
        _setMetadata("context", bytes(context));
        _setMetadata("endpoint[mcp]", bytes(mcpEndpoint));
        // The agent's account on Ethereum mainnet, keyed by its ERC-7930 Chain Identifier
        _setMetadata("address[0x00010000010100]", abi.encodePacked(agent));
    }

    function metadata(string calldata key) external view override returns (bytes memory) {
        return _metadata[key];
    }

    function setMetadata(string calldata key, bytes calldata value) external onlyOwner {
        _setMetadata(key, value);
    }

    function _setMetadata(string memory key, bytes memory value) private {
        _metadata[key] = value;
        emit MetadataSet(key, key, value);
    }
}

Security Considerations

This ERC is designed to put metadata onchain, providing security benefits through onchain storage.

A metadata_contract is chosen by the document, so the bytes it returns are untrusted, and clients should verify its address as for any new contract interaction.

Copyright and related rights waived via CC0.