security: H-03 sequencer uptime check + H-04 bad debt resolution

Fixes two confirmed HIGH findings from internal pre-audit security review
prior to LOTIQUE LAB submission.

H-03 (OracleModule): Add Chainlink L2 sequencer uptime check to getPrice().
When sequencerFeed is configured, reverts if the Arbitrum sequencer is down
or within the 3600-second post-restart grace period (SEQ_GRACE_PERIOD).
Optional: address(0) disables the check for non-Arbitrum networks. Wired
to Arbitrum One sequencer feed (0xFdB631F5EE196F0ed6FAa767959853A9F217697D)
in .env.mainnet.example and both deploy scripts via SEQUENCER_FEED env var.
OracleModule constructor gains a fourth parameter: address sequencerFeed_.

H-04 (VaultManager): Add resolveBadDebt() GUARDIAN-gated emergency function
for irrecoverably underwater positions where seize > collateral prevents
normal liquidation. Clears vault state, seizes remaining collateral to
caller, tracks uncovered debt in totalBadDebt, emits BadDebtResolved event.
Operable while paused for incident response. Normal liquidation unaffected.

Tests: +22 new tests (OracleModuleSequencer.t.sol, VaultBadDebt.t.sol).
183/183 tests pass. All existing test suites updated for new constructor sig.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Author: NEXUS120-Official

.env.mainnet.example

@@ -0,0 +1,88 @@
+# ============================================================
+# NEXUS Finance — Mainnet Environment Template
+# Network: Arbitrum One (chain ID 42161)
+# Date: 2026-03-21
+# ============================================================
+# USAGE:
+#   cp .env.mainnet.example .env.mainnet
+#   Fill in [TBD] values before deploy
+#   source .env.mainnet
+#   forge script script/DeployCoreHardened.s.sol --rpc-url $ARBITRUM_ONE_RPC_URL --broadcast
+#
+# SECURITY:
+#   NEVER commit .env.mainnet to version control.
+#   .env.mainnet is in .gitignore.
+# ============================================================
+
+# -------------------------------------------------------
+# RPC
+# -------------------------------------------------------
+ARBITRUM_ONE_RPC_URL=https://arb1.arbitrum.io/rpc
+
+# -------------------------------------------------------
+# ORACLE PARAMETERS
+# Confirmed: Oracle Phase 2.1 (2026-03-21)
+# Evidence: docs/ORACLE_MAINNET_CONFIG.md
+# -------------------------------------------------------
+
+# Chainlink ETH/USD feed on Arbitrum One
+# Verified on-chain: decimals=8, description="ETH / USD", version=4
+# Live at block 444134833: answer=$2,155.71, age=146s
+ORACLE_FEED=0x639Fe6ab55C921f74e7fac1ee960C0B6293ba612
+
+# H-03 FIX: Chainlink Arbitrum One sequencer uptime feed.
+# Required for Arbitrum deployments to enforce sequencer liveness check.
+# Prevents liquidation raids on positions that could not defend themselves
+# during sequencer downtime. Grace period: 3600s (OracleModule.SEQ_GRACE_PERIOD).
+# Source: https://docs.chain.link/data-feeds/l2-sequencer-feeds
+# Verified on Arbitrum One: latestRoundData().answer==0 (sequencer up), decimals=0
+SEQUENCER_FEED=0xFdB631F5EE196F0ed6FAa767959853A9F217697D
+
+# OracleModule.maxDelay (seconds)
+# Empirically derived: 25-round analysis, max gap=1261s, 3600s = 2.85× max
+# Deviation-driven feed (0.05%) — not heartbeat-driven
+ORACLE_MAX_DELAY=3600
+
+# VaultManager.maxDelay (seconds)
+# MUST equal ORACLE_MAX_DELAY — tighter value silently governs all vault ops
+VAULT_MAX_DELAY=3600
+
+# -------------------------------------------------------
+# COLLATERAL
+# -------------------------------------------------------
+# WETH on Arbitrum One — confirm via:
+#   cast call 0x82aF49447D8a07e3bd95BD0d56f35241523fBab1 "symbol()(string)" --rpc-url $ARBITRUM_ONE_RPC_URL
+# Expected: "WETH"
+COLLATERAL_ADDRESS=0x82aF49447D8a07e3bd95BD0d56f35241523fBab1
+
+# -------------------------------------------------------
+# VAULT PARAMETERS
+# -------------------------------------------------------
+# Confirm these against NXUSD_GENESIS_PARAMETERS.md before deploy
+MIN_COLLATERAL_RATIO_BPS=15000    # 150%
+LIQUIDATION_RATIO_BPS=13000       # 130%
+CLOSE_FACTOR_BPS=5000             # 50%
+KEEPER_BONUS_BPS=500              # 5%
+
+# -------------------------------------------------------
+# GOVERNANCE ADDRESSES
+# TBD — fill before deploy
+# -------------------------------------------------------
+MAINNET_SAFE=[TBD]                # New mainnet Safe — NOT the testnet Safe
+MAINNET_TIMELOCK=[TBD]            # Deployed via DeployTimelockController.s.sol (GOV-03)
+MAINNET_GUARDIAN=[TBD]            # Option A or B from MAINNET_OPERATIONS_PACK.md
+MAINNET_KEEPER_BOT=[TBD]          # Primary automated keeper address
+MAINNET_KEEPER_BACKUP=[TBD]       # Secondary keeper address
+
+# -------------------------------------------------------
+# DEPLOY CREDENTIALS
+# TBD — provide at deploy time; never store in file
+# -------------------------------------------------------
+# PRIVATE_KEY=[deployer private key — provide via env at deploy time]
+# ARBISCAN_API_KEY=[for contract verification]
+
+# -------------------------------------------------------
+# SUPPLY CAP
+# -------------------------------------------------------
+# 0 = inactive at deploy; activate via governance post-launch
+INITIAL_SUPPLY_CAP=0

