Amendment XLS: AMM Invalid State Recovery and Settlement

[shortthefomo]

xls: xx
title: AMM Invalid State Recovery and Settlement
description: Extends the LedgerStateFix transaction type to support recovery and settlement of AMMs that have entered an invalid state, returning remaining assets to liquidity providers.  author: Lathan @shortthefomo
status: Draft
category: Amendment
created: 2026-05-27

Abstract

This proposal extends the existing LedgerStateFix transaction to handle Automated Market Makers (AMMs) on the XRP Ledger that enter an invalid state. When triggered on a qualifying AMM, the pool is closed and any remaining locked tokens are proportionally returned to liquidity providers (LP token holders).

Motivation

The current AMM implementation (XLS-30) lacks a built-in recovery path for inconsistent or broken states caused by bugs, extreme edge cases, or future protocol changes. This can lead to permanent liquidity lockup. Leveraging the existing LedgerStateFix framework provides a recovery mechanism without introducing a new transaction type.

With further optionality to AMM on the horizon there should at least be a way to clean these up.

Real-World Examples of Invalid AMM States

Pathfinding operations for example for ever trip over this invariant pools when looking for routes. Even though the path find operations complete because they are sandboxed the logs are littered for example.

Throwing exception of type xrpl::FlowException: An internal error has occurred during processing.
 0# xrpl::logThrow(std::__1::basic_string<char, std::__1::char_traits<char>, std::__1::allocator<char>> const&) in /xrpld
 1# void xrpl::Throw<xrpl::FlowException, xrpl::TERSubset<xrpl::CanCvtToTER> const&>(xrpl::TERSubset<xrpl::CanCvtToTER> const&) in /xrpld
 2# void xrpl::BookStep<xrpl::IOUAmount, xrpl::XRPAmount, xrpl::BookPaymentStep<xrpl::IOUAmount, xrpl::XRPAmount>>::consumeOffer<xrpl::AMMOffer>(xrpl::PaymentSandbox&, xrpl::AMMOffer<xrpl::IOUAmount, xrpl::XRPAmount>&, xrpl::TAmounts<xrpl::IOUAmount, xrpl::XRPAmount> const&, xrpl::TAmounts<xrpl::IOUAmount, xrpl::XRPAmount> const&, xrpl::XRPAmount const&) const in /xrpld
 3# bool xrpl::BookStep<xrpl::IOUAmount, xrpl::XRPAmount, xrpl::BookPaymentStep<xrpl::IOUAmount, xrpl::XRPAmount>>::fwdImp(xrpl::PaymentSandbox&, xrpl::ApplyView&, boost::container::flat_set<xrpl::BaseUInt<256ul, void>, std::__1::less<xrpl::BaseUInt<256ul, void>>, void>&, xrpl::IOUAmount const&)::'lambda'(auto&, xrpl::TAmounts<xrpl::IOUAmount, xrpl::XRPAmount> const&, xrpl::TAmounts<xrpl::IOUAmount, xrpl::XRPAmount> const&, xrpl::XRPAmount const&, unsigned int, unsigned int)::operator()<xrpl::AMMOffer<xrpl::IOUAmount, xrpl::XRPAmount>>(auto&, xrpl::TAmounts<xrpl::IOUAmount, xrpl::XRPAmount> const&, xrpl::TAmounts<xrpl::IOUAmount, xrpl::XRPAmount> const&, xrpl::XRPAmount const&, unsigned int, unsigned int) in /xrpld
 4# auto std::__1::pair<boost::container::flat_set<xrpl::BaseUInt<256ul, void>, std::__1::less<xrpl::BaseUInt<256ul, void>>, void>, unsigned int> xrpl::BookStep<xrpl::IOUAmount, xrpl::XRPAmount, xrpl::BookPaymentStep<xrpl::IOUAmount, xrpl::XRPAmount>>::forEachOffer<xrpl::BookStep<xrpl::IOUAmount, xrpl::XRPAmount, xrpl::BookPaymentStep<xrpl::IOUAmount, xrpl::XRPAmount>>::fwdImp(xrpl::PaymentSandbox&, xrpl::ApplyView&, boost::container::flat_set<xrpl::BaseUInt<256ul, void>, std::__1::less<xrpl::BaseUInt<256ul, void>>, void>&, xrpl::IOUAmount const&)::'lambda'(auto&, xrpl::TAmounts<xrpl::IOUAmount, xrpl::XRPAmount> const&, xrpl::TAmounts<xrpl::IOUAmount, xrpl::XRPAmount> const&, xrpl::XRPAmount const&, unsigned int, unsigned int)>(xrpl::PaymentSandbox&, xrpl::ApplyView&, xrpl::DebtDirection, auto&) const::'lambda'(auto&)::operator()<xrpl::AMMOffer<xrpl::IOUAmount, xrpl::XRPAmount>>(auto&) const in /xrpld
 5# std::__1::pair<boost::container::flat_set<xrpl::BaseUInt<256ul, void>, std::__1::less<xrpl::BaseUInt<256ul, void>>, void>, unsigned int> xrpl::BookStep<xrpl::IOUAmount, xrpl::XRPAmount, xrpl::BookPaymentStep<xrpl::IOUAmount, xrpl::XRPAmount>>::forEachOffer<xrpl::BookStep<xrpl::IOUAmount, xrpl::XRPAmount, xrpl::BookPaymentStep<xrpl::IOUAmount, xrpl::XRPAmount>>::fwdImp(xrpl::PaymentSandbox&, xrpl::ApplyView&, boost::container::flat_set<xrpl::BaseUInt<256ul, void>, std::__1::less<xrpl::BaseUInt<256ul, void>>, void>&, xrpl::IOUAmount const&)::'lambda'(auto&, xrpl::TAmounts<xrpl::IOUAmount, xrpl::XRPAmount> const&, xrpl::TAmounts<xrpl::IOUAmount, xrpl::XRPAmount> const&, xrpl::XRPAmount const&, unsigned int, unsigned int)>(xrpl::PaymentSandbox&, xrpl::ApplyView&, xrpl::DebtDirection, auto&) const in /xrpld
 6# xrpl::BookStep<xrpl::IOUAmount, xrpl::XRPAmount, xrpl::BookPaymentStep<xrpl::IOUAmount, xrpl::XRPAmount>>::fwdImp(xrpl::PaymentSandbox&, xrpl::ApplyView&, boost::container::flat_set<xrpl::BaseUInt<256ul, void>, std::__1::less<xrpl::BaseUInt<256ul, void>>, void>&, xrpl::IOUAmount const&) in /xrpld
 7# xrpl::StepImp<xrpl::IOUAmount, xrpl::XRPAmount, xrpl::BookStep<xrpl::IOUAmount, xrpl::XRPAmount, xrpl::BookPaymentStep<xrpl::IOUAmount, xrpl::XRPAmount>>>::fwd(xrpl::PaymentSandbox&, xrpl::ApplyView&, boost::container::flat_set<xrpl::BaseUInt<256ul, void>, std::__1::less<xrpl::BaseUInt<256ul, void>>, void>&, xrpl::EitherAmount const&) in /xrpld
 8# xrpl::StrandResult<xrpl::IOUAmount, xrpl::XRPAmount> xrpl::flow<xrpl::IOUAmount, xrpl::XRPAmount>(xrpl::PaymentSandbox const&, std::__1::vector<std::__1::unique_ptr<xrpl::Step, std::__1::default_delete<xrpl::Step>>, std::__1::allocator<std::__1::unique_ptr<xrpl::Step, std::__1::default_delete<xrpl::Step>>>> const&, std::__1::optional<xrpl::IOUAmount> const&, xrpl::XRPAmount const&, beast::Journal) in /xrpld
 9# xrpl::FlowResult<xrpl::IOUAmount, xrpl::XRPAmount> xrpl::flow<xrpl::IOUAmount, xrpl::XRPAmount>(xrpl::PaymentSandbox const&, std::__1::vector<std::__1::vector<std::__1::unique_ptr<xrpl::Step, std::__1::default_delete<xrpl::Step>>, std::__1::allocator<std::__1::unique_ptr<xrpl::Step, std::__1::default_delete<xrpl::Step>>>>, std::__1::allocator<std::__1::vector<std::__1::unique_ptr<xrpl::Step, std::__1::default_delete<xrpl::Step>>, std::__1::allocator<std::__1::unique_ptr<xrpl::Step, std::__1::default_delete<xrpl::Step>>>>>> const&, xrpl::XRPAmount const&, bool, xrpl::OfferCrossing, std::__1::optional<xrpl::Quality> const&, std::__1::optional<xrpl::STAmount> const&, beast::Journal, xrpl::AMMContext&, xrpl::path::detail::FlowDebugInfo*) in /xrpld
