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:
| Field | Content |
|---|---|
v | Record format version, 1 |
n | Generation number |
engine | Engine version, forgeus-engine/1 |
prev_hash | Hash of the previous record |
seed | Seed for this generation's randomness |
params | The engine parameters (window, warmup, pop, cost, weights) |
window | Per market: first and last quote id and block, start and end time, warmup_from_id, quotes_hash |
population | The 24 circuits evaluated: id, genome, parent, born |
results | Per circuit: ret, maxdd, fitness, trades, rank, outcome |
baseline | Per market hold baseline: ret, maxdd, fitness |
offspring | Children: id, parent, genome, diffs |
trades_hash | Hash of every paper trade in the generation |
null | Whether this is a null result |
null_reason | Why, or null |
best | Rank 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
undefinedvalues dropped. - Numbers and strings written by
JSON.stringify. - Arrays keep their order.
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#
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#
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.
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:
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#
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.