Concepts
One step on chain
What the program executes to settle a dispute, and what the transaction carries.
When a dispute has narrowed to one step, the laplace program executes that step itself. prove_step carries everything the step reads, each piece with a Merkle proof against a root the program already holds. This page gives the payload byte by byte, the checks the program makes, and why the instruction travels in a v1 transaction.
What the program already holds
Nothing in the payload is trusted. Every piece is tied to one of these values, all on chain before prove_step arrives:
| Value | Where | Fixed by |
|---|---|---|
program_root | The Model account | register_model. Commits to every step of the model. |
weights_root | The Model account | register_model. Commits to every weight chunk. |
step_count, state_pages, chunk_count | The Model account | register_model. They fix the depth of each tree. |
lo | The Dispute account | The game. The index of the one step left. |
lo_root | The Dispute account | The game. The state root before step lo, which both sides agree on. |
hi_root | The Dispute account | The game. The root after step lo as one side claimed it. That side is hi_owner. |
input, seed | The Receipt account | request. |
Hashing rules
All hashes are SHA-256. Leaves and inner nodes carry different prefixes, so a node can never pass as a leaf:
leaf = sha256(0x00 || bytes)
node = sha256(0x01 || left || right)| Tree | Leaf i | Depth |
|---|---|---|
| Program | The 32-byte descriptor of step i. | The smallest d with 2^d at least step_count. |
| Weights | The bytes of chunk i. | The smallest d with 2^d at least chunk_count. |
| State | The 512 bytes of page i. | The smallest d with 2^d at least state_pages. |
Positions past the last leaf hold 32 zero bytes. A path lists sibling hashes from the leaf up. At each level the running hash goes on the left when the index is even and on the right when it is odd, then the index is halved.
The payload
prove_step takes one argument, payload, a byte vector. Every integer in it is little-endian.
| Order | Bytes | Field |
|---|---|---|
| 1 | 4 | step, a u32. It must equal the dispute's lo. |
| 2 | 32 | The step descriptor. |
| 3 | 1 + 32·n | The descriptor's path to program_root: a count n, then n hashes. n must equal the program tree's depth. |
| 4 | 4 + 1 + 512, or 4 + 1 + 32, per page | One entry for each page the step opens: the page index as a u32, a kind byte, then the page (kind 0, 512 bytes) or only its hash (kind 1, 32 bytes). |
| 5 | 1 + 32·n | The state multiproof: a count n, then n sibling hashes. |
| 6 | 4 + 2 + len + 1 + 32·n | Only when the step reads weights: the chunk index as a u32, the chunk length as a u16, the chunk, then its path to weights_root as a count and n hashes. n must equal the weights tree's depth. |
The payload ends there. Any byte after the last field fails the proof.
The pages a step opens
The descriptor names up to three pages: a and b, which the step reads, and c, its target. The entries in part 4 are those pages with duplicates removed, in ascending index order. There is no count in front of them: the program derives the list from the descriptor and requires each entry's index to match.
A page the step reads is sent whole, as kind 0. The target is sent as kind 1, hash only, when the step overwrites it without reading it, which is the case for load, embed and argmax. Kind 1 for a page the step reads fails the proof.
The state multiproof
The opened pages are leaves of one tree, so they share one proof. The program walks the tree level by level with the opened leaves in index order. Two opened nodes that are siblings combine with each other. Any other node combines with the next hash from the proof. The proof must hold exactly the hashes the walk consumes.
The walk is done twice over the same siblings: once with the hashes of the pages as they were, once with the target replaced by the hash of the page the step produced. The first gives the root before the step. The second gives the root after it.
The weight chunk
A matvec or norm-apply step names its chunk in the descriptor. An embed or add-row step names a base, and the chunk index is computed from what it reads in the input page (for embed the token, for add-row the token's segment), so the proven page decides which chunk must be supplied. The chunk index in the payload must equal the one the program computes.
What the program does
prove_step requires the dispute to be in the proving state. Then, in order:
- Reads
stepand requires it to equallo. - Hashes the descriptor as a leaf and requires its path to lead to
program_rootat indexlo. The step is now known to be steploof this model. - Reads each opened page and takes its hash. Each index must be below
state_pages. - Works out which chunk the step reads, hashes the supplied chunk as a leaf and requires its path to lead to
weights_root. - Executes the step with the same
laplace-vmstep function every node and browser runs, on the opened pages, the chunk, and the receipt'sinputandseed. - Runs the multiproof. The root computed from the pages as supplied must equal
lo_root. - Takes the result: the state root with the new target page, or for the model's last step the output leaf.
- Compares the result with
hi_root.
| Result | Winner |
|---|---|
Equal to hi_root | The hi_owner: its claim for this step was right. |
| Different | The other side: the hi_owner claimed a root the step does not lead to. |
The dispute records the computed root as computed_root, and the API returns it as result.step.computedRoot beside claimedRoot.
Because the pages are proven against a root both sides agreed on, the weights and the step against roots fixed at registration, and the input and seed are read from the receipt, the sender chooses nothing. A valid payload for a given dispute has one possible result.
The output leaf
The last step of every model is output. It writes no page. It reads the answer from a page and produces
sha256("laplace.output" || count as u16 || each output token as u16)That value is the last leaf of every trace. When a challenge opens, the program sets hi_root to the output leaf of the challenger's output, so a dispute that narrows to the last step is decided by the tokens the state actually holds.
Refusals
| Error | When |
|---|---|
WrongState (6010) | The dispute is not in proving: it still has more than one step, or it is resolved. |
BadStep (6023) | The payload is shorter than 4 bytes, or its step is not the dispute's lo. |
BadProof (6022) | Any other check above fails: the descriptor does not hash to program_root, a page index is wrong or out of range, a read page is sent as a hash, the pages do not hash to lo_root, the chunk is not the one the step reads or does not hash to weights_root, a path has the wrong length, the payload is short or has bytes left over, or the step cannot execute on what was supplied. |
A refused prove_step changes nothing. The dispute stays in proving and its deadline keeps running.
Who may send it
Any key may sign prove_step, and the result is the program's whoever signs. The network's keeper sends it for every game that reaches proving, within seconds, and a node that is a side of a game proves its own step as well. The signer pays the transaction fee and gains nothing by signing: the bonds move to the two sides and the protocol by the result. The first proof to land settles the dispute, and a second is refused with WrongState.
In proving the side on turn is the hi_owner, and if no valid prove_step lands before the turn's deadline, claim_timeout gives the win to the other side.
Nothing to sign. On the dispute's page the panel turns to "The last step", and the line at the top reads "One step left" with the step the keeper executes on chain. The page shows the result when it lands.
const { signature, step } = await laplace.proveStep(dispute)For a server key: the payload is built from an honest run and sent as a v1 transaction, which the signer signs over its message bytes. playTurn returns { kind: 'proving', step } at this point and sends nothing.
laplace serve and laplace watch send it unattended when a dispute they are a side of reaches one step.
Building and checking a payload
@laplace/sdk/vm builds the payload for any step of a run and executes it exactly as the program does, without a chain:
import { loadModel, toHex } from '@laplace/sdk/vm'
const model = await loadModel(program, weights)
const input = [101, 1050, 17258, 2401, 10299, 6599, 10035, 1998, 13275, 2049, 17680, 102]
const seed = 42n
const run = await model.run(input, seed)
const k = 300_000
const payload = model.prove(input, seed, k)
const result = model.verify(payload, k, run.root(k), input, seed)
console.log(model.step(k).op, payload.length)
console.log(result !== null && toHex(result.root) === toHex(run.root(k + 1)))program and weights are the bytes of the model's program.bin and weights.bin. On the market model, with the input Nvidia beats revenue estimates and raises its outlook, this prints matvec 3399 and true. verify returns null where the program fails with BadProof. The native binary does the same with laplace-vm prove <model dir> --input <ids> --seed <n> --step <k>, which prints the payload as hex.
Why a v1 transaction
A step's inputs do not fit a legacy or v0 transaction, which carries 1,232 bytes. One page is 512 bytes, a matvec step opens two and reads a weight chunk, and three Merkle proofs come with them. The largest payloads, measured over every step of a full run of each model:
| Model | Largest payload | Operator | The whole transaction |
|---|---|---|---|
judge | 3,351 bytes | matvec | 3,851 bytes |
market | 3,511 bytes | matvec | 4,011 bytes |
The whole transaction is the payload plus 500 bytes when its eleven accounts are all different keys: the message around the instruction data with its 8-byte priority fee, the data's 12-byte prefix and one signature. A v1 transaction carries 4096 bytes, so every step of both models fits in one. The market model's largest payload is step 1,318,372, the pooler reading the first position's hidden state. It is made of:
| Part | Bytes |
|---|---|
step and descriptor | 36 |
| Descriptor path, depth 21 | 673 |
| Two pages with index and kind | 1,034 |
| State multiproof, 20 siblings | 641 |
| Chunk index, length and a 544-byte chunk | 550 |
| Chunk path, depth 18 | 577 |
The SDK sends prove_step as a v1 transaction with sendV1. The message it builds:
| Bytes | Field |
|---|---|
| 1 | The version byte, 0x81. |
| 3 | The number of signers, of read-only signers and of read-only non-signers. |
| 4 | The config mask as a u32: the priority fee, the compute-unit limit and the loaded-accounts data limit are set. |
| 32 | The recent blockhash. |
| 1 + 1 | The instruction count and the account count. |
| 32 per account | The account keys, inline: the payer first, then other signers, then writable accounts, then read-only ones. |
| 8 | The priority fee as a u64: lamports for the whole compute-unit limit, the compute-unit price (Priority fees) times the limit, divided by 1,000,000 and rounded up. |
| 4 + 4 | The compute-unit limit, 1400000 by default, and the loaded-accounts data limit, 2097152 bytes. |
| 4 per instruction | The program's account index, the number of accounts, and the data length as a u16. |
| per instruction | The account indices, then the instruction data. |
| 64 per signer | The signatures, after the message. |
The payer is the only signer, a server key such as the keeper's or a node's. It signs the message bytes with signMessage, and the transaction goes to sendTransaction as base64. sendV1 refuses to build a transaction above 4096 bytes.
The instruction data is Anchor's 8-byte discriminator for prove_step, the payload length as a u32, and the payload. The accounts are the signer, Config, the Dispute, the Receipt, the Model, the vault, the fee recipient, the defender's wallet, the challenger's wallet and the defender's Operator account when the defender is an operator.
After the step
prove_step settles the dispute in the same instruction: the loser's bond is split, the dispute becomes resolved, and the receipt returns to answered with the answer that stands. How it ends describes both results.