refactor!: sdex burn ratio to uint64 (#895)

* refactor!: sdex burn ratio to uint64

The value for `sdexBurnOnDepositRatio` was previously stored as an
uint32 which proved to be too small for shortDN. A new slot in the
storage struct was defined for the new value as uint64.

BREAKING CHANGE: this is breaking for consumers which expect a uint32,
and it requires a storage update for the existing protocol instances

* feat: add storage upgrade function

* build: add upgrade script for v2

* chore: update upgrade script

* chore: add new fallback deployment to upgrade script

* chore: add validatation to upgrade script

* chore: rename constant

* chore: rename contract

* chore: change script notice comment

* chore: update lockfile

* docs: add how to calculate the storage slot

* docs: re-order natspec

* chore: add asserts for script

Author: beeb

package-lock.json

@@ -0,0 +1,60 @@
+// SPDX-License-Identifier: UNLICENSED
+pragma solidity 0.8.26;
+
+import { Script } from "forge-std/Script.sol";
+
+import { UsdnWstethUsdConfig } from "./deploymentConfigs/UsdnWstethUsdConfig.sol";
+import { Utils } from "./utils/Utils.s.sol";
+
+import { UsdnProtocolFallback } from "../src/UsdnProtocol/UsdnProtocolFallback.sol";
+import { UsdnProtocolImpl } from "../src/UsdnProtocol/UsdnProtocolImpl.sol";
+import { UsdnProtocolConstantsLibrary as Constants } from
+    "../src/UsdnProtocol/libraries/UsdnProtocolConstantsLibrary.sol";
+import { IUsdnProtocol } from "../src/interfaces/UsdnProtocol/IUsdnProtocol.sol";
+
+/**
+ * @title Upgrade script
+ * @notice This script is only made for upgrading the Usdn protocol from v1.x.x to v2.0.0.
+ * @dev The sender must already have the `PROXY_UPGRADE_ROLE` before launching this script.
+ */
+contract UpgradeV2 is UsdnWstethUsdConfig, Script {
+    IUsdnProtocol constant USDN_PROTOCOL = IUsdnProtocol(0x656cB8C6d154Aad29d8771384089be5B5141f01a);
+
+    /// @dev this is the keccak-256 hash of "eip1967.proxy.implementation" subtracted by 1.
+    bytes32 constant IMPL_SLOT = 0x360894a13ba1a3210667c828492db98dca3e2076cc3735a920a3ca505d382bbc;
+
+    Utils utils;
+
+    constructor() {
+        utils = new Utils();
+    }
+
+    function run()
+        external
+        returns (UsdnProtocolFallback newUsdnProtocolFallback_, UsdnProtocolImpl newUsdnProtocolImpl_)
+    {
+        utils.validateProtocol("UsdnProtocolImpl", "UsdnProtocolFallback");
+
+        require(
+            USDN_PROTOCOL.hasRole(Constants.PROXY_UPGRADE_ROLE, msg.sender),
+            "Sender does not have the permission to upgrade the protocol"
+        );
+        bytes32 oldImpl = vm.load(address(USDN_PROTOCOL), IMPL_SLOT);
+
+        vm.startBroadcast();
+
+        newUsdnProtocolFallback_ = new UsdnProtocolFallback(MAX_SDEX_BURN_RATIO, MAX_MIN_LONG_POSITION);
+        newUsdnProtocolImpl_ = new UsdnProtocolImpl();
+        USDN_PROTOCOL.upgradeToAndCall(
+            address(newUsdnProtocolImpl_),
+            abi.encodeWithSelector(UsdnProtocolImpl.initializeStorageV2.selector, address(newUsdnProtocolFallback_))
+        );
+        bytes32 newImpl = vm.load(address(USDN_PROTOCOL), IMPL_SLOT);
+        require(oldImpl != newImpl, "Upgrade failed");
+        require(address(uint160(uint256(newImpl))) == address(newUsdnProtocolImpl_), "Upgrade failed");
+        require(USDN_PROTOCOL.getSdexBurnOnDepositRatio() > 0, "New storage not initialized");
+        require(USDN_PROTOCOL.getFallbackAddress() == address(newUsdnProtocolFallback_), "New fallback not set");
+
+        vm.stopBroadcast();
+    }
+}

script/55_UpgradeV2.s.sol

@@ -314,7 +314,7 @@ contract UsdnProtocolFallback is
     }
 
     /// @inheritdoc IUsdnProtocolFallback
