DOCSEARCHbyAlgolia
Submit Docs

ERC-8004 Trustless Agents Protocol

repository·master·Indexed 42 days ago

https://github.com/erc-8004/erc-8004-contracts

A protocol implementation for trustless agent discovery and trust management. It utilizes three core registries: the Identity Registry (an ERC-721 based system for agent identification), the Reputation Registry (for recording and aggregating signed feedback signals), and an experimental Validation Registry for formal agent verification via TEE oracles or zkML proofs.

Tokens
8.6K
Snippets
12
Records
34
Agent score
54%

What's inside ERC-8004

  2. Understand the ERC-8004 Trustless Agents protocol

    master

    ERC-8004 is a protocol designed to enable open-ended agent economies by providing mechanisms to discover, choose, and interact with agents across organizational boundaries without pre-existing trust.

    It achieves this through a pluggable and tiered trust model where security is proportional to the value at risk. Developers can implement different trust mechanisms depending on the task requirements, such as:

    • Reputation systems: Using client feedback.
    • Validation via stake-secured re-execution: Stakers re-running jobs.
    • Zero-knowledge machine learning (zkML) proofs.
    • Trusted Execution Environment (TEE) oracles.
    • Trusted judges.

  3. How the ERC-8004 registry system works

    master

    The protocol relies on three lightweight registries that can be deployed as per-chain singletons on Mainnet or any L2. These registries facilitate discovery and trust:

    1. Identity Registry: Provides a portable, censorship-resistant identifier for every agent. It is based on [ERC-721] with the URIStorage extension and resolves to an agent's registration file.
    2. Reputation Registry: A standard interface for posting and fetching feedback signals. Scoring and aggregation can happen both on-chain (for composability) and off-chain (for complex algorithms), supporting auditor networks and insurance pools.
    3. Validation Registry: Provides generic hooks for requesting and recording independent validator checks, such as zkML verifiers, TEE oracles, or stakers re-running a job.

  4. How agent identification works

    master

    An agent in the ERC-8004 ecosystem is identified by two primary components that should be included in all off-chain payloads (such as registration files or feedback files) to ensure they can be tied back to the on-chain identity:

    1. agentRegistry: A string following the format {namespace}:{chainId}:{identityRegistry} (e.g., eip155:11155111:0x...).
    2. agentId: The specific ERC-721 tokenId minted by the Identity Registry.

    ERC-8004 enables discovery by using an ERC-721 identity where the tokenURI points to a registration file containing agent metadata and service endpoints.

  5. How the UUPS Proxy Pattern and Vanity Deployment work

    master

    The ERC-8004 protocol uses the UUPS (Universal Upgradeable Proxy Standard) pattern (EIP-1822) combined with a MinimalUUPS Placeholder Strategy to achieve deterministic vanity addresses via CREATE2.

    The Two-Phase Deployment Model

    1. Phase 1 (Placeholder): Proxies are deployed pointing to MinimalUUPS. This is a lightweight implementation that only stores the _identityRegistry and the owner. This phase allows the proxies to be mined at specific vanity addresses.
    2. Phase 2 (Upgrade): The proxies are upgraded to the real Implementation Contracts (e.g., IdentityRegistryUpgradeable) using pre-signed transactions.

    Storage Persistence

    To ensure data persists through the upgrade from the placeholder to the real implementation, the _identityRegistry is stored at slot 0 in both MinimalUUPS and the real implementations. All other contract data is stored using ERC-7201 namespaced storage to prevent collisions.

  6. Understand the design rationale for ERC-8004

    master

    ERC-8004 is designed to provide a flexible, interoperable framework for Trustless Agents. Key design principles include:

    • Flexible Communication: Instead of locking into a single protocol, the specification links blockchain identities to a registration file that can include various endpoints like MCP (Model Context Protocol), A2A (Agent-to-Agent), wallet addresses, DIDs, and ENS names.
    • Standardized Nomenclature: It leverages existing AI primitives (e.g., tasks and skills from A2A; tools and prompts from MCP) to ensure compatibility with current AI ecosystems.
    • Frictionless Feedback: By removing the requirement for clients to be registered, applications can implement feedback mechanisms using EIP-7702 for gas sponsorship.
    • On-chain Indexing: Feedback data is stored on-chain (with full data suggested on IPFS), making it compatible with subgraphs for easy indexing and improved UX.
    • Cross-chain Interoperability: Registries are intended to be singletons per chain. An agent registered on Chain A can still operate and transact on other chains, and agents can be registered on multiple chains simultaneously.

  7. Understand the ERC-8004 Identity Registry and Agent Identification

    master

    The Identity Registry uses ERC-721 with the URIStorage extension to register agents as NFTs. This makes agents browsable and transferable using standard NFT applications.

    An agent is uniquely identified by two components:

    1. agentRegistry: A colon-separated string in the format {namespace}:{chainId}:{identityRegistry} (e.g., eip155:1:0x742...).
      • namespace: Chain family (e.g., eip155 for EVM).
      • chainId: Network identifier.
      • identityRegistry: The contract address of the ERC-721 registry.
    2. agentId: The specific ERC-721 tokenId assigned by the registry.

    In the specification, tokenId is referred to as agentId and tokenURI is referred to as agentURI.

  8. How the Vanity Address deployment strategy works

    master

    The deployment uses a MinimalUUPS placeholder strategy to achieve deterministic vanity addresses for proxies. Because proxy addresses are determined by the bytecode of the implementation they point to during deployment, we cannot deploy a proxy directly to a vanity address if the final implementation bytecode is unknown or different.

    The Workflow:

    1. Placeholder Deployment: A MinimalUUPS contract is deployed via CREATE2. This contract is designed to have a specific bytecode that, when used as the initial implementation for proxies, results in the desired vanity addresses.
    2. Proxy Deployment: Proxies (Identity, Reputation, and Validation Registries) are deployed pointing to the MinimalUUPS implementation. These proxies land on the target vanity addresses.
    3. Implementation Deployment: The real, full-featured implementation contracts are deployed via CREATE2.
    4. Upgrade: The proxies are upgraded from MinimalUUPS to the real implementations using pre-signed transactions.

    Storage Compatibility: To ensure data persists during the upgrade, MinimalUUPS and the real implementations share the same storage layout for critical variables. Specifically, _identityRegistry is stored at Slot 0 in both versions.

  10. Deploy ERC-8004 Upgradeable Contracts

    master

    To deploy the upgradeable registry suite on a live network, follow these steps in sequence. Note that generating pre-signed upgrades requires the OWNER_PRIVATE_KEY to be set in your .env file.

    1. Deploy CREATE2 factory: Ensure the factory is present on the network.
    2. Deploy all contracts: This deploys the MinimalUUPS placeholders, the proxies (at vanity addresses), and the initial implementations.
    3. Generate pre-signed upgrades: Creates the transactions required to move from the placeholder to the real implementation.
    4. Broadcast upgrades: Executes the pre-signed transactions to finalize the upgrade.
    5. Verify: Confirm the deployment and upgrades were successful.
    # 1. Deploy CREATE2 factory (if needed)
