ARCHIVE/xrpl-dev-portal
1
0
Fork 0
mirror of https://github.com/XRPLF/xrpl-dev-portal.git synced 2025-11-27 23:25:51 +00:00
Code Issues Packages Projects Releases Wiki Activity

Merge pull request #1541 from XRPLF/amm_ref

Browse Source 
Automated Market Maker (XLS-30d) reference documentation
This commit is contained in:
Rome Reginelli
2022-11-23 14:33:21 -08:00
committed by GitHub
parent b3baec9187 ecb8acfafb
commit e3a6935cb2
30 changed files with 1317 additions and 37 deletions
Download Patch File Download Diff File Expand all files Collapse all files

9
content/references/protocol-reference/transactions/transaction-results/tec-codes.md
View File

@@ -15,6 +15,14 @@ For the most part, transactions with `tec` codes take no action other than to de
| Code | Value | Explanation |
|:---------------------------|:------|:----------------------------------------|
| `tecAMM_BALANCE` | 163 |
| `tecAMM_DIRECT_PAYMENT` | 169 | The transaction tried to send money directly to an AccountRoot object that is part of an Automated Market Maker (AMM) :not_enabled:. AMM AccountRoot entries cannot send or receive money directly except through [AMMWithdraw][] and [AMMDeposit][] transactions. |
| `tecAMM_EXISTS` | 167 | The [AMMCreate transaction][] :not_enabled: tried to create an Automated Market Maker (AMM) instance that already exists. There can only be at most one AMM per unique currency pair. |
| `tecAMM_FAILED_DEPOSIT` | 164 | The [AMMDeposit transaction][] :not_enabled: failed, probably because the sender does not have enough of the specified assets, or because the deposit requested an effective price that isn't possible with the available amounts. |
| `tecAMM_FAILED_WITHDRAW` | 165 | The [AMMWithdraw transaction][] :not_enabled: failed, probably because the sender does not have enough LP Tokens, or because the withdraw requested an effective price that isn't possible with the available amounts. |
| `tecAMM_FAILED_BID` | 168 | The [AMMBid transaction][] :not_enabled: failed, probably because the price to win the auction was higher than the specified maximum value or the sender's current balance. |
| `tecAMM_FAILED_VOTE` | 170 | The [AMMVote transaction][] :not_enabled: failed, probably because there are already too many votes from accounts that hold more LP Tokens for this AMM. (This can still recalculate the AMM's trading fee.) |
| `tecAMM_INVALID_TOKENS` | 166 | The AMM-related transaction :not_enabled: failed due to insufficient LP Tokens or problems with rounding; for example, depositing a very small amount of assets could fail if the amount of LP Tokens to be returned rounds down to zero. |
| `tecCANT_ACCEPT_OWN_NFTOKEN_OFFER` | 157 | The transaction tried to accept an offer that was placed by the same account to buy or sell a [non-fungible token](non-fungible-tokens.html). _(Added by the [NonFungibleTokensV1_1 amendment][].)_ |
| `tecCLAIM` | 100 | Unspecified failure, with transaction cost destroyed. |
| `tecCRYPTOCONDITION_ERROR` | 146 | This [EscrowCreate][] or [EscrowFinish][] transaction contained a malformed or mismatched crypto-condition. |
@@ -59,6 +67,7 @@ For the most part, transactions with `tec` codes take no action other than to de
| `tecTOO_SOON` | 152 | The [AccountDelete transaction][] failed because the account to be deleted had a `Sequence` number that is too high. The current ledger index must be at least 256 higher than the account's sequence number. |
| `tecUNFUNDED` | 129 | The transaction failed because the account does not hold enough XRP to pay the amount in the transaction _and_ satisfy the additional [reserve](reserves.html) necessary to execute this transaction. |
| `tecUNFUNDED_ADD` | 102 | **DEPRECATED.** |
| `tecUNFUNDED_AMM` | 162 | The [AMMCreate transaction][] :not_enabled: failed because the sender does not have enough of the specified assets to fund it. |
| `tecUNFUNDED_PAYMENT` | 104 | The transaction failed because the sending account is trying to send more XRP than it holds, not counting the [reserve](reserves.html). |
| `tecUNFUNDED_OFFER` | 103 | The [OfferCreate transaction][] failed because the account creating the offer does not have any of the `TakerGets` currency. |

10
content/references/protocol-reference/transactions/transaction-results/tem-codes.md
View File

@@ -11,10 +11,12 @@ These codes indicate that the transaction was malformed, and cannot succeed acco
**Tip:** Transactions with `tem` codes are not applied to ledgers, and cannot cause any changes to XRP Ledger state. A `tem` result is final unless the rules for a valid transaction change. (For example, using functionality from an [Amendment](amendments.html) before that amendment is enabled results in `temDISABLED`; such a transaction could succeed later if it becomes valid when the amendment is enabled.)
| Code | Explanation |
|:-----------------------------|:----------------------------------------------|
| Code | Explanation |
|:------------------------------|:----------------------------------------------|
| `temBAD_AMM_OPTIONS` | The AMM-related transaction :not_enabled: specified a combination of parameters that is invalid. |
| `temBAD_AMM_TOKENS` | The AMM-related transaction :not_enabled: specified its LP Tokens in an invalid format or specified LP Tokens for the wrong AMM instance. |
| `temBAD_AMOUNT` | An amount specified by the transaction (for example the destination `Amount` or `SendMax` values of a [Payment][]) was invalid, possibly because it was a negative number. |
| `temBAD_AUTH_MASTER` | The key used to sign this transaction does not match the master key for the account sending it, and the account does not have a [Regular Key](cryptographic-keys.html) set. |
| `temBAD_AUTH_MASTER` | The key used to sign this transaction does not match the master key for the account sending it, and the account does not have a [Regular Key](cryptographic-keys.html) set. |
| `temBAD_CURRENCY` | The transaction improperly specified a currency field. See [Specifying Currency Amounts][Currency Amount] for the correct format. |
| `temBAD_EXPIRATION` | The transaction improperly specified an expiration value, for example as part of an [OfferCreate transaction][]. Alternatively, the transaction did not specify a required expiration value, for example as part of an [EscrowCreate transaction][]. |
| `temBAD_FEE` | The transaction improperly specified its `Fee` value, for example by listing a non-XRP currency or some negative amount of XRP. |
@@ -43,6 +45,8 @@ These codes indicate that the transaction was malformed, and cannot succeed acco
| `temREDUNDANT` | The transaction would do nothing; for example, it is sending a payment directly to the sending account, or creating an offer to buy and sell the same currency from the same issuer. |
| `temREDUNDANT_SEND_MAX` | [Removed in: rippled 0.28.0][] |
| `temRIPPLE_EMPTY` | The [Payment transaction][] includes an empty `Paths` field, but paths are necessary to complete this payment. |
| `temBAD_AMM_OPTIONS` | The transaction specified an invalid combination of options regarding an Automated Market Maker (AMM). :not_enabled: |
| `temBAD_AMM_TOKENS` | The transaction incorrectly specified an Automated Market Maker's LP Tokens. :not_enabled: |
| `temBAD_WEIGHT` | The [SignerListSet transaction][] includes a `SignerWeight` that is invalid, for example a zero or negative value. |
| `temBAD_SIGNER` | The [SignerListSet transaction][] includes a signer who is invalid. For example, there may be duplicate entries, or the owner of the SignerList may also be a member. |
| `temBAD_QUORUM` | The [SignerListSet transaction][] has an invalid `SignerQuorum` value. Either the value is not greater than zero, or it is more than the sum of all signers in the list. |

1
content/references/protocol-reference/transactions/transaction-results/ter-codes.ja.md
View File

@@ -17,6 +17,7 @@ labels:
| `terINSUF_FEE_B` | トランザクションの送信元アカウントに、トランザクションに指定されている`Fee`の支払いに十分なXRPがありません。 |
| `terLAST` | 内部使用のみ。通常はこのコードは返されません。 |
| `terNO_ACCOUNT` | レジャーのトランザクション送信元アドレスに（まだ）資金が供給されていません。 |
| `terNO_AMM` | The AMM-related transaction :not_enabled: specifies an asset pair that does not currently have an AMM instance. <!-- TODO: translate --> |
| `terNO_AUTH` | トランザクションでは、`lsfRequireAuth`が有効であるアカウントが発行した通貨を未承認のトラストラインに追加する操作が行われます。たとえば、保有が許可されていない通貨を購入するオファーを出した場合などです。 |
| `terNO_LINE` | 内部使用のみ。通常はこのコードは返されません。 |
| `terNO_RIPPLE` | 内部使用のみ。通常はこのコードは返されません。 |

23
content/references/protocol-reference/transactions/transaction-results/ter-codes.md
View File

@@ -13,18 +13,19 @@ These codes indicate that the transaction failed, but it could apply successfull
| Code | Explanation |
|:-----------------|:----------------------------------------------------------|
| `terFUNDS_SPENT` | **DEPRECATED.** |
| `terFUNDS_SPENT` | **DEPRECATED.** |
| `terINSUF_FEE_B` | The account sending the transaction does not have enough XRP to pay the `Fee` specified in the transaction. |
| `terLAST` | Used internally only. This code should never be returned. |
| `terNO_ACCOUNT` | The address sending the transaction is not funded in the ledger (yet). |
| `terNO_AUTH` | The transaction would involve adding currency issued by an account with `lsfRequireAuth` enabled to a trust line that is not authorized. For example, you placed an offer to buy a currency you aren't authorized to hold. |
| `terNO_LINE` | Used internally only. This code should never be returned. |
| `terNO_RIPPLE` | Used internally only. This code should never be returned. |
| `terOWNERS` | The transaction requires that account sending it has a nonzero "owners count", so the transaction cannot succeed. For example, an account cannot enable the [`lsfRequireAuth`](accountset.html#accountset-flags) flag if it has any trust lines or available offers. |
| `terPRE_SEQ` | The `Sequence` number of the current transaction is higher than the current sequence number of the account sending the transaction. |
| `terPRE_TICKET` | The transaction attempted to use a [Ticket](tickets.html), but the specified `TicketSequence` number does not exist in the ledger. However, the Ticket could still be created by another transaction. |
| `terRETRY` | Unspecified retriable error. |
| `terQUEUED` | The transaction met the load-scaled [transaction cost](transaction-cost.html) but did not meet the open ledger requirement, so the transaction has been queued for a future ledger. |
| `terLAST` | Used internally only. This code should never be returned. |
| `terNO_ACCOUNT` | The address sending the transaction is not funded in the ledger (yet). |
| `terNO_AMM` | The AMM-related transaction :not_enabled: specifies an asset pair that does not currently have an AMM instance. |
| `terNO_AUTH` | The transaction would involve adding currency issued by an account with `lsfRequireAuth` enabled to a trust line that is not authorized. For example, you placed an offer to buy a currency you aren't authorized to hold. |
| `terNO_LINE` | Used internally only. This code should never be returned. |
| `terNO_RIPPLE` | Used internally only. This code should never be returned. |
| `terOWNERS` | The transaction requires that account sending it has a nonzero "owners count", so the transaction cannot succeed. For example, an account cannot enable the [`lsfRequireAuth`](accountset.html#accountset-flags) flag if it has any trust lines or available offers. |
| `terPRE_SEQ` | The `Sequence` number of the current transaction is higher than the current sequence number of the account sending the transaction. |
| `terPRE_TICKET` | The transaction attempted to use a [Ticket](tickets.html), but the specified `TicketSequence` number does not exist in the ledger. However, the Ticket could still be created by another transaction. |
| `terRETRY` | Unspecified retriable error. |
| `terQUEUED` | The transaction met the load-scaled [transaction cost](transaction-cost.html) but did not meet the open ledger requirement, so the transaction has been queued for a future ledger. |
<!--{# common link defs #}-->
{% include '_snippets/rippled-api-links.md' %}

139
content/references/protocol-reference/transactions/transaction-types/ammbid.md Normal file
View File

@@ -0,0 +1,139 @@
---
html: ammbid.html
parent: transaction-types.html
blurb: Bid on an Automated Market Maker's auction slot, which grants a discounted fee.
labels:
- AMM
status: not_enabled
---
# AMMBid
[[Source]](https://github.com/gregtatcam/rippled/blob/amm-core-functionality/src/ripple/app/tx/impl/AMMBid.cpp "Source")
<!-- TODO: Update source link to merged version when available -->
{% include '_snippets/amm-disclaimer.md' %}
Bid on an Automated Market Maker's (AMM's) auction slot. If you win, you can trade against the AMM at a discounted fee until you are outbid or 24 hours have passed. If you are outbid before 24 hours have passed, you are refunded part of the cost of your bid based on how much time remains.
You bid using the AMM's LP Tokens; the amount of a winning bid is returned to the AMM, decreasing the outstanding balance of LP Tokens.
## Example {{currentpage.name}} JSON
```json
{
"Account" : "rJVUeRqDFNs2xqA7ncVE6ZoAhPUoaJJSQm",
"Asset" : {
"currency" : "XRP"
},
"Asset2" : {
"currency" : "TST",
"issuer" : "rP9jPyP5kyvFRb6ZiRghAGw5u8SGAmU4bd"
},
"AuthAccounts" : [
{
"AuthAccount" : {
"Account" : "rMKXGCbJ5d8LbrqthdG46q3f969MVK2Qeg"
}
},
{
"AuthAccount" : {
"Account" : "rBepJuTLFJt3WmtLXYAxSjtBWAeQxVbncv"
}
}
],
"BidMax" : {
"currency" : "039C99CD9AB0B70B32ECDA51EAAE471625608EA2",
"issuer" : "rE54zDvgnghAoPopCgvtiqWNq3dU5y836S",
"value" : "100"
},
"Fee" : "10",
"Flags" : 2147483648,
"Sequence" : 9,
"TransactionType" : "AMMBid"
}
```
{% include '_snippets/tx-fields-intro.md' %}
| Field | JSON Type | [Internal Type][] | Required? | Description |
|:---------------|:--------------------|:------------------|:----------|:------------|
| `Asset` | Object | STIssue | Yes | The 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). |
| `Asset2` | Object | STIssue | Yes | The 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). |
| `BidMin` | [Currency Amount][] | Amount | No | Pay at least this amount for the slot. Setting this value higher makes it harder for others to outbid you. If omitted, pay the minimum necessary to win the bid. |
| `BidMax` | [Currency Amount][] | Amount | No | Pay at most this amount for the slot. If the cost to win the bid is higher than this amount, the transaction fails. If omitted, pay as much as necessary to win the bid. |
| `AuthAccounts` | Array | STArray | No | A list of up to 4 additional accounts that you allow to trade at the discounted fee. This cannot include the address of the transaction sender. Each of these objects should be an [AuthAccount object](#authaccount-objects). |
You cannot specify both `BidMin` and `BidMax`.
### AuthAccount Objects
Each member of the `AuthAccounts` array must be an object with the following field:
| Field | JSON Type | [Internal Type][] | Required? | Description |
|:---------------|:----------|:------------------|:----------|:------------|
| `Account` | String | AccountID | Yes | The address of the account to authorize. |
Like other "inner objects" that can appear in arrays, the JSON representation of each of these objects is wrapped in an object whose only key is the object type, `AuthAccount`.
## Auction Slot Price
If successful, the transaction automatically outbids the previous slot owner and debits the bid price from the sender's LP Tokens. The price to win the auction decreases over time, divided into 20 intervals of 72 minutes each. If the sender does not have enough LP Tokens to win the bid, or the price of the bid is higher than the transaction's `BidMax` value, the transaction fails with a `tecAMM_FAILED_BID` result.
- If the auction slot is currently empty, expired, or in its last interval, the **minimum bid** is **0.001% of the AMM's total LP Tokens balance**.
**Caution:** This minimum value is a placeholder and may change before the AMM feature becomes finalized.
- Otherwise, the price to outbid the current holder is calculated using the following formula:
P = B × 1.05 × (1 - t⁶⁰) + M
- `P` is the price to outbid, in LP Tokens.
- `B` is the price of the current bid, in LP Tokens.
- `t` is the fraction of time elapsed in the current 24-hour slot, rounded down to a multiple of 0.05.
- `M` is the **minimum bid** as defined above.
There are two special cases for the cost to outbid someone. In the **first interval** after someone wins the bid, the price to outbid them is the minimum bid plus 5% more than the existing bid:
P = B × 1.05 + M
In the **last interval** of someone's slot, the cost to outbid someone is only the minimum bid:
P = M
**Note:** To make sure all servers in the network reach the same results when building a ledger, time measurements are based on the [official close time](ledgers.html#ledger-close-times) of the previous ledger, which is approximate.
## Bid Refunds
When you outbid an active auction slot, the AMM refunds the previous holder part of the price, using this formula:
```text
R = B × (1 - t)
```
- `R` is the amount to refund, in LP Tokens.
- `B` is the price of the previous bid to be refunded, in LP Tokens.
- `t` is the fraction of time elapsed in the current 24-hour slot, rounded down to a multiple of 0.05.
As a special case, during the final (20th) interval of the auction slot, the refunded amount is zero.
**Note:** As with all XRP Ledger times, transaction processing uses the [official close time](ledgers.html#ledger-close-times) of the _previous_ ledger, which can result in a difference of up to about 10 seconds from real time.
## AMM Cases previous holder
In addition to errors that can occur for all transactions, {{currentpage.name}} transactions can result in the following [transaction result codes](transaction-results.html):
| Error Code | Description |
|:------------------------|:---------------------------------------------|
| `tecAMM_FAILED_BID` | This transaction could not win the auction, either because the sender does not hold enough LP Tokens to pay the necessary bid or because the price to win the auction was higher than the transaction's specified `BidMax` value. |
| `tecAMM_INVALID_TOKENS` | The sender of this transaction does not hold enough LP Tokens to meet the slot price. |
| `temBAD_AMM_TOKENS` | The specified `BidMin` or `BidMax` were not specified as the correct LP Tokens for this AMM. |
| `temBAD_AMM_OPTIONS` | The transaction specified invalid options, such as a list of `AuthAccounts` that is too long, or specifying both `BidMin` and `BidMax`. |
| `temDISABLED` | The AMM feature :not_enabled: is not enabled on this network. |
| `terNO_ACCOUNT` | One of the accounts specified in this request do not exist. |
| `terNO_AMM` | The Automated Market Maker instance for the asset pair in this transaction does not exist. |
<!--{# common link defs #}-->
{% include '_snippets/rippled-api-links.md' %}
{% include '_snippets/tx-type-links.md' %}
{% include '_snippets/rippled_versions.md' %}

71
content/references/protocol-reference/transactions/transaction-types/ammcreate.md Normal file
View File

@@ -0,0 +1,71 @@
---
html: ammcreate.html
parent: transaction-types.html
blurb: Create a new AMM instance for trading a given pair of assets.
labels:
- AMM
status: not_enabled
---
# AMMCreate
[[Source]](https://github.com/gregtatcam/rippled/blob/amm-core-functionality/src/ripple/app/tx/impl/AMMCreate.cpp "Source")
<!-- TODO: Update source link to merged version when available -->
{% include '_snippets/amm-disclaimer.md' %}
Create a new Automated Market-Maker (AMM) instance for trading a pair of assets ([fungible tokens](tokens.html) or [XRP](xrp.html)).
Creates both an [AMM object][] and a [special AccountRoot object](accountroot.html#special-amm-accountroot-objects) to represent the AMM. Also transfers ownership of the starting balance of both assets from the sender to the created `AccountRoot` and issues an initial balance of liquidity provider tokens (LP Tokens) from the AMM account to the sender.
**Caution:** When you create the AMM, you should fund it with (approximately) equal-value amounts of each asset. Otherwise, other users can profit at your expense by trading with this AMM ([performing arbitrage](https://www.machow.ski/posts/an_introduction_to_automated_market_makers/#price-arbitrage)). The currency risk that liquidity providers take on increases with the volatility (potential for imbalance) of the asset pair. The higher the trading fee, the more it offsets this risk, so it's best to set the trading fee based on the volatility of the asset pair.
## Example {{currentpage.name}} JSON
```json
{
"Account" : "rJVUeRqDFNs2xqA7ncVE6ZoAhPUoaJJSQm",
"Amount" : {
"currency" : "TST",
"issuer" : "rP9jPyP5kyvFRb6ZiRghAGw5u8SGAmU4bd",
"value" : "25"
},
"Amount2" : "250000000",
"Fee" : "10",
"Flags" : 2147483648,
"Sequence" : 6,
"TradingFee" : 500,
"TransactionType" : "AMMCreate"
}
```
{% include '_snippets/tx-fields-intro.md' %}
<!--{# fix md highlighting_ #}-->
| Field | JSON Type | [Internal Type][] | Required? | Description |
|:-------------|:--------------------|:------------------|:----------|:------------|
| `Amount` | [Currency Amount][] | Amount | Yes | The first of the two assets to fund this AMM with. This must be a positive amount. |
| `Amount2` | [Currency Amount][] | Amount | Yes | The second of the two assets to fund this AMM with. This must be a positive amount. |
| `TradingFee` | Number | UInt16 | Yes | The fee to charge for trades against this AMM instance, in units of 1/100,000; a value of 1 is equivalent to 0.001%. The maximum value is `1000`, indicating a 1% fee. The minimum value is `0`. |
One or both of `Amount` and `Amount2` can be [tokens](tokens.html); at most one of them can be [XRP](xrp.html). They cannot both have the same currency code and issuer. An AMM's LP tokens _can_ be used as one of the assets for another AMM.
## Error Cases
In addition to errors that can occur for all transactions, {{currentpage.name}} transactions can result in the following [transaction result codes](transaction-results.html):
| Error Code | Description |
|:--------------------|:---------------------------------------------|
| `temDISABLED` | The AMM feature :not_enabled: is not enabled on this network. |
| `temINVALID_FLAG` | The transaction specified an invalid `Flags` value. Since there are currently no flags defined for this transaction type, only [Global Flags](transaction-common-fields.html#global-flags) are allowed. |
| `temBAD_AMM_TOKENS` | The values of `Amount` and `Amount2` are not valid: for example, both refer to the same token. |
| `temBAD_FEE` | The `TradingFee` value is invalid. It must be zero or a positive integer and cannot be over 1000. |
| `terNO_ACCOUNT` | One of the accounts referenced in the request does not exist. |
| `tecNO_AUTH` | The sender is not authorized to hold one of the deposit assets (`Amount` or `Amount2`). |
| `tecNO_LINE` | The sender does not have a trust line for one of the deposit assets (`Amount` or `Amount2`). |
| `tecFROZEN` | At least one of the deposit assets (`Amount` or `Amount2`) is currently [frozen](freezes.html). |
| `tecUNFUNDED_AMM` | The sender does not hold enough money to fund the AMM with the amounts specified in `Amount` and `Amount2`. |
| `tecAMM_EXISTS` | There is already another AMM trading this currency pair. |
<!--{# common link defs #}-->
{% include '_snippets/rippled-api-links.md' %}
{% include '_snippets/tx-type-links.md' %}
{% include '_snippets/rippled_versions.md' %}

137
content/references/protocol-reference/transactions/transaction-types/ammdeposit.md Normal file
View File

@@ -0,0 +1,137 @@
---
html: ammdeposit.html
parent: transaction-types.html
blurb: Deposit funds into an Automated Market Maker in exchange for LPTokens.
labels:
- AMM
status: not_enabled
---
# AMMDeposit
[[Source]](https://github.com/gregtatcam/rippled/blob/amm-core-functionality/src/ripple/app/tx/impl/AMMDeposit.cpp "Source")
<!-- TODO: Update source link to merged version when available -->
{% include '_snippets/amm-disclaimer.md' %}
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](trust-lines-and-issuing.html) to the AMM Account (limit 0) to hold the LP Tokens.
## Example {{currentpage.name}} JSON
```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"
}
```
{% include '_snippets/tx-fields-intro.md' %}
| Field | JSON Type | [Internal Type][] | Required? | Description |
|:--------------|:--------------------|:------------------|:----------|:------------|
| `Asset` | Object | STIssue | Yes | The 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). |
| `Asset2` | Object | STIssue | Yes | The 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). |
| `Amount` | [Currency Amount][] | Amount | No | The amount of one asset to deposit to the AMM. If present, this must match the type of one of the assets (tokens or XRP) in the AMM's pool. |
| `Amount2` | [Currency Amount][] | Amount | No | The amount of another asset to add to the AMM. If present, this must match the type of the other asset in the AMM's pool and cannot be the same asset as `Amount`. |
| `EPrice` | [Currency Amount][] | Amount | No | The maximum effective price, in the deposit asset, to pay for each LP Token received. |
| `LPTokenOut` | [Currency Amount][] | Amount | No | How many of the AMM's LP Tokens to buy. |
### 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**:
| Flag Name | Flag Value | Fields Specified | Meaning |
|--------------|--------------|------------------------|---------|
| `tfLPToken` | `0x00010000` | `LPTokenOut` only | Deposit both of this AMM's assets, in amounts calculated so that you receive the specified amount of LP Tokens in return. The amounts deposited maintain the relative proportions of the two assets the AMM already holds. |
| `tfTwoAsset` | `0x00100000` | `Amount` and `Amount2` | Deposit both of this AMM's assets, up to the specified amounts. The actual amounts deposited must maintain the same balance of assets as the AMM already holds, so the amount of either one deposited MAY be less than specified. The amount of LP Tokens you get in return is based on the total value deposited. |
The following combinations of fields indicate a **single asset deposit**:
| Flag Name | Flag Value | Fields Specified | Meaning |
|---------------------|--------------|----------------------------|---------|
| `tfSingleAsset` | `0x00080000` | `Amount` only | Deposit exactly the specified amount of one asset, and receive an amount of LP Tokens based on the resulting share of the pool (minus fees). |
| `tfOneAssetLPToken` | `0x00200000` | `Amount` and `LPTokenOut` | Deposit up to the specified amount of one asset, so that you receive exactly the specified amount of LP Tokens in return (after fees). |
| `tfLimitLPToken` | `0x00400000` | `Amount` and `EPrice` | Deposit up to the specified amount of one asset, but pay no more than the specified effective price per LP Token (after fees). |
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 performed 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:
{{ include_svg("img/amm-single-asset-deposit-formula.svg", "L = T × ( (( 1 + (B - (F × (1 - W) × B)) ÷ P)^W) - 1)") }}
<!-- TODO: improve graphic -->
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
### AMMDeposit Flags
Transactions of the AMMDeposit type support additional values in the [`Flags` field](transaction-common-fields.html#flags-field), as follows:
| Flag Name | Hex Value | Decimal Value | Description |
|:--------------------|:-------------|:--------------|:----------------------|
| `tfLPToken` | `0x00010000` | 65536 | Perform a double-asset deposit and receive the specified amount of LP Tokens. |
| `tfSingleAsset` | `0x00080000` | 524288 | Perform a single-asset deposit with a specified amount of the asset to deposit. |
| `tfTwoAsset` | `0x00100000` | 1048576 | Perform a double-asset deposit with specified amounts of both assets. |
| `tfOneAssetLPToken` | `0x00200000` | 2097152 | Perform a single-asset deposit and receive the specified amount of LP Tokens. |
| `tfLimitLPToken` | `0x00400000` | 4194304 | Perform a single-asset deposit with a specified effective price. |
You must specify **exactly one** of these flags, in addition to any [global flags](transaction-common-fields.html#global-flags).
## Error Cases
In addition to errors that can occur for all transactions, {{currentpage.name}} transactions can result in the following [transaction result codes](transaction-results.html):
| Error Code | Description |
|:------------------------|:---------------------------------------------|
| `temBAD_AMM_OPTIONS` | The transaction specified an invalid combination of fields. See [AMMDeposit Modes](#ammdeposit-modes). |
| `tecFROZEN` | The transaction tried to deposit a [frozen](freezes.html) token. |
| `tecAMM_BALANCE` | The AMM does not have enough of one of the assets to accept the deposit (for example, to satisfy the trade portion of a single-asset deposit) or the sender does not have enough of a given token. |
| `temBAD_AMM_TOKENS` | The 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. |
| `tecAMM_FAILED_DEPOSIT` | The conditions on the deposit could not be satisfied; for example, the requested effective price in the `EPrice` field is too low. |
| `tecAMM_INVALID_TOKENS` | The AMM for this token pair does not exist, or one of the calculations resulted in a deposit amount rounding to zero. |
| `tecINSUF_RESERVE_LINE` | The sender of this transaction does meet the increased [reserve requirement](reserves.html) of processing this transaction, probably because they need a new trust line to hold the LP Tokens, and they don't have enough XRP to meet the additional owner reserve for a new trust line. |
| `tecNO_AUTH` | The sender is not authorized to hold one of the deposit assets. |
| `tecNO_LINE` | The sender does not have a trust line for one of the deposit assets. |
| `tecUNFUNDED_AMM` | The sender does not have a high enough balance to make the specified deposit. |
| `terNO_ACCOUNT` | An account specified in the request does not exist. |
| `terNO_AMM` | The Automated Market Maker instance for the asset pair in this transaction does not exist. |
<!--{# common link defs #}-->
{% include '_snippets/rippled-api-links.md' %}
{% include '_snippets/tx-type-links.md' %}
{% include '_snippets/rippled_versions.md' %}

61
content/references/protocol-reference/transactions/transaction-types/ammvote.md Normal file
View File

@@ -0,0 +1,61 @@
---
html: ammvote.html
parent: transaction-types.html
blurb: Vote on the trading fee for an Automated Market Maker instance.
labels:
- AMM
status: not_enabled
---
# AMMVote
[[Source]](https://github.com/gregtatcam/rippled/blob/amm-core-functionality/src/ripple/app/tx/impl/AMMVote.cpp "Source")
<!-- TODO: Update source link to merged version when available -->
{% include '_snippets/amm-disclaimer.md' %}
Vote on the trading fee for an Automated Market Maker instance. Up to 8 accounts can vote in proportion to the amount of the AMM's LP Tokens they hold. Each new vote re-calculates the AMM's trading fee based on a weighted average of the votes.
## Example {{currentpage.name}} JSON
```json
{
"Account" : "rJVUeRqDFNs2xqA7ncVE6ZoAhPUoaJJSQm",
"Asset" : {
"currency" : "XRP"
},
"Asset2" : {
"currency" : "TST",
"issuer" : "rP9jPyP5kyvFRb6ZiRghAGw5u8SGAmU4bd"
},
"Fee" : "10",
"Flags" : 2147483648,
"Sequence" : 8,
"TradingFee" : 600,
"TransactionType" : "AMMVote"
}
```
{% include '_snippets/tx-fields-intro.md' %}
| Field | JSON Type | [Internal Type][] | Required? | Description |
|:-------------|:----------|:------------------|:----------|:------------|
| `Asset` | Object | STIssue | Yes | The 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). |
| `Asset2` | Object | STIssue | Yes | The 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). |
| `TradingFee` | Number | UInt16 | Yes | The proposed fee to vote for, in units of 1/100,000; a value of 1 is equivalent to 0.001%. The maximum value is 1000, indicating a 1% fee. |
## Error Cases
In addition to errors that can occur for all transactions, {{currentpage.name}} transactions can result in the following [transaction result codes](transaction-results.html):
| Error Code | Description |
|:------------------------|:---------------------------------------------|
| `tecAMM_INVALID_TOKENS` | The sender cannot vote because they do not hold any of this AMM's LP Tokens. |
| `tecAMM_FAILED_VOTE` | There are already 8 votes from accounts that hold more LP Tokens than the sender of this transaction. |
| `terNO_ACCOUNT` | An account specified in this transaction does not exist. |
| `temBAD_FEE` | The `TradingFee` from this transaction is not valid. |
| `terNO_AMM` | The Automated Market Maker instance for the asset pair in this transaction does not exist. |
<!--{# common link defs #}-->
{% include '_snippets/rippled-api-links.md' %}
{% include '_snippets/tx-type-links.md' %}
{% include '_snippets/rippled_versions.md' %}

125
content/references/protocol-reference/transactions/transaction-types/ammwithdraw.md Normal file
View File

@@ -0,0 +1,125 @@
---
html: ammwithdraw.html
parent: transaction-types.html
blurb: Return LPTokens into an Automated Market Maker in exchange for a share of the assets the pool holds.
labels:
- AMM
status: not_enabled
---
# AMMWithdraw
[[Source]](https://github.com/gregtatcam/rippled/blob/amm-core-functionality/src/ripple/app/tx/impl/AMMWithdraw.cpp "Source")
<!-- TODO: Update source link to merged version when available -->
{% include '_snippets/amm-disclaimer.md' %}
Withdraw assets from an Automated Market-Maker (AMM) instance by returning the AMM's liquidity provider tokens (LP Tokens).
## Example {{currentpage.name}} JSON
```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"
}
```
{% include '_snippets/tx-fields-intro.md' %}
| Field | JSON Type | [Internal Type][] | Required? | Description |
|:-------------|:--------------------|:------------------|:----------|:------------|
| `Asset` | Object | STIssue | Yes | The 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). |
| `Asset2` | Object | STIssue | Yes | The 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). |
| `Amount` | [Currency Amount][] | Amount | No | The 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. |
| `Amount2` | [Currency Amount][] | Amount | No | The 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`. |
| `EPrice` | [Currency Amount][] | Amount | No | The minimum effective price, in LP Token returned, to pay per unit of the asset to withdraw. |
| `LPTokenIn` | [Currency Amount][] | Amount | No | How many of the AMM's LP Tokens to redeem. |
**Note:** For a two-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 modes are for a **double-asset withdrawal**:
| Flag Name(s) | Flag Value | Fields Specified | Meaning |
|-----------------|--------------|------------------------|---------|
| `tfLPToken` | `0x00010000` | `LPTokenIn` only | Return 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. |
| `tfWithdrawAll` | `0x00020000` | No Fields | Return _all_ of your LP Tokens and receive as much as you can of both assets in the AMM's pool. |
| `tfTwoAsset` | `0x00100000` | `Amount` and `Amount2` | Withdraw 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 Value | Fields Specified | Meaning |
|-------------------------|--------------|--------------------------|---------|
| `tfSingleAsset` | `0x00080000` | `Amount` only | Withdraw exactly the specified amount of one asset, by returning as many LP Tokens as necessary. |
| `tfOneAssetWithdrawAll` | `0x00040000` | `Amount` only | Withdraw 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. |
| `tfOneAssetLPToken` | `0x00200000` | `Amount` and `LPTokenIn` | Withdraw up to the specified amount of one asset, by returning up to the specified amount of LP Tokens. |
| `tfLimitLPToken` | `0x00400000` | `Amount` and `EPrice` | Withdraw 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 performed 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.
<!-- TODO: add a formula and example calculation(s) of single-asset withdrawal fees -->
### AMMWithdraw Flags
Transactions of the AMMWithdraw type support additional values in the [`Flags` field](transaction-common-fields.html#flags-field), as follows:
| Flag Name | Hex Value | Decimal Value | Description |
|:------------------------|:-------------|:--------------|:----------------------|
| `tfLPToken` | `0x00010000` | 65536 | Perform a double-asset withdrawal and receive the specified amount of LP Tokens. |
| `tfWithdrawAll` | `0x00020000` | 131072 | Perform a double-asset withdrawal returning all your LP Tokens. |
| `tfOneAssetWithdrawAll` | `0x00040000` | 262144 | Perform a single-asset withdrawal returning all of your LP Tokens. |
| `tfSingleAsset` | `0x00080000` | 524288 | Perform a single-asset withdrawal with a specified amount of the asset to withdrawal. |
| `tfTwoAsset` | `0x00100000` | 1048576 | Perform a double-asset withdrawal with specified amounts of both assets. |
| `tfOneAssetLPToken` | `0x00200000` | 2097152 | Perform a single-asset withdrawal and receive the specified amount of LP Tokens. |
| `tfLimitLPToken` | `0x00400000` | 4194304 | Perform a single-asset withdrawal with a specified effective price. |
You must specify **exactly one** of these flags, in addition to any [global flags](transaction-common-fields.html#global-flags).
## Error Cases
In addition to errors that can occur for all transactions, {{currentpage.name}} transactions can result in the following [transaction result codes](transaction-results.html):
| Error Code | Description |
|:-------------------------|:---------------------------------------------|
| `tecFROZEN` | The transaction tried to deposit a [frozen](freezes.html) token. |
| `tecAMM_BALANCE` | The transaction would withdraw all of one asset from the pool, or rounding would cause a "withdraw all" to leave a nonzero amount behind. |
| `tecAMM_FAILED_WITHDRAW` | The conditions on the withdrawal could not be satisfied; for example, the requested effective price in the `EPrice` field is too low. |
| `tecAMM_INVALID_TOKENS` | The AMM for this token pair does not exist, or one of the calculations resulted in a withdrawal amount rounding to zero. |
| `tecINSUF_RESERVE_LINE` | The sender of this transaction does meet the increased [reserve requirement](reserves.html) 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_AUTH` | The sender is not authorized to hold one of the deposit assets. |
| `temBAD_AMM_OPTIONS` | The transaction specified an invalid combination of fields. See [AMMWithdraw Modes](#ammwithdraw-modes). |
| `temBAD_AMM_TOKENS` | The 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_AMM` | The Automated Market Maker instance for the asset pair in this transaction does not exist. |
<!--{# common link defs #}-->
{% include '_snippets/rippled-api-links.md' %}
{% include '_snippets/tx-type-links.md' %}
{% include '_snippets/rippled_versions.md' %}