Start
Quickstart: ask a model
From nothing to a receipt, in the app, with the SDK and with the CLI.
This page takes you from nothing to a first receipt: a claim put to the judge model, answered by an operator with a bond, and final once its window has closed. Each step is shown three ways: in the app, with the SDK and with the CLI.
Get the SDK or the CLI
Nothing to install. Open Ask.
npm install @laplace/sdk @solana/web3.js@laplace/sdk is an ES module package for Node and the browser. TypeScript SDK is its reference.
The CLI is the laplace command. CLI covers getting it. It signs with its own key, kept in a file encrypted under a password:
laplace key newThe command asks for a new password and prints the key's address. laplace key show prints the address again. The key file is ~/.laplace/key.json unless --key <file> or LAPLACE_KEY names another.
A wallet with the fee mint and SOL
A request is paid from the wallet that signs it. The wallet needs two things:
- the offer's price, in the offer's mint, in the wallet's associated token account for that mint,
- SOL for the transaction fee, its priority fee, and the rent of the receipt account, which the requester pays. The first request in a mint also pays the rent of the escrow's token account for it.
The price and the mint are the operator's. Read them before funding the wallet:
The model's page, /models/judge, lists its offers with price and mint. Ask shows the same list under Offer and the total under You pay.
import { createLaplace } from '@laplace/sdk'
const laplace = createLaplace({ rpcUrl: process.env.LAPLACE_RPC!, apiUrl: process.env.LAPLACE_API! })
const { items } = await laplace.api.offers('judge')
for (const offer of items.filter((o) => o.active && o.live)) {
console.log(offer.address, offer.price, offer.mint.symbol, offer.mint.address, offer.mint.decimals)
}price is in the mint's base units. The list puts live offers first and sorts each group by price.
The CLI has no command that lists offers. Read them from the API, where LAPLACE_API is the API's address from Addresses:
curl "$LAPLACE_API/v1/offers?model=judge"Fund the address laplace key show prints.
Ask the judge
The judge reads a claim and a passage of evidence and answers yes, unclear or no from that passage alone.
On Ask:
- Under Model, pick Judge.
- Under Input, write the Claim and the Evidence.
- Under Offer, the cheapest live offer is selected. Pick another to name a different operator.
- Press Connect wallet if no wallet is connected, then Ask, and sign the one transaction in the wallet.
The panel shows the transaction through Building, Signing, Sent and Confirmed.
import { readFileSync } from 'node:fs'
import { Keypair } from '@solana/web3.js'
import { createLaplace, keypairSigner } from '@laplace/sdk'
const keypair = Keypair.fromSecretKey(Uint8Array.from(JSON.parse(readFileSync('keypair.json', 'utf8'))))
const laplace = createLaplace({
rpcUrl: process.env.LAPLACE_RPC!,
apiUrl: process.env.LAPLACE_API!,
wallet: keypairSigner(keypair),
})
const { receipt, signature } = await laplace.ask('judge', {
claim: 'The bridge opened in 1932.',
evidence: 'The bridge opened to traffic in March 1932.',
})
console.log(receipt.toBase58(), signature)rpcUrl and apiUrl are the network's addresses from Addresses. ask takes the cheapest live offer. Pass { offer } as a third argument to name one, and { maxFee } to cap the fee at the price you showed.
laplace ask judge --claim "The bridge opened in 1932." --evidence "The bridge opened to traffic in March 1932."The command asks for the key's password, takes the cheapest live offer and sends the request. --offer <address> names another offer. --rpc and --api, or LAPLACE_RPC and LAPLACE_API, set the network's addresses.
The market model is asked the same way, with one text in place of the claim and the evidence. It reads a market headline or statement and answers negative, neutral or positive. The text is cut to the model's 32 tokens, so a long one is read from its start.
On Ask, pick Market under Model and write the Headline or statement under Input. The rest is the same.
const market = await laplace.ask('market', {
text: 'Shipments rose 18% in the third quarter, above guidance.',
})laplace ask market "Shipments rose 18% in the third quarter, above guidance."Every argument after market that is not a flag is joined with spaces into the text.
What is signed and what it costs
All three ways sign the same thing: one transaction with one request instruction. It names the model and the operator, carries the input as token ids, a seed and max_fee, the most the requester pays, and moves the offer's price from the wallet into the fee escrow. The app sends the price it showed as max_fee; the SDK and the CLI send the price they read just before sending. An operator that raises its price in between gets nothing: the program refuses the request with FeeAboveMax and no fee moves. On Ask the panel then reads "The operator’s price went up after this page read it. Nothing was charged. Read the new price and ask again." The receipt account is created in the same transaction, in state requested, and its address is known from that moment.
The cost is the offer's price in the offer's mint, plus the SOL named above. The fee waits in escrow: it is paid to the answerer when the receipt is final, and it returns in full if the receipt goes void. Fees and offers follows the fee through each case.
On Ask, the What you send panel shows all of it before the signature: the model, the operator, the bond behind the answer, the window, and the amount under You pay.
The receipt reaches answered
The operator named by the offer has until the receipt's answer deadline to answer. Its answer puts the output and the trace root on the receipt, locks the model's bond behind them and opens the window. The state is answered.
The panel reads Waiting for the answer with the time the operator has left. When the answer lands it shows the Answer, the SOL bonded behind it, and Open the receipt, which leads to the receipt at /receipts/<address>.
import { JUDGE_LABELS } from '@laplace/sdk'
const answered = await laplace.waitFor(receipt, (r) => r.state !== 'requested')
console.log(answered.state, JUDGE_LABELS[answered.output[0]!], answered.bond, answered.windowEndsAt)waitFor reads the receipt once a second and gives up after 10 minutes. ask does the same wait itself when called with { waitForAnswer: true }.
laplace ask waits for the answer. It prints the receipt's address, then the answer as its label: yes, unclear or no for the judge, negative, neutral or positive for the market model. It gives up after 10 minutes with Timed out waiting for the receipt.
Wait for final
An answered receipt can be challenged until its window closes. After that, with no dispute open, anyone can send finalize, and the network itself sends it. The state is then final, and that is the state other programs act on.
The window's length is the model's. It is on the model's page, in windowSeconds from GET /v1/models/judge, and on the receipt as the time it closes.
The receipt's page counts the window down under Window, with the time it closes in UTC. When the window has closed and the receipt is not final yet, a connected wallet sees Finalize. Once final, the page reads Final since with the time.
const { model, inputHash, output } = await laplace.final(receipt)final resolves when the receipt is final and throws when it went void. It sends nothing. To send finalize from your own wallet once the window has closed, call await laplace.finalize(receipt).
laplace receipt <address>The command prints the receipt as JSON. Its state field reads final once the receipt is finalized, and windowEndsAt is the time the window closes, in UTC.
Read the output
The output is on the receipt as token ids. Each model answers one token, the index of its label:
output[0] | judge | market |
|---|---|---|
0 | yes | negative |
1 | unclear | neutral |
2 | no | positive |
The receipt's page shows the Answer beside the input, the Claim and the Evidence or the Headline or statement, with the operator, the bond locked, the fee, the input hash and the trace root.
import { JUDGE_LABELS } from '@laplace/sdk'
const { output } = await laplace.final(receipt)
console.log(JUDGE_LABELS[output[0]!]) // 'yes', 'unclear' or 'no'For the market model, the same index goes into MARKET_LABELS:
import { MARKET_LABELS } from '@laplace/sdk'
const { output } = await laplace.final(market.receipt)
console.log(MARKET_LABELS[output[0]!]) // 'negative', 'neutral' or 'positive'laplace receipt <address> prints these fields: state, model, operator, input, output, traceRoot, answerer, bondLamports and windowEndsAt. input and output are token ids.
Void, and Cancel and refund
A request that the operator does not answer before the answer deadline can be cancelled by its requester. cancel_request returns the whole fee to the requester's token account and sets the receipt to void, which is terminal: a void receipt has no output and is never final.
The answer deadline is on the receipt: answerDeadline in GET /v1/receipts/:address and in laplace.receipt(address). Cancelling before it fails with AnswerDeadlineOpen, and only the requester's wallet can cancel.
Once the deadline has passed, Ask and the receipt's page show Cancel and refund to the requester's wallet. After the signature the receipt reads void and the fee is back in the wallet.
const r = await laplace.receipt(receipt)
if (r.state === 'requested' && Date.now() / 1000 > r.answerDeadline) {
await laplace.cancel(receipt)
}The CLI has no cancel command. Cancel from the app or with the SDK, with the wallet that sent the request.
Run it again
The receipt you now hold can be checked by anyone, you included: run the model on the same input and compare the bits with the operator's.