Reference

Program accounts

Every account of the laplace program: seeds, fields, types and sizes.

The laplace program keeps its state in seven account types and one token account per fee mint. This page gives each one's address, its fields in the order they are stored, and its size, so an account can be found, filtered and decoded from any client.

AccountSeedsHolds
Config["config"]admin, fee_recipient, protocol_share_bps (u16, of each finalized fee), slash_winner_bps (u16, of a lost bond to the winner), answer_deadline_secs, turn_deadline_secs, withdraw_cooldown_secs, bump, vault_bump, escrow_bump, registration_open (false: only the admin registers models)
Vault["vault"]no fields: its lamports above rent are every bond, in SOL (operators' free and locked, and challengers')
Model["model", slug]publisher, slug (24 bytes), slug_len, arch (0 the judge, 1 the market model), weights_root, program_root, init_root, step_count, state_pages, chunk_count, input_max, output_len, window_secs, bond_lamports, files_hash (sha256 of the model's manifest), registered_at, bump
Operator["operator", authority]authority, bond_free, bond_locked, withdraw_amount, withdraw_at, answered, disputes_won, disputes_lost, last_answer_at, registered_at, bump
Offer["offer", operator_authority, model]operator, model, mint, price, active, updated_at, bump
Receipt["receipt", requester, nonce u64 le]model, operator, requester, nonce, seed, mint, fee, input_len, input (64 u16), output_len, output (64 u16), trace_root, answerer, answerer_is_operator, bond, state, requested_at, answer_deadline, answered_at, window_ends_at, window_remaining, dispute, disputes, finalized_at, bump
Dispute["dispute", receipt, index u16 le]receipt, index, defender, defender_is_operator, challenger, defender_output_len, defender_output, defender_trace, challenger_output_len, challenger_output, challenger_trace, bond, lo, hi, lo_root, hi_root, hi_owner, points_len, points (7), turn, deadline, turns, state, winner, resolved_by (0 step, 1 timeout), computed_root, opened_at, resolved_at, bump
fee escrow["escrow"], plus its associated token account per mintfees between request and finalize / cancel_request

Layout

Every account is an Anchor account: an 8-byte discriminator, then the fields in the order listed, Borsh-encoded. Integers are little-endian, a Pubkey is 32 bytes, a bool is one byte, an enum is one byte holding its variant's number, and a fixed array is its elements with no length prefix. Sizes below include the discriminator. Times are Clock.unix_timestamp seconds as i64. The offset column counts from the first byte of the account, for memcmp filters.

All addresses are program-derived under the program id on Addresses. A seed written as a quoted word is its ASCII bytes.

AccountDiscriminator (bytes)Size (bytes)Rent paid by
Config155, 12, 170, 224, 30, 250, 204, 130104the admin, in init_config
Vault211, 8, 232, 43, 2, 152, 117, 1198the admin, in init_config
Model152, 221, 247, 122, 185, 125, 223, 151231the publisher, in register_model
Operator219, 31, 188, 145, 69, 139, 204, 117105the operator, in register_operator
Offer215, 88, 60, 71, 170, 162, 73, 229122the operator, in the first set_offer
Receipt39, 154, 73, 106, 80, 102, 145, 153575the requester, in request
Dispute36, 49, 241, 67, 40, 36, 241, 74798the challenger, in challenge

Three constants size the arrays: MAX_TOKENS = 64, MAX_POINTS = 7, SLUG_MAX = 24.

Config

The values every other instruction reads. One per program, created by init_config and changed by set_config.

Seeds: ["config"].

OffsetFieldTypeMeaning
8adminPubkeyThe key that can send set_config, and the one key that registers models while registration is closed.
40fee_recipientPubkeyThe wallet that receives the protocol's share of each finalized fee and its part of each lost bond.
72protocol_share_bpsu16Basis points of each finalized fee that go to fee_recipient. At most 10,000.
74slash_winner_bpsu16Basis points of a lost bond that go to the winner. The rest goes to fee_recipient. At most 10,000.
76answer_deadline_secsi64Seconds an operator has to answer a request. Above 0.
84turn_deadline_secsi64Seconds a side has for each turn of a game. Above 0.
92withdraw_cooldown_secsi64Seconds between request_withdraw and withdraw_bond. 0 or more.
100bumpu8Bump of this account.
101vault_bumpu8Bump of the vault.
102escrow_bumpu8Bump of the fee escrow authority.
103registration_openboolfalse: only admin sends register_model. true: any key does. false from init_config until set_config opens it.

Vault

The account that holds every bond in SOL: operators' free and locked bond and challengers' bonds. It has no fields. Its lamport balance is its own rent plus every bond in the program.

Seeds: ["vault"].

Bonds enter by a System Program transfer in deposit_bond and challenge. They leave when the program moves lamports out in withdraw_bond, finalize, prove_step and claim_timeout. Which part of the balance belongs to whom is recorded on the Operator, Receipt and Dispute accounts.

Model

A registered model. Created by register_model and never written again.

Seeds: ["model", slug], where slug is the slug's bytes: 1 to 24 characters of a to z, 0 to 9 and -.

OffsetFieldTypeMeaning
8publisherPubkeyThe key that registered the model.
40slug[u8; 24]The slug's bytes, zero-padded.
64slug_lenu8How many bytes of slug are used.
65archu8The architecture number from the model's manifest: 0 for judge, 1 for market.
66weights_root[u8; 32]Merkle root of the weight chunks.
98program_root[u8; 32]Merkle root of the step descriptors.
130init_root[u8; 32]The state root before step 0.
162step_countu32Steps in one run.
166state_pagesu32Pages in the model's state.
170chunk_countu32Weight chunks.
174input_maxu16Most input tokens a request can carry. 1 to 64.
176output_lenu16Exact number of output tokens in an answer. 1 to 64.
178window_secsu32The window, in seconds.
182bond_lamportsu64The bond behind each answer, in lamports.
190files_hash[u8; 32]SHA-256 of the model's manifest file.
222registered_ati64When it was registered.
230bumpu8Bump of this account.

Operator

One per operator key. Created by register_operator.

Seeds: ["operator", authority], with authority as its 32 bytes.

OffsetFieldTypeMeaning
8authorityPubkeyThe operator's key. It signs every operator instruction.
40bond_freeu64Lamports deposited and not behind any answer.
48bond_lockedu64Lamports behind answers whose receipts are not final.
56withdraw_amountu64Lamports marked by request_withdraw. 0 when nothing is requested.
64withdraw_ati64When the marked amount can be withdrawn. 0 when nothing is requested.
72answeredu64Answers posted.
80disputes_wonu32Disputes this operator won as defender, counted when its Operator account is passed to the settling instruction.
84disputes_lostu32Disputes this operator lost as defender.
88last_answer_ati64When it last answered. 0 before the first answer.
96registered_ati64When it registered.
104bumpu8Bump of this account.

Offer

One operator's price for one model. Created and changed by set_offer.

Seeds: ["offer", authority, model]: the operator's key, then the address of the Model account, 32 bytes each.

OffsetFieldTypeMeaning
8operatorPubkeyThe operator's key (its authority), not the Operator account.
40modelPubkeyThe Model account.
72mintPubkeyThe SPL Token mint the price is charged in.
104priceu64The fee per request, in the mint's base units.
112activeboolWhether request accepts this offer.
113updated_ati64When set_offer last ran.
121bumpu8Bump of this account.

Receipt

One request and its answer. Created by request. Receipts describes what it is for.

Seeds: ["receipt", requester, nonce]: the requester's 32 bytes, then nonce as a u64 in 8 little-endian bytes.

OffsetFieldTypeMeaning
8modelPubkeyThe Model account the request names.
40operatorPubkeyThe key of the operator the request names, taken from the offer.
72requesterPubkeyThe key that sent the request.
104nonceu64The requester's nonce.
112seedu64The requester's seed. The first step of a run writes it into the input page, so it enters the state roots and the trace root. No step reads it, so the output does not depend on it.
120mintPubkeyThe fee's mint, from the offer.
152feeu64The fee in escrow, the offer's price when the request landed.
160input_lenu8Input tokens used.
161input[u16; 64]Input token ids. The first input_len are the input, the rest are 0.
289output_lenu8Output tokens used. 0 before an answer.
290output[u16; 64]Output token ids. The first output_len are the answer.
418trace_root[u8; 32]The trace root of the standing answer. Zero before an answer.
450answererPubkeyThe key whose bond stands behind the answer. The zero key before an answer.
482answerer_is_operatorbooltrue while the named operator's answer stands, false once a challenger's answer has replaced it.
483bondu64Lamports locked behind the answer.
491stateReceiptStateSee the table below.
492requested_ati64When the request landed.
500answer_deadlinei64The last second the operator can answer.
508answered_ati64When the standing answer was posted.
516window_ends_ati64When the window closes. Not updated while the receipt is challenged.
524window_remainingi64Seconds of window left when a challenge paused it. 0 outside a challenge.
532disputePubkeyThe open Dispute. The zero key when none is open.
564disputesu16Challenges opened against this receipt. The next dispute's index.
566finalized_ati64When the receipt became final or void. 0 before.
574bumpu8Bump of this account.

ReceiptState

ValueVariantWritten as
0Requestedrequested
1Answeredanswered
2Challengedchallenged
3Finalfinal
4Voidvoid

A memcmp on offset 491 selects receipts by state.

Dispute

One challenge to one receipt. Created by challenge. The challenge game describes how its fields move.

Seeds: ["dispute", receipt, index]: the receipt's 32 bytes, then index as a u16 in 2 little-endian bytes. index is the receipt's disputes count when the challenge is sent.

OffsetFieldTypeMeaning
8receiptPubkeyThe receipt in dispute.
40indexu16Which challenge of that receipt this is, from 0.
42defenderPubkeyThe receipt's answerer when the challenge opened.
74defender_is_operatorboolWhether the defender's bond is an operator's locked bond.
75challengerPubkeyThe key that opened the challenge.
107defender_output_lenu8Tokens used in defender_output.
108defender_output[u16; 64]The answer that stood when the challenge opened.
236defender_trace[u8; 32]Its trace root.
268challenger_output_lenu8Tokens used in challenger_output.
269challenger_output[u16; 64]The challenger's output.
397challenger_trace[u8; 32]The challenger's trace root.
429bondu64Each side's bond in lamports: the model's bond.
437lou32Start of the disputed interval. Both sides agree on the root here.
441hiu32End of the disputed interval. The sides disagree on the root here.
445lo_root[u8; 32]The agreed root at lo. Starts as the model's init_root.
477hi_root[u8; 32]The root one side claims at hi. Starts as the output leaf of the challenger's output.
509hi_owneru8The side that claims hi_root. A side number, below.
510points_lenu8Points stored, 0 to 7.
511points[[u8; 32]; 7]The points waiting for the side on turn: the other side's roots inside [lo, hi].
735turnu8The side to move. A side number.
736deadlinei64The last second the side on turn can move.
744turnsu16Turns taken. The challenge is turn 1.
746stateDisputeStateSee the table below.
747winneru8The side that won. A side number, set when state is Resolved.
748resolved_byu80 a proven step, 1 a timeout. Set when resolved.
749computed_root[u8; 32]The root the program computed in prove_step. Zero for a timeout.
781opened_ati64When the challenge opened.
789resolved_ati64When it resolved. 0 before.
797bumpu8Bump of this account.

DisputeState

ValueVariantWritten as
0Openopen
1Provingproving
2Resolvedresolved

Side

hi_owner, turn and winner hold a side as a u8.

ValueConstantSide
0DEFENDERThe defender.
1CHALLENGERThe challenger.

The fee escrow

Fees wait in token accounts owned by one program-derived authority.

AddressDerivationHolds
Escrow authoritySeeds ["escrow"].Nothing. It has no data and signs the transfers out of its token accounts.
Escrow token account, per mintThe associated token account of the escrow authority for the mint, under the SPL Token program.Every fee in that mint between request and finalize or cancel_request.

The first request that uses a mint creates that mint's escrow token account, and the requester pays its rent.

Decoding in TypeScript

decode in @laplace/sdk turns account data into typed objects, and accountKind names an account by its discriminator.

TypeScript
import { createLaplace, decode, accountKind, pda } from '@laplace/sdk'

const laplace = createLaplace({ rpcUrl, apiUrl })
const info = await laplace.connection.getAccountInfo(pda.config())

accountKind(info!.data)                  // 'Config'
const config = decode.config(info!.data) // { admin, feeRecipient, protocolShareBps, ... }
CallReturns
decode.config(data)ConfigAccount
decode.model(data)ModelAccount, with slug as a string
decode.operator(data)OperatorAccount
decode.offer(data)OfferAccount
decode.receipt(data)ReceiptAccount, with input and output cut to their lengths, state as its written name, and dispute as null when none is open
decode.dispute(data)DisputeAccount, with sides as 'defender' or 'challenger', resolvedBy as 'step' or 'timeout', and points cut to points_len
accountKind(data)'Config', 'Vault', 'Model', 'Operator', 'Offer', 'Receipt', 'Dispute' or null