--- eip: 8174 title: Intent spec for contracts description: A machine-verifiable semantic metadata to enable autonomous agent reasoning author: Collins Adi (@collinsadi) discussions-to: https://ethereum-magicians.org/t/erc-8174-intent-spec-for-contracts/27869 status: Draft type: Standards Track category: ERC created: 2026-02-11 requires: 165 --- ## Abstract This proposal defines a standard for attaching machine-readable semantic manifests to Ethereum smart contracts. It specifies: 1. An [ERC-165](./eip-165.md) discoverable interface (`IIntentSpec`) exposing a metadata URI. 2. A canonical JSON schema describing contract-level and function-level semantic intent. While the Application Binary Interface (ABI) defines how to call a function, it does not define the semantic intent, preconditions, or economic risks associated with execution. This ERC introduces a structured metadata layer to enable automated systems to reason about contract behavior prior to execution. ## Motivation This ERC is complementary to [ERC-8004](./eip-8004.md). [ERC-8004](./eip-8004.md) defines infrastructure primitives for autonomous agents, including identity, reputation, and validation mechanisms. It standardizes how agents establish identity and trust. This ERC defines a structured semantic documentation layer for smart contracts. It standardizes how contract behavior is described and interpreted prior to execution. Together, these standards address complementary layers of autonomous agent interaction. Smart contracts are primarily documented for human auditors. Automated agents interacting with contracts must infer intent from naming conventions or sparse NatSpec comments, which may be ambiguous or incomplete. The ABI provides function signatures and parameter types but does not express: - Economic intent - Safety preconditions - Irreversible effects - Risk disclosures This proposal defines a standardized documentation layer enabling structured semantic disclosure at the contract level. ## Specification The key words MUST, MUST NOT, REQUIRED, SHALL, SHALL NOT, SHOULD, SHOULD NOT, RECOMMENDED, MAY, and OPTIONAL in this document are to be interpreted as described in RFC 2119. ### Interface Detection Contracts implementing this standard MUST support [ERC-165](./eip-165.md) interface detection as defined in [ERC-165](./eip-165.md). ### `IIntentSpec` Interface Contracts MUST expose a metadata pointer through the following interface: ```solidity pragma solidity ^0.8.0; /// @title IIntentSpec /// @notice Interface for contracts that expose their Intent Spec metadata URI. interface IIntentSpec { /// @notice Emitted when the Intent Spec metadata URI changes. /// @param uri The new URI pointing to the manifest. event IntentSpecURIUpdated(string uri); /// @notice Returns the URI where the Intent Spec JSON is stored. /// @return A URI (e.g. ipfs://... or https://...) pointing to the manifest. function intentSpecURI() external view returns (string memory); } ``` ### Metadata Resolution * The returned URI MUST resolve to a JSON document conforming to the canonical schema defined below. * The URI SHOULD reference immutable content (e.g., content-addressed storage). * Once deployed, the manifest SHOULD NOT change. * If the URI changes, the contract MUST emit `IntentSpecURIUpdated` with the new URI. * Agents MUST verify content-addressed URIs where applicable. ### Agent Verification A manifest is self-declared by the contract author and MAY be inaccurate. Agents that rely on a manifest: * SHOULD independently verify the described behavior against the contract bytecode, execution simulations, and third-party attestations. * SHOULD simulate execution and compare the observed state transitions with the declared `effects`. ### Canonical Manifest Schema The resource returned by `intentSpecURI()` MUST conform to the following JSON Schema (Draft 2020-12): ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "title": "IntentSpec", "type": "object", "required": ["schemaVersion", "contract", "functions"], "properties": { "schemaVersion": { "type": "string", "description": "Semantic version of the IntentSpec schema (e.g. 1.0.0)" }, "contract": { "type": "object", "required": ["name"], "properties": { "name": { "type": "string" }, "version": { "type": "string" }, "description": { "type": "string" } } }, "functions": { "type": "array", "items": { "type": "object", "required": ["name", "intent"], "properties": { "name": { "type": "string" }, "selector": { "type": "string", "description": "EVM function selector in hexadecimal (0x + 8 hex chars)" }, "signature": { "type": "string", "description": "Canonical Solidity function signature (e.g. transfer(address,uint256))" }, "intent": { "type": "string" }, "preconditions": { "type": "array", "items": { "type": "string" } }, "effects": { "type": "array", "items": { "type": "string" } }, "risks": { "type": "array", "items": { "type": "string" } }, "agentGuidance": { "type": "string" } } } }, "events": { "type": "array", "items": { "type": "object", "required": ["name"], "properties": { "name": { "type": "string" }, "description": { "type": "string" } } } }, "invariants": { "type": "array", "items": { "type": "string" } } } } ``` #### Schema Requirements * `schemaVersion`, `contract`, and `functions` are REQUIRED. * Each function entry MUST include: * `name` * `intent` * `selector` and `signature` are OPTIONAL but RECOMMENDED. * Agents MAY ignore unknown fields for forward compatibility. ### NatSpec Integration (Non-Normative) This ERC does not modify the Solidity compiler or NatSpec standard. Developers MAY use custom NatSpec tags to generate manifests via external tooling. Suggested tags include: | Level | Tag | Purpose | | -------- | ---------------------------- | ------------------------- | | Contract | `@custom:agent-version` | Contract version | | Contract | `@custom:agent-description` | Short description | | Contract | `@custom:agent-invariant` | Invariant (repeatable) | | Contract | `@custom:agent-event` | Event name + description | | Function | `@custom:agent-intent` | One-line intent | | Function | `@custom:agent-precondition` | Precondition (repeatable) | | Function | `@custom:agent-effect` | Effect (repeatable) | | Function | `@custom:agent-risk` | Risk (repeatable) | | Function | `@custom:agent-guidance` | Guidance | Tooling MAY extract these tags at build time to emit schema-conformant JSON. ## Rationale ### Structured JSON Schema A standardized schema enables deterministic parsing of contract metadata. Required fields provide minimal semantic guarantees while allowing optional enrichment. ### Off-Chain Metadata Storing semantic documentation on-chain is cost prohibitive. A URI pointer reduces gas overhead while allowing immutable documentation through content-addressed storage. ### Single Discovery Entry Point `intentSpecURI()` provides a consistent discovery mechanism for metadata retrieval. ## Backwards Compatibility This proposal is fully backwards compatible. Existing contracts MAY support this standard through: * Proxy upgrades * Wrapper contracts * Metadata registries Contracts not implementing this interface are treated as lacking semantic metadata. ## Security Considerations ### Metadata Misrepresentation Manifest content is self-declared and can misrepresent contract behavior, whether by mistake or intent. An agent that trusts a manifest without checking it against the contract can be led into unsafe actions. The Agent Verification requirements in the Specification limit this exposure by cross-checking the manifest against bytecode, execution simulations, and third-party attestations. ### Simulation Verification Declared `effects` describe expected state transitions but are not enforced on-chain. Comparing simulated execution against the declared `effects`, as required in the Specification, lets an agent detect divergence before submitting a transaction. ### Metadata Integrity A manifest referenced by a mutable URI can be swapped after review. Content-addressed storage, together with the content-addressed URI verification required in the Specification, ties the manifest to a fixed hash and prevents undetected tampering. ## Copyright Copyright and related rights waived via [CC0](../LICENSE.md).