# Concepts

> **NOTE — unofficial library.** `@p4n/erc8004-ui` is an independent, community-built project. It is not affiliated with, maintained by, or endorsed by the authors of ERC-8004. It reads the standard's on-chain data through public subgraphs; it does not speak for the standard.

What you need to know about ERC-8004 to use this library — no protocol deep-dive required.

## What is ERC-8004?

ERC-8004 is an Ethereum standard for on-chain AI agent identity. It lets agents register themselves on the blockchain with a name, description, image, and service endpoints — and lets users leave feedback and validations. Think of it like a public profile + review system for AI agents, but the data lives on-chain so it can't be faked.

## Why use this library?

For the specific Subgraph quirks this library handles on your behalf, see the [Introduction](https://erc8004-ui.vercel.app/docs/introduction). Two gaps in the underlying data are worth flagging up front, since they shape the empty states you'll see:

> **Warning — the Validation Registry isn't deployed anywhere yet:** `validationRegistry` is the zero address on every chain checked, testnets included. Validation queries succeed and return nothing, so `VerificationBadge`, `ValidationScore`, `ValidationList` and `ValidationDisplay` render their empty state everywhere. Verified 2026-09-04 across Ethereum, Base, Polygon, BNB Smart Chain, BNB Chapel and Base Sepolia.


## The Three Registries

### Identity Registry

Like a business registration. Each agent gets an NFT (ERC-721 token) with a registration file containing its name, description, image, and service endpoints. This is where "who is this agent?" data lives.

_Components: AgentName, AgentImage, AgentDescription, AgentCard, EndpointStatus._

### Reputation Registry

Like a review system. Users who interact with an agent can leave feedback — a score, tags describing what the agent does well, and optional written reviews. This is where "is this agent any good?" data lives.

_Components: ReputationScore, ReputationTimeline, ReputationDistribution, FeedbackList, TagCloud._

### Validation Registry

Like a certification body. Independent third-party verifiers can assess an agent and record a score (0–100). This is where "has this agent been independently verified?" data lives.

_Components: VerificationBadge, ValidationScore, ValidationList._

> **Warning:** Not deployed on any chain yet — `validationRegistry` is the zero address everywhere, testnets included. These components render their empty state on every chain.

## Agent Identity: agentRegistry + agentId

Every component takes two props that together uniquely identify an agent across any chain:

- **`agentRegistry`** — A string in the format `eip155:{chainId}:{contractAddress}`. Breaking it down:
  - `eip155` — namespace meaning it's an Ethereum-compatible chain.
  - `chainId` — identifies which blockchain (1 = Ethereum, 8453 = Base, etc.).
  - `contractAddress` — where the Identity Registry smart contract is deployed.
- **`agentId`** — The ERC-721 token ID, the unique number assigned to this agent when it registered.

Example: `agentRegistry="eip155:8453:0x8004A169FB4a3325136EB29fA0ceB6D2e539a432"` + `agentId={888}` means "agent #888 on the Base blockchain."

## Two Ways to Pass Identifiers

Components accept identifiers two ways:

**Directly as props** — fine for a single component:

```tsx
<ReputationScore agentRegistry="eip155:8453:0x..." agentId={888} />
```

**Via `AgentProvider`** — cleaner when rendering multiple components for the same agent:

```tsx
<AgentProvider agentRegistry="eip155:8453:0x..." agentId={888}>
  <AgentCard />
  <ReputationScore />
  <FeedbackList />
</AgentProvider>
```

Props on individual components override the provider, so you can mix both patterns when needed.

## Trustless Data

Components never accept display data as props. You only pass identifiers — the component fetches verified data from the blockchain internally. This means the data you see is guaranteed to be real on-chain data, not something that could be spoofed by a developer passing fake props.

This differs from a typical React component where you'd pass something like `<AgentCard name="Alice" score={4.8} />` — those values could be anything the developer types. Here, the component fetches `name` and `score` itself from on-chain data, so what's displayed is what's actually registered.

## Supported Chains

| Chain | ID |
| --- | --- |
| Ethereum Mainnet | 1 |
| Base Mainnet | 8453 |
| Polygon Mainnet | 137 |
| BSC Mainnet | 56 |
| Monad Mainnet | 143 |
| Base Sepolia (testnet) | 84532 |
| BSC Chapel (testnet) | 97 |
| Monad Testnet (testnet) | 10143 |


## Where the Data Comes From

All data is fetched from [The Graph](https://thegraph.com) — a decentralised indexing service that watches the blockchain, extracts ERC-8004 events, and serves them via fast GraphQL queries. You don't need to understand GraphQL to use this library — components handle all queries internally. You just need a free API key from The Graph.

## Reference

- Live page: https://erc8004-ui.vercel.app/docs/concepts
- Markdown source: https://erc8004-ui.vercel.app/docs/concepts.md