-    function getSdexBurnOnDepositRatio() external view returns (uint32 ratio_) {
+    function getSdexBurnOnDepositRatio() external view returns (uint64 ratio_) {
         return Utils._getMainStorage()._sdexBurnOnDepositRatio;
     }
 
@@ -590,7 +590,7 @@ contract UsdnProtocolFallback is
     }
 
     /// @inheritdoc IUsdnProtocolFallback
-    function setSdexBurnOnDepositRatio(uint32 newRatio) external onlyRole(Constants.SET_PROTOCOL_PARAMS_ROLE) {
+    function setSdexBurnOnDepositRatio(uint64 newRatio) external onlyRole(Constants.SET_PROTOCOL_PARAMS_ROLE) {
         Setters.setSdexBurnOnDepositRatio(MAX_SDEX_BURN_RATIO, newRatio);
     }
 

src/UsdnProtocol/UsdnProtocolFallback.sol

@@ -52,6 +52,17 @@ contract UsdnProtocolImpl is
         Setters.setInitialStorage(initStorage);
     }
 
+    /// @inheritdoc IUsdnProtocolImpl
+    function initializeStorageV2(address newFallback) public reinitializer(2) {
+        Storage storage s = Utils._getMainStorage();
+        // sanity check, only do the upgrade if necessary
+        if (s.__unused == 0 || s._sdexBurnOnDepositRatio > 0) {
+            return;
+        }
+        s._sdexBurnOnDepositRatio = s.__unused;
+        s._protocolFallbackAddr = newFallback;
+    }
+
     /**
      * @inheritdoc UUPSUpgradeable
      * @notice Verifies that the caller is allowed to upgrade the protocol.

src/UsdnProtocol/UsdnProtocolImpl.sol

@@ -230,7 +230,7 @@ library UsdnProtocolSettersLibrary {
     }
 
     /// @notice See {UsdnProtocolFallback.setSdexBurnOnDepositRatio}.
-    function setSdexBurnOnDepositRatio(uint256 highestPossibleValue, uint32 newRatio) external {
+    function setSdexBurnOnDepositRatio(uint256 highestPossibleValue, uint64 newRatio) external {
         Types.Storage storage s = Utils._getMainStorage();
 
         if (newRatio > highestPossibleValue) {

src/UsdnProtocol/libraries/UsdnProtocolSettersLibrary.sol

@@ -543,7 +543,7 @@ library UsdnProtocolUtilsLibrary {
      * @param sdexBurnRatio The ratio of SDEX burned per minted USDN.
      * @return sdexToBurn_ The amount of SDEX tokens to burn.
      */
