Architecture

How Bench is built — from source adapters to on-chain anchoring.

System Overview


┌─────────────────────────────────────────────────────────────────┐
│                        Agent / Client                           │
│                    POST /v1/certify                              │
└──────────────────────────┬──────────────────────────────────────┘
                           │
                           ▼
┌─────────────────────────────────────────────────────────────────┐
│                      Attestor API (Hono)                        │
│  ┌──────────────────────────────────────────────────────────┐   │
│  │                  Source Adapters (13)                      │   │
│  │  1inch │ Paraswap │ KyberSwap │ OKX │ OpenOcean │ ...    │   │
│  │        Parallel fan-out, normalized responses             │   │
│  └──────────────────────────┬───────────────────────────────┘   │
│                              │                                   │
│  ┌──────────────────────────▼───────────────────────────────┐   │
│  │              Consensus Engine                              │   │
│  │  Outlier removal → Weighted median → Agreement score      │   │
│  └──────────────────────────┬───────────────────────────────┘   │
│                              │                                   │
│  ┌──────────────────────────▼───────────────────────────────┐   │
│  │            Certificate Builder                             │   │
│  │  Canonical hash (sorted-key JSON) → EIP-712 signing       │   │
│  └──────────────────────────┬───────────────────────────────┘   │
│                              │                                   │
└──────────────────────────────┼──────────────────────────────────┘
                               │
              ┌────────────────┼────────────────┐
              ▼                ▼                ▼
┌──────────────────┐ ┌──────────────┐ ┌────────────────┐
│   PostgreSQL     │ │    Redis     │ │  BenchRegistry │
│  7 tables        │ │  quote cache │ │  X Layer (196) │
│  cert history    │ │  TTL = 12s   │ │  on-chain      │
└──────────────────┘ └──────────────┘ └────────────────┘

Component Breakdown

@bench/shared

Core types, canonical hashing (sorted-key JSON, RFC 8785 subset), EIP-712 signing utilities, and BEC v2 constants. Zero external dependencies.

@bench/attestor

13 source adapters, consensus engine, certificate builder, and Hono API server. Each adapter normalizes quotes to a standard format. The consensus engine computes weighted median, agreement scores, and certification levels.

@bench/contracts

BenchRegistry.sol (Solidity 0.8.24) — on-chain certificate anchoring. Stores cert hashes with attestor address and timestamp. Supports single and batch anchoring.

@bench/db

PostgreSQL schema (7 tables) for certificate history, agent profiles, and aggregator performance. Redis layer for quote caching (12s TTL).

@bench/skill

OKX Onchain OS plugin (BenchSkill SDK) — allows agents in the Onchain OS ecosystem to access Bench natively.

@usebench/verifier

Independent verification package. Zero internal dependencies — only uses ethers.js. Anyone can verify a certificate without trusting Bench infrastructure.

@bench/explorer

Next.js 15 dashboard with 7+ routes. Displays live certificates, aggregator rankings, agent leaderboards, and comprehensive documentation.

Trust Model

Bench minimizes trust assumptions at every layer:

Price DataMulti-source consensus

No single source is trusted. The weighted median of 13 independent sources provides the consensus price. Outliers are automatically removed.

Certificate IntegrityCryptographic signing

Certificates are signed with EIP-712 typed data. The signature is verifiable by anyone with the attestor's public key. Tampering is detectable.

Canonical HashingDeterministic serialization

Certificate hashes use sorted-key JSON (RFC 8785 subset). Same input always produces the same hash — no ambiguity, no manipulation.

On-Chain RecordBlockchain immutability

Once anchored to BenchRegistry, certificate records cannot be modified or deleted. X Layer provides the immutability guarantee.

Independent VerificationOpen-source verifier

@usebench/verifier has zero internal dependencies. It reconstructs the expected hash and recovers the signer — no Bench API calls needed.

Data Flow

  1. 1Agent sends POST /v1/certify with token pair, amount, and chain
  2. 2Attestor checks Redis cache for recent quotes (TTL 12s)
  3. 3If cache miss: fan out to all 13 adapters in parallel
  4. 4Each adapter normalizes its response to the standard SourceQuote format
  5. 5Consensus engine: outlier removal → weighted median → agreement scoring
  6. 6Certificate builder: canonical hash → EIP-712 sign → BEC v2 certificate
  7. 7Certificate stored in PostgreSQL, cache updated in Redis
  8. 8Certificate anchored to BenchRegistry on X Layer (async)
  9. 9Signed certificate returned to agent
← Integration GuideFAQ →