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

# Architecture

> How Orica's on-chain and off-chain components work together.

Orica combines the security of Solana smart contracts with the performance of a centralized indexer to deliver a seamless prediction market experience.

***

## System Overview

```mermaid theme={"dark"}
flowchart TB
    subgraph Users["User Applications"]
        Frontend["Web Frontend"]
        Bot["Trading Bot"]
        Analytics["Analytics Dashboard"]
    end

    subgraph Solana["Solana Blockchain"]
        OricaProgram["Orica Program"]
        DisputesProgram["Disputes Program"]
        MarketAccounts["Market Accounts"]
        PositionAccounts["Position Accounts"]
    end

    subgraph OricaCloud["Orica Cloud"]
        API["Public API"]
        Indexer["Indexer Service"]
        Database["PostgreSQL"]
    end

    Frontend --> |"Read Data"| API
    Frontend --> |"Sign & Send Tx"| Solana
    Bot --> |"Read Data"| API
    Bot --> |"Sign & Send Tx"| Solana
    Analytics --> |"Read Data"| API

    Indexer --> |"Subscribe"| Solana
    Indexer --> |"Write"| Database
    API --> |"Query"| Database
```

***

## On-Chain Components

> [card] Orica Program
>
> **Program ID**: `oEarJ8xDDssLcWwgkSpRVVbmiUyeDnoHFNAHPp6eetw`
>
> Handles:
>
> * Market creation
> * Trading (buy/sell)
> * Redemption
> * Fee collection

> [card] Disputes Program
>
> **Program ID**: `oVEzkDiY2FZP4ADfCeUfrg8jgCoMnPcVQao99indSqN`
>
> Handles:
>
> * Dispute initiation
> * Weighted voting
> * Message posting
> * Resolution override

***

## Account Types

| Account | Description | Derivation |
| - | - | - |
| `GlobalState` | Protocol configuration and fee settings | `["global_state"]` |
| `Market` | Individual market state | `["market", global_state, market_id]` |
| `Position` | User's shares in a market | `["position", market, user]` |
| `Dispute` | Dispute state for a market | `["dispute", market]` |
| `DisputeVote` | User's vote in a dispute | `["dispute_vote", dispute, user]` |
| `DisputeMessage` | On-chain chat message | `["message", dispute, author, index]` |

***

## Off-Chain Components

### Indexer Service

The indexer continuously monitors the Solana blockchain for:

* New markets created
* Trades executed
* Market resolutions
* Dispute activity

It parses transaction logs and account updates, then writes structured data to the database.

> [!NOTE]
>
> The indexer uses Solana's WebSocket subscription to receive updates in real-time, typically within 1-2 seconds of block confirmation.

### Public API

The API provides:

* **REST endpoints**: Query markets, trades, disputes, and analytics
* **WebSocket streams**: Real-time price updates and trade activity

All data served by the API is derived from the blockchain via the indexer.

### AI Resolution System

The auto-resolver is a **multi-agent AI daemon** that monitors closed markets and autonomously determines outcomes:

```mermaid theme={"dark"}
flowchart TB
    subgraph Daemon["Auto-Resolver Daemon"]
        Monitor["Market Monitor"]
        Semaphore["Concurrency Controller<br/>(max 100 parallel)"]
    end

    subgraph AgentPool["Agent Pool"]
        Agent1["Resolution Agent 1"]
        Agent2["Resolution Agent 2"]
        AgentN["Resolution Agent N"]
    end

    subgraph SubWorkers["Sub-Worker Layer"]
        Search["Search Workers"]
        Scrape["Intelligent Scrape Agents"]
        SubAI["Sub-AI Analyzers"]
    end

    subgraph Crawlers["Extraction Crawlers"]
        MD["Markdown"]
        JSON["JSON Schema"]
        Screen["Screenshot"]
        Links["Link Graph"]
    end

    Monitor -->|"Closed Markets"| Semaphore
    Semaphore --> Agent1 & Agent2 & AgentN
    Agent1 & Agent2 & AgentN --> Search & Scrape
    Scrape --> SubAI
    SubAI --> MD & JSON & Screen & Links
```

**Key characteristics:**

* **Parallel Processing**: Up to 100 markets resolved simultaneously via semaphore-controlled concurrency
* **Hierarchical Agents**: Primary orchestrator delegates to specialized sub-AI workers for scraping
* **Multi-Format Extraction**: Sub-crawlers support markdown, JSON schemas, screenshots, and link discovery
* **Agentic Loops**: Orchestrator runs up to 20 iterations; sub-AI scrapers run up to 5 iterations each
* **Immutable Proofs**: Full reasoning chains persisted to IPFS via Pinata

***

## Data Flow

**1. User Signs Transaction**

A user's wallet signs a transaction (e.g., buy shares) and broadcasts it to Solana.

**2. Program Executes**

The Orica program validates the instruction, updates market state, and transfers tokens.

**3. Indexer Receives Update**

The indexer's WebSocket subscription receives the confirmed transaction.

**4. Database Updated**

The indexer parses the transaction, extracts relevant data, and writes to PostgreSQL.

**5. API Serves Data**

Clients query the API and receive the updated data with low latency.

***

## Why Use the API?

Querying Solana directly has limitations:

* **No complex queries**: Can't sort, filter, or aggregate efficiently
* **No historical data**: Account state only shows current values
* **Rate limits**: RPC nodes have strict call limits
* **Latency**: Multiple RPC calls required for complete data

The Orica API solves these by providing:

* Pre-computed aggregations (volume, trade count)
* Historical snapshots (price history, trade history)
* Efficient pagination and filtering
* WebSocket streams for real-time updates

***

## Security Model

| Component | Trust Assumptions |
| - | - |
| On-chain programs | Trustless - Code is immutable and verifiable |
| Market vaults | Trustless - Controlled by PDAs, not keys |
| Indexer | Trust to accurately reflect on-chain state |
| API | Trust for data availability (not correctness) |

> [!WARNING]
>
> While the API is trusted for data availability, **all writes must go through the blockchain**. The API cannot modify on-chain state.

***

## Next Steps

> [card] [On-Chain Programs](https://docs.orica.markets/guides/on-chain-programs.md)
>
> Deep dive into program instructions.

> [card] [Indexer](https://docs.orica.markets/guides/indexer.md)
>
> Learn how the indexer processes data.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.