Pathfinding Integration

Back to AMM: Automated Market Maker

---

Introduction

One of XRPL's unique features is the deep integration between AMM pools and the pathfinding engine. Unlike other blockchains where AMM and order book liquidity are separate, XRPL's pathfinding engine can route payments through both CLOB offers and AMM pools, automatically selecting the best execution path.

This chapter explores how AMM offers are generated, how they compete with CLOB offers, and the algorithms that ensure optimal payment routing.

Architecture Overview

Dual Liquidity Model

┌─────────────────────────────────────────────────────────────┐
│                    Payment Request                          │
│                 (Source -> Destination)                     │
└─────────────────────────┬───────────────────────────────────┘
                          │
                          ▼
┌─────────────────────────────────────────────────────────────┐
│                  Pathfinding Engine                         │
│                                                             │
│   ┌───────────────────┐       ┌───────────────────┐         │
│   │   Order Book      │       │    AMM Pool       │         │
│   │   (CLOB)          │       │   (Synthetic)     │         │
│   │                   │       │                   │         │
│   │  Offer 1: 2.00    │       │  Quality: 2.05    │         │
│   │  Offer 2: 2.01    │       │  (calculated)     │         │
│   │  Offer 3: 2.02    │       │                   │         │
│   └─────────┬─────────┘       └─────────┬─────────┘         │
│             │                           │                   │
│             └───────────┬───────────────┘                   │
│                         │                                   │
│                         ▼                                   │
│              ┌─────────────────────┐                        │
│              │  Best Execution     │                        │
│              │  Path Selection     │                        │
│              └─────────────────────┘                        │
└─────────────────────────────────────────────────────────────┘

Key Components

Component	Location	Purpose
AMMLiquidity	src/xrpld/app/paths/AMMLiquidity.cpp	Generate synthetic offers
AMMOffer	src/xrpld/app/paths/AMMOffer.cpp	Represent AMM offers
AMMContext	src/xrpld/app/paths/AMMContext.h	Track AMM state during payment
BookStep	src/xrpld/app/paths/impl/BookStep.cpp	Integrate AMM with order book

AMMContext: State Management

The AMMContext class tracks AMM usage during payment execution.

Location: src/xrpld/app/paths/AMMContext.h

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; }
};

Iteration Limit

The 30-iteration limit prevents:

• Infinite loops in complex path finding

• Excessive computation for large payments

• Potential DoS through pathfinding abuse

AMMLiquidity: Offer Generation

The AMMLiquidity class generates synthetic offers from AMM pools.

Location: src/xrpld/app/paths/AMMLiquidity.cpp

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;
};

Offer Generation Strategies

Single Path Mode

When processing a single payment path, AMM offers are sized to match CLOB quality:

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);
}

Multi-Path Mode

For payments using multiple paths, Fibonacci sequence sizing prevents over-concentration:

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};
}

AMMOffer: Synthetic Offer Representation

The AMMOffer class represents an AMM-backed offer in the pathfinding system. Unlike CLOB offers which are stored on the ledger, AMMOffers are created dynamically during payment execution.

Location: src/xrpld/app/paths/AMMOffer.cpp

When Are AMMOffers Created?

AMMOffers are not ledger objects - they are synthetic, ephemeral offers generated on-the-fly:

┌─────────────────────────────────────────────────────────────────┐
│                    AMMOffer Lifecycle                           │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│  1. Payment Request                                             │
│         │                                                       │
│         ▼                                                       │
│  2. BookStep processes order book for currency pair             │
│         │                                                       │
│         ▼                                                       │
│  3. AMMLiquidity::getOffer() called                             │
│     ┌─────────────────────────────────────────────────────┐     │
│     │ - Reads current pool balances from ltAMM            │     │
│     │ - Looks at best CLOB offer quality                  │     │
│     │ - Calculates AMM offer to match/beat that quality   │     │
│     │ - Creates NEW AMMOffer object (in memory only!)     │     │
│     └─────────────────────────────────────────────────────┘     │
│         │                                                       │
│         ▼                                                       │
│  4. AMMOffer competes with CLOB offers on quality               │
│         │                                                       │
│         ▼                                                       │
│  5. If AMM wins: AMMOffer::consume() applies the swap           │
│     - Pool balances updated in sandbox                          │
│     - AMMOffer marked as consumed                               │
│         │                                                       │
│         ▼                                                       │
│  6. New AMMOffer generated for remaining payment (if any)       │
│     - Fresh calculation with updated pool balances              │
│     - Cycle repeats until payment complete or max iterations    │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘

Key Insight: AMMOffers Are Ephemeral

CLOB Offer	AMMOffer
Stored on ledger	Created in memory
Persists until filled/cancelled	Exists only during payment execution
Has explicit size	Size calculated dynamically
Fixed quality	Quality adapts to pool state
Created by OfferCreate tx	Created by AMMLiquidity::getOffer()

How AMMOffers Are Sized

The size of an AMMOffer depends on the context:

Single-Path Mode:

// Match the best CLOB quality
auto amounts = changeSpotPriceQuality(pool, clobQuality, fee);
// AMMOffer is sized so that AFTER the trade,
// the pool's new spot price equals the CLOB quality

Multi-Path Mode:

// Use Fibonacci sequence to avoid over-consumption
// Iteration 0: 5/20000 of pool (0.025%)
// Iteration 1: 8/20000 of pool (0.04%)
// Iteration 2: 13/20000 of pool (0.065%)
// ... growing offers ensure gradual consumption

