Last updated
Edit

AMMWithdraw

[Source]

(Added by the AMM amendment)

Withdraw assets from an Automated Market Maker (AMM) instance by returning the AMM's liquidity provider tokens (LP Tokens).

Example AMMWithdraw JSON

{
    "Account" : "rJVUeRqDFNs2xqA7ncVE6ZoAhPUoaJJSQm",
    "Amount" : {
        "currency" : "TST",
        "issuer" : "rP9jPyP5kyvFRb6ZiRghAGw5u8SGAmU4bd",
        "value" : "5"
    },
    "Amount2" : "50000000",
    "Asset" : {
        "currency" : "TST",
        "issuer" : "rP9jPyP5kyvFRb6ZiRghAGw5u8SGAmU4bd"
    },
    "Asset2" : {
        "currency" : "XRP"
    },
    "Fee" : "10",
    "Flags" : 1048576,
    "Sequence" : 10,
    "TransactionType" : "AMMWithdraw"
}

AMMWithdraw Fields

In addition to the common fields, AMMWithdraw transactions use the following fields:

FieldJSON TypeInternal TypeRequired?Description
AssetObjectSTIssueYesThe definition for one of the assets in the AMM's pool. In JSON, this is an object with currency and issuer fields (omit issuer for XRP).
Asset2ObjectSTIssueYesThe definition for the other asset in the AMM's pool. In JSON, this is an object with currency and issuer fields (omit issuer for XRP).
AmountCurrency AmountAmountNoThe amount of one asset to withdraw from the AMM. This must match the type of one of the assets (tokens or XRP) in the AMM's pool.
Amount2Currency AmountAmountNoThe amount of another asset to withdraw from the AMM. If present, this must match the type of the other asset in the AMM's pool and cannot be the same type as Amount.
EPriceCurrency AmountAmountNoThe minimum effective price, in LP Token returned, to pay per unit of the asset to withdraw.
LPTokenInCurrency AmountAmountNoHow many of the AMM's LP Tokens to redeem.

Note: For a double-asset withdrawal, it is possible for Asset to correspond to either Amount or Amount2 as long as Asset2 corresponds to the other one. It is recommended to match them (that is, Amount2 is an amount of the asset defined in Asset2) because it is less confusing that way.

AMMWithdraw Modes

This transaction has several modes, depending on which flags you specify. Each mode expects a specific combination of fields. The modes fall into two categories:

  • Double-asset withdrawals, in which you receive both assets from the AMM's pool in proportions that match their balances there. These withdrawals are not subject to a fee.
  • Single-asset withdrawals, in which you receive one asset from the AMM's pool. The AMM charges a fee based on how much your deposit shifts the balance of assets in the pool. Depending on the withdraw mode, the amount of the fee can be added to the amount of LP Tokens paid in, or debited from the amount of the asset paid out.

The following combinations of fields indicate a double-asset withdrawal:

Flag Name(s)Flag ValueFields SpecifiedMeaning
tfLPToken0x00010000LPTokenIn onlyReturn the specified amount of LP Tokens and receive both assets from the AMM's pool in amounts based on the returned LP Tokens' share of the total LP Tokens issued.
tfWithdrawAll0x00020000No FieldsReturn all of your LP Tokens and receive as much as you can of both assets in the AMM's pool.
tfTwoAsset0x00100000Amount and Amount2Withdraw both of this AMM's assets, in up to the specified amounts. The actual amounts received maintains the balance of assets in the AMM's pool.

The following combinations of fields indicate a single asset withdrawal:

Flag Name(s)Flag ValueFields SpecifiedMeaning
tfSingleAsset0x00080000Amount onlyWithdraw exactly the specified amount of one asset, by returning as many LP Tokens as necessary.
tfOneAssetWithdrawAll0x00040000Amount onlyWithdraw at least the specified amount of one asset, by returning all of your LP Tokens. Fails if you can't receive at least the specified amount. The specified amount can be 0, meaning the transaction succeeds if it withdraws any positive amount.
tfOneAssetLPToken0x00200000Amount and LPTokenInWithdraw up to the specified amount of one asset, by returning up to the specified amount of LP Tokens.
tfLimitLPToken0x00400000Amount and EPriceWithdraw up to the specified amount of one asset, but pay no more than the specified effective price in LP Tokens per unit of the asset received.

Any other combination of these fields is invalid.

Single Asset Withdrawal Fee

The fee for a single asset withdrawal is calculated to be the same as if you had done a double-asset withdrawal and then used the AMM to trade all of the other asset for the one you are withdrawing. The trading fee applies to the amount you would need to trade for, but not to the rest of the withdrawal.

AMM Deletion

If the transaction withdraws the last of the AMM's assets, it automatically tries to delete the AMM along with all associated trust lines. However, there is a limit to how many empty trust lines can be removed in one transaction. If too many empty trust lines exist, the AMM remains in the ledger in an empty state; it can be deleted with further AMMDelete transactions, or it can be refilled with a special "empty AMM" two-asset AMMDeposit transaction. While an AMM is empty, no other operations on it are valid.

AMMWithdraw Flags

Transactions of the AMMWithdraw type support additional values in the Flags field, as follows:

Flag NameHex ValueDecimal ValueDescription
tfLPToken0x0001000065536Perform a double-asset withdrawal and receive the specified amount of LP Tokens.
tfWithdrawAll0x00020000131072Perform a double-asset withdrawal returning all your LP Tokens.
tfOneAssetWithdrawAll0x00040000262144Perform a single-asset withdrawal returning all of your LP Tokens.
tfSingleAsset0x00080000524288Perform a single-asset withdrawal with a specified amount of the asset to withdrawal.
tfTwoAsset0x001000001048576Perform a double-asset withdrawal with specified amounts of both assets.
tfOneAssetLPToken0x002000002097152Perform a single-asset withdrawal and receive the specified amount of LP Tokens.
tfLimitLPToken0x004000004194304Perform a single-asset withdrawal with a specified effective price.

You must specify exactly one of these flags, plus any global flags.

Error Cases

Besides errors that can occur for all transactions, AMMWithdraw transactions can result in the following transaction result codes:

Error CodeDescription
tecAMM_EMPTYThe AMM has no assets in its pool. In this state, you can only delete the AMM or fund it with a new deposit.
tecAMM_BALANCEThe transaction would withdraw all of one asset from the pool, or rounding would cause a "withdraw all" to leave a nonzero amount behind.
tecAMM_FAILEDThe conditions on the withdrawal could not be satisfied; for example, the requested effective price in the EPrice field is too low.
tecAMM_INVALID_TOKENSThe AMM for this token pair does not exist, or one of the calculations resulted in a withdrawal amount rounding to zero.
tecFROZENThe transaction tried to withdraw a frozen token.
tecINSUF_RESERVE_LINEThe sender of this transaction does not meet the increased reserve requirement of processing this transaction, probably because they need at least one new trust line to hold one of the assets to be withdrawn, and they don't have enough XRP to meet the additional owner reserve for a new trust line.
tecNO_AUTHThe sender is not authorized to hold one of the AMM assets.
temMALFORMEDThe transaction specified an invalid combination of fields. See AMMWithdraw Modes. (This error can also occur if the transaction is malformed in other ways.)
temBAD_AMM_TOKENSThe transaction specified the LP Tokens incorrectly; for example, the issuer is not the AMM's associated AccountRoot address or the currency is not the currency code for this AMM's LP Tokens, or the transaction specified this AMM's LP Tokens in one of the asset fields.
terNO_AMMThe Automated Market Maker instance for the asset pair in this transaction does not exist.