Package Logo
erc8004-substreams
erc8004-substreams@v0.2.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
map_flash_events map Flashblocks streaming at 200ms latency (partial blocks safe)
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.2.0.spkg
substreams-sink-sql run "psql://erc8004:erc8004pass@localhost:5432/erc8004?sslmode=disable" ./erc8004-substreams-v0.2.0.spkg

ClickHouse

docker compose up -d clickhouse
substreams-sink-sql setup "clickhouse://default:@localhost:9000/default" ./erc8004-substreams-v0.2.0.spkg
substreams-sink-sql run "clickhouse://default:@localhost:9000/default" ./erc8004-substreams-v0.2.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

Flashblocks (200ms Streaming)

Stream ERC-8004 events with 200ms latency using Base Flashblocks:

# Stream live with partial blocks
substreams run -e https://base-mainnet.streamingfast.io map_flash_events -s -1 --partial-blocks

# Visual debugger with Flashblocks
substreams gui -e https://base-mainnet.streamingfast.io map_flash_events -s -1 --partial-blocks

# Webhook sink for real-time notifications
substreams sink webhook --partial-blocks -e https://base-mainnet.streamingfast.io http://your-webhook.com ./erc8004-substreams-v0.2.0.spkg -s -1

The map_flash_events module only processes transactionTraces — no block-level aggregation — so it's safe for partial blocks. You get each ERC-8004 event as soon as it's sequenced by the Base sequencer, rather than waiting for full block confirmation.

Links

Documentation

Modules

Maps icon
Maps

map
map_events

631ee896d7a762b7a3d27f8104e62b651939b3ec
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.2.0 map_events

map
map_flash_events

7d467f3839e9e5252f6696960e77c0d8f8923ee0
map map_flash_events (
paramsstring
)  -> erc8004.v1.Events
Default param : identity_registry=0x8004A169FB4a3325136EB29fA0ceB6D2e539a432,reputation_registry=0x8004BAa17C55a88189AE136b182e5fdA19dE9b63

Flashblocks-compatible module for 200ms streaming on Base. Only processes transactionTraces — no block-level aggregation. Safe for partial blocks. Use with --partial-blocks flag: substreams run -e https://base-mainnet.streamingfast.io map_flash_events -s -1 --partial-blocks

substreams gui erc8004-substreams@v0.2.0 map_flash_events

map
db_out

84337a6ce04b52facec3aac5354964b935c483c3

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

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

store
store_agents

f5f680fa3bcdf15c25251ef56c84b6263dcdd752
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.2.0 store_agents

store
store_feedback_counts

2e0e963027d4f80cbca3f28e164fda93539d8bca
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.2.0 store_feedback_counts

store
store_reputation

15c2a5abcca4b8c44b56cab7544be9d3f437e0b9
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.2.0 store_reputation
Protobuf

Protobuf Docs Explorer

erc8004.v1