Pythia - Decentralized Prediction Markets on Sui

Pythia is a decentralized prediction market platform built on the Sui blockchain. It empowers users to create, participate in, and resolve markets on real-world events, leveraging the high scalability and low latency of the Sui network.

Motivation

Pythia addresses the need for reliable, decentralized prediction markets on Sui by implementing a sophisticated oracle system with multi-signature arbiters and built-in dispute resolution. The platform ensures fair outcomes through economic incentives, reputation tracking, and transparent governance mechanisms.

Features

Prediction Markets: Seamlessly create and trade on markets for any future event.
Unified Wallet Access: Log in effortlessly using Google accounts (zkLogin) or connect standard Sui wallets.
Decentralized & Secure: Fully on-chain logic ensures transparency and security for all market data and funds.
Community Driven: Built for the community, with tools for decentralized moderation and dispute resolution.
Multi-Sig Arbiters: Secure resolution system with configurable thresholds and performance tracking
User Profiles: Auto-created profiles tracking betting history, wins, reputation, and earnings
Dispute System: Bonded dispute mechanism allowing users to challenge unfair resolutions
Protocol Economics: Configurable fee structure for creators, arbiters, and protocol treasury
Trust Scores: Reputation system for arbiters based on resolution accuracy
Creator Incentives: Fee sharing for market creators to encourage quality markets
Market Sharing: Creators can share markets via QR codes and social links
Unified Claim System: Single interface for winners to claim payouts and losers to update stats
Storage Optimization: Automatic cleanup of resolved data to minimize gas costs
Comprehensive Testing: Full test suite covering market lifecycle, disputes, and edge cases
Suibase Integration: Seamless local development and deployment workflows

Prerequisites

Before you begin, install the following:

Quick Start

Get Pythia running in minutes:

# Clone and install
git clone https://github.com/Sui-Romanian-Hackathon/pythia.git
cd pythia
pnpm install

# Start local network and deploy contract
pnpm localnet:start
pnpm localnet:deploy

# Run the frontend
pnpm start

Visit localhost:5173 to access the application locally.

Live Demo: pythia-frontend-zeta.vercel.app

Installation

Clone the Repository

Clone the repository:

git clone https://github.com/Sui-Romanian-Hackathon/pythia.git
cd pythia

Install dependencies:

pnpm install

Development Workflow

Local Development

Start local Sui network:
```
pnpm localnet:start
```
Deploy contract:
```
pnpm localnet:deploy
```
Run frontend:
```
pnpm start
```

Network Deployment

Deploy to different networks:

# Testnet
pnpm testnet:deploy

# Mainnet
pnpm mainnet:deploy

Usage

1. Run the local Sui network:

pnpm localnet:start

Local Sui Explorer will be available on localhost:9001

2. Deploy the Pythia contract to the local network:

pnpm localnet:deploy

This command deploys the Pythia Move package with all prediction market functionality.

3. Switch to the local network in your browser wallet settings.

4. Fund your localnet account/address:

You have a few options here:

a) Use the Faucet button integrated into your wallet (e.g. Sui Wallet).

b) Copy the localnet address from your wallet and run the following in your console:

pnpm localnet:faucet 0xYOURADDRESS

c) Run the app and use the Faucet button in the footer.

5. Run the application:

pnpm start

The frontend will be available on localhost:5173

Testing

Backend (Move Contract)

pnpm test

The test suite covers:

Market lifecycle (creation, betting, resolution, claiming)
Dispute mechanism (filing, resolution, bond handling)
Access control (admin functions, arbiter authorization)
Consensus logic (multi-arbiter voting, thresholds)
Economic safety (bet amounts, fee distribution)
Edge cases (deadlines, invalid parameters, state transitions)

Frontend Testing

pnpm frontend:test

Documentation & Support

Backend Documentation - Move contract details and API
Frontend Documentation - React app and components
Available Commands - Development and deployment commands
GitHub Issues - Report bugs and request features

Architecture

Backend (Move Package)

Located in packages/backend/move/pythia/, containing:

