Concepts

Receipts

What a receipt holds and the states it moves through.

A receipt is one account of the laplace program on Solana. It records a request to a model and, once the operator answers, the output, the trace root and the bond behind them. Everything else on the network is done to a receipt: it is asked for, answered, run again, challenged, finalized and read.

Address

A receipt is a program-derived account with the seeds ["receipt", requester, nonce], where nonce is a u64 in little-endian bytes chosen by the requester. The address is known before the request lands, so a caller can hand it to another program or follow it at once.

What it holds

FieldMeaning
modelThe model account the request names.
operatorThe operator the request names. Only this operator can answer.
requesterThe key that sent the request and paid the fee.
nonceThe requester's nonce, part of the address.
seedA u64 the requester chooses. The run loads it into the model's state with the input, so it is part of every state root.
inputThe input as token ids, at most 64 u16 values and at most the model's input_max.
mint, feeThe mint and amount taken from the requester into the fee escrow, from the operator's offer.
outputThe answer as token ids, exactly the model's output_len values. Empty until answered.
trace_rootThe Merkle root over the run's roots: the model's init_root, then the root after each step. The last step's root is the hash of the output.
answererThe key whose bond stands behind the output.
answerer_is_operatortrue while the named operator's answer stands, false once a challenger's answer has replaced it.
bondLamports locked behind the answer. 0 before it.
stateOne of the five states below.
requested_at, answer_deadlineWhen the request landed and the last moment the operator can answer.
answered_at, window_ends_atWhen the standing answer was posted and when its window closes.
window_remainingSet while challenged: the seconds of window that resume if the challenger loses.
finalized_atWhen the receipt became final or void.
disputeThe open dispute, if there is one.
disputesHow many challenges this receipt has seen.

All times are Clock.unix_timestamp seconds on chain. The API returns them as ISO-8601 UTC strings.

The input hash that programs and the SDK use to identify what was asked is the SHA-256 of the input tokens, each written as a u16 in little-endian bytes.

States

StateMeaningEntered by
requestedThe fee is in escrow and the operator has until answer_deadline to answer.request
answeredAn output and trace root are posted with a bond. The window is open.answer, or the end of a dispute
challengedA rival output and trace root are posted with a bond. The window is paused and the game is in play.challenge
finalThe window closed with no dispute open. The fee is paid and the bond is unlocked.finalize
voidNo answer arrived before the deadline. The fee went back to the requester.cancel_request
requestedansweransweredfinalizefinal
requestedcancel_requestvoid
answeredchallengechallengedprove_step · claim_timeoutanswered
The five states of a receipt and the instruction behind each move.

A receipt can be challenged more than once. Each dispute ends with the receipt back in answered: with the same answer and the rest of its window if the challenger lost, or with the challenger's answer, the challenger's bond and a fresh window if the defender lost. final and void are terminal.

The trace root

The operator does not post only the output. It posts the trace root: a commitment to the model's whole state after each of its steps. Two runs of the same model on the same input and seed give the same trace root, bit for bit. A run that differs anywhere gives a different one, and the two roots are what the challenge game narrows to one step.

Reading a receipt

FromWithReturns
The app/receipts/[address]The receipt, its transactions and Run it again.
HTTPGET /v1/receipts/:addressReceiptDetail: the receipt with decoded text, its transactions and its past disputes.
TypeScriptlaplace.receipt(address)The receipt decoded from the account.
TypeScriptlaplace.final(address){ model, inputHash, output }, resolved once the state is final.
CLIlaplace receipt <address>The receipt, printed.
A Solana programlaplace_receipt::read(&account)model, input_hash and output, only when the state is final.

A program that acts on a model's answer reads it through laplace_receipt::read, which refuses every state but final.