DeviationSentinel

The DeviationSentinel is a Venus periphery contract that monitors price deviations between the ResilientOracle and a DEX-based SentinelOracle. When deviations exceed configured thresholds, it routes emergency actions through the EBrake contract to pause market actions and zero collateral factors, protecting the protocol from price manipulation or oracle failures.

Version scope: This API reference follows venus-periphery v1.2.0. DeviationSentinel, EBrake, SentinelOracle, and the DEX oracle contracts are upgradeable. Resolve the current proxy implementation, configured backend, pools, direct-price overrides, keepers, token thresholds, and ACM grants before treating this page as live configuration.

Overview

Price oracle reliability is critical for lending protocols. A compromised or malfunctioning oracle can lead to undercollateralized borrows or improper liquidations. The DeviationSentinel mitigates this risk by continuously comparing prices from two independent sources and taking protective action when they diverge beyond acceptable limits.

The system consists of seven contract types:

Contract	Description
`DeviationSentinel`	Detects price deviations and routes emergency actions through EBrake
`EBrake`	Executes emergency actions (pauses, CF decrease) on the Comptroller
`SentinelOracle`	Aggregator routing per-token to a DEX oracle or returning a direct price override
`UniswapOracle`	Fetches prices from Uniswap V3 pools
`PancakeSwapOracle`	Fetches prices from PancakeSwap V3 pools
`CurveOracle`	Fetches prices from Curve StableSwap-NG pools via `get_dy`
`AerodromeSlipstreamOracle`	Fetches prices from Aerodrome Slipstream (CL) pools — Uniswap V3 fork

Economic Rationale

The deviation response logic is designed to counter specific attack vectors that arise when oracle prices diverge from real market prices.

When DEX Price > Oracle Price (borrow attack):

Attacker deposits an asset (e.g., BNB) as collateral
Borrows the mispriced token at its undervalued oracle price
Sells the borrowed token on DEX at the higher DEX price
Repeats until protocol liquidity is drained

Action: Pause borrowing for the affected asset.

When DEX Price < Oracle Price (collateral attack):

Attacker deposits the mispriced token as collateral, valued at the higher oracle price
Borrows other assets up to the loan-to-value limit
Sells or hedges the collateral token at the lower DEX price
Walks away with profit if the protocol later realigns, leaving bad debt

Action: Set collateral factor to 0 and pause supply for the affected asset.

Thresholds are configured per token to balance incident sensitivity against normal pool volatility. Whether a particular deviation is economically exploitable depends on the configured threshold, available liquidity, pool depth, execution costs, and the rest of the transaction path; the contract does not prove that a smaller deviation is harmless.

Deviation Response Logic

When a deviation is detected, the response depends on the direction:

Condition	Action	Rationale
Sentinel price > Oracle price	Pause borrowing via EBrake	Prevents borrowing out undervalued assets
Sentinel price ≤ Oracle price	Zero collateral factor and pause supply via EBrake	Prevents supplying overvalued assets as collateral

DeviationSentinel can only tighten restrictions. Recovery (unpausing, restoring collateral factors) is handled exclusively via a governance VIP, which calls the corresponding EBrake snapshot reset functions after restoring Comptroller parameters.

Off-Chain Monitoring

An off-chain monitoring service continuously compares the ResilientOracle price with the on-chain price reported by the SentinelOracle for each monitored token (sourced from its configured DEX backend). When the deviation exceeds a configured threshold, the monitor calls handleDeviation via a trusted keeper address, which routes the emergency action through EBrake to pause the affected market.

handleDeviation re-runs the configured check against current on-chain inputs before acting. This prevents a keeper from substituting an arbitrary off-chain price, but it does not make the result independent of the selected DEX pool, spot-price manipulation, token configuration, or a governance-set direct-price override. Once the incident is resolved, a governance VIP restores all parameters on the Comptroller and calls the EBrake snapshot reset functions to prepare for future incidents.

Architecture

One of four DEX-oracle backends (UniswapOracle, PancakeSwapOracle, CurveOracle, or AerodromeSlipstreamOracle) can sit behind SentinelOracle for a token. The live choice is mutable configuration and can differ by token and network.

Inheritance

All DeviationSentinel-system contracts (DeviationSentinel, SentinelOracle, UniswapOracle, PancakeSwapOracle, CurveOracle, AerodromeSlipstreamOracle) inherit from AccessControlledV8 — every privileged setter is gated through the Venus Access Control Manager.

