Keepers

Keepers are automated agents that perform essential protocol maintenance operations. They ensure timely settlements, accurate price snapshots, and efficient liquidations.

Overview

The protocol relies on keepers for several critical functions:

• Price Snapshots: Recording oracle prices at key moments
• Settlement Triggers: Executing settlements at expiry
• Liquidation Operations: Processing margin and settlement readiness liquidations

Price Snapshots

Before settlement can occur, a price snapshot must be taken within the settlement window. Keepers monitor expiring series and trigger snapshots:

// Take a snapshot for a single series
takeSnapshot(seriesId);

// Batch snapshot for multiple series
takeSnapshotBatch(seriesId[]);

Timing Requirements:

• Snapshots can only be taken during the settlement window (1 hour before to 1 hour after expiry)
• Each series can only be snapshotted once
• The snapshot price is used for all settlements of that series

Settlement Triggers

After a price snapshot is taken, keepers can trigger settlements:

// Settle a single position
settlePosition(portfolioId, seriesId);

// Batch settlement
settleBatch(portfolioId, seriesId[]);

Keepers earn a small fee for triggering settlements (paid from the settlement gas savings).

Liquidation Operations

Keepers monitor portfolio health and trigger liquidations when:

1. Margin Liquidation: Portfolio equity falls below maintenance margin
2. Settlement Readiness Liquidation: Expiring positions lack sufficient cash for settlement

Margin Liquidation

Triggered when equity < maintenanceMargin. The keeper:

1. Identifies the underwater portfolio
2. Calls liquidate() or liquidateToTarget()
3. Receives bounty from the liquidated portfolio

Settlement Readiness Liquidation

Triggered for positions within 1 day of expiry with net obligations. The keeper:

1. Checks settlement readiness via checkSettlementReadiness()
2. Calls liquidateToTarget() to reduce position size
3. Ensures sufficient cash exists for settlement

Error Handling

Common keeper errors and resolutions:

Competitive Dynamics

Multiple keepers may compete to perform the same operation. The protocol uses:

• First-come-first-served: First successful transaction wins
• No revert on competition: Failed attempts don't penalize keepers
• Gas optimization: Keepers should use appropriate gas settings

Related

• Settlement Engine - Contract implementation
• Liquidation Engine - Liquidation contracts
• Options Settlement - Settlement protocol