AMM transactions & pathfinding

NotTEC AMMCreate::preflight(PreflightContext const& ctx)
{
    // 1. Check Amount != Amount2 (different currencies)
    if (ctx.tx[sfAmount] == ctx.tx[sfAmount2])
        return temBAD_AMM_TOKENS;

    // 2. Validate both amounts are positive
    if (ctx.tx[sfAmount] <= beast::kZero ||
        ctx.tx[sfAmount2] <= beast::kZero)
        return temBAD_AMOUNT;

    // 3. Check TradingFee range (0-1000)
    if (ctx.tx[sfTradingFee] > TRADING_FEE_THRESHOLD)
        return temBAD_FEE;

    return tesSUCCESS;
}

TER AMMCreate::preclaim(PreclaimContext const& ctx)
{
    // 1. Check AMM doesn't already exist
    if (ctx.view.read(keylet::amm(issue1, issue2)))
        return tecDUPLICATE;

    // 2. Validate account authorization for both assets
    // 3. Check neither asset is frozen
    // 4. Verify DefaultRipple is set on token issuers
    // 5. Check sufficient XRP reserve for trustlines
    // 6. Verify neither amount is an LP token
    // 7. Check no clawback enabled (unless featureAMMClawback)

    return tesSUCCESS;
}

TER AMMCreate::doApply()
{
    // 1. Create pseudo-account for AMM
    auto ammAccountID = calcAccountID(keylet::amm(...).key);

    // 2. Calculate initial LP tokens
    // LPT = sqrt(amount * amount2)
    auto const lpTokens = ammLPTokens(amount, amount2, lptIssue);

    // 3. Create ltAMM ledger entry
    auto sleAMM = std::make_shared<SLE>(keylet::amm(...));
    sleAMM->setFieldAmount(sfLPTokenBalance, lpTokens);
    sleAMM->setFieldU16(sfTradingFee, tradingFee);
    // ... set other fields

    // 4. Transfer assets from creator to AMM account
    // 5. Send LP tokens to creator
    // 6. Initialize vote slots and auction slot

    return tesSUCCESS;
}

// For tfLPToken flag (equal value from both assets)
TER AMMDeposit::doApply()
{
    // 1. Get current pool state
    auto const [asset1Balance, asset2Balance, lpBalance] = ammHolds(...);

    // 2. Calculate required deposits for requested LP tokens
    auto const ratio = lpTokensRequested / lpBalance;
    auto const deposit1 = asset1Balance * ratio;
    auto const deposit2 = asset2Balance * ratio;

    // 3. Transfer assets to AMM
    // 4. Mint LP tokens to depositor
    // 5. Update ltAMM.LPTokenBalance

    return tesSUCCESS;
}

// For tfSingleAsset flag (trading fee charged)
TER AMMDeposit::doApply()
{
    // 1. Get pool state and trading fee
    // 2. Calculate LP tokens using formula (with fee deduction)
    auto const lpTokens = lpTokensOut(
        assetBalance,
        lpBalance,
        depositAmount,
        tradingFee
    );

    // 3. Transfer single asset to AMM
    // 4. Mint calculated LP tokens
    // 5. Update pool state

    return tesSUCCESS;
}

TER AMMWithdraw::doApply()
{
    // 1. Calculate withdrawal amounts
    auto const ratio = lpTokensIn / lpBalance;
    auto const withdraw1 = asset1Balance * ratio;
    auto const withdraw2 = asset2Balance * ratio;

    // 2. Burn LP tokens
    // 3. Transfer assets from AMM to withdrawer
    // 4. Update ltAMM.LPTokenBalance

    // 5. If LP balance becomes 0, mark for deletion
    if (newLPBalance == 0)
        // Pool can be deleted with AMMDelete

    return tesSUCCESS;
}