They all use the upgradeable initializer pattern: each constructor sets immutables and calls _disableInitializers(); initialize(address accessControlManager_) wires the ACM on the proxy after deployment.

State Variables

DeviationSentinel

Immutable

Variable	Type	Description
`EBRAKE`	`IEBrake`	EBrake contract through which all emergency actions are executed
`RESILIENT_ORACLE`	`ResilientOracleInterface`	Primary oracle for reference prices
`SENTINEL_ORACLE`	`OracleInterface`	DEX-based oracle for comparison prices

Mutable

Variable	Type	Description
`tokenConfigs`	`mapping(address => DeviationConfig)`	Deviation threshold and enabled status per token
`trustedKeepers`	`mapping(address => bool)`	Addresses authorized to call `handleDeviation`

Constants

Constant	Value	Description
`MAX_DEVIATION`	100	Maximum configurable deviation (100%)

Storage Reservation

Variable	Type	Description
`__gap`	`uint256[48]`	Reserved storage slots for future upgrades (private)

SentinelOracle

Variable	Type	Description
`tokenConfigs`	`mapping(address => TokenConfig)`	Maps tokens to their DEX oracle address
`directPrices`	`mapping(address => uint256)`	Direct price overrides (0 means use DEX oracle)

UniswapOracle / PancakeSwapOracle

Variable	Type	Description
`RESILIENT_ORACLE`	`ResilientOracleInterface`	Immutable reference for pair token prices
`tokenPools`	`mapping(address => address)`	Maps tokens to their DEX pool address

CurveOracle

Variable	Type	Description
`RESILIENT_ORACLE`	`ResilientOracleInterface`	Immutable reference for the reference token’s USD price
`poolConfigs`	`mapping(address => PoolConfig)`	Maps each priced token to its Curve pool routing config

AerodromeSlipstreamOracle

Variable	Type	Description
`RESILIENT_ORACLE`	`ResilientOracleInterface`	Immutable reference for pair token prices
`tokenPools`	`mapping(address => address)`	Maps tokens to their Aerodrome Slipstream pool address

Structs

DeviationConfig

struct DeviationConfig {
    uint8 deviation;   // Maximum allowed deviation percentage (1-100)
    bool enabled;      // Whether monitoring is active for this token
}

DeviationAction

enum DeviationAction {
    BorrowPaused,            // Triggered when sentinel price > oracle price
    SupplyPausedAndCFZeroed  // Triggered when sentinel price <= oracle price
}

TokenConfig (SentinelOracle)

struct TokenConfig {
    address oracle;  // DEX oracle contract address
}

PoolConfig (CurveOracle)

struct PoolConfig {
    address pool;            // Curve StableSwap-NG pool
    uint8   coinIndex;       // index of the priced asset in the pool
    uint8   refCoinIndex;    // index of the reference token in the same pool
    address referenceToken;  // token whose USD price is fetched from ResilientOracle
    uint8   assetDecimals;   // decimals of the priced asset (cached to avoid a per-call STATICCALL)
}

Solidity API

DeviationSentinel

constructor

constructor(IEBrake eBrake_, ResilientOracleInterface resilientOracle_, OracleInterface sentinelOracle_)

Sets the three immutables (EBRAKE, RESILIENT_ORACLE, SENTINEL_ORACLE) and disables initializers on the implementation. Reverts with ZeroAddress if any argument is the zero address.

initialize

function initialize(address accessControlManager_) external initializer

Wires the Access Control Manager. Called once on the proxy after deployment.

handleDeviation

Checks for price deviation on a market and takes protective action. This is the core function called by trusted keepers.

function handleDeviation(IVToken market) external

Parameters

Name	Type	Description
market	IVToken	The vToken market to check and act on

Behavior

Retrieves the underlying token and its deviation config
Calls checkPriceDeviation to compare oracle prices
Returns early if no deviation is detected (prices within configured threshold)
If deviation detected:
- If sentinel price > oracle price: calls EBRAKE.pauseBorrow(market)
- If sentinel price ≤ oracle price: calls EBRAKE.decreaseCF(market, 0) then EBRAKE.pauseSupply(market)
Emits DeviationHandled with the prices and the action taken

Idempotency is handled by EBrake — duplicate calls for an already-paused market are no-ops on the EBrake side.

Access Requirements

Caller must be a trusted keeper

Errors

