Reference

CLI

Every command and flag of the laplace binary.

laplace is one program with seven commands: the operator's node, the watcher's node, a one-line request, a receipt reader, the model compiler and publisher, the operator's instructions and the key file. This page lists every command, argument, flag, default and variable, and what each prints.

Install and invoke

The CLI is the file src/cli/main.ts of the package laplace-backend, in the backend/ folder of the Laplace source. The package is private and needs Node 22. It declares one bin, laplace, at dist/src/cli/main.js.

Shell
cd backend
npm install
npm run laplace -- operator show

npm run laplace runs tsx src/cli/main.ts. Everything after -- goes to the CLI.

The rest of the docs write laplace <command> for either form.

With no command, or one it does not know, the CLI prints its usage:

Text
laplace <command>

  serve [--models judge,market] [--fault]    answer every request naming this key
  watch [--models judge,market]              run every answer again; challenge a difference
  ask judge --claim "…" --evidence "…"        request an answer and wait for it
  ask market <headline…>
  receipt <address>
  model compile <slug> --weights <dir> --out <dir>
  model publish <dir> --window <secs> --bond <sol>
  operator register | bond <sol> | offer <model> <price> --mint <mint> [--off] | withdraw <sol> | withdraw --claim | show
  key new | import <keypair.json> | show

  --rpc <url> (LAPLACE_RPC)  --api <url> (LAPLACE_API)  --key <file> (LAPLACE_KEY)

Writing flags

  • A flag and its value are two arguments: --models judge,market. The form --models=judge,market is not read.
  • --fault, --off and the --claim of operator withdraw take no value and can stand anywhere.
  • --force takes no value and goes last on the line.
  • Flags can come before or after the positional arguments.

The native laplace-vm binary

serve, watch and model compile run models with laplace-vm, the native build of the step function. It is the bin laplace-vm of the crate laplace-vm-native:

Shell
cd backend/chain
cargo build --release -p laplace-vm-native

The CLI looks for the binary (laplace-vm, or laplace-vm.exe on Windows) in this order and takes the first that exists:

  1. the path in LAPLACE_VM_BIN,
  2. backend/chain/target/release/, where the build above puts it,
  3. a bin/ folder two levels above the CLI's node/ folder: backend/bin/ when run from source, backend/dist/bin/ when run built,
  4. laplace-vm on PATH.

ask, receipt, model publish, operator and key do not need it.

The key file

The CLI signs with one Solana keypair kept in a file encrypted under a password.

Location--key <file>, else LAPLACE_KEY, else .laplace/key.json in the home directory.
EncryptionThe 64-byte secret key is encrypted with AES-256-GCM under a key derived from the password by scrypt (N = 32768, r = 8, p = 1, a 16-byte random salt, a 12-byte random IV).
ContentsJSON with version (1), publicKey (base58), and salt, iv, tag, data in hex.
PermissionsThe folder is created if missing. The file is written with mode 0600.

The password

Every command that signs asks once per launch, without echoing: Password for <file>: . Ctrl-C at the prompt exits with code 130.

When LAPLACE_PASSWORD is set, its value is the password and nothing is asked. That is how a service starts. With no terminal attached and no LAPLACE_PASSWORD, the command fails with Set LAPLACE_PASSWORD or run in a terminal.

A wrong password fails with Wrong password for this key. A missing file fails with No key at <file>. Run `laplace key new` or `laplace key import <file>`.

A sealed key in a variable

When LAPLACE_KEY_SEALED is set, its value is read as the whole contents of a key file and used in place of the file at the key path. The password comes from LAPLACE_PASSWORD. This lets a hosted node take its key as a variable with no file on disk.

laplace key

CommandDoesPrints
laplace key newGenerates a keypair, asks New password: once, writes the key file.The public key, base58.
laplace key import <keypair.json>Reads a keypair file holding the secret key as a JSON array of 64 numbers (the format solana-keygen writes), asks New password: once, writes the key file.The public key, base58.
laplace key showReads the public key from the key file. No password.The public key, or No key at <file>.
--forceflag
Replace an existing key file. Without it, new and import fail with A key exists at <file>. Pass --force to replace it. Goes last on the line.
Shell
laplace key new
laplace key import ./operator-keypair.json --force
laplace key show --key ./keys/watcher.json

Global flags and variables

A flag wins over its variable, and the variable wins over the default.

