Soothsayer ZK Oracle Architecture

Off-chain service architecture for trustless prediction market resolution. Category-based adapter registry with 15 data source adapters across 6 domains, zkTLS attestation via Primus, and on-chain settlement.

Layer 1 — User Interface (test-ui)
Intent Input (NL)
Rule-Based NLP Parser
Gemini LLM Fallback
Market Definition Polisher
Results Display
Layer 2 — Category Registry (CategoryDescriptor pattern)
Crypto
Cryptocurrency prices, exchange info, global market data
  • binance-priceBinance
  • binance-exchange-infoBinance
  • coingecko-priceCoinGecko
  • coingecko-globalCoinGecko
DeFi
Protocol TVL, chain-level metrics, DeFi ecosystem
  • defillama-tvlDefiLlama
  • defillama-chainsDefiLlama
Blockchain
On-chain infrastructure, gas, transaction counts
  • etherscan-gasEtherscan
  • etherscan-txcountEtherscan
Sentiment
Market sentiment indices and fear/greed indicators
  • alternative-me-fngAlternative.me
Equities
Traditional stock market data and equity prices
  • yahoo-financeYahoo Finance
Sports
NBA, FIFA, soccer leagues, LoL/CS2/Dota2 esports
  • balldontlie-nbaBallDontLie
  • balldontlie-fifaBallDontLie
  • balldontlie-esportsBallDontLie
  • football-datafootball-data.org
  • pandascorePandaScore
Layer 3 — Service Layer
Evaluator
Comparison logic engine supporting GT, LT, EQ, GTE, LTE, NEQ, CONTAINS operators against adapter output
evaluate(actual, op, threshold)
Resolver
Resolution service that orchestrates adapter fetch, evaluation, and result packaging into ResolutionResult
resolve(request) → ResolutionResult
Serviceability Assessor
Maps URLs and adapter names to the correct CategoryDescriptor and validates market serviceability
findAdapterForUrl(url)
Layer 4 — Keeper (separate package)
  • Market Monitor Event polling for pending resolutions
  • Settlement Keeper Resolution strategies + execution
  • Primus zkTLS Client Attestation generation via Primus
Layer 5 — On-Chain
  • ZkOracleAdjudicator.sol Smart contract adjudicator
  • TruthMarket Contracts Prediction market settlement
  • Primus zkTLS Verification On-chain attestation verify
Data Flow — End-to-End Resolution
01
User types question → NLP Parser → structured ResolutionRequest
02
Category Registry routes request to correct adapter via keywords + URL patterns
03
Adapter fetches Web2 API data → Evaluator compares against threshold
04
Keeper monitors on-chain → triggers resolution → fetches Primus attestation
05
Attestation submitted on-chain → ZkOracleAdjudicator verifies → market settles
External APIs — 8 Data Sources
Binance API
Crypto
CoinGecko API
Crypto
DefiLlama API
DeFi
Etherscan API
Blockchain
Alternative.me
Sentiment
Yahoo Finance
Equities
BallDontLie API
Sports
Google Gemini
AI / NLP
UI Layer
Category Registry
Service Layer
Keeper (off-chain)
On-Chain
15 adapters / 6 categories / 8 external APIs