TER AMMVote::doApply()
{
    // 1. Get voter's LP token balance
    auto const lpBalance = ammLPHolds(view, ammAccount, voterAccount);

    // 2. Calculate vote weight
    auto const weight = (lpBalance / totalLPTokens) * VOTE_WEIGHT_SCALE_FACTOR;

    // 3. Find or create vote slot
    if (existingSlot)
    {
        // Update existing vote
        slot.FeeVal = proposedFee;
        slot.VoteWeight = weight;
    }
    else if (voteSlots.size() < VOTE_MAX_SLOTS)
    {
        // Add new vote slot
        voteSlots.push_back({account, proposedFee, weight});
    }
    else
    {
        // Replace lowest weight vote if ours is higher
        auto minSlot = findMinWeightSlot(voteSlots);
        if (weight > minSlot.VoteWeight)
            *minSlot = {account, proposedFee, weight};
        else
            return tecAMM_FAILED;
    }

    // 4. Recalculate trading fee as weighted average
    uint32_t newFee = calculateWeightedFee(voteSlots);
    sleAMM->setFieldU16(sfTradingFee, newFee);

    return tesSUCCESS;
}

TER AMMBid::doApply()
{
    // 1. Calculate required bid based on slot state
    auto const minBid = calculateMinBid(
        currentSlot,
        timeRemaining,
        minSlotPrice
    );

    // 2. Determine actual bid (between BidMin and BidMax)
    auto const actualBid = std::clamp(minBid, bidMin, bidMax);

    // 3. Calculate refund to previous holder
    auto const refund = (1 - timeFractionUsed) * currentSlot.Price;

    // 4. Execute bid
    // - Transfer LP tokens from bidder
    // - Refund to previous holder
    // - Burn remaining (actualBid - refund)

    // 5. Update auction slot
    auctionSlot.Account = bidder;
    auctionSlot.Expiration = now + 24h;
    auctionSlot.DiscountedFee = 0;  // Usually 0 for slot holder
    auctionSlot.Price = actualBid;
    auctionSlot.AuthAccounts = authAccounts;

    return tesSUCCESS;
}

TER AMMDelete::preclaim(PreclaimContext const& ctx)
{
    // 1. Verify AMM exists
    // 2. Check LP token balance is 0
    if (sleAMM->getFieldAmount(sfLPTokenBalance) != beast::kZero)
        return tecAMM_NOT_EMPTY;

    return tesSUCCESS;
}

TER AMMDelete::doApply()
{
    // 1. Delete trustlines (limited per transaction)
    auto const maxTrustlines = ctx.view().rules().enabled(fixAMMv1_3)
        ? AMM_MAX_TRUSTLINES_DELETE_V3
        : AMM_MAX_TRUSTLINES_DELETE;

    auto deleted = deleteAMMTrustlines(view, ammAccount, maxTrustlines);

    // 2. If trustlines remain, return incomplete
    if (remainingTrustlines > 0)
        return tecINCOMPLETE;

    // 3. Delete ltAMM ledger entry
    view.erase(sleAMM);

    // 4. Delete pseudo-account
    view.erase(sleAMMAccount);

    return tesSUCCESS;
}

class AMMContext {
    AccountID account_;           // Transaction sender
    bool multiPath_;              // Using multiple paths?
    bool ammUsed_;               // AMM consumed this iteration?
    std::uint16_t ammIters_;     // AMM iteration counter

    constexpr static std::uint8_t MaxIterations = 30;

public:
    // Mark AMM offer as consumed
    void setAMMUsed() { ammUsed_ = true; }

    // Called after each iteration
    void update() {
        if (ammUsed_)
            ++ammIters_;
        ammUsed_ = false;  // Reset for next iteration
    }

    // Check iteration limit
    bool maxItersReached() const {
        return ammIters_ >= MaxIterations;
    }

    // Reset for new iteration
    void clear() { ammUsed_ = false; }
};

template <typename TIn, typename TOut>
class AMMLiquidity {
    AccountID ammAccountID_;
    std::uint32_t tradingFee_;
    Issue issueIn_;
    Issue issueOut_;
    TAmounts<TIn, TOut> initialBalances_;

public:
    // Get AMM offer for payment path
    std::optional<AMMOffer<TIn, TOut>>
    getOffer(ReadView const& view, AMMContext& ctx) const;

    // Fetch current pool balances
    TAmounts<TIn, TOut>
    fetchBalances(ReadView const& view) const;

    // Generate offer matching CLOB quality
    std::optional<TAmounts<TIn, TOut>>
    generateOfferForQuality(Quality const& quality) const;

