Architecture Deep Dive

Understand how the smart contract, backend, and frontend work together to create a trustless, provably fair dice game.

System Overview

QTUM Dice is a three-tier application: a Solidity smart contract for on-chain logic, a Node.js backend for seed management and blockchain interaction, and a React frontend for the user interface. Here's how they connect:

The Commit-Reveal Scheme

The core of the provably fair system is the commit-reveal pattern. This cryptographic protocol ensures that neither the house nor the player can influence the outcome after committing to their random seed.

Why Not Just Use a Random Number?

Blockchains are deterministic — there's no native source of randomness that can't be predicted or manipulated by miners. Common approaches and their problems:

• Block hash: Miners can choose not to publish blocks with unfavorable hashes
• Timestamp: Miners have some flexibility in setting block timestamps
• Single-party random: The generator can cheat by choosing seeds that produce favorable outcomes

The commit-reveal scheme solves this by having both parties contribute to the randomness, with commitments locked in before either seed is revealed.

Detailed Flow

export function generateSeed(): string {
  const randomBytes = crypto.randomBytes(32);
  return '0x' + randomBytes.toString('hex');
}

export function hashSeed(seed: string): string {
  return keccak256(seed);
}

export function generateSeed(): string {
  const randomBytes = new Uint8Array(32);
  crypto.getRandomValues(randomBytes);
  return '0x' + Array.from(randomBytes)
    .map(b => b.toString(16).padStart(2, '0'))
    .join('');
}

bytes32 combined = keccak256(
    abi.encodePacked(houseSeed, playerSeed, betId)
);
uint8 roll = uint8(uint256(combined) % 100) + 1;

Backend Architecture

The backend is a Node.js/Express application that serves three primary functions: managing house seeds, monitoring blockchain events, and coordinating the reveal process.

Core Components

DiceGameManager (game.ts)

The central coordinator that manages the game's state:

• House seed generation: Creates random seeds, stores them indexed by hash, auto-expires after 2 hours
• Bet registration: Links on-chain bets with stored house seeds when BetPlaced events arrive
• Player seed storage: Accepts revealed player seeds and triggers the resolution process
• Reveal coordination: Calls revealAndResolve() on the contract when both seeds are available
• Recovery: On startup, retries any pending reveals that may have failed

ContractMonitor (contractMonitor.ts)

Polls the QTUM blockchain every 5 seconds for contract events:

• Uses searchlogs RPC to find BetPlaced and BetResolved events
• Tracks the last processed block to avoid re-processing
• Flattens nested log arrays (QTUM-specific behavior)
• Filters events by topic hash locally (since QTUM ignores the topic parameter)
• Triggers registerBetPlaced() and recordBetResolved() on the game manager

QtumClient (qtum.ts)

A wrapper around QTUM's JSON-RPC interface:

Persistence (persistence.ts)

Simple file-based storage that saves state to JSON files in backend/data/:

• house-seeds.json — Active house seeds indexed by hash
• pending-reveals.json — Bets awaiting resolution
• resolved-bets.json — History of resolved bets

Frontend Architecture

The frontend is a React SPA built with Vite and TypeScript. It handles wallet connection, bet placement, and result display.

Key Hooks

useQtumWallet

Manages the MetaMask + qtum-wallet connection. Provides:

• connect() — Installs snap if needed, gets address and balance
• sendContractTransaction() — Sends encoded contract calls via the snap
• refreshBalance() — Updates the displayed wallet balance
• State: isConnected, address (base58), addressHex, balance

useContract

Handles ABI encoding for smart contract interaction:

• placeBet() — Encodes placeBet(bytes32,uint8,bool,bytes32) and sends via snap
• calculateMultiplier() — Client-side multiplier preview
• calculatePayout() — Client-side payout preview

Betting State Machine

The BetForm component manages a state machine that tracks the bet through its lifecycle:

• idle: Waiting for user input
• placing: Generating seeds, getting house seed, sending transaction
• confirming: Polling backend every 3s for bet to appear on-chain
• resolving: Player seed submitted, waiting for contract resolution
• resolved: Result available, showing win/loss

Smart Contract Architecture

The DiceGame contract is deliberately simple — it handles bet storage, seed verification, roll computation, and payouts. All game logic lives on-chain for transparency and trustlessness.

State

Multiplier Formula

The payout multiplier is calculated based on the win probability, minus the house edge:

// Win chance depends on target and bet direction
winChance = isOver ? (100 - target) : (target - 1);

// Multiplier in basis points (10000 = 1x)
multiplierBps = ((10000 - houseEdgeBps) * 100) / winChance;

// Example: target=50, isOver=true, edge=1%
// winChance = 50, multiplier = 9900 * 100 / 50 = 19800 (1.98x)

Safety Features

• Seed verification: Both seeds are verified against their committed hashes before resolution
• Coverage check: Contract verifies it has enough balance to pay potential winnings before accepting a bet
• Refund mechanism: Players can claim a refund if their bet isn't resolved within 1 hour
• Seed uniqueness: Each house seed hash can only be used once (prevents replay)
• Owner-only admin: Only the contract deployer can change limits or withdraw funds

Data Flow Summary