feat(pegs): L2 oracle health monitor — stables/oracles.py (#301)

[spalen0]

Closes #301. Layer 2 of peg monitoring.

⚠️ Stacked on #305 (foundation). Base is feat/peg-monitoring-foundation, not main — review/merge #305 first, then this retargets to main automatically. The diff below is L2-only.

What this is

Where protocols/stables/main.py watches market price (DeFiLlama, fast profile), this watches the on-chain oracles our lending markets actually liquidate on — the real liquidation-risk signal. Driven entirely by the shared PeggedAsset registry from the foundation.

Checks

Chainlink-backed assets (USDC, USDT, USDS, USDe, cbBTC, LBTC):

• Staleness — now − updatedAt > heartbeat + buffer.
• Round sanity / monotonicity — positive answer, completed round, answeredInRound ≥ roundId, and a non-decreasing roundId vs the cached run.
• Deviation from peg — oracle price vs the asset's PegTarget.
• Oracle ↔ market divergence — Chainlink vs DeFiLlama.

Each check is a pure Alert | None function, so the forced-stale / forced-divergence / off-peg / round-malfunction cases are unit-tested without a chain (acceptance criterion).

Rate / fundamental oracles: generic monotonicity + delta-vs-cached handler (reuses the apyusd approach). A monotonic/capped decrease is CRITICAL (per #196).

Severity

Condition	Severity
Non-positive answer / incomplete round / roundId backwards	CRITICAL
Lagging answeredInRound	HIGH
Staleness, peg deviation, market divergence	HIGH
Fundamental-oracle monotonic decrease	CRITICAL
Fundamental-oracle delta beyond threshold	HIGH

Tenderly coverage / gap analysis (per #196 step 6)

TENDERLY_COVERED documents the LBTC Redstone fundamental oracle (0xb415…0bc81, capped @ 1) which already has a Tenderly alert — so it is not double-polled here. The registry currently exposes no uncovered fundamental oracle; the docstring records exactly what data a new one needs (address, read fn + precision, monotonic/capped flag) to be wired as a rate_oracle.

Foundation change

Added ChainlinkFeed.quote: PegTarget (default USD) so BTC-denominated feeds (LBTC/BTC) convert to a USD basis for the divergence comparison; LBTC's feed marked quote=BTC. Backward-compatible.

Tunables (env-overridable)

PEG_ORACLE_STALENESS_BUFFER (600s), PEG_ORACLE_DIVERGENCE_THRESHOLD (1%), PEG_ORACLE_RATE_DELTA_THRESHOLD (5%).

Automation

Added stables-oracles to the hourly profile in automation/jobs.yaml (renders; hourly now 24 tasks; test_automation_* green).

Validation

• ruff format + ruff check clean; mypy clean on new modules (remaining errors pre-exist in utils/abi.py/utils/web3_wrapper.py).
• 52 passed peg tests (incl. forced-stale/-divergence) + 13 passed automation tests.
• Live mainnet smoke run reads all 6 feeds and computes peg/market deviations correctly — e.g. LBTC oracle $60,405 = 1.0043 BTC × $60,146, all within tolerance → 0 alerts, 1 Tenderly-covered oracle skipped.

Decisions for review

• Divergence threshold defaults to 1% globally; could be made per-asset if BTC assets need a looser band.
• LBTC Redstone left document-only (Tenderly-covered) rather than actively polled, to avoid duplicate alerts. Say the word if you'd prefer active polling here too.

🤖 Generated with Claude Code