@ubk-labs/ubk-oracle 0.1.8 → 0.2.0

package/contracts/constants/UBKOracleConstants.sol

@@ -23,10 +23,13 @@ library UBKOracleConstants {
     uint256 public constant ORACLE_MIN_VAULT_RATE_WAD = 0.2e18; // 0.2x (20%)
     uint256 public constant ORACLE_MAX_VAULT_RATE_WAD = 3e18; // 3x (300%)
 
+    uint256 public constant ORACLE_MAX_VAULT_ASSETS_PER_SHARE = 1e36;
+
     // -----------------------------------------------------------------------
     // Oracle Staleness Periods
     // -----------------------------------------------------------------------
     uint256 public constant ORACLE_MIN_STALE_PERIOD = 1 hours;
+    uint256 public constant ORACLE_DEFAULT_STALE_PERIOD = 24 hours;
     uint256 public constant ORACLE_MAX_STALE_PERIOD = 48 hours;
 
     uint256 public constant ORACLE_DEFAULT_STALE_FALLBACK_MULTIPLIER = 2; //2x stale

package/contracts/core/UBKOracle.sol

@@ -7,17 +7,18 @@ import "@openzeppelin/contracts/interfaces/IERC4626.sol";
 import "@openzeppelin/contracts/token/ERC20/extensions/IERC20Metadata.sol";
 
 import "@chainlink/contracts/src/v0.8/interfaces/AggregatorV3Interface.sol";
+import "@ubk-labs/ubk-commons/contracts/abstract/UBKDecimalsBounded.sol";
 
 import "../../interfaces/IUBKOracle.sol";
 import "../errors/UBKOracleErrors.sol";
 import "../constants/UBKOracleConstants.sol";
 
 /**
- * @title Oracle
- * @notice This contract is an implementation of the IUBKOracle interface.
+ * @title UBKOracle
+ * @notice This contract is the canonical implementation of the IUBKOracle interface.
  *
  * @dev
- *  The oracle computes normalized 1e18 prices for all supported assets,
+ *  The contract computes normalized 1e18 (WAD) prices for all supported assets,
  *  combining manual overrides, ERC4626 vault conversions, and Chainlink feeds.
  *
  *  === PRICE RESOLUTION ORDER ===
@@ -25,6 +26,12 @@ import "../constants/UBKOracleConstants.sol";
  *  2. ERC4626 vault-derived (convertToAssets * underlying price)
  *  3️. Chainlink feed (normalized to 1e18)
  *
+ *  === DECIMAL INVARIANTS ===
+ *  - Only explicitly registered tokens may be priced or converted.
+ *  - Token decimals are validated once at registration and MUST lie within [6, 18].
+ *  - Validated decimals are cached immutably and never queried from token contracts at runtime.
+ *  - All internal price and value computations assume and rely on these enforced bounds.
+ *  - ERC-4626 vaults are only supported when vault.decimals() == underlying.decimals(), preventing cross-decimal normalization errors in vault pricing.
  *  === SAFETY FEATURES ===
  *  - Recursion guard (nested ERC4626 depth ≤ 5)
  *  - Chainlink stale-period enforcement
@@ -39,7 +46,8 @@ import "../constants/UBKOracleConstants.sol";
  *  - UI / Subgraphs can use `isPriceFresh()` and `getPriceAge()` for safety checks.
  *
  */
-contract UBKOracle is IUBKOracle, Ownable {
+
+contract UBKOracle is IUBKOracle, UBKDecimalsBounded, Ownable {
     // -----------------------------------------------------------------------
     // Storage
     // -----------------------------------------------------------------------
@@ -79,6 +87,9 @@ contract UBKOracle is IUBKOracle, Ownable {
     /// @notice Mapping to track supported tokens.
     mapping(address => bool) public isSupported;
 
+    /// @notice Cache that tracks decimals for supported tokens.
+    mapping(address => uint8) internal tokenDecimals;
+
     // -----------------------------------------------------------------------
     // Constructor & Modifiers
     // -----------------------------------------------------------------------
@@ -87,10 +98,7 @@ contract UBKOracle is IUBKOracle, Ownable {
      * @notice Deploys the Oracle contract.
      * @param _owner The address to assign as the owner (governance or deployer).
      */
-    constructor(address _owner) Ownable(_owner) {
-        if (_owner == address(0))
-            revert ZeroAddress("UBKOracle::constructor", "owner");
-    }
+    constructor(address _owner) Ownable(_owner) {}
 
     /// @notice Ensures oracle is not paused.
     modifier whenNotPaused() {
@@ -108,6 +116,12 @@ contract UBKOracle is IUBKOracle, Ownable {
         _recursionDepth--;
     }
 
+    /// @notice Does not allow execution of the decorated function if token is unsupported.
+    modifier supportedTokenOnly(address token) {
+        if (!isSupported[token]) revert TokenNotSupported(token);
+        _;
+    }
+
     // -----------------------------------------------------------------------
     // Admin / Configuration
     // -----------------------------------------------------------------------
@@ -123,21 +137,11 @@ contract UBKOracle is IUBKOracle, Ownable {
     }
 
     /**
-     * @notice Sets the maximum time (in seconds) a Chainlink feed value is valid.
+     * @notice External facing admin function that sets the maximum time (in seconds) a Chainlink feed value is valid.
      * @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(address token, uint256 period) external onlyOwner {
-        if (
-            period < UBKOracleConstants.ORACLE_MIN_STALE_PERIOD ||
-            period > UBKOracleConstants.ORACLE_MAX_STALE_PERIOD
-        ) revert InvalidStalePeriod(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]);
+        _setStalePeriod(token, period);
     }
 
     /**
@@ -172,8 +176,11 @@ contract UBKOracle is IUBKOracle, Ownable {
     ) external onlyOwner {
         if (vault == address(0))
             revert ZeroAddress("UBKOracle::setVaultRateBounds", "vault");
-        if (minRate == 0 || maxRate <= minRate || maxRate > 100e18)
-            revert InvalidVaultBounds(vault, minRate, maxRate);
+        if (
+            minRate == 0 ||
+            maxRate <= minRate ||
+            maxRate > UBKOracleConstants.ORACLE_MAX_VAULT_RATE_WAD
+        ) revert InvalidVaultBounds(vault, minRate, maxRate);
 
         vaultRateBounds[vault] = VaultRateBounds(minRate, maxRate);
         emit VaultRateBoundsSet(vault, minRate, maxRate);
@@ -192,6 +199,10 @@ contract UBKOracle is IUBKOracle, Ownable {
     ) external onlyOwner whenNotPaused {
         if (token == address(0))
             revert ZeroAddress("UBKOracle::setManualPrice", "token");
+        if (!isSupported[token]) {
+            _addSupportedToken(token);
+        }
+
         if (
             price < UBKOracleConstants.ORACLE_MIN_ABSOLUTE_PRICE_WAD ||
             price > UBKOracleConstants.ORACLE_MAX_ABSOLUTE_PRICE_WAD
@@ -226,9 +237,9 @@ contract UBKOracle is IUBKOracle, Ownable {
      * @notice Disables manual pricing for a token.
      * @param token The token address.
      */
-    function disableManualPrice(address token) external onlyOwner {
-        if (token == address(0))
-            revert ZeroAddress("UBKOracle::disableManualPrice", "token");
+    function disableManualPrice(
+        address token
+    ) external onlyOwner supportedTokenOnly(token) {
         isManual[token] = false;
         emit ManualModeEnabled(token, false);
     }
@@ -240,9 +251,7 @@ contract UBKOracle is IUBKOracle, Ownable {
      * @dev Ensures decimals ≤ 18 and feed returns a nonzero updatedAt value.
      */
     function setChainlinkFeed(address token, address feed) external onlyOwner {
-        if (token == address(0) || feed == address(0))
-            revert ZeroAddress("UBKOracle::setChainlinkFeed", "input");
-        if (feed.code.length == 0) revert InvalidFeedContract(feed);
+        _validateChainlinkFeed(token, feed);
 
         AggregatorV3Interface agg = AggregatorV3Interface(feed);
         uint8 decimals = agg.decimals();
@@ -269,18 +278,13 @@ contract UBKOracle is IUBKOracle, Ownable {
      * @notice Registers an ERC4626 vault and its underlying asset.
      * @param vault ERC4626 vault token.
      * @param underlying Reference underlying asset used for pricing.
-     * @dev Does not enforce .asset() == underlying for flexibility
-     *      (e.g., sUSDe → USDC pegging for depeg protection).
+     * @dev Stricly enforces == underlying for flexibility
      */
     function setERC4626Vault(
         address vault,
         address underlying
     ) external onlyOwner {
-        if (vault == address(0) || underlying == address(0))
-            revert ZeroAddress("UBKOracle::setERC4626Vault", "input");
-        try IERC4626(vault).asset() returns (address) {} catch {
-            revert InvalidERC4626Vault(vault);
-        }
+        _validateERC4626Vault(vault, underlying);
         erc4626Underlying[vault] = underlying;
         _addSupportedToken(vault);
         emit ERC4626Registered(vault, underlying);
@@ -307,8 +311,6 @@ contract UBKOracle is IUBKOracle, Ownable {
     function fetchAndUpdatePrice(
         address token
     ) external whenNotPaused returns (uint256) {
-        if (token == address(0))
-            revert ZeroAddress("UBKOracle::fetchAndUpdatePrice", "token");
         return _fetchAndUpdatePrice(token);
     }
 
@@ -381,17 +383,28 @@ contract UBKOracle is IUBKOracle, Ownable {
     // -----------------------------------------------------------------------
 
     /**
-     * @notice Converts a token amount into USD (18 decimals)
-     * @param token Token address
-     * @param amount Raw token amount (native decimals)
-     * @return usdValue USD value (18 decimals)
+     * @notice Converts a supported token amount into USD (18 decimals).
+     * @dev
+     *  Requirements:
+     *  - `token` MUST be registered as supported by the oracle.
+     *  - Token decimals are cached at registration and guaranteed to be within [6,18].
+     *  - Reverts if the token is not supported or if the cached price is stale or unavailable.
+     *
+     *  Behavior:
+     *  - Returns 0 if `amount == 0` without reading oracle price.
+     *  - Uses cached decimals and cached price for deterministic gas usage.
+     *
+     * @param token Supported token address.
+     * @param amount Raw token amount in native decimals.
+     * @return usdValue USD value with 18 decimals of precision.
      */
+
     function toUSD(
         address token,
         uint256 amount
     ) external view returns (uint256 usdValue) {
         if (amount == 0) return 0;
-        uint8 decimals = IERC20Metadata(token).decimals();
+        uint8 decimals = tokenDecimals[token];
         uint256 normalized = (amount * UBKOracleConstants.WAD) /
             (10 ** decimals);
         uint256 price = _getPrice(token); // 18 decimals
@@ -399,17 +412,28 @@ contract UBKOracle is IUBKOracle, Ownable {
     }
 
     /**
-     * @notice Converts a USD amount (18 decimals) into token units
-     * @param token Token address
-     * @param usdAmount USD value (18 decimals)
-     * @return tokenAmount Equivalent in token units
+     * @notice Converts a USD amount (18 decimals) into units of a supported token.
+     * @dev
+     *  Requirements:
+     *  - `token` MUST be registered as supported by the oracle.
+     *  - Token decimals are cached at registration and guaranteed to be within [6,18].
+     *  - Reverts if the token is not supported or if the cached price is stale or unavailable.
+     *
+     *  Behavior:
+     *  - Returns 0 if `usdAmount == 0` without reading oracle price.
+     *  - Uses cached decimals and cached price for deterministic gas usage.
+     *
+     * @param token Supported token address.
+     * @param usdAmount USD value with 18 decimals of precision.
+     * @return tokenAmount Equivalent amount in token native decimals.
      */
+
     function fromUSD(
         address token,
         uint256 usdAmount
     ) external view returns (uint256 tokenAmount) {
         if (usdAmount == 0) return 0;
-        uint8 decimals = IERC20Metadata(token).decimals();
+        uint8 decimals = tokenDecimals[token];
         uint256 price = _getPrice(token); // 18 decimals
         uint256 normalized = (usdAmount * UBKOracleConstants.WAD) / price;
         tokenAmount = (normalized * (10 ** decimals)) / UBKOracleConstants.WAD;
@@ -420,14 +444,35 @@ contract UBKOracle is IUBKOracle, Ownable {
     // -----------------------------------------------------------------------
 
     /**
-     * @notice Returns the cached price for a token (1e18 precision).
-     * @dev Reverts if no valid price or if staleness > stalePeriod.
+     * @notice Returns the cached USD price for a token.
+     *
+     * @dev
+     *  This function is the canonical read path for all pricing operations
+     *  (including `toUSD` and `fromUSD`). It intentionally performs **no explicit
+     *  supported-token check** in order to minimize gas usage on hot, view-only paths.
+     *
+     *  Reverts in the following cases:
+     *
+     *   1. `NoFallbackPrice(token)`
+     *      - The token has **never had a successfully resolved and cached price**, OR
+     *      - The token is **unsupported** and therefore has no initialized pricing state.
+     *
+     *   2. `StalePrice(token, lastUpdated, now)`
+     *      - A cached price exists, but its age exceeds `stalePeriod[token]`.
+     *
+     *  Supported tokens are guaranteed to have:
+     *   - non-zero addresses,
+     *   - validated and cached decimals within [6, 18],
+     *   - pricing state initialized only via explicit configuration paths
+     *     (e.g. Chainlink feeds, ERC4626 vaults, or manual pricing).
+     *
+     *  As a result, callers of `toUSD` and `fromUSD` can safely rely on this function
+     *  for correctness while avoiding redundant SLOADs or branching.
+     *
      * @param token Asset token address.
-     * @return price Cached price in 1e18 precision.
+     * @return price Cached token price in 1e18 precision.
      */
-    function _getPrice(address token) internal view returns (uint256) {
-        if (token == address(0))
-            revert ZeroAddress("UBKOracle::getPrice", "token");
+    function _getPrice(address token) internal view returns (uint256 price) {
         LastValidPrice memory lv = lastValidPrice[token];
         if (lv.price == 0) revert NoFallbackPrice(token);
         if (!_isPriceFresh(token))
@@ -454,17 +499,20 @@ contract UBKOracle is IUBKOracle, Ownable {
      * @dev Derives price via convertToAssets() * underlying price.
      *      Ensures vault rate lies within acceptable bounds.
      */
-    function _getVaultPrice(
+    function _resolveVaultPrice(
         address vault,
         address underlying
     ) internal checkRecursion returns (uint256 price) {
-        uint8 shareDecimals = IERC20Metadata(vault).decimals();
-        uint8 underlyingDecimals = IERC20Metadata(underlying).decimals();
+        uint8 shareDecimals = tokenDecimals[vault];
+        uint8 underlyingDecimals = tokenDecimals[underlying];
 
         uint256 oneShare = 10 ** shareDecimals;
         uint256 assetsPerShare = IERC4626(vault).convertToAssets(oneShare);
-        if (assetsPerShare == 0 || assetsPerShare > 1e36)
-            revert InvalidVaultExchangeRate(vault, assetsPerShare);
+        if (
+            assetsPerShare == 0 ||
+            assetsPerShare >
+            UBKOracleConstants.ORACLE_MAX_VAULT_ASSETS_PER_SHARE
+        ) revert InvalidVaultExchangeRate(vault, assetsPerShare);
 
         uint256 scaledAssets = (assetsPerShare * UBKOracleConstants.WAD) /
             (10 ** underlyingDecimals);
@@ -549,11 +597,14 @@ 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) internal returns (uint256 price) {
+    function _resolvePrice(
+        address token
+    ) internal supportedTokenOnly(token) returns (uint256 price) {
         if (isManual[token]) return manualPrices[token];
 
         address underlying = erc4626Underlying[token];
-        if (underlying != address(0)) return _getVaultPrice(token, underlying);
+        if (underlying != address(0))
+            return _resolveVaultPrice(token, underlying);
 
         address feed = chainlinkFeeds[token];
         if (feed == address(0)) revert NoPriceFeed(token);
@@ -588,7 +639,7 @@ contract UBKOracle is IUBKOracle, Ownable {
         if (
             price < UBKOracleConstants.ORACLE_MIN_ABSOLUTE_PRICE_WAD ||
             price > UBKOracleConstants.ORACLE_MAX_ABSOLUTE_PRICE_WAD
-        ) revert InvalidOraclePrice(token, address(0));
+        ) revert InvalidOraclePrice(token, price);
 
         lastValidPrice[token] = LastValidPrice(price, block.timestamp);
         emit LastValidPriceUpdated(token, price, block.timestamp);
@@ -606,10 +657,85 @@ contract UBKOracle is IUBKOracle, Ownable {
      * Emits a {TokenSupportAdded} event upon successful addition.
      */
     function _addSupportedToken(address token) internal {
+        if (token == address(0)) {
+            revert ZeroAddress("UBKOracle::_addSupportedToken", "token");
+        }
+
         if (!isSupported[token]) {
             supportedTokens.push(token);
             isSupported[token] = true;
+            tokenDecimals[token] = _validateTokenDecimals(token);
+            _setStalePeriod(
+                token,
+                UBKOracleConstants.ORACLE_DEFAULT_STALE_PERIOD
+            );
             emit TokenSupportAdded(token);
         }
     }
+
+    /**
+     * @notice Validates assets and their associated Chainlink feeds before mutating system state.
+     * @param token Asset token address.
+     * @param feed Chainlink AggregatorV3 feed address.
+     * @dev Ensures decimals ≤ 18 and feed returns a nonzero updatedAt value.
+     */
+    function _validateChainlinkFeed(address token, address feed) internal view {
+        if (token == address(0))
+            revert ZeroAddress("UBKOracle::setChainlinkFeed", "token");
+        if (feed == address(0))
+            revert ZeroAddress("UBKOracle::setChainlinkFeed", "feed");
+        if (feed.code.length == 0) revert InvalidFeedContract(feed);
+        _validateTokenDecimals(token);
+    }
+
+    /**
+     * @notice Validates input parameters before setting an ERc 4626 vault.
+     * @dev Ensures decimals for vault and underlying assets are equal, and bounded by global invariants.
+     * @param vault ERC-4626 asset.
+     * @param underlying ERC-20 asset.
+     */
+    function _validateERC4626Vault(
+        address vault,
+        address underlying
+    ) internal view {
+        if (vault == address(0))
+            revert ZeroAddress("UBKOracle::_validateERC4626Vault", "vault");
+        if (underlying == address(0)) {
+            revert ZeroAddress(
+                "UBKOracle::_validateERC4626Vault",
+                "underlying"
+            );
+        }
+        try IERC4626(vault).asset() returns (address) {} catch {
+            revert InvalidERC4626Vault(vault);
+        }
+        uint8 vaultDecimals = _validateTokenDecimals(vault); // Must be between [6,18]
+        uint8 underlyingDecimals = _validateTokenDecimals(underlying); // Must be between [6,18]
+
+        if (vaultDecimals != underlyingDecimals) {
+            revert ERC4626DecimalsMismatch(
+                "UBKOracle::_validateERC4626Vault",
+                vault,
+                underlying
+            );
+        }
+    }
+
+    /**
+     * @notice Sets the maximum time (in seconds) a Chainlink feed value is valid.
+     * @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(address token, uint256 period) internal {
+        if (
+            period < UBKOracleConstants.ORACLE_MIN_STALE_PERIOD ||
+            period > UBKOracleConstants.ORACLE_MAX_STALE_PERIOD
+        ) revert InvalidStalePeriod(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]);
+    }
 }

package/contracts/errors/UBKOracleErrors.sol

@@ -4,18 +4,24 @@ pragma solidity ^0.8.20;
 import "@ubk-labs/ubk-commons/contracts/errors/UBKErrors.sol";
 
 // ───────────── Errors ─────────────
+error ERC4626DecimalsMismatch(
+    string functionName,
+    address vault,
+    address underlying
+);
+error InvalidERC4626Vault(address vault);
+error InvalidFeedContract(address feed);
+error InvalidFeedDecimals(address feed, uint8 decimals);
 error InvalidManualPrice(address token, uint256 price);
+error InvalidOraclePrice(address token, uint256 price);
 error InvalidStalePeriod(uint256 period);
 error InvalidVaultBounds(address vault, uint256 minRate, uint256 maxRate);
-error InvalidFeedContract(address feed);
-error InvalidFeedDecimals(address feed, uint8 decimals);
-error InvalidERC4626Vault(address vault);
 error InvalidVaultExchangeRate(address vault, uint256 rate);
-error InvalidOraclePrice(address token, address feed);
+error NoFallbackPrice(address token);
 error NoPriceFeed(address token);
-error StalePrice(address token, uint256 updatedAt, uint256 currentTime);
+error OraclePaused(address oracle, uint256 timestamp);
+error RecursiveResolution(address token);
 error StaleFallback(address token);
-error NoFallbackPrice(address token);
+error StalePrice(address token, uint256 updatedAt, uint256 currentTime);
 error SuspiciousVaultRate(address vault, uint256 rate);
-error RecursiveResolution(address token);
-error OraclePaused(address oracle, uint256 timestamp);
+error TokenNotSupported(address token);

package/deployments/mainnet.json

@@ -0,0 +1,5 @@
+{
+    "0.1.7": "0x37814FAA5bd659888380CBa070F098Cc0999A8cA",
+    "0.1.8": "0x5d4747d514B529005F4014f26068E1f4Ec47E06B",
+    "0.1.9": "0x04B21e27e24Ab71472690C9a09BC7A826d658668"
+}

package/package.json

@@ -1,13 +1,14 @@
 {
   "name": "@ubk-labs/ubk-oracle",
-  "version": "0.1.8",
+  "version": "0.2.0",
   "description": "Oracle supporting ERC-20 and ERC-4626 assets for use in decentralized financial applications.",
   "scripts": {
     "build": "npx hardhat compile",
     "test": "npx hardhat test",
     "coverage": "hardhat coverage",
     "lint": "prettier --check .",
-    "format": "prettier --write ."
+    "format": "prettier --write .",
+    "deploy:mainnet": "npx hardhat run scripts/deploy.js --network mainnet"
   },
   "keywords": [
     "DeFi",
@@ -20,6 +21,7 @@
   "files": [
     "contracts",
     "interfaces",
+    "deployments",
     "README.md",
     "LICENSE",
     "package.json"
@@ -37,6 +39,6 @@
   },
   "dependencies": {
     "@chainlink/contracts": "^0.6.1",
-    "@ubk-labs/ubk-commons": "^0.1.5"
+    "@ubk-labs/ubk-commons": "^0.1.7"
   }
 }