diff --git a/docs/references/protocol/transactions/types/offercreate.md b/docs/references/protocol/transactions/types/offercreate.md index b44a638311..8dc751f57b 100644 --- a/docs/references/protocol/transactions/types/offercreate.md +++ b/docs/references/protocol/transactions/types/offercreate.md @@ -34,15 +34,15 @@ An OfferCreate transaction places an [Offer](../../../../concepts/tokens/decentr {% tx-example txid="0CD69FD1F0A890CC57CDA430213FD294F7D65FF4A0F379A0D09D07A222D324E6" /%} {% raw-partial file="/docs/_snippets/tx-fields-intro.md" /%} - -| Field | JSON Type | [Internal Type][] | Description | -|:---------------|:--------------------|:------------------|:------------------| -| [`Expiration`](../../../../concepts/tokens/decentralized-exchange/offers.md#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. | +| Field | JSON Type | [Internal Type][] | Required? | Description | +|:-----------------|:--------------------|:------------------|:----------|-------------| +| `DomainID` | String - [Hash][] | Hash256 | No | The ledger entry ID of a permissioned domain. If provided, restrict this offer to the [permissioned DEX](../../../../concepts/permissioned-dexes.md) of that domain. _(Requires the [PermissionedDEX amendment][] {% not-enabled /%})_ | +| [`Expiration`](../../../../concepts/tokens/decentralized-exchange/offers.md#offer-expiration) | Number | UInt32 | No | Time after which the Offer is no longer active, in [seconds since the Ripple Epoch][]. | +| `OfferSequence` | Number | UInt32 | No | An Offer to delete first, specified in the same way as [OfferCancel][]. | +| `TakerGets` | [Currency Amount][] | Amount | Yes | The amount and type of currency being sold. | +| `TakerPays` | [Currency Amount][] | Amount | Yes | The amount and type of currency being bought. | ## OfferCreate Flags @@ -50,31 +50,33 @@ 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). 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/index.md) `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. | +| `tfPassive` | `0x00010000` | 65536 | Do not consume offers that exactly match this one, only offers that cross it. This makes it possible to set up offers in the ledger that peg the exchange rate at a specific value. | +| `tfImmediateOrCancel` | `0x00020000` | 131072 | Treat the offer as an [Immediate or Cancel order](http://en.wikipedia.org/wiki/Immediate_or_cancel) and do not place an [Offer entry][] into the order books. The transaction trades as much as it can by consuming existing offers when it's processed. | +| `tfFillOrKill` | `0x00040000` | 262144 | Treat the offer as a [Fill or Kill order](http://en.wikipedia.org/wiki/Fill_or_kill), do not place an [Offer entry][] into the order books, and cancel the offer 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. | +| `tfHybrid` | `0x00100000` | 1048576 | Make this a hybrid offer that can use both a permissioned DEX and the open DEX. The `DomainID` field must be provided when using this flag. | ## 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. | -| `tecKILLED` | Occurs if the transaction specifies `tfFillOrKill`, and the full amount cannot be filled. If the _[ImmediateOfferKilled amendment][]_ is enabled, this result code also occurs when the transaction specifies `tfImmediateOrCancel` and executes without moving funds (previously, this would return `tesSUCCESS`). | -| `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](../../../../concepts/tokens/fungible-tokens/freezes.md) trust line (including local and global freezes). Occurs if the `TakerPays` (buy amount) token has been deep-frozen by the issuer. | -| `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](../../../../concepts/tokens/fungible-tokens/authorized-trust-lines.md) and the necessary trust line does not exist. | -| `tecNO_AUTH` | Occurs if the transaction involves a token whose issuer uses [Authorized Trust Lines](../../../../concepts/tokens/fungible-tokens/authorized-trust-lines.md) 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 rest.) | -| `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. | +| `temINVALID_FLAG` | The transaction specifies an invalid flag combination, such as both `tfImmediateOrCancel` and `tfFillOrKill`, or the transaction uses `tfHybrid` but omits the `DomainID` field. | +| `tecEXPIRED` | The transaction specifies an `Expiration` time that has already passed. | +| `tecKILLED` | The transaction specifies `tfFillOrKill`, and the full amount cannot be filled. If the _[ImmediateOfferKilled amendment][]_ is enabled, this result code also occurs when the transaction specifies `tfImmediateOrCancel` and executes without moving funds (previously, an Immediate or Cancel offer would return `tesSUCCESS` even if no funds were moved). | +| `temBAD_EXPIRATION` | The transaction contains an `Expiration` field that is not validly formatted. | +| `temBAD_SEQUENCE` | The transaction contains an `OfferSequence` that is not validly formatted, or is higher than the transaction's own `Sequence` number. | +| `temBAD_OFFER` | The offer tries to trade XRP for XRP, or tries to trade an invalid or negative amount of a token. | +| `temREDUNDANT` | The transaction specifies a token for the same token (same issuer and currency code). | +| `temBAD_CURRENCY` | The transaction specifies a token with the currency code "XRP". | +| `temBAD_ISSUER` | The transaction specifies a token with an invalid `issuer` value. | +| `tecNO_ISSUER` | The transaction specifies a token whose `issuer` value is not a funded account in the ledger. | +| `tecNO_PERMISSION` | The transaction uses a `DomainID` but the sender is not a member of that domain. _(Requires the [PermissionedDEX amendment][] {% not-enabled /%})_ | +| `tecFROZEN` | The transaction involves a token on a [frozen](../../../../concepts/tokens/fungible-tokens/freezes.md) trust line (including local and global freezes). The `TakerPays` (buy amount) token has been deep-frozen by the issuer. | +| `tecUNFUNDED_OFFER` | 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` | The transaction involves a token whose issuer uses [Authorized Trust Lines](../../../../concepts/tokens/fungible-tokens/authorized-trust-lines.md) and the necessary trust line does not exist. | +| `tecNO_AUTH` | The transaction involves a token whose issuer uses [Authorized Trust Lines](../../../../concepts/tokens/fungible-tokens/authorized-trust-lines.md) and the the trust line that would receive the tokens exists but has not been authorized. | +| `tecINSUF_RESERVE_OFFER` | 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 rest.) | +| `tecDIR_FULL` | The owner owns too many items in the ledger, or the order book contains too many Offers at the same exchange rate already. | {% raw-partial file="/docs/_snippets/common-links.md" /%} diff --git a/docs/references/protocol/transactions/types/payment.md b/docs/references/protocol/transactions/types/payment.md index 98231775e2..320e6ee93e 100644 --- a/docs/references/protocol/transactions/types/payment.md +++ b/docs/references/protocol/transactions/types/payment.md @@ -1,6 +1,4 @@ --- -html: payment.html -parent: transaction-types.html seo: description: Send funds from one account to another. labels: @@ -10,7 +8,7 @@ labels: - Tokens --- # Payment -[[Source]](https://github.com/XRPLF/rippled/blob/5425a90f160711e46b2c1f1c93d68e5941e4bfb6/src/ripple/app/transactors/Payment.cpp "Source") +[[Source]](https://github.com/XRPLF/rippled/blob/master/src/xrpld/app/tx/detail/Payment.cpp "Source") A Payment transaction represents a transfer of value from one account to another. (Depending on the path taken, this can involve additional exchanges of value, which occur atomically.) This transaction type can be used for several [types of payments](#types-of-payments). @@ -44,9 +42,10 @@ Payments are also the only way to [create accounts](#creating-accounts). | `Amount` | [Currency Amount][] | Amount | API v1: Yes | Alias to `DeliverMax`. | | `CredentialIDs` | Array of Strings | Vector256 | No | Set of Credentials to authorize a deposit made by this transaction. Each member of the array must be the ledger entry ID of a Credential entry in the ledger. _(Requires the [Credentials amendment][]._ {% not-enabled /%})_ | | `DeliverMax` | [Currency Amount][] | Amount | Yes | [API v2][]: The maximum amount of currency to deliver. [Partial payments](#partial-payments) can deliver less than this amount and still succeed; other payments fail unless they deliver the exact amount. {% badge href="https://github.com/XRPLF/rippled/releases/tag/2.0.0" %}New in: rippled 2.0.0{% /badge %} | -| `DeliverMin` | [Currency Amount][] | Amount | No | Minimum amount of destination currency this transaction should deliver. Only valid if this is a [partial payment](../../../../concepts/payment-types/partial-payments.md). For non-XRP amounts, the nested field names are lower-case. | +| `DeliverMin` | [Currency Amount][] | Amount | No | Minimum amount of destination currency this transaction should deliver. Only valid if this is a [partial payment](#partial-payments). For non-XRP amounts, the nested field names are lower-case. | | `Destination` | String | AccountID | Yes | The unique address of the account receiving the payment. | | `DestinationTag` | Number | UInt32 | No | Arbitrary tag that identifies the reason for the payment to the destination, or a hosted recipient to pay. | +| `DomainID` | String - [Hash][] | Hash256 | No | The ledger entry ID of a permissioned domain. If this is a cross-currency payment, only use the corresponding [permissioned DEX](../permissioned-dexes.md) to convert currency. Both the sender and the recipient must have valid credentials that grant access to the specified domain. This field has no effect if the payment is not cross-currency. _(Requires the [PermissionedDEX amendment][] {% not-enabled /%})_ | | `InvoiceID` | String | Hash256 | No | Arbitrary 256-bit hash representing a specific reason or identifier for this payment. | | `Paths` | Array of path arrays | PathSet | No | _(Auto-fillable)_ Array of [payment paths](../../../../concepts/tokens/fungible-tokens/paths.md) to be used for this transaction. Must be omitted for XRP-to-XRP transactions. | | `SendMax` | [Currency Amount][] | Amount | No | Highest amount of source currency this transaction is allowed to cost, including [transfer fees](../../../../concepts/tokens/transfer-fees.md), exchange rates, and [slippage](http://en.wikipedia.org/wiki/Slippage_%28finance%29). Does not include the [XRP destroyed as a cost for submitting the transaction](../../../../concepts/transactions/transaction-cost.md). Must be supplied for cross-currency/cross-issue payments. Must be omitted for XRP-to-XRP payments. | @@ -111,7 +110,7 @@ Transactions of the Payment type support additional values in the [`Flags` field | Flag Name | Hex Value | Decimal Value | Description | |:-------------------|:-------------|:--------------|:-----------------------------| | `tfNoRippleDirect` | `0x00010000` | 65536 | Do not use the default path; only use paths included in the `Paths` field. This is intended to force the transaction to take arbitrage opportunities. Most clients do not need this. | -| `tfPartialPayment` | `0x00020000` | 131072 | If the specified `Amount` cannot be sent without spending more than `SendMax`, reduce the received amount instead of failing outright. See [Partial Payments](../../../../concepts/payment-types/partial-payments.md) for more details. | +| `tfPartialPayment` | `0x00020000` | 131072 | If the specified `Amount` cannot be sent without spending more than `SendMax`, reduce the received amount instead of failing outright. See [Partial Payments](#partial-payments) for more details. | | `tfLimitQuality` | `0x00040000` | 262144 | Only take paths where all the conversions have an input:output ratio that is equal or better than the ratio of `Amount`:`SendMax`. See [Limit Quality](#limit-quality) for details. | ## Partial Payments