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:

ValueWhereFixed by
program_rootThe Model accountregister_model. Commits to every step of the model.
weights_rootThe Model accountregister_model. Commits to every weight chunk.
step_count, state_pages, chunk_countThe Model accountregister_model. They fix the depth of each tree.
loThe Dispute accountThe game. The index of the one step left.
lo_rootThe Dispute accountThe game. The state root before step lo, which both sides agree on.
hi_rootThe Dispute accountThe game. The root after step lo as one side claimed it. That side is hi_owner.
input, seedThe Receipt accountrequest.

Hashing rules

All hashes are SHA-256. Leaves and inner nodes carry different prefixes, so a node can never pass as a leaf:

Text
leaf  = sha256(0x00 || bytes)
node  = sha256(0x01 || left || right)
TreeLeaf iDepth
ProgramThe 32-byte descriptor of step i.The smallest d with 2^d at least step_count.
WeightsThe bytes of chunk i.The smallest d with 2^d at least chunk_count.
StateThe 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.

OrderBytesField
14step, a u32. It must equal the dispute's lo.
232The step descriptor.
31 + 32·nThe descriptor's path to program_root: a count n, then n hashes. n must equal the program tree's depth.
44 + 1 + 512, or 4 + 1 + 32, per pageOne 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).
51 + 32·nThe state multiproof: a count n, then n sibling hashes.
64 + 2 + len + 1 + 32·nOnly 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:

  1. Reads step and requires it to equal lo.
  2. Hashes the descriptor as a leaf and requires its path to lead to program_root at index lo. The step is now known to be step lo of this model.
  3. Reads each opened page and takes its hash. Each index must be below state_pages.
  4. Works out which chunk the step reads, hashes the supplied chunk as a leaf and requires its path to lead to weights_root.
  5. Executes the step with the same laplace-vm step function every node and browser runs, on the opened pages, the chunk, and the receipt's input and seed.
  6. Runs the multiproof. The root computed from the pages as supplied must equal lo_root.
  7. Takes the result: the state root with the new target page, or for the model's last step the output leaf.
  8. Compares the result with hi_root.
ResultWinner
Equal to hi_rootThe hi_owner: its claim for this step was right.
DifferentThe 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

Text
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

ErrorWhen
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.

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:

TypeScript
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:

ModelLargest payloadOperatorThe whole transaction
judge3,351 bytesmatvec3,851 bytes
market3,511 bytesmatvec4,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:

PartBytes
step and descriptor36
Descriptor path, depth 21673
Two pages with index and kind1,034
State multiproof, 20 siblings641
Chunk index, length and a 544-byte chunk550
Chunk path, depth 18577

The SDK sends prove_step as a v1 transaction with sendV1. The message it builds:

BytesField
1The version byte, 0x81.
3The number of signers, of read-only signers and of read-only non-signers.
4The config mask as a u32: the priority fee, the compute-unit limit and the loaded-accounts data limit are set.
32The recent blockhash.
1 + 1The instruction count and the account count.
32 per accountThe account keys, inline: the payer first, then other signers, then writable accounts, then read-only ones.
8The 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 + 4The compute-unit limit, 1400000 by default, and the loaded-accounts data limit, 2097152 bytes.
4 per instructionThe program's account index, the number of accounts, and the data length as a u16.
per instructionThe account indices, then the instruction data.
64 per signerThe 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.