script/DeployCore.s.sol

@@ -14,6 +14,10 @@ contract DeployCore is Script {
         address oracleFeed;
         address collateralToken;
         address keeper;
+        // H-03: Chainlink L2 sequencer uptime feed. address(0) disables the check.
+        // Set to 0xFdB631F5EE196F0ed6FAa767959853A9F217697D on Arbitrum One.
+        // Leave as address(0) on testnets or non-Arbitrum networks.
+        address sequencerFeed;
         uint256 oracleMaxDelay;
         uint256 vaultMaxDelay;
         uint256 minCollateralRatioBps;
@@ -26,6 +30,9 @@ contract DeployCore is Script {
         cfg.oracleFeed = vm.envAddress("ORACLE_FEED");
         cfg.collateralToken = vm.envAddress("COLLATERAL_TOKEN");
         cfg.keeper = vm.envAddress("KEEPER");
+        // SEQUENCER_FEED: set to address(0) for testnets; Arbitrum One sequencer
+        // uptime feed address for mainnet. See OracleModule.sequencerFeed.
+        cfg.sequencerFeed = vm.envOr("SEQUENCER_FEED", address(0));
 
         cfg.oracleMaxDelay = vm.envUint("ORACLE_MAX_DELAY");
         cfg.vaultMaxDelay = vm.envUint("VAULT_MAX_DELAY");
@@ -42,7 +49,7 @@ contract DeployCore is Script {
 
         NXUSDToken nxusd = new NXUSDToken(cfg.admin);
 
-        OracleModule oracle = new OracleModule(cfg.admin, cfg.oracleFeed, cfg.oracleMaxDelay);
+        OracleModule oracle = new OracleModule(cfg.admin, cfg.oracleFeed, cfg.oracleMaxDelay, cfg.sequencerFeed);
 
         VaultManager vault = new VaultManager(
             cfg.admin,
@@ -73,6 +80,7 @@ contract DeployCore is Script {
         console2.log("Admin             :", cfg.admin);
         console2.log("Keeper            :", cfg.keeper);
         console2.log("Oracle Feed       :", cfg.oracleFeed);
+        console2.log("Sequencer Feed    :", cfg.sequencerFeed);
         console2.log("Collateral Token  :", cfg.collateralToken);
     }
 }

script/DeployCoreHardened.s.sol

@@ -21,6 +21,10 @@ contract DeployCoreHardenedScript is Script {
         address collateralToken;
         address keeper;
         address guardian;
+        // H-03: Chainlink L2 sequencer uptime feed. address(0) disables the check.
+        // Arbitrum One: 0xFdB631F5EE196F0ed6FAa767959853A9F217697D
+        // Testnets / non-Arbitrum: address(0)
+        address sequencerFeed;
         uint256 oracleMaxDelay;
         uint256 vaultMaxDelay;
         uint256 minCollateralRatioBps;
@@ -34,6 +38,9 @@ contract DeployCoreHardenedScript is Script {
         cfg.collateralToken = vm.envAddress("COLLATERAL_TOKEN");
         cfg.keeper = vm.envAddress("KEEPER");
         cfg.guardian = vm.envAddress("GUARDIAN");
+        // SEQUENCER_FEED: mandatory for Arbitrum One mainnet deployments.
+        // Omitting or setting to address(0) disables the H-03 protection.
+        cfg.sequencerFeed = vm.envOr("SEQUENCER_FEED", address(0));
 
         cfg.oracleMaxDelay = vm.envUint("ORACLE_MAX_DELAY");
         cfg.vaultMaxDelay = vm.envUint("VAULT_MAX_DELAY");
@@ -50,7 +57,7 @@ contract DeployCoreHardenedScript is Script {
 
         NXUSDToken nxusd = new NXUSDToken(cfg.admin);
 
-        OracleModule oracle = new OracleModule(cfg.admin, cfg.oracleFeed, cfg.oracleMaxDelay);
+        OracleModule oracle = new OracleModule(cfg.admin, cfg.oracleFeed, cfg.oracleMaxDelay, cfg.sequencerFeed);
 
         VaultManager vault = new VaultManager(
             cfg.admin,
@@ -93,6 +100,7 @@ contract DeployCoreHardenedScript is Script {
         console2.log("Keeper            :", cfg.keeper);
         console2.log("Guardian          :", cfg.guardian);
         console2.log("Oracle Feed       :", cfg.oracleFeed);
+        console2.log("Sequencer Feed    :", cfg.sequencerFeed);
         console2.log("Collateral Token  :", cfg.collateralToken);
         console2.log("Vault paused      :", vault.paused());
         console2.log("Liq paused        :", liq.paused());

script/DeploySmokeStack.s.sol

@@ -49,7 +49,7 @@ contract DeploySmokeStack is Script {
 
         NXUSDToken nxusd = new NXUSDToken(cfg.admin);
 
-        OracleModule oracle = new OracleModule(cfg.admin, address(feed), cfg.oracleMaxDelay);
+        OracleModule oracle = new OracleModule(cfg.admin, address(feed), cfg.oracleMaxDelay, address(0));
 
         VaultManager vault = new VaultManager(
             cfg.admin,

src/oracle/OracleModule.sol

@@ -12,24 +12,52 @@ interface IAggregatorV3 {
 }
 
 contract OracleModule is AccessControl {
+    /// @notice Hard upper bound on maxDelay. Prevents disabling freshness checks
+    ///         via extreme values (e.g. type(uint256).max). 7 days is generous
+    ///         enough for irregular testnet feeds while blocking the attack vector.
+    uint256 public constant MAX_DELAY = 7 days;
+
+    /// @notice Grace period enforced after Arbitrum sequencer restart before prices
+    ///         are accepted. Prevents liquidation raids on positions that could not
+    ///         defend themselves during sequencer downtime.
+    ///         Chainlink recommendation for Arbitrum L2 deployments: minimum 3600s.
+    uint256 public constant SEQ_GRACE_PERIOD = 3600;
+
     IAggregatorV3 public feed;
     uint256 public maxDelay;
 
+    /// @notice Chainlink L2 sequencer uptime feed. address(0) = check disabled.
+    ///         Must be set to the Arbitrum sequencer uptime feed on Arbitrum One:
+    ///         0xFdB631F5EE196F0ed6FAa767959853A9F217697D
+    ///         Leave as address(0) on non-Arbitrum networks or in testing.
+    IAggregatorV3 public sequencerFeed;
+
     event OracleFeedSet(address indexed feed, address indexed by);
     event OracleMaxDelaySet(uint256 maxDelay, address indexed by);
+    event SequencerFeedSet(address indexed feed, address indexed by);
 
-    constructor(address admin, address feed_, uint256 maxDelay_) {
+    /// @param admin           Address granted DEFAULT_ADMIN_ROLE.
+    /// @param feed_           Chainlink price feed address.
+    /// @param maxDelay_       Maximum accepted age of price data (seconds).
+    /// @param sequencerFeed_  Chainlink L2 sequencer uptime feed. address(0) disables
+    ///                        the check (use on non-Arbitrum networks or in tests).
+    constructor(address admin, address feed_, uint256 maxDelay_, address sequencerFeed_) {
         require(admin != address(0), "ORACLE: admin is zero");
         require(feed_ != address(0), "ORACLE: feed is zero");
         require(maxDelay_ > 0, "ORACLE: maxDelay is zero");
+        require(maxDelay_ <= MAX_DELAY, "ORACLE: maxDelay too large");
 
         _grantRole(DEFAULT_ADMIN_ROLE, admin);
 
         feed = IAggregatorV3(feed_);
         maxDelay = maxDelay_;
 
+        // sequencerFeed_ == address(0) is valid and disables the uptime check.
+        sequencerFeed = IAggregatorV3(sequencerFeed_);
+
         emit OracleFeedSet(feed_, admin);
         emit OracleMaxDelaySet(maxDelay_, admin);
+        emit SequencerFeedSet(sequencerFeed_, admin);
     }
 
     function setFeed(address feed_) external onlyRole(DEFAULT_ADMIN_ROLE) {
@@ -47,11 +75,46 @@ contract OracleModule is AccessControl {
 
     function setMaxDelay(uint256 maxDelay_) external onlyRole(DEFAULT_ADMIN_ROLE) {
         require(maxDelay_ > 0, "ORACLE: maxDelay is zero");
+        require(maxDelay_ <= MAX_DELAY, "ORACLE: maxDelay too large");
         maxDelay = maxDelay_;
         emit OracleMaxDelaySet(maxDelay_, msg.sender);
     }
 
+    /// @notice Set or clear the Arbitrum L2 sequencer uptime feed.
+    ///         Pass address(0) to disable the check (non-Arbitrum networks).
+    ///         Pass the Chainlink sequencer uptime feed address to enable it.
+    function setSequencerFeed(address sequencerFeed_) external onlyRole(DEFAULT_ADMIN_ROLE) {
+        sequencerFeed = IAggregatorV3(sequencerFeed_);
+        emit SequencerFeedSet(sequencerFeed_, msg.sender);
+    }
+
+    /// @notice Returns the current price from the configured Chainlink feed.
+    ///
+    ///         H-03 FIX: When sequencerFeed is configured, checks the Chainlink
+    ///         Arbitrum sequencer uptime feed before accepting any price data:
+    ///           - answer == 0: sequencer is up (Chainlink convention)
+    ///           - answer != 0: sequencer is down → revert
+    ///           - SEQ_GRACE_PERIOD must have elapsed since last sequencer restart
+    ///             before prices are accepted, preventing liquidation raids on positions
+    ///             that could not be defended during downtime.
     function getPrice() external view returns (uint256 price, uint256 updatedAt, uint8 decimals) {
+        // ── L2 sequencer uptime check ─────────────────────────────────────────
+        // Only executed when sequencerFeed is configured (non-zero).
+        // Chainlink L2 sequencer uptime feed convention:
+        //   latestRoundData().answer == 0 → sequencer is UP
+        //   latestRoundData().answer != 0 → sequencer is DOWN
+        //   latestRoundData().startedAt   → timestamp of last state change
+        //
+        // After a restart (answer flips to 0), startedAt records the restart time.
+        // The grace period ensures that at least SEQ_GRACE_PERIOD seconds have passed
+        // since restart before any price-sensitive operation is allowed, giving users
+        // time to respond to price changes that occurred during downtime.
+        if (address(sequencerFeed) != address(0)) {
+            (, int256 seqAnswer, uint256 seqStartedAt,,) = sequencerFeed.latestRoundData();
+            require(seqAnswer == 0, "ORACLE: sequencer down");
+            require(block.timestamp - seqStartedAt >= SEQ_GRACE_PERIOD, "ORACLE: sequencer grace period");
+        }
+
         decimals = feed.decimals();
 
         (, int256 answer,, uint256 upd,) = feed.latestRoundData();