Models

The integer format

Weights, the step program, the state layout and their Merkle roots.

A compiled model is a folder of four files. This page gives each file's layout, the encoding of weights and steps, the layout of the state, how every root on the Model account is computed from the files, and the limits a model meets to be registered and to have any of its steps proven in one transaction.

The files

FileHolds
program.binThe header, the step list and the page names.
weights.binThe weight chunks with their index.
vocab.txtThe tokenizer: the uncased WordPiece vocabulary, one piece per line, each piece's token id its line counted from 0. Both models on the network use the same file. The step function never reads it.
manifest.jsonThe model's description, its counts, its three roots and the SHA-256 of the other three files.

The store serves each file by its SHA-256. The manifest's own SHA-256 is the files_hash on the Model account, so the chain vouches for the manifest and the manifest vouches for the rest.

manifest.json

slugstringrequired
The model's slug, the seed of its Model account.
namestringrequired
The display name.
task'judge' | 'market'required
What kind of input the model reads: a claim and its evidence, or one text.
summarystringrequired
One line on what the model answers.
archnumberrequired
0 for the judge, 1 for the market model. Both are compiled from the BERT layout. The same byte is in program.bin.
weightsobjectrequired
source, licence and url of the open weights the model was compiled from.
parametersnumberrequired
The parameter count of the source weights.
sizeBytesnumberrequired
The size of weights.bin.
stepCountnumberrequired
Steps in a run.
statePagesnumberrequired
Pages in the state.
chunkCountnumberrequired
Weight chunks.
inputMaxnumberrequired
The most input tokens a request may carry.
outputLennumberrequired
The exact number of output tokens.
labelsstring[] | nullrequired
The label of each output token id, in order.
rootsobjectrequired
program, weights and init: the three roots as 64 lowercase hex characters.
filesobjectrequired
program, weights and tokenizer, each with hash (SHA-256, hex) and bytes.

The file is JSON with two-space indentation and a trailing newline. Its bytes are hashed as written, so reformatting it changes files_hash.

weights.bin

All integers are little-endian.

OffsetBytesField
08The magic LPLCWGT1.
84count, the number of chunks, as a u32.
124 × (count + 1)Offsets as u32. Chunk i spans offset i to offset i + 1, counted from the start of the chunk data. The first offset is 0.
12 + 4 × (count + 1)the restThe chunks, back to back.

A chunk is the unit a step reads and the unit weights_root commits to. There are three layouts:

Read byLayout
embed, add-rowOne i32 scale, then one i8 per word. The word's value in Q16 is (i8 * scale) >> 8.
matvecFor r rows of n columns: r scales as i32, then r biases as i32 in Q16 when the step's BIAS flag is set, then r × n weights as i8, row by row.
norm-applyThe gain exponent as i32, the bias exponent as i32, n gains as i16, n biases as i16.

A scale is in units of 2^-24, so a weight's real value is i8 * scale / 2^24. An i16 value with exponent shift is v / 2^shift.

Chunking

A matrix is cut so that no step reads more than a transaction carries. Its input is taken one page at a time, 128 columns per page, and its rows are grouped so that a matvec step reads at most 512 weight bytes: 4 rows of 128 columns. A group never crosses from one output page into the next. The bias travels with the slice that covers the first input page.

Chunks with identical bytes are stored once, so a matrix applied at every token position is one set of chunks. Embedding rows are addressed by position from a base index and are never shared: row t of a table whose vectors span p pages is the p chunks starting at base + t × p. There are two such tables, the word embeddings by token id, and the position and segment embeddings summed into one row per pair.

program.bin

OffsetBytesField
08The magic LPLCPRG1.
81arch.
92input_max as a u16.
112output_len as a u16.
134pages, the number of state pages, as a u32.
174steps, the step count, as a u32.
2132 × stepsThe step descriptors, in run order.
21 + 32 × stepsthe restOne name per page: its length as a u16, then UTF-8 bytes.

The page names (input, token 0 · hidden · 1, norm stats, answer) are for people. They are not part of any root.

The step descriptor

Each step is 32 bytes. The descriptor is the leaf program_root commits to and the first thing in a prove_step payload.

OffsetBytesFieldMeaning
01opThe operator code.
11flagsThe value 1 is BIAS: the chunk carries one bias per row. The value 2 is OVERWRITE: the step writes its result instead of adding it to the target. A step with both holds 3.
22rFor matvec, the number of rows.
44aThe first page the step reads.
84bThe second page the step reads.
124cThe target page.
164wThe weight chunk, or the base index of a table.
2012pSix u16 parameters, p0 to p5, whose meaning depends on the operator.

A page or chunk field that is unused holds 0xFFFFFFFF.

What each operator takes from the descriptor:

