From 5449124ee8c6c5674022a55d95085944a9ef2596 Mon Sep 17 00:00:00 2001 From: macnelson9 Date: Wed, 25 Feb 2026 17:34:44 +0100 Subject: [PATCH] docs: developer onboarding documentation --- ARCHITECTURE.md | 597 ++++++++++++++++++++++++++++++++++++++++++ CONTRIBUTING.md | 567 ++++++++++++++++++++++++++++++++++++++++ DEVELOPMENT.md | 682 ++++++++++++++++++++++++++++++++++++++++++++++++ 3 files changed, 1846 insertions(+) create mode 100644 ARCHITECTURE.md create mode 100644 CONTRIBUTING.md create mode 100644 DEVELOPMENT.md diff --git a/ARCHITECTURE.md b/ARCHITECTURE.md new file mode 100644 index 0000000..4f44c3d --- /dev/null +++ b/ARCHITECTURE.md @@ -0,0 +1,597 @@ +# PredictIQ Architecture + +Comprehensive architecture documentation for the PredictIQ prediction market platform. + +## Table of Contents + +- [System Overview](#system-overview) +- [Architecture Principles](#architecture-principles) +- [Smart Contract Architecture](#smart-contract-architecture) +- [Module Design](#module-design) +- [Data Flow](#data-flow) +- [Oracle Integration](#oracle-integration) +- [Security Architecture](#security-architecture) +- [Scalability Considerations](#scalability-considerations) + +## System Overview + +PredictIQ is a decentralized prediction market platform built on Stellar's Soroban smart contract platform. The system enables users to create and participate in prediction markets with hybrid resolution mechanisms combining oracle data and community voting. + +### High-Level Architecture + +``` +┌─────────────────────────────────────────────────────────────┐ +│ Frontend Layer │ +│ (Web App, Mobile App, Third-party Integrations) │ +└────────────────────┬────────────────────────────────────────┘ + │ + │ JSON-RPC / REST API + │ +┌────────────────────▼────────────────────────────────────────┐ +│ Stellar Blockchain │ +│ ┌──────────────────────────────────────────────────────┐ │ +│ │ PredictIQ Smart Contract │ │ +│ │ ┌────────┐ ┌────────┐ ┌────────┐ ┌────────┐ │ │ +│ │ │Markets │ │ Bets │ │Oracles │ │ Voting │ │ │ +│ │ └────────┘ └────────┘ └────────┘ └────────┘ │ │ +│ │ ┌────────┐ ┌────────┐ ┌────────┐ ┌────────┐ │ │ +│ │ │Disputes│ │ Fees │ │ Admin │ │Circuit │ │ │ +│ │ └────────┘ └────────┘ └────────┘ │Breaker │ │ │ +│ │ └────────┘ │ │ +│ └──────────────────────────────────────────────────────┘ │ +└────────────────────┬────────────────────────────────────────┘ + │ + │ Oracle Feeds + │ +┌────────────────────▼────────────────────────────────────────┐ +│ Oracle Providers │ +│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │ +│ │Pyth Network │ │ Reflector │ │Custom Oracles│ │ +│ └──────────────┘ └──────────────┘ └──────────────┘ │ +└─────────────────────────────────────────────────────────────┘ +``` + +### Core Components + +1. **Smart Contract Layer**: Soroban smart contracts handling all business logic +2. **Oracle Layer**: External data providers (Pyth, Reflector) +3. **Storage Layer**: On-chain persistent storage +4. **Event Layer**: Contract events for off-chain indexing +5. **Frontend Layer**: User interfaces and integrations + +## Architecture Principles + +### 1. Modularity + +The contract is organized into independent modules, each responsible for a specific domain: + +- **Separation of Concerns**: Each module handles one aspect of functionality +- **Loose Coupling**: Modules interact through well-defined interfaces +- **High Cohesion**: Related functionality is grouped together + +### 2. Security First + +- **Access Control**: Role-based permissions for sensitive operations +- **Input Validation**: All inputs validated before processing +- **Circuit Breaker**: Emergency pause mechanism for critical issues +- **Fail-Safe Defaults**: Secure defaults for all configurations + +### 3. Gas Optimization + +- **Efficient Storage**: Minimized storage operations +- **Batch Operations**: Support for batching where possible +- **Lazy Loading**: Data loaded only when needed +- **Event-Driven**: Use events instead of storage for historical data + +### 4. Extensibility + +- **Plugin Architecture**: Easy to add new oracle providers +- **Upgradeable Design**: Support for future enhancements +- **Configurable Parameters**: Admin-adjustable settings + +## Smart Contract Architecture + +### Contract Structure + +```rust +PredictIQContract +├── Storage +│ ├── Markets (Map) +│ ├── Bets (Map<(u64, Address), Bet>) +│ ├── Votes (Map<(u64, Address), Vote>) +│ ├── Config (Admin, Fees, etc.) +│ └── Monitoring (Error counts, metrics) +├── Modules +│ ├── admin.rs # Admin functions +│ ├── markets.rs # Market management +│ ├── bets.rs # Betting logic +│ ├── oracles.rs # Oracle integration +│ ├── voting.rs # Voting system +│ ├── disputes.rs # Dispute resolution +│ ├── fees.rs # Fee management +│ ├── governance.rs # Governance functions +│ ├── circuit_breaker.rs # Emergency controls +│ ├── monitoring.rs # System monitoring +│ └── events.rs # Event definitions +└── Types + ├── Market # Market data structure + ├── Bet # Bet data structure + ├── Vote # Vote data structure + └── ErrorCode # Error definitions +``` + +### Data Structures + +#### Market + +```rust +pub struct Market { + pub id: u64, + pub creator: Address, + pub title: String, + pub description: String, + pub outcomes: Vec, + pub deadline: u64, + pub status: MarketStatus, + pub resolution_source: ResolutionSource, + pub winning_outcome: Option, + pub total_volume: i128, + pub outcome_volumes: Vec, + pub created_at: u64, + pub resolved_at: Option, +} + +pub enum MarketStatus { + Active, + Closed, + PendingResolution, + Disputed, + Resolved, + Cancelled, +} + +pub enum ResolutionSource { + Oracle, + Voting, + Hybrid, +} +``` + +#### Bet + +```rust +pub struct Bet { + pub bettor: Address, + pub market_id: u64, + pub outcome: u32, + pub amount: i128, + pub odds: u32, + pub placed_at: u64, + pub claimed: bool, +} +``` + +#### Vote + +```rust +pub struct Vote { + pub voter: Address, + pub market_id: u64, + pub outcome: u32, + pub weight: i128, + pub voted_at: u64, +} +``` + +## Module Design + +### Markets Module + +**Responsibility**: Market creation, lifecycle management, and queries + +**Key Functions**: +- `create_market()`: Create new prediction market +- `get_market()`: Retrieve market data +- `close_market()`: Close market for betting +- `cancel_market()`: Cancel market (admin only) + +**State Transitions**: +``` +Active → Closed → PendingResolution → Resolved + ↓ + Disputed → Resolved +``` + +### Bets Module + +**Responsibility**: Bet placement, tracking, and payout calculation + +**Key Functions**: +- `place_bet()`: Place bet on market outcome +- `get_bet()`: Retrieve bet information +- `calculate_payout()`: Calculate potential winnings +- `claim_winnings()`: Claim winnings after resolution + +**Bet Lifecycle**: +``` +Placed → Active → (Market Resolved) → Claimable → Claimed +``` + +### Oracles Module + +**Responsibility**: Oracle integration and data fetching + +**Supported Oracles**: +1. **Pyth Network**: High-frequency price feeds +2. **Reflector**: Stellar-native oracle +3. **Custom**: Extensible for additional providers + +**Key Functions**: +- `fetch_oracle_result()`: Get result from oracle +- `register_oracle()`: Add new oracle provider +- `set_oracle_priority()`: Configure fallback order + +**Oracle Resolution Flow**: +``` +1. Query Primary Oracle (Pyth) + ↓ (if fails) +2. Query Secondary Oracle (Reflector) + ↓ (if fails) +3. Fallback to Community Voting +``` + +### Voting Module + +**Responsibility**: Community voting for disputed markets + +**Key Functions**: +- `cast_vote()`: Cast vote on disputed market +- `get_vote_results()`: Get current vote tally +- `finalize_vote()`: Finalize voting and resolve market + +**Voting Mechanism**: +- **Weight**: Based on reputation or stake +- **Duration**: Configurable voting period +- **Threshold**: Majority required for resolution +- **Incentives**: Rewards for correct votes + +### Disputes Module + +**Responsibility**: Dispute filing and resolution + +**Key Functions**: +- `file_dispute()`: Challenge market resolution +- `get_dispute_status()`: Check dispute state +- `resolve_dispute()`: Finalize dispute resolution + +**Dispute Process**: +``` +1. Market Resolved (Oracle) + ↓ +2. User Files Dispute (within window) + ↓ +3. Voting Period Opens + ↓ +4. Community Votes + ↓ +5. Dispute Resolved (majority wins) +``` + +### Circuit Breaker Module + +**Responsibility**: Emergency pause mechanism + +**States**: +- `Open`: Normal operation +- `PartialFreeze`: Limited operations (withdrawals only) +- `FullFreeze`: All operations paused + +**Triggers**: +- Manual (admin) +- Automatic (error threshold exceeded) +- Governance vote + +## Data Flow + +### Market Creation Flow + +``` +User → create_market() + ↓ +Validate inputs + ↓ +Check authorization + ↓ +Generate market ID + ↓ +Store market data + ↓ +Emit MarketCreated event + ↓ +Return market ID +``` + +### Bet Placement Flow + +``` +User → place_bet() + ↓ +Validate market exists & active + ↓ +Check deadline not passed + ↓ +Validate outcome index + ↓ +Transfer tokens from user + ↓ +Calculate odds + ↓ +Store bet data + ↓ +Update market volumes + ↓ +Emit BetPlaced event + ↓ +Return success +``` + +### Market Resolution Flow + +``` +Deadline Passed + ↓ +close_market() → Status: Closed + ↓ +resolve_market() + ↓ +Query Oracle + ↓ +┌─────────────┬─────────────┐ +│ Success │ Failure │ +↓ ↓ +Set outcome Open voting + ↓ ↓ +Status: Status: +Resolved PendingResolution + ↓ ↓ +Emit event Wait for votes + ↓ + Finalize vote + ↓ + Status: Resolved +``` + +### Dispute Resolution Flow + +``` +Market Resolved + ↓ +User files dispute (within window) + ↓ +Status: Disputed + ↓ +Voting period opens + ↓ +Users cast votes + ↓ +Voting period ends + ↓ +Tally votes + ↓ +Majority outcome wins + ↓ +Update market outcome + ↓ +Status: Resolved + ↓ +Emit DisputeResolved event +``` + +## Oracle Integration + +### Oracle Architecture + +``` +┌─────────────────────────────────────────┐ +│ PredictIQ Contract │ +│ ┌───────────────────────────────────┐ │ +│ │ Oracle Manager │ │ +│ │ ┌─────────┐ ┌─────────┐ │ │ +│ │ │Priority │ │Fallback │ │ │ +│ │ │ Queue │ │ Logic │ │ │ +│ │ └─────────┘ └─────────┘ │ │ +│ └───────────────────────────────────┘ │ +└─────────────────────────────────────────┘ + │ │ │ + ▼ ▼ ▼ + ┌────────┐ ┌────────┐ ┌────────┐ + │ Pyth │ │Reflect.│ │Custom │ + │Network │ │ Oracle │ │Oracles │ + └────────┘ └────────┘ └────────┘ +``` + +### Oracle Priority System + +1. **Primary**: Pyth Network (high-frequency, institutional-grade) +2. **Secondary**: Reflector (Stellar-native, reliable) +3. **Tertiary**: Custom oracles (market-specific) +4. **Fallback**: Community voting + +### Oracle Data Format + +```rust +pub struct OracleResult { + pub source: String, // Oracle identifier + pub outcome: u32, // Winning outcome index + pub confidence: u32, // Confidence score (0-100) + pub timestamp: u64, // Result timestamp + pub signature: BytesN<64>, // Cryptographic signature +} +``` + +## Security Architecture + +### Access Control + +``` +┌─────────────────────────────────────┐ +│ Access Control │ +├─────────────────────────────────────┤ +│ Admin │ +│ - Set fees │ +│ - Pause contract │ +│ - Update config │ +│ - Emergency actions │ +├─────────────────────────────────────┤ +│ Market Creator │ +│ - Create markets │ +│ - Cancel own markets (conditions) │ +├─────────────────────────────────────┤ +│ Users │ +│ - Place bets │ +│ - Cast votes │ +│ - File disputes │ +│ - Claim winnings │ +└─────────────────────────────────────┘ +``` + +### Security Layers + +1. **Input Validation**: All inputs sanitized and validated +2. **Authorization Checks**: Role-based access control +3. **Reentrancy Protection**: State updates before external calls +4. **Integer Overflow Protection**: Safe math operations +5. **Circuit Breaker**: Emergency pause mechanism +6. **Rate Limiting**: Prevent spam and abuse +7. **Monitoring**: Automatic error detection + +### Threat Mitigation + +| Threat | Mitigation | +|--------|------------| +| Oracle Manipulation | Multiple oracle sources, voting fallback | +| Front-running | Commit-reveal scheme (future) | +| Spam Markets | Market creation fee, reputation system | +| Vote Manipulation | Weighted voting, stake requirements | +| Reentrancy | Checks-effects-interactions pattern | +| Integer Overflow | Checked arithmetic operations | +| Unauthorized Access | Role-based access control | +| DoS Attacks | Rate limiting, gas limits | + +## Scalability Considerations + +### Storage Optimization + +- **Minimal Storage**: Only essential data on-chain +- **Event-Driven**: Historical data via events +- **Pagination**: Large datasets paginated +- **Archival**: Old markets archived off-chain + +### Gas Optimization + +- **Batch Operations**: Multiple operations in one transaction +- **Efficient Data Structures**: Optimized storage layout +- **Lazy Evaluation**: Compute only when needed +- **Caching**: Frequently accessed data cached + +### Performance Targets + +| Metric | Target | +|--------|--------| +| Market Creation | < 0.5s | +| Bet Placement | < 0.3s | +| Market Query | < 0.1s | +| Vote Casting | < 0.3s | +| Resolution | < 1.0s | + +### Horizontal Scaling + +- **Multiple Markets**: Unlimited concurrent markets +- **Sharding**: Future consideration for extreme scale +- **Off-chain Indexing**: Event indexing for queries +- **CDN**: Static content delivery + +## Future Enhancements + +### Planned Features + +1. **Advanced Market Types** + - Scalar markets (price ranges) + - Combinatorial markets + - Conditional markets + +2. **Enhanced Oracle Integration** + - More oracle providers + - Oracle reputation system + - Decentralized oracle network + +3. **Governance** + - DAO structure + - Token-based voting + - Protocol upgrades + +4. **Layer 2 Integration** + - State channels for high-frequency trading + - Rollups for scalability + +5. **Cross-chain Support** + - Bridge to other blockchains + - Multi-chain markets + +### Upgrade Path + +``` +Current: v1.0 (Monolithic Contract) + ↓ +v2.0: Modular Contracts + ↓ +v3.0: DAO Governance + ↓ +v4.0: Cross-chain Support +``` + +## Diagrams + +### System Context Diagram + +``` +┌──────────┐ ┌──────────┐ ┌──────────┐ +│ Users │────▶│PredictIQ │────▶│ Stellar │ +└──────────┘ │ Frontend │ │Blockchain│ + └──────────┘ └──────────┘ + │ │ + ▼ ▼ + ┌──────────┐ ┌──────────┐ + │Analytics │ │ Oracles │ + └──────────┘ └──────────┘ +``` + +### Component Diagram + +``` +┌─────────────────────────────────────────┐ +│ PredictIQ Contract │ +│ │ +│ ┌────────┐ ┌────────┐ ┌────────┐ │ +│ │Markets │ │ Bets │ │Oracles │ │ +│ └───┬────┘ └───┬────┘ └───┬────┘ │ +│ │ │ │ │ +│ └───────────┼────────────┘ │ +│ │ │ +│ ┌─────▼─────┐ │ +│ │ Storage │ │ +│ └───────────┘ │ +└─────────────────────────────────────────┘ +``` + +## References + +- [Stellar Documentation](https://developers.stellar.org/) +- [Soroban Documentation](https://soroban.stellar.org/docs) +- [Pyth Network](https://pyth.network/) +- [Reflector Oracle](https://reflector.network/) + +--- + +For implementation details, see [DEVELOPMENT.md](./DEVELOPMENT.md). +For contribution guidelines, see [CONTRIBUTING.md](./CONTRIBUTING.md). diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..d7fc69c --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,567 @@ +# Contributing to PredictIQ + +Thank you for your interest in contributing to PredictIQ! This guide will help you get started with contributing to our decentralized prediction market platform. + +## Table of Contents + +- [Code of Conduct](#code-of-conduct) +- [Getting Started](#getting-started) +- [Development Workflow](#development-workflow) +- [Coding Standards](#coding-standards) +- [Testing Requirements](#testing-requirements) +- [Commit Guidelines](#commit-guidelines) +- [Pull Request Process](#pull-request-process) +- [Code Review Checklist](#code-review-checklist) +- [Getting Help](#getting-help) + +## Code of Conduct + +We are committed to providing a welcoming and inclusive environment. Please: + +- Be respectful and considerate +- Welcome newcomers and help them get started +- Focus on constructive feedback +- Respect differing viewpoints and experiences +- Accept responsibility and apologize for mistakes + +## Getting Started + +### Prerequisites + +Before contributing, ensure you have: + +1. Read the [DEVELOPMENT.md](./DEVELOPMENT.md) guide +2. Set up your local development environment +3. Familiarized yourself with the [ARCHITECTURE.md](./ARCHITECTURE.md) +4. Reviewed existing issues and pull requests + +### Finding Work + +- Check [GitHub Issues](https://github.com/your-org/predict-iq/issues) for open tasks +- Look for issues labeled `good-first-issue` or `help-wanted` +- Comment on an issue to express interest before starting work +- Ask questions if requirements are unclear + +## Development Workflow + +### 1. Fork and Clone + +```bash +# Fork the repository on GitHub, then clone your fork +git clone https://github.com/YOUR_USERNAME/predict-iq.git +cd predict-iq + +# Add upstream remote +git remote add upstream https://github.com/your-org/predict-iq.git +``` + +### 2. Create a Branch + +```bash +# Update your main branch +git checkout main +git pull upstream main + +# Create a feature branch +git checkout -b feature/your-feature-name +# or +git checkout -b fix/issue-number-description +``` + +### Branch Naming Convention + +- `feature/` - New features (e.g., `feature/add-market-filters`) +- `fix/` - Bug fixes (e.g., `fix/123-resolve-bet-calculation`) +- `docs/` - Documentation updates (e.g., `docs/update-api-guide`) +- `refactor/` - Code refactoring (e.g., `refactor/optimize-oracle-queries`) +- `test/` - Test additions/fixes (e.g., `test/add-market-integration-tests`) +- `chore/` - Maintenance tasks (e.g., `chore/update-dependencies`) + +### 3. Make Changes + +Follow our [coding standards](#coding-standards) and ensure: + +- Code is well-documented +- Tests are included +- No linting errors +- Commits follow our guidelines + +### 4. Test Your Changes + +```bash +# Run all tests +make test + +# Run specific test suites +cargo test --lib # Unit tests +cargo test --test integration_test # Integration tests + +# Check formatting +cargo fmt --all -- --check + +# Run linter +cargo clippy -- -D warnings +``` + +### 5. Commit Your Changes + +Follow our [commit guidelines](#commit-guidelines): + +```bash +git add . +git commit -m "feat: add market filtering by category" +``` + +### 6. Push and Create PR + +```bash +# Push to your fork +git push origin feature/your-feature-name + +# Create a Pull Request on GitHub +``` + +## Coding Standards + +### Rust Code Style + +We follow the official Rust style guide with some additions: + +#### Formatting + +```bash +# Format all code before committing +cargo fmt --all +``` + +#### Naming Conventions + +```rust +// Constants: SCREAMING_SNAKE_CASE +const MAX_OUTCOMES: u32 = 100; + +// Functions and variables: snake_case +fn create_market(market_id: u64) -> Result<(), ErrorCode> { } + +// Types and traits: PascalCase +struct MarketData { } +trait OracleProvider { } + +// Modules: snake_case +mod circuit_breaker; +``` + +#### Documentation + +All public functions must have documentation: + +```rust +/// Creates a new prediction market with the specified parameters. +/// +/// # Arguments +/// +/// * `creator` - Address of the market creator +/// * `title` - Market title/question +/// * `outcomes` - Vector of possible outcomes +/// * `deadline` - Market resolution deadline +/// +/// # Returns +/// +/// Returns the market ID on success, or an error code on failure. +/// +/// # Errors +/// +/// * `NotAuthorized` - Caller lacks permission +/// * `InvalidOutcome` - Outcome count exceeds maximum +/// +/// # Examples +/// +/// ``` +/// let market_id = create_market( +/// creator_addr, +/// "Will BTC reach $100k?", +/// vec!["Yes", "No"], +/// deadline +/// )?; +/// ``` +pub fn create_market( + creator: Address, + title: String, + outcomes: Vec, + deadline: u64 +) -> Result { + // Implementation +} +``` + +#### Error Handling + +```rust +// Use Result types for fallible operations +fn get_market(id: u64) -> Result { + // Implementation +} + +// Use descriptive error codes +return Err(ErrorCode::MarketNotFound); + +// Avoid unwrap() in production code +// Use ? operator or proper error handling +let market = get_market(id)?; +``` + +#### Code Organization + +```rust +// Order within modules: +// 1. Imports +// 2. Constants +// 3. Type definitions +// 4. Public functions +// 5. Private functions +// 6. Tests + +use soroban_sdk::{contract, contractimpl, Address}; + +const MAX_MARKETS: u32 = 1000; + +pub struct Market { + // fields +} + +#[contractimpl] +impl Contract { + pub fn public_function() { } + + fn private_helper() { } +} + +#[cfg(test)] +mod tests { + // tests +} +``` + +### TypeScript/JavaScript (Frontend/Backend) + +```typescript +// Use TypeScript strict mode +// Use functional components with hooks +// Use async/await over promises +// Use descriptive variable names + +// Good +const fetchMarketData = async (marketId: string): Promise => { + const response = await api.get(`/markets/${marketId}`); + return response.data; +}; + +// Avoid +const getData = (id) => { + return api.get('/markets/' + id).then(r => r.data); +}; +``` + +## Testing Requirements + +### Test Coverage + +- All new features must include tests +- Aim for >80% code coverage +- Include both positive and negative test cases +- Test edge cases and error conditions + +### Test Types + +```rust +// Unit tests - test individual functions +#[test] +fn test_calculate_odds() { + let odds = calculate_odds(100, 200); + assert_eq!(odds, 50); +} + +// Integration tests - test module interactions +#[test] +fn test_market_lifecycle() { + let env = Env::default(); + let contract = create_contract(&env); + + // Create market + let market_id = contract.create_market(/* ... */); + + // Place bet + contract.place_bet(market_id, /* ... */); + + // Resolve market + contract.resolve_market(market_id, /* ... */); + + // Verify results + let market = contract.get_market(market_id); + assert_eq!(market.status, MarketStatus::Resolved); +} +``` + +### Running Tests + +```bash +# Run all tests +cargo test + +# Run with output +cargo test -- --nocapture + +# Run specific test +cargo test test_market_lifecycle + +# Run tests with coverage +cargo tarpaulin --out Html +``` + +## Commit Guidelines + +We follow [Conventional Commits](https://www.conventionalcommits.org/): + +### Commit Message Format + +``` +(): + + + +