Multi-Player Hash

Core Concepts

Architecture

Generate: Admin API → MultiPlayerHashGeneratorService → GenerateHashesTransaction. Consume: Game Engine → ConsumeHashTransaction → MultiPlayerHashService → Postgres.

Hash Generation

Triggered by a SUPER_ADMIN via the admin API. The controller fires a floating promise — HTTP returns 201 immediately while work runs in the background. A production batch is 5M hashes (~1.5–2 years of play) and now finishes in a few minutes.

The generator (rng.ts → createHashes) starts from SHA-256(uuid) and repeatedly hashes the previous value, yielding pages of 10,000 to keep memory bounded. For 5M that's 500 inserts, all inside a single GenerateHashesTransaction — so a partial run rolls back to zero new hashes; just re-run it.

Index & Ordering — The Critical Detail

Why reversed?

SHA-256 is one-directional. By consuming the last-generated hash first, each round's hash is the SHA-256 pre-image of the previous round's. A player verifies round k by hashing it once and checking it equals round k-1's published hash — chaining back to the revealed round-1 anchor. Future hashes stay hidden because you can't run SHA-256 in reverse. (Consuming in generation order would let anyone hash the first revealed hash forward to reproduce every future result — see Gotchas in Known Problems.)

Index assignment formula

// generate-hashes.transaction.ts
const hashes = hashPage.map((hash, i) => ({
  index: firstAvailableIndex
    + (numberOfHashes - 1)                  // max offset
    - (currentPage * resolvedPageSize + i),  // minus generation position
}));

For a fresh batch of 5 hashes (firstAvailableIndex = 0):

Appending to an existing batch

Generating on top of a non-exhausted batch continues from the current highest unused index + 1. Old and new hashes share one consumption queue; old ones are consumed first.

Hash Consumption

Each round, ConsumeHashTransaction calls findNextHash to select the lowest-index unused hash (WHERE gameId=? AND used=false ORDER BY index ASC LIMIT 1), then marks it used=true and returns it for the caller to decrypt and feed into HMAC. The composite index (used, gameId, index) keeps this fast at 5M rows.

Encryption

Hashes are stored AES-256-CBC encrypted so direct DB access can't leak future results, using the CIPHER_KEY (32-byte hex) and CIPHER_IV (16-byte hex) env vars.

