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

# Architecture

> How Reiy's on-chain contracts and the Fisherman coordinator fit together, with the full set of flow diagrams.

# Architecture

Reiy runs a hybrid system. The **Reiy Protocol** contracts on Sui hold custody and enforce every user protection. **Fisherman**, the off-chain Execution Coordinator, runs solver competition and signs the certificate that authorizes settlement. Solvers act as a meta aggregator, sourcing liquidity across Sui venues to fill intents.

This page collects the diagrams for the whole system in one place.

## System overview

```mermaid theme={null}
flowchart LR
    User["Trader / App"]
    Coord["Fisherman<br/>(Execution Coordinator)"]
    Indexer["Reiy Indexer"]
    Solvers["Solvers"]
    Venues["Sui liquidity<br/>DeepBook · Cetus · inventory · CoW matches"]
    Contracts["Reiy Protocol<br/>(Move contracts on Sui)"]

    User -->|submit intent| Contracts
    Contracts -->|intent events| Indexer
    Indexer -->|open intents| Coord
    User -->|quote request| Coord
    Coord <-->|quote / solve| Solvers
    Coord -->|signed certificate| Solvers
    Solvers -->|source liquidity| Venues
    Solvers -->|settle| Contracts
    Contracts -->|net payout| User
```

Custody and protection live entirely in the contracts. Fisherman coordinates but never holds funds, and solvers can only move escrow by passing the contract's checks.

## Quote flow

A quote is a pre-trade price estimate. It does not move funds.

```mermaid theme={null}
sequenceDiagram
    autonumber
    participant App
    participant F as Fisherman
    participant S as Solvers
    App->>F: quote request
    F->>F: normalize request
    F->>S: fan out to enabled solvers
    S-->>F: quotes (within the response window)
    F->>F: validate and rank by economics
    F-->>App: best quote and all results
```

## Auction and settlement flow

The end-to-end path from an open intent to a settled trade.

```mermaid theme={null}
sequenceDiagram
    autonumber
    participant I as Indexer
    participant F as Fisherman
    participant S as Solvers
    participant W as Winning solver
    participant C as Reiy contracts
    participant U as Trader
    I->>F: open intents
    F->>F: group into an auction round
    F->>S: solve request
    S-->>F: solutions (fills, payouts, score)
    F->>F: validate and pick the highest score
    F->>F: sign settlement certificate
    F->>S: notify winner and losers
    F->>W: settle request
    W->>C: submit settlement (one transaction)
    C->>C: verify certificate and floors
    C->>U: net payout
    C->>W: solver fee share
```

## Settlement transaction

The winning solver settles in a single Sui programmable transaction block. Every check must pass or the whole transaction aborts and escrow never moves.

```mermaid theme={null}
flowchart TD
    A[Verify certificate<br/>signature, solver, epoch, expiry] --> B{Valid?}
    B -- No --> X[Abort: escrow stays put]
    B -- Yes --> C[Take escrowed intent<br/>full or partial]
    C --> D[Source liquidity]
    D --> E[Deliver payout]
    E --> F{Clears protected minimum<br/>after the volume fee?}
    F -- No --> X
    F -- Yes --> G[Split fees]
    G --> H[Trader receives net payout]
    G --> I[Solver receives fee share]
```

## Auction round lifecycle

How Fisherman tracks a round off-chain.

```mermaid theme={null}
stateDiagram-v2
    [*] --> collecting
    collecting --> solving: collection window closes
    solving --> solved: valid winner chosen
    solving --> failed: no valid solution
    solved --> settling: certificate issued
    settling --> settled: settlement confirmed
    settling --> expired: deadline missed
    collecting --> expired: round deadline missed
    expired --> collecting: retry
    failed --> collecting: retry
```

## Intent lifecycle

How a single intent object moves through its states on-chain.

```mermaid theme={null}
stateDiagram-v2
    [*] --> Open
    Open --> PartialFill: partial settlement
    PartialFill --> PartialFill: another partial fill
    Open --> Filled: full settlement
    PartialFill --> Filled: final fill
    Open --> Cancelled: owner cancels
    PartialFill --> Cancelled: owner cancels residual
    Open --> Expired: deadline passes
    PartialFill --> Expired: deadline passes
    Filled --> [*]
    Cancelled --> [*]
    Expired --> [*]
```

## Related Topics

<CardGroup cols={2}>
  <Card title="Fisherman" href="/reiy-protocol/concepts/introduction/fisherman">
    What the coordinator owns and does not own.
  </Card>

  <Card title="Contracts" href="/reiy-protocol/reference/core/contracts">
    The Move modules behind these flows.
  </Card>
</CardGroup>


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