Kybos - Decentralized Dice Prediction Market

A prediction market application built on Demos Network where users bet on dice roll outcomes using DEM cryptocurrency.

What is Kybos?

Kybos is a real-money prediction market for d20 dice rolls. Users connect their Demos Network wallet, place bets on dice outcomes (high/low, even/odd, exact numbers, or ranges), and win payouts based on blockchain-verified random dice rolls.

The application uses Decentralized Autonomous Honest Randomness (DAHR) to ensure provably fair dice rolls, with all results verifiable on the Demos blockchain.

Features

Four bet types: High/Low, Even/Odd, Exact Number, Range (1-10)
Real-time dice roll updates via WebSocket
Blockchain-verified payment transactions
Automatic payout processing for winning bets
Full betting history tracking
Responsive design for mobile and desktop

Architecture

Frontend

React 18 with TypeScript
Vite build system
Zustand for state management
TailwindCSS for styling
Demos SDK for wallet integration

Backend

Bun runtime with TypeScript
Hono web framework
SQLite database for persistence
Redis for caching and real-time state
WebSocket for live updates

Blockchain

Demos Network for payments and identity
DAHR (Decentralized Autonomous Honest Randomness) for dice rolls
On-chain transaction verification

Production Deployment

Prerequisites

Docker and Docker Compose installed
Demos Network wallet mnemonic for server
Domain names configured:
- kybos.demos.sh - Frontend
- backendkybos.demos.sh - Backend API

Environment Configuration

Create a .env file in the project root:

# Backend Configuration
SERVER_MNEMONIC=your_twelve_word_mnemonic_here
DEMOS_RPC_URL=https://node2.demos.sh
PORT=3001
NODE_ENV=production
DICE_ROLL_INTERVAL=60000
DATABASE_URL=./data/dice_rolls.db
REDIS_URL=redis://redis:6379

# Frontend Configuration
VITE_BACKEND_URL=https://backendkybos.demos.sh
VITE_WEBSOCKET_URL=wss://backendkybos.demos.sh/ws
VITE_DEMOS_RPC_URL=https://node2.demos.sh

Running with Docker Compose

# Start all services
docker-compose -f docker-compose.prod.yml up -d

# View logs
docker-compose -f docker-compose.prod.yml logs -f

# Stop services
docker-compose -f docker-compose.prod.yml down

# Restart specific service
docker-compose -f docker-compose.prod.yml restart backend

Services

The production setup includes:

frontend - React application (port 80)
backend - API server (ports 3001-3002)
redis - Caching layer (port 6379)
db-backup - Automated daily database backups
nginx (optional) - Reverse proxy for SSL termination

Health Checks

All services include health checks for reliability:

# Backend health
curl https://backendkybos.demos.sh/health

# Frontend health (through reverse proxy)
curl https://kybos.demos.sh

Database Backups

Automated backups run daily and are stored in ./backups/:

# List backups
ls -lh backups/

# Restore from backup
cp backups/dice_rolls_20250124_120000.db server/data/dice_rolls.db
docker-compose -f docker-compose.prod.yml restart backend

Backups are automatically cleaned up after 7 days.

Development Setup

Prerequisites

Bun 1.0+ installed
Node.js 18+ (for compatibility)
Redis running locally

Installation

# Install dependencies
bun install

# Start backend
cd server
bun run dev

# Start frontend (in new terminal)
bun run dev

Development URLs

Frontend: http://localhost:3000
Backend API: http://localhost:3001
WebSocket: ws://localhost:3002/ws

Environment Variables (Development)

Create .env files:

Root .env:

VITE_BACKEND_URL=http://localhost:3001
VITE_WEBSOCKET_URL=ws://localhost:3002/ws
VITE_DEMOS_RPC_URL=https://node2.demos.sh

server/.env:

SERVER_MNEMONIC=your_development_mnemonic
DEMOS_RPC_URL=https://node2.demos.sh
PORT=3001

API Documentation

Authentication

All bet placement requires a valid Demos Network wallet signature.

Endpoints

GET /health

Health check endpoint

{
  "status": "healthy",
  "services": {
    "database": true,
    "redis": true,
    "diceService": true
  }
}

GET /api/markets

Get available betting markets

{
  "success": true,
  "data": [
    {
      "id": "high_low",
      "title": "High or Low",
      "description": "Bet if dice lands 11-20 (High) or 1-10 (Low)",
      "status": "active"
    }
  ]
}

POST /api/predictions/payment

Place a bet with DEM payment

Headers:

X-Idempotency-Key: Unique request identifier (required)

Body:

{
  "marketId": "high_low",
  "userId": "0x...",
  "prediction": "high",
  "amount": 5,
  "transactionHash": "0x..."
}

Response:

