delvtech · jalextowle · Mar 7, 2024 · Mar 2, 2024 · Mar 2, 2024
@@ -16,7 +16,7 @@ contract StETHHyperdriveCoreDeployer is IHyperdriveCoreDeployer {
     /// @notice The Lido contract.
     ILido public immutable lido;
 
-    /// @notice Instanstiates the core deployer.
+    /// @notice Instantiates the core deployer.
     /// @param _lido The Lido contract.
     constructor(ILido _lido) {
         lido = _lido;

@@ -16,7 +16,7 @@ contract StETHTarget0Deployer is IHyperdriveTargetDeployer {
     /// @notice The Lido contract.
     ILido public immutable lido;
 
-    /// @notice Instanstiates the target0 deployer.
+    /// @notice Instantiates the target0 deployer.
     /// @param _lido The Lido contract.
     constructor(ILido _lido) {
         lido = _lido;

@@ -16,7 +16,7 @@ contract StETHTarget1Deployer is IHyperdriveTargetDeployer {
     /// @notice The Lido contract.
     ILido public immutable lido;
 
-    /// @notice Instanstiates the target1 deployer.
+    /// @notice Instantiates the target1 deployer.
     /// @param _lido The Lido contract.
     constructor(ILido _lido) {
         lido = _lido;

@@ -16,7 +16,7 @@ contract StETHTarget2Deployer is IHyperdriveTargetDeployer {
     /// @notice The Lido contract.
     ILido public immutable lido;
 
-    /// @notice Instanstiates the target2 deployer.
+    /// @notice Instantiates the target2 deployer.
     /// @param _lido The Lido contract.
     constructor(ILido _lido) {
         lido = _lido;

@@ -16,7 +16,7 @@ contract StETHTarget3Deployer is IHyperdriveTargetDeployer {
     /// @notice The Lido contract.
     ILido public immutable lido;
 
-    /// @notice Instanstiates the target3 deployer.
+    /// @notice Instantiates the target3 deployer.
     /// @param _lido The Lido contract.
     constructor(ILido _lido) {
         lido = _lido;

@@ -16,7 +16,7 @@ contract StETHTarget4Deployer is IHyperdriveTargetDeployer {
     /// @notice The Lido contract.
     ILido public immutable lido;
 
-    /// @notice Instanstiates the target4 deployer.
+    /// @notice Instantiates the target4 deployer.
     /// @param _lido The Lido contract.
     constructor(ILido _lido) {
         lido = _lido;

@@ -84,8 +84,8 @@ abstract contract Hyperdrive is
     ///         stateful functions.
     address public immutable target3;
 
-    /// @notice The target4 address. This is a logic contract that contains all
-    ///         some stateful functions.
+    /// @notice The target4 address. This is a logic contract that contains
+    ///         stateful functions.
     address public immutable target4;
 
     /// @notice The typehash used to calculate the EIP712 hash for `permitForAll`.

@@ -136,8 +136,8 @@ abstract contract HyperdriveTarget0 is
     /// @param tokenID The asset to approve the use of.
     /// @param operator The address who will be able to use the tokens.
     /// @param amount The max tokens the approved person can use, setting to
-    ///        uint256.max will cause the value to never decrement [saving gas
-    ///        on transfer].
+    ///        uint256.max will cause the value to never decrement (saving gas
+    ///        on transfer).
     function setApproval(
         uint256 tokenID,
         address operator,

@@ -37,9 +37,10 @@ abstract contract HyperdriveTarget4 is
     /// @param _maxDeposit The most the user expects to deposit for this trade.
     ///        The units of this quantity are either base or vault shares,
     ///        depending on the value of `_options.asBase`.
-    /// @param _minVaultSharePrice The minimum vault share price at which to open
-    ///        the short. This allows traders to protect themselves from opening
-    ///        a short in a checkpoint where negative interest has accrued.
+    /// @param _minVaultSharePrice The minimum vault share price at which to
+    ///        open the short. This allows traders to protect themselves from
+    ///        opening a short in a checkpoint where negative interest has
+    ///        accrued.
     /// @param _options The options that configure how the trade is settled.
     /// @return The maturity time of the short.
     /// @return The amount the user deposited for this trade. The units of this

@@ -128,7 +128,7 @@ contract HyperdriveFactory is IHyperdriveFactory {
     mapping(address => bool) public isDeployerCoordinator;
 
     /// @notice A mapping from deployed Hyperdrive instances to the deployer
-    ///         coordintor that deployed them. This is useful for verifying
+    ///         coordinator that deployed them. This is useful for verifying
     ///         the bytecode that was used to deploy the instance.
     mapping(address instance => address deployCoordinator)
         public instancesToDeployerCoordinators;

@@ -140,7 +140,6 @@ abstract contract ERC4626Base is HyperdriveBase {
 
     /// @notice Loads the vault share price from the yield source.
     /// @return The current vault share price.
-    /// @dev must remain consistent with the impl inside of the DataProvider
     function _pricePerVaultShare() internal view override returns (uint256) {
         return _vault.convertToAssets(ONE);
     }

@@ -37,8 +37,8 @@ contract ERC4626Target0 is HyperdriveTarget0, ERC4626Base {
     ///      this in mind, we sweep the tokens to the fee collector address to
     ///      then redistribute to users.
     /// @dev WARN: It is unlikely but possible that there is a selector overlap
-    ///      with 'transferFrom'. Any integrating contracts should be checked
-    ///      for that, as it may result in an unexpected call from this address.
+    ///      with 'transfer'. Any integrating contracts should be checked for
+    ///      that, as it may result in an unexpected call from this address.
     /// @param _target The target token to sweep.
     function sweep(IERC20 _target) external {
         // Ensure that the sender is the fee collector or a pauser.

@@ -8,7 +8,9 @@ import { ERC4626Base } from "./ERC4626Base.sol";
 
 /// @author DELV
 /// @title ERC4626Target1
-/// @notice ERC4626Hyperdrive's target1 logic contract.
+/// @notice ERC4626Hyperdrive's target1 logic contract. This contract contains
+///         several stateful functions that couldn't fit into the Hyperdrive
+///         contract.
 /// @custom:disclaimer The language used in this code is for coding convenience
 ///                    only, and is not intended to, and does not, have any
 ///                    particular legal or regulatory significance.

@@ -58,7 +58,7 @@ abstract contract StETHBase is HyperdriveBase {
             // Submit the provided ether to Lido to be deposited. The fee
             // collector address is passed as the referral address; however,
             // users can specify whatever referrer they'd like by depositing
-            // stETH instead of WETH.
+            // stETH instead of ETH.
             shares = _lido.submit{ value: _amount }(_feeCollector);
         } else {
             // Refund any ether that was sent to the contract.

@@ -42,7 +42,7 @@ contract StETHTarget0 is HyperdriveTarget0, StETHBase {
             revert IHyperdrive.Unauthorized();
         }
 
-        // Ensure that thet target isn't the stETH token.
+        // Ensure that the target isn't the stETH token.
         if (address(_target) == address(_lido)) {
             revert IHyperdrive.UnsupportedToken();
         }

@@ -15,7 +15,8 @@ interface IHyperdriveGovernedRegistry {
     /// @param _governance The new governance address.
     function updateGovernance(address _governance) external;
 
-    /// @notice Allows governance set arbitrary info for a Hyperdrive instance.
+    /// @notice Allows governance to set arbitrary info for a Hyperdrive
+    ///         instance.
     /// @param _hyperdriveInstance The Hyperdrive instance address.
     /// @param _data The uint256 value to be set to convey information about the
     ///        instance.

@@ -31,6 +31,11 @@ interface IMultiTokenCore {
 
     /// @notice Allows a user to set an approval for an individual asset with
     ///         specific amount.
+    /// @param tokenID The asset to approve the use of.
+    /// @param operator The address who will be able to use the tokens.
+    /// @param amount The max tokens the approved person can use, setting to
+    ///        uint256.max will cause the value to never decrement (saving gas
+    ///        on transfer).
     function setApproval(
         uint256 tokenID,
         address operator,

@@ -7,16 +7,19 @@ interface IMultiTokenRead {
     function decimals() external view returns (uint8);
 
     /// @notice Gets the name of the MultiToken.
+    /// @param tokenId The sub-token ID.
     /// @return The name of the MultiToken.
-    function name(uint256 id) external view returns (string memory);
+    function name(uint256 tokenId) external view returns (string memory);
 
     /// @notice Gets the symbol of the MultiToken.
+    /// @param tokenId The sub-token ID.
     /// @return The symbol of the MultiToken.
-    function symbol(uint256 id) external view returns (string memory);
+    function symbol(uint256 tokenId) external view returns (string memory);
 
     /// @notice Gets the total supply of the MultiToken.
+    /// @param tokenId The sub-token ID.
     /// @return The total supply of the MultiToken.
-    function totalSupply(uint256 id) external view returns (uint256);
+    function totalSupply(uint256 tokenId) external view returns (uint256);
 
     /// @notice Gets the approval-for-all status of a spender on behalf of an
     ///         owner.

@@ -262,7 +262,7 @@ abstract contract HyperdriveBase is IHyperdriveEvents, HyperdriveStorage {
     }
 
     /// @dev Checks if any of the bonds the trader purchased on the curve
-    ///      were purchased above price of 1 base per bonds.
+    ///      were purchased above the price of 1 base per bonds.
     /// @param _shareCurveDelta The amount of shares the trader pays the curve.
     /// @param _bondCurveDelta The amount of bonds the trader receives from the
     ///        curve.
@@ -399,7 +399,7 @@ abstract contract HyperdriveBase is IHyperdriveEvents, HyperdriveStorage {
                 .divUp(_vaultSharePrice)
                 .toUint128();
 
-            // NOTE: Round down to underestimate the zombhie interest given to
+            // NOTE: Round down to underestimate the zombie interest given to
             // the LPs and governance.
             //
             // Calculate and collect the governance fee.
@@ -532,7 +532,7 @@ abstract contract HyperdriveBase is IHyperdriveEvents, HyperdriveStorage {
         // NOTE: Round down to underestimate the governance curve fee.
         //
         // We leave the governance fee in terms of bonds:
-        // governanceCurveFee = curve_fee * p * phi_gov
+        // governanceCurveFee = curve_fee * phi_gov
         //                    = bonds * phi_gov
         governanceCurveFee = curveFee.mulDown(_governanceLPFee);
     }
@@ -548,6 +548,8 @@ abstract contract HyperdriveBase is IHyperdriveEvents, HyperdriveStorage {
     /// @return flatFee The flat fee. The fee is in terms of shares.
     /// @return governanceCurveFee The curve fee that goes to governance. The
     ///         fee is in terms of shares.
+    /// @return totalGovernanceFee The total fee that goes to governance. The
+    ///         fee is in terms of shares.
     function _calculateFeesGivenBonds(
         uint256 _bondAmount,
         uint256 _normalizedTimeRemaining,

@@ -214,7 +214,7 @@ abstract contract HyperdriveLP is
             // The LP shares minted to the LP is derived by solving for the
             // change in LP shares that preserves the ratio of present value to
             // total LP shares. This ensures that LPs are fairly rewarded for
-            // adding liquidity.This is given by:
+            // adding liquidity. This is given by:
             //
             // PV0 / l0 = PV1 / (l0 + dl) => dl = ((PV1 - PV0) * l0) / PV0
             lpShares = (endingPresentValue - startingPresentValue).mulDivDown(

@@ -57,7 +57,7 @@ abstract contract HyperdriveLong is IHyperdriveEvents, HyperdriveLP {
             _options
         );
 
-        // Enforce the minimum user outputs and the mininum vault share price.
+        // Enforce the minimum user outputs and the minimum vault share price.
         //
         // NOTE: We use the value that is returned from the deposit to check
         // against the minimum transaction amount because in the event of

@@ -84,20 +84,20 @@ library AssetId {
 
     /// @dev Converts an asset ID to a token symbol.
     /// @param _id The asset ID.
-    /// @return _name The token symbol.
+    /// @return _symbol The token symbol.
     function assetIdToSymbol(
         uint256 _id
-    ) internal pure returns (string memory _name) {
+    ) internal pure returns (string memory _symbol) {
         (AssetIdPrefix prefix, uint256 timestamp) = decodeAssetId(_id);
         string memory _timestamp = toString(timestamp);
         if (prefix == AssetIdPrefix.LP) {
-            _name = "HYPERDRIVE-LP";
+            _symbol = "HYPERDRIVE-LP";
         } else if (prefix == AssetIdPrefix.Long) {
-            _name = string(abi.encodePacked("HYPERDRIVE-LONG:", _timestamp));
+            _symbol = string(abi.encodePacked("HYPERDRIVE-LONG:", _timestamp));
         } else if (prefix == AssetIdPrefix.Short) {
-            _name = string(abi.encodePacked("HYPERDRIVE-SHORT:", _timestamp));
+            _symbol = string(abi.encodePacked("HYPERDRIVE-SHORT:", _timestamp));
         } else if (prefix == AssetIdPrefix.WithdrawalShare) {
-            _name = "HYPERDRIVE-WS";
+            _symbol = "HYPERDRIVE-WS";
         }
     }
 

@@ -198,7 +198,8 @@ library FixedPointMath {
     }
 
     /// @dev Computes ln(x) in 1e18 fixed point.
-    /// @dev Reverts if x is negative
+    /// @dev Credit to Remco (https://github.com/recmo/experiment-solexp/blob/main/src/FixedPointMathLib.sol)
+    /// @dev Reverts if x is negative or zero.
     /// @param x Fixed point number in 1e18 format.
     /// @return r Result of ln(x).
     function ln(int256 x) internal pure returns (int256 r) {
@@ -212,6 +213,9 @@ library FixedPointMath {
             // ln(x * C) = ln(x) + ln(C), we can simply do nothing here
             // and add ln(2**96 / 10**18) at the end.
 
+            // This step inlines the `ilog2` call in Remco's implementation:
+            // https://github.com/recmo/experiment-solexp/blob/bbc164fb5ec078cfccf3c71b521605106bfae00b/src/FixedPointMathLib.sol#L57-L68
+            //
             /// @solidity memory-safe-assembly
             assembly {
                 r := shl(7, lt(0xffffffffffffffffffffffffffffffff, x))
@@ -224,7 +228,7 @@ library FixedPointMath {
                 r := or(r, lt(0x1, shr(r, x)))
             }
 
-            // Reduce range of x to (1, 2) * 2**96
+            // Reduce range of x to [1, 2) * 2**96
             // ln(2^k * x) = k * ln(2) + ln(x)
             int256 k = r - 96;
             x <<= uint256(159 - k);

@@ -442,7 +442,7 @@ library LPMath {
 
     /// @dev Calculates the amount of withdrawal shares that can be redeemed and
     ///      the share proceeds the withdrawal pool should receive given the
-    ///      pool's current idle liquidity. We use the following algorith to
+    ///      pool's current idle liquidity. We use the following algorithm to
     ///      ensure that the withdrawal pool receives the correct amount of
     ///      shares to (1) preserve the LP share price and (2) pay out as much
     ///      of the idle liquidity as possible to the withdrawal pool:
@@ -575,10 +575,10 @@ library LPMath {
         );
 
         // If the present value calculation failed or if the ending present
-        // value is greater than the starting present value, we short-circuit to
-        // avoid distributing excess idle. This edge-case can occur when the
-        // share reserves is very close to the minimum share reserves with a
-        // large value of k.
+        // value is greater than or equal to the starting present value, we
+        // short-circuit to avoid distributing excess idle. This edge-case can
+        // occur when the share reserves is very close to the minimum share
+        // reserves with a large value of k.
         if (!success || endingPresentValue >= _params.startingPresentValue) {
             return 0;
         }