Documentation
Reference and guides for @galabet/fair, the GFS 1.0 library. Every example on these pages was run against the library before it was published.
The library does one job. It turns a server seed, a client seed and a nonce into a game result that anyone can recalculate later. These pages explain how to call it, what each function returns, how records are built and checked, and how to reproduce the results in another language.
Examples use one public seed so that you can compare your output with ours line by line. The seed is for documentation only. A live server seed stays on your server until you rotate it.
Start here
InstallationAdd @galabet/fair to a Node, browser or TypeScript project and confirm it produces the published roll.Your first verified roundBuild a small Dice server that commits, takes a bet and reveals its seed, then check the round from the player's side and watch a tampered record fail.How it worksThe life of one bet under GFS 1.0, from the hash a player sees before betting to the check anyone can run afterwards.How to check a betFor players, step by step, from saving the commitment before you play to reading the verifier's report after the seed is revealed.
Core concepts
Server seeds and commitmentsWhat the server seed is, how its SHA-256 commitment is calculated and checked, and what the commitment cannot prove without the operator's help.Client seedsThe player's half of the randomness, the two rules a client seed must follow, and what Galabet's demo does when a player changes theirs.Nonce and cursorTwo counters in the HMAC message that get confused, one counting bets and one counting digests inside a single bet.From digest to floatsHow 32 bytes of HMAC output become eight fractions in [0, 1), why each one is exact in a double, and why results are scaled by multiplication and floor with no modulo.Rotation and revealRetiring a server seed publishes it, and that is the moment every bet made under it becomes checkable.Round lifecycleThe order of events for one single-player bet, naming who acts, which library function runs, what the server stores and what the player can see at each point.Crash round lifecycleHow the multiplayer Crash engine and Galabet Flight run a round in time, from chain creation and the salt to bets, cash-outs and the reveal, with the current settlement and recovery boundaries.What verification provesA verified round means less than most people assume and more than a casino's own word. This page draws the line.
Games
DiceWhere a Dice roll comes from, how to check one you were given, and how to run the same calculation in your own code.LimboHow one float becomes a multiplier, where the house edge goes in, and why about one round in fifty lands on exactly 1.00.PlinkoHow a Plinko path is read from the seeds, why the row count decides the cursor in the record, and how often each bucket comes up.MinesWhere the mines go on a 25-tile board, and the harder problem of keeping that answer hidden until the round is over.RouletteOne float, one multiplication, a pocket from 0 to 36. The shortest mapper in the library.WheelA Wheel spin is one float multiplied by the number of segments, and what comes back is a segment index, never a prize.KenoA Keno draw shuffles forty numbers, keeps the first ten and sorts them, which costs 39 floats and leaves the order of the draw out of the record.BlackjackWhat a shuffled deck from the library proves about a blackjack hand, what it can't, and how to keep the part it can't.Hi-LoHi-Lo walks the Blackjack deck one card at a time, and the rules for aces and equal ranks are yours to choose and publish.CrashThe multiplayer profile. A hash chain fixed in advance, a salt nobody controlled, and a crash point anyone can recalculate from the two.
Records
Record formatEvery field of a GFS 1.0 record, which ones are fixed, which appear later, and how a record is hashed and signed.Canonical JSON and record hashThe exact serialisation rules behind recordHash and record signatures, what canonicalJson does with values that are not JSON, and a Python port that produces the same bytes.Signing recordsEd25519 signatures over records, the key layout, and what to do about a bet-time signature that stops verifying once the server seed is revealed.Verifying recordsWhat verifyRecord checks, every field it returns, every reason string it can give, and the things it leaves unchecked.Inspecting untrusted recordsinspectRecord validates a record from a stranger before calculating anything, then reports each check on its own line with a status of matches, mismatch or incomplete.
Building a backend
Storing seeds and reserving noncesWhat a backend has to keep for each player session, why the nonce counter gets a key of its own, and what disappears when seeds live only in memory.Concealed gamesHow a server runs a round whose result has to stay hidden while the player is still making choices, shown with an in-memory Mines round and the rules Galabet's demo API enforces around it.Settling betsThe library hands back an outcome and never sees a stake, so payout rules, rounding, the order of debit and credit, and retried requests are all the application's job.Exposing a verify endpointA stateless HTTP route that recomputes a result from seeds and a nonce, with the request shape, the input bounds and the rate limits Galabet's demo API uses, and a plain Node version you can run.Verifying in the browserRunning play, verifyRecord and inspectRecord on the player's device, handing a record from one page to another without sending it to a server, and the size limits that apply.Testing your integrationTests that show a provably fair backend is wired correctly, from known answers and vectors to concurrency and distribution checks, and what this project's own API tests leave unproven.Self-hosting the APIRunning Galabet's NestJS API on your own machine or server, with its Postgres and Redis, environment variables, worker process, PM2 and Nginx setup, and the pieces the repository does not yet contain.
Recipes
Plain Node serverA single-file Dice server on node:http with many sessions, player-chosen client seeds, settled bets, rotation and a history that gains seeds as they are revealed.NestJSFrom an empty Nest project to a seeds service with bet, rotate, history and verify routes, using a store provider, a zod pipe and a session header, distilled from Galabet's demo API.Redis seed storageThe Redis keys, Lua scripts and lock that Galabet's demo API keeps around @galabet/fair, and how every key of a session is made to expire at the same moment.React verifierA small React component that checks a pasted record with inspectRecord, shows the status, the checks and the first difference, and never shows a result for text that has since changed.
Security
Protecting the server seedThe server seed is the only secret in a single-player round, and this page covers what it is worth to an attacker, where it leaks from, and how to test that it hasn't.Publishing commitmentsA commitment is worth something only if the player could see it before betting, and no record can prove that, so this page is about what operators and players do instead.Nonce reuse and replayWhat a player gains when a server seed, client seed and nonce are used for a second bet, the five ways that happens, and what Galabet's demo API does about each.Threat modelWho can attack a GFS 1.0 round, what each of them might try, and whether the scheme prevents it, detects it or does nothing about it.
Porting
Porting guideEvery detail a GFS 1.0 implementation in another language has to reproduce exactly, why each one is the way it is, and what you see when it's wrong.Already running a provably fair systemHow an operator with a working provably fair system finds out whether it already matches GFS 1.0, which differences are the usual ones, and what to do about bets already placed.Test vectorsWhat's in the vector files, and a 60-line Python program that reproduces all 2,240 game results without the library.Python walkthroughA GFS 1.0 port written in Python one stage at a time, with each stage checked against its section of the vector files before the next is started.
HTTP API
Verify endpointsReference for the three POST routes under /api/verify in Galabet's demo API, with every request field, the response bodies, the error shapes, and the limits that apply.Demo game endpointsThe session, seed and practice-chip routes under /api/demo in Galabet's demo API, in the order a client calls them, from opening a session to checking its history after rotation.Flight endpointGET and POST /api/flight, the practice crash game served by the Galabet site itself, with its session cookie, five actions, server-clock settlement and the record a finished flight leaves behind.
Reference
Library APIEvery export of @galabet/fair 0.1.0 and @galabet/fair/games, with its signature, what it returns, what it throws and what it leaves unchecked.TypesEvery type exported by @galabet/fair 0.1.0, as the source declares it, with the notes a definition cannot carry.ErrorsEvery message @galabet/fair 0.1.0 can throw, which function throws it and why, plus the reason strings verifyRecord returns.TroubleshootingSymptoms people hit with @galabet/fair 0.1.0, each reproduced before it was written down, with the causes in the order they usually turn out to be true.Limits and non-goalsWhat @galabet/fair 0.1.0 and GFS 1.0 leave out, what a claim of conformance does and does not cover, and every numeric limit in one table.GlossaryThe words this documentation and the verifier use, each with what the thing is for and the page that covers it.Versioning and changelogThe three version numbers in this project, what each one promises to someone holding old records, and the changelog for @galabet/fair.
Versions
Three numbers appear on this site and they measure different things. GFS 1.0 is the specification, the calculation rules these pages document. It is the only GFS version. A 1.1 that adds a public randomness beacon is planned and not written. 0.1.0 is the version of the @galabet/fair package. Fair 1.0, 2.0 and 3.0 are editions of the Galabet product, covering the foundation, the ten game pages and Galabet Flight. An edition number says nothing about the calculation rules. Every edition uses GFS 1.0.
Try It Without Installing Anything
The Dice page runs the same calculation in your browser and shows each step. The verifier checks a completed record locally, without uploading it.