System XLS: AMM Pool Discovery

[JibreelMuhammad]

Canonical draft (kept current): https://github.com/JibreelMuhammad/xls-drafts/blob/main/XLS-AMM-Pool-Discovery.md

Posting at the Proposal stage per XLS-1; no XLS number is requested yet (an Editor assigns it at PR time). Feedback welcome before I open a PR.

---

  title: AMM Pool Discovery
  description: A read-only amm_pools API method to enumerate and filter AMM pools without prior knowledge of the asset pair.
  author: Jibreel Muhammad
  category: System
  status: Proposal
  requires: 30
  created: 2026-06-20
  updated: 2026-06-20

System XLS: AMM Pool Discovery

1. Abstract

This standard adds a read-only public API method, amm_pools, that enumerates Automated Market Maker (AMM) pools and supports filtering and pagination. It introduces no new ledger entries, no new fields on existing entries, and no new transactions, and therefore requires no amendment — it is a core server (rippled/Clio) feature over state that already exists.

Today, amm_info returns details for a pool whose asset pair the caller already knows. There is no protocol-level way to answer the inverse question — "what pools exist?" — without scanning the entire ledger or relying on third-party indexers. amm_pools closes that gap.

2. Motivation

The AMM (XLS-30), and the proposed AMM Swappable Curves work (which adds multiple pools per pair keyed by curve type), both assume the caller can already locate a pool. Discovery is a blind spot:

• amm_info requires the answer in advance: it takes asset + asset2 (or amm_account) and returns one known pool. It cannot list pools, filter by a single asset, or find recently created pools.
• The only native alternative is a full ledger_data scan filtered by entry type amm — expensive and impractical for most clients, and it returns raw entries rather than a queryable, filterable list.
• As a result, discovery is pushed off-ledger: traders, treasuries, and analytics tools rely on third-party indexers to answer "which pools exist and which have liquidity," recreating off-chain a capability the ledger already has the data to serve.

Concrete needs this blocks: routing/best-execution across multiple curve pools for a pair; treasury and custody enumeration; market-oversight (detecting thin pools, comparing spreads); and the basic wallet/frontend primitive "show me all pools for asset X."

3. Specification

3.1. Method: amm_pools

A new read-only public API method (WebSocket and JSON-RPC) that enumerates AMM pools, optionally filtered, with cursor-based pagination.

3.1.1. Request Fields

Field Name	Required?	JSON Type	Description
asset	No	object	Filter to pools that include this asset. { currency, issuer? }; XRP omits issuer.
asset2	No	object	Filter to pools including this second asset. With asset, matches the exact pair.
curve_type	No	number	Filter to a single curve type. Requires the Swappable Curves feature; ignored otherwise.
with_liquidity	No	boolean	When true, return only pools with LPTokenBalance > 0. Default false.
limit	No	number	Page size. Default 50, maximum 200.
marker	No	string	Opaque continuation token from a previous response.
ledger_index / ledger_hash	No	string / number	Ledger to query. Default validated.

Filtering semantics: no asset/asset2 enumerates all pools; asset only returns all pools containing that asset; asset + asset2 returns all pools for that exact pair (one per curve type). Asset ordering is normalized server-side, so callers need not order the pair.

3.1.2. Response Fields

Field Name	Always Present?	JSON Type	Description
pools	Yes	array	Matching pools (see element fields below).
marker	No	string	Present only when more results exist.
ledger_index	Yes	number	Ledger queried.
validated	Yes	boolean	Whether the ledger is validated.

Each element of pools:

Field Name	Always Present?	JSON Type	Description
amm_account	Yes	string	The pool's pseudo-account address.
pool_id	Yes	string	The pool's ledger-entry key (hex).
asset	Yes	object	First asset (canonical order).
asset2	Yes	object	Second asset (canonical order).
curve_type	Conditional	number	Present when the Swappable Curves feature is enabled.
trading_fee	Yes	number	Pool trading fee, in units of 1/100,000.
lp_token	Yes	object	{ currency, issuer, value }; value is total supply.
amount	Yes	string/object	Current reserve of asset.
amount2	Yes	string/object	Current reserve of asset2.

amm_pools returns summary/identity data for discovery and routing. For full per-pool detail (vote slots, auction slot, etc.), callers follow up with amm_info using the returned amm_account.

3.1.3. Failure Conditions

