Solana Jackpot

Provably fair SOL jackpot rounds on Solana, built with Anchor and ORAO VRF. Players deposit into a shared pool; when a round ends, a winner is selected on-chain using verifiable randomness and claims the pot from a program-controlled vault.

---

Table of Contents

• Overview
• Architecture
• Features
• Prerequisites
• Quick Start
• CLI Reference
• Program Instructions
• On-Chain Accounts
• Security Notes
• Development
• Contact
• License

---

Overview

This repository contains:

• solana_jackpot — Anchor program for round lifecycle, deposits, winner selection, and payouts
• TypeScript CLI — Admin and player workflows against devnet or custom RPC
• ORAO VRF integration — Verifiable random winner selection weighted by deposit size

Each round is independent. The platform operator configures global limits once, creates rounds with custom duration and caps, and resolves winners after the countdown. Winner odds equal player_deposit / total_pool.

---

Architecture

┌──────────────────────────────────────────────────────────────┐
│                        Solana Jackpot                         │
├──────────────────┬─────────────────────────┬─────────────────┤
│  CLI (TypeScript)│  solana_jackpot (Rust)  │    ORAO VRF     │
│  config          │  configure              │  randomness     │
│  create / join   │  create_round           │  fulfillment    │
│  winner / claim  │  join_round             │                 │
│                  │  set_winner             │                 │
│                  │  claim_reward           │                 │
└──────────────────┴─────────────────────────┴─────────────────┘
                              │
                              ▼
                    Solana (devnet / mainnet)

Repository layout

.
├── programs/solana_jackpot/     # Anchor program
│   └── src/
│       ├── lib.rs               # Instruction dispatch
│       ├── constants.rs         # PDA seeds
│       ├── state/
│       │   ├── config.rs        # PlatformConfig
│       │   └── jackpot_round.rs # JackpotRound + PlayerDeposit
│       └── instructions/
│           ├── admin/           # configure, create_round, set_winner
│           └── user/            # join_round, claim_reward
├── cli/                         # Commander CLI entrypoint
├── lib/                         # Transaction builders and constants
├── idl/                         # IDL reference (regenerate via anchor build)
├── types/                       # TypeScript program types placeholder
├── Anchor.toml
└── package.json

Round lifecycle

1. Configure — Admin initializes PlatformConfig and the global SOL vault (once).
2. Create round — Admin opens a round, requests ORAO VRF randomness, and sets duration / deposit limits.
3. Join — Players deposit SOL; the countdown starts when the second player joins.
4. Set winner — After ends_at, admin submits the fulfilled VRF result; the contract picks a weighted winner.
5. Claim — The winner withdraws the pool from the global vault.

Round IDs used in the CLI (-g) are 0-indexed PDA seeds.

---

Features

Feature	Description
Weighted odds	Chance proportional to deposit share of the pool
ORAO VRF	On-chain verifiable randomness for winner selection
Platform fee	Configurable basis-point fee routed to team_wallet
Resizable rounds	Dynamic account space as players join
Full CLI	End-to-end devnet workflow without a custom frontend

---

Prerequisites

Tool	Version
Rust	1.75+
Solana CLI	1.18+
Anchor	0.30.1
Node.js	16+
Yarn	1.x / 3.x

rustc --version
solana --version
anchor --version
node --version
yarn --version

---

Quick Start

1. Install dependencies

git clone https://github.com/your-org/solana-jackpot.git
cd solana-jackpot
yarn install

2. Configure Solana

solana config set --url devnet

mkdir -p keys
solana-keygen new -o ./keys/admin.json
solana airdrop 5 $(solana-keygen pubkey ./keys/admin.json) -u devnet

Point Anchor.toml [provider] at your admin keypair. Add ./keys/feePayer.json for rent/top-up operations used by the CLI scripts.

3. Build and deploy

RUSTUP_TOOLCHAIN="nightly-2024-11-19" anchor build
anchor keys sync
RUSTUP_TOOLCHAIN="nightly-2024-11-19" anchor build
anchor deploy

Ensure the deployed program ID matches declare_id! in programs/solana_jackpot/src/lib.rs and [programs.*] in Anchor.toml.

4. Run a full round

# Initialize platform config
yarn script config

# Create round: 5 min, 0.1 SOL minimum, 100 players max
yarn script create -t 300 -d 100000000 -j 100

# Join round 0 with 0.5 SOL
yarn script join -a 500000000 -g 0

# After the round ends, resolve the winner
yarn script winner -g 0

# Winner claims the pot
yarn script claim -g 0

Global CLI flags: -e cluster, -r RPC URL, -k keypair path.

---

CLI Reference

Command	Role	Example
config	Admin	yarn script config
create	Admin	yarn script create -t 300 -d 100000000 -j 100
join	Player	yarn script join -a 500000000 -g 0
winner	Admin	yarn script winner -g 0
claim	Winner	yarn script claim -g 0

Flag	Meaning
-t / --duration	Round duration in seconds
-d / --minDeposit	Minimum deposit in lamports
-j / --maxPlayers	Maximum players per round
-a / --amount	Deposit amount in lamports
-g / --roundId	Round id (0-indexed)

---

Program Instructions

Instruction	Caller	Purpose
configure	Admin	Create or update PlatformConfig
create_round	Admin	Open a round and request VRF
join_round	Player	Deposit SOL into a round
set_winner	Admin	Finalize winner from ORAO VRF
claim_reward	Winner	Transfer pool SOL from vault

---

On-Chain Accounts

PlatformConfig

Field	Description
authority	Admin signer for privileged instructions
payer_wallet	Pays account rent / reallocations
team_wallet	Receives platform fees
round_counter	Monotonic round index for PDA derivation
platform_fee_bps	Fee in basis points (10_000 = 100%)
min_deposit_amount	Global minimum deposit floor
max_player_count	Global maximum players per round

JackpotRound

Per-round state: timing, total_deposit, vrf_seed, winner, deposits[] (PlayerDeposit { player, amount }), and completion flags.

PDAs

Seed	Account
["config"]	PlatformConfig
["global"]	Global SOL vault
["jackpot_round", round_id_le_bytes]	JackpotRound

---

Security Notes

• Privileged instructions require PlatformConfig.authority.
• Randomness comes from ORAO VRF; admin only submits fulfillment, not arbitrary values.
• PDAs isolate config, rounds, and pooled funds.
• Safe arithmetic and explicit state guards on every transition.

Audit thoroughly and use a hardware wallet on mainnet. This software is provided as-is.

---

Development

# Build
RUSTUP_TOOLCHAIN="nightly-2024-11-19" anchor build

# Tests
anchor test

# Format / lint TypeScript
yarn lint
yarn lint:fix

After anchor build, copy generated artifacts from target/idl/ and target/types/ if you rely on full TypeScript typings.

---

Contact

Telegram: @xxninex

For questions, integrations, or collaboration, reach out on Telegram.

---

License

ISC