How Reiy Works

Reiy is an intent-based exchange system on Sui. Users do not submit a direct swap route. Instead, they submit a protected trade intent, solvers compete to execute it, and the winning settlement is enforced by Sui Move contracts.

​

System map

​

1. A user submits an intent

A user chooses what they want to sell, what they want to buy, the sell amount, the minimum acceptable payout, a deadline, and whether partial fills are allowed. The app builds a transaction with @reiy-finance/contracts-sdk and calls the Reiy Move contracts. The contracts validate admission rules and escrow the sell coin inside an Intent<Sell, Buy> shared object. The intent becomes the authoritative on-chain record for the user’s order. For mainnet design, the specs introduce SBBO admission checks. SBBO means the user’s minimum output must be close enough to an on-chain market reference after slippage, so a bad minimum cannot be exploited as easily by solvers.

​

2. The indexer discovers protocol events

The reiy-indexer service subscribes to Sui checkpoints and decodes Reiy events and object changes. It writes durable history to Postgres, publishes realtime updates through Redis Streams, and exposes typed query surfaces through gRPC. Fisherman, solvers, dashboards, and apps should consume indexed state instead of each service independently replaying chain history.

​

3. Fisherman coordinates off-chain competition

Fisherman is the Execution Coordinator. It does not route swaps itself. Its job is to normalize requests, call solver endpoints, validate responses, rank valid candidates, persist auction state, and sign the winning settlement certificate. For quotes, Fisherman fans a normalized request out to enabled solvers and returns the best valid quote plus status for every solver. For auctions, it groups compatible open intents by token pair and target epoch, asks solvers to solve the batch, validates fills and protected minimums, then selects the highest-scoring valid solution. Fisherman controls timing policy off-chain: quote windows, batch windows, certificate TTL, retry behavior, and settlement handoff. The contracts still enforce the hard safety checks.

​

4. Solvers produce executable settlements

Solvers own liquidity discovery and route construction. A solver can use internal inventory, CoW matching between opposite intents, external liquidity venues, or aggregator routes. The current solver repository has three main pieces:

• packages/solver-core for pure TypeScript solving logic, CoW netting, clearing price, fill construction, and scoring.
• packages/settlement for settlement plan assembly with live integrations still separated behind interfaces.
• apps/solver-service for the Bun/Hono service shell that receives coordinator requests.

Mainnet mechanism work introduces stronger fairness goals such as uniform surplus ratio or EPSR-style behavior. The design intent is that users in the same fairness scope receive proportional improvement above their floor, while scoring is normalized so unrelated token units are not mixed.

​

5. The coordinator signs a certificate

After choosing a winner, Fisherman signs a canonical SolutionMessage with the coordinator Ed25519 key. The certificate binds the solver, epoch, protocol objects, token pair, intent IDs, fills, gross payouts, protected minimums, expiry, and key version. This certificate is not a suggestion. It is the exact settlement authorization the contracts will verify. If a solver changes the ordered intent list, payout values, epoch, or sender, settlement aborts.

​

6. The winning solver settles on-chain

The winning solver submits one Sui programmable transaction block:

1. Verify the coordinator signature with settlement::verify_solution.
2. Take each authorized intent in certificate order.
3. Source the required buy-token liquidity.
4. Deliver the exact gross payout for each intent.
5. Let the contracts split protocol and solver fees.
6. Emit settlement and fee events for the indexer.

The contracts reject expired certificates, wrong solvers, wrong epochs, invalid intent order, bad gross payout values, inactive solvers, and payouts below the protected minimum.

​

7. Fees and user protection are enforced at settlement

The user’s net payout must satisfy the protected minimum after fee logic. Fee parameters live in on-chain configuration and fee vaults collect protocol revenue per token type. Solver fee share is paid during settlement when the solver successfully executes a valid certificate. In the current contract guide, fees include volume fees, surplus fees, caps, solver share, and protocol share. Exact public fee tables should be generated from live deployment configuration before publishing.

​

8. Operations keep services in sync

Local and cloud infrastructure is owned by infrastructures. The local stack runs Fisherman, Postgres, Redis, and the indexer sidecar. Cloud deployment uses Docker images, ECR, ECS Fargate, RDS, secrets, logs, and load balancing. The most important operational invariant is configuration consistency. Fisherman, the SDK, contracts, indexer, and infrastructure secrets must agree on package IDs, shared object IDs, coordinator keys, supported pairs, fee vaults, and network.

​

Trust boundaries

Reiy assumes neither users nor solvers are trusted.

• User input is normalized and checked before quote fanout or intent submission.
• Solver responses are validated for shape, pair, request ID, amount equations, expiry, duplicate intents, floors, and score.
• Coordinator certificates are verified on-chain before assets move.
• Escrowed user funds remain in contracts unless cancellation or valid settlement succeeds.

The result is a hybrid system: flexible competition and batching happen off-chain, while custody and settlement safety remain enforced by Sui Move.

​

Related Topics