npx hardhat run scripts/deploy-create2-factory.ts --network <network>

# 2. Deploy all contracts
npx hardhat run scripts/deploy-vanity.ts --network <network>

# 3. Generate pre-signed upgrades (requires OWNER_PRIVATE_KEY in .env)
npx hardhat run scripts/generate-triple-presigned-upgrade.ts --network <network>

# 4. Broadcast upgrades
npx hardhat run scripts/upgrade-vanity-presigned.ts --network <network>

# 5. Verify
npx hardhat run scripts/verify-vanity.ts --network <network>

  11. Test ERC-8004 deployment on localhost

    master

    For local development and testing, you can automate the entire deployment and upgrade flow using the npm run local command. This requires running a local Hardhat node first.

    1. Start the local node:
      npx hardhat node
    2. In a separate terminal, run the full deployment suite:
      npm run local

    The npm run local command executes:

    • local:factory: Deploys the CREATE2 factory.
    • local:vanity: Performs the deployment, upgrade, and verification steps.
    npx hardhat node
npm run local

  12. Implement the end-to-end ERC-8004 agent flow

    master

    To fully onboard an agent using ERC-8004, follow these steps:

    1. Register: Call register(...) on the Identity Registry to obtain an agentId.
    2. Publish: Create a registration JSON file (containing metadata and services) and host it (e.g., on IPFS). Set this location using setAgentURI(agentId, uri).
    3. Verify Wallet (Optional): Use setAgentWallet(...) with an EIP-712/ERC-1271 proof to establish a verified receiving wallet.
    4. Collect Feedback: Use giveFeedback(...) on the Reputation Registry to gather trust signals from users.
    5. Aggregate: Use getSummary(...) or readAllFeedback(...) to calculate trust scores for in-app logic.