npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2026 – Pkg Stats / Ryan Hefner

@nirholas/erc-8004-contracts

v1.0.0

Published

[![npm version](https://img.shields.io/npm/v/@nirholas/erc-8004-contracts.svg)](https://www.npmjs.com/package/@nirholas/erc-8004-contracts)

Vulnerabilities

Powered byPowered by Snyk
  • 0High
  • 0Medium
  • 0Low

Links

Git

Maintainers

nirholasnirholas

Keywords

Readme

ERC-8004: Trustless Agents

npm version

Implementation of the ERC-8004 protocol for agent discovery and trust through reputation and validation.

Contract Addresses

Ethereum Mainnet

Ethereum Sepolia

Base Sepolia

  • IdentityRegistry: to be deployed
  • ReputationRegistry: to be deployed

Linea Sepolia

  • IdentityRegistry: to be deployed
  • ReputationRegistry: to be deployed

Polygon Amoy

  • IdentityRegistry: to be deployed
  • ReputationRegistry: to be deployed

Hedera Testnet

  • IdentityRegistry: to be deployed
  • ReputationRegistry: to be deployed

HyperEVM Testnet

  • IdentityRegistry: to be deployed
  • ReputationRegistry: to be deployed

SKALE Base Sepolia Testnet

  • IdentityRegistry: to be deployed
  • ReputationRegistry: to be deployed

About

This repository implements ERC-8004 (Trustless Agents): a lightweight set of on-chain registries that make agents discoverable and enable trust signals across organizational boundaries.

At a high level, ERC-8004 defines three registries:

  • Identity Registry: an ERC-721 registry for agent identities (portable, browsable, transferable).
  • Reputation Registry: a standardized interface for publishing and reading feedback signals.
  • Validation Registry: hooks for validator smart contracts to publish validation results.

The normative spec lives in ERC8004SPEC.md.

Quickstart

Install dependencies:

npm install

Run tests:

npm test

Or via Hardhat:

npx hardhat test

Core concepts (from the spec)

Agent identifier

An agent is identified by:

  • agentRegistry: {namespace}:{chainId}:{identityRegistry} (e.g., eip155:11155111:0x...)
  • agentId: the ERC-721 tokenId minted by the Identity Registry

Off-chain payloads (registration files, feedback files, evidence) should include both fields so they can be tied back to the on-chain agent.

What ERC-8004 does (and doesn’t)

  • Discovery: ERC-8004 makes agents discoverable via an ERC-721 identity whose tokenURI points to a registration file.
  • Trust signals: ERC-8004 standardizes how reputation and validation signals are posted and queried on-chain.
  • Not payments: payment rails are intentionally out-of-scope; the spec shows how payments can enrich feedback signals, but ERC-8004 does not mandate a payment system.

Registries

Identity Registry (agent discovery)

The Identity Registry is an upgradeable ERC-721 (ERC721URIStorage) where:

  • agentURI (tokenURI) points to the agent registration file (e.g., ipfs://... or https://...).
  • register mints a new agent NFT and assigns an agentId.
  • setAgentURI updates the agent’s URI.

On-chain metadata

The registry also provides optional on-chain metadata:

  • getMetadata(agentId, metadataKey) -> bytes
  • setMetadata(agentId, metadataKey, metadataValue)

The reserved key agentWallet is managed specially:

  • It is set automatically on registration (initially to the owner’s address).
  • It can be updated only after proving control of the new wallet via setAgentWallet(...) (EIP-712 / ERC-1271).
  • It is cleared on transfer so a new owner must re-verify.
  • Helpers: getAgentWallet(agentId) and unsetAgentWallet(agentId).

Agent registration file (recommended shape)

The agentURI should resolve to a JSON document that is friendly to NFT tooling (name/description/image) and also advertises agent endpoints. The spec’s registration file includes:

  • type: schema identifier for the registration format
  • name, description, image
  • services: a list of endpoints (e.g., A2A agent card URL, MCP endpoint, OASF manifest, ENS name, email)
  • registrations: a list of { agentRegistry, agentId } references to bind the file back to on-chain identity
  • supportedTrust: optional list such as reputation, crypto-economic, tee-attestation

Optional: endpoint domain verification

If an agent advertises an HTTPS endpoint, it can optionally prove domain control by hosting a well-known file (see ERC8004SPEC.md). Verifiers can use it to confirm that an endpoint domain is controlled by the same agent identity.

Reputation Registry (trust signals)

The Reputation Registry stores and exposes feedback signals as a signed fixed-point number:

  • value: int128 (signed)
  • valueDecimals: uint8 (0–18)

Everything else is optional metadata (tags, endpoint URI, off-chain payload URI + hash).

Interpreting value + valueDecimals

Treat the pair as a signed decimal number:

  • Example: value=9977, valueDecimals=2 → 99.77
  • Example: value=560, valueDecimals=0 → 560

This allows a single on-chain schema to represent percentages, scores, timings, dollar amounts, etc. (the meaning is conveyed by tag1/tag2 and/or the off-chain file).

Give feedback

giveFeedback(...) records feedback for an agent. The implementation prevents self-feedback from the agent owner or approved operators (checked via the Identity Registry).

Read + aggregate

Typical read paths:

  • readFeedback(agentId, clientAddress, feedbackIndex)
  • readAllFeedback(agentId, clientAddresses, tag1, tag2, includeRevoked)
  • getSummary(agentId, clientAddresses, tag1, tag2) → returns (count, summaryValue, summaryValueDecimals)

Note: getSummary requires clientAddresses to be provided (non-empty) to reduce Sybil/spam risk.

Responses & revocation

  • Clients can revoke their feedback: revokeFeedback(agentId, feedbackIndex)
  • Anyone can append responses: appendResponse(agentId, clientAddress, feedbackIndex, responseURI, responseHash)

Suggested end-to-end flow

  1. Register an agent in the Identity Registry (register(...)) and get an agentId.
  2. Publish a registration file (e.g., on IPFS/HTTPS) and set it as the agentURI via setAgentURI(agentId, ...).
  3. (Optional) Set a verified receiving wallet via setAgentWallet(...) (EIP-712/1271 proof).
  4. Collect feedback from users/clients via giveFeedback(...) on the Reputation Registry.
  5. Aggregate trust in-app using getSummary(...) and/or pull raw feedback via readAllFeedback(...) for off-chain scoring.

Validation Registry

Warning

The Validation Registry portion of the ERC-8004 spec is still under active update and discussion with the TEE community. This section will be revised and expanded in a follow-up spec update later this year.

The current implementation supports:

  • validationRequest(validatorAddress, agentId, requestURI, requestHash) (must be called by owner/operator of agentId)
  • validationResponse(requestHash, response, responseURI, responseHash, tag) (must be called by the requested validator)
  • Read functions: getValidationStatus, getSummary, getAgentValidations, getValidatorRequests

JSON payloads (off-chain)

Agent registration file (Identity Registry)

The agent’s agentURI should resolve to a registration file (see ERC8004SPEC.md) containing human-friendly metadata plus a list of advertised services/endpoints (e.g., A2A, MCP, OASF, ENS, email).

Feedback file (optional, Reputation Registry)

The on-chain feedback can optionally reference a richer off-chain JSON payload (again see the spec) that includes:

  • agentRegistry, agentId, clientAddress, createdAt
  • value, valueDecimals
  • Optional categorization under namespaces like mcp, a2a, and oasf

Tip: keep the on-chain call minimal (tags + numeric signal), and put verbose context (task transcript, payment proof, artifacts, model/version info) in the off-chain JSON referenced by feedbackURI.

Project structure

contracts/
├── IdentityRegistryUpgradeable.sol     - ERC-721 based agent registration (upgradeable)
├── ReputationRegistryUpgradeable.sol   - Feedback + aggregation (upgradeable)
└── ValidationRegistryUpgradeable.sol   - Validation request/response (upgradeable)

abis/                                  - Contract ABIs for integrations
ignition/modules/                       - Deployment modules
scripts/                                - Deployment/upgrade utilities
test/                                   - Test suite
ERC8004SPEC.md                           - Protocol spec used as source-of-truth for docs

Resources

License

CC0 - Public Domain

Contacts

ERC-8004 is a community effort coordinated by Marco De Rossi (MetaMask) and Davide Crapis (EF), with the co-authorship of Jordan Ellis (Google) and Erik Reppel (Coinbase). Our core team is joined by Leonard Tan (MetaMask), Vitto Rivabella (EF), and Isha Sangani (EF).

Check out our website at 8004.org and reach out at [email protected].