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

# Solution Validation and Ranking

> How Fisherman validates solver responses, ranks winners, and hands settlement to the contracts.

# Solution Validation and Ranking

The current Reiy runtime ranks solver solutions in Fisherman, not in an on-chain allocation-selection phase. Fisherman validates solver responses, picks the highest valid score, signs a certificate, and asks the winning solver to settle on-chain.

## Solve request

For each auction round, Fisherman sends enabled solvers a `SolveRequest` containing:

* `auctionId`
* `sellType` and `buyType`
* `epoch`
* `deadlineMs`
* `maxBatchSize`
* `feeConfig`
* the grouped open intents

Compatible intents are grouped by `sellType`, `buyType`, and `targetEpoch`.

## Solve response

A solver returns a `SolveResponse` with:

| Field | Meaning |
| - | - |
| `solver` | Solver identity. |
| `solutionId` | Solver-provided solution id. |
| `sellType`, `buyType` | Directed token pair for the solution. |
| `epoch` | Must match the request epoch. |
| `intentIds` | Intents covered by the solution. |
| `fills` | Fill amount per intent. |
| `grossPayouts` | Gross payout per intent before protocol fees. |
| `protectedMins` | Minimum payout each intent must remain above. |
| `score` | Solver-declared score used for ranking. |
| `expiresAtMs` | Solution expiry. |
| `counter` | Optional opposite-direction draft for CoW-cross settlement. |

## Fisherman validation

Fisherman rejects a solution before ranking if:

* It is empty or exceeds `maxBatchSize`.
* The token pair does not match the auction round.
* The epoch does not match.
* Vector lengths do not match.
* The solution has already expired.
* An intent id is duplicated or not in the round.
* A covered intent is not open.
* A fill is zero or greater than the intent sell amount.
* `grossPayout < protectedMin`.
* `protectedMin < intent.minAmountOut`.
* `score` is not a valid integer string.

Invalid solver replies are stored as invalid solution records for observability.

## Winner ranking

Fisherman sorts valid solutions by score:

$$
\begin{aligned}
winner = \operatorname{arg\,max}_{valid\ solutions} score
\end{aligned}
$$

If scores tie, Fisherman breaks the tie deterministically by solver endpoint id.

The current implementation does not use on-chain PairBenchmark or Allocation objects for winner selection. It also does not expose an on-chain bid or selection phase gate.

## Certificate signing

After ranking, Fisherman signs a certificate for the winning solver. The certificate binds:

* protocol state id
* config id
* coordinator key version
* live epoch
* solution id
* solver address
* token types
* intent ids
* fills
* gross payouts
* protected minimums
* expiry

For a CoW-cross solution, Fisherman can sign a linked counter certificate so both directions are submitted together.

## Contract settlement checks

At settlement, the Move contracts verify:

* the transaction sender is the signed solver
* the solver is registered and has at least `min_solver_stake`
* the coordinator signature is valid
* the certificate has not expired
* the certificate epoch is the live `AuctionState.current_epoch`
* each intent target epoch matches the certificate epoch
* intents are not expired and have not already been partial-filled in the same epoch
* `fill` is valid for full or partial settlement
* `protectedMin >= intent.minAmountOut`
* `protectedMin >= m_eff` for the actual fill
* delivered payout equals the signed `grossPayout`
* payout after volume fee remains at or above `protectedMin`

If any check fails, the PTB aborts and escrow does not move.

## Related Topics

<CardGroup cols={2}>
  <Card title="Auction rounds and certificates" href="/reiy-protocol/concepts/how-it-works/auction-rounds-and-certificates">
    Current coordination lifecycle.
  </Card>

  <Card title="Fee formulas" href="/reiy-protocol/reference/core/fee-formulas">
    Settlement fee calculation.
  </Card>
</CardGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.