10# decltype(auto) std::__1::__variant_detail::__visitation::__base::__dispatcher<1ul, 0ul>::__dispatch[abi:ne200100]<std::__1::__variant_detail::__visitation::__variant::__value_visitor<xrpl::flow(xrpl::PaymentSandbox&, xrpl::STAmount const&, xrpl::BaseUInt<160ul, xrpl::detail::AccountIDTag> const&, xrpl::BaseUInt<160ul, xrpl::detail::AccountIDTag> const&, xrpl::STPathSet const&, bool, bool, bool, xrpl::OfferCrossing, std::__1::optional<xrpl::Quality> const&, std::__1::optional<xrpl::STAmount> const&, std::__1::optional<xrpl::BaseUInt<256ul, void>> const&, beast::Journal, xrpl::path::detail::FlowDebugInfo*)::$_1>&&, std::__1::__variant_detail::__base<(std::__1::__variant_detail::_Trait)0, xrpl::AmountType<xrpl::XRPAmount>, xrpl::AmountType<xrpl::IOUAmount>, xrpl::AmountType<xrpl::MPTAmount>>&&, std::__1::__variant_detail::__base<(std::__1::__variant_detail::_Trait)0, xrpl::AmountType<xrpl::XRPAmount>, xrpl::AmountType<xrpl::IOUAmount>, xrpl::AmountType<xrpl::MPTAmount>>&&>(std::__1::__variant_detail::__visitation::__variant::__value_visitor<xrpl::flow(xrpl::PaymentSandbox&, xrpl::STAmount const&, xrpl::BaseUInt<160ul, xrpl::detail::AccountIDTag> const&, xrpl::BaseUInt<160ul, xrpl::detail::AccountIDTag> const&, xrpl::STPathSet const&, bool, bool, bool, xrpl::OfferCrossing, std::__1::optional<xrpl::Quality> const&, std::__1::optional<xrpl::STAmount> const&, std::__1::optional<xrpl::BaseUInt<256ul, void>> const&, beast::Journal, xrpl::path::detail::FlowDebugInfo*)::$_1>&&, std::__1::__variant_detail::__base<(std::__1::__variant_detail::_Trait)0, xrpl::AmountType<xrpl::XRPAmount>, xrpl::AmountType<xrpl::IOUAmount>, xrpl::AmountType<xrpl::MPTAmount>>&&, std::__1::__variant_detail::__base<(std::__1::__variant_detail::_Trait)0, xrpl::AmountType<xrpl::XRPAmount>, xrpl::AmountType<xrpl::IOUAmount>, xrpl::AmountType<xrpl::MPTAmount>>&&) in /xrpld
11# xrpl::flow(xrpl::PaymentSandbox&, xrpl::STAmount const&, xrpl::BaseUInt<160ul, xrpl::detail::AccountIDTag> const&, xrpl::BaseUInt<160ul, xrpl::detail::AccountIDTag> const&, xrpl::STPathSet const&, bool, bool, bool, xrpl::OfferCrossing, std::__1::optional<xrpl::Quality> const&, std::__1::optional<xrpl::STAmount> const&, std::__1::optional<xrpl::BaseUInt<256ul, void>> const&, beast::Journal, xrpl::path::detail::FlowDebugInfo*) in /xrpld
12# xrpl::path::RippleCalc::rippleCalculate(xrpl::PaymentSandbox&, xrpl::STAmount const&, xrpl::STAmount const&, xrpl::BaseUInt<160ul, xrpl::detail::AccountIDTag> const&, xrpl::BaseUInt<160ul, xrpl::detail::AccountIDTag> const&, xrpl::STPathSet const&, std::__1::optional<xrpl::BaseUInt<256ul, void>> const&, xrpl::ServiceRegistry&, xrpl::path::RippleCalc::Input const*) in /xrpld
13# xrpl::Pathfinder::getPathLiquidity(xrpl::STPath const&, xrpl::STAmount const&, xrpl::STAmount&, unsigned long long&) const in /xrpld
14# xrpl::Pathfinder::rankPaths(int, xrpl::STPathSet const&, std::__1::vector<xrpl::Pathfinder::PathRank, std::__1::allocator<xrpl::Pathfinder::PathRank>>&, std::__1::function<bool ()> const&) in /xrpld
15# xrpl::Pathfinder::computePathRanks(int, std::__1::function<bool ()> const&) in /xrpld
16# xrpl::PathRequest::getPathFinder(std::__1::shared_ptr<xrpl::AssetCache> const&, std::__1::unordered_map<xrpl::PathAsset, std::__1::unique_ptr<xrpl::Pathfinder, std::__1::default_delete<xrpl::Pathfinder>>, beast::Uhash<beast::Xxhasher>, std::__1::equal_to<xrpl::PathAsset>, std::__1::allocator<std::__1::pair<xrpl::PathAsset const, std::__1::unique_ptr<xrpl::Pathfinder, std::__1::default_delete<xrpl::Pathfinder>>>>>&, xrpl::PathAsset const&, xrpl::STAmount const&, int, std::__1::function<bool ()> const&) in /xrpld
17# xrpl::PathRequest::findPaths(std::__1::shared_ptr<xrpl::AssetCache> const&, int, json::Value&, std::__1::function<bool ()> const&) in /xrpld
18# xrpl::PathRequest::doUpdate(std::__1::shared_ptr<xrpl::AssetCache> const&, bool, std::__1::function<bool ()> const&) in /xrpld
19# xrpl::PathRequestManager::updateAll(std::__1::shared_ptr<xrpl::ReadView const> const&) in /xrpld
20# xrpl::LedgerMaster::updatePaths() in /xrpld
21# xrpl::Job::doJob() in /xrpld
22# xrpl::JobQueue::processTask(int) in /xrpld
23# xrpl::Workers::Worker::run() in /xrpld
24# void* std::__1::__thread_proxy[abi:ne200100]<std::__1::tuple<std::__1::unique_ptr<std::__1::__thread_struct, std::__1::default_delete<std::__1::__thread_struct>>, void (xrpl::Workers::Worker::*)(), xrpl::Workers::Worker*>>(void*) in /xrpld
25# _pthread_start in /usr/lib/system/libsystem_pthread.dylib

