> ## 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.

# Contracts

> Overview of Reiy Protocol Move modules, on-chain objects, and responsibilities.

# Contracts

Reiy uses a **hybrid** architecture: quote collection, solve orchestration, scoring, and winner selection run off-chain in the **Execution Coordinator** (Fisherman); the Move contracts on Sui escrow user funds, verify the Coordinator's signed solution, enforce each user's protection, and split fees. Move 2024, DeepBook v3.

## Core responsibilities

| Area | Responsibility |
| - | - |
| Intent escrow | Lock user sell tokens until cancellation or valid settlement. |
| SBBO admission | Reject intents whose `min_amount_out` falls below the DeepBook-mid admission floor. |
| Solver registry | Track solver registration and stake-based active status. |
| Certificate verification | Verify the Coordinator's Ed25519 signature, solver identity, epoch, token types, and expiry. |
| Settlement | Enforce protected minimum, exact payout, partial-fill rules, fee split, and per-intent atomicity. |
| Fee vaults | Accumulate the protocol's fee share per token. |

## Modules

| Module | Role |
| - | - |
| `config` | `GlobalConfig` (shared) + `AdminCap` (owned): parameters, ACL, allowlists, Coordinator key. |
| `intent_book` | `Intent<Sell, Buy>` shared object: SBBO-gated creation, escrow, partial-fill, cancel. |
| `auction` | Slim `AuctionState` (shared): epoch counter, per-epoch partial-fill set, fee totals. |
| `settlement` | Certificate verification + per-intent settlement, fee split, user protection. |
| `solver_registry` | `SolverRegistry<Stake>` (shared): solver stake + active status. |
| `fee_vault` | `FeeVault<T>` (shared): per-token protocol fee balance. |
| `price_adapter` | DeepBook mid-price reader + SBBO helper math. |
| `events`, `math`, `types` | Event structs, fixed-point helpers, `PairKey`. |

## On-chain objects

| Object | Kind | Notes |
| - | - | - |
| `GlobalConfig` | shared | One per deployment. All mutations require `AdminCap`. |
| `AdminCap` | owned | Held by the deployer; transfer to a multisig for mainnet. |
| `AuctionState` | shared | Protocol state; pinned by `SolutionMessage.protocol_state_id`. |
| `SolverRegistry<Stake>` | shared | Solver stake; `Stake` is the eligibility coin type. |
| `FeeVault<T>` | shared | Canonical fee sink for token `T`, registered in config. |
| `Intent<Sell, Buy>` | shared | Holds escrowed `Sell`; source of truth for one user order. |

## Settlement flow (one PTB)

The winning solver settles in a single programmable transaction block:

1. `verify_solution`: checks the signature, sender, epoch, token types, and expiry, then returns a `SolutionAuth` hot-potato.
2. `take_authorized_intent_full | take_authorized_intent_partial`: per intent, in certificate order, receive the escrowed sell coin.
3. Source liquidity and produce the `payout: Coin<Buy>`.
4. `settle_intent`: deliver the payout. The contract splits fees, pays the user net, and pays the solver fee share.

There is **no on-chain settlement phase gate**; `auction::phase_code()` is a compatibility getter that always returns `0`. The contract enforces epoch safety only: the signed epoch must equal the live `AuctionState` epoch and each intent's `target_epoch` must match.

## Events

`IntentCreatedEvent`, `IntentCancelledEvent`, `IntentUpdatedEvent`, `EpochAdvancedEvent`, `SolutionAuthorizedEvent`, `SettlementEvent`, `SettlementFeeChargedEvent`, `BatchFeeSummaryEvent`, `SolverFeePaidEvent`, `ProtocolFeeCollectedEvent`, `SolverRegisteredEvent`, `SolverDeregisteredEvent`, `FeeVaultRegisteredEvent`, `ExecutionCoordinatorUpdatedEvent`, `ConfigUpdatedEvent`, `RoleGrantedEvent`, `RoleRevokedEvent`.

## Deployment addresses

Deployment addresses and verified source references are published with each testnet or mainnet release. See [Smart Contracts](/resources/smart-contracts) for the current canonical references.

<CardGroup cols={2}>
  <Card title="Definitions" href="/reiy-protocol/reference/core/definitions">
    Look up contract-facing protocol terms.
  </Card>

  <Card title="Scoring and ranking" href="/reiy-protocol/reference/core/scoring-and-ranking">
    Review off-chain validation and winner selection.
  </Card>
</CardGroup>


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