AMMDeposit

[Source]

(Added by the AMM amendment)

Deposit funds into an Automated Market Maker (AMM) instance and receive the AMM's liquidity provider tokens (LP Tokens) in exchange. You can deposit one or both of the assets in the AMM's pool.

If successful, this transaction creates a trust line to the AMM Account (limit 0) to hold the LP Tokens.

Example AMMDeposit JSON

{
    "Account" : "rJVUeRqDFNs2xqA7ncVE6ZoAhPUoaJJSQm",
    "Amount" : {
        "currency" : "TST",
        "issuer" : "rP9jPyP5kyvFRb6ZiRghAGw5u8SGAmU4bd",
        "value" : "2.5"
    },
    "Amount2" : "30000000",
    "Asset" : {
        "currency" : "TST",
        "issuer" : "rP9jPyP5kyvFRb6ZiRghAGw5u8SGAmU4bd"
    },
    "Asset2" : {
        "currency" : "XRP"
    },
    "Fee" : "10",
    "Flags" : 1048576,
    "Sequence" : 7,
    "TransactionType" : "AMMDeposit"
}

AMMDeposit Fields

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

AMMDeposit Modes

This transaction has five modes, defined by which flag you specify. Each mode expects a specific combination of fields. The modes fall into two categories:

• Double-asset deposits, in which you provide both assets in the AMM's pool, proportional to the balance of the assets already there. These deposits are not subject to a fee.
• Single-asset deposits, in which you provide only one of the AMM's two assets. The AMM charges a fee, debited from the LP Tokens paid out, based on how much your deposit shifts the balance of assets in the pool.

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

The following combinations of fields indicate a single asset deposit:

Any other combination of these fields and flags is invalid.

Single Asset Deposit Fee

The fee for a single asset deposit is calculated to be the same as if you had used the AMM to trade part of the deposit amount for the other asset, then done a double-asset deposit. The AMM's trading fee applies to the amount you would need to trade for, but not to the rest of the deposit. For example, if the AMM's asset pool is split perfectly evenly between USD and EUR, and you try to deposit 100 USD, the amount of LP Tokens you receive is slightly less than if you had deposited 50 EUR + 50 USD, because you pay the trading fee to convert some of your USD to an equal amount of EUR.

The formula for how many LP Tokens you receive for a double-asset deposit is:

Where:

• L is the amount of LP Tokens returned
• T is the total outstanding LP Tokens before the deposit
• B is the amount of the asset being deposited
• F is the trading fee, as a decimal
• W is the weight of the deposit asset in the pool. This is defined as 0.5 for all AMM pools (meaning a 50/50 split), so exponentiation by W is equivalent to taking the square root.
• P is the total amount of the deposit asset in the pool before the deposit

Empty AMM Special Case

In some cases, an AMM can exist with no assets in its pool. You cannot perform normal deposits into an AMM in such a state because the ratio between the assets is undefined (0/0). Instead, you can use a special "Empty AMM" deposit case with the flag tfTwoAssetIfEmpty and exact amounts of both assets. This directly sets the ratio between the assets in the same way an AMMCreate transaction does when an AMM is initially created. Like a double-asset deposit, this is not subject to a fee.

You can only do a special "Empty AMM" deposit if the AMM is empty.

AMMDeposit Flags

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

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

Error Cases

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