https://github.com/risc0/risc0 create shithead card game with integrating risc0, give me…
- User
https://github.com/risc0/risc0 create shithead card game with integrating risc0, give me everything step by step
Assistant
Okay, let's build a simplified command-line version of the Shithead card game and integrate RISC Zero to prove the initial shuffle and deal were done correctly according to the rules.
Goal: Create a basic Shithead game where the deck shuffling and initial card distribution are performed inside a RISC Zero zkVM. The host application will verify the ZK proof (receipt) to ensure the game starts with a fairly generated state.
Why RISC Zero here? We'll use it to generate cryptographic proof that:
- A standard 52-card deck was used.
- The deck was shuffled using a specified, publicly known algorithm (seeded by a public input).
- Cards were dealt according to Shithead rules (3 down, 3 up, 3 hand per player).
This prevents anyone from claiming the initial deal was rigged, as long as they trust the RISC Zero system and the guest code logic.
We will not be proving every single move within the ZK circuit in this example, as that adds significant complexity. We'll focus on the verifiable setup.
Steps:
Step 0: Prerequisites
- Install Rust: If you haven't already, install Rust and Cargo: https://www.rust-lang.org/tools/install
- Install
cargo-risczero: This tool helps manage RISC Zero projects.cargo install cargo-risczero - Install RISC Zero toolchain:
cargo risczero install
Step 1: Project Setup
- Create a new Rust project using the
cargo-risczerotemplate:
This creates a directory structure like:cargo risczero new shithead-zk cd shithead-zkshithead-zk/ ├── host/ # Code that runs on your machine (the Prover/Verifier) │ ├── src/ │ │ └── main.rs │ └── Cargo.toml ├── methods/ # Code that runs inside the zkVM (the Guest) │ ├── guest/ │ │ ├── src/ │ │ │ └── main.rs │ │ └── Cargo.toml │ └── build.rs # Build script for guest code ├── .gitignore └── Cargo.toml # Workspace Cargo file
Step 2: Define Core Game Logic (Shared Structures)
Since both the host and guest need to understand cards, decks, etc., let's define these structures. We could create a separate shared crate, but for simplicity, we'll define them in both
host/src/main.rsandmethods/guest/src/main.rs. Keep them identical!-
In
methods/guest/src/main.rs(and later copy tohost/src/main.rs): Add necessary dependencies tomethods/guest/Cargo.toml:[package] name = "shithead-methods-guest" version = "0.1.0" edition = "2021" [dependencies] risc0-zkvm = { version = "0.20", default-features = false, features = ["std"] } serde = { version = "1.0", default-features = false, features = ["derive"] } rand = { version = "0.8", default-features = false } rand_chacha = { version = "0.3", default-features = false } getrandom = { version = "0.2", features = ["custom"] } # Needed for rand within risc0- Add
getrandom::register_custom_getrandom!(risc0_fake_rng);somewhere before usingrand. - Define the structures:
// methods/guest/src/main.rs #![no_main] #![no_std] // Important for guest code extern crate alloc; // Use alloc crate for collections like Vec use alloc::vec; use alloc::vec::Vec; use alloc::string::{String, ToString}; // Use alloc's String use core::mem; // For mem::take use risc0_zkvm::guest::env; use serde::{Deserialize, Serialize}; use rand::{seq::SliceRandom, SeedableRng}; use rand_chacha::ChaCha8Rng; // Define a fake RNG source for the guest environment fn risc0_fake_rng(buf: &mut [u8]) -> Result<(), getrandom::Error> { // In a real scenario, you might want a more secure way or use host input // For now, fill with a deterministic pattern or zeros if needed, // but we'll seed ChaCha8Rng directly. // This function just needs to exist to satisfy the getrandom trait. for byte in buf.iter_mut() { *byte = 0; } Ok(()) } getrandom::register_custom_getrandom!(risc0_fake_rng); // --- Shared Game Logic Structures --- #[derive(Serialize, Deserialize, Debug, PartialEq, Eq, PartialOrd, Ord, Clone, Copy)] pub enum Suit { Clubs, Diamonds, Hearts, Spades } #[derive(Serialize, Deserialize, Debug, PartialEq, Eq, PartialOrd, Ord, Clone, Copy)] pub enum Rank { Two, Three, Four, Five, Six, Seven, Eight, Nine, Ten, Jack, Queen, King, Ace } impl Rank { // Assign numerical values for comparison if needed (optional for basic Shithead) fn value(&self) -> u8 { match self { Rank::Two => 2, Rank::Three => 3, Rank::Four => 4, Rank::Five => 5, Rank::Six => 6, Rank::Seven => 7, Rank::Eight => 8, Rank::Nine => 9, Rank::Ten => 10, Rank::Jack => 11, Rank::Queen => 12, Rank::King => 13, Rank::Ace => 14, } } } #[derive(Serialize, Deserialize, Debug, PartialEq, Eq, PartialOrd, Ord, Clone, Copy)] pub struct Card { rank: Rank, suit: Suit, } impl Card { fn new(rank: Rank, suit: Suit) -> Self { Card { rank, suit } } } // Implement Display for Card (using alloc::string) impl core::fmt::Display for Card { fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result { let rank_str = match self.rank { Rank::Two => "2", Rank::Three => "3", Rank::Four => "4", Rank::Five => "5", Rank::Six => "6", Rank::Seven => "7", Rank::Eight => "8", Rank::Nine => "9", Rank::Ten => "T", Rank::Jack => "J", Rank::Queen => "Q", Rank::King => "K", Rank::Ace => "A", }; let suit_char = match self.suit { Suit::Clubs => '♣', Suit::Diamonds => '♦', Suit::Hearts => '♥', Suit::Spades => '♠', }; write!(f, "{}{}", rank_str, suit_char) } } pub fn new_deck() -> Vec<Card> { let mut deck = Vec::with_capacity(52); for &suit in [Suit::Clubs, Suit::Diamonds, Suit::Hearts, Suit::Spades].iter() { for &rank in [ Rank::Two, Rank::Three, Rank::Four, Rank::Five, Rank::Six, Rank::Seven, Rank::Eight, Rank::Nine, Rank::Ten, Rank::Jack, Rank::Queen, Rank::King, Rank::Ace, ].iter() { deck.push(Card::new(rank, suit)); } } deck } #[derive(Serialize, Deserialize, Debug, Clone)] pub struct PlayerCards { face_down: Vec<Card>, // Kept private usually, but revealed in proof output for this example face_up: Vec<Card>, // Public hand: Vec<Card>, // Kept private usually } // Represents the publicly verifiable output of the setup phase #[derive(Serialize, Deserialize, Debug, Clone)] pub struct InitialGameData { player1_face_up: Vec<Card>, player2_face_up: Vec<Card>, // We won't reveal the actual private cards in the journal, // just prove they were dealt correctly. // We *could* commit to hashes of them if needed later. player1_hand_count: usize, player1_face_down_count: usize, player2_hand_count: usize, player2_face_down_count: usize, draw_pile_count: usize, // We could also include hashes of the dealt private cards here // player1_hand_hash: [u8; 32], // Example } // --- Guest Code Main Logic --- risc0_zkvm::guest::entry!(main); // Define the entrypoint pub fn main() { // 1. Read input seed from the host let seed: u64 = env::read(); // 2. Create PRNG from seed // Note: ChaCha8Rng is deterministic given the seed. let mut rng = ChaCha8Rng::seed_from_u64(seed); // 3. Create and shuffle the deck let mut deck = new_deck(); deck.shuffle(&mut rng); // 4. Deal cards (e.g., for 2 players) let num_players = 2; let mut players_cards: Vec<PlayerCards> = Vec::with_capacity(num_players); for _ in 0..num_players { players_cards.push(PlayerCards { face_down: Vec::with_capacity(3), face_up: Vec::with_capacity(3), hand: Vec::with_capacity(3), }); } // Deal face down for i in 0..3 { for player_idx in 0..num_players { if let Some(card) = deck.pop() { players_cards[player_idx].face_down.push(card); } else { panic!("Deck ran out unexpectedly during face down deal"); } } } // Deal face up for i in 0..3 { for player_idx in 0..num_players { if let Some(card) = deck.pop() { players_cards[player_idx].face_up.push(card); } else { panic!("Deck ran out unexpectedly during face up deal"); } } } // Deal hand for i in 0..3 { for player_idx in 0..num_players { if let Some(card) = deck.pop() { players_cards[player_idx].hand.push(card); } else { panic!("Deck ran out unexpectedly during hand deal"); } } } // Remaining deck is the draw pile let draw_pile_count = deck.len(); // 5. Prepare the public output // We only commit *publicly known* information or information // that is okay to reveal for this proof's purpose. // For Shithead setup, face-up cards are public. let output = InitialGameData { player1_face_up: players_cards[0].face_up.clone(), // Clone necessary data player2_face_up: players_cards[1].face_up.clone(), player1_hand_count: players_cards[0].hand.len(), player1_face_down_count: players_cards[0].face_down.len(), player2_hand_count: players_cards[1].hand.len(), player2_face_down_count: players_cards[1].face_down.len(), draw_pile_count, // Note: We are *not* committing the actual hand/face-down cards // to keep them private from observers just looking at the journal. // The proof implicitly guarantees they were dealt from the shuffled deck. }; // 6. Commit the output to the journal env::commit(&output); // The guest execution finishes here. The host will get the journal and a receipt. } - Add
Step 3: Build the Guest Code
Before writing the host, compile the guest code into a RISC-V executable and generate its Method ID.
-
Navigate to the
methodsdirectory:cd methods -
Build the guest:
cargo risczero buildThis creates:
../target/riscv32im-risc0-zkvm-elf/release/shithead-methods-guest: The RISC-V ELF file.../host/src/method_ids.rs(or similar): Contains theSHITHEAD_METHODS_GUEST_IDandSHITHEAD_METHODS_GUEST_ELF. The host code will use these.
-
Go back to the project root:
cd ..
Step 4: Create the Host Code
-
Copy Shared Structures: Copy the
Suit,Rank,Card,PlayerCards,InitialGameDatastructs and thenew_deckfunction from the guest code intohost/src/main.rs. You'll also need theDisplayimplementation forCard. -
Add Host Dependencies: Update
host/Cargo.toml:[package] name = "host" version = "0.1.0" edition = "2021" [dependencies] risc0-zkvm = { version = "0.20" } serde = "1.0" rand = "0.8" # For generating the seed in the host methods = { path = "../methods" } # Link to the methods crate build script output tracing-subscriber = { version = "0.3", features = ["env-filter"] } # Optional: for logging -
Write
host/src/main.rs:use risc0_zkvm::{ExecutorEnv, ExecutorImpl, Receipt, Session, VerifierContext}; use methods::{SHITHEAD_METHODS_GUEST_ELF, SHITHEAD_METHODS_GUEST_ID}; // Import from build script output use serde::{Deserialize, Serialize}; use rand::RngCore; // To generate a random seed // --- Paste the EXACT SAME shared game logic structures here --- // Suit, Rank, Card, PlayerCards, InitialGameData, new_deck, Display for Card // Make sure they are identical to the guest versions! // ... (Paste Suit enum here) ... #[derive(Serialize, Deserialize, Debug, PartialEq, Eq, PartialOrd, Ord, Clone, Copy)] pub enum Suit { Clubs, Diamonds, Hearts, Spades } // ... (Paste Rank enum here, including value() method if you kept it) ... #[derive(Serialize, Deserialize, Debug, PartialEq, Eq, PartialOrd, Ord, Clone, Copy)] pub enum Rank { Two, Three, Four, Five, Six, Seven, Eight, Nine, Ten, Jack, Queen, King, Ace } // ... (value() method if needed) ... // ... (Paste Card struct here) ... #[derive(Serialize, Deserialize, Debug, PartialEq, Eq, PartialOrd, Ord, Clone, Copy)] pub struct Card { rank: Rank, suit: Suit, } impl Card { fn new(rank: Rank, suit: Suit) -> Self { Card { rank, suit } } } // ... (Paste Display for Card here) ... // Need std::fmt now in the host impl std::fmt::Display for Card { fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result { let rank_str = match self.rank { Rank::Two => "2", Rank::Three => "3", Rank::Four => "4", Rank::Five => "5", Rank::Six => "6", Rank::Seven => "7", Rank::Eight => "8", Rank::Nine => "9", Rank::Ten => "T", Rank::Jack => "J", Rank::Queen => "Q", Rank::King => "K", Rank::Ace => "A", }; let suit_char = match self.suit { Suit::Clubs => '♣', Suit::Diamonds => '♦', Suit::Hearts => '♥', Suit::Spades => '♠', }; write!(f, "{}{}", rank_str, suit_char) } } // ... (Paste PlayerCards struct here) ... #[derive(Serialize, Deserialize, Debug, Clone)] pub struct PlayerCards { face_down: Vec<Card>, face_up: Vec<Card>, hand: Vec<Card>, } // ... (Paste InitialGameData struct here) ... #[derive(Serialize, Deserialize, Debug, Clone)] pub struct InitialGameData { player1_face_up: Vec<Card>, player2_face_up: Vec<Card>, player1_hand_count: usize, player1_face_down_count: usize, player2_hand_count: usize, player2_face_down_count: usize, draw_pile_count: usize, } // ... (Paste new_deck function here) ... pub fn new_deck() -> Vec<Card> { // ... (same implementation as guest) ... let mut deck = Vec::with_capacity(52); for &suit in [Suit::Clubs, Suit::Diamonds, Suit::Hearts, Suit::Spades].iter() { for &rank in [ Rank::Two, Rank::Three, Rank::Four, Rank::Five, Rank::Six, Rank::Seven, Rank::Eight, Rank::Nine, Rank::Ten, Rank::Jack, Rank::Queen, Rank::King, Rank::Ace, ].iter() { deck.push(Card::new(rank, suit)); } } deck } // --- Host Main Logic --- fn main() { // Optional: Initialize tracing for risc0 logs tracing_subscriber::fmt() .with_env_filter(tracing_subscriber::EnvFilter::from_default_env()) .init(); // 1. Generate a random seed for the PRNG in the guest // This seed is public input to the proof. let mut rng = rand::thread_rng(); let seed = rng.next_u64(); println!("Using seed: {}", seed); // 2. Set up the Executor environment let env = ExecutorEnv::builder() .add_input(&[seed]) // Pass the seed to the guest .build() .expect("Failed to build executor environment"); // 3. Create an Executor and run the guest code // This runs the zkVM execution locally. For production, you might use a remote prover. println!("Running the ZKVM guest code (shuffle and deal)..."); let mut exec = ExecutorImpl::from_elf(env, SHITHEAD_METHODS_GUEST_ELF) .expect("Failed to create executor"); let session = exec.run().expect("Guest code execution failed"); // 4. Prove the session to generate a receipt println!("Generating ZK proof..."); let receipt = session.prove().expect("Proving failed"); println!("Proof generated."); // 5. Verify the receipt // This checks the cryptographic proof against the known Method ID. // Anyone can run this verification step without re-running the execution. println!("Verifying the ZK proof..."); receipt .verify(SHITHEAD_METHODS_GUEST_ID) .expect("Proof verification failed"); println!("Proof verified successfully!"); // 6. Extract the public output (journal) from the receipt let initial_data: InitialGameData = receipt .journal .decode() .expect("Failed to decode journal output"); println!("\n--- Verified Initial Game State ---"); println!("Player 1 Face Up: {:?}", initial_data.player1_face_up.iter().map(|c| c.to_string()).collect::<Vec<_>>()); println!("Player 2 Face Up: {:?}", initial_data.player2_face_up.iter().map(|c| c.to_string()).collect::<Vec<_>>()); println!("Player 1 Hand Size: {}", initial_data.player1_hand_count); println!("Player 1 Face Down Size: {}", initial_data.player1_face_down_count); println!("Player 2 Hand Size: {}", initial_data.player2_hand_count); println!("Player 2 Face Down Size: {}", initial_data.player2_face_down_count); println!("Draw Pile Size: {}", initial_data.draw_pile_count); println!("\nProof guarantees the deck was standard, shuffled with seed {}, and dealt correctly.", seed); println!("You can now proceed with the game using this verified initial state."); // --- TODO: Implement the actual Shithead game logic here --- // This part runs *outside* the ZK proof for this example. // You would use the 'initial_data' to set up your game state. // You would need to: // - Reconstruct the full (private) state for the host/players if needed. // (Since we didn't commit private cards, the host can't fully reconstruct // just from the journal. A real game would need a way to distribute // the private info securely after verification, or include it encrypted // in the journal, or have players generate parts of the proof). // - Implement turns, playing rules, drawing, special cards (2, 7, 10), etc. // - Handle player input and display the game state. // - Check for win conditions. // run_game(initial_data); // Placeholder for game loop function } // fn run_game(initial_data: InitialGameData) { // println!("\nStarting game (basic logic - not implemented)..."); // // ... Full game implementation goes here ... // }
Step 5: Run the Host Application
- Make sure you are in the project root directory (
shithead-zk). - Run the host code:
cargo run
You should see output similar to this:
Using seed: 1234567890123456789 # (Will be a different random number each time) Running the ZKVM guest code (shuffle and deal)... Generating ZK proof... Proof generated. Verifying the ZK proof... Proof verified successfully! --- Verified Initial Game State --- Player 1 Face Up: ["Q♠", "3♦", "8♣"] # (Example cards, will vary) Player 2 Face Up: ["K♥", "A♣", "5♠"] # (Example cards, will vary) Player 1 Hand Size: 3 Player 1 Face Down Size: 3 Player 2 Hand Size: 3 Player 2 Face Down Size: 3 Draw Pile Size: 34 Proof guarantees the deck was standard, shuffled with seed 1234567890123456789, and dealt correctly. You can now proceed with the game using this verified initial state.Explanation:
- Guest (
methods/guest/src/main.rs):- Runs inside the RISC Zero zkVM.
- Takes a
seedas private input from the host. - Creates a standard deck.
- Shuffles it deterministically using
ChaCha8Rngseeded with the inputseed. - Deals cards according to the rules (3 down, 3 up, 3 hand for 2 players).
- Constructs the
InitialGameDatacontaining only the publicly known results (face-up cards, counts of private cards). env::commits this public data to the journal.
- Host (
host/src/main.rs):- Generates a random
seed. - Sets up the
ExecutorEnv, providing theseedas input to the guest. - Runs the guest code using
ExecutorImpl::run(). This executes the RISC-V ELF we built earlier. - Generates a
Receiptusingsession.prove(). This contains the journal output and the ZK proof. - Crucially, it verifies the
receiptusingreceipt.verify(SHITHEAD_METHODS_GUEST_ID). This mathematical check confirms the guest code (identified bySHITHEAD_METHODS_GUEST_ID) produced the journal output according to its logic, without needing to trust the host that ran the execution. - Decodes the
InitialGameDatafrom the verified receipt's journal. - Prints the verified initial state.
- Generates a random
Next Steps & Improvements:
- Implement Game Logic: Build the rest of the Shithead game loop in the
hostusing the verifiedinitial_data. This involves handling turns, player input, card validation, special cards, drawing, and winning conditions. - Private State Distribution: In a real multi-player scenario, the host (or a trusted setup service) running the proof would need a way to securely communicate the private hands and face-down cards to the respective players after the proof is generated and verified. The current example doesn't handle this distribution.
- ZK for Moves (Advanced): To prove each move is valid, you would:
- Define the game state transition logic within a new guest method.
- Input to the guest: Current public game state (or hash), player's private hand, intended move.
- Guest logic: Validate the move against the rules and the player's hand. Calculate the new game state.
- Output (Journal): New public game state (or hash), public description of the move ("Player played Ace").
- The host would run this proof for each turn, verifying each state transition. This is much more complex.
- Error Handling: Add more robust error handling (e.g., using
Resultinstead ofexpect). - Input/Output: Create a more interactive command-line interface or a graphical UI.
This example provides a solid foundation for using RISC Zero to establish verifiable trust in the setup phase of your Shithead game.
Other models, same or similar prompt
Responses were produced in different, uncontrolled contexts (system prompts, settings, prior turns). This is not a benchmark.