Create Fraud Detection and Anomaly Alerting System, then real-time financial reconciliation engine

[Jumongweb]

Summary

Implemented a real-time fraud/anomaly detection engine and financial reconciliation system in Keeper, fully integrated into the existing execution pipeline and live event flow.

Related Issue

Closes #449
Closes #453

Type of Change

• Feature
• Bug fix
• Refactor
• Documentation

Changes Made

Fraud Detection

• Added heuristic fraud/anomaly engine in keeper/src/fraudDetection.js
• Integrated fraud monitoring into the execution pipeline via keeper/index.js
• Extended metrics and admin visibility in keeper/src/metrics.js
• Added protected /admin/fraud state inspection endpoint
• Added configuration support in keeper/src/config.js
• Added environment variable examples in keeper/.env.example
• Added documentation in:
  • keeper/docs/fraud-detection.md
  • keeper/README.md
• Added test coverage in keeper/__tests__/fraudDetection.test.js

Fraud Detection Behavior

• Detects rapid task bursts
• Detects repeated execution failures
• Detects abnormal fee spikes
• Detects rapid fee-drain patterns
• Debounces duplicate alerts using alert signatures
• Retries outbound webhook delivery with bounded retries and timeout protection
• Falls back safely to local logging and metrics when delivery fails
• Prevents sensitive data leakage in alert payloads

Financial Reconciliation

• Added reconciliation service in keeper/src/reconciliation.js
• Extended registry accounting event emission in keeper/src/registry.js
• Wired reconciliation into startup, polling, and execution completion flows in keeper/index.js
• Extended metrics and admin visibility in keeper/src/metrics.js
• Added configuration and environment support in:
  • keeper/src/config.js
  • keeper/.env.example
• Added documentation in:
  • keeper/docs/reconciliation.md
  • keeper/docs/prometheus-metrics.md
  • keeper/README.md
• Added focused test coverage in keeper/__tests__/reconciliation.test.js

Reconciliation Behavior

• Matches successful execution fees against KeeperPaid balance deductions
• Tracks deposits and withdrawals as separate accounting events
• Detects and alerts on:
  • Accounting mismatches
  • Unresolved executions
  • Balance drift
• Debounces duplicate alerts
• Falls back safely to local logging and metrics when webhook delivery is unavailable or fails
• Exposes protected /admin/reconciliation state inspection endpoint

Validation

• Manual verification completed
• Targeted test suite passed:
  • npm test -- --runInBand --no-coverage __tests__/fraudDetection.test.js __tests__/metrics.test.js
  • npm test -- --runInBand --no-coverage __tests__/reconciliation.test.js __tests__/fraudDetection.test.js __tests__/metrics.test.js
• Syntax validation completed:
  • node --check on all modified runtime files
  • JavaScript syntax checks passed on all changed files
• cargo fmt --all (if contract changed)
• npm run lint in frontend (if frontend changed)

Screenshots (if UI changes)

N/A

Checklist

• Scope is focused and avoids unrelated changes
• Commit messages are clear
• Documentation updated when needed
• ETA was provided when requesting assignment for the linked issue

Notes

• Completed a code-level security review and added supporting controls/documentation.
• A separate formal security audit toolchain was not executed in this workspace.
• __tests__/snapshot_reconciliation.test.js encountered an unrelated workspace dependency issue (which-typed-array missing from node_modules) and was not included in the validation results above.

[drips-wave]

@Jumongweb Great news! 🎉 Based on an automated assessment of this PR, the linked Wave issue(s) no longer count against your application limits.

You can now already apply to more issues while waiting for a review of this PR. Keep up the great work! 🚀

Learn more about application limits