🃏 Arcium Poker - Encrypted Texas Hold'em on Solana

A fully-featured poker game with Arcium Multi-Party Computation (MPC) integration

---

🎯 Project Overview

This project implements a complete Texas Hold'em poker game on Solana with real Arcium MPC integration for:

• 🔀 Fair deck shuffling - Multi-party computation ensures no single player controls the shuffle
• 🎴 Encrypted card dealing - Cards encrypted to specific players using owner-specific keys
• 👁️ Secure showdown - Threshold decryption reveals cards fairly

🚀 Live on Devnet

Program ID: Cm5y2aab75vj9dpRcyG1EeZNgeh4GZLRkN3BmmRVNEwZ
Network:    Solana Devnet
RPC:        https://api.devnet.solana.com
Explorer:   https://explorer.solana.com/address/Cm5y2aab75vj9dpRcyG1EeZNgeh4GZLRkN3BmmRVNEwZ?cluster=devnet

---

✨ Features

✅ Complete Poker Game

• Full Texas Hold'em rules (Pre-flop, Flop, Turn, River, Showdown)
• Betting rounds with raise, call, fold, check, all-in
• Side pot handling for multiple all-ins
• Automatic blind posting
• Tournament support
• Statistics tracking

🔐 Arcium MPC Integration

• 4 MPC Circuits in encrypted-ixs/:

  • shuffle_deck() - Fisher-Yates shuffle in MPC
  • deal_card() - Encrypted card dealing
  • reveal_hole_cards() - Threshold decryption at showdown
  • generate_random() - Secure randomness

• Dual-Mode Operation:

  • Production: Uses real Arcium MXE via CPI
  • Testing: Falls back to deterministic mock

🧪 Comprehensive Testing

• 48/48 tests passing
• Full coverage of game logic
• MXE integration tests
• Edge case handling

---

🚀 Quick Start

Prerequisites

# Install Rust
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

# Install Solana
sh -c "$(curl -sSfL https://release.solana.com/stable/install)"

# Install Anchor
cargo install --git https://github.com/coral-xyz/anchor avm --locked --force
avm install latest
avm use latest

# Install Node dependencies
yarn install

Build

# Build Solana program
anchor build

# Build MPC circuits
cd encrypted-ixs && cargo build

Test

# Run all tests (48 tests)
npm test

# Run specific test file
anchor test --skip-build tests/test_betting.ts

---

📁 Project Structure

arcium_poker/
├── programs/
│   └── arcium_poker/          # Main Solana program
│       └── src/
│           ├── arcium/        # ✅ MPC integration (Phase 3 complete)
│           │   ├── mpc_shuffle.rs    # Dual-mode shuffle
│           │   ├── mpc_deal.rs       # Dual-mode dealing
│           │   ├── mpc_reveal.rs     # Dual-mode reveal
│           │   └── integration.rs    # MXE helpers
│           ├── betting/       # Betting logic
│           ├── cards/         # Card handling
│           ├── game/          # Game flow
│           ├── player/        # Player management
│           └── showdown/      # Winner determination
│
├── encrypted-ixs/             # ✅ Arcium MPC circuits
│   └── src/
│       └── lib.rs             # 4 confidential instructions
│
├── tests/                     # ✅ 48 passing tests
│   ├── test_betting.ts
│   ├── test_game_flow.ts
│   ├── test_mxe_integration.ts  # NEW: MXE examples
│   └── ...
│
└── Documentation/
    ├── PHASE_3_COMPLETE.md           # Integration guide
    ├── IMPLEMENTATION_STATUS.md      # Feature status
    └── FULL_MPC_INTEGRATION_ROADMAP.md

---

🔐 Arcium MPC Architecture

How It Works

┌─────────────────────────────────────────────────────┐
│  1. SHUFFLE                                         │
│     Players → Entropy → MPC Shuffle → Encrypted Deck│
│                                                     │
│  2. DEAL                                            │
│     Encrypted Deck → MPC Deal → Player-Specific Key│
│                                                     │
│  3. REVEAL                                          │
│     Encrypted Cards → Threshold Decrypt → Revealed │
└─────────────────────────────────────────────────────┘

Dual-Mode Operation

// Production: With MXE accounts
let result = mpc_shuffle_deck_with_mxe(MxeShuffleParams {
    mxe_program: Some(mxe_program),  // ✅ Real MPC
    comp_def: Some(comp_def),
    mempool: Some(mempool),
    cluster: Some(cluster),
    // ...
})?;

