@ubk-labs/ubk-oracle 0.1.6 → 0.1.8

package/contracts/constants/UBKOracleConstants.sol

@@ -3,7 +3,6 @@ pragma solidity ^0.8.20;
 
 import "@ubk-labs/ubk-commons/contracts/constants/UBKConstants.sol";
 
-
 library UBKOracleConstants {
     // -----------------------------------------------------------------------
     // UBK System Constants
@@ -27,12 +26,14 @@ library UBKOracleConstants {
     // -----------------------------------------------------------------------
     // Oracle Staleness Periods
     // -----------------------------------------------------------------------
-    uint256 public constant ORACLE_DEFAULT_STALE_PERIOD = 1 hours;
     uint256 public constant ORACLE_MIN_STALE_PERIOD = 1 hours;
-    uint256 public constant ORACLE_MAX_STALE_PERIOD = 3 hours;
+    uint256 public constant ORACLE_MAX_STALE_PERIOD = 48 hours;
+
+    uint256 public constant ORACLE_DEFAULT_STALE_FALLBACK_MULTIPLIER = 2; //2x stale
+    uint256 public constant ORACLE_MAX_STALE_FALLBACK_MULTIPLIER = 3; //3x stale
 
     // -----------------------------------------------------------------------
     // Oracle Recursion
     // -----------------------------------------------------------------------
-    uint256 public constant MAX_RECURSION_DEPTH = 5;
+    uint256 public constant ORACLE_MAX_RECURSION_DEPTH = 5;
 }

package/contracts/core/UBKOracle.sol

@@ -14,7 +14,7 @@ import "../constants/UBKOracleConstants.sol";
 
 /**
  * @title Oracle
- * @notice This contract is an implementation of the IOracle interface.
+ * @notice This contract is an implementation of the IUBKOracle interface.
  *
  * @dev
  *  The oracle computes normalized 1e18 prices for all supported assets,
@@ -63,11 +63,10 @@ contract UBKOracle is IUBKOracle, Ownable {
     mapping(address => VaultRateBounds) public vaultRateBounds;
 
     /// @notice Maximum staleness period for Chainlink feeds (seconds).
-    uint256 public stalePeriod = UBKOracleConstants.ORACLE_DEFAULT_STALE_PERIOD;
+    mapping(address => uint256) public stalePeriod;
 
     /// @notice Staleness tolerance for fallback prices (seconds).
-    uint256 public fallbackStalePeriod =
-        UBKOracleConstants.ORACLE_DEFAULT_STALE_PERIOD * 2;
+    mapping(address => uint256) public fallbackStalePeriod;
 
     OracleMode public mode = OracleMode.NORMAL;
 
@@ -102,7 +101,7 @@ contract UBKOracle is IUBKOracle, Ownable {
 
     /// @notice Prevents infinite recursion when resolving nested ERC4626 vaults.
     modifier checkRecursion() {
-        if (_recursionDepth >= UBKOracleConstants.MAX_RECURSION_DEPTH)
+        if (_recursionDepth >= UBKOracleConstants.ORACLE_MAX_RECURSION_DEPTH)
             revert RecursiveResolution(address(0));
         _recursionDepth++;
         _;
@@ -125,16 +124,20 @@ contract UBKOracle is IUBKOracle, Ownable {
 
     /**
      * @notice Sets the maximum time (in seconds) a Chainlink feed value is valid.
-     * @param period The new staleness threshold.
+     * @param period The new fallback staleness threshold. Must be 1.5x of stalePeriod of the same token.
      * @dev Must lie within [UBKOracleConstants.ORACLE_MIN_STALE_PERIOD, UBKOracleConstants.ORACLE_MAX_STALE_PERIOD].
      */
-    function setStalePeriod(uint256 period) external onlyOwner {
+    function setStalePeriod(address token, uint256 period) external onlyOwner {
         if (
             period < UBKOracleConstants.ORACLE_MIN_STALE_PERIOD ||
             period > UBKOracleConstants.ORACLE_MAX_STALE_PERIOD
         ) revert InvalidStalePeriod(period);
-        stalePeriod = period;
-        emit StalePeriodUpdated(period);
+        stalePeriod[token] = period;
+        fallbackStalePeriod[token] =
+            UBKOracleConstants.ORACLE_DEFAULT_STALE_FALLBACK_MULTIPLIER *
+            period; //Minimum fallback period should be 2x stalePeriod[token].
+        emit StalePeriodUpdated(token, stalePeriod[token]);
+        emit FallbackStalePeriodUpdated(token, fallbackStalePeriod[token]);
     }
 
     /**
@@ -142,10 +145,17 @@ contract UBKOracle is IUBKOracle, Ownable {
      * @param period Maximum allowed seconds for fallback validity.
      * @dev Must be ≥ stalePeriod to remain meaningful.
      */
-    function setFallbackStalePeriod(uint256 period) external onlyOwner {
-        if (period < stalePeriod) revert InvalidStalePeriod(period);
-        fallbackStalePeriod = period;
-        emit FallbackStalePeriodUpdated(period);
+    function setFallbackStalePeriod(
+        address token,
+        uint256 period
+    ) external onlyOwner {
+        uint256 stalePeriodToken = stalePeriod[token]; // Default stale period of token.
+        uint256 maxFallbackPeriod = stalePeriodToken *
+            UBKOracleConstants.ORACLE_MAX_STALE_FALLBACK_MULTIPLIER; // The absolute maximum fallback stale period allowed. (3x)
+        if (period < stalePeriodToken || period > maxFallbackPeriod)
+            revert InvalidStalePeriod(period);
+        fallbackStalePeriod[token] = period;
+        emit FallbackStalePeriodUpdated(token, period);
     }
 
     /**
@@ -188,12 +198,16 @@ contract UBKOracle is IUBKOracle, Ownable {
         ) revert InvalidManualPrice(token, price);
 
         LastValidPrice memory lv = lastValidPrice[token];
-        if (lv.price > 0 && block.timestamp - lv.timestamp <= stalePeriod) {
+        if (
+            lv.price > 0 && block.timestamp - lv.timestamp <= stalePeriod[token]
+        ) {
             uint256 lowerBound = (lv.price *
-                (UBKOracleConstants.WAD - UBKOracleConstants.ORACLE_MANUAL_PRICE_MAX_DELTA_WAD)) /
+                (UBKOracleConstants.WAD -
+                    UBKOracleConstants.ORACLE_MANUAL_PRICE_MAX_DELTA_WAD)) /
                 UBKOracleConstants.WAD;
             uint256 upperBound = (lv.price *
-                (UBKOracleConstants.WAD + UBKOracleConstants.ORACLE_MANUAL_PRICE_MAX_DELTA_WAD)) /
+                (UBKOracleConstants.WAD +
+                    UBKOracleConstants.ORACLE_MANUAL_PRICE_MAX_DELTA_WAD)) /
                 UBKOracleConstants.WAD;
             if (price < lowerBound || price > upperBound)
                 revert InvalidManualPrice(token, price);
@@ -245,7 +259,6 @@ contract UBKOracle is IUBKOracle, Ownable {
         } catch {
             revert InvalidFeedContract(feed);
         }
-
         chainlinkFeeds[token] = feed;
         isManual[token] = false;
         _addSupportedToken(token);
@@ -299,6 +312,36 @@ contract UBKOracle is IUBKOracle, Ownable {
         return _fetchAndUpdatePrice(token);
     }
 
+    /**
+     * @notice Batch price fetch & update for multiple tokens.
+     * @param tokens Array of asset token addresses.
+     * @return prices Array of fresh prices in 1e18 precision.
+     *
+     * @dev
+     *  - Runs whenNotPaused modifier.
+     *  - Reverts if any token is zero address.
+     *  - Each iteration calls the same internal `_fetchAndUpdatePrice`.
+     *  - Gas-efficient: msg.sender checked once, calldata parsed once.
+     */
+    function fetchAndUpdatePrice(
+        address[] calldata tokens
+    ) external whenNotPaused returns (uint256[] memory prices) {
+        uint256 len = tokens.length;
+        prices = new uint256[](len);
+
+        for (uint256 i = 0; i < len; ++i) {
+            address token = tokens[i];
+            if (token == address(0)) {
+                revert ZeroAddress(
+                    "UBKOracle::fetchAndUpdatePriceBatch",
+                    "token"
+                );
+            }
+
+            prices[i] = _fetchAndUpdatePrice(token);
+        }
+    }
+
     /**
      * @notice Returns age of last cached price in seconds.
      * @param token Token address.
@@ -310,15 +353,12 @@ contract UBKOracle is IUBKOracle, Ownable {
         return block.timestamp - lv.timestamp;
     }
 
-    /**
+    /** Public wrapper for _isPriceFresh
      * @notice Checks if cached price is within freshness threshold.
-     * @param token Token address.
      * @return isFresh True if price updated ≤ stalePeriod ago.
      */
     function isPriceFresh(address token) external view returns (bool isFresh) {
-        LastValidPrice memory lv = lastValidPrice[token];
-        return (lv.timestamp != 0 &&
-            block.timestamp - lv.timestamp <= stalePeriod);
+        return _isPriceFresh(token);
     }
 
     /**
@@ -352,7 +392,8 @@ contract UBKOracle is IUBKOracle, Ownable {
     ) external view returns (uint256 usdValue) {
         if (amount == 0) return 0;
         uint8 decimals = IERC20Metadata(token).decimals();
-        uint256 normalized = (amount * UBKOracleConstants.WAD) / (10 ** decimals);
+        uint256 normalized = (amount * UBKOracleConstants.WAD) /
+            (10 ** decimals);
         uint256 price = _getPrice(token); // 18 decimals
         usdValue = (normalized * price) / UBKOracleConstants.WAD;
     }
@@ -385,13 +426,26 @@ contract UBKOracle is IUBKOracle, Ownable {
      * @return price Cached price in 1e18 precision.
      */
     function _getPrice(address token) internal view returns (uint256) {
-        if (token == address(0)) revert ZeroAddress("UBKOracle::getPrice", "token");
+        if (token == address(0))
+            revert ZeroAddress("UBKOracle::getPrice", "token");
         LastValidPrice memory lv = lastValidPrice[token];
         if (lv.price == 0) revert NoFallbackPrice(token);
-        if (!this.isPriceFresh(token))
+        if (!_isPriceFresh(token))
             revert StalePrice(token, lv.timestamp, block.timestamp);
         return lv.price;
     }
+
+    /**
+     * @notice Checks if cached price is within freshness threshold.
+     * @param token Token address.
+     * @return isFresh True if price updated ≤ stalePeriod ago.
+     */
+    function _isPriceFresh(address token) internal view returns (bool isFresh) {
+        LastValidPrice memory lv = lastValidPrice[token];
+        return (lv.timestamp != 0 &&
+            block.timestamp - lv.timestamp <= stalePeriod[token]);
+    }
+
     /**
      * @notice Resolves the fair price of an ERC4626 vault share.
      * @param vault ERC4626 vault token address.
@@ -428,13 +482,13 @@ contract UBKOracle is IUBKOracle, Ownable {
         if (rate > maxRate || rate < minRate)
             revert SuspiciousVaultRate(vault, rate);
 
-        uint256 underlyingPrice = resolvePrice(underlying);
+        uint256 underlyingPrice = _resolvePrice(underlying);
         return (underlyingPrice * rate) / UBKOracleConstants.WAD;
     }
 
     /**
      * @notice Fetches and validates the latest Chainlink feed price.
-     * @param feed The address of the Chainlink AggregatorV3 feed.
+     * @param token The address of the token whose feed needs to be read.
      * @return price The normalized price (1e18 precision).
      * @return valid Boolean indicating whether the feed result is valid.
      *
@@ -448,8 +502,9 @@ contract UBKOracle is IUBKOracle, Ownable {
      *  If any condition fails or the feed call reverts, returns `(0, false)`.
      */
     function _getChainlinkPrice(
-        address feed
+        address token
     ) internal view returns (uint256 price, bool valid) {
+        address feed = chainlinkFeeds[token];
         try AggregatorV3Interface(feed).latestRoundData() returns (
             uint80,
             int256 answer,
@@ -460,7 +515,7 @@ contract UBKOracle is IUBKOracle, Ownable {
             if (
                 answer <= 0 ||
                 updatedAt == 0 ||
-                block.timestamp - updatedAt > stalePeriod
+                block.timestamp - updatedAt > stalePeriod[token]
             ) return (0, false);
 
             uint8 feedDecimals = AggregatorV3Interface(feed).decimals();
@@ -494,7 +549,7 @@ contract UBKOracle is IUBKOracle, Ownable {
      * @return price Resolved fair price in 1e18 precision.
      * @dev May trigger state updates if underlying vaults are resolved.
      */
-    function resolvePrice(address token) public returns (uint256 price) {
+    function _resolvePrice(address token) internal returns (uint256 price) {
         if (isManual[token]) return manualPrices[token];
 
         address underlying = erc4626Underlying[token];
@@ -503,12 +558,12 @@ contract UBKOracle is IUBKOracle, Ownable {
         address feed = chainlinkFeeds[token];
         if (feed == address(0)) revert NoPriceFeed(token);
 
-        (uint256 clPrice, bool valid) = _getChainlinkPrice(feed);
+        (uint256 clPrice, bool valid) = _getChainlinkPrice(token);
         if (valid) return clPrice;
 
         LastValidPrice memory lv = lastValidPrice[token];
         if (lv.price == 0) revert NoFallbackPrice(token);
-        if (block.timestamp - lv.timestamp > fallbackStalePeriod)
+        if (block.timestamp - lv.timestamp > fallbackStalePeriod[token])
             revert StaleFallback(token);
 
         emit OracleFallbackUsed(
@@ -529,7 +584,7 @@ contract UBKOracle is IUBKOracle, Ownable {
     function _fetchAndUpdatePrice(
         address token
     ) internal returns (uint256 price) {
-        price = resolvePrice(token);
+        price = _resolvePrice(token);
         if (
             price < UBKOracleConstants.ORACLE_MIN_ABSOLUTE_PRICE_WAD ||
             price > UBKOracleConstants.ORACLE_MAX_ABSOLUTE_PRICE_WAD

package/interfaces/IUBKOracle.sol

@@ -2,6 +2,10 @@
 pragma solidity ^0.8.20;
 
 interface IUBKOracle {
+    // -----------------------------------------------------------------------
+    // ENUMS & STRUCTS
+    // -----------------------------------------------------------------------
+
     /// @notice Operational state of the oracle.
     enum OracleMode {
         NORMAL,
@@ -14,31 +18,40 @@ interface IUBKOracle {
         uint256 timestamp;
     }
 
-    /// @notice Custom vault rate bounds (min/max multiplier per vault).
+    /// @notice Vault-specific allowable min/max exchange rates.
     struct VaultRateBounds {
         uint256 minRate;
         uint256 maxRate;
     }
 
-    /// @notice Oracle specific events for subgraph indexing.
+    // -----------------------------------------------------------------------
+    // EVENTS (for Subgraph indexing)
+    // -----------------------------------------------------------------------
+
     event ChainlinkFeedSet(address indexed token, address indexed feed);
     event ERC4626Registered(address indexed vault, address indexed underlying);
     event TokenSupportAdded(address indexed token);
+
     event ManualPriceSet(address indexed token, uint256 price);
     event ManualModeEnabled(address indexed token, bool enabled);
-    event StalePeriodUpdated(uint256 newPeriod);
+
+    event StalePeriodUpdated(address indexed token, uint256 newPeriod);
+    event FallbackStalePeriodUpdated(address indexed token, uint256 newPeriod);
+
     event OracleModeChanged(OracleMode oldMode, OracleMode newMode);
-    event FallbackStalePeriodUpdated(uint256 newPeriod);
+
     event VaultRateBoundsSet(
         address indexed vault,
         uint256 minRate,
         uint256 maxRate
     );
+
     event LastValidPriceUpdated(
         address indexed token,
         uint256 price,
         uint256 timestamp
     );
+
     event OracleFallbackUsed(
         address indexed token,
         uint256 lastValid,
@@ -46,17 +59,90 @@ interface IUBKOracle {
         string reason
     );
 
-    // View Functions
+    // -----------------------------------------------------------------------
+    // VIEW PRICING API (Consumer-facing)
+    // -----------------------------------------------------------------------
+
+    /**
+     * @notice Returns the cached fair price for a token (1e18 precision).
+     * @dev Reverts if the price is stale or no valid price exists.
+     */
     function getPrice(address token) external view returns (uint256);
+
+    /**
+     * @notice Converts a token amount (native decimals) into USD value (1e18).
+     */
     function toUSD(
         address token,
         uint256 amount
     ) external view returns (uint256 usdValue);
+
+    /**
+     * @notice Converts a USD amount (1e18) into token units (native decimals).
+     */
     function fromUSD(
         address token,
         uint256 usdAmount
     ) external view returns (uint256 tokenAmount);
 
-    // Mutators
+    // -----------------------------------------------------------------------
+    // KEEPER / MUTATOR FUNCTIONS
+    // -----------------------------------------------------------------------
+
+    /**
+     * @notice Fetches and resolves the token price, then persists it as lastValidPrice.
+     * @dev Keeper entrypoint. May revert if price resolution fails.
+     */
     function fetchAndUpdatePrice(address token) external returns (uint256);
+    function fetchAndUpdatePrice(
+        address[] calldata tokens
+    ) external returns (uint256[] memory);
+    // -----------------------------------------------------------------------
+    // ADMIN / GOVERNANCE CONFIGURATION
+    // -----------------------------------------------------------------------
+
+    /**
+     * @notice Sets the operating mode of the oracle (NORMAL or PAUSED).
+     * @dev PAUSED mode disables fetchAndUpdatePrice().
+     */
+    function setOracleMode(OracleMode newMode) external;
+
+    /**
+     * @notice Sets the maximum allowed staleness for Chainlink feed data.
+     */
+    function setStalePeriod(address token, uint256 period) external;
+
+    /**
+     * @notice Sets the fallback staleness threshold for relying on lastValidPrice.
+     */
+    function setFallbackStalePeriod(address token, uint256 period) external;
+
+    /**
+     * @notice Defines allowable min/max ERC4626 exchange rate bounds for a vault.
+     */
+    function setVaultRateBounds(
+        address vault,
+        uint256 minRate,
+        uint256 maxRate
+    ) external;
+
+    /**
+     * @notice Manually sets a token's price (1e18), constrained by ±10% of lastValidPrice.
+     */
+    function setManualPrice(address token, uint256 price) external;
+
+    /**
+     * @notice Disables manual pricing mode for a token.
+     */
+    function disableManualPrice(address token) external;
+
+    /**
+     * @notice Registers or updates a Chainlink feed for a token.
+     */
+    function setChainlinkFeed(address token, address feed) external;
+
+    /**
+     * @notice Registers an ERC4626 vault and its underlying token for valuation.
+     */
+    function setERC4626Vault(address vault, address underlying) external;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ubk-labs/ubk-oracle",
-  "version": "0.1.6",
+  "version": "0.1.8",
   "description": "Oracle supporting ERC-20 and ERC-4626 assets for use in decentralized financial applications.",
   "scripts": {
     "build": "npx hardhat compile",