From 374d4e6eb65a777f82bd4e8d6eebd56f9bd26ef1 Mon Sep 17 00:00:00 2001 From: Alex Towle Date: Thu, 29 Feb 2024 22:00:06 -0600 Subject: [PATCH 1/2] Made the documentation of the derivatives used in `LPMath` clearer --- contracts/src/libraries/LPMath.sol | 39 +++++++++++++++++++++--------- 1 file changed, 27 insertions(+), 12 deletions(-) diff --git a/contracts/src/libraries/LPMath.sol b/contracts/src/libraries/LPMath.sol index b893b179b..f5f58a005 100644 --- a/contracts/src/libraries/LPMath.sol +++ b/contracts/src/libraries/LPMath.sol @@ -711,8 +711,8 @@ library LPMath { ( derivative, success - ) = calculateSharesOutGivenBondsInDerivativeSafe( - params, + ) = calculateSharesOutGivenBondsInDerivativeNegationSafe( + _params, _originalEffectiveShareReserves, uint256(_params.netCurveTrade) ); @@ -1138,10 +1138,11 @@ library LPMath { return (maxShareReservesDelta, true); } - /// @dev Calculates the derivative of `calculateSharesOutGivenBondsIn`. This - /// derivative is given by: + /// @dev Calculates the negation of the derivative of + /// `calculateSharesOutGivenBondsIn`. The negation of the derivative is + /// given by: /// - /// derivative = - (1 - zeta / z) * ( + /// derivative = (1 - zeta / z) * ( /// 1 - (1 / c) * ( /// c * (mu * z_e(x)) ** -t_s + /// (y / z_e) * y(x) ** -t_s - @@ -1151,16 +1152,23 @@ library LPMath { /// ) ** (t_s / (1 - t_s)) /// ) /// - /// We round down to avoid overshooting the optimal solution in Newton's - /// method (the derivative we use is 1 minus this derivative so this - /// rounds the derivative up). + /// This quantity is used in Newton's method to search for the optimal + /// share proceeds. The derivative of the objective function F(x) is + /// given by: + /// + /// F'(x) = 1 - derivative + /// + /// With this in mind, this function rounds its result down so that + /// F'(x) is overestimated. Since F'(x) is in the denominator of + /// Newton's method, overestimating F'(x) helps to avoid overshooting + /// the optimal solution. /// @param _params The parameters for the calculation. /// @param _originalEffectiveShareReserves The original effective share /// reserves. /// @param _bondAmount The amount of bonds to sell. /// @return The derivative. /// @return A flag indicating whether the derivative could be computed. - function calculateSharesOutGivenBondsInDerivativeSafe( + function calculateSharesOutGivenBondsInDerivativeNegationSafe( DistributeExcessIdleParams memory _params, uint256 _originalEffectiveShareReserves, uint256 _bondAmount @@ -1288,9 +1296,16 @@ library LPMath { /// ) ** (t_s / (1 - t_s)) - 1 /// ) /// - /// We round down to avoid overshooting the optimal solution in - /// Newton's method (the derivative we use is 1 minus this derivative - /// so this rounds the derivative up). + /// This quantity is used in Newton's method to search for the optimal + /// share proceeds. The derivative of the objective function F(x) is + /// given by: + /// + /// F'(x) = 1 - derivative + /// + /// With this in mind, this function rounds its result down so that + /// F'(x) is overestimated. Since F'(x) is in the denominator of + /// Newton's method, overestimating F'(x) helps to avoid overshooting + /// the optimal solution. /// @param _params The parameters for the calculation. /// @param _originalEffectiveShareReserves The original effective share /// reserves. From eaaca796870f7e930f2d6de595c4772a35190abc Mon Sep 17 00:00:00 2001 From: Alex Towle Date: Tue, 5 Mar 2024 13:44:07 -0600 Subject: [PATCH 2/2] Addressed review feedback from @cmichel --- contracts/src/libraries/LPMath.sol | 18 ++++++++++++------ 1 file changed, 12 insertions(+), 6 deletions(-) diff --git a/contracts/src/libraries/LPMath.sol b/contracts/src/libraries/LPMath.sol index f5f58a005..954e48d74 100644 --- a/contracts/src/libraries/LPMath.sol +++ b/contracts/src/libraries/LPMath.sol @@ -1153,10 +1153,13 @@ library LPMath { /// ) /// /// This quantity is used in Newton's method to search for the optimal - /// share proceeds. The derivative of the objective function F(x) is - /// given by: + /// share proceeds. We can express the derivative of the objective + /// function F(x) by the derivative -z_out'(x) this function returns: /// - /// F'(x) = 1 - derivative + /// -F'(x) = l * -PV'(x) + /// = l * (1 - net_c'(x)) + /// = l * (1 + z_out'(x)) + /// = l * (1 - derivative) /// /// With this in mind, this function rounds its result down so that /// F'(x) is overestimated. Since F'(x) is in the denominator of @@ -1297,10 +1300,13 @@ library LPMath { /// ) /// /// This quantity is used in Newton's method to search for the optimal - /// share proceeds. The derivative of the objective function F(x) is - /// given by: + /// share proceeds. We can express the derivative of the objective + /// function F(x) by the derivative z_in'(x) this function returns: /// - /// F'(x) = 1 - derivative + /// -F'(x) = l * -PV'(x) + /// = l * (1 - net_c'(x)) + /// = l * (1 - z_in'(x)) + /// = l * (1 - derivative) /// /// With this in mind, this function rounds its result down so that /// F'(x) is overestimated. Since F'(x) is in the denominator of