# sailfish-finance/predictions-contract architecture

> Architecture diagram of the GitHub repository sailfish-finance/predictions-contract, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-13). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/sailfish-finance/predictions-contract
- Repository: https://github.com/sailfish-finance/predictions-contract

## Overview

##### Project Type and Purpose
- This is an Ethereum smart‐contract project for a prediction market (“SailFish Prediction”) that integrates a V3 price oracle (Uniswap V3 or similar).
- It consists of on‐chain Solidity contracts (prediction logic + oracle integration) and off‐chain Node.js/Hardhat scripts to deploy, manage rounds, and orchestrate contract calls.

##### File Structure Analysis
- contracts/
- oracle/ – base contracts, interfaces, libraries, utils for pulling V3 price data
- predictions/ – core prediction market contracts (round logic, locking, execution)
- readme.md – local README for contract subfolders
- scripts/ – deployment and operational scripts (start/lock/execute rounds)
- test/ – TypeScript tests for prediction flows
- hardhat.config.js – Hardhat setup for compilation, testing, networks
- ignition/ – auxiliary modules (e.g., Lock.js for runtime orchestration)
- package.json & lockfile – Node.js dependencies

##### Reading the README
- Describes network addresses for the oracle and prediction markets
- Outlines “kick-start,” “continue,” and “resume” round operations through specific function calls

a. Main Components
1. Users/Clients (wallets, UIs, or other services)
2. Off-chain Orchestrator (Node.js scripts + ignition modules)
3. Hardhat Tooling (compilation, tests, local fork)
4. Smart Contracts on Ethereum
– Prediction Contract Module
– Oracle Integration Module (V3 price oracle interfaces & libraries)
5. External Price Oracle Feed (Uniswap V3 pool or a Chainlink‐style feed)
6. Ethereum Networks (Mainnet / Testnet)
b. Relationships & Interactions
– Users send transactions (place bets, withdraw) to the Prediction Contract.
– Orchestrator scripts call startGenesisRound(), lockGenesisRound(), executeRound(), pause(), unpause() on the Prediction Contract at designated blocks.
– Prediction Contract fetches price data from the Oracle Module, which in turn reads on‐chain V3 pool observations.
– Hardhat config drives compilation, local testing, and deployment to networks.
– Tests invoke contract methods via ethers.js to validate round logic.
c. Architectural Patterns & Principles
– Modular contract design: interfaces, base classes, and utility libraries in /contracts/oracle
– Clear separation of on-chain logic (contracts) vs. off-chain orchestration (scripts, ignition)
– Use of standardized Oracle interface patterns to allow swapping or upgrading data sources
– Asynchronous, event/block‐driven execution flow for rounds
d. Key Technologies
– Solidity for contracts
– Hardhat & ethers.js for build, test, deploy
– Node.js scripts (JavaScript) for runtime orchestration
– TypeScript for tests
– Uniswap V3 or similar oracle for price data