CodeNamePagesChunk and parameters
0loadc the input pageNone.
1embeda the input page, c the targetw the table base, p0 the token position, p1 the page within the vector, p2 pages per vector, p3 words written. The chunk is w + token × p2 + p1.
2add-rowa the input page, c the targetAs embed. The chunk is w + (p0 × 2 + segment) × p2 + p1.
3matveca the input, c the targetw the chunk, r rows, p0 the first target word, p1 the columns read from a, flags.
4norm-statsa and optionally b the pages measured, c the stats pagep0 the slot: the mean goes to word 2 × p0, the inverse deviation to the next. p1 words per page.
5norm-applya the stats page, c the targetw the chunk, p0 the slot, p1 words.
6norm-suma the page measured, c the stats pagep0 the token: its four words start at 4 × p0 and hold the sum, 0, and the sum of squares as low and high 32 bits. p1 words. OVERWRITE on the vector's first page.
7activationc the targetp0 the function (0 GELU, otherwise tanh), p1 the first word, p2 the count.
8norm-statsc the stats pagep0 the token, as norm-sum: the mean goes to word 4 × p0, the inverse deviation to the next, which norm-apply reads as slot 2 × p0. p1 the vector's width in words.
9residuala the addend, c the targetp1 the first word, p2 the count.
11scoresa a query page, b a key page, c the scores pagep0 the key's token: the score lands in word p0 of each head's row. p2 heads per page (0 for 2), p3 keys per row (0 for 64), p4 the scale in Q16 (0 for 1/8, a shift by 3).
13softmaxa the input page, c the scores pagep2 and p3 as scores. The valid length is the input's length, at most p3.
14weighted-suma the scores page, b a value page, c the targetp0 the value's token, p2 and p3 as scores, flags.
16argmaxa the logits, c the targetp1 the number of words compared.
19outputa the page holding the answerNone. It answers word 0 of a as one token.

The judge's attention steps hold 0 in p2, p3 and p4: two heads of 64 dimensions per page, 64 keys, scaled by 1/8. The market model's hold 4, 32 and 11585. load, embed and argmax overwrite the target without reading it. Every other operator reads the target's old contents. Deterministic inference says what each operator computes.

The state

The state is pages pages. A page is 128 words, each an i32 in Q16, stored and hashed as 512 little-endian bytes. Every page is zero before step 0.

A vector wider than 128 words spans consecutive pages: a 256-wide hidden vector is two pages, a 384-wide one three, a 1,536-wide one twelve. Which page holds what is the model's layout, fixed by its compiler and visible in the page names.

The input page is the one load writes:

WordsContent
0The number of input tokens.
1 to 64The tokens. A model reads as many positions as its input_max.
126The low 32 bits of the seed.
127The high 32 bits of the seed.

The BERT layout

Each token position has its own pages, and a few pages serve the whole run:

PagesPerHolds
hiddenPosition, one hidden vectorThe running hidden state.
query, key, valuePosition, one hidden vector eachThe attention projections.
scoresPosition, one hidden vectorThe attention scores, one row of keys per head.
attentionPosition, one hidden vectorThe weighted sum of values.
sublayer outPosition, one hidden vectorThe attention output and the feed-forward output before each residual.
ffnPosition, one intermediate vectorThe feed-forward block.
inputRunThe input page.
norm statsRunThe mean and inverse deviation of every position's norm.
pooledRun, one hidden vectorThe pooler on the first position.
logitsRunThe three class logits.
answerRunThe class argmax chose, in word 0.
judgemarket
Positions6432
Pages per hidden vector23
Pages per intermediate vector812
Pages per position2233
Pages for the run67
State pages1,4141,063

How each root is computed

Every tree is a binary Merkle tree with SHA-256:

Text
leaf  = sha256(0x00 || bytes)
node  = sha256(0x01 || left || right)

The tree's depth is the smallest d with 2^d at least the number of leaves, and positions past the last leaf hold 32 zero bytes.

RootLeavesRecorded
program_rootOne per step: the leaf hash of its 32-byte descriptor.On the Model account.
weights_rootOne per chunk: the leaf hash of its bytes.On the Model account.
init_rootOne per page: the leaf hash of 512 zero bytes.On the Model account. It is the state root before step 0.
State rootOne per page: the leaf hash of the page's 512 bytes.Committed by each side in the game.
Trace rootThe roots of a run in order, used as they are: the init_root, the state root after each step but the last, then the output leaf. step_count + 1 leaves.On the receipt.
files_hashNot a tree: the SHA-256 of manifest.json.On the Model account.

The output leaf is sha256("laplace.output" || count as u16 || each output token as u16).

@laplace/sdk/vm computes the three model roots from the two binary files: loadModel(program, weights) returns a model with programRoot, weightsRoot, initRoot and stepCount.

Limits

register_model accepts a model when all of these hold, and fails with InvalidModel (6002) otherwise:

FieldRequirement
slug1 to 24 bytes, each a lowercase letter, a digit or -.
step_count, state_pages, chunk_countAbove zero. Each is a u32.
input_max1 to 64.
output_len1 to 64.
window_secsAbove zero. A u32.
bond_lamportsAbove zero. A u64.

The 64-token bounds are the size of the input page and of the input and output fields of a receipt.

For any step of the model to be proven in one transaction, the format bounds what a step touches:

BoundValue
Pages a step opensAt most 3, each 512 bytes.
Chunks a step readsAt most 1. Its length is a u16 in the payload.
Hashes in one path or multiproofA u8 count, so at most 255.
Weight bytes in one matvec step, as the compiler cuts them512.
The whole prove_step transaction4096 bytes. The SDK refuses to build a larger one.

One step on chain gives the largest payload each model on the network produces.