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.

🚀 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:

# 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

Fork the repository

Create a feature branch

git checkout -b feature/your-feature-name

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

Commit your changes

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

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

Create feature branch
Implement feature with tests
Update documentation
Run full test suite
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

FilesExpand file tree

README.md

Latest commit

History