Keeper network

Overview

Keepers are the off-chain operators that keep Atomic's solvency invariant intact. They monitor every open position against on-chain prices and call liquidate() on positions that have crossed the 88% margin loss threshold.

The role exists because Ethereum-family chains do not run code on a schedule. Liquidations need an external trigger; keepers are that trigger.

What a keeper does

1. Subscribe to position state - typically by indexing the AtomicPositionRegistry contract events or polling the subgraph.
2. Monitor on-chain prices for each open position's market via DEX aggregator quotes.
3. Detect positions whose current loss exceeds 88% of margin.
4. Submit a liquidate(positionId) transaction to AtomicTrading.
5. Earn the keeper bounty if the transaction lands first.

The bounty is paid in USDC.e out of the liquidated position's residual margin, before the 12% buffer is returned to the trader.

Why this design

A few alternatives Atomic explicitly does not use:

• Single trusted liquidator. Single point of failure, censorship risk, MEV-extraction concerns.
• Bonded keeper set. Reduces competition, allows keeper collusion, requires governance to adjust.
• Auction-based liquidations. Adds latency at the moment when speed matters most.

Open competition for a fixed bounty maximizes liquidation responsiveness while keeping the system trustless.

Liquidation incentives

The bounty is sized so that:

• Profitable for keepers even on small positions - gas + opportunity cost is comfortably covered.
• Not so generous that it eats into the trader's residual buffer unnecessarily.

The exact bounty schedule is part of AtomicTrading configuration and is published in the contract. Roughly: a flat USDC.e component plus a small percentage of position size, scaling with liquidation size.

Running a keeper

Atomic's keeper interface is fully on-chain and documented; no off-chain registration is needed. A minimal keeper:

while running:
  positions = getOpenPositions()           # via subgraph or registry events
  for p in positions:
      price = quoteAggregatorPrice(p.market)
      if computeLoss(p, price) >= 0.88 * p.margin:
          tx = AtomicTrading.liquidate(p.id)
          broadcast(tx)

Production keepers are more sophisticated:

• Mempool monitoring to front-run other keepers on the same opportunity.
• Private RPC submission (Flashbots-equivalent on Arbitrum) to avoid being sniped.
• Gas pricing strategy to land transactions reliably under congestion.
• Sharded position monitoring to scale to thousands of open positions.

The competitive equilibrium is a handful of well-tuned keeper operations splitting the bounty pool. Atomic does not need to subsidize this - the bounty itself is the entire incentive.

Keeper failure modes

What can go wrong, and what the protocol does about it:

• No keeper picks up a position in time. Possible during extreme network congestion. The bounty rises (per-position bounty grows linearly with how far past the threshold the position has drifted), incentivizing keepers to take the trade even at high gas.
• Keepers collude to delay liquidation. The bounty is paid first-past-the-post; any single non-colluding keeper can break the cartel by submitting first.
• Keeper bug closes positions early. Cannot happen - the on-chain liquidate() function reverts if the threshold has not been hit. Keepers can only submit valid liquidations.

What this means for traders

You do not interact with keepers directly. The relevant takeaways:

• The 88% threshold is enforced on-chain. A keeper triggering early would have its transaction revert.
• Liquidation execution may not happen exactly at 88% - there is a small lag while keepers race to submit. In practice this is typically a fraction of a basis point past the threshold.
• The keeper bounty is part of the close fee, deducted from your buffer. See Liquidations → What happens on liquidation.