AMMHelpers.h

#pragma once
 
#include <xrpl/basics/Log.h>
#include <xrpl/basics/Number.h>
#include <xrpl/basics/contract.h>
#include <xrpl/beast/utility/Journal.h>
#include <xrpl/beast/utility/Zero.h>
#include <xrpl/ledger/ApplyView.h>
#include <xrpl/ledger/ReadView.h>
#include <xrpl/ledger/Sandbox.h>
#include <xrpl/ledger/helpers/TokenHelpers.h>
#include <xrpl/protocol/AMMCore.h>
#include <xrpl/protocol/AccountID.h>
#include <xrpl/protocol/AmountConversions.h>
#include <xrpl/protocol/Asset.h>
#include <xrpl/protocol/Feature.h>
#include <xrpl/protocol/IOUAmount.h>
#include <xrpl/protocol/Issue.h>
#include <xrpl/protocol/MPTAmount.h>
#include <xrpl/protocol/Quality.h>
#include <xrpl/protocol/Rules.h>
#include <xrpl/protocol/STAmount.h>
#include <xrpl/protocol/STLedgerEntry.h>
#include <xrpl/protocol/TER.h>
#include <xrpl/protocol/XRPAmount.h>
 
#include <algorithm>
#include <cstdint>
#include <expected>
#include <functional>
#include <optional>
#include <stdexcept>
#include <tuple>
#include <utility>
 