Example 1: Drained Pool + Invariant Violation (March 2024 Bug)
One of the earliest AMM pools (USD.rvYA / USD.rhub) was impacted by a multi-path payment bug.

Example 2: Fully Drained One-Sided Pool (EUR.rhub / SeagullCash.rNHe)
Another pool hit by the same bug:

• An OfferCreate transaction (using auto-bridging) completely drained one side of the pool.

These pools still exist today and cause these errors/warnings depending how you classify that in the logs today.

Specification

1. Invalid State Definition

An AMM is considered to be in an invalid state if any of the following conditions are met:

• One or both asset balances are negative.
• The LP token supply is inconsistent with the pool composition.
• The AMM ledger object or its associated AccountRoot is missing or corrupted.
• Internal invariants are broken (e.g., division by zero in ratio calculations with non-zero assets).
• Any other protocol-defined consistency checks fail.

2. LedgerStateFix Extension

TransactionType: LedgerStateFix (existing)

New LedgerFixType

Add a new LedgerFixType value for AMM recovery:

• Proposed value: 3 (assuming values 1 and 2 are already allocated to prior fixes)

Additional Fields (when LedgerFixType = 3):

Field	Required	Type	Description
Asset	Yes	Object	Definition of one asset in the AMM pool (XRP, IOU, or MPT)
Asset2	Yes	Object	Definition of the other asset in the AMM pool

