Operators
Bond and offers
Free and locked bond, the withdrawal cooldown, and pricing an offer per model.
An operator has two things to manage: the SOL bond behind its answers and one offer per model it serves. This page is each task, in the terminal, with the SDK and on Operate, with the exact errors. What a bond and an offer are is on Bonds and windows and Fees and offers.
Every task here is one transaction signed by the operator's key. The SDK samples assume a client made with that key as its wallet:
import { createLaplace } from '@laplace/sdk'
const laplace = createLaplace({ rpcUrl, apiUrl, wallet })rpcUrl and apiUrl are the network's addresses: Addresses. Each operator.* call resolves to the transaction's signature and throws LaplaceError when it fails, with the program's error in programError as { code, name }.
Register
Done once per key, before anything else on this page.
laplace operator registerawait laplace.operator.register()On Operate, connect the wallet and press Register as operator.
register_operator creates the Operator account at seeds ["operator", authority], paid for by the key. Sent a second time for the same key it fails, because the account already exists.
Deposit bond
laplace operator bond 5The amount is in SOL and may be a decimal.
await laplace.operator.deposit(5_000_000_000n) // lamports: 5 SOLIn the Bond panel, enter the amount in SOL under Deposit and press Deposit bond. The Bond free tile rises by the amount.
deposit_bond moves the lamports from the key's wallet into the vault and adds them to bond_free. There is no minimum and no limit on how often it is sent.
| Fails | When |
|---|---|
| In simulation, before signing | The wallet holds less SOL than the amount plus the fee. |
With Anchor's AccountNotInitialized | The key is not registered. |
How many answers a bond covers
Each answer moves the model's bond from free to locked until its receipt is final. So for one model:
answers open at once = floor(bond_free / model bond)The bond of a model is bondLamports of GET /v1/models/:slug. The bond describes the two balances.
laplace operator showPrints bondFree and bondLocked in lamports.
const me = await laplace.operator.account(wallet.publicKey)
const judge = await laplace.api.model('judge')
const answersAtOnce = me.bondFree / BigInt(judge.bondLamports)operator.account(key) returns the Operator account: authority, bondFree, bondLocked, withdrawAmount (lamports, bigint), withdrawAt, answered, disputesWon, disputesLost, lastAnswerAt, registeredAt.
The Bond free tile on Operate carries the count for every model under the figure, as <n> judge or <n> market answers at once. Bond locked is the tile beside it.
When the free bond is smaller than the model's bond, answer fails with InsufficientFreeBond (6003) and the API stops listing the operator's offer for that model as live. Answering and deadlines describes what the node does then.
Set an offer
One offer per model: a price, the mint it is charged in, and whether it takes requests.
modelslugrequired- The model the offer is for.
priceu64required- The fee per request, in the mint's base units. For a mint with 6 decimals,
20000is 0.02 of the token. mintaddressrequired- A mint of the SPL Token program. Every request through this offer is charged in it.
activebool- Whether the offer takes requests. On by default in the CLI, the SDK and the app.
laplace operator offer judge 20000 --mint <mint>The price is written in base units, as a whole number. --mint is required.
import { PublicKey } from '@solana/web3.js'
const mint = new PublicKey(mintAddress)
await laplace.operator.offer('judge', 20_000n, mint) // on, at 20,000 base units
await laplace.operator.offer('judge', 20_000n, mint, false) // offIn the Offers panel, each registered model has a row with its bond per answer and window. Enter the Price in whole tokens (0.02), pick the Mint from the ones the page knows or press "Another mint" and paste its address, set Taking requests to On, and press Set offer. The page converts the price to base units with the mint's decimals, and with 6 decimals for a mint entered by address.
set_offer creates the Offer account at seeds ["offer", authority, model] the first time and overwrites it after that, so it is also how an offer is changed.
Change an offer
Send set_offer again with the new values, the same three ways as above. Price, mint and active are all replaced by what the call carries, and the offer's updated_at is set.
A request already made keeps the mint and fee it was made with: both were copied onto its receipt by request. Only requests after the change pay the new price.
Turn an offer off
laplace operator offer judge 20000 --mint <mint> --offThe price and mint are written again with the offer inactive.
await laplace.operator.offer('judge', 20_000n, mint, false)In the model's row, set Taking requests to Off and press Set offer. The row then reads "offer off".
A request through an inactive offer fails with OfferInactive (6006). Requests made before stay with the operator and are answered as usual. The same call without --off, or with active true, turns it back on.
Withdraw the bond
Free bond leaves in two transactions with the cooldown between them. The cooldown is withdraw_cooldown_secs of the Config account.
Request the withdrawal
Shell laplace operator withdraw 2The amount is in SOL.
TypeScript await laplace.operator.requestWithdraw(2_000_000_000n) // lamports: 2 SOLIn the Bond panel, enter the amount under Withdraw, or press "Max" for the whole free bond, and press Request withdrawal. An amount above the free bond shows "Only free bond can leave" and the button stays disabled.
request_withdrawrecords the amount aswithdraw_amountand setswithdraw_atto now plus the cooldown. It fails withInsufficientFreeBond(6003) when the amount is zero or larger than the free bond.A second request replaces the first: the new amount stands and the cooldown starts again.
Wait the cooldown
The moment the withdrawal becomes available:
From Where CLI withdrawAtoflaplace operator show, in unix seconds.SDK withdrawAtoflaplace.operator.account(key), in unix seconds.HTTP withdrawal.availableAtofGET /v1/operators/:key.App The Bond panel shows the amount, "available in" with a countdown, and the time in UTC. /operators/<key>shows it as Withdrawal.The requested amount stays in the free bond during the cooldown, and the node keeps answering from it.
Withdraw
Shell laplace operator withdraw --claimTypeScript await laplace.operator.withdraw()Once the countdown reads "ready to withdraw", press Withdraw bond.
withdraw_bondpays the requested amount from the vault to the key's wallet, subtracts it frombond_freeand clears the request.Fails with Code When NoWithdrawal6005 Nothing is requested. WithdrawNotReady6004 The cooldown has not ended. InsufficientFreeBond6003 The requested amount is larger than the free bond now, because answers locked part of it during the cooldown. It succeeds once enough of those receipts are final, or after a new request for a smaller amount.
The whole sequence with the SDK, reading the time from the account and naming the error:
import { createLaplace, LaplaceError } from '@laplace/sdk'
const laplace = createLaplace({ rpcUrl, apiUrl, wallet })
await laplace.operator.requestWithdraw(2_000_000_000n) // lamports: 2 SOL
const { withdrawAt } = await laplace.operator.account(wallet.publicKey) // unix seconds
try {
await laplace.operator.withdraw()
} catch (e) {
if (e instanceof LaplaceError && e.programError?.name === 'WithdrawNotReady') {
console.log(`Available at ${new Date(withdrawAt * 1000).toISOString()}`)
} else throw e
}Locked bond is not withdrawn. It returns to the free bond when its receipt is finalized.
How a failure reads
| Way | A program error reads |
|---|---|
| CLI | The program refused it: WithdrawNotReady. on standard error, exit code 1. |
| SDK | A LaplaceError with stage (build, wallet, simulate, confirm or unknown), programError as { code: 6004, name: 'WithdrawNotReady' } and the transaction's logs. |
| App | Under the button, the stages Building, Signing, Sent, Confirmed stop at the one that failed, with the line "The program refused." and the error as WithdrawNotReady (6004). |