Scalable usdc spot strategy

aalavandhan · aalavandhan · commit f96c1cbc4200 · 2024-10-27T21:36:07.000-04:00
diff --git a/spot-vaults/contracts/_utils/AlphaVaultHelpers.sol b/spot-vaults/contracts/_utils/AlphaVaultHelpers.sol
@@ -44,7 +44,6 @@ library AlphaVaultHelpers {
         if (percToRemove <= 0) {
             return;
         }
-
         int24 _fullLower = vault.fullLower();
         int24 _fullUpper = vault.fullUpper();
         int24 _baseLower = vault.baseLower();
@@ -61,8 +60,12 @@ library AlphaVaultHelpers {
         );
         // docs: https://learn.charm.fi/charm/technical-references/core/alphaprovault#emergencyburn
         // We remove the calculated percentage of base and full range liquidity.
-        vault.emergencyBurn(_fullLower, _fullUpper, fullLiquidityToBurn);
-        vault.emergencyBurn(_baseLower, _baseUpper, baseLiquidityToBurn);
+        if (fullLiquidityToBurn > 0) {
+            vault.emergencyBurn(_fullLower, _fullUpper, fullLiquidityToBurn);
+        }
+        if (baseLiquidityToBurn > 0) {
+            vault.emergencyBurn(_baseLower, _baseUpper, baseLiquidityToBurn);
+        }
     }
 
     /// @dev A low-level method, which interacts directly with the vault and executes
diff --git a/spot-vaults/contracts/charm/UsdcSpotManager.sol b/spot-vaults/contracts/charm/UsdcSpotManager.sol
@@ -1,19 +1,26 @@
 // SPDX-License-Identifier: BUSL-1.1
 pragma solidity ^0.8.24;
 
+import { Math } from "@openzeppelin/contracts/utils/math/Math.sol";
+import { SafeCast } from "@openzeppelin/contracts/utils/math/SafeCast.sol";
 import { Ownable } from "@openzeppelin/contracts/access/Ownable.sol";
 import { AlphaVaultHelpers } from "../_utils/AlphaVaultHelpers.sol";
+import { Range } from "../_interfaces/types/CommonTypes.sol";
 
 import { IMetaOracle } from "../_interfaces/IMetaOracle.sol";
 import { IAlphaProVault } from "../_interfaces/external/IAlphaProVault.sol";
 import { IUniswapV3Pool } from "@uniswap/v3-core/contracts/interfaces/IUniswapV3Pool.sol";
 
 /// @title UsdcSpotManager
 /// @notice This contract is a programmatic manager for the USDC-SPOT Charm AlphaProVault.
