Skip to content
VIGIL
Architecture
Start

Architecture

The VIGIL components, how data flows between them, what lives onchain versus offchain, and the constraints that shaped the design.

This page describes the components of VIGIL, the two data flows through them (a paid call through escrow, and a probe result through to a score), the boundary between onchain and offchain parts, and the constraints that shaped the design. It assumes you have read the Overview.

Components

Facilitator

The VIGIL Facilitator is a drop-in x402 facilitator. An agent points its x402 payment step at the Facilitator instead of settling directly with the provider. The Facilitator verifies the agent's signed USDC authorization, locks the amount in the escrow contract, forwards the request with a payment proof, runs the four checks (schema, size, deadline, price integrity) on the response, and submits a signed verdict to the escrow contract. It returns the response, or a failure with a reason code, to the agent.

The Facilitator runs offchain and never holds USDC. Its URL is https://facilitator.vigil.example (placeholder, not live).

Escrow contract

The escrow contract lives on Base and holds USDC for the duration of one call. Its surface is small: lock funds against a quote and a deadline, accept a signed verdict, release to the provider on pass, refund the agent on fail, and refund once the deadline has passed without a response. It emits a Checked event with each verdict. Its state machine is in Escrow flow. The contract is not deployed and not audited; its address is 0x0000000000000000000000000000000000000000 (placeholder, contracts not deployed).

Attestation registry

The attestation registry is an append-only contract on Base. Each entry is one Attestation: endpoint, method, quoted and charged price, the four check verdicts, latency, the Watcher's address and region, and a signature. Probes write here directly; the escrow contract's Checked events are recorded here too, so paid traffic and probe traffic share one record. A disputed attestation is marked excluded, not deleted, so the history stays auditable.

Score aggregator

The score aggregator reads the attestation registry and computes an Endpoint Score (0–100) per endpoint: a weighted mean in which each attestation is weighted by the Watcher's stake (capped at 10% of total weight per endpoint) and by an exponential time decay with a half-life of 7 days. Check weights are uptime 30, schema 30, price 25, latency 15. A score is public only after at least 25 attestations from at least 5 distinct Watchers. The formula is in Checks and scoring.

The aggregator runs offchain because it touches every attestation for an endpoint. It is deterministic: at a given block height, anyone can recompute the score from the public registry and compare it against the content hash written onchain.

ERC-8004 adapter

The ERC-8004 adapter writes five fields to the Reputation Registry per endpoint: the agent or endpoint identifier, the score (0–100), the attestation count, the last updated block, and a content hash of the aggregated attestation set. It reads the Identity Registry to resolve an endpoint to its provider identity, so endpoints can be grouped and a badge attached to the right identity. Reads are free. See ERC-8004.

Component diagram

VIGIL component architectureAn agent routes an x402 payment through the VIGIL Facilitator, which locks USDC in the escrow contract on Base, forwards the request to the provider, checks the response and triggers release or refund. Watchers run probes against the provider and publish attestations; the score aggregator turns attestations into an Endpoint Score written to the ERC-8004 Reputation Registry, which the agent reads for free.Agentx402 clientVIGIL Facilitatordrop-in x402 facilitatorProviderx402 endpointEscrow contractBase · USDCERC-8004Reputation RegistryScore aggregatordeterministic, offchainAttestation registryBase · append-onlyWatchersstaked · run Probes402 quoterequestresponseUSDC lockchecks verdictrelease (pass)refund (fail)Checked eventchecksevery 60 sattestationsaggregatescore writefree readonchain (Base)offchaincontract eventcontracts not deployed · addresses are placeholders

Lapis outlines are contracts on Base; grey boxes run offchain. The dashed line is the Checked event that joins the paid-call path (top) to the measurement path (bottom).

Data flow

The paid-call path:

  1. The agent requests a resource and receives a 402 quote from the provider: price, content type or schema, size bounds, maximum timeout.
  2. The agent sends the quote, a signed USDC authorization and its deadline (default 30 s, maximum 300 s) to the Facilitator.
  3. The Facilitator locks the quoted amount in the escrow contract on Base.
  4. The Facilitator forwards the request to the provider with the payment proof.
  5. The provider responds. If it does not respond before the deadline, the escrow refunds the agent automatically.
  6. The Facilitator runs the four checks within 10 s and submits a signed verdict to the escrow contract.
  7. On pass, the escrow releases USDC to the provider, less the 0.5% fee, and the agent receives the response. On fail, the escrow refunds the agent, who receives the failure with a reason code.

The measurement path:

  1. Probes call each endpoint every 60 s from at least 3 regions, paying the quoted price per probe.
  2. Each result is signed and written to the attestation registry. Escrow verdicts are recorded alongside.
  3. The score aggregator computes the Endpoint Score from the registry.
  4. The ERC-8004 adapter writes score, count, last block and content hash to the Reputation Registry.
  5. Agents read the score for free, from the registry or from https://api.vigil.example/v1/score/{endpoint} (placeholder).

Trust boundaries

Onchain, on Base:

  • USDC custody. Funds sit in the escrow contract and move only on a signed verdict or after the deadline. The Facilitator cannot take them.
  • Attestations. Every probe result and every verdict is a signed, timestamped record. Disputed entries are excluded, not erased.
  • Scores and their commitment. Score, attestation count and content hash live in the ERC-8004 Reputation Registry, readable by any contract or agent.
  • Stake, disputes and slashing. Enforced by contract.

Offchain, because the chain cannot do them or cannot afford them:

  • HTTP calls and checks. Calling a provider, parsing a body, validating it against a JSON Schema and measuring latency cannot happen inside a transaction. The Facilitator and Probes do this work and commit signed results.
  • Score aggregation. A weighted mean with time decay across hundreds of attestations would cost more gas than the fee on the call. The aggregator computes offchain and commits the result plus a content hash so anyone can recompute and challenge it.

A Facilitator or Watcher can lie about what it observed, but every claim is signed, onchain and disputable, and false attestations cost a fraction of stake defined by governance. One verdict is one signature; a score is many signatures from many staked parties, decayed over time and capped per Watcher.

Design constraints

  • One attestation per call. The gas budget on Base allows each probe result to be written as one compact transaction. Attestations carry hashes and verdicts, never response bodies. Batching is an optimisation, not an assumption.
  • Everything reads free. Scores, counts and content hashes are view reads on Base and a free HTTP endpoint. No agent needs a key, a balance or a subscription to decide whether to trust an endpoint.
  • Drop-in for x402. The provider does not change. Adoption is a client-side decision by the agent.
  • One score for paid and probe traffic. Escrow verdicts and probe attestations share one registry and one formula, so a provider cannot behave well for probes and badly for paying agents without it showing.
  • Slow to trust, fast to doubt. The 7-day half-life, the 25-attestation and 5-Watcher minimums and the 10% per-Watcher cap mean no single party can pump a score, while a run of failures moves it quickly.