FlagVariableDefaultMeaning
--rpc <url>LAPLACE_RPCA validator on the local machineThe Solana RPC endpoint. Reads use the confirmed commitment.
--api <url>LAPLACE_APIAn API on the local machineThe Laplace API.
--key <file>LAPLACE_KEY.laplace/key.json in the home directoryThe key file.
--data <dir>LAPLACE_DATA.laplace/serve or .laplace/watch in the home directoryWhere serve and watch keep model files and runs.
LAPLACE_PASSWORDThe key file's password, in place of the prompt.
LAPLACE_KEY_SEALEDA key file's contents, in place of the file.
LAPLACE_VM_BINThe path of the laplace-vm binary.
PRIORITY_FEE_MICROLAMPORTSRecent fees on the clusterA fixed compute-unit price, in µlamports, for every transaction the command sends. Unset, the price follows recent fees: Priority fees.

Set --rpc and --api, or their variables, to the network's addresses: Addresses.

laplace serve

The operator's node. It answers every request that names this key, for the models it serves, and plays every turn of the disputes this key is a side of. It runs until it is stopped.

Answers and games run in two loops side by side. The answer loop reads this key's requested receipts every 1.5 seconds and answers each one. The game loop reads this key's unresolved disputes every second and plays the next move of each, so no burst of requests holds a turn past its deadline. When a game reaches its last step the node proves it itself, as a v1 transaction.

Shell
laplace serve --models judge,market
--modelsslugs
Comma-separated model slugs to answer for. Default judge,market.
--datadir
The data folder. Default LAPLACE_DATA, else .laplace/serve in the home directory.
--faultflag
Corrupts one step of each answer for which it finds a corruption that changes the output, so that answer is wrong and loses to a challenge. An answer with no such corruption is posted as run. For playing a dispute on a test network.

Needs the key, the laplace-vm binary, a registered operator with free bond, and an offer per model. Run a node is the guide, and Answering and deadlines describes each pass.

What it writes to disk

Under the data folder:

PathHolds
models/<slug>-<first 16 hex of the manifest hash>/program.bin, weights.binThe model's program and weights, downloaded from the API's store and checked by SHA-256 against the hashes GET /v1/models/:slug/files lists. The download asks for gzip and is decompressed before the check, so the market model's program file travels compressed. A file already on disk with the right hash is not downloaded again.
runs/roots-*.binOne file per run held for the game: the state root after every step, 32 bytes each.
faults.jsonWith --fault only: the corruption used per receipt, so a restart defends the same answer.

What it prints

One JSON object per line on standard output. Every line has at (ISO-8601 UTC), node (the first 6 characters of the key) and event:

