Skip to content

architecture.md

Latest commit

 

History

History
110 lines (89 loc) · 5.31 KB

architecture.md

File metadata and controls

110 lines (89 loc) · 5.31 KB
Raw

Architecture

Agent Bounties separates an autonomous custody protocol from an open hosted coordination layer.

Trust Boundary

Base native USDC custody, canonical bounty configuration, claims, submissions, verdict authorization, payouts, and refunds live in immutable per-bounty contracts. The hosted network cannot release those funds and has no settlement signer.

Search, routing, terms publication, evidence preimages, attribution, public profiles, templates, reputation, analytics, and notifications remain off-chain. Those services improve coordination but do not control custody.

Components

  • AgentBountyFactory: deploys deterministic canonical EIP-1167 clones and optionally funds them through token approval or EIP-3009 authorization.
  • AgentBounty: isolates one bounty's USDC, immutable verifier policy, solver bond, settlement, timeout, and refund state.
  • chain-base: builds exact calldata and EIP-712 payloads, decodes canonical events, validates terms/config agreement, and derives work/verifier feeds.
  • worker: scans the factory and canonical clones in confirmed block ranges, using bounded multi-address RPC batches.
  • db: persists terms, evidence preimages, canonical events, cursors, and the broader product graph in Postgres. Objective aggregates use revision-checked compare-and-swap updates so concurrent signed actions cannot overwrite one another.
  • api: exposes OpenAPI planners, feeds, evidence publication, and public protocol state. It also owns the credential-isolated, quota-bounded hosted cloud drafting adapter; model output has draft-only authority.
  • mcp-server: exposes the same operations as machine-native tools and proxies cloud drafting without receiving the model credential.
  • web-public and site: publish discovery, post/fund/earn flows, proof boundaries, and the distribution loop.
  • verifier-sdk: defines deterministic verifier adapters and fixtures.
  • eval-harness: runs routing, template, verifier, proof, and abuse loops.
  • ops/self-healing-policy.json plus scripts/self_heal.py: classifies trusted runtime observations into bounded automatic recovery or explicit containment. It has no signer, settlement authority, secret rotation, or destructive data path.

See cloud-agent-operations.md for the no-local-model runtime boundary and production readiness contract.

Data Flow

poster -> publish canonical terms -> factory plan -> wallet signature
       -> factory + bounty events -> confirmed indexer -> canonical feed

solver -> claim + bond -> execute task -> submit commitments
       -> publish matching evidence preimages -> verification job feed

verifier agents -> deterministic proof or scoped EIP-712 quorum
                -> canonical contract -> pass payout or funded reopen
                -> confirmed events -> proof/reputation/distribution surfaces

requesting party -> signed objective -> provider proposal -> authority acceptance
                 -> contribution DAG -> signed in-kind verification
                 -> canonical BountySettled reconciliation for paid work
                 -> final verification -> completed objective

Sources Of Truth

  • Canonical factory and implementation: site/protocol.json plus verified deployment evidence.
  • Bounty configuration: four factory creation events joined to the content-addressed terms document.
  • Funding and lifecycle: confirmed canonical clone events.
  • Solver payment: BountySettled only.
  • Objective coordination: the latest revisioned Postgres aggregate plus its recorded wallet approvals. It coordinates state but never proves payment.
  • Stripe or PayPal: future fiat-to-USDC convenience onramps, never autonomous settlement authorities.
  • GitHub comments, PR status, hosted database rows, planner responses, signatures, and transaction hashes: coordination evidence only.

Runtime Modes

Without DATABASE_URL, API and MCP services support local deterministic demos. Hosted canonical discovery requires shared Postgres because terms, evidence, events, and index cursors must survive restarts and be consistent across services.

The worker owns chain ingestion. It advances its cursor only after decoded events are persisted. API and MCP planners fail closed when the database, factory configuration, terms, or canonical event graph is unavailable.

API and MCP process availability is supervised through /health; durable freshness uses separate readiness evidence. The worker retries only typed RPC and SQL transport failures from its persisted monotonic cursor with capped backoff, then exits after a bounded failure budget so the platform can replace the process. Unclassified or integrity failures write a redacted failed heartbeat and halt ingestion. Recovery never moves the cursor backward or treats replay as new economic evidence.

Verification Boundary

Deterministic modules settle from an immutable on-chain result. Signed and AI quorums settle from exact EIP-712 signatures by the precommitted verifier set. AI quality filters used in product development remain advisory. An autonomous AI judge gains settlement authority only as one member of the immutable on-chain quorum, never from a raw model response or hosted API decision.

See autonomous-protocol.md for financial invariants, event schemas, timeout behavior, and known limits.