How sailfish-finance/predictions-contract works
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)