ARCHIVE/xrpl-dev-portal
1
0
Fork 0
mirror of https://github.com/XRPLF/xrpl-dev-portal.git synced 2025-12-01 17:15:51 +00:00
Code Issues Packages Projects Releases Wiki Activity

Re-level non-docs content to top of repo and rename content→docs

Browse Source
This commit is contained in:
mDuo13
2024-01-31 16:24:01 -08:00
parent f841ef173c
commit c10beb85c2
2907 changed files with 1 additions and 1 deletions
Download Patch File Download Diff File Expand all files Collapse all files

170
docs/references/protocol/transactions/common-fields.md Normal file
View File

@@ -0,0 +1,170 @@
---
html: transaction-common-fields.html
parent: transaction-formats.html
seo:
description: These common fields can be provided on any XRP Ledger transaction.
labels:
- Transaction Sending
---
# Transaction Common Fields
Every transaction has the same set of common fields, plus additional fields based on the [transaction type](types/index.md). Field names are case-sensitive. The common fields for all transactions are:
| Field | JSON Type | [Internal Type][] | Description |
|:---------------------|:-----------------|:------------------|:-----------------|
| `Account` | String | AccountID | _(Required)_ The unique address of the [account](../../../concepts/accounts/accounts.md) that initiated the transaction. |
| `TransactionType` | String | UInt16 | _(Required)_ The type of transaction. Valid [transaction types](types/index.md) include: `Payment`, `OfferCreate`, `TrustSet`, and many others. |
| `Fee` | String | Amount | _(Required; [auto-fillable][])_ Integer amount of XRP, in drops, to be destroyed as a cost for distributing this transaction to the network. Some transaction types have different minimum requirements. See [Transaction Cost][] for details. |
| `Sequence` | Number | UInt32 | _(Required; [auto-fillable][])_ The [sequence number](../data-types/basic-data-types.md#account-sequence) of the account sending the transaction. A transaction is only valid if the `Sequence` number is exactly 1 greater than the previous transaction from the same account. The special case `0` means the transaction is using a [Ticket](../../../concepts/accounts/tickets.md) instead _(Added by the [TicketBatch amendment][].)_. |
| [`AccountTxnID`](#accounttxnid) | String | Hash256 | _(Optional)_ Hash value identifying another transaction. If provided, this transaction is only valid if the sending account's previously-sent transaction matches the provided hash. |
| [`Flags`](#flags-field) | Number | UInt32 | _(Optional)_ Set of bit-flags for this transaction. |
| `LastLedgerSequence` | Number | UInt32 | _(Optional; strongly recommended)_ Highest ledger index this transaction can appear in. Specifying this field places a strict upper limit on how long the transaction can wait to be validated or rejected. See [Reliable Transaction Submission](../../../concepts/transactions/reliable-transaction-submission.md) for more details. |
| [`Memos`](#memos-field) | Array of Objects | Array | _(Optional)_ Additional arbitrary information used to identify this transaction. |
| [`NetworkID`](#networkid-field) | Number | UInt32 | _(Network-specific)_ The network ID of the chain this transaction is intended for. **MUST BE OMITTED** for Mainnet and some test networks. **REQUIRED** on chains whose network ID is 1025 or higher. |
| [`Signers`](#signers-field) | Array | Array | _(Optional)_ Array of objects that represent a [multi-signature](../../../concepts/accounts/multi-signing.md) which authorizes this transaction. |
| `SourceTag` | Number | UInt32 | _(Optional)_ Arbitrary integer used to identify the reason for this payment, or a sender on whose behalf this transaction is made. Conventionally, a refund should specify the initial payment's `SourceTag` as the refund payment's `DestinationTag`. |
| `SigningPubKey` | String | Blob | _(Automatically added when signing)_ Hex representation of the public key that corresponds to the private key used to sign this transaction. If an empty string, indicates a multi-signature is present in the `Signers` field instead. |
| `TicketSequence` | Number | UInt32 | _(Optional)_ The sequence number of the [ticket](../../../concepts/accounts/tickets.md) to use in place of a `Sequence` number. If this is provided, `Sequence` must be `0`. Cannot be used with `AccountTxnID`. |
| `TxnSignature` | String | Blob | _(Automatically added when signing)_ The signature that verifies this transaction as originating from the account it says it is from. |
[auto-fillable]: #auto-fillable-fields
{% badge href="https://github.com/XRPLF/rippled/releases/tag/0.28.0" %}Removed in: rippled 0.28.0{% /badge %}: The `PreviousTxnID` field of transactions was replaced by the [`AccountTxnID`](#accounttxnid) field. This String / Hash256 field is present in some historical transactions. This is unrelated to the field also named `PreviousTxnID` in some [ledger objects](../ledger-data/index.md).
## AccountTxnID
<!-- SPELLING_IGNORE: AccountTxnID -->
The `AccountTxnID` field lets you chain your transactions together, so that a current transaction is not valid unless the previous transaction sent from the same account has a specific [transaction hash][identifying hash].
Unlike the `PreviousTxnID` field, which tracks the last transaction to _modify_ an account (regardless of sender), the `AccountTxnID` tracks the last transaction _sent by_ an account. To use `AccountTxnID`, you must first enable the [`asfAccountTxnID`](types/accountset.md#accountset-flags) flag, so that the ledger keeps track of the ID for the account's previous transaction. (`PreviousTxnID`, by comparison, is always tracked.)
One situation in which this is useful is if you have a primary system for submitting transactions and a passive backup system. If the passive backup system becomes disconnected from the primary, but the primary is not fully dead, and they both begin operating at the same time, you could potentially have serious problems like some transactions sending twice and others not at all. Chaining your transactions together with `AccountTxnID` ensures that, even if both systems are active, only one of them can submit valid transactions at a time.
The `AccountTxnID` field cannot be used on transactions that use [Tickets](../../../concepts/accounts/tickets.md). Transactions that use `AccountTxnID` cannot be placed in the [transaction queue](../../../concepts/transactions/transaction-queue.md).
## Auto-fillable Fields
Some fields can be automatically filled in before a transaction is signed, either by a `rippled` server or by a [client library](../../client-libraries.md). Auto-filling values requires an active connection to the XRP Ledger to get the latest state, so it cannot be done offline. The details can vary by library, but auto-filling always provides suitable values for at least the following fields:
* `Fee` - Automatically fill in the [Transaction Cost][] based on the network.
**Note:** When using `rippled`'s [sign command][], you can limit the maximum possible auto-filled value, using the `fee_mult_max` and `fee_div_max` parameters.)
* `Sequence` - Automatically use the next sequence number for the account sending the transaction.
For a production system, we recommend _not_ leaving these fields to be filled by the server. For example, if transaction costs become high due to a temporary spike in network load, you may want to wait for the cost to decrease before sending some transactions, instead of paying the temporarily-high cost.
The [`Paths` field](types/payment.md#paths) of the [Payment transaction][] type can also be automatically filled in.
## Flags Field
The `Flags` field can contain various options that affect how a transaction should behave. The options are represented as binary values that can be combined with bitwise-or operations to set multiple flags at once.
To check whether a transaction has a given flag enabled, use the bitwise-and operator on the flag's value and the `Flags` field. A result of zero indicates the flag is disabled, and a result equal to the flag value indicates the flag is enabled. (If you got any other result, you did something wrong.)
Most flags only have meaning for a specific transaction type. The same bitwise value may be reused for flags on different transaction types, so it is important to pay attention to the `TransactionType` field when setting and reading flags.
Bits that are not defined as flags MUST be 0. (The [fix1543 amendment][] enforces this rule on some transaction types. Most transaction types enforce this rule by default.)
### Global Flags
The only flag that applies globally to all transactions is as follows:
| Flag Name | Hex Value | Decimal Value | Description |
|:----------------------|:-----------|:--------------|:--------------------------|
| `tfFullyCanonicalSig` | `0x80000000` | 2147483648 | **DEPRECATED** No effect. (If the [RequireFullyCanonicalSig amendment][] is not enabled, this flag enforces a [fully-canonical signature](../../../concepts/transactions/finality-of-results/transaction-malleability.md#alternate-secp256k1-signatures).) |
When using the [sign method][] (or [submit method][] in "sign-and-submit" mode), `rippled` adds a `Flags` field with `tfFullyCanonicalSig` enabled unless the `Flags` field is already present. The `tfFullyCanonicalSig` flag is not automatically enabled if `Flags` is explicitly specified. The flag is not automatically enabled when using the [sign_for method][] to add a signature to a multi-signed transaction.
**Note:** The `tfFullyCanonicalSig` flag was used from 2014 until 2020 to protect against [transaction malleability](../../../concepts/transactions/finality-of-results/transaction-malleability.md) while maintaining compatibility with legacy signing software. The [RequireFullyCanonicalSig amendment][] ended compatibility with such legacy software and made the protections the default for all transactions. If you are using a [parallel network](../../../concepts/networks-and-servers/parallel-networks.md) that does not have RequireFullyCanonicalSig enabled, you should always enable the `tfFullyCanonicalSig` flag to protect against transaction malleability.
### Flag Ranges
A transaction's `Flags` field can contain flags that apply at different levels or contexts. Flags for each context are limited to the following ranges:
| Range Name | Bit Mask | Description |
|:-----------------|:-------------|:-------------------------------------------|
| Universal Flags | `0xff000000` | Flags that apply equally to all transaction types. |
| Type-based Flags | `0x00ff0000` | Flags with different meanings depending on the [transaction type](types/index.md) that uses them. |
| Reserved Flags | `0x0000ffff` | Flags that are not currently defined. A transaction is only valid if these flags are disabled. |
**Note:** The [AccountSet transaction][] type has [its own non-bitwise flags](types/accountset.md#accountset-flags), which serve a similar purpose to type-based flags. [Ledger objects](../ledger-data/ledger-entry-types/index.md) also have a `Flags` field with different bitwise flag definitions.
## Memos Field
The `Memos` field includes arbitrary messaging data with the transaction. It is presented as an array of objects. Each object has only one field, `Memo`, which in turn contains another object with *one or more* of the following fields:
| Field | Type | [Internal Type][] | Description |
|:-------------|:-------|:------------------|:---------------------------------|
| `MemoData` | String | Blob | Arbitrary hex value, conventionally containing the content of the memo. |
| `MemoFormat` | String | Blob | Hex value representing characters allowed in URLs. Conventionally containing information on how the memo is encoded, for example as a [MIME type](http://www.iana.org/assignments/media-types/media-types.xhtml). |
| `MemoType` | String | Blob | Hex value representing characters allowed in URLs. Conventionally, a unique relation (according to [RFC 5988](http://tools.ietf.org/html/rfc5988#section-4)) that defines the format of this memo. |
The `MemoType` and `MemoFormat` fields should only consist of the following characters: `ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789-._~:/?#[]@!$&'()*+,;=%`
The `Memos` field is limited to no more than 1 KB in size (when serialized in binary format).
Example of a transaction with a Memos field:
```json
{
"TransactionType": "Payment",
"Account": "rMmTCjGFRWPz8S2zAUUoNVSQHxtRQD4eCx",
"Destination": "r3kmLJN5D28dHuH8vZNUZpMC43pEHpaocV",
"Memos": [
{
"Memo": {
"MemoType": "687474703a2f2f6578616d706c652e636f6d2f6d656d6f2f67656e65726963",
"MemoData": "72656e74"
}
}
],
"Amount": "1"
}
```
## NetworkID Field
{% badge href="https://github.com/XRPLF/rippled/releases/tag/1.11.0" %}New in: rippled 1.11.0{% /badge %}
The `NetworkID` field is a protection against "cross-chain" transaction replay attacks, preventing the same transaction from being copied over and executing on a [parallel network](../../../concepts/networks-and-servers/parallel-networks.md) that it wasn't intended for. For compatibility with existing chains, the `NetworkID` field must be omitted on any network with a Network ID of 1024 or less, but must be included on any network with a Network ID of 1025 or greater. The following table shows the status and values for various known networks:
| Network | ID | `NetworkID` Field |
|---------------|----|-------------------|
| Mainnet | 0 | Disallowed |
| Testnet | 1 | Disallowed |
| Devnet | 2 | Disallowed |
| AMM Devnet | 25 | Disallowed |
| Sidechains Devnet Locking Chain | 2551 | Disallowed, but will become required after an update |
| Sidechains Devnet Issuing Chain | 2552 | Disallowed, but will become required after an update |
| Hooks V3 Testnet | 21338 | Required |
Transaction replay attacks are theoretically possible, but require specific conditions on the second network. All of the following must be true:
- The transaction's sender is a funded account on the second network.
- The sender's `Sequence` number on the second network matches the transaction's `Sequence`, or the transaction uses a [Ticket](../../../concepts/accounts/tickets.md) that's available on the second network.
- Either the transaction does not have a `LastLedgerSequence` field, or it specifies a value that is higher than the current ledger index on the second ledger.
- Mainnet generally has a higher ledger index than test networks or sidechains, so it is easier to replay Mainnet transactions on a sidechain or test network than the other way around, when transactions use `LastLedgerSequence` as intended.
- Either the networks both have IDs of 1024 or less, both networks use the same ID, or the second network does not require the `NetworkID` field.
## Signers Field
The `Signers` field contains a [multi-signature](../../../concepts/accounts/multi-signing.md), which has signatures from up to 32 key pairs, that together should authorize the transaction. The `Signers` list is an array of objects, each with one field, `Signer`. The `Signer` field has the following nested fields:
| Field | Type | [Internal Type][] | Description |
|:----------------|:-------|:------------------|:--------------------------------|
| `Account` | String | AccountID | The address associated with this signature, as it appears in the signer list. |
| `TxnSignature` | String | Blob | A signature for this transaction, verifiable using the `SigningPubKey`. |
| `SigningPubKey` | String | Blob | The public key used to create this signature. |
The `SigningPubKey` must be a key that is associated with the `Account` address. If the referenced `Account` is a funded account in the ledger, then the `SigningPubKey` can be that account's current Regular Key if one is set. It could also be that account's Master Key, unless the [`lsfDisableMaster`](../ledger-data/ledger-entry-types/accountroot.md#accountroot-flags) flag is enabled. If the referenced `Account` address is not a funded account in the ledger, then the `SigningPubKey` must be the master key associated with that address.
Because signature verification is a compute-intensive task, multi-signed transactions cost additional XRP to relay to the network. Each signature included in the multi-signature increases the [transaction cost][] required for the transaction. For example, if the current minimum transaction cost to relay a transaction to the network is `10000` drops, then a multi-signed transaction with 3 entries in the `Signers` array would need a `Fee` value of at least `40000` drops to relay.
{% raw-partial file="/_snippets/common-links.md" /%}

16
docs/references/protocol/transactions/index.md Normal file
View File

@@ -0,0 +1,16 @@
---
html: transaction-formats.html
parent: protocol-reference.html
seo:
description: Definitions for all the protocol's transaction types and their results.
metadata:
indexPage: true
---
# Transaction Reference
A _Transaction_ is the only way to cause changes in the XRP Ledger. Transactions' outcomes are only [final](../../../concepts/transactions/finality-of-results/index.md) if signed, submitted, and accepted into a validated ledger version following the [consensus process](../../../concepts/consensus-protocol/index.md). Some ledger rules also generate _[pseudo-transactions](pseudo-transaction-types/pseudo-transaction-types.md)_, which aren't signed or submitted, but still must be accepted by consensus. Transactions that fail are also included in ledgers because they modify balances of XRP to pay for the anti-spam [transaction cost][].
{% raw-partial file="/_snippets/common-links.md" /%}
{% child-pages /%}

98
docs/references/protocol/transactions/metadata.md Normal file
View File

@@ -0,0 +1,98 @@
---
html: transaction-metadata.html
parent: transaction-formats.html
seo:
description: Transaction metadata describes the outcome of the transaction in detail, regardless of whether the transaction is successful.
labels:
- Blockchain
---
# Transaction Metadata
Transaction metadata is a section of data that gets added to a transaction after it is processed. Any transaction that gets included in a ledger has metadata, regardless of whether it is successful. The transaction metadata describes the outcome of the transaction in detail.
**Warning:** The changes described in transaction metadata are only final if the transaction is in a validated ledger version.
Some fields that may appear in transaction metadata include:
{% partial file="/_snippets/tx-metadata-field-table.md" /%}
## Example Metadata
The following JSON object shows the metadata for [a complex cross-currency payment](https://livenet.xrpl.org/transactions/8C55AFC2A2AA42B5CE624AEECDB3ACFDD1E5379D4E5BF74A8460C5E97EF8706B):
{% code-snippet file="/_api-examples/metadata/cross-currency-payment.json" language="json" /%}
## AffectedNodes
The `AffectedNodes` array contains a complete list of the [ledger entries](../ledger-data/ledger-entry-types/index.md) that this transaction modified in some way. Each item in this array is an object with one top-level field indicating what happened:
- `CreatedNode` indicates that the transaction created a new ledger entry.
- `DeletedNode` indicates that the transaction removed a ledger entry
- `ModifiedNode` indicates that the transaction modified an existing ledger entry.
The value of each of these fields is a JSON object describing the changes made to the ledger entry.
### CreatedNode Fields
A `CreatedNode` object contains the following fields:
| Field | Value | Description |
|:------------------|:------------------|:-------------------------------------|
| `LedgerEntryType` | String | The [type of ledger entry](../ledger-data/ledger-entry-types/index.md) that was created. |
| `LedgerIndex` | String - [Hash][] | The [ID of this ledger entry](../ledger-data/common-fields.md) in the ledger's [state tree](../../../concepts/ledgers/index.md). **Note:** This is **not the same** as a [ledger index](../data-types/basic-data-types.md#ledger-index), even though the field name is very similar. |
| `NewFields` | Object | The content fields of the newly-created ledger entry. Which fields are present depends on what type of ledger entry was created. |
### DeletedNode Fields
A `DeletedNode` object contains the following fields:
| Field | Value | Description |
|:------------------|:------------------|:-------------------------------------|
| `LedgerEntryType` | String | The [type of ledger entry](../ledger-data/ledger-entry-types/index.md) that was deleted. |
| `LedgerIndex` | String - [Hash][] | The [ID of this ledger entry](../ledger-data/common-fields.md) in the ledger's [state tree](../../../concepts/ledgers/index.md). **Note:** This is **not the same** as a [ledger index](../data-types/basic-data-types.md#ledger-index), even though the field name is very similar. |
| `FinalFields` | Object | The content fields of the ledger entry immediately before it was deleted. Which fields are present depends on what type of ledger entry was created. |
### ModifiedNode Fields
A `ModifiedNode` object contains the following fields:
| Field | Value | Description |
|:--------------------|:--------------------------|:---------------------------|
| `LedgerEntryType` | String | The [type of ledger entry](../ledger-data/ledger-entry-types/index.md) that was modified. |
| `LedgerIndex` | String - [Hash][] | The [ID of this ledger entry](../ledger-data/common-fields.md) in the ledger's [state tree](../../../concepts/ledgers/index.md). **Note:** This is **not the same** as a [ledger index](../data-types/basic-data-types.md#ledger-index), even though the field name is very similar. |
| `FinalFields` | Object | The content fields of the ledger entry after applying any changes from this transaction. Which fields are present depends on what type of ledger entry was created. This omits the `PreviousTxnID` and `PreviousTxnLgrSeq` fields, even though most types of ledger entries have them. |
| `PreviousFields` | Object | The previous values for all fields of the object that were changed as a result of this transaction. If the transaction _only added_ fields to the object, this field is an empty object. |
| `PreviousTxnID` | String - [Hash][] | _(May be omitted)_ The [identifying hash][] of the previous transaction to modify this ledger entry. Omitted for ledger entry types that do not have a `PreviousTxnID` field. |
| `PreviousTxnLgrSeq` | Number - [Ledger Index][] | _(May be omitted)_ The [Ledger Index][] of the ledger version containing the previous transaction to modify this ledger entry. Omitted for ledger entry types that do not have a `PreviousTxnLgrSeq` field. |
**Note:** If the modified ledger entry has `PreviousTxnID` and `PreviousTxnLgrSeq` fields, the transaction always updates them with the transaction's own identifying hash and the index of the ledger version that included the transaction, but these fields' new value is not listed in the `FinalFields` of the `ModifiedNode` object, and their previous values are listed at the top level of the `ModifiedNode` object rather than in the nested `PreviousFields` object.
## NFT Fields
Transactions (`tx` and `account_tx`) involving NFTs can contain the following fields in the metadata. These values are added by the Clio server at request time and are not stored in the hashed binary metadata:
| Field | Value | Description |
|:--------------------|:--------------------------|:---------------------------|
| `nftoken_id` | String | Shows the `NFTokenID` for the `NFToken` that changed on the ledger as a result of the transaction. Only present if the transaction is `NFTokenMint` or `NFTokenAcceptOffer`. See [NFTokenID](../data-types/nftoken.md#nftokenid). |
| `nftoken_ids` | Array | Shows all the `NFTokenIDs` for the `NFTokens` that changed on the ledger as a result of the transaction. Only present if the transaction is `NFTokenCancelOffer`. |
| `offer_id` | String | Shows the `OfferID`of a new `NFTokenOffer` in a response from a `NFTokenCreateOffer` transaction. |
## delivered_amount
The `Amount` of a [Payment transaction][] indicates the amount to deliver to the `Destination`, so if the transaction was successful, then the destination received that much -- **except if the transaction was a [partial payment](../../../concepts/payment-types/partial-payments.md)**. (In that case, any positive amount up to `Amount` might have arrived.) Rather than choosing whether or not to trust the `Amount` field, you should use the `delivered_amount` field of the metadata to see how much actually reached its destination.
The `rippled` server provides a `delivered_amount` field in JSON transaction metadata for all successful Payment transactions. This field is formatted like a normal currency amount. However, the delivered amount is not available for transactions that meet both of the following criteria:
* Is a partial payment
* Included in a validated ledger before 2014-01-20
If both conditions are true, then `delivered_amount` contains the string value `unavailable` instead of an actual amount. If this happens, you can only figure out the actual delivered amount by reading the `AffectedNodes` in the transaction's metadata.
**Note:** The `delivered_amount` field is generated on-demand for the request, and is not included in the binary format for transaction metadata, nor is it used when calculating the [hash](../data-types/basic-data-types.md#hashes) of the transaction metadata. In contrast, the `DeliveredAmount` field _is_ included in the binary format for partial payment transactions after 2014-01-20.
See also: [Partial Payments](../../../concepts/payment-types/partial-payments.md)
<!--{# Spell-check can ignore these field names used in headings #}-->
<!-- SPELLING_IGNORE: affectednodes, creatednode, deletednode, modifiednode, delivered_amount -->
{% raw-partial file="/_snippets/common-links.md" /%}

62
docs/references/protocol/transactions/pseudo-transaction-types/enableamendment.md Normal file
View File

@@ -0,0 +1,62 @@
---
html: enableamendment.html
parent: pseudo-transaction-types.html
seo:
description: Enable a change in transaction processing.
labels:
- Blockchain
---
# EnableAmendment
An `EnableAmendment` pseudo-transaction marks a change in the status of a proposed amendment when it:
- Gains supermajority approval from validators.
- Loses supermajority approval.
- Is enabled on the XRP Ledger protocol.
<!-- TODO: Move to propose amendments tutorial.
A server only enables amendments when these conditions are met:
- A previous ledger includes an `EnableAmendment` pseudo-transaction with the `tfGotMajority` flag enabled.
- The previous ledger in question is an ancestor of the current ledger.
- The previous ledger in question has a close time that is at least two weeks before the close time of the latest flag ledger.
- There are no `EnableAmendment` pseudo-transactions for this amendment with the `tfLostMajority` flag enabled in the consensus ledgers between the `tfGotMajority` pseudo-transaction and the current ledger.
-->
## Example {% $frontmatter.seo.title %} JSON
```json
{
"Account": "rrrrrrrrrrrrrrrrrrrrrhoLvTp",
"Amendment": "42426C4D4F1009EE67080A9B7965B44656D7714D104A72F9B4369F97ABF044EE",
"Fee": "0",
"LedgerSequence": 21225473,
"Sequence": 0,
"SigningPubKey": "",
"TransactionType": "EnableAmendment"
}
```
{% partial file="/_snippets/pseudo-tx-fields-intro.md" /%}
<!--{# fix md highlighting_ #}-->
| Field | JSON Type | [Internal Type][] | Description |
|:-----------------|:----------|:------------------|:--------------------------|
| `Amendment` | String | Hash256 | A unique identifier for the amendment. This is not intended to be a human-readable name. See [Amendments](../../../../concepts/networks-and-servers/amendments.md) for a list of known amendments. |
| `LedgerSequence` | Number | UInt32 | The [ledger index][] where this pseudo-transaction appears. This distinguishes the pseudo-transaction from other occurrences of the same change. |
## EnableAmendment Flags
The `Flags` value of the EnableAmendment pseudo-transaction indicates the status of the amendment at the time of the ledger including the pseudo-transaction.
A `Flags` value of `0` (no flags) or an omitted `Flags` field indicates that the amendment has been enabled, and applies to all ledgers afterward. Other `Flags` values are as follows:
| Flag Name | Hex Value | Decimal Value | Description |
|:-----------------|:-------------|:--------------|:---------------------------|
| `tfGotMajority` | `0x00010000` | 65536 | Support for this amendment increased to at least 80% of trusted validators starting with this ledger version. |
| `tfLostMajority` | `0x00020000` | 131072 | Support for this amendment decreased to less than 80% of trusted validators starting with this ledger version. |
{% raw-partial file="/_snippets/common-links.md" /%}

40
docs/references/protocol/transactions/pseudo-transaction-types/pseudo-transaction-types.md Normal file
View File

@@ -0,0 +1,40 @@
---
html: pseudo-transaction-types.html
parent: transaction-formats.html
seo:
description: Formats of pseudo-transactions that validators sometimes apply to the XRP Ledger.
metadata:
indexPage: true
labels:
- Blockchain
---
# Pseudo-Transactions
Pseudo-transactions are never submitted by users, nor [propagated through the network](../../../../concepts/networks-and-servers/peer-protocol.md). Instead, a server may choose to inject pseudo-transactions in a proposed ledger directly according to specific protocol rules. If enough servers propose the exact same pseudo-transaction, the [consensus process](../../../../concepts/consensus-protocol/index.md) approves it, and the pseudo-transaction is included in that ledger's transaction data.
## Special Values for Common Fields
Some of the required [common fields][] for normal transactions do not make sense for pseudo-transactions. Pseudo-transactions use following special values for these common fields:
| Field | JSON Type | [Internal Type][] | Value |
|:----------------|:----------|:------------------|:---------------------------|
| `Account` | String | AccountID | [ACCOUNT_ZERO](../../../../concepts/accounts/addresses.md#special-addresses) |
| `Fee` | String | Amount | `0` |
| `Sequence` | Number | UInt32 | `0` |
| `SigningPubKey` | String | Blob | `""` (Empty string) |
| `TxnSignature` | String | Blob | `""` (Empty string) |
Pseudo-transactions use the following common fields as normal:
- `TransactionType`
- `Flags`
| Field | JSON Type | [Internal Type][] | Description |
|:------------------|:----------|:------------------|:-------------------------|
| `TransactionType` | String | UInt16 | _(Required)_ The type of transaction. |
| `Flags` | Number | UInt32 | _(Optional)_ A set of bit-flags for this transaction. The meaning of specific flags varies based on the transaction type. |
{% raw-partial file="/_snippets/common-links.md" /%}
{% child-pages /%}

58
docs/references/protocol/transactions/pseudo-transaction-types/setfee.md Normal file
View File

@@ -0,0 +1,58 @@
---
html: setfee.html
parent: pseudo-transaction-types.html
seo:
description: Change global reserve and transaction cost settings.
labels:
- Fees
---
# SetFee
A `SetFee` [pseudo-transaction](pseudo-transaction-types.md) marks a change in [transaction cost](../../../../concepts/transactions/transaction-cost.md) or [reserve requirements](../../../../concepts/accounts/reserves.md) as a result of [Fee Voting](../../../../concepts/consensus-protocol/fee-voting.md).
**Note:** You cannot send a pseudo-transaction, but you may find one when processing ledgers.
## Example {% $frontmatter.seo.title %} JSON
```json
{
"Account": "rrrrrrrrrrrrrrrrrrrrrhoLvTp",
"BaseFee": "000000000000000A",
"Fee": "0",
"ReferenceFeeUnits": 10,
"ReserveBase": 20000000,
"ReserveIncrement": 5000000,
"Sequence": 0,
"SigningPubKey": "",
"TransactionType": "SetFee",
"date": 439578860,
"hash": "1C15FEA3E1D50F96B6598607FC773FF1F6E0125F30160144BE0C5CBC52F5151B",
"ledger_index": 3721729,
}
```
{% partial file="/_snippets/pseudo-tx-fields-intro.md" /%}
<!--{# fix md highlighting_ #}-->
| Field | JSON Type | [Internal Type][] | Description |
|:--------------------|:-----------------|:------------------|:----------------|
| `BaseFee` | String | UInt64 | The charge, in drops of XRP, for the reference transaction, as hex. (This is the [transaction cost](../../../../concepts/transactions/transaction-cost.md) before scaling for load.) |
| `ReferenceFeeUnits` | Unsigned Integer | UInt32 | The cost, in fee units, of the reference transaction |
| `ReserveBase` | Unsigned Integer | UInt32 | The base reserve, in drops |
| `ReserveIncrement` | Unsigned Integer | UInt32 | The incremental reserve, in drops |
| `LedgerSequence` | Number | UInt32 | _(Omitted for some historical `SetFee` pseudo-transactions)_ The index of the ledger version where this pseudo-transaction appears. This distinguishes the pseudo-transaction from other occurrences of the same change. |
If the _[XRPFees amendment][]_ is enabled, `SetFee` pseudo-transactions use these fields instead:
| Field | JSON Type | [Internal Type][] | Description |
|:------------------------|:----------|:------------------|:----------------|
| `BaseFeeDrops` | String | Amount | The charge, in drops of XRP, for the reference transaction. (This is the [transaction cost](../../../../concepts/transactions/transaction-cost.md) before scaling for load.) |
| `ReserveBaseDrops` | String | Amount | The base reserve, in drops |
| `ReserveIncrementDrops` | String | Amount | The incremental reserve, in drops |
| `LedgerSequence` | Number | UInt32 | _(Omitted for some historical `SetFee` pseudo-transactions)_ The index of the ledger version where this pseudo-transaction appears. This distinguishes the pseudo-transaction from other occurrences of the same change. |
{% raw-partial file="/_snippets/setfee_uniqueness_note.md" /%}
{% raw-partial file="/_snippets/common-links.md" /%}

42
docs/references/protocol/transactions/pseudo-transaction-types/unlmodify.md Normal file
View File

@@ -0,0 +1,42 @@
---
html: unlmodify.html
parent: pseudo-transaction-types.html
seo:
description: Change the list of trusted validators currently considered offline.
labels:
- Blockchain
---
# UNLModify
_(Added by the [NegativeUNL amendment][].)_
A `UNLModify` [pseudo-transaction](pseudo-transaction-types.md) marks a change to the [Negative UNL](../../../../concepts/consensus-protocol/negative-unl.md), indicating that a trusted validator has gone offline or come back online.
**Note:** You cannot send a pseudo-transaction, but you may find one when processing ledgers.
## Example {% $frontmatter.seo.title %} JSON
```json
{
"Account": "",
"Fee": "0",
"LedgerSequence": 1600000,
"Sequence": 0,
"SigningPubKey": "",
"TransactionType": "UNLModify",
"UNLModifyDisabling": 1,
"UNLModifyValidator": "ED6629D456285AE3613B285F65BBFF168D695BA3921F309949AFCD2CA7AFEC16FE",
}
```
{% partial file="/_snippets/pseudo-tx-fields-intro.md" /%}
<!--{# fix md highlighting_ #}-->
| Name | JSON Type | [Internal Type][] | Description |
|:---------------------|:----------|:------------------|:----------------------|
| `TransactionType` | String | UInt16 | The value `0x0066`, mapped to the string `UNLModify`, indicates that this object is an `UNLModify` pseudo-transaction. |
| `LedgerSequence` | Number | UInt32 | The [ledger index][] where this pseudo-transaction appears. This distinguishes the pseudo-transaction from other occurrences of the same change. |
| `UNLModifyDisabling` | Number | UInt8 | If `1`, this change represents adding a validator to the Negative UNL. If `0`, this change represents removing a validator from the Negative UNL. (No other values are allowed.) |
| `UNLModifyValidator` | String | Blob | The validator to add or remove, as identified by its master public key. |
{% raw-partial file="/_snippets/common-links.md" /%}

73
docs/references/protocol/transactions/transaction-results/tec-codes.md Normal file
View File

@@ -0,0 +1,73 @@
---
html: tec-codes.html
parent: transaction-results.html
seo:
description: tec codes indicate that the transaction failed, but it was applied to a ledger to deduct the transaction cost.
labels:
- Transaction Sending
---
# tec Codes
These codes indicate that the transaction failed, but it was applied to a ledger to apply the [transaction cost](../../../../concepts/transactions/transaction-cost.md). They have numerical values in the range 100 to 199. It is recommended to use the text code, not the numeric value.
Transactions with `tec` codes destroy the XRP paid as a [transaction cost](../../../../concepts/transactions/transaction-cost.md), and consume a [sequence number](../../data-types/basic-data-types.md#account-sequence). For the most part, the transactions take no other action, but there are some exceptions. For example, a transaction that results in `tecOVERSIZE` still cleans up some [unfunded offers](../../../../concepts/tokens/decentralized-exchange/offers.md#lifecycle-of-an-offer). Always look at the [transaction metadata](../metadata.md) to see precisely what a transaction did.
**Caution:** A transaction that provisionally failed with a `tec` code may still succeed or fail with a different code after being reapplied. The result is final when it appears in a validated ledger version. For more information, see [Finality of Results](../../../../concepts/transactions/finality-of-results/index.md) and [Reliable Transaction Submission](../../../../concepts/transactions/reliable-transaction-submission.md).
| Code | Value | Explanation |
|:---------------------------|:------|:----------------------------------------|
| `tecAMM_ACCOUNT` | 168 | The transaction failed because the operation is not allowed on Automated Market Maker (AMM) accounts. _(Requires the [AMM amendment][] {% not-enabled /%})_ |
| `tecAMM_UNFUNDED` | 162 | The [AMMCreate transaction][] failed because the sender does not have enough of the specified assets to fund it. _(Requires the [AMM amendment][] {% not-enabled /%})_ |
| `tecAMM_BALANCE` | 163 | The [AMMDeposit][] or [AMMWithdraw][] transaction failed because either the AMM or the user does not hold enough of one of the specified assets. (For example, you tried to withdraw more than the AMM holds.) _(Requires the [AMM amendment][] {% not-enabled /%})_ |
| `tecAMM_EMPTY` | 166 | The AMM-related transaction failed because the AMM has no assets in its pool. In this state, you can only delete the AMM or fund it with a new deposit. _(Requires the [AMM amendment][] {% not-enabled /%})_ |
| `tecAMM_FAILED` | 164 | The AMM-related transaction failed. For [AMMDeposit][] or [AMMWithdraw][] this could be because the sender does not have enough of the specified assets, or the transaction requested an effective price that isn't possible with the available amounts. For [AMMBid][] this could be because the account does not have enough to win the bid or needs more than their specified maximum bid. For [AMMVote][], this could be because there are already too many votes from other accounts that hold more of this AMM's LP Tokens. _(Requires the [AMM amendment][] {% not-enabled /%})_ |
| `tecAMM_INVALID_TOKENS` | 165 | The AMM-related transaction 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. _(Requires the [AMM amendment][] {% not-enabled /%})_ |
| `tecAMM_NOT_EMPTY` | 167 | The transaction was meant to operate on an AMM with empty asset pools, but the specified AMM currently holds assets. _(Requires the [AMM amendment][] {% not-enabled /%})_ |
| `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](../../../../concepts/tokens/nfts/index.md). _(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. |
| `tecDIR_FULL` | 121 | The transaction tried to add an object (such as a trust line, Check, Escrow, or Payment Channel) to an account's owner directory, but that account cannot own any more objects in the ledger. |
| `tecDUPLICATE` | 149 | The transaction tried to create an object (such as a [DepositPreauth][] authorization) that already exists. |
| `tecDST_TAG_NEEDED` | 143 | The [Payment transaction][] omitted a [destination tag](../../../../concepts/transactions/source-and-destination-tags.md), but the destination account has the `lsfRequireDestTag` flag enabled. |
| `tecEXPIRED` | 148 | The transaction tried to create an object (such as an Offer or a Check) whose provided Expiration time has already passed. |
| `tecFAILED_PROCESSING` | 105 | An unspecified error occurred when processing the transaction. |
| `tecFROZEN` | 137 | The [OfferCreate transaction][] failed because one or both of the assets involved are subject to a [global freeze](../../../../concepts/tokens/fungible-tokens/freezes.md). |
| `tecHAS_OBLIGATIONS` | 151 | The [AccountDelete transaction][] failed because the account to be deleted owns objects that cannot be deleted. See [Deleting Accounts](../../../../concepts/accounts/deleting-accounts.md) for details. |
| `tecINSUF_RESERVE_LINE` | 122 | The transaction failed because the sending account does not have enough XRP to create a new trust line. (See: [Reserves](../../../../concepts/accounts/reserves.md)) This error occurs when the counterparty already has a trust line in a non-default state to the sending account for the same currency. (See `tecNO_LINE_INSUF_RESERVE` for the other case.) |
| `tecINSUF_RESERVE_OFFER` | 123 | The transaction failed because the sending account does not have enough XRP to create a new Offer. (See: [Reserves](../../../../concepts/accounts/reserves.md)) |
| `tecINSUFF_FEE` | 136 | The transaction failed because the sending account does not have enough XRP to pay the [transaction cost](../../../../concepts/transactions/transaction-cost.md) that it specified. (In this case, the transaction processing destroys all of the sender's XRP even though that amount is lower than the specified transaction cost.) This result only occurs if the account's balance decreases _after_ this transaction has been distributed to enough of the network to be included in a consensus set. Otherwise, the transaction fails with [`terINSUF_FEE_B`](ter-codes.md) before being distributed. |
| `tecINSUFFICIENT_FUNDS` | 158 | One of the accounts involved does not hold enough of a necessary asset. _(Added by the [NonFungibleTokensV1_1 amendment][].)_ |
| `tecINSUFFICIENT_PAYMENT` | 161 | The amount specified is not enough to pay all fees involved in the transaction. For example, when trading a non-fungible token, the buy amount may not be enough to pay both the broker fee and the sell amount. _(Added by the [NonFungibleTokensV1_1 amendment][].)_ |
| `tecINSUFFICIENT_RESERVE` | 141 | The transaction would increase the [reserve requirement](../../../../concepts/accounts/reserves.md) higher than the sending account's balance. [SignerListSet][], [PaymentChannelCreate][], [PaymentChannelFund][], and [EscrowCreate][] can return this error code. See [Signer Lists and Reserves](../../ledger-data/ledger-entry-types/signerlist.md#signer-lists-and-reserves) for more information. |
| `tecINTERNAL` | 144 | Unspecified internal error, with transaction cost applied. This error code should not normally be returned. If you can reproduce this error, please [report an issue](https://github.com/XRPLF/rippled/issues). |
| `tecINVARIANT_FAILED` | 147 | An invariant check failed when trying to execute this transaction. Added by the [EnforceInvariants amendment][]. If you can reproduce this error, please [report an issue](https://github.com/XRPLF/rippled/issues). |
| `tecKILLED` | 150 | The [OfferCreate transaction][] specified the `tfFillOrKill` flag and could not be filled, so it was killed. _(Added by the [fix1578 amendment][].)_ |
| `tecMAX_SEQUENCE_REACHED` | 153 | A sequence number field is already at its maximum. This includes the `MintedNFTokens` field. _(Added by the [NonFungibleTokensV1_1 amendment][].)_ |
| `tecNEED_MASTER_KEY` | 142 | This transaction tried to cause changes that require the master key, such as [disabling the master key or giving up the ability to freeze balances](../types/accountset.md#accountset-flags). |
| `tecNFTOKEN_BUY_SELL_MISMATCH` | 155 | The [NFTokenAcceptOffer transaction][] attempted to match incompatible offers to buy and sell a non-fungible token. _(Added by the [NonFungibleTokensV1_1 amendment][].)_ |
| `tecNFTOKEN_OFFER_TYPE_MISMATCH` | 156 | One or more of the offers specified in the transaction was not the right type of offer. (For example, a buy offer was specified in the `NFTokenSellOffer` field.) _(Added by the [NonFungibleTokensV1_1 amendment][].)_ |
| `tecNO_ALTERNATIVE_KEY` | 130 | The transaction tried to remove the only available method of [authorizing transactions](../../../../concepts/transactions/index.md#authorizing-transactions). This could be a [SetRegularKey transaction][] to remove the regular key, a [SignerListSet transaction][] to delete a SignerList, or an [AccountSet transaction][] to disable the master key. (Prior to `rippled` 0.30.0, this was called `tecMASTER_DISABLED`.) |
| `tecNO_AUTH` | 134 | The transaction failed because it needs to add a balance on a trust line to an account with the `lsfRequireAuth` flag enabled, and that trust line has not been authorized. If the trust line does not exist at all, `tecNO_LINE` occurs instead. |
| `tecNO_DST` | 124 | The account on the receiving end of the transaction does not exist. This includes Payment and TrustSet transaction types. (It could be created if it received enough XRP.) |
| `tecNO_DST_INSUF_XRP` | 125 | The account on the receiving end of the transaction does not exist, and the transaction is not sending enough XRP to create it. |
| `tecNO_ENTRY` | 140 | The transaction tried to modify a [ledger object](../../ledger-data/ledger-entry-types/index.md), such as a [Check](../../../../concepts/payment-types/checks.md), [Payment Channel](../../../../concepts/payment-types/payment-channels.md), or [Deposit Preauthorization](../../ledger-data/ledger-entry-types/depositpreauth.md), but the specified object does not exist. It may have already been deleted by a previous transaction or the transaction may have an incorrect value in an ID field such as `CheckID`, `Channel`, `Unauthorize`. |
| `tecNO_ISSUER` | 133 | The account specified in the `issuer` field of a currency amount does not exist. |
| `tecNO_LINE` | 135 | The `TakerPays` field of the [OfferCreate transaction][] specifies an asset whose issuer has `lsfRequireAuth` enabled, and the account making the offer does not have a trust line for that asset. (Normally, making an offer implicitly creates a trust line if necessary, but in this case it does not bother because you cannot hold the asset without authorization.) If the trust line exists, but is not authorized, `tecNO_AUTH` occurs instead. |
| `tecNO_LINE_INSUF_RESERVE` | 126 | The transaction failed because the sending account does not have enough XRP to create a new trust line. (See: [Reserves](../../../../concepts/accounts/reserves.md)) This error occurs when the counterparty does not have a trust line to this account for the same currency. (See `tecINSUF_RESERVE_LINE` for the other case.) |
| `tecNO_LINE_REDUNDANT` | 127 | The transaction failed because it tried to set a trust line to its default state, but the trust line did not exist. |
| `tecNO_PERMISSION` | 139 | The sender does not have permission to do this operation. For example, the [EscrowFinish transaction][] tried to release a held payment before its `FinishAfter` time, someone tried to use [PaymentChannelFund][] on a channel the sender does not own, or a [Payment][] tried to deliver funds to an account with the "DepositAuth" flag enabled. |
| `tecNO_REGULAR_KEY` | 131 | The [AccountSet transaction][] tried to disable the master key, but the account does not have another way to [authorize transactions](../../../../concepts/transactions/index.md#authorizing-transactions). If [multi-signing](../../../../concepts/accounts/multi-signing.md) is enabled, this code is deprecated and `tecNO_ALTERNATIVE_KEY` is used instead. |
| `tecNO_SUITABLE_NFTOKEN_PAGE` | 154 | The transaction tried to mint or acquire a non-fungible token but the account receiving the `NFToken` does not have a directory page that can hold it. This situation is rare. _(Added by the [NonFungibleTokensV1_1 amendment][].)_ |
| `tecNO_TARGET` | 138 | The transaction referenced an Escrow or PayChannel ledger object that doesn't exist, either because it never existed or it has already been deleted. (For example, another [EscrowFinish transaction][] has already executed the held payment.) Alternatively, the destination account has `asfDisallowXRP` set so it cannot be the destination of this [PaymentChannelCreate][] or [EscrowCreate][] transaction. |
| `tecOBJECT_NOT_FOUND` | 160 | One of the objects specified by this transaction did not exist in the ledger. _(Added by the [NonFungibleTokensV1_1 amendment][].)_ |
| `tecOVERSIZE` | 145 | This transaction could not be processed, because the server created an excessively large amount of [metadata](../metadata.md) when it tried to apply the transaction. |
| `tecOWNERS` | 132 | The transaction cannot succeed because the sender already owns objects in the ledger. For example, an account cannot enable the [`lsfRequireAuth`](../types/accountset.md#accountset-flags) flag if it has any trust lines or available offers. |
| `tecPATH_DRY` | 128 | The transaction failed because the provided [paths](../../../../concepts/tokens/fungible-tokens/paths.md) did not have enough liquidity to send anything at all. This could mean that the source and destination accounts are not linked by [trust lines](../../../../concepts/tokens/fungible-tokens/index.md). |
| `tecPATH_PARTIAL` | 101 | The transaction failed because the provided [paths](../../../../concepts/tokens/fungible-tokens/paths.md) did not have enough liquidity to send the full amount. |
| `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](../../../../concepts/accounts/reserves.md) necessary to execute this transaction. |
| `tecUNFUNDED_ADD` | 102 | **DEPRECATED.** |
| `tecUNFUNDED_PAYMENT` | 104 | The transaction failed because the sending account is trying to send more XRP than it holds, not counting the [reserve](../../../../concepts/accounts/reserves.md). |
| `tecUNFUNDED_OFFER` | 103 | The [OfferCreate transaction][] failed because the account creating the offer does not have any of the `TakerGets` currency. |
{% raw-partial file="/_snippets/common-links.md" /%}

40
docs/references/protocol/transactions/transaction-results/tef-codes.md Normal file
View File

@@ -0,0 +1,40 @@
---
html: tef-codes.html
parent: transaction-results.html
seo:
description: tef codes indicate that the transaction failed and was not included in a ledger, but the transaction could have succeeded in some theoretical ledger.
labels:
- Transaction Sending
---
# tef Codes
<!-- SPELLING_IGNORE: tef -->
These codes indicate that the transaction failed and was not included in a ledger, but the transaction could have succeeded in some theoretical ledger. Typically this means that the transaction can no longer succeed in any future ledger. They have numerical values in the range -199 to -100. The exact code for any given error is subject to change, so don't rely on it.
**Caution:** Transactions with `tef` codes are not applied to ledgers and cannot cause any changes to the XRP Ledger state. However, a transaction that provisionally failed may still succeed or fail with a different code after being reapplied. For more information, see [Finality of Results](../../../../concepts/transactions/finality-of-results/index.md) and [Reliable Transaction Submission](../../../../concepts/transactions/reliable-transaction-submission.md).
| Code | Explanation |
|:-----------------------|:----------------------------------------------------|
| `tefALREADY` | The same exact transaction has already been applied. |
| `tefBAD_ADD_AUTH` | **DEPRECATED.** |
| `tefBAD_AUTH` | The key used to sign this account is not authorized to modify this account. (It could be authorized if the account had the same key set as the [Regular Key](../../../../concepts/accounts/cryptographic-keys.md).) |
| `tefBAD_AUTH_MASTER` | The single signature provided to authorize this transaction does not match the master key, but no regular key is associated with this address. |
| `tefBAD_LEDGER` | While processing the transaction, the ledger was discovered in an unexpected state. If you can reproduce this error, please [report an issue](https://github.com/XRPLF/rippled/issues) to get it fixed. |
| `tefBAD_QUORUM` | The transaction was [multi-signed](../../../../concepts/accounts/multi-signing.md), but the total weights of all included signatures did not meet the quorum. |
| `tefBAD_SIGNATURE` | The transaction was [multi-signed](../../../../concepts/accounts/multi-signing.md), but contained a signature for an address not part of a SignerList associated with the sending account. |
| `tefCREATED` | **DEPRECATED.** |
| `tefEXCEPTION` | While processing the transaction, the server entered an unexpected state. This may be caused by unexpected inputs, for example if the binary data for the transaction is grossly malformed. If you can reproduce this error, please [report an issue](https://github.com/XRPLF/rippled/issues) to get it fixed. |
| `tefFAILURE` | Unspecified failure in applying the transaction. |
| `tefINTERNAL` | When trying to apply the transaction, the server entered an unexpected state. If you can reproduce this error, please [report an issue](https://github.com/XRPLF/rippled/issues) to get it fixed. |
| `tefINVARIANT_FAILED` | An invariant check failed when trying to claim the [transaction cost](../../../../concepts/transactions/transaction-cost.md). Added by the [EnforceInvariants amendment][]. If you can reproduce this error, please [report an issue](https://github.com/XRPLF/rippled/issues). |
| `tefMASTER_DISABLED` | The transaction was signed with the account's master key, but the account has the `lsfDisableMaster` field set. |
| `tefMAX_LEDGER` | The transaction included a [`LastLedgerSequence`](../../../../concepts/transactions/reliable-transaction-submission.md#lastledgersequence) parameter, but the current ledger's sequence number is already higher than the specified value. |
| `tefNFTOKEN_IS_NOT_TRANSFERABLE` | The transaction attempted to send a [non-fungible token](../../../../concepts/tokens/nfts/index.md) to another account, but the `NFToken` has the `lsfTransferable` flag disabled and the transfer would not be to or from the issuer. _(Added by the [NonFungibleTokensV1_1 amendment][].)_ |
| `tefNO_AUTH_REQUIRED` | The [TrustSet transaction][] tried to mark a trust line as authorized, but the `lsfRequireAuth` flag is not enabled for the corresponding account, so authorization is not necessary. |
| `tefNO_TICKET` | The transaction attempted to use a [Ticket](../../../../concepts/accounts/tickets.md), but the specified `TicketSequence` number does not exist in the ledger, and cannot be created in the future because it is earlier than the sender's current sequence number. |
| `tefNOT_MULTI_SIGNING` | The transaction was [multi-signed](../../../../concepts/accounts/multi-signing.md), but the sending account has no SignerList defined. |
| `tefPAST_SEQ` | The sequence number of the transaction is lower than the current sequence number of the account sending the transaction. |
| `tefTOO_BIG` | The transaction would affect too many objects in the ledger. For example, this was an [AccountDelete transaction][] but the account to be deleted owns over 1000 objects in the ledger. |
| `tefWRONG_PRIOR` | The transaction contained an `AccountTxnID` field (or the deprecated `PreviousTxnID` field), but the transaction specified there does not match the account's previous transaction. |
{% raw-partial file="/_snippets/common-links.md" /%}

34
docs/references/protocol/transactions/transaction-results/tel-codes.md Normal file
View File

@@ -0,0 +1,34 @@
---
html: tel-codes.html
parent: transaction-results.html
seo:
description: tel codes indicate an error in the local server processing the transaction.
labels:
- Transaction Sending
---
# tel Codes
These codes indicate an error in the local server processing the transaction; it is possible that another server with a different configuration or load level could process the transaction successfully. They have numerical values in the range -399 to -300. The exact code for any given error is subject to change, so don't rely on it.
**Caution:** Transactions with `tel` codes are not applied to ledgers and cannot cause any changes to the XRP Ledger state. However, these transactions may be automatically cached and retried later. Transactions that provisionally failed may still succeed or fail with a different code after being reapplied. For more information, see [Finality of Results](../../../../concepts/transactions/finality-of-results/index.md) and [Reliable Transaction Submission](../../../../concepts/transactions/reliable-transaction-submission.md).
| Code | Explanation |
|:----------------|:------------|
| `telBAD_DOMAIN` | The transaction specified a domain value (for example, the `Domain` field of an [AccountSet transaction][]) that cannot be used, probably because it is too long to store in the ledger. |
| `telBAD_PATH_COUNT` | The transaction contains too many paths for the local server to process. |
| `telBAD_PUBLIC_KEY` | The transaction specified a public key value (for example, as the `MessageKey` field of an [AccountSet transaction][]) that cannot be used, probably because it is not the right length. |
| `telCAN_NOT_QUEUE` | The transaction did not meet the [open ledger cost](../../../../concepts/transactions/transaction-cost.md), but this server did not queue this transaction because it did not meet the [queuing restrictions](../../../../concepts/transactions/transaction-queue.md#queuing-restrictions). For example, a transaction returns this code when the sender already has 10 other transactions in the queue. You can try again later or sign and submit a replacement transaction with a higher transaction cost in the `Fee` field. |
| `telCAN_NOT_QUEUE_BALANCE` | The transaction did not meet the [open ledger cost](../../../../concepts/transactions/transaction-cost.md) and also was not added to the transaction queue because the sum of potential XRP costs of already-queued transactions is greater than the expected balance of the account. You can try again later, or try submitting to a different server. |
| `telCAN_NOT_QUEUE_BLOCKS` | The transaction did not meet the [open ledger cost](../../../../concepts/transactions/transaction-cost.md) and also was not added to the transaction queue. This transaction could not replace an existing transaction in the queue because it would block already-queued transactions from the same sender. (For details, see [Queuing Restrictions](../../../../concepts/transactions/transaction-queue.md#queuing-restrictions).) You can try again later, or try submitting to a different server. |
| `telCAN_NOT_QUEUE_BLOCKED` | The transaction did not meet the [open ledger cost](../../../../concepts/transactions/transaction-cost.md) and also was not added to the transaction queue because a transaction queued ahead of it from the same sender blocks it. (For details, see [Queuing Restrictions](../../../../concepts/transactions/transaction-queue.md#queuing-restrictions).) You can try again later, or try submitting to a different server. |
| `telCAN_NOT_QUEUE_FEE` | The transaction did not meet the [open ledger cost](../../../../concepts/transactions/transaction-cost.md) and also was not added to the transaction queue. This code occurs when a transaction with the same sender and sequence number already exists in the queue and the new one does not pay a large enough transaction cost to replace the existing transaction. To replace a transaction in the queue, the new transaction must have a `Fee` value that is at least 25% more, as measured in [fee levels](../../../../concepts/transactions/transaction-cost.md#fee-levels). You can increase the `Fee` and try again, send this with a higher `Sequence` number so it doesn't replace an existing transaction, or try sending to another server. |
| `telCAN_NOT_QUEUE_FULL` | The transaction did not meet the [open ledger cost](../../../../concepts/transactions/transaction-cost.md) and the server did not queue this transaction because this server's transaction queue is full. You could increase the `Fee` and try again, try again later, or try submitting to a different server. The new transaction must have a higher transaction cost, as measured in [fee levels](../../../../concepts/transactions/transaction-cost.md#fee-levels), than the transaction in the queue with the smallest transaction cost. |
| `telFAILED_PROCESSING` | An unspecified error occurred when processing the transaction. |
| `telINSUF_FEE_P` | The `Fee` from the transaction is not high enough to meet the server's current [transaction cost](../../../../concepts/transactions/transaction-cost.md) requirement, which is derived from its load level and network-level requirements. If the individual server is too busy to process your transaction right now, it may cache the transaction and automatically retry later. |
| `telLOCAL_ERROR` | Unspecified local error. The transaction may be able to succeed if you submit it to a different server. |
| `telNETWORK_ID_MAKES_TX_NON_CANONICAL` | The transaction specifies the [`NetworkID` field](../common-fields.md#networkid-field), but the current network rules require that the `NetworkID` field be omitted. (Mainnet and other networks with a chain ID of 1024 or less do not use this field.) If the transaction was intended for a network that does not use `NetworkID`, remove the field and try again. If the transaction was intended for a different network, submit it to a server that is connected to the correct network. {% badge href="https://github.com/XRPLF/rippled/releases/tag/1.11.0" %}New in: rippled 1.11.0{% /badge %} |
| `telNO_DST`_`PARTIAL` | The transaction is an XRP payment that would fund a new account, but the [`tfPartialPayment` flag](../../../../concepts/payment-types/partial-payments.md) was enabled. This is disallowed. |
| `telREQUIRES_NETWORK_ID` | The transaction does not specify a [`NetworkID` field](../common-fields.md#networkid-field), but the current network requires one. If the transaction was intended for a network that requires `NetworkID`, add the field and try again. If the transaction was intended for a different network, submit it to a server that is connected to the correct network. {% badge href="https://github.com/XRPLF/rippled/releases/tag/1.11.0" %}New in: rippled 1.11.0{% /badge %} |
| `telWRONG_NETWORK` | The transaction specifies the wrong [`NetworkID` value](../common-fields.md#networkid-field) for the current network. Either specify the correct the `NetworkID` value for the intended network, or submit the transaction to a server that is connected to the correct network. {% badge href="https://github.com/XRPLF/rippled/releases/tag/1.11.0" %}New in: rippled 1.11.0{% /badge %} |
{% raw-partial file="/_snippets/common-links.md" /%}

55
docs/references/protocol/transactions/transaction-results/tem-codes.md Normal file
View File

@@ -0,0 +1,55 @@
---
html: tem-codes.html
parent: transaction-results.html
seo:
description: tem codes indicate that the transaction was malformed, and cannot succeed according to the XRP Ledger protocol.
labels:
- Transaction Sending
---
# tem Codes
These codes indicate that the transaction was malformed, and cannot succeed according to the XRP Ledger protocol. They have numerical values in the range -299 to -200. The exact code for any given error is subject to change, so don't rely on it.
**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](../../../../concepts/networks-and-servers/amendments.md) 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 |
|:------------------------------|:----------------------------------------------|
| `temBAD_AMM_TOKENS` | The transaction incorrectly specified one or more assets. For example, the asset's issuer does not match the corresponding asset in the AMM's pool, or the transaction specified the same asset twice. _(Requires the [AMM amendment][] {% not-enabled /%})_ |
| `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](../../../../concepts/accounts/cryptographic-keys.md) 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. |
| `temBAD_ISSUER` | The transaction improperly specified the `issuer` field of some currency included in the request. |
| `temBAD_LIMIT` | The [TrustSet transaction][] improperly specified the `LimitAmount` value of a trust line. |
| `temBAD_NFTOKEN_TRANSFER_FEE` | The [NFTokenMint transaction][] improperly specified the `TransferFee` field of the transaction. _(Added by the [NonFungibleTokensV1_1 amendment][].)_ |
| `temBAD_OFFER` | The [OfferCreate transaction][] specifies an invalid offer, such as offering to trade XRP for itself, or offering a negative amount. |
| `temBAD_PATH` | The [Payment transaction][] specifies one or more [Paths](../../../../concepts/tokens/fungible-tokens/paths.md) improperly, for example including an issuer for XRP, or specifying an account differently. |
| `temBAD_PATH_LOOP` | One of the [Paths](../../../../concepts/tokens/fungible-tokens/paths.md) in the [Payment transaction][] was flagged as a loop, so it cannot be processed in a bounded amount of time. |
| `temBAD_SEND_XRP_LIMIT` | The [Payment transaction][] used the [`tfLimitQuality` flag](../types/payment.md#limit-quality) in a direct XRP-to-XRP payment, even though XRP-to-XRP payments do not involve any conversions. |
| `temBAD_SEND_XRP_MAX` | The [Payment transaction][] included a `SendMax` field in a direct XRP-to-XRP payment, even though sending XRP should never require `SendMax`. (XRP is only valid in `SendMax` if the destination `Amount` is not XRP.) |
| `temBAD_SEND_XRP_NO_DIRECT` | The [Payment transaction][] used the [`tfNoDirectRipple` flag](../types/payment.md#payment-flags) for a direct XRP-to-XRP payment, even though XRP-to-XRP payments are always direct. |
| `temBAD_SEND_XRP_PARTIAL` | The [Payment transaction][] used the [`tfPartialPayment` flag](../../../../concepts/payment-types/partial-payments.md) for a direct XRP-to-XRP payment, even though XRP-to-XRP payments should always deliver the full amount. |
| `temBAD_SEND_XRP_PATHS` | The [Payment transaction][] included `Paths` while sending XRP, even though XRP-to-XRP payments should always be direct. |
| `temBAD_SEQUENCE` | The transaction is references a sequence number that is higher than its own `Sequence` number, for example trying to cancel an offer that would have to be placed after the transaction that cancels it. |
| `temBAD_SIGNATURE` | The signature to authorize this transaction is either missing, or formed in a way that is not a properly-formed signature. (See [`tecNO_PERMISSION`](tec-codes.md) for the case where the signature is properly formed, but not authorized for this account.) |
| `temBAD_SRC_ACCOUNT` | The `Account` on whose behalf this transaction is being sent (the "source account") is not a properly-formed [account](../../../../concepts/accounts/accounts.md) address. |
| `temBAD_TRANSFER_RATE` | The [`TransferRate` field of an AccountSet transaction](../types/accountset.md#transferrate) is not properly formatted or out of the acceptable range. |
| `temCANNOT_PREAUTH_SELF` | The sender of the [DepositPreauth transaction][] was also specified as the account to preauthorize. You cannot preauthorize yourself. |
| `temDST_IS_SRC` | The transaction improperly specified a destination address as the `Account` sending the transaction. This includes trust lines (where the destination address is the `issuer` field of `LimitAmount`) and payment channels (where the destination address is the `Destination` field). |
| `temDST_NEEDED` | The transaction improperly omitted a destination. This could be the `Destination` field of a [Payment transaction][], or the `issuer` sub-field of the `LimitAmount` field fo a `TrustSet` transaction. |
| `temINVALID` | The transaction is otherwise invalid. For example, the transaction ID may not be the right format, the signature may not be formed properly, or something else went wrong in understanding the transaction. |
| `temINVALID_COUNT` | The transaction includes a `TicketCount` field, but the number of Tickets specified is invalid. |
| `temINVALID_FLAG` | The transaction includes a [Flag](../common-fields.md#flags-field) that does not exist, or includes a contradictory combination of flags. |
| `temMALFORMED` | Unspecified problem with the format of the transaction. |
| `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` | {% badge href="https://github.com/XRPLF/rippled/releases/tag/0.28.0" %}Removed in: rippled 0.28.0{% /badge %} |
| `temRIPPLE_EMPTY` | The [Payment transaction][] includes an empty `Paths` field, but paths are necessary to complete this payment. |
| `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. |
| `temUNCERTAIN` | Used internally only. This code should never be returned. |
| `temUNKNOWN` | Used internally only. This code should never be returned. |
| `temDISABLED` | The transaction requires logic that is disabled. Typically this means you are trying to use an [amendment](../../../../concepts/networks-and-servers/amendments.md) that is not enabled for the current ledger. |
{% raw-partial file="/_snippets/common-links.md" /%}

32
docs/references/protocol/transactions/transaction-results/ter-codes.md Normal file
View File

@@ -0,0 +1,32 @@
---
html: ter-codes.html
parent: transaction-results.html
seo:
description: ter codes indicate that the transaction has not been applied yet, but it could apply successfully in the future - for example, if some other transaction applies first.
labels:
- Transaction Sending
---
# ter Codes
These codes indicate that the transaction has not been [applied](../../../../concepts/consensus-protocol/index.md) yet, and generally will be automatically retried by the server that returned the result code. The transaction could apply successfully in the future; for example, if a certain other transaction applies first. These codes have numerical values in the range -99 to -1, but the exact code for any given error is subject to change, so don't rely on it.
**Note:** Transactions with `ter` codes have not been applied to the current ledger and have not yet changed the XRP Ledger state. A transaction that provisionally got a `ter` result may still succeed or fail with a different code after being automatically applied later. For more information, see [Finality of Results](../../../../concepts/transactions/finality-of-results/index.md) and [Reliable Transaction Submission](../../../../concepts/transactions/reliable-transaction-submission.md).
| Code | Explanation |
|:-----------------|:----------------------------------------------------------|
| `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_AMM` | The AMM-related transaction specifies an asset pair that does not currently have an AMM instance. _(Requires the [AMM amendment][] {% not-enabled /%})_ |
| `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`](../types/accountset.md#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](../../../../concepts/accounts/tickets.md), but the specified `TicketSequence` number does not exist in the ledger. However, the Ticket could still be created by another transaction. |
| `terQUEUED` | The transaction met the load-scaled [transaction cost](../../../../concepts/transactions/transaction-cost.md) but did not meet the open ledger requirement, so the transaction has been queued for a future ledger. |
| `terRETRY` | Unspecified retriable error. |
| `terSUBMITTED` | Transaction has been submitted, but not yet applied. |
{% raw-partial file="/_snippets/common-links.md" /%}

17
docs/references/protocol/transactions/transaction-results/tes-success.md Normal file
View File

@@ -0,0 +1,17 @@
---
html: tes-success.html
parent: transaction-results.html
seo:
description: tesSUCCESS is the only code that indicates a transaction succeeded.
labels:
- Transaction Sending
---
# tes Success
The code `tesSUCCESS` is the only code that indicates a transaction succeeded. This does not always mean it accomplished what you expected it to do. (For example, an [OfferCancel][] can "succeed" even if there is no offer for it to cancel.) The `tesSUCCESS` result uses the numerical value 0.
| Code | Explanation |
|:-----------|:----------------------------------------------------------------|
| `tesSUCCESS` | The transaction was applied and forwarded to other servers. If this appears in a validated ledger, then the transaction's success is final. |
{% raw-partial file="/_snippets/common-links.md" /%}

55
docs/references/protocol/transactions/transaction-results/transaction-results.md Normal file
View File

@@ -0,0 +1,55 @@
---
html: transaction-results.html
parent: transaction-formats.html
seo:
description: Learn how to interpret rippled server transaction results.
labels:
- Transaction Sending
---
# Transaction Results
[[Source]](https://github.com/XRPLF/rippled/blob/master/src/ripple/protocol/TER.h "Source")
The `rippled` server summarizes transaction results with result codes, which appear in fields such as `engine_result` and `meta.TransactionResult`. These codes are grouped into several categories of with different prefixes:
| Category | Prefix | Description |
|:----------------------|:--------------------------|:-------------------------|
| Claimed cost only | [`tec`](tec-codes.md) | The transaction did not achieve its intended purpose, but the [transaction cost](../../../../concepts/transactions/transaction-cost.md) was destroyed. This result is only final in a validated ledger. |
| Failure | [`tef`](tef-codes.md) | The transaction cannot be applied to the server's current (in-progress) ledger or any later one. It may have already been applied, or the condition of the ledger makes it impossible to apply in the future. |
| Local error | [`tel`](tel-codes.md) | The `rippled` server had an error due to local conditions, such as high load. You may get a different response if you resubmit to a different server or at a different time. |
| Malformed transaction | [`tem`](tem-codes.md) | The transaction was not valid, due to improper syntax, conflicting options, a bad signature, or something else. |
| Retry | [`ter`](ter-codes.md) | The transaction could not be applied, but it could apply successfully in a future ledger. |
| Success | [`tes`](tes-success.md) | (Not an error) The transaction succeeded. This result only final in a validated ledger. |
The `rippled` server automatically retries failed transactions. It is important not to assume that a transaction has completely failed based on a tentative failure result. A transaction may later succeed unless its success or failure is [final](../../../../concepts/transactions/finality-of-results/index.md).
**Warning:** Transactions' provisional result codes may differ than their final result. Transactions that provisionally succeeded may eventually fail and transactions that provisionally failed may eventually succeed. Transactions that provisionally failed may also eventually fail with a different code. See [finality of results](../../../../concepts/transactions/finality-of-results/index.md) for how to know when a transaction's result is final.
The distinction between a local error (`tel`) and a malformed transaction (`tem`) is a matter of protocol-level rules. For example, the protocol sets no limit on the maximum number of paths that can be included in a transaction. However, a server may define a finite limit of paths it can process. If two different servers are configured differently, then one of them may return a `tel` error for a transaction with many paths, while the other server could successfully process the transaction. If enough servers are able to process the transaction that it survives consensus, then it can still be included in a validated ledger.
By contrast, a `tem` error implies that no server anywhere can apply the transaction, regardless of settings. Either the transaction breaks the rules of the protocol, it is unacceptably ambiguous, or it is completely nonsensical. The only way a malformed transaction could become valid is through changes in the protocol; for example, if a new feature is adopted, then transactions using that feature could be considered malformed by servers that are running older software which predates that feature.
## Immediate Response
The response from the [submit method][] contains a provisional result from the `rippled` server indicating what happened during local processing of the transaction.
The response from `submit` contains the following fields:
| Field | Value | Description |
|:------------------------|:---------------|:----------------------------------|
| `engine_result` | String | A code indicating the outcome of the transaction, such as `tecPATH_DRY`. |
| `engine_result_code` | Signed Integer | A number that corresponds to the `engine_result`. The exact values are subject to change without notice. |
| `engine_result_message` | String | A human-readable message explaining what happened. This message is intended for developers to diagnose problems, and is subject to change without notice. |
If nothing went wrong when submitting and applying the transaction locally, the response looks like this:
```js
"engine_result": "tesSUCCESS",
"engine_result_code": 0,
"engine_result_message": "The transaction was applied. Only final in a validated ledger."
```
**Note:** A successful result at this stage does not indicate that the transaction has completely succeeded; only that it was successfully applied to the provisional version of the ledger kept by the local server. Failed results at this stage are also provisional and may change. See [Finality of Results](../../../../concepts/transactions/finality-of-results/index.md) for details.
{% raw-partial file="/_snippets/common-links.md" /%}

63
docs/references/protocol/transactions/types/accountdelete.md Normal file
View File

@@ -0,0 +1,63 @@
---
html: accountdelete.html
parent: transaction-types.html
seo:
description: Delete an account.
labels:
- Accounts
---
# AccountDelete
[[Source]](https://github.com/XRPLF/rippled/blob/develop/src/ripple/app/tx/impl/DeleteAccount.cpp "Source")
_Added by the [DeletableAccounts amendment](../../../../resources/known-amendments.md#deletableaccounts)_
An AccountDelete transaction deletes an [account](../../ledger-data/ledger-entry-types/accountroot.md) and any objects it owns in the XRP Ledger, if possible, sending the account's remaining XRP to a specified destination account. See [Deleting Accounts](../../../../concepts/accounts/deleting-accounts.md) for the requirements to delete an account.
## Example {% $frontmatter.seo.title %} JSON
```json
{
"TransactionType": "AccountDelete",
"Account": "rWYkbWkCeg8dP6rXALnjgZSjjLyih5NXm",
"Destination": "rPT1Sjq2YGrBMTttX4GZHjKu9dyfzbpAYe",
"DestinationTag": 13,
"Fee": "2000000",
"Sequence": 2470665,
"Flags": 2147483648
}
```
[Query example transaction. >](/resources/dev-tools/websocket-api-tool?server=wss%3A%2F%2Fxrplcluster.com%2F&req=%7B%22id%22%3A%22example_AccountDelete%22%2C%22command%22%3A%22tx%22%2C%22transaction%22%3A%221AF19BF9717DA0B05A3BFC5007873E7743BA54C0311CCCCC60776AAEAC5C4635%22%2C%22binary%22%3Afalse%7D)
{% raw-partial file="/_snippets/tx-fields-intro.md" /%}
<!--{# fix md highlighting_ #}-->
| Field | JSON Type | [Internal Type][] | Description |
|:-----------------|:-----------------|:------------------|:-------------------|
| `Destination` | String - [Address][] | AccountID | The address of an account to receive any leftover XRP after deleting the sending account. Must be a funded account in the ledger, and must not be the sending account. |
| `DestinationTag` | Number | UInt32 | _(Optional)_ Arbitrary [destination tag](../../../../concepts/transactions/source-and-destination-tags.md) that identifies a hosted recipient or other information for the recipient of the deleted account's leftover XRP. |
## Special Transaction Cost
As an additional deterrent against ledger spam, the AccountDelete transaction requires a much higher than usual [transaction cost](../../../../concepts/transactions/transaction-cost.md): instead of the standard minimum of 0.00001 XRP, AccountDelete must destroy at least the owner reserve amount, currently 2 XRP. This discourages excessive creation of new accounts because the [reserve requirement](../../../../concepts/accounts/reserves.md) cannot be fully recouped by deleting the account.
The transaction cost always applies when a transaction is included in a validated ledger, even if the transaction fails to delete the account. (See [Error Cases](#error-cases).) To greatly reduce the chances of paying the high transaction cost if the account cannot be deleted, [submit the transaction](../../../http-websocket-apis/public-api-methods/transaction-methods/submit.md) with `fail_hard` enabled.
## Error Cases
Besides errors that can occur for all transactions, {% $frontmatter.seo.title %} transactions can result in the following [transaction result codes](../transaction-results/transaction-results.md):
| Error Code | Description |
|:-----------|:------------|
| `temDISABLED` | Occurs if the [DeletableAccounts amendment](../../../../resources/known-amendments.md#deletableaccounts) is not enabled. |
| `temDST_IS_SRC` | Occurs if the `Destination` matches the sender of the transaction (`Account` field). |
| `tecDST_TAG_NEEDED` | Occurs if the `Destination` account requires a [destination tag](../../../../concepts/transactions/source-and-destination-tags.md), but the `DestinationTag` field was not provided. |
| `tecNO_DST` | Occurs if the `Destination` account is not a funded account in the ledger. |
| `tecNO_PERMISSION` | Occurs if the `Destination` account requires [deposit authorization](../../../../concepts/accounts/depositauth.md) and the sender is not preauthorized. |
| `tecTOO_SOON` | Occurs if the sender's `Sequence` number is too high. The transaction's `Sequence` number plus 256 must be less than the current [Ledger Index][]. This prevents replay of old transactions if this account is resurrected after it is deleted. |
| `tecHAS_OBLIGATIONS` | Occurs if the account to be deleted is connected to objects that cannot be deleted in the ledger. (This includes objects created by other accounts, such as [escrows](../../../../concepts/payment-types/escrow.md) and for example [NFT's minted](nftokenmint.md), [even if owned by another account](https://github.com/XRPLF/rippled/blob/develop/src/ripple/app/tx/impl/DeleteAccount.cpp#L197).) |
| `tefTOO_BIG` | Occurs if the sending account is linked to more than 1000 objects in the ledger. The transaction could succeed on retry if some of those objects were deleted separately first. |
{% raw-partial file="/_snippets/common-links.md" /%}

143
docs/references/protocol/transactions/types/accountset.md Normal file
View File

@@ -0,0 +1,143 @@
---
html: accountset.html
parent: transaction-types.html
seo:
description: Set options on an account.
labels:
- Accounts
---
# AccountSet
[[Source]](https://github.com/XRPLF/rippled/blob/master/src/ripple/app/tx/impl/SetAccount.cpp "Source")
An AccountSet transaction modifies the properties of an [account in the XRP Ledger](../../ledger-data/ledger-entry-types/accountroot.md).
## Example {% $frontmatter.seo.title %} JSON
```json
{
"TransactionType": "AccountSet",
"Account" : "rf1BiGeXwwQoi8Z2ueFYTEXSwuJYfV2Jpn",
"Fee": "12",
"Sequence": 5,
"Domain": "6578616D706C652E636F6D",
"SetFlag": 5,
"MessageKey": "03AB40A0490F9B7ED8DF29D246BF2D6269820A0EE7742ACDD457BEA7C7D0931EDB"
}
```
[Query example transaction. >](/resources/dev-tools/websocket-api-tool?server=wss%3A%2F%2Fxrplcluster.com%2F&req=%7B%22id%22%3A%22example_AccountSet%22%2C%22command%22%3A%22tx%22%2C%22transaction%22%3A%22327FD263132A4D08170E1B01FE1BB2E21D0126CE58165C97A9173CA9551BCD70%22%2C%22binary%22%3Afalse%7D)
{% raw-partial file="/_snippets/tx-fields-intro.md" /%}
| Field | JSON Type | [Internal Type][] | Description |
|:-----------------|:-----------------|:------------------|:-------------------|
| [`ClearFlag`](#accountset-flags) | Number | UInt32 | _(Optional)_ Unique identifier of a flag to disable for this account. |
| [`Domain`](#domain) | String | Blob | _(Optional)_ The domain that owns this account, as a string of hex representing the ASCII for the domain in lowercase. [Cannot be more than 256 bytes in length.](https://github.com/XRPLF/rippled/blob/55dc7a252e08a0b02cd5aa39e9b4777af3eafe77/src/ripple/app/tx/impl/SetAccount.h#L34) |
| `EmailHash` | String | Hash128 | _(Optional)_ An arbitrary 128-bit value. Conventionally, clients treat this as the md5 hash of an email address to use for displaying a [Gravatar](http://en.gravatar.com/site/implement/hash/) image. |
| `MessageKey` | String | Blob | _(Optional)_ Public key for sending encrypted messages to this account. To set the key, it must be exactly 33 bytes, with the first byte indicating the key type: `0x02` or `0x03` for secp256k1 keys, `0xED` for Ed25519 keys. To remove the key, use an empty value. |
| `NFTokenMinter` | String | Blob | _(Optional)_ Another account that can [mint NFTokens for you](../../../../tutorials/quickstart/assign-an-authorized-minter-using-javascript.md). _(Added by the [NonFungibleTokensV1_1 amendment][].)_ |
| [`SetFlag`](#accountset-flags) | Number | UInt32 | _(Optional)_ Integer flag to enable for this account. |
| [`TransferRate`](#transferrate) | Number | UInt32 | _(Optional)_ The fee to charge when users transfer this account's tokens, represented as billionths of a unit. Cannot be more than `2000000000` or less than `1000000000`, except for the special case `0` meaning no fee. |
| [`TickSize`](../../../../concepts/tokens/decentralized-exchange/ticksize.md) | Number | UInt8 | _(Optional)_ Tick size to use for offers involving a currency issued by this address. The exchange rates of those offers is rounded to this many significant digits. Valid values are `3` to `15` inclusive, or `0` to disable. _(Added by the [TickSize amendment][])_ |
| `WalletLocator` | String | Hash256 | _(Optional)_ An arbitrary 256-bit value. If specified, the value is stored as part of the account but has no inherent meaning or requirements. |
| `WalletSize` | Number | UInt32 | _(Optional)_ Not used. This field is valid in AccountSet transactions but does nothing. |
If none of these options are provided, then the AccountSet transaction has no effect (beyond destroying the transaction cost). See [Cancel or Skip a Transaction](../../../../concepts/transactions/finality-of-results/canceling-a-transaction.md) for more details.
## Domain
The `Domain` field is represented as the hex string of the lowercase ASCII of the domain. For example, the domain *example.com* would be represented as `"6578616D706C652E636F6D"`.
To remove the `Domain` field from an account, send an AccountSet with the Domain set to an empty string.
You can put any domain in your account's `Domain` field. To prove that an account and domain belong to the same person or business, you need a "two-way link":
- Accounts you own should have a domain you own in the `Domain` field.
- At that domain, host an [xrp-ledger.toml file](../../../xrp-ledger-toml.md) listing accounts you own, and optionally other information about how you use the XRP Ledger.
## AccountSet Flags
There are several options which can be either enabled or disabled for an account. Account options are represented by different types of flags depending on the situation:
* The `AccountSet` transaction type has several "AccountSet Flags" (prefixed **`asf`**) that can enable an option when passed as the `SetFlag` parameter, or disable an option when passed as the `ClearFlag` parameter. Newer options have only this style of flag. You can enable up to one `asf` flag per transaction, and disable up to one `asf` flag per transaction.
* The `AccountSet` transaction type has several transaction flags (prefixed **`tf`**) that can be used to enable or disable specific account options when passed in the `Flags` parameter. You can enable and disable a combination of settings in one transaction using multiple `tf` flags, but not all settings have `tf` flags.
* The `AccountRoot` ledger object type has several ledger-state-flags (prefixed **`lsf`**) which represent the state of particular account options within a particular ledger. These settings apply until a transaction changes them.
To enable or disable Account Flags, use the `SetFlag` and `ClearFlag` parameters of an AccountSet transaction. AccountSet flags have names that begin with **`asf`**.
All flags are disabled by default.
The available AccountSet flags are:
| Flag Name | Decimal Value | Corresponding Ledger Flag | Description |
|:----------------------------------|:--------------|:----------------------------------|:--------------|
| `asfAccountTxnID` | 5 | (None) | Track the ID of this account's most recent transaction. Required for [`AccountTxnID`](../common-fields.md#accounttxnid) |
| `asfAllowTrustLineClawback` | 16 | `lsfAllowTrustlineClawback` | Allow account to claw back tokens it has issued. _(Requires the Clawback amendment {% not-enabled /%})_ Can only be set if the account has an empty owner directory (no trust lines, offers, escrows, payment channels, checks, or signer lists). After you set this flag, it cannot be reverted. The account permanently gains the ability to claw back issued assets on trust lines. |
| `asfAuthorizedNFTokenMinter` | 10 | (None) | Enable to allow another account to mint non-fungible tokens (NFTokens) on this account's behalf. Specify the authorized account in the `NFTokenMinter` field of the [AccountRoot](../../ledger-data/ledger-entry-types/accountroot.md) object. To remove an authorized minter, enable this flag and omit the `NFTokenMinter` field. _(Added by the [NonFungibleTokensV1_1 amendment][].)_ |
| `asfDefaultRipple` | 8 | `lsfDefaultRipple` | Enable [rippling](../../../../concepts/tokens/fungible-tokens/rippling.md) on this account's trust lines by default. |
| `asfDepositAuth` | 9 | `lsfDepositAuth` | Enable [Deposit Authorization](../../../../concepts/accounts/depositauth.md) on this account. _(Added by the [DepositAuth amendment][].)_ |
| `asfDisableMaster` | 4 | `lsfDisableMaster` | Disallow use of the master key pair. Can only be enabled if the account has configured another way to sign transactions, such as a [Regular Key](../../../../concepts/accounts/cryptographic-keys.md) or a [Signer List](../../../../concepts/accounts/multi-signing.md). |
| `asfDisallowIncomingCheck` | 13 | `lsfDisallowIncomingCheck` | Block incoming Checks. _(Requires the [DisallowIncoming amendment][] {% not-enabled /%})_ |
| `asfDisallowIncomingNFTokenOffer` | 12 | `lsfDisallowIncomingNFTokenOffer` | Block incoming NFTokenOffers. _(Requires the [DisallowIncoming amendment][] {% not-enabled /%})_ |
| `asfDisallowIncomingPayChan` | 14 | `lsfDisallowIncomingPayChan` | Block incoming Payment Channels. _(Requires the [DisallowIncoming amendment][] {% not-enabled /%})_ |
| `asfDisallowIncomingTrustline` | 15 | `lsfDisallowIncomingTrustline` | Block incoming trust lines. _(Requires the [DisallowIncoming amendment][] {% not-enabled /%})_ |
| `asfDisallowXRP` | 3 | `lsfDisallowXRP` | XRP should not be sent to this account. (Advisory; not enforced by the XRP Ledger protocol.) |
| `asfGlobalFreeze` | 7 | `lsfGlobalFreeze` | [Freeze](../../../../concepts/tokens/fungible-tokens/freezes.md) all assets issued by this account. |
| `asfNoFreeze` | 6 | `lsfNoFreeze` | Permanently give up the ability to [freeze individual trust lines or disable Global Freeze](../../../../concepts/tokens/fungible-tokens/freezes.md). This flag can never be disabled after being enabled. |
| `asfRequireAuth` | 2 | `lsfRequireAuth` | Require authorization for users to hold balances issued by this address. Can only be enabled if the address has no trust lines connected to it. |
| `asfRequireDest` | 1 | `lsfRequireDestTag` | Require a destination tag to send transactions to this account. |
To enable the `asfDisableMaster` or `asfNoFreeze` flags, you must [authorize the transaction](../../../../concepts/transactions/index.md#authorizing-transactions) by signing it with the master key pair. You cannot use a regular key pair or a multi-signature. You can disable `asfDisableMaster` (that is, re-enable the master key pair) using a regular key pair or multi-signature.
The following [Transaction flags](../common-fields.md#flags-field) (`tf` flags), specific to the AccountSet transaction type, serve the same purpose. Due to limited space, some settings do not have associated `tf` flags, and new `tf` flags are not being added to the `AccountSet` transaction type. You can use a combination of `tf` and `asf` flags to enable multiple settings with a single transaction.
| Flag Name | Hex Value | Decimal Value | Replaced by AccountSet Flag |
|:--------------------|:-------------|:--------------|:----------------------------|
| `tfRequireDestTag` | `0x00010000` | 65536 | `asfRequireDest` (`SetFlag`) |
| `tfOptionalDestTag` | `0x00020000` | 131072 | `asfRequireDest` (`ClearFlag`) |
| `tfRequireAuth` | `0x00040000` | 262144 | `asfRequireAuth` (`SetFlag`) |
| `tfOptionalAuth` | `0x00080000` | 524288 | `asfRequireAuth` (`ClearFlag`) |
| `tfDisallowXRP` | `0x00100000` | 1048576 | `asfDisallowXRP` (`SetFlag`) |
| `tfAllowXRP` | `0x00200000` | 2097152 | `asfDisallowXRP` (`ClearFlag`) |
**Caution:** The numeric values of `tf` and `asf` flags in transactions do not match up with the values they set in the accounts "at rest" in the ledger. To read the flags of an account in the ledger, see [`AccountRoot` flags](../../ledger-data/ledger-entry-types/accountroot.md#accountroot-flags).
### Blocking Incoming Transactions
<!-- This concept info should be moved to another topic after the IA.v2 migration. -->
Incoming transactions with unclear purposes may be an inconvenience for financial institutions, who would have to recognize when a customer made a mistake, and then potentially refund accounts or adjust balances depending on the mistake. The `asfRequireDest` and `asfDisallowXRP` flags are intended to protect users from accidentally sending funds in a way that is unclear about the reason the funds were sent.
For example, a destination tag is typically used to identify which hosted balance should be credited when a financial institution receives a payment. If the destination tag is omitted, it may be unclear which account should be credited, creating a need for refunds, among other problems. By using the `asfRequireDest` tag, you can ensure that every incoming payment has a destination tag, which makes it harder for others to send you an ambiguous payment by accident.
You can protect against unwanted incoming payments for non-XRP currencies by not creating trust lines in those currencies. Since XRP does not require trust, the `asfDisallowXRP` flag is used to discourage users from sending XRP to an account. However, this flag is not enforced in the XRP Ledger protocol because it could potentially cause accounts to become unusable if they run out of XRP. Instead, client applications should disallow or discourage XRP payments to accounts with the `asfDisallowXRP` flag enabled.
If you want to block _all_ incoming payments, you can enable [Deposit Authorization](../../../../concepts/accounts/depositauth.md). This prevents any transaction from sending money to you, even XRP, unless your account is below the [reserve requirement](../../../../concepts/accounts/reserves.md).
If the [DisallowIncoming amendment][] {% not-enabled /%} is enabled, you also have the option to block all incoming Checks, NFTokenOffers, Payment Channels, and trust lines. It is generally harmless to be on the receiving end of these objects, but they can block you from deleting your account and it can be confusing to have objects you didn't expect mixed in with the list of objects you created. To block incoming objects, use one or more of these account flags:
- `asfDisallowIncomingCheck` - for Check objects
- `asfDisallowIncomingNFTOffer` - for NFTokenOffer objects
- `asfDisallowIncomingPayChan` - for PayChannel objects
- `asfDisallowIncomingTrustline` - for RippleState (trust line) objects
When a transaction would create one of these ledger entries, if the destination account has the corresponding flag enabled, the transaction fails with the result code `tecNO_PERMISSION`. Unlike Deposit Authorization, these settings do not prevent you from receiving payments in general. Also, enabling this setting doesn't stop you from creating these types of objects yourself (unless the destination of your transaction is also using the setting, of course).
## TransferRate
The `TransferRate` field specifies a fee to charge whenever counterparties transfer the currency you issue.
In the HTTP and WebSocket APIs, the transfer fee is represented as an integer, the amount that must be sent for 1 billion units to arrive. For example, a 20% transfer fee is represented as the value `1200000000`. The value cannot be less than 1000000000. (Less than that would indicate giving away money for sending transactions, which is exploitable.) You can specify `0` as a shortcut for `1000000000`, meaning no fee.
See [Transfer Fees](../../../../concepts/tokens/transfer-fees.md) for more information.
## NFTokenMinter
To remove an authorized minter, set `ClearFlag` to 10 (`asfAuthorizedNFTokenMinter`) and omit the `NFTokenMinter` field.
<!-- SPELLING_IGNORE: TransferRate -->
{% raw-partial file="/_snippets/common-links.md" /%}

142
docs/references/protocol/transactions/types/ammbid.md Normal file
View File

@@ -0,0 +1,142 @@
---
html: ammbid.html
parent: transaction-types.html
seo:
description: Bid on an Automated Market Maker's auction slot, which grants a discounted fee.
labels:
- AMM
status: not_enabled
---
# AMMBid
[[Source]](https://github.com/XRPLF/rippled/blob/master/src/ripple/app/tx/impl/AMMBid.cpp "Source")
_(Requires the [AMM amendment][] {% not-enabled /%})_
Bid on an [Automated Market Maker](../../../../concepts/tokens/decentralized-exchange/automated-market-makers.md)'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 {% $frontmatter.seo.title %} 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"
}
```
{% raw-partial file="/_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 [Auth Account object](#auth-account-objects). |
You cannot specify both `BidMin` and `BidMax`.
### Auth Account 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](../../../../concepts/ledgers/ledger-close-times.md) 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](../../../../concepts/ledgers/ledger-close-times.md) of the _previous_ ledger, which can result in a difference of up to about 10 seconds from real time.
## Error Cases
Besides errors that can occur for all transactions, {% $frontmatter.seo.title %} transactions can result in the following [transaction result codes](../transaction-results/transaction-results.md):
| Error Code | Description |
|:------------------------|:---------------------------------------------|
| `tecAMM_EMPTY` | The AMM has no assets in its pool. In this state, you can only delete the AMM or fund it with a new deposit. |
| `tecAMM_FAILED` | 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. |
| `temDISABLED` | The AMM feature is not enabled on this network. |
| `temMALFORMED` | The transaction specified invalid options, such as a list of `AuthAccounts` that is too long. |
| `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. |
{% raw-partial file="/_snippets/common-links.md" /%}

73
docs/references/protocol/transactions/types/ammcreate.md Normal file
View File

@@ -0,0 +1,73 @@
---
html: ammcreate.html
parent: transaction-types.html
seo:
description: Create a new Automated Market Maker for trading a given pair of assets.
labels:
- AMM
status: not_enabled
---
# AMMCreate
[[Source]](https://github.com/XRPLF/rippled/blob/master/src/ripple/app/tx/impl/AMMCreate.cpp "Source")
_(Requires the [AMM amendment][] {% not-enabled /%})_
Create a new [Automated Market Maker](../../../../concepts/tokens/decentralized-exchange/automated-market-makers.md) (AMM) instance for trading a pair of assets ([fungible tokens](../../../../concepts/tokens/index.md) or [XRP](../../../../introduction/what-is-xrp.md)).
Creates both an [AMM entry][] and a [special AccountRoot entry](../../ledger-data/ledger-entry-types/accountroot.md#special-amm-accountroot-entries) 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 {% $frontmatter.seo.title %} JSON
```json
{
"Account" : "rJVUeRqDFNs2xqA7ncVE6ZoAhPUoaJJSQm",
"Amount" : {
"currency" : "TST",
"issuer" : "rP9jPyP5kyvFRb6ZiRghAGw5u8SGAmU4bd",
"value" : "25"
},
"Amount2" : "250000000",
"Fee" : "2000000",
"Flags" : 2147483648,
"Sequence" : 6,
"TradingFee" : 500,
"TransactionType" : "AMMCreate"
}
```
{% raw-partial file="/_snippets/tx-fields-intro.md" /%}
| 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](../../../../concepts/tokens/index.md); at most one of them can be [XRP](../../../../introduction/what-is-xrp.md). They cannot both have the same currency code and issuer. The tokens' issuers must have [Default Ripple](../../../../concepts/tokens/fungible-tokens/rippling.md#the-default-ripple-flag) enabled. If the [Clawback amendment][] {% not-enabled /%} is enabled, those issuers must not have enabled the Allow Clawback flag. The assets _cannot_ be LP tokens for another AMM.
## Special Transaction Cost
Since each AMM instance involves an AccountRoot ledger entry, an AMM ledger entry, and a trust line for each token in its pool, an AMMCreate transaction requires a much higher than usual [transaction cost][] to deter ledger spam. Instead of the standard minimum of 0.00001 XRP, AMMCreate must destroy at least the incremental owner reserve amount, currently 2 XRP. This is the same special transaction cost as [AccountDelete transactions][].
## Error Cases
Besides errors that can occur for all transactions, {% $frontmatter.seo.title %} transactions can result in the following [transaction result codes](../transaction-results/transaction-results.md):
| Error Code | Description |
|:--------------------|:---------------------------------------------|
| `tecAMM_INVALID_TOKENS` | Either `Amount` or `Amount2` has a currency code that is the same as this AMM's LP Tokens would use. (This is very unlikely to occur.) |
| `tecDUPLICATE` | There is already another AMM for this currency pair. |
| `tecFROZEN` | At least one of the deposit assets (`Amount` or `Amount2`) is currently [frozen](../../../../concepts/tokens/fungible-tokens/freezes.md). |
| `tecINSUF_RESERVE_LINE` | The sender of this transaction does meet the increased [reserve requirement](../../../../concepts/accounts/reserves.md) 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` | At least one of the deposit assets uses [authorized trust lines](../../../../concepts/tokens/fungible-tokens/authorized-trust-lines.md) and the sender does not have authorization to hold that asset. |
| `tecNO_LINE` | The sender does not have a trust line for at least one of the deposit assets. |
| `tecNO_PERMISSION` | At least one of the deposit assets cannot be used in an AMM. For example, the issuer has enabled Clawback support. |
| `tecUNFUNDED_AMM` | The sender does not hold enough of the assets specified in `Amount` and `Amount2` to fund the AMM. |
| `terNO_RIPPLE` | The issuer of at least one of the assets has not enabled the [Default Ripple flag](../../../../concepts/tokens/fungible-tokens/rippling.md#the-default-ripple-flag). |
| `temAMM_BAD_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. |
| `temDISABLED` | The AMM feature is not enabled on this network. |
{% raw-partial file="/_snippets/common-links.md" /%}

57
docs/references/protocol/transactions/types/ammdelete.md Normal file
View File

@@ -0,0 +1,57 @@
---
html: ammdelete.html
parent: transaction-types.html
seo:
description: Delete an Automated Market Maker instance with an empty asset pool.
labels:
- AMM
status: not_enabled
---
# AMMDelete
[[Source]](https://github.com/XRPLF/rippled/blob/develop/src/ripple/app/tx/impl/AMMDelete.cpp "Source")
_(Requires the [AMM amendment][] {% not-enabled /%})_
Delete an empty [Automated Market Maker](../../../../concepts/tokens/decentralized-exchange/automated-market-makers.md) (AMM) instance that could not be fully deleted automatically.
Normally, an [AMMWithdraw transaction][] automatically deletes an AMM and all associated ledger entries when it withdraws all the assets from the AMM's pool. However, if there are too many trust lines to the AMM account to remove in one transaction, it may stop before fully removing the AMM. Similarly, an AMMDelete transaction removes up to a maximum of 512 trust lines; it may take several AMMDelete transactions to delete all the trust lines and the associated AMM. In all cases, only the last such transaction deletes the AMM and AccountRoot ledger entries.
## Example {% $frontmatter.seo.title %} JSON
```json
{
"Account" : "rJVUeRqDFNs2xqA7ncVE6ZoAhPUoaJJSQm",
"Asset" : {
"currency" : "XRP"
},
"Asset2" : {
"currency" : "TST",
"issuer" : "rP9jPyP5kyvFRb6ZiRghAGw5u8SGAmU4bd"
},
"Fee" : "10",
"Flags" : 0,
"Sequence" : 9,
"TransactionType" : "AMMDelete"
}
```
{% raw-partial file="/_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). |
## Error Cases
Besides errors that can occur for all transactions, AMMCreate transactions can result in the following [transaction result codes](../transaction-results/transaction-results.md):
| Error Code | Description |
|:--------------------|:---------------------------------------------|
| `tecAMM_NOT_EMPTY` | The AMM holds assets in its pools, so it cannot be deleted. If you are one of the AMM's liquidity providers, use [AMMWithdraw][] first. |
| `tecINCOMPLETE` | There were too many associated ledger entries to fully delete, so the transaction removed as many as it could, but the AMM has not been fully deleted. You can send another AMMDelete transaction to continue and possibly finish the job. |
| `terNO_AMM` | The specified AMM does not exist. (It may have been deleted already, or you may have specified a wrong asset for the AMM you intended.) |
{% raw-partial file="/_snippets/common-links.md" /%}

142
docs/references/protocol/transactions/types/ammdeposit.md Normal file
View File

@@ -0,0 +1,142 @@
---
html: ammdeposit.html
parent: transaction-types.html
seo:
description: Deposit funds into an Automated Market Maker in exchange for LPTokens.
labels:
- AMM
status: not_enabled
---
# AMMDeposit
[[Source]](https://github.com/XRPLF/rippled/blob/master/src/ripple/app/tx/impl/AMMDeposit.cpp "Source")
_(Requires the [AMM amendment][] {% not-enabled /%})_
Deposit funds into an [Automated Market Maker](../../../../concepts/tokens/decentralized-exchange/automated-market-makers.md) (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](../../../../concepts/tokens/fungible-tokens/index.md) to the AMM Account (limit 0) to hold the LP Tokens.
## Example {% $frontmatter.seo.title %} 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"
}
```
{% raw-partial file="/_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. |
| `tfTwoAssetIfEmpty` | `0x00800000` | `Amount` and `Amount2` | Deposit both of this AMM's assets, in exactly the specified amounts, to an AMM with an empty asset pool. 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 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:
[{% inline-svg file="/img/amm-single-asset-deposit-formula.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
### 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](../common-fields.md#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. |
| `tfTwoAssetIfEmpty` | `0x00800000` | 8388608 | Perform a special double-asset deposit to an AMM with an empty pool. |
You must specify **exactly one** of these flags, plus any [global flags](../common-fields.md#global-flags).
## Error Cases
Besides errors that can occur for all transactions, {% $frontmatter.seo.title %} transactions can result in the following [transaction result codes](../transaction-results/transaction-results.md):
| Error Code | Description |
|:------------------------|:---------------------------------------------|
| `tecAMM_EMPTY` | The AMM currently holds no assets, so you cannot do a normal deposit. You must use the Empty AMM Special Case deposit instead. |
| `tecAMM_NOT_EMPTY` | The transaction specified `tfTwoAssetIfEmpty`, but the AMM was not empty. |
| `tecAMM_FAILED` | The conditions on the deposit could not be satisfied. For example, the requested effective price in the `EPrice` field is too low. |
| `tecFROZEN` | The transaction tried to deposit a [frozen](../../../../concepts/tokens/fungible-tokens/freezes.md) token. |
| `tecINSUF_RESERVE_LINE` | The sender of this transaction does meet the increased [reserve requirement](../../../../concepts/accounts/reserves.md) 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. |
| `tecUNFUNDED_AMM` | The sender does not have a high enough balance to make the specified deposit. |
| `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. |
| `temBAD_AMOUNT` | An amount specified in the transaction is invalid. For example, a deposit amount is negative. |
| `temBAD_FEE` | A fee value specified in the transaction is invalid. For example, the trading fee is outside the allowable range. |
| `temMALFORMED` | The transaction specified an invalid combination of fields. See [AMMDeposit Modes](#ammdeposit-modes). |
| `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. |
{% raw-partial file="/_snippets/common-links.md" /%}

57
docs/references/protocol/transactions/types/ammvote.md Normal file
View File

@@ -0,0 +1,57 @@
---
html: ammvote.html
parent: transaction-types.html
seo:
description: Vote on the trading fee for an Automated Market Maker instance.
labels:
- AMM
status: not_enabled
---
# AMMVote
[[Source]](https://github.com/XRPLF/rippled/blob/master/src/ripple/app/tx/impl/AMMVote.cpp "Source")
_(Requires the [AMM amendment][] {% not-enabled /%})_
Vote on the trading fee for an [Automated Market Maker](../../../../concepts/tokens/decentralized-exchange/automated-market-makers.md) 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 {% $frontmatter.seo.title %} JSON
```json
{
"Account" : "rJVUeRqDFNs2xqA7ncVE6ZoAhPUoaJJSQm",
"Asset" : {
"currency" : "XRP"
},
"Asset2" : {
"currency" : "TST",
"issuer" : "rP9jPyP5kyvFRb6ZiRghAGw5u8SGAmU4bd"
},
"Fee" : "10",
"Flags" : 2147483648,
"Sequence" : 8,
"TradingFee" : 600,
"TransactionType" : "AMMVote"
}
```
{% raw-partial file="/_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
Besides errors that can occur for all transactions, {% $frontmatter.seo.title %} transactions can result in the following [transaction result codes](../transaction-results/transaction-results.md):
| Error Code | Description |
|:------------------------|:---------------------------------------------|
| `tecAMM_EMPTY` | The AMM has no assets in its pool. In this state, you can only delete the AMM or fund it with a new deposit. |
| `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. |
| `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. |
{% raw-partial file="/_snippets/common-links.md" /%}

125
docs/references/protocol/transactions/types/ammwithdraw.md Normal file
View File

@@ -0,0 +1,125 @@
---
html: ammwithdraw.html
parent: transaction-types.html
seo:
description: 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/XRPLF/rippled/blob/master/src/ripple/app/tx/impl/AMMWithdraw.cpp "Source")
_(Requires the [AMM amendment][] {% not-enabled /%})_
Withdraw assets from an [Automated Market Maker](../../../../concepts/tokens/decentralized-exchange/automated-market-makers.md) (AMM) instance by returning the AMM's liquidity provider tokens (LP Tokens).
## Example {% $frontmatter.seo.title %} 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"
}
```
{% raw-partial file="/_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 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 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 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.
<!-- TODO: add a formula and example calculation(s) of single-asset withdrawal fees -->
### 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](../common-fields.md#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, plus any [global flags](../common-fields.md#global-flags).
## Error Cases
Besides errors that can occur for all transactions, {% $frontmatter.seo.title %} transactions can result in the following [transaction result codes](../transaction-results/transaction-results.md):
| Error Code | Description |
|:------------------------|:---------------------------------------------|
| `tecAMM_EMPTY` | The AMM has no assets in its pool. In this state, you can only delete the AMM or fund it with a new deposit. |
| `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` | 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. |
| `tecFROZEN` | The transaction tried to withdraw a [frozen](../../../../concepts/tokens/fungible-tokens/freezes.md) token. |
| `tecINSUF_RESERVE_LINE` | The sender of this transaction does not meet the increased [reserve requirement](../../../../concepts/accounts/reserves.md) 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 AMM assets. |
| `temMALFORMED` | The transaction specified an invalid combination of fields. See [AMMWithdraw Modes](#ammwithdraw-modes). (This error can also occur if the transaction is malformed in other ways.) |
| `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. |
{% raw-partial file="/_snippets/common-links.md" /%}

41
docs/references/protocol/transactions/types/checkcancel.md Normal file
View File

@@ -0,0 +1,41 @@
---
html: checkcancel.html
parent: transaction-types.html
seo:
description: Cancel a check.
labels:
- Checks
---
# CheckCancel
[[Source]](https://github.com/XRPLF/rippled/blob/master/src/ripple/app/tx/impl/CancelCheck.cpp "Source")
_(Added by the [Checks amendment][].)_
Cancels an unredeemed Check, removing it from the ledger without sending any money. The source or the destination of the check can cancel a Check at any time using this transaction type. If the Check has expired, any address can cancel it.
## Example {% $frontmatter.seo.title %} JSON
```json
{
"Account": "rUn84CUYbNjRoTQ6mSW7BVJPSVJNLb1QLo",
"TransactionType": "CheckCancel",
"CheckID": "49647F0D748DC3FE26BDACBC57F251AADEFFF391403EC9BF87C97F67E9977FB0",
"Fee": "12"
}
```
[Query example transaction. >](/resources/dev-tools/websocket-api-tool?server=wss%3A%2F%2Fs1.ripple.com%2F&req=%7B%22id%22%3A%22example_CheckCancel%22%2C%22command%22%3A%22tx%22%2C%22transaction%22%3A%22D3328000315C6DCEC1426E4E549288E3672752385D86A40D56856DBD10382953%22%2C%22binary%22%3Afalse%7D)
{% raw-partial file="/_snippets/tx-fields-intro.md" /%}
<!--{# fix md highlighting_ #}-->
| Field | JSON Type | [Internal Type][] | Description |
|:------------|:----------|:------------------|:-------------------------------|
| `CheckID` | String | Hash256 | The ID of the [Check ledger object](../../ledger-data/ledger-entry-types/check.md) to cancel, as a 64-character hexadecimal string. |
## Error Cases
- If the object identified by the `CheckID` does not exist or is not a Check, the transaction fails with the result `tecNO_ENTRY`.
- If the Check is not expired and the sender of the CheckCancel transaction is not the source or destination of the Check, the transaction fails with the result `tecNO_PERMISSION`.
{% raw-partial file="/_snippets/common-links.md" /%}

52
docs/references/protocol/transactions/types/checkcash.md Normal file
View File

@@ -0,0 +1,52 @@
---
html: checkcash.html
parent: transaction-types.html
seo:
description: Redeem a check.
labels:
- Checks
---
# CheckCash
[[Source]](https://github.com/XRPLF/rippled/blob/master/src/ripple/app/tx/impl/CashCheck.cpp "Source")
_(Added by the [Checks amendment][].)_
Attempts to redeem a Check object in the ledger to receive up to the amount authorized by the corresponding [CheckCreate transaction][]. Only the `Destination` address of a Check can cash it with a CheckCash transaction. Cashing a check this way is similar to executing a [Payment][] initiated by the destination.
Since the funds for a check are not guaranteed, redeeming a Check can fail because the sender does not have a high enough balance or because there is not enough liquidity to deliver the funds. If this happens, the Check remains in the ledger and the destination can try to cash it again later, or for a different amount.
## Example {% $frontmatter.seo.title %} JSON
```json
{
"Account": "rfkE1aSy9G8Upk4JssnwBxhEv5p4mn2KTy",
"TransactionType": "CheckCash",
"Amount": "100000000",
"CheckID": "838766BA2B995C00744175F69A1B11E32C3DBC40E64801A4056FCBD657F57334",
"Fee": "12"
}
```
[Query example transaction. >](/resources/dev-tools/websocket-api-tool?server=wss%3A%2F%2Fs1.ripple.com%2F&req=%7B%22id%22%3A%22example_CheckCash%22%2C%22command%22%3A%22tx%22%2C%22transaction%22%3A%2267B71B13601CDA5402920691841AC27A156463678E106FABD45357175F9FF406%22%2C%22binary%22%3Afalse%7D)
{% raw-partial file="/_snippets/tx-fields-intro.md" /%}
<!--{# fix md highlighting_ #}-->
| Field | JSON Type | [Internal Type][] | Description |
|:-------------|:--------------------|:------------------|:--------------------|
| `CheckID` | String | Hash256 | The ID of the [Check ledger object](../../ledger-data/ledger-entry-types/check.md) to cash, as a 64-character hexadecimal string. |
| `Amount` | [Currency Amount][] | Amount | _(Optional)_ Redeem the Check for exactly this amount, if possible. The currency must match that of the `SendMax` of the corresponding CheckCreate transaction. You must provide either this field or `DeliverMin`. |
| `DeliverMin` | [Currency Amount][] | Amount | _(Optional)_ Redeem the Check for at least this amount and for as much as possible. The currency must match that of the `SendMax` of the corresponding CheckCreate transaction. You must provide either this field or `Amount`. |
The transaction ***must*** include either `Amount` or `DeliverMin`, but not both.
## Error Cases
- If the sender of the CheckCash transaction is not the `Destination` of the check, the transaction fails with the result code `tecNO_PERMISSION`.
- If the Check identified by the `CheckID` field does not exist, the transaction fails with the result `tecNO_ENTRY`.
- If the Check identified by the `CheckID` field has already expired, the transaction fails with the result `tecEXPIRED`.
- If the destination of the Check has the `RequireDest` flag enabled but the Check, as created, does not have a destination tag, the transaction fails with the result code `tecDST_TAG_NEEDED`.
- If the transaction specifies both `Amount` and `DeliverMin`, or omits both, the transaction fails with the result `temMALFORMED`.
- If the `Amount` or `DeliverMin` does not match the currency (and issuer, if not XRP) of the Check, the transaction fails with the result `temBAD_CURRENCY`.
{% raw-partial file="/_snippets/common-links.md" /%}

55
docs/references/protocol/transactions/types/checkcreate.md Normal file
View File

@@ -0,0 +1,55 @@
---
html: checkcreate.html
parent: transaction-types.html
seo:
description: Create a check.
labels:
- Checks
---
# CheckCreate
[[Source]](https://github.com/XRPLF/rippled/blob/master/src/ripple/app/tx/impl/CreateCheck.cpp "Source")
_(Added by the [Checks amendment][].)_
Create a Check object in the ledger, which is a deferred payment that can be cashed by its intended destination. The sender of this transaction is the sender of the Check.
## Example {% $frontmatter.seo.title %} JSON
```json
{
"TransactionType": "CheckCreate",
"Account": "rUn84CUYbNjRoTQ6mSW7BVJPSVJNLb1QLo",
"Destination": "rfkE1aSy9G8Upk4JssnwBxhEv5p4mn2KTy",
"SendMax": "100000000",
"Expiration": 570113521,
"InvoiceID": "6F1DFD1D0FE8A32E40E1F2C05CF1C15545BAB56B617F9C6C2D63A6B704BEF59B",
"DestinationTag": 1,
"Fee": "12"
}
```
[Query example transaction. >](/resources/dev-tools/websocket-api-tool?server=wss%3A%2F%2Fxrplcluster.com%2F&req=%7B%22id%22%3A%22example_CheckCreate%22%2C%22command%22%3A%22tx%22%2C%22transaction%22%3A%224E0AA11CBDD1760DE95B68DF2ABBE75C9698CEB548BEA9789053FCB3EBD444FB%22%2C%22binary%22%3Afalse%7D)
{% raw-partial file="/_snippets/tx-fields-intro.md" /%}
<!--{# fix md highlighting_ #}-->
| Field | JSON Type | [Internal Type][] | Description |
|:-----------------|:--------------------|:------------------|:----------------|
| `Destination` | String | AccountID | The unique address of the [account](../../../../concepts/accounts/accounts.md) that can cash the Check. |
| `SendMax` | [Currency Amount][] | Amount | Maximum amount of source currency the Check is allowed to debit the sender, including [transfer fees](../../../../concepts/tokens/transfer-fees.md) on non-XRP currencies. The Check can only credit the destination with the same currency (from the same issuer, for non-XRP currencies). For non-XRP amounts, the nested field names MUST be lower-case. |
| `DestinationTag` | Number | UInt32 | _(Optional)_ Arbitrary tag that identifies the reason for the Check, or a hosted recipient to pay. |
| `Expiration` | Number | UInt32 | _(Optional)_ Time after which the Check is no longer valid, in [seconds since the Ripple Epoch][]. |
| `InvoiceID` | String | Hash256 | _(Optional)_ Arbitrary 256-bit hash representing a specific reason or identifier for this Check. |
## Error Cases
- If the `Destination` account is blocking incoming Checks, the transaction fails with the result code `tecNO_PERMISSION`. _(Requires the [DisallowIncoming amendment][] {% not-enabled /%})_
- If the `Destination` is the sender of the transaction, the transaction fails with the result code `temREDUNDANT`.
- If the `Destination` [account](../../../../concepts/accounts/accounts.md) does not exist in the ledger, the transaction fails with the result code `tecNO_DST`.
- If the `Destination` account has the `RequireDest` flag enabled but the transaction does not include a `DestinationTag` field, the transaction fails with the result code `tecDST_TAG_NEEDED`.
- If `SendMax` specifies a token which is [frozen](../../../../concepts/tokens/fungible-tokens/freezes.md), the transaction fails with the result `tecFROZEN`.
- If the `Expiration` of the transaction is in the past, the transaction fails with the result `tecEXPIRED`.
- If the sender does not have enough XRP to meet the [owner reserve](../../../../concepts/accounts/reserves.md#owner-reserves) after adding the Check, the transaction fails with the result `tecINSUFFICIENT_RESERVE`.
- If either the sender or the destination of the Check cannot own more objects in the ledger, the transaction fails with the result `tecDIR_FULL`.
{% raw-partial file="/_snippets/common-links.md" /%}

53
docs/references/protocol/transactions/types/clawback.md Normal file
View File

@@ -0,0 +1,53 @@
---
html: clawback.html
parent: transaction-types.html
seo:
description: Claw back tokens you've issued.
labels:
- Tokens
---
# Clawback
[[Source]](https://github.com/XRPLF/rippled/blob/master/src/ripple/app/tx/impl/Clawback.cpp "Source")
{% partial file="/_snippets/clawback-disclaimer.md" /%}
Claw back tokens issued by your account.
Clawback is disabled by default. To use clawback, you must send an [AccountSet transaction][] to enable the **Allow Trust Line Clawback** setting. An issuer with any existing tokens cannot enable Clawback. You can only enable **Allow Trust Line Clawback** if you have a completely empty owner directory, meaning you must do so before you set up any trust lines, offers, escrows, payment channels, checks, or signer lists. After you enable Clawback, it cannot reverted: the account permanently gains the ability to claw back issued assets on trust lines.
## Example {% $frontmatter.seo.title %} JSON
```json
{
"TransactionType": "Clawback",
"Account": "rp6abvbTbjoce8ZDJkT6snvxTZSYMBCC9S",
"Amount": {
"currency": "FOO",
"issuer": "rsA2LpzuawewSBQXkiju3YQTMzW13pAAdW",
"value": "314.159"
}
}
```
{% raw-partial file="/_snippets/tx-fields-intro.md" /%}
| Field | JSON Type | [Internal Type][] | Description |
|:-------------------|:----------|:------------------|:------------------|
| `Amount` | [Currency Amount][] | Amount |Indicates the amount being clawed back, as well as the counterparty from which the amount is being clawed back. The quantity to claw back, in the `value` sub-field, must not be zero. If this is more than the current balance, the transaction claws back the entire balance. The sub-field `issuer` within `Amount` represents the token holder's account ID, rather than the issuer's.|
**Note:** In the XRP Ledger, the party that created a token is called the _issuer_, but trust lines are bidirectional and, under some configurations, both sides can be seen as the issuer. In this transaction, the token issuer's address is in the `Account` field, and the token holder's address is in the `Amount` field's `issuer` sub-field.
## Error Cases
Besides errors that can occur for all transactions, {% $frontmatter.seo.title %} transactions can result in the following [transaction result codes](../transaction-results/transaction-results.md):
| Error Code | Description |
|:-----------|:------------|
| `temDISABLED` | Occurs if the [Clawback amendment](../../../../resources/known-amendments.md#clawback) is not enabled. |
| `temBAD_AMOUNT` | Occurs if the holder's balance is 0. It is not an error if the amount exceeds the holder's balance; in that case, the maximum available balance is clawed back. Also occurs if the counterparty listed in `Amount` is the same as the `Account` issuing this transaction. |
| `tecNO_LINE` | Occurs there is no trust line with the counterparty or that trust line's balance is 0. |
| `tecNO_PERMISSION` | Occurs if you attempt to set `lsfAllowTrustlineClawback` while `lsfNoFreeze` is set. Also occurs, conversely, if you try to set `lsfNoFreeze` while `lsfAllowTrustLineClawback` is set. |
{% raw-partial file="/_snippets/common-links.md" /%}

52
docs/references/protocol/transactions/types/depositpreauth.md Normal file
View File

@@ -0,0 +1,52 @@
---
html: depositpreauth.html
parent: transaction-types.html
seo:
description: Preauthorizes an account to send payments to this one.
labels:
- Security
---
# DepositPreauth
[[Source]](https://github.com/XRPLF/rippled/blob/master/src/ripple/app/tx/impl/DepositPreauth.cpp "Source")
_Added by the [DepositPreauth amendment][]._
A DepositPreauth transaction gives another account pre-approval to deliver payments to the sender of this transaction. This is only useful if the sender of this transaction is using (or plans to use) [Deposit Authorization](../../../../concepts/accounts/depositauth.md).
**Tip:** You can use this transaction to preauthorize certain counterparties before you enable Deposit Authorization. This may be useful to ensure a smooth transition from not requiring deposit authorization to requiring it.
## Example {% $frontmatter.seo.title %} JSON
```json
{
"TransactionType" : "DepositPreauth",
"Account" : "rsUiUMpnrgxQp24dJYZDhmV4bE3aBtQyt8",
"Authorize" : "rEhxGqkqPPSxQ3P25J66ft5TwpzV14k2de",
"Fee" : "10",
"Flags" : 2147483648,
"Sequence" : 2
}
```
[Query example transaction. >](/resources/dev-tools/websocket-api-tool?server=wss%3A%2F%2Fxrplcluster.com%2F&req=%7B%22id%22%3A%22example_DepositPreauth%22%2C%22command%22%3A%22tx%22%2C%22transaction%22%3A%22CB1BF910C93D050254C049E9003DA1A265C107E0C8DE4A7CFF55FADFD39D5656%22%2C%22binary%22%3Afalse%7D)
{% raw-partial file="/_snippets/tx-fields-intro.md" /%}
<!--{# fix md highlighting_ #}-->
| Field | JSON Type | [Internal Type][] | Description |
|:--------------|:----------|:------------------|:-----|
| `Authorize` | String | AccountID | _(Optional)_ The XRP Ledger address of the sender to preauthorize. |
| `Unauthorize` | String | AccountID | _(Optional)_ The XRP Ledger address of a sender whose preauthorization should be revoked. |
You must provide _either_ `Authorize` or `Unauthorize`, but not both.
This transaction has the following limitations:
- An account cannot preauthorize (or unauthorize) its own address. Attempting to do so fails with the result [`temCANNOT_PREAUTH_SELF`](../transaction-results/tem-codes.md).
- Attempting to preauthorize an account which is already preauthorized fails with the result [`tecDUPLICATE`](../transaction-results/tec-codes.md).
- Attempting to unauthorize an account which is not preauthorized fails with the result [`tecNO_ENTRY`](../transaction-results/tec-codes.md).
- Attempting to preauthorize an address that is not funded in the ledger fails with the result [`tecNO_TARGET`](../transaction-results/tec-codes.md).
- Adding authorization adds a [DepositPreauth object](../../ledger-data/ledger-entry-types/depositpreauth.md) to the ledger, which counts toward the [owner reserve requirement](../../../../concepts/accounts/reserves.md#owner-reserves). If the sender of the transaction does not have enough XRP to pay for the increased reserve, the transaction fails with the result [`tecINSUFFICIENT_RESERVE`](../transaction-results/tec-codes.md). If the sender of the account is already at the maximum number of owned objects, the transaction fails with the result [`tecDIR_FULL`](../transaction-results/tec-codes.md).
{% raw-partial file="/_snippets/common-links.md" /%}

43
docs/references/protocol/transactions/types/diddelete.md Normal file
View File

@@ -0,0 +1,43 @@
---
html: diddelete.html
parent: transaction-types.html
seo:
description: Delete a DID.
labels:
- DID
status: not_enabled
---
# DIDDelete
[[Source]](https://github.com/XRPLF/rippled/blob/master/src/ripple/app/tx/impl/DID.cpp "Source")
_(Requires the [DID amendment][] {% not-enabled /%})_
Delete the [DID ledger entry](../../ledger-data/ledger-entry-types/did.md) associated with the specified `Account` field.
**Note:** This transaction only uses the [common fields][].
## Example {% $frontmatter.seo.title %} JSON
```json
{
"TransactionType": "DIDDelete",
"Account": "rp4pqYgrTAtdPHuZd1ZQWxrzx45jxYcZex",
"Fee": "12",
"Sequence": 391,
"SigningPubKey":"0293A815C095DBA82FAC597A6BB9D338674DB93168156D84D18417AD509FFF5904",
"TxnSignature":"3044022011E9A7EE3C7AE9D202848390522E6840F7F3ED098CD13E..."
}
```
## Error Cases
Besides errors that can occur for all transactions, {% $frontmatter.seo.title %} transactions can result in the following [transaction result codes](../transaction-results/transaction-results.md):
| Error Code | Description |
|:--------------------|:---------------------------------------------|
| `tecNO_ENTRY` | The account doesn't have a DID. |
{% raw-partial file="/_snippets/common-links.md" /%}

55
docs/references/protocol/transactions/types/didset.md Normal file
View File

@@ -0,0 +1,55 @@
---
html: didset.html
parent: transaction-types.html
seo:
description: Create or update a DID.
labels:
- DID
status: not_enabled
---
# DIDSet
[[Source]](https://github.com/XRPLF/rippled/blob/master/src/ripple/app/tx/impl/DID.cpp "Source")
_(Requires the [DID amendment][] {% not-enabled /%})_
Creates a new [DID ledger entry](../../ledger-data/ledger-entry-types/did.md) or updates the fields of an existing one.
## Example {% $frontmatter.seo.title %} JSON
```json
{
"TransactionType": "DIDSet",
"Account": "rHb9CJAWyB4rj91VRWn96DkukG4bwdtyTh",
"Fee": "10",
"Sequence": 391,
"URI": "697066733A2F2F62616679626569676479727A74357366703775646D37687537367568377932366E6634646675796C71616266336F636C67747179353566627A6469",
"Data": "",
"SigningPubKey":"0330E7FC9D56BB25D6893BA3F317AE5BCF33B3291BD63DB32654A313222F7FD020"
}
```
{% raw-partial file="/_snippets/tx-fields-intro.md" /%}
| Field | JSON Type | [Internal Type][] | Required? | Description |
|:--------------|:----------|:------------------|:----------|:------------|
| `Data` | String | Blob | No | The public attestations of identity credentials associated with the DID. |
| `DIDDocument` | String | Blob | No | The DID document associated with the DID. |
| `URI` | String | Blob | No | The Universal Resource Identifier associated with the DID. |
You must include either `Data`, `DIDDocument`, or `URI` when you submit the `DIDSet` transaction. If all three fields are missing, the transaction fails.
**Note:** To delete the `Data`, `DIDDocument`, or `URI` field from an existing DID ledger entry, add the field as an empty string.
## Error Cases
Besides errors that can occur for all transactions, {% $frontmatter.seo.title %} transactions can result in the following [transaction result codes](../transaction-results/transaction-results.md):
| Error Code | Description |
|:--------------------|:---------------------------------------------|
| `tecEMPTY_DID` | The transaction will create an empty DID ledger entry. Check that your updates don't remove the `Data`, `DIDDocument`, and `URI` fields. |
| `temEMPTY_DID` | The transaction is malformed and missing any DID information. Include either the `Data`, `DIDDocument`, or `URI` fields. |
{% raw-partial file="/_snippets/common-links.md" /%}

44
docs/references/protocol/transactions/types/escrowcancel.md Normal file
View File

@@ -0,0 +1,44 @@
---
html: escrowcancel.html
parent: transaction-types.html
seo:
description: Reclaim escrowed XRP.
labels:
- Escrow
---
# EscrowCancel
[[Source]](https://github.com/XRPLF/rippled/blob/master/src/ripple/app/tx/impl/Escrow.cpp "Source")
_Added by the [Escrow amendment][]._
Return escrowed XRP to the sender.
## Example {% $frontmatter.seo.title %} JSON
```json
{
"Account": "rf1BiGeXwwQoi8Z2ueFYTEXSwuJYfV2Jpn",
"TransactionType": "EscrowCancel",
"Owner": "rf1BiGeXwwQoi8Z2ueFYTEXSwuJYfV2Jpn",
"OfferSequence": 7,
}
```
[Query example transaction. >](/resources/dev-tools/websocket-api-tool?server=wss%3A%2F%2Fxrplcluster.com%2F&req=%7B%22id%22%3A%22example_EscrowCancel%22%2C%22command%22%3A%22tx%22%2C%22transaction%22%3A%22B24B9D7843F99AED7FB8A3929151D0CCF656459AE40178B77C9D44CED64E839B%22%2C%22binary%22%3Afalse%7D)
{% raw-partial file="/_snippets/tx-fields-intro.md" /%}
<!--{# fix md highlighting_ #}-->
| Field | JSON Type | [Internal Type][] | Description |
|:----------------|:----------|:------------------|:---------------------------|
| `Owner` | String | AccountID | Address of the source account that funded the escrow payment. |
| `OfferSequence` | Number | UInt32 | Transaction sequence (or [Ticket](../../../../concepts/accounts/tickets.md) number) of [EscrowCreate transaction][] that created the escrow to cancel. |
Any account may submit an EscrowCancel transaction.
* If the corresponding [EscrowCreate transaction][] did not specify a `CancelAfter` time, the EscrowCancel transaction fails.
* Otherwise the EscrowCancel transaction fails if the `CancelAfter` time is after the close time of the most recently-closed ledger.
{% raw-partial file="/_snippets/common-links.md" /%}

62
docs/references/protocol/transactions/types/escrowcreate.md Normal file
View File

@@ -0,0 +1,62 @@
---
html: escrowcreate.html
parent: transaction-types.html
seo:
description: Create an escrowed XRP payment.
labels:
- Escrow
---
# EscrowCreate
[[Source]](https://github.com/XRPLF/rippled/blob/master/src/ripple/app/tx/impl/Escrow.cpp "Source")
_Added by the [Escrow amendment][]._
Sequester XRP until the escrow process either finishes or is canceled.
## Example {% $frontmatter.seo.title %} JSON
```json
{
"Account": "rf1BiGeXwwQoi8Z2ueFYTEXSwuJYfV2Jpn",
"TransactionType": "EscrowCreate",
"Amount": "10000",
"Destination": "rsA2LpzuawewSBQXkiju3YQTMzW13pAAdW",
"CancelAfter": 533257958,
"FinishAfter": 533171558,
"Condition": "A0258020E3B0C44298FC1C149AFBF4C8996FB92427AE41E4649B934CA495991B7852B855810100",
"DestinationTag": 23480,
"SourceTag": 11747
}
```
[Query example transaction. >](/resources/dev-tools/websocket-api-tool?server=wss%3A%2F%2Fxrplcluster.com%2F&req=%7B%22id%22%3A%22example_EscrowCreate%22%2C%22command%22%3A%22tx%22%2C%22transaction%22%3A%22C44F2EB84196B9AD820313DBEBA6316A15C9A2D35787579ED172B87A30131DA7%22%2C%22binary%22%3Afalse%7D)
{% raw-partial file="/_snippets/tx-fields-intro.md" /%}
<!--{# fix md highlighting_ #}-->
| Field | JSON Type | [Internal Type][] | Description |
|:-----------------|:----------|:------------------|:--------------------------|
| `Amount` | String | Amount | Amount of [XRP, in drops][Currency Amount], to deduct from the sender's balance and escrow. Once escrowed, the XRP can either go to the `Destination` address (after the `FinishAfter` time) or returned to the sender (after the `CancelAfter` time). |
| `Destination` | String | AccountID | Address to receive escrowed XRP. |
| `CancelAfter` | Number | UInt32 | _(Optional)_ The time, in [seconds since the Ripple Epoch][], when this escrow expires. This value is immutable; the funds can only be returned to the sender after this time. |
| `FinishAfter` | Number | UInt32 | _(Optional)_ The time, in [seconds since the Ripple Epoch][], when the escrowed XRP can be released to the recipient. This value is immutable, and the funds can't be accessed until this time. |
| `Condition` | String | Blob | _(Optional)_ Hex value representing a [PREIMAGE-SHA-256 crypto-condition](https://tools.ietf.org/html/draft-thomas-crypto-conditions-02#section-8.1). The funds can only be delivered to the recipient if this condition is fulfilled. If the condition is not fulfilled before the expiration time specified in the `CancelAfter` field, the XRP can only revert to the sender. |
| `DestinationTag` | Number | UInt32 | _(Optional)_ Arbitrary tag to further specify the destination for this escrowed payment, such as a hosted recipient at the destination address. |
You must specify one of the following combinations of fields:
| Summary | `FinishAfter` | `Condition` | `CancelAfter` |
|-----------------------------------|---------------|-------------|---------------|
| Time-based | ✅ | | |
| Time-based with expiration | ✅ | | ✅ |
| Timed conditional | ✅ | ✅ | |
| Timed conditional with expiration | ✅ | ✅ | ✅ |
| Conditional with expiration | | ✅ | ✅ |
It is not possible to create a conditional escrow with no expiration, but you can specify an expiration that is very far in the future.
**Note:** Before the [fix1571 amendment][] became enabled on 2018-06-19, it was possible to create an escrow with `CancelAfter` only. These escrows could be finished by anyone at any time before the specified expiration.
{% raw-partial file="/_snippets/common-links.md" /%}

53
docs/references/protocol/transactions/types/escrowfinish.md Normal file
View File

@@ -0,0 +1,53 @@
---
html: escrowfinish.html
parent: transaction-types.html
seo:
description: Deliver escrowed XRP to recipient.
labels:
- Escrow
---
# EscrowFinish
[[Source]](https://github.com/XRPLF/rippled/blob/master/src/ripple/app/tx/impl/Escrow.cpp "Source")
_Added by the [Escrow amendment][]._
Deliver XRP from a held payment to the recipient.
## Example {% $frontmatter.seo.title %} JSON
```json
{
"Account": "rf1BiGeXwwQoi8Z2ueFYTEXSwuJYfV2Jpn",
"TransactionType": "EscrowFinish",
"Owner": "rf1BiGeXwwQoi8Z2ueFYTEXSwuJYfV2Jpn",
"OfferSequence": 7,
"Condition": "A0258020E3B0C44298FC1C149AFBF4C8996FB92427AE41E4649B934CA495991B7852B855810100",
"Fulfillment": "A0028000"
}
```
[Query example transaction. >](/resources/dev-tools/websocket-api-tool?server=wss%3A%2F%2Fxrplcluster.com%2F&req=%7B%22id%22%3A%22example_EscrowFinish%22%2C%22command%22%3A%22tx%22%2C%22transaction%22%3A%22317081AF188CDD4DBE55C418F41A90EC3B959CDB3B76105E0CBE6B7A0F56C5F7%22%2C%22binary%22%3Afalse%7D)
{% raw-partial file="/_snippets/tx-fields-intro.md" /%}
<!--{# fix md highlighting_ #}-->
| Field | JSON Type | [Internal Type][] | Description |
|:----------------|:-----------------|:------------------|:--------------------|
| `Owner` | String | AccountID | Address of the source account that funded the held payment. |
| `OfferSequence` | Unsigned Integer | UInt32 | Transaction sequence of [EscrowCreate transaction][] that created the held payment to finish. |
| `Condition` | String | Blob | _(Optional)_ Hex value matching the previously-supplied [PREIMAGE-SHA-256 crypto-condition](https://tools.ietf.org/html/draft-thomas-crypto-conditions-02#section-8.1) of the held payment. |
| `Fulfillment` | String | Blob | _(Optional)_ Hex value of the [PREIMAGE-SHA-256 crypto-condition fulfillment](https://tools.ietf.org/html/draft-thomas-crypto-conditions-02#section-8.1.4) matching the held payment's `Condition`. |
Any account may submit an EscrowFinish transaction.
- If the held payment has a `FinishAfter` time, you cannot execute it before this time. Specifically, if the corresponding [EscrowCreate transaction][] specified a `FinishAfter` time that is after the close time of the most recently-closed ledger, the EscrowFinish transaction fails.
- If the held payment has a `Condition`, you cannot execute it unless you provide a matching `Fulfillment` for the condition.
- You cannot execute a held payment after it has expired. Specifically, if the corresponding [EscrowCreate transaction][] specified a `CancelAfter` time that is before the close time of the most recently-closed ledger, the EscrowFinish transaction fails.
**Note:** The minimum [transaction cost](../../../../concepts/transactions/transaction-cost.md) to submit an EscrowFinish transaction increases if it contains a fulfillment. If the transaction has no fulfillment, the transaction cost is the standard 10 drops. If the transaction contains a fulfillment, the transaction cost is 330 [drops of XRP][] plus another 10 drops for every 16 bytes in size of the preimage.
In [non-production networks](../../../../concepts/networks-and-servers/parallel-networks.md), it may be possible [to delete](../../../../concepts/accounts/deleting-accounts.md) the destination account of a pending escrow. In this case, an attempt to finish the escrow fails with the result `tecNO_TARGET`, but the escrow object remains unless it has expired normally. If another payment re-creates the destination account, the escrow can be finished successfully. The destination account of an escrow can only be deleted if the escrow was created before the [fix1523 amendment](../../../../resources/known-amendments.md#fix1523) became enabled. No such escrows exist in the production XRP Ledger, so this edge case is not possible on the production XRP Ledger. This edge case is also not possible in test networks that enable both fix1523 and Escrow amendments at the same time, which is the default when you [start a new genesis ledger](../../../../infrastructure/testing-and-auditing/start-a-new-genesis-ledger-in-stand-alone-mode.md).
{% raw-partial file="/_snippets/common-links.md" /%}

22
docs/references/protocol/transactions/types/index.md Normal file
View File

@@ -0,0 +1,22 @@
---
html: transaction-types.html
parent: transaction-formats.html
seo:
description: All the different types of transactions that the XRP Ledger can process.
metadata:
indexPage: true
labels:
- Blockchain
---
# Transaction Types
The type of a transaction (`TransactionType` field) is the most fundamental information about a transaction. This indicates what type of operation the transaction is supposed to do.
All transactions have certain fields in common:
* [Common Fields](../common-fields.md)
Each transaction type has additional fields relevant to the type of action it causes.
{% child-pages /%}

108
docs/references/protocol/transactions/types/nftokenacceptoffer.md Normal file
View File

@@ -0,0 +1,108 @@
---
html: nftokenacceptoffer.html
parent: transaction-types.html
seo:
description: Accept an offer to buy or sell an NFToken.
labels:
- NFTs, Non-fungible Tokens
---
# NFTokenAcceptOffer
[[Source]](https://github.com/XRPLF/rippled/blob/master/src/ripple/app/tx/impl/NFTokenAcceptOffer.cpp "Source")
The `NFTokenAcceptOffer` transaction is used to accept offers to `buy` or `sell` an `NFToken`. It can either:
* Allow one offer to be accepted. This is called _direct_ mode.
* Allow two distinct offers, one offering to buy a given `NFToken` and the other offering to sell the same `NFToken`, to be accepted in an atomic fashion. This is called _brokered_ mode.
_(Added by the [NonFungibleTokensV1_1 amendment][].)_
## Example NFTokenAcceptOffer JSON
```json
{
"Account": "r9spUPhPBfB6kQeF6vPhwmtFwRhBh2JUCG",
"Fee": "12",
"LastLedgerSequence": 75447550,
"Memos": [
{
"Memo": {
"MemoData": "61356534373538372D633134322D346663382D616466362D393666383562356435386437"
}
}
],
"NFTokenSellOffer": "68CD1F6F906494EA08C9CB5CAFA64DFA90D4E834B7151899B73231DE5A0C3B77",
"Sequence": 68549302,
"TransactionType": "NFTokenAcceptOffer"
}
```
[Query example transaction. >](/resources/dev-tools/websocket-api-tool?server=wss%3A%2F%2Fs1.ripple.com%2F&req=%7B%22id%22%3A%22example_NFTokenAcceptOffer%22%2C%22command%22%3A%22tx%22%2C%22transaction%22%3A%22BEB64444C36D1072820BAED317BE2E6470AFDAD9D8FB2D16A15A4D46E5A71909%22%2C%22binary%22%3Afalse%7D)
## Brokered vs. Direct Mode
The mode in which the transaction operates depends on the presence of the `NFTokenSellOffer` and `NFTokenBuyOffer` fields of the transaction:
| `NFTokenSellOffer` | `NFTokenBuyOffer` | Mode |
|:-------------------|:------------------|:---------|
| ✔️ | ✔️ | Brokered |
| ✔️ | ❌ | Direct |
| ❌ | ✔️ | Direct |
If neither of those fields is specified, the transaction is malformed and produces a `tem` class error.
The semantics of brokered mode are slightly different than direct mode: the account sending the transaction acts as a broker, bringing the two offers together and causing them to be matched, but does not acquire ownership of the involved `NFToken`. If the transaction is successful, the `NFToken` is sent directly from the seller to the buyer.
## Execution Details
If the transaction succeeds:
- The `NFToken` changes ownership, meaning that the token is removed from the `NFTokenPage` of the existing owner and added to the `NFTokenPage` of the new owner.
- Funds are transferred from the buyer to the seller, as specified in the `NFTokenOffer`. If the `NFToken` has a transfer fee, then its issuer receives the specified percentage, and the rest goes to the seller.
The transaction fails with a [`tec`-class code](../transaction-results/tec-codes.md) if:
- The buyer already owns the `NFToken`.
- The seller is not the current owner of the `NFToken`.
- One or both offers in the transaction have already expired.
- The sell offer specifies a specific destination account, and the sender of the transaction is not that account.
- The sender of this transaction owns the buy or sell offer.
## Fields
{% raw-partial file="/_snippets/tx-fields-intro.md" /%}
| Field | JSON Type | [Internal Type][] | Description |
|:-------------------|:--------------------|:------------------|:--------------|
| `NFTokenSellOffer` | String | Hash256 | _(Optional)_ Identifies the `NFTokenOffer` that offers to sell the `NFToken`. |
| `NFTokenBuyOffer` | String | Hash256 | _(Optional)_ Identifies the `NFTokenOffer` that offers to buy the `NFToken`. |
| `NFTokenBrokerFee` | [Currency Amount][] | Amount | _(Optional)_ This field is only valid in brokered mode, and specifies the amount that the broker keeps as part of their fee for bringing the two offers together; the remaining amount is sent to the seller of the `NFToken` being bought. If specified, the fee must be such that, before applying the transfer fee, the amount that the seller would receive is at least as much as the amount indicated in the sell offer. |
In direct mode, you must specify **either** the `NFTokenSellOffer` or the `NFTokenBuyOffer` field. In brokered mode, you must specify **both** fields.
This functionality is intended to allow the owner of an `NFToken` to offer their token for sale to a third party broker, who may then attempt to sell the `NFToken` on for a larger amount, without the broker having to own the `NFToken` or custody funds.
If both offers are for the same asset, it is possible that the order in which funds are transferred might cause a transaction that would succeed to fail due to a lack of funds. To ensure deterministic transaction execution and maximize the chances of successful execution, the account attempting to buy the `NFToken` is debited first. Funds due to the broker are credited _before_ crediting the seller.
In brokered mode, the offers referenced by `NFTokenBuyOffer` and `NFTokenSellOffer` must both specify the same `NFTokenID`; that is, both must be for the same `NFToken`.
## Error Cases
Besides errors that can occur for all transactions, {% $frontmatter.seo.title %} transactions can result in the following [transaction result codes](../transaction-results/transaction-results.md):
| Error Code | Description |
|:-----------------------------------|:----------------------------------------|
| `temDISABLED` | The [NonFungibleTokensV1 amendment][] is not enabled. |
| `temMALFORMED` | The transaction was not validly formatted. For example, it specified neither `NFTokenSellOffer` nor `NFTokenBuyOffer`, or it specified a negative `NFTokenBrokerFee`. |
| `tecCANT_ACCEPT_OWN_NFTOKEN_OFFER` | The buyer and seller are the same account. |
| `tecEXPIRED` | An offer specified in the transaction has already expired. |
| `tecINSUFFICIENT_FUNDS` | The buyer does not have the full amount they are offering. If the buy amount is specified in XRP, this could be because of the [reserve requirement](../../../../concepts/accounts/reserves.md). If the buy amount is a token, it could be because the token is [frozen](../../../../concepts/tokens/fungible-tokens/freezes.md). |
| `tecINSUFFICIENT_PAYMENT` | In brokered mode, the buy amount offered is not high enough to pay the `BrokerFee` _and_ the sell cost of the `NFToken`. |
| `tecOBJECT_NOT_FOUND` | One of the offers specified in the transaction does not exist in the ledger. |
| `tecNFTOKEN_BUY_SELL_MISMATCH` | In brokered mode, the two offers are not a valid match. For example, the seller is asking more than the buyer is offering, the buy and sell offer are denominated in different assets, or the seller specified a destination that is not the buyer or the broker. |
| `tecNFTOKEN_OFFER_TYPE_MISMATCH` | The object identified by the `NFTokenBuyOffer` is not actually a buy offer, or the object identified by the `NFTokenSellOffer` is not actually a sell offer. |
| `tecNO_PERMISSION` | The seller does not own the `NFToken` being sold; or the matching offer specifies a different `Destination` account than the account accepting the offer. |
{% raw-partial file="/_snippets/common-links.md" /%}

53
docs/references/protocol/transactions/types/nftokenburn.md Normal file
View File

@@ -0,0 +1,53 @@
---
html: nftokenburn.html
parent: transaction-types.html
seo:
description: Use TokenBurn to permanently destroy NFTs.
labels:
- Non-fungible Tokens, NFTs
---
# NFTokenBurn
[[Source]](https://github.com/XRPLF/rippled/blob/master/src/ripple/app/tx/impl/NFTokenBurn.cpp "Source")
The `NFTokenBurn` transaction is used to remove a `NFToken` object from the `NFTokenPage` in which it is being held, effectively removing the token from the ledger (_burning_ it).
The sender of this transaction must be the owner of the `NFToken` to burn; or, if the `NFToken` has the `lsfBurnable` flag enabled, can be the issuer or the issuer's authorized `NFTokenMinter` account instead.
If this operation succeeds, the corresponding `NFToken` is removed. If this operation empties the `NFTokenPage` holding the `NFToken` or results in consolidation, thus removing a `NFTokenPage`, the owner’s reserve requirement is reduced by one.
_(Added by the [NonFungibleTokensV1_1 amendment][].)_
## Example {% $frontmatter.seo.title %} JSON
```json
{
"TransactionType": "NFTokenBurn",
"Account": "rNCFjv8Ek5oDrNiMJ3pw6eLLFtMjZLJnf2",
"Owner": "rvYAfWj5gh67oV6fW32ZzP3Aw4Eubs59B",
"Fee": "10",
"NFTokenID": "000B013A95F14B0044F78A264E41713C64B5F89242540EE208C3098E00000D65"
}
```
[Query example transaction. >](/resources/dev-tools/websocket-api-tool?server=wss%3A%2F%2Fs1.ripple.com%2F&req=%7B%22id%22%3A%22example_NFTokenBurn%22%2C%22command%22%3A%22tx%22%2C%22transaction%22%3A%227B9EFDFDC801C58F2B61B89AA2751634F49CE2A93923671FF0F4F099C7EE17FF%22%2C%22binary%22%3Afalse%7D)
{% raw-partial file="/_snippets/tx-fields-intro.md" /%}
| Field | JSON Type | [Internal Type][] | Description |
|:------------------|:----------|:------------------|:-------------------------|
| `NFTokenID` | String | Hash256 | The `NFToken` to be removed by this transaction. |
| `Owner` | String | AccountID | _(Optional)_ The owner of the `NFToken` to burn. Only used if that owner is different than the account sending this transaction. The issuer or authorized minter can use this field to burn NFTs that have the `lsfBurnable` flag enabled. |
## Error Cases
Besides errors that can occur for all transactions, {% $frontmatter.seo.title %} transactions can result in the following [transaction result codes](../transaction-results/transaction-results.md):
| Error Code | Description |
|:-------------------|:--------------------------------------------------------|
| `temDISABLED` | The [NonFungibleTokensV1 amendment][] is not enabled. |
| `tecNO_ENTRY` | The specified `TokenID` was not found. |
| `tecNO_PERMISSION` | The account does not have permission to burn the token. |
{% raw-partial file="/_snippets/common-links.md" /%}

62
docs/references/protocol/transactions/types/nftokencanceloffer.md Normal file
View File

@@ -0,0 +1,62 @@
---
html: nftokencanceloffer.html
parent: transaction-types.html
seo:
description: Cancel existing token offers to buy or sell an NFToken.
labels:
- NFTs, Non-fungible Tokens
---
# NFTokenCancelOffer
[[Source]](https://github.com/XRPLF/rippled/blob/master/src/ripple/app/tx/impl/NFTokenCancelOffer.cpp "Source")
The `NFTokenCancelOffer` transaction can be used to cancel existing token offers created using `NFTokenCreateOffer`.
_(Added by the [NonFungibleTokensV1_1 amendment][].)_
## Example {% $frontmatter.seo.title %} JSON
```json
{
"TransactionType": "NFTokenCancelOffer",
"Account": "ra5nK24KXen9AHvsdFTKHSANinZseWnPcX",
"NFTokenOffers": [
"9C92E061381C1EF37A8CDE0E8FC35188BFC30B1883825042A64309AC09F4C36D"
]
}
```
[Query example transaction. >](/resources/dev-tools/websocket-api-tool?server=wss%3A%2F%2Fs1.ripple.com%2F&req=%7B%22id%22%3A%22example_NFTokenCancelOffer%22%2C%22command%22%3A%22tx%22%2C%22transaction%22%3A%229FF6366C19F762AE3479DC01390CDE17F1055EFF0C52A28B8ACF0CC11AEF0CC5%22%2C%22binary%22%3Afalse%7D)
## Permissions
An existing offer, represented by an `NFTokenOffer` object, can be cancelled by:
* The account that originally created the `NFTokenOffer`.
* The account in the `Destination` field of the `NFTokenOffer`, if one is present.
* Any account, if the `NFTokenOffer` specifies an expiration time and the close time of the parent ledger in which the `NFTokenCancelOffer` is included is greater than the expiration time.
This transaction removes the listed `NFTokenOffer` object from the ledger, if present, and adjusts the reserve requirements accordingly. It is not an error if the `NFTokenOffer` cannot be found: if that is the case, the transaction should complete successfully.
{% raw-partial file="/_snippets/tx-fields-intro.md" /%}
| Field | JSON Type | [Internal Type][] | Description |
|:------------------|:----------|:------------------|:-------------------------|
| `NFTokenOffers` | Array | VECTOR256 | An array of IDs of the `NFTokenOffer` objects to cancel (not the IDs of `NFToken` objects, but the IDs of the `NFTokenOffer` objects). Each entry must be a different [object ID](../../ledger-data/common-fields.md) of an [NFTokenOffer](../../ledger-data/ledger-entry-types/nftokenoffer.md) object; the transaction is invalid if the array contains duplicate entries. |
The transaction can succeed even if one or more of the IDs in the `NFTokenOffers` field do not refer to objects that currently exist in the ledger. (For example, those token offers might already have been deleted.) The transaction fails with an error if one of the IDs points to an object that does exist, but is not a [NFTokenOffer](../../ledger-data/ledger-entry-types/nftokenoffer.md) object.
It is important to note that if you inadvertently provide a `nft_id` rather than a `nft_offer_index`, you might receive a `tesSUCCESS` response. The reason is that when passed a properly formatted ID value that is not found, the system assumes that the `NFTokenOffer` has already been deleted.
The transaction fails with an error if one of the IDs points to an object that does exist, but is not a [NFTokenOffer](../../ledger-data/ledger-entry-types/nftokenoffer.md) object.
## Error Cases
Besides errors that can occur for all transactions, {% $frontmatter.seo.title %} transactions can result in the following [transaction result codes](../transaction-results/transaction-results.md):
| Error Code | Description |
|:-------------------|:--------------------------------------------------------|
| `temDISABLED` | The [NonFungibleTokensV1 amendment][] is not enabled. |
| `temMALFORMED` | The transaction was not validly formatted. For example, the `NFTokenOffers` array was empty or contained more than the maximum number of offers that can be canceled at one time. |
| `tecNO_PERMISSION` | At least one of the IDs in the `NFTokenOffers` field refers to an object that cannot be canceled. For example, the sender of this transaction is not the owner or `Destination` of the offer, or the object was not an `NFTokenOffer` type object. |
{% raw-partial file="/_snippets/common-links.md" /%}

73
docs/references/protocol/transactions/types/nftokencreateoffer.md Normal file
View File

@@ -0,0 +1,73 @@
---
html: nftokencreateoffer.html
parent: transaction-types.html
seo:
description: Create an offer to buy or sell NFTs.
labels:
- Non-fungible Tokens, NFTs
---
# NFTokenCreateOffer
[[Source]](https://github.com/XRPLF/rippled/blob/master/src/ripple/app/tx/impl/NFTokenCreateOffer.cpp "Source")
Creates either a new _Sell_ offer for an `NFToken` owned by the account executing the transaction, or a new _Buy_ offer for an `NFToken` owned by another account.
If successful, the transaction creates a [NFTokenOffer object][]. Each offer counts as one object towards the [owner reserve](../../../../concepts/accounts/reserves.md) of the account that placed the offer.
_(Added by the [NonFungibleTokensV1_1 amendment][].)_
## Example {% $frontmatter.seo.title %} JSON
```json
{
"TransactionType": "NFTokenCreateOffer",
"Account": "rs8jBmmfpwgmrSPgwMsh7CvKRmRt1JTVSX",
"NFTokenID": "000100001E962F495F07A990F4ED55ACCFEEF365DBAA76B6A048C0A200000007",
"Amount": "1000000",
"Flags": 1
}
```
[Query example transaction. >](/resources/dev-tools/websocket-api-tool?server=wss%3A%2F%2Fs1.ripple.com%2F&req=%7B%22id%22%3A%22example_NFTokenCreateOffer%22%2C%22command%22%3A%22tx%22%2C%22transaction%22%3A%22780C44B2EDFF8FC4152B3F7E98D4C435C13DF9BB5498E4BB2D019FCC7EF45BC6%22%2C%22binary%22%3Afalse%7D)
{% raw-partial file="/_snippets/tx-fields-intro.md" /%}
| Field | JSON Type | [Internal Type][] | Description |
|:--------------|:--------------------|:------------------|:-------------------|
| `Owner` | String | AccountID | _(Optional)_ Who owns the corresponding `NFToken`. If the offer is to buy a token, this field must be present and it must be different than the `Account` field (since an offer to buy a token one already holds is meaningless). If the offer is to sell a token, this field must not be present, as the owner is, implicitly, the same as the `Account` (since an offer to sell a token one doesn't already hold is meaningless). |
| `NFTokenID` | String | Hash256 | Identifies the `NFToken` object that the offer references. |
| `Amount` | [Currency Amount][] | Amount | Indicates the amount expected or offered for the corresponding `NFToken`. The amount must be non-zero, except where this is an offer to sell and the asset is XRP; then, it is legal to specify an amount of zero, which means that the current owner of the token is giving it away, gratis, either to anyone at all, or to the account identified by the `Destination` field. |
| `Expiration` | Number | UInt32 | _(Optional)_ Time after which the offer is no longer active, in [seconds since the Ripple Epoch][]. |
| `Destination` | String | AccountID | _(Optional)_ If present, indicates that this offer may only be accepted by the specified account. Attempts by other accounts to accept this offer MUST fail. |
## NFTokenCreateOffer Flags
Transactions of the NFTokenCreateOffer type support additional values in the [`Flags` field](../common-fields.md#flags-field), as follows:
| Flag Name | Hex Value | Decimal Value | Description |
|:----------------|:-------------|:--------------|:------------------------------|
| `tfSellNFToken` | `0x00000001` | `1` | If enabled, indicates that the offer is a sell offer. Otherwise, it is a buy offer. |
## Error Cases
Besides errors that can occur for all transactions, {% $frontmatter.seo.title %} transactions can result in the following [transaction result codes](../transaction-results/transaction-results.md):
| Error Code | Description |
|:---------------------------------|:------------------------------------------|
| `temDISABLED` | The [NonFungibleTokensV1 amendment][] is not enabled. |
| `temBAD_AMOUNT` | The `Amount` field is not valid. For example, the amount was zero for a buy offer, or the amount is denominated in fungible tokens but the `NFToken` has the [`lsfOnlyXRP` flag](../../data-types/nftoken.md#nftoken-flags) enabled. |
| `temBAD_EXPIRATION` | The specified `Expiration` time is invalid (for example, `0`). |
| `tecDIR_FULL` | The sender already owns too many objects in the ledger, or there are already too many offers to buy or sell this token. |
| `tecEXPIRED` | The specified `Expiration` time has already passed. |
| `tecFROZEN` | The `Amount` is denominated in fungible tokens, but one of the trust lines that would receive tokens from this offer is [frozen](../../../../concepts/tokens/fungible-tokens/freezes.md). This could be the seller's trust line or the `NFToken`'s issuer's trust line (if the `NFToken` has a transfer fee). |
| `tecINSUFFICIENT_RESERVE` | The sender does not have enough XRP to meet the [reserve requirement](../../../../concepts/accounts/reserves.md) after placing this offer. |
| `tecNO_DST` | The account specified in the `Destination` field does not exist in the ledger. |
| `tecNO_ENTRY` | The `NFToken` is not owned by the expected account. |
| `tecNO_ISSUER` | The issuer specified in the `Amount` field does not exist. |
| `tecNO_LINE` | The `Amount` field is denominated in fungible tokens, but the `NFToken`'s issuer does not have a trust line for those tokens and the `NFToken` does not have the [`lsfTrustLine` flag](../../data-types/nftoken.md#nftoken-flags) enabled. |
| `tecNO_PERMISSION` | The `Destination` account blocks incoming NFTokenOffers. _(Requires the [DisallowIncoming amendment][] {% not-enabled /%})_
| `tecUNFUNDED_OFFER` | For a buy offer, the sender does have the funds specified in the `Amount` field available. If the `Amount` is XRP, this could be due to the reserve requirement; if the `Amount` is denominated in fungible tokens, this could be because they are [frozen](../../../../concepts/tokens/fungible-tokens/freezes.md). |
| `tefNFTOKEN_IS_NOT_TRANSFERABLE` | The `NFToken` has the [`lsfTransferable` flag](../../data-types/nftoken.md#nftoken-flags) disabled and this transaction would not transfer the `NFToken` to or from the issuer. |
{% raw-partial file="/_snippets/common-links.md" /%}

119
docs/references/protocol/transactions/types/nftokenmint.md Normal file
View File

@@ -0,0 +1,119 @@
---
html: nftokenmint.html
parent: transaction-types.html
seo:
description: Use TokenMint to issue new NFTs.
labels:
- Non-fungible Tokens, NFTs
---
# NFTokenMint
[[Source]](https://github.com/XRPLF/rippled/blob/master/src/ripple/app/tx/impl/NFTokenMint.cpp "Source")
The `NFTokenMint` transaction creates a non-fungible token and adds it to the relevant [NFTokenPage object][] of the `NFTokenMinter` as an [NFToken][] object. This transaction is the only opportunity the `NFTokenMinter` has to specify any token fields that are defined as immutable (for example, the `TokenFlags`).
_(Added by the [NonFungibleTokensV1_1 amendment][].)_
## Example {% $frontmatter.seo.title %} JSON
```json
{
"TransactionType": "NFTokenMint",
"Account": "rvYAfWj5gh67oV6fW32ZzP3Aw4Eubs59B",
"TransferFee": 314,
"NFTokenTaxon": 0,
"Flags": 8,
"Fee": "10",
"URI": "697066733A2F2F62616679626569676479727A74357366703775646D37687537367568377932366E6634646675796C71616266336F636C67747179353566627A6469",
"Memos": [
{
"Memo": {
"MemoType":
"687474703A2F2F6578616D706C652E636F6D2F6D656D6F2F67656E65726963",
"MemoData": "72656E74"
}
}
]
}
```
[Query example transaction. >](/resources/dev-tools/websocket-api-tool?server=wss%3A%2F%2Fs1.ripple.com%2F&req=%7B%22id%22%3A%22example_NFTokenMint%22%2C%22command%22%3A%22tx%22%2C%22transaction%22%3A%22B42C7A0C9C3061463C619999942D0F25E4AE5FB051EA0D7A4EE1A924DB6DFEE8%22%2C%22binary%22%3Afalse%7D)
{% raw-partial file="/_snippets/tx-fields-intro.md" /%}
| Field | JSON Type | [Internal Type][] | Description |
|:--------------|:--------------------|:------------------|:-------------------|
| `NFTokenTaxon` | Number | UInt32 | An arbitrary _taxon_, or shared identifier, for a series or collection of related NFTs. To mint a series of NFTs, give them all the same taxon. |
| `Issuer` | String | AccountID | _(Optional)_ The issuer of the token, if the sender of the account is issuing it on behalf of another account. This field must be omitted if the account sending the transaction is the issuer of the `NFToken`. If provided, the issuer's [AccountRoot object][] must have the `NFTokenMinter` field set to the sender of this transaction (this transaction's `Account` field). |
| `TransferFee` | Number | UInt16 | _(Optional)_ The value specifies the fee charged by the issuer for secondary sales of the `NFToken`, if such sales are allowed. Valid values for this field are between 0 and 50000 inclusive, allowing transfer rates of between 0.00% and 50.00% in increments of 0.001. If this field is provided, the transaction MUST have the [`tfTransferable` flag](#nftokenmint-flags) enabled. |
| `URI` | String | Blob | _(Optional)_ Up to 256 bytes of arbitrary data. In JSON, this should be encoded as a string of hexadecimal. You can use the [`xrpl.convertStringToHex`](https://js.xrpl.org/modules.html#convertStringToHex) utility to convert a URI to its hexadecimal equivalent. This is intended to be a URI that points to the data or metadata associated with the NFT. The contents could decode to an HTTP or HTTPS URL, an IPFS URI, a magnet link, immediate data encoded as an [RFC 2379 "data" URL](https://datatracker.ietf.org/doc/html/rfc2397), or even an issuer-specific encoding. The URI is NOT checked for validity. |
## NFTokenMint Flags
Transactions of the NFTokenMint type support additional values in the [`Flags` field](../common-fields.md#flags-field), as follows:
| Flag Name | Hex Value | Decimal Value | Description |
|:--------------|:-------------|:--------------|:------------------------------|
| `tfBurnable` | `0x00000001` | 1 | Allow the issuer (or an entity authorized by the issuer) to destroy the minted `NFToken`. (The `NFToken`'s owner can _always_ do so.) |
| `tfOnlyXRP` | `0x00000002` | 2 | The minted `NFToken` can only be bought or sold for XRP. This can be desirable if the token has a transfer fee and the issuer does not want to receive fees in non-XRP currencies. |
| `tfTrustLine` | `0x00000004` | 4 | **DEPRECATED** Automatically create [trust lines](../../../../concepts/tokens/fungible-tokens/index.md) from the issuer to hold transfer fees received from transferring the minted `NFToken`. The [fixRemoveNFTokenAutoTrustLine amendment][] makes it invalid to set this flag. |
| `tfTransferable` | `0x00000008` | 8 | The minted `NFToken` can be transferred to others. If this flag is _not_ enabled, the token can still be transferred _from_ or _to_ the issuer, but a transfer to the issuer must be made based on a buy offer from the issuer and not a sell offer from the NFT holder. |
## Embedding additional information
If you need to specify additional information during minting (for example, details identifying a property by referencing a particular [plat](https://en.wikipedia.org/wiki/Plat), a vehicle by specifying a [VIN](https://en.wikipedia.org/wiki/Vehicle_identification_number), or other object-specific descriptions) you can use a [transaction memo](../common-fields.md#memos-field). Memos are a part of the signed transaction and are available from historical archives, but are not stored in the ledger's state data.
## Issuing on behalf of another account
If you want to issue an NFT for another account there are two things you must do. Given that *Account A* is your account and *Account B* is the account for which you want to mint a NFToken:
1. Set the `NFTokenMinter` account setting on *Account B* to be *Account A*. (This says that *Account B* trusts *Account A* to create NFTs on their behalf.)
2. When you mint the NFToken, set the `Issuer` field to Account B.
### Example of NFTokenMint with an issuer
```json
{
"TransactionType": "NFTokenMint",
"Account": "rvYAfWj5gh67oV6fW32ZzP3Aw4Eubs59B",
"Issuer": "rNCFjv8Ek5oDrNiMJ3pw6eLLFtMjZLJnf2",
"TransferFee": 25000,
"NFTokenTaxon": 0,
"Flags": 8,
"Fee": "10",
"URI": "697066733A2F2F62616679626569676479727A74357366703775646D37687537367568377932366E6634646675796C71616266336F636C67747179353566627A6469",
"Memos": [
{
"Memo": {
"MemoType":
"687474703A2F2F6578616D706C652E636F6D2F6D656D6F2F67656E65726963",
"MemoData": "72656E74"
}
}
]
}
```
This transaction assumes that the issuer, `rNCFjv8Ek5oDrNiMJ3pw6eLLFtMjZLJnf2`, has set the `NFTokenMinter` field in its `AccountRoot` to `rvYAfWj5gh67oV6fW32ZzP3Aw4Eubs59B`, thereby authorizing that account to mint tokens on its behalf.
## Error Cases
Besides errors that can occur for all transactions, {% $frontmatter.seo.title %} transactions can result in the following [transaction result codes](../transaction-results/transaction-results.md):
| Error Code | Description |
|:------------------------------|:---------------------------------------------|
| `temDISABLED` | The [NonFungibleTokensV1 amendment][] is not enabled. |
| `temBAD_NFTOKEN_TRANSFER_FEE` | The `TransferFee` is not within the acceptable range. |
| `temINVALID_FLAG` | The `Flags` value has bits enabled that are not allowed or valid flags. If the [fixRemoveNFTokenAutoTrustLine amendment][] is enabled, the `tfTrustLine` flag causes this error. |
| `temMALFORMED` | The transaction was not validly specified. For example, the `URI` field is longer than 256 bytes. |
| `tecNO_ISSUER` | The `Issuer` refers to an account that does not exist in the ledger. |
| `tecNO_PERMISSION` | The account referenced by the `Issuer` field has not authorized this transaction's sender (using the `NFTokenMinter` setting) to mint on their behalf. |
| `tecINSUFFICIENT_RESERVE` | The owner would not meet the updated [reserve requirement](../../../../concepts/accounts/reserves.md) after minting the token. Note that new `NFToken`s only increase the owner's reserve if it requires a new [NFTokenPage object][], which can each hold up to 32 NFTs. |
| `tecMAX_SEQUENCE_REACHED` | The `Issuer`'s `MintedNFTokens` field is already at its maximum. This is only possible if 2<sup>32</sup>-1 `NFToken`s have been minted in total by the issuer or on their behalf. |
{% raw-partial file="/_snippets/common-links.md" /%}

41
docs/references/protocol/transactions/types/offercancel.md Normal file
View File

@@ -0,0 +1,41 @@
---
html: offercancel.html
parent: transaction-types.html
seo:
description: Withdraw a currency-exchange order.
labels:
- Decentralized Exchange
---
# OfferCancel
[[Source]](https://github.com/XRPLF/rippled/blob/master/src/ripple/app/tx/impl/CancelOffer.cpp "Source")
An OfferCancel transaction removes an Offer object from the XRP Ledger.
## Example {% $frontmatter.seo.title %} JSON
```json
{
"TransactionType": "OfferCancel",
"Account": "ra5nK24KXen9AHvsdFTKHSANinZseWnPcX",
"Fee": "12",
"Flags": 0,
"LastLedgerSequence": 7108629,
"OfferSequence": 6,
"Sequence": 7
}
```
[Query example transaction. >](/resources/dev-tools/websocket-api-tool?server=wss%3A%2F%2Fxrplcluster.com%2F&req=%7B%22id%22%3A%22example_OfferCancel%22%2C%22command%22%3A%22tx%22%2C%22transaction%22%3A%22E7697D162A606FCC138C5732BF0D2A4AED49386DC59235FC3E218650AAC19744%22%2C%22binary%22%3Afalse%7D)
{% raw-partial file="/_snippets/tx-fields-intro.md" /%}
| Field | JSON Type | [Internal Type][] | Description |
|:----------------|:----------|:------------------|:-----------------------------|
| `OfferSequence` | Number | UInt32 | The sequence number (or [Ticket](../../../../concepts/accounts/tickets.md) number) of a previous OfferCreate transaction. If specified, cancel any offer object in the ledger that was created by that transaction. It is not considered an error if the offer specified does not exist. |
*Tip:* To remove an old offer and replace it with a new one, you can use an [OfferCreate transaction][] with an `OfferSequence` parameter, instead of using OfferCancel and another OfferCreate.
The OfferCancel method returns [`tesSUCCESS`](../transaction-results/tes-success.md) even if it did not find an offer with the matching sequence number.
{% raw-partial file="/_snippets/common-links.md" /%}

80
docs/references/protocol/transactions/types/offercreate.md Normal file
View File

@@ -0,0 +1,80 @@
---
html: offercreate.html
parent: transaction-types.html
seo:
description: Submit an order to exchange currency.
labels:
- Decentralized Exchange
---
# OfferCreate
[[Source]](https://github.com/XRPLF/rippled/blob/master/src/ripple/app/tx/impl/CreateOffer.cpp "Source")
An OfferCreate transaction places an [Offer](../../../../concepts/tokens/decentralized-exchange/offers.md) in the [decentralized exchange](../../../../concepts/tokens/decentralized-exchange/index.md).
## Example {% $frontmatter.seo.title %} JSON
```json
{
"TransactionType": "OfferCreate",
"Account": "ra5nK24KXen9AHvsdFTKHSANinZseWnPcX",
"Fee": "12",
"Flags": 0,
"LastLedgerSequence": 7108682,
"Sequence": 8,
"TakerGets": "6000000",
"TakerPays": {
"currency": "GKO",
"issuer": "ruazs5h1qEsqpke88pcqnaseXdm6od2xc",
"value": "2"
}
}
```
[Query example transaction. >](/resources/dev-tools/websocket-api-tool?server=wss%3A%2F%2Fxrplcluster.com%2F&req=%7B%22id%22%3A%22example_OfferCreate%22%2C%22command%22%3A%22tx%22%2C%22transaction%22%3A%220CD69FD1F0A890CC57CDA430213FD294F7D65FF4A0F379A0D09D07A222D324E6%22%2C%22binary%22%3Afalse%7D)
{% raw-partial file="/_snippets/tx-fields-intro.md" /%}
<!--{# fix md highlighting_ #}-->
| 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. |
## OfferCreate Flags
Transactions of the OfferCreate type support additional values in the [`Flags` field](../common-fields.md#flags-field), as follows:
| 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/transaction-results.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. |
| `tfSell` | `0x00080000` | 524288 | Exchange the entire `TakerGets` amount, even if it means obtaining more than the `TakerPays` amount in exchange. |
## 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). |
| `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. |
{% raw-partial file="/_snippets/common-links.md" /%}

141
docs/references/protocol/transactions/types/payment.md Normal file
View File

@@ -0,0 +1,141 @@
---
html: payment.html
parent: transaction-types.html
seo:
description: Send funds from one account to another.
labels:
- Payments
- XRP
- Cross-Currency
- Tokens
---
# Payment
[[Source]](https://github.com/XRPLF/rippled/blob/5425a90f160711e46b2c1f1c93d68e5941e4bfb6/src/ripple/app/transactors/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).
Payments are also the only way to [create accounts](#creating-accounts).
## Example {% $frontmatter.seo.title %} JSON
```json
{
"TransactionType" : "Payment",
"Account" : "rf1BiGeXwwQoi8Z2ueFYTEXSwuJYfV2Jpn",
"Destination" : "ra5nK24KXen9AHvsdFTKHSANinZseWnPcX",
"Amount" : {
"currency" : "USD",
"value" : "1",
"issuer" : "rf1BiGeXwwQoi8Z2ueFYTEXSwuJYfV2Jpn"
},
"Fee": "12",
"Flags": 2147483648,
"Sequence": 2,
}
```
[Query example transaction. >](/resources/dev-tools/websocket-api-tool?server=wss%3A%2F%2Fxrplcluster.com%2F&req=%7B%22id%22%3A%22example_Payment%22%2C%22command%22%3A%22tx%22%2C%22transaction%22%3A%227BF105CFE4EFE78ADB63FE4E03A851440551FE189FD4B51CAAD9279C9F534F0E%22%2C%22binary%22%3Afalse%7D)
{% raw-partial file="/_snippets/tx-fields-intro.md" /%}
<!--{# fix md highlighting_ #}-->
| Field | JSON Type | [Internal Type][] | Description |
|:-----------------|:---------------------|:------------------|:---------------|
| `Amount` | [Currency Amount][] | Amount | [API v1][]: Only available in API v1. The maximum amount of currency to deliver. For non-XRP amounts, the nested field names MUST be lower-case. If the [`tfPartialPayment` flag](#payment-flags) is set, deliver _up to_ this amount instead. |
| `DeliverMax` | [Currency Amount][] | Amount | [API v2][]: Only available in API v2. The maximum amount of currency to deliver. For non-XRP amounts, the nested field names MUST be lower-case. If the [`tfPartialPayment` flag](#payment-flags) is set, deliver _up to_ this amount instead. {% badge href="https://github.com/XRPLF/rippled/releases/tag/2.0.0" %}New in: rippled 2.0.0{% /badge %} |
| `DeliverMin` | [Currency Amount][] | Amount | _(Optional)_ 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. |
| `Destination` | String | AccountID | The unique address of the account receiving the payment. |
| `DestinationTag` | Number | UInt32 | _(Optional)_ Arbitrary tag that identifies the reason for the payment to the destination, or a hosted recipient to pay. |
| `InvoiceID` | String | Hash256 | _(Optional)_ Arbitrary 256-bit hash representing a specific reason or identifier for this payment. |
| `Paths` | Array of path arrays | PathSet | (Optional, 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 | _(Optional)_ 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). For non-XRP amounts, the nested field names MUST be lower-case. Must be supplied for cross-currency/cross-issue payments. Must be omitted for XRP-to-XRP payments. |
## Types of Payments
The `Payment` transaction type functions differently depending on how you fill in the `Payment` fields:
| Payment type | `Amount` | `SendMax` | `Paths` | `Account` = `Destination`? | Description |
|:-------------|:----------|:-----------|:----------|:---------------------------|:--|
| [Direct XRP Payment][] | String (XRP) | Omitted | Omitted | No | Transfers XRP directly from one account to another, using one transaction. Always delivers the exact amount. No fee applies other than the basic [transaction cost](../../../../concepts/transactions/transaction-cost.md). |
| [Creating or redeeming tokens][] | Object | Object (optional) | Optional | No | Increases or decreases the amount of a non-XRP currency or asset tracked in the XRP Ledger. [Transfer fees](../../../../concepts/tokens/transfer-fees.md) and [freezes](../../../../concepts/tokens/fungible-tokens/freezes.md) do not apply when sending and redeeming directly. |
| [Cross-currency Payment][] | Object (non-XRP) / String (XRP) | Object (non-XRP) / String (XRP) | Usually required | No | Send tokens from one holder to another. The `Amount` or `SendMax` can be XRP or tokens, but can't both be XRP. These payments [ripple through](../../../../concepts/tokens/fungible-tokens/rippling.md) the issuer and can take longer [paths](../../../../concepts/tokens/fungible-tokens/paths.md) through several intermediaries if the transaction specifies a path set. [Transfer fees](../../../../concepts/tokens/transfer-fees.md) set by the issuer(s) apply to this type of transaction. These transactions consume offers in the [decentralized exchange](../../../../concepts/tokens/decentralized-exchange/index.md) to connect different currencies, or currencies with the same currency code and different issuers. |
| [Partial payment][] | Object (non-XRP) / String (XRP) | Object (non-XRP) / String (XRP) | Usually required | No | Sends _up to_ a specific amount of any currency. Uses the [`tfPartialPayment` flag](#payment-flags). May include a `DeliverMin` amount specifying the minimum that the transaction must deliver to be successful; if the transaction does not specify `DeliverMin`, it can succeed by delivering _any positive amount_. |
| Currency conversion | Object (non-XRP) / String (XRP) | Object (non-XRP) / String (XRP) | Required | Yes | Consumes offers in the [decentralized exchange](../../../../concepts/tokens/decentralized-exchange/index.md) to convert one currency to another, possibly taking [arbitrage](https://en.wikipedia.org/wiki/Arbitrage) opportunities. The `Amount` and `SendMax` cannot both be XRP. Also called a _circular payment_ because it delivers money to the sender. This type of transaction may be classified as an "exchange" and not a "payment". |
[Direct XRP Payment]: ../../../../concepts/payment-types/direct-xrp-payments.md
[Creating or redeeming tokens]: ../../../../concepts/tokens/index.md
[Cross-currency Payment]: ../../../../concepts/payment-types/cross-currency-payments.md
[Partial payment]: ../../../../concepts/payment-types/partial-payments.md
## Special issuer Values for SendMax and Amount
<!-- SPELLING_IGNORE: sendmax -->
Most of the time, the `issuer` field of a non-XRP [Currency Amount][] indicates the issuer of a token. However, when describing payments, there are special rules for the `issuer` field in the `Amount` and `SendMax` fields of a payment.
* There is only ever one balance between two addresses for the same currency code. This means that, sometimes, the `issuer` field of an amount actually refers to a counterparty, instead of the address that issued the token.
* When the `issuer` field of the destination `Amount` field matches the `Destination` address, it is treated as a special case meaning "any issuer that the destination accepts." This includes all addresses to which the destination has trust lines with a positive limit, as well as tokens with the same currency code issued by the destination.
* When the `issuer` field of the `SendMax` field matches the source account's address, it is treated as a special case meaning "any issuer that the source can use." This includes creating new tokens on trust lines that other accounts have extended to the source account, and sending tokens the source account holds from other issuers.
## Creating Accounts
The Payment transaction type can create new accounts in the XRP Ledger by sending enough XRP to an unfunded address. Other transactions to unfunded addresses always fail.
For more information, see [Accounts](../../../../concepts/accounts/accounts.md#creating-accounts).
## Paths
If present, the `Paths` field must contain a _path set_ - an array of path arrays. Each individual path represents one way value can flow from the sender to receiver through various intermediary accounts and order books. A single transaction can potentially use multiple paths, for example if the transaction exchanges currency using several different order books to achieve the best rate.
You must omit the `Paths` field for direct payments, including:
* An XRP-to-XRP transfer.
* A direct transfer on a trust line that connects the sender and receiver.
If the `Paths` field is provided, the server decides at transaction processing time which paths to use, from the provided set plus a _default path_ (the most direct way possible to connect the specified accounts). This decision is deterministic and attempts to minimize costs, but it is not guaranteed to be perfect.
The `Paths` field must not be an empty array, nor an array whose members are all empty arrays.
For more information, see [Paths](../../../../concepts/tokens/fungible-tokens/paths.md).
## Payment Flags
Transactions of the Payment type support additional values in the [`Flags` field](../common-fields.md#flags-field), as follows:
| Flag Name | Hex Value | Decimal Value | Description |
|:-------------------|:-------------|:--------------|:-----------------------------|
| `tfNoDirectRipple` | `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. |
| `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
A partial payment allows a payment to succeed by reducing the amount received. Partial payments are useful for [returning payments](../../../../concepts/payment-types/bouncing-payments.md) without incurring additional costs to oneself. However, partial payments can also be used to exploit integrations that naively assume the `Amount` field of a successful transaction always describes the exact amount delivered.
A partial payment is any [Payment transaction][] with the `tfPartialPayment` flag enabled. A partial payment can be successful if it delivers any positive amount greater than or equal to its `DeliverMin` field (or any positive amount at all if `DeliverMin` is not specified) without sending more than the `SendMax` value.
The [`delivered_amount`](../metadata.md#delivered_amount) field of a payment's metadata indicates the amount of currency actually received by the destination account.
For more information, see the full article on [Partial Payments](../../../../concepts/payment-types/partial-payments.md).
## Limit Quality
The XRP Ledger defines the "quality" of a currency exchange as the ratio of the numeric amount in to the numeric amount out. For example, if you spend $2 USD to receive £1 GBP, then the "quality" of that exchange is `0.5`. <!-- SPELLING_IGNORE: GBP -->
The [`tfLimitQuality` flag](#payment-flags) allows you to set a minimum quality of conversions that you are willing to take. This limit quality is defined as the destination `Amount` divided by the `SendMax` amount (the numeric amounts only, regardless of currency). When set, the payment processing engine avoids using any paths whose quality (conversion rate) is worse (numerically lower) than the limit quality.
By itself, the `tfLimitQuality` flag reduces the number of situations in which a transaction can succeed. Specifically, it rejects payments where some part of the payment uses an unfavorable conversion, even if the overall *average* quality of conversions in the payment is equal or better than the limit quality. If a payment is rejected in this way, the [transaction result](../transaction-results/transaction-results.md) is `tecPATH_DRY`.
Consider the following example. If I am trying to send you 100 Chinese Yuan (`Amount` = 100 CNY) for 20 United States dollars (`SendMax` = 20 USD) or less, then the limit quality is `5`. Imagine one trader is offering ¥95 for $15 (a ratio of about `6.3` CNY per USD), but the next best offer in the market is ¥5 for $2 (a ratio of `2.5` CNY per USD). If I were to take both offers to send you 100 CNY, then it would cost me 17 USD, for an average quality of about `5.9`.
Without the `tfLimitQuality` flag set, this transaction would succeed, because the $17 it costs me is within my specified `SendMax`. However, with the `tfLimitQuality` flag enabled, the transaction would fail instead, because the path to take the second offer has a quality of `2.5`, which is worse than the limit quality of `5`.
The `tfLimitQuality` flag is most useful when combined with [partial payments](../../../../concepts/payment-types/partial-payments.md). When both `tfPartialPayment` and `tfLimitQuality` are set on a transaction, then the transaction delivers as much of the destination `Amount` as it can, without using any conversions that are worse than the limit quality.
In the above example with a ¥95/$15 offer and a ¥5/$2 offer, the situation is different if my transaction has both `tfPartialPayment` and `tfLimitQuality` enabled. If we keep my `SendMax` of 20 USD and a destination `Amount` of 100 CNY, then the limit quality is still `5`. However, because I am doing a partial payment, the transaction sends as much as it can instead of failing if the full destination amount cannot be sent. This means that my transaction consumes the ¥95/$15 offer, whose quality is about `6.3`, but it rejects the ¥5/$2 offer because that offer's quality of `2.5` is worse than the quality limit of `5`. In the end, my transaction only delivers ¥95 instead of the full ¥100, but it avoids wasting money on poor exchange rates.
{% raw-partial file="/_snippets/common-links.md" /%}

72
docs/references/protocol/transactions/types/paymentchannelclaim.md Normal file
View File

@@ -0,0 +1,72 @@
---
html: paymentchannelclaim.html
parent: transaction-types.html
seo:
description: Claim money from a payment channel.
labels:
- Payment Channels
---
# PaymentChannelClaim
[[Source]](https://github.com/XRPLF/rippled/blob/master/src/ripple/app/tx/impl/PayChan.cpp "Source")
_Added by the [PayChan amendment][]._
Claim XRP from a payment channel, adjust the payment channel's expiration, or both. This transaction can be used differently depending on the transaction sender's role in the specified channel:
The **source address** of a channel can:
- Send XRP from the channel to the destination with _or without_ a signed Claim.
- Set the channel to expire as soon as the channel's `SettleDelay` has passed.
- Clear a pending `Expiration` time.
- Close a channel immediately, with or without processing a claim first. The source address cannot close the channel immediately if the channel has XRP remaining.
The **destination address** of a channel can:
- Receive XRP from the channel using a signed Claim.
- Close the channel immediately after processing a Claim, refunding any unclaimed XRP to the channel's source.
**Any address** sending this transaction can:
- Cause a channel to be closed if its `Expiration` or `CancelAfter` time is older than the previous ledger's close time. Any validly-formed PaymentChannelClaim transaction has this effect regardless of the contents of the transaction.
## Example {% $frontmatter.seo.title %} JSON
```json
{
"Channel": "C1AE6DDDEEC05CF2978C0BAD6FE302948E9533691DC749DCDD3B9E5992CA6198",
"Balance": "1000000",
"Amount": "1000000",
"Signature": "30440220718D264EF05CAED7C781FF6DE298DCAC68D002562C9BF3A07C1E721B420C0DAB02203A5A4779EF4D2CCC7BC3EF886676D803A9981B928D3B8ACA483B80ECA3CD7B9B",
"PublicKey": "32D2471DB72B27E3310F355BB33E339BF26F8392D5A93D3BC0FC3B566612DA0F0A"
}
```
[Query example transaction. >](/resources/dev-tools/websocket-api-tool?server=wss%3A%2F%2Fxrplcluster.com%2F&req=%7B%22id%22%3A%22example_PaymentChannelClaim%22%2C%22command%22%3A%22tx%22%2C%22transaction%22%3A%229C0CAAC3DD1A74461132DA4451F9E53BDF4C93DFDBEFCE1B10021EC569013B33%22%2C%22binary%22%3Afalse%7D)
<!--{# TODO: replace the above example with one where the channel, public key, signature, and balance match #}-->
{% raw-partial file="/_snippets/tx-fields-intro.md" /%}
<!--{# fix md highlighting_ #}-->
| Field | JSON Type | [Internal Type][] | Description |
|:------------|:----------|:------------------|:-------------------------------|
| `Channel` | String | Hash256 | The unique ID of the channel, as a 64-character hexadecimal string. |
| `Balance` | String | Amount | _(Optional)_ Total amount of [XRP, in drops][Currency Amount], delivered by this channel after processing this claim. Required to deliver XRP. Must be more than the total amount delivered by the channel so far, but not greater than the `Amount` of the signed claim. Must be provided except when closing the channel. |
| `Amount` | String | Amount | _(Optional)_ The amount of [XRP, in drops][Currency Amount], authorized by the `Signature`. This must match the amount in the signed message. This is the cumulative amount of XRP that can be dispensed by the channel, including XRP previously redeemed. |
| `Signature` | String | Blob | _(Optional)_ The signature of this claim, as hexadecimal. The signed message contains the channel ID and the amount of the claim. Required unless the sender of the transaction is the source address of the channel. |
| `PublicKey` | String | Blob | _(Optional)_ The public key used for the signature, as hexadecimal. This must match the `PublicKey` stored in the ledger for the channel. Required unless the sender of the transaction is the source address of the channel and the `Signature` field is omitted. (The transaction includes the public key so that `rippled` can check the validity of the signature before trying to apply the transaction to the ledger.) |
If the payment channel was created before the [fixPayChanRecipientOwnerDir amendment](../../../../resources/known-amendments.md#fixpaychanrecipientownerdir) became enabled (on 2020-05-01), it is possible that the destination of the payment channel has been [deleted](../../../../concepts/accounts/deleting-accounts.md) and does not currently exist in the ledger. If the destination has been deleted, the source account cannot send XRP from the channel to the destination; instead, the transaction fails with `tecNO_DST`. (And, of course, the deleted account cannot send any transactions at all.) Other uses of this transaction type are unaffected when the destination account has been deleted, including adjusting the channel expiration, closing a channel with no XRP, or removing a channel that has passed its expiration time.
## PaymentChannelClaim Flags
Transactions of the PaymentChannelClaim type support additional values in the [`Flags` field](../common-fields.md#flags-field), as follows:
| Flag Name | Hex Value | Decimal Value | Description |
|:----------|:-------------|:--------------|:----------------------------------|
| `tfRenew` | `0x00010000` | 65536 | Clear the channel's `Expiration` time. (`Expiration` is different from the channel's immutable `CancelAfter` time.) Only the source address of the payment channel can use this flag. |
| `tfClose` | `0x00020000` | 131072 | Request to close the channel. Only the channel source and destination addresses can use this flag. This flag closes the channel immediately if it has no more XRP allocated to it after processing the current claim, or if the destination address uses it. If the source address uses this flag when the channel still holds XRP, this schedules the channel to close after `SettleDelay` seconds have passed. (Specifically, this sets the `Expiration` of the channel to the close time of the previous ledger plus the channel's `SettleDelay` time, unless the channel already has an earlier `Expiration` time.) If the destination address uses this flag when the channel still holds XRP, any XRP that remains after processing the claim is returned to the source address. |
{% raw-partial file="/_snippets/common-links.md" /%}

49
docs/references/protocol/transactions/types/paymentchannelcreate.md Normal file
View File

@@ -0,0 +1,49 @@
---
html: paymentchannelcreate.html
parent: transaction-types.html
seo:
description: Open a new payment channel.
labels:
- Payment Channels
---
# PaymentChannelCreate
[[Source]](https://github.com/XRPLF/rippled/blob/master/src/ripple/app/tx/impl/PayChan.cpp "Source")
_Added by the [PayChan amendment][]._
Create a [payment channel](../../../../concepts/payment-types/payment-channels.md) and fund it with XRP. The address sending this transaction becomes the "source address" of the payment channel.
## Example {% $frontmatter.seo.title %} JSON
```json
{
"Account": "rf1BiGeXwwQoi8Z2ueFYTEXSwuJYfV2Jpn",
"TransactionType": "PaymentChannelCreate",
"Amount": "10000",
"Destination": "rsA2LpzuawewSBQXkiju3YQTMzW13pAAdW",
"SettleDelay": 86400,
"PublicKey": "32D2471DB72B27E3310F355BB33E339BF26F8392D5A93D3BC0FC3B566612DA0F0A",
"CancelAfter": 533171558,
"DestinationTag": 23480,
"SourceTag": 11747
}
```
[Query example transaction. >](/resources/dev-tools/websocket-api-tool?server=wss%3A%2F%2Fxrplcluster.com%2F&req=%7B%22id%22%3A%22example_PaymentChannelCreate%22%2C%22command%22%3A%22tx%22%2C%22transaction%22%3A%22711C4F606C63076137FAE90ADC36379D7066CF551E96DA6FE2BDAB5ECBFACF2B%22%2C%22binary%22%3Afalse%7D)
{% raw-partial file="/_snippets/tx-fields-intro.md" /%}
<!--{# fix md highlighting_ #}-->
| Field | JSON Type | [Internal Type][] | Description |
|:-----------------|:----------|:------------------|:--------------------------|
| `Amount` | String | Amount | Amount of [XRP, in drops][Currency Amount], to deduct from the sender's balance and set aside in this channel. While the channel is open, the XRP can only go to the `Destination` address. When the channel closes, any unclaimed XRP is returned to the source address's balance. |
| `Destination` | String | AccountID | Address to receive XRP claims against this channel. This is also known as the "destination address" for the channel. Cannot be the same as the sender (`Account`). |
| `SettleDelay` | Number | UInt32 | Amount of time the source address must wait before closing the channel if it has unclaimed XRP. |
| `PublicKey` | String | Blob | The 33-byte public key of the key pair the source will use to sign claims against this channel, in hexadecimal. This can be any secp256k1 or Ed25519 public key. For more information on key pairs, see [Key Derivation](../../../../concepts/accounts/cryptographic-keys.md#key-derivation) <!-- STYLE_OVERRIDE: will --> |
| `CancelAfter` | Number | UInt32 | _(Optional)_ The time, in [seconds since the Ripple Epoch][], when this channel expires. Any transaction that would modify the channel after this time closes the channel without otherwise affecting it. This value is immutable; the channel can be closed earlier than this time but cannot remain open after this time. |
| `DestinationTag` | Number | UInt32 | _(Optional)_ Arbitrary tag to further specify the destination for this payment channel, such as a hosted recipient at the destination address. |
If the `Destination` account is blocking incoming payment channels, the transaction fails with result code `tecNO_PERMISSION`. _(Requires the [DisallowIncoming amendment][] {% not-enabled /%})_
{% raw-partial file="/_snippets/common-links.md" /%}

53
docs/references/protocol/transactions/types/paymentchannelfund.md Normal file
View File

@@ -0,0 +1,53 @@
---
html: paymentchannelfund.html
parent: transaction-types.html
seo:
description: Add more XRP to a payment channel.
labels:
- Payment Channels
---
# PaymentChannelFund
[[Source]](https://github.com/XRPLF/rippled/blob/master/src/ripple/app/tx/impl/PayChan.cpp "Source")
_Added by the [PayChan amendment][]._
Add additional [XRP](../../../../introduction/what-is-xrp.md) to an open [payment channel](../../../../concepts/payment-types/payment-channels.md), and optionally update the expiration time of the channel. Only the source address of the channel can use this transaction.
Example PaymentChannelFund:
```json
{
"Account": "rf1BiGeXwwQoi8Z2ueFYTEXSwuJYfV2Jpn",
"TransactionType": "PaymentChannelFund",
"Channel": "C1AE6DDDEEC05CF2978C0BAD6FE302948E9533691DC749DCDD3B9E5992CA6198",
"Amount": "200000",
"Expiration": 543171558
}
```
[Query example transaction. >](/resources/dev-tools/websocket-api-tool?server=wss%3A%2F%2Fs1.ripple.com%2F&req=%7B%22id%22%3A%22example_PaymentChannelFund%22%2C%22command%22%3A%22tx%22%2C%22transaction%22%3A%22877FA6E2FF8E08597D1F24E30BE8E52D0C9C06F0D620C5721E55622B6A632DFF%22%2C%22binary%22%3Afalse%7D)
{% raw-partial file="/_snippets/tx-fields-intro.md" /%}
<!--{# fix md highlighting_ #}-->
| Field | JSON Type | [Internal Type][] | Description |
|:-------------|:----------|:------------------|:------------------------------|
| `Channel` | String | Hash256 | The unique ID of the channel to fund, as a 64-character hexadecimal string. |
| `Amount` | String | Amount | Amount of [XRP, in drops][Currency Amount] to add to the channel. Must be a positive amount of XRP. |
| `Expiration` | Number | UInt32 | _(Optional)_ New `Expiration` time to set for the channel, in [seconds since the Ripple Epoch][]. This must be later than either the current time plus the `SettleDelay` of the channel, or the existing `Expiration` of the channel. After the `Expiration` time, any transaction that would access the channel closes the channel without taking its normal action. Any unspent XRP is returned to the source address when the channel closes. (`Expiration` is separate from the channel's immutable `CancelAfter` time.) For more information, see the [PayChannel ledger object type](../../ledger-data/ledger-entry-types/paychannel.md). |
## Error Cases
Besides errors that can occur for all transactions, {% $frontmatter.seo.title %} transactions can result in the following [transaction result codes](../transaction-results/transaction-results.md):
| Error Code | Description |
|:--------------------------|:-------------------------------------------------|
| `tecINSUFFICIENT_RESERVE` | The sending account has less XRP than the [reserve requirement](../../../../concepts/accounts/reserves.md). |
| `tecNO_DST` | The destination account of the channel has been deleted. This is only possible if the payment channel was created before the [fixPayChanRecipientOwnerDir amendment](../../../../resources/known-amendments.md#fixpaychanrecipientownerdir) became enabled (on 2020-05-01). |
| `tecNO_ENTRY` | The Payment Channel identified by the `Channel` field does not exist. |
| `tecNO_PERMISSION` | The sender of the transaction is not the source address for the channel. |
| `tecUNFUNDED` | The sending account does not have enough XRP to fund the channel with the requested amount and still meet the [reserve requirement](../../../../concepts/accounts/reserves.md). |
| `temBAD_AMOUNT` | The `Amount` field of the transaction is invalid. The amount must be XRP and it cannot be zero or negative. |
| `temBAD_EXPIRATION` | The `Expiration` field is invalid. |
{% raw-partial file="/_snippets/common-links.md" /%}

46
docs/references/protocol/transactions/types/setregularkey.md Normal file
View File

@@ -0,0 +1,46 @@
---
html: setregularkey.html
parent: transaction-types.html
seo:
description: Add, remove, or modify an account's regular key pair.
labels:
- Security
---
# SetRegularKey
[[Source]](https://github.com/XRPLF/rippled/blob/4239880acb5e559446d2067f00dabb31cf102a23/src/ripple/app/transactors/SetRegularKey.cpp "Source")
A `SetRegularKey` transaction assigns, changes, or removes the regular key pair associated with an account.
You can protect your account by assigning a regular key pair to it and using it instead of the master key pair to sign transactions whenever possible. If your regular key pair is compromised, but your master key pair is not, you can use a `SetRegularKey` transaction to regain control of your account.
## Example {% $frontmatter.seo.title %} JSON
```json
{
"Flags": 0,
"TransactionType": "SetRegularKey",
"Account": "rf1BiGeXwwQoi8Z2ueFYTEXSwuJYfV2Jpn",
"Fee": "12",
"RegularKey": "rAR8rR8sUkBoCZFawhkWzY4Y5YoyuznwD"
}
```
[Query example transaction. >](/resources/dev-tools/websocket-api-tool?server=wss%3A%2F%2Fxrplcluster.com%2F&req=%7B%22id%22%3A%22example_SetRegularKey%22%2C%22command%22%3A%22tx%22%2C%22transaction%22%3A%226AA6F6EAAAB56E65F7F738A9A2A8A7525439D65BA990E9BA08F6F4B1C2D349B4%22%2C%22binary%22%3Afalse%7D)
{% raw-partial file="/_snippets/tx-fields-intro.md" /%}
<!--{# fix md highlighting_ #}-->
| Field | JSON Type | [Internal Type][] | Description |
|:-------------|:----------|:------------------|:------------------------------|
| `RegularKey` | String | AccountID | _(Optional)_ A base-58-encoded [Address][] that indicates the regular key pair to be assigned to the account. If omitted, removes any existing regular key pair from the account. Must not match the master key pair for the address. |
## See Also
For more information about regular and master key pairs, see [Cryptographic Keys](../../../../concepts/accounts/cryptographic-keys.md).
For a tutorial on assigning a regular key pair to an account, see [Working with a Regular Key Pair](../../../../tutorials/manage-account-settings/assign-a-regular-key-pair.md).
For even greater security, you can use [multi-signing](../../../../concepts/accounts/multi-signing.md), but multi-signing requires additional XRP for the [transaction cost][] and [reserve](../../../../concepts/accounts/reserves.md).
{% raw-partial file="/_snippets/common-links.md" /%}

67
docs/references/protocol/transactions/types/signerlistset.md Normal file
View File

@@ -0,0 +1,67 @@
---
html: signerlistset.html
parent: transaction-types.html
seo:
description: Add, remove, or modify an account's multi-signing list.
labels:
- Security
---
# SignerListSet
[[Source]](https://github.com/XRPLF/rippled/blob/master/src/ripple/app/tx/impl/SetSignerList.cpp "Source")
The SignerListSet transaction creates, replaces, or removes a list of signers that can be used to [multi-sign](../../../../concepts/accounts/multi-signing.md) a transaction. This transaction type was introduced by the [MultiSign amendment][].
## Example {% $frontmatter.seo.title %} JSON
```json
{
"Flags": 0,
"TransactionType": "SignerListSet",
"Account": "rf1BiGeXwwQoi8Z2ueFYTEXSwuJYfV2Jpn",
"Fee": "12",
"SignerQuorum": 3,
"SignerEntries": [
{
"SignerEntry": {
"Account": "rsA2LpzuawewSBQXkiju3YQTMzW13pAAdW",
"SignerWeight": 2
}
},
{
"SignerEntry": {
"Account": "rUpy3eEg8rqjqfUoLeBnZkscbKbFsKXC3v",
"SignerWeight": 1
}
},
{
"SignerEntry": {
"Account": "raKEEVSGnKSD9Zyvxu4z6Pqpm4ABH8FS6n",
"SignerWeight": 1
}
}
]
}
```
[Query example transaction. >](/resources/dev-tools/websocket-api-tool?server=wss%3A%2F%2Fxrplcluster.com%2F&req=%7B%22id%22%3A%22example_SignerListSet%22%2C%22command%22%3A%22tx%22%2C%22transaction%22%3A%2209A9C86BF20695735AB03620EB1C32606635AC3DA0B70282F37C674FC889EFE7%22%2C%22binary%22%3Afalse%7D)
{% raw-partial file="/_snippets/tx-fields-intro.md" /%}
<!--{# fix md highlighting_ #}-->
| Field | JSON Type | [Internal Type][] | Description |
|:--------------|:----------|:------------------|:-----------------------------|
| `SignerQuorum` | Number | UInt32 | A target number for the signer weights. A multi-signature from this list is valid only if the sum weights of the signatures provided is greater than or equal to this value. To delete a signer list, use the value `0`. |
| `SignerEntries` | Array | Array | _(Omitted when deleting)_ Array of [`SignerEntry` objects](../../ledger-data/ledger-entry-types/signerlist.md#signer-entry-object), indicating the addresses and weights of signers in this list. This signer list must have at least 1 member and no more than 32 members. No address may appear more than once in the list, nor may the `Account` submitting the transaction appear in the list. _(Updated by the [ExpandedSignerList amendment][].)_ |
A successful SignerListSet transaction replaces the account's [`SignerList` object](../../ledger-data/ledger-entry-types/signerlist.md) in the ledger, or adds one if it did not exist before. An account may not have more than one signer list. To delete a signer list, you must set `SignerQuorum` to `0` _and_ omit the `SignerEntries` field. Otherwise, the transaction fails with the error [`temMALFORMED`](../transaction-results/tem-codes.md). A transaction to delete a signer list is considered successful even if there was no signer list to delete.
You cannot create a signer list such that the `SignerQuorum` could never be met. The `SignerQuorum` must be greater than 0 but less than or equal to the sum of the `SignerWeight` values in the list. Otherwise, the transaction fails with the error [`temMALFORMED`](../transaction-results/tem-codes.md).
You can create, update, or remove a signer list using the master key, regular key, or the current signer list, if those methods of signing transactions are available.
You cannot remove the last method of signing transactions from an account. If an account's master key is disabled (the account has the [`lsfDisableMaster` flag](../../ledger-data/ledger-entry-types/accountroot.md#accountroot-flags) enabled) and the account does not have a [Regular Key](../../../../concepts/accounts/cryptographic-keys.md) configured, then you cannot delete the signer list from the account. Instead, the transaction fails with the error [`tecNO_ALTERNATIVE_KEY`](../transaction-results/tec-codes.md).
Creating or replacing a signer list enables the `lsfOneOwnerCount` flag on the [SignerList object](../../ledger-data/ledger-entry-types/signerlist.md). Lists that were created before the [MultiSignReserve amendment][] became enabled do not have this flag and have a higher [owner reserve](../../../../concepts/accounts/reserves.md#owner-reserves). You can decrease the owner reserve for these lists by replacing the list with the same list. For more information, see [SignerList Flags](../../ledger-data/ledger-entry-types/signerlist.md#signerlist-flags).
{% raw-partial file="/_snippets/common-links.md" /%}

52
docs/references/protocol/transactions/types/ticketcreate.md Normal file
View File

@@ -0,0 +1,52 @@
---
html: ticketcreate.html
parent: transaction-types.html
seo:
description: Set aside one or more sequence numbers as Tickets.
labels:
- Transaction Sending
---
# TicketCreate
[[Source]](https://github.com/XRPLF/rippled/blob/develop/src/ripple/app/tx/impl/CreateTicket.cpp "Source")
_(Added by the [TicketBatch amendment][].)_
A TicketCreate transaction sets aside one or more [sequence numbers][Sequence Number] as [Tickets](../../../../concepts/accounts/tickets.md).
## Example {% $frontmatter.seo.title %} JSON
```json
{
"TransactionType": "TicketCreate",
"Account": "rf1BiGeXwwQoi8Z2ueFYTEXSwuJYfV2Jpn",
"Fee": "10",
"Sequence": 381,
"TicketCount": 10
}
```
[Query example transaction. >](/resources/dev-tools/websocket-api-tool?server=wss%3A%2F%2Fs1.ripple.com%2F&req=%7B%22id%22%3A%22example_TicketCreate%22%2C%22command%22%3A%22tx%22%2C%22transaction%22%3A%22738AEF36B48CA4A2D85C2B74910DC34DDBBCA4C83643F2DB84A58785ED5AD3E3%22%2C%22binary%22%3Afalse%7D)
{% raw-partial file="/_snippets/tx-fields-intro.md" /%}
<!--{# fix md highlighting_ #}-->
| Field | JSON Type | [Internal Type][] | Description |
|:-----------------|:-----------------|:------------------|:-------------------|
| `TicketCount` | Number | UInt32 | How many Tickets to create. This must be a positive number and cannot cause the account to own more than 250 Tickets after executing this transaction. |
If the transaction cannot create _all_ of the requested Tickets (either due to the 250-Ticket limit or the [owner reserve](../../../../concepts/accounts/reserves.md)), it fails and creates no Tickets. To look up how many Tickets an account currently owns, use the [account_info method][] and check the `account_data.TicketCount` field.
**Tip:** This transaction increases the sending account's [sequence number][Sequence Number] by 1 _plus_ the number of tickets created (`TicketCount`). This is the only transaction that increases an account's sequence number by more than 1.
## Error Cases
Besides errors that can occur for all transactions, {% $frontmatter.seo.title %} transactions can result in the following [transaction result codes](../transaction-results/transaction-results.md):
| Error Code | Description |
|:--------------------------|:-------------------------------------------------|
| `temINVALID_COUNT` | The `TicketCount` field is invalid. It must be an integer from 1 to 250. |
| `tecDIR_FULL` | This transaction would cause the account to own more than the limit of 250 Tickets at a time, or more than the maximum number of ledger objects in general. |
| `tecINSUFFICIENT_RESERVE` | The sending account does not have enough XRP to meet the [owner reserve](../../../../concepts/accounts/reserves.md) of all the requested Tickets. |
{% raw-partial file="/_snippets/common-links.md" /%}

66
docs/references/protocol/transactions/types/trustset.md Normal file
View File

@@ -0,0 +1,66 @@
---
html: trustset.html
parent: transaction-types.html
seo:
description: Add or modify a trust line.
labels:
- Tokens
---
# TrustSet
[[Source]](https://github.com/XRPLF/rippled/blob/master/src/ripple/app/tx/impl/SetTrust.cpp "Source")
Create or modify a [trust line](../../../../concepts/tokens/fungible-tokens/index.md) linking two accounts.
## Example {% $frontmatter.seo.title %} JSON
```json
{
"TransactionType": "TrustSet",
"Account": "ra5nK24KXen9AHvsdFTKHSANinZseWnPcX",
"Fee": "12",
"Flags": 262144,
"LastLedgerSequence": 8007750,
"LimitAmount": {
"currency": "USD",
"issuer": "rsP3mgGb2tcYUrxiLFiHJiQXhsziegtwBc",
"value": "100"
},
"Sequence": 12
}
```
[Query example transaction. >](/resources/dev-tools/websocket-api-tool?server=wss%3A%2F%2Fxrplcluster.com%2F&req=%7B%22id%22%3A%22example_TrustSet%22%2C%22command%22%3A%22tx%22%2C%22transaction%22%3A%228566673ECD0A9731C516906E5D2F47129C5C13713602140733831A56CEAE1A05%22%2C%22binary%22%3Afalse%7D)
{% raw-partial file="/_snippets/tx-fields-intro.md" /%}
<!--{# fix md highlighting_ #}-->
| Field | JSON Type | [Internal Type][] | Description |
|:-------------------------|:----------|:------------------|:------------------|
| `LimitAmount` | Object | Amount | Object defining the trust line to create or modify, in the format of a [Currency Amount][]. |
| `LimitAmount`.`currency` | String | (Amount.currency) | The currency to this trust line applies to, as a three-letter [ISO 4217 Currency Code](https://www.xe.com/iso4217.php) or a 160-bit hex value according to [currency format](../../data-types/currency-formats.md). "XRP" is invalid. |
| `LimitAmount`.`value` | String | (Amount.value) | Quoted decimal representation of the limit to set on this trust line. |
| `LimitAmount`.`issuer` | String | (Amount.issuer) | The address of the account to extend trust to. |
| `QualityIn` | Number | UInt32 | _(Optional)_ Value incoming balances on this trust line at the ratio of this number per 1,000,000,000 units. A value of `0` is shorthand for treating balances at face value. |
| `QualityOut` | Number | UInt32 | _(Optional)_ Value outgoing balances on this trust line at the ratio of this number per 1,000,000,000 units. A value of `0` is shorthand for treating balances at face value. |
If the account specified in `LimitAmount.issuer` is blocking incoming trust lines, the transaction fails with the result code `tecNO_PERMISSION`. _(Requires the [DisallowIncoming amendment][] {% not-enabled /%})_
## TrustSet Flags
Transactions of the TrustSet type support additional values in the [`Flags` field](../common-fields.md#flags-field), as follows:
| Flag Name | Hex Value | Decimal Value | Description |
|:------------------|:-------------|:--------------|:--------------------------|
| `tfSetfAuth` | `0x00010000` | 65536 | Authorize the other party to hold [currency issued by this account](../../../../concepts/tokens/index.md). (No effect unless using the [`asfRequireAuth` AccountSet flag](accountset.md#accountset-flags).) Cannot be unset. |
| `tfSetNoRipple` | `0x00020000` | 131072 | Enable the No Ripple flag, which blocks [rippling](../../../../concepts/tokens/fungible-tokens/rippling.md) between two trust lines of the same currency if this flag is enabled on both. |
| `tfClearNoRipple` | `0x00040000` | 262144 | Disable the No Ripple flag, allowing [rippling](../../../../concepts/tokens/fungible-tokens/rippling.md) on this trust line. |
| `tfSetFreeze` | `0x00100000` | 1048576 | [Freeze](../../../../concepts/tokens/fungible-tokens/freezes.md) the trust line. |
| `tfClearFreeze` | `0x00200000` | 2097152 | [Unfreeze](../../../../concepts/tokens/fungible-tokens/freezes.md) the trust line. |
If a transaction tries to enable No Ripple but cannot, it fails with the result code `tecNO_PERMISSION`. Before the [fix1578 amendment][] became enabled, such a transaction would result in `tesSUCCESS` (making any other changes it could) instead.
The Auth flag of a trust line does not determine whether the trust line counts towards its owner's XRP reserve requirement. However, an enabled Auth flag prevents the trust line from being in its default state. An authorized trust line can never be deleted. An issuer can pre-authorize a trust line with the `tfSetfAuth` flag only, even if the limit and balance of the trust line are 0.
{% raw-partial file="/_snippets/common-links.md" /%}

64
docs/references/protocol/transactions/types/xchainaccountcreatecommit.md Normal file
View File

@@ -0,0 +1,64 @@
---
html: xchainaccountcreatecommit.html
parent: transaction-types.html
seo:
description: Create an account on one of the chains that the bridge connects. This account serves as the bridge entrance for that chain.
labels:
- Interoperability
status: not_enabled
---
# XChainAccountCreateCommit
[[Source]](https://github.com/XRPLF/rippled/blob/master/src/ripple/protocol/impl/TxFormats.cpp#L466-L474 "Source")
_(Requires the [XChainBridge amendment][] {% not-enabled /%})_
This transaction can only be used for XRP-XRP bridges.
The `XChainAccountCreateCommit` transaction creates a new account for a witness server to submit transactions on an issuing chain.
**Warning:** This transaction should only be executed if the witness attestations will be reliably delivered to the destination chain. If the signatures aren't delivered, then account creation will be blocked until attestations are received. This can be used maliciously; to disable this transaction on XRP-XRP bridges, omit the bridge's `MinAccountCreateAmount` field.
## Example XChainAccountCreateCommit JSON
```json
{
"Account": "rwEqJ2UaQHe7jihxGqmx6J4xdbGiiyMaGa",
"Destination": "rD323VyRjgzzhY4bFpo44rmyh2neB5d8Mo",
"TransactionType": "XChainAccountCreateCommit",
"Amount": "20000000",
"SignatureReward": "100",
"XChainBridge": {
"LockingChainDoor": "rMAXACCrp3Y8PpswXcg3bKggHX76V3F8M4",
"LockingChainIssue": {
"currency": "XRP"
},
"IssuingChainDoor": "rHb9CJAWyB4rj91VRWn96DkukG4bwdtyTh",
"IssuingChainIssue": {
"currency": "XRP"
}
}
}
```
## XChainAccountCreateCommit Fields
| Field | JSON Type | [Internal Type][] | Required? | Description |
|:------------------|:--------------------|:------------------|:----------| :-----------|
| `Amount` | [Currency Amount][] | Amount | Yes | The amount, in XRP, to use for account creation. This must be greater than or equal to the `MinAccountCreateAmount` specified in the `Bridge` ledger object. |
| `Destination` | String | Account | Yes | The destination account on the destination chain. |
| `SignatureReward` | [Currency Amount][] | Amount | No | The amount, in XRP, to be used to reward the witness servers for providing signatures. This must match the amount on the `Bridge` ledger object. |
| `XChainBridge` | XChainBridge | XChain_Bridge | Yes | The bridge to create accounts for. |
### XChainBridge Fields
| Field | JSON Type | [Internal Type][] | Required? | Description |
|:--------------------|:----------|:------------------|:----------|:----------------|
| `IssuingChainDoor` | String | Account | Yes | The door account on the issuing chain. For an XRP-XRP bridge, this must be the genesis account (the account that is created when the network is first started, which contains all of the XRP). |
| `IssuingChainIssue` | Issue | Issue | Yes | The asset that is minted and burned on the issuing chain. For an IOU-IOU bridge, the issuer of the asset must be the door account on the issuing chain, to avoid supply issues. |
| `LockingChainDoor` | String | Account | Yes | The door account on the locking chain. |
| `LockingChainIssue` | Issue | Issue | Yes | The asset that is locked and unlocked on the locking chain. |
{% raw-partial file="/_snippets/common-links.md" /%}

81
docs/references/protocol/transactions/types/xchainaddaccountcreateattestation.md Normal file
View File

@@ -0,0 +1,81 @@
---
html: xchainaddaccountcreateattestation.html
parent: transaction-types.html
seo:
description: The `XChainAddAccountCreateAttestation` transaction provides an attestation from a witness server that a `XChainAccountCreateCommit` transaction occurred on the other chain.
labels:
- Interoperability
status: not_enabled
---
# XChainAddAccountCreateAttestation
[[Source]](https://github.com/XRPLF/rippled/blob/master/src/ripple/protocol/impl/TxFormats.cpp#L447-L464 "Source")
_(Requires the [XChainBridge amendment][] {% not-enabled /%})_
The `XChainAddAccountCreateAttestation` transaction provides an attestation from a witness server that an `XChainAccountCreateCommit` transaction occurred on the other chain.
The signature must be from one of the keys on the door's signer list at the time the signature was provided. If the signature list changes between the time the signature was submitted and the quorum is reached, the new signature set is used and some of the currently collected signatures may be removed.
Any account can submit signatures.
**Note:** The reward is only sent to accounts that have keys on the current list. A quorum of signers need to agree on the `SignatureReward`, the same way they need to agree on the other data. A single witness server can't provide an incorrect value for this in an attempt to collect a larger reward.
## Example XChainAddAccountCreateAttestation JSON
```json
{
"Account": "rDr5okqGKmMpn44Bbhe5WAfDQx8e9XquEv",
"TransactionType": "XChainAddAccountCreateAttestation",
"OtherChainSource": "rUzB7yg1LcFa7m3q1hfrjr5w53vcWzNh3U",
"Destination": "rJMfWNVbyjcCtds8kpoEjEbYQ41J5B6MUd",
"Amount": "2000000000",
"PublicKey": "EDF7C3F9C80C102AF6D241752B37356E91ED454F26A35C567CF6F8477960F66614",
"Signature": "F95675BA8FDA21030DE1B687937A79E8491CE51832D6BEEBC071484FA5AF5B8A0E9AFF11A4AA46F09ECFFB04C6A8DAE8284AF3ED8128C7D0046D842448478500",
"WasLockingChainSend": 1,
"AttestationRewardAccount": "rpFp36UHW6FpEcZjZqq5jSJWY6UCj3k4Es",
"AttestationSignerAccount": "rpWLegmW9WrFBzHUj7brhQNZzrxgLj9oxw",
"XChainAccountCreateCount": "2",
"SignatureReward": "204",
"XChainBridge": {
"LockingChainDoor": "r3nCVTbZGGYoWvZ58BcxDmiMUU7ChMa1eC",
"LockingChainIssue": {
"currency": "XRP"
},
"IssuingChainDoor": "rHb9CJAWyB4rj91VRWn96DkukG4bwdtyTh",
"IssuingChainIssue": {
"currency": "XRP"
}
},
"Fee": "20"
}
```
## XChainAddAccountCreateAttestation Fields
| Field | JSON Type | [Internal Type][] | Required? | Description |
|:---------------------------|:--------------------|:------------------|:----------|:------------|
| `Amount` | [Currency Amount][] | Amount | Yes | The amount committed by the `XChainAccountCreateCommit` transaction on the source chain. |
| `AttestationRewardAccount` | String | Account | Yes | The account that should receive this signer's share of the `SignatureReward`. |
| `AttestationSignerAccount` | String | Account | Yes | The account on the door account's signer list that is signing the transaction. |
| `Destination` | String | Account | Yes | The destination account for the funds on the destination chain. |
| `OtherChainSource` | String | Account | Yes | The account on the source chain that submitted the `XChainAccountCreateCommit` transaction that triggered the event associated with the attestation. |
| `PublicKey` | String | Blob | Yes | The public key used to verify the signature. |
| `Signature` | String | Blob | Yes | The signature attesting to the event on the other chain. |
| `SignatureReward` | [Currency Amount][] | Amount | Yes | The signature reward paid in the `XChainAccountCreateCommit` transaction. |
| `WasLockingChainSend` | Number | UInt8 | Yes | A boolean representing the chain where the event occurred. |
| `XChainAccountCreateCount` | String | UInt64 | Yes | The counter that represents the order that the claims must be processed in. |
| `XChainBridge` | XChainBridge | XChain_Bridge | Yes | The bridge associated with the attestation. |
### XChainBridge Fields
| Field | JSON Type | [Internal Type][] | Required? | Description |
|:--------------------|:----------|:------------------|:----------|:----------------|
| `IssuingChainDoor` | String | Account | Yes | The door account on the issuing chain. For an XRP-XRP bridge, this must be the genesis account (the account that is created when the network is first started, which contains all of the XRP). |
| `IssuingChainIssue` | Issue | Issue | Yes | The asset that is minted and burned on the issuing chain. For an IOU-IOU bridge, the issuer of the asset must be the door account on the issuing chain, to avoid supply issues. |
| `LockingChainDoor` | String | Account | Yes | The door account on the locking chain. |
| `LockingChainIssue` | Issue | Issue | Yes | The asset that is locked and unlocked on the locking chain. |
{% raw-partial file="/_snippets/common-links.md" /%}

100
docs/references/protocol/transactions/types/xchainaddclaimattestation.md Normal file
View File

@@ -0,0 +1,100 @@
---
html: xchainaddclaimattestation.html
parent: transaction-types.html
seo:
description: Submit proof (attestation) to the destination chain that an event that happened on the source chain.
labels:
- Interoperability
status: not_enabled
---
# XChainAddClaimAttestation
[[Source]](https://github.com/XRPLF/rippled/blob/master/src/ripple/protocol/impl/TxFormats.cpp#L429-L445 "Source")
_(Requires the [XChainBridge amendment][] {% not-enabled /%})_
The `XChainAddClaimAttestation` transaction provides proof from a witness server, attesting to an `XChainCommit` transaction.
The signature must be from one of the keys on the door's signer list at the time the signature was provided. However, if the signature list changes between the time the signature was submitted and the quorum is reached, the new signature set is used and some of the currently collected signatures may be removed.
Any account can submit signatures.
**Note:** The reward is only sent to accounts that have keys on the current list. A quorum of signers need to agree on the `SignatureReward`, the same way they need to agree on the other data. A single witness server can't provide an incorrect value for this in an attempt to collect a larger reward.
## Example XChainAddClaimAttestation JSON
```json
{
"TransactionType": "XChainAddClaimAttestation",
"Account": "rHb9CJAWyB4rj91VRWn96DkukG4bwdtyTh",
"XChainAttestationBatch": {
"XChainBridge": {
"IssuingChainDoor": "rKeSSvHvaMZJp9ykaxutVwkhZgWuWMLnQt",
"IssuingChainIssue": {
"currency": "XRP"
},
"LockingChainDoor": "rJvExveLEL4jNDEeLKCVdxaSCN9cEBnEQC",
"LockingChainIssue": {
"currency": "XRP"
}
},
"XChainClaimAttestationBatch" : [
{
"XChainClaimAttestationBatchElement" : {
"Account" : "rnJmYAiqEVngtnb5ckRroXLtCbWC7CRUBx",
"Amount" : "100000000",
"AttestationSignerAccount" : "rnJmYAiqEVngtnb5ckRroXLtCbWC7CRUBx",
"Destination" : "r9A8UyNpW3X46FUc6P7JZqgn6WgAPjBwPg",
"PublicKey" : "03DAB289CA36FF377F3F4304C7A7203FDE5EDCBFC209F430F6A4355361425526D0",
"Signature" : "616263",
"WasLockingChainSend" : 1,
"XChainClaimID" : "0000000000000000"
}
}
],
"XChainCreateAccountAttestationBatch": [
{
"XChainCreateAccountAttestationBatchElement": {
"Account": "rnJmYAiqEVngtnb5ckRroXLtCbWC7CRUBx",
"Amount": "1000000000",
"AttestationSignerAccount": "rEziJZmeZzsJvGVUmpUTey7qxQLKYxaK9f",
"Destination": "rKT9gDkaedAosiHyHZTjyZs2HvXpzuiGmC",
"PublicKey": "03ADB44CA8E56F78A0096825E5667C450ABD5C24C34E027BC1AAF7E5BD114CB5B5",
"Signature": "3044022036C8B90F85E8073C465F00625248A72D4714600F98EBBADBAD3B7ED226109A3A02204C5A0AE12D169CF790F66541F3DB59C289E0D9CA7511FDFE352BB601F667A26",
"SignatureReward": "1000000",
"WasLockingChainSend": 1,
"XChainAccountCreateCount": "0000000000000001"
}
}
]
}
}
```
## XChainAddClaimAttestation Fields
| Field | JSON Type | [Internal Type][] | Required? | Description |
|:---------------------------|:--------------------|:------------------|:----------|-------------|
| `Amount` | [Currency Amount][] | Amount | Yes | The amount committed by the `XChainCommit` transaction on the source chain. |
| `AttestationRewardAccount` | String | Account | Yes | The account that should receive this signer's share of the `SignatureReward`. |
| `AttestationSignerAccount` | String | Account | Yes | The account on the door account's signer list that is signing the transaction. |
| `Destination` | String | Account | No | The destination account for the funds on the destination chain (taken from the `XChainCommit` transaction). |
| `OtherChainSource` | String | Account | Yes | The account on the source chain that submitted the `XChainCommit` transaction that triggered the event associated with the attestation. |
| `PublicKey` | String | Blob | Yes | The public key used to verify the attestation signature. |
| `Signature` | String | Blob | Yes | The signature attesting to the event on the other chain. |
| `WasLockingChainSend` | Number | UInt8 | Yes | A boolean representing the chain where the event occurred. |
| `XChainBridge` | XChainBridge | XChain_Bridge | Yes | The bridge to use to transfer funds. |
| `XChainClaimID` | String | UInt64 | Yes | The `XChainClaimID` associated with the transfer, which was included in the `XChainCommit` transaction. |
### XChainBridge Fields
| Field | JSON Type | [Internal Type][] | Required? | Description |
|:--------------------|:----------|:------------------|:----------|:----------------|
| `IssuingChainDoor` | String | Account | Yes | The door account on the issuing chain. For an XRP-XRP bridge, this must be the genesis account (the account that is created when the network is first started, which contains all of the XRP). |
| `IssuingChainIssue` | Issue | Issue | Yes | The asset that is minted and burned on the issuing chain. For an IOU-IOU bridge, the issuer of the asset must be the door account on the issuing chain, to avoid supply issues. |
| `LockingChainDoor` | String | Account | Yes | The door account on the locking chain. |
| `LockingChainIssue` | Issue | Issue | Yes | The asset that is locked and unlocked on the locking chain. |
{% raw-partial file="/_snippets/common-links.md" /%}

63
docs/references/protocol/transactions/types/xchainclaim.md Normal file
View File

@@ -0,0 +1,63 @@
---
html: xchainclaim.html
parent: transaction-types.html
seo:
description: Complete a cross-chain transfer of value by claiming the value on the destination chain.
labels:
- Interoperability
status: not_enabled
---
# XChainClaim
[[Source]](https://github.com/XRPLF/rippled/blob/master/src/ripple/protocol/impl/TxFormats.cpp#L418-L427 "Source")
_(Requires the [XChainBridge amendment][] {% not-enabled /%})_
The `XChainClaim` transaction completes a cross-chain transfer of value. It allows a user to claim the value on the destination chain - the equivalent of the value locked on the source chain. A user can only claim the value if they own the cross-chain claim ID associated with the value locked on the source chain (the `Account` field). The user can send the funds to anyone (the `Destination` field). This transaction is only needed if an `OtherChainDestination` isn't specified in the `XChainCommit` transaction, or if something goes wrong with the automatic transfer of funds.
If the transaction succeeds in moving funds, the referenced `XChainOwnedClaimID` ledger object will be destroyed. This prevents transaction replay. If the transaction fails, the `XChainOwnedClaimID` won't be destroyed and the transaction can be re-run with different parameters.
## Example XChainClaim JSON
```json
{
"Account": "rahDmoXrtPdh7sUdrPjini3gcnTVYjbjjw",
"Amount": "10000",
"TransactionType": "XChainClaim",
"XChainClaimID": "13f",
"Destination": "rahDmoXrtPdh7sUdrPjini3gcnTVYjbjjw",
"XChainBridge": {
"LockingChainDoor": "rMAXACCrp3Y8PpswXcg3bKggHX76V3F8M4",
"LockingChainIssue": {
"currency": "XRP"
},
"IssuingChainDoor": "rHb9CJAWyB4rj91VRWn96DkukG4bwdtyTh",
"IssuingChainIssue": {
"currency": "XRP"
}
}
}
```
## XChainClaim Fields
| Field | JSON Type | [Internal Type][] | Required? | Description |
|:------------------------|:--------------------|:------------------|:----------|-------------|
| `Amount` | [Currency Amount][] | Amount | Yes | The amount to claim on the destination chain. This must match the amount attested to on the attestations associated with this `XChainClaimID`. |
| `Destination` | String | Account | Yes | The destination account on the destination chain. It must exist or the transaction will fail. However, if the transaction fails in this case, the sequence number and collected signatures won't be destroyed, and the transaction can be rerun with a different destination. |
| `DestinationTag` | Number | UInt32 | No | An integer destination tag. |
| `XChainBridge` | XChainBridge | XChain_Bridge | Yes | The bridge to use for the transfer. |
| `XChainClaimID` | String | UInt64 | Yes | The unique integer ID for the cross-chain transfer that was referenced in the corresponding `XChainCommit` transaction. |
### XChainBridge Fields
| Field | JSON Type | [Internal Type][] | Required? | Description |
|:--------------------|:----------|:------------------|:----------|:----------------|
| `IssuingChainDoor` | String | Account | Yes | The door account on the issuing chain. For an XRP-XRP bridge, this must be the genesis account (the account that is created when the network is first started, which contains all of the XRP). |
| `IssuingChainIssue` | Issue | Issue | Yes | The asset that is minted and burned on the issuing chain. For an IOU-IOU bridge, the issuer of the asset must be the door account on the issuing chain, to avoid supply issues. |
| `LockingChainDoor` | String | Account | Yes | The door account on the locking chain. |
| `LockingChainIssue` | Issue | Issue | Yes | The asset that is locked and unlocked on the locking chain. |
{% raw-partial file="/_snippets/common-links.md" /%}

59
docs/references/protocol/transactions/types/xchaincommit.md Normal file
View File

@@ -0,0 +1,59 @@
---
html: xchaincommit.html
parent: transaction-types.html
seo:
description: Initiate a cross-chain transfer of value.
labels:
- Interoperability
status: not_enabled
---
# XChainCommit
[[Source]](https://github.com/XRPLF/rippled/blob/master/src/ripple/protocol/impl/TxFormats.cpp#L408-L416 "Source")
_(Requires the [XChainBridge amendment][] {% not-enabled /%})_
The `XChainCommit` is the second step in a cross-chain transfer. It puts assets into trust on the locking chain so that they can be wrapped on the issuing chain, or burns wrapped assets on the issuing chain so that they can be returned on the locking chain.
## Example XChainCommit JSON
```json
{
"Account": "rMTi57fNy2UkUb4RcdoUeJm7gjxVQvxzUo",
"TransactionType": "XChainCommit",
"XChainBridge": {
"LockingChainDoor": "rMAXACCrp3Y8PpswXcg3bKggHX76V3F8M4",
"LockingChainIssue": {
"currency": "XRP"
},
"IssuingChainDoor": "rHb9CJAWyB4rj91VRWn96DkukG4bwdtyTh",
"IssuingChainIssue": {
"currency": "XRP"
}
},
"Amount": "10000",
"XChainClaimID": "13f"
}
```
## XChainCommit Fields
| Field | JSON Type | [Internal Type][] | Required? | Description |
|:------------------------|:--------------------|:------------------|:----------|-------------|
| `Amount` | [Currency Amount][] | Amount | Yes | The asset to commit, and the quantity. This must match the door account's `LockingChainIssue` (if on the locking chain) or the door account's `IssuingChainIssue` (if on the issuing chain). |
| `OtherChainDestination` | String | Account | No | The destination account on the destination chain. If this is not specified, the account that submitted the `XChainCreateClaimID` transaction on the destination chain will need to submit a `XChainClaim` transaction to claim the funds. |
| `XChainBridge` | XChainBridge | XChain_Bridge | Yes | The bridge to use to transfer funds. |
| `XChainClaimID` | String | UInt64 | Yes | The unique integer ID for a cross-chain transfer. This must be acquired on the destination chain (via a `XChainCreateClaimID` transaction) and checked from a validated ledger before submitting this transaction. If an incorrect sequence number is specified, the funds will be lost. |
### XChainBridge Fields
| Field | JSON Type | [Internal Type][] | Required? | Description |
|:--------------------|:----------|:------------------|:----------|:----------------|
| `IssuingChainDoor` | String | Account | Yes | The door account on the issuing chain. For an XRP-XRP bridge, this must be the genesis account (the account that is created when the network is first started, which contains all of the XRP). |
| `IssuingChainIssue` | Issue | Issue | Yes | The asset that is minted and burned on the issuing chain. For an IOU-IOU bridge, the issuer of the asset must be the door account on the issuing chain, to avoid supply issues. |
| `LockingChainDoor` | String | Account | Yes | The door account on the locking chain. |
| `LockingChainIssue` | Issue | Issue | Yes | The asset that is locked and unlocked on the locking chain. |
{% raw-partial file="/_snippets/common-links.md" /%}

64
docs/references/protocol/transactions/types/xchaincreatebridge.md Normal file
View File

@@ -0,0 +1,64 @@
---
html: xchaincreatebridge.html
parent: transaction-types.html
seo:
description: Create a bridge between two chains.
labels:
- Interoperability
status: not_enabled
---
# XChainCreateBridge
[[Source]](https://github.com/XRPLF/rippled/blob/master/src/ripple/protocol/impl/TxFormats.cpp#L381-L388 "Source")
_(Requires the [XChainBridge amendment][] {% not-enabled /%})_
The `XChainCreateBridge` transaction creates a new `Bridge` ledger object and defines a new cross-chain bridge entrance on the chain that the transaction is submitted on. It includes information about door accounts and assets for the bridge.
The transaction must be submitted first by the locking chain door account. To set up a valid bridge, door accounts on both chains must submit this transaction, in addition to setting up witness servers.
The complete production-grade setup would also include a `SignerListSet` transaction on the two door accounts for the witnesses’ signing keys, as well as disabling the door accounts’ master key. This ensures that the witness servers are truly in control of the funds.
**Note:** Each door account can only have one bridge. This prevents the creation of duplicate bridges for the same asset, which can cause asset imbalances on either chain.
## Example XChainCreateBridge JSON
```json
{
"TransactionType": "XChainCreateBridge",
"Account": "rhWQzvdmhf5vFS35vtKUSUwNZHGT53qQsg",
"XChainBridge": {
"LockingChainDoor": "rhWQzvdmhf5vFS35vtKUSUwNZHGT53qQsg",
"LockingChainIssue": {
"currency": "XRP"
},
"IssuingChainDoor": "rHb9CJAWyB4rj91VRWn96DkukG4bwdtyTh",
"IssuingChainIssue": {
"currency": "XRP"
}
},
"SignatureReward": 200,
"MinAccountCreateAmount": 1000000
}
```
## XChainCreateBridge Fields
| Field | JSON Type | [Internal Type][] | Required? | Description |
|:-------------------------|:--------------------|:------------------|:----------|:------------|
| `MinAccountCreateAmount` | [Currency Amount][] | Amount | No | The minimum amount, in XRP, required for a `XChainAccountCreateCommit` transaction. If this isn't present, the `XChainAccountCreateCommit` transaction will fail. This field can only be present on XRP-XRP bridges. |
| `SignatureReward` | [Currency Amount][] | Amount | Yes | The total amount to pay the witness servers for their signatures. This amount will be split among the signers. |
| `XChainBridge` | XChainBridge | XChain_Bridge | Yes | The bridge (door accounts and assets) to create. |
### XChainBridge Fields
| Field | JSON Type | [Internal Type][] | Required? | Description |
|:--------------------|:----------|:------------------|:----------|:----------------|
| `IssuingChainDoor` | String | Account | Yes | The door account on the issuing chain. For an XRP-XRP bridge, this must be the genesis account (the account that is created when the network is first started, which contains all of the XRP). |
| `IssuingChainIssue` | Issue | Issue | Yes | The asset that is minted and burned on the issuing chain. For an IOU-IOU bridge, the issuer of the asset must be the door account on the issuing chain, to avoid supply issues. |
| `LockingChainDoor` | String | Account | Yes | The door account on the locking chain. |
| `LockingChainIssue` | Issue | Issue | Yes | The asset that is locked and unlocked on the locking chain. |
{% raw-partial file="/_snippets/common-links.md" /%}

62
docs/references/protocol/transactions/types/xchaincreateclaimid.md Normal file
View File

@@ -0,0 +1,62 @@
---
html: xchaincreateclaimid.html
parent: transaction-types.html
seo:
description: Create a cross-chain claim ID that is used for a cross-chain transfer.
labels:
- Interoperability
status: not_enabled
---
# XChainCreateClaimID
[[Source]](https://github.com/XRPLF/rippled/blob/master/src/ripple/protocol/impl/TxFormats.cpp#L399-L406 "Source")
_(Requires the [XChainBridge amendment][] {% not-enabled /%})_
The `XChainCreateClaimID` transaction creates a new cross-chain claim ID that is used for a cross-chain transfer. A cross-chain claim ID represents *one* cross-chain transfer of value.
This transaction is the first step of a cross-chain transfer of value and is submitted on the destination chain, not the source chain.
It also includes the account on the source chain that locks or burns the funds on the source chain.
## Example XChainCreateClaimID JSON
```json
{
"Account": "rahDmoXrtPdh7sUdrPjini3gcnTVYjbjjw",
"OtherChainSource": "rMTi57fNy2UkUb4RcdoUeJm7gjxVQvxzUo",
"TransactionType": "XChainCreateClaimID",
"SignatureReward": "100",
"XChainBridge": {
"LockingChainDoor": "rMAXACCrp3Y8PpswXcg3bKggHX76V3F8M4",
"LockingChainIssue": {
"currency": "XRP"
},
"IssuingChainDoor": "rHb9CJAWyB4rj91VRWn96DkukG4bwdtyTh",
"IssuingChainIssue": {
"currency": "XRP"
}
}
}
```
## XChainCreateClaimID Fields
| Field | JSON Type | [Internal Type][] | Required? | Description |
|:-------------------|:------------------|:------------------|:----------|-------------|
| `OtherChainSource` | String | Account | Yes | The account that must send the `XChainCommit` transaction on the source chain. |
| `SignatureReward` | String | Account | Yes | The amount, in XRP, to reward the witness servers for providing signatures. This must match the amount on the `Bridge` ledger object. |
| `XChainBridge` | XChainBridge | XChain_Bridge | Yes | The bridge to create the claim ID for. |
### XChainBridge Fields
| Field | JSON Type | [Internal Type][] | Required? | Description |
|:--------------------|:----------|:------------------|:----------|:----------------|
| `IssuingChainDoor` | String | Account | Yes | The door account on the issuing chain. For an XRP-XRP bridge, this must be the genesis account (the account that is created when the network is first started, which contains all of the XRP). |
| `IssuingChainIssue` | Issue | Issue | Yes | The asset that is minted and burned on the issuing chain. For an IOU-IOU bridge, the issuer of the asset must be the door account on the issuing chain, to avoid supply issues. |
| `LockingChainDoor` | String | Account | Yes | The door account on the locking chain. |
| `LockingChainIssue` | Issue | Issue | Yes | The asset that is locked and unlocked on the locking chain. |
{% raw-partial file="/_snippets/common-links.md" /%}

72
docs/references/protocol/transactions/types/xchainmodifybridge.md Normal file
View File

@@ -0,0 +1,72 @@
---
html: xchainmodifybridge.html
parent: transaction-types.html
seo:
description: Modify the parameters of a bridge.
labels:
- Interoperability
status: not_enabled
---
# XChainModifyBridge
[[Source]](https://github.com/XRPLF/rippled/blob/develop/src/ripple/protocol/impl/TxFormats.cpp#L390-L397 "Source")
_(Requires the [XChainBridge amendment][] {% not-enabled /%})_
The `XChainModifyBridge` transaction allows bridge managers to modify the parameters of the bridge. They can only change the `SignatureReward` and the `MinAccountCreateAmount`.
This transaction must be sent by the door account and requires the entities that control the witness servers to coordinate and provide the signatures for this transaction. This coordination happens outside the ledger.
**Note:** You can't modify the signer list for the bridge with this transaction. The signer list is on the door account itself and is changed in the same way signer lists are changed on accounts (via a `SignerListSet` transaction).
## Example XChainModifyBridge JSON
```json
{
"TransactionType": "XChainModifyBridge",
"Account": "rhWQzvdmhf5vFS35vtKUSUwNZHGT53qQsg",
"XChainBridge": {
"LockingChainDoor": "rhWQzvdmhf5vFS35vtKUSUwNZHGT53qQsg",
"LockingChainIssue": {
"currency": "XRP"
},
"IssuingChainDoor": "rHb9CJAWyB4rj91VRWn96DkukG4bwdtyTh",
"IssuingChainIssue": {
"currency": "XRP"
}
},
"SignatureReward": 200,
"MinAccountCreateAmount": 1000000
}
```
## XChainModifyBridge Fields
| Field | JSON Type | [Internal Type][] | Required? | Description |
|:-------------------------|:--------------------|:------------------|:----------|-------------|
| `Flags` | Number | UInt32 | Yes | Specifies the flags for this transaction. |
| `MinAccountCreateAmount` | [Currency Amount][] | Amount | No | The minimum amount, in XRP, required for a `XChainAccountCreateCommit` transaction. If this is not present, the `XChainAccountCreateCommit` transaction will fail. This field can only be present on XRP-XRP bridges. |
| `SignatureReward` | [Currency Amount][] | Amount | No | The signature reward split between the witnesses for submitting attestations. |
| `XChainBridge` | XChainBridge | XChain_Bridge | Yes | The bridge to modify. |
### XChainBridge Fields
| Field | JSON Type | [Internal Type][] | Required? | Description |
|:--------------------|:----------|:------------------|:----------|:----------------|
| `IssuingChainDoor` | String | Account | Yes | The door account on the issuing chain. For an XRP-XRP bridge, this must be the genesis account (the account that is created when the network is first started, which contains all of the XRP). |
| `IssuingChainIssue` | Issue | Issue | Yes | The asset that is minted and burned on the issuing chain. For an IOU-IOU bridge, the issuer of the asset must be the door account on the issuing chain, to avoid supply issues. |
| `LockingChainDoor` | String | Account | Yes | The door account on the locking chain. |
| `LockingChainIssue` | Issue | Issue | Yes | The asset that is locked and unlocked on the locking chain. |
## Transaction Flags
In addition to the universal transaction flags that are applicable to all transactions, you can specify this flag:
| Flag Name | Flag Value | Description |
|------------------------------|--------------|-------------|
| `tfClearAccountCreateAmount` | `0x00010000` | Clears the `MinAccountCreateAmount` of the bridge. |
{% raw-partial file="/_snippets/common-links.md" /%}