Concepts

Deterministic inference

Why every machine that runs a Laplace model gets the same bits.

A Laplace model is an integer program run by one step function. This page says what makes two runs of it identical bit for bit: the number formats, the operators, the order of steps, what the seed does, and the three builds of the same source. It also defines the step, the state, the state root and the trace root that the rest of the docs use.

What a run is

A model is three things, fixed when it is compiled: a list of weight chunks, a list of steps, and a set of state pages. A run takes an input (token ids) and a seed, starts from a state of all-zero pages, and executes every step in order. Nothing else enters a run.

PartWhat it is
Page128 words, each a signed 32-bit integer. A page is 512 bytes, little-endian.
StateAll of the model's pages. The page count is fixed per model.
Weight chunkA run of bytes holding quantized weights. A step reads at most one.
StepOne bounded slice of one operator. It reads at most three pages (a, b and its target c) and one weight chunk, and writes the target page.
Step countThe length of the step list. Every run of the model executes exactly that many steps, whatever the input.

The first step of every model is load, which writes the input and the seed into a page. The last is output, which reads the answer from a page. Everything between is arithmetic on pages.

Numbers

Every value in a run is an integer. The step function has no floating-point operation in it.

ValueFormat
A word of statei32, read as Q16 fixed point: 65536 is 1.0.
A weighti8, with one i32 scale per matrix row. The scale is in units of 2^-24: 16777216 is 1.0.
A biasi32, Q16.
A norm gain or biasi16, with one i32 exponent shift per block: the value is v / 2^shift.
An intermediate resulti64. Sums and sums of squares in the norms use i128.

The rules that fix the low bits:

OperationRule
Multiply two Q16 values(a * b) >> 16 on i64 with an arithmetic shift, so it rounds toward negative infinity. The product saturates at the i64 range.
Divide two Q16 values(a << 16) / b, rounding toward zero. Division by zero gives 0.
Write a wordEvery result is clamped into the i32 range before it is stored: above 2147483647 it becomes 2147483647, below -2147483648 it becomes -2147483648.
A weight times a wordi8 * i32 summed in i64 across the row, then (sum * scale) >> 24.
An embedding row(i8 * scale) >> 8 per word.
Square rootThe integer floor of the square root of a u64.
MeanThe sum divided by the count, rounding toward zero.
Inverse deviationThe variance in Q32 plus 1, its integer square root, then 2^32 divided by that root.
e^xDefined for x at or below zero. x is multiplied by 94548 (log2 of e in Q16), split into an integer and a fraction, and 2^fraction is a degree-5 polynomial with fixed Q30 coefficients. Below -24.0 the result is 0.
tanh(1 - e^(-2a)) / (1 + e^(-2a)) for a the magnitude of x, from the rules above, with the sign of x.
geluThe tanh form, 0.5 x (1 + tanh(k (x + c x^3))), with the constants 52293 (the square root of 2/pi) and 2930 (0.044715).

Each of these is a pure function of its integer arguments. A CPU, a WASM engine and the Solana runtime compute integer arithmetic identically, so each gives the same result.

Operators

The step function has 15 operators. A step names one by its code. target is the page the step writes.

CodeNameComputes
0loadClears the target, then writes the token count into word 0, the tokens into words 1 to 64, and the seed into words 126 (low 32 bits) and 127 (high 32 bits). The input and seed come from the receipt.
1embedOverwrites the target with one embedding row: the row of the token at a fixed position of the input page.
2add-rowAdds one row to the target: the row for a fixed position and its segment. The segment is 1 for positions inside the input's length that come after the first token 102, otherwise 0.
3matvecA few rows of a matrix against one page: each output word is the row's dot product with the page, scaled, plus the row's bias when the chunk carries one. The first slice of a row writes the word, later slices add to it.
4norm-statsThe mean and the inverse standard deviation of one or two pages, written to two words of the target.
5norm-applyLayer norm on the target: subtract the mean, multiply by the inverse deviation, multiply by the gain, add the bias.
6norm-sumFor a vector wider than two pages: adds the sum and the sum of squares of page a into four words of the target. The vector's first page overwrites them.
7activationGELU or tanh on a range of the target, in place.
8norm-statsTurns those sums into the mean and the inverse standard deviation, in the same words of the target.
9residualtarget + a, word by word.
11scoresAttention scores for the heads one page holds: each head's query against one token's key, a dot product, scaled. The judge's pages hold two heads of 64 dimensions scaled by 1/8; the market model's hold four heads of 32 dimensions scaled by 11585 (the inverse square root of 32 in Q16).
13softmaxSoftmax over each head's row of the target. Keys beyond the input's length are set to 0.
14weighted-sumAdds one token's value page, weighted by its attention probability in each head, into the target.
16argmaxWrites the index of the largest of the first n words of page a into word 0 of the target. On a tie the lowest index stands.
19outputReads the answer, word 0 of page a, and produces the output leaf instead of a page.