Code	Condition
invalidParams	A field is malformed, or curve_type is out of range.
actNotFound	An issuer/account referenced in asset/asset2 does not exist.
lgrNotFound	The requested ledger is not available on this server.

An empty pools array (not an error) is returned when the filters match no pools.

3.1.4. Example Request

{
  "command": "amm_pools",
  "asset": { "currency": "USD", "issuer": "rISSUER..." },
  "with_liquidity": true,
  "limit": 100,
  "ledger_index": "validated"
}

3.1.5. Example Response

{
  "result": {
    "pools": [
      {
        "amm_account": "rAMM1...",
        "pool_id": "9F3C...",
        "asset":  { "currency": "XRP" },
        "asset2": { "currency": "USD", "issuer": "rISSUER..." },
        "curve_type": 0,
        "trading_fee": 500,
        "lp_token": { "currency": "03A...", "issuer": "rAMM1...", "value": "1000000" },
        "amount":  "5000000000",
        "amount2": { "currency": "USD", "issuer": "rISSUER...", "value": "5000" }
      }
    ],
    "marker": "A1B2...",
    "ledger_index": 12345,
    "validated": true
  }
}

4. Rationale

Why an API method rather than new ledger state. All data needed for discovery already lives in ltAMM entries; the missing piece is retrieval, not storage. Keeping this off-ledger means zero state growth, no migration, and no amendment vote — the lowest-risk path to the capability.

Why mirror existing methods. The request/response shape, limit/marker pagination, and ledger_index selector follow account_objects and book_offers, so the method is familiar to implementers and clients.

Why summary fields only. Returning identity + reserves + fee keeps each page light and lets amm_pools (discovery) compose cleanly with amm_info (detail) instead of duplicating it.

Alternate designs considered. (1) Adding discovery metadata fields (name, tags, status) to ltAMM: rejected here because it bloats every pool and is a separable concern — it belongs in its own proposal. (2) A new PermissionedDomain-style registry ledger object listing pools: rejected as redundant, since the pools already exist as ledger entries and only need to be queryable. (3) Relying on third-party indexers (status quo): rejected because it fragments a capability the ledger can serve consistently and verifiably.

5. Test Plan

• Enumerate with no filter on a ledger with N pools; verify all are returned across paged requests and that marker round-trips.
• Filter by asset only; verify every returned pool contains that asset and none are omitted.
• Filter by asset + asset2; verify exactly the pools for that pair (one per curve type when Swappable Curves is enabled).
• with_liquidity: true excludes zero-reserve pools; false/absent includes them.
• limit boundary tests (1, default, max 200, >200 clamped); marker continuation produces no duplicates or gaps.
• Error cases: malformed asset, nonexistent issuer (actNotFound), unavailable ledger (lgrNotFound), out-of-range curve_type (invalidParams).
• Determinism: results for a fixed validated ledger are stable across calls and across rippled/Clio.

6. Security Considerations

Denial-of-service / cost. Enumeration is the main abuse surface. Mitigations: a hard limit cap (200), mandatory cursor pagination, and read-only/idempotent execution. Servers should treat amm_pools like other large read methods (ledger_data, account_objects) for rate-limiting, and may restrict unfiltered full enumeration to admin connections.

No new write surface. The method cannot modify state; it adds no transaction and no authorization path.

Index/consensus consistency. Any server-side AMM index is a derived cache of validated ledger state; results MUST reflect the requested validated ledger and never report pools absent from it.

Privacy. Pools are already public ledger state; serving them via a query reveals nothing a full ledger scan would not.

7. Appendix

7.1. FAQ

Should the response include TVL or 24h volume? TVL is derivable from reserves at query time; rolling volume is not stored on-ledger and would require server-side aggregation. Recommendation: keep volume out of this method (define it where aggregation already happens, e.g. Clio analytics); treat TVL as optional/derived.

Public or admin-only enumeration? Unfiltered enumeration is the heaviest call. Servers may serve it publicly with strict paging and rate limits, or restrict the no-filter case to admin connections by policy.

Sort order. Keyspace order is cheapest and pagination-stable. A sort option (e.g. by reserves) can be added later without breaking changes.

[mvadari]

The only native alternative is a full ledger_data scan filtered by entry type amm — expensive and impractical for most clients, and it returns raw entries rather than a queryable, filterable list.

Wouldn't this RPC basically be doing the same thing under the hood, thereby still being "expensive and impractical" (perhaps moreso since that effort would now be hidden within rippled)?