Behavior (LedgerFixType = 3)

1. Locate the target AMM using the Asset + Asset2 pair.
2. Verify the AMM is in an invalid state. If not, return tecAMM_NOT_INVALID.
3. Calculate each LP token holder's proportional share of the remaining pool assets.
4. Distribute Asset1 and Asset2 proportionally based on LP token balances.
5. Burn all outstanding LP tokens.
6. Delete the AMM ledger object, associated AccountRoot, and related trust lines (processed in batches if necessary).
7. Emit appropriate metadata for indexing and tracking.

If trust line cleanup exceeds transaction limits, return tecINCOMPLETE (similar to AMMDelete).

3. Error Codes

• tecAMM_NOT_INVALID — The specified AMM is not in an invalid state.
• tecAMM_INVALID_STATE — Returned by all standard AMM transactions when the pool is invalid. Users should use LedgerStateFix instead.
• tecINSUFFICIENT_BALANCE — Defensive error during distribution.

4. Changes to Existing Components

• AMM Transactions: AMMDeposit, AMMWithdraw, AMMBid, AMMDelete, etc. must return tecAMM_INVALID_STATE if the pool is invalid.
• RPC Method: amm_info should return two new fields:
  • InvalidState (boolean)
  • InvalidStateReason (optional string)

5. Proportional Distribution

