Docs

How it works

Generations & the hash chain

The generation record, canonical JSON, how the seed is derived, and what quotes_hash and trades_hash bind.

The record#

When a generation closes, the engine writes one record. Its fields:

FieldContent
vRecord format version, 1
nGeneration number
engineEngine version, forgeus-engine/1
prev_hashHash of the previous record
seedSeed for this generation's randomness
paramsThe engine parameters (window, warmup, pop, cost, weights)
windowPer market: first and last quote id and block, start and end time, warmup_from_id, quotes_hash
populationThe 24 circuits evaluated: id, genome, parent, born
resultsPer circuit: ret, maxdd, fitness, trades, rank, outcome
baselinePer market hold baseline: ret, maxdd, fitness
offspringChildren: id, parent, genome, diffs
trades_hashHash of every paper trade in the generation
nullWhether this is a null result
null_reasonWhy, or null
bestRank 1 circuit: id, fitness, ret

Canonical JSON#

Hashes are taken over canonical JSON, so the same record always gives the same bytes:

  • Object keys sorted.
  • No whitespace.
  • Keys with undefined values dropped.
  • Numbers and strings written by JSON.stringify.
  • Arrays keep their order.
ts
function canonical(v: unknown): string {
  if (v === null || typeof v !== "object") return JSON.stringify(v);
  if (Array.isArray(v)) return `[${v.map(canonical).join(",")}]`;
  const o = v as Record<string, unknown>;
  return `{${Object.keys(o)
    .filter((k) => o[k] !== undefined)
    .sort()
    .map((k) => `${JSON.stringify(k)}:${canonical(o[k])}`)
    .join(",")}}`;
}

The hash#

text
hash = sha256( prev_hash + "\n" + canonical(record) )

The result is lowercase hex. Generation 1 uses 64 zeros as prev_hash. Every later record names the previous hash, so editing or deleting any generation breaks every hash after it.

Seed#

text
seed = first 8 hex chars of sha256( prev_hash + ":" + n )

The seed feeds mulberry32, a small deterministic PRNG. The genesis population uses sha256("000…000:0") (64 zeros, then :0). Because the seed comes from the previous hash, nobody can pick a favourable seed without changing the record before it.

ts
function rng(seedHex: string) {
  let a = parseInt(seedHex, 16) >>> 0;
  return () => {
    a = (a + 0x6d2b79f5) >>> 0;
    let t = a;
    t = Math.imul(t ^ (t >>> 15), t | 1);
    t ^= t + Math.imul(t ^ (t >>> 7), t | 61);
    return ((t ^ (t >>> 14)) >>> 0) / 4294967296;
  };
}

quotes_hash#

One per market. It covers all 120 quotes (warmup and window), oldest first:

text
quotes_hash = sha256( canonical( quotes.map(q => [q.id, q.block, q.sqrt_price]) ) )

It binds the raw on-chain value and the block, not the derived price. The price is checked separately against sqrt_price during replay.

trades_hash#

text
trades_hash = sha256( canonical(trades) )

trades is every paper trade of the generation, in population order and then in time order. Each trade has strategy, market, quote_id, block, ts, price, from, to and reason.

Why floats are safe#

The engine uses only + - * / and comparisons on floats, and rounds results at fixed points. These operations are exact under IEEE 754 in every JavaScript engine, so a replay in your browser or in Node gives the same bytes as the server.

Paper only. No funds are traded. $FOUS is not launched. Nothing here is financial advice.