MetaOracle (Deviation Timelock)

The MetaOracleDeviationTimelock is a safety wrapper that selects between a primary and backup oracle. It switches to the backup when prices diverge beyond a threshold for a sustained challenge period, and switches back to the primary after prices reconverge for a sustained healing period. The contract implements Morpho’s IOracle interface, so downstream systems can treat it like any other oracle.

Deployments

Use the network-specific factory addresses to deploy new MetaOracleDeviationTimelock instances.

Chain	MetaOracle factory
Ethereum	0x44d049eEd4AD33807859C45bBd3a8eb47917a9F4
Base	0x507f940234005f7c49dfE2F27E361C3b66Fb31CF
Arbitrum	0x4f3F56A045a2D33ceEf1D1fD5F4C776b8bFb2168
Katana	0x53A30343c8A51d685d17c1c40AAe8e76D2B79b68
Polygon	0xd058Fc46edd745B6c883Ef3F775669039235753d
Monad	0x1C1FD6dc5D84C16cD152aC2E91F80327FE3aEd9F
Unichain	0xf1BaEC963675A367E3ADe06A531B6407D78ab2A3
HyperEVM	0x9fAE9968e4e68bEE5ddcb48bb68Fb27CC57ff384

Explorer links reflect current public explorers; swap in preferred explorers if needed.

Audit and source

• MetaOracleDeviationTimelock source: MetaOracleDeviationTimelock.sol

• Factory source: MetaOracleDeviationTimelockFactory.sol

• Audit report (Cantina): MetaOracleDeviationTimelock audit report

Core behavior

• The contract starts with the primary oracle selected after initialization.

• price() reflects whichever oracle is active (primary or backup).

• Deviation is computed as abs(primary - backup) * 1e18 / average(primary, backup).

• A deviation can only trigger a switch after a timelocked challenge; reconvergence can only trigger a switch back after a timelocked healing.

Flow diagram

Primary → backup (challenge)

Backup → primary (healing)

Parameters

• primaryOracle: preferred oracle used in normal conditions.

• backupOracle: fallback oracle used during deviation periods.

• deviationThreshold: maximum allowed relative deviation, scaled by 1e18 (e.g., 0.01e18 for 1%).

• challengeTimelockDuration: seconds a deviation must persist before switching to backup.

• healingTimelockDuration: seconds prices must remain reconverged before switching back to primary.

Initialization rejects zero addresses, equal oracle addresses, non-positive thresholds, and any initial deviation above deviationThreshold.

Challenge flow (primary → backup)

1. Anyone calls challenge() when the primary is active and prices are deviant.

2. The contract starts a challenge timelock (challengeExpiresAt).

3. If prices reconverge before expiry, anyone can call revokeChallenge().

4. After expiry, anyone can call acceptChallenge() while deviation still holds to switch to the backup.

Healing flow (backup → primary)

1. Anyone calls heal() when the backup is active and prices have reconverged.

2. The contract starts a healing timelock (healingExpiresAt).

3. If prices deviate again before expiry, anyone can call revokeHealing().

4. After expiry, anyone can call acceptHealing() while prices are still converged to switch back to the primary.

Example: XAUT/USDT market

Setup

• Primary oracle: XAUT priced from the XAU (gold) reference feed, USDT fixed at 1.

• Backup oracle: XAUT/USDT market TWAP (both legs from market pricing).

Flow

1. As long as the gold reference and the XAUT market price are close, the MetaOracle uses the primary oracle.

2. If XAUT trades away from the gold reference (or USDT drifts), the deviation exceeds the threshold and challenge() starts the timelock.

3. If the deviation persists through the challenge timelock, acceptChallenge() switches pricing to the market TWAP backup.

4. Once the market price reconverges with the gold reference for the healing timelock, acceptHealing() switches back to the primary.

Factory

MetaOracleDeviationTimelock instances are deployed by MetaOracleDeviationTimelockFactory using EIP-1167 clones. Each deployment emits MetaOracleDeployed with the proxy address, implementation, oracle pair, threshold, and timelock durations.