16 snails labeled 0-F race on concentric rings. Their movement is determined by Wownero block hashes - making every race provably fair and publicly verifiable.

Game Cycle (20 blocks)

Betting Period (10 blocks) - Pick your snails and pay with WOW
Racing Period (10 blocks) - Block hashes drive snail movement
Payout - Winner gets 14x their bet

Snail Movement

Each block's last hex character is compared to each snail's hex digit using circular distance:

Distance	Movement
0 (match)	+3 rings
1-2	+2 rings
3-4	+1 ring
5-6	no move
7-8	-1 ring

First snail to ring 16 wins. If none reach it after 10 blocks, furthest out wins.

Requirements

Node.js 18+
PostgreSQL 14+
wownerod (Wownero daemon)
wownero-wallet-rpc

Setup

# Install dependencies
npm install

# Copy and edit config
cp .env.example .env
# Edit .env with your database credentials, wallet endpoints, etc.

# Create database
createdb wowrace

# Start the server (migrations run automatically)
npm start

# Or for development
npm run dev

Environment Variables

Variable	Default	Description
`PORT`	5000	HTTP server port
`DB_HOST`	localhost	PostgreSQL host
`DB_PORT`	5432	PostgreSQL port
`DB_NAME`	wowrace	Database name
`DB_USER`	wowrace	Database user
`DB_PASSWORD`	-	Database password
`PRIMARY_RPC_ENDPOINT`	http://127.0.0.1:34568	Wownero daemon RPC
`FALLBACK_RPC_ENDPOINT`	http://127.0.0.1:34568	Fallback daemon RPC
`PRIMARY_WALLET_ENDPOINT`	http://127.0.0.1:34570	Wallet RPC
`RPC_POLL_INTERVAL`	10000	Daemon poll interval (ms)
`BET_AMOUNT`	100000000000	Bet amount in atomic units (1 WOW)
`PAYOUT_MULTIPLIER`	14	Winner payout multiplier
`SESSION_SECRET`	-	Session encryption secret
`CRYPTO_TYPE`	WOW	Currency type
`CURRENCY_DECIMALS`	11	Atomic unit decimals

Tor Deployment

WowRace is designed to run as a Tor hidden service:

Install Tor

Add to /etc/tor/torrc:

HiddenServiceDir /var/lib/tor/wowrace/
HiddenServicePort 80 127.0.0.1:5000

Restart Tor: systemctl restart tor
Get your .onion address: cat /var/lib/tor/wowrace/hostname

No HTTPS needed - Tor provides its own encryption layer. Session cookies are configured for HTTP (secure: false).

Architecture

Express.js - Server framework with EJS templates
PostgreSQL - Races, bets, payments, sessions
Server-Side Rendering - No client-side JavaScript at all
Meta Refresh - Auto-refresh for live updates (15s racing, 30s betting)
SVG - Inline SVG race track with 4 animated snail varieties (classic, bigeye, skinny, slimy)
CSS Animations - Per-variety snail animations (body undulation, eye blinking, dripping ooze, etc.)

Key Files

src/
  index.js              - Express app, all routes
  game/
    raceManager.js      - Core game loop, state machine
    snailMovement.js    - Movement calculation (pure functions)
    payoutCalculator.js - Payout strategies
  payments/
    walletRPC.js        - Wallet RPC integration
    paymentMonitor.js   - Payment detection
  rpc/
    daemonRPC.js        - Block height/hash polling
views/
  landing.ejs           - Game explanation page
  play.ejs              - Main game view
  partials/
    raceTrack.ejs       - SVG concentric rings + animation keyframes
    snail.ejs           - Variety dispatcher (routes to correct snail type)
    snail_classic.ejs   - Classic snail (body creep, tentacle sway)
    snail_bigeye.ejs    - Big-eyed snail (blinking, pupil darting)
    snail_skinny.ejs    - Skinny snail (fast stretch, quick tentacles)
    snail_slimy.ejs     - Slimy snail (dripping ooze, bubbles, wet sheen)

Provably Fair

Everything is determined by public blockchain data:

Race number = floor(blockHeight / 20)
Phase = blockHeight % 20 < 10 ? betting : racing
Movement = deterministic function of block hash last character
No server-side randomness

Anyone can verify any race by looking up the block hashes on any Wownero block explorer.

Running Tests

npm test

License

ISC