Skip to main content
ModeController implements a four-state operating mode machine that progressively restricts protocol operations during adverse conditions. The keeper calls checkOracleAndPause() periodically to automate oracle-driven transitions.

​
Contract Relationships

​
State Machine

​
Operations by Mode

OperationNORMALDEGRADEDREDUCE_ONLYPAUSED
Open positionYesNoNoNo
Close positionYesYesYesNo
SettlementYesYesYesNo
LiquidationYesYesYesNo
DepositYesYesYesNo
WithdrawYesYesYesNo

​
Read Functions

​
currentMode

function currentMode() external view returns (Mode)
Returns the current operating mode (NORMAL, DEGRADED, REDUCE_ONLY, or PAUSED).

​
Permission Checks

FunctionReturns true when
canOpenPosition()Mode is NORMAL
canClosePosition()Mode is not PAUSED
canLiquidate()Mode is not PAUSED
canSettle()Mode is not PAUSED
canDeposit()Mode is not PAUSED
canWithdraw()Mode is not PAUSED

​
Degraded Mode State

FunctionReturns
degradedConfig()DegradedConfig struct
degradedEnteredAt()Timestamp when DEGRADED mode was entered (0 if not degraded)
oracleModule()OracleModule contract address

​
Admin Functions

​
enterPausedMode

function enterPausedMode(bytes32 reasonCode) external
Immediately pauses the protocol. Restricted to PAUSER_ROLE. Can be called from any non-paused mode.

​
exitPausedMode

function exitPausedMode(Mode targetMode, bytes32 reasonCode) external
Exits PAUSED mode to either NORMAL or REDUCE_ONLY. Restricted to PAUSER_ROLE.
NameTypeDescription
targetModeModeMust be NORMAL or REDUCE_ONLY
reasonCodebytes32Reason for unpausing

​
setReduceOnly

function setReduceOnly(bool enabled) external
Toggles reduce-only mode. Restricted to DEFAULT_ADMIN_ROLE. Cannot be called from PAUSED.

​
setDegraded

function setDegraded(bytes32 reasonCode) external
Enters DEGRADED mode. Restricted to DEFAULT_ADMIN_ROLE. Can only transition from NORMAL or REDUCE_ONLY.

​
exitDegradedMode

function exitDegradedMode(bytes32 reasonCode) external
Exits DEGRADED mode back to NORMAL. Restricted to DEFAULT_ADMIN_ROLE.

​
checkOracleAndPause

function checkOracleAndPause() external returns (bool)
Checks oracle validity and manages automatic mode transitions. Restricted to PAUSER_ROLE. Called periodically by the keeper. Two-stage escalation:
  1. If oracle is fully invalid → transition to PAUSED
  2. If in DEGRADED and timeout exceeded (degradedDurationSeconds) → escalate to PAUSED
  3. If in DEGRADED and oracle recovers → return to NORMAL
Returns true if oracle is valid, false if degraded or paused.

​
setOracleModule

function setOracleModule(address _oracleModule) external
Sets the OracleModule address for validity checks. Restricted to DEFAULT_ADMIN_ROLE.

​
setDegradedConfig

function setDegradedConfig(DegradedConfig calldata newConfig) external
Updates DEGRADED mode configuration. Restricted to DEFAULT_ADMIN_ROLE.

​
Reason Codes

ConstantValueUsage
REASON_ADMINkeccak256("ADMIN")Manual admin transitions
REASON_ORACLE_INVALIDkeccak256("ORACLE_INVALID")Oracle fully invalid
REASON_ORACLE_DEGRADEDkeccak256("ORACLE_DEGRADED")Oracle deviation detected
REASON_ORACLE_RECOVEREDkeccak256("ORACLE_RECOVERED")Oracle recovered from DEGRADED
REASON_DEGRADED_TIMEOUTkeccak256("DEGRADED_TIMEOUT")DEGRADED mode exceeded duration limit

​
Events

EventWhen Emitted
ModeTransitionAny mode change (includes from, to, reason, actor, timestamp)
OracleModuleSetOracleModule address configured
OracleInvalidatedOracle invalid triggers auto-pause
DegradedConfigUpdatedDegraded config parameters changed

Mode Escalation

Detailed escalation paths and recovery procedures.

Emergency Procedures

Emergency shutdown and recovery playbook.

Oracle Safeguards

Oracle validation checks that trigger mode transitions.