ERC-8122 - Minimal Agent Registry

Abstract

This protocol proposes a lightweight onchain registry for discovering AI agents using ERC-6909 as the underlying registry design, ERC-7930 for cross-chain agent identification, and ERC-8048 for onchain metadata. Each agent is represented as a token ID with a single owner and fully onchain metadata, enabling agent discovery and ownership transfer without reliance on external storage.

Motivation

While various offchain agent protocols handle things like agent-to-agent communication, they don't inherently cover agent discovery. To foster an open permissionless agent economy, we need a mechanism for discovering agents in a decentralized way, as well as decentralized registration and publishing of agent metadata. We also need a standard that anyone can use to deploy their own agent registry.

ERC-8004 provides an existing agent registry standard, but it defines a singleton registry—one per chain. A registry standard that supports custom deployments is necessary for specialized use cases, such as curated collections of agents (e.g., Whitehat Hacking Agents, DeFi Stablecoin Strategy Agents) or fixed-supply agent collections.

This ERC addresses this need through a lightweight minimal agent registry using ERC-6909. Anyone can deploy their own registry on any L2 or Mainnet Ethereum. All agent metadata is stored fully onchain using ERC-8048, ensuring censorship resistance and eliminating dependencies on external storage systems.

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.

Agent Registry

The agent registry extends ERC-6909 and implements ERC-8048 for onchain metadata. Each agent is uniquely identified globally by:

• agentRegistry: An ERC-7930 Interoperable Address (binary) pointing to the registry contract
• agentId: The token ID (uint256) assigned by the registry per its implementation-defined scheme

The ERC-7930 Interoperable Address encodes the chain type, chain reference, and contract address in a single binary format, eliminating the need for separate namespace and chainId fields.

Agent ID Format

When displaying the Agent ID as text, it MUST follow the ERC-8127 Human Readable Token Identifiers format: [alias.]agentId@registry, where registry is the lowercase hex representation of the ERC-7930 interoperable address and agentId is the decimal token ID. The optional alias MAY be taken from the agent's name metadata field. For example: agent.12345@0x00010000010114d8da6bf26964af9d7eed9e03e53415d37aa96045 or 12345@0x00010000010114d8da6bf26964af9d7eed9e03e53415d37aa96045 (without alias).

Ownership Model

Each agent has a single owner. The registry MUST maintain a mapping from agentId to owner address and provide an ownerOf(uint256 agentId) function that returns the current owner. It MUST revert if the agentId does not exist.

Transfer Restrictions

To enforce single ownership:

• The amount parameter in transfer and transferFrom MUST be exactly 1
• Transfers MUST revert if amount is not 1
• Upon transfer, the _owners mapping MUST be updated to reflect the new owner

Contract-Level Metadata

The registry SHOULD implement ERC-8049 for contract-level metadata about the registry itself. If ERC-8049 is used it MUST also expose a setContractMetadata function. Access control for this function is implementation-specific.

Standard Contract Metadata Keys

The following contract metadata keys SHOULD be set:

The following contract metadata keys MAY be set:

Implementations MAY define additional contract metadata keys as needed.

Agent Metadata

All agent metadata is stored onchain using the ERC-8048 key-value store interface. The registry MUST implement the ERC-8048 interface and expose a setMetadata function. This function MUST revert if the caller is not the owner of the agentId, an approved spender, or an operator for the owner.

Standard Metadata Keys

The following metadata keys are RECOMMENDED for interoperability:

Implementations MAY define additional keys as needed. All metadata values are stored as bytes. If the type is not otherwise specified, the value MUST be a UTF-8 string encoded as bytes.

URI Format and Substitutions

URIs in metadata fields (such as image and service) MAY include the {id} placeholder, which clients SHOULD replace with the token ID when resolving the URI. For example, a service URI of https://api.example.com/agents/{id} with token ID 12345 would resolve to https://api.example.com/agents/12345.

URIs MAY use InterPlanetary File System (IPFS) protocol. IPFS URIs SHOULD use the format ipfs://<CID>. Clients SHOULD support resolving IPFS URIs through IPFS gateways or native IPFS clients.

Additional services can be added using ERC-8119 Parameterized Storage Keys. For example, a second service can be stored using service_type: 1 and service: 1, a third service using service_type: 2 and service: 2, and so on.

Registration

New agents can be minted by calling one of the registration functions defined in the interface below. Upon registration:

• A new agentId MUST be assigned according to the registry's implementation-defined scheme and MUST be unique
• The provided owner MUST be set as the owner in the _owners mapping
• The owner MUST receive a balance of 1 for that agentId

This emits an ERC-6909 Transfer event (from address(0) to the owner), one ERC-8048 MetadataSet event for each metadata entry if any, and a Registered event as defined in the interface below. If any of the event parameters (service_type, service, or agent_account) are not set, they MUST be set to default empty values (empty string for strings, zero address for addresses) when emitting the event.

Interface

The registry MUST implement ERC-6909, ERC-8048, and MAY implement ERC-8049. The following interface defines the additional functions and events specific to this ERC:

interface IERC8122 {
    struct MetadataEntry {
        string key;
        bytes value;
    }

    event Registered(uint256 indexed agentId, address indexed owner, string service_type, string service, address agent_account);

    function register(address owner, string calldata service_type, string calldata service, address agent_account) external returns (uint256 agentId);
    function register(address owner, MetadataEntry[] calldata metadata) external returns (uint256 agentId);
    function registerBatch(address[] calldata owners, MetadataEntry[][] calldata metadata) external returns (uint256[] memory agentIds);
    function ownerOf(uint256 agentId) external view returns (address);
}

interface IERC8049SetContractMetadata {
    function setContractMetadata(string calldata key, bytes calldata value) external;
}

Rationale

The minimal agent registry is designed to be a simple, focused foundation for agent discovery, registration, and onchain metadata. ERC-6909 was chosen as the registry design because it is the most efficient minimal token standard, minimizing gas costs for agent registration and transfers. By storing all metadata onchain, we leverage the full power of Ethereum and its L2s: censorship resistance, atomic updates, composability with other smart contracts, and permanence. This approach ensures that agent information cannot be taken down or altered by external parties, and allows other protocols to build on top of the registry, whether for reputation systems, credentials (such as KYA "Know Your Agent"), or validation, without requiring changes to the core registry itself.

Backwards Compatibility

No issues.

Security Considerations

None.

Copyright

Copyright and related rights waived via CC0.