domino.gg backend

Go backend for the domino.gg crypto-betting platform: provably-fair games (Plinko, Mines, Dice, Blackjack), multi-chain payment infrastructure (BTC, LTC, ETH, BSC + ERC20/BEP20 stables), JWT auth with refresh rotation, a Postgres-backed job queue, and WebSocket transport for live bets.

Repository layout

domino.gg/
├── cmd/                       # process entrypoints (main packages)
│   ├── server/                # HTTP + WS API server
│   ├── payments/              # background worker: deposit monitor, withdrawal broadcast
│   ├── games/                 # offline simulation/RTP CLI
│   └── test/                  # manual integration smoke tests
├── internal/                  # application packages
│   ├── auth/                  # JWT + refresh token rotation
│   ├── dbm/                   # Postgres access (queries, row types, helpers)
│   ├── games/                 # game orchestration facade
│   │   ├── plinko/            # Plinko engine + RTP math
│   │   ├── mines/             # Mines engine + payout tables
│   │   ├── dice/              # Dice over/under engine
│   │   ├── blackjack/         # Blackjack engine (seeded shoe + hit/stand/double/split)
│   │   └── fariness/          # provably-fair seed/HMAC primitives (pkg name: fairness)
│   ├── http/                  # router, middleware (pkg name: http; alias as httpapi)
│   │   ├── handlers/          # REST endpoint handlers
│   │   └── ws/                # WebSocket hub + bet handlers
│   ├── network/               # low-level TLS-aware transport (Electrum, RPC)
│   ├── payments/              # payment domain contracts + driver registry
│   │   ├── utxo/              # BTC/LTC driver (Electrum-backed)
│   │   ├── evm/               # ETH/BSC driver (native + ERC20/BEP20)
│   │   ├── deposits/          # detected/confirmed callbacks + recovery
│   │   └── withdrawals/       # withdrawal handler + broadcaster + recovery
│   └── queue/                 # Postgres job queue (FOR UPDATE SKIP LOCKED + LISTEN/NOTIFY)
├── utils/                     # cross-package helpers (bcrypt, hCaptcha, misc)
├── domino.gg-database/        # Postgres docker-compose, init SQL, migrations
├── go.mod                     # module: domino.gg (Go 1.25)
└── env.example                # required environment variables

Running

# 1. start Postgres
cd domino.gg-database && docker compose up -d

# 2. populate .env (see env.example for the full list)
cp env.example .env && $EDITOR .env

# 3. run API + WS server
go run ./cmd/server

# 4. run background workers (deposit monitor, withdrawal broadcast)
go run ./cmd/payments

Required env vars: DATABASE_URL, JWT_SECRET, SITE_KEY, HCAPTCHA_SECRET, MODE (DEV/PROD). Chain-specific vars (BTC_*, LTC_*, ETH_*, BSC_*) are listed in env.example and default to mainnet/public defaults when unset.

Where to look

• Add a new HTTP endpoint → internal/http/handlers/ + wire in internal/http/router.go
• Add a new WS message → internal/http/ws/ — read pump dispatches by JSON key
• Add a new game → drop an engine package under internal/games/, wire it into internal/games/games.go, then add a WS handler in internal/http/ws/bets.go
• Add a new chain/asset → implement payments.Driver, register in cmd/server/main.go and cmd/payments/main.go; add the enum entry in internal/payments/types.go and storage divisor in internal/payments/units.go
• Add a new DB query → put SQL in internal/dbm/ so handlers stay transport-only
• Add a background job → register a handler kind on queue.Queue in cmd/payments/main.go

Subpackage docs

Each package has a README explaining types, key functions, and usage. Start with the package you are touching:

• cmd/server, cmd/payments, cmd/games, cmd/test
• internal/auth, internal/dbm, internal/queue, internal/network
• internal/http, handlers, ws
• internal/games, plinko, mines, dice, blackjack, fairness
• internal/payments, utxo, evm, deposits, withdrawals
• utils, domino.gg-database

Conventions

• Money is stored as integer base units (satoshi for BTC/LTC, wei for ETH/BSC, smallest token unit for ERC20/BEP20). Conversion factors live in internal/payments/units.go.
• DB enum crypto_currencies is the single source of truth for supported assets; keep internal/payments/types.go and internal/dbm/crypto.go in sync with it.
• Game outcomes must be deterministic given (serverSeed, clientSeed, nonce) — fairness primitives are in internal/games/fariness/.
• Every settled bet is persisted to the bets table for the public feed and audit (see internal/dbm/bets.go and internal/http/ws/bets.go).