Agentpass Scan

How EVM contract facts, indexing, profile processing, metrics, the Discover API, and Agentpass Scan fit together.

Agentpass is split into a trusted write path and a scalable read path. The EVM contracts preserve identity and reputation facts. The indexer and workers turn those facts into queryable projections. The Discover API and Agentpass Scan read those projections.

System architecture

Write Integration

Partner Backend

EVM Contract Integration

EVM Contract Layer

Identity Registry Contract

Reputation Registry Contract

EVM Contract State and Events

Off-chain Runtime

agentpass-indexer

Profile Fetch Worker

Metrics Worker

agentpass-discover

Read Consumers

Partner Frontend

Agentpass Scan

Contract writes produce EVM state and events. The indexer and workers project those facts into PostgreSQL, then the Discover API serves read-only data to product UIs.

System layers

Layer	Responsibility	Design boundary
Identity Registry Contract	Owns Agent identity, owner, profile URI, metadata, collection pointer, operator wallet, lifecycle state, and authorization checks.	It is the authority for identity control and lifecycle facts.
Reputation Registry Contract	Owns feedback submission, revocation, response append, self-review prevention, and feedback/response sequence integrity.	It stores traceable reputation facts, not expensive ranking aggregates.
agentpass-indexer	Reads confirmed EVM contract activity, decodes events, applies idempotent database writes, and advances cursor state.	It writes projections and jobs; it does not expose product APIs.
Profile Fetch Worker	Fetches externally hosted Registration Files, validates content boundaries, and preserves profile snapshot history.	Agent profiles remain externally hosted; Agentpass indexes snapshots for discovery.
Metrics Worker	Consumes recalculation jobs and materializes reputation metrics.	Heavy aggregation stays outside synchronous request handling.
agentpass-discover	Serves read-only HTTP APIs for agents, search, feedback, responses, reputation, leaderboard, readiness, and metrics.	It reads PostgreSQL projections and tolerates eventual consistency with EVM contract state.
Agentpass Scan	Provides the public discovery interface over the Discover API.	It is a presentation layer, not an authority for identity control.

Data model

Agentpass uses stable business identifiers across EVM contract events, database projections, APIs, and UI:

agentId: unique Agent number minted by the Identity Registry Contract.
canonicalAgentId: cross-chain identifier used by read APIs and UI when numeric IDs may be ambiguous across networks.
feedbackId: per-Agent feedback sequence maintained by the Reputation Registry Contract.
responseId: per-feedback response sequence maintained by the Reputation Registry Contract.

External integrations should store business identifiers instead of internal database surrogate keys.

Projection flow

Trusted Write Path

Agent Owner or Operator

Feedback Client

Identity Registry Contract Call

Reputation Registry Contract Call

EVM Contract State and Events

Projection Path

Indexer Event Reader

EVM Contract Event Decoder

Idempotent Event Processor

Profile and Metric Jobs

Query Read Path

PostgreSQL Projection

Discover REST API

Agentpass Scan or Partner UI

The write path is authoritative. The projection path is idempotent and retryable. The read path is optimized for search, details, rankings, and partner-facing API responses.

A caller writes an identity or reputation transaction to the EVM contracts.
The EVM contracts update state and emit events.
The indexer reads confirmed events, decodes them, and applies idempotent database writes.
Profile URI changes enqueue profile fetch jobs.
Feedback changes enqueue metric recalculation jobs.
Discover API reads PostgreSQL projections.
Agentpass Scan and partner products consume the Discover API.

Reputation metric

Agentpass currently uses a transparent discovery metric:

Weighted Score = Average Score x ln(Unique Clients + 1) x Positive Ratio x Diversity Ratio

Where:

Average Score is computed from active, non-revoked feedback values after decimal normalization.
Unique Clients counts distinct feedback submitters.
Positive Ratio is the share of active feedback with a score greater than zero.
Diversity Ratio is Unique Clients / Total Active Feedback.

The current tier model is:

Tier	Rule
`unrated`	No active feedback.
`bronze`	Active feedback exists and weighted score is below `0.75`.
`silver`	Weighted score is at least `0.75` and below `2`.
`gold`	Weighted score is at least `2`.

These tiers are discovery aids. They are not warranties, credit ratings, service-level guarantees, anti-fraud decisions, compliance determinations, or official certifications.

Consistency model

The read path is eventually consistent with confirmed EVM contract events. Search and rankings avoid direct EVM RPC dependency by reading materialized projections. Operators should monitor indexer cursor lag, profile fetch failures, metric job backlog, API latency, rate-limit hits, and database saturation.

Security boundaries

EVM contract state is authoritative for identity control.
The PostgreSQL database is a read projection.
Self-feedback is blocked for the current owner or authorized operator.
Feedback revocation preserves history and can only be initiated by the original feedback submitter.
External Registration Files are fetched with network, timeout, size, and JSON validation boundaries.
Secrets such as private keys, seed phrases, wallet files, keystores, and RPC tokens must not be stored in public docs, fixtures, URLs, or repository configuration.

Architecture and Design