🪙 Thru Coin Flip CLI

A polished command-line interface for interacting with coin flip programs on the Thru blockchain.

✨ Features

• 🪙 Flip coins using blockchain entropy for randomness
• 🎮 Interactive mode for easy coin flipping
• ⚙️ Configuration for custom program IDs
• 🚀 Works instantly with pre-deployed program

🛠 Setup

Prerequisites

• Node.js 16+
• Thru CLI installed and configured

Installation & Usage

# One-time use (no installation)
npx thru-coin-flip-cli@latest flip

# Interactive mode
npx thru-coin-flip-cli@latest interactive

# Or install globally
npm install -g thru-coin-flip-cli
coin-flip flip

📋 Commands

coin-flip check

Verify that thru-cli is installed and system is ready.

coin-flip flip [--program <programId>]

Execute a coin flip. Uses built-in default program or custom program ID.

coin-flip config [--show] [--set <programId>]

Manage default program ID configuration.

coin-flip interactive

Start interactive mode for easy coin flipping.

🎲 How It Works

The coin flip program uses blockchain entropy for randomness:

1. Entropy Sources: Combines parent block hash, state root, block time, slot, transaction signature, and nonce
2. SHA256 Hashing: Creates deterministic hash from multiple entropy sources
3. Fair Result: Uses least significant bit for 50/50 probability
4. Event Emission: Results are permanently recorded on-chain
5. Verification: All entropy sources are publicly verifiable

📁 Project Structure

thru-programs/
├── src/                    # TypeScript CLI source
│   ├── cli.ts             # Main CLI interface
│   ├── utils.ts           # Thru CLI wrapper utilities
│   └── types.ts           # TypeScript definitions
├── coin_flip.c            # C program source
├── coin_flip.h            # C program header
├── GNUmakefile           # Tutorial-style makefile
├── Local.mk              # SDK build configuration
└── build/                # Compiled artifacts
    └── thruvm/bin/       # Program binaries

🔧 Development

# Run in development mode
npm run dev

# Build TypeScript
npm run build

# Build C program
npm run build-program

# Clean all builds
npm run clean

💡 Examples

Basic Usage

# Quick flip with default program
coin-flip flip

# Flip using specific program
coin-flip flip --program ta8xK9mNcP2wQ5...

# Interactive mode
coin-flip interactive

Configuration

# View current config
coin-flip config --show

# Set custom default program
coin-flip config --set ta8xK9mNcP2wQ5...

🚀 Technical Details

• Language: C program compiled to RISC-V bytecode
• Blockchain: Thru testnet with zero-fee transactions
• Randomness: Cryptographically secure blockchain entropy
• CLI: TypeScript with Commander.js framework
• Build System: Thru SDK makefile with proper linking

🎯 Result Format

🎲 COIN FLIP RESULT 🎲
═══════════════════════════════════════
Result: HEADS
Slot: 756
Signature: tsJDG61YPxWfmKQj...
Compute Units: 44,445
Events: 1 emitted
═══════════════════════════════════════

🛡 Randomness

The coin flip uses blockchain-based randomness:

• Entropy comes from blockchain data (not user-controllable)
• SHA256 ensures deterministic but unpredictable results
• All data sources are publicly verifiable on-chain
• Program logic is open source and auditable

📝 License

MIT - Feel free to use and modify for your projects.

Built with ❤️ for the Thru blockchain ecosystem