iPredict — Prediction Market on Starknet

Decentralized binary prediction market built on Starknet. Users bet STRK on yes/no outcomes and earn IPREDICT tokens regardless of whether they win or lose.

Deployed Contracts (Sepolia)

Contract	Address	Explorer
Prediction Market	`0x031c610a...e2fd5c5`	StarScan
IPREDICT Token	`0x01d78041...321140c`	StarScan
Referral Registry	`0x0057591c...e0345d0`	StarScan
Leaderboard	`0x0533a470...4ed2038`	StarScan

Admin: 0x05652251ea1bf17c7979b6496f9c585187778dc47c2cda8c2632640ab9b2b28c

What It Does

Binary markets — Admin creates yes/no markets; users bet STRK on their prediction
Reward tokens — Winners get 10 IPREDICT, losers still get 2 IPREDICT per claim
Referral system — Referrers earn 0.5% of every bet placed by people they referred
Leaderboard — Tracks points, bets, wins, and losses per user
2% fee — 1.5% platform + 0.5% referrer (if no referrer, full 2% goes to platform)

Architecture

┌─────────────────────────────────────────────────────────────────┐
│                     Next.js 14 Frontend                        │
│  (App Router • Tailwind CSS • StarkZap SDK)                    │
└──────────────┬──────────────┬──────────────┬──────────────┬─────┘
               │              │              │              │
        Starknet RPC     Starknet RPC   Starknet RPC   Starknet RPC
               │              │              │              │
  ┌────────────▼──┐ ┌────────▼────┐ ┌───────▼──────┐ ┌────▼────────┐
  │  Prediction   │ │  IPREDICT   │ │   Referral   │ │ Leaderboard │
  │    Market     │ │    Token    │ │   Registry   │ │             │
  │               │ │             │ │              │ │             │
  │ create_market │ │ mint        │ │ register     │ │ add_pts     │
  │ place_bet ────┼─┼─► mint ◄───┼─┤ credit ──────┼─┤ record_bet  │
  │ resolve    ───┼─┼─► mint     │ │ get_referrer │ │ get_stats   │
  │ claim      ───┼─┼─► mint     │ │ get_earnings │ │ get_top     │
  │ cancel        │ │ transfer   │ │ is_registered│ │ get_rank    │
  │ withdraw_fees │ │ balance    │ │              │ │             │
  └───────────────┘ └────────────┘ └──────────────┘ └─────────────┘

Inter-Contract Call Flow

Place Bet: PredictionMarket.place_bet() → approve + transfer STRK → ReferralRegistry.credit() (splits fee: 0.5% to referrer, 1.5% to platform) → Leaderboard.record_bet() → IPredictToken.mint() (bet participation tokens)

Resolve Market: PredictionMarket.resolve_market() → Stores outcome onchain

Claim Reward: PredictionMarket.claim() → Calculates pro-rata payout → Transfers STRK to user → Leaderboard.add_pts() (win: 30 pts / lose: 10 pts) → IPredictToken.mint() (win: 10 IPRED / lose: 2 IPRED)

Referral Registration: ReferralRegistry.register_referral() → Leaderboard.add_bonus_pts() (5 pts) → IPredictToken.mint() (1 IPRED welcome bonus)

Reward System

Outcome	STRK Payout	Points	IPREDICT Tokens
Win	Pro-rata share of losing pool	+30 pts	+10 IPRED
Lose	0 STRK	+10 pts	+2 IPRED
Cancelled	Full refund	+10 pts	+2 IPRED
Referral Registration	—	+5 pts	+1 IPRED
Referred Bet (referrer earns)	0.5% of bet	+3 pts	—

Payout Formula

$$\text{Payout} = \frac{\text{UserBet}}{\text{WinningSidePool}} \times \text{TotalPool}$$

Fee Model

Component	Rate	Recipient
Platform fee	1.5%	Admin (accumulated, withdrawable)
Referral fee	0.5%	Referrer's STRK wallet
Total	2.0%	Deducted at bet time

If bettor has no referrer, full 2% goes to platform.

Tech Stack

Layer	Technology
Smart Contracts	Cairo 2.11.4 + OpenZeppelin Cairo Contracts 1.0.0
Contract Build	Scarb 2.11.4
Contract Testing	snforge 0.45.0 (Starknet Foundry)
Frontend	Next.js 14 (App Router)
UI	React 18 + Tailwind CSS
Wallet	StarkZap SDK (Privy, Cartridge, StarkSigner)
Starknet SDK	starknet.js 6.23.1
Testing	Vitest + Testing Library
CI	GitHub Actions (Scarb + Node 20)
Hosting	Vercel (frontend) + Starknet Sepolia (contracts)

Project Structure

ipredict-starknet/
├── .github/workflows/ci.yml       # CI pipeline
├── contracts/
│   ├── Scarb.toml                  # Workspace manifest
│   ├── prediction_market/          # Core market logic (Cairo)
│   ├── ipredict_token/             # Platform ERC20 token
│   ├── referral_registry/          # Referral tracking
│   └── leaderboard/                # Rankings + stats
├── frontend/
│   ├── public/                     # Favicon, OG image
│   ├── src/
│   │   ├── app/                    # Next.js pages (7 routes)
│   │   ├── components/             # 30+ React components
│   │   │   ├── layout/             # Navbar, Footer, MobileMenu
│   │   │   ├── market/             # MarketCard, BettingPanel, OddsBar…
│   │   │   ├── leaderboard/        # LeaderboardTable, Tabs, PlayerRow
│   │   │   ├── profile/            # BetHistory, PointsCard, Referral…
│   │   │   ├── social/             # ShareBetButton, SocialShareModal
│   │   │   ├── wallet/             # WalletConnect, WalletModal
│   │   │   ├── admin/              # CreateMarket, Resolve, Stats
│   │   │   └── ui/                 # Spinner, Skeleton, Toast, Badge…
│   │   ├── hooks/                  # useMarket, useWallet, useBet…
│   │   ├── services/               # Starknet RPC service layer
│   │   ├── utils/                  # Helpers, cache, formatting
│   │   ├── config/                 # Network constants
│   │   └── types/                  # TypeScript interfaces
│   ├── __tests__/                  # Test suites
│   └── .env.local.example          # Environment template
├── docs/
│   ├── ARCHITECTURE.md
│   ├── DEPLOYMENT-GUIDE.md
│   ├── USER-FEEDBACK.md
│   └── ITERATION-LOG.md
└── README.md

