feat(backend): real-time stream anomaly detection & high-velocity drain sentinel (#1469)

[Aj-Kayvee]

Summary

Implements #1469 — a real-time Stream Anomaly Detection & High-Velocity Drain Sentinel.

Today the indexer records every withdrawal and stream creation only after the fact, so a compromised payroll wallet can drain many streams before anyone notices. This PR turns those indexed events into a live risk signal: a new SentinelService maintains sliding-window velocity trackers, evaluates a set of heuristics on every indexed event, grades the resulting incidents by severity, fans alerts out to on-call channels, and — for CRITICAL incidents — attaches an HMAC-signed set_emergency_pause(true) proposal so multisig signers can act immediately instead of hand-authoring the payload.

Closes #1469

What changed

File	Change
backend/src/lib/redis.ts	SlidingWindowTracker built on Redis sorted sets (ZADD / ZREMRANGEBYSCORE) with a bounded in-memory fallback. Exposes getRedisClient().
backend/src/services/sentinel.service.ts	New. The monitoring engine: velocity trackers, heuristic rules, severity grading, cooldown dedup, incident history, alert adapter, circuit-breaker proposer.
backend/src/workers/soroban-event-worker.ts	Feeds tokens_withdrawn and stream_created events into the sentinel (best-effort — analysis failures never quarantine a valid event).
backend/src/controllers/admin.controller.ts	listSentinelAlertsHandler, acknowledgeSentinelAlertHandler.
backend/src/routes/v1/admin.routes.ts	GET /v1/admin/sentinel/alerts, POST /v1/admin/sentinel/alerts/:id/acknowledge.
backend/src/lib/metrics.ts	flowfi_sentinel_incidents_total, flowfi_sentinel_alerts_dispatched_total, flowfi_sentinel_threat_score.
backend/src/config/swagger.ts	SentinelIncident schema.
backend/.env.example	Documented SENTINEL_* configuration.
backend/tests/sentinel-service.test.ts	New. 25 unit tests.
backend/tests/sentinel.admin.test.ts	New. 4 API tests.

Sliding-window velocity trackers

RedisSlidingWindowTracker stores one sample per event in a sorted set, scored by timestamp, and answers two questions in a single range read:

• count — how many events are inside the window,
• sum — the volume, recovered from the weight encoded in each sorted-set member.

Samples age out with ZREMRANGEBYSCORE on the retention horizon at insert time. Reads are deliberately read-only: a narrow snapshot() must not prune the longer history a baseline snapshot() depends on. When REDIS_URL is unset (single instance, tests) the same interface is served by a bounded in-memory implementation, so detection degrades rather than disappearing.

Heuristics & severity

Rule	Trigger
VELOCITY_SPIKE	Per-wallet volume in the rolling window ≥ multiplier × the trailing 24h baseline (default 4× = a 300% increase).
TOKEN_VELOCITY_SPIKE	Same, aggregated across all wallets for one token — catches distributed drains that individually stay under the bar.
MULTI_STREAM_DRAIN	One address withdrawing from more than SENTINEL_MULTI_STREAM_MAX distinct streams inside the ledger window.
HIGH_VALUE_DRAIN	A single withdrawal above the USD notional threshold, or one that drains ≥ SENTINEL_BALANCE_DRAIN_PCT of the stream's deposit (unit-free, so it works without a price feed).
STREAM_CREATION_SPIKE	Burst of new streams for a single token.
ZERO_RUNWAY_FLOOD	More than SENTINEL_ZERO_RUNWAY_FLOOD_THRESHOLD near-zero-runway streams created in a burst.

Severity is LOW / MEDIUM / HIGH / CRITICAL, derived from how far past the threshold the observation is. Repeats of the same rule + subject inside SENTINEL_ALERT_COOLDOWN_MS are suppressed so one attack cannot generate an alert storm.

Alerting & circuit breaker

A unified adapter fans each incident out to Slack, Discord and PagerDuty (any subset configured), with a rich contextual payload — rule, severity, address, token, stream, ledger, evidence, and the threat score. Delivery failures are recorded (flowfi_sentinel_alerts_dispatched_total{channel,outcome}) and logged, but never thrown, so a stale webhook cannot stop the next incident from being detected.

CRITICAL incidents additionally carry circuitBreaker: an HMAC-SHA256-signed set_emergency_pause(true) proposal (payloadHash + signature + reason + incidentId). Signing proves provenance to multisig tooling and cannot be used to move funds.

Admin API

GET  /v1/admin/sentinel/alerts?severity=CRITICAL&address=G...&limit=50
POST /v1/admin/sentinel/alerts/:id/acknowledge

The list endpoint returns the aggregate 0–100 threat score (with a per-severity breakdown), flagged addresses ranked by accumulated risk, and the incident history, newest first. Both routes sit behind the existing requireAdmin + admin rate limiter.

Configuration

All thresholds are env-driven with sane defaults — see the new SENTINEL_* block in backend/.env.example. SENTINEL_ENABLED=false disables the pipeline entirely.

Testing

• backend/tests/sentinel-service.test.ts — tracker contracts (Redis path via a fake sorted-set client + in-memory), every heuristic, all four severity bands, alert fan-out with a mocked fetch, cooldown suppression, threat score / flagged addresses, and an end-to-end simulated coordinated drain (15 withdrawals across 15 streams in one minute) asserting both VELOCITY_SPIKE and MULTI_STREAM_DRAIN fire.
• backend/tests/sentinel.admin.test.ts — route-level tests for the dashboard feed, severity filter, limit, and acknowledge/404.

Test Files  61 passed (61)
     Tests  631 passed | 16 skipped (647)

npx tsc --noEmit is clean for backend/.

Acceptance criteria

• Redis sliding-window velocity tracker calculates withdrawal rate per address and per token.
• Threshold breaches categorize severity (LOW / MEDIUM / HIGH / CRITICAL).
• Webhook alerts are dispatched to configured endpoints with rich contextual incident payloads.
• Admin API exposes active threat scores and flagged transaction lists.
• Test suite simulates rapid drain attacks and verifies timely alert triggering.

🤖 Generated with Codebuff