// Testing: Without MXE accounts
let result = mpc_shuffle_deck_with_mxe(MxeShuffleParams {
    mxe_program: None,  // ✅ Mock mode
    comp_def: None,
    mempool: None,
    cluster: None,
    // ...
})?;

---

🧪 Testing

Run All Tests

npm test
# ✅ 48 passing (2m)

Test Categories

• Betting Tests (12 tests) - Raises, calls, folds, all-ins
• Game Flow Tests (11 tests) - Stage transitions, game lifecycle
• Game Initialization (7 tests) - Valid/invalid configurations
• Player Actions (7 tests) - Join, leave, edge cases
• Side Pots (3 tests) - Multiple all-ins, complex scenarios
• Edge Cases (7 tests) - Race conditions, zero values
• MXE Integration (1 test) - Mock mode demonstration

---

🚀 Deployment

✅ Deployed to Devnet!

Program ID: Cm5y2aab75vj9dpRcyG1EeZNgeh4GZLRkN3BmmRVNEwZ Network: Devnet RPC Endpoint: https://api.devnet.solana.com Deployed Slot: 416979428 MXE Cluster: 1078779259

Frontend Integration

import { Program, AnchorProvider } from "@coral-xyz/anchor";
import { PublicKey } from "@solana/web3.js";
import idl from "./idl/arcium_poker.json";
import { ArciumPoker } from "./types/arcium_poker";

// Program configuration
const PROGRAM_ID = new PublicKey("Cm5y2aab75vj9dpRcyG1EeZNgeh4GZLRkN3BmmRVNEwZ");
const RPC_ENDPOINT = "https://api.devnet.solana.com";

// Initialize program
const connection = new Connection(RPC_ENDPOINT, "confirmed");
const provider = new AnchorProvider(connection, wallet, {});
const program = new Program<ArciumPoker>(idl, PROGRAM_ID, provider);

// Call contract methods
await program.methods
  .initializeGame(gameId, smallBlind, bigBlind, minBuyIn, maxBuyIn, maxPlayers)
  .accounts({ authority: wallet.publicKey })
  .rpc();

Environment Variables

Create .env.local in your frontend:

NEXT_PUBLIC_PROGRAM_ID=Cm5y2aab75vj9dpRcyG1EeZNgeh4GZLRkN3BmmRVNEwZ
NEXT_PUBLIC_RPC_ENDPOINT=https://api.devnet.solana.com
NEXT_PUBLIC_NETWORK=devnet

Real MPC Integration

Deploy MXE Program ✅ DONE!

# MXE deployed to cluster 1078779259
arcium deploy --cluster-offset 1078779259 --keypair-path ~/.config/solana/id.json -u d

Use Real MPC in Frontend

// See HOW_TO_USE_REAL_MPC.md for complete integration guide
import { getMxeAccount, getCompDefAccount, getClusterAccount } from "./utils/arcium";

// Get MXE accounts for real MPC
const mxeAccount = getMxeAccount(PROGRAM_ID);
const compDefAccount = getCompDefAccount(PROGRAM_ID, 1);
const clusterAccount = getClusterAccount(PROGRAM_ID, 1078779259);

// Start game with REAL encrypted MPC!
await program.methods
  .startGame(entropy)
  .accounts({
    game,
    authority: wallet.publicKey,
    mxeProgram: PROGRAM_ID,
    compDef: compDefAccount,
    cluster: clusterAccount,
  })
  .rpc();

Step 1: Deploy MXE Program

cd encrypted-ixs
cargo build-sbf
solana program deploy target/deploy/encrypted_ixs.so

Step 2: Initialize Arcium

arcium init-mxe --program-id <YOUR_MXE_ID>
arcium init-cluster --name poker-cluster

Step 3: Update Client with MXE

const MXE_PROGRAM_ID = new PublicKey("YOUR_MXE_ID");

// Derive MXE accounts
const [compDef] = PublicKey.findProgramAddressSync(
  [Buffer.from("comp_def"), Buffer.from("shuffle_deck")],
  MXE_PROGRAM_ID
);

// Use in transactions
await program.methods
  .startGame(playerEntropy)
  .accounts({
    game,
    authority,
    // MXE accounts automatically enable real MPC
    mxeProgram: MXE_PROGRAM_ID,
    compDef,
    mempool,
    cluster,
  })
  .rpc();

---

📊 Project Status