UnauthorizedKeeper if caller is not a trusted keeper
MarketNotConfigured if token has no deviation config
TokenMonitoringDisabled if monitoring is disabled for the token

checkPriceDeviation

View function that checks whether a market’s underlying token has a price deviation exceeding its configured threshold.

function checkPriceDeviation(
    IVToken market
) public view returns (
    bool hasDeviation,
    uint256 oraclePrice,
    uint256 sentinelPrice,
    uint256 deviationPercent
)

Parameters

Name	Type	Description
market	IVToken	The vToken market to check

Return Values

Name	Type	Description
hasDeviation	bool	True if deviation exceeds the configured threshold
oraclePrice	uint256	Price from the ResilientOracle
sentinelPrice	uint256	Price from the SentinelOracle
deviationPercent	uint256	Calculated deviation as a percentage

Deviation Calculation

deviationPercent = (|oraclePrice - sentinelPrice| / oraclePrice) * 100

If either price is 0, the function sets hasDeviation to true and deviationPercent to type(uint256).max.

setTokenConfig

Configures deviation monitoring parameters for a token.

function setTokenConfig(address token, DeviationConfig calldata config) external

Parameters

Name	Type	Description
token	address	The underlying token address
config	DeviationConfig	Deviation threshold and status

Access Requirements

Governance only (via AccessControlManager)

Errors

ZeroAddress if token is the zero address
ZeroDeviation if config.deviation is 0
ExceedsMaxDeviation if config.deviation exceeds 100

Events

TokenConfigUpdated emitted on success

setTokenMonitoringEnabled

Enables or disables deviation monitoring for a previously configured token.

function setTokenMonitoringEnabled(address token, bool enabled) external

Parameters

Name	Type	Description
token	address	The underlying token address
enabled	bool	Whether monitoring should be active

Access Requirements

Governance only

Errors

ZeroAddress if token is the zero address
MarketNotConfigured if token has no existing config

Events

TokenMonitoringStatusChanged emitted on success

setTrustedKeeper

Adds or removes an address from the trusted keepers list.

function setTrustedKeeper(address keeper, bool isTrusted) external

Parameters

Name	Type	Description
keeper	address	The keeper address
isTrusted	bool	Whether the address should be trusted

Access Requirements

Governance only

Errors

ZeroAddress if keeper is the zero address

Events

TrustedKeeperUpdated emitted on success

SentinelOracle

constructor

constructor()

Disables initializers on the implementation. SentinelOracle has no immutables.

initialize

function initialize(address accessControlManager_) external initializer

Wires the Access Control Manager. Called once on the proxy after deployment.

getPrice

Returns the price of an asset from the configured DEX oracle or a direct price override.

function getPrice(address asset) external view returns (uint256)

Parameters

Name	Type	Description
asset	address	The token address

Return Values

Type	Description
uint256	Asset price in (36 - asset decimals) format

Price Resolution Order

If directPrices[asset] is non-zero, return it
Otherwise, fetch from the configured DEX oracle

Errors

TokenNotConfigured if no oracle is configured and no direct price is set

setTokenOracleConfig

Associates a token with a DEX oracle for price fetching.

function setTokenOracleConfig(address token, address oracle) external

Parameters

Name	Type	Description
token	address	The underlying token address
oracle	address	The DEX oracle address

Access Requirements

Governance only

Errors

ZeroAddress if either address is zero

Events

TokenOracleConfigUpdated emitted on success

setDirectPrice

Sets a direct price override for a token. Set to 0 to revert to DEX oracle pricing.

function setDirectPrice(address token, uint256 price) external

Parameters

Name	Type	Description
token	address	The underlying token address
price	uint256	The price override (0 to use DEX oracle)

Access Requirements

Governance only

Events

DirectPriceUpdated emitted on success

UniswapOracle

constructor

constructor(ResilientOracleInterface resilientOracle_)

Sets the immutable RESILIENT_ORACLE and disables initializers on the implementation.

initialize

function initialize(address accessControlManager_) external initializer

Wires the Access Control Manager. Called once on the proxy after deployment.

getPrice

Returns the price of a token derived from its Uniswap V3 pool.

function getPrice(address asset) external view returns (uint256)

Parameters

Name	Type	Description
asset	address	The token address

Return Values

Type	Description
uint256	Asset price in (36 - asset decimals) format

Price Calculation

