Keeper roles and incentives
Keepers are permissionless bots that liquidate unhealthy positions and execute orders, paid by the instruction they run.
Updated Nov 9, 2026
Keepers submit permissionless transactions for liquidation, orders and market maintenance. Discovery can use indexer hints; eligibility, amounts and execution are checked against fresh on-chain state.
Jobs and incentives
| Job | Instruction | Who may call | Reward |
|---|---|---|---|
| Preview borrowing or leverage health | preview_liquidation_health | Anyone | Read-only; returns current liquidation health |
| Quote and fill collateral | preview_flash_liquidation, begin_flash_liquidation, settle_flash_liquidation | Anyone meeting the bound payment | Profit from the actual collateral discount and execution route |
| Internal emergency settlement | preview_emergency_liquidation, emergency_liquidation | Anyone, when the program permits it | Progressive proceeds share capped at 1%, including insolvent positions |
| Execute a take-profit or stop-loss | delegated_close_leverage with the delegate's before_take_profit / before_stop_loss and after_close_order hooks | Anyone, while the order's trigger holds | 5% of the margin on a full close, or of the net residual on a partial, capped by the proceeds; the owner also pays the 10 bps protocol order fee |
| Execute a limit entry | execute_leverage_entry_order | Anyone, while the price condition holds and the order has not expired | The executor_bounty the order creator escrowed |
| Execute an hLP stop-loss or stop-rate | execute_hlp_order | Anyone, while the trigger holds | 5% of the withdrawal output, rounded up |
| Run a protection order | The delegate's execute_protection_order | Anyone with working capital in the payment asset | Reimbursement of the payment plus the sponsor's chosen reward, at most 10% |
| Restore a stressed hLP hedge | preview_hlp_flash, begin_hlp_flash, settle_hlp_flash | Anyone meeting the bound payment | Profit from the released collateral and chosen execution route |
| Terminal hLP closeout | close_insolvent_hlp | Anyone, once funding has exhausted the vault | A bounded bounty from recovered interest, 0.5% |
| Harvest yield for an LP | harvest | The LP owner, the recipient, or a harvest authority the owner named | Whatever the LP agreed off-chain; the program pays the recipient |
| Roll a paid-down income book | roll_income_epoch | Anyone, once borrowers have paid part of the book | None; until it runs, a fully paid book blocks the market's next interest accrual |
| Compound the junior seed | fund_junior_seed, compound_junior_seed | Anyone; compounding needs spot within 1 bp of the centre average | None; a service to the market's first-loss capital |
| Open the next junior generation | initialize_junior | Anyone, after a wipeout | None; the caller pays rent for the new mint and cohort |
| Execute operator bundles | execute_operator_change | Anyone, after the full notice, with any required successor acceptance | None; a service to the market |
| Settle protocol auctions | settle_protocol_auction | Anyone with the accepted mint | The auction's own pricing versus the market |
Every reward is paid by the instruction that earns it, in the same transaction. There are no off-chain payouts and no whitelist.
Where the work comes from
- Borrowing and leverage. Current health determines eligibility and incentives. Ordinary flash fills execute atomically, and the emergency service uses the on-chain emergency preview. No separate observation transaction is required.
- Orders. Take-profit, stop-loss, entry and hLP orders are accounts on the delegate program. Their triggers are evaluated against the market's closeout price, NAV per share or funding average;
preview_hlp_order_triggerand the entry previews tell you where those stand. - Vault stress. A solvent funding gap can use atomic hLP flash recovery. An exhausted vault can use terminal closeout with explicit loss accounting.
- Lifecycle. Operator bundles whose notice has elapsed, auctions that reached their windows, income books that need a new epoch, and a wiped junior tranche that needs its next generation.
The indexer publishes discovery hints (GET /liquidations, the changes stream, the wallet and statistics payloads), but none of them authorises anything. A keeper re-reads every decision account from RPC immediately before it acts and rebuilds the transaction against the pinned IDL.
Building a fill
Use the matching SDK's DuskLiquidations helpers:
| Helper | Responsibility |
|---|---|
transferFeeNotices | Coherent mint/Clock snapshot for the position's two assets |
previewHealth | Simulate current health without a transaction or timer |
preview / previewAmm / buildFlash | Quote an external purchase or the final internal Dusk-AMM receipt, then build the paired begin/route/settle sequence |
previewEmergency / buildEmergency | Quote and build the permitted internal fallback |
For buildFlash, select internal Dusk settlement or provide a route that credits the isolated repayment vault. The required payment is a net vault credit, so an inventory payment must gross up the current debt-token transfer fee. Include all compute-budget and setup instructions before calculating the bound settle index; do not prepend instructions to a finished plan without rebuilding it.
The reference keeper has native Rust transaction construction and independent TypeScript plan/codec parity. Its automatic execution can use Dusk settlement or explicitly bounded inventory purchases.
Jupiter routing is not supplied by this migration. A route implementation can use the external flash builder; it must independently protect the keeper's wallet and satisfy the quoted payment.
Mutable-fee monitoring
Poll both admitted mints and Clock.
A pending fee affects admission immediately, but liquidation valuation includes it only in the final notice epoch. Transfers always use the effective fee.
Evaluate each schedule's exact rounded, capped fee and choose the worse net credit; do not combine one schedule's rate with the other's cap.
Prioritize affected markets in the final notice epoch, then re-read the position, market, mints, Clock and required hLP state before evaluation and submission. Invalidate a quote on fee-authority or schedule changes, cancellation, rescheduling or epoch rollover. Do not wait for an indexer market-update event: rollover needs no market write.
Races and limits
A successful simulation is not a completed liquidation. Check debt reduction, net token credits, owner payout, session release and preservation of any pre-existing payment-vault balance.
A competing repayment, liquidation or recovered health requires a fresh evaluation. A pending signature must be reconciled before signing a replacement.
The health-based discount does not guarantee a profitable route. Keepers need explicit amount and reward bounds, sufficient SOL for fees/rent, and a warmed address lookup table when the atomic transaction exceeds the packet limit. See keeper operations.