Amendment XLS: Permissioned AMM

[JibreelMuhammad]

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

Related: System XLS: AMM Pool Discovery (#565).

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: Permissioned AMM
  description: Pool-level, domain-based access control for the XRPL AMM, gating liquidity, withdrawal, governance, and optionally swaps.
  author: Jibreel Muhammad
  category: Amendment
  status: Proposal
  requires: 30, 70, 80
  created: 2026-06-20
  updated: 2026-06-20

Amendment XLS: Permissioned AMM

1. Abstract

This amendment adds optional, pool-level access control to the XRP Ledger's native AMM (XLS-30), reusing the credential and domain machinery from Credentials (XLS-70) and Permissioned Domains (XLS-80). An AMM pool may reference a Permissioned Domain, after which AMM-specific market actions — providing liquidity, withdrawing liquidity, voting on the trading fee, and bidding for the auction slot — require the acting account to be a member of that domain. Swaps may remain public or be gated as well, mirroring the hybrid model of Permissioned DEX (XLS-81).

Where Permissioned DEX gates the order-book primitive ("who may place and take offers in this domain"), Permissioned AMM gates the pool primitive ("who may enter, fund, withdraw from, and govern this specific pool"), using the AMM ledger object as the market identity. The two are complementary controls over the two different market engines the XRPL already recognizes.

2. Introduction

2.1. Terminology

• Pool / AMM object: the ltAMM ledger entry created by AMMCreate.
• Domain: a PermissionedDomain ledger entry (XLS-80) defined by a set of accepted credentials.
• Member: an account holding a valid, accepted, unexpired credential that the domain accepts (XLS-70).
• Gated action: an AMM action that requires domain membership when the corresponding permission flag is set.

2.2. Summary

• Serialized Types: none introduced.
• Ledger Entries: ltAMM modified (adds sfDomainID, sfAssetDomain, sfAsset2Domain, sfPoolPermissions). No new entry type; reuses the existing PermissionedDomain membership test.
• Transactions: AMMCreate, AMMDeposit, AMMWithdraw, AMMVote, AMMBid modified; AMM swap routing modified.
• API: none required (existing amm_info returns the new fields).

2.3. Relationship to Permissioned DEX

	Permissioned DEX (XLS-81)	Permissioned AMM (this proposal)
Market engine	Order book	Liquidity pool
Price source	User-posted offers	Pool reserves + invariant
Counterparty	Other traders	The pool
Gated subject	Placing / taking offers	Pool participation actions
Market identity	Offer + DomainID	ltAMM object + DomainID
Control surface	Trade access	Provide / withdraw / govern (and optionally swap)

Both build on the same PermissionedDomain object and the same membership test. This proposal reuses that test verbatim, so an account already onboarded to a domain for Permissioned DEX needs no additional onboarding for a Permissioned AMM scoped to the same domain.

3. Specification

3.1. Ledger Entry: ltAMM (Modified)

3.1.1. Fields

Four optional fields are added. All default to absent, in which case the pool behaves as a standard, fully public XLS-30 pool.

Field Name	Constant	Required	Internal Type	Default	Description
DomainID	Yes	No	HASH256	N/A	The Permissioned Domain governing this pool. Membership required for gated actions.
AssetDomain	Yes	No	HASH256	N/A	Per-side override: domain required to provide/withdraw the Asset side. Falls back to DomainID.
Asset2Domain	Yes	No	HASH256	N/A	Per-side override: domain required to provide/withdraw the Asset2 side. Falls back to DomainID.
PoolPermissions	No	No	UINT16	0	Bit flags selecting which action classes are gated (see §3.1.2).

A pool is "permissioned" if DomainID (or either per-side domain) is set. These domain fields are constant after AMMCreate: changing the governing domain on a live pool would retroactively strand existing positions whose owners qualified under the old rules, matching the conservative posture of the AMM amendment family.

3.1.2. Flags

PoolPermissions is a bitmask. Absent/zero means the default policy: all liquidity and governance actions are gated by DomainID, swaps remain public (hybrid).

Flag Name	Flag Value	Description
lsfSwapsPermissioned	0x0001	Swaps routing through this pool require the taker to be a domain member. Unset = hybrid (public swaps).
lsfDepositPermissioned	0x0002	AMMDeposit requires membership (default on for permissioned pools).
lsfWithdrawPermissioned	0x0004	AMMWithdraw requires membership, subject to the §3.5 carve-out.
lsfGovernancePermissioned	0x0008	AMMVote and AMMBid require membership (default on for permissioned pools).

Per-side domains (AssetDomain / Asset2Domain) refine deposits/withdrawals: a single-asset action on the Asset side checks AssetDomain (or DomainID if unset); a two-asset action checks membership of both side-domains.

3.1.3. Ownership, Reserves, Deletion

Unchanged from XLS-30. The added fields impose no additional owner reserve and do not alter pool deletion conditions.

3.1.4. Membership Test

Identical to Permissioned Domains / Permissioned DEX: an account is a member of domain D if it holds a credential that D accepts, the credential has been accepted by the holder (XLS-70), and the credential is not expired or revoked. No new membership notion or credential type is introduced. Membership is evaluated at transaction-application time, so revocation takes effect immediately.

3.1.5. Example JSON

{
  "LedgerEntryType": "AMM",
  "Account": "rAMM...",
  "Asset": { "currency": "XRP" },
  "Asset2": { "currency": "USD", "issuer": "rISSUER..." },
  "TradingFee": 30,
  "DomainID": "AbC123...",
  "PoolPermissions": 14
}

3.2. Transaction: AMMCreate (Modified)

New optional fields DomainID, AssetDomain, Asset2Domain, PoolPermissions. The creator MUST be a member of every domain it sets (it cannot create a pool it could not participate in). On tesSUCCESS, these are written to the ltAMM object.

3.3. Transactions: AMMDeposit, AMMWithdraw (Modified)

When the relevant flag applies, the actor must be a member of the relevant domain(s): the side-domain for single-asset actions, both side-domains for two-asset actions. AMMWithdraw is subject to the §3.5 carve-out.

3.4. Transactions: AMMVote, AMMBid (Modified)

When lsfGovernancePermissioned applies, the actor must be a member of DomainID.

3.5. Swap Routing and the Withdrawal Carve-out

Swaps. When lsfSwapsPermissioned is set, the AMM is eligible as a liquidity source for a payment-engine step only when the executing account is a member of DomainID; otherwise the pool is skipped in routing for that account. When unset, the pool participates in pathfinding exactly as today (hybrid behavior, consistent with XLS-81 hybrid offers).

Withdrawal carve-out. If withdrawals are gated and an LP's credential later lapses, the LP would otherwise be locked out of its own funds. AMMWithdraw therefore permits an account to withdraw liquidity from a position it owns even if its membership has lapsed, provided it withdraws to itself and performs no other gated action in the same transaction. Compliance is preserved (the account is exiting, creating no new exposure) while custody safety is guaranteed.

3.6. Failure Conditions

Code	Condition
temDISABLED	A permission field is present but featurePermissionedAMM is not enabled.
temMALFORMED	A referenced field is structurally invalid, or PoolPermissions has unknown bits set.
tecNO_PERMISSION	The actor is not a member of the required domain for the attempted action.
tecOBJECT_NOT_FOUND	A referenced DomainID does not exist.

3.7. State Changes

On success, AMMCreate records the domain fields and flags on the new ltAMM. Gated AMMDeposit/AMMWithdraw/AMMVote/AMMBid behave exactly as their XLS-30 counterparts once the membership check passes; the only added behavior is the pre-action membership gate and the §3.5 carve-out.

4. Rationale

Why reuse Permissioned Domains. The ledger already standardizes credential-based membership (XLS-70/80) and applies it to order books (XLS-81). Reusing it for pools gives consistent compliance semantics, shared onboarding, and delegable KYC, while adding only restrictions and no new membership concept.

Why per-side domains and a flag bitmask. RWA operators need finer control than "can this account trade" — e.g. members may add the property-token side while anyone may swap, or governance may be restricted while deposits are open. Per-side domains plus the flag bitmask express the motivating cases without a new ledger object.

Why immutable domain fields. Mutating the governing domain on a live pool would retroactively change who qualifies for existing positions and could strand liquidity; immutability keeps a pool's rules stable for its lifetime.

Alternate designs considered (pathways evaluated).

• Native pool-level allowlist (address array on the pool). Simplest mentally and needs no issuer, but it does not scale, duplicates compliance logic the ledger standardizes, and diverges from the credential-based direction. The domain model achieves the same allowlist outcome (an operator can be the sole credential issuer) while remaining consistent and delegable.
• Reuse Permissioned DEX unchanged. XLS-81 gates offer placement/taking; an AMM's privileged surface (deposit per side, withdraw, vote, bid) has no offer equivalent, and a pool can gate liquidity while keeping swaps public — a configuration the order-book model cannot express. The two are complementary, not redundant.
• Token-level controls only (status quo). Authorized trust lines, MPT authorization, and freeze gate the asset, not the pool, and cannot express per-pool/per-action rules. Pool-level control is additive and composes with these.
• Per-credential-to-per-action mapping. A richer model pointing each action class at a distinct credential type was deferred as over-engineering; per-side domains plus the bitmask cover the motivating cases and finer granularity can be layered later without breaking existing pools.

5. Backwards Compatibility

Fully backwards compatible. All new fields are optional; a pool created without them is a standard public XLS-30 pool, byte-identical in behavior. Existing pools are unaffected and require no migration. On servers where featurePermissionedAMM is not enabled, the presence of any new field is rejected with temDISABLED.

6. Test Plan

• Create permissioned pools with DomainID only, with per-side domains, and with each PoolPermissions combination; verify fields persist and are immutable.
• A member can deposit/withdraw/vote/bid as gated; a non-member receives tecNO_PERMISSION for each gated action.
• Per-side: a member of AssetDomain but not Asset2Domain can single-asset-deposit the Asset side but not perform a two-asset deposit.
• Swaps: with lsfSwapsPermissioned unset, non-members can swap (hybrid); set, non-members' paths skip the pool while members route normally.
• Carve-out: an LP whose credential is revoked can still withdraw its own position to itself, but cannot perform any other gated action in the same transaction.
• Immediacy: revoking a credential blocks the next gated action in the following ledger.
• temDISABLED when fields are present pre-activation; temMALFORMED on unknown PoolPermissions bits; tecOBJECT_NOT_FOUND on a missing DomainID.
• An implementation test plan in rippled (unit + integration) is required for this XLS to reach Final.

7. Security Considerations

Apply-time checks. Gated actions re-evaluate membership when applied, so credential expiry/revocation takes effect immediately; there is no cached-permission window.

No trapped capital. The §3.5 self-withdrawal carve-out guarantees an LP can always exit its own position, preventing a revoked credential from becoming a custodial loss.

No new privilege path. The amendment adds only restrictions; it never grants access an account would not otherwise have, and introduces no new credential or membership concept beyond XLS-70/80.

Pathfinding disclosure. When swaps are gated, a non-member's path simply excludes the pool — identical to how a Permissioned DEX book is excluded for non-members; no information beyond public ledger state is revealed.

Operator centralization. A single credential issuer can fully control membership. This is intended for regulated venues; participants can inspect a pool's DomainID and the domain's accepted credentials before depositing.

8. Appendix

8.1. FAQ

Does a credential have to be issued before someone can participate? Yes. Under XLS-70/80 a domain is defined by accepted credentials, not an address list; an account becomes a member only by holding a credential that has been issued and accepted. An operator wanting a simple allowlist can be the sole issuer and issue only to chosen accounts.

Can swaps stay public while liquidity is gated? Yes — leave lsfSwapsPermissioned unset. This is the default hybrid behavior.

Can a pool require different credentials for each side? Yes — set AssetDomain and Asset2Domain to different domains.

8.2. System Diagram

A Mermaid diagram of the gating flow is maintained alongside this spec; see the companion permissioned-amm-flow figure (participant + domain → membership check → gated liquidity/governance actions, with swaps public unless flagged).