Reads sqrtPriceX96 from the Uniswap V3 pool’s slot0
Computes priceX96 = (sqrtPriceX96)² / Q96
Determines target token position (token0 or token1)
Fetches the reference token price from ResilientOracle
Converts the pool ratio to a USD price using the reference price

Errors

TokenNotConfigured if no pool is configured for the token
InvalidPool if the configured pool does not contain the token

setPoolConfig

Associates a token with a Uniswap V3 pool.

function setPoolConfig(address token, address pool) external

Parameters

Name	Type	Description
token	address	The underlying token address
pool	address	The Uniswap V3 pool address

Access Requirements

Governance only

Errors

ZeroAddress if either address is zero

Events

PoolConfigUpdated emitted on success

PancakeSwapOracle

constructor

constructor(ResilientOracleInterface resilientOracle_)

Sets the immutable RESILIENT_ORACLE and disables initializers on the implementation.

initialize

function initialize(address accessControlManager_) external initializer

Wires the Access Control Manager. Called once on the proxy after deployment.

getPrice

Returns the price of a token derived from its PancakeSwap V3 pool. Identical behavior to UniswapOracle.getPrice.

function getPrice(address asset) external view returns (uint256)

setPoolConfig

Associates a token with a PancakeSwap V3 pool. Identical behavior to UniswapOracle.setPoolConfig.

function setPoolConfig(address token, address pool) external

CurveOracle

constructor

constructor(ResilientOracleInterface resilientOracle_)

Sets the immutable RESILIENT_ORACLE and disables initializers. Reverts with ZeroAddress if resilientOracle_ is the zero address.

initialize

function initialize(address accessControlManager_) external initializer

Wires the Access Control Manager. Called once on the proxy after deployment.

getPrice

Returns the price of a token derived from its configured Curve StableSwap-NG pool.

function getPrice(address asset) external view returns (uint256)

Parameters

Name	Type	Description
asset	address	The token address

Return Values

Type	Description
uint256	Asset price in (36 - asset decimals) format

Price Calculation

Reads dy = pool.get_dy(coinIndex, refCoinIndex, 10**assetDecimals) — instantaneous swap output for one unit of the asset, reflecting the current pool state (including any active manipulation).
Fetches the reference token’s USD price refPriceUsd from ResilientOracle.
Computes price = dy * refPriceUsd / 10**assetDecimals.

refDecimals cancels out of the formula, so only assetDecimals is needed at call time. It is cached in the PoolConfig at setup time to avoid an extra STATICCALL per getPrice.

Errors

TokenNotConfigured if no pool is configured for the asset
ZeroPrice if get_dy returns 0

setPoolConfig

Associates a token with a Curve StableSwap-NG pool and its reference-token routing.

function setPoolConfig(
    address token,
    address pool,
    uint8 coinIndex,
    uint8 refCoinIndex,
    address referenceToken,
    uint8 assetDecimals
) external

Parameters

Name	Type	Description
token	address	The token to price
pool	address	The Curve StableSwap-NG pool
coinIndex	uint8	Index of `token` in the pool’s coins array
refCoinIndex	uint8	Index of `referenceToken` in the same pool
referenceToken	address	The pool’s other coin, whose USD price is fetched from ResilientOracle
assetDecimals	uint8	Decimals of `token` (cached to avoid a per-call STATICCALL)

Access Requirements

Governance only

Errors

ZeroAddress if token, pool, or referenceToken is the zero address
AssetMismatch if pool.coins(coinIndex) != token
ReferenceMismatch if pool.coins(refCoinIndex) != referenceToken

Events

PoolConfigUpdated(token, pool, coinIndex, refCoinIndex, referenceToken, assetDecimals) emitted on success

AerodromeSlipstreamOracle

constructor

constructor(ResilientOracleInterface resilientOracle_)

Sets the immutable RESILIENT_ORACLE and disables initializers on the implementation.

initialize

function initialize(address accessControlManager_) external initializer

Wires the Access Control Manager. Called once on the proxy after deployment.

getPrice

Returns the price of a token derived from its configured Aerodrome Slipstream pool.

function getPrice(address asset) external view returns (uint256)

Price Calculation

Aerodrome Slipstream is a concentrated-liquidity AMM (Uniswap V3 fork). Its slot0() returns six values (no feeProtocol field), so the pool ABI is incompatible with IUniswapV3Pool, but the price-derivation math is otherwise identical:

