Hashbit

A provably fair Bitcoin block hash prediction game built on the Stacks blockchain. Users predict whether the last character of an upcoming Bitcoin block hash will be ODD or EVEN, with payouts distributed based on pool ratios.

This repository contains both the smart contracts (onchain) and the web application (offchain).

Prerequisites

Before running the project, ensure you have the following installed:

General

• Docker: Required for running the local Stacks devnet.

Onchain (Smart Contracts)

• Clarinet: The Stacks smart contract development tool.
  • Installation Guide

Offchain (Web App)

• Elixir: The programming language for the backend.
• Erlang: The runtime system for Elixir.
• Phoenix Framework: The web framework.
• PostgreSQL: The database.
• Node.js & npm: For managing frontend assets.

Setup

1. Clone the repository:

   git clone <repository-url>
   cd hashbit

2. Setup Offchain Environment:

   cd offchain
   # Copy environment file
   cp env_example .env.dev
   
   # Install dependencies and setup database
   mix setup
   cd ..

3. Setup Onchain Environment:

   cd onchain
   npm install
   cd ..

Running the Application

You need to run the services in separate terminal windows:

Terminal 1 - Start Clarinet Devnet:

cd onchain
clarinet devnet start

Terminal 2 - Start Phoenix Server:

cd offchain
source .env.dev
iex -S mix phx.server

Access the application at http://localhost:4000.

What is Hashbit?

Hashbit is a prediction game where users stake STX or sBTC tokens on whether the last character of a future Bitcoin block's hash will be ODD or EVEN.

Provable Fairness

The game is 100% provably fair because:

• Bitcoin block hashes are generated through cryptographic mining (proof-of-work)
• No one can predict or manipulate Bitcoin block hashes
• All results are publicly verifiable on the Bitcoin blockchain
• Smart contracts execute payouts automatically based on immutable blockchain data

Character Classification

• ODD characters: 1, 3, 5, 7, 9, B, D, F (hexadecimal odd values)
• EVEN characters: 0, 2, 4, 6, 8, A, C, E (hexadecimal even values)

Payout Mechanics

Payouts are determined by the pool ratio:

• If 60% predict EVEN and 40% predict ODD, and EVEN wins:
  • Total pool = 100 (60 EVEN + 40 ODD)
  • EVEN winners split: their original 60 + losing 40 = 100 total
  • Each EVEN predictor gets back: ~1.67x their stake (100/60)
• If ODD wins instead:
  • ODD winners split: their original 40 + losing 60 = 100 total
  • Each ODD predictor gets back: ~2.5x their stake (100/40)

The less popular prediction yields higher payouts when correct, creating a dynamic, market-driven system.

How It Works

User Flow

1. User connects Stacks wallet (Leather, Xverse, etc.)
2. User views current pool data (ODD/EVEN ratios)
3. User selects prediction type and enters stake amount in STX/sBTC
4. Transaction sent to Stacks smart contract
5. Backend monitors blockchain for new blocks
6. When target block arrives, result is processed
7. Smart contract calculates payouts
8. User claims winnings via UI

Real-time Updates

• Phoenix PubSub broadcasts real-time updates to all connected clients
• Pool data updates instantly when new predictions are placed
• Block results broadcast immediately when blocks arrive
• No page refresh needed for any updates

Technology Stack

Backend

• Elixir/Phoenix: Web framework and real-time communication
• PostgreSQL: Database for prediction tracking and block data
• Ecto: Database ORM and migrations
• GenServer Workers: Background processing for blockchain monitoring

Frontend

• Svelte 5: Reactive UI components using runes
• LiveSvelte: Phoenix LiveView + Svelte integration
• Stacks.js: Blockchain interaction library
• TailwindCSS: Utility-first styling framework

Blockchain

• Stacks Blockchain: Smart contract platform
• Bitcoin: Source of unpredictable block hashes
• Clarity: Smart contract language (external contracts)

Contributing

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

License

This project is open source. See LICENSE file for details.