Skip to content

Commit 40c46aa

Browse files
gitctrlxgitctrlx
committed
Update documentation to reflect 30 supported networks and add comprehensive usage examples
- Update main README: change network count from 18 to 30 (16 mainnet + 14 testnet) - Add 12 new networks to supported networks table: Abstract, Avalanche C-Chain, Linea, Mantle, MegaETH, Optimism (both mainnet and testnet variants) - Enhance erc8004-events README with crates.io and docs.rs badges - Add complete supported networks table (28 chains: 16 mainnet + 12 testnet) to events documentation - Document
1 parent 70622dc commit 40c46aa

2 files changed

Lines changed: 107 additions & 18 deletions

File tree

‎README.md‎

Lines changed: 14 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -19,7 +19,7 @@
1919

2020
**Type-safe Rust SDK for the [ERC-8004](https://eips.ethereum.org/EIPS/eip-8004) Trustless Agents standard — on-chain identity, reputation, and validation registries for AI agents.**
2121

22-
ERC-8004 enables **discovery, reputation, and validation** of AI agents across organizational boundaries without pre-existing trust. This SDK provides ergonomic, alloy-native bindings for all three registries, with 18 pre-configured network deployments (CREATE2 deterministic addresses) and full off-chain type support (registration files, service endpoints, feedback).
22+
ERC-8004 enables **discovery, reputation, and validation** of AI agents across organizational boundaries without pre-existing trust. This SDK provides ergonomic, alloy-native bindings for all three registries, with 30 pre-configured network deployments (CREATE2 deterministic addresses) and full off-chain type support (registration files, service endpoints, feedback).
2323

2424
See [Security](SECURITY.md) before using in production.
2525

@@ -95,7 +95,7 @@ let json = reg.to_json()?;
9595
| **[`Identity`](erc8004/src/identity.rs)** | Identity Registry (ERC-721) — register agents, manage URIs, wallets, metadata, EIP-712 signatures |
9696
| **[`Reputation`](erc8004/src/reputation.rs)** | Reputation Registry — submit / revoke feedback, read aggregated summaries, list clients |
9797
| **[`Validation`](erc8004/src/validation.rs)** | Validation Registry — request / respond to validation, query status and summaries |
98-
| **[`Network`](erc8004/src/networks.rs)** | 18 pre-configured deployments (10 mainnet + 8 testnet) with CREATE2 deterministic addresses |
98+
| **[`Network`](erc8004/src/networks.rs)** | 30 pre-configured deployments (16 mainnet + 14 testnet) with CREATE2 deterministic addresses |
9999
| **[`types`](erc8004/src/types.rs)** | Off-chain JSON types — `RegistrationFile`, `ServiceEndpoint`, `Feedback`, `ReputationSummary` |
100100
| **[`contracts`](erc8004/src/contracts.rs)** | Inline Solidity bindings (`sol!` macro) — alloy-recommended, preserves full type information |
101101

@@ -115,6 +115,12 @@ Contracts are deployed via CREATE2, so all mainnets share the same addresses and
115115
| Taiko (Alethia) | mainnet | 167000 |
116116
| Monad | mainnet | 143 |
117117
| BNB Smart Chain | mainnet | 56 |
118+
| Abstract | mainnet | 2741 |
119+
| Avalanche C-Chain | mainnet | 43114 |
120+
| Linea | mainnet | 59144 |
121+
| Mantle | mainnet | 5000 |
122+
| MegaETH | mainnet | 4326 |
123+
| Optimism | mainnet | 10 |
118124
| Ethereum Sepolia | testnet | 11155111 |
119125
| Base Sepolia | testnet | 84532 |
120126
| Polygon Amoy | testnet | 80002 |
@@ -123,6 +129,12 @@ Contracts are deployed via CREATE2, so all mainnets share the same addresses and
123129
| Scroll Sepolia | testnet | 534351 |
124130
| Monad Testnet | testnet | 10143 |
125131
| BNB Smart Chain Testnet | testnet | 97 |
132+
| Abstract Testnet | testnet | 11124 |
133+
| Avalanche Fuji | testnet | 43113 |
134+
| Linea Sepolia | testnet | 59141 |
135+
| Mantle Sepolia | testnet | 5003 |
136+
| MegaETH Testnet | testnet | 6342 |
137+
| Optimism Sepolia | testnet | 11155420 |
126138

127139
## Design
128140

‎erc8004-events/README.md‎

Lines changed: 93 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -1,12 +1,60 @@
11
# ERC-8004 Events
22

3-
Raw on-chain event archiver for the [ERC-8004](https://eips.ethereum.org/EIPS/eip-8004) protocol.
3+
[![crates.io][crate-badge]][crate-url]
4+
[![docs.rs][doc-badge]][doc-url]
45

5-
Fetches all event logs from the **Identity Registry** and **Reputation Registry** contracts across every known ERC-8004 deployment and stores them as [Apache Parquet](https://parquet.apache.org/) files.
6+
[crate-badge]: https://img.shields.io/crates/v/erc8004-events.svg
7+
[crate-url]: https://crates.io/crates/erc8004-events
8+
[doc-badge]: https://img.shields.io/docsrs/erc8004-events.svg
9+
[doc-url]: https://docs.rs/erc8004-events
10+
11+
Raw on-chain event archiver for the [ERC-8004](https://eips.ethereum.org/EIPS/eip-8004) Trustless Agents protocol.
12+
13+
Fetches all event logs from the **Identity Registry** and **Reputation Registry** contracts across every known ERC-8004 deployment and stores them as [Apache Parquet](https://parquet.apache.org/) files. The archived dataset is published to [HuggingFace](https://huggingface.co/datasets/qntx/erc8004-events) and updated automatically via GitHub Actions.
14+
15+
## Supported Networks
16+
17+
28 chains are currently tracked (16 mainnets + 12 testnets):
18+
19+
| Network | Chain ID | Type |
20+
| --- | --- | --- |
21+
| Base | 8453 | mainnet |
22+
| Ethereum | 1 | mainnet |
23+
| Polygon | 137 | mainnet |
24+
| Arbitrum One | 42161 | mainnet |
25+
| Celo | 42220 | mainnet |
26+
| Gnosis | 100 | mainnet |
27+
| Scroll | 534352 | mainnet |
28+
| Taiko (Alethia) | 167000 | mainnet |
29+
| BNB Smart Chain | 56 | mainnet |
30+
| Monad | 143 | mainnet |
31+
| Abstract | 2741 | mainnet |
32+
| Avalanche C-Chain | 43114 | mainnet |
33+
| Linea | 59144 | mainnet |
34+
| Mantle | 5000 | mainnet |
35+
| MegaETH | 4326 | mainnet |
36+
| Optimism | 10 | mainnet |
37+
| Base Sepolia | 84532 | testnet |
38+
| Ethereum Sepolia | 11155111 | testnet |
39+
| Polygon Amoy | 80002 | testnet |
40+
| Arbitrum Sepolia | 421614 | testnet |
41+
| Celo Alfajores | 44787 | testnet |
42+
| Scroll Sepolia | 534351 | testnet |
43+
| BNB Smart Chain Testnet | 97 | testnet |
44+
| Monad Testnet | 10143 | testnet |
45+
| Linea Sepolia | 59141 | testnet |
46+
| Mantle Sepolia | 5003 | testnet |
47+
| MegaETH Testnet | 6342 | testnet |
48+
| Optimism Sepolia | 11155420 | testnet |
649

750
## Data Format
851

9-
Each Parquet file contains raw EVM event logs in the standard `eth_getLogs` structure:
52+
Each chain produces two Parquet files under `data/<chain_id>/`:
53+
54+
- **`identity.parquet`** — events from the Identity Registry (ERC-721 agent NFTs)
55+
- **`reputation.parquet`** — events from the Reputation Registry (feedback signals)
56+
57+
Both files use the raw `eth_getLogs` schema:
1058

1159
| Column | Type | Description |
1260
| --- | --- | --- |
@@ -24,41 +72,68 @@ Each Parquet file contains raw EVM event logs in the standard `eth_getLogs` stru
2472

2573
This is the **universal EVM log format** — any EVM library in any language can decode these fields directly.
2674

75+
### Key Event Signatures
76+
77+
**Identity Registry:**
78+
79+
| Event | `topic0` |
80+
| --- | --- |
81+
| `Transfer(address,address,uint256)` | `0xddf252ad…f523b3ef` |
82+
| Agent registered (custom) | `0xca52e62c…9bc4a` |
83+
| Agent URI updated (custom) | `0x2c149ed5…1468b` |
84+
85+
**Reputation Registry:**
86+
87+
| Event | `topic0` |
88+
| --- | --- |
89+
| Feedback given (custom) | `0x6a4a6174…58febc` |
90+
| Response appended (custom) | `0xb1c6be0b…6051d4` |
91+
92+
> **Tip:** Filter mint events with `topic0 = Transfer AND topic1 = 0x000…000` to count unique agent registrations.
93+
2794
## Usage
2895

2996
```bash
3097
# Sync all mainnet chains
31-
cargo run -- sync --data-dir ./data
98+
cargo run --release -- sync --data-dir ./data
3299

33-
# Sync a specific chain
34-
cargo run -- sync --data-dir ./data --chain 8453
100+
# Sync a specific chain by chain ID
101+
cargo run --release -- sync --data-dir ./data --chain 8453
35102

36103
# Use a custom RPC endpoint
37-
cargo run -- sync --data-dir ./data --chain 8453 --rpc https://my-rpc.example.com
104+
cargo run --release -- sync --data-dir ./data --chain 8453 --rpc https://my-rpc.example.com
38105

39106
# Include testnets
40-
cargo run -- sync --data-dir ./data --include-testnets
107+
cargo run --release -- sync --data-dir ./data --include-testnets
41108

42109
# List all supported chains
43-
cargo run -- list
110+
cargo run --release -- list
44111
```
45112

113+
Sync is **incremental** — a `cursor.json` file tracks the last synced block per chain. Re-running sync only fetches new events.
114+
46115
## Consuming the Data
47116

48-
### Python (pandas / polars)
117+
### Python
49118

50119
```python
51120
import pandas as pd
52121

122+
# Load identity events for Base mainnet
53123
df = pd.read_parquet("data/8453/identity.parquet")
54-
print(f"Total events: {len(df)}")
55-
print(df.head())
124+
125+
# Count unique registered agents (ERC-721 mints: Transfer from 0x0)
126+
TRANSFER = "0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef"
127+
ZERO = "0x" + "0" * 64
128+
mints = df[(df["topic0"] == TRANSFER) & (df["topic1"] == ZERO)]
129+
print(f"Registered agents: {mints['topic3'].nunique()}")
56130
```
57131

58-
### Rust (arrow / parquet)
132+
### Rust
59133

60134
```rust
61135
use parquet::arrow::arrow_reader::ParquetRecordBatchReaderBuilder;
136+
62137
let file = std::fs::File::open("data/8453/identity.parquet")?;
63138
let reader = ParquetRecordBatchReaderBuilder::try_new(file)?.build()?;
64139
for batch in reader {
@@ -69,9 +144,11 @@ for batch in reader {
69144
### DuckDB
70145

71146
```sql
72-
SELECT * FROM read_parquet('data/8453/identity.parquet')
73-
WHERE topic0 = '0xca52e62c367d81bb2e328eb795f7c7ba24afb478408a26c0e201d155c449bc4a'
74-
LIMIT 10;
147+
-- Count registered agents on Base
148+
SELECT count(DISTINCT topic3) AS agents
149+
FROM read_parquet('data/8453/identity.parquet')
150+
WHERE topic0 = '0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef'
151+
AND topic1 = '0x0000000000000000000000000000000000000000000000000000000000000000';
75152
```
76153

77154
## License

0 commit comments

Comments
 (0)