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
| Field | Meaning |
|---|---|
model | The model account the request names. |
operator | The operator the request names. Only this operator can answer. |
requester | The key that sent the request and paid the fee. |
nonce | The requester's nonce, part of the address. |
seed | A u64 the requester chooses. The run loads it into the model's state with the input, so it is part of every state root. |
input | The input as token ids, at most 64 u16 values and at most the model's input_max. |
mint, fee | The mint and amount taken from the requester into the fee escrow, from the operator's offer. |
output | The answer as token ids, exactly the model's output_len values. Empty until answered. |
trace_root | The 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. |
answerer | The key whose bond stands behind the output. |
answerer_is_operator | true while the named operator's answer stands, false once a challenger's answer has replaced it. |
bond | Lamports locked behind the answer. 0 before it. |
state | One of the five states below. |
requested_at, answer_deadline | When the request landed and the last moment the operator can answer. |
answered_at, window_ends_at | When the standing answer was posted and when its window closes. |
window_remaining | Set while challenged: the seconds of window that resume if the challenger loses. |
finalized_at | When the receipt became final or void. |
dispute | The open dispute, if there is one. |
disputes | How 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
| State | Meaning | Entered by |
|---|---|---|
requested | The fee is in escrow and the operator has until answer_deadline to answer. | request |
answered | An output and trace root are posted with a bond. The window is open. | answer, or the end of a dispute |
challenged | A rival output and trace root are posted with a bond. The window is paused and the game is in play. | challenge |
final | The window closed with no dispute open. The fee is paid and the bond is unlocked. | finalize |
void | No answer arrived before the deadline. The fee went back to the requester. | cancel_request |
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
| From | With | Returns |
|---|---|---|
| The app | /receipts/[address] | The receipt, its transactions and Run it again. |
| HTTP | GET /v1/receipts/:address | ReceiptDetail: the receipt with decoded text, its transactions and its past disputes. |
| TypeScript | laplace.receipt(address) | The receipt decoded from the account. |
| TypeScript | laplace.final(address) | { model, inputHash, output }, resolved once the state is final. |
| CLI | laplace receipt <address> | The receipt, printed. |
| A Solana program | laplace_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.