Models

Publish a model

Upload a compiled model and register it with its window and bond.

Publishing puts a compiled model on the network: one register_model transaction records its roots, its window and its bond for good, and four uploads put its files in the store where browsers and nodes fetch them. laplace model publish does both. This page covers the command, what the registration records, the upload and its checks, what the publisher pays, and what happens next.

Before publishing

  • A compiled model folder holding manifest.json, program.bin, weights.bin and the tokenizer, from Compile a model.
  • A key with SOL for one transaction and the rent of one account. The CLI reads it from its sealed key file; CLI covers laplace key new and --key.
  • A key the program lets register. While registration_open on the program's Config is false, only the program's admin registers models; once the admin sets it to true, any key does. Who may register shows how to read it.
  • The network's RPC and API addresses, passed as --rpc and --api or set as LAPLACE_RPC and LAPLACE_API. They are listed on Addresses.
  • A window and a bond. Choosing a bond and a window covers how to set them.

Publish

  1. Run the command

    Shell
    laplace model publish ./out/market --window 900 --bond 2

    This registers the model with a window of 900 seconds and a bond of 2 SOL per answer. The CLI asks for the key file's password, or reads it from LAPLACE_PASSWORD.

  2. It registers the model

    The CLI reads manifest.json and looks up the Model account for its slug. When the account does not exist it sends register_model, signed by the key: the admin's key while registration is closed. When it exists the CLI skips this step and only uploads.

  3. It uploads the files

    Four requests to POST /v1/files, in this order: the manifest, program.bin, weights.bin, the tokenizer. The store checks each against the chain before keeping it.

  4. Read what it printed

    One JSON object with three fields: slug, model (the address of the Model account) and signature (the register_model transaction, or null when the account already existed).

Arguments

dirpathrequired
The compiled model folder.
--windowseconds
The model's window. An integer number of seconds. Left out, the CLI sends 600.
--bondSOL
The model's bond per answer, in SOL, decimals allowed. It is converted to lamports and rounded. Left out, the CLI sends 1.
--rpcurl
The cluster's RPC address. Also LAPLACE_RPC.
--apiurl
The network's API address, whose store takes the files. Also LAPLACE_API.
--keypath
The sealed key file of the publisher. Also LAPLACE_KEY. The default is .laplace/key.json in the home folder.

Who may register

Config.registration_open decides who signs register_model. It is false from the moment the program is set up, and the admin changes it with set_config.

registration_openWho registers
falseThe admin, the key in Config.admin. Any other key is refused with Unauthorized (6000).
trueAny key.
TypeScript
import { Connection } from '@solana/web3.js'
import { decode, pda } from '@laplace/sdk'

const connection = new Connection(process.env.LAPLACE_RPC!, 'confirmed')
const info = await connection.getAccountInfo(pda.config(), 'confirmed')
const config = decode.config(info!.data)
config.registrationOpen // false: only config.admin registers
config.admin

What register_model records

The instruction creates the Model account at seeds ["model", slug]. The publisher signs and pays for it.

FieldFromMeaning
slugThe manifestThe model's name on the network and the seed of its address.
publisherThe signerThe key that registered it.
archThe manifest0 for the judge, 1 for the market model.
weights_root, program_root, init_rootThe manifest's rootsWhat every proof in a dispute is checked against.
step_count, state_pages, chunk_countThe manifestThe size of the run, the state and the weights.
input_max, output_lenThe manifestThe most input tokens a request may carry and the exact length of an answer.
window_secs--windowThe seconds after an answer during which anyone may challenge it.
bond_lamports--bondThe lamports locked behind each answer, and the bond a challenger posts.
files_hashThe SHA-256 of manifest.jsonWhat the store checks an uploaded manifest against.
registered_atThe chain's clockClock.unix_timestamp when the instruction ran.

The instruction fails with Unauthorized (6000) when registration is closed and the signer is not the admin, and with InvalidModel (6002) when the slug is empty, longer than 24 bytes or holds a character other than a lowercase letter, a digit or -, when a count, the window or the bond is zero, or when input_max or output_len is outside 1 to 64.

A slug is registered once. The address is derived from the slug alone, so a second register_model for a slug that is taken fails, whoever sends it.

The upload

POST /v1/files takes one file per request: the raw bytes as the body, and two headers.

HeaderValue
X-ModelThe model's slug.
X-Filemanifest, program, weights or tokenizer.
Content-Typeapplication/octet-stream
Shell
curl -X POST "$LAPLACE_API/v1/files" \
  -H "Content-Type: application/octet-stream" \
  -H "X-Model: market" -H "X-File: manifest" \
  --data-binary @out/market/manifest.json

The response is { "hash": "<sha256 of the file, hex>", "bytes": <its size> }. The store keeps a file under its SHA-256 and writes it once, so uploading the same file again returns the same answer.

The store reads the Model account from the chain on every upload and keeps a file only when the chain vouches for it:

FileKept when
manifestIts SHA-256 equals the model's files_hash, and the three roots it names equal the model's weights_root, program_root and init_root.
program, weights, tokenizerIts SHA-256 equals the hash the stored manifest names for that file.

So the manifest goes first, and nobody but the publisher decides what the files are: any file that does not hash to what was registered is refused, whoever uploads it.

StatusCodeWhen
400VALIDATION_ERRORX-File is not one of the four kinds.
409MODEL_NOT_REGISTEREDNo Model account exists for the slug in X-Model, or a file other than the manifest arrives before the manifest is in the store.
413PAYLOAD_TOO_LARGEThe file is larger than 67,108,864 bytes (64 MiB).
422ROOT_MISMATCHThe manifest does not hash to files_hash or names other roots, or a file is not the one the manifest names.
429RATE_LIMITEDMore than 30 writes in a minute from one client. The response carries retryAfterSeconds.

Every failure is the API's error envelope with stage: "upload", except the rate limit and a body over 64 MiB, which carry stage: "validation". HTTP API describes the envelope. The CLI stops at the first failed upload and prints the code and message. Running laplace model publish again on the same folder skips the registration and uploads the files.

What the publisher pays

CostAmount
The register_model transactionOne signature's fee.
The Model accountThe rent-exempt deposit for 231 bytes, taken from the publisher's wallet.
The uploadsNothing. POST /v1/files takes no payment and no signature.

The publisher posts no bond. The bond set here is what each answerer locks behind an answer to this model, and what each challenger posts to dispute one.

After publishing

The model has an account, and its files are in the store.

WhereWhat is there
/models/<slug>The model's page in the app: its roots, step count, window, bond, offers and receipts.
GET /v1/models/:slugModelDetail: the registration, the manifest's description, the offers and the files. It answers NOT_FOUND until the manifest is in the store.
GET /v1/models/:slug/filesThe hash, size and URL of the manifest, weights, program and tokenizer.
GET /v1/files/:hashThe bytes of any of them.

The model answers nothing until an operator serves it. An operator sets an offer for the slug and starts a node that holds it:

Shell
laplace operator offer <slug> <price> --mint <mint>
laplace serve --models <slug>

The node reads the model's file list from the API, downloads program.bin and weights.bin by hash, checks each against its hash and keeps them in its data folder. A watcher does the same with laplace watch --models <slug>. Run a node and Run a watcher are the guides.