> ## Documentation Index
> Fetch the complete documentation index at: https://developer.bron.org/llms.txt
> Use this file to discover all available pages before exploring further.

# Solver Guide

## Who is a Solver?

A Solver is an independent participant that fulfils user orders during the on-chain auction.
Solvers compete by quoting prices, deliver assets on the quote network, and earn order fees.

## Becoming a Solver

Registration is a two-step process: the solver locks BRON insurance and submits a request, then the Bron DAO accepts it.

### 1. Submit a registration request

Approve BRON for the `SolverRegister` contract, then call:

```solidity theme={"system"}
bronToken.approve(solverRegisterAddress, insuranceAmount);
SolverRegister.registerSolver(address insuranceTokenAddress, uint256 insuranceAmount);
```

Currently the only supported insurance token is **BRON**. After the call, the solver status is `PENDING` and BRON tokens are locked. While in `PENDING`, the solver can call `cancelSolverRegistration()` to back out and reclaim the deposit.

### 2. DAO approval

The Bron DAO calls `registerSolverResponse(solver, isAccepted)`. On acceptance, status becomes `ACTIVE` and the solver can react to orders. Until that point, `solverReact` reverts.

### 3. Top up / withdraw insurance

```solidity theme={"system"}
SolverRegister.addSolverInsuranceAmount(uint256 amount);                   // top up
SolverRegister.requestWithdrawSolverInsuranceAmount(uint256 amount);       // request withdrawal
SolverRegister.claimWithdrawSolverInsuranceAmount();                       // claim after withdrawalDelay
```

Withdrawal is bounded by `getAvailableAmountToWithdraw(solver)` — you cannot withdraw funds currently locked against active orders.

***

## How insurance works

Insurance is the solver's collateral against failure to deliver. The amount of order volume a solver can react on is calculated as:

```
availableOperationAmount = insuranceAmount × haircut / 100 − activeLocks
```

`haircut` is configured per insurance token. Haircut and liquidation premium values are not hard-coded in the docs because the DAO can adjust them — read the current values via `InsuranceManager.getInsuranceTokens(insuranceTokenAddress)`.

If the solver fails to deliver in time, oracles trigger liquidation. A backup solver picks up the order and is rewarded a **liquidation premium** taken from the original solver's insurance. Once the original solver's insurance is exhausted, status changes to `INACTIVE` automatically.

***

## Reacting to orders

### `solverReact`

```solidity theme={"system"}
function solverReact(
    string memory _orderId,
    string memory _solverAddressOnBaseChain,
    string memory _solverSettlementFromAddress,
    uint256 _price_e18
) external;
```

| Param                          | Description                                                                                       |
| ------------------------------ | ------------------------------------------------------------------------------------------------- |
| `_orderId`                     | Order id                                                                                          |
| `_solverAddressOnBaseChain`    | Address where the user will send funds on the **base** network                                    |
| `_solverSettlementFromAddress` | Address from which the solver will send funds on the **quote** network                            |
| `_price_e18`                   | Quoted price, scaled by 1e18. Must be `>= maxPrice_e18` and strictly better than the current best |

Solvers can react during `USER_INITIATED` and `AUCTION_IN_PROGRESS` states, until `auctionDuration` elapses. The contract enforces address bindings:

* A `_solverSettlementFromAddress` is bound to one solver per `(quoteNetworkId, address)` while there are active orders — prevents another solver from frontrunning your settlement address.
* A solver can have only **one** active settlement-from address per quote network — rotation is rejected.

### Settling the order

Once the order moves to `WAIT_FOR_SOLVER_TX`, send funds to the user on the quote network and record the tx hash:

```solidity theme={"system"}
function setSolverTxOnQuoteNetwork(string memory _orderId, string memory _solverTxHash) external;
```

Only the solver address registered with the order (`order.solver == msg.sender`) can call this — settlement is **not** "from any address". The `_solverTxHash` must be unique on that quote network.

After `setSolverTxOnQuoteNetwork`, oracles confirm the transaction on-chain. On a positive quorum the order moves to `COMPLETED`.

***

## Liquidation

If the solver fails to deliver before the configured deadline, oracles can move the order to `TO_BE_LIQUIDATED`. A new solver picks the order up by reacting again — the new solver is paid a **liquidation premium** from the original solver's insurance.

The original solver:

* Loses the locked operation amount + premium from insurance.
* Stays `ACTIVE` while insurance > 0; goes `INACTIVE` automatically once insurance is fully drained.
* Can be `SUSPENDED` and ultimately `kickOracle`- removed by the DAO (`updateSuspendSolverStatus`, `kickSolver`) for repeated failures.