Core prediction market logic
Multi-signature arbiter system
User profile management
Dispute resolution mechanism
Protocol configuration

Frontend (React App)

Located in packages/frontend/, providing:

Market creation interface
Betting interface
Portfolio and profile management
Dispute filing system
Arbiter dashboard

User Flows

Bettor Workflow

graph TD
    A[User Connects Wallet] --> B[Browse Markets]
    B --> C[Select Market]
    C --> D[Place Bet YES/NO]
    D --> E[Wait for Resolution]
    E --> F{Market Resolved}
    F -->|Yes| G[Claim Winnings]
    F -->|No| H[Update Loss Stats]
    F -->|Disagree| I[File Dispute]
    I --> J[Wait for Dispute Resolution]
    J --> K[Claim Winnings/Update Stats]

Creator Workflow

graph TD
    A[Creator Connects Wallet] --> B[Create Market]
    B --> C[Set Parameters]
    C --> D[Select Arbiters]
    D --> E[Deploy Market]
    E --> F[Share Market]
    F --> G[Monitor Betting]
    G --> H[Wait for Resolution]
    H --> I[Collect Creator Fees]
    I --> J[Share Results]

Arbiter Workflow

graph TD
    A[Apply as Arbiter] --> B{Admin Approval}
    B -->|Approved| C[Arbiter Approved]
    B -->|Rejected| D[Application Denied]
    C --> E[Receive Market Assignment]
    E --> F[Research Market Topic]
    F --> G[Submit Resolution Vote]
    G --> H{Consensus Reached}
    H -->|Yes| I[Market Resolved]
    H -->|No| J[Wait for More Votes]
    I --> K[Earn Arbiter Fees]
    K --> L[Update Reputation]

    M[Admin Review] --> N{Performance Check}
    N -->|Poor Performance| O[Revoke Arbiter Status]
    N -->|Good Performance| L
    O --> P[Lose Arbiter Privileges]

Useful Links

Key Components

Core Features

Prediction Markets: Create YES/NO markets with customizable parameters
Multi-Sig Resolution: Configurable arbiter thresholds for secure outcomes
Dispute System: Bonded challenges to ensure fair resolutions
User Profiles: Track betting history, reputation, and earnings
Protocol Fees: Sustainable economic model with fee distribution

Technical Highlights

Storage Optimization: Automatic cleanup to minimize gas costs
Comprehensive Testing: Full coverage of all market scenarios
Type Safety: Strongly typed Move contract with formal verification
Event-Driven: Rich event system for frontend integration

License & Copyright

Code is licensed under MIT

Roadmap

Q1 2026: Enhanced UI/UX with real-time market updates
Q2 2026: Mobile app development (React Native) with push notifications
Q3 2026: Advanced market types (multi-outcome, conditional)
Q4 2026: Cross-chain oracle integration
Future: DAO governance for protocol parameters

Performance & Security

Gas Optimization

Storage rebates through automatic data cleanup
Efficient batch operations for multiple bets
Optimized dispute resolution flow

Security Measures

Multi-signature arbiter validation
Bonded dispute system to prevent spam
Access control for admin functions
Comprehensive test coverage including edge cases

Contributing

We welcome contributions! Please see our Contributing Guide for details.

Development Setup:

Fork the repository
Create a feature branch: git checkout -b feature/amazing-feature
Make your changes and add tests
Run tests: pnpm test
Submit a pull request

Areas for Contribution:

Frontend UI/UX improvements
Additional test coverage
Documentation enhancements
Performance optimizations
New market types or features

Name		Name	Last commit message	Last commit date
Latest commit History 42 Commits
.github		.github
.vscode		.vscode
packages		packages
.gitignore		.gitignore
LICENSE		LICENSE
LICENSE-GRAPHICS		LICENSE-GRAPHICS
README.md		README.md
package.json		package.json
pnpm-lock.yaml		pnpm-lock.yaml
pnpm-workspace.yaml		pnpm-workspace.yaml

Uh oh!

Folders and files

Latest commit

History

Repository files navigation