eventOther fieldsWhen
servemodels, faultAt start.
watchmodelsAt start of laplace watch.
models_readymodelsEvery model's files are on disk and checked.
models_waitingmessageFetching the files failed. It tries again every 3 seconds.
answeredreceipt, model, output (first 8 tokens), fault, signatureAn answer transaction confirmed.
answer_failedreceipt, messageThe run or the answer transaction failed.
matchedreceipt, modelwatch: the re-run gave the same output and trace root.
trace_differs_output_samereceiptwatch: the output is equal and the trace root is not. No challenge is sent.
challengedreceipt, dispute, theirs, ours (first 8 tokens each), signaturewatch: a challenge transaction confirmed.
check_failedreceipt, messagewatch: the re-run or the challenge transaction failed.
bisectdispute, side, interval ([lo, hi] selected), signatureA turn was played.
proveddispute, step, payloadBytes, signatureA prove_step transaction confirmed.
claimed_timeoutdispute, signatureA claim_timeout transaction confirmed.
play_faileddispute, message, programError (the error's name)A game transaction failed.
errormessageA pass failed, for example the API did not answer. The next pass runs as usual.

Stopping

SIGINT or SIGTERM ends the loop after the current pass.

laplace watch

The watcher's node. It runs every answered receipt of its models again, opens a challenge when the output differs, and plays every turn of the disputes this key is a side of. It runs until it is stopped.

Re-runs and games run in two loops side by side. Every 2 seconds the re-run loop reads every page of answered receipts for each model, 100 to a page, and runs each one it has not run for that trace root. The game loop is the same as serve's: every second, the next move of each unresolved dispute of this key, proving the last step itself.

Shell
laplace watch --models judge,market
--modelsslugs
Comma-separated model slugs to watch. Default judge,market.
--datadir
The data folder. Default LAPLACE_DATA, else .laplace/watch in the home directory.

Needs the key, the laplace-vm binary, and SOL in the key's wallet for each challenge's bond. It writes the same models/ and runs/ folders as serve and prints the same lines. Run a watcher is the guide.

laplace ask

Sends a request to a model, waits for the answer and prints it.

Shell
laplace ask judge --claim "The bridge opened in 1932." --evidence "The bridge opened to traffic in March 1932."
laplace ask market Nvidia beats revenue estimates and raises its outlook
modelslugrequired
The first argument: judge or market.
--claimstring
judge: the claim. Without the flag, the argument after the model.
--evidencestring
judge: the passage of evidence. Without the flag, the second argument after the model.
headlinewords
market: every argument after the model, joined with spaces.
--seedu64
The seed the receipt records. Left out, a random one is taken. Neither model samples, so it does not change the answer.
--offeraddress
The offer account to take. Left out, the first live offer of GET /v1/offers?model=, which lists live offers first and cheapest first.

It asks for the key's password, sends request, and waits until the receipt is no longer requested, for at most 600 seconds. Then it prints two lines: the receipt's address, and the answer (yes, unclear or no for judge, negative, neutral or positive for market).

The input is tokenized with the model's WordPiece vocabulary and cut to the model's inputMax: for market, [CLS], the first word pieces of the headline and [SEP]; for judge, the longer of the evidence and the claim loses its last word pieces until both fit.

Fails withWhen
No operator is live for <model>.No offer for the model is active and live, and --offer is not given.
The program refused it: OfferInactive.The offer named is off.
Timed out waiting for the receipt.No answer within 600 seconds. The request stands on chain and can be cancelled after its answer deadline.

laplace receipt

Reads a receipt account from the chain and prints it. No key and no password.

Shell
laplace receipt <address>

It prints one JSON object:

FieldValue
staterequested, answered, challenged, final or void.
model, operator, answererAddresses, base58.
input, outputToken ids.
traceRoot64 hex characters.
bondLamportsThe bond locked behind the answer, as a decimal string.
windowEndsAtISO-8601 UTC, or null before an answer.

An address with no account fails with No account at <address>.

laplace model compile

Turns open weights into the integer program. Needs the laplace-vm binary. No key.

Shell
laplace model compile judge --weights ./source/judge --out ./models/judge
slugslugrequired
judge or market. Any other slug fails with The compiler knows judge and market; <slug> is neither.
--weightsdirrequired
The folder with the source weights and tokenizer, model.safetensors and vocab.txt, for either model.
--outdirrequired
Where program.bin, weights.bin, the tokenizer file and manifest.json are written.

It prints one JSON object with program, weights and init (the three roots), stepCount, statePages, chunkCount and filesHash (the SHA-256 of manifest.json). Compile a model is the guide.

laplace model publish

Registers a compiled model and uploads its files to the API's store.

Shell
laplace model publish ./models/judge --window 300 --bond 2
dirdirrequired
A folder written by model compile.
--windowseconds
The model's window. Default 600.
--bondSOL
The model's bond per answer, in SOL. Default 1.

It asks for the key's password. When no Model account exists for the slug it sends register_model signed by the key, which becomes the publisher. While Config.registration_open is false that key must be the program's admin: any other key is refused with Unauthorized. Then it uploads the manifest, the program, the weights and the tokenizer. It prints one JSON object: slug, model (the Model account's address) and signature (null when the model was already registered). Publish a model is the guide.

laplace operator

The operator's instructions, each one transaction signed by the key. Each asks for the password and prints the transaction's signature.

CommandInstructionArguments
laplace operator registerregister_operatorNone.
laplace operator bond <sol>deposit_bondThe amount in SOL, a decimal: 5, 0.5.
laplace operator offer <model> <price> --mint <mint> [--off]set_offerThe model's slug; the price as a whole number of the mint's base units; --mint, the mint's address, required; --off sets the offer inactive.
laplace operator withdraw <sol>request_withdrawThe amount in SOL, a decimal.
laplace operator withdraw --claimwithdraw_bondNone.
laplace operator shownone, a readNone.

laplace operator show prints one JSON object: key, bondFree, bondLocked and withdraw in lamports as decimal strings, and withdrawAt in unix seconds (0 when nothing is requested). For a key with no Operator account it prints Not registered.

Shell
laplace operator register
laplace operator bond 5
laplace operator offer judge 20000 --mint <mint>
laplace operator offer judge 20000 --mint <mint> --off
laplace operator withdraw 2
laplace operator withdraw --claim
laplace operator show

Bond and offers covers each task and its errors.

Exit behaviour

CaseStandard outputStandard errorExit code
A command succeedsWhat the command prints0
No command, or an unknown oneThe usage text0
A command failsThe error's message, one line1
Ctrl-C at the password prompt130

A transaction the program refuses fails with The program refused it: <ErrorName>., where the name is one of the program errors. A transaction that fails for another reason prints Simulation failed: … or The transaction failed: … with the cluster's error, and one that did not land before its blockhash expired prints The transaction expired before it landed.

serve and watch do not exit on a failed pass or a failed transaction. They print the line and continue.