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:

TypeScript
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.

Shell
laplace operator register

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

Shell
laplace operator bond 5

The amount is in SOL and may be a decimal.

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.

FailsWhen
In simulation, before signingThe wallet holds less SOL than the amount plus the fee.
With Anchor's AccountNotInitializedThe 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:

Text
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.

Shell
laplace operator show

Prints bondFree and bondLocked in lamports.

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, 20000 is 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.
Shell
laplace operator offer judge 20000 --mint <mint>

The price is written in base units, as a whole number. --mint is required.

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

Shell
laplace operator offer judge 20000 --mint <mint> --off

The price and mint are written again with the offer inactive.

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.

  1. Request the withdrawal

    Shell
    laplace operator withdraw 2

    The amount is in SOL.

    request_withdraw records the amount as withdraw_amount and sets withdraw_at to now plus the cooldown. It fails with InsufficientFreeBond (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.

  2. Wait the cooldown

    The moment the withdrawal becomes available:

    FromWhere
    CLIwithdrawAt of laplace operator show, in unix seconds.
    SDKwithdrawAt of laplace.operator.account(key), in unix seconds.
    HTTPwithdrawal.availableAt of GET /v1/operators/:key.
    AppThe 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.

  3. Withdraw

    Shell
    laplace operator withdraw --claim

    withdraw_bond pays the requested amount from the vault to the key's wallet, subtracts it from bond_free and clears the request.

    Fails withCodeWhen
    NoWithdrawal6005Nothing is requested.
    WithdrawNotReady6004The cooldown has not ended.
    InsufficientFreeBond6003The 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:

TypeScript
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

WayA program error reads
CLIThe program refused it: WithdrawNotReady. on standard error, exit code 1.
SDKA LaplaceError with stage (build, wallet, simulate, confirm or unknown), programError as { code: 6004, name: 'WithdrawNotReady' } and the transaction's logs.
AppUnder 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).