\n ERC-8004: Trustless Agents\n \n \n \n \n \n \n
\nDiscover agents and establish trust through reputation and validation
\n| Authors | \nMarco De Rossi (@MarcoMetaMask), Davide Crapis (@dcrapis) <davide@ethereum.org>, Jordan Ellis <jordanellis@google.com>, Erik Reppel <erik.reppel@coinbase.com> | \n
|---|---|
| Created | \n2025-08-13 | \n
| Discussion Link | \nhttps://ethereum-magicians.org/t/erc-8004-trustless-agents/25098 | \n
| Requires | \n\n\n EIP-155, \n\n EIP-712, \n\n EIP-721, \n\n EIP-1271\n\n | \n
\n\n \n\n
Table of Contents
\n- \n
- Abstract \n
- Motivation \n
- Specification\n \n \n
- Rationale \n
- Security Considerations \n
- Copyright \n
\n \n \n Abstract\n \n \n
\n\nThis protocol proposes to use blockchains to discover, choose, and interact with agents across organizational boundaries without pre-existing trust, thus enabling open-ended agent economies.
\n\nTrust models are pluggable and tiered, with security proportional to value at risk, from low-stake tasks like ordering pizza to high-stake tasks like medical diagnosis. Developers can choose from different trust models: reputation systems using client feedback, validation via stake-secured re-execution, zero-knowledge machine learning (zkML) proofs, or trusted execution environment (TEE) oracles.
\n \n\n \n \n Motivation\n \n \n
\n\nModel context protocol (MCP) allows servers to list and offer their capabilities (prompts, resources, tools, and completions), while Agent2Agent (A2A) handles agent authentication, skills advertisement via AgentCards, direct messaging, and complete task-lifecycle orchestration. However, these agent communication protocols don’t inherently cover agent discovery and trust.
\n\nTo foster an open, cross-organizational agent economy, we need mechanisms for discovering and trusting agents in untrusted settings. This ERC addresses this need through three lightweight registries, which can be deployed on any L2 or on Mainnet as per-chain singletons:
\n\nIdentity Registry - A minimal on-chain handle based on ERC-721 with URIStorage extension that resolves to an agent’s registration file, providing every agent with a portable, censorship-resistant identifier.
\n\nReputation Registry - A standard interface for posting and fetching feedback signals. Scoring and aggregation occur both on-chain (for composability) and off-chain (for sophisticated algorithms), enabling an ecosystem of specialized services for agent scoring, auditor networks, and insurance pools.
\n\nValidation Registry - Generic hooks for requesting and recording independent validators checks (e.g. stakers re-running the job, zkML verifiers, TEE oracles, trusted judges).
\n\nPayments are orthogonal to this protocol and not covered here. However, examples are provided showing how x402 payments can enrich feedback signals.
\n \n\n \n \n Specification\n \n \n
\n\nThe 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.
\n \n\n \n \n Identity Registry\n \n \n
\n\nThe Identity Registry uses ERC-721 with the URIStorage extension for agent registration, making all agents immediately browsable and transferable with NFTs-compliant apps. Each agent is uniquely identified globally by:
\n\n- \n
- agentRegistry: A colon-separated string
{namespace}:{chainId}:{identityRegistry}(e.g.,eip155:1:0x742...) where:\n- \n
- namespace: The chain family identifier (
eip155for EVM chains) \n - chainId: The blockchain network identifier \n
- identityRegistry: The address where the ERC-721 registry contract is deployed \n
\n - namespace: The chain family identifier (
- agentId: The ERC-721 tokenId assigned incrementally by the registry \n
Throughout this document, tokenId in ERC-721 is referred to as agentId and tokenURI in ERC-721 is referred to as agentURI. The owner of the ERC-721 token is the owner of the agent and can transfer ownership or delegate management (e.g., updating the registration file) to operators, as supported by ERC721URIStorage.
\n \n \n Agent URI and Agent Registration File\n \n \n
\n\nThe agentURI MUST resolve to the agent registration file. It MAY use any URI scheme such as ipfs:// (e.g., ipfs://cid), https:// (e.g., https://example.com/agent3.json), or a base64-encoded data: URI (e.g., data:application/json;base64,eyJ0eXBlIjoi...) for fully on-chain metadata. When the registration uri changes, it can be updated with setAgentURI().
The registration file MUST have the following structure:
\n\n{\n \"type\": \"https://eips.ethereum.org/EIPS/eip-8004#registration-v1\",\n \"name\": \"myAgentName\",\n \"description\": \"A natural language description of the Agent, which MAY include what it does, how it works, pricing, and interaction methods\",\n \"image\": \"https://example.com/agentimage.png\",\n \"services\": [\n {\n \"name\": \"web\",\n \"endpoint\": \"https://web.agentxyz.com/\"\n },\n {\n \"name\": \"A2A\",\n \"endpoint\": \"https://agent.example/.well-known/agent-card.json\",\n \"version\": \"0.3.0\"\n },\n {\n \"name\": \"MCP\",\n \"endpoint\": \"https://mcp.agent.eth/\",\n \"version\": \"2025-06-18\"\n },\n {\n \"name\": \"OASF\",\n \"endpoint\": \"ipfs://{cid}\",\n \"version\": \"0.8\", // https://github.com/agntcy/oasf/tree/v0.8.0\n \"skills\": [], // OPTIONAL\n \"domains\": [] // OPTIONAL\n },\n {\n \"name\": \"ENS\",\n \"endpoint\": \"vitalik.eth\",\n \"version\": \"v1\"\n },\n {\n \"name\": \"DID\",\n \"endpoint\": \"did:method:foobar\",\n \"version\": \"v1\"\n },\n {\n \"name\": \"email\",\n \"endpoint\": \"mail@myagent.com\"\n }\n ],\n \"x402Support\": false,\n \"active\": true,\n \"registrations\": [\n {\n \"agentId\": 22,\n \"agentRegistry\": \"{namespace}:{chainId}:{identityRegistry}\" // e.g. eip155:1:0x742...\n }\n ],\n \"supportedTrust\": [\n \"reputation\",\n \"crypto-economic\",\n \"tee-attestation\"\n ]\n}\nThe type, name, description, and image fields at the top SHOULD ensure compatibility with ERC-721 apps. The number and type of endpoints are fully customizable, allowing developers to add as many as they wish. The version field in endpoints is a SHOULD, not a MUST.
\n\nAgents MAY advertise their endpoints, which point to an A2A agent card, an MCP endpoint, an ENS agent name, DIDs, or the agent’s wallets on any chain (even chains where the agent is not registered).
\n \n\n \n \n Endpoint Domain Verification (Optional)\n \n \n
\n\nSince endpoints can point to domains not controlled by the agent owner, an agent MAY optionally prove control of an HTTPS endpoint-domain by publishing https://{endpoint-domain}/.well-known/agent-registration.json containing at least a registrations list (or the full agent registration file). Users MAY treat the endpoint-domain as verified if the file is reachable over HTTPS and includes a registrations entry whose agentRegistry and agentId match the on-chain agent; if the endpoint-domain is the same domain that serves the agent’s primary registration file referenced by agentURI, this additional check is not needed because domain control is already demonstrated there.
Agents SHOULD have at least one registration (multiple are possible), and all fields in the registration are mandatory.\nThe supportedTrust field is OPTIONAL. If absent or empty, this ERC is used only for discovery, not for trust.
\n \n\n \n \n On-chain metadata\n \n \n
\n\nThe registry extends ERC-721 by adding getMetadata(uint256 agentId, string metadataKey) and setMetadata(uint256 agentId, string metadataKey, bytes metadataValue) functions for optional extra on-chain agent metadata:
function getMetadata(uint256 agentId, string memory metadataKey) external view returns (bytes memory)\nfunction setMetadata(uint256 agentId, string memory metadataKey, bytes memory metadataValue) external\nWhen metadata is set, the following event is emitted:
\n\nevent MetadataSet(uint256 indexed agentId, string indexed indexedMetadataKey, string metadataKey, bytes metadataValue)\nThe key agentWallet is reserved and cannot be set via setMetadata() or during register() (including the metadata array overload). It represents the address where the agent receives payments and is initially set to the owner’s address. To change it, the agent owner must prove control of the new wallet by providing a valid EIP-712 signature for EOAs or ERC-1271 for smart contract wallets—by calling:
function setAgentWallet(uint256 agentId, address newWallet, uint256 deadline, bytes calldata signature) external\nTo read and clear the currently set wallet, the following functions are exposed:
\n\nfunction getAgentWallet(uint256 agentId) external view returns (address)\nfunction unsetAgentWallet(uint256 agentId) external\nWhen the agent is transferred, agentWallet is automatically cleared (effectively resetting it to the zero address) and must be re-verified by the new owner.
\n \n \n Registration\n \n \n
\n\nNew agents can be minted by calling one of these functions:
\n\nstruct MetadataEntry {\nstring metadataKey;\nbytes metadataValue;\n}\n\nfunction register(string agentURI, MetadataEntry[] calldata metadata) external returns (uint256 agentId)\n\nfunction register(string agentURI) external returns (uint256 agentId)\n\n// agentURI is added later with setAgentURI()\nfunction register() external returns (uint256 agentId)\nThis emits one Transfer event, one MetadataSet event for the reserved agentWallet key, one MetadataSet event for each additional metadata entry (if any), and
event Registered(uint256 indexed agentId, string agentURI, address indexed owner)\n\n \n \n Update agentURI\n \n \n
\n\nThe agentURI can be updated by calling the following function, which emits a URIUpdated event:
\n\n\nfunction setAgentURI(uint256 agentId, string calldata newURI) external\n\nevent URIUpdated(uint256 indexed agentId, string newURI, address indexed updatedBy)\n\nIf the owner wants to store the entire registration file on-chain, the agentURI SHOULD use a base64-encoded data URI rather than a serialized JSON string:
\n\ndata:application/json;base64,eyJ0eXBlIjoi...\n\n \n \n Reputation Registry\n \n \n
\n\nWhen the Reputation Registry is deployed, the identityRegistry address is set via initialize(address identityRegistry_) and publicly visible by calling:
function getIdentityRegistry() external view returns (address identityRegistry)\nThe feedback given by a clientAddress to an agent consists of a signed fixed-point value (int128) and its valueDecimals (uint8, 0-18), plus optional tag1 and tag2 (left to developers’ discretion to provide maximum on-chain composability and filtering), an endpoint URI, a file URI pointing to an off-chain JSON containing additional information, and its KECCAK-256 file hash to guarantee integrity. We suggest using IPFS or equivalent services to make feedback easily indexed by subgraphs or similar technologies. For IPFS URIs, the hash is not required.\nAll fields except value and valueDecimals are OPTIONAL, so the off-chain file is not required and can be omitted.
\n \n \n Giving Feedback\n \n \n
\n\nNew feedback can be added by any clientAddress calling:
\n\nfunction giveFeedback(uint256 agentId, int128 value, uint8 valueDecimals, string calldata tag1, string calldata tag2, string calldata endpoint, string calldata feedbackURI, bytes32 feedbackHash) external\nThe agentId must be a validly registered agent. The valueDecimals MUST be between 0 and 18. The feedback submitter MUST NOT be the agent owner or an approved operator for agentId. tag1, tag2, endpoint, feedbackURI, and feedbackHash are OPTIONAL.
\n\nWhere provided, feedbackHash is the KECCAK-256 hash (keccak256) of the content referenced by feedbackURI, enabling verifiable integrity for non-content-addressed URIs. For IPFS (or other content-addressed URIs), feedbackHash is OPTIONAL and can be omitted (e.g., set to bytes32(0)).
If the procedure succeeds, an event is emitted:
\n\nevent NewFeedback(uint256 indexed agentId, address indexed clientAddress, uint64 feedbackIndex, int128 value, uint8 valueDecimals, string indexed indexedTag1, string tag1, string tag2, string endpoint, string feedbackURI, bytes32 feedbackHash)\nThe feedback fields value, valueDecimals, tag1, tag2, and isRevoked are stored in the contract storage along with the feedbackIndex (a 1-indexed counter of feedback submissions that clientAddress has given to agentId). The fields endpoint, feedbackURI, and feedbackHash are emitted but are not stored. This exposes reputation signals to any smart contract, enabling on-chain composability.
\n\nWhen the feedback is given by an agent (i.e., the client is an agent), the agent SHOULD use the address set in the on-chain optional agentWallet metadata as the clientAddress, to facilitate reputation aggregation.
\n \n \n Examples of value / valueDecimals\n \n \n
\n\n| tag1 | \nWhat it measures | \nExample human value | \nvalue | \n valueDecimals | \n
|---|---|---|---|---|
starred | \n Quality rating (0-100) | \n87/100 | \n 87 | \n 0 | \n
reachable | \n Endpoint reachable (binary) | \ntrue | \n 1 | \n 0 | \n
ownerVerified | \n Endpoint owned by agent owner (binary) | \ntrue | \n 1 | \n 0 | \n
uptime | \n Endpoint uptime (%) | \n99.77% | \n 9977 | \n 2 | \n
successRate | \n Endpoint success rate (%) | \n89% | \n 89 | \n 0 | \n
responseTime | \n Response time (ms) | \n560ms | \n 560 | \n 0 | \n
blocktimeFreshness | \n Avg block delay (blocks) | \n4 blocks | \n 4 | \n 0 | \n
revenues | \n Cumulative revenues (e.g., USD) | \n$560 | \n 560 | \n 0 | \n
tradingYield (tag2 = day, week, month, year) | \n Yield | \n-3,2% | \n -32 | \n 1 | \n
\n \n \n Off-Chain Feedback File Structure\n \n \n
\n\nThe OPTIONAL file at the URI could look like:
\n\n{\n // MUST FIELDS\n \"agentRegistry\": \"eip155:1:{identityRegistry}\",\n \"agentId\": 22,\n \"clientAddress\": \"eip155:1:{clientAddress}\",\n \"createdAt\": \"2025-09-23T12:00:00Z\",\n \"value\": 100,\n \"valueDecimals\": 0,\n\n // ALL OPTIONAL FIELDS\n \"tag1\": \"foo\",\n \"tag2\": \"bar\",\n \"endpoint\": \"https://agent.example.com/GetPrice\",\n\n \"mcp\": { \"tool\": \"ToolName\" }, // or: { \"prompt\": \"PromptName\" } / { \"resource\": \"ResourceName\" }\n\n // A2A: see \"Context Identifier Semantics\" and Task model in the A2A specification.\n \"a2a\": {\n \"skills\": [\"as-defined-by-A2A\"], // e.g., AgentSkill identifiers\n \"contextId\": \"as-defined-by-A2A\",\n \"taskId\": \"as-defined-by-A2A\"\n },\n\n \"oasf\": {\n \"skills\": [\"as-defined-by-OASF\"],\n \"domains\": [\"as-defined-by-OASF\"]\n },\n \n \"proofOfPayment\": { // this can be used for x402 proof of payment\n\t \"fromAddress\": \"0x00...\",\n\t \"toAddress\": \"0x00...\",\n\t \"chainId\": \"1\",\n\t \"txHash\": \"0x00...\"\n },\n\n // Other fields\n \" ... \": { \" ... \" } // MAY\n}\n\n \n \n Revoking Feedback\n \n \n
\n\nclientAddress can revoke feedback by calling:
\n\nfunction revokeFeedback(uint256 agentId, uint64 feedbackIndex) external\nThis emits:
\n\nevent FeedbackRevoked(uint256 indexed agentId, address indexed clientAddress, uint64 indexed feedbackIndex)\n\n \n \n Appending Responses\n \n \n
\n\nAnyone (e.g., the agentId showing a refund, any off-chain data intelligence aggregator tagging feedback as spam) can call:
\n\nfunction appendResponse(uint256 agentId, address clientAddress, uint64 feedbackIndex, string calldata responseURI, bytes32 responseHash) external\nWhere responseHash is the KECCAK-256 file hash of the responseURI file content to guarantee integrity. This field is not required for IPFS URIs.
\n\nThis emits:
\n\nevent ResponseAppended(uint256 indexed agentId, address indexed clientAddress, uint64 feedbackIndex, address indexed responder, string responseURI, bytes32 responseHash)\n\n \n \n Read Functions\n \n \n
\n\nfunction getSummary(uint256 agentId, address[] calldata clientAddresses, string tag1, string tag2) external view returns (uint64 count, int128 summaryValue, uint8 summaryValueDecimals)\n// agentId and clientAddresses are mandatory; tag1 and tag2 are optional filters.\n// clientAddresses MUST be provided (non-empty); results without filtering by clientAddresses are subject to Sybil/spam attacks. See Security Considerations for details\n\nfunction readFeedback(uint256 agentId, address clientAddress, uint64 feedbackIndex) external view returns (int128 value, uint8 valueDecimals, string tag1, string tag2, bool isRevoked)\n\nfunction readAllFeedback(uint256 agentId, address[] calldata clientAddresses, string tag1, string tag2, bool includeRevoked) external view returns (address[] memory clients, uint64[] memory feedbackIndexes, int128[] memory values, uint8[] memory valueDecimals, string[] memory tag1s, string[] memory tag2s, bool[] memory revokedStatuses)\n// agentId is the only mandatory parameter; others are optional filters. Revoked feedback are omitted by default.\n\nfunction getResponseCount(uint256 agentId, address clientAddress, uint64 feedbackIndex, address[] responders) external view returns (uint64 count)\n// agentId is the only mandatory parameter; others are optional filters.\n\nfunction getClients(uint256 agentId) external view returns (address[] memory)\n\nfunction getLastIndex(uint256 agentId, address clientAddress) external view returns (uint64)\nWe expect reputation systems around reviewers/clientAddresses to emerge. While simple filtering by reviewer (useful to mitigate spam) and by tag are enabled on-chain, more complex reputation aggregation will happen off-chain.
\n \n\n \n \n Validation Registry\n \n \n
\n\nThis registry enables agents to request verification of their work and allows validator smart contracts to provide responses that can be tracked on-chain. Validator smart contracts could use, for example, stake-secured inference re-execution, zkML verifiers or TEE oracles to validate or reject requests.
\n\nWhen the Validation Registry is deployed, the identityRegistry address is set via initialize(address identityRegistry_) and is visible by calling getIdentityRegistry(), as described above.
\n \n \n Validation Request\n \n \n
\n\nAgents request validation by calling:
\n\nfunction validationRequest(address validatorAddress, uint256 agentId, string requestURI, bytes32 requestHash) external\nThis function MUST be called by the owner or operator of agentId. The requestURI points to off-chain data containing all information needed for the validator to validate, including inputs and outputs needed for the verification. The requestHash is a commitment to this data (keccak256 of the request payload) and identifies the request. All other fields are mandatory.
A ValidationRequest event is emitted:
\n\nevent ValidationRequest(address indexed validatorAddress, uint256 indexed agentId, string requestURI, bytes32 indexed requestHash)\n\n \n \n Validation Response\n \n \n
\n\nValidators respond by calling:
\n\nfunction validationResponse(bytes32 requestHash, uint8 response, string responseURI, bytes32 responseHash, string tag) external\nOnly requestHash and response are mandatory; responseURI, responseHash and tag are optional. This function MUST be called by the validatorAddress specified in the original request. The response is a value between 0 and 100, which can be used as binary (0 for failed, 100 for passed) or with intermediate values for validations with a spectrum of outcomes. The optional responseURI points to off-chain evidence or audit of the validation, responseHash is its commitment (in case the resource is not on IPFS), while tag allows for custom categorization or additional data.
\n\nvalidationResponse() can be called multiple times for the same requestHash, enabling use cases like progressive validation states (e.g., “soft finality” and “hard finality” using tag) or updates to validation status.
\n\nUpon successful execution, a ValidationResponse event is emitted with all function parameters:
\n\nevent ValidationResponse(address indexed validatorAddress, uint256 indexed agentId, bytes32 indexed requestHash, uint8 response, string responseURI, bytes32 responseHash, string tag)\nThe contract stores requestHash, validatorAddress, agentId, response, responseHash, lastUpdate, and tag for on-chain querying and composability.
\n \n\n \n \n Read Functions\n \n \n
\n\nfunction getValidationStatus(bytes32 requestHash) external view returns (address validatorAddress, uint256 agentId, uint8 response, bytes32 responseHash, string tag, uint256 lastUpdate)\n\n//Returns aggregated validation statistics for an agent. agentId is the only mandatory parameter; validatorAddresses and tag are optional filters\nfunction getSummary(uint256 agentId, address[] calldata validatorAddresses, string tag) external view returns (uint64 count, uint8 averageResponse)\n\nfunction getAgentValidations(uint256 agentId) external view returns (bytes32[] memory requestHashes)\n\nfunction getValidatorRequests(address validatorAddress) external view returns (bytes32[] memory requestHashes)\nIncentives and slashing related to validation are managed by the specific validation protocol and are outside the scope of this registry.
\n \n\n \n \n Rationale\n \n \n
\n\n- \n
- Agent communication protocols: MCP and A2A are popular, and other protocols could emerge. For this reason, this protocol links from the blockchain to a flexible registration file including a list where endpoints can be added at will, combining AI primitives (MCP, A2A) and Web3 primitives such as wallet addresses, DIDs, and ENS names. \n
- Feedback: The protocol combines the leverage of nomenclature already established by A2A (such as tasks and skills) and MCP (such as tools and prompts) with complete flexibility in the feedback signal structure. \n
- Gas Sponsorship: Since clients don’t need to be registered anymore, any application can implement frictionless feedback leveraging EIP-7702. \n
- Indexing: Since feedback data is saved on-chain and we suggest using IPFS for full data, it’s easy to leverage subgraphs to create indexers and improve UX. \n
- Deployment: We expect the registries to be deployed with singletons per chain. Note that an agent registered and receiving feedback on chain A can still operate and transact on other chains. Agents can also be registered on multiple chains if desired. \n
\n \n \n Security Considerations\n \n \n
\n\n- \n
- Sybil attacks are possible, inflating the reputation of fake agents. The protocol’s contribution is to make signals public and use the same schema. We expect many players to build reputation systems, for example, trusting or giving reputation to reviewers (and therefore filtering by reviewer, as the protocol already enables). \n
- On-chain pointers and hashes cannot be deleted, ensuring audit trail integrity \n
- Validator incentives and slashing are managed by specific validation protocols \n
- While this ERC cryptographically ensures the registration file corresponds to the on-chain agent, it cannot cryptographically guarantee that advertised capabilities are functional and non-malicious. The three trust models (reputation, validation, and TEE attestation) are designed to support this verification need \n
\n \n \n Copyright\n \n \n
\n\nCopyright and related rights waived via CC0.
\n\nCitation
\nPlease cite this document as:
\n \nMarco De Rossi (@MarcoMetaMask), Davide Crapis (@dcrapis) <davide@ethereum.org>, Jordan Ellis <jordanellis@google.com>, Erik Reppel <erik.reppel@coinbase.com>, \"ERC-8004: Trustless Agents [DRAFT],\" Ethereum Improvement Proposals, no. 8004, August 2025. Available: https://eips.ethereum.org/EIPS/eip-8004.
\n