Package Logo
erc8004-substreams
erc8004-substreams@v0.1.0
Total Downloads
5
Published
21 hours ago
Network
base base
Publisher
User Avatar PaulieB14

Readme

ERC-8004 Substreams

High-performance Substreams indexer for ERC-8004 Trustless Agents on Base.

ERC-8004

Contracts Indexed

Contract Address Events
IdentityRegistry 0x8004A169FB4a3325136EB29fA0ceB6D2e539a432 Registered, Transfer, MetadataSet, URIUpdated
ReputationRegistry 0x8004BAa17C55a88189AE136b182e5fdA19dE9b63 NewFeedback, FeedbackRevoked, ResponseAppended

Modules

Module Type Description
map_events map Extracts all ERC-8004 events from both contracts
store_agents store Tracks agent owner, URI, and wallet state
store_feedback_counts store Aggregate feedback/response counts per agent
store_reputation store Running reputation scores per agent and tag
db_out map Produces DatabaseChanges for PostgreSQL/ClickHouse

Quick Start

# Authenticate
substreams auth

# Build
substreams build

# Test with 1000 blocks
substreams run -s 25000000 -t +1000 map_events

# Visual debugger
substreams gui -s 25000000 -t +1000 map_events

SQL Sinks

PostgreSQL

docker compose up -d postgres
substreams-sink-sql setup "psql://erc8004:erc8004pass@localhost:5432/erc8004?sslmode=disable" ./erc8004-substreams-v0.1.0.spkg
substreams-sink-sql run "psql://erc8004:erc8004pass@localhost:5432/erc8004?sslmode=disable" ./erc8004-substreams-v0.1.0.spkg

ClickHouse

docker compose up -d clickhouse
substreams-sink-sql setup "clickhouse://default:@localhost:9000/default" ./erc8004-substreams-v0.1.0.spkg
substreams-sink-sql run "clickhouse://default:@localhost:9000/default" ./erc8004-substreams-v0.1.0.spkg

The ClickHouse schema includes 6 materialized views for real-time analytics:

  • Hourly registration stats
  • Daily feedback volume per agent
  • Per-tag feedback aggregates
  • Top agents by activity
  • Client activity leaderboard
  • Hourly protocol metrics

Database Tables

  • agents — Agent identities (owner, URI, wallet)
  • agent_metadata — Key-value metadata per agent
  • agent_transfers — Transfer history
  • feedbacks — All feedback entries with scores and tags
  • responses — Feedback responses
  • identity_events — Raw IdentityRegistry event log
  • reputation_events — Raw ReputationRegistry event log

Make Targets

make build              # Build WASM + spkg
make run                # Test run (1000 blocks)
make gui                # Visual debugger
make docker-up          # Start Postgres + ClickHouse + Grafana
make all-postgres       # Full setup: build + setup + run PostgreSQL sink
make all-clickhouse     # Full setup: build + setup + run ClickHouse sink

Links

Documentation

Modules

Maps icon
Maps

map
map_events

807281c63c793fba35a03fa079a845f153fc960b
map map_events (
paramsstring
blocksf.ethereum.type.v2.Block
)  -> erc8004.v1.Events
Default param : identity_registry=0x8004A169FB4a3325136EB29fA0ceB6D2e539a432,reputation_registry=0x8004BAa17C55a88189AE136b182e5fdA19dE9b63

Extracts all ERC-8004 events from IdentityRegistry and ReputationRegistry contracts on Base. Covers agent registrations, transfers, metadata changes, feedback, revocations, and responses.

substreams gui erc8004-substreams@v0.1.0 map_events

map
db_out

f9e752234f157e1ed34eea2871f20fcf31067c89

Produces DatabaseChanges for all ERC-8004 events and aggregated state. Powers both PostgreSQL and ClickHouse sinks.

substreams gui erc8004-substreams@v0.1.0 db_out
Stores icon
Stores

store
store_agents

2ca062af5e039db9570f5f17c5e08c82f288f407
store <set,string> store_agents (
)

Tracks current agent state: owner address, URI, and wallet. Key format: agent:{agentId} → owner|uri|wallet

substreams gui erc8004-substreams@v0.1.0 store_agents

store
store_feedback_counts

edc85f25fb892dc3aaea99b6bdc14da7f687d9ed
store <add,int64> store_feedback_counts (
)

Tracks total feedback count, active (non-revoked) count, and response count per agent. Keys: feedback_total:{agentId}, feedback_active:{agentId}, responses:{agentId}

substreams gui erc8004-substreams@v0.1.0 store_feedback_counts

store
store_reputation

0d997e53ff6096e469e10b84e9358e5d4dc60c51
store <set,string> store_reputation (
)

Maintains running reputation score aggregates per agent. Key: rep:{agentId} → sum_value|count|avg Also per-tag: rep:{agentId}:{tag1} → sum_value|count|avg

substreams gui erc8004-substreams@v0.1.0 store_reputation
Protobuf

Protobuf Docs Explorer

erc8004.v1