# Changelog Source: https://docs.reiy.finance/changelog Public product, protocol, and documentation change notes. This page tracks public documentation, product, and protocol changes. Internal implementation notes should be summarized here only when they affect users, solvers, app developers, or operators. ## Unreleased * Restructured docs v2 around Welcome, Reiy Protocol, Concepts, Tutorials, Technical Reference, and Integrate. * Added focused category landing pages for reader paths. * Linked API Reference to the live Fisherman docs and OpenAPI spec. * Added Smart Contracts and API Reference resource pages. * Consolidated orderbook API into Fisherman; removed deprecated standalone service. ## Related Topics # Welcome Source: https://docs.reiy.finance/index Documentation for Reiy Finance, an intent-based meta DEX aggregator on Sui.

# Reiy Finance Reiy Finance is an intent-based meta DEX aggregator on Sui. Instead of picking a pool or a route, you state the outcome you want, and solvers compete to fill it by aggregating liquidity across every Sui venue. The result is best execution with custody and a guaranteed minimum enforced on-chain. Reiy is built from two layers that work together. ## What is Reiy Protocol? Reiy Protocol is the on-chain layer: a set of Move contracts on Sui that hold your funds in escrow, admit each intent against a fair market floor, verify the winning solution, and settle it atomically. Custody and every user protection live here, so safety never depends on an off-chain operator. ## What is Fisherman? Fisherman is the off-chain Execution Coordinator. It reads open intents, groups them into auction rounds, asks solvers to compete, ranks their solutions, and signs a certificate that lets the winning solver settle. Fisherman orchestrates competition but holds no funds and cannot override the contracts. ## How to use these docs Reiy docs follow a question-oriented structure: * **Concepts** explain what something is (for example, intents or how settlement works). * **Tutorials** show how to do something (make a trade, run a solver). * **Technical Reference** holds exact details (definitions, formulas, contracts, APIs, architecture). * **Integrate** points developers and solvers to the right implementation path. State an intent and watch solvers compete to fill it. Join the network, implement the API, and settle winning rounds. Build on the intent interface with the contracts SDK. # LLMs.txt Source: https://docs.reiy.finance/llms How AI tools can use Reiy Finance documentation. # LLMs.txt Reiy Finance documentation is structured so AI tools can understand the protocol docs as source material. If your documentation deployment exposes `llms.txt` and `llms-full.txt`, use those files as machine-readable entry points. ## Available files | File | Description | | ---------------------------------- | ------------------------------------------------------------------------------ | | [`/llms.txt`](/llms.txt) | Structured overview with links to documentation pages. | | [`/llms-full.txt`](/llms-full.txt) | Complete documentation content in one file, when enabled by the docs platform. | ## Usage Add the docs URL or `llms.txt` URL to AI tools that support documentation sources. Use the compact file when you need navigation context, and the full file when you need the complete docs content. Start with the protocol overview. Use exact definitions, formulas, and API details. # Fees Source: https://docs.reiy.finance/reiy-protocol/concepts/fees A conceptual overview of Reiy Protocol fees. # Fees Reiy collects fees only when an intent settles successfully. If an intent expires, is cancelled, or does not fill, the trader does not pay settlement fees. ## What fees include | Component | Meaning | | ---------------- | ------------------------------------------------------------------------------------- | | Volume fee | A small percentage of trade amount. | | Surplus fee | A share of surplus above the user's protected minimum, capped by protocol parameters. | | Total fee cap | A hard cap limiting the total fee per intent. | | Solver fee share | The part of total fees paid to the solver; the rest goes to the protocol FeeVault. | Fees are deducted from the settlement payout. The protocol verifies protected minimums before settlement can complete. ## Typical defaults | Parameter | Default | | --------------------- | ---------------- | | Standard volume fee | 0.0075% of trade | | Correlated volume fee | 0.001% of trade | | Surplus fee | 10% of surplus | | Surplus fee cap | 0.1% of trade | | Max total fee | 0.15% of trade | | Solver fee share | 35% of total fee | For exact formulas and caps, use the technical reference. Review exact protocol fee calculations. See the trader-facing fee flow. # Auction Rounds and Certificates Source: https://docs.reiy.finance/reiy-protocol/concepts/how-it-works/auction-rounds-and-certificates How Fisherman groups intents, ranks solver solutions, and signs settlement certificates. # Auction Rounds and Certificates The current Reiy runtime uses a hybrid model. Fisherman coordinates solver competition off-chain, while the Move contracts verify the signed settlement certificate and protect user escrow on-chain. ## Auction rounds Fisherman builds auction rounds from open indexed intents. Compatible intents are grouped by `sellType`, `buyType`, and `targetEpoch`, then chunked up to `maxBatchSize`. Auction rounds move through these statuses: | Status | Meaning | | ------------ | -------------------------------------------------------------------- | | `collecting` | The round is gathering intents until the collection window matures. | | `solving` | Fisherman is calling enabled solver endpoints with a `SolveRequest`. | | `solved` | A valid winner was selected and a certificate was issued. | | `settling` | Fisherman has asked the winning solver to submit settlement. | | `settled` | Settlement succeeded or was recorded as complete. | | `expired` | The round or certificate missed its usable deadline. | | `failed` | Solving or settlement failed and operator retry may be needed. | ## Winner ranking For the current Fisherman implementation, each enabled solver returns a `SolveResponse` with intent ids, fills, gross payouts, protected minimums, score, and expiry. Fisherman validates the response shape, token pair, epoch, expiry, fill bounds, duplicate intent ids, user floors, and protected minimums. The highest valid `score` wins. If scores tie, Fisherman breaks the tie deterministically by solver endpoint id. ## Certificates After selecting a winner, Fisherman signs a settlement certificate. The certificate binds the protocol state id, config id, key version, current epoch, solution id, solver address, token types, intent ids, fills, gross payouts, protected minimums, and expiry. Settlement can happen immediately after a valid current-epoch certificate is issued. The contracts do not expose a separate on-chain bid, selection, or settlement phase gate. See what the contracts enforce at settlement. Read the current validation and ranking rules. # Epoch and Auction Lifecycle Source: https://docs.reiy.finance/reiy-protocol/concepts/how-it-works/epoch-lifecycle How Reiy separates contract epochs from Fisherman auction-round statuses. # Epoch and Auction Lifecycle Reiy has two timing layers: * **Contract epoch**: a simple counter on-chain. * **Fisherman auction round**: the off-chain coordination loop that moves from collecting intents to settling a winner. The contracts have no on-chain bidding or selection phases. The epoch is only a safety boundary, not an auction clock. ## Contract epoch An intent is created for the current epoch. A certificate is signed for that same epoch, and settlement rejects any intent whose epoch does not match. The epoch advances once a minimum collection time has passed, and a partially filled intent rolls its remainder into the next epoch. ## Fisherman auction round Off-chain, Fisherman runs each round through a short lifecycle: | Status | Purpose | | ---------- | ----------------------------------------------------------- | | collecting | Group open intents by pair and target epoch. | | solving | Ask enabled solvers to solve the round. | | solved | Store the winning solution and signed certificate. | | settling | Ask the winning solver to settle on-chain. | | settled | Mark the round complete once settlement is recorded. | | expired | Mark a stale round or certificate unusable. | | failed | Stop a bad round so automation does not keep re-solving it. | See the [round lifecycle diagram](/reiy-protocol/reference/architecture) for the full state machine. ## Round timing Because there are no on-chain phases, the timeline of a round is set entirely by Fisherman. These are the current testnet windows (each is configurable per deployment): | Window | Testnet | What it bounds | | --------------------- | ---------- | ----------------------------------------------------------------- | | Collection window | 6s | How long a round gathers intents before solving. | | Quote response window | 5s | How long pre-trade quotes are collected from solvers. | | Solver timeout | 4s | How long each solver has to answer a solve request. | | Certificate validity | 45s | How long the winner has to settle before the certificate expires. | | Batch size | 4 (max 10) | How many intents a round can hold. | On-chain, the only timing rule is that the epoch advances after a minimum collection time (10s by default). Exact configuration keys are listed in [Definitions](/reiy-protocol/reference/core/definitions). ## Why this matters Settlement can happen immediately after Fisherman issues a valid current-epoch certificate. Timing controls such as quote response windows, collection windows, certificate validity, retry policy, and settlement watcher polling all belong to Fisherman, not the contracts. Learn how rounds become settlement authority. Review the exact current validation rules. # Flow of an Intent Source: https://docs.reiy.finance/reiy-protocol/concepts/how-it-works/flow-of-an-intent How an intent moves from submission to settlement in Reiy Protocol. # Flow of an Intent An intent moves through Reiy as a protected object. The user locks funds, Fisherman coordinates solver competition, and settlement succeeds only if Move contracts verify the signed result. ```mermaid theme={null} flowchart LR A[Submit intent] --> B[Indexed] B --> C[Grouped into a round] C --> D[Solvers compete] D --> E[Winner gets a certificate] E --> F[Settled on-chain] ``` For the full set of sequence and state diagrams, see [Architecture](/reiy-protocol/reference/architecture). ## 1. The user submits an intent The user chooses the sell token, buy token, amount, minimum payout, deadline, slippage tolerance, and partial-fill preference. The app builds a transaction with the contracts SDK and submits it to the Reiy Move contracts. At admission, the protocol applies Slippage-Bounded Best Offer (SBBO). If the user's minimum is too far below the oracle-anchored fair price after slippage tolerance, the intent is rejected. ## 2. The intent is indexed The indexer reads Sui checkpoints, decodes Reiy events and object changes, and writes protocol state for coordinators, solvers, and dashboards. ## 3. Fisherman creates an auction round Fisherman groups open intents that share the same token pair and epoch into a round. After the collection window closes, it asks registered solvers to solve the round. ## 4. Solvers compete Each solver returns a proposed solution: how much of each intent it fills, the payout, a protected minimum, and a score. Fisherman validates every response and selects the highest valid score. ## 5. Fisherman signs a certificate For the winning solution, Fisherman signs a settlement certificate. The certificate names the solver and the exact per-intent payouts, and it expires after a short window. ## 6. Settlement executes on-chain The winning solver settles in a single Sui transaction. The contracts verify the signature, the solver, the epoch, the deadline, and each user's protected minimum before any funds move. If any check fails, settlement aborts and the escrow stays put. Understand contract epochs and Fisherman statuses. See trader-facing settlement outcomes. # Concepts Source: https://docs.reiy.finance/reiy-protocol/concepts/index Core ideas behind Reiy Protocol. # Concepts Concepts explain what Reiy is and how the protocol works without requiring API schemas or implementation details first. How users express protected trading outcomes. The execution providers that compete to fill intents and settle on-chain. The off-chain coordinator that runs competition and signs certificates. Follow an intent from submission to settlement. Understand contract epochs and Fisherman auction-round statuses. Learn how Fisherman groups intents, ranks solver solutions, and signs settlement certificates. SBBO, protected minimums, custody, epoch safety, and certificate checks. A user-facing explanation of protocol fees. # Fisherman Source: https://docs.reiy.finance/reiy-protocol/concepts/introduction/fisherman The off-chain Execution Coordinator that orchestrates solver competition and signs settlement certificates. # Fisherman Fisherman is Reiy's Execution Coordinator. It is the off-chain service that turns a stream of on-chain intents into competitive, settleable solutions. It is the orchestration brain of the protocol, but it holds no funds and cannot override on-chain protections. ## What Fisherman does Fisherman owns everything between intent submission and on-chain settlement: * Reads on-chain intents and exposes them through an orderbook. * Groups compatible open intents into auction rounds. * Asks registered solvers to quote and to solve each round, within bounded time windows. * Validates every solver response: fills, floors, token pair, epoch, and expiry. * Ranks valid solutions by score and picks the winner. * Signs a settlement certificate for the winner and hands off settlement. * Reissues a certificate if the winner fails to settle before it expires. ## What Fisherman does not do * It does not hold user funds. Escrow lives in the contracts. * It does not build solver routes. Solvers source their own liquidity. * It has no on-chain authority. Its signature only lets one solver attempt settlement, and the contracts still enforce every user protection independently. ## Round and certificate state Fisherman tracks the lifecycle of each round and certificate. A round moves from collecting intents, to solving, to a chosen winner, to settling, to settled, with separate states for deadline misses and retries. ## Why a coordinator instead of an on-chain auction Running quote collection, batching, and ranking off-chain keeps the on-chain surface small and cheap: the contracts only verify a signature and enforce floors. Windows, batch sizes, and retry policy can be tuned without redeploying contracts, while custody and user safety stay fully on-chain. See how a round becomes signed settlement authority. The live coordinator API and OpenAPI spec. # Intents Source: https://docs.reiy.finance/reiy-protocol/concepts/introduction/intents How Reiy users express protected trading outcomes as on-chain objects on Sui. # Intents An intent is a trade instruction that says what you want, not how to get it. You specify the token to sell, the token to receive, the least you will accept, a deadline, a slippage tolerance, and whether partial fills are allowed. Solvers then compete to satisfy it. Unlike a routed swap, an intent never forces you to pick a pool or path. You define the acceptable outcome, and the market competes to beat it. ## An intent is an on-chain object In Reiy, an intent is not an off-chain message. It is a real shared object created on Sui when you submit. The object holds your sell tokens in escrow and records the terms of the trade. Your funds stay inside it until the trade settles or you cancel, and no one, not a solver and not the coordinator, can move them without passing the contract's checks. Each intent object records: | Field | Meaning | | ------------------ | ---------------------------------------------------------------------- | | Sell asset | Your tokens, held in escrow inside the object. | | Buy asset | The token you want to receive. | | Minimum out | The least you will accept, enforced at settlement. | | Admission floor | A fair market floor (SBBO) checked when the intent is created. | | Slippage tolerance | How far the price may move before the intent is rejected at admission. | | Partial fill | Whether unfilled volume can roll over to a later round. | | Target epoch | The settlement window the intent belongs to. | | Deadline | When the intent expires. | | Status | Open, partially filled, filled, cancelled, or expired. | ## Advantages and trade-offs Holding the intent on-chain gives you real guarantees: * **True custody.** Your funds are escrowed in the object, not approved for someone to pull. * **A hard floor.** The contracts reject any settlement below your minimum. * **Transparency.** The intent and its outcome are visible and verifiable on-chain. * **Composability.** Other Sui programs and indexers can read intent state directly. The model also has trade-offs to be aware of: * It depends on solver competition. With few solvers, you may get fewer or worse offers. * Coordination is off-chain, so liveness of the coordinator affects how quickly rounds run. * Trades settle in rounds rather than instantly, which adds a short wait in exchange for competition. ## Reiy intents vs CoW Protocol orders Reiy's intents are inspired by CoW Protocol's order flow but adapted to Sui. | | Reiy (Sui) | CoW Protocol (EVM) | | ---------- | ------------------------------------------------------------- | ---------------------------------------------------- | | Form | An on-chain object that escrows your funds | An off-chain signed order plus a token allowance | | Custody | Funds locked in the intent until settle or cancel | Funds stay in your wallet until pulled at settlement | | Liquidity | Solvers aggregate across Sui venues and matches | Solvers use batch auctions and on-chain liquidity | | Settlement | A signed certificate authorizes an atomic on-chain settlement | Solvers settle the batch on-chain | The shared idea is the same: you state an outcome, and a competitive solver market finds the best way to deliver it. See what happens after an intent is submitted. Follow the trader-facing submission guide. # Solvers Source: https://docs.reiy.finance/reiy-protocol/concepts/introduction/solvers The execution providers that compete to fill Reiy intents and settle on-chain. # Solvers Solvers are the execution providers of Reiy. They compete to fill user intents and, when they win, settle the result on-chain. A solver can use any routing strategy as long as the final settlement satisfies the signed certificate and the Move contract checks. ## What a solver does * **Registers on-chain** with a stake and stays active while that stake is held. * **Runs a service** that Fisherman calls to request quotes and solutions. * **Returns solutions**: proposed fills, payouts, and a score for the intents in a round. * **Settles on a win**: takes the escrowed funds, sources liquidity, and delivers the payout, all in one Sui transaction. ## Where solvers source liquidity * CoW matching across intents in the same batch * Internal inventory * External Sui venues such as DeepBook * Aggregators or other execution infrastructure ## What constrains a solver A solver is never trusted by the protocol. Every claim is re-checked on-chain at settlement: the payout must exactly match the certificate, must clear the user's protected minimum (which survives the volume fee), and the intent's epoch and fill rules must hold. Any violation aborts the whole transaction, so a solver that cannot deliver simply fails to settle, and escrow never moves. The coordinator that runs solver competition. Implement a solver service end to end. # Protections Source: https://docs.reiy.finance/reiy-protocol/concepts/protections How SBBO, protected minimums, custody, epoch safety, and certificates protect Reiy users. # Protections Reiy's protection model is split between Fisherman and the Move contracts. Fisherman coordinates and signs only validated solutions; the contracts decide whether settlement can actually move escrow. ## SBBO admission When you submit an intent, the contracts read a fair market price and compute an SBBO floor from your sell amount and slippage tolerance. If your minimum is below that floor, or your slippage exceeds the configured maximum, the intent is rejected before any solver sees it. ## Protected minimums Every certificate carries a protected minimum for each filled intent, set at or above your own minimum. Fisherman checks this before signing, and the contracts enforce it again at settlement: the delivered payout must match the certificate exactly, must clear the protected minimum, and must still clear it after the volume fee. Partial fills are protected proportionally to the amount filled. **Example.** You submit an intent to sell 1,000 USDC for SUI with a minimum of 245 SUI. * **Admission:** the fair price is about 250 SUI. Your minimum must sit at or above the SBBO floor after slippage, so a minimum of 200 would be rejected, but 245 is accepted. * **Competition:** the winning solver proposes 252 SUI, with a protected minimum of 245. * **Settlement:** the contracts check 252 ≥ 245 (protected minimum) ≥ 245 (your minimum), and that 252 still clears 245 after the volume fee. * **Result:** you receive 252 SUI minus a small fee. Any settlement that tried to pay you less than 245 would be rejected. ## Custody safety Your sell tokens stay locked in the intent until cancellation or valid settlement. A solver cannot take the escrow just because Fisherman picked it. The certificate only proposes a settlement; the on-chain transaction must still pass every check: the signature, the solver identity, the epoch, expiry, and your floor. ## Epoch safety Each certificate is bound to the current epoch, and settlement rejects an intent whose epoch does not match. If only part of an intent is filled, the remainder rolls forward to the next epoch. ## Certificate expiry Certificates expire after a short window. The contracts reject an expired certificate, and Fisherman reissues a fresh one to retry the round. ## Atomic settlement Settlement runs in a single Sui transaction. If any check fails, the whole transaction aborts and your escrow does not move. Follow the coordination path. Review exact checks. # Reiy Protocol Source: https://docs.reiy.finance/reiy-protocol/index What Reiy is, who it serves, and why intent-based meta aggregation gives better trades on Sui. # Reiy Protocol Reiy is an intent-based meta DEX aggregator on Sui. You do not choose a pool, a route, or a price. You describe the trade you want, sell this token, receive at least this much of another, within your time and slippage limits, and let the market come to you. ## A better way to trade On a normal DEX you commit to one route before the market has a chance to compete, and you carry the risk of bad pricing, failed routes, and value leaking to the people ordering transactions. Reiy flips that around. When you submit an intent, solvers compete to fill it. Each solver searches every source of liquidity on Sui, on-chain pools, their own inventory, and matches with other users, and proposes the best execution it can. The proposal that gives you the most wins. Because they compete on the outcome you receive, the gains go to you instead of leaking away. ## What you get * **Best execution by competition.** Many solvers race to fill your trade across all of Sui's liquidity, not a single route. * **A guaranteed minimum.** You set the least you will accept, and the contracts reject any settlement that pays less. * **Real custody.** Your funds sit in an on-chain object until the trade settles or you cancel. No one can touch them in between. * **No surprises.** You see the expected result before you confirm, and you only pay a fee when the trade actually settles. ## Who it serves * **Traders** get protected, competitive execution by simply stating what they want. * **Solvers** compete for order flow and earn a share of the value they create. * **Apps** integrate one intent interface instead of building routing from scratch. Learn the protocol vocabulary and how it works. Use Reiy as a trader or a solver. Definitions, formulas, contracts, architecture, and APIs. Choose an integration path for solver or app development. # App Integration Source: https://docs.reiy.finance/reiy-protocol/integrate/app-integration How apps can prepare to submit Reiy intents. # App Integration Apps integrate Reiy by building transactions that submit protected intents to the protocol. The current docs mention generated TypeScript bindings through `@reiy-finance/contracts-sdk`; finalized package, deployment, and address details should be published with the relevant release. ## Current integration model An app should prepare to: * Connect a Sui-compatible wallet. * Let users choose sell token, buy token, amount, minimum payout, slippage tolerance, deadline, and partial-fill preference. * Build a transaction against the Reiy Move contracts. * Show the user net payout and fee expectations before confirmation. * Track intent status through indexed protocol state. ## What is forthcoming Public app integration should wait for final deployment addresses, SDK package details, and canonical examples. Until those are published, use the conceptual and trader tutorials to model the intended flow. Understand the user-facing trade object. Review the expected app workflow. # Integrate Source: https://docs.reiy.finance/reiy-protocol/integrate/index Choose the right integration path for building with Reiy Protocol. # Integrate Reiy can be integrated from two main directions: solver services that compete in auctions, and apps that submit protected intents for users. Implement the solver service, API endpoints, and settlement flow. Build user-facing intent submission with the contracts SDK when deployment details are available. # Solver Integration Source: https://docs.reiy.finance/reiy-protocol/integrate/solver-integration Implementation path for solver services on Reiy Protocol. # Solver Integration Solver integration means exposing the HTTP endpoints expected by the coordinator, registering on-chain, responding within auction windows, and settling winning certificates on Sui. ## Recommended path 1. Read [Solvers](/reiy-protocol/concepts/introduction/solvers) and [Fisherman](/reiy-protocol/concepts/introduction/fisherman). 2. Follow [Join as a Solver](/reiy-protocol/tutorials/solvers/join-as-solver). 3. Implement against the [Fisherman API](/reiy-protocol/reference/apis/solver-api) and the live [OpenAPI spec](https://testnet-fisherman.reiy.finance/openapi.json). 4. Use [Execute Settlement](/reiy-protocol/tutorials/solvers/execute-settlement) for the winning transaction flow. 5. Review [Solution Validation and Ranking](/reiy-protocol/reference/core/scoring-and-ranking) before returning solve responses. ## Integration requirements * Public HTTP service URL configured for coordinator discovery. * `/quote`, `/solve`, `/settle`, and `/notify` endpoints. * Sui signing wallet for settlement. * Idempotency handling for retries and notifications. * Liquidity strategy that can satisfy protected minimums. Fisherman docs, endpoint groups, and OpenAPI links. Settlement transaction checklist. # Fisherman API Source: https://docs.reiy.finance/reiy-protocol/reference/apis/solver-api Canonical API reference for the Reiy Fisherman execution coordinator. # Fisherman API The canonical API reference for the Reiy execution coordinator is hosted by the live testnet Fisherman deployment: Browse the Scalar API reference for the current testnet deployment. Use the OpenAPI 3.1 spec for client generation, validation, or integration tests. ## Current deployment | Field | Value | | --------------------- | ----------------------------------------------------- | | API docs | `https://testnet-fisherman.reiy.finance/docs` | | OpenAPI spec | `https://testnet-fisherman.reiy.finance/openapi.json` | | OpenAPI version | `3.1.0` | | Fisherman API version | `0.1.0` | | Server | `https://testnet-fisherman.reiy.finance` | ## Endpoint groups The testnet Fisherman API currently exposes these groups: | Group | Endpoints | | ------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------- | | System | `GET /health`, `GET /metrics`, `GET /events/stream` | | Orderbook | `GET /orderbook` | | Auctions | `GET /auctions/active`, `GET /auctions/{id}`, `POST /solve`, `POST /reveal`, `POST /admin/retry/{auctionId}` | | Certificates | `GET /certificates/{id}`, `POST /settle` | | Solvers | `POST /quote`, `POST /notify` | | Indexer | `POST /indexer/sync`, `GET /indexer/health`, `GET /indexer/intents`, `GET /indexer/settlements`, `GET /indexer/state/{kind}`, `GET /indexer/events/stream` | ## Winner selection summary Fisherman currently validates solver `SolveResponse` payloads and selects the highest valid `score`. If scores tie, the winner is chosen deterministically by solver endpoint id. After ranking, Fisherman signs a certificate and asks the winning solver to settle it on-chain. Treat the hosted OpenAPI document as the source of truth for request and response schemas. This page intentionally links to Fisherman instead of duplicating schema details that can drift. ## Integration path Follow the implementation path for solver services. Review the settlement flow after receiving a winning certificate. # Architecture Source: https://docs.reiy.finance/reiy-protocol/reference/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
(Execution Coordinator)"] Indexer["Reiy Indexer"] Solvers["Solvers"] Venues["Sui liquidity
DeepBook · Cetus · inventory · CoW matches"] Contracts["Reiy Protocol
(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
signature, solver, epoch, expiry] --> B{Valid?} B -- No --> X[Abort: escrow stays put] B -- Yes --> C[Take escrowed intent
full or partial] C --> D[Source liquidity] D --> E[Deliver payout] E --> F{Clears protected minimum
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 What the coordinator owns and does not own. The Move modules behind these flows. # Contracts Source: https://docs.reiy.finance/reiy-protocol/reference/core/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` 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` (shared): solver stake + active status. | | `fee_vault` | `FeeVault` (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` | shared | Solver stake; `Stake` is the eligibility coin type. | | `FeeVault` | shared | Canonical fee sink for token `T`, registered in config. | | `Intent` | 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`. 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. Look up contract-facing protocol terms. Review off-chain validation and winner selection. # Definitions Source: https://docs.reiy.finance/reiy-protocol/reference/core/definitions Current Reiy Protocol terms, actors, statuses, and parameters. # Definitions These definitions follow the current Fisherman coordinator and Move contract implementation. ## Core Terms | Term | Meaning | | --------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Intent** | A user's on-chain order object. It escrows the sell asset and records sell token, buy token, remaining sell amount, minimum output, SBBO admission data, partial-fill preference, deadline, and target epoch. | | **Contract epoch** | The on-chain `AuctionState.current_epoch` counter. It is used as a settlement safety boundary, not as a multi-phase on-chain auction machine. | | **Fisherman** | The Execution Coordinator. It handles quote fanout, auction rounds, solver solution validation, winner ranking, certificate signing, retries, and settlement handoff. | | **Auction round** | Fisherman's off-chain batching object. It groups compatible open intents by `sellType`, `buyType`, and `targetEpoch`. | | **Solver** | An execution provider that exposes HTTP endpoints for Fisherman, returns quotes and solutions, and settles winning certificates on-chain. | | **Solution** | A solver response for an auction round. It contains intent ids, fills, gross payouts, protected minimums, score, expiry, and optional counter-leg data. | | **Score** | Solver-declared integer used by Fisherman to rank valid solutions. The highest valid score wins; ties break by solver endpoint id. | | **Certificate** | A signed authorization from Fisherman that lets the winning solver settle on-chain. It binds protocol/config ids, key version, live epoch, solver, token types, intent ids, fills, gross payouts, protected minimums, and expiry. | | **Protected minimum** | The per-intent minimum payout carried in the certificate. Fisherman validates it against the user minimum, and contracts enforce it against the actual fill and post-volume-fee payout. | | **Settlement** | The winning solver's Sui PTB. It verifies the certificate, takes the authorized intent escrow, sources liquidity, delivers the exact signed gross payout, splits fees, and pays the user net output. | ## Auction Round Statuses | Status | Meaning | | ------------ | ----------------------------------------------------------------------- | | `collecting` | Fisherman is grouping open intents until the collection window matures. | | `solving` | Fisherman is calling enabled solver endpoints. | | `solved` | A winner was selected and a certificate was issued. | | `settling` | Fisherman has sent the settlement request to the winning solver. | | `settled` | Settlement succeeded or was recorded as complete. | | `expired` | A round or certificate missed its deadline. | | `failed` | A round failed and can be retried by operator action. | ## Certificate Statuses | Status | Meaning | | ---------- | --------------------------------------------- | | `issued` | Fisherman signed the certificate. | | `settling` | Settlement is in progress. | | `settled` | Settlement completed. | | `expired` | Certificate is no longer usable. | | `reissued` | A newer certificate replaced it during retry. | | `failed` | Settlement failed. | ## Parameters | Parameter | Meaning | | -------------------------- | ----------------------------------------------------------------------------------------- | | `min_solver_stake` | Minimum stake a solver must keep in the on-chain `SolverRegistry` to be active. | | `min_batch_collect_ms` | Minimum time before the on-chain epoch can advance. On-chain default: `10000`. | | `CERTIFICATE_TTL_MS` | Fisherman certificate time-to-live. Code default `45000`; testnet `45000`. | | `COLLECTING_WINDOW_MS` | Fisherman collection window before solving a round. Code default `15000`; testnet `6000`. | | `QUOTE_RESPONSE_WINDOW_MS` | Quote fanout response cap. Code default `1200`; testnet `5000`. | | `SOLVER_TIMEOUT_MS` | Per-solver HTTP timeout. Code default `2000`; testnet `4000`. | | `DEFAULT_BATCH_SIZE` | Default number of intents per round chunk. Default `4`. | | `MAX_BATCH_SIZE` | Maximum intents in a solve request. Default `10`. | ## Current Non-Goals The current implementation does not expose on-chain `PairBenchmark`, `Allocation`, `Auctioneer`, or multi-phase bid/selection objects. Those terms may appear in older mechanism notes, but they are not the current Fisherman and Move contract execution path. Exact current validation rules. Move module responsibilities. # Fee Formulas Source: https://docs.reiy.finance/reiy-protocol/reference/core/fee-formulas Protocol fee structure, formulas, defaults, and tiers, expressed as percentages. # Fee Formulas Reiy collects fees on each settled intent, split between the solver and the protocol. Fees are charged in the settled **buy** token and deducted from the gross payout. All rates below are percentages of the relevant base; the contract evaluates them in integer token units (rounding down). ## Vocabulary | Term | Meaning | | ---------------- | -------------------------------------------------------------------------------------------- | | Gross | The buy-token payout before any fees. | | Net | What the user receives after fees: `gross − total fee`. | | Surplus | The payout above the user's protected minimum. | | Volume fee | A percentage of the gross payout. Applied first. | | Surplus fee | A percentage of the surplus, capped by a percentage of gross. | | Solver fee share | The percentage of the total fee paid to the solver; the rest goes to the protocol fee vault. | ## Fee computation Fees are computed per intent, in order: ### 1. Volume fee $$ \begin{aligned} \text{volume fee} = \text{gross} \times \text{volume fee rate} \end{aligned} $$ The rate comes from the pair's fee tier (see below). Settlement is rejected if `gross − volume fee` falls below the protected minimum. ### 2. Surplus fee $$ \begin{aligned} \text{surplus} &= (\text{gross} - \text{volume fee}) - \text{protected min} \\ \text{surplus fee} &= \min\big(\text{surplus} \times 10\%,\;\; \text{gross} \times 0.1\%\big) \end{aligned} $$ The surplus fee is the smaller of 10% of surplus or 0.1% of gross (the cap). ### 3. Total fee cap $$ \begin{aligned} \text{total fee} = \min\big(\text{volume fee} + \text{surplus fee},\;\; \text{gross} \times 0.15\%\big) \end{aligned} $$ ### 4. Net payout $$ \begin{aligned} \text{net} = \text{gross} - \text{total fee} \end{aligned} $$ ### 5. Solver split $$ \begin{aligned} \text{solver fee} &= \text{total fee} \times 35\% \\ \text{protocol fee} &= \text{total fee} - \text{solver fee} \end{aligned} $$ The solver fee is paid out immediately. The protocol fee goes to the per-token `FeeVault`. ## Default fee parameters | Parameter | Default | Maximum | | --------------------- | ---------------- | ------- | | Standard volume fee | 0.0075% | 1% | | Correlated volume fee | 0.001% | 1% | | Surplus fee | 10% of surplus | 100% | | Surplus fee cap | 0.1% of gross | 2% | | Max total fee | 0.15% of gross | 2% | | Solver fee share | 35% of total fee | 100% | ## Fee tiers Each pair is assigned one of four tiers: | Tier | Volume fee | Description | | ---------- | ------------ | ------------------------------- | | Standard | 0.0075% | Default for most pairs. | | Correlated | 0.001% | Stablecoin / correlated assets. | | Custom | configurable | Per-pair override. | | Disabled | 0% | No volume fee. | ## Related Topics How solutions are validated and ranked. User-facing fee overview. # Solution Validation and Ranking Source: https://docs.reiy.finance/reiy-protocol/reference/core/scoring-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 Current coordination lifecycle. Settlement fee calculation. # FAQ Source: https://docs.reiy.finance/reiy-protocol/reference/faq Common questions about using Reiy. # FAQ ## Your trades It's how you tell Reiy what you want to trade. You specify the token to sell, what you want to receive, your minimum payout, and a deadline. The protocol handles the rest. A regular swap locks you into one route: one pool, one price. Reiy lets solvers compete to fill your trade using whatever route gives you the best outcome: matching with another user's order, internal inventory, or external liquidity. You can cancel and get your sell token back. You only ever pay a fee on a successful settlement. Yes, as long as your trade hasn't been filled yet. Cancellation returns your sell token to your wallet. If you allow it, a solver can fill part of your trade now and the rest in a later batch. Your remaining balance carries over automatically, with no need to resubmit. ## Fees A small fee when your trade settles, typically under 0.15%. It includes a volume fee (percentage of trade) and a surplus fee (share of anything above your minimum). You see the net amount before confirming. No. You only pay when your trade settles successfully. You do. Intents are self-paid: you sign and pay gas for your own submission, just like any Sui transaction. ## Safety Yes. Your sell token is locked in the protocol. No one, not even the winning solver, can touch it until you cancel or settlement executes. The minimum you set when submitting. The protocol enforces it, and any settlement that pays you less is rejected. Execution providers who compete to fill trades. They register with a stake to participate. If a winning solver fails to execute, your funds stay safe in escrow and the trade can be retried with another solver or cancelled. ## Technical Sui, chosen for its low fees, fast finality, and secure smart contract model. Any Sui-compatible wallet works. Testnet is available now. Mainnet launch details will be announced. ## Related Topics How to make your first trade. What you pay and how you're protected. # Technical Reference Source: https://docs.reiy.finance/reiy-protocol/reference/index Exact Reiy Protocol definitions, formulas, contracts, and API schemas. # Technical Reference Technical Reference is for exact information: protocol definitions, scoring rules, fee formulas, contract architecture, and API schemas. System overview and the full set of flow and lifecycle diagrams. Core terms, actors, extended terms, and parameters. Fisherman solution validation, score ranking, and contract settlement checks. Volume fee, surplus fee, total cap, net payout, and solver split. Move module responsibilities and deployment note. Canonical Fisherman API docs and OpenAPI links. Common questions for traders and technical readers. # Tutorials Source: https://docs.reiy.finance/reiy-protocol/tutorials/index Step-by-step guides for traders and solvers using Reiy Protocol. # Tutorials Tutorials show how to complete specific Reiy workflows. Use these when you want to do something rather than study the protocol model. Start from the trader journey: choose a pair, submit an intent, and check the result. Configure minimum payout, slippage, partial fills, and deadline. Understand statuses, settlement outcomes, expiry, cancellation, and partial fills. Set up a solver service and register for competition. Build and submit the winning settlement transaction. # Execute Settlement Source: https://docs.reiy.finance/reiy-protocol/tutorials/solvers/execute-settlement How winning solvers execute settlement on-chain. # Execute Settlement When you win, you settle in a single Sui programmable transaction block. If any protocol check fails, the transaction aborts and user funds remain safe. ## Prepare Before settlement, confirm you have: * Winning auction data and covered intents. * The signed settlement certificate from the coordinator. * Liquidity needed to deliver payouts. * A Sui wallet with enough gas. ## Steps **Verify authorization**: check coordinator signature, solver address, epoch, and expiry. **Build the transaction**: use the authorized intents, fills, payouts, and certificate. **Deliver payouts**: execute your liquidity strategy and provide buy tokens to users. **Let contracts handle fees**: settlement splits solver and protocol fee shares. **Submit and record the digest**: return settlement results through the solver API. Never split a CoW-cross settlement into separate transactions. Both legs must succeed or fail together. ## Pre-submit checklist * Certificate has not expired. * Solver address matches your wallet. * Epoch matches current protocol state. * Intent IDs, fill amounts, and payouts are correct. * User minimums and partial-fill rules are respected. * Wallet has enough gas. Review `/settle` request and response details. Understand settlement fee calculations. # Join as a Solver Source: https://docs.reiy.finance/reiy-protocol/tutorials/solvers/join-as-solver Set up a solver service and connect to Reiy Protocol. # Join as a Solver To become a solver, run an HTTP service that implements the Reiy solver API, register on-chain with the required minimum stake, and start competing for settlement. ## What you need * An HTTP server exposing the solver API endpoints. * A Sui wallet that can submit transactions. * Stake for on-chain solver registration. * Reliable liquidity access through inventory, venues, aggregators, or other routing logic. ## Steps **Understand the protocol**: read intents, solvers, Fisherman auction rounds, certificates, and solution ranking. **Implement the service**: expose `/quote`, `/solve`, `/settle`, and `/notify`. **Register on-chain**: post the required minimum stake and publish your solver address and service URL. **Return valid quotes and solutions**: satisfy user minimums, deadlines, epochs, and validation rules. **Wire settlement**: submit winning settlements on Sui with the contracts SDK or direct Sui calls. **Test failure paths**: invalid requests, expired deadlines, wrong epochs, and incorrect payouts should fail safely. ## Good practices * Keep quote responses fast. * Validate everything before submitting transactions. * Use idempotency keys for retries. * Log request IDs, auction IDs, certificate IDs, and transaction digests. * Release reserved liquidity on lost, timeout, or invalid-solution notifications. Implement the endpoint contract. Build the winning on-chain transaction. # Make a Trade Source: https://docs.reiy.finance/reiy-protocol/tutorials/traders/make-a-trade How to trade on Reiy, from submitting an intent to receiving tokens. # Make a Trade Reiy lets you trade by stating the outcome you want. You set the token pair, amount, minimum payout, and preferences. Solvers compete to fill the trade, and settlement only succeeds if your conditions are met. ## Steps **Pick a pair**: choose the token you want to sell and the token you want to receive. **Set your terms**: enter the amount, slippage tolerance, and deadline. **Choose partial fills**: decide whether a solver can fill part now and leave the rest for a later batch. **Review**: check your minimum payout and expected fees. **Submit**: your sell token is locked safely in the protocol. **Wait for competition**: solvers compete to fill your intent. **Check the result**: settled, cancelled, expired, or still in progress. Your sell token stays in protocol escrow from submission until cancellation or valid settlement. ## Statuses | Status | Meaning | | --------- | --------------------------------------------------- | | Created | Your trade is submitted and visible to solvers. | | Quoting | Solvers are preparing offers. | | Solving | The best valid outcome is being selected. | | Settling | A winning solver is executing settlement. | | Settled | You received your buy token. | | Cancelled | You cancelled before execution and reclaimed funds. | | Expired | Time ran out; funds remain safe to reclaim. | Learn each trade preference. Understand what happens after submission. # Submit an Intent Source: https://docs.reiy.finance/reiy-protocol/tutorials/traders/submit-an-intent Configure and submit a protected Reiy trade intent. # Submit an Intent An intent tells Reiy what trade result you want. You specify details, the protocol locks your sell token, and solvers compete to satisfy your constraints. ## Steps **Connect**: open the Reiy app and connect a Sui-compatible wallet. **Choose a pair**: select the token you are selling, the token you want to buy, and the amount. **Set preferences**: configure minimum payout, slippage, partial fills, and deadline. **Review fees and minimums**: check the net amount before confirming. **Confirm and submit**: your sell token is locked in the protocol. ## Preference options | Setting | What it does | | ------------------ | -------------------------------------------------------- | | Minimum payout | The least you are willing to receive. | | Slippage tolerance | How far market price may move before admission fails. | | Partial fill | Allows part of the trade to fill now and the rest later. | | Deadline | How long the intent can remain active. | A minimum payout that is too tight can reduce solver participation. Partial fills can help large trades settle across multiple batches. Learn how the protocol enforces user safety. Follow your intent after submission. # Track Settlement Source: https://docs.reiy.finance/reiy-protocol/tutorials/traders/track-settlement What happens when a Reiy intent fills, expires, cancels, or remains in progress. # Track Settlement Once Fisherman selects a winning solver and issues a certificate for your intent, settlement happens automatically. You do not need to stay online. ## Successful settlement When settlement succeeds: * Your buy token arrives in your wallet. * Fees are deducted from the trade payout. * The transaction is recorded on Sui. ## If the intent does not fill Settlement may not happen if the deadline passes, the market moves too much, no solver can meet your minimum, or the winning certificate expires before settlement. In those cases, your sell token remains protected in protocol escrow until cancellation or a later valid settlement path. ## Partial fills If you enabled partial fills, a solver may fill part of your trade in one batch and leave the remaining balance active for a later batch. ## Common outcomes | Outcome | What it means | | ----------- | ------------------------------------------------------- | | Settled | You received the buy token. | | Cancelled | You reclaimed the sell token before execution. | | Expired | The deadline passed and funds are safe to reclaim. | | In progress | The intent is still waiting for a valid solver outcome. | Understand settlement fees at a high level. Read common trader questions. # API Reference Source: https://docs.reiy.finance/resources/api-reference External API resources for Reiy testnet services. # API Reference Reiy's live testnet API reference is served directly by Fisherman, the execution coordinator. ## Fisherman | Resource | URL | | -------------------- | ---------------------------------------------------------------------------------------------------------- | | Interactive API docs | [https://testnet-fisherman.reiy.finance/docs](https://testnet-fisherman.reiy.finance/docs) | | OpenAPI JSON | [https://testnet-fisherman.reiy.finance/openapi.json](https://testnet-fisherman.reiy.finance/openapi.json) | | Server base URL | `https://testnet-fisherman.reiy.finance` | The API covers coordinator health, orderbook snapshots, auction details, certificates, solver quote/notify flows, settlement orchestration, and upstream indexer reads. Read the in-doc summary and integration links. Follow the implementation path for solver services. # Glossary Source: https://docs.reiy.finance/resources/glossary Quick reference for the key Reiy Protocol terms. # Glossary The essential terms for how Reiy works. For exact fields and parameters, see [Definitions](/reiy-protocol/reference/core/definitions). | Term | Meaning | | ------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------- | | **Intent** | Your order. It locks the token you sell and records the least you accept, a deadline, and your preferences. You pay your own gas. | | **SBBO** | The admission check. An intent is rejected if its minimum is below a fair market price after slippage. | | **Fisherman** | The off-chain coordinator. It batches intents, runs solver competition, picks the winner, and signs a certificate. It never holds your funds. | | **Solver** | An execution provider that competes to fill intents and settles the winning result on-chain. | | **Stake** | A deposit a solver keeps to stay eligible to compete. | | **Auction round** | A batch of compatible open intents that solvers compete over. | | **Solution** | A solver's proposed fills and payouts for a round, plus a score. | | **Score** | The number Fisherman uses to rank solutions. The highest valid score wins. | | **Certificate** | The signed authorization that lets the winning solver settle on-chain. | | **Protected minimum** | The guaranteed floor for an intent. Settlement that pays below it is rejected. | | **Gross and net payout** | Gross is the amount before fees; net is what you receive after fees. | | **Epoch** | An on-chain counter used as a settlement safety boundary. | | **Partial fill** | Filling part of an intent now and leaving the rest for a later round. | | **Settlement** | The on-chain step where the winning solver delivers your tokens and fees are split. | | **Fee vault** | Where the protocol's share of fees is collected, per token. | Full terms, statuses, and parameters. Learn how these pieces fit together. # References Source: https://docs.reiy.finance/resources/references External references, related work, and academic background for Reiy Finance. ## Technical specifications | Title | Description | | ----------------------------------------------------------------------------- | -------------------------------------------------------------------------------- | | [CoW Protocol Documentation](https://docs.cow.fi) | Reference architecture for intent-based batch auctions with solver competition | | [Reiy Fisherman API](https://testnet-fisherman.reiy.finance/docs) | Live testnet API reference for the execution coordinator | | [Reiy Fisherman OpenAPI](https://testnet-fisherman.reiy.finance/openapi.json) | OpenAPI 3.1 JSON for client generation and schema validation | | [Sui Documentation](https://docs.sui.io) | Sui blockchain official documentation | | [Cetus Documentation](https://docs.cetus.zone) | Concentrated-liquidity AMM on Sui; fallback execution path for unmatched intents | | [DeepBook Documentation](https://deepbook.tech) | On-chain central-limit order book on Sui; reference mid-price source for solvers | ## Related Topics # Smart Contracts Source: https://docs.reiy.finance/resources/smart-contracts Deployed Reiy Protocol contract addresses for testnet and mainnet. # Smart Contracts The Reiy contracts on Sui hold intent custody, admission checks, solver registration, certificate verification, user protection, fee accounting, and settlement. For what each module does, see the [Contracts reference](/reiy-protocol/reference/core/contracts). ## Testnet Reiy is live on Sui testnet. These are the current addresses. | | Address | | --------------- | -------------------------------------------------------------------- | | Package | `0x9d7ba9ae48cac8d8c52cf5c43933f394649ecde632cb79e45456387f1600b19d` | | Auction state | `0xb39720579abbe50a5e5dc26c3abc0a67a9f7214d7344d9b8755da1b8cbe5576d` | | Global config | `0xef0c481bb56de94a845c6a2e33e9a03d44127db476a6cd356c8da309b5603809` | | Solver registry | `0xc72bd2d13e94070e03a53cfbf651a1ae39f5bad6ac69d32badc8d3d7eb17f8c4` | | Fee vault | `0x844e8c9d7f3ab29ac46f4312e59e354ed73828d974f0f64573f9e7a54bf924cf` | The Execution Coordinator signs settlement certificates with the public key `8a314ea161111c630b0c0621504e32823da8e26ba216ecc8846754bfd34d17a1`. Solvers verify each certificate against this key. ## Mainnet Mainnet addresses will be published here at launch. ## Related resources What each Move module does. Look up protocol terms. # Mechanism Overview Source: https://docs.reiy.finance/resources/whitepaper A compact overview of the Reiy Protocol mechanism. # Mechanism Overview Reiy Finance is an intent-based meta DEX aggregator on Sui. It escrows protected user intents on-chain, lets solvers compete through Fisherman auction rounds by aggregating liquidity across Sui venues, and enforces settlement through Move contracts. ## Abstract Users submit intents that define the tokens, amount, minimum payout, deadline, slippage tolerance, and partial-fill preference. Fisherman groups open intents into auction rounds, asks enabled solvers for executable solutions, validates the replies, ranks by score, signs the winning certificate, and hands settlement to the winning solver. Contracts verify the certificate and settlement checks before escrow can move. ## Mechanism 1. **Intent submission**: users lock sell tokens in protocol escrow. 2. **Admission protection**: SBBO checks the minimum payout against an oracle-anchored fair price after slippage tolerance. 3. **Round creation**: Fisherman groups indexed open intents by directed pair and target epoch. 4. **Solver competition**: solvers return `SolveResponse` payloads with fills, gross payouts, protected minimums, scores, and expiries. 5. **Winner ranking**: Fisherman validates replies and selects the highest valid score, with deterministic tie-breaking by solver endpoint id. 6. **Certificate signing**: Fisherman signs the winning settlement certificate for the current epoch. 7. **Settlement**: the winning solver settles on-chain, with contracts verifying the certificate, solver registration, payouts, fees, epochs, deadlines, and atomicity. ## Key invariants * **Escrowed custody**: user sell tokens remain in protocol contracts until cancellation or valid settlement. * **Protected minimums**: settlement cannot pay less than the signed protected minimum after the volume-fee floor check. * **Partial fills when enabled**: a solver may fill part of an intent only when the user allows it. * **Solver accountability**: settlement requires the signed solver to remain registered and above the minimum active stake. Read the product overview. Review the current validation rules.