Component	Status	Completion
Poker Game Logic	✅ DONE	100%
MPC Circuits	✅ DONE	100%
MXE Integration	✅ DONE	100%
Tests	✅ PASSING	48/48
Documentation	✅ COMPLETE	100%
Deployment	✅ DEPLOYED	100%

Overall: 100% Complete (Deployed to Devnet!)

---

🏆 Hackathon Highlights

Innovation

1. Dual-Mode Architecture - Seamless MXE/mock switching
2. Cross-Program Invocation - Direct MXE calls from Solana
3. Threshold Decryption - Multi-party showdown reveals
4. Owner-Specific Encryption - Privacy-preserving card dealing

Technical Excellence

• ✅ Clean, modular code
• ✅ Comprehensive test coverage
• ✅ Production-ready error handling
• ✅ Detailed documentation

---

📚 Documentation

• MXE_DEPLOYMENT_INFO.md - Complete deployment details and MPC configuration
• HOW_TO_USE_REAL_MPC.md - Frontend integration guide for real MPC
• PHASE_3_COMPLETE.md - Full integration guide
• IMPLEMENTATION_STATUS.md - Feature checklist
• FULL_MPC_INTEGRATION_ROADMAP.md - Development roadmap
• tests/test_mxe_integration.ts - Code examples

---

How to Play

1. Initialize Game

await program.methods
  .initializeGame(
    gameId,
    smallBlind,
    bigBlind,
    minBuyIn,
    maxBuyIn,
    maxPlayers
  )
  .accounts({ authority: wallet.publicKey })
  .rpc();

2. Join Game

await program.methods
  .joinGame(buyIn)
  .accounts({ game, player })
  .rpc();

3. Start Game (with Real MPC!)

const playerEntropy = generateEntropy(); // Client-side

// Use mock mode (default)
await program.methods
  .startGame(playerEntropy)
  .accounts({ game, authority })
  .rpc();

// Or use REAL MPC (see HOW_TO_USE_REAL_MPC.md)
const PROGRAM_ID = new PublicKey("Cm5y2aab75vj9dpRcyG1EeZNgeh4GZLRkN3BmmRVNEwZ");
const mxeAccounts = {
  mxeProgram: PROGRAM_ID,
  compDef: getCompDefAccount(PROGRAM_ID, 1),
  cluster: getClusterAccount(PROGRAM_ID, 1078779259),
};

await program.methods
  .startGame(playerEntropy)
  .accounts({ game, authority, ...mxeAccounts })
  .rpc(); // 🔐 Real encrypted MPC shuffle!

4. Play

// Bet
await program.methods.bet(amount).rpc();

// Call
await program.methods.call().rpc();

// Fold
await program.methods.fold().rpc();

// All-in
await program.methods.allIn().rpc();

---

🤝 Contributing

This is a hackathon project, but contributions are welcome!

Areas for Improvement

• Deploy to devnet - DONE!
• Deploy MXE circuits to devnet - DONE! (Cluster 1078779259)
• Add callback server for MPC results (optional - current architecture works)
• Implement frontend UI
• Add more game variants (Omaha, 7-Card Stud)
• Performance optimization
• Add tournament brackets
• Implement rake/fees system

---

📄 License

MIT License - See LICENSE file for details

---

🙏 Acknowledgments

• Arcium - For the amazing MPC infrastructure
• Solana - For the fast, scalable blockchain
• Anchor - For the excellent Solana framework

---

📞 Contact

• GitHub: @ANAVHEOBA
• Twitter: @AnavheobaDEV
• Discord: anavheoba_17

---

🎯 Hackathon Submission

Track: Arcium's Side Track Category: Hidden-Information Games Status: ✅ DEPLOYED & READY

What We Built

A complete Texas Hold'em poker game with real Arcium MPC integration for fair, encrypted gameplay.

Key Features

• ✅ 48/48 tests passing
• ✅ 4 working MPC circuits deployed
• ✅ Full integration layer with CPI calls
• ✅ Dual-mode operation (mock + real MPC)
• ✅ Deployed to Devnet (both Solana program & MXE)
• ✅ Production-ready architecture

Live Deployment

• Program ID: Cm5y2aab75vj9dpRcyG1EeZNgeh4GZLRkN3BmmRVNEwZ
• MXE Cluster: 1078779259
• Network: Solana Devnet
• Explorer: View on Solana Explorer

Demo

See tests/test_mxe_integration.ts for live examples of MXE integration, and HOW_TO_USE_REAL_MPC.md for complete frontend integration guide.

---

Built with ❤️ for the Arcium Hackathon