Token Price Oracle enhancement: multi-source aggregation, freshness/heartbeat, anomaly detection

[curryxbo]

Background

Morph's current token-price-oracle service supports Alt Fee Tokens by fetching prices from a single CEX (Bitget) and updating L2TokenRegistry when the deviation crosses a basis-points threshold. This single-source, deviation-only design has several gaps:

• Single point of failure on one CEX
• No on-chain / decentralized oracle cross-check
• No heartbeat — prices can stay stale indefinitely if deviation is small
• No anomaly / circuit-breaker protection against price manipulation
• Limited per-token / per-source observability
• Stablecoins are pinned to $1.0 with no de-peg detection

Goals

1. Improve price reliability via multi-source aggregation and fallback
2. Add manipulation protection via anomaly detection and circuit breakers
3. Integrate industry-standard oracles (Chainlink, Pyth) as off-chain data sources
4. Optional on-chain validation via TWAP for tokens with sufficient liquidity
5. Per-token freshness/staleness metrics and alerting
6. Define exchange-rate risk model and degradation policy

Scope (off-chain only)

The integration boundary is the off-chain token-price-oracle service. Morph contracts (e.g. L2TokenRegistry) keep their existing interface — Chainlink and Pyth are consumed off-chain, then aggregated and written to the existing registry. No Pyth pull-update or Chainlink Aggregator adapter on the contract side.

Key Requirements

• Multi-source price feeds: Chainlink (RPC), Pyth (Hermes / Price Service), Bitget, Binance/OKX (optional), TWAP from Uniswap V2/V3
• Aggregation strategies: median, quorum, weighted average, priority fallback
• Per-source freshness, confidence, precision, and health validation
• Heartbeat: maxStaleness forces an update even if deviation threshold not met
• Anomaly detection: jump detection, multi-source deviation, stablecoin de-peg
• Circuit breakers at token / source / global level
• Per-token + per-source Prometheus metrics, alert rules
• Per-token configuration with hot reload
• Documented exchange-rate risk model and degradation priorities

Non-Goals

• No change to the L2TokenRegistry contract interface
• No change to gas-fee calculation logic
• No new governance / permission mechanism
• Morph business contracts will NOT directly read Chainlink / Pyth feeds
• Not all tokens are required to have Chainlink / Pyth / TWAP support

Phases

• Phase 1 (P0): risk model, Chainlink integration, per-token freshness, heartbeat, base monitoring
• Phase 2 (P1): Pyth integration, TWAP validation, multi-source deviation, anomaly detection
• Phase 3 (P2): quorum / median aggregation, circuit breakers, stablecoin de-peg, more CEX sources
• Phase 4 (P3): performance, hot reload, ops automation

References

• Spec: morph-l2/morph-specs → specs/2026/Q2/spec-006-token-price-oracle-enhancement/spec.md
• Chainlink Price Feeds
• Pyth Pull Updates
• Uniswap V3 Oracle
• Arbitrum Orbit Fee Token Pricer