Protocol

Keeper

The bot that makes promises self-executing, and how to run your own.

Every payout in Par is permissionless: anyone can trigger a missed installment, execute a claim or force-settle a defaulter. The keeper is a small Node.js bot that does it automatically, so promises execute themselves.

Source: keeper/src/index.ts

What it automates#

JobConditionCall
Missed installmentsScheduled commitment, index unsettled, now > due + grace, before expiryvault.triggerMissed(id, index, up, lo)
ClaimsOpen and undisputed after the challenge window, or disputed and unresolved past disputedAt + 7 daysvault.executeClaim(id, up, lo)
Circuit defaultersnow ≥ cycleClose + settleWindow, net < 0, unsettledcircuit.forceSettle(circle, cycle, debtor, up, lo)
Expired commitmentsPast expiry, no open claim; an expired clearing line the circuit is still owed on is skipped (LineOwed) (on by default)vault.closeCommitment(id)
Health watchhealth(0).ok == falseAlert the owner (under-reserved)
Inactive troveTrove closed or liquidated with active commitmentsAlert (trove-inactive)
Recovery ModeA call reverts RecoveryModeNeedsReserve(btc)Alert with the BTC needed, retry next tick

It runs every 15 seconds. Every call is simulated first, so a job that is not due, or that someone else already did, costs nothing. It uses chain time (the latest block timestamp), not wall-clock time. Hints come from HintHelpers and SortedTroves, with zero hints as a fallback.

Run it#

Terminal
cd keepernpm installFACTORY=0x2907A39A64c3f304E7eEdF2F7107Bc825756E4f0 CIRCUIT=0x198099cF3C11A6A7E0f107a63B013E20A96f9CB1 KEEPER_KEY=<private key> npm start# one pass and exit:npm run once

The keeper key pays gas in BTC. Use a dedicated key with a small balance; the keeper alerts when its balance runs low.

Configuration#

VariableDefaultMeaning
FACTORYrequiredParFactory address.
CIRCUITunsetParCircuit address. Circuit jobs are skipped without it.
KEEPER_KEYrequiredPrivate key that sends transactions. Keep it secret.
CHAINtestnettestnet, mainnet or local.
RPC_URLchain defaultCustom RPC endpoint.
INTERVAL_MS15000Time between ticks.
AUTO_CLOSE_EXPIREDtrueClose expired commitments to free capacity.
ALERT_WEBHOOK_URLunsetJSON webhook for alerts.
TELEGRAM_BOT_TOKEN, TELEGRAM_CHAT_IDunsetSend alerts to Telegram.
ALERT_COOLDOWN_MS30 minutesMinimum time between repeats of the same alert.
LOW_BALANCE_BTC0.005Alert when the keeper's balance falls below this.
CIRCUIT_LOOKBACK_CYCLES3How many past cycles to check for unsettled debtors.
MAX_RETRIES40Attempts before a failing job raises job-keeps-failing.
TROVE_MANAGER, HINT_HELPERS, SORTED_TROVESofficial addressesOverride the contracts used for hints.

Without a webhook or Telegram, alerts go to the log only.

Run your own#

Nothing in Par depends on the official keeper. Anyone can run one, and beneficiaries can trigger their own payouts from the app or a block explorer. A deployment template for Railway (keeper/railway.json) and a Dockerfile are included.

Last updated 16 November 2026Suggest an edit on GitHub