Reads sqrtPriceX96 from the pool’s slot0().
Computes priceX96 = (sqrtPriceX96)² / Q96.
Determines target token position (token0 or token1).
Fetches the reference token price from ResilientOracle.
Converts the pool ratio to a USD price using the reference price.

Uses the current slot0 price (no TWAP). Suitable for sentinel deviation detection where some manipulation tolerance is acceptable.

Errors

TokenNotConfigured if no pool is configured for the token
InvalidPool if the configured pool does not contain the token

setPoolConfig

Associates a token with an Aerodrome Slipstream pool. Identical behavior to UniswapOracle.setPoolConfig.

function setPoolConfig(address token, address pool) external

Errors

ZeroAddress if either address is zero

Events

PoolConfigUpdated emitted on success

Events

DeviationSentinel Events

Event	Parameters	Description
`TokenConfigUpdated`	token, config	Deviation config set for a token
`TokenMonitoringStatusChanged`	token, enabled	Monitoring toggled for a token
`TrustedKeeperUpdated`	keeper, isTrusted	Keeper added or removed
`DeviationHandled`	market, oraclePrice, sentinelPrice, action	Deviation detected and acted on; `action` is a `DeviationAction` enum value

Pause and collateral factor events are now emitted by EBrake (ActionPaused, CollateralFactorDecreased) rather than by DeviationSentinel directly.

SentinelOracle Events

Event	Parameters	Description
`TokenOracleConfigUpdated`	token, oracle	Token associated with DEX oracle
`DirectPriceUpdated`	token, price	Direct price override set

UniswapOracle / PancakeSwapOracle / AerodromeSlipstreamOracle Events

Event	Parameters	Description
`PoolConfigUpdated`	token, pool	Token associated with a DEX pool (V3 / Slipstream)

CurveOracle Events

Event	Parameters	Description
`PoolConfigUpdated`	token, pool, coinIndex, refCoinIndex, referenceToken, assetDecimals	Token associated with a Curve pool route

Security Considerations

Access Control

Governance Functions: All configuration functions (setTokenConfig, setTrustedKeeper, setTokenMonitoringEnabled) are restricted via AccessControlManager
Keeper Functions: handleDeviation is restricted to trusted keepers via the onlyKeeper modifier
Direct Price Overrides: setDirectPrice on SentinelOracle is governance-controlled. A nonzero override replaces the configured DEX-backend value, so its live value is part of the system’s trust and configuration surface.

Separation of Detection and Execution

DeviationSentinel contains only detection logic. All Comptroller interactions (pausing, CF changes) are executed by EBrake. This means:

A keeper cannot supply an arbitrary off-chain price; it can trigger only the EBrake action produced by the configured on-chain comparison. Those on-chain inputs and configurations must still be trusted and monitored.
EBrake enforces its own “tighten only” invariant independently — the sentinel cannot unpause or restore CF even if its logic were modified
Pre-incident state snapshots (original CF, borrow caps, supply caps) are tracked by EBrake, not DeviationSentinel

Recovery

Recovery from a sentinel-triggered freeze requires a governance VIP that:

Restores Comptroller parameters (unpause actions, restore CF)
Calls the appropriate EBrake snapshot reset functions (resetCFSnapshot, resetBorrowCapSnapshot, resetSupplyCapSnapshot) to clear the stored snapshots

Custom Errors

Per-contract reference of revert reasons:

Contract	Errors
`DeviationSentinel`	`ZeroAddress`, `ZeroDeviation`, `ExceedsMaxDeviation`, `UnauthorizedKeeper`, `MarketNotConfigured`, `TokenMonitoringDisabled`
`SentinelOracle`	`ZeroAddress`, `TokenNotConfigured`
`UniswapOracle`	`ZeroAddress`, `InvalidPool`, `TokenNotConfigured`
`PancakeSwapOracle`	`ZeroAddress`, `InvalidPool`, `TokenNotConfigured`
`CurveOracle`	`ZeroAddress`, `TokenNotConfigured`, `AssetMismatch`, `ReferenceMismatch`, `ZeroPrice`
`AerodromeSlipstreamOracle`	`ZeroAddress`, `InvalidPool`, `TokenNotConfigured`

Deployment

See Deployed Contracts for current addresses.

Audits

Published DeviationSentinel and EBrake audit reports are indexed in the venus-periphery v1.2.0 release. Check each report’s scope and reviewed commit against every current proxy implementation and configured oracle backend.