arctools for Arc

arc-agents

885,423 agents are registered. Nothing lets you list them.

ERC-8004 identity and reputation are the substrate for Arc's agentic economy — Circle's stated top grant priority — and every application in that space has to read these registries. Neither of the two obvious ways to do it works.

How enumeration works Reputation

Why this is hard

No totalSupply()

AgentIdentity is a plain ERC-721 — supportsInterface(0x80ac58cd) is true — but it does not implement ERC721Enumerable. There is no count to ask for.

Counting by logs is expensive

The registries are busy — ~268,000 logs in the last 1.17M blocks — but the 885k agents accumulated over the chain's whole ~58M-block history, so a complete count means backfilling all of it: 2,000–5,900 requests at the real eth_getLogs caps.

Read state instead

Token ids are minted sequentially from 0, and ownerOf reverts past the end. That makes the registry size findable by exponential probe plus binary search: 

node src/cli.ts count
ERC-8004 AgentIdentity  0x8004A818BFB912233c491871b3d84c89A494BD9e

  registered agents   885423
  highest token id    885422
  cost                41 eth_calls
41
eth_calls to find the registry size
2,000+
eth_getLogs calls a full backfill would need
O(log n)
vs O(blocks) — the probe scales with registry size, not chain length

Commands

node src/cli.ts count
node src/cli.ts list --from 0 --limit 20 --resolve
node src/cli.ts show 1 --resolve
node src/cli.ts reputation 4 --max-clients 500

--resolve fetches the metadata document that tokenURI points at, usually on IPFS. Resolution failure never fails a listing — one unreachable gateway must not take down twenty rows. Many public gateways redirect to a per-CID subdomain, which sandboxed and corporate networks refuse, so set ARC_IPFS_GATEWAY or pass --gateway when the defaults are blocked.

Reputation

The ReputationRegistry read surface is not in Arc's documentation — the tutorials cover writes only. These were found by probing the deployed contract:

FunctionReturnsStatus
getClients(uint256)address[] — who attestedverified
getLastIndex(uint256,address)uint64 — attestations from one clientverified
getSummary(uint256,address[],string,string)aggregateexists, untested
readFeedback(uint256,address,uint64)a tuple with no published layoutnot decoded
Why readFeedback is left undecoded

Its return tuple can be observed but not confirmed: guessing which word holds the score would silently produce plausible, wrong numbers. So arc-agents reports attestation volume and the most active attesters, and says explicitly that per-attestation scores need the canonical ERC-8004 ABI. A stated gap is worth more than a confident guess.

Popular agents have thousands of attesters — agent #1 has 1,315 — and one eth_call each trips the rate limit. The fan-out is capped at 100 clients by default; a partial result is marked with + and says how to widen it.

Agent metadata

tokenURI points at an application-defined JSON document. The shape from Arc's own example: 

{
  "name": "DeFi Arbitrage Agent v1.0",
  "description": "Autonomous trading agent for cross-DEX arbitrage on Arc",
  "agent_type": "trading",
  "capabilities": ["arbitrage_detection", "liquidity_monitoring"],
  "version": "1.0.0"
}

Nothing enforces this — the fields are application-defined unless an integration follows a separate convention, so callers get whatever the operator published.

What this is a foundation for

An agent directory: searchable capabilities, reputation ranking, metadata pinning. That is the obvious next build, and it needs exactly what this package does — cheap enumeration plus an honest reputation read.

Tests

17 tests, no network. The binary search is verified against fixture registries of several sizes including an empty one, the concurrency pool is checked for bounded parallelism and order preservation, and EIP-55 checksumming is pinned to the canonical test vector.