ERC-8004 Trustless agents
Draft · Other · created 2025-08-13
A standard that registers AI agents on the blockchain so they can be discovered and selected across organizational boundaries. With three registries for identity, reputation, and validation, agents can be transacted with even without prior trust.
Why it is needed
Protocols for communication between AI agents, such as MCP (Model Context Protocol) and A2A (Agent2Agent), exist, but these protocols do not address how to discover agents or how far to trust them. To delegate work to an agent from an unfamiliar organization, a common mechanism is needed to verify who the agent is, whether it has performed well in the past, and whether its results are correct. Without such a mechanism, the agent economy remains confined to closed transactions among organizations that already know each other. This standard places three lightweight registries, for identity, reputation, and validation, on the blockchain so that agents can be discovered, selected, and interacted with even without prior trust. The trust method can be chosen and is designed to be tiered, applying security proportional to the value at stake, from low-risk tasks like ordering a pizza to high-risk tasks like medical diagnosis.
What to implement
function register(string agentURI, MetadataEntry[] calldata metadata) external returns (uint256 agentId): Mints a new agent by specifying both a registration file URI and additional on-chain metadata.function register(string agentURI) external returns (uint256 agentId): Mints a new agent by specifying only a registration file URI.function register() external returns (uint256 agentId): Mints an agent first without a URI, then adds the agentURI later via setAgentURI().event Registered(uint256 indexed agentId, string agentURI, address indexed owner): An event emitted when agent registration is completed.function setAgentURI(uint256 agentId, string calldata newURI) external: Updates the agentURI pointing to the agent's registration file.event URIUpdated(uint256 indexed agentId, string newURI, address indexed updatedBy): An event emitted when the agentURI is updated.function getMetadata(uint256 agentId, string memory metadataKey) external view returns (bytes memory): Queries an agent's on-chain metadata by key.function setMetadata(uint256 agentId, string memory metadataKey, bytes memory metadataValue) external: Stores an agent's on-chain metadata as a key-value pair.event MetadataSet(uint256 indexed agentId, string indexed indexedMetadataKey, string metadataKey, bytes metadataValue): An event emitted when metadata is set.function setAgentWallet(uint256 agentId, address newWallet, uint256 deadline, bytes calldata signature) external: Changes the payout agentWallet by proving ownership with the new wallet's signature (EIP-712 for EOAs, ERC-1271 for contract wallets).function getAgentWallet(uint256 agentId) external view returns (address): Queries the currently configured agentWallet address.function unsetAgentWallet(uint256 agentId) external: Clears the configured agentWallet.function getIdentityRegistry() external view returns (address identityRegistry): Queries the address of the identity registry linked to the reputation and validation registries.function giveFeedback(uint256 agentId, int128 value, uint8 valueDecimals, string calldata tag1, string calldata tag2, string calldata endpoint, string calldata feedbackURI, bytes32 feedbackHash) external: An arbitrary client address leaves feedback for an agent with a fixed-point value, an optional tag, and a file URI.event 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): An event emitted when new feedback is registered.function revokeFeedback(uint256 agentId, uint64 feedbackIndex) external: The client that left the feedback withdraws their own feedback.event FeedbackRevoked(uint256 indexed agentId, address indexed clientAddress, uint64 indexed feedbackIndex): An event emitted when feedback is withdrawn.function appendResponse(uint256 agentId, address clientAddress, uint64 feedbackIndex, string calldata responseURI, bytes32 responseHash) external: Anyone can attach a response to a specific piece of feedback (e.g., proof of refund, marking as spam).event ResponseAppended(uint256 indexed agentId, address indexed clientAddress, uint64 feedbackIndex, address indexed responder, string responseURI, bytes32 responseHash): An event emitted when a response is attached to feedback.function getSummary(uint256 agentId, address[] calldata clientAddresses, string tag1, string tag2) external view returns (uint64 count, int128 summaryValue, uint8 summaryValueDecimals): Aggregates the feedback count and summary value, filtered by a specified list of clients and tags. clientAddresses cannot be left empty.function readFeedback(uint256 agentId, address clientAddress, uint64 feedbackIndex) external view returns (int128 value, uint8 valueDecimals, string tag1, string tag2, bool isRevoked): Reads one specific piece of feedback left by a specific client.function 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): Reads all feedback matching the filter conditions as an array. Withdrawn feedback is excluded by default.function getResponseCount(uint256 agentId, address clientAddress, uint64 feedbackIndex, address[] responders) external view returns (uint64 count): Queries the number of responses appended to feedback. Arguments other than agentId are optional filters.function getClients(uint256 agentId) external view returns (address[] memory): Queries the list of client addresses that left feedback for the given agent.function getLastIndex(uint256 agentId, address clientAddress) external view returns (uint64): Queries the last feedback index left by a specific client for the given agent.function validationRequest(address validatorAddress, uint256 agentId, string requestURI, bytes32 requestHash) external: The agent owner or operator requests task validation from a designated validator.event ValidationRequest(address indexed validatorAddress, uint256 indexed agentId, string requestURI, bytes32 indexed requestHash): Event emitted when a validation request is registered.function validationResponse(bytes32 requestHash, uint8 response, string responseURI, bytes32 responseHash, string tag) external: The validator designated in the request records a validation result with a score from 0 to 100. This can be called multiple times for the same request.event ValidationResponse(address indexed validatorAddress, uint256 indexed agentId, bytes32 indexed requestHash, uint8 response, string responseURI, bytes32 responseHash, string tag): Event emitted when a validation response is recorded.function getValidationStatus(bytes32 requestHash) external view returns (address validatorAddress, uint256 agentId, uint8 response, bytes32 responseHash, string tag, uint256 lastUpdate): Queries the current status of a specific validation request.function getSummary(uint256 agentId, address[] calldata validatorAddresses, string tag) external view returns (uint64 count, uint8 averageResponse): Aggregates an agent's validation statistics (count and average score). The validator list and tags are optional filters.function getAgentValidations(uint256 agentId) external view returns (bytes32[] memory requestHashes): Queries the list of validation request hashes for an agent.function getValidatorRequests(address validatorAddress) external view returns (bytes32[] memory requestHashes): Queries the list of validation request hashes sent to a specific validator.
In depth
Identity Registry: ERC-721-based agent identity
The Identity Registry extends ERC-721 with the URIStorage extension to register agents. The original text calls ERC-721's tokenId the agentId and tokenURI the agentURI. An agent's global identifier is the combination of the agentRegistry string {namespace}:{chainId}:{identityRegistry} (e.g. eip155:1:0x742...) and the agentId, which the registry assigns incrementally. The token owner is the agent's owner and can transfer ownership or delegate management such as updating the registration file to an operator. register() has three overloads, and registration emits one Transfer event, one MetadataSet event for the reserved key agentWallet, a MetadataSet event for each additional metadata entry, and a Registered event. Because it is ERC-721-based, all agents can be queried and transferred directly in NFT-compatible apps.
Registration file structure and domain verification
agentURI must link to a registration file, and any URI scheme can be used, including ipfs://, https://, and base64-encoded data: URIs. The type, name, description, and image fields at the top of the file exist for compatibility with ERC-721 apps. The services list can include as many endpoints as desired, such as web, A2A agent cards, MCP endpoints, OASF, ENS names, DIDs, and email, and the version field is a recommendation. registrations contains the agentId and agentRegistry, and all fields in a registration entry are required. supportedTrust is optional; if it is absent or empty, this standard is used only for discovery, not trust. Since an endpoint may point to a domain not owned by the agent owner, domain control can be proven by posting a registrations entry matching the on-chain agent at that domain's /.well-known/agent-registration.json.
On-chain metadata and agentWallet
The registry supports optional on-chain metadata via getMetadata(uint256 agentId, string metadataKey) and setMetadata(uint256 agentId, string metadataKey, bytes metadataValue). The key agentWallet is reserved and cannot be set via setMetadata() or the metadata array in register(). This key represents the address where the agent receives payment, and it is initially set to the owner's address. To change it, call setAgentWallet(agentId, newWallet, deadline, signature), proving control with a valid signature for the new wallet (EIP-712 for EOAs, ERC-1271 for contract wallets). When an agent is transferred, agentWallet is automatically cleared, effectively resetting it to the zero address, and the new owner must verify it again.
Reputation Registry: writing feedback
Any clientAddress can leave feedback via giveFeedback(). Values are expressed as a signed fixed-point value (int128) and valueDecimals (uint8, 0 to 18); for example, 99.77% uptime is written as value 9977 with valueDecimals 2. The submitter must not be the owner or an approved operator of the given agentId. tag1, tag2, endpoint, feedbackURI, and feedbackHash are optional, and feedbackHash is the KECCAK-256 hash of the content pointed to by feedbackURI, ensuring integrity. The hash can be omitted if the URI is content-addressed, as with IPFS. The contract stores value, valueDecimals, tag1, tag2, and isRevoked together with a per-client feedbackIndex starting at 1; endpoint, feedbackURI, and feedbackHash are only emitted in events and are not stored. Feedback can be revoked with revokeFeedback(), and anyone can append a response, such as proof of a refund or a spam flag, with appendResponse().
Division of roles between reading and aggregating reputation
getSummary() requires both agentId and clientAddresses, and clientAddresses cannot be left empty, because aggregated results not filtered by client are exposed to Sybil and spam attacks. readAllFeedback() requires only agentId; the rest are optional filters, and revoked feedback is excluded by default. getClients() and getLastIndex() can be used to query the list of addresses that left feedback and the last index. The original text explains that simple filtering by reviewer and tag is supported on-chain, but more complex reputation aggregation is expected to happen off-chain. If the party leaving feedback is itself an agent, it is recommended to use the address set in the on-chain agentWallet metadata as the clientAddress, to make reputation aggregation easier.
Validation Registry: requests and responses
An agent's owner or operator requests validation via validationRequest(). requestURI points to off-chain data containing all the inputs and outputs needed for validation, and requestHash is the keccak256 commitment to that data and also serves as the request's identifier. Only the validatorAddress designated in the request can leave a response via validationResponse(). response is a value from 0 to 100, which can be used as a binary verdict where 0 is fail and 100 is pass, or as an intermediate value to express a spectrum of verdicts. The same requestHash can receive multiple responses, allowing staged validation states such as soft finality and hard finality, or status updates, using tags. The contract stores requestHash, validatorAddress, agentId, response, responseHash, lastUpdate, and tag, enabling on-chain querying and composition. Validators can use mechanisms such as stake-backed re-execution, zkML verifiers, TEE oracles, or trusted arbiters, and rewards and slashing are left to the individual validation protocol.
Design rationale, deployment approach, and proposal status
According to the original Rationale section, this standard anticipates that communication protocols beyond MCP and A2A may emerge, so it adopts a structure where a flexible registration file is linked from the blockchain, to which endpoints can be freely added. Since clients do not need to register, EIP-7702 can be used to implement frictionless feedback, and because feedback is recorded on-chain and the full data is recommended to live on IPFS, building a subgraph indexer is straightforward. The registry is expected to be deployed as a singleton per chain; an agent registered on one chain may be active on another, and it may also be registered redundantly on multiple chains. Payment is a separate matter from this protocol and is not covered by the standard. This proposal is still in Draft status, so its content may change.
Things to watch out for
- Possibility of Sybil attacks: Sybil attacks that inflate a fake agent's reputation are possible. The original text states that this protocol's contribution is to expose signals and have everyone use the same schema, and it expects multiple reputation systems to emerge that treat reviewers as the basis of trust and filter by reviewer.
- On-chain records cannot be deleted: Pointers and hashes posted on-chain cannot be deleted, which ensures the integrity of the audit trail.
- Validator rewards and slashing are out of scope: Rewards and slashing for validators are managed by individual validation protocols and are not within the scope of this standard.
- Does not guarantee that the functionality actually works: This standard cryptographically guarantees that the registration file corresponds to the on-chain agent, but it cannot guarantee that the advertised functionality actually works or is not malicious. Three trust models, reputation, validation, and TEE attestation, are designed to support this need for verification.