Running a keeper
Operating the pending flash/emergency keeper interface, fee monitoring, durable submission and release checks.
Updated Nov 3, 2026
Service roles
| Existing profile | Liquidation responsibility |
|---|---|
lending-trigger | Preview borrowing health and report eligible positions; it signs nothing |
lending-bidder | Quote and submit atomic ordinary borrowing fills |
lending-settler | Quote and submit permitted internal borrowing emergency settlements |
leverage | Preview leverage health, try ordinary fills and then permitted emergency settlement |
sentinel | Read-only discovery and fee-notice monitoring |
Protocol revenue auctions and proposal lifecycle operations remain separate jobs. The Rust runtime executes the liquidation plans; TypeScript independently resolves/encodes plans and checks parity. The TypeScript runtime is not a second live executor in this migration.
Before each attempt
- Discover a candidate, then fetch its position and market directly from RPC. An indexer hint cannot authorize a transaction.
- Read both mints, Clock, custody and reserve accounts, owner payout and current hLP accounts from a sufficiently fresh bank. Check account identities and token-program owners.
- Ask the on-chain preview for eligibility, partial/full permission, exact amounts and fees. Apply the operator's wallet and reward bounds.
- Simulate the complete transaction. Verify debt reduction, net wallet credits, release of the session and preservation of the payment vault's starting balance.
- Re-read the decision state before submission. If market, position, mint schedules or epoch changed, discard the quote and start again.
This direct-RPC policy is for keepers. The webapp continues to use the indexer for displayed protocol state; this update does not introduce frontend polling.
Fee-notice monitoring
Poll mints and Clock even when the market emits no update.
A future schedule affects admission immediately; it enters liquidation health in its final notice epoch. Actual transfers use the current effective schedule until activation.
A schedule change, cancellation, authority change or epoch rollover invalidates cached assumptions.
The monitor prioritizes affected markets and exposes scan failures in readiness. Priority does not bypass health or profitability checks.
If keepers miss the notice window, the later transfer fee can make collateral difficult or impossible to realize. Junior-first then senior funded-loss accounting remains the final backstop; it does not promise full recovery.
Funding and transaction size
The keeper supports ordinary internal Dusk settlement and opt-in inventory purchases.
Inventory mode requires a configured market, maximum wallet payment and minimum net collateral credit. It does not supply an automatic Jupiter route. External route integrations can use the paired builder, provided the fixed payment and keeper wallet bounds are preserved.
ATA preparation can be committed before the liquidation transaction. The flash begin, route and settle always remain together.
Put compute-budget and setup instructions in place before binding the settle index. Larger plans use a configured active, warmed address lookup table; do not split the atomic pair to fit the packet limit.
Minimum rewards are denominated in debt-token atoms. Operators must account for SOL transaction fees, priority fees and rent when choosing them; the keeper does not infer a debt-token/SOL exchange rate.
Durable submission and recovery
A PostgreSQL lease and durable work record must exist before signing. The journal records the observed state, exact message, blockhash, signature and ordered attempt events before submission. Database or lease failure prevents a new signature.
An unknown submission is reconciled using its existing signature. A retry may rebroadcast the exact recorded bytes. It must not refresh the blockhash and create a competing replacement while that signature could still land.
Expiry recovery requires finalized history; missing archival evidence leaves the attempt pending and requires operator attention.
No observation transaction precedes a fill. Eligibility and the discount come from current health at execution, so a fill that fails or loses a race leaves no timer behind; the next attempt quotes again.
Release and alerts
Before live promotion, verify the deployed binaries, program IDs, IDLs, SDK, generated account layouts and compatibility fingerprints against one frozen lock. Apply the database migrations, configure each service wallet and amount limits, and validate the RPC and lookup-table setup. These are release steps, not effects of merging the docs or keeper PR.
Alert on stale or failed fee scans, final-notice exposure with no successful cleanup, pending signatures, missing archival history, DB/lease failures, packet-size failures, low SOL balances and native/TypeScript parity drift. A successful scan or preview is not evidence that an eligible position was liquidated.
See the repository's protocol-upgrade runbook, incident response and keeper builders.