Run a solver

Run the node

Build una-solver, configure it, and follow what it does with each sealed batch.

una-solver is the solver's node: one binary that follows sealed batches, solves each one, posts the clearing and proves it. It needs a registered solver with free bond (Register and bond), a Solana RPC endpoint, the Una API and a prover (Proving).

Build

The node ships as source in the Una repository: the Rust crate backend/solver/, with its Dockerfile. It depends on the clearing crate beside it, crates/clearing, the same code the program and the guest run. Proving is behind two features, one for each prover mode:

Shell
cd backend/solver
cargo build --release --features native-gnark   # for PROVER=cpu: links gnark in, needs Go at build
cargo build --release --features prove          # for PROVER=network

The binary is solver/target/release/una-solver. A binary built with neither feature registers, reads status and claims commission, and it refuses to prove: PROVER=cpu and PROVER=network both return an error that names the missing feature.

The source also carries a Dockerfile that builds the binary with --features prove, the prover network build, on rust:1.99-bookworm, and copies the guest in. Its build context is the repository's backend/ folder:

Shell
docker build -f solver/Dockerfile -t una-solver .

The image sets GUEST_ELF_PATH=/app/guest/elf/una-guest and PROVER=network, and its command is una-solver run.

Configure

Every setting is an environment variable with a flag of the same meaning. Flags go before the command: una-solver --rpc-url https://your-rpc-endpoint run.

VariableFlagDefaultMeaning
SOLVER_KEYPAIR--solver-keypairnone, requiredThe operator's key. It signs and pays for every transaction the node sends.
RPC_URL--rpc-urlset itThe Solana JSON-RPC endpoint.
API_URL--api-urlset itThe Una API. The node reads each batch's input records from it.
PROGRAM_ID--program-idBAP8m3hSZnrkpJij3Pmya12LvKNLCseq8c441qHFQB2FThe Una program.
PROVER--proverset itcpu or network. run requires it. Case and surrounding spaces are ignored.
NETWORK_PRIVATE_KEY--network-private-keynoneThe prover network key. Required when PROVER=network.
GUEST_ELF_PATH--guest-elf-path../guest/elf/una-guestThe guest program's ELF file, read at each proof.
SOLVER_STATE_DIR--state-dirsolver-stateThe folder where the node saves the state and the result of each batch it clears, and the input and state of a batch it could not solve. A relative path is taken from the folder the node is started in.