-    function _calcSdexToBurn(uint256 usdnAmount, uint32 sdexBurnRatio) internal pure returns (uint256 sdexToBurn_) {
+    function _calcSdexToBurn(uint256 usdnAmount, uint64 sdexBurnRatio) internal pure returns (uint256 sdexToBurn_) {
         sdexToBurn_ = FixedPointMathLib.fullMulDivUp(usdnAmount, sdexBurnRatio, Constants.SDEX_BURN_ON_DEPOSIT_DIVISOR);
     }
 

src/UsdnProtocol/libraries/UsdnProtocolUtilsLibrary.sol

@@ -604,7 +604,7 @@ library UsdnProtocolVaultLibrary {
         if (usdnToMintEstimated == 0) {
             revert IUsdnProtocolErrors.UsdnProtocolDepositTooSmall();
         }
-        uint32 burnRatio = s._sdexBurnOnDepositRatio;
+        uint64 burnRatio = s._sdexBurnOnDepositRatio;
         data_.sdexToBurn = Utils._calcSdexToBurn(usdnToMintEstimated, burnRatio);
     }
 

src/UsdnProtocol/libraries/UsdnProtocolVaultLibrary.sol

@@ -336,7 +336,7 @@ interface IUsdnProtocolFallback is IUsdnProtocolTypes {
      * @notice Gets the ratio of SDEX tokens to burn per minted USDN.
      * @return ratio_ The ratio (to be divided by SDEX_BURN_ON_DEPOSIT_DIVISOR).
      */
-    function getSdexBurnOnDepositRatio() external view returns (uint32 ratio_);
+    function getSdexBurnOnDepositRatio() external view returns (uint64 ratio_);
 
     /**
      * @notice Gets the amount of native tokens used as security deposit when opening a new position.
@@ -660,7 +660,7 @@ interface IUsdnProtocolFallback is IUsdnProtocolTypes {
      * constructor argument when the {UsdnProtocolFallback} contract is deployed and is stored in an immutable variable.
      * @param newRatio The new ratio.
      */
-    function setSdexBurnOnDepositRatio(uint32 newRatio) external;
+    function setSdexBurnOnDepositRatio(uint64 newRatio) external;
 
     /**
      * @notice Sets the security deposit value.

src/interfaces/UsdnProtocol/IUsdnProtocolFallback.sol

@@ -31,4 +31,13 @@ interface IUsdnProtocolImpl is
      * Any call with a function signature not present in this contract will be delegated to the fallback contract.
      */
     function initializeStorage(InitStorage calldata initStorage) external;
+
+    /**
+     * @notice Updates the protocol's storage from V1 to V2.
+     * @dev This specifically re-assigns the value for `sdexBurnOnDepositRatio` to a new storage slot, and updates
+     * the address of the fallback contract.
+     * It can only be called once and should only be called if the protocol was initially deployed as V1.
+     * @param newFallback The address of the new fallback contract that was deployed.
+     */
+    function initializeStorageV2(address newFallback) external;
 }

src/interfaces/UsdnProtocol/IUsdnProtocolImpl.sol

@@ -593,7 +593,7 @@ interface IUsdnProtocolTypes {
      * @param _positionFeeBps The position fee in basis points.
      * @param _vaultFeeBps The fee for vault deposits and withdrawals, in basis points.
      * @param _sdexRewardsRatioBps The ratio of SDEX rewards to send to the user (in basis points).
-     * @param _sdexBurnOnDepositRatio The ratio of USDN to SDEX tokens to burn on deposit.
+     * @param __unused Old slot for `_sdexBurnOnDepositRatio`.
      * @param _feeCollector The fee collector's address.
      * @param _securityDepositValue The deposit required for a new position.
      * @param _targetUsdnPrice The nominal (target) price of USDN (with _priceFeedDecimals).
@@ -624,6 +624,7 @@ interface IUsdnProtocolTypes {
      * @param _tickBitmap The bitmap used to quickly find populated ticks.
      * @param _protocolFallbackAddr The address of the fallback contract.
      * @param _nonce The user EIP712 nonce.
+     * @param _sdexBurnOnDepositRatio The ratio of USDN to SDEX tokens to burn on deposit.
      */
     struct Storage {
         // immutable
@@ -660,7 +661,7 @@ interface IUsdnProtocolTypes {
         uint16 _positionFeeBps;
         uint16 _vaultFeeBps;
         uint16 _sdexRewardsRatioBps;
-        uint32 _sdexBurnOnDepositRatio;
+        uint32 __unused;
         address _feeCollector;
         uint64 _securityDepositValue;
         uint128 _targetUsdnPrice;
@@ -692,6 +693,7 @@ interface IUsdnProtocolTypes {
         address _protocolFallbackAddr;
         // EIP712
         mapping(address => uint256) _nonce;
+        uint64 _sdexBurnOnDepositRatio;
     }
 
     /**
@@ -763,7 +765,7 @@ interface IUsdnProtocolTypes {
         uint16 positionFeeBps;
         uint16 vaultFeeBps;
         uint16 sdexRewardsRatioBps;
-        uint32 sdexBurnOnDepositRatio;
+        uint64 sdexBurnOnDepositRatio;
         address feeCollector;
         uint64 securityDepositValue;
         uint128 targetUsdnPrice;

src/interfaces/UsdnProtocol/IUsdnProtocolTypes.sol

@@ -22,7 +22,7 @@ contract TestUsdnProtocolCalcUsdnPrice is UsdnProtocolBaseFixture {
      * @custom:then The correct amount of SDEX to burn is returned
      */
     function test_calcSdexToBurn() public view {
-        uint32 burnRatio = protocol.getSdexBurnOnDepositRatio();
+        uint64 burnRatio = protocol.getSdexBurnOnDepositRatio();
         uint256 burnRatioDivisor = Constants.SDEX_BURN_ON_DEPOSIT_DIVISOR;
         uint8 usdnDecimals = Constants.TOKENS_DECIMALS;
 

test/unit/UsdnProtocol/Vault/_CalcSdexToBurn.t.sol

@@ -377,7 +377,7 @@ contract UsdnProtocolHandler is UsdnProtocolImpl, UsdnProtocolFallback, Test {
         return Utils._getOraclePrice(action, timestamp, actionId, priceData);
     }
 
-    function i_calcSdexToBurn(uint256 usdnAmount, uint32 sdexBurnRatio) external pure returns (uint256) {
+    function i_calcSdexToBurn(uint256 usdnAmount, uint64 sdexBurnRatio) external pure returns (uint256) {
         return Utils._calcSdexToBurn(usdnAmount, sdexBurnRatio);
     }