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.
cd backend
npm install
npm run laplace -- operator shownpm run laplace runs tsx src/cli/main.ts. Everything after -- goes to the CLI.
cd backend
npm install
npm run build
node dist/src/cli/main.js operator shownpm run build runs prisma generate and tsc -p tsconfig.json, which writes the CLI to dist/src/cli/main.js, the file the laplace bin points to.
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:
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,marketis not read. --fault,--offand the--claimofoperator withdrawtake no value and can stand anywhere.--forcetakes 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:
cd backend/chain
cargo build --release -p laplace-vm-nativeThe CLI looks for the binary (laplace-vm, or laplace-vm.exe on Windows) in this order and takes the first that exists:
- the path in
LAPLACE_VM_BIN, backend/chain/target/release/, where the build above puts it,- a
bin/folder two levels above the CLI'snode/folder:backend/bin/when run from source,backend/dist/bin/when run built, laplace-vmonPATH.
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. |
| Encryption | The 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). |
| Contents | JSON with version (1), publicKey (base58), and salt, iv, tag, data in hex. |
| Permissions | The 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
| Command | Does | Prints |
|---|---|---|
laplace key new | Generates 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 show | Reads 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,
newandimportfail withA key exists at <file>. Pass --force to replace it.Goes last on the line.
laplace key new
laplace key import ./operator-keypair.json --force
laplace key show --key ./keys/watcher.jsonGlobal flags and variables
A flag wins over its variable, and the variable wins over the default.
| Flag | Variable | Default | Meaning |
|---|---|---|---|
--rpc <url> | LAPLACE_RPC | A validator on the local machine | The Solana RPC endpoint. Reads use the confirmed commitment. |
--api <url> | LAPLACE_API | An API on the local machine | The Laplace API. |
--key <file> | LAPLACE_KEY | .laplace/key.json in the home directory | The key file. |
--data <dir> | LAPLACE_DATA | .laplace/serve or .laplace/watch in the home directory | Where serve and watch keep model files and runs. |
LAPLACE_PASSWORD | The key file's password, in place of the prompt. | ||
LAPLACE_KEY_SEALED | A key file's contents, in place of the file. | ||
LAPLACE_VM_BIN | The path of the laplace-vm binary. | ||
PRIORITY_FEE_MICROLAMPORTS | Recent fees on the cluster | A 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.
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/servein 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:
| Path | Holds |
|---|---|
models/<slug>-<first 16 hex of the manifest hash>/program.bin, weights.bin | The 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-*.bin | One file per run held for the game: the state root after every step, 32 bytes each. |
faults.json | With --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:
event | Other fields | When |
|---|---|---|
serve | models, fault | At start. |
watch | models | At start of laplace watch. |
models_ready | models | Every model's files are on disk and checked. |
models_waiting | message | Fetching the files failed. It tries again every 3 seconds. |
answered | receipt, model, output (first 8 tokens), fault, signature | An answer transaction confirmed. |
answer_failed | receipt, message | The run or the answer transaction failed. |
matched | receipt, model | watch: the re-run gave the same output and trace root. |
trace_differs_output_same | receipt | watch: the output is equal and the trace root is not. No challenge is sent. |
challenged | receipt, dispute, theirs, ours (first 8 tokens each), signature | watch: a challenge transaction confirmed. |
check_failed | receipt, message | watch: the re-run or the challenge transaction failed. |
bisect | dispute, side, interval ([lo, hi] selected), signature | A turn was played. |
proved | dispute, step, payloadBytes, signature | A prove_step transaction confirmed. |
claimed_timeout | dispute, signature | A claim_timeout transaction confirmed. |
play_failed | dispute, message, programError (the error's name) | A game transaction failed. |
error | message | A 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.
laplace watch --models judge,market--modelsslugs- Comma-separated model slugs to watch. Default
judge,market. --datadir- The data folder. Default
LAPLACE_DATA, else.laplace/watchin 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.
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 outlookmodelslugrequired- The first argument:
judgeormarket. --claimstringjudge: the claim. Without the flag, the argument after the model.--evidencestringjudge: the passage of evidence. Without the flag, the second argument after the model.headlinewordsmarket: 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 with | When |
|---|---|
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.
laplace receipt <address>It prints one JSON object:
| Field | Value |
|---|---|
state | requested, answered, challenged, final or void. |
model, operator, answerer | Addresses, base58. |
input, output | Token ids. |
traceRoot | 64 hex characters. |
bondLamports | The bond locked behind the answer, as a decimal string. |
windowEndsAt | ISO-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.
laplace model compile judge --weights ./source/judge --out ./models/judgeslugslugrequiredjudgeormarket. Any other slug fails withThe compiler knows judge and market; <slug> is neither.--weightsdirrequired- The folder with the source weights and tokenizer,
model.safetensorsandvocab.txt, for either model. --outdirrequired- Where
program.bin,weights.bin, the tokenizer file andmanifest.jsonare 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.
laplace model publish ./models/judge --window 300 --bond 2dirdirrequired- 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.
| Command | Instruction | Arguments |
|---|---|---|
laplace operator register | register_operator | None. |
laplace operator bond <sol> | deposit_bond | The amount in SOL, a decimal: 5, 0.5. |
laplace operator offer <model> <price> --mint <mint> [--off] | set_offer | The 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_withdraw | The amount in SOL, a decimal. |
laplace operator withdraw --claim | withdraw_bond | None. |
laplace operator show | none, a read | None. |
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.
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 showBond and offers covers each task and its errors.
Exit behaviour
| Case | Standard output | Standard error | Exit code |
|---|---|---|---|
| A command succeeds | What the command prints | 0 | |
| No command, or an unknown one | The usage text | 0 | |
| A command fails | The error's message, one line | 1 | |
| Ctrl-C at the password prompt | 130 |
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.