mirror of
https://github.com/XRPLF/xrpl-dev-portal.git
synced 2025-11-20 11:45:50 +00:00
Improve Docs for Decentralized Exchange (#1357)
* Decentralized Exchange concept article 1st draft * DEX: example trade diagram, offers rewording * Offers: more rewriting/updates * OfferCreate: Add error cases + other updates * Known Amendments: fix tecEXPIRED, DepositPreauth - tecEXPIRED was initially attached to the Checks amendment but got moved to DepositPreauth before either became released. The docs weren't previously updated to reflect this change - A change to the snippets caused the DepositPreauth amendment reference link to get overwritten so the table links to the feature page rather than the amendment description. Special cases this one link. * OfferCreate error cases: switch to table * DEX/Offers: edits per review
This commit is contained in:
Rome Reginelli
@@ -9,9 +9,7 @@ labels:
|
||||
|
||||
[[Source]](https://github.com/ripple/rippled/blob/master/src/ripple/app/tx/impl/CreateOffer.cpp "Source")
|
||||
|
||||
An OfferCreate transaction is effectively a [limit order](http://en.wikipedia.org/wiki/limit_order). It defines an intent to exchange currencies, and creates an [Offer object](offer.html) if not completely fulfilled when placed. Offers can be partially fulfilled.
|
||||
|
||||
For more information about how Offers work, see [Offers](offers.html).
|
||||
An OfferCreate transaction places an [Offer](offers.html) in the [decentralized exchange](decentralized-exchange.html).
|
||||
|
||||
## Example {{currentpage.name}} JSON
|
||||
|
||||
@@ -38,10 +36,10 @@ For more information about how Offers work, see [Offers](offers.html).
|
||||
|
||||
| Field | JSON Type | [Internal Type][] | Description |
|
||||
|:---------------|:--------------------|:------------------|:------------------|
|
||||
| [`Expiration`](offers.html#offer-expiration) | Number | UInt32 | _(Optional)_ Time after which the offer is no longer active, in [seconds since the Ripple Epoch][]. |
|
||||
| `OfferSequence` | Number | UInt32 | _(Optional)_ An offer to delete first, specified in the same way as [OfferCancel][]. |
|
||||
| `TakerGets` | [Currency Amount][] | Amount | The amount and type of currency being provided by the offer creator. |
|
||||
| `TakerPays` | [Currency Amount][] | Amount | The amount and type of currency being requested by the offer creator. |
|
||||
| [`Expiration`](offers.html#offer-expiration) | Number | UInt32 | _(Optional)_ Time after which the Offer is no longer active, in [seconds since the Ripple Epoch][]. |
|
||||
| `OfferSequence` | Number | UInt32 | _(Optional)_ An Offer to delete first, specified in the same way as [OfferCancel][]. |
|
||||
| `TakerGets` | [Currency Amount][] | Amount | The amount and type of currency being sold. |
|
||||
| `TakerPays` | [Currency Amount][] | Amount | The amount and type of currency being bought. |
|
||||
|
||||
## OfferCreate Flags
|
||||
|
||||
@@ -49,18 +47,32 @@ Transactions of the OfferCreate type support additional values in the [`Flags` f
|
||||
|
||||
| Flag Name | Hex Value | Decimal Value | Description |
|
||||
|:----------------------|:-------------|:--------------|:----------------------|
|
||||
| `tfPassive` | `0x00010000` | 65536 | If enabled, the offer does not consume offers that exactly match it, and instead becomes an Offer object in the ledger. It still consumes offers that cross it. |
|
||||
| `tfImmediateOrCancel` | `0x00020000` | 131072 | Treat the offer as an [Immediate or Cancel order](http://en.wikipedia.org/wiki/Immediate_or_cancel). If enabled, the offer never becomes a ledger object: it only tries to match existing offers in the ledger. If the offer cannot match any offers immediately, it executes "successfully" without trading any currency. In this case, the transaction has the [result code](transaction-results.html) `tesSUCCESS`, but creates no [Offer objects](offer.html) in the ledger. |
|
||||
| `tfFillOrKill` | `0x00040000` | 262144 | Treat the offer as a [Fill or Kill order](http://en.wikipedia.org/wiki/Fill_or_kill). Only try to match existing offers in the ledger, and only do so if the entire `TakerPays` quantity can be obtained. If the [fix1578 amendment][] is enabled and the offer cannot be executed when placed, the transaction has the [result code](transaction-results.html) `tecKILLED`; otherwise, the transaction uses the result code `tesSUCCESS` even when it was killed without trading any currency. |
|
||||
| `tfPassive` | `0x00010000` | 65536 | If enabled, the Offer does not consume Offers that exactly match it, and instead becomes an Offer object in the ledger. It still consumes Offers that cross it. |
|
||||
| `tfImmediateOrCancel` | `0x00020000` | 131072 | Treat the Offer as an [Immediate or Cancel order](http://en.wikipedia.org/wiki/Immediate_or_cancel). The Offer never creates an [Offer object][] in the ledger: it only trades as much as it can by consuming existing Offers at the time the transaction is processed. If no Offers match, it executes "successfully" without trading anything. In this case, the transaction still uses the [result code](transaction-results.html) `tesSUCCESS`. |
|
||||
| `tfFillOrKill` | `0x00040000` | 262144 | Treat the offer as a [Fill or Kill order](http://en.wikipedia.org/wiki/Fill_or_kill). The Offer never creates an [Offer object][] in the ledger, and is canceled if it cannot be fully filled at the time of execution. By default, this means that the owner must receive the full `TakerPays` amount; if the `tfSell` flag is enabled, the owner must be able to spend the entire `TakerGets` amount instead. |
|
||||
| `tfSell` | `0x00080000` | 524288 | Exchange the entire `TakerGets` amount, even if it means obtaining more than the `TakerPays` amount in exchange. |
|
||||
|
||||
The following invalid flag combination prompts a `temINVALID_FLAG` error:
|
||||
|
||||
* `tfImmediateOrCancel` and `tfFillOrKill`
|
||||
|
||||
|
||||
|
||||
## Error Cases
|
||||
|
||||
| Error Code | Description |
|
||||
|:-------------------------|:--------------------------------------------------|
|
||||
| `temINVALID_FLAG` | Occurs if the transaction specifies both `tfImmediateOrCancel` and `tfFillOrKill`. |
|
||||
| `tecEXPIRED` | Occurs if the transaction specifies an `Expiration` time that has already passed _(Updated by the [DepositPreauth amendment][]: previously, the transaction used the result code `tesSUCCESS` in this case. In either case, the transaction has no effect except to destroy the XRP paid as a [transaction cost](transaction-cost.html).)_ |
|
||||
| `tecKILLED` | Occurs if the transaction specifies `tfFillOrKill`, and the full amount cannot be filled. _(Updated by the [fix1578 amendment][]: previously, the transaction used the result code `tesSUCCESS` in this case. In either case, the transaction does not execute any trades.)_ |
|
||||
| `temBAD_EXPIRATION` | Occurs if the transaction contains an `Expiration` field that is not validly formatted. |
|
||||
| `temBAD_SEQUENCE` | Occurs if the transaction contains an `OfferSequence` that is not validly formatted, or is higher than the transaction's own `Sequence` number. |
|
||||
| `temBAD_OFFER` | Occurs if the Offer tries to trade XRP for XRP, or tries to trade an invalid or negative amount of a token. |
|
||||
| `temREDUNDANT` | Occurs if the transaction specifies a token for the same token (same issuer and currency code). |
|
||||
| `temBAD_CURRENCY` | Occurs if the transaction specifies a token with the currency code "XRP". |
|
||||
| `temBAD_ISSUER` | Occurs if the transaction specifies a token with an invalid `issuer` value. |
|
||||
| `tecNO_ISSUER` | Occurs if the transaction specifies a token whose `issuer` value is not a funded account in the ledger. |
|
||||
| `tecFROZEN` | Occurs if the transaction involves a token on a [frozen](freezes.html) trust line (including local and global freezes). |
|
||||
| `tecUNFUNDED_OFFER` | Occurs if the owner does not hold a positive amount of the `TakerGets` currency. (Exception: if `TakerGets` specifies a token that the owner issues, the transaction can succeed.) |
|
||||
| `tecNO_LINE` | Occurs if the transaction involves a token whose issuer uses [Authorized Trust Lines](authorized-trust-lines.html) and the necessary trust line does not exist. |
|
||||
| `tecNO_AUTH` | Occurs if the transaction involves a token whose issuer uses [Authorized Trust Lines](authorized-trust-lines.html) and the the trust line that would receive the tokens exists but has not been authorized. |
|
||||
| `tecINSUF_RESERVE_OFFER` | Occurs if the owner does not have enough XRP to meet the reserve requirement of adding a new Offer object to the ledger, and the transaction did not convert any currency. (If the transaction successfully traded any amount, the transaction succeeds with the result code `tesSUCCESS`, but does not create an Offer object in the ledger for the remainder.) |
|
||||
| `tecDIR_FULL` | Occurs if the owner owns too many items in the ledger, or the order book contains too many Offers at the same exchange rate already. |
|
||||
|
||||
|
||||
|
||||
|
||||
Reference in New Issue
Block a user