    // Fibonacci sequence for multi-path
    std::optional<TAmounts<TIn, TOut>>
    generateFibSeqOffer(std::uint16_t iteration) const;
};

std::optional<AMMOffer<TIn, TOut>>
AMMLiquidity::getOffer(ReadView const& view, AMMContext& ctx) const
{
    // Get best CLOB offer quality
    auto const clobQuality = getBestCLOBQuality(view);

    // Generate AMM offer matching this quality
    auto const amounts = changeSpotPriceQuality(
        balances_,
        clobQuality,
        tradingFee_
    );

    if (!amounts)
        return std::nullopt;

    return AMMOffer<TIn, TOut>(*this, *amounts, balances_, quality);
}

std::optional<TAmounts<TIn, TOut>>
AMMLiquidity::generateFibSeqOffer(std::uint16_t iteration) const
{
    // Fibonacci fractions: 5/20000, 8/20000, 13/20000, 21/20000, ...
    static constexpr std::array<std::uint16_t, 10> fib = {
        5, 8, 13, 21, 34, 55, 89, 144, 233, 377
    };

    auto const fraction = Number(fib[iteration]) / 20000;
    auto const offerIn = balances_.in * fraction;
    auto const offerOut = swapAssetIn(balances_, offerIn, tradingFee_);

    return TAmounts{offerIn, offerOut};
}

template <typename TIn, typename TOut>
class AMMOffer {
    AMMLiquidity<TIn, TOut> const& ammLiquidity_;
    TAmounts<TIn, TOut> amounts_;      // Offer amounts
    TAmounts<TIn, TOut> balances_;     // Current pool balances
    Quality quality_;                   // Spot price quality
    bool consumed_;                     // Has been consumed?

public:
    // Get offer quality (exchange rate)
    Quality quality() const { return quality_; }

    // Limit output to specific amount
    void limitOut(TOut const& limit);

    // Limit input to specific amount
    void limitIn(TIn const& limit);

    // Apply offer to AMM pool
    void consume();

    // Verify pool invariant after trade
    bool checkInvariant() const;
};

void AMMOffer::limitOut(TOut const& limit)
{
    if (limit < amounts_.out)
    {
        // Recalculate input for limited output
        amounts_.in = swapAssetOut(balances_, limit, tradingFee_);
        amounts_.out = limit;
    }
}

void AMMOffer::limitIn(TIn const& limit)
{
    if (limit < amounts_.in)
    {
        // Recalculate output for limited input
        amounts_.out = swapAssetIn(balances_, limit, tradingFee_);
        amounts_.in = limit;
    }
}

std::pair<TAmounts, bool>
BookStep::compute(
    PaymentSandbox& view,
    AMMContext& ammContext,
    ...)
{
    // 1. Get CLOB offers
    auto clobOffers = getOrderBookOffers(view);

    // 2. Get AMM offer (if available)
    auto ammOffer = ammLiquidity_.getOffer(view, ammContext);

    // 3. Interleave based on quality
    while (hasOffers())
    {
        // Compare qualities
        auto const clobQuality = clobOffers.front().quality();
        auto const ammQuality = ammOffer ? ammOffer->quality() : Quality{0};

        if (ammQuality >= clobQuality && ammOffer)
        {
            // Use AMM offer (better or equal quality)
            consumeAMMOffer(*ammOffer, ammContext);

            // Generate new AMM offer for remaining
            ammOffer = ammLiquidity_.getOffer(view, ammContext);
        }
        else
        {
            // Use CLOB offer
            consumeCLOBOffer(clobOffers.front());
            clobOffers.pop_front();
        }
    }

    return {totalConsumed, success};
}

Iteration 1:
  - CLOB offer: 5,000 XRP @ 2.00
  - AMM offer: Generated to match 2.00 quality
  - Result: Split between both at equal quality

Iteration 2:
  - CLOB offer: 3,000 XRP @ 1.98
  - AMM offer: New quality after iteration 1
  - Result: CLOB wins (better quality)

Iteration 3:
  - Remaining: ~2,000 XRP
  - AMM fills remainder at current pool quality

Total: 10,000 XRP -> ~19,800 USD
(Blend of CLOB and AMM liquidity)