System Overview
1. Design Philosophy
Ratio's FX Engine is designed to mirror the behaviour of an institutional FX dealer desk — using oracle-based pricing, rules-based spread construction, and inventory-aware mid-rate adjustment — rather than an AMM curve. The goal is predictable, institutionally acceptable execution for PSPs and remittance operators, with zero AMM slippage and full auditability on-chain.
The Stablecoin Orchestration Layer (SOL) separates the user experience (instant settlement) from the market execution (inventory management). Users always receive instant, atomic settlement on Kaia. Behind the scenes, the protocol manages inventory risk asynchronously through a two-phase rebalancing system.
2. Architecture Map
3. On-Chain vs. Off-Chain Split
Ratio follows a hybrid architecture: critical settlement and accounting logic lives on-chain for auditability and trustlessness, while decision-making and orchestration logic runs off-chain for performance and flexibility.
On-Chain (Kaia Blockchain)
| Contract | Purpose |
|---|---|
| FX Swap Contract | Executes atomic swaps against the Vault; splits revenue (50/30/20); queries oracle for mid-market price |
| Vault Contract | Rebasing ERC-20 liquidity pool maintaining 1:1 peg with underlying stablecoin. Uses dynamic Liquidity Index to distribute fees and yield to kToken holders |
| Fee Contract | Accumulates 20% Global Fee from all pools; distributes to Vault via updateIndex() based on token TVL proportions |
| Oracle Aggregator | Aggregates Pyth (push-based, ~400ms) and Orakl (pull-based, Kaia-native) price feeds with staleness checks |
| Deposit Ledger | Immutable record of every LP deposit with timestamp, amount, intent class for cooldown tracking |
| Cooldown & Intent Enforcement | Lock periods and withdrawal notice periods enforced at contract level |
Off-Chain (Backend Services)
| Service | Purpose |
|---|---|
| FX Engine (9-Layer Pipeline) | Request validation, direction filtering, size check, corridor routing, oracle aggregation, state engine, pricing engine, arbitrage check, execution |
| State Engine | Evaluates system health across four states (NORMAL, PROTECT, RESTRICT, HALT) based on oracle health, pool depth, and VaR |
| Rebalancing Bot | Executes Phase 2 external rebalancing via RFQ to Binance, Wintermute, or OTC partners |
| Deposit Routing Engine | Routes LP deposits to Reserve/Yield pools based on intent class and admin config |
| Withdrawal Queue Manager | FIFO queue with NORMAL/SLOW/PAUSED states; gated by Reserve health, State Engine, and VaR |
| Admin Config Store | Partner parameters, fee tiers, pool thresholds, corridor config — changeable without on-chain tx |
4. Smart Contract Revenue Model
Every FX swap generates revenue that is split three ways:
Swap Revenue = Spread Profit + Platform Fee
Split: 50% → Treasury Wallet (protocol revenue)
20% → Fee Contract (Global Swap Fee Pool)
30% → Vault Contract (LP reward via Liquidity Index)
The Fee Contract accumulates the 20% global fee across all pools. On distribution, it converts fees into target assets based on [token TVL / Total TVL], sends to the Vault, and calls updateIndex(amount) — causing a "jump" in the Liquidity Index that auto-compounds into all kToken holder balances.
Platform fees (fixed + variable) and base spread vary by transaction size per corridor. See Volume-Tiered Fee Schedule for the per-corridor tier tables.
5. Subsystem Map
Each section of this documentation covers a specific subsystem. Here's how they interconnect:
| Subsystem | Primary Function | Key Interactions |
|---|---|---|
| FX Engine | Quote and execution pipeline (9 layers) | Reads oracles, State Engine, pool balances; writes to Active Pool |
| Risk Management | VaR monitoring and Emergency RFQ | Reads Reserve Pool; can override State Engine; triggers external RFQ |
| Inventory Skew | Dynamic mid-rate adjustment | Reads Active Pool balance ratio; feeds into Pricing Engine |
| Smart Rebalancing | Phase 2 external clearance triggers | Reads Reserve Pool; triggers Off-Chain Bot; coordinates Yield Pool recall |
| LP Withdrawals | Cooldown, queue, and whale protection | Reads Reserve health; sources from Reserve/Yield; isolated from Active |
| Liquidity Onboarding | Deposit routing and kToken model | Routes to Reserve/Yield by intent class; dual Liquidity Index |
| Partner Onboarding | 5-stage partner lifecycle | Issues credentials; configures fee tiers, corridors, LP class |