ARCHIVE/xrpl-dev-portal
1
0
Fork 0
mirror of https://github.com/XRPLF/xrpl-dev-portal.git synced 2025-11-07 05:15:48 +00:00
Code Issues Packages Projects Releases Wiki Activity

Transactions, mostly fixed links

Browse Source
This commit is contained in:
ddawson
2022-11-23 17:13:51 -08:00
parent 13ee5a061f
commit cf01686600
22 changed files with 306 additions and 6539 deletions
Download Patch File Download Diff File Expand all files Collapse all files

50
content/concepts/accounts/account-creating.md
View File

@@ -1,50 +0,0 @@
---
html: account-creating.html
parent: accounts.html
blurb: Create an account by sending a minimum reserve amount to a valid address.
labels:
- Accounts
---
# Creating Accounts
There is not a dedicated "create account" transaction. The `Payment` transaction automatically creates a new account if a payment sends XRP equal to or greater than the account reserve to a mathematically valid address that does not already have an account. This is called _funding_ an account, and creates an AccountRoot object in the ledger. No other transaction can create an account.
**Caution:** Funding an account _does not_ give you any special privileges over that account. Whoever has the secret key corresponding to the account's address has full control over the account and all XRP it contains. For some addresses, it is possible that no one has the secret key, in which case the account is a black hole and the XRP is lost forever.
The typical way to get an account in the XRP Ledger is as follows:
1. Generate a key pair from a strong source of randomness and calculate the address of that key pair. (For example, you can use the `wallet_propose` method to do this.)
2. Have someone who already has an account in the XRP Ledger send XRP to the address you generated.
- For example, you can buy XRP in a private exchange, then withdraw XRP from the exchange to the address you specified.
**Caution:** The first time you receive XRP at your own XRP Ledger address, you must pay the account reserve (currently 10 XRP), which locks up that amount of XRP indefinitely. In contrast, private exchanges usually hold all their customers' XRP in a few shared XRP Ledger accounts, so customers don't have to pay the reserve for individual accounts at the exchange. Before withdrawing, consider whether having your own account directly on the XRP Ledger is worth the price.
## Transaction History
In the XRP Ledger, transaction history is tracked by a "thread" of transactions linked by a transaction's identifying hash and the ledger index. The `AccountRoot` ledger object has the identifying hash and ledger of the transaction that most recently modified it; the metadata of that transaction includes the previous state of the `AccountRoot` node, so it is possible to iterate through the history of a single account this way. This transaction history includes any transactions that modify the `AccountRoot` node directly, including:
- Transactions sent by the account, because they modify the account's `Sequence` number. These transactions also modify the account's XRP balance because of the [transaction cost](../transactions/transaction-cost.md).
- Transactions that modified the account's XRP balance, including incoming `Payment` transactions and other types of transactions such as `PaymentChannelClaim` and `EscrowFinish`.
The _conceptual_ transaction history of an account also includes transactions that modified the account's owned objects and non-XRP balances. These objects are separate ledger objects, each with their own thread of transactions that affected them. If you have an account's full ledger history, you can follow it forward to find the ledger objects created or modified by it. A "complete" transaction history includes the history of objects owned by a transaction, such as:
- `RippleState` objects (Trust Lines) connected to the account.
- `DirectoryNode` objects, especially the owner directory tracking the account's owned objects.
- `Offer` objects, representing the account's outstanding currency-exchange orders in the decentralized exchange
- `PayChannel` objects, representing asynchronous payment channels to and from the account
- `Escrow` objects, representing held payments to or from the account that are locked by time or a crypto-condition.
- `SignerList` objects, representing lists of addresses that can authorize transactions for the account by multi-signing.
## Address Encoding
**Tip:** These technical details are only relevant for people building low-level library software for XRP Ledger compatibility!
[[Source]](https://github.com/ripple/rippled/blob/35fa20a110e3d43ffc1e9e664fc9017b6f2747ae/src/ripple/protocol/impl/AccountID.cpp#L109-L140 "Source")
XRP Ledger addresses are encoded using base58 with the _dictionary_ `rpshnaf39wBUDNEGHJKLM4PQRST7VWXYZ2bcdeCg65jkm8oFqi1tuvAxyz`. Since the XRP Ledger encodes several types of keys with base58, it prefixes the encoded data with a one-byte "type prefix" (also called a "version prefix") to distinguish them. The type prefix causes addresses to usually start with different letters in base58 format.

14
content/concepts/accounts/accounts.md
View File

@@ -9,23 +9,21 @@ labels:
An "Account" in the XRP Ledger represents a holder of XRP and a sender of transactions.
<!-- Need to document the information you need to create a tranaction from one account to another. What else do you need to know to use a basic account? -->
An account consists of an address, an XRP balance, a sequence number, and a history of its transactions. (See [Account Structure](account-structure.html)) for details.
## Creating Accounts
There is not a dedicated "create account" transaction. The `Payment` transaction automatically creates a new account if a payment sends XRP equal to or greater than the account reserve to a mathematically valid address that does not already have an account. This is called _funding_ an account, and creates an AccountRoot object in the ledger. No other transaction can create an account.
**Caution:** Funding an account _does not_ give you any special privileges over that account. Whoever has the secret key corresponding to the account's address has full control over the account and all XRP it contains. For some addresses, it is possible that no one has the secret key, in which case the account is a black hole and the XRP is lost forever.
The typical way to get an account in the XRP Ledger is as follows:
1. Generate a key pair from a strong source of randomness and calculate the address of that key pair. (For example, you can use the `wallet_propose` method to do this.)
2. Have someone who already has an account in the XRP Ledger send XRP to the address you generated.
2. Have someone who already has an account in the XRP Ledger send XRP to the address you generate. For example, you can buy XRP in a private exchange, then withdraw XRP from the exchange to the address you specify.
**Caution:** Funding an account _does not_ give you any special privileges over that account. Whoever has the secret key corresponding to the account's address has full control over the account and all XRP it contains. For some addresses, it is possible that no one has the secret key, in which case the account is a black hole and the XRP is lost forever.
**Caution:** The first time you receive XRP at your own XRP Ledger address, you must pay the account reserve (currently 10 XRP), which locks up that amount of XRP indefinitely. In contrast, private exchanges usually hold all their customers' XRP in a few shared XRP Ledger accounts, so customers do not have to pay the reserve for individual accounts at the exchange. Before withdrawing, consider whether having your own account directly on the XRP Ledger is worth the price.
- For example, you can buy XRP in a private exchange, then withdraw XRP from the exchange to the address you specified.
**Caution:** The first time you receive XRP at your own XRP Ledger address, you must pay the account reserve (currently 10 XRP), which locks up that amount of XRP indefinitely. In contrast, private exchanges usually hold all their customers' XRP in a few shared XRP Ledger accounts, so customers do not have to pay the reserve for individual accounts at the exchange. Before withdrawing, consider whether having your own account directly on the XRP Ledger is worth the price.

2
content/concepts/accounts/cryptographic-keys.md
View File

@@ -9,7 +9,7 @@ labels:
In the XRP Ledger, a digital signature _authorizes_ a [transaction](../transactions/transactions.md) to do a specific set of actions. Only signed transactions can be submitted to the network and included in a validated ledger.
To make a digital signature, you use a cryptographic key pair associated with the transaction's sending account. A key pair may be generated using any of the XRP Ledger's supported cryptographic signing algorithms signing-algorithms. A key pair can be used as a master key pair, regular key pair, or a member of a signer list, regardless of what algorithm was used to generate it.
To make a digital signature, you use a cryptographic key pair associated with the transaction's sending account. A key pair can be generated using any of the XRP Ledger's supported cryptographic signing algorithms signing-algorithms. A key pair can be used as a master key pair, regular key pair, or a member of a signer list, regardless of what algorithm was used to generate it.
**Warning:** It is important to maintain proper security over your cryptographic keys. Digital signatures are the only way of authorizing transactions in the XRP Ledger, and there is no privileged administrator who can undo or reverse any transactions after they have applied. If someone else knows the seed or private key of your XRP Ledger account, that person can create digital signatures to authorize any transaction the same as you could.

50
content/concepts/tokens/tokens.md
View File

@@ -7,56 +7,26 @@ labels:
---
# Tokens
All assets other than XRP can be represented in the XRP Ledger as **tokens**. Standard tokens are tracked in relationships called [trust lines](trust-lines-and-issuing.html) between accounts. Tokens can represent any type of value, including "stablecoins" backed by assets that exist outside of the ledger, purely digital tokens created specifically on the XRP Ledger, community credit, and more.
All assets other than XRP can be represented in the XRP Ledger as **tokens**. Tokens can represent any type of value, including _stablecoins_ backed by assets that exist outside of the ledger, purely digital tokens created specifically on the XRP Ledger, community credit, and more.
**Note:** Tokens on the XRP Ledger have also been called "IOUs" (as in [I-owe-you](https://en.wikipedia.org/wiki/IOU)) and "issued currencies" in the past. However, these terms are not preferred because they do not cover the full range of digital assets that XRP Ledger tokens can represent.
Any account can issue tokens to other recipients who are willing to hold them, but you cannot unilaterally give tokens away to users who do not want them.
Any account can issue tokens to other recipients who are willing to hold them, but cannot unilaterally transfer tokens to users who do not want them.
Standard tokens are fungible: meaning, all units of that token are interchangeable and indistinguishable. Non-fungible tokens are also possible: see [Non-Fungible Tokens](non-fungible-tokens.html) for details of the XRP Ledger's native support.
Standard tokens are tracked in relationships called [trust lines](trust-lines-and-issuing.html) between accounts.
Tokens can be used for [cross-currency payments](cross-currency-payments.html) and can be traded in the [decentralized exchange](decentralized-exchange.html).
Tokens can used for [cross-currency payments](cross-currency-payments.html) and can be traded in the <!-- * -->decentralized exchange.
The balance on a trust line is negative or positive, depending on which side you view it from. The side with the negative balance is called the "issuer" and can control some properties of how those tokens behave. When you send tokens to another account that is not the issuer, those tokens "ripple" through the issuer and possibly other accounts using the same currency code. This is useful in some cases, but can cause unexpected and undesirable behavior in others. You can use the [No Ripple flag](rippling.html#the-no-ripple-flag) on trust lines to prevent those trust lines from rippling.
<!-- * [decentralized exchange](../server/decentralized-exchange.md) -->
**Note:** Tokens on the XRP Ledger have also been called "IOUs" (as in [I-owe-you](https://en.wikipedia.org/wiki/IOU)) and "issued currencies" in the past. However, these terms are not preferred because they do not cover the full range of digital assets that XRP Ledger tokens can represent.
The balance on a trust line is negative or positive depending on which side you view it from. The side with the negative balance is called the "issuer" and can control some properties of how those tokens behave. When you send tokens to another account that isn't the issuer, those tokens "ripple" through the issuer and possibly other accounts using the same currency code. This is useful in some cases, but can cause unexpected and undesirable behavior in others. You can use the [No Ripple flag](rippling.html#the-no-ripple-flag) on trust lines to prevent those trust lines from rippling.
## Token Structure
## Token Properties
Tokens in the XRP Ledger are <!--*-->fundamentally different than XRP. Tokens always exist _in trust lines_, and all transfers of tokens move along trust lines. You cannot cause someone else's account to hold more of a token than the _limit_ configured on their trust line. (You _can_ cause your own trust line to go over the limit, for example by buying more of it in the <!--  -->decentralized exchange or by decreasing the limit after you already have a positive balance.)
<!-- * [fundamentally different than XRP](currency-formats.md#comparison) -->
<!--  [decentralized exchange](../servers/decentralized-exchange.md) -->
Tokens in the XRP Ledger are fundamentally different than XRP. Tokens always exist _in trust lines_, and all transfers of tokens move along trust lines. You cannot cause someone else's account to hold more of a token than the _limit_ configured on their trust line. (You _can_ cause your own trust line to go over the limit, for example by buying more of it in the [decentralized exchange](../servers/decentralized-exchange.md) or by decreasing the limit after you already have a positive balance.)
Tokens use decimal (base-10) math with 15 digits of precision and an exponent that allows them to express very large values (up to 9999999999999999 × 10<sup>80</sup>) and very small values (down to 1.0 × 10<sup>-81</sup>).
Anyone can issue tokens by sending a `Payment` transaction if the necessary trust lines are in place. You can "burn" tokens by sending them back to the issuer. In some cases, [cross-currency payments](cross-currency-payments.html) or trades can also create more tokens according to an issuer's settings.
Issuers can charge a [transfer fee](transfer-fees.html) that is automatically deducted when users transfer their tokens. Issuers can also define a <!-- * -->tick size for exchanges rates involving their tokens. Both issuers and regular accounts can [freeze](freezing-tokens.html) trust lines, which limits how the tokens in those trust lines can be used. (None of these things applies to XRP.)
<!-- * [tick size](ticksize.md) -->
<!--
For a tutorial of the technical steps involved in issuing a token, see [Issue a Fungible Token](issue-a-fungible-token.html).
## See Also
- **Concepts:**
- [XRP](xrp.html)
- [Cross-Currency Payments](cross-currency-payments.html)
- [Decentralized Exchange](decentralized-exchange.html)
- **Tutorials:**
- [Issue a Fungible Token](issue-a-fungible-token.html)
- [Become an XRP Ledger Gateway](become-an-xrp-ledger-gateway.html)
- [Look Up Transaction Results](look-up-transaction-results.html)
- [Use Specialized Payment Types](use-specialized-payment-types.html)
- **References:**
- [Payment transaction][]
- [TrustSet transaction][]
- [RippleState object](ripplestate.html)
- [account_lines method][]
- [account_currencies method][]
- [gateway_balances method][]
-->
Issuers can charge a [transfer fee](transfer-fees.html) that is automatically deducted when users transfer their tokens. Issuers can also define a tick size for exchanges rates involving their tokens. Both issuers and regular accounts can [freeze](freezing-tokens.html) trust lines, which limits how the tokens in those trust lines can be used. (None of these things applies to XRP.)

8
content/concepts/transactions/canceling-a-transaction.md
View File

@@ -7,17 +7,17 @@ labels:
---
# Canceling a Transaction
An important and intentional feature of the XRP Ledger is that a [transaction](transactions.md)'s outcome is [final](finality-of-results.md) as soon as it has been incorporated in a [ledger version](../xrpl/ledgers.md) that is validated by the [consensus process](../xrpl/consensus.md).
An important and intentional feature of the XRP Ledger is that a [transaction](transactions.html)'s outcome is [final](finality-of-results.html) as soon as it has been incorporated in a [ledger version](ledgers.html) that is validated by the [consensus process](consensus.html).
If a transaction has _not_ yet been included in a validated ledger, it might be possible to effectively cancel it by sending another transaction from the same sending address with the same `Sequence` value. If you do not want the replacement transaction to do anything, send an `AccountSet` transaction with no options.
**Caution:** There is no guaranteed way to cancel a valid transaction after it has been distributed to the network. The process described here might or might not work, depending on factors including how busy the network is, the network topology, and the [transaction cost](transaction-cost.md) of the proposed transaction.
**Caution:** There is no guaranteed way to cancel a valid transaction after it has been distributed to the network. The process described here might or might not work, depending on factors including how busy the network is, the network topology, and the [transaction cost](transaction-cost.html) of the proposed transaction.
<!-- Too many links here. -->
If the transaction has already been distributed to the network and proposed as a [candidate transaction](../xrpl/consensus.md#consensus-1) in servers' consensus proposals, it might be too late to cancel. It is more likely that you can successfully cancel a transaction that is [queued](../server/transaction-queue.md) or is stuck "in limbo" because its [transaction cost](transaction-cost.md) is not high enough to meet the network's current requirements. In this case, the replacement transaction can either do nothing, or do the same thing as the transaction to be canceled. The replacement transaction is more likely to succeed if its transaction cost is higher.
If the transaction has already been distributed to the network and proposed as a [candidate transaction](consensus.html#consensus-1) in servers' consensus proposals, it might be too late to cancel. It is more likely that you can successfully cancel a transaction that is [queued](transaction-queue.html) or is stuck "in limbo" because its [transaction cost](transaction-cost.html) is not high enough to meet the network's current requirements. In this case, the replacement transaction can either do nothing, or do the same thing as the transaction to be canceled. The replacement transaction is more likely to succeed if its transaction cost is higher.
For example, if you try to submit 3 transactions with sequence numbers 11, 12, and 13, but transaction 11 gets lost somehow or does not have a high enough [transaction cost](transaction-cost.md) to be propagated to the network, then you can cancel transaction 11 by submitting an AccountSet transaction with no options and sequence number 11. This does nothing (except destroying the transaction cost for the new transaction 11), but it allows transactions 12 and 13 to become valid.
For example, if you try to submit 3 transactions with sequence numbers 11, 12, and 13, but transaction 11 gets lost somehow or does not have a high enough [transaction cost](transaction-cost.html) to be propagated to the network, then you can cancel transaction 11 by submitting an AccountSet transaction with no options and sequence number 11. This does nothing (except destroying the transaction cost for the new transaction 11), but it allows transactions 12 and 13 to become valid.
This approach is preferable to renumbering and resubmitting transactions 12 and 13, because it prevents transactions from being effectively duplicated under different sequence numbers.

17
content/concepts/transactions/finality-of-results.md
View File

@@ -33,11 +33,9 @@ When you initially submit a transaction, the `rippled` server tentatively applie
- If an address sends two different transactions using the same sequence number, at most one of those transactions can become validated. If those transactions are relayed through the network in different paths, a tentatively-successful transaction that some servers saw first might end up failing because the other, conflicting transaction reached a majority of servers first.
- To protect the network from spam, all transactions must destroy a [transaction cost](transaction-cost.md) in XRP to be relayed throughout the XRP Ledger peer-to-peer network. If heavy load on the peer-to-peer network causes the transaction cost to increase, a transaction that tentatively succeeded might not get relayed to enough servers to achieve a consensus, or might be [queued](transaction-queue.html) for later.
- To protect the network from spam, all transactions must destroy a [transaction cost](transaction-cost.html) in XRP to be relayed throughout the XRP Ledger peer-to-peer network. If heavy load on the peer-to-peer network causes the transaction cost to increase, a transaction that tentatively succeeded might not get relayed to enough servers to achieve a consensus, or might be [queued](transaction-queue.html) for later.
- Temporary internet outages or delays might prevent a proposed transaction from being successfully relayed before the transaction's intended expiration, as set by the `LastLedgerSequence` field. (If the transaction does not have an expiration, then it remains valid and could succeed any amount of time later, which can be undesirable in its own way.
<!-- See [Reliable Transaction Submission](reliable-transaction-submission.html) for details.) -->
- Combinations of two or more of these factors can also occur.
@@ -45,21 +43,8 @@ When you initially submit a transaction, the `rippled` server tentatively applie
- If two transactions would each fully consume the same <!-- * -->offer] in the decentralized exchange, whichever one comes first succeeds, and the other fails. Since the order in which those transactions apply might change, the one that succeeded can fail and the one that failed can succeed. Since offers can be partially executed, they could also still succeed, but to a greater or lesser extent.
<!-- * [Offer](offers.html) -->
<!--  [decentralized exchange](decentralized-exchange.html) -->
- If a [cross-currency payment](./payments/cross-currency-payments.md) succeeds by consuming an <!-- * -- >Offer in the <!-- * -->decentralized exchange, but a different transaction consumes or creates offers in the same order book, the cross-currency payment might succeed with a different exchange rate than it had when it executed tentatively. If it was a [partial payment](./payments/partial-payments.md), it could also deliver a different amount.
- A `Payment` transaction that tentatively failed because the sender did not have enough funds might later succeed because another transaction delivering the necessary funds came first in the canonical order. The reverse is also possible: a transaction that tentatively succeeded might fail because a transaction delivering the necessary funds did not come first after being put into canonical order.
**Tip:** For this reason, when running tests against the XRP Ledger, be sure to wait for a ledger close in between transactions if you have several accounts affecting the same data. If you are testing against a server in stand-alone mode, you must manually close the ledger in such cases.
<!-- [manually close the ledger](advance-the-ledger-in-stand-alone-mode.html) -->
<!--
## See Also
- [Look up Transaction Results](look-up-transaction-results.html)
- [Transaction Results Reference](transaction-results.html)
-->

18
content/concepts/transactions/multi-signing.md
View File

@@ -7,7 +7,7 @@ labels:
---
# Multi-Signing
Multi-signing in the XRP Ledger is a method of [authorizing transactions](transactions.md#authorizing-transactions) for the XRP Ledger by using a combination of multiple secret keys. You can have any combination of authorization methods enabled for your address, including multi-signing, a [master key pair](../accounts/cryptographic-keys.md#master-key-pair), and a [regular key pair](../accounts/cryptographic-keys.md#regular-key-pair). (The only requirement is that _at least one_ method must be enabled.)
Multi-signing in the XRP Ledger is a method of [authorizing transactions](transactions.html#authorizing-transactions) for the XRP Ledger by using a combination of multiple secret keys. You can have any combination of authorization methods enabled for your address, including multi-signing, a [master key pair](../accounts/cryptographic-keys.html#master-key-pair), and a [regular key pair](../accounts/cryptographic-keys.html#regular-key-pair). (The only requirement is that _at least one_ method must be enabled.)
Benefits of multi-signing include:
@@ -40,7 +40,7 @@ _(Added by the [ExpandedSignerList amendment][].)_
### Examples Using Signer Weight and Signer Quorum
The weight and quorum allow you to set an appropriate level of oversight for each transaction, based on the relative trust and authority relegated to responsible participants who manage the account.
The signer weight and signer quorum allow you to set an appropriate level of oversight for each transaction, based on the relative trust and authority relegated to responsible participants who manage the account.
For a typical use case, you might have a shared account with a quorum of 1, then give all participants a weight of 1. A single approval from any one of them is all that is required to approve a transaction.
@@ -48,7 +48,7 @@ For a very important account, you might set the quorum to 3, with 3 participants
Another account might also have a quorum of 3. You assign your CEO a weight of 3, 3 Vice Presidents a weight of 2 each, and 3 Directors a weight of 1 each. To approve a transaction for this account requires the approval of all 3 Directors (total weight of 3), 1 Vice President and 1 Director (total weight of 3), 2 Vice Presidents (total weight of 4), or the CEO (total weight of 3).
In each of the previous three use cases, you would disable the master key without configuring a regular key, so that multi-signing is the only way of [authorizing transactions](transactions.md#authorizing-transactions).
In each of the previous three use cases, you would disable the master key without configuring a regular key, so that multi-signing is the only way of [authorizing transactions](transactions.html#authorizing-transactions).
There might be a scenario where you create a multi-signing list as a "backup plan." The account owner normally uses a regular key for their transactions (not a multi-signing key). For safety, the owner adds a SignerList containing 3 friends, each with a weight of 1, and a quorum of 3. If the account owner were to lose the private key, they can ask their friends to multi-sign a transaction to replace the regular key.
@@ -57,18 +57,16 @@ There might be a scenario where you create a multi-signing list as a "backup pla
To successfully submit a multi-signed transaction, you must do all of the following:
* The address sending the transaction (specified in the `Account` field) must have a SignerList in the ledger.<!--
[SignerList in the ledger](signerlist.html)
* The address sending the transaction (specified in the `Account` field) must have a signer list in the ledger.
For instructions on how to do this, see [Set Up Multi-Signing](set-up-multi-signing.html).
-->* The transaction must include the `SigningPubKey` field as an empty string.
* The transaction must include a `Signers` field containing an array of signatures.<!--
](transaction-common-fields.html#signers-field)
-->* The signatures present in the `Signers` array must match signers defined in the SignerList.
* The transaction must include the `SigningPubKey` field as an empty string.
* The transaction must include a `Signers` field containing an array of signatures.
* The signatures present in the `Signers` array must match signers defined in the SignerList.
* For the provided signatures, the total weight associated with those signers must be equal or greater than the quorum for the SignerList.
* The [transaction cost](transaction-cost.md) (specified in the `Fee` field) must be at least (N+1) times the normal transaction cost, where N is the number of signatures provided.
* All fields of the transaction must be defined before collecting signatures. You cannot auto fill any fields.<!-- [auto-fill](transaction-common-fields.html#auto-fillable-fields) -->
* All fields of the transaction must be defined before collecting signatures. You cannot auto fill any fields.
* If presented in binary form, the `Signers` array must be sorted based on the numeric value of the signer addresses, with the lowest value first. (If submitted as JSON, the `submit_multisigned` method handles this automatically.)
<!--

17
content/concepts/transactions/source-and-destination-tags.md
View File

@@ -1,11 +1,9 @@
# Source and Destination Tags
_Source tags_ and _destination tags_ are a feature of XRP Ledger [payments](../payments/payment-types.md) that can indicate specific purposes for payments from and to multi-purpose addresses. Source and destination tags do not have direct on-ledger functionality; source and destination tags merely provide information about how off-ledger systems should process a payment. In transactions, both source and destination tags are formatted as 32-bit unsigned integers.
_Source tags_ and _destination tags_ are a feature of XRP Ledger [payments](../payments/payment-types.html) that can indicate specific purposes for payments from and to multi-purpose addresses. Source and destination tags do not have direct on-ledger functionality; source and destination tags merely provide information about how off-ledger systems should process a payment. In transactions, both source and destination tags are formatted as 32-bit unsigned integers.
Destination tags indicate the beneficiary or destination for a payment. For example, a payment to an exchange or gateway address can use a destination tag to indicate which customer to credit for the amount of the payment in that business's own systems. A payment to a merchant could indicate what item or cart the payment is buying.
<!-- [exchange](list-xrp-as-an-exchange.html) or [gateway](become-an-xrp-ledger-gateway.html) -->
Source tags indicate the originator or source of a payment. Most commonly, a Source Tag is included so that the recipient of the payment knows where to send a return, or "bounced", payment. When returning an incoming payment, you should use the source tag from the incoming payment as the destination tag of the outgoing (return) payment.
The practice of giving customers the ability to send and receive transactions from your XRP Ledger address using another interface is called providing _hosted accounts_. Hosted accounts typically use source and destination tags for each customer.
@@ -14,7 +12,7 @@ The practice of giving customers the ability to send and receive transactions fr
## Rationale
In other distributed ledgers, it is common to use different deposit addresses for each customer. In the XRP Ledger, an address must be a funded, permanent [account](../accounts/accounts.md) to receive payments. Using this approach in the XRP Ledger wastefully consumes resources of all servers in the network, and is costly because the [reserve](../accounts/reserves.md) amount must be set aside indefinitely for each address.
In other distributed ledgers, it is common to use different deposit addresses for each customer. In the XRP Ledger, an address must be a funded, permanent [account](accounts.html) to receive payments. Using this approach in the XRP Ledger wastefully consumes resources of all servers in the network, and is costly because the [reserve](reserves.html) amount must be set aside indefinitely for each address.
Source and destination tags provide a more lightweight way to map deposits and payments to individual customers.
@@ -31,17 +29,6 @@ To prevent overlap while protecting privacy, a business can divide the total ran
Assigning tags in numerical order provides less privacy to customers. Since all XRP Ledger transactions are public, assigning tags in this way can make it possible to guess which tags correspond to various users' addresses or to derive information about users' accounts based on the tags used.
## Requiring Tags
For an XRP Ledger address that may receive payments intended for several customer accounts, receiving a payment _without_ a destination tag can be a problem: it is not immediately obvious which customer to credit, which can require a manual intervention and a discussion with the sender to figure out who was the intended recipient. To reduce cases like this, you can enable the `RequireDest` setting. That way, if a user forgets to include a destination tag in a payment, the XRP Ledger rejects their payment instead of giving you money you don't know what to do with. The user can then send the payment again, using the tag as they should have.
<!--
[enable the `RequireDest` setting](require-destination-tags.html)
## See Also
- [Require Destination Tags](require-destination-tags.html)
- [XRP Ledger Businesses](xrp-ledger-businesses.html)
- [Payment Types](payment-types.html) -->

50
content/concepts/transactions/tickets.md
View File

@@ -9,64 +9,48 @@ labels:
_(Added by the TicketBatch amendment.)_
A Ticket in the XRP Ledger is a way of setting aside a sequence number for a transaction without sending it right away. Tickets allow transactions to be sent outside of the normal sequence order. One use case for this is to allow for [multi-signed transactions](multi-signing.md) where it may take a while to collect the necessary signatures: while collecting signatures for a transaction that uses a Ticket, you can still send other transactions.
A _ticket_ in the XRP Ledger is a way of setting aside a sequence number for a transaction without sending it right away. Tickets allow transactions to be sent outside of the normal sequence order. One use case for this is to allow for [multi-signed transactions](multi-signing.html) where it might take a while to collect the necessary signatures: while collecting signatures for a transaction that uses a ticket, you can still send other transactions.
## Background
[Transactions](transactions.md) have sequence numbers so that any given transaction can execute no more than once. Sequence numbers also make sure any given transaction is unique: if you send the exact same amount of money to the same person multiple times, the Sequence Number is one detail that is guaranteed to be different each time. Finally, Sequence Numbers provide an elegant way to put transactions in a consistent order, even if some of them arrive out of order when sent throughout the network.
[Transactions](transactions.html) have sequence numbers so that any given transaction can execute no more than once. Sequence numbers also make sure any given transaction is unique: if you send the exact same amount of money to the same person multiple times, the Sequence Number is one detail that is guaranteed to be different each time. Finally, Sequence Numbers provide an elegant way to put transactions in a consistent order, even if some of them arrive out of order when sent throughout the network.
However, there are some situations where sequence numbers are too limiting. For example:
- Two or more users share access to an account, each with the ability to send transactions independently. If these users try to send transactions around the same time without coordinating first, they may each try to use the same Sequence number for different transactions, and only one can succeed.
- You may want to prepare and sign a transaction in advance, then save it in some secure storage so that it can be executed at any future point if certain events occur. However, if you want to continue using your account as normal in the meantime, you don't know what Sequence number the set-aside transaction will need. <!-- STYLE_OVERRIDE: will -->
- When [multiple people must sign a transaction](multi-signing.md) to make it valid, it can be difficult to plan more than one transaction at a time. If you number the transactions with separate sequence numbers, you can't send the later-numbered transactions until everyone has signed the previous transactions; but if you use the same sequence number for each pending transactions, only one of them can succeed.
- When [multiple people must sign a transaction](multi-signing.html) to make it valid, it can be difficult to plan more than one transaction at a time. If you number the transactions with separate sequence numbers, you can't send the later-numbered transactions until everyone has signed the previous transactions; but if you use the same sequence number for each pending transactions, only one of them can succeed.
Tickets provide a solution to all of these problems by setting aside sequence numbers that can be used later, outside of their usual order, but still no more than once each.
## Tickets Are Reserved Sequence Numbers
A Ticket is a record that a sequence number has been set aside to be used later. An account first sends a `TicketCreate` transaction to set aside one or more sequence numbers as Tickets; this puts a record in the ledger's state data, in the form of a `Ticket object`, for each sequence number reserved.
A ticket is a record that a sequence number has been set aside to be used later. An account first sends a `TicketCreate` transaction to set aside one or more sequence numbers as tickets; this puts a record in the ledger's state data, in the form of a `Ticket` object, for each sequence number reserved.
Tickets are numbered using the sequence numbers that were set aside to create them. For example, if your account's current sequence number is 101 and you create 3 Tickets, those Tickets have Ticket Sequence numbers 102, 103, and 104. Doing so increases your account's sequence number to 105.
Tickets are numbered using the sequence numbers that were set aside to create them. For example, if your account's current sequence number is 101 and you create 3 tickets, those tickets have ticket sequence numbers 102, 103, and 104. Doing so increases your account's sequence number to 105.
{{ include_svg("img/ticket-creation.svg", "Diagram: Creating three Tickets") }}
Later, you can send a transaction using a specific Ticket instead of a sequence number; doing so removes the corresponding Ticket from the ledger's state data and does not change your account's normal sequence number. You can also still send transactions using normal sequence numbers without using Tickets. You can use any of your available Tickets in any order at any time, but each Ticket can only be used once.
Later, you can send a transaction using a specific ticket instead of a sequence number; doing so removes the corresponding ticket from the ledger's state data and does not change your account's normal sequence number. You can also still send transactions using normal sequence numbers without using tickets. You can use any of your available tickets in any order at any time, but each ticket can only be used once.
{{ include_svg("img/ticket-usage.svg", "Diagram: Using Ticket 103.") }}
Continuing the above example, you can send a transaction using sequence number 105 or any of the three Tickets you created. If you send a transaction using Ticket 103, doing so deletes Ticket 103 from the ledger. Your next transaction after that can use sequence number 105, Ticket 102, or Ticket 104.
Continuing the above example, you can send a transaction using sequence number 105 or any of the three tickets you created. If you send a transaction using ticket 103, doing so deletes ticket 103 from the ledger. Your next transaction after that can use sequence number 105, ticket 102, or ticket 104.
**Caution:** Each Ticket counts as a separate item for the [owner reserve](../accounts/reserves.md), so you must set aside 2 XRP for each Ticket. (The XRP becomes available again after you use the Ticket.) This cost can add up quickly if you create a large number of Tickets at once.
**Caution:** Each ticket counts as a separate item for the [owner reserve](reserves.html), so you must set aside 2 XRP for each ticket. (The XRP becomes available again after you use the ticket.) This cost can add up quickly if you create a large number of tickets at once.
As with sequence numbers, sending a transaction uses up the Ticket _if and only if_ the transaction is confirmed by [consensus](../xrpl/consensus.md). However, transactions that fail to do what they were intended to do can still be confirmed by consensus with [`tec`-class result codes](./transaction-results/tec-codes.md).
As with sequence numbers, sending a transaction uses up the ticket _if and only if_ the transaction is confirmed by [consensus](consensus.html). However, transactions that fail to do what they were intended to do can still be confirmed by consensus with [`tec`-class result codes](tec-codes.html).
To look up what Tickets an account has available, use the `account_objects` method.
To look up what tickets an account has available, use the `account_objects` method.
## Limitations
Any account can create and use Tickets on any type of transaction. However, some restrictions apply:
Any account can create and use tickets on any type of transaction. However, some restrictions apply:
- Each Ticket can only be used once. It is possible to have multiple different candidate transactions that would use the same Ticket Sequence, but only one of those candidates can be validated by consensus.
- Each account cannot have more than 250 Tickets in the ledger at a time. You cannot create more than 250 Tickets at a time, either.
- You _can_ use a Ticket to create more Tickets. If you do, the Ticket you used does not count towards the total number of Tickets you can have at once.
- Each Ticket counts toward the [owner reserve](../accounts/reserves.md), so you must set aside 2 XRP for each Ticket you have not used yet. The XRP becomes available for you to use again after the Ticket is used.
- Within an individual ledger, transactions that use Tickets execute after other transactions from the same sender. If an account has multiple transactions using Tickets in the same ledger version, those Tickets execute in order from lowest Ticket Sequence to highest. (For more information, see the documentation on consensus's [canonical order](consensus.html#calculate-and-share-validations).)
- To "cancel" a Ticket, use the Ticket to [perform a no-op](about-canceling-a-transaction.md) `AccountSet transaction`. This deletes the Ticket so that you don't have to meet its reserve requirement.
<!--
## See Also
- **Concepts:**
- [Multi-Signing](multi-signing.html)
- **Tutorials:**
- [Use Tickets](use-tickets.html)
- **References:**
- [TicketCreate transaction][]
- [Transaction Common Fields](transaction-common-fields.html)
- [Ticket object](ticket.html)
- [account_objects method][] -->
- Each ticket can only be used once. It is possible to have multiple different candidate transactions that would use the same ticket sequence, but only one of those candidates can be validated by consensus.
- Each account cannot have more than 250 tickets in the ledger at a time. You cannot create more than 250 tickets at a time, either.
- You _can_ use a ticket to create more tickets. If you do, the ticket you used does not count towards the total number of tickets you can have at once.
- Each ticket counts toward the [owner reserve](reserves.html), so you must set aside 2 XRP for each ticket you have not used yet. The XRP becomes available for you to use again after the ticket is used.
- Within an individual ledger, transactions that use tickets execute after other transactions from the same sender. If an account has multiple transactions using tickets in the same ledger version, those tickets execute in order from lowest ticket Sequence to highest. (For more information, see the documentation on consensus's [canonical order](consensus.html#calculate-and-share-validations).)
- To "cancel" a ticket, use the ticket to [perform a no-op](about-canceling-a-transaction.html) `AccountSet transaction`. This deletes the ticket so that you don't have to meet its reserve requirement.

48
content/concepts/transactions/transaction-cost.md
View File

@@ -7,7 +7,7 @@ labels:
---
# Transaction Cost
To protect the XRP Ledger from being disrupted by spam and denial-of-service attacks, each transaction must destroy a small amount of [XRP](../../../introduction/what-is-xrp.md). This _transaction cost_ is designed to increase along with the load on the network, making it very expensive to deliberately or inadvertently overload the network.
To protect the XRP Ledger from being disrupted by spam and denial-of-service attacks, each transaction must destroy a small amount of [XRP](what-is-xrp.html). This _transaction cost_ is designed to increase along with the load on the network, making it very expensive to deliberately or inadvertently overload the network.
Every transaction must [specify how much XRP to destroy](#specifying-the-transaction-cost) to pay the transaction cost.
@@ -30,8 +30,6 @@ Some transactions have different transaction costs:
| EscrowFinish Transaction with Fulfillment | 10 drops × (33 + (Fulfillment size in bytes ÷ 16)) |
| [AccountDelete Transaction](accounts.html#deletion-of-accounts) | 2,000,000 drops |
<!-- [EscrowFinish Transaction with Fulfillment](escrowfinish.html) -->
## Beneficiaries of the Transaction Cost
The transaction cost is not paid to any party: the XRP is irrevocably destroyed.
@@ -54,8 +52,6 @@ This divides transactions into roughly three categories:
Each `rippled` server maintains a cost threshold based on its current load. If you submit a transaction with a `Fee` value that is lower than current load-based transaction cost of the `rippled` server, that server neither applies nor relays the transaction. (**Note:** If you submit a transaction through an admin connection, the server applies and relays the transaction as long as the transaction meets the un-scaled minimum transaction cost.) A transaction is very unlikely to survive [the consensus process](../xrpl/consensus.md) unless its `Fee` value meets the requirements of a majority of servers.
<!-- [admin connection](get-started-using-http-websocket-apis.html) -->
## Open Ledger Cost
@@ -63,7 +59,7 @@ The `rippled` server has a second mechanism for enforcing the transaction cost,
For each new ledger version, the server picks a soft limit on the number of transactions to be included in the open ledger, based on the number of transactions in the previous ledger. The open ledger cost is equal to the minimum un-scaled transaction cost until the number of transactions in the open ledger is equal to the soft limit. After that, the open ledger cost increases exponentially for each transaction included in the open ledger. For the next ledger, the server increases the soft limit if the current ledger contained more transactions than the soft limit, and decreases the soft limit if the consensus process takes more than 5 seconds.
The open ledger cost requirement is [proportional to the normal cost of the transaction](#fee-levels), not the absolute transaction cost. Transaction types that have a higher-than-normal requirement, such as [multi-signed transactions](multi-signing.md) must pay more to meet the open ledger cost than transactions which have minimum transaction cost requirements.
The open ledger cost requirement is [proportional to the normal cost of the transaction](#fee-levels), not the absolute transaction cost. Transaction types that have a higher-than-normal requirement, such as [multi-signed transactions](multi-signing.html) must pay more to meet the open ledger cost than transactions which have minimum transaction cost requirements.
See also: [Fee Escalation explanation in `rippled` repository](https://github.com/ripple/rippled/blob/release/src/ripple/app/misc/FeeEscalation.md).
@@ -71,11 +67,11 @@ See also: [Fee Escalation explanation in `rippled` repository](https://github.co
When `rippled` receives a transaction that meets the server's local load cost but not the [open ledger cost](#open-ledger-cost), the server estimates whether the transaction is "likely to be included" in a later ledger. If so, the server adds the transaction to the transaction queue and relays the transaction to other members of the network. Otherwise, the server discards the transaction. The server tries to minimize the amount of network load caused by transactions that would not pay a transaction cost, since [the transaction cost only applies when a transaction is included in a validated ledger](#transaction-costs-and-failed-transactions).
For more information on queued transactions, see [Transaction Queue](../server/transaction-queue.md).
For more information on queued transactions, see [Transaction Queue](../server/transaction-queue.html).
## Reference Transaction Cost
The "Reference Transaction" is the cheapest (non-free) transaction, in terms of the necessary [transaction cost](transaction-cost.md) before load scaling. Most transactions have the same cost as the reference transaction. Some transactions, such as [multi-signed transactions](multi-signing.md), require a multiple of this cost instead. When the open ledger cost escalates, the requirement is proportional to the basic cost of the transaction.
The "Reference Transaction" is the cheapest (non-free) transaction, in terms of the necessary [transaction cost](transaction-cost.html) before load scaling. Most transactions have the same cost as the reference transaction. Some transactions, such as [multi-signed transactions](multi-signing.html), require a multiple of this cost instead. When the open ledger cost escalates, the requirement is proportional to the basic cost of the transaction.
### Fee Levels
@@ -84,8 +80,8 @@ _Fee levels_ represent the proportional difference between the minimum cost and
| Transaction | Minimum cost in drops | Minimum cost in Fee levels | Double cost in drops | Double cost in fee levels |
|-------------|-----------------------|----------------------------|----------------------|---------------------------|
| Reference transaction (most transactions) | 10 | 256 | 20 | 512 |
| [Multi-signed transaction](multi-signing.md) with 4 signatures | 50 | 256 | 100 | 512 |
| [Key reset transaction](transaction-cost.md#key-reset-transaction) | 0 | (Effectively infinite) | N/A | (Effectively infinite) |
| [Multi-signed transaction](multi-signing.html) with 4 signatures | 50 | 256 | 100 | 512 |
| [Key reset transaction](transaction-cost.html#key-reset-transaction) | 0 | (Effectively infinite) | N/A | (Effectively infinite) |
| EscrowFinish transaction with 32-byte preimage. | 350 | 256 | 700 | 512 |
<!-- [EscrowFinish transaction](escrowfinish.html) -->
@@ -109,11 +105,9 @@ The `server_state` method returns a direct representation of `rippled`'s interna
**Current Transaction Cost in Drops = (`base_fee` × `load_factor`) ÷ `load_base`**
<!-- [drops of XRP](basic-data-types.md#specifying-currency-amounts) -->
## Specifying the Transaction Cost
Every signed transaction must include the transaction cost in the [`Fee` field](transaction-common-fields.md). Like all fields of a signed transaction, this field cannot be changed without invalidating the signature.
Every signed transaction must include the transaction cost in the [`Fee` field](transaction-common-fields.html). Like all fields of a signed transaction, this field cannot be changed without invalidating the signature.
As a rule, the XRP Ledger executes transactions _exactly_ as they are signed. (To do anything else would be difficult to coordinate across a decentralized consensus network, at the least.) As a consequence of this, every transaction destroys the exact amount of XRP specified by the `Fee` field, even if the specified amount is much more than the current minimum transaction cost for any part of the network. The transaction cost can even destroy XRP that would otherwise be set aside for an account's [reserve requirement](reserves.html).
@@ -122,10 +116,10 @@ Before signing a transaction, we recommend [looking up the current load-based tr
### Automatically Specifying the Transaction Cost
The `Fee` field is one of the things that can be [auto-filled](transaction-common-fields.md#auto-fillable-fields) when creating a transaction. In this case, the auto-filling software provides a suitable `Fee` value based on the current load in the peer-to-peer network. However, there are several drawbacks and limitations to automatically filling in the transaction cost in this manner:
The `Fee` field is one of the things that can be [auto-filled](transaction-common-fields.html#auto-fillable-fields) when creating a transaction. In this case, the auto-filling software provides a suitable `Fee` value based on the current load in the peer-to-peer network. However, there are several drawbacks and limitations to automatically filling in the transaction cost in this manner:
- If the network's transaction cost goes up between auto-filling and submitting the transaction, the transaction may not be confirmed.
- To prevent a transaction from getting stuck in a state of being neither definitively confirmed or rejected, be sure to provide a `LastLedgerSequence` parameter so it eventually expires. Alternatively, you can try to [cancel a stuck transaction](about-canceling-a-transaction.md) by reusing the same `Sequence` number.
- To prevent a transaction from getting stuck in a state of being neither definitively confirmed or rejected, be sure to provide a `LastLedgerSequence` parameter so it eventually expires. Alternatively, you can try to [cancel a stuck transaction](about-canceling-a-transaction.html) by reusing the same `Sequence` number.
<!-- See [reliable transaction submission](reliable-transaction-submission.html) for best practices. -->
@@ -137,15 +131,15 @@ The `Fee` field is one of the things that can be [auto-filled](transaction-commo
## Transaction Costs and Failed Transactions
Since the purpose of the transaction cost is to protect the XRP Ledger peer-to-peer network from excessive load, it should apply to any transaction that gets distributed to the network, regardless of whether or not that transaction succeeds. However, to affect the shared global ledger, a transaction must be included in a validated ledger. Thus, `rippled` servers try to include failed transactions in ledgers, with [`tec` status codes](./transaction-results/transaction-results.md) ("tec" stands for "Transaction Engine - Claimed fee only").
Since the purpose of the transaction cost is to protect the XRP Ledger peer-to-peer network from excessive load, it should apply to any transaction that gets distributed to the network, regardless of whether or not that transaction succeeds. However, to affect the shared global ledger, a transaction must be included in a validated ledger. Thus, `rippled` servers try to include failed transactions in ledgers, with [`tec` status codes](transaction-results.html) ("tec" stands for "Transaction Engine - Claimed fee only").
The transaction cost is only debited from the sender's XRP balance when the transaction actually becomes included in a validated ledger. This is true whether the transaction is considered successful or fails with a `tec` code.
If a transaction's failure is [final](finality-of-results.md), the `rippled` server does not relay it to the network. The transaction does not get included in a validated ledger, so it cannot have any effect on anyone's XRP balance.
If a transaction's failure is [final](finality-of-results.html), the `rippled` server does not relay it to the network. The transaction does not get included in a validated ledger, so it cannot have any effect on anyone's XRP balance.
### Insufficient XRP
When a `rippled` server initially evaluates a transaction, it rejects the transaction with the error code `terINSUF_FEE_B` if the sending account does not have a high enough XRP balance to pay the XRP transaction cost. Since this is a `ter` (Retry) code, the `rippled` server retries the transaction without relaying it to the network, until the transaction's outcome is [final](finality-of-results.md).
When a `rippled` server initially evaluates a transaction, it rejects the transaction with the error code `terINSUF_FEE_B` if the sending account does not have a high enough XRP balance to pay the XRP transaction cost. Since this is a `ter` (Retry) code, the `rippled` server retries the transaction without relaying it to the network, until the transaction's outcome is final.
When a transaction has already been distributed to the network, but the account does not have enough XRP to pay the transaction cost, the result code `tecINSUFF_FEE` occurs instead. In this case, the account pays all the XRP it can, ending with 0 XRP. This can occur because `rippled` decides whether to relay the transaction to the network based on its in-progress ledger, but transactions may be dropped or reordered when building the consensus ledger.
@@ -163,20 +157,4 @@ When the `FeeEscalation` amendment is enabled, `rippled` prioritizes key reset t
## Changing the Transaction Cost
The XRP Ledger has a mechanism for changing the minimum transaction cost to account for long-term changes in the value of XRP. Any changes have to be approved by the consensus process. See [Fee Voting](../xrpl/fee-voting.md) for more information.
<!--
## See Also
- **Concepts:**
- [Reserves](reserves.html)
- [Fee Voting](fee-voting.html)
- [Transaction Queue](transaction-queue.html)
- **Tutorials:**
- [Reliable Transaction Submission](reliable-transaction-submission.html)
- **References:**
- [fee method][]
- [server_info method][]
- [FeeSettings object](feesettings.html)
- [SetFee pseudo-transaction][]
-->
The XRP Ledger has a mechanism for changing the minimum transaction cost to account for long-term changes in the value of XRP. Any changes have to be approved by the consensus process. See [Fee Voting](fee-voting.html) for more information.

28
content/concepts/transactions/transaction-malleability.md
View File

@@ -21,8 +21,8 @@ Before 2014, single-signed transactions could be malleable due to properties of
In the XRP Ledger, a transaction cannot execute unless:
- All [fields of a transaction](transaction-common-fields.md) are signed, except the signature itself.
- The key pair(s) used to sign the transaction are [authorized to send transactions on behalf of that account](transaction-basics.md#authorizing-transactions).
- All [fields of a transaction](transaction-common-fields.html) are signed, except the signature itself.
- The key pair(s) used to sign the transaction are [authorized to send transactions on behalf of that account](transaction-basics.html#authorizing-transactions).
- The signature is _canonical_ and matches the transaction instructions.
Any change to the signed fields, no matter how small, would invalidate the signature, so no part of the transaction can be malleable except for the signature itself. In most cases, any change to a signature itself also invalidates the signature, but there are some specific exceptions, described below.
@@ -41,11 +41,11 @@ Generally speaking, any standard ECDSA implementation handles these requirements
An ECDSA signature consists of two integers, called R and S. The secp256k1 _group order_, called N, is a constant value for all secp256k1 signatures. Specifically, N is the value `0xFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFEBAAEDCE6AF48A03BBFD25E8CD0364141`. For any given signature `(R,S)`, the signature `(R, N-S)` (that is, using N minus S in place of S) is also valid.
Thus, to have _fully_ canonical signatures, one must choose which of the two possibilities is preferred and declare the other to be invalid. The creators of the XRP Ledger decided arbitrarily to prefer the _smaller_ of the two possible values, `S` or `N-S`. A transaction is considered _fully canonical_ if it uses the preferred (smaller) value of `S`, and follows all the normal rules for being canonical. To calculate a fully-canonical ECDSA signature, one must compare S and N-S to determine which is smaller, then use that value in the `Signature` field of the transaction.
To have _fully_ canonical signatures, you must choose which of the two possibilities is preferred and declare the other to be invalid. The creators of the XRP Ledger decided arbitrarily to prefer the _smaller_ of the two possible values, `S` or `N-S`. A transaction is considered _fully canonical_ if it uses the preferred (smaller) value of `S`, and follows all the normal rules for being canonical. To calculate a fully-canonical ECDSA signature, one must compare S and N-S to determine which is smaller, then use that value in the `Signature` field of the transaction.
With the RequireFullyCanonicalSig amendment (enabled in 2020), all transactions must use _fully canonical_ signatures only.
Between 2014 and 2020, the XRP Ledger was compatible with legacy software that did not always generate fully canonical signatures, but used a flag on transactions called [**`tfFullyCanonicalSig`**](transaction-common-fields.md#global-flags) to protect compatible software from transaction malleability. This flag, which compatible signing software enables by default, required that the transaction use a _fully-canonical_ signature to be valid. Now that the RequireFullyCanonicalSig amendment is enabled, the flag is no longer necessary, but there is no harm in enabling it anyway.
Between 2014 and 2020, the XRP Ledger was compatible with legacy software that did not always generate fully canonical signatures, but used a flag on transactions called [**`tfFullyCanonicalSig`**](transaction-common-fields.html#global-flags) to protect compatible software from transaction malleability. This flag, which compatible signing software enables by default, required that the transaction use a _fully-canonical_ signature to be valid. Now that the RequireFullyCanonicalSig amendment is enabled, the flag is no longer necessary, but there is no harm in enabling it anyway.
### Malleability with Multi-Signatures
@@ -121,28 +121,10 @@ The process to exploit a vulnerable system follows a series of steps like the fo
If the transaction included the `LastLedgerSequence` field, this would occur after the specified ledger index has passed.
If the transaction omitted the `LastLedgerSequence` field, this could be wrong in another way: if no other transaction from the same sender uses the same `Sequence` number, then the transaction could theoretically succeed later regardless of how much time has passed.
<!-- (See [Reliable Transaction Submission](reliable-transaction-submission.html) for details.) -->
If the transaction omitted the `LastLedgerSequence` field, this could be wrong in another way: if no other transaction from the same sender uses the same `Sequence` number, then the transaction could theoretically succeed later regardless of how much time has passed.
8. The vulnerable system takes action assuming that the transaction has failed.
For example, it may refund (or not debit) a customer's balance in its own system, to account for the funds that it thinks have not been sent in the XRP Ledger.
Worse, the vulnerable system might construct a new transaction to replace the transaction, picking new `Sequence`, `LastLedgerSequence`, and `Fee` parameters based on the current state of the network, but keeping the rest of the transaction the same as the original. If this new transaction is also malleable, the system could be exploited in the same way an indefinite number of times.
<!--
## See Also
- **Concepts:**
- [Transaction Basics](transaction-basics.html)
- [Finality of Results](finality-of-results.html)
- **Tutorials:**
- [Look Up Transaction Results](look-up-transaction-results.html)
- [Reliable Transaction Submission](reliable-transaction-submission.html)
- **References:**
- [Basic Data Types - Hashes](basic-data-types.html#hashes)
- [Transaction Common Fields - Global Flags](transaction-common-fields.html#global-flags)
- [Transaction Results](transaction-results.html)
- [Serialization Format](serialization.html)
-->

1027
content/concepts/transactions/transaction-metadata-concept.md
View File

File diff suppressed because it is too large Load Diff

1049
content/concepts/transactions/transaction-results/tec-codes-concepts.md
View File

File diff suppressed because it is too large Load Diff

1017
content/concepts/transactions/transaction-results/tef-codes-concepts.md
View File

File diff suppressed because it is too large Load Diff

18
content/concepts/transactions/transaction-results/tel-codes-concepts.md
View File

@@ -9,7 +9,7 @@ labels:
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](../finality-of-results.md).
**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](finality-of-results.html).
<!-- and [Reliable Transaction Submission](reliable-transaction-submission.md). -->
@@ -18,16 +18,16 @@ These codes indicate an error in the local server processing the transaction; it
| `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](transaction-cost.html), but this server did not queue this transaction because it did not meet the [queuing restrictions](../../server/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](../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. New in: rippled 0.70.2 |
| `telCAN_NOT_QUEUE_BLOCKS` | The transaction did not meet the [open ledger cost](../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 by changing authorization methods. (This includes all `SetRegularKey` and `SignerListSet` transactions, as well as `AccountSet` transactions that change the `RequireAuth`/`OptionalAuth`, `DisableMaster`, or `AccountTxnID` flags.) You can try again later, or try submitting to a different server. New in: rippled 0.70.2 |
| `telCAN_NOT_QUEUE_BLOCKED` | The transaction did not meet the [open ledger cost](../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. (This includes all `SetRegularKey` and `SignerListSet` transactions, as well as `AccountSet` transactions that change the `RequireAuth`/`OptionalAuth`, `DisableMaster`, or `AccountTxnID` flags.) You can try again later, or try submitting to a different server. New in: rippled 0.70.2 |
| `telCAN_NOT_QUEUE_FEE` | The transaction did not meet the [open ledger cost](../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](../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. New in: rippled 0.70.2 |
| `telCAN_NOT_QUEUE_FULL` | The transaction did not meet the [open ledger cost](../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](../transaction-cost.md#fee-levels), than the transaction in the queue with the smallest transaction cost. New in: rippled 0.70.2 |
| `telCAN_NOT_QUEUE` | The transaction did not meet the [open ledger cost](transaction-cost.html), but this server did not queue this transaction because it did not meet the [queuing restrictions](transaction-queue.html#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](transaction-cost.html) 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. New in: rippled 0.70.2 |
| `telCAN_NOT_QUEUE_BLOCKS` | The transaction did not meet the [open ledger cost](transaction-cost.html) 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 by changing authorization methods. (This includes all `SetRegularKey` and `SignerListSet` transactions, as well as `AccountSet` transactions that change the `RequireAuth`/`OptionalAuth`, `DisableMaster`, or `AccountTxnID` flags.) You can try again later, or try submitting to a different server. New in: rippled 0.70.2 |
| `telCAN_NOT_QUEUE_BLOCKED` | The transaction did not meet the [open ledger cost](transaction-cost.html) and also was not added to the transaction queue because a transaction queued ahead of it from the same sender blocks it. (This includes all `SetRegularKey` and `SignerListSet` transactions, as well as `AccountSet` transactions that change the `RequireAuth`/`OptionalAuth`, `DisableMaster`, or `AccountTxnID` flags.) You can try again later, or try submitting to a different server. New in: rippled 0.70.2 |
| `telCAN_NOT_QUEUE_FEE` | The transaction did not meet the [open ledger cost](transaction-cost.html) 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](transaction-cost.html#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. New in: rippled 0.70.2 |
| `telCAN_NOT_QUEUE_FULL` | The transaction did not meet the [open ledger cost](transaction-cost.html) 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](transaction-cost.html#fee-levels), than the transaction in the queue with the smallest transaction cost. New in: rippled 0.70.2 |
| `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](../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. |
| `telINSUF_FEE_P` | The `Fee` from the transaction is not high enough to meet the server's current [transaction cost](transaction-cost.html) 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. |
| `telNO_DST`_`PARTIAL` | The transaction is an XRP payment that would fund a new account, but the [`tfPartialPayment` flag](../payments/partial-payments.md) was enabled. This is disallowed. |
| `telNO_DST`_`PARTIAL` | The transaction is an XRP payment that would fund a new account, but the [`tfPartialPayment` flag](partial-payments.html) was enabled. This is disallowed. |
<!---->
<!--

1029
content/concepts/transactions/transaction-results/tem-codes-concepts.md
View File

File diff suppressed because it is too large Load Diff

1013
content/concepts/transactions/transaction-results/ter-codes-concepts.md
View File

File diff suppressed because it is too large Load Diff

1022
content/concepts/transactions/transaction-results/transaction-results-concepts.md
View File

File diff suppressed because it is too large Load Diff

129
content/concepts/transactions/transaction-structure.md
View File

@@ -37,7 +37,128 @@ Every transaction has the same set of common fields, plus additional fields base
Removed in: rippled 0.28.0: 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](../../../../references/protocol-reference/ledger-data/ledger-data-formats.md).
### Example Unsigned Transaction
Here is an example of an unsigned `Payment` transaction in JSON:
```json
{
"TransactionType" : "Payment",
"Account" : "rf1BiGeXwwQoi8Z2ueFYTEXSwuJYfV2Jpn",
"Destination" : "ra5nK24KXen9AHvsdFTKHSANinZseWnPcX",
"Amount" : {
"currency" : "USD",
"value" : "1",
"issuer" : "rf1BiGeXwwQoi8Z2ueFYTEXSwuJYfV2Jpn"
},
"Fee": "12",
"Flags": 2147483648,
"Sequence": 2,
}
```
| Field Name | Description |
|-----------------|-------------|
| TransactionType | Send a Payment. |
| Account | The account sending the funds. |
| Destination | The account receiving the funds. |
| Amount | The amount and type of currency. |
| currency | Currency type to transfer. |
| value | Quantity of currency to transfer. |
| issuer | Account that originally issued the currency. |
| Fee | Transaction fee, in drops (millionths of one XRP). |
| Flags | Additional standard settings for the transaction. |
| Sequence | Unique sequence number for the transaction. |
Example response from the `tx` command:
```json
{
"id": 6,
"status": "success",
"type": "response",
"result": {
"Account": "rf1BiGeXwwQoi8Z2ueFYTEXSwuJYfV2Jpn",
"Amount": {
"currency": "USD",
"issuer": "rf1BiGeXwwQoi8Z2ueFYTEXSwuJYfV2Jpn",
"value": "1"
},
"Destination": "ra5nK24KXen9AHvsdFTKHSANinZseWnPcX",
"Fee": "10",
"Flags": 2147483648,
"Sequence": 2,
"SigningPubKey": "03AB40A0490F9B7ED8DF29D246BF2D6269820A0EE7742ACDD457BEA7C7D0931EDB",
"TransactionType": "Payment",
"TxnSignature": "3045022100D64A32A506B86E880480CCB846EFA3F9665C9B11FDCA35D7124F53C486CC1D0402206EC8663308D91C928D1FDA498C3A2F8DD105211B9D90F4ECFD75172BAE733340",
"date": 455224610,
"hash": "33EA42FC7A06F062A7B843AF4DC7C0AB00D6644DFDF4C5D354A87C035813D321",
"inLedger": 7013674,
"ledger_index": 7013674,
"meta": {
"AffectedNodes": [
{
"ModifiedNode": {
"FinalFields": {
"Account": "rf1BiGeXwwQoi8Z2ueFYTEXSwuJYfV2Jpn",
"Balance": "99999980",
"Flags": 0,
"OwnerCount": 0,
"Sequence": 3
},
"LedgerEntryType": "AccountRoot",
"LedgerIndex": "13F1A95D7AAB7108D5CE7EEAF504B2894B8C674E6D68499076441C4837282BF8",
"PreviousFields": {
"Balance": "99999990",
"Sequence": 2
},
"PreviousTxnID": "7BF105CFE4EFE78ADB63FE4E03A851440551FE189FD4B51CAAD9279C9F534F0E",
"PreviousTxnLgrSeq": 6979192
}
},
{
"ModifiedNode": {
"FinalFields": {
"Balance": {
"currency": "USD",
"issuer": "rrrrrrrrrrrrrrrrrrrrBZbvji",
"value": "2"
},
"Flags": 65536,
"HighLimit": {
"currency": "USD",
"issuer": "rf1BiGeXwwQoi8Z2ueFYTEXSwuJYfV2Jpn",
"value": "0"
},
"HighNode": "0000000000000000",
"LowLimit": {
"currency": "USD",
"issuer": "ra5nK24KXen9AHvsdFTKHSANinZseWnPcX",
"value": "100"
},
"LowNode": "0000000000000000"
},
"LedgerEntryType": "RippleState",
"LedgerIndex": "96D2F43BA7AE7193EC59E5E7DDB26A9D786AB1F7C580E030E7D2FF5233DA01E9",
"PreviousFields": {
"Balance": {
"currency": "USD",
"issuer": "rrrrrrrrrrrrrrrrrrrrBZbvji",
"value": "1"
}
},
"PreviousTxnID": "7BF105CFE4EFE78ADB63FE4E03A851440551FE189FD4B51CAAD9279C9F534F0E",
"PreviousTxnLgrSeq": 6979192
}
}
],
"TransactionIndex": 0,
"TransactionResult": "tesSUCCESS"
},
"validated": true
}
}
```
## 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]. -->
@@ -48,8 +169,6 @@ One situation in which this is useful is if you have a primary system for submit
The `AccountTxnID` field cannot be used on transactions that use [Tickets](tickets.html). Transactions that use `AccountTxnID` cannot be placed in the [transaction queue](../server/transaction-queue.html).
## 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](../../../references/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:
@@ -64,7 +183,6 @@ For a production system, we recommend _not_ leaving these fields to be filled by
The [`Paths` field](../../../../references/protocol-reference/transactions/transaction-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.
@@ -133,7 +251,6 @@ Example of a transaction with a Memos field:
}
```
## Signers Field
The `Signers` field contains a [multi-signature](multi-signing.html), which has signatures from up to 8 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:
@@ -144,8 +261,8 @@ The `Signers` field contains a [multi-signature](multi-signing.html), which has
| `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`](../../../../references/protocol-reference/ledger-data/ledger-object-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.
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`](/accountroot.html#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](transaction-cost.md) 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.
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](transaction-cost.html) 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.

142
content/concepts/transactions/transactions.md
View File

@@ -11,153 +11,25 @@ _Transactions_ allow accounts to modify the XRP Ledger.
Transactions can do more than transfer currency. In addition to supporting various payment types, transactions in the XRP Ledger can rotate cryptographic keys, manage other settings, and trade in the XRP Ledger's decentralized exchange.
## Transaction Structure
### Example Unsigned Transaction
Here is an example of an unsigned `Payment` transaction in JSON:
```json
{
"TransactionType" : "Payment",
"Account" : "rf1BiGeXwwQoi8Z2ueFYTEXSwuJYfV2Jpn",
"Destination" : "ra5nK24KXen9AHvsdFTKHSANinZseWnPcX",
"Amount" : {
"currency" : "USD",
"value" : "1",
"issuer" : "rf1BiGeXwwQoi8Z2ueFYTEXSwuJYfV2Jpn"
},
"Fee": "12",
"Flags": 2147483648,
"Sequence": 2,
}
```
| Field Name | Description |
|-----------------|-------------|
| TransactionType | Send a Payment. |
| Account | The account sending the funds. |
| Destination | The account receiving the funds. |
| Amount | The amount and type of currency. |
| currency | Currency type to transfer. |
| value | Quantity of currency to transfer. |
| issuer | Account that originally issued the currency. |
| Fee | Transaction fee, in drops (millionths of one XRP). |
| Flags | Additional standard settings for the transaction. |
| Sequence | Unique sequence number for the transaction. |
### Signing and Submitting Transactions
## Signing and Submitting Transactions
Sending a transaction to the XRP Ledger involves several steps:
1. Create an [unsigned transaction in JSON format](#example-unsigned-transaction).
1. Create an [unsigned transaction in JSON format](transaction-structure.html#example-unsigned-transaction).
2. Use one or more signatures to [authorize the transaction](#authorizing-transactions).
3. Submit a transaction to an XRP Ledger server (usually a [`rippled` instance](server-modes.html)). If the transaction is properly formed, the server provisionally applies the transaction to its current version of the ledger and relays the transaction to other members of the peer-to-peer network.
3. Submit a transaction to an XRP Ledger server.
4. The [consensus process](consensus.html) determines which provisional transactions get included in the next validated ledger.
5. The servers apply those transactions to the previous ledger in a canonical order and share their results.
6. If enough trusted validators created the exact same ledger, that ledger is declared _validated_ and the <!-- * --> results of the transactions in that ledger are immutable.
<!-- * [results of the transactions](transaction-results.html) -->
6. If enough trusted validators create the exact same ledger, the ledger is _validated_ and the results of the transactions in that ledger are immutable.
### Example Executed Transaction Response with Metadata
After a transaction has been executed, the XRP Ledger adds <!-- * --> metadata to show the transaction's final outcome and all the changes that the transaction made to the shared state of the XRP Ledger.
After a transaction is complete, the XRP Ledger adds metadata to show the transaction's final outcome and all the changes that the transaction made to the shared state of the XRP Ledger.
<!-- * [metadata](transaction-metadata.html) -->
You can check a transaction's status using the API (for example, using the `tx` command).
You can check a transaction's status using the API, for example using the `tx` command.
The results of a transaction, including all its metadata, are not final until the transaction appears in a validated ledger.
The results of a transaction, including all its metadata, are not final until the transaction appears in a **validated** ledger.
Example response from the `tx` command:
```json
{
"id": 6,
"status": "success",
"type": "response",
"result": {
"Account": "rf1BiGeXwwQoi8Z2ueFYTEXSwuJYfV2Jpn",
"Amount": {
"currency": "USD",
"issuer": "rf1BiGeXwwQoi8Z2ueFYTEXSwuJYfV2Jpn",
"value": "1"
},
"Destination": "ra5nK24KXen9AHvsdFTKHSANinZseWnPcX",
"Fee": "10",
"Flags": 2147483648,
"Sequence": 2,
"SigningPubKey": "03AB40A0490F9B7ED8DF29D246BF2D6269820A0EE7742ACDD457BEA7C7D0931EDB",
"TransactionType": "Payment",
"TxnSignature": "3045022100D64A32A506B86E880480CCB846EFA3F9665C9B11FDCA35D7124F53C486CC1D0402206EC8663308D91C928D1FDA498C3A2F8DD105211B9D90F4ECFD75172BAE733340",
"date": 455224610,
"hash": "33EA42FC7A06F062A7B843AF4DC7C0AB00D6644DFDF4C5D354A87C035813D321",
"inLedger": 7013674,
"ledger_index": 7013674,
"meta": {
"AffectedNodes": [
{
"ModifiedNode": {
"FinalFields": {
"Account": "rf1BiGeXwwQoi8Z2ueFYTEXSwuJYfV2Jpn",
"Balance": "99999980",
"Flags": 0,
"OwnerCount": 0,
"Sequence": 3
},
"LedgerEntryType": "AccountRoot",
"LedgerIndex": "13F1A95D7AAB7108D5CE7EEAF504B2894B8C674E6D68499076441C4837282BF8",
"PreviousFields": {
"Balance": "99999990",
"Sequence": 2
},
"PreviousTxnID": "7BF105CFE4EFE78ADB63FE4E03A851440551FE189FD4B51CAAD9279C9F534F0E",
"PreviousTxnLgrSeq": 6979192
}
},
{
"ModifiedNode": {
"FinalFields": {
"Balance": {
"currency": "USD",
"issuer": "rrrrrrrrrrrrrrrrrrrrBZbvji",
"value": "2"
},
"Flags": 65536,
"HighLimit": {
"currency": "USD",
"issuer": "rf1BiGeXwwQoi8Z2ueFYTEXSwuJYfV2Jpn",
"value": "0"
},
"HighNode": "0000000000000000",
"LowLimit": {
"currency": "USD",
"issuer": "ra5nK24KXen9AHvsdFTKHSANinZseWnPcX",
"value": "100"
},
"LowNode": "0000000000000000"
},
"LedgerEntryType": "RippleState",
"LedgerIndex": "96D2F43BA7AE7193EC59E5E7DDB26A9D786AB1F7C580E030E7D2FF5233DA01E9",
"PreviousFields": {
"Balance": {
"currency": "USD",
"issuer": "rrrrrrrrrrrrrrrrrrrrBZbvji",
"value": "1"
}
},
"PreviousTxnID": "7BF105CFE4EFE78ADB63FE4E03A851440551FE189FD4B51CAAD9279C9F534F0E",
"PreviousTxnLgrSeq": 6979192
}
}
],
"TransactionIndex": 0,
"TransactionResult": "tesSUCCESS"
},
"validated": true
}
}
```
## Identifying Transactions

39
content/concepts/transactions/trust-lines-and-issuing.md
View File

@@ -8,9 +8,9 @@ labels:
# Trust Lines and Issuing
Trust lines are structures in the XRP Ledger for holding [tokens](../tokens/tokens.md). Trust lines enforce the XRP Ledger's rule that you cannot cause someone else to hold a token they don't want. This precaution is necessary to enable the XRP Ledger's use case for [community credit](../tokens/tokens.md#community-credit) among other benefits.
Trust lines are structures in the XRP Ledger for holding [tokens](../tokens/tokens.md). Trust lines enforce the XRP Ledger's rule that you cannot cause someone else to hold a token they do not want. This precaution is necessary to enable the XRP Ledger's use case for [community credit](../tokens/tokens.md#community-credit) among other benefits.
Each "trust line" is a _bidirectional_ relationship consisting of:
Each trust line is a _bidirectional_ relationship consisting of:
- The identifiers for the **two [accounts](../accounts/accounts.md)** that the trust line connects.
- A single, shared **balance**, which is positive from the perspective of one account and negative from the other perspective.
@@ -25,7 +25,7 @@ Each trust line is specific to a given currency code. Two accounts can have any
Any account can unilaterally "trust" another account to issue a token by sending a `TrustSet` transaction with a nonzero limit and their own settings. This creates a line with a zero balance, and sets the other side's settings to the default.
Trust lines can be implicitly created by some transactions, such as when you buy a token in the decentralized exchange.<!-- ](decentralized-exchange.html). --> In this case, the trust line uses entirely default settings.
Trust lines can be implicitly created by some transactions, such as when you buy a token in the decentralized exchange. In this case, the trust line uses entirely default settings.
## Going Below the Limit
@@ -34,32 +34,32 @@ There are three cases where you can hold a balance that is _greater_ than your l
1. When you acquire more of that token through trading. <!--](decentralized-exchange.html).-->
2. When you decrease the limit on a trust line that has a positive balance.
3. When you acquire more of that token by [cashing a Check](payments/checks.md). (_Requires the CheckCashMakesTrustLine amendment :not_enabled:_)
3. When you acquire more of that token by [cashing a Check](checks.html). (_Requires the CheckCashMakesTrustLine amendment :not_enabled:_)
## Trust Line Settings
In addition to the shared balance, each account has its own settings on the trust line, which consist of the following:
- The **Limit**, a number from 0 to the maximum token amount.<!--](currency-formats.html).--> Payments and other accounts' actions cannot cause the trust line's balance (from this account's perspective) to go over the limit. The default is `0`.
- **Authorized**: A true/false value used with Authorized Trust Lines<!--](authorized-trust-lines.html)--> to allow the other side to hold tokens this account issues. The default is `false`. Once set to `true`, this cannot be changed back.
- **No Ripple**: A true/false value to control whether tokens can [ripple](../tokens/rippling.md) through this trust line. The default depends on the account's "Default Ripple" setting; for new accounts, "Default Ripple" is off which means that `true` is the default for No Ripple. Usually, issuers should allow rippling and non-issuers should disable rippling unless they are using trust lines for community credit.
- **Freeze**: A true/false value indicating whether an [individual freeze](../tokens/freezing-tokens.md#individual-freeze) is in effect on this trust line. The default is `false`.
- The **Limit**, a number from 0 to the maximum token amount. Payments and other accounts' actions cannot cause the trust line's balance (from this account's perspective) to go over the limit. The default is `0`.
- **Authorized**: A true/false value used with Authorized Trust Lines to allow the other side to hold tokens this account issues. The default is `false`. Once set to `true`, this cannot be changed back.
- **No Ripple**: A true/false value to control whether tokens can [ripple](rippling.html) through this trust line. The default depends on the account's "Default Ripple" setting; for new accounts, "Default Ripple" is off which means that `true` is the default for No Ripple. Usually, issuers should allow rippling and non-issuers should disable rippling unless they are using trust lines for community credit.
- **Freeze**: A true/false value indicating whether an [individual freeze](freezing-tokens.html#individual-freeze) is in effect on this trust line. The default is `false`.
- **Quality In** and **Quality Out** settings, which allow the account to value tokens issued by the other account on this trust line at less (or more) than face value. For example, if a stablecoin issuer charges a 3% fee for withdrawing tokens for the equivalent off-ledger assets, you could use these settings to value those tokens at 97% of face value. The default, `0`, represents face value.
## Reserves and Deletion
Since a trust line occupies space in the ledger, [a trust line increases the XRP your account must hold in reserve](../accounts/reserves.md). Either or both accounts in the trust line may be charged the reserve for the trust line, depending on the status of the trust line: if any of your settings are not the default, or if you hold a positive balance, it counts as one item toward your owner reserve.
Since a trust line occupies space in the ledger, [a trust line increases the XRP your account must hold in reserve](reserves.html). Either or both accounts in the trust line can be charged the reserve for the trust line, depending on the status of the trust line: if any of your settings are not the default, or if you hold a positive balance, it counts as one item toward your owner reserve.
Generally, this means that the account that created the trust line is responsible for the reserve and the issuer is not.
Trust lines are automatically deleted if both sides' settings are in the default state and the balance is 0. This means that, to delete a trust line, you need to:
1. Send a `TrustSet` transaction to set your settings to the defaults.
2. Offload any positive balance you have on the trust line. You could do this by sending a [payment](payments/cross-currency-payments.md), or by selling the currency in the decentralized exchange. <!--](decentralized-exchange.html). -->
2. Offload any positive balance you have on the trust line. You could do this by sending a [payment](cross-currency-payments.html), or by selling the currency in the decentralized exchange.
If your balance is negative (you are the issuer) or the other side's settings are not in the default state, you cannot cause the trust line to be totally deleted, but you can make it so that it does not count towards your owner reserve by following the same steps.
If your balance is negative (you are the issuer) or the other side's settings are not in the default state, you cannot cause the trust line to be totally deleted, but you can make it so that it does not count toward your owner reserve by following the same steps.
Since the **Authorized** setting cannot be turned off after it has been turned on, it does not count toward the trust line's default state.
@@ -70,19 +70,4 @@ Since trust lines are a powerful feature of the XRP Ledger, there is a special f
When an account creates a new trust line, if the account owns at most 2 items in the ledger including the new line, the account's owner reserve is treated as zero instead of the normal amount. This allows the transaction to succeed even if the account does not hold enough XRP to meet the increased reserve requirement for owning objects in the ledger.
When an account owns 3 or more objects in the ledger, the full owner reserve applies.
<!--
## See Also
- **Concepts:**
- [Decentralized Exchange](decentralized-exchange.html)
- [Rippling](rippling.html)
- **Tutorials:**
- [Become an XRP Ledger Gateway](become-an-xrp-ledger-gateway.html)
- **References:**
- [account_lines method][] - Look up trust lines attached to a given account
- [gateway_balances method][] - Look up an issuer's total balance issued
- [RippleState object](ripplestate.html) - The data format for trust lines in the ledger's state data.
- [TrustSet transaction][] - The transaction to create or modify trust lines.
-->
When an account owns 3 or more objects in the ledger, the full owner reserve applies.

58
dactyl-config.yml
View File

@@ -457,29 +457,11 @@ pages:
targets:
- ja
# Concepts ---------------------------------------------------------------------
- name: Concepts
html: concepts.html
parent: docs.html
top_nav_grouping: Article Types
template: pagetype-category.html.jinja
blurb: Learn the "what" and "why" behind fundamental aspects of the XRP Ledger.
targets:
- en
- name: コンセプト
html: concepts.html
parent: docs.html
top_nav_grouping: Article Types
template: pagetype-category.html.jinja
blurb: XRP Ledgerの基本的な部分の背景に「何があるか」、「なぜなのか」を学びましょう。
targets:
- ja
# Introduction -----------------------------------------------------------------
- name: Introduction
html: introduction.html
parent: concepts.html
parent: docs.html
template: pagetype-category.html.jinja
blurb: This is a quick introduction to the principal features of the XRP Ledger (XRPL). Read this to get a high level understanding of the XRPL, then you can read more about areas of particular interest. The XRP Ledger is a blockchain that permanently records digital transactions of tokens between accounts. The sections below expand on the concepts introduced in that sentence.
targets:
@@ -510,15 +492,27 @@ pages:
targets:
- en
- ja
# Concepts ---------------------------------------------------------------------
- name: Concepts
html: concepts.html
parent: docs.html
top_nav_grouping: Article Types
template: pagetype-category.html.jinja
blurb: Learn the "what" and "why" behind fundamental aspects of the XRP Ledger.
targets:
- en
- name: コンセプト
html: concepts.html
parent: docs.html
top_nav_grouping: Article Types
template: pagetype-category.html.jinja
blurb: XRP Ledgerの基本的な部分の背景に「何があるか」、「なぜなのか」を学びましょう。
targets:
- ja
# - name: Understanding the XRP Ledger
# html: understanding-xrpl.html
# parent: concepts.html
# template: pagetype-category.html.jinja
# blurb: This is an in-depth discussion of all elements of the XRP Ledger.
# targets:
# - en
# - ja
- md: concepts/server/rippled-server.md
parent: concepts.html
@@ -868,14 +862,14 @@ pages:
targets:
- en
- ja
- md: concepts/accounts/deposit-authorization.md
- md: concepts/accounts/cryptographic-keys.md
parent: accounts.html
targets:
- en
- ja
- md: concepts/accounts/cryptographic-keys.md
- md: concepts/accounts/deposit-authorization.md
parent: accounts.html
targets:
- en