Architecture

This guide explains how Agent Passport turns a wallet request into an explainable decision: the service boundary, request lifecycle, Algorand data flow, contracts, caching, persistence, and scaling model. For the scoring rules themselves, see the algorithm and scoring reference.

1. System overview

Agent Passport is a self-hosted HTTP API for evaluating Algorand agents. Read endpoints return trust, delegation, Sybil, reputation, credit, and underwriting evidence. Mutating delegation and reputation routes can write to the configured Algorand applications when an operator wallet is enabled.

Read endpoints do not require an application database: they fetch from the configured Algorand algod and indexer services and use a 60-second in-memory response cache. The service does not silently provision hosted storage, queues, billing, or identity infrastructure.

For stateful endpoints, four per-process stores are NOT shared across pods and must be backed by Redis (or equivalent) when running with REPLICA_COUNT > 1:

• src/lib/idempotency.ts — Idempotency-Key cache
• src/lib/security.ts — per-IP rate-limit map
• src/lib/system-exposure.ts — global + per-wallet exposure ledger
• src/lib/webhooks.ts — webhook subscriber registry

A boot-time warning is logged for each store when REPLICA_COUNT > 1. The on-disk JSON files (data/*.json) only protect against restart loss, not against pod fan-out — each replica independently enforces its cap and serves its subscriber list. Scale reads by adding pods; scale state by adding Redis.

HTTP parsing stays at the application edge. Shared wallet and amount rules live in src/http/validation.ts, while domain modules remain independent of Express request and response objects. New routes should validate and normalize at this boundary, call a domain function, and then map its result to HTTP.

2. Request lifecycle

A request passes through ordered platform and security stages before its route handler. The stack validates input, assigns a request ID, applies CORS and rate limits, enforces deadlines and optional payment/authentication, and then dispatches to the capability. Operational routes are kept separate from business logic so health, readiness, metrics, and version metadata remain safe to expose to deployment tooling.

Operational endpoints (/health, /ready, /health/deep, /metrics, /registry/status) are exempt from rate limiting (step 6) and from payment (step 10).

3. Cache and idempotency stores

Response cache

src/lib/cache.ts — TTLCache<unknown>(maxEntries: 500, ttlMs: 60_000). Caches /score and /passport for 60 s. Invalidated on /delegate, /revoke, /reputation/record for the affected wallet.

Idempotency store

src/lib/idempotency.ts — in-memory Map<key, { bodyHash, status, body, expiresAt }>. Default 24 h TTL, 10 000 entry cap, 5-minute sweeper. Body hash uses canonical JSON (sorted keys) so {"a":1,"b":2} and {"b":2,"a":1} produce the same hash.

For multi-replica deployments, back this with Redis. The current implementation is per-process.

Rate-limit and system-exposure JSON files

Two single-purpose data/*.json files persist across restarts:

• data/rate-limit.json — per-IP request counts (resets after 60 s)
• data/system-exposure.json — cumulative approved credit per wallet

Both use the shared JSON-file persistence helper (src/lib/json-store.ts) with a write-queue mutex to prevent concurrent-write races. Multi-replica needs Redis for both.

4. Smart contracts

Two TEAL v10 contracts under contracts/:

registry.teal — delegation registry

• App ID: REGISTRY_APP_ID env var
• Global state: admin (operator address)
• Box storage: one box per (sponsor, agent) pair, value = amount in microALGO units plus the last-update timestamp
• Methods:
• add_delegation(sponsor, agent, amount) — creates a box
• revoke_delegation(sponsor, agent) — deletes the box
• update_admin(new_admin) — rotates the operator key
• Update permission: only the admin address

The current transaction format passes the agent and sponsor as application accounts (Accounts[0] and Accounts[1]) and includes the deterministic box reference in the application call. Existing deployments created with the older payment-transfer format must be redeployed (or migrated with a planned contract upgrade) before enabling the updated service.

reputation.teal — on-chain reputation events

• App ID: REPUTATION_APP_ID env var
• Global state: admin, event_count, per-wallet event counter
• Local state: per-account event log
• Methods:
• record_event(wallet, event_type, amount, counterparty) — appends
• update_admin(new_admin) — rotates the operator key
• Update permission: only the admin address

Deploying the contracts: npm run deploy-registry and npm run deploy-reputation (uses DEPLOYER_MNEMONIC). The runtime operator wallet (OPERATOR_MNEMONIC) is a separate key with on-chain permission.

5. Data flow (request → Algorand → response)

Trust-score generation fans out 5 sub-score calls (age, activity, volume, velocity, compliance), each hitting algod once. The composite is computed in-process. Total: 1 status() + 1 accountInformation() + 0-25 txlist/txinfo for delegation, all in parallel where independent.

6. Module reference

7. Scaling characteristics

For horizontal scaling:

1. Add a load balancer that forwards X-Forwarded-For and set TRUST_PROXY_HOPS to the number of trusted hops. The default of 0 is fail-closed (does not honour the spoofable header); set to 1 for a single reverse proxy (ALB, nginx), to 2 for CloudFront → ALB → app, and to 2 or 3 for k8s ingress → sidecar → app depending on the topology.
2. Set REPLICA_COUNT to the planned replica fan-out. The service will emit a boot-time warning for each per-process store (rate-limit, idempotency, system-exposure, webhook subscribers) so you remember to back them with Redis. The src/lib/json-store.ts interface is designed to be drop-in replaceable.
3. Configure your orchestrator's readinessProbe to /ready and livenessProbe to /health.