diff --git a/ceremony/attestations/README.md b/ceremony/attestations/README.md new file mode 100644 index 0000000..2c0dd1b --- /dev/null +++ b/ceremony/attestations/README.md @@ -0,0 +1,83 @@ +# Ceremony Attestations + +This directory contains signed attestations from ceremony participants. + +## Purpose + +Each participant signs an attestation confirming: +1. They generated genuine randomness +2. They followed the ceremony process +3. **They destroyed their toxic waste** + +These attestations create public accountability and transparency. + +## Attestation Format + +Each attestation is a text file (optionally PGP-signed) containing: + +``` +BitCell Trusted Setup Ceremony Attestation + +Ceremony: [BattleCircuit | StateCircuit] +Round: N +Date: YYYY-MM-DD +Participant: [Name or Pseudonym] + +I hereby attest that: + +1. I generated the contribution independently using genuine randomness. + Entropy sources used: [description] + +2. I verified the input parameters matched the published hash. + Input hash: abc123... + +3. I ran the contribution tool and verified the output. + Output hash: def456... + +4. I securely destroyed all files containing toxic waste: + [detailed destruction method] + +5. To the best of my knowledge, no copies remain. + +6. I acted in good faith to support BitCell security. + +Signature: [PGP signature or contact info] +Date: YYYY-MM-DD +``` + +## Files + +After the ceremony completes, this directory will contain: + +- `battle_round_01_alice.txt` - Alice's attestation for BattleCircuit round 1 +- `battle_round_02_bob.txt.asc` - Bob's PGP-signed attestation +- `state_round_01_alice.txt` - Alice's attestation for StateCircuit round 1 +- ... (one file per participant per circuit) + +## Verification + +To verify a PGP-signed attestation: + +```bash +# Import participant's public key (if available) +gpg --import participant_pubkey.asc + +# Verify signature +gpg --verify battle_round_01_alice.txt.asc +``` + +For unsigned attestations, verification relies on: +- Matching to public transcript +- Cross-referencing with coordinator records +- Community recognition of participant identity + +## Status + +**Current Status:** Awaiting Ceremony (Q1 2026) + +This directory will be populated as participants contribute to the ceremony. + +--- + +**Last Updated:** December 2025 +**Ceremony Status:** Planning Phase diff --git a/ceremony/coordinator_checklist.md b/ceremony/coordinator_checklist.md new file mode 100644 index 0000000..ee03440 --- /dev/null +++ b/ceremony/coordinator_checklist.md @@ -0,0 +1,391 @@ +# Ceremony Coordinator Checklist + +**Version:** 1.0 +**Target Date:** Q1 2026 +**Status:** Planning Phase + +This checklist guides the ceremony coordinator through all phases of the trusted setup. + +--- + +## Pre-Ceremony (4-6 weeks before) + +### Week -6 to -4: Infrastructure Setup + +- [ ] **Set up ceremony server infrastructure** + - [ ] Provision secure server with TLS certificates + - [ ] Set up upload/download endpoints + - [ ] Configure monitoring and logging + - [ ] Test bandwidth and reliability + - [ ] Set up backup mirrors + +- [ ] **Build ceremony tools** + - [ ] Build `ceremony-contribute` binary for Linux/macOS/Windows + - [ ] Build `ceremony-verify` tool + - [ ] Build `ceremony-coordinator` tool + - [ ] Test tools on multiple platforms + - [ ] Create release packages + +- [ ] **Prepare documentation** + - [ ] Finalize participant instructions + - [ ] Create FAQ document + - [ ] Prepare announcement templates + - [ ] Set up communication channels (Discord, Telegram, email) + +- [ ] **Security audit of ceremony code** + - [ ] Internal code review + - [ ] External security review (if budget permits) + - [ ] Penetration testing of server infrastructure + - [ ] Document security measures + +### Week -4 to -2: Participant Recruitment + +- [ ] **Create participant list** + - [ ] Target: 20-30 participants minimum + - [ ] Aim for geographic diversity (5+ countries) + - [ ] Aim for background diversity (devs, academics, enterprises) + - [ ] Document independence verification methods + +- [ ] **Outreach campaigns** + - [ ] Blog post announcing ceremony + - [ ] Social media announcements (Twitter, Reddit, Discord) + - [ ] Email to BitCell community mailing list + - [ ] Reach out to academic institutions + - [ ] Contact blockchain security firms + - [ ] Contact partner projects + +- [ ] **Collect participant registrations** + - [ ] Create registration form + - [ ] Collect names/pseudonyms + - [ ] Collect contact info (email/Telegram) + - [ ] Collect PGP keys (optional) + - [ ] Verify independence of participants + - [ ] Document verification evidence + +### Week -2 to 0: Pre-Ceremony Prep + +- [ ] **Schedule contribution slots** + - [ ] Assign each participant a specific time window (1-2 days) + - [ ] Build buffer time between contributions + - [ ] Accommodate timezone differences + - [ ] Send calendar invites + +- [ ] **Participant preparation** + - [ ] Send participant instructions document + - [ ] Provide download credentials + - [ ] Conduct test runs with willing participants + - [ ] Set up support channels + - [ ] Answer pre-ceremony questions + +- [ ] **Generate initial parameters** + - [ ] Choose random beacon (recent Bitcoin block hash) + - [ ] Generate initial parameters from beacon + - [ ] Compute hash of initial parameters + - [ ] Publish hash as public commitment + - [ ] Announce ceremony start date + +- [ ] **Final checks** + - [ ] Test full ceremony flow end-to-end + - [ ] Verify all tools work correctly + - [ ] Confirm server capacity + - [ ] Prepare incident response plan + - [ ] Brief support team + +--- + +## During Ceremony (2-3 weeks per circuit) + +### BattleCircuit Ceremony + +**Initialize Round 0:** + +- [ ] Select Bitcoin block for random beacon + - [ ] Use a future block (e.g., "block mined on ceremony start date") + - [ ] Document block number and hash + - [ ] Publish on website, social media, and Discord + +- [ ] Generate initial parameters + ```bash + ./ceremony-coordinator init \ + --circuit battle \ + --beacon \ + --output params_round_0.bin + ``` + +- [ ] Publish initial parameters + - [ ] Upload to ceremony server + - [ ] Compute and announce hash + - [ ] Post to IPFS as backup + - [ ] Update ceremony website + +**For Each Contribution (Round 1 to N):** + +- [ ] **Before participant contribution** + - [ ] Notify participant their window is open + - [ ] Provide download link for `params_round_X.bin` + - [ ] Provide expected hash for verification + - [ ] Remind them of timeline (they have 24-48 hours) + +- [ ] **During participant contribution** + - [ ] Monitor upload progress + - [ ] Provide support via Discord/Telegram if needed + - [ ] Be available for troubleshooting + +- [ ] **After receiving contribution** + - [ ] Download contribution file + - [ ] Verify hash matches participant's reported hash + - [ ] Run verification tool: + ```bash + ./ceremony-verify \ + --input params_round_X.bin \ + --output params_round_X+1.bin \ + --proof contribution_proof_X.json + ``` + - [ ] If verification fails: + - [ ] Contact participant + - [ ] Debug issue + - [ ] Allow re-attempt if needed + - [ ] If verification succeeds: + - [ ] Publish updated parameters as `params_round_X+1.bin` + - [ ] Compute and publish hash + - [ ] Update transcript with contribution details + - [ ] Post announcement: + ``` + Round X accepted + Participant: [Name] + Input: sha256:... + Output: sha256:... + Verified: ✓ + Timestamp: [UTC] + ``` + - [ ] Thank participant publicly + - [ ] Collect participant's attestation + +- [ ] **Move to next round** + - [ ] Notify next participant + - [ ] Repeat process + +**After All Contributions:** + +- [ ] **Generate final keys** + ```bash + ./ceremony-coordinator finalize \ + --circuit battle \ + --input params_round_N.bin \ + --output-dir keys/battle/ + ``` + +- [ ] Verify final keys + - [ ] Compute proving key hash + - [ ] Compute verification key hash + - [ ] Test proof generation and verification + - [ ] Run test cases with final keys + +- [ ] **Publish final keys** + - [ ] Commit to repository: `keys/battle/` + - [ ] Upload to IPFS + - [ ] Create BitTorrent + - [ ] Update website + - [ ] Publish hashes everywhere + +- [ ] **Generate and publish transcript** + - [ ] Compile full ceremony log + - [ ] Include all participant attestations + - [ ] Include all verification proofs + - [ ] Include random beacon + - [ ] Commit to repository: `ceremony/transcripts/battle_transcript.json` + +### StateCircuit Ceremony + +Repeat the same process as BattleCircuit ceremony for StateCircuit. + +--- + +## Post-Ceremony (1-2 weeks after) + +### Verification and Announcement + +- [ ] **Independent verification** + - [ ] Invite external auditors to verify transcript + - [ ] Publish verification tools and data + - [ ] Document any verification findings + - [ ] Address any concerns raised + +- [ ] **Public announcement** + - [ ] Blog post: "BitCell Trusted Setup Complete" + - [ ] Social media announcement + - [ ] Email to community + - [ ] Press release (if applicable) + - [ ] Update docs with "Ceremony Complete" status + +- [ ] **Repository updates** + - [ ] Tag release: `ceremony-complete-v1.0` + - [ ] Update README with key hashes + - [ ] Update CEREMONY.md with results + - [ ] Archive ceremony tools + +### Participant Recognition + +- [ ] **Public acknowledgment** + - [ ] Update ceremony page with all participant names + - [ ] Create ceremony Hall of Fame page + - [ ] Publish list of participants and their contributions + +- [ ] **Commemorative NFTs (optional)** + - [ ] Design commemorative NFT + - [ ] Mint NFTs for participants + - [ ] Distribute to participant addresses + +- [ ] **Thank you communications** + - [ ] Send personal thank you emails + - [ ] Public shout-outs on social media + - [ ] Feature participants in blog posts + +### Documentation and Archival + +- [ ] **Complete documentation** + - [ ] Final ceremony report + - [ ] Statistical analysis (participation rate, timing, etc.) + - [ ] Lessons learned document + - [ ] Update RELEASE_REQUIREMENTS.md + +- [ ] **Long-term archival** + - [ ] Archive all ceremony files + - [ ] Multiple backup locations + - [ ] IPFS pinning + - [ ] Cold storage backups + +- [ ] **Integration verification** + - [ ] Test keys work in node software + - [ ] Update CI/CD to use ceremony keys + - [ ] Document key loading process for node operators + - [ ] Monitor initial network usage + +--- + +## Incident Response + +### If Participant Drops Out + +- [ ] Wait 24 hours past their deadline +- [ ] Attempt to contact participant +- [ ] If no response, move to next participant +- [ ] Document skip in transcript +- [ ] Continue ceremony + +### If Contribution Fails Verification + +- [ ] Contact participant immediately +- [ ] Debug the issue together +- [ ] Check if input parameters were correct +- [ ] Check if tools were built correctly +- [ ] Allow re-attempt with fresh parameters +- [ ] If repeated failures, may need to skip + +### If Security Issue Discovered + +- [ ] Pause ceremony immediately +- [ ] Assess the severity +- [ ] Notify all participants +- [ ] Fix the issue +- [ ] Determine if restart is needed +- [ ] Document the incident and resolution + +### If Website/Server Goes Down + +- [ ] Switch to backup mirror +- [ ] Notify participants of new URL +- [ ] Investigate root cause +- [ ] Restore primary service +- [ ] Document downtime + +--- + +## Tools and Commands Reference + +### Coordinator Tool Commands + +```bash +# Initialize ceremony with random beacon +./ceremony-coordinator init \ + --circuit [battle|state] \ + --beacon \ + --output params_round_0.bin + +# Verify a contribution +./ceremony-verify \ + --input params_round_N.bin \ + --output params_round_N+1.bin \ + --proof contribution_proof.json + +# Generate final keys +./ceremony-coordinator finalize \ + --circuit [battle|state] \ + --input params_round_final.bin \ + --output-dir keys/[battle|state]/ + +# Generate transcript +./ceremony-coordinator transcript \ + --ceremony-dir ceremony_data/ \ + --output transcript.json +``` + +### Hash Computation + +```bash +# Compute SHA-256 hash +sha256sum params_round_N.bin + +# Verify hash matches +echo " params_round_N.bin" | sha256sum -c +``` + +### Key Distribution + +```bash +# Upload to IPFS +ipfs add -r keys/ + +# Create torrent +transmission-create keys/ -o bitcell-keys.torrent + +# Publish hashes +echo "## Key Hashes" > KEY_HASHES.md +sha256sum keys/battle/*.bin >> KEY_HASHES.md +sha256sum keys/state/*.bin >> KEY_HASHES.md +``` + +--- + +## Contact Information + +**Coordinator:** [Name/Team] +**Email:** ceremony@bitcell.org +**Backup:** [Alternative contact] +**Emergency:** [Phone number for critical issues] + +**Support Channels:** +- Discord: #ceremony-support +- Telegram: @BitCellCeremony +- Email: ceremony@bitcell.org + +--- + +## Success Criteria + +The ceremony is considered successful when: + +- [x] At least 20 independent participants contributed +- [x] All contributions verified successfully +- [x] Final keys generated and tested +- [x] Keys published to multiple distribution channels +- [x] Full transcript published with all attestations +- [x] Independent verification completed +- [x] No security issues discovered +- [x] Community confidence in the ceremony + +--- + +**Last Updated:** December 2025 +**Ceremony Status:** Planning Phase +**Next Review:** Before ceremony start diff --git a/ceremony/participant_instructions.md b/ceremony/participant_instructions.md new file mode 100644 index 0000000..2f9db4e --- /dev/null +++ b/ceremony/participant_instructions.md @@ -0,0 +1,606 @@ +# Participant Instructions for BitCell Trusted Setup Ceremony + +**Version:** 1.0 +**Date:** December 2025 +**Estimated Time:** 2-4 hours + +Thank you for participating in the BitCell trusted setup ceremony! Your contribution is **critical** to the security of the BitCell blockchain. + +--- + +## Table of Contents + +1. [Before You Start](#before-you-start) +2. [Environment Setup](#environment-setup) +3. [Generating Randomness](#generating-randomness) +4. [Making Your Contribution](#making-your-contribution) +5. [Verification](#verification) +6. [Destroying Secrets](#destroying-secrets) +7. [Attestation](#attestation) +8. [Troubleshooting](#troubleshooting) + +--- + +## Before You Start + +### Understanding Your Role + +As a ceremony participant, you will: +1. Download parameters from the previous participant (or initial beacon) +2. Mix in your own randomness +3. Generate updated parameters +4. Upload your contribution to the coordinator +5. **Destroy all secrets** from your machine +6. Attest that you destroyed your secrets + +**Critical:** As long as you destroy your secrets, the final keys will be secure - even if all other participants are compromised! + +### Prerequisites + +- **Time:** Block out 2-4 hours (contribution ~30 min, but allow time for downloads/uploads) +- **Hardware:** Computer with 16GB+ RAM, 20GB+ free disk space +- **OS:** Linux, macOS, or Windows (Linux/macOS recommended) +- **Internet:** Stable connection for downloading parameters (~2-5 GB) +- **Software:** Rust toolchain (we'll install this) + +### Security Recommendations + +**HIGHLY RECOMMENDED:** +- ✅ Use a dedicated VM or fresh machine +- ✅ Disconnect from the internet during contribution (after downloading params) +- ✅ Use physical entropy sources (dice, coins) for randomness +- ✅ Wipe the machine completely after contribution + +**ACCEPTABLE:** +- ⚠️ Use your regular machine but follow cleanup steps carefully +- ⚠️ Stay online if necessary, but be aware of attack surface + +**NOT RECOMMENDED:** +- ❌ Using a shared machine where others have access +- ❌ Skipping cleanup steps +- ❌ Reusing the machine for ceremony-related work afterwards + +--- + +## Environment Setup + +### Step 1: Prepare Your Machine + +If using a VM (recommended): +```bash +# Create a fresh Ubuntu VM with at least: +# - 4 CPU cores +# - 16 GB RAM +# - 30 GB disk +``` + +If using your regular machine: +```bash +# Create a dedicated directory +mkdir -p ~/bitcell-ceremony +cd ~/bitcell-ceremony +``` + +### Step 2: Install Rust + +```bash +# Install Rust toolchain +curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh +source $HOME/.cargo/env + +# Verify installation +rustc --version +cargo --version +``` + +### Step 3: Clone Repository + +```bash +# Clone BitCell repository +git clone https://github.com/Steake/BitCell.git +cd BitCell + +# Check out ceremony branch (if applicable) +git checkout ceremony-2025 + +# Build ceremony tools +cd ceremony/tools +cargo build --release +``` + +### Step 4: Contact Coordinator + +Before proceeding, contact the ceremony coordinator to: +1. Confirm your participation slot +2. Get download credentials/URLs +3. Verify the expected hash of input parameters +4. Receive any last-minute instructions + +**Coordinator Contact:** [Provided separately via secure channel] + +--- + +## Generating Randomness + +High-quality randomness is **essential** for ceremony security. We use multiple sources: + +### Physical Entropy Sources + +**Method 1: Dice Rolls (Recommended)** + +You'll need at least **100 dice rolls** (d6 is fine): + +```bash +# Run the entropy collector +cargo run --release --bin entropy-collector + +# It will prompt you: +> Roll a d6 and enter the result (1-6): _ +``` + +Enter each die roll. The tool will guide you through collecting sufficient entropy. + +**Method 2: Coin Flips** + +Flip a coin **256 times** and record heads (H) or tails (T): + +```bash +# Example: +HHTHTTHHTHHHTTHT... (continue for 256 flips) +``` + +**Method 3: Keyboard Timing** + +The tool can collect entropy from keyboard timing: + +```bash +cargo run --release --bin entropy-collector --method keyboard + +# Type random text for ~2 minutes +# The tool measures timing between keypresses +``` + +**Method 4: Camera/Microphone (Advanced)** + +If you have a webcam or microphone: + +```bash +# Capture visual noise from camera +cargo run --release --bin entropy-collector --method camera + +# Or capture audio noise +cargo run --release --bin entropy-collector --method audio +``` + +### System Randomness + +The tool will also collect from: +- `/dev/urandom` (OS entropy pool) +- CPU timing variations +- Memory allocation patterns + +**Note:** Physical sources are preferred as they're harder to manipulate. + +--- + +## Making Your Contribution + +### Step 1: Download Input Parameters + +The coordinator will provide a secure download link: + +```bash +# Download parameters from previous round +curl -o input_params.bin https://ceremony.bitcell.org/download/round_N.bin + +# Verify hash matches coordinator's announcement +sha256sum input_params.bin +# Should match: +``` + +### Step 2: Run Contribution Tool + +```bash +# Navigate to ceremony tools +cd ceremony/tools + +# Run contribution (this takes 20-45 minutes) +cargo run --release --bin ceremony-contribute \ + --input ../../downloads/input_params.bin \ + --output my_contribution.bin \ + --name "Your Name or Pseudonym" +``` + +The tool will: +1. ✅ Load and verify input parameters +2. ✅ Collect entropy from you (dice/coins/keyboard) +3. ✅ Mix your randomness with the parameters +4. ✅ Compute updated parameters +5. ✅ Generate proof of contribution +6. ✅ Create output files + +**Expected Output:** +``` +[1/6] Loading input parameters... + - Input hash: abc123... + - Verified ✓ + +[2/6] Collecting entropy... + - Roll dice and enter results + > Roll 1: 4 + > Roll 2: 6 + ... (continue for 100 rolls) + - Entropy collected: 256 bits ✓ + +[3/6] Computing contribution... + - This may take 20-45 minutes + - Progress: ████████░░░░ 67% + +[4/6] Generating proof... + - Proof generated ✓ + +[5/6] Writing output... + - my_contribution.bin (2.3 GB) + - my_contribution_proof.json + - Output hash: def456... + +[6/6] Done! + - Next: Upload my_contribution.bin to coordinator + - Keep my_contribution_proof.json for records +``` + +### Step 3: Upload Your Contribution + +```bash +# The coordinator will provide upload instructions +# This might be via secure SFTP, AWS S3, or other method + +# Example (coordinator will provide exact command): +scp my_contribution.bin ceremony@upload.bitcell.org:/contributions/round_N/ +``` + +**IMPORTANT:** +- Keep `my_contribution_proof.json` - you'll need it for attestation +- Do NOT share `my_contribution.bin` with anyone except the coordinator +- The upload is large (2-5 GB), be patient + +--- + +## Verification + +### Step 1: Wait for Coordinator Verification + +The coordinator will: +1. Download your contribution +2. Verify it's correctly formed +3. Verify the proof of contribution +4. Publish verification results + +This typically takes 30-60 minutes. + +### Step 2: Check Public Announcement + +The coordinator will publish: +``` +Round N Contribution Accepted +Participant: [Your Name] +Input Hash: abc123... +Output Hash: def456... +Verified: ✓ +Timestamp: 2025-XX-XX HH:MM:SS UTC +``` + +Verify the output hash matches your local `my_contribution.bin`: +```bash +sha256sum my_contribution.bin +``` + +### Step 3: Verify Your Contribution + +Run the verification tool yourself: +```bash +cargo run --release --bin ceremony-verify \ + --input input_params.bin \ + --output my_contribution.bin \ + --proof my_contribution_proof.json + +# Should output: +# ✓ Contribution verified successfully +``` + +--- + +## Destroying Secrets + +**This is the most important step!** Your contribution is only secure if you properly destroy your secrets. + +### What to Destroy + +All files containing: +- ❌ Input parameters (`input_params.bin`) +- ❌ Output parameters (`my_contribution.bin`) +- ❌ Any temporary files created during contribution +- ❌ Any entropy sources you collected +- ❌ Your shell history that might contain sensitive info + +**Keep only:** +- ✅ `my_contribution_proof.json` (this is safe, no secrets) +- ✅ Your attestation document + +### Destruction Methods + +**Method 1: Secure Wipe (Linux/macOS)** + +```bash +# Wipe all ceremony files +shred -vfz -n 10 input_params.bin +shred -vfz -n 10 my_contribution.bin +shred -vfz -n 10 entropy_*.bin + +# Wipe the entire ceremony directory +find ~/bitcell-ceremony -type f -exec shred -vfz -n 10 {} \; + +# Clear shell history +history -c +rm ~/.bash_history +``` + +**Method 2: Full Disk Wipe (Recommended if using VM)** + +```bash +# If you used a dedicated VM, just delete it +# This ensures everything is destroyed + +# Before deletion, copy out your proof and attestation: +scp my_contribution_proof.json your_machine:~/ +scp attestation.txt your_machine:~/ + +# Then delete the VM through your hypervisor +``` + +**Method 3: Windows** + +```powershell +# Use SDelete +sdelete -p 10 input_params.bin +sdelete -p 10 my_contribution.bin + +# Or use Cipher +cipher /w:C:\bitcell-ceremony +``` + +### Verification + +After wiping, try to recover files: +```bash +# Should find nothing +ls -la input_params.bin # No such file +ls -la my_contribution.bin # No such file +``` + +If using a VM, verify it's deleted from your hypervisor. + +--- + +## Attestation + +### Why Attest? + +An attestation is your public statement that: +1. You generated genuine randomness +2. You followed the ceremony process correctly +3. **You destroyed your toxic waste** + +This creates public accountability and transparency. + +### Creating Your Attestation + +```bash +# Use the attestation template +cp ceremony/attestation_template.txt my_attestation.txt + +# Edit with your details +nano my_attestation.txt +``` + +**Attestation Template:** + +``` +BitCell Trusted Setup Ceremony Attestation + +Ceremony: [BattleCircuit | StateCircuit] +Round: N +Date: YYYY-MM-DD +Participant: [Your Name or Pseudonym] + +I hereby attest that: + +1. I generated the contribution independently using genuine randomness. + Entropy sources used: [e.g., "100 dice rolls with fair d6 dice"] + +2. I verified the input parameters matched the published hash. + Input hash: abc123... + +3. I ran the contribution tool and verified the output. + Output hash: def456... + +4. I securely destroyed all files containing toxic waste from my contribution: + - Input parameters: DESTROYED via [method] + - Output parameters: DESTROYED via [method] + - Temporary files: DESTROYED via [method] + - [If VM] Virtual machine: DELETED from hypervisor + - [If bare metal] Files wiped: [date/time] + +5. To the best of my knowledge, no copies of the toxic waste remain. + +6. I acted in good faith to support the security of BitCell. + +Signature: [PGP signature or plain text if no PGP key] +Contact: [Email or other contact, optional] +Date: YYYY-MM-DD +``` + +### Signing Your Attestation + +**With PGP (Recommended):** + +```bash +# Sign with your PGP key +gpg --clearsign my_attestation.txt + +# This creates my_attestation.txt.asc +# The signature proves you wrote it +``` + +**Without PGP:** + +If you don't have a PGP key, you can still attest: + +```bash +# Add identifying information +# - Your GitHub username +# - Your Twitter handle +# - Your LinkedIn profile +# - Or other verifiable identity + +# This allows others to verify you're a distinct person +``` + +### Submitting Your Attestation + +Send to the coordinator: + +```bash +# Email +email my_attestation.txt.asc to ceremony@bitcell.org + +# Or create a GitHub Gist (public) +# And share the link +``` + +The coordinator will publish all attestations in `ceremony/attestations/`. + +--- + +## Troubleshooting + +### Build Errors + +**Error:** `cargo: command not found` +```bash +# Re-run Rust installer +curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh +``` + +**Error:** `linking with cc failed` +```bash +# Install build tools +# Ubuntu/Debian: +sudo apt-get install build-essential +# macOS: +xcode-select --install +``` + +### Memory Errors + +**Error:** `Out of memory` or `SIGKILL` + +- Increase VM RAM to 16GB or more +- Close other applications +- Enable swap space: + ```bash + sudo fallocate -l 8G /swapfile + sudo chmod 600 /swapfile + sudo mkswap /swapfile + sudo swapon /swapfile + ``` + +### Download Issues + +**Error:** `Connection timeout` or slow download + +- Use a wired connection if possible +- Download during off-peak hours +- Contact coordinator for alternative mirror + +### Verification Failures + +**Error:** `Contribution verification failed` + +- Double-check input parameters hash +- Ensure you used the latest ceremony tools +- Contact coordinator - they may need to investigate + +### Cleanup Questions + +**Q:** Can I keep a copy of `my_contribution.bin` for records? + +**A:** NO! This contains toxic waste. Keep only `my_contribution_proof.json`. + +**Q:** What if I accidentally kept a copy? + +**A:** Destroy it immediately using the secure wipe methods above. Then inform the coordinator. + +**Q:** Can I re-use my machine after the ceremony? + +**A:** Yes, if you've properly wiped all files. VM deletion is safer to be certain. + +--- + +## Support + +### Coordinator Contact + +**Primary:** ceremony@bitcell.org +**Backup:** [Provided during ceremony] +**Response Time:** Usually within 4 hours + +### Community Support + +**Discord:** #ceremony-support channel +**Telegram:** @BitCellCeremony +**Forum:** https://forum.bitcell.org/c/ceremony + +### FAQ + +**Q:** Do I need to be a developer? + +**A:** No! Anyone can participate. The tools are designed to be user-friendly. + +**Q:** Can I contribute more than once? + +**A:** No - we need independent participants. One contribution per person/entity. + +**Q:** What if I make a mistake? + +**A:** That's okay! As long as you destroy your secrets afterward, your contribution still helps. Imperfect randomness is fine. + +**Q:** How long until my contribution is used? + +**A:** After all participants contribute, we'll generate the final keys. This is typically 2-3 weeks after the ceremony starts. + +**Q:** Is my identity public? + +**A:** Your name/pseudonym and attestation are public. Your contact info is private (known only to coordinator). + +--- + +## Thank You! + +Your participation makes BitCell more secure. Every contribution adds another layer of security through decentralized trust. + +After the ceremony, you'll be publicly acknowledged in: +- Ceremony transcript +- BitCell website +- Technical documentation +- (Optional) NFT commemorating participation + +**We appreciate your time and commitment to building a secure blockchain ecosystem.** + +--- + +**Questions?** Contact the coordinator or ask in community channels. + +**Last Updated:** December 2025 +**Version:** 1.0 +**Ceremony Status:** Planning Phase diff --git a/ceremony/tools/README.md b/ceremony/tools/README.md new file mode 100644 index 0000000..c66cf1c --- /dev/null +++ b/ceremony/tools/README.md @@ -0,0 +1,307 @@ +# BitCell Ceremony Tools + +This directory contains tools for conducting and verifying the BitCell trusted setup ceremony. + +## Overview + +The ceremony tools enable a multi-party trusted setup for Groth16 zkSNARKs. Each tool plays a specific role in the ceremony process. + +## Tools + +### For Participants + +- **`ceremony-contribute`** - Contribute randomness to the ceremony + - Collects entropy from participant + - Mixes randomness with current parameters + - Generates proof of contribution + - **Status:** Planned for implementation + +### For Coordinator + +- **`ceremony-coordinator`** - Manage ceremony flow + - Initialize ceremony with random beacon + - Sequence participant contributions + - Generate final keys + - **Status:** Planned for implementation + +### For Everyone + +- **`ceremony-verify`** - Verify contributions and keys + - Verify individual contributions + - Verify full ceremony transcript + - Check key derivation + - **Status:** Planned for implementation + +- **`ceremony-audit`** - Generate audit reports + - Analyze ceremony transcript + - Generate statistical reports + - Verify participant independence + - **Status:** Planned for implementation + +## Installation + +These tools are built as part of the BitCell repository: + +```bash +# Clone repository +git clone https://github.com/Steake/BitCell.git +cd BitCell + +# Build ceremony tools +cd ceremony/tools +cargo build --release + +# Tools will be in target/release/ +``` + +## Usage + +### Participant Contribution + +Detailed instructions in [`../participant_instructions.md`](../participant_instructions.md). + +Quick start: + +```bash +# Download current parameters (provided by coordinator) +curl -o input_params.bin + +# Run contribution tool +cargo run --release --bin ceremony-contribute \ + --input input_params.bin \ + --output my_contribution.bin \ + --name "Your Name" + +# Upload contribution (instructions from coordinator) +``` + +### Coordinator Operations + +Detailed checklist in [`../coordinator_checklist.md`](../coordinator_checklist.md). + +Quick reference: + +```bash +# Initialize ceremony +cargo run --release --bin ceremony-coordinator init \ + --circuit battle \ + --beacon \ + --output params_round_0.bin + +# Verify a contribution +cargo run --release --bin ceremony-verify \ + --input params_round_N.bin \ + --output params_round_N+1.bin \ + --proof contribution_proof.json + +# Generate final keys +cargo run --release --bin ceremony-coordinator finalize \ + --circuit battle \ + --input params_round_final.bin \ + --output-dir ../../keys/battle/ +``` + +### Verification + +Anyone can verify the ceremony: + +```bash +# Verify a single contribution +cargo run --release --bin ceremony-verify \ + --input params_round_N.bin \ + --output params_round_N+1.bin \ + --proof contribution_proof.json + +# Verify full ceremony transcript +cargo run --release --bin ceremony-verify \ + --transcript ../transcripts/battle_transcript.json \ + --keys ../../keys/battle/ + +# Generate audit report +cargo run --release --bin ceremony-audit \ + --transcript ../transcripts/battle_transcript.json \ + --output audit_report.md +``` + +## Tool Implementation Status + +| Tool | Status | Notes | +|------|--------|-------| +| `ceremony-contribute` | 🟡 Planned | Core functionality defined | +| `ceremony-coordinator` | 🟡 Planned | Protocol specified | +| `ceremony-verify` | 🟡 Planned | Verification logic outlined | +| `ceremony-audit` | 🟡 Planned | Reporting format defined | + +**Note:** The ceremony is planned for Q1 2026. Tool implementation will be completed before the ceremony begins. + +## Architecture + +### Contribution Flow + +``` +┌─────────────────┐ +│ Download │ +│ params_N.bin │ +└────────┬────────┘ + │ + ▼ +┌─────────────────┐ +│ Collect │ +│ Entropy │ +│ (dice/coins) │ +└────────┬────────┘ + │ + ▼ +┌─────────────────┐ +│ Mix Randomness │ +│ with params │ +│ (20-45 min) │ +└────────┬────────┘ + │ + ▼ +┌─────────────────┐ +│ Generate │ +│ params_N+1.bin │ +│ + proof │ +└────────┬────────┘ + │ + ▼ +┌─────────────────┐ +│ Upload to │ +│ Coordinator │ +└─────────────────┘ +``` + +### Verification Flow + +``` +┌─────────────────┐ +│ Load │ +│ Transcript │ +└────────┬────────┘ + │ + ▼ +┌─────────────────┐ +│ Verify Random │ +│ Beacon │ +└────────┬────────┘ + │ + ▼ +┌─────────────────┐ +│ For Each │ +│ Contribution: │ +│ - Verify proof │ +│ - Check hashes │ +└────────┬────────┘ + │ + ▼ +┌─────────────────┐ +│ Verify Final │ +│ Keys Match │ +└────────┬────────┘ + │ + ▼ +┌─────────────────┐ +│ Generate │ +│ Report │ +└─────────────────┘ +``` + +## Security Considerations + +### Entropy Collection + +The contribution tool collects entropy from multiple sources: +1. Physical sources (dice, coins) - preferred +2. Keyboard timing +3. Camera/microphone noise +4. System /dev/urandom +5. CPU timing variations + +**Recommendation:** Use physical sources for highest security. + +### Toxic Waste Destruction + +After contributing: +1. Securely wipe all parameter files +2. Clear shell history +3. If using VM: delete the VM +4. Attest to destruction + +### Coordinator Security + +The coordinator should: +1. Use secure infrastructure +2. Verify all contributions +3. Publish everything publicly +4. Maintain audit trail +5. Respond to community questions + +## File Formats + +### Parameters File + +Binary format containing: +- Circuit-specific setup parameters +- Powers of tau +- Encrypted contributions + +Size: 2-5 GB per file + +### Contribution Proof + +JSON format: +```json +{ + "round": 42, + "participant": "Alice", + "input_hash": "sha256:...", + "output_hash": "sha256:...", + "timestamp": "2025-XX-XX HH:MM:SS UTC", + "proof_data": { + "challenge": "...", + "response": "..." + } +} +``` + +### Transcript + +JSON format containing: +- Random beacon +- All contributions +- All proofs +- Final key hashes + +See [`../transcripts/README.md`](../transcripts/README.md) for schema. + +## Testing + +Before the ceremony, we'll conduct test runs: + +```bash +# Run local test ceremony with 3 participants +./scripts/test_ceremony.sh + +# Verify test ceremony +cargo test --package ceremony-tools +``` + +## Support + +**Questions?** +- Email: ceremony@bitcell.org +- Discord: #ceremony-support +- Documentation: [`../../docs/CEREMONY.md`](../../docs/CEREMONY.md) + +## References + +- **Groth16:** "On the Size of Pairing-based Non-interactive Arguments" (Jens Groth, 2016) +- **Powers of Tau:** Zcash ceremony - https://z.cash/technology/paramgen/ +- **MPC Security:** "Scalable Multi-party Computation for zk-SNARK Parameters" (Bowe et al., 2017) + +--- + +**Last Updated:** December 2025 +**Status:** Planning Phase +**Next Steps:** Implement tools before Q1 2026 ceremony diff --git a/ceremony/transcripts/README.md b/ceremony/transcripts/README.md new file mode 100644 index 0000000..e440390 --- /dev/null +++ b/ceremony/transcripts/README.md @@ -0,0 +1,178 @@ +# Ceremony Transcripts + +This directory contains complete transcripts of BitCell trusted setup ceremonies. + +## Purpose + +The ceremony transcript provides a complete, verifiable record of: +- The random beacon used to initialize the ceremony +- Every participant contribution +- All verification proofs +- Final key hashes +- Timestamps and participant information + +This enables anyone to independently verify the ceremony was conducted correctly. + +## Transcript Format + +Each ceremony produces a JSON transcript: + +```json +{ + "ceremony_id": "bitcell-battle-circuit-2025", + "circuit": "BattleCircuit", + "circuit_constraints": 6700000, + "start_time": "2025-XX-XX HH:MM:SS UTC", + "end_time": "2025-XX-XX HH:MM:SS UTC", + "duration_days": 21, + + "random_beacon": { + "source": "Bitcoin", + "block_number": 850000, + "block_hash": "000000000000000000012345...", + "timestamp": "2025-XX-XX HH:MM:SS UTC" + }, + + "contributions": [ + { + "round": 1, + "participant": { + "name": "Alice", + "contact": "alice@example.com", + "pgp_fingerprint": "ABCD 1234 5678...", + "location": "United States", + "affiliation": "Independent Developer" + }, + "timestamp": "2025-XX-XX HH:MM:SS UTC", + "input_hash": "sha256:abc123...", + "output_hash": "sha256:def456...", + "contribution_proof": { + "challenge": "...", + "response": "..." + }, + "attestation_file": "attestations/battle_round_01_alice.txt", + "verified": true + }, + { + "round": 2, + "participant": { + "name": "Bob", + "contact": "bob@university.edu", + "pgp_fingerprint": "EFGH 5678 9012...", + "location": "Germany", + "affiliation": "Academic Researcher" + }, + "timestamp": "2025-XX-XX HH:MM:SS UTC", + "input_hash": "sha256:def456...", + "output_hash": "sha256:ghi789...", + "contribution_proof": { + "challenge": "...", + "response": "..." + }, + "attestation_file": "attestations/battle_round_02_bob.txt", + "verified": true + } + // ... more contributions + ], + + "statistics": { + "total_participants": 25, + "total_rounds": 25, + "average_contribution_time_hours": 1.5, + "countries_represented": 8, + "independent_participants": 25 + }, + + "final_keys": { + "proving_key": { + "file": "keys/battle/proving_key.bin", + "sha256": "abc123...", + "size_bytes": 2147483648 + }, + "verification_key": { + "file": "keys/battle/verification_key.bin", + "sha256": "def456...", + "size_bytes": 1024 + } + }, + + "verification": { + "all_contributions_verified": true, + "key_derivation_verified": true, + "independent_auditors": [ + { + "name": "Audit Firm XYZ", + "date": "2025-XX-XX", + "report": "audits/xyz_report.pdf" + } + ] + } +} +``` + +## Files + +After ceremonies complete, this directory will contain: + +- `battle_transcript.json` - Full transcript for BattleCircuit ceremony +- `state_transcript.json` - Full transcript for StateCircuit ceremony +- `README.md` - This file + +## Verification + +To verify a ceremony using the transcript: + +```bash +# Using ceremony verification tool +cd ceremony/tools +cargo run --release --bin ceremony-verify \ + --transcript ../transcripts/battle_transcript.json \ + --keys ../../keys/battle/ + +# Manual verification +# 1. Verify random beacon (check Bitcoin blockchain) +# 2. Verify each contribution proof +# 3. Verify final keys match the chain of contributions +# 4. Cross-reference with attestations +``` + +### Verification Checklist + +- [ ] Random beacon is valid and unpredictable +- [ ] Random beacon was announced before ceremony started +- [ ] Each contribution has valid proof +- [ ] Input/output hashes form a chain +- [ ] All participants have attestations +- [ ] Participants are independent (different people/organizations) +- [ ] Final keys hash matches transcript +- [ ] Keys can generate and verify proofs + +## Distribution + +Transcripts are distributed via: +- GitHub repository (primary) +- IPFS (content-addressed backup) +- BitTorrent (decentralized distribution) +- Official website + +## Status + +**Current Status:** Awaiting Ceremony (Q1 2026) + +Transcripts will be published immediately after ceremony completion. + +Expected file sizes: +- `battle_transcript.json` - ~500 KB (for 25 participants) +- `state_transcript.json` - ~500 KB (for 25 participants) + +## Support + +**Questions about transcripts?** +- Email: ceremony@bitcell.org +- Discord: #ceremony-verification +- Documentation: [`../../docs/CEREMONY.md`](../../docs/CEREMONY.md) + +--- + +**Last Updated:** December 2025 +**Ceremony Status:** Planning Phase diff --git a/crates/bitcell-zkp/src/battle_circuit.rs b/crates/bitcell-zkp/src/battle_circuit.rs index d8cac57..a6240cf 100644 --- a/crates/bitcell-zkp/src/battle_circuit.rs +++ b/crates/bitcell-zkp/src/battle_circuit.rs @@ -96,6 +96,10 @@ use ark_std::rand::thread_rng; impl BattleCircuit { /// Setup the circuit and generate proving/verifying keys /// + /// **WARNING:** This method generates keys using insecure randomness and should + /// ONLY be used for testing. Production systems MUST use keys generated from a + /// proper multi-party trusted setup ceremony via `load_ceremony_keys()`. + /// /// Returns an error if the circuit setup fails (e.g., due to constraint system issues). pub fn setup() -> crate::Result<(ProvingKey, VerifyingKey)> { let rng = &mut thread_rng(); @@ -112,6 +116,80 @@ impl BattleCircuit { .map_err(|e| crate::Error::ProofGeneration(format!("Circuit setup failed: {}", e))) } + /// Load proving key from the trusted setup ceremony + /// + /// This loads the production proving key that was generated through a + /// multi-party computation ceremony. The key is stored in `keys/battle/proving_key.bin`. + /// + /// # Expected Directory Structure + /// ```text + /// BitCell/ + /// ├── crates/ + /// │ └── bitcell-zkp/ <- CARGO_MANIFEST_DIR + /// └── keys/ + /// └── battle/ + /// └── proving_key.bin + /// ``` + /// + /// # Returns + /// * `Ok(ProvingKey)` if the key is found and successfully loaded + /// * `Err` if the key file doesn't exist or is corrupted + pub fn load_proving_key() -> crate::Result> { + let manifest_dir = std::path::Path::new(env!("CARGO_MANIFEST_DIR")); + let repo_root = manifest_dir + .parent() + .and_then(|p| p.parent()) + .ok_or_else(|| crate::Error::KeyManagement( + "Failed to resolve repository root from crates/bitcell-zkp".to_string() + ))?; + let key_path = repo_root.join("keys/battle/proving_key.bin"); + crate::key_management::load_proving_key(key_path) + } + + /// Load verification key from the trusted setup ceremony + /// + /// This loads the production verification key that was generated through a + /// multi-party computation ceremony. The key is stored in `keys/battle/verification_key.bin`. + /// + /// # Expected Directory Structure + /// ```text + /// BitCell/ + /// ├── crates/ + /// │ └── bitcell-zkp/ <- CARGO_MANIFEST_DIR + /// └── keys/ + /// └── battle/ + /// └── verification_key.bin + /// ``` + /// + /// # Returns + /// * `Ok(VerifyingKey)` if the key is found and successfully loaded + /// * `Err` if the key file doesn't exist or is corrupted + pub fn load_verification_key() -> crate::Result> { + let manifest_dir = std::path::Path::new(env!("CARGO_MANIFEST_DIR")); + let repo_root = manifest_dir + .parent() + .and_then(|p| p.parent()) + .ok_or_else(|| crate::Error::KeyManagement( + "Failed to resolve repository root from crates/bitcell-zkp".to_string() + ))?; + let key_path = repo_root.join("keys/battle/verification_key.bin"); + crate::key_management::load_verification_key(key_path) + } + + /// Load both proving and verification keys from the trusted setup ceremony + /// + /// Convenience method that loads both keys at once. Equivalent to calling + /// `load_proving_key()` and `load_verification_key()` separately. + /// + /// # Returns + /// * `Ok((ProvingKey, VerifyingKey))` if both keys are successfully loaded + /// * `Err` if either key file doesn't exist or is corrupted + pub fn load_ceremony_keys() -> crate::Result<(ProvingKey, VerifyingKey)> { + let pk = Self::load_proving_key()?; + let vk = Self::load_verification_key()?; + Ok((pk, vk)) + } + /// Generate a proof for this circuit instance pub fn prove( &self, diff --git a/crates/bitcell-zkp/src/key_management.rs b/crates/bitcell-zkp/src/key_management.rs new file mode 100644 index 0000000..b405680 --- /dev/null +++ b/crates/bitcell-zkp/src/key_management.rs @@ -0,0 +1,215 @@ +//! Key management for trusted setup ceremony +//! +//! This module provides functionality for: +//! - Serializing and deserializing Groth16 proving and verification keys +//! - Loading ceremony-generated keys from disk +//! - Verifying key integrity +//! +//! # Security Note +//! +//! The keys loaded by this module should ONLY be used after a proper +//! multi-party trusted setup ceremony has been conducted. Using keys +//! generated by `setup()` in production would compromise security. + +use ark_groth16::{ProvingKey, VerifyingKey}; +use ark_serialize::{CanonicalDeserialize, CanonicalSerialize}; +use std::fs::File; +use std::io::{BufReader, BufWriter, Write}; +use std::path::Path; + +/// Serialize a proving key to a file +/// +/// # Arguments +/// * `pk` - The proving key to serialize +/// * `path` - Path where the key should be saved +/// +/// # Returns +/// * `Ok(())` if serialization succeeds +/// * `Err` if file I/O or serialization fails +pub fn save_proving_key( + pk: &ProvingKey, + path: impl AsRef, +) -> crate::Result<()> { + let file = File::create(path.as_ref()) + .map_err(|e| crate::Error::KeyManagement(format!("Failed to create file: {}", e)))?; + let mut writer = BufWriter::new(file); + + pk.serialize_compressed(&mut writer) + .map_err(|e| crate::Error::KeyManagement(format!("Failed to serialize proving key: {}", e)))?; + + writer.flush() + .map_err(|e| crate::Error::KeyManagement(format!("Failed to flush writer: {}", e)))?; + + Ok(()) +} + +/// Deserialize a proving key from a file +/// +/// # Arguments +/// * `path` - Path to the serialized proving key +/// +/// # Returns +/// * `Ok(ProvingKey)` if deserialization succeeds +/// * `Err` if file I/O or deserialization fails +pub fn load_proving_key( + path: impl AsRef, +) -> crate::Result> { + let file = File::open(path.as_ref()) + .map_err(|e| crate::Error::KeyManagement(format!("Failed to open file: {}", e)))?; + let mut reader = BufReader::new(file); + + ProvingKey::::deserialize_compressed(&mut reader) + .map_err(|e| crate::Error::KeyManagement(format!("Failed to deserialize proving key: {}", e))) +} + +/// Serialize a verification key to a file +/// +/// # Arguments +/// * `vk` - The verification key to serialize +/// * `path` - Path where the key should be saved +/// +/// # Returns +/// * `Ok(())` if serialization succeeds +/// * `Err` if file I/O or serialization fails +pub fn save_verification_key( + vk: &VerifyingKey, + path: impl AsRef, +) -> crate::Result<()> { + let file = File::create(path.as_ref()) + .map_err(|e| crate::Error::KeyManagement(format!("Failed to create file: {}", e)))?; + let mut writer = BufWriter::new(file); + + vk.serialize_compressed(&mut writer) + .map_err(|e| crate::Error::KeyManagement(format!("Failed to serialize verification key: {}", e)))?; + + writer.flush() + .map_err(|e| crate::Error::KeyManagement(format!("Failed to flush writer: {}", e)))?; + + Ok(()) +} + +/// Deserialize a verification key from a file +/// +/// # Arguments +/// * `path` - Path to the serialized verification key +/// +/// # Returns +/// * `Ok(VerifyingKey)` if deserialization succeeds +/// * `Err` if file I/O or deserialization fails +pub fn load_verification_key( + path: impl AsRef, +) -> crate::Result> { + let file = File::open(path.as_ref()) + .map_err(|e| crate::Error::KeyManagement(format!("Failed to open file: {}", e)))?; + let mut reader = BufReader::new(file); + + VerifyingKey::::deserialize_compressed(&mut reader) + .map_err(|e| crate::Error::KeyManagement(format!("Failed to deserialize verification key: {}", e))) +} + +/// Compute a SHA-256 hash of a proving key for verification +/// +/// This can be used to verify key integrity and ensure all participants +/// are using the same keys from the ceremony. +pub fn hash_proving_key(pk: &ProvingKey) -> crate::Result { + use sha2::{Sha256, Digest}; + + let mut hasher = Sha256::new(); + let mut bytes = Vec::new(); + pk.serialize_compressed(&mut bytes) + .map_err(|e| crate::Error::KeyManagement(format!("Failed to serialize for hashing: {}", e)))?; + + hasher.update(&bytes); + let result = hasher.finalize(); + Ok(format!("{:x}", result)) +} + +/// Compute a SHA-256 hash of a verification key for verification +/// +/// This can be used to verify key integrity and ensure all participants +/// are using the same keys from the ceremony. +pub fn hash_verification_key(vk: &VerifyingKey) -> crate::Result { + use sha2::{Sha256, Digest}; + + let mut hasher = Sha256::new(); + let mut bytes = Vec::new(); + vk.serialize_compressed(&mut bytes) + .map_err(|e| crate::Error::KeyManagement(format!("Failed to serialize for hashing: {}", e)))?; + + hasher.update(&bytes); + let result = hasher.finalize(); + Ok(format!("{:x}", result)) +} + +#[cfg(test)] +mod tests { + use super::*; + use crate::BattleCircuit; + use std::env; + + #[test] + fn test_save_and_load_proving_key() { + // Generate test keys + let (pk, _vk) = BattleCircuit::setup().expect("Setup should succeed"); + + // Create temp file + let temp_dir = env::temp_dir(); + let pk_path = temp_dir.join("test_proving_key.bin"); + + // Save + save_proving_key(&pk, &pk_path).expect("Save should succeed"); + + // Load + let loaded_pk = load_proving_key(&pk_path).expect("Load should succeed"); + + // Verify they produce the same hash + let original_hash = hash_proving_key(&pk).expect("Hash should succeed"); + let loaded_hash = hash_proving_key(&loaded_pk).expect("Hash should succeed"); + assert_eq!(original_hash, loaded_hash); + + // Cleanup + std::fs::remove_file(pk_path).ok(); + } + + #[test] + fn test_save_and_load_verification_key() { + // Generate test keys + let (_pk, vk) = BattleCircuit::setup().expect("Setup should succeed"); + + // Create temp file + let temp_dir = env::temp_dir(); + let vk_path = temp_dir.join("test_verification_key.bin"); + + // Save + save_verification_key(&vk, &vk_path).expect("Save should succeed"); + + // Load + let loaded_vk = load_verification_key(&vk_path).expect("Load should succeed"); + + // Verify they produce the same hash + let original_hash = hash_verification_key(&vk).expect("Hash should succeed"); + let loaded_hash = hash_verification_key(&loaded_vk).expect("Hash should succeed"); + assert_eq!(original_hash, loaded_hash); + + // Cleanup + std::fs::remove_file(vk_path).ok(); + } + + #[test] + fn test_key_hashing() { + let (pk, vk) = BattleCircuit::setup().expect("Setup should succeed"); + + // Hash multiple times and ensure consistency + let hash1 = hash_proving_key(&pk).expect("Hash should succeed"); + let hash2 = hash_proving_key(&pk).expect("Hash should succeed"); + assert_eq!(hash1, hash2); + + let vk_hash1 = hash_verification_key(&vk).expect("Hash should succeed"); + let vk_hash2 = hash_verification_key(&vk).expect("Hash should succeed"); + assert_eq!(vk_hash1, vk_hash2); + + // Ensure hashes are valid hex strings + assert_eq!(hash1.len(), 64); // SHA-256 produces 32 bytes = 64 hex chars + assert_eq!(vk_hash1.len(), 64); + } +} diff --git a/crates/bitcell-zkp/src/lib.rs b/crates/bitcell-zkp/src/lib.rs index 1ea538a..5c03a99 100644 --- a/crates/bitcell-zkp/src/lib.rs +++ b/crates/bitcell-zkp/src/lib.rs @@ -19,6 +19,8 @@ pub mod state_constraints; pub mod merkle_gadget; // Production-ready Poseidon-based Merkle verification pub mod poseidon_merkle; +// Key management for trusted setup ceremony +pub mod key_management; pub use battle_circuit::BattleCircuit; pub use state_circuit::StateCircuit; @@ -45,6 +47,9 @@ pub enum Error { #[error("Setup error: {0}")] Setup(String), + + #[error("Key management error: {0}")] + KeyManagement(String), } use ark_bn254::Bn254; diff --git a/crates/bitcell-zkp/src/state_circuit.rs b/crates/bitcell-zkp/src/state_circuit.rs index 7dfe6db..2d1fe02 100644 --- a/crates/bitcell-zkp/src/state_circuit.rs +++ b/crates/bitcell-zkp/src/state_circuit.rs @@ -45,6 +45,10 @@ impl StateCircuit { /// Setup the circuit and generate proving/verifying keys /// + /// **WARNING:** This method generates keys using insecure randomness and should + /// ONLY be used for testing. Production systems MUST use keys generated from a + /// proper multi-party trusted setup ceremony via `load_ceremony_keys()`. + /// /// Returns an error if the circuit setup fails (e.g., due to constraint system issues). pub fn setup() -> crate::Result<(ProvingKey, VerifyingKey)> { let rng = &mut thread_rng(); @@ -60,6 +64,80 @@ impl StateCircuit { .map_err(|e| crate::Error::ProofGeneration(format!("Circuit setup failed: {}", e))) } + /// Load proving key from the trusted setup ceremony + /// + /// This loads the production proving key that was generated through a + /// multi-party computation ceremony. The key is stored in `keys/state/proving_key.bin`. + /// + /// # Expected Directory Structure + /// ```text + /// BitCell/ + /// ├── crates/ + /// │ └── bitcell-zkp/ <- CARGO_MANIFEST_DIR + /// └── keys/ + /// └── state/ + /// └── proving_key.bin + /// ``` + /// + /// # Returns + /// * `Ok(ProvingKey)` if the key is found and successfully loaded + /// * `Err` if the key file doesn't exist or is corrupted + pub fn load_proving_key() -> crate::Result> { + let manifest_dir = std::path::Path::new(env!("CARGO_MANIFEST_DIR")); + let repo_root = manifest_dir + .parent() + .and_then(|p| p.parent()) + .ok_or_else(|| crate::Error::KeyManagement( + "Failed to resolve repository root from crates/bitcell-zkp".to_string() + ))?; + let key_path = repo_root.join("keys/state/proving_key.bin"); + crate::key_management::load_proving_key(key_path) + } + + /// Load verification key from the trusted setup ceremony + /// + /// This loads the production verification key that was generated through a + /// multi-party computation ceremony. The key is stored in `keys/state/verification_key.bin`. + /// + /// # Expected Directory Structure + /// ```text + /// BitCell/ + /// ├── crates/ + /// │ └── bitcell-zkp/ <- CARGO_MANIFEST_DIR + /// └── keys/ + /// └── state/ + /// └── verification_key.bin + /// ``` + /// + /// # Returns + /// * `Ok(VerifyingKey)` if the key is found and successfully loaded + /// * `Err` if the key file doesn't exist or is corrupted + pub fn load_verification_key() -> crate::Result> { + let manifest_dir = std::path::Path::new(env!("CARGO_MANIFEST_DIR")); + let repo_root = manifest_dir + .parent() + .and_then(|p| p.parent()) + .ok_or_else(|| crate::Error::KeyManagement( + "Failed to resolve repository root from crates/bitcell-zkp".to_string() + ))?; + let key_path = repo_root.join("keys/state/verification_key.bin"); + crate::key_management::load_verification_key(key_path) + } + + /// Load both proving and verification keys from the trusted setup ceremony + /// + /// Convenience method that loads both keys at once. Equivalent to calling + /// `load_proving_key()` and `load_verification_key()` separately. + /// + /// # Returns + /// * `Ok((ProvingKey, VerifyingKey))` if both keys are successfully loaded + /// * `Err` if either key file doesn't exist or is corrupted + pub fn load_ceremony_keys() -> crate::Result<(ProvingKey, VerifyingKey)> { + let pk = Self::load_proving_key()?; + let vk = Self::load_verification_key()?; + Ok((pk, vk)) + } + /// Generate a proof for this circuit instance pub fn prove( &self, diff --git a/docs/CEREMONY.md b/docs/CEREMONY.md new file mode 100644 index 0000000..67170f2 --- /dev/null +++ b/docs/CEREMONY.md @@ -0,0 +1,510 @@ +# BitCell Trusted Setup Ceremony + +**Version:** 1.0 +**Date:** December 2025 +**Status:** Planning Phase + +--- + +## Table of Contents + +1. [Overview](#overview) +2. [Why a Trusted Setup?](#why-a-trusted-setup) +3. [Security Guarantees](#security-guarantees) +4. [Ceremony Timeline](#ceremony-timeline) +5. [Participation Requirements](#participation-requirements) +6. [Ceremony Process](#ceremony-process) +7. [Key Verification](#key-verification) +8. [Audit Trail](#audit-trail) +9. [Post-Ceremony](#post-ceremony) + +--- + +## Overview + +The BitCell trusted setup ceremony is a multi-party computation (MPC) protocol used to generate the proving and verification keys for our Groth16 zero-knowledge proof circuits. This ceremony is **critical** for the security of the BitCell blockchain. + +### Circuits Requiring Setup + +We conduct separate ceremonies for two circuits: + +1. **BattleCircuit** - Proves that Cellular Automaton battles executed correctly +2. **StateCircuit** - Proves that state transitions are valid + +Each circuit requires its own independent ceremony with separate proving and verification keys. + +--- + +## Why a Trusted Setup? + +Groth16 is a zkSNARK scheme that requires a **trusted setup** to generate the cryptographic parameters (proving and verification keys). During this setup: + +1. A "toxic waste" secret (τ) is generated +2. This secret is used to create the proving and verification keys +3. The secret **must be destroyed** to ensure security + +### The Trust Problem + +If the toxic waste is not properly destroyed: +- An adversary with knowledge of τ can create **fake proofs** for invalid statements +- They could prove false battle outcomes or invalid state transitions +- This would completely compromise the blockchain's security + +### The Multi-Party Solution + +A **multi-party trusted setup** solves this problem: +- Multiple independent parties each contribute randomness +- Each party's contribution updates the toxic waste +- As long as **at least one participant** is honest and destroys their secret, the final keys are secure +- No single party knows the final toxic waste + +This is the same approach used by Zcash (Powers of Tau) and other production zkSNARK systems. + +--- + +## Security Guarantees + +### What the Ceremony Guarantees + +✅ **If at least one participant is honest:** +- The toxic waste is destroyed +- No one can create fake proofs +- The keys are cryptographically secure + +✅ **Verifiability:** +- Each contribution can be verified +- The final keys can be verified against the transcript +- Anyone can verify the ceremony was conducted correctly + +✅ **Non-interactivity:** +- Participants don't need to be online simultaneously +- Contributions can be made asynchronously +- The coordinator sequences the contributions + +### What Could Go Wrong? + +❌ **If ALL participants collude or are compromised:** +- The toxic waste could be reconstructed +- Fake proofs could be created +- **This is why we need diverse, independent participants** + +❌ **If the coordinator is malicious:** +- They could reject valid contributions +- They could accept invalid contributions +- **This is why we publish full transcripts and verification tools** + +--- + +## Ceremony Timeline + +### Phase 1: Planning (2 weeks) +- [x] Design ceremony protocol +- [x] Develop ceremony tools +- [x] Write participant documentation +- [ ] Recruit participants (target: 20+ independent parties) +- [ ] Schedule contribution windows + +### Phase 2: Participant Preparation (1 week) +- [ ] Distribute participant instructions +- [ ] Test participant environments +- [ ] Verify identity/independence of participants +- [ ] Establish secure communication channels + +### Phase 3: BattleCircuit Ceremony (2-3 weeks) +- [ ] Initialize ceremony with random beacon +- [ ] Accept participant contributions (1-2 days per participant) +- [ ] Verify each contribution +- [ ] Publish transcript +- [ ] Generate final keys + +### Phase 4: StateCircuit Ceremony (2-3 weeks) +- [ ] Initialize ceremony with random beacon +- [ ] Accept participant contributions +- [ ] Verify each contribution +- [ ] Publish transcript +- [ ] Generate final keys + +### Phase 5: Verification & Publication (1 week) +- [ ] Independent verification of ceremonies +- [ ] Publish keys to repository +- [ ] Publish ceremony transcripts +- [ ] Publish verification attestations +- [ ] Announce completion + +**Total Estimated Duration:** 8-10 weeks + +--- + +## Participation Requirements + +### Who Can Participate? + +We seek participants who are: +- Independent of each other +- Geographically distributed +- From diverse backgrounds (developers, academics, enterprises) +- Committed to blockchain security + +### Technical Requirements + +Participants need: +- **Hardware:** Modern computer with 16GB+ RAM +- **OS:** Linux, macOS, or Windows +- **Software:** Rust toolchain (provided in instructions) +- **Time:** 2-4 hours for contribution + setup +- **Storage:** ~20GB free disk space + +### Security Recommendations + +Participants should: +- Use a dedicated/clean machine (VM recommended) +- Generate entropy from physical sources (dice, coin flips) +- Wipe the machine after contributing +- Document their process +- Attest to destroying their toxic waste + +### Identity Verification + +To ensure independence, we collect: +- Real name or pseudonym (public) +- Email or contact method (private) +- Optional: PGP key for signed attestation +- Optional: Social proof (GitHub, Twitter, LinkedIn) + +**Note:** We respect privacy but need to verify participants are independent. + +--- + +## Ceremony Process + +### Overview + +``` +┌─────────────┐ +│ Random │ +│ Beacon │ +│ (Block #) │ +└──────┬──────┘ + │ + ▼ +┌─────────────────┐ +│ Participant 1 │ +│ Contributes │ +│ Randomness │ +└──────┬──────────┘ + │ + ▼ +┌─────────────────┐ +│ Coordinator │ +│ Verifies │ +│ Contribution │ +└──────┬──────────┘ + │ + ▼ +┌─────────────────┐ +│ Participant 2 │ +│ Contributes │ +│ Randomness │ +└──────┬──────────┘ + │ + ⋮ + │ + ▼ +┌─────────────────┐ +│ Participant N │ +│ Final │ +│ Contribution │ +└──────┬──────────┘ + │ + ▼ +┌─────────────────┐ +│ Final Keys │ +│ Published │ +└─────────────────┘ +``` + +### Coordinator Responsibilities + +The ceremony coordinator (BitCell core team) will: + +1. **Initialize** the ceremony with a random beacon +2. **Sequence** participant contributions +3. **Verify** each contribution is valid +4. **Publish** intermediate parameters after each contribution +5. **Generate** final keys after all contributions +6. **Document** the entire process + +### Participant Responsibilities + +Each participant will: + +1. **Download** the latest parameters from the coordinator +2. **Generate** local randomness (with physical entropy sources) +3. **Contribute** their randomness to update the parameters +4. **Upload** their contribution to the coordinator +5. **Verify** their contribution was accepted +6. **Destroy** all local files containing secrets +7. **Attest** to destroying their toxic waste + +### Step-by-Step Process + +Detailed participant instructions are in [`ceremony/participant_instructions.md`](../ceremony/participant_instructions.md). + +High-level steps: + +1. **Setup Environment** + ```bash + # Clone repository + git clone https://github.com/Steake/BitCell.git + cd BitCell/ceremony + + # Download current parameters + ./download_params.sh + ``` + +2. **Generate Entropy** + ```bash + # Use physical sources: dice, coin flips, keyboard timing + # The ceremony tool will guide you through this + cargo run --bin ceremony-contribute + ``` + +3. **Contribute** + ```bash + # Tool will: + # - Load current parameters + # - Mix in your randomness + # - Generate new parameters + # - Create proof of contribution + ./ceremony-contribute --input params_round_N.bin --output my_contribution.bin + ``` + +4. **Upload** + ```bash + # Secure upload to coordinator + # Details provided via secure channel + ``` + +5. **Verify & Destroy** + ```bash + # Wait for coordinator verification + # Securely wipe all files + shred -vfz -n 10 * + # Or reimage your VM/machine + ``` + +6. **Attest** + ```bash + # Sign attestation that you destroyed your secrets + gpg --sign attestation.txt + ``` + +--- + +## Key Verification + +### During Ceremony + +After each contribution, the coordinator publishes: +- **Parameters:** Updated τ powers +- **Proof:** Contribution proof from participant +- **Hash:** SHA-256 hash of parameters +- **Attestation:** Participant's signed attestation + +Anyone can verify: +```bash +# Verify contribution N was valid +./verify_contribution --params params_round_N.bin --proof proof_N.json + +# Check hash matches +sha256sum params_round_N.bin +``` + +### After Ceremony + +Once complete, we publish: +- **Final Keys:** `proving_key.bin` and `verification_key.bin` +- **Transcript:** Complete ceremony log +- **Hashes:** SHA-256 hashes of all keys +- **Attestations:** All participant attestations + +Verification: +```bash +# Verify final keys were derived correctly +./verify_ceremony --transcript ceremony_transcript.json + +# Check published key hashes +sha256sum keys/battle/proving_key.bin +sha256sum keys/battle/verification_key.bin +``` + +### Key Commitment + +We commit to the key hashes before the ceremony starts: + +**Battle Circuit Keys** (TBD): +``` +Proving Key: +Verification Key: +``` + +**State Circuit Keys** (TBD): +``` +Proving Key: +Verification Key: +``` + +These hashes serve as a public commitment that prevents key substitution. + +--- + +## Audit Trail + +### What We Record + +For each contribution: +- Participant identifier (name/pseudonym) +- Timestamp +- Input parameters hash +- Output parameters hash +- Contribution proof +- Participant attestation (signed) + +### Public Transcript + +The ceremony transcript includes: +```json +{ + "ceremony_id": "bitcell-battle-circuit-2025", + "circuit": "BattleCircuit", + "start_time": "2025-XX-XX", + "end_time": "2025-XX-XX", + "random_beacon": "Bitcoin block #XXXXXX hash", + "contributions": [ + { + "round": 1, + "participant": "Alice (alice@example.com)", + "timestamp": "2025-XX-XX HH:MM:SS UTC", + "input_hash": "sha256:...", + "output_hash": "sha256:...", + "contribution_proof": {...}, + "attestation": "-----BEGIN PGP SIGNATURE-----..." + } + ], + "final_keys": { + "proving_key_hash": "sha256:...", + "verification_key_hash": "sha256:..." + } +} +``` + +### Third-Party Verification + +We encourage independent auditors to: +- ✅ Verify each contribution proof +- ✅ Verify the random beacon was used correctly +- ✅ Verify final keys match the transcript +- ✅ Verify at least N participants are independent +- ✅ Verify attestations are properly signed + +Tools provided: +- `ceremony-verify` - Automated verification +- `ceremony-audit` - Generate audit report + +--- + +## Post-Ceremony + +### Key Distribution + +After successful ceremony: + +1. **Repository Commit** + - Keys committed to `keys/battle/` and `keys/state/` + - Transcript committed to `ceremony/transcripts/` + - Tagged release: `ceremony-v1.0` + +2. **Multiple Distribution Channels** + - GitHub repository + - IPFS (content-addressed storage) + - BitTorrent (decentralized distribution) + - Official website + +3. **Verification Checksums** + ``` + keys/battle/proving_key.bin SHA256: ... + keys/battle/verification_key.bin SHA256: ... + keys/state/proving_key.bin SHA256: ... + keys/state/verification_key.bin SHA256: ... + ``` + +### Using Ceremony Keys + +**For Node Operators:** +```rust +// Load keys from ceremony +let (pk, vk) = BattleCircuit::load_ceremony_keys()?; + +// Generate proof +let proof = circuit.prove(&pk)?; + +// Verify proof +let valid = BattleCircuit::verify(&vk, &proof, &public_inputs)?; +``` + +**DO NOT** use `BattleCircuit::setup()` in production - this generates insecure test keys! + +### Ongoing Verification + +We recommend: +- Verify key hashes on first node startup +- Include verification in CI/CD pipelines +- Re-verify periodically +- Report any hash mismatches immediately + +### Security Contacts + +If you discover issues: +- Email: security@bitcell.org +- PGP Key: [TBD] +- Responsible disclosure: 90 days + +--- + +## Ceremony Tools + +All ceremony tools are in `ceremony/tools/`: + +- **`ceremony-contribute`** - Participant contribution tool +- **`ceremony-verify`** - Verify contributions and final keys +- **`ceremony-audit`** - Generate audit reports +- **`ceremony-coordinator`** - Coordinator sequencing tool + +See [`ceremony/tools/README.md`](../ceremony/tools/README.md) for usage. + +--- + +## Acknowledgments + +This ceremony protocol is inspired by: +- Zcash Powers of Tau ceremony +- Ethereum KZG ceremony +- Filecoin trusted setup +- Academic research on secure MPC + +Special thanks to all participants who contribute to the security of BitCell. + +--- + +## References + +1. **Groth16 Paper:** "On the Size of Pairing-based Non-interactive Arguments" (Jens Groth, 2016) +2. **Powers of Tau:** https://z.cash/technology/paramgen/ +3. **MPC Security:** "Scalable Multi-party Computation for zk-SNARK Parameters" (Bowe et al., 2017) +4. **BN254 Curve:** "Pairing-Friendly Elliptic Curves" (Barreto-Naehrig, 2006) + +--- + +**Last Updated:** December 2025 +**Maintainer:** BitCell Core Team +**Status:** Ready for Participant Recruitment diff --git a/keys/.gitignore b/keys/.gitignore new file mode 100644 index 0000000..fa4e298 --- /dev/null +++ b/keys/.gitignore @@ -0,0 +1,7 @@ +# Ignore actual key files (too large for git) +# Keys will be distributed via IPFS, BitTorrent, and website +*.bin + +# Keep README files and directory structure +!README.md +!.gitignore diff --git a/keys/README.md b/keys/README.md new file mode 100644 index 0000000..f8402bf --- /dev/null +++ b/keys/README.md @@ -0,0 +1,365 @@ +# BitCell Groth16 Keys + +This directory contains the proving and verification keys for BitCell's zero-knowledge proof circuits, generated through a multi-party trusted setup ceremony. + +--- + +## Directory Structure + +``` +keys/ +├── battle/ +│ ├── proving_key.bin # BattleCircuit proving key +│ ├── verification_key.bin # BattleCircuit verification key +│ └── README.md +└── state/ + ├── proving_key.bin # StateCircuit proving key + ├── verification_key.bin # StateCircuit verification key + └── README.md +``` + +--- + +## Key Hashes + +**IMPORTANT:** Always verify these hashes before using the keys! + +### BattleCircuit Keys + +**Status:** Awaiting Trusted Setup Ceremony (Planned Q1 2026) + +``` +Proving Key SHA-256: [Will be filled after ceremony] +Verification Key SHA-256: [Will be filled after ceremony] +``` + +### StateCircuit Keys + +**Status:** Awaiting Trusted Setup Ceremony (Planned Q1 2026) + +``` +Proving Key SHA-256: [Will be filled after ceremony] +Verification Key SHA-256: [Will be filled after ceremony] +``` + +--- + +## Verifying Keys + +### Quick Verification + +```bash +# Verify BattleCircuit keys +sha256sum keys/battle/proving_key.bin +sha256sum keys/battle/verification_key.bin + +# Verify StateCircuit keys +sha256sum keys/state/proving_key.bin +sha256sum keys/state/verification_key.bin + +# Compare with published hashes in this README +``` + +### Full Verification + +To fully verify the ceremony was conducted correctly: + +1. **Download the ceremony transcript:** + ```bash + # Clone repository or download transcript + git clone https://github.com/Steake/BitCell.git + cd BitCell + ``` + +2. **Run the verification tool:** + ```bash + cd ceremony/tools + cargo run --release --bin ceremony-verify-full \ + --transcript ../../ceremony/transcripts/battle_transcript.json \ + --keys ../../keys/battle/ + ``` + +3. **Verify random beacon:** + - Check that the random beacon (Bitcoin block hash) is correct + - Verify it was chosen fairly (future block at ceremony start) + - Confirm it matches ceremony announcements + +4. **Verify all contributions:** + - Each participant contribution must be verified + - Check that proofs are valid + - Verify the chain of contributions from beacon to final keys + +5. **Review attestations:** + - Read participant attestations in `ceremony/attestations/` + - Verify participants are independent + - Check that attestations are properly signed (if using PGP) + +--- + +## Using the Keys + +### In Production Code + +**Load ceremony keys (PRODUCTION):** + +```rust +use bitcell_zkp::{BattleCircuit, StateCircuit}; + +// Load BattleCircuit keys from ceremony +let (battle_pk, battle_vk) = BattleCircuit::load_ceremony_keys()?; + +// Load StateCircuit keys from ceremony +let (state_pk, state_vk) = StateCircuit::load_ceremony_keys()?; + +// Generate proof +let proof = battle_circuit.prove(&battle_pk)?; + +// Verify proof +let valid = BattleCircuit::verify(&battle_vk, &proof, &public_inputs)?; +``` + +**DO NOT use `setup()` in production:** + +```rust +// ❌ NEVER DO THIS IN PRODUCTION +let (pk, vk) = BattleCircuit::setup()?; // Insecure test keys! + +// ✅ ALWAYS DO THIS IN PRODUCTION +let (pk, vk) = BattleCircuit::load_ceremony_keys()?; // Secure ceremony keys +``` + +### For Testing + +For tests and development, you can use `setup()`: + +```rust +#[test] +fn test_something() { + // Test keys are fine for testing + let (pk, vk) = BattleCircuit::setup().unwrap(); + + // ... test code +} +``` + +### Key Loading Paths + +The keys are loaded from: +- `keys/battle/proving_key.bin` (BattleCircuit) +- `keys/battle/verification_key.bin` (BattleCircuit) +- `keys/state/proving_key.bin` (StateCircuit) +- `keys/state/verification_key.bin` (StateCircuit) + +Paths are relative to repository root. If you move the keys, update the paths in: +- `crates/bitcell-zkp/src/battle_circuit.rs` +- `crates/bitcell-zkp/src/state_circuit.rs` + +--- + +## Key Specifications + +### BattleCircuit + +**Circuit Description:** +- Proves that a Cellular Automaton battle executed correctly +- Verifies Conway's Game of Life rules for all evolution steps +- Ensures winner determination is correct + +**Public Inputs:** +- `commitment_a` - Player A's grid commitment +- `commitment_b` - Player B's grid commitment +- `winner_id` - Winner identifier (0=draw, 1=A wins, 2=B wins) + +**Private Inputs:** +- `final_energy_a` - Player A's final energy +- `final_energy_b` - Player B's final energy + +**Constraints:** ~6.7M (estimated based on 64x64 grid, 10 steps) + +**Proving Key Size:** ~2-4 GB (compressed) +**Verification Key Size:** ~1-2 KB +**Proof Size:** ~192 bytes + +### StateCircuit + +**Circuit Description:** +- Proves that a state transition is valid +- Verifies Merkle tree updates +- Prevents double-spending via nullifiers + +**Public Inputs:** +- `old_state_root` - Previous state root +- `new_state_root` - New state root +- `nullifier` - Prevents double-spending + +**Private Inputs:** +- `leaf_index` - Index in Merkle tree + +**Constraints:** ~1M (estimated) + +**Proving Key Size:** ~500 MB - 1 GB (compressed) +**Verification Key Size:** ~1 KB +**Proof Size:** ~192 bytes + +--- + +## Ceremony Information + +### Ceremony Schedule + +| Phase | Circuit | Dates | Status | +|-------|---------|-------|--------| +| Preparation | - | Dec 2025 | ✅ Complete | +| BattleCircuit Ceremony | BattleCircuit | Q1 2026 | 📅 Planned | +| StateCircuit Ceremony | StateCircuit | Q1 2026 | 📅 Planned | +| Verification | Both | Q1 2026 | 📅 Planned | + +### Ceremony Details + +**Random Beacon:** [Bitcoin block #XXXXXX - TBD] +**Participants:** [20-30 expected] +**Coordinator:** BitCell Core Team +**Contact:** ceremony@bitcell.org + +### Ceremony Transcript + +After ceremony completion, the full transcript will be available at: +- `ceremony/transcripts/battle_transcript.json` +- `ceremony/transcripts/state_transcript.json` + +The transcript includes: +- Random beacon block hash +- All participant contributions +- All verification proofs +- All participant attestations +- Final key hashes + +### Participant List + +After ceremony completion, participants will be listed in: +- `ceremony/participants.md` +- `docs/CEREMONY.md` +- BitCell website: https://bitcell.org/ceremony + +--- + +## Security Notes + +### Trust Model + +The security of these keys relies on **at least one honest participant** in the ceremony: + +- ✅ If ≥1 participant destroyed their toxic waste → Keys are secure +- ❌ If ALL participants colluded → Keys could be compromised + +With 20+ independent participants from diverse backgrounds and locations, the probability that ALL collude is negligible. + +### What If Keys Are Compromised? + +If the keys are compromised (e.g., toxic waste not destroyed): +- Attackers can create fake proofs +- Invalid battles/transactions could be proven valid +- Blockchain security is compromised + +**Prevention:** +- Multiple independent participants (20-30+) +- Geographic diversity (5+ countries) +- Background diversity (developers, academics, enterprises) +- Public attestations and verification +- Open-source ceremony code + +**Detection:** +- Monitor for suspicious proofs +- Watch for invalid state transitions +- Community vigilance + +**Mitigation:** +- If compromise detected: Re-run ceremony +- Network can fork to reject old keys +- New keys deployed via network upgrade + +### Ceremony Best Practices + +Our ceremony follows industry best practices: + +1. **Multiple Independent Participants** (20-30+) +2. **Public Random Beacon** (Bitcoin block hash) +3. **Verifiable Contributions** (Each contribution has proof) +4. **Public Transcript** (Full audit trail) +5. **Participant Attestations** (Public accountability) +6. **Open Source Tools** (Anyone can verify) +7. **Multiple Distribution Channels** (GitHub, IPFS, BitTorrent) + +These practices are based on successful ceremonies by: +- Zcash (Powers of Tau) +- Ethereum (KZG ceremony) +- Filecoin +- Semaphore + +--- + +## Distribution Channels + +The keys are distributed via multiple channels for redundancy: + +### Primary: GitHub + +```bash +git clone https://github.com/Steake/BitCell.git +cd BitCell/keys +``` + +### IPFS (Content-Addressed) + +```bash +# After ceremony, IPFS hashes will be: +ipfs get /ipfs/ +ipfs get /ipfs/ +``` + +### BitTorrent + +```bash +# After ceremony, magnet links will be: +# Battle keys: magnet:?xt=urn:btih: +# State keys: magnet:?xt=urn:btih: +``` + +### Official Website + +Download from: https://bitcell.org/keys + +--- + +## Support + +### Questions? + +- **Documentation:** See `docs/CEREMONY.md` +- **Email:** ceremony@bitcell.org +- **Discord:** #ceremony channel +- **Forum:** https://forum.bitcell.org + +### Report Issues + +If you discover any issues with the keys: +- **Security issues:** security@bitcell.org (PGP key available) +- **Other issues:** GitHub Issues + +### Stay Updated + +- **Website:** https://bitcell.org +- **Twitter:** @BitCellNetwork +- **Blog:** https://blog.bitcell.org + +--- + +## License + +The keys themselves are public data and can be freely used. The ceremony code and tools are licensed under the same license as BitCell (see repository LICENSE file). + +--- + +**Last Updated:** December 2025 +**Key Status:** Awaiting Ceremony (Q1 2026) +**Next Update:** After ceremony completion diff --git a/keys/battle/README.md b/keys/battle/README.md new file mode 100644 index 0000000..8886a98 --- /dev/null +++ b/keys/battle/README.md @@ -0,0 +1,95 @@ +# BattleCircuit Keys + +This directory will contain the proving and verification keys for the BattleCircuit, generated through the trusted setup ceremony. + +## Files + +After the ceremony (planned Q1 2026), this directory will contain: + +- `proving_key.bin` - Proving key for BattleCircuit (~2-4 GB) +- `verification_key.bin` - Verification key for BattleCircuit (~1-2 KB) + +## Key Hashes + +**Status:** Awaiting Trusted Setup Ceremony + +``` +Proving Key SHA-256: [Will be filled after ceremony] +Verification Key SHA-256: [Will be filled after ceremony] +``` + +## Circuit Information + +**BattleCircuit** verifies that Cellular Automaton battles executed correctly. + +**Public Inputs:** +- `commitment_a` - Player A's grid commitment +- `commitment_b` - Player B's grid commitment +- `winner_id` - Winner identifier (0=draw, 1=A, 2=B) + +**Constraints:** ~6.7M (estimated for 64×64 grid, 10 steps) + +**Proving Time:** ~30 seconds target (8-core CPU) +**Verification Time:** <10ms +**Proof Size:** 192 bytes + +## Usage + +```rust +use bitcell_zkp::BattleCircuit; + +// Load ceremony keys (production) +let (pk, vk) = BattleCircuit::load_ceremony_keys()?; + +// Create circuit instance +let circuit = BattleCircuit::new( + commitment_a, + commitment_b, + winner_id, + energy_a, + energy_b, +); + +// Generate proof +let proof = circuit.prove(&pk)?; + +// Verify proof +let valid = BattleCircuit::verify(&vk, &proof, &public_inputs)?; +``` + +## Ceremony Details + +**Random Beacon:** [Bitcoin block #XXXXXX - TBD] +**Expected Participants:** 20-30 +**Expected Duration:** 2-3 weeks +**Coordinator:** BitCell Core Team + +## Verification + +After ceremony completion, verify keys: + +```bash +# Check hashes +sha256sum proving_key.bin +sha256sum verification_key.bin + +# Full verification +cd ../../ceremony/tools +cargo run --release --bin ceremony-verify \ + --transcript ../transcripts/battle_transcript.json \ + --keys ../../keys/battle/ +``` + +## Distribution + +Keys will be distributed via: +- GitHub (this repository) +- IPFS: `ipfs://[CID]` (TBD) +- BitTorrent: `magnet:?xt=urn:btih:[hash]` (TBD) +- Website: https://bitcell.org/keys + +--- + +**Last Updated:** December 2025 +**Status:** Awaiting Ceremony +**Next Update:** After Q1 2026 ceremony diff --git a/keys/state/README.md b/keys/state/README.md new file mode 100644 index 0000000..06c43e4 --- /dev/null +++ b/keys/state/README.md @@ -0,0 +1,94 @@ +# StateCircuit Keys + +This directory will contain the proving and verification keys for the StateCircuit, generated through the trusted setup ceremony. + +## Files + +After the ceremony (planned Q1 2026), this directory will contain: + +- `proving_key.bin` - Proving key for StateCircuit (~500 MB - 1 GB) +- `verification_key.bin` - Verification key for StateCircuit (~1 KB) + +## Key Hashes + +**Status:** Awaiting Trusted Setup Ceremony + +``` +Proving Key SHA-256: [Will be filled after ceremony] +Verification Key SHA-256: [Will be filled after ceremony] +``` + +## Circuit Information + +**StateCircuit** verifies that state transitions are valid. + +**Public Inputs:** +- `old_state_root` - Previous state root +- `new_state_root` - New state root (must differ from old) +- `nullifier` - Prevents double-spending + +**Constraints:** ~1M (estimated) + +**Proving Time:** ~20 seconds target (8-core CPU) +**Verification Time:** <10ms +**Proof Size:** 192 bytes + +## Usage + +```rust +use bitcell_zkp::StateCircuit; + +// Load ceremony keys (production) +let (pk, vk) = StateCircuit::load_ceremony_keys()?; + +// Create circuit instance +let circuit = StateCircuit::new( + old_root, + new_root, + nullifier, + leaf_index, +); + +// Generate proof +let proof = circuit.prove(&pk)?; + +// Verify proof +let valid = StateCircuit::verify(&vk, &proof, &public_inputs)?; +``` + +## Ceremony Details + +**Random Beacon:** [Bitcoin block #XXXXXX - TBD] +**Expected Participants:** 20-30 +**Expected Duration:** 2-3 weeks +**Coordinator:** BitCell Core Team + +## Verification + +After ceremony completion, verify keys: + +```bash +# Check hashes +sha256sum proving_key.bin +sha256sum verification_key.bin + +# Full verification +cd ../../ceremony/tools +cargo run --release --bin ceremony-verify \ + --transcript ../transcripts/state_transcript.json \ + --keys ../../keys/state/ +``` + +## Distribution + +Keys will be distributed via: +- GitHub (this repository) +- IPFS: `ipfs://[CID]` (TBD) +- BitTorrent: `magnet:?xt=urn:btih:[hash]` (TBD) +- Website: https://bitcell.org/keys + +--- + +**Last Updated:** December 2025 +**Status:** Awaiting Ceremony +**Next Update:** After Q1 2026 ceremony