For each LP holder with LP balance L_i and total LP supply L:

• Share of Asset A = (L_i / L) × Balance_A
• Share of Asset B = (L_i / L) × Balance_B

Distributions are performed using standard payment primitives. Any dust amounts below the minimum transfer threshold may be burned or sent to the account that triggered the settlement.

Implementation Considerations

• Backward Compatibility: Fully backward compatible. Only impacts AMMs in invalid states.
• Security: Strong validation enforced. Malicious or incorrect triggers on healthy pools are rejected.
• Fee: Higher base fee recommended due to potentially expensive cleanup operations.
• Automation: Future amendments may allow automatic application of this LedgerFixType upon detection of invalid state.
• Rationale for LedgerStateFix: Reuses the established ledger repair framework, avoids transaction type proliferation, and maintains protocol cleanliness.

Rationale

• Protects liquidity providers from permanent capital loss.
• Maintains decentralization — any account can trigger recovery on a broken AMM.
• Builds upon existing LedgerStateFix logic.
• Aligns with the intended purpose of LedgerStateFix for exceptional state corrections.

[mDuo13]

I'm supportive of the idea of cleaning up ledger corruption, but I have some concerns with this fix as described:

• It can cause liquidity providers to hold tokens they aren't currently holding, which has effects like increasing their reserve unexpectedly. This goes against the principles of the XRPL design.
  • A mitigating factor is that the user's LP Token trust line will be removed at the same time, so in the case where one asset is fully drained, creating a new trust line to hold one liquidated asset means their total reserve requirement should go net even.
• There are a lot of edge cases that can stop normal payments from completing; if any of those across any LP can fail this transaction, it seems like it would be pretty likely that the fix can't be applied. I'm talking about cases like:
  • If some LPs have frozen trust lines for the returned asset(s)
  • If LPs don't have authorization to hold the asset (I believe you can do a single-asset deposit to an AMM even if the other asset in the AMM requires auth that you don't have)
  • If receiving the holdings would put an LP over their trust line limit