SOLVER_KEYPAIR takes any of three forms: a path to a keypair file, a JSON array of 64 bytes, or a base58 string of the 64 bytes. A value that starts with [ is read as the array. A value of 80 characters or more with no /, \ or . in it is read as base58. Anything else is read as a path, and the file may hold either form.

The Una API is at https://api.una.markets.

Commands

CommandOptionDoes
una-solver register--commission-bps, default 500Sends register_solver. See Register and bond.
una-solver statusPrints the protocol's batch counters, the solver's record and its accrued commission. See Read the solver.
una-solver run--poll-ms, default 1000Runs the loop below until the process is stopped.
una-solver claim-commission--token, a token indexClaims the operator's accrued commission in every token, or in the one named. See Claim the commission.

Start

Shell
SOLVER_KEYPAIR=~/solver-operator.json \
RPC_URL=https://your-rpc-endpoint \
API_URL=https://api.una.markets \
PROVER=network \
NETWORK_PRIVATE_KEY=your-prover-network-key \
GUEST_ELF_PATH=./guest/elf/una-guest \
una-solver run

The node stops at once, with the reason, if the program id is not a valid address or the keypair does not load. run also stops at once, with exit code 1, when PROVER is not set or is not cpu or network.

What the node does each pass

Every --poll-ms milliseconds the node reads the program's Config account at confirmed commitment. If the account does not exist yet it waits and reads again. Otherwise it walks batch ids in order, from four before next_clear_batch_id (never below 1) up to the batch before the open one, and handles each in turn. A pass handles one batch at a time, clearing and proving it before it moves to the next.

  1. Read the solver and the batch

    It reads its own solver account and the batch account. A batch that is not Sealed or Cleared is passed over, and so is one whose account has been closed.

  2. Read the input and check it

    It requests GET /v1/batches/{id}/input from the API, which returns the batch's place and cancel records in the order they were folded. The node folds them itself, from sha256("una/batch" || batch_id), and compares the result with the batch's input_hash on chain. Only an input that hashes to the on-chain value is solved. When the two differ the node reports it and takes the batch up again on the next pass.

  3. Read the state

    For a sealed batch it reads the Token account of every batch token, and of wSOL, for the last proven prices. It reads the Pair account of every pair whose two tokens are both in that set, which is the set clear_batch requires. With the band and the clearing fee from Config, these make the state, and its SHA-256 is the state hash.

  4. Solve and check

    solve searches the price vector inside each token's band and the fill fractions for rationed directions. The node then runs check on the result, the same function the guest runs. A result that check refuses is never posted. When solve finds no result, the node keeps the batch in a file: see When a batch cannot be solved.

  5. Send clear_batch

    The transaction carries the state hash, the batch tokens with a price and a fee each, the fill fractions and the number of pairs. Its accounts are the batch's Token accounts, its Pair accounts, and the stake pool of each liquid staking token the solver holds. When it confirms, the batch is Cleared, the solver's bond is locked behind it, and the proof deadline is set.

  6. Publish the state

    The node wrote the state it solved against and the result to batch-<id>.json in SOLVER_STATE_DIR before it sent the clearing. Once the clearing confirms it posts both to the API at POST /v1/batches/{id}/state.

  7. Prove

    The node reads the batch again. If it is cleared and its solver is this node's, the node proves the clearing with the records, the state and the result it cleared with. Proving has the modes.

  8. Send prove_batch

    The transaction carries the proof. Its accounts are the batch's Token accounts, then for each token with a protocol share to pay: the mint, the token's vault, the fee recipient's token account and the token program. When it confirms, the batch is Proven, the bond is free, and the fee is credited. See Commission and payouts.

The state a proof is made from

clear_batch moves the batch's pairs, so after a clearing the chain no longer holds the state it was solved against. The proof is made from that earlier state, and the node keeps it in two places.

Before it sends a clearing, the node writes the state and the result to batch-<id>.json in SOLVER_STATE_DIR, creating the folder if it is not there. A clearing refused with StateHashMismatch is solved again and the file is written again. When the clearing confirms, the node posts both to POST /v1/batches/{id}/state, and it posts them again each time it proves from the file. The API stores them when their hashes equal the batch's state_hash and result_hash on chain, and serves them to anyone at GET /v1/batches/{id}/state.

A batch the node finds already cleared by its own solver, as it does after a restart, goes straight to the proving step. The node takes the state and the result from the file, or from the API when the file is not there, checks their hashes against the batch account, and proves them. It does not solve a cleared batch again. When neither holds them, or the hashes differ, it logs solver_batch_error for the batch and sends nothing.

How a transaction is sent

Every transaction goes the same way:

  1. The node simulates it with a compute limit of 1,400,000 units. A simulation that fails stops there, and nothing is sent.
  2. It sets the compute limit to the units the simulation used plus 20%, between 50,000 and 1,400,000, and a compute unit price of 1,000 micro-lamports.
  3. It sends the transaction once, without preflight, and asks for its status every 500 ms for up to 60 seconds.
  4. confirmed or finalized is success. An error on chain, or 60 seconds with neither, is a failure.

The operator's key is the fee payer.

What it logs

Events are single lines of JSON. Progress goes to standard output:

EventFieldsWhen
solver_startedoperator, prover, stateDirOnce, when run starts.
batch_clearedbatchId, sig, cu, attemptA clear_batch transaction confirmed. cu is the compute units the simulation used. attempt is 1, 2 or 3.
state_hash_mismatch_retrybatchId, attemptThe program refused a clearing with StateHashMismatch.
batch_provenbatchId, sig, cu, proverA prove_batch transaction confirmed.

Failures go to standard error:

EventFieldsWhen
solver_batch_errorbatchId, errorAny step for one batch failed. error is the reason, with the program's logs when a simulation failed.
publish_state_errorbatchId, errorThe post of a cleared batch's state to the API failed. The file is already written, and the node goes on to prove.
config_decode_errorerrorThe Config account did not decode.
rpc_errorerrorThe RPC endpoint did not answer the Config read.

No failure stops the loop. The node logs it, goes on to the next batch, and comes back to this one on the next pass while it is still in range.

When a batch cannot be solved

When solve returns no result for a sealed batch, the node writes what it was solving to unsolved-<id>.json in SOLVER_STATE_DIR: a JSON array of two items, the batch's input records and the state it read, in the clearing crate's own types. The pair can be run through the crate's solve again as it stands.

The node sends nothing for the batch and logs solver_batch_error with solve rejected and the crate's reason. It solves the batch again on each later pass, against the state as it then is, and writes the file again each time it fails. The batch stays sealed until a solver clears it or it is rolled.

When another solver clears first

The first clearing the program accepts is the batch's clearing. If another solver's lands while this node is solving, the batch is no longer sealed and the simulation of this node's clear_batch fails with BatchAlreadyCleared. Nothing is sent and no bond is locked. The node logs one solver_batch_error for the batch. On later passes it finds the batch cleared by another solver and passes over it: it proves only batches its own solver cleared.

When the state hash no longer matches

A position added or removed between the node's read and its transaction changes the pair, so the live state hashes differently from the one the node solved against. The program refuses with StateHashMismatch, error 6009. The node logs state_hash_mismatch_retry, reads the state again, solves again and sends again, up to three attempts in one pass. After the third it logs solver_batch_error, and the next pass starts over with three more.

When a clear fails

clear_batch is refused in simulation, before anything is sent, when the program would refuse it:

ErrorRaised when
BatchNotSealedThe batch is still open, or rolled.
BatchAlreadyClearedThe batch is already cleared.
BatchAlreadyProvenThe batch is already proven.
BatchAlreadySlashedThe batch is slashed.
OutOfOrderBatchThe batch is not next_clear_batch_id. Sealed batches clear in order.
StateHashMismatchThe state the program hashes differs from the hash passed.
PriceOutOfBandA price is zero or outside its token's band.
InsufficientBondThe solver's free bond is below the batch's value moved.
UnauthorizedThe solver account is not active.
InvalidStakePoolA stake pool account for a liquid staking token in the bond is missing or is another account.
InvalidBatchAccountsThe token or pair accounts are incomplete, out of order or not the program's: prices and fees do not match the token count, the tokens are not strictly ascending, a token of the batch's orders is left out, or the pairs are not exactly the pairs between the batch tokens.
InvalidIndexA token index is 32 or above.
CapacityExceededMore than 16 batch tokens or more than 16 fill fractions.
InvalidConfigA fill fraction is above FILL_ONE, or the fractions are not in ascending order of sell and buy token.
MathOverflowAn intermediate value does not fit.

With InsufficientBond the batch stays sealed for a solver with more free bond, and this node tries it again each pass until it is cleared or rolled.

A clear that was sent and did not confirm in 60 seconds is logged as a failure too. Its state is already in the state folder. On the next pass the node reads the batch: if the transaction landed after all, the batch is cleared by this solver, and the node proves it from the file and publishes the state then.

When a proof transaction fails

The node keeps no proof between passes. If proving fails, or prove_batch fails or does not confirm, it logs solver_batch_error and the batch stays cleared with the bond locked. On each later pass in which the batch is still within the four ids before next_clear_batch_id, the node proves it again from the saved state and sends again.

ErrorRaised when
BatchNotClearedThe batch is open, sealed or rolled.
BatchAlreadyProvenThe batch is already proven.
BatchAlreadySlashedThe batch is slashed.
ProofWindowExpiredThe current slot is past the batch's proof_deadline_slot.
InvalidProofThe proof does not verify against the batch's public values.
InvalidBatchAccountsThe Token accounts are missing or are not the batch's tokens in order.
InvalidFeeRecipientAtaThe accounts for a token's protocol share are missing, or are not that token's mint, vault and token program and the fee recipient's associated token account.

After ProofWindowExpired the batch can only be slashed. Proving has the deadline.