Two Ways to Point to Agent Metadata — and Neither Is Complete
Every AI agent registered under ERC-8004 needs a way to say “here’s my metadata.” That metadata — the JSON file describing the agent’s name, capabilities, service endpoints, and trust model — lives on IPFS. The question is how you point to it.
Two approaches have emerged, and the trade-offs between them define one of the most consequential infrastructure decisions in the AI agent ecosystem.
On-chain CID storage records the raw IPFS content identifier directly in the smart contract. Every time the metadata changes, the agent owner uploads new JSON to IPFS, gets a new CID, and calls setAgentURI() to update the on-chain pointer. Every update is an Ethereum transaction. Every transaction emits a URIUpdated event. Every event is permanently recorded, creating an immutable audit trail of every metadata version the agent has ever published.
IPNS (InterPlanetary Name System) takes the opposite approach. Instead of recording the CID on-chain, you register with an ipns:// URI that stays constant. The IPNS name is the hash of a public key. The key holder signs records pointing to the current CID and publishes them to the IPFS DHT or via libp2p PubSub. Updates happen off-chain. No gas fees. No transactions. The on-chain pointer never changes.
A February 2026 Filebase article made the case for IPNS explicitly: register agents with ipns:// URIs instead of raw CIDs and update metadata at zero gas cost. The scenario is compelling — swap from Llama-2 to Llama-3 instantly, manage fleets of 1,000 DAO worker agents pointing to one IPNS key, iterate on capability declarations without paying Ethereum gas every time.
ERC-8004 accommodates both. The spec accepts any URI scheme — ipfs://, ipns://, https://, or data: URIs. The choice is left to the registrant.
The Audit Trail Problem
This is where the trade-off gets sharp.
On-chain CID storage creates a version history by default. Every setAgentURI() call emits an event. Indexing services like The Graph Protocol can reconstruct the complete sequence of CIDs an agent has published. Anyone querying the agent’s history can see: this agent pointed to CID-A from January to March, switched to CID-B in March, updated to CID-C in April. The timeline is public, permanent, and independently verifiable.
IPNS erases this trail. An IPNS name only points to the current CID. There is no built-in version history. When the key holder updates the pointer, the previous target disappears from the protocol’s perspective. IPNS records propagate via the DHT with a default TTL and expire after roughly 24 hours if not re-published. Once an IPNS record is overwritten, the old CID it pointed to is gone unless someone independently pinned it or recorded it elsewhere.
For AI agent identity, this matters enormously. The entire premise of on-chain reputation is that history is verifiable. An agent that has been operating for six months with stable metadata and consistent behavior is fundamentally different from an agent registered yesterday — but only if you can prove the history. IPNS makes metadata updates invisible, which means metadata history becomes unverifiable at the protocol level.
There’s an open proposal on GitHub (ipfs/specs #191) to add a previous field to IPNS records, which would create a linked chain of updates — essentially turning IPNS into a migration log. But this isn’t implemented yet. Today, IPNS is a pointer with no memory.
The Gas Cost Reality
The argument for IPNS is almost entirely economic.
Calling setAgentURI() on Ethereum mainnet costs gas. For a single agent updating metadata occasionally, this is negligible. For a fleet of agents updating frequently — rotating model versions, adding new A2A skills, refreshing MCP tool declarations — the costs compound. A DAO operating 1,000 agents that each update metadata weekly would pay for 52,000 on-chain transactions per year.
L2 chains reduce this dramatically. Base (Coinbase’s L2) and Optimism offer transaction costs orders of magnitude cheaper than mainnet while inheriting Ethereum’s security guarantees. The ERC-8004 Identity Registry is deployed on mainnet, but nothing prevents L2 deployments, and projects like Pinata’s IPCM (InterPlanetary CID Mapping) are already deployed on Base specifically to make CID updates affordable.
IPCM formalizes the on-chain CID registry pattern with a minimal contract: updateMapping() and getMapping() functions, plus MappingUpdated events that serve as a complete version history. It also integrates with ENS through a custom hybrid resolver bridging Base to mainnet — giving you human-readable names, on-chain CID history, and L2 gas costs.
The common optimization path is ENS → IPNS → CID, which avoids gas costs on every update by keeping the on-chain ENS record pointing to an IPNS name while the IPNS name rotates CIDs off-chain. This is elegant but inherits the audit trail problem: the ENS record’s ContenthashChanged events only log when the IPNS pointer itself changes, not when the underlying CID updates.
Content Integrity: The Subtle Difference
There’s a deeper technical distinction that gets overlooked in the IPNS-vs-CID debate.
An ipfs:// CID is content-addressed. The hash is the content. If you resolve the CID and get a file, you can independently verify that the file matches the hash. This is a cryptographic guarantee: nobody can serve you a different file under the same CID.
An ipns:// name is key-addressed. The name is derived from a public key. The key holder can point it at any CID at any time. If you resolve the IPNS name and get a file, you know the file was endorsed by the key holder — but you don’t know if it’s the same file that was there yesterday, or last week, or when the agent was first registered.
For agent metadata, this means on-chain CID storage lets anyone reconstruct exactly what an agent claimed about itself at any point in time. IPNS only lets you see what it claims right now. If an agent declared MCP support last month and quietly removed it, on-chain CID history exposes that change. IPNS hides it.
This distinction becomes critical when agents interact with each other. Google’s A2A protocol expects agents to discover each other’s capabilities via Agent Cards. Anthropic’s MCP discovers capabilities through runtime handshakes. Both protocols assume the declared capabilities are current and accurate. Neither protocol has a mechanism to detect that an agent’s capability declarations have changed since the last interaction — and with IPNS, there’s no external record that they did.
Ceramic, OrbitDB, and the Third Path
The IPNS-vs-CID binary isn’t the only option. Two other approaches offer different trade-off profiles.
Ceramic Network provides the most complete mutable-data-on-IPFS solution. Every Ceramic document gets a permanent StreamID that never changes regardless of content updates. Under the hood, streams are append-only logs of signed IPLD commits, periodically anchored to Ethereum via Merkle trees. You get a stable identifier, a full tamper-proof audit trail of every change, and no per-update gas costs for the stream itself. The anchoring transactions batch many updates into single Merkle roots, amortizing costs across the network.
Ceramic’s architecture is arguably the closest existing precedent to what AI agent metadata actually needs: a stable pointer, a verifiable version history, and affordable updates. The trade-off is infrastructure dependency — you’re adding Ceramic’s node network to your stack, and adoption among AI agent builders is still early.
OrbitDB uses Merkle-CRDTs for conflict-free peer-to-peer databases on IPFS. Each database has a stable address with an append-only operation log. It’s designed for collaborative, multi-writer scenarios — potentially useful for agents that have multiple operators or that participate in multi-agent coordination where several parties need to update shared state.
A more radical proposal comes from DIAP (Decentralized Interstellar Agent Protocol), published on arXiv in November 2025. DIAP binds identity to an immutable CID permanently and uses zero-knowledge proofs to dynamically prove ownership. Instead of migrating CIDs when metadata changes, the agent’s DID Document CID becomes a permanent identifier. Key rotation and ownership changes are proven via ZKP without ever updating the CID. This sidesteps the entire versioning problem by making the CID permanent and decoupling ownership proof from content state.
The Migration Attestation Approach
There’s a way to get the benefits of on-chain CID history without paying mainnet gas for every update — and without losing the audit trail that IPNS sacrifices.
Ethereum Attestation Service (EAS) supports attestation schemas with reference UIDs. Each attestation can explicitly reference a previous one, forming a chain. A CID migration schema could encode the previous CID, the new CID, the agent’s token ID, and the reason for the update. Each migration creates a new attestation referencing the last via refUID.
The result is a verifiable, on-chain chain of custody for agent metadata — separate from the Identity Registry’s tokenURI updates, cheaper on L2s like Base where EAS is natively deployed, and queryable by anyone who wants to trace an agent’s metadata history.
This pairs naturally with IPNS. An agent registers with an ipns:// URI for gas-free metadata updates. Separately, each meaningful metadata change gets recorded as an EAS migration attestation on Base, linking the old CID to the new CID with a timestamp and optional context. You get the economic efficiency of IPNS and the verifiable history of on-chain storage — at the cost of maintaining two parallel systems.
ERC-4906 (Metadata Update Extension) provides the notification layer — MetadataUpdate(tokenId) events signal indexers to re-fetch metadata — but records neither old nor new CIDs. It tells you that something changed, not what changed. Migration attestations fill this gap.
What This Means for the Agent Ecosystem
The IPNS-vs-CID question isn’t academic. It determines whether the ERC-8004 registry becomes a verifiable history of agent identity or an opaque pointer system where the past is invisible.
For agents that rarely update metadata, on-chain CID storage — especially on L2s — is straightforward and creates a complete audit trail by default. For agents that update frequently, IPNS is economically necessary but creates a verification gap that needs to be filled by a separate history layer.
The 104,000+ agents currently registered on ERC-8004 made this choice at registration time, and most chose the default: raw ipfs:// CIDs stored on-chain. That’s actually the better outcome for the ecosystem’s long-term trust infrastructure, even though it costs more per update. Every one of those CID changes is permanently recorded. Every version is recoverable. The history exists.
The question is whether anyone is reading it. A registry with 104,000 entries and a complete on-chain version history is only valuable if someone resolves the CIDs, checks what’s inside, and surfaces the patterns. Otherwise the audit trail exists but nobody’s auditing.
That’s the infrastructure gap — not which storage method wins, but whether anyone builds the layer that makes either method’s data legible and useful.
RNWY resolves every ERC-8004 CID and surfaces the metadata, version history, and behavioral data behind each registration. Explore any agent’s full history at rnwy.com/explorer.