The Keeper includes a reconciliation engine that continuously checks whether every successful execution fee is reflected in the corresponding task balance movement.
The engine compares:
- Successful execution records and their
feePaidvalues KeeperPaidcontract events and the balance delta they produce- Registry snapshots for each task's current
gas_balance
This keeps the accounting model exact and auditable across retries, polling cycles, and service restarts.
- The keeper records each successful execution with its transaction fee.
- The registry emits accounting changes when the contract reports
KeeperPaid,GasDeposited, orGasWithdrawn. - The reconciliation engine matches the execution fee to the corresponding
KeeperPaiddelta. - Any mismatch, unresolved execution, or unexpected balance drift becomes a reconciliation alert.
Alerts are queued and delivered to RECONCILIATION_ALERT_WEBHOOK_URL when configured.
If no webhook is configured, the engine falls back to local logging and metrics.
The alert payload is sanitized and contains only accounting metadata:
- Task ID
- Expected balance
- Observed balance
- Drift amount
- Ledger metadata
- Transaction hash when available
GET /admin/reconciliationreturns the current reconciliation state
This endpoint is protected by the keeper admin token and can be used to inspect:
- Pending executions
- Recent mismatches
- Current balance drift
- Alert delivery status
- Keep
RECONCILIATION_TOLERANCE=0for strict exact accounting - Set
RECONCILIATION_EXECUTION_SETTLING_MSlong enough to cover one poll cycle plus network delay - Configure
RECONCILIATION_ALERT_WEBHOOK_URLfor paging or incident response automation
- No keeper secrets are included in reconciliation payloads
- Accounting events are handled in-process and emitted through structured logs and metrics
- Webhook delivery is bounded by timeout and retry settings