Merge pull request #45 from quicknode/claude/determined-brown-8vPKa

Add parimutuel betting market program

Author: mikemaccana

README.md

@@ -17,6 +17,13 @@ Each example is available in one or more of the following frameworks:
 
 ## Financial Software
 
+### Betting Market
+
+Parimutuel (pooled) prediction market — an admin opens an event with multiple outcomes, bettors stake tokens on an outcome, and at settlement the losing pool (minus a protocol fee) is split among winners in proportion to their stake.
+
+[⚓ Anchor](./tokens/betting-market/anchor)
+
+
 ### Escrow
 
 **Start here — the best first finance program to learn on Solana.** A neutral account that holds funds until both sides deliver, like a real-estate escrow or a lawyer's trust account. The maker deposits token A and names how much token B they want; when a taker supplies token B, the program swaps both in a single all-or-nothing transaction. This swap is the core idea behind every onchain exchange.

tokens/betting-market/anchor/.gitignore

@@ -0,0 +1,7 @@
+.anchor
+.DS_Store
+target
+**/*.rs.bk
+node_modules
+test-ledger
+.yarn

tokens/betting-market/anchor/Anchor.toml

@@ -0,0 +1,16 @@
+[toolchain]
+solana_version = "3.1.8"
+
+[features]
+resolution = true
+skip-lint = false
+
+[programs.localnet]
+betting_market = "7LyqAeLR3mK9dfj9LqxWzfKH61VVHzuNpkgW5Y32De74"
+
+[provider]
+cluster = "Localnet"
+wallet = "~/.config/solana/id.json"
+
+[scripts]
+test = "cargo test"

tokens/betting-market/anchor/Cargo.toml

@@ -0,0 +1,15 @@
+[workspace]
+members = [
+    "programs/*"
+]
+resolver = "2"
+
+[profile.release]
+overflow-checks = true
+lto = "fat"
+codegen-units = 1
+
+[profile.release.build-override]
+opt-level = 3
+incremental = false
+codegen-units = 1

tokens/betting-market/anchor/README.md

@@ -0,0 +1,108 @@
+# Betting Market
+
+A parimutuel (pooled) betting market. An admin opens an **event**, adds the possible
+**outcomes**, and bettors stake a token on the outcome they think will win. Every stake across
+every outcome goes into one pool. When the admin settles the event to the winning outcome, the
+losing stakes — minus a protocol fee — are split among the winners in proportion to their stake.
+
+This is the pooled model used by Solana prediction-market platforms such as Hedgehog Markets,
+where odds are set by the crowd's stakes rather than by an order book or a fixed-odds bookmaker.
+
+## Purpose
+
+It solves the core problem of trustless betting: collecting stakes from many bettors, holding them
+in one place no single bettor controls, and paying winners by a fixed, public formula. The pool is
+a token account owned by the event's PDA, so payouts are signed by the program with the event's
+seeds — there is no admin key that can move bettors' stakes out of the pool. The admin's only
+powers are creating events/outcomes and choosing the winning outcome (or cancelling).
+
+## Major Concepts
+
+### Accounts
+
+- **Config** (`seeds = [b"config"]`) — one per deployment. Holds the `admin` (the only key that can
+  create events/outcomes, settle, and cancel), the `token_mint` every market accepts, the
+  `fee_recipient`, and the `fee_bps`.
+- **Event** (`seeds = [b"event", event_id]`) — one betting market. Tracks `total_pool`, `status`
+  (`Open` / `Settled` / `Cancelled`), and — once settled — the `winning_outcome_index`,
+  `winning_pool`, and `distributable_losing_pool` that the payout formula reads. The `fee_bps` is
+  snapshotted at creation so later Config changes can't alter a market bettors have already joined.
+- **Outcome** (`seeds = [b"outcome", event, index]`) — one possible result. Its `total_amount` is
+  the outcome's share of the pool and the denominator for pro-rata payouts when it wins.
+- **Bet** (`seeds = [b"bet", outcome, bettor]`) — a bettor's total stake on one outcome. Re-betting
+  the same outcome adds to the existing Bet, so there is exactly one per (outcome, bettor).
+- **User** (`seeds = [b"user", wallet]`) — a per-wallet index listing the bettor's Bet addresses, so
+  a client can find someone's positions without scanning every Bet on the program. The list is
+  capped (see `MAX_BETS_PER_USER`) to keep the account a fixed size; the Bet accounts are the
+  authoritative stake record.
+
+### The vault
+
+Each event owns a single vault token account — the associated token account of the Event PDA for
+`config.token_mint`. `place_bet` moves the stake from the bettor's token account into this vault.
+`settle_event`, `claim_winnings`, and `claim_refund` move tokens back out, with the program signing
+as the Event PDA (`seeds = [b"event", event_id, bump]`).
+
+### Payout formula
+
+When an event settles to a winning outcome:
+
+```
+losing_pool             = total_pool - winning_pool
+fee                     = losing_pool * fee_bps / 10000      // charged only on the losing side
+distributable_losing    = losing_pool - fee
+```
+
+Each winning bet then claims:
+
+```
+payout = stake + stake * distributable_losing / winning_pool
+```
+
+A winner always gets their own stake back; the fee is only ever taken from losing stakes. Integer
+division floors each share, leaving at most a few base units of dust in the vault.
+
+**Worked example:** Outcome A pool 100, Outcome B pool 50, `fee_bps = 200` (2%). A wins.
+`losing_pool = 50`, `fee = 1`, `distributable_losing = 49`. A bettor who staked 40 claims
+`40 + 40 * 49 / 100 = 59`.
+
+### Instruction handlers
+
+| Handler | Who | What it does |
+| --- | --- | --- |
+| `initialize_config` | anyone (becomes admin) | One-time setup: sets admin, stake token, fee, fee recipient. |
+| `create_event` | admin | Opens a market and creates its vault. |
+| `add_outcome` | admin | Adds a possible result. Only before any bet is placed. |
+| `place_bet` | bettor | Stakes tokens on one outcome; updates the pools and the user's index. |
+| `settle_event` | admin | Resolves to a winning outcome, takes the fee, records the payout figures. |
+| `claim_winnings` | winning bettor | Withdraws stake plus pro-rata share of the losing pool. |
+| `cancel_event` | admin | Voids an unresolved market. |
+| `claim_refund` | bettor | After a cancellation, reclaims the exact stake. |
+
+`add_outcome` is locked once betting starts, so the field of choices can't change under existing
+bettors. `settle_event` rejects a winning outcome with no bets — use `cancel_event` to unwind an
+event that can't be resolved fairly.
+
+## Setup
+
+Install the [Solana CLI](https://docs.anza.xyz/cli/install) (provides `cargo-build-sbf`) and
+[Anchor](https://www.anchor-lang.com/docs/installation). Build the program so the test binary
+exists on disk:
+
+```sh
+anchor build
+```
+
+## Testing
+
+Tests are Rust integration tests running against [LiteSVM](https://www.anchor-lang.com/docs/testing/litesvm)
+with [solana-kite](https://crates.io/crates/solana-kite) helpers. They cover the full lifecycle
+(bet → settle → claim with exact payout and fee assertions), admin authorization, the
+bet-after-settle and double-claim guards, settling an outcome with no bets, and the cancel/refund
+path.
+
+```sh
+anchor test
+```
+
+(`Anchor.toml` sets `test = "cargo test"`, so `cargo test` works too.)

tokens/betting-market/anchor/programs/betting-market/Cargo.toml

@@ -0,0 +1,35 @@
+[package]
+name = "betting-market"
+version = "0.1.0"
+description = "Created with Anchor"
+edition = "2021"
+
+[lib]
+crate-type = ["cdylib", "lib"]
+name = "betting_market"
+
+[features]
+default = []
+cpi = ["no-entrypoint"]
+no-entrypoint = []
+no-idl = []
+no-log-ix-name = []
+idl-build = ["anchor-lang/idl-build", "anchor-spl/idl-build"]
+anchor-debug = []
+custom-heap = []
+custom-panic = []
+
+[dependencies]
+# init-if-needed: place_bet and the lazy User index create accounts only on first use.
+anchor-lang = { version = "1.0.0", features = ["init-if-needed"] }
+anchor-spl = "1.0.0"
+
+[dev-dependencies]
+litesvm = "0.11.0"
+solana-signer = "3.0.0"
+solana-keypair = "3.0.1"
+solana-kite = "0.3.0"
+borsh = "1.6.1"
+
+[lints.rust]
+unexpected_cfgs = { level = "warn", check-cfg = ['cfg(target_os, values("solana"))'] }

tokens/betting-market/anchor/programs/betting-market/Xargo.toml

@@ -0,0 +1,2 @@
+[target.bpfel-unknown-unknown.dependencies.std]
+features = []

tokens/betting-market/anchor/programs/betting-market/src/error.rs

@@ -0,0 +1,33 @@
+use anchor_lang::prelude::*;
+
+#[error_code]
+pub enum BettingError {
+    #[msg("Fee in basis points cannot exceed 10000 (100%)")]
+    FeeTooHigh,
+    #[msg("Only the admin may perform this action")]
+    Unauthorized,
+    #[msg("The event is not open for this action")]
+    EventNotOpen,
+    #[msg("The event has not been settled")]
+    EventNotSettled,
+    #[msg("The event has not been cancelled")]
+    EventNotCancelled,
+    #[msg("The winning outcome has no bets, so the event cannot be settled to it")]
+    OutcomeHasNoBets,
+    #[msg("The winning outcome index does not match the provided outcome account")]
+    InvalidWinningOutcome,
+    #[msg("This bet did not win, so there is nothing to claim")]
+    NothingToClaim,
+    #[msg("This bet has already been claimed")]
+    AlreadyClaimed,
+    #[msg("The bet amount must be greater than zero")]
+    ZeroAmount,
+    #[msg("This bettor already holds the maximum number of distinct bets")]
+    TooManyBets,
+    #[msg("Outcomes can only be added before any bets are placed")]
+    BettingAlreadyStarted,
+    #[msg("The event description is too long")]
+    DescriptionTooLong,
+    #[msg("The outcome label is too long")]
+    LabelTooLong,
+}

tokens/betting-market/anchor/programs/betting-market/src/instructions/add_outcome.rs

@@ -0,0 +1,63 @@
+use anchor_lang::prelude::*;
+
+use crate::{error::BettingError, Config, Event, EventStatus, Outcome};
+
+pub const MAX_LABEL_LEN: usize = 64;
+
+#[derive(Accounts)]
+pub struct AddOutcome<'info> {
+    #[account(mut)]
+    pub admin: Signer<'info>,
+
+    #[account(
+        seeds = [b"config"],
+        bump = config.bump,
+        has_one = admin @ BettingError::Unauthorized,
+    )]
+    pub config: Account<'info, Config>,
+
+    #[account(
+        mut,
+        seeds = [b"event", event.event_id.to_le_bytes().as_ref()],
+        bump = event.bump,
+    )]
+    pub event: Account<'info, Event>,
+
+    #[account(
+        init,
+        payer = admin,
+        space = Outcome::DISCRIMINATOR.len() + Outcome::INIT_SPACE,
+        seeds = [b"outcome", event.key().as_ref(), &[event.outcome_count]],
+        bump
+    )]
+    pub outcome: Account<'info, Outcome>,
+
+    pub system_program: Program<'info, System>,
+}
+
+pub fn handle_add_outcome(context: Context<AddOutcome>, label: String) -> Result<()> {
+    require!(label.len() <= MAX_LABEL_LEN, BettingError::LabelTooLong);
+    require!(
+        context.accounts.event.status == EventStatus::Open,
+        BettingError::EventNotOpen
+    );
+    // Lock the outcome set once betting starts so the field of choices can't
+    // change out from under existing bettors.
+    require!(
+        context.accounts.event.total_pool == 0,
+        BettingError::BettingAlreadyStarted
+    );
+
+    let index = context.accounts.event.outcome_count;
+    context.accounts.outcome.set_inner(Outcome {
+        event: context.accounts.event.key(),
+        index,
+        label,
+        total_amount: 0,
+        bet_count: 0,
+        bump: context.bumps.outcome,
+    });
+
+    context.accounts.event.outcome_count += 1;
+    Ok(())
+}

tokens/betting-market/anchor/programs/betting-market/src/instructions/cancel_event.rs

@@ -0,0 +1,33 @@
+use anchor_lang::prelude::*;
+
+use crate::{error::BettingError, Config, Event, EventStatus};
+
+// Abandon an event that can't be resolved (e.g. the real-world result is void).
+// Bettors then reclaim their exact stakes via `claim_refund`; no fee is taken.
+#[derive(Accounts)]
+pub struct CancelEvent<'info> {
+    pub admin: Signer<'info>,
+
+    #[account(
+        seeds = [b"config"],
+        bump = config.bump,
+        has_one = admin @ BettingError::Unauthorized,
+    )]
+    pub config: Account<'info, Config>,
+
+    #[account(
+        mut,
+        seeds = [b"event", event.event_id.to_le_bytes().as_ref()],
+        bump = event.bump,
+    )]
+    pub event: Account<'info, Event>,
+}
+
+pub fn handle_cancel_event(context: Context<CancelEvent>) -> Result<()> {
+    require!(
+        context.accounts.event.status == EventStatus::Open,
+        BettingError::EventNotOpen
+    );
+    context.accounts.event.status = EventStatus::Cancelled;
+    Ok(())
+}