> ## Documentation Index
> Fetch the complete documentation index at: https://docs.darkpool.fun/llms.txt
> Use this file to discover all available pages before exploring further.

# Architecture

> How DarkPool layers on top of DeepBook Predict.

DarkPool is **not** a reimplementation of a prediction market. DeepBook Predict already provides the core primitives: markets, oracle-priced positions, shared vault liquidity, PLP shares. DarkPool **augments** Predict with three things Predict does not have on its own: position privacy, agent-native delegation, and arbitrary-event resolution.

## The three augmentations

| Layer      | Predict provides           | DarkPool adds                                                                                                                                   |
| ---------- | -------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
| Markets    | Price-only via `OracleSVI` | Templated per-market YES/NO Move packages trading on DeepBook V3 pools, plus `oo_resolution` for non-price questions (30-min auto-finalize)     |
| Privacy    | Public positions           | `DarkPoolVault`. Pooled V3 BalanceManager (k-anonymity), live on testnet with a TradeCap keeper loop                                            |
| Agents     | None                       | `TradeAgent` registry + TradeCap delegation (no withdrawal rights) + native LLM mode                                                            |
| Settlement | Per-user `redeem`          | Auto-settle keeper + `settlement::distribute_fees` (1% protocol / 0.5% resolver / 0.5% creator)                                                 |
| Backend    | Predict server REST        | `@darkpool/server`. Indexer to Postgres, quote poller to Redis + WS push, write-on-tx confirm                                                   |
| Frontend   | None                       | React + Vite app with live Pyth ticker, TradingView chart, strike book, event markets, mark-to-market positions, agent fleet view, profile P\&L |

## What the V3 pivot bought us

The v0.3 thesis is that **DeepBook V3 is the trading engine for everything**:

| Layer                                 | Job                         | DeepBook primitive                                                      |
| ------------------------------------- | --------------------------- | ----------------------------------------------------------------------- |
| Price markets (`/markets`)            | BTC up/down strikes         | DeepBook **Predict** (existing)                                         |
| Event markets (`/markets` Events tab) | YES/NO binaries on anything | DeepBook **V3 pools** (per-market `Pool<YES,DUSDC>` + `Pool<NO,DUSDC>`) |
| Dark-pool vault (`/dark-pool`)        | Position privacy            | DeepBook V3 **BalanceManager** held by the vault                        |
| AI agents (`/agents`)                 | Key-less delegated trading  | DeepBook V3 **TradeCap**                                                |

The v0.2 internal AMM and Seal-encrypted intent ledger were deleted. They served their purpose but don't fit V3-native architecture.

## Full system

<Frame caption="Signed PTBs go from the React frontend to four on-chain targets. The Docker-composed backend runs api, indexer, quote-worker, resolver, and agent-service, fronted by Postgres and Redis. Pyth Hermes feeds prices to the resolver.">
  <img src="https://mintcdn.com/dp-550c5f99/trXP5ShOf9c6_pwA/images/architecture-system.png?fit=max&auto=format&n=trXP5ShOf9c6_pwA&q=85&s=c7916a5c82df16d000b4c86c2f0fc793" alt="DarkPool full-system architecture. Browser hosts a React + Vite frontend that signs PTBs to DeepBook Predict, DarkPool package, DeepBook V3 pools, and Binary market packages. Backend (Docker compose) runs api on :8081 (Fastify REST + WS), indexer (queryEvents loop), quote-worker (devInspect loop), resolver on :8082 (auto-settle keeper), agent-service on :8083+ (LLM or heuristic), Postgres, and Redis (cache + pubsub). Pyth Hermes feeds prices." width="1024" height="1536" data-path="images/architecture-system.png" />
</Frame>

## On-chain layering

<Frame caption="DarkPool sits on top of Predict and V3. We add three module groups: vault privacy, agent delegation, non-price resolution. Predict and V3 are unchanged. Sui is the foundation.">
  <img src="https://mintcdn.com/dp-550c5f99/trXP5ShOf9c6_pwA/images/architecture-layering.png?fit=max&auto=format&n=trXP5ShOf9c6_pwA&q=85&s=d8b882980b4cefa7f22556165397621f" alt="DarkPool on-chain layering. DarkPool (our code) groups three module pairs: Vault privacy (dark_pool, settlement), Agent delegation (agent, TradeCap), Non-price resolution (oo_resolution, market). It builds on DeepBook Predict (Predict shared, PredictManager per user, OracleSVI per asset and expiry, Vault + PLP shares). Predict integrates with DeepBook V3 (BalanceManager, TradeCap / TradeProof). V3 runs on the Sui base layer." width="1024" height="1536" data-path="images/architecture-layering.png" />
</Frame>

## Sui-unique advantages

1. **Atomic PTB settlement.** Pyth price update + OracleSVI settle + position redemption + fee distribution in one transaction.
2. **TradeCap delegation.** Agents trade without withdrawal rights via DeepBook V3's existing capability pattern.
3. **Move-native Optimistic Oracle.** Bond-backed propose/dispute on-chain, settles in minutes.
4. **PLP share-based liquidity.** AI agents act as 24/7 vault suppliers.

## Invariants

1. **Attribution.** `predict_facade::attribute_*` is wired into the resolver's settlement PTB and `scripts/supply-plp.ts`. Frontend and agent-service mints are unattributed.
2. **Predict pin.** `predict-testnet-4-16`. Never reference `main`.
3. **Env.** `.env` is gitignored, `.env.example` is the schema, zod throws on missing required vars.
4. **Binary market = one Move publish.** Slug must match `/^[a-z0-9_]+$/`. Registry on disk is authoritative.
5. **DUSDC** is the only quote asset Predict accepts: `0xe95040…::dusdc::DUSDC`.
6. **`agent::pause` and `resume` emit no events.** Authoritative source is `sui.getObject(TradeAgent).is_active`.

Full list: [Invariants & Conventions](/reference/invariants).