Run a solver
Register and bond
Create a solver account with its commission, put stake behind it, and read how much of its bond is free.
A solver is an account in the program, owned by one operator key. Registering creates it. From then on anyone can stake behind it, the operator included, and that stake is the bond its batches lock.
This page takes an operator from a keypair to a solver with free bond. It uses the una-solver binary. Run the node builds it and lists its settings.
Register
SOLVER_KEYPAIR=~/solver-operator.json \
RPC_URL=https://your-rpc-endpoint \
una-solver register --commission-bps 500The command signs one register_solver transaction with the operator key and waits for it to confirm. It prints the solver's address, the operator's address, the commission, the transaction signature and the compute units used. If the transaction fails it prints register failed: with the reason and exits with code 1.
una-solver register
--commission-bpsu16- The commission in basis points. Without the flag the command sends 500.
What register_solver does
The operator signs and pays the rent of the new account. The solver's address is derived from the operator's key, with seeds "solver" and the operator's public key, so one key registers one solver.
register_solver
commission_bpsu16required- The part of the solver's clearing fees the operator keeps, in basis points, from 0 to 10,000.
The program stores the operator and the commission, marks the solver active and emits SolverRegistered with the solver, the operator and the commission.
| Error | Raised when |
|---|---|
InvalidConfig | commission_bps is above 10,000. |
The commission
The commission is set once, by register_solver. The program has no instruction that changes it afterwards, so the figure a staker reads on the solver's page is the figure every batch is split by. Commission and payouts has the split.
The solver account
Everything the program knows about a solver is in this one account. The fields an operator reads:
Solver
operatorPubkey- The key that registered it. Only this key sends
clear_batchfor the solver and claims its commission. commission_bpsu16- The commission.
bond_pool_amounts[u64; 4]- The staked amount of each bond token, in that token's atoms, one slot per token on the bond list.
bond_locked_lamportsu64- Bond locked behind batches that are cleared and not yet proven.
pending_unstake_lamportsu64- Stake that has asked to leave and is in its cooldown.
batches_clearedu64- Batches this solver has cleared.
batches_provenu64- Batches it has proven.
slash_countu32- Batches it was slashed for.
operator_commission[u64; 32]- Commission waiting to be claimed, per token index, in that token's atoms.
activeu8- 1 from registration.
clear_batchrequires it.
The program reference lists every field.
Put stake behind it
A solver's bond is the stake behind it: the operator's own and every staker's, in one pool per bond token. The program does not tell the two apart. The operator stakes with the same stake instruction as anyone else, and that stake earns the stakers' part of each batch like any other.
Open /solvers/[address] with the address una-solver register printed and connect the operator's wallet. Under Stake behind the solver, enter an amount, pick the bond token, and press Stake. The form shows what the amount counts as bond, in SOL, before you sign.
// The solver address `una-solver register` printed.
const solverAddress = process.env.SOLVER_ADDRESS!
// Stake 2 SOL behind it. The amount is in atoms of the bond token.
const { bondMints } = await una.protocol()
const sol = bondMints.find((m) => m.symbol === 'SOL')!
const staked = await una.stake({ solver: solverAddress, bondMint: sol.mint, amount: '2000000000' })
console.log(`staked in transaction ${staked.signature}`)una is the bound client from createUna, made with the operator's key.
The bond tokens are SOL and liquid staking tokens, valued in SOL at the stake pool’s own rate. una.protocol() returns the list as bondMints. Stake behind a solver covers the instruction, its shares and its errors in full, and the solver's page is where stakers find the solver and read its record.
Free and locked bond
The program counts bond in lamports. When a clearing is posted it values each bond token the solver holds at that moment and takes off what is already spoken for:
total = sum over bond tokens of floor(pool amount * stake pool lamports / stake pool token supply) free = total - bond_locked_lamports - pending_unstake_lamports
SOL counts one for one. A liquid staking token counts at its stake pool's own rate, read from the pool's account in the same instruction. If the subtraction would go below zero, free bond is zero.
Bond moves between the two states with the batch:
| Moment | What changes |
|---|---|
clear_batch is accepted | bond_locked_lamports rises by the batch's value moved. |
prove_batch verifies | It falls by the same amount. |
slash_batch after a missed proof window | It falls by the same amount, and that much of the staked tokens moves to the batch's cover. |
A staker sends request_unstake | pending_unstake_lamports rises by the value of the shares leaving, at once. |
The staker sends withdraw_stake | It falls again, and the pool amount falls with it. |
How much free bond a batch needs
clear_batch requires
free >= value_moved
value_moved is everything the batch's orders offer plus everything its pairs pay out, in lamports at the posted prices. The bond invariant has the formula and what a stake carries per proof window.
The errors of clear_batch that come from the bond:
| Error | Raised when |
|---|---|
InsufficientBond | Free bond is below the batch's value moved. |
InvalidStakePool | The solver holds a liquid staking token and the transaction does not pass that token's stake pool account, or passes another account in its place. |
Unauthorized | The solver account is not active. |
Read the solver
SOLVER_KEYPAIR=~/solver-operator.json \
RPC_URL=https://your-rpc-endpoint \
una-solver statusstatus sends nothing. It reads the chain and prints one line each:
| Line | Holds |
|---|---|
program | The program id the node is pointed at. |
operator | The operator's address. |
solver_pda | The solver's address. |
slot | The current slot. |
protocol | The open batch's number, the next batch to clear, the count of tokens and pairs, the band and the clearing fee in basis points. Before the program is live it reads waiting (Config account not initialized). |
solver | active, commission_bps, cleared, proven, slashes and locked_lamports. Before registration it reads not registered. |
accrued_commission | The commission waiting to be claimed, per token index, in that token's atoms. Printed when a balance is above zero. |
Free bond is on the solver's page in the app, as Bond free beside Bond locked, and in the API:
const solver = await una.solver(solverAddress)
console.log(`free ${solver.bondFreeLamports} lamports, locked ${solver.bondLockedLamports} lamports, commission ${solver.commissionBps} bps`)SolverDetail also carries the solver's recent batches with their proof times, its slashes and the bond tokens it accepts.