##### Diagramming Details
- From Orchestrator → Prediction Contract (function calls)
- Prediction Contract → Oracle Module → External Feed (data requests)
- Users → Prediction Contract (bet/place/withdraw transactions)
- Labels & Legends:
- Network endpoints (Mainnet RPC, Testnet RPC)
- Timing triggers (lockBlock = now + intervalBlocks)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Users
    Users["Users/Clients\n(wallets, UIs)"]:::external

    %% External Price Feed
    ExtOracleFeed((External Price Oracle Feed)):::external

    %% Ethereum Network
    EthereumNet[(Ethereum Blockchain\nMainnet/Testnet)]:::blockchain

    %% On-Chain Contracts
    subgraph "On-Chain Contracts" 
        direction TB
        PredMod["Prediction Contract Module"]:::onchain
        subgraph "Oracle Integration Module"
            direction TB
            OracleInterfaces["interfaces"]:::onchain
            OracleInterface["interface"]:::onchain
            OracleBase["base"]:::onchain
            OracleLibraries["libraries"]:::onchain
            OracleUtils["utils"]:::onchain
        end
        ReadmeContracts["contracts/readme.md"]:::docs
    end

    %% Off-Chain Orchestrator
    subgraph "Off-Chain Orchestrator" 
        direction TB
        DeployPred["deploy-prediction-v2.js"]:::offchain
        DeployOracle["deploy-v3-oracle.js"]:::offchain
        CheckOracle["check-oracle-compilation.js"]:::offchain
        LockModule["ignition/modules/Lock.js"]:::offchain
    end

    %% Dev & DevOps Tools
    subgraph "Development & Tooling" 
        direction TB
        HardhatNode["hardhat.config.js"]:::devtools
        TestHarness["test/prediction.test.ts"]:::devtools
        DocsHow["docs/HowItWorks.md"]:::docs
        DocsPred["docs/Prediction.md"]:::docs
        PackageJSON["package.json"]:::docs
        PackageLock["package-lock.json"]:::docs
        RootReadme["README.md"]:::docs
    end

    %% Relationships
    Users -->|"bets/place/withdraw"| PredMod
    DeployPred -->|"startGenesisRound(), lockGenesisRound(), executeRound()"| PredMod
    DeployOracle -->|deploy oracle contracts| PredMod
    CheckOracle -->|verify oracle build| OracleInterface
    LockModule -->|"runtime orchestration"| DeployPred

    PredMod -->|"fetchPrice()"| OracleInterface
    OracleInterface -->|"uses base logic"| OracleBase
    OracleBase -->|"uses libraries"| OracleLibraries
    OracleLibraries -->|"utility functions"| OracleUtils
    OracleUtils -->|"reads observations"| ExtOracleFeed

    HardhatNode -->|"compile/deploy/test"| EthereumNet
    TestHarness -->|"ethers.js calls"| PredMod

    PredMod --> EthereumNet
    OracleInterface --> EthereumNet

    %% Click Events
    click PredMod "https://github.com/sailfish-finance/predictions-contract/tree/main/contracts/predictions/"
    click OracleInterface "https://github.com/sailfish-finance/predictions-contract/tree/main/contracts/oracle/interface/"
    click OracleInterfaces "https://github.com/sailfish-finance/predictions-contract/tree/main/contracts/oracle/interfaces/"
    click OracleBase "https://github.com/sailfish-finance/predictions-contract/tree/main/contracts/oracle/base/"
    click OracleLibraries "https://github.com/sailfish-finance/predictions-contract/tree/main/contracts/oracle/libraries/"
    click OracleUtils "https://github.com/sailfish-finance/predictions-contract/tree/main/contracts/oracle/utils/"
    click DeployPred "https://github.com/sailfish-finance/predictions-contract/blob/main/scripts/deploy-prediction-v2.js"
    click DeployOracle "https://github.com/sailfish-finance/predictions-contract/blob/main/scripts/deploy-v3-oracle.js"
    click CheckOracle "https://github.com/sailfish-finance/predictions-contract/blob/main/scripts/check-oracle-compilation.js"
    click LockModule "https://github.com/sailfish-finance/predictions-contract/blob/main/ignition/modules/Lock.js"
    click HardhatNode "https://github.com/sailfish-finance/predictions-contract/blob/main/hardhat.config.js"
    click TestHarness "https://github.com/sailfish-finance/predictions-contract/blob/main/test/prediction.test.ts"
    click DocsHow "https://github.com/sailfish-finance/predictions-contract/blob/main/docs/HowItWorks.md"
    click DocsPred "https://github.com/sailfish-finance/predictions-contract/blob/main/docs/Prediction.md"
    click PackageJSON "https://github.com/sailfish-finance/predictions-contract/blob/main/package.json"
    click PackageLock "https://github.com/sailfish-finance/predictions-contract/blob/main/package-lock.json"
    click RootReadme "https://github.com/sailfish-finance/predictions-contract/blob/main/README.md"
    click ReadmeContracts "https://github.com/sailfish-finance/predictions-contract/blob/main/contracts/readme.md"

    %% Styles
    classDef onchain fill:#E0F7FA,stroke:#00796B,stroke-width:2px
    classDef offchain fill:#E8F5E9,stroke:#388E3C,stroke-width:2px
    classDef blockchain fill:#CFD8DC,stroke:#607D8B,stroke-width:2px,stroke-dasharray: 5 5
    classDef external fill:#FFF3E0,stroke:#FB8C00,stroke-width:2px
    classDef devtools fill:#F3E5F5,stroke:#8E24AA,stroke-width:2px
    classDef docs fill:#ECEFF1,stroke:#546E7A,stroke-width:2px
```