The key/IV pair is fixed and shared across all three multiplayer games and every batch, so encryption is deterministic — the UNIQUE constraint on encryptedHash also rejects duplicate hashes. This key is purely for at-rest encryption; it is not the provably-fair server seed (that's the per-batch random UUID — see Known Problems).

Seeding Events & Provably Fair

The seeding event is the public commitment that lets any player verify past results. Flow:

Example pastebin post

Moonspin.com

Seeding Event for Crash game!
Our 5 millionth hash is 8ea9a675098f2d028edfd5d51ad76c984d3d77970aa144e0752522f82eb5c7a7.
The client seed will be the hash of the un-mined Ethereum block #18733310.

"5 millionth" is the hash's generation position (last of 5M produced), not its round number. It is the round-1 hash.

The Ethereum block as client seed

The client seed must be (1) unknown at generation time, (2) publicly verifiable afterward, and (3) outside Swivel's control. A future Ethereum block hash satisfies all three: every ~12s a validator produces a new block with a unique 32-byte hash, unpredictable until mined, then permanently public. At seeding time the target block doesn't exist yet. (Any public randomness source — Bitcoin, a lottery — would also work; Ethereum is just the chosen one.)

Finding it on Etherscan

Look up blocks and their hashes on etherscan.io — the latest block number is in the header, and etherscan.io/block/<number> shows the "Block Hash" field once mined (404 while still pending).

How far ahead to pick

Where clientSeed lives

// apps/engine/src/games/crash/services/game.service.ts
const nextHash = await this.consumeHashTransaction.run(this.gameId);
this.hash = { id: nextHash.id, hash: this.hashService.decrypt(nextHash.encryptedHash) };

this.multiplier = this.getRoundMultiplier(
  this.hash.hash, houseEdgePercentage,
  this.gameConfig.clientSeed  // ← from GlobalConfig.games.crash.clientSeed
);
// inside: const seed = createHmac(clientSeed, hash); → getCrashMultiplier(...)

Verifying results

const crypto = require('crypto');
const round1Hash = '8ea9a675...';  // the revealed hash = round 1
const clientSeed = '4d9b4a97...'; // the mined ETH block hash

// Round 1: same HMAC the engine runs
const seed1 = crypto.createHmac('sha256', clientSeed).update(round1Hash).digest('hex');

// Round 2: prove it chains back — SHA-256(round2) must equal round1Hash
const link = crypto.createHash('sha256').update(round2Hash).digest('hex');
console.log(link === round1Hash);  // must be true

In-product, the "check hash" link on each multiplayer game's provably-fair modal opens a CodeSandbox prefilled with the round's seed and hash (e.g. https://qwqymg.csb.app/?seed=…&hash=…), so players can run the same verification without writing code.

Step-by-Step Procedure

1. Disable multiplayer games

   Hide from UI so players aren't stuck waiting.

2. Generate hashes

   POST admin-api/multi-player-hashes/generate with { game, hashNumber: 5000000 }. Returns 201; runs in background (few minutes).

3. Decrypt index-0 hash

   Query WHERE gameId='crash' AND used=false ORDER BY index ASC LIMIT 1, then run the decrypt script below.

4. Post seeding event to Pastebin

   Post the revealed hash + target future block number. Reuse an existing Moonspin/Sidepot post as template. Ideally also publish a public blog post — Pastebin isn't discoverable, so a blog post (or in-product page) makes the commitment findable by players.

5. Update client seed + redeploy

   Set clientSeed to the block hash once mined, then redeploy.

6. Verify

   Confirm seed is live in prod and the Pastebin hash matches the DB.

7. Enable multiplayer games

   Unhide from UI. Done.

Decrypt Script

Run locally with secrets from the AWS vault. Pass the encryptedHash of the lowest-index row per game.

// decrypt-hashes.js — run: node decrypt-hashes.js
const crypto = require('crypto');
const IV  = 'XXXX';  // CIPHER_IV  (hex)
const KEY = 'XXXX';  // CIPHER_KEY (hex)

function decrypt(label, encryptedHash) {
  const d = crypto.createDecipheriv('aes-256-cbc',
    Buffer.from(KEY, 'hex'), Buffer.from(IV, 'hex'));
  console.log(label, d.update(encryptedHash, 'hex', 'utf-8') + d.final('utf-8'));
}

// encryptedHash WHERE gameId=? AND used=false ORDER BY index ASC LIMIT 1
decrypt('CRASH', 'XXX');
decrypt('WMB',   'XXX');
decrypt('CHART', 'XXX');

Known Problems — Why This Isn't Fully Provably Fair

1. Old chain consumed under the new client seed

We don't wait for a chain to exhaust before rotating. The seed is switched while thousands of old hashes remain — they were committed to the old seed, so replaying them under the new one breaks reproducibility for thousands of rounds, detectable by anyone who kept the original post.

2. The server seed is never persisted, so it can't be revealed

A proper scheme reveals the server seed once a chain exhausts, so anyone can regenerate the whole chain and confirm nothing was cherry-picked. We can't: the chain's initial randomUUID() is generated inline in generate-hashes.transaction.ts, used once, and discarded — it's gone the moment generation finishes. There's no per-chain secret left to reveal, so the "reveal then rotate" step is impossible. (The AES CIPHER_KEY/CIPHER_IV is unrelated — it's only at-rest encryption of the stored hashes, not the provably-fair seed.)

3. The three games never deplete in sync

Crash, WhenMoonBro, and Chart burn hashes at different rates, so they're never all exhausted together. With one shared secret and one combined rotation, there's no clean moment to retire a chain — so we rotate early and globally, which triggers problem 1.

4. The commitment isn't published immutably or discoverably

Pastebin can be edited or deleted after the fact, and it isn't discoverable — players have no reliable way to find the post. A seeding event should ideally be accompanied by a public blog post (or in-product page) so the commitment is findable, and it must be tamper-evident before the first round of the new chain runs (ideally anchored on-chain).