{
  "success": true,
  "data": {
    "id": "bet_abc123",
    "status": "pending",
    "prediction": "high",
    "amount": 5
  }
}

GET /api/rolls/latest

Get most recent dice roll

{
  "success": true,
  "data": {
    "result": 15,
    "timestamp": 1706112000000,
    "attestation_hash": "0x...",
    "valid": true
  }
}

GET /api/predictions/:userId

Get betting history for a user

{
  "success": true,
  "data": [
    {
      "id": "bet_123",
      "prediction": "high",
      "amount": 5,
      "status": "won",
      "payout": 10,
      "created_at": 1706112000000
    }
  ]
}

WebSocket Events

Connect to /ws for real-time updates:

const ws = new WebSocket('wss://backendkybos.demos.sh/ws');

ws.onmessage = (event) => {
  const { type, data } = JSON.parse(event.data);

  switch (type) {
    case 'dice_roll':
      // New dice roll result
      console.log('Roll:', data.result);
      break;

    case 'bet_verified':
      // Bet payment verified
      console.log('Bet verified:', data.betId);
      break;

    case 'bet_resolved':
      // Bet outcome determined
      console.log('Bet result:', data.status);
      break;
  }
};

Security Features

Implemented

Environment variable validation at startup
Circuit breakers for RPC calls (30s timeout, auto-retry)
Idempotency keys for duplicate bet prevention
Transaction hash uniqueness constraints
CORS restrictions to known domains
Health checks for all services
Automated database backups

Production Recommendations

Enable rate limiting on reverse proxy
Implement structured logging (Pino/Winston)
Add Prometheus metrics for monitoring
Set up blockchain payment verification
Configure automated alerts for health check failures

See TODO.md for remaining production hardening tasks.

Project Structure

.
├── src/                    # Frontend React application
│   ├── components/         # React components
│   ├── services/          # API and WebSocket clients
│   ├── stores/            # Zustand state management
│   └── lib/               # Utility functions
├── server/                 # Backend Bun application
│   ├── src/
│   │   ├── services/      # Business logic services
│   │   ├── utils/         # Utilities and helpers
│   │   └── schemas/       # Validation schemas
│   └── data/              # SQLite database
├── docker-compose.prod.yml # Production deployment
├── Dockerfile.frontend     # Frontend container
├── Dockerfile.backend      # Backend container
└── backups/               # Database backups directory

Troubleshooting

Backend won't start

Check environment variables:

docker-compose -f docker-compose.prod.yml exec backend env | grep SERVER_MNEMONIC

WebSocket connection fails

Verify reverse proxy WebSocket support:

curl -i -N -H "Connection: Upgrade" -H "Upgrade: websocket" \
  https://backendkybos.demos.sh/ws

Database locked errors

Stop all containers and restart:

docker-compose -f docker-compose.prod.yml down
docker-compose -f docker-compose.prod.yml up -d

Circuit breaker open

RPC endpoint is failing. Check Demos Network status:

curl https://node2.demos.sh

Support

For issues and questions:

Check TODO.md for known limitations
Review PAYMENT_VERIFICATIONS.md for payment architecture
Consult Demos Network documentation: https://docs.demos.sh

Name		Name	Last commit message	Last commit date
Latest commit History 62 Commits
.serena		.serena
public		public
server		server
src		src
.dockerignore		.dockerignore
.env.example		.env.example
.gitignore		.gitignore
Dockerfile.backend		Dockerfile.backend
Dockerfile.frontend		Dockerfile.frontend
README.md		README.md
bun.lock		bun.lock
bun.lockb		bun.lockb
diagnose-production.sh		diagnose-production.sh
docker-compose.prod.yml		docker-compose.prod.yml
docker-compose.yml		docker-compose.yml
index.html		index.html
package.json		package.json
postcss.config.js		postcss.config.js
tailwind.config.ts		tailwind.config.ts
tsconfig.json		tsconfig.json
tsconfig.node.json		tsconfig.node.json
vite.config.ts		vite.config.ts

Folders and files

Latest commit

History

Repository files navigation

Kybos - Decentralized Dice Prediction Market

What is Kybos?

Features

Architecture

Frontend

Backend

Blockchain

Production Deployment

Prerequisites

Environment Configuration

Running with Docker Compose

Services

Health Checks

Database Backups

Development Setup

Prerequisites

Installation

Development URLs

Environment Variables (Development)

API Documentation

Authentication

Endpoints

GET /health

GET /api/markets

POST /api/predictions/payment

GET /api/rolls/latest

GET /api/predictions/:userId

WebSocket Events

Security Features

Implemented

Production Recommendations

Project Structure

Troubleshooting

Backend won't start

WebSocket connection fails

Database locked errors

Circuit breaker open

Support

License

About

Resources

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages