Skip to content

Spearbit #55: Clarified the documentation of the derivatives used in LPMath #811

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 2 commits into from
Mar 6, 2024
Merged

Spearbit #55: Clarified the documentation of the derivatives used in LPMath #811

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
374d4e6
Made the documentation of the derivatives used in `LPMath` clearer
jalextowle Mar 1, 2024
eaaca79
Addressed review feedback from @cmichel
jalextowle Mar 5, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
45 changes: 33 additions & 12 deletions contracts/src/libraries/LPMath.sol
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -711,8 +711,8 @@ library LPMath {
(
derivative,
success
) = calculateSharesOutGivenBondsInDerivativeSafe(
params,
) = calculateSharesOutGivenBondsInDerivativeNegationSafe(
_params,
_originalEffectiveShareReserves,
uint256(_params.netCurveTrade)
);
Expand Down Expand Up @@ -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 -
Expand All @@ -1151,16 +1152,26 @@ 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. We can express the derivative of the objective
/// function F(x) by the derivative -z_out'(x) this function returns:
///
/// -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
/// 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
Expand Down Expand Up @@ -1288,9 +1299,19 @@ 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. We can express the derivative of the objective
/// function F(x) by the derivative z_in'(x) this function returns:
///
/// -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
/// 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.
Expand Down