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:
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=networkThe 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:
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.
| Variable | Flag | Default | Meaning |
|---|---|---|---|
SOLVER_KEYPAIR | --solver-keypair | none, required | The operator's key. It signs and pays for every transaction the node sends. |
RPC_URL | --rpc-url | set it | The Solana JSON-RPC endpoint. |
API_URL | --api-url | set it | The Una API. The node reads each batch's input records from it. |
PROGRAM_ID | --program-id | BAP8m3hSZnrkpJij3Pmya12LvKNLCseq8c441qHFQB2F | The Una program. |
PROVER | --prover | set it | cpu or network. run requires it. Case and surrounding spaces are ignored. |
NETWORK_PRIVATE_KEY | --network-private-key | none | The prover network key. Required when PROVER=network. |
GUEST_ELF_PATH | --guest-elf-path | ../guest/elf/una-guest | The guest program's ELF file, read at each proof. |
SOLVER_STATE_DIR | --state-dir | solver-state | The 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
| Command | Option | Does |
|---|---|---|
una-solver register | --commission-bps, default 500 | Sends register_solver. See Register and bond. |
una-solver status | Prints the protocol's batch counters, the solver's record and its accrued commission. See Read the solver. | |
una-solver run | --poll-ms, default 1000 | Runs the loop below until the process is stopped. |
una-solver claim-commission | --token, a token index | Claims the operator's accrued commission in every token, or in the one named. See Claim the commission. |
Start
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 runThe 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.
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.
Read the input and check it
It requests
GET /v1/batches/{id}/inputfrom the API, which returns the batch's place and cancel records in the order they were folded. The node folds them itself, fromsha256("una/batch" || batch_id), and compares the result with the batch'sinput_hashon 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.Read the state
For a sealed batch it reads the
Tokenaccount of every batch token, and of wSOL, for the last proven prices. It reads thePairaccount of every pair whose two tokens are both in that set, which is the setclear_batchrequires. With the band and the clearing fee fromConfig, these make the state, and its SHA-256 is the state hash.Solve and check
solvesearches the price vector inside each token's band and the fill fractions for rationed directions. The node then runscheckon the result, the same function the guest runs. A result thatcheckrefuses is never posted. Whensolvefinds no result, the node keeps the batch in a file: see When a batch cannot be solved.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
Tokenaccounts, itsPairaccounts, 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.Publish the state
The node wrote the state it solved against and the result to
batch-<id>.jsoninSOLVER_STATE_DIRbefore it sent the clearing. Once the clearing confirms it posts both to the API atPOST /v1/batches/{id}/state.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.
Send prove_batch
The transaction carries the proof. Its accounts are the batch's
Tokenaccounts, 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:
- The node simulates it with a compute limit of 1,400,000 units. A simulation that fails stops there, and nothing is sent.
- 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.
- It sends the transaction once, without preflight, and asks for its status every 500 ms for up to 60 seconds.
confirmedorfinalizedis 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:
| Event | Fields | When |
|---|---|---|
solver_started | operator, prover, stateDir | Once, when run starts. |
batch_cleared | batchId, sig, cu, attempt | A clear_batch transaction confirmed. cu is the compute units the simulation used. attempt is 1, 2 or 3. |
state_hash_mismatch_retry | batchId, attempt | The program refused a clearing with StateHashMismatch. |
batch_proven | batchId, sig, cu, prover | A prove_batch transaction confirmed. |
Failures go to standard error:
| Event | Fields | When |
|---|---|---|
solver_batch_error | batchId, error | Any step for one batch failed. error is the reason, with the program's logs when a simulation failed. |
publish_state_error | batchId, error | The 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_error | error | The Config account did not decode. |
rpc_error | error | The 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:
| Error | Raised when |
|---|---|
BatchNotSealed | The batch is still open, or rolled. |
BatchAlreadyCleared | The batch is already cleared. |
BatchAlreadyProven | The batch is already proven. |
BatchAlreadySlashed | The batch is slashed. |
OutOfOrderBatch | The batch is not next_clear_batch_id. Sealed batches clear in order. |
StateHashMismatch | The state the program hashes differs from the hash passed. |
PriceOutOfBand | A price is zero or outside its token's band. |
InsufficientBond | The solver's free bond is below the batch's value moved. |
Unauthorized | The solver account is not active. |
InvalidStakePool | A stake pool account for a liquid staking token in the bond is missing or is another account. |
InvalidBatchAccounts | The 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. |
InvalidIndex | A token index is 32 or above. |
CapacityExceeded | More than 16 batch tokens or more than 16 fill fractions. |
InvalidConfig | A fill fraction is above FILL_ONE, or the fractions are not in ascending order of sell and buy token. |
MathOverflow | An 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.
| Error | Raised when |
|---|---|
BatchNotCleared | The batch is open, sealed or rolled. |
BatchAlreadyProven | The batch is already proven. |
BatchAlreadySlashed | The batch is slashed. |
ProofWindowExpired | The current slot is past the batch's proof_deadline_slot. |
InvalidProof | The proof does not verify against the batch's public values. |
InvalidBatchAccounts | The Token accounts are missing or are not the batch's tokens in order. |
InvalidFeeRecipientAta | The 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.