namespace xrpl {
 
namespace detail {
 
Number
reduceOffer(auto const& amount)
{
    static Number const kReducedOfferPct(9999, -4);
 
    // Make sure the result is always less than amount or zero.
    NumberRoundModeGuard const mg(Number::RoundingMode::TowardsZero);
    return amount * kReducedOfferPct;
}
 
}  // namespace detail
 
enum class IsDeposit : bool { No = false, Yes = true };
 
inline Number const kAMMInvariantRelativeTolerance{1, -11};

STAmount
ammLPTokens(STAmount const& asset1, STAmount const& asset2, Asset const& lptIssue);

STAmount
lpTokensOut(
    STAmount const& asset1Balance,
    STAmount const& asset1Deposit,
    STAmount const& lptAMMBalance,
    std::uint16_t tfee);

STAmount
ammAssetIn(
    STAmount const& asset1Balance,
    STAmount const& lptAMMBalance,
    STAmount const& lpTokens,
    std::uint16_t tfee);

STAmount
lpTokensIn(
    STAmount const& asset1Balance,
    STAmount const& asset1Withdraw,
    STAmount const& lptAMMBalance,
    std::uint16_t tfee);

STAmount
ammAssetOut(
    STAmount const& assetBalance,
    STAmount const& lptAMMBalance,
    STAmount const& lpTokens,
    std::uint16_t tfee);

inline bool
withinRelativeDistance(Quality const& calcQuality, Quality const& reqQuality, Number const& dist)
{
    if (calcQuality == reqQuality)
        return true;
    auto const [min, max] = std::minmax(calcQuality, reqQuality);
    // Relative distance is (max - min)/max. Can't use basic operations
    // on Quality. Have to use Quality::rate() instead, which
    // is inverse of quality: (1/max.rate - 1/min.rate)/(1/max.rate)
    return ((min.rate() - max.rate()) / min.rate()) < dist;
}

template <typename Amt>
    requires(
        std::is_same_v<Amt, STAmount> || std::is_same_v<Amt, IOUAmount> ||
        std::is_same_v<Amt, XRPAmount> || std::is_same_v<Amt, MPTAmount> ||
        std::is_same_v<Amt, Number>)
bool
withinRelativeDistance(Amt const& calc, Amt const& req, Number const& dist)
{
    if (calc == req)
        return true;
    auto const [min, max] = std::minmax(calc, req);
    return ((max - min) / max) < dist;
}

std::optional<Number>
solveQuadraticEqSmallest(Number const& a, Number const& b, Number const& c);

template <typename TIn, typename TOut>
std::optional<TAmounts<TIn, TOut>>
getAMMOfferStartWithTakerGets(
    TAmounts<TIn, TOut> const& pool,
    Quality const& targetQuality,
    std::uint16_t const& tfee)
{
    if (targetQuality.rate() == beast::kZero)
        return std::nullopt;
 
    NumberRoundModeGuard const mg(Number::RoundingMode::ToNearest);
    auto const f = feeMult(tfee);
    auto const a = 1;
    auto const b = pool.in * (1 - 1 / f) / targetQuality.rate() - 2 * pool.out;
    auto const c = pool.out * pool.out - (pool.in * pool.out) / targetQuality.rate();
 
    auto nTakerGets = solveQuadraticEqSmallest(a, b, c);
    if (!nTakerGets || *nTakerGets <= 0)
        return std::nullopt;  // LCOV_EXCL_LINE
 
    auto const nTakerGetsConstraint = pool.out - pool.in / (targetQuality.rate() * f);
    if (nTakerGetsConstraint <= 0)
        return std::nullopt;
 
    // Select the smallest to maximize the quality
    if (nTakerGetsConstraint < *nTakerGets)
        nTakerGets = nTakerGetsConstraint;
 
    auto getAmounts = [&pool, &tfee](Number const& nTakerGetsProposed) {
        // Round downward to minimize the offer and to maximize the quality.
        // This has the most impact when takerGets is integral.
        auto const takerGets =
            toAmount<TOut>(getAsset(pool.out), nTakerGetsProposed, Number::RoundingMode::Downward);
        return TAmounts<TIn, TOut>{swapAssetOut(pool, takerGets, tfee), takerGets};
    };
 
    // Try to reduce the offer size to improve the quality.
    // The quality might still not match the targetQuality for a tiny offer.
    auto amounts = getAmounts(*nTakerGets);
    if (Quality{amounts} < targetQuality)
        return getAmounts(detail::reduceOffer(amounts.out));
    return amounts;
}

template <typename TIn, typename TOut>
std::optional<TAmounts<TIn, TOut>>
getAMMOfferStartWithTakerPays(
    TAmounts<TIn, TOut> const& pool,
    Quality const& targetQuality,
    std::uint16_t tfee)
{
    if (targetQuality.rate() == beast::kZero)
        return std::nullopt;
 
    NumberRoundModeGuard const mg(Number::RoundingMode::ToNearest);
    auto const f = feeMult(tfee);
    auto const& a = f;
    auto const b = pool.in * (1 + f);
    auto const c = pool.in * pool.in - pool.in * pool.out * targetQuality.rate();
 
    auto nTakerPays = solveQuadraticEqSmallest(a, b, c);
    if (!nTakerPays || nTakerPays <= 0)
        return std::nullopt;  // LCOV_EXCL_LINE
 
    auto const nTakerPaysConstraint = pool.out * targetQuality.rate() - pool.in / f;
    if (nTakerPaysConstraint <= 0)
        return std::nullopt;
 
    // Select the smallest to maximize the quality
    if (nTakerPaysConstraint < *nTakerPays)
        nTakerPays = nTakerPaysConstraint;
 
    auto getAmounts = [&pool, &tfee](Number const& nTakerPaysProposed) {
        // Round downward to minimize the offer and to maximize the quality.
        // This has the most impact when takerPays is integral.
        auto const takerPays =
            toAmount<TIn>(getAsset(pool.in), nTakerPaysProposed, Number::RoundingMode::Downward);
        return TAmounts<TIn, TOut>{takerPays, swapAssetIn(pool, takerPays, tfee)};
    };
 
    // Try to reduce the offer size to improve the quality.
    // The quality might still not match the targetQuality for a tiny offer.
    auto amounts = getAmounts(*nTakerPays);
    if (Quality{amounts} < targetQuality)
        return getAmounts(detail::reduceOffer(amounts.in));
    return amounts;
}

template <typename TIn, typename TOut>
std::optional<TAmounts<TIn, TOut>>
changeSpotPriceQuality(
    TAmounts<TIn, TOut> const& pool,
    Quality const& quality,
    std::uint16_t tfee,
    Rules const& rules,
    beast::Journal j)
{
    if (!rules.enabled(fixAMMv1_1))
    {
        // Finds takerPays (i) and takerGets (o) such that given pool
        // composition poolGets(I) and poolPays(O): (O - o) / (I + i) = quality.
        // Where takerGets is calculated as the swapAssetIn (see below).
        // The above equation produces the quadratic equation:
        // i^2*(1-fee) + i*I*(2-fee) + I^2 - I*O/quality,
        // which is solved for i, and o is found with swapAssetIn().
        auto const f = feeMult(tfee);  // 1 - fee
        auto const& a = f;
        auto const b = pool.in * (1 + f);
        Number const c = pool.in * pool.in - pool.in * pool.out * quality.rate();
        auto const res = b * b - 4 * a * c;
        if (res < 0)
        {
            return std::nullopt;  // LCOV_EXCL_LINE
        }
        if (auto const nTakerPaysPropose = (-b + root2(res)) / (2 * a); nTakerPaysPropose > 0)
        {
            auto const nTakerPays = [&]() {
                // The fee might make the AMM offer quality less than CLOB
                // quality. Therefore, AMM offer has to satisfy this constraint:
                // o / i >= q. Substituting o with swapAssetIn() gives: i <= O /
                // q - I / (1 - fee).
                auto const nTakerPaysConstraint = pool.out * quality.rate() - pool.in / f;
                if (nTakerPaysPropose > nTakerPaysConstraint)
                    return nTakerPaysConstraint;
                return nTakerPaysPropose;
            }();
            if (nTakerPays <= 0)
            {
                JLOG(j.trace()) << "changeSpotPriceQuality calc failed: " << to_string(pool.in)
                                << " " << to_string(pool.out) << " " << quality << " " << tfee;
                return std::nullopt;
            }
            auto const takerPays =
                toAmount<TIn>(getAsset(pool.in), nTakerPays, Number::RoundingMode::Upward);
            // should not fail
            if (auto amounts = TAmounts<TIn, TOut>{takerPays, swapAssetIn(pool, takerPays, tfee)};
                Quality{amounts} < quality &&
                !withinRelativeDistance(Quality{amounts}, quality, Number(1, -7)))
            {
                JLOG(j.error()) << "changeSpotPriceQuality failed: " << to_string(pool.in) << " "
                                << to_string(pool.out) << " "
                                << " " << quality << " " << tfee << " " << to_string(amounts.in)
                                << " " << to_string(amounts.out);
                Throw<std::runtime_error>("changeSpotPriceQuality failed");
            }
            else
            {
                JLOG(j.trace()) << "changeSpotPriceQuality succeeded: " << to_string(pool.in) << " "
                                << to_string(pool.out) << " "
                                << " " << quality << " " << tfee << " " << to_string(amounts.in)
                                << " " << to_string(amounts.out);
                return amounts;
            }
        }
        JLOG(j.trace()) << "changeSpotPriceQuality calc failed: " << to_string(pool.in) << " "
                        << to_string(pool.out) << " " << quality << " " << tfee;
        return std::nullopt;
    }
 
    auto amounts = [&]() {
        bool const inIntegral = getAsset(pool.in).integral();
        bool const outIntegral = getAsset(pool.out).integral();
 
        // Preserve historical behavior for fractional pairs and XRP/IOU-style
        // one-integral-side pairs. For two integral assets, pick the side whose
        // minimum unit is economically coarser at this quality.
        //
        // Quality::rate() is input units per output unit, so one output unit is
        // coarser when it costs at least one input unit. Ties use takerGets,
        // matching the historical XRP-output behavior.
        if (outIntegral && (!inIntegral || Number(quality.rate()) >= 1))
            return getAMMOfferStartWithTakerGets(pool, quality, tfee);
        return getAMMOfferStartWithTakerPays(pool, quality, tfee);
    }();
    if (!amounts)
    {
        JLOG(j.trace()) << "changeSpotPrice calc failed: " << to_string(pool.in) << " "
                        << to_string(pool.out) << " " << quality << " " << tfee;
        return std::nullopt;
    }
 
    if (Quality{*amounts} < quality)
    {
        JLOG(j.error()) << "changeSpotPriceQuality failed: " << to_string(pool.in) << " "
                        << to_string(pool.out) << " " << quality << " " << tfee << " "
                        << to_string(amounts->in) << " " << to_string(amounts->out);
        return std::nullopt;
    }
 
    JLOG(j.trace()) << "changeSpotPriceQuality succeeded: " << to_string(pool.in) << " "
                    << to_string(pool.out) << " "
                    << " " << quality << " " << tfee << " " << to_string(amounts->in) << " "
                    << to_string(amounts->out);
 
    return amounts;
}


template <typename TIn, typename TOut>
TOut
swapAssetIn(TAmounts<TIn, TOut> const& pool, TIn const& assetIn, std::uint16_t tfee)
{
    if (auto const& rules = getCurrentTransactionRules(); rules && rules->enabled(fixAMMv1_1))
    {
        // set rounding to always favor the amm. Clip to zero.
        // calculate:
        // pool.out -
        // (pool.in * pool.out) / (pool.in + assetIn * feeMult(tfee)),
        // and explicitly set the rounding modes
        // Favoring the amm means we should:
        // minimize:
        // pool.out -
        // (pool.in * pool.out) / (pool.in + assetIn * feeMult(tfee)),
        // maximize:
        // (pool.in * pool.out) / (pool.in + assetIn * feeMult(tfee)),
        // (pool.in * pool.out)
        // minimize:
        // (pool.in + assetIn * feeMult(tfee)),
        // minimize:
        // assetIn * feeMult(tfee)
        // feeMult is: (1-fee), fee is tfee/100000
        // minimize:
        // 1-fee
        // maximize:
        // fee
        SaveNumberRoundMode const _{Number::getround()};
 
        Number::setround(Number::RoundingMode::Upward);
        auto const numerator = pool.in * pool.out;
        auto const fee = getFee(tfee);
 
        Number::setround(Number::RoundingMode::Downward);
        auto const denom = pool.in + assetIn * (1 - fee);
 
        if (denom.signum() <= 0)
            return toAmount<TOut>(getAsset(pool.out), 0);
 
        Number::setround(Number::RoundingMode::Upward);
        auto const ratio = numerator / denom;
 
        Number::setround(Number::RoundingMode::Downward);
        auto const swapOut = pool.out - ratio;
 
        if (swapOut.signum() < 0)
            return toAmount<TOut>(getAsset(pool.out), 0);
 
        return toAmount<TOut>(getAsset(pool.out), swapOut, Number::RoundingMode::Downward);
    }
 
    return toAmount<TOut>(
        getAsset(pool.out),
        pool.out - (pool.in * pool.out) / (pool.in + assetIn * feeMult(tfee)),
        Number::RoundingMode::Downward);
}

template <typename TIn, typename TOut>
TIn
swapAssetOut(TAmounts<TIn, TOut> const& pool, TOut const& assetOut, std::uint16_t tfee)
{
    if (auto const& rules = getCurrentTransactionRules(); rules && rules->enabled(fixAMMv1_1))
    {
        // set rounding to always favor the amm. Clip to zero.
        // calculate:
        // ((pool.in * pool.out) / (pool.out - assetOut) - pool.in) /
        // (1-tfee/100000)
        // maximize:
        // ((pool.in * pool.out) / (pool.out - assetOut) - pool.in)
        // maximize:
        // (pool.in * pool.out) / (pool.out - assetOut)
        // maximize:
        // (pool.in * pool.out)
        // minimize
        // (pool.out - assetOut)
        // minimize:
        // (1-tfee/100000)
        // maximize:
        // tfee/100000
 
        SaveNumberRoundMode const _{Number::getround()};
 
        Number::setround(Number::RoundingMode::Upward);
        auto const numerator = pool.in * pool.out;
 
        Number::setround(Number::RoundingMode::Downward);
        auto const denom = pool.out - assetOut;
        if (denom.signum() <= 0)
        {
            return toMaxAmount<TIn>(getAsset(pool.in));
        }
 
        Number::setround(Number::RoundingMode::Upward);
        auto const ratio = numerator / denom;
        auto const numerator2 = ratio - pool.in;
        auto const fee = getFee(tfee);
 
        Number::setround(Number::RoundingMode::Downward);
        auto const feeMult = 1 - fee;
 
        Number::setround(Number::RoundingMode::Upward);
        auto const swapIn = numerator2 / feeMult;
        if (swapIn.signum() < 0)
            return toAmount<TIn>(getAsset(pool.in), 0);
 
        return toAmount<TIn>(getAsset(pool.in), swapIn, Number::RoundingMode::Upward);
    }
 
    return toAmount<TIn>(
        getAsset(pool.in),
        ((pool.in * pool.out) / (pool.out - assetOut) - pool.in) / feeMult(tfee),
        Number::RoundingMode::Upward);
}

Number
square(Number const& n);

STAmount
adjustLPTokens(STAmount const& lptAMMBalance, STAmount const& lpTokens, IsDeposit isDeposit);

std::tuple<STAmount, std::optional<STAmount>, STAmount>
adjustAmountsByLPTokens(
    STAmount const& amountBalance,
    STAmount const& amount,
    std::optional<STAmount> const& amount2,
    STAmount const& lptAMMBalance,
    STAmount const& lpTokens,
    std::uint16_t tfee,
    IsDeposit isDeposit);

Number
solveQuadraticEq(Number const& a, Number const& b, Number const& c);
 
STAmount
multiply(STAmount const& amount, Number const& frac, Number::RoundingMode rm);
 
namespace detail {
 
inline Number::RoundingMode
getLPTokenRounding(IsDeposit isDeposit)
{
    // Minimize on deposit, maximize on withdraw to ensure
    // AMM invariant sqrt(poolAsset1 * poolAsset2) >= LPTokensBalance
    return isDeposit == IsDeposit::Yes ? Number::RoundingMode::Downward
                                       : Number::RoundingMode::Upward;
}
 
inline Number::RoundingMode
getAssetRounding(IsDeposit isDeposit)
{
    // Maximize on deposit, minimize on withdraw to ensure
    // AMM invariant sqrt(poolAsset1 * poolAsset2) >= LPTokensBalance
    return isDeposit == IsDeposit::Yes ? Number::RoundingMode::Upward
                                       : Number::RoundingMode::Downward;
}
 
}  // namespace detail

template <typename A>
STAmount
getRoundedAsset(Rules const& rules, STAmount const& balance, A const& frac, IsDeposit isDeposit)
{
    if (!rules.enabled(fixAMMv1_3))
    {
        if constexpr (std::is_same_v<A, STAmount>)
        {
            return multiply(balance, frac, balance.asset());
        }
        else
        {
            return toSTAmount(balance.asset(), balance * frac);
        }
    }
    auto const rm = detail::getAssetRounding(isDeposit);
    return multiply(balance, frac, rm);
}

STAmount
getRoundedAsset(
    Rules const& rules,
    std::function<Number()> const& noRoundCb,
    STAmount const& balance,
    std::function<Number()> const& productCb,
    IsDeposit isDeposit);

STAmount
getRoundedLPTokens(
    Rules const& rules,
    STAmount const& balance,
    Number const& frac,
    IsDeposit isDeposit);

STAmount
getRoundedLPTokens(
    Rules const& rules,
    std::function<Number()> const& noRoundCb,
    STAmount const& lptAMMBalance,
    std::function<Number()> const& productCb,
    IsDeposit isDeposit);
 
/* Next two functions adjust asset in/out amount to factor in the adjusted
 * lptokens. The lptokens are calculated from the asset in/out. The lptokens are
 * then adjusted to factor in the loss in precision. The adjusted lptokens might
 * be less than the initially calculated tokens. Therefore, the asset in/out
 * must be adjusted. The rounding might result in the adjusted amount being
 * greater than the original asset in/out amount. If this happens,
 * then the original amount is reduced by the difference in the adjusted amount
 * and the original amount. The actual tokens and the actual adjusted amount
 * are then recalculated. The minimum of the original and the actual
 * adjusted amount is returned.
 */
std::pair<STAmount, STAmount>
adjustAssetInByTokens(
    Rules const& rules,
    STAmount const& balance,
    STAmount const& amount,
    STAmount const& lptAMMBalance,
    STAmount const& tokens,
    std::uint16_t tfee);
std::pair<STAmount, STAmount>
adjustAssetOutByTokens(
    Rules const& rules,
    STAmount const& balance,
    STAmount const& amount,
    STAmount const& lptAMMBalance,
    STAmount const& tokens,
    std::uint16_t tfee);

Number
adjustFracByTokens(
    Rules const& rules,
    STAmount const& lptAMMBalance,
    STAmount const& tokens,
    Number const& frac);

std::pair<STAmount, STAmount>
ammPoolHolds(
    ReadView const& view,
    AccountID const& ammAccountID,
    Asset const& asset1,
    Asset const& asset2,
    FreezeHandling freezeHandling,
    AuthHandling authHandling,
    beast::Journal const j);

TER
checkAMMPrecisionLoss(Number const& poolProductMean, STAmount const& newLPTokenBalance);

TER
checkAMMPrecisionLoss(
    ReadView const& view,
    AccountID const& ammAccountID,
    Asset const& asset1,
    Asset const& asset2,
    STAmount const& newLPTokenBalance,
    beast::Journal const j);

std::expected<std::tuple<STAmount, STAmount, STAmount>, TER>
ammHolds(
    ReadView const& view,
    SLE const& ammSle,
    std::optional<Asset> const& optAsset1,
    std::optional<Asset> const& optAsset2,
    FreezeHandling freezeHandling,
    AuthHandling authHandling,
    beast::Journal const j);

STAmount
ammLPHolds(
    ReadView const& view,
    Asset const& asset1,
    Asset const& asset2,
    AccountID const& ammAccount,
    AccountID const& lpAccount,
    beast::Journal const j);
 
STAmount
ammLPHolds(
    ReadView const& view,
    SLE const& ammSle,
    AccountID const& lpAccount,
    beast::Journal const j);

std::uint16_t
getTradingFee(ReadView const& view, SLE const& ammSle, AccountID const& account);

STAmount
ammAccountHolds(ReadView const& view, AccountID const& ammAccountID, Asset const& asset);

TER
deleteAMMAccount(Sandbox& view, Asset const& asset, Asset const& asset2, beast::Journal j);

void
initializeFeeAuctionVote(
    ApplyView& view,
    SLE::pointer& ammSle,
    AccountID const& account,
    Asset const& lptAsset,
    std::uint16_t tfee);

std::expected<bool, TER>
isOnlyLiquidityProvider(ReadView const& view, Issue const& ammIssue, AccountID const& lpAccount);

std::expected<bool, TER>
verifyAndAdjustLPTokenBalance(
    Sandbox& sb,
    STAmount const& lpTokens,
    SLE::pointer& ammSle,
    AccountID const& account);
 
}  // namespace xrpl