Structure

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;
};

Quality Calculation

Quality AMMOffer::quality() const
{
    // Quality = out / in (how much you get per unit spent)
    return Quality(amounts_.out / amounts_.in);
}

Limiting Offers

When the payment doesn't need the full offer:

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;
    }
}

Consuming Offers

void AMMOffer::consume()
{
    // Mark as consumed
    consumed_ = true;

    // Update balances (for next iteration)
    balances_.in += amounts_.in;
    balances_.out -= amounts_.out;

    // Verify invariant
    assert(checkInvariant());
}

Integration with BookStep

The BookStep class handles order book traversal, including AMM integration.

Location: src/xrpld/app/paths/impl/BookStep.cpp

Processing Order

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};
}

Quality Competition

AMM and CLOB offers compete purely on quality (exchange rate):

If AMM quality >= CLOB quality:
    Use AMM offer
Else:
    Use CLOB offer

This ensures best execution regardless of liquidity source.

Multi-Path Payment Example

Scenario

Payment: 10,000 XRP -> USD Available liquidity:

• CLOB: 5,000 XRP @ 2.00 USD/XRP

• CLOB: 3,000 XRP @ 1.98 USD/XRP

• AMM Pool: 100,000 XRP / 200,000 USD (spot: 2.00)

Execution

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)

Flow Diagram

┌─────────────────────────────────────────────────────────────┐
│                    Payment Flow                             │
└─────────────────────────┬───────────────────────────────────┘
                          │
                          ▼
              ┌─────────────────────┐
              │  BookStep::compute  │
              └──────────┬──────────┘
                         │
           ┌─────────────┴─────────────┐
           │                           │
           ▼                           ▼
┌────────────────────┐     ┌────────────────────┐
│  Get CLOB Offers   │     │  Get AMM Offer     │
│  from OrderBook    │     │  from AMMLiquidity │
└─────────┬──────────┘     └─────────┬──────────┘
          │                          │
          └────────────┬─────────────┘
                       │
                       ▼
              ┌─────────────────────┐
              │  Compare Qualities  │
              │  AMM vs CLOB        │
              └──────────┬──────────┘
                         │
         ┌───────────────┴───────────────┐
         │                               │
         ▼                               ▼
┌─────────────────┐            ┌─────────────────┐
│  AMM Better?    │            │  CLOB Better?   │
│  Consume AMM    │            │  Consume CLOB   │
│  Update Context │            │  Next Offer     │
└────────┬────────┘            └────────┬────────┘
         │                              │
         └──────────────┬───────────────┘
                        │
                        ▼
               ┌─────────────────┐
               │  More to Pay?   │
               │  Continue Loop  │
               └─────────────────┘

Performance Considerations

Iteration Limits

// Maximum AMM iterations per payment
constexpr std::uint8_t MaxIterations = 30;

Why 30?

• Balances payment quality with computation cost

• Prevents pathfinding abuse

• Sufficient for most payment sizes

Quality Caching

// Cache quality calculations to avoid recomputation
Quality cachedQuality_;
bool qualityValid_ = false;

Quality getQuality() {
    if (!qualityValid_) {
        cachedQuality_ = computeQuality();
        qualityValid_ = true;
    }
    return cachedQuality_;
}

Balance Snapshots

// Snapshot balances at start to avoid repeated ledger reads
TAmounts<TIn, TOut> initialBalances_;

AMMLiquidity(...) {
    initialBalances_ = fetchBalances(view);
}

Edge Cases

Empty AMM Pool

if (balances_.in == 0 || balances_.out == 0)
    return std::nullopt;  // No offer available

Iteration Limit Reached

if (ammContext.maxItersReached())
    return std::nullopt;  // Stop using AMM

Quality Worse Than CLOB

if (ammQuality < minAcceptableQuality)
    return std::nullopt;  // Skip AMM for this path

Debugging Tips

Tracing AMM Offers

Enable detailed logging:

JLOG(j_.trace()) << "AMM offer: "
    << "in=" << amounts_.in
    << " out=" << amounts_.out
    << " quality=" << quality_;

Verifying Integration

Check that AMM is being considered:

# In rippled logs
grep "AMM offer" debug.log

Testing Quality Competition

Create test scenarios with known CLOB and AMM qualities to verify correct selection.

Summary

The AMM pathfinding integration enables:

1. Best Execution: Automatic selection between AMM and CLOB

2. Seamless Liquidity: Users don't need to know liquidity source

3. Fair Competition: Quality-based selection ensures best rates

4. Bounded Computation: Iteration limits prevent abuse

5. Multi-Path Support: Fibonacci sizing for complex payments

This integration is unique to XRPL and provides significant advantages over systems where AMM and order book liquidity are separate.

References to Source Code

• src/xrpld/app/paths/AMMLiquidity.cpp - Offer generation

• src/xrpld/app/paths/AMMOffer.cpp - Offer representation

• src/xrpld/app/paths/AMMContext.h - State management

• src/xrpld/app/paths/impl/BookStep.cpp - Integration point

• src/xrpld/app/misc/AMMHelpers.h - Quality calculations

Cross-References

• AMM Architecture - Pool structure

• AMM Logic - Quality and swap formulas

• Module 02: Transaction Lifecycle - Payment flow