ERC-8174: Intent spec for contracts

collinsadi · March 1, 2026, 4:31pm

Add ERC: Agent-Readable Smart Contract Documentation Layer (Intent Spec)

master ← collinsadi:erc-intent-spec

opened 03:23PM - 21 Feb 26 UTC

This PR introduces a draft ERC defining a standardized, machine-readable semanti…c metadata layer for smart contracts. The proposal specifies: - An ERC-165 discoverable interface (`IIntentSpec`) exposing a metadata URI. - A canonical JSON schema defining contract-level and function-level semantic intent. - Normative requirements for metadata resolution and schema compliance. The goal is to provide a structured documentation layer enabling automated systems to reason about contract behavior prior to execution. This ERC is complementary to ERC-8004. While ERC-8004 standardizes identity, reputation, and validation primitives for autonomous agents, this proposal standardizes semantic intent disclosure at the contract level. Discussion thread: To be opened on Ethereum Magicians.

I’ve recently proposed ERC-8174, which defines a standard for attaching machine-readable semantic manifests to smart contracts. While the ABI tells us how to call a function, it doesn’t tell an autonomous agent what the economic consequences or safety risks are. This ERC introduces IIntentSpec to bridge that gap.

Abstract

This proposal specifies:

An ERC-165 interface (IIntentSpec) that exposes a metadata URI.
A canonical JSON schema that describes contract-level and function-level semantic intent, preconditions, and risks.

The goal is to move beyond human-readable NatSpec and provide a structured layer that LLMs and autonomous agents can use to reason about contract behavior before execution.

Motivation: Why do we need this?

Current automated agents (AI/Autonomous Agents) have to “guess” intent based on function names or by parsing messy NatSpec comments. This leads to:

Ambiguity: Is swap() a simple trade or a complex multi-hop?
Risk: Agents cannot programmatically “know” if a function has irreversible effects without deep simulation.
Compatibility: This ERC is designed to be the semantic counterpart to ERC-8004 (Agent Identity). While 8004 handles who the agent is, 8174 handles what the agent is interacting with.

Key Features

Off-chain Metadata: To save gas, the manifest lives on IPFS/Arweave, pointed to by getIntentSpecURI().
Standardized Schema: Includes fields like intent, preconditions, effects, and risks.
NatSpec Friendly: I suggest custom tags (e.g., @custom:agent-intent) so developers can generate these JSON manifests automatically during the build process.

Discussion Points for the Community

I would love to get the community’s thoughts on a few specific areas:

The Schema: Is the current JSON schema too heavy, or are we missing critical fields that an agent would need?
On-chain vs. Off-chain: Is a URI pointer the best approach, or should we consider a registry-based approach for non-upgradeable contracts?
Security: How can we better protect agents from “Semantic Lying” (where the manifest claims one thing, but the code does another)?
Integration: How can we best align this with existing developer workflows (Hardhat/Foundry plugins)?