Bots
Summary
The protocol relies on two off-chain bots: (1) a liquidation bot (keeper) that monitors open positions and submits liquidate_position when a position falls below its maintenance margin, and (2) a market-maker bot that organizes vault liquidity on the order book.
Both bots are permissionless: anyone can run one and earn liquidation fees (liquidation bot) or manage vault liquidity (MM bot).
Neither bot brings its own trading capital, both execute trades against vault liquidity. The MM bot places its two-sided quotes using the Market-Making Vault, giving the order book the depth needed for organic trading and for liquidations to close at a fair price. The Liquidation Vault holds a separate reserve, drawn on only when a liquidated position is insolvent and the book alone can't cover the shortfall.
Responsibilities
| Responsibility | On-chain or Off-chain | Notes |
|---|---|---|
| Market making (MM bot) | Off-chain monitoring + on-chain execution | Places and manages two-sided quotes for the Market-Making Vault |
| Funding settlement | Permissionless | Anyone can call it, protocol keeper calls it periodically as a fallback |
| Liquidations | Off-chain monitoring + on-chain execution | Core liquidation bot responsibility |
Liquidation Flow
Liquidation Mechanics
When a position is liquidated:
- The keeper submits
liquidate_position - The program verifies that the position's margin ratio is genuinely below the maintenance threshold at the current mark price
- The position is closed at mark price
- The remaining margin is distributed:
- Liquidation fee - paid to the keeper as incentive
- Remaining collateral - returned to the user (if any)
- If the position is insolvent (mark price moved past liquidation price), the insurance fund covers the shortfall
| Parameter | Description |
|---|---|
maintenance_margin | Minimum margin ratio before liquidation is allowed (per market, set by admin) |
liquidation_fee | Percentage of position size paid to the liquidator (set in GlobalConfig) |
insurance_fund | Protocol-held USDC reserve that covers insolvent liquidations |
Position Monitoring
The keeper needs to efficiently monitor all open positions to detect liquidation candidates. There are two approaches:
| Approach | How it works | Trade-off |
|---|---|---|
| Poll all positions | Fetch all Position PDAs periodically via getProgramAccounts | Simple, slightly laggy at high position counts |
| Account subscriptions | Subscribe to Position account changes via WebSocket RPC | Real-time updates |
Incentive Design
The liquidation fee must be large enough to cover:
- Solana transaction fee (~0.000005 SOL)
- VAA fetch
- Keeper operational costs
If the fee is too low, no external bot will bother liquidating. If it is too high, users lose more collateral than necessary. A typical range is 0.5% - 1% of the position notional value.
Because liquidation is permissionless, MEV bots and external keepers naturally compete to liquidate underwater positions as quickly as possible. The protocol benefits from this competition, it reduces the risk of positions staying underwater long enough to become insolvent.
Funding Settlement
settle_funding is a permissionless instruction that applies the accumulated funding payment to all open positions for a market. The keeper calls it periodically, but any wallet can call it.
Interval enforcement: The program only applies funding if now >= last_funding_timestamp + funding_interval. Calls made before the interval has elapsed are no-ops, the instruction returns without changing any state. This means the keeper can call settle_funding freely without risk of double-applying payments. The funding_interval is configured per market (e.g. 1 hour) and the last_funding_timestamp is stored in FundingState.
If nobody calls it: Funding accumulates in FundingState and is applied lazily the next time a user interacts with their position (e.g. close_position, withdraw_margin). The protocol remains correct even if the keeper misses several intervals, users simply receive or pay the accrued amount at their next interaction.