Codes 10, 12, 15, 17 and 18 name no operator. A step with one of them does not execute.

The integer format gives every field of a step and what each operator reads from it.

A fixed order

The step list is part of the model. Step k is the same operator on the same pages in every run, and there is no branch, loop or early exit that depends on the data: the judge always runs 64 token positions and the market model always runs 32, however long the input is. The only choice the data makes is which weight chunk an embed or add-row step reads, and that choice is a fixed formula of the token in the input page.

Every sum inside a step runs in index order, so there is no reordering for the result to depend on.

The seed

Neither model samples. Each answers one token, the argmax of three logits, so the answer is a function of the input alone.

The seed is the u64 on the receipt. load writes it into words 126 and 127 of the input page, and no step reads those words. The seed changes the input page, so it changes every state root from step 1 on and the trace root, and it changes nothing else: the same input gives the same answer under any seed. Two runs agree on the trace root only when they agree on the seed, which is why a run again uses the receipt's.

One step function, three builds

The step function is one Rust source, the crate laplace-vm, built three ways:

BuildWhere it runs
NativeThe laplace-vm binary that laplace serve and laplace watch run a model with.
WASMInside @laplace/sdk/vm, which the browser uses for Run it again and the SDK uses for rerun.
SBFLinked into the laplace program, which executes one step in prove_step.

Hashing is SHA-256 in all three: the sol_sha256 syscall inside the program, the sha2 crate elsewhere.

A run in WASM gives the native run's output and trace root. laplace-vm check runs a model natively, builds the prove_step payload for a sample of steps, and executes each payload through verify, the function the program calls in prove_step, comparing the root each leads to with the run's own: Prove sampled steps.

The same bits everywhere runs one real step in the page and shows its bits beside the bits the on-chain build gives.

The state root

The state root commits to every page. Each page is hashed as a leaf, and the leaves form a binary Merkle tree:

Text
leaf  = sha256(0x00 || the page's 512 bytes)
node  = sha256(0x01 || left || right)

The tree has the smallest power-of-two number of leaves that holds the model's pages. Positions past the last page hold 32 zero bytes. The root before step 0, with every page zero, is the model's init_root.

A step changes one page, so it changes one leaf and the nodes above it. That is what lets a single step be checked from a few pages and a short proof, as One step on chain describes.

The trace root

A run of T steps produces T + 1 roots:

RootValue
root(0)The init_root.
root(k) for k from 1 to T - 1The state root after k steps.
root(T)The output leaf: sha256("laplace.output" || count as u16 || each output token as u16), little-endian.

The trace root is the root of a Merkle tree whose leaves are these T + 1 values, in order, used as they are. Nodes hash as above and missing positions hold 32 zero bytes.

The trace root is what an operator posts with its output. Two runs that agree at every step have the same trace root. Two runs that differ at any step have different roots from that step on, and the challenge game finds the first one.

operator
this run
operator ≡ this run
Two runs of one model on one input and seed have one trace root.

Seeing it

Run a model twice with the native binary and compare the lines. The first argument is a folder holding the model's program.bin and weights.bin. This is the market model on Nvidia beats revenue estimates and raises its outlook, twelve tokens, with seed 42:

Shell
laplace-vm run models/market --input 101,1050,17258,2401,10299,6599,10035,1998,13275,2049,17680,102 --seed 42
JSON
{"output":[2],"traceRoot":"06a493141d3ad1be6922705a48d1e1c28c10fe0b050842e18be8fde99e96bc83","stepCount":1318668,"ms":1934}

The answer is token 2, positive. A second run prints the same output and traceRoot, and the same model in WASM through @laplace/sdk/vm gives them too. Only ms, the time the run took, changes between runs and machines.

With --seed 7 the answer stays 2 and the trace root becomes another:

JSON
{"output":[2],"traceRoot":"0d740772ae55e91e844d67dcbf24c3e272b69d7e72f1ef1604b07a5bcf0cfa49","stepCount":1318668,"ms":1964}