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.
| Account | Seeds | Holds |
|---|---|---|
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 mint | fees 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.
| Account | Discriminator (bytes) | Size (bytes) | Rent paid by |
|---|---|---|---|
Config | 155, 12, 170, 224, 30, 250, 204, 130 | 104 | the admin, in init_config |
Vault | 211, 8, 232, 43, 2, 152, 117, 119 | 8 | the admin, in init_config |
Model | 152, 221, 247, 122, 185, 125, 223, 151 | 231 | the publisher, in register_model |
Operator | 219, 31, 188, 145, 69, 139, 204, 117 | 105 | the operator, in register_operator |
Offer | 215, 88, 60, 71, 170, 162, 73, 229 | 122 | the operator, in the first set_offer |
Receipt | 39, 154, 73, 106, 80, 102, 145, 153 | 575 | the requester, in request |
Dispute | 36, 49, 241, 67, 40, 36, 241, 74 | 798 | the 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"].
| Offset | Field | Type | Meaning |
|---|---|---|---|
| 8 | admin | Pubkey | The key that can send set_config, and the one key that registers models while registration is closed. |
| 40 | fee_recipient | Pubkey | The wallet that receives the protocol's share of each finalized fee and its part of each lost bond. |
| 72 | protocol_share_bps | u16 | Basis points of each finalized fee that go to fee_recipient. At most 10,000. |
| 74 | slash_winner_bps | u16 | Basis points of a lost bond that go to the winner. The rest goes to fee_recipient. At most 10,000. |
| 76 | answer_deadline_secs | i64 | Seconds an operator has to answer a request. Above 0. |
| 84 | turn_deadline_secs | i64 | Seconds a side has for each turn of a game. Above 0. |
| 92 | withdraw_cooldown_secs | i64 | Seconds between request_withdraw and withdraw_bond. 0 or more. |
| 100 | bump | u8 | Bump of this account. |
| 101 | vault_bump | u8 | Bump of the vault. |
| 102 | escrow_bump | u8 | Bump of the fee escrow authority. |
| 103 | registration_open | bool | false: 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 -.
| Offset | Field | Type | Meaning |
|---|---|---|---|
| 8 | publisher | Pubkey | The key that registered the model. |
| 40 | slug | [u8; 24] | The slug's bytes, zero-padded. |
| 64 | slug_len | u8 | How many bytes of slug are used. |
| 65 | arch | u8 | The architecture number from the model's manifest: 0 for judge, 1 for market. |
| 66 | weights_root | [u8; 32] | Merkle root of the weight chunks. |
| 98 | program_root | [u8; 32] | Merkle root of the step descriptors. |
| 130 | init_root | [u8; 32] | The state root before step 0. |
| 162 | step_count | u32 | Steps in one run. |
| 166 | state_pages | u32 | Pages in the model's state. |
| 170 | chunk_count | u32 | Weight chunks. |
| 174 | input_max | u16 | Most input tokens a request can carry. 1 to 64. |
| 176 | output_len | u16 | Exact number of output tokens in an answer. 1 to 64. |
| 178 | window_secs | u32 | The window, in seconds. |
| 182 | bond_lamports | u64 | The bond behind each answer, in lamports. |
| 190 | files_hash | [u8; 32] | SHA-256 of the model's manifest file. |
| 222 | registered_at | i64 | When it was registered. |
| 230 | bump | u8 | Bump of this account. |
Operator
One per operator key. Created by register_operator.
Seeds: ["operator", authority], with authority as its 32 bytes.
| Offset | Field | Type | Meaning |
|---|---|---|---|
| 8 | authority | Pubkey | The operator's key. It signs every operator instruction. |
| 40 | bond_free | u64 | Lamports deposited and not behind any answer. |
| 48 | bond_locked | u64 | Lamports behind answers whose receipts are not final. |
| 56 | withdraw_amount | u64 | Lamports marked by request_withdraw. 0 when nothing is requested. |
| 64 | withdraw_at | i64 | When the marked amount can be withdrawn. 0 when nothing is requested. |
| 72 | answered | u64 | Answers posted. |
| 80 | disputes_won | u32 | Disputes this operator won as defender, counted when its Operator account is passed to the settling instruction. |
| 84 | disputes_lost | u32 | Disputes this operator lost as defender. |
| 88 | last_answer_at | i64 | When it last answered. 0 before the first answer. |
| 96 | registered_at | i64 | When it registered. |
| 104 | bump | u8 | Bump 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.
| Offset | Field | Type | Meaning |
|---|---|---|---|
| 8 | operator | Pubkey | The operator's key (its authority), not the Operator account. |
| 40 | model | Pubkey | The Model account. |
| 72 | mint | Pubkey | The SPL Token mint the price is charged in. |
| 104 | price | u64 | The fee per request, in the mint's base units. |
| 112 | active | bool | Whether request accepts this offer. |
| 113 | updated_at | i64 | When set_offer last ran. |
| 121 | bump | u8 | Bump 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.
| Offset | Field | Type | Meaning |
|---|---|---|---|
| 8 | model | Pubkey | The Model account the request names. |
| 40 | operator | Pubkey | The key of the operator the request names, taken from the offer. |
| 72 | requester | Pubkey | The key that sent the request. |
| 104 | nonce | u64 | The requester's nonce. |
| 112 | seed | u64 | The 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. |
| 120 | mint | Pubkey | The fee's mint, from the offer. |
| 152 | fee | u64 | The fee in escrow, the offer's price when the request landed. |
| 160 | input_len | u8 | Input tokens used. |
| 161 | input | [u16; 64] | Input token ids. The first input_len are the input, the rest are 0. |
| 289 | output_len | u8 | Output tokens used. 0 before an answer. |
| 290 | output | [u16; 64] | Output token ids. The first output_len are the answer. |
| 418 | trace_root | [u8; 32] | The trace root of the standing answer. Zero before an answer. |
| 450 | answerer | Pubkey | The key whose bond stands behind the answer. The zero key before an answer. |
| 482 | answerer_is_operator | bool | true while the named operator's answer stands, false once a challenger's answer has replaced it. |
| 483 | bond | u64 | Lamports locked behind the answer. |
| 491 | state | ReceiptState | See the table below. |
| 492 | requested_at | i64 | When the request landed. |
| 500 | answer_deadline | i64 | The last second the operator can answer. |
| 508 | answered_at | i64 | When the standing answer was posted. |
| 516 | window_ends_at | i64 | When the window closes. Not updated while the receipt is challenged. |
| 524 | window_remaining | i64 | Seconds of window left when a challenge paused it. 0 outside a challenge. |
| 532 | dispute | Pubkey | The open Dispute. The zero key when none is open. |
| 564 | disputes | u16 | Challenges opened against this receipt. The next dispute's index. |
| 566 | finalized_at | i64 | When the receipt became final or void. 0 before. |
| 574 | bump | u8 | Bump of this account. |
ReceiptState
| Value | Variant | Written as |
|---|---|---|
| 0 | Requested | requested |
| 1 | Answered | answered |
| 2 | Challenged | challenged |
| 3 | Final | final |
| 4 | Void | void |
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.
| Offset | Field | Type | Meaning |
|---|---|---|---|
| 8 | receipt | Pubkey | The receipt in dispute. |
| 40 | index | u16 | Which challenge of that receipt this is, from 0. |
| 42 | defender | Pubkey | The receipt's answerer when the challenge opened. |
| 74 | defender_is_operator | bool | Whether the defender's bond is an operator's locked bond. |
| 75 | challenger | Pubkey | The key that opened the challenge. |
| 107 | defender_output_len | u8 | Tokens used in defender_output. |
| 108 | defender_output | [u16; 64] | The answer that stood when the challenge opened. |
| 236 | defender_trace | [u8; 32] | Its trace root. |
| 268 | challenger_output_len | u8 | Tokens used in challenger_output. |
| 269 | challenger_output | [u16; 64] | The challenger's output. |
| 397 | challenger_trace | [u8; 32] | The challenger's trace root. |
| 429 | bond | u64 | Each side's bond in lamports: the model's bond. |
| 437 | lo | u32 | Start of the disputed interval. Both sides agree on the root here. |
| 441 | hi | u32 | End of the disputed interval. The sides disagree on the root here. |
| 445 | lo_root | [u8; 32] | The agreed root at lo. Starts as the model's init_root. |
| 477 | hi_root | [u8; 32] | The root one side claims at hi. Starts as the output leaf of the challenger's output. |
| 509 | hi_owner | u8 | The side that claims hi_root. A side number, below. |
| 510 | points_len | u8 | Points stored, 0 to 7. |
| 511 | points | [[u8; 32]; 7] | The points waiting for the side on turn: the other side's roots inside [lo, hi]. |
| 735 | turn | u8 | The side to move. A side number. |
| 736 | deadline | i64 | The last second the side on turn can move. |
| 744 | turns | u16 | Turns taken. The challenge is turn 1. |
| 746 | state | DisputeState | See the table below. |
| 747 | winner | u8 | The side that won. A side number, set when state is Resolved. |
| 748 | resolved_by | u8 | 0 a proven step, 1 a timeout. Set when resolved. |
| 749 | computed_root | [u8; 32] | The root the program computed in prove_step. Zero for a timeout. |
| 781 | opened_at | i64 | When the challenge opened. |
| 789 | resolved_at | i64 | When it resolved. 0 before. |
| 797 | bump | u8 | Bump of this account. |
DisputeState
| Value | Variant | Written as |
|---|---|---|
| 0 | Open | open |
| 1 | Proving | proving |
| 2 | Resolved | resolved |
Side
hi_owner, turn and winner hold a side as a u8.
| Value | Constant | Side |
|---|---|---|
| 0 | DEFENDER | The defender. |
| 1 | CHALLENGER | The challenger. |
The fee escrow
Fees wait in token accounts owned by one program-derived authority.
| Address | Derivation | Holds |
|---|---|---|
| Escrow authority | Seeds ["escrow"]. | Nothing. It has no data and signs the transfers out of its token accounts. |
| Escrow token account, per mint | The 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.
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, ... }| Call | Returns |
|---|---|
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 |