+/// @dev The vault provides highly concentrated liquidity when the market-price of SPOT is within
+///      the "active" zone as defined by the owner. When price moves outside the
+///      zone, the vault moves all assets into a full range position (infinite band).
 contract UsdcSpotManager is Ownable {
     //-------------------------------------------------------------------------
     // Libraries
     using AlphaVaultHelpers for IAlphaProVault;
+    using Math for uint256;
 
     //-------------------------------------------------------------------------
     // Constants & Immutables
@@ -22,6 +29,10 @@ contract UsdcSpotManager is Ownable {
     uint256 public constant DECIMALS = 18;
     uint256 public constant ONE = (10 ** DECIMALS);
 
+    /// @dev Vault parameter to set max full range weight (100%).
+    uint24 public constant VAULT_MAX_FRW = (10 ** 6);
+    int24 public constant POOL_MAX_TICK = 880000;
+
     /// @notice The USDC-SPOT charm alpha vault.
     IAlphaProVault public immutable VAULT;
 
@@ -37,6 +48,17 @@ contract UsdcSpotManager is Ownable {
     /// @notice The recorded deviation factor at the time of the last successful rebalance operation.
     uint256 public prevDeviation;
 
+    /// @notice The lower and upper deviation factor within which
+    ///         SPOT's price is considered to be in the active zone.
+    Range public activeZoneDeviation;
+
+    /// @notice The width of concentrated liquidity band,
+    ///         SPOT's price is in the active zone.
+    uint256 public concBandDeviationWidth;
+
+    /// @notice The maximum USDC balance of the vault's full range position.
+    uint256 public fullRangeMaxUsdcBal;
+
     //-----------------------------------------------------------------------------
     // Constructor and Initializer
 
@@ -50,6 +72,12 @@ contract UsdcSpotManager is Ownable {
         updateOracle(oracle_);
 
         prevDeviation = 0;
+        activeZoneDeviation = Range({
+            lower: ((ONE * 95) / 100), // 0.95 or 95%
+            upper: ((ONE * 105) / 100) // 1.05 or 105%
+        });
+        concBandDeviationWidth = ((ONE * 5) / 100); // 0.05 or 5%
+        fullRangeMaxUsdcBal = 250000 * (10 ** 6); // 250k USDC
     }
 
     //--------------------------------------------------------------------------
@@ -62,18 +90,6 @@ contract UsdcSpotManager is Ownable {
         oracle = oracle_;
     }
 
-    /// @notice Updates the vault's liquidity range parameters.
-    function setLiquidityRanges(
-        int24 baseThreshold,
-        uint24 fullRangeWeight,
-        int24 limitThreshold
-    ) external onlyOwner {
-        // Update liquidity parameters on the vault.
-        VAULT.setBaseThreshold(baseThreshold);
-        VAULT.setFullRangeWeight(fullRangeWeight);
-        VAULT.setLimitThreshold(limitThreshold);
-    }
-
     /// @notice Forwards the given calldata to the vault.
     /// @param callData The calldata to pass to the vault.
     /// @return The data returned by the vault method call.
@@ -87,25 +103,43 @@ contract UsdcSpotManager is Ownable {
         return r;
     }
 
+    /// @notice Updates the active zone definition.
+    function updateActiveZone(Range memory activeZoneDeviation_) external onlyOwner {
+        activeZoneDeviation = activeZoneDeviation_;
+    }
+
+    /// @notice Updates the width of the concentrated liquidity band.
+    function updateConcentratedBand(uint256 concBandDeviationWidth_) external onlyOwner {
+        concBandDeviationWidth = concBandDeviationWidth_;
+    }
+
+    /// @notice Updates the amount of liquidity in the full range liquidity band.
+    function updateFullRangeLiquidity(uint256 fullRangeMaxUsdcBal_) external onlyOwner {
+        fullRangeMaxUsdcBal = fullRangeMaxUsdcBal_;
+    }
+
     //--------------------------------------------------------------------------
     // External write methods
 
     /// @notice Executes vault rebalance.
     function rebalance() public {
         (uint256 deviation, bool deviationValid) = oracle.spotPriceDeviation();
+        bool withinActiveZone = (deviationValid && activeZone(deviation));
+        bool withinActiveZoneBefore = activeZone(prevDeviation);
+        bool shouldForceRebalance = ((!withinActiveZone && withinActiveZoneBefore) ||
+            (withinActiveZone && !withinActiveZoneBefore));
+
+        // Set liquidity parameters.
+        withinActiveZone ? _setupActiveZoneLiq(deviation) : _resetLiq();
 
         // Execute rebalance.
         // NOTE: the vault.rebalance() will revert if enough time has not elapsed.
         // We thus override with a force rebalance.
         // https://learn.charm.fi/charm/technical-references/core/alphaprovault#rebalance
-        (deviationValid && shouldForceRebalance(deviation, prevDeviation))
-            ? VAULT.forceRebalance()
-            : VAULT.rebalance();
+        shouldForceRebalance ? VAULT.forceRebalance() : VAULT.rebalance();
 
         // Trim positions after rebalance.
-        if (!deviationValid || shouldRemoveLimitRange(deviation)) {
-            VAULT.removeLimitLiquidity(POOL);
-        }
+        _trimLiquidity(withinActiveZone);
 
         // Update valid rebalance state.
         if (deviationValid) {
@@ -116,25 +150,15 @@ contract UsdcSpotManager is Ownable {
     //-----------------------------------------------------------------------------
     // External/Public view methods
 
-    /// @notice Checks if a rebalance has to be forced.
-    function shouldForceRebalance(
-        uint256 deviation,
-        uint256 prevDeviation_
-    ) public pure returns (bool) {
-        // We rebalance if the deviation factor has crossed ONE (in either direction).
-        return ((deviation <= ONE && prevDeviation_ > ONE) ||
-            (deviation >= ONE && prevDeviation_ < ONE));
-    }
-
-    /// @notice Checks if limit range liquidity needs to be removed.
-    function shouldRemoveLimitRange(uint256 deviation) public view returns (bool) {
-        // We only activate the limit range liquidity, when
-        // the vault sells SPOT and deviation is above ONE, or when
-        // the vault buys SPOT and deviation is below ONE
-        bool extraSpot = isOverweightSpot();
-        bool activeLimitRange = ((deviation >= ONE && extraSpot) ||
-            (deviation <= ONE && !extraSpot));
-        return (!activeLimitRange);
+    /// @notice Based on the given deviation factor,
+    ///         calculates if the pool needs to be in the active zone.
+    function activeZone(uint256 deviation) public view returns (bool) {
+        Range memory concBandDeviation = Range({
+            lower: (activeZoneDeviation.lower + concBandDeviationWidth / 2),
+            upper: (activeZoneDeviation.upper - concBandDeviationWidth / 2)
+        });
+        return (concBandDeviation.lower <= deviation &&
+            deviation <= concBandDeviation.upper);
     }
 
     /// @notice Checks the vault is overweight SPOT and looking to sell the extra SPOT for USDC.
@@ -144,8 +168,55 @@ contract UsdcSpotManager is Ownable {
         return VAULT.isUnderweightToken0();
     }
 
+    /// @notice Calculates the Univ3 tick equivalent of the given deviation factor.
+    function deviationToTicks(uint256 deviation) public pure returns (int24) {
+        // 2% ~ 200 ticks -> (POOL.tickSpacing())
+        // NOTE: width can't be zero, we set the minimum possible to 200.
+        uint256 t = deviation.mulDiv(10000, ONE);
+        t -= (t % 200);
+        return (t >= 200 ? SafeCast.toInt24(SafeCast.toInt256(t)) : int24(200));
+    }
+
     /// @return Number of decimals representing 1.0.
     function decimals() external pure returns (uint8) {
         return uint8(DECIMALS);
     }
+
+    /// @dev Configures the vault to provide concentrated liquidity in the active zone.
+    function _setupActiveZoneLiq(uint256 deviation) private {
+        (uint256 usdcBal, ) = VAULT.getTotalAmounts();
+        uint256 fullRangeWeight = uint256(VAULT_MAX_FRW).mulDiv(
+            fullRangeMaxUsdcBal,
+            usdcBal
+        );
+        uint256 limitBandDeviationWidth = isOverweightSpot()
+            ? activeZoneDeviation.upper - deviation
+            : deviation - activeZoneDeviation.lower;
+        VAULT.setFullRangeWeight(SafeCast.toUint24(fullRangeWeight));
+
+        // IMPORTANT: The deviation percentage, to ticks conversion isn't precise.
+        // In the worst case, there might be liquidity up to 2% outside the active zone definition.
+        VAULT.setBaseThreshold(deviationToTicks(concBandDeviationWidth));
+        VAULT.setLimitThreshold(deviationToTicks(limitBandDeviationWidth));
+    }
+
+    /// @dev Resets the vault to provide full range liquidity.
+    function _resetLiq() private {
+        VAULT.setFullRangeWeight(VAULT_MAX_FRW);
+        VAULT.setBaseThreshold(POOL_MAX_TICK);
+        VAULT.setLimitThreshold(POOL_MAX_TICK);
+    }
+
+    /// @dev Removes excess liquidity from the vault after rebalance.
+    function _trimLiquidity(bool withinActiveZone) private {
+        // If we are in the active zone, we keep all the liquidity.
+        if (withinActiveZone) {
+            return;
+        }
+        // Otherwise, we trim positions.
+        (uint256 usdcBal, ) = VAULT.getTotalAmounts();
+        uint256 percToRemove = (ONE - ONE.mulDiv(fullRangeMaxUsdcBal, usdcBal));
+        VAULT.trimLiquidity(POOL, percToRemove, ONE);
+        VAULT.removeLimitLiquidity(POOL);
+    }
 }
diff --git a/spot-vaults/test/UsdcSpotManager.ts b/spot-vaults/test/UsdcSpotManager.ts
