PredictIQ Contracts

Platform: Stellar Soroban
Language: Rust
License: MIT

📖 About

PredictIQ Contracts is a comprehensive 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 that combine real-time oracle data (from Pyth Network and Reflector oracles) with community voting. This platform is designed for developers, traders, and organizations looking to build decentralized prediction markets with institutional-grade oracle integration, dispute resolution, and governance features.

The project is ideal for developers building on Stellar, smart contract auditors, and teams creating prediction market applications that require reliable price feeds, community governance, and robust dispute resolution mechanisms.

---

📋 Table of Contents

1. Quick Start
2. Project Structure
3. Setup Instructions
4. Development
5. Testing
6. Deployment
7. Documentation
8. Contributing

---

🚀 Quick Start

# Clone the repository
git clone <repository-url>
cd PredictIQ

# Install dependencies (Rust and Soroban CLI)
# See Setup Instructions below

# Build contracts
cd contracts/predict-iq
make build

# Run tests
make test

---

📁 Project Structure

PredictIQ/
├── .archive/                 # Historical documentation
├── .github/                  # GitHub templates and workflows
│   ├── PULL_REQUEST_TEMPLATE.md
│   └── workflows/
├── contracts/
│   └── predict-iq/           # Main prediction market contract
│       ├── src/              # Contract source code
│       └── Makefile          # Build and test commands
├── docs/                     # Comprehensive documentation
│   ├── README.md             # Documentation index
│   ├── gas/                  # Gas optimization guides
│   ├── security/             # Security documentation
│   └── quick-reference/      # Quick reference guides
├── tests/                    # Test files
├── README.md                 # This file
├── CONTRIBUTING.md           # Contribution guidelines
├── DEVELOPMENT.md            # Development setup guide
├── ARCHITECTURE.md           # System architecture
├── API_SPEC.md               # API specification
├── CHANGELOG.md              # Version history
└── Cargo.toml                # Workspace configuration

Key Components:

• contracts/predict-iq/: Main prediction market contract with oracle integration, voting, disputes, and governance
• docs/: Organized documentation by category
• .archive/: Historical documentation for reference

---

🛠️ Setup Instructions

Requirements

• Rust (latest stable version)
• Soroban CLI (version 20.0.0 or later)
• Stellar Account (for deployment and testing)
• Git (for cloning the repository)

Installation

1. Install Rust

# Install Rust using rustup
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

# Verify installation
rustc --version
cargo --version

2. Install Soroban CLI

# Install Soroban CLI
cargo install --locked --version 20.0.0 soroban-cli

# Verify installation
soroban --version

3. Install Stellar Contract Tools

# Install Stellar contract build tools
cargo install --locked stellar-cli

# Verify installation
stellar --version

Environment Setup

Configure Stellar Networks

# Add testnet (recommended for development)
soroban config network add testnet \
  --rpc-url https://soroban-testnet.stellar.org:443 \
  --network-passphrase "Test SDF Network ; September 2015"

# Add futurenet (for testing new features)
soroban config network add futurenet \
  --rpc-url https://rpc-futurenet.stellar.org:443 \
  --network-passphrase "Test SDF Future Network ; October 2022"

# Add mainnet (for production deployment)
soroban config network add mainnet \
  --rpc-url https://rpc.mainnet.stellar.org:443 \
  --network-passphrase "Public Global Stellar Network ; September 2015"

Set Default Network

# Use testnet for development
soroban config network use testnet

Environment Variables

Create a .env file in the project root (or .env.testnet for testnet):

# .env.testnet
NETWORK=testnet
DEPLOYER_SECRET_KEY="SB..."  # Your deployer account secret key
ADMIN_ADDRESS="GB..."        # Admin account address
ORACLE_CONTRACT="..."        # Oracle contract address (optional for testing)

⚠️ Security Note: Never commit .env files to version control. Add them to .gitignore.

Build the Project

# From project root
cd contracts/predict-iq

# Build the contract
make build

# Or use cargo directly
cargo build --target wasm32-unknown-unknown --release

The compiled WASM file will be at:

target/wasm32-unknown-unknown/release/predict_iq.wasm

---

🧪 Testing

Run All Tests

# From contract directory
cd contracts/predict-iq
make test

# Or use cargo directly
cargo test

Run Specific Test Suites

# Unit tests only
cargo test --lib

# Integration tests
cargo test --test integration_test

# Property-based tests
cargo test --test property_based_tests

Test on Testnet

# Deploy to testnet for integration testing
soroban contract deploy \
  --wasm target/wasm32-unknown-unknown/release/predict_iq.wasm \
  --network testnet \
  --source $DEPLOYER_SECRET_KEY

# Initialize the contract
soroban contract invoke \
  --id <contract_id> \
  --fn initialize \
  --network testnet \
  --source $DEPLOYER_SECRET_KEY \
  --arg admin=$ADMIN_ADDRESS

---

🚀 Deployment

Deploy to Testnet (Recommended First Step)

# Ensure you're on testnet
soroban config network use testnet

# Deploy contract
soroban contract deploy \
  --wasm target/wasm32-unknown-unknown/release/predict_iq.wasm \
  --network testnet \
  --source $DEPLOYER_SECRET_KEY

# Save the contract ID from the output
CONTRACT_ID="<contract_id_from_output>"

