Errors

Version 0.1.0 throws plain Error objects. There is a message and nothing else: no code, no subclass, no cause. That is a gap. Matching on message text breaks the day a message is reworded, so until codes exist the safer pattern is to validate before calling, with assertServerSeed, assertClientSeed and isGameName, and to treat anything caught as "bad input" without parsing it. The messages below are copied from the source. Angle brackets mark a part that varies, such as <rows>.

A thrown error travels up through every caller. play calls deriveFloats, which calls deriveDigest, which runs both seed assertions, so a bad client seed surfaces from all four with the same text. The "thrown by" column names the function that owns the message and then the exported functions it can escape from.

Seeds

Derivation

Games

The mapper messages escape from play and verifyRecord as well, when the value came in through params.

dice, limbo and roulette throw nothing, including for floats outside 0 to 1.

Crash

verifyCrashLink and expandCrashChain have no messages of their own.

Signing

verifySignature and verifyRecordSignature return false for malformed keys and signatures. They don't throw for them.

Canonical JSON and Hex

inspectRecord and parseInspection

These messages are written for the person who pasted the record, which is why they read differently from the rest. The first five come from parseInspection. inspectRecord runs its input through JSON.stringify and then parseInspection, so it throws them too, with one exception noted in the table.

Range messages for parameters name the bare key (rows: ...), while the unsupported-key message has the prefix (params.rows: ...). Don't rely on either form.

Platform Errors

Some failures come from the platform with the platform's wording. A null record or a record with no commitment makes verifyRecord reject with a TypeError. Web Crypto rejects a secret key whose two halves don't match, an empty HMAC key, and a randomBytes request over 65,536 bytes. On a platform without Ed25519, generateKeyPair, sign and verifySignature reject with whatever that platform raises, and inspectRecord reports the Signature check as unsupported.

Reasons Returned by verifyRecord

verifyRecord has two ways of saying no. A record whose fields are well formed but whose values don't add up resolves with ok: false and one string per problem in reasons. A record with a malformed field throws, using the messages above, because the record is replayed through play without being validated first. inspectRecord draws the line more cleanly: it throws for malformed input only, and everything else comes back as checks with a state.

Reasons accumulate. A record can come back with several.

import { commit, inspectRecord, play, verifyRecord } from '@galabet/fair';

const serverSeed = '5c1f7d3e8a2b4c6d9e0f1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a0b1c2d';
const { commitment } = await commit(serverSeed);
const record = {
  spec: 'GFS/1.0', profile: 'single-player', game: 'dice', params: {},
  serverSeed, commitment, clientSeed: 'galabet', nonce: 42, cursor: 0, result: 56.12, at: 0,
};

try {
  await play({ game: 'plinko', params: { rows: 7 }, serverSeed, clientSeed: 'galabet', nonce: 42 });
} catch (error) {
  console.log(error instanceof Error, error.code, error.message);
}

const wrong = await verifyRecord({ ...record, spec: 'GFS/2.0', result: 12.34, cursor: 3 });
console.log(wrong.ok, wrong.reasons);

for (const check of [verifyRecord, inspectRecord]) {
  try {
    await check({ ...record, nonce: -1 });
  } catch (error) {
    console.log(`${check.name} threw: ${error.message}`);
  }
}

true undefined rows must be 8 to 16
false [
  'unsupported spec GFS/2.0',
  'cursor mismatch: computed 0, record 3',
  'result does not match seeds'
]
verifyRecord threw: nonce must be a non-negative integer
inspectRecord threw: nonce: enter a whole number from 0 to 9007199254740991.

Wrong values came back as three reasons. The malformed nonce threw from both functions, each with its own wording.