@cellar-door/erc-8004

𓉸 @cellar-door/erc-8004

EXIT Protocol adapter for ERC-8004 Trustless Agents — link departure records to on-chain agent identities and reputation registries.

𓉸 Passage Protocol · exit-door · entry-door · mcp · langchain · vercel · eliza · eas · erc-8004 · sign · python

⚠️ Pre-release software — no formal security audit has been conducted. Report vulnerabilities to [e-mail].

Install

npm install @cellar-door/erc-8004 ethers

Usage

import { resolveAgent, registerDeparture, queryDepartures } from '@cellar-door/erc-8004';
import { JsonRpcProvider, Wallet } from 'ethers';

const provider = new JsonRpcProvider('https://mainnet.base.org');

// Resolve an agent's on-chain identity
const agent = await resolveAgent(1n, { provider, chain: 'base' });
// → { agentId: 1n, owner: '0x...', agentURI: '...', did: 'did:pkh:eip155:8453:0x...' }

// Register an EXIT departure as a reputation signal
const signer = new Wallet(privateKey, provider);
const result = await registerDeparture(exitMarker, {
  signer,
  agentId: 1n,
  chain: 'base',
  markerUri: 'ipfs://bafybeig...',
});
// → { txHash: '0x...', blockNumber: 12345, feedbackIndex: 0n }

// Query an agent's departure history
const departures = await queryDepartures(1n, { provider, chain: 'base' });
// → [{ origin, exitType, timestamp, feedbackURI, feedbackHash, txHash }]

API

resolveAgent(agentId, options)

Query the IdentityRegistry for an agent's owner, URI, and DID.

Parameter	Type	Description
agentId	bigint | number	Agent token ID
options.provider	Provider	ethers v6 provider
options.chain	ChainName?	Chain name (auto-detected if omitted)

registerDeparture(marker, options)

Register an EXIT marker as a reputation signal via giveFeedback().

Parameter	Type	Description
marker	ExitMarkerLike	EXIT departure marker
options.signer	Signer	ethers v6 signer
options.agentId	bigint | number	Target agent ID
options.chain	ChainName?	Chain name (auto-detected if omitted)
options.markerUri	string?	URI to full marker (IPFS, HTTP)

queryDepartures(agentId, options)

Query NewFeedback events filtered by tag1="departure".

Parameter	Type	Description
agentId	bigint | number	Agent token ID
options.provider	Provider	ethers v6 provider
options.chain	ChainName?	Chain name (auto-detected if omitted)

Contract Addresses

Deterministic across all chains (CREATE2):

Network	IdentityRegistry	ReputationRegistry
Mainnet	0x8004A169FB4a3325136EB29fA0ceB6D2e539a432	0x8004BAa17C55a88189AE136b182e5fdA19dE9b63
Testnet	0x8004A818BFB912233c491871b3d84c89A494BD9e	0x8004B663056A597Dffe9eCcC1965A193B7388713

Supported chains: Ethereum, Base, Arbitrum, Optimism, Avalanche, BSC, Celo, Gnosis, Abstract, GOAT, Sepolia, Base Sepolia, Arbitrum Sepolia.

Feedback Signal Format

Departures are encoded as ReputationRegistry feedback:

giveFeedback(agentId, 0, 0, "departure", origin, "", markerUri, markerHash)

• value=0 — neutral signal (departure is informational, not positive/negative)
• tag1="departure" — indexed for efficient querying
• tag2=origin — the platform the agent departed from
• feedbackURI — pointer to full EXIT marker
• feedbackHash — keccak256 commitment of marker content

Security Considerations

Permissionless Feedback

ERC-8004's ReputationRegistry allows anyone to post feedback for any agent. This means fake departure records can be created at low cost (fractions of a cent on L2). Consumers of departure data should verify:

• The msg.sender is the agent's owner or authorized operator
• The feedbackURI resolves to a valid, signed EXIT marker
• The marker's cryptographic proof is valid

Hash Salt

computeMarkerHash() automatically generates a 256-bit random salt to prevent brute-force attacks on the hash. The salt is returned alongside the hash and must be stored for later verification. Without the salt, the hash cannot be recomputed.

On-Chain Data

Departure records written on-chain are immutable. The origin field (platform name) is stored in cleartext. Consider privacy implications before registering departures for sensitive platforms.

Known Limitations

• Three-DID problem: EXIT markers use did:key, ERC-8004 derives did:pkh, and registration files may declare other DIDs. These are not cryptographically linked in v0.1.0.
• Ed25519/secp256k1 mismatch: EXIT proofs use Ed25519 or P-256, but did:pkh resolves to secp256k1 keys. Cross-algorithm binding is not yet implemented.

Ecosystem

Package	Language	Description
cellar-door-exit	TypeScript	Core protocol (reference impl)
cellar-door-exit	Python	Core protocol
cellar-door-entry	TypeScript	Arrival/entry markers
@cellar-door/langchain	TypeScript	LangChain integration
cellar-door-langchain	Python	LangChain integration
@cellar-door/vercel-ai-sdk	TypeScript	Vercel AI SDK
@cellar-door/mcp-server	TypeScript	MCP server
@cellar-door/eliza	TypeScript	ElizaOS plugin
@cellar-door/eas	TypeScript	EAS attestation anchoring
@cellar-door/erc-8004	TypeScript	ERC-8004 identity/reputation ← you are here
@cellar-door/sign-protocol	TypeScript	Sign Protocol attestation

Paper · Website

License

Apache-2.0