# Initialize contract
soroban contract invoke \
  --id $CONTRACT_ID \
  --fn initialize \
  --network testnet \
  --source $DEPLOYER_SECRET_KEY \
  --arg admin=$ADMIN_ADDRESS

Deploy to Mainnet

⚠️ Production Deployment Checklist:

• All tests passing
• Security audit completed
• Testnet deployment verified
• Admin keys secured (preferably multisig)
• Oracle contracts configured
• Monitoring setup ready

# Switch to mainnet
soroban config network use mainnet

# Deploy contract
soroban contract deploy \
  --wasm target/wasm32-unknown-unknown/release/predict_iq.wasm \
  --network mainnet \
  --source $DEPLOYER_SECRET_KEY

# Initialize contract
soroban contract invoke \
  --id $CONTRACT_ID \
  --fn initialize \
  --network mainnet \
  --source $DEPLOYER_SECRET_KEY \
  --arg admin=$ADMIN_ADDRESS

# Record contract ID securely
echo "Mainnet Contract ID: $CONTRACT_ID" >> deployment.log

Verify Deployment

# Inspect deployed contract
soroban contract inspect \
  --id $CONTRACT_ID \
  --network $NETWORK

---

📚 Documentation

🔗 Quick Links

Document	Description
📖 Documentation Index	Complete documentation overview
🚀 Getting Started	Development setup and workflows
🤝 Contributing	Contribution guidelines
🏗️ Architecture	System design and architecture
📋 API Specification	API reference and integration
📝 Changelog	Version history and changes

Documentation by Category

🚀 Getting Started

• Development Guide - Complete setup instructions
• Quick Start - Get up and running quickly
• Contributing Guidelines - How to contribute

🏗️ Architecture & Design

• Architecture Overview - System design and components
• API Specification - Complete API reference

⛽ Gas Optimization

• Gas Optimization Guide - Optimization strategies
• Quick Start Gas Optimization - Quick tips

🔒 Security

• Multisig Emergency Pause - Emergency controls
• Security Best Practices - Security guidelines

📚 Reference

• Quick Reference Guides - Command references and cheat sheets
• Contract Documentation - Detailed contract docs

---

🤝 Contributing

We welcome contributions! Here's how to get started:

Development Workflow

1. Fork the repository
2. Create a feature branch

   git checkout -b feature/your-feature-name

3. Make your changes
   • Follow Rust formatting: cargo fmt --all
   • Ensure tests pass: make test
   • Update documentation as needed
4. Commit your changes

   git commit -m "Add: description of your changes"

5. Push and create a Pull Request

Code Standards

• Formatting: Use cargo fmt --all before committing
• Testing: All new features must include tests
• Documentation: Update relevant docs for new features
• Security: Review security implications of changes

Contribution Guidelines

• Issues: Use GitHub issues for bug reports and feature requests
• Pull Requests: Include description of changes and test results
• Code Review: All PRs require review before merging
• Testing: Ensure all tests pass and add tests for new features

Getting Help

• Documentation: Check the docs directory
• Issues: Search existing issues or create a new one
• Discussions: Use GitHub Discussions for questions

---

🔮 Oracle Setup

The PredictIQ contract supports multiple oracle providers for price feeds:

Supported Oracles

• Pyth Network: Institutional-grade price feeds with high-frequency updates (400ms)
• Reflector Oracle: Stellar-native oracle with proven track record
• Custom Oracles: Extensible architecture for additional providers

Oracle Configuration

See the Contract README for detailed oracle setup instructions and integration examples.

---

🔍 Development

Code Formatting

# Format all code
cargo fmt --all

# Or from contract directory
cd contracts/predict-iq
make fmt

Running Tests

# Run all tests
make test

# Run with output
cargo test -- --nocapture

# Run specific test
cargo test test_name

Project Structure

• contracts/predict-iq/src/: Main contract source code
  • lib.rs: Contract entry point and main implementation
  • modules/: Modular contract implementation
    • admin.rs: Admin functions
    • markets.rs: Market creation and management
    • oracles.rs: Oracle integration (Pyth, Reflector)
    • voting.rs: Community voting system
    • disputes.rs: Dispute resolution mechanism
    • fees.rs: Fee management
  • types.rs: Core data structures
  • errors.rs: Error definitions

Adding New Features

1. Create feature branch
2. Implement feature with tests
3. Update documentation
4. Run full test suite
5. Submit PR with description

---

📊 Monitoring

Tools

• Stellar Expert: Blockchain explorer
• Soroban CLI: Contract inspection and interaction
• Custom Scripts: Monitor transactions and events

Key Metrics

• Oracle submission frequency and reliability
• Market creation and resolution rates
• Dispute activations and resolution times
• Gas costs and optimization opportunities

---

🔐 Security

Security Best Practices

• Review Security Documentation before deployment
• Complete security audit checklist
• Use hardware wallets for admin keys
• Implement multisig for critical operations
• Monitor for suspicious activity

Reporting Security Issues

⚠️ Do not open public issues for security vulnerabilities.

Please report security issues privately to the maintainers. See Security Best Practices for details.

---

📝 License

This project is open source and available under the MIT License.

---

🔗 Additional Resources

• Stellar Documentation: Stellar platform docs
• Stellar Developer Discord: Community support

---

💬 Support

• Issues: GitHub Issues
• Documentation: Documentation Index
• Questions: Use GitHub Discussions

---

Last updated: 2026