Getting Started

Prerequisites

Scarb 2.11.4 (Cairo build tool)
Starknet Foundry 0.45.0 (snforge for tests, sncast/starkli for deployment)
Node.js 20+
A Starknet-compatible wallet with Sepolia STRK

Build & Test

git clone https://github.com/Akanimoh12/ipredict-starknet.git
cd ipredict-starknet

# Build Cairo contracts
cd contracts
scarb build

# Run contract tests
snforge test

# Frontend
cd ../frontend
npm install
npm test
npm run dev  # http://localhost:3000

Environment Variables

Copy .env.local.example to .env.local in frontend/ and fill in contract addresses. The deployed Sepolia addresses are listed above.

Deploy Contracts (Sepolia)

See docs/DEPLOYMENT-GUIDE.md for the full step-by-step deployment guide with correct dependency order.

Testing

# Cairo contract tests
cd contracts && snforge test

# Frontend unit tests
cd frontend && npm test

Smart Contract Functions

Prediction Market

Function	Description
`set_contracts(token, referral, leaderboard, fee_token)`	Owner-only setup of linked contracts
`create_market(question, image_url, duration_secs)`	Create new prediction market
`place_bet(market_id, is_yes, amount)`	Place or increase bet (2% fee deducted)
`resolve_market(market_id, outcome)`	Admin resolves with YES/NO outcome
`cancel_market(market_id)`	Cancel market, enable refunds
`claim(market_id)`	Claim payout + points + tokens
`withdraw_fees()`	Admin withdraws accumulated platform fees
`get_market(market_id)`	Read market data
`get_bet(market_id, user)`	Read user's bet on market
`get_market_count()`	Total markets created
`get_odds(market_id)`	Current YES/NO percentages
`get_market_bettors(market_id)`	List all bettors on a market
`get_accumulated_fees()`	Total unclaimed platform fees

IPREDICT Token (ERC20)

Function	Description
`constructor(owner, name, symbol)`	Token deployment with metadata
`set_minter(minter)`	Authorize address to mint
`mint(to, amount)`	Mint tokens (authorized minters only)
`transfer(recipient, amount)`	Transfer tokens between accounts
`burn(amount)`	Burn tokens
`balance_of(account)`	Get token balance
`total_supply()`	Total tokens minted
`name()` / `symbol()` / `decimals()`	Token metadata (18 decimals)

Referral Registry

Function	Description
`set_contracts(market, token, leaderboard, fee_token)`	Owner-only setup
`register_referral(display_name, referrer?)`	Register with optional referrer
`credit(user, referral_fee)`	Credit referral fee (called by market contract)
`get_referrer(user)`	Get user's referrer address
`get_display_name(user)`	Get registered display name
`get_referral_count(user)`	Number of referrals
`get_earnings(user)`	Total referral earnings
`has_referrer(user)` / `is_registered(user)`	Status checks

Leaderboard

Function	Description
`set_market_contract(market)`	Owner-only: link market contract
`set_referral_contract(referral)`	Owner-only: link referral contract
`add_pts(user, points, is_winner)`	Add win/loss points + update stats
`add_bonus_pts(user, points)`	Add bonus points (no stat inflation)
`record_bet(user)`	Increment total bets count
`get_points(user)`	Get user's total points
`get_stats(user)`	Full player stats (points, bets, wins, losses)
`get_top_players(limit)`	Sorted leaderboard
`get_rank(user)`	User's current rank

Roadmap

User-created markets with oracle-based resolution
IPREDICT token staking and governance
Starknet mainnet deployment
Categories and market discovery

License

MIT

Built by Akan.

Name		Name	Last commit message	Last commit date
Latest commit History 4 Commits
.github/workflows		.github/workflows
contracts		contracts
docs		docs
frontend		frontend
.gitignore		.gitignore
README.md		README.md
iPredict-Project-Structure.md		iPredict-Project-Structure.md
ipredict.md		ipredict.md

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Repository files navigation

iPredict — Prediction Market on Starknet

Deployed Contracts (Sepolia)

What It Does

Architecture

Inter-Contract Call Flow

Reward System

Payout Formula

Fee Model

Tech Stack

Project Structure

Getting Started

Prerequisites

Build & Test

Environment Variables

Deploy Contracts (Sepolia)

Testing

Smart Contract Functions

Prediction Market

IPREDICT Token (ERC20)

Referral Registry

Leaderboard

Roadmap

License

About

Uh oh!

Releases

Packages

Uh oh!

Contributors

Uh oh!

Languages

Folders and files

Latest commit

History

Repository files navigation

iPredict — Prediction Market on Starknet

Deployed Contracts (Sepolia)

What It Does

Architecture

Inter-Contract Call Flow

Reward System

Payout Formula

Fee Model

Tech Stack

Project Structure

Getting Started

Prerequisites

Build & Test

Environment Variables

Deploy Contracts (Sepolia)

Testing

Smart Contract Functions

Prediction Market

IPREDICT Token (ERC20)

Referral Registry

Leaderboard

Roadmap

License

About

Resources

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages