Convertible Deposits

src/libraries/DecimalString.sol

@@ -0,0 +1,92 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+pragma solidity ^0.8;
+
+import {uint2str} from "./Uint2Str.sol";
+import {console2} from "forge-std/console2.sol";
+
+library DecimalString {
+    /// @notice Converts a uint256 value to a string with a specified number of decimal places.
+    ///         The value is adjusted by the scale factor and then formatted to the specified number of decimal places.
+    ///         The decimal places are not zero-padded, so the result is not always the same length.
+    /// @dev    This is inspired by code in [FixedStrikeOptionTeller](https://github.com/Bond-Protocol/option-contracts/blob/b8ce2ca2bae3bd06f0e7665c3aa8d827e4d8ca2c/src/fixed-strike/FixedStrikeOptionTeller.sol#L722).
+    ///
+    /// @param  value_            The uint256 value to convert to a string.
+    /// @param  valueDecimals_    The scale factor of the value.
+    /// @param  decimalPlaces_    The number of decimal places to format the value to.
+    /// @return result            A string representation of the value with the specified number of decimal places.
+    function toDecimalString(
+        uint256 value_,
+        uint8 valueDecimals_,
+        uint8 decimalPlaces_
+    ) internal pure returns (string memory) {
+        // Handle zero case
+        if (value_ == 0) return "0";
+
+        // Convert the entire number to string first
+        string memory str = uint2str(value_);
+        bytes memory bStr = bytes(str);
+
+        // If no decimal places requested, just handle the scaling and return
+        if (decimalPlaces_ == 0) {
+            if (bStr.length <= valueDecimals_) return "0";
+            return uint2str(value_ / (10 ** valueDecimals_));
+        }
+
+        // If value is a whole number, return as-is
+        if (valueDecimals_ == 0) return str;
+
+        // Calculate decimal places to show (limited by request and available decimals)
+        uint256 maxDecimalPlaces = valueDecimals_ > decimalPlaces_
+            ? decimalPlaces_
+            : valueDecimals_;
+
+        // Handle numbers smaller than 1
+        if (bStr.length <= valueDecimals_) {
+            bytes memory smallResult = new bytes(2 + maxDecimalPlaces);
+            smallResult[0] = "0";
+            smallResult[1] = ".";
+
+            uint256 leadingZeros = valueDecimals_ - bStr.length;
+            uint256 zerosToAdd = leadingZeros > maxDecimalPlaces ? maxDecimalPlaces : leadingZeros;
+
+            // Add leading zeros after decimal
+            for (uint256 i = 0; i < zerosToAdd; i++) {
+                smallResult[i + 2] = "0";
+            }
+
+            // Add available digits
+            for (uint256 i = 0; i < maxDecimalPlaces - zerosToAdd && i < bStr.length; i++) {
+                smallResult[i + 2 + zerosToAdd] = bStr[i];
+            }
+
+            return string(smallResult);
+        }
+
+        // Find decimal position and last significant digit
+        uint256 decimalPosition = bStr.length - valueDecimals_;
+        uint256 lastNonZeroPos = decimalPosition;
+        for (uint256 i = 0; i < maxDecimalPlaces && i + decimalPosition < bStr.length; i++) {
+            if (bStr[decimalPosition + i] != "0") {
+                lastNonZeroPos = decimalPosition + i + 1;
+            }
+        }
+
+        // Create and populate result
+        bytes memory finalResult = new bytes(
+            lastNonZeroPos - decimalPosition > 0 ? lastNonZeroPos + 1 : lastNonZeroPos
+        );
+
+        for (uint256 i = 0; i < decimalPosition; i++) {
+            finalResult[i] = bStr[i];
+        }
+
+        if (lastNonZeroPos > decimalPosition) {
+            finalResult[decimalPosition] = ".";
+            for (uint256 i = 0; i < lastNonZeroPos - decimalPosition; i++) {
+                finalResult[decimalPosition + 1 + i] = bStr[decimalPosition + i];
+            }
+        }
+
+        return string(finalResult);
+    }
+}

src/libraries/Timestamp.sol

@@ -0,0 +1,45 @@
+// SPDX-License-Identifier: MIT
+pragma solidity 0.8.15;
+
+import {uint2str} from "./Uint2Str.sol";
+
+library Timestamp {
+    function toPaddedString(
+        uint48 timestamp
+    ) internal pure returns (string memory, string memory, string memory) {
+        // Convert a number of days into a human-readable date, courtesy of BokkyPooBah.
+        // Source: https://github.com/bokkypoobah/BokkyPooBahsDateTimeLibrary/blob/master/contracts/BokkyPooBahsDateTimeLibrary.sol
+
+        uint256 year;
+        uint256 month;
+        uint256 day;
+        {
+            int256 __days = int256(int48(timestamp) / 1 days);
+
+            int256 num1 = __days + 68_569 + 2_440_588; // 2440588 = OFFSET19700101
+            int256 num2 = (4 * num1) / 146_097;
+            num1 = num1 - (146_097 * num2 + 3) / 4;
+            int256 _year = (4000 * (num1 + 1)) / 1_461_001;
+            num1 = num1 - (1461 * _year) / 4 + 31;
+            int256 _month = (80 * num1) / 2447;
+            int256 _day = num1 - (2447 * _month) / 80;
+            num1 = _month / 11;
+            _month = _month + 2 - 12 * num1;
+            _year = 100 * (num2 - 49) + _year + num1;
+
+            year = uint256(_year);
+            month = uint256(_month);
+            day = uint256(_day);
+        }
+
+        string memory yearStr = uint2str(year % 10_000);
+        string memory monthStr = month < 10
+            ? string(abi.encodePacked("0", uint2str(month)))
+            : uint2str(month);
+        string memory dayStr = day < 10
+            ? string(abi.encodePacked("0", uint2str(day)))
+            : uint2str(day);
+
+        return (yearStr, monthStr, dayStr);
+    }
+}

src/libraries/Uint2Str.sol

@@ -0,0 +1,27 @@
+// SPDX-License-Identifier: UNLICENSED
+pragma solidity ^0.8;
+
+// Some fancy math to convert a uint into a string, courtesy of Provable Things.
+// Updated to work with solc 0.8.0.
+// https://github.com/provable-things/ethereum-api/blob/master/provableAPI_0.6.sol
+function uint2str(uint256 _i) pure returns (string memory) {
+    if (_i == 0) {
+        return "0";
+    }
+    uint256 j = _i;
+    uint256 len;
+    while (j != 0) {
+        len++;
+        j /= 10;
+    }
+    bytes memory bstr = new bytes(len);
+    uint256 k = len;
+    while (_i != 0) {
+        k = k - 1;
+        uint8 temp = (48 + uint8(_i - (_i / 10) * 10));
+        bytes1 b1 = bytes1(temp);
+        bstr[k] = b1;
+        _i /= 10;
+    }
+    return string(bstr);
+}

src/modules/CDEPO/CDEPO.v1.sol

@@ -0,0 +1,187 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+pragma solidity 0.8.15;
+
+import {Kernel, Module} from "src/Kernel.sol";
+import {ERC20} from "solmate/tokens/ERC20.sol";
+import {ERC4626} from "solmate/mixins/ERC4626.sol";
+
+/// @title  CDEPOv1
+/// @notice This is a base contract for a custodial convertible deposit token. It is designed to be used in conjunction with an ERC4626 vault.
+abstract contract CDEPOv1 is Module, ERC20 {
+    // ========== EVENTS ========== //
+
+    /// @notice Emitted when the reclaim rate is updated
+    event ReclaimRateUpdated(uint16 newReclaimRate);
+
+    /// @notice Emitted when the yield is swept
+    event YieldSwept(address receiver, uint256 reserveAmount, uint256 sReserveAmount);
+
+    // ========== ERRORS ========== //
+
+    /// @notice Thrown when the caller provides invalid arguments
+    error CDEPO_InvalidArgs(string reason);
+
+    // ========== CONSTANTS ========== //
+
+    /// @notice Equivalent to 100%
+    uint16 public constant ONE_HUNDRED_PERCENT = 100e2;
+
+    // ========== STATE VARIABLES ========== //
+
+    /// @notice The reclaim rate of the convertible deposit token
+    /// @dev    A reclaim rate of 99e2 (99%) means that for every 100 convertible deposit tokens burned, 99 underlying asset tokens are returned
+    uint16 internal _reclaimRate;
+
+    /// @notice The total amount of vault shares in the contract
+    uint256 public totalShares;
+
+    // ========== ERC20 OVERRIDES ========== //
+
+    /// @notice Mint tokens to the caller in exchange for the underlying asset
+    /// @dev    The implementing function should perform the following:
+    ///         - Transfers the underlying asset from the caller to the contract
+    ///         - Mints the corresponding amount of convertible deposit tokens to the caller
+    ///         - Deposits the underlying asset into the ERC4626 vault
+    ///         - Emits a `Transfer` event
+    ///
+    /// @param  amount_   The amount of underlying asset to transfer
+    function mint(uint256 amount_) external virtual;
+
+    /// @notice Mint tokens to `account_` in exchange for the underlying asset
+    ///         This function behaves the same as `mint`, but allows the caller to
+    ///         specify the address to mint the tokens to and pull the asset from.
+    ///         The `account_` address must have approved the contract to spend the underlying asset.
+    /// @dev    The implementing function should perform the following:
+    ///         - Transfers the underlying asset from the `account_` address to the contract
+    ///         - Mints the corresponding amount of convertible deposit tokens to the `account_` address
+    ///         - Deposits the underlying asset into the ERC4626 vault
+    ///         - Emits a `Transfer` event
+    ///
+    /// @param  account_    The address to mint the tokens to and pull the asset from
+    /// @param  amount_     The amount of asset to transfer
+    function mintFor(address account_, uint256 amount_) external virtual;
+
+    /// @notice Preview the amount of convertible deposit tokens that would be minted for a given amount of underlying asset
+    /// @dev    The implementing function should perform the following:
+    ///         - Computes the amount of convertible deposit tokens that would be minted for the given amount of underlying asset
+    ///         - Returns the computed amount
+    ///
+    /// @param  amount_   The amount of underlying asset to transfer
+    /// @return tokensOut The amount of convertible deposit tokens that would be minted
+    function previewMint(uint256 amount_) external view virtual returns (uint256 tokensOut);
+
+    /// @notice Burn tokens from the caller and reclaim the underlying asset
+    ///         The amount of underlying asset may not be 1:1 with the amount of
+    ///         convertible deposit tokens, depending on the value of `burnRate`
+    /// @dev    The implementing function should perform the following:
+    ///         - Withdraws the underlying asset from the ERC4626 vault
+    ///         - Transfers the underlying asset to the caller
+    ///         - Burns the corresponding amount of convertible deposit tokens from the caller
+    ///         - Marks the forfeited amount of the underlying asset as yield
+    ///
+    /// @param  amount_   The amount of convertible deposit tokens to burn
+    function reclaim(uint256 amount_) external virtual;
+
+    /// @notice Burn tokens from `account_` and reclaim the underlying asset
+    ///         This function behaves the same as `reclaim`, but allows the caller to
+    ///         specify the address to burn the tokens from and transfer the underlying
+    ///         asset to.
+    ///         The `account_` address must have approved the contract to spend the convertible deposit tokens.
+    /// @dev    The implementing function should perform the following:
+    ///         - Validates that the `account_` address has approved the contract to spend the convertible deposit tokens
+    ///         - Withdraws the underlying asset from the ERC4626 vault
+    ///         - Transfers the underlying asset to the `account_` address
+    ///         - Burns the corresponding amount of convertible deposit tokens from the `account_` address
+    ///         - Marks the forfeited amount of the underlying asset as yield
+    ///
+    /// @param  account_    The address to burn the convertible deposit tokens from and transfer the underlying asset to
+    /// @param  amount_     The amount of convertible deposit tokens to burn
+    function reclaimFor(address account_, uint256 amount_) external virtual;
+
+    /// @notice Preview the amount of underlying asset that would be reclaimed for a given amount of convertible deposit tokens
+    /// @dev    The implementing function should perform the following:
+    ///         - Computes the amount of underlying asset that would be returned for the given amount of convertible deposit tokens
+    ///         - Returns the computed amount
+    ///
+    /// @param  amount_   The amount of convertible deposit tokens to burn
+    /// @return assetsOut The amount of underlying asset that would be reclaimed
+    function previewReclaim(uint256 amount_) external view virtual returns (uint256 assetsOut);
+
+    /// @notice Redeem convertible deposit tokens for the underlying asset
+    ///         This differs from the reclaim function, in that it is an admin-level and permissioned function that does not apply the burn rate.
+    /// @dev    The implementing function should perform the following:
+    ///         - Validates that the caller is permissioned
+    ///         - Transfers the corresponding underlying assets to the caller
+    ///         - Burns the corresponding amount of convertible deposit tokens from the caller
+    ///
+    /// @param  amount_   The amount of convertible deposit tokens to burn
+    /// @return tokensOut The amount of underlying assets that were transferred to the caller
+    function redeem(uint256 amount_) external virtual returns (uint256 tokensOut);
+
+    /// @notice Redeem convertible deposit tokens for the underlying asset
+    ///         This differs from the redeem function, in that it allows the caller to specify the address to burn the convertible deposit tokens from.
+    ///         The `account_` address must have approved the contract to spend the convertible deposit tokens.
+    /// @dev    The implementing function should perform the following:
+    ///         - Validates that the caller is permissioned
+    ///         - Validates that the `account_` address has approved the contract to spend the convertible deposit tokens
+    ///         - Burns the corresponding amount of convertible deposit tokens from the `account_` address
+    ///         - Transfers the corresponding underlying assets to the caller (not the `account_` address)
+    ///
+    /// @param  account_    The address to burn the convertible deposit tokens from
+    /// @param  amount_     The amount of convertible deposit tokens to burn
+    /// @return tokensOut   The amount of underlying assets that were transferred to the caller
+    function redeemFor(
+        address account_,
+        uint256 amount_
+    ) external virtual returns (uint256 tokensOut);
+
+    // ========== YIELD MANAGER ========== //
+
+    /// @notice Claim the yield accrued on the reserve token
+    /// @dev    The implementing function should perform the following:
+    ///         - Validating that the caller has the correct role
+    ///         - Withdrawing the yield from the sReserve token
+    ///         - Transferring the yield to the caller
+    ///         - Emitting an event
+    ///
+    /// @param  to_         The address to sweep the yield to
+    /// @return yieldReserve  The amount of reserve token that was swept
+    /// @return yieldSReserve The amount of sReserve token that was swept
+    function sweepYield(
+        address to_
+    ) external virtual returns (uint256 yieldReserve, uint256 yieldSReserve);
+
+    /// @notice Preview the amount of yield that would be swept
+    ///
+    /// @return yieldReserve  The amount of reserve token that would be swept
+    /// @return yieldSReserve The amount of sReserve token that would be swept
+    function previewSweepYield()
+        external
+        view
+        virtual
+        returns (uint256 yieldReserve, uint256 yieldSReserve);
+
+    // ========== ADMIN ========== //
+
+    /// @notice Set the reclaim rate of the convertible deposit token
+    /// @dev    The implementing function should perform the following:
+    ///         - Validating that the caller has the correct role
+    ///         - Validating that the new rate is within bounds
+    ///         - Setting the new reclaim rate
+    ///         - Emitting an event
+    ///
+    /// @param  newReclaimRate_    The new reclaim rate
+    function setReclaimRate(uint16 newReclaimRate_) external virtual;
+
+    // ========== STATE VARIABLES ========== //
+
+    /// @notice The ERC4626 vault that holds the underlying asset
+    function vault() external view virtual returns (ERC4626);
+
+    /// @notice The underlying ERC20 asset
+    function asset() external view virtual returns (ERC20);
+
+    /// @notice The reclaim rate of the convertible deposit token
+    /// @dev    A reclaim rate of 99e2 (99%) means that for every 100 convertible deposit tokens burned, 99 underlying asset tokens are returned
+    function reclaimRate() external view virtual returns (uint16);
+}