diff --git a/assets/js/apitool-methods-ws.js b/assets/js/apitool-methods-ws.js index 42218b6104..1123700c9b 100644 --- a/assets/js/apitool-methods-ws.js +++ b/assets/js/apitool-methods-ws.js @@ -99,7 +99,7 @@ Request('gateway_balances', { }) Request('noripple_check', { - description: "Compares an account's DefaultRipple and NoRipple flags to the recommended settings.", + description: "Compares an account's Default Ripple and No Ripple flags to the recommended settings.", link: "noripple_check.html", body: { "id": 0, diff --git a/assets/js/tx-sender.js b/assets/js/tx-sender.js index 705e530c1c..7f181f5891 100644 --- a/assets/js/tx-sender.js +++ b/assets/js/tx-sender.js @@ -235,14 +235,14 @@ const set_up_tx_sender = async function() { } $("#pp_progress .progress-bar").width("20%") - // 2. Set DefaultRipple on issuer + // 2. Set Default Ripple on issuer let resp = await submit_and_verify({ TransactionType: "AccountSet", Account: pp_issuer_address, SetFlag: 8 }, pp_issuer_secret, true) if (resp === undefined) { - console.log("Couldn't set DefaultRipple for partial payment issuer") + console.log("Couldn't set Default Ripple for partial payment issuer") return } $("#pp_progress .progress-bar").width("40%") diff --git a/content/_img-sources/noripple-05.uxf b/content/_img-sources/noripple-05.uxf index 54c35a6601..a8f526488c 100644 --- a/content/_img-sources/noripple-05.uxf +++ b/content/_img-sources/noripple-05.uxf @@ -45,7 +45,7 @@ A lt=<- $1 -NoRipple +No Ripple 10.0;20.0;110.0;20.0 @@ -82,7 +82,7 @@ B lt=<- $100 -NoRipple +No Ripple 120.0;20.0;10.0;20.0 diff --git a/content/_img-sources/noripple-06.uxf b/content/_img-sources/noripple-06.uxf index 4dc50fc28f..4e952f1f90 100644 --- a/content/_img-sources/noripple-06.uxf +++ b/content/_img-sources/noripple-06.uxf @@ -45,7 +45,7 @@ A lt=<- $1 - NoRipple + No Ripple 10.0;20.0;110.0;20.0 @@ -82,7 +82,7 @@ B lt=<- $100 -NoRipple . +No Ripple . 120.0;20.0;10.0;20.0 @@ -167,7 +167,7 @@ A lt=<- $1 - NoRipple + No Ripple 10.0;20.0;110.0;20.0 @@ -392,7 +392,7 @@ A lt=<- $1 - NoRipple + No Ripple 10.0;20.0;110.0;20.0 @@ -416,7 +416,7 @@ $1 lt=<- $100 - NoRipple + No Ripple 10.0;20.0;120.0;20.0 @@ -467,7 +467,7 @@ bg=green 110 This path is valid -because Daniel, but not Emily, has set the NoRipple flag on the trust line between them +because Daniel, but not Emily, has set the No Ripple flag on the trust line between them bg=yellow diff --git a/content/_snippets/depositauth-semantics-table.html b/content/_snippets/depositauth-semantics-table.html index d8b906f352..60a2dccacb 100644 --- a/content/_snippets/depositauth-semantics-table.html +++ b/content/_snippets/depositauth-semantics-table.html @@ -66,7 +66,7 @@ Only if account previously created a matching offer - Payment
(If account has more than the minimum XRP reserve, enables NoRipple on all trust lines, and places no offers)
+ Payment
(If account has more than the minimum XRP reserve, enables No Ripple on all trust lines, and places no offers)
Cross-currency only OK   @@ -84,7 +84,7 @@ OK - Payment
(If account has any trust lines with NoRipple disabled)
+ Payment
(If account has any trust lines with No Ripple disabled)
Cross-currency only OK   diff --git a/content/_snippets/gateways-intro.md b/content/_snippets/gateways-intro.md index fd74e3a276..3ac1eecd4b 100644 --- a/content/_snippets/gateways-intro.md +++ b/content/_snippets/gateways-intro.md @@ -1,5 +1,5 @@ Gateways are businesses that provide a way for money and other forms of value to move in and out of the XRP Ledger. There are three major models that gateways can follow, with different purposes and modes of operation. -* An **Issuing Gateway** receives money (or other assets of value) outside of the XRP Ledger, and creates issuances in the XRP Ledger. This provides a direct way for customers to get money in and out of the XRP Ledger. All currencies in the XRP Ledger, except for XRP, take the form of issuances tied to a specific issuing gateway. +* An **Issuing Gateway** receives money (or other assets of value) outside of the XRP Ledger, and issues currency in the XRP Ledger. This provides a direct way for customers to get money in and out of the XRP Ledger. All currencies in the XRP Ledger, except for XRP, are tied to a specific issuing gateway. * A **Private Exchange** holds XRP and lets its customers buy and sell that XRP in its own system. Most cryptocurrencies rely on private exchanges to provide a market for the cryptocurrency, but the XRP Ledger has a currency exchange built into the protocol itself. * **Merchants** accept payment within the XRP Ledger in exchange for goods and services in the outside world. Currently, Ripple (the company) does not provide support for merchant operations using the XRP Ledger. diff --git a/content/_snippets/tutorial-submit-step.md b/content/_snippets/tutorial-submit-step.md index 08141888e0..307c4444e3 100644 --- a/content/_snippets/tutorial-submit-step.md +++ b/content/_snippets/tutorial-submit-step.md @@ -1,3 +1,3 @@ -Take the signed transaction blob from the previous step and submit it to a `rippled` server. You can do this safely even if you do not operate the `rippled` server. The response contains a provisional result, which should be `tesSUCCESS`, but this result is [usually not final](finality-of-results.html). A provisional response of `terQUEUED` is also OK, since [queued transactions](transaction-cost.html#queued-transactions) are generally included in the next open ledger version (usually about 10 seconds after submission). +Take the signed transaction blob from the previous step and submit it to a `rippled` server. You can do this safely even if you do not run the `rippled` server. The response contains a provisional result, which should be `tesSUCCESS`, but this result is [usually not final](finality-of-results.html). A provisional response of `terQUEUED` is also OK, since [queued transactions](transaction-cost.html#queued-transactions) are generally included in the next open ledger version (usually about 10 seconds after submission). **Tip:** If the preliminary result is `tefMAX_LEDGER`, the transaction has failed permanently because its `LastLedgerSequence` parameter is lower than the current ledger. This happens when you take longer than the expected number of ledger versions between preparing and submitting the transaction. If this occurs, [start over from step 1]({{step_1_link}}) with a higher `LastLedgerSequence` value. diff --git a/content/concepts/consensus-network/amendments/known-amendments.md b/content/concepts/consensus-network/amendments/known-amendments.md index 662db25f97..01cc765679 100644 --- a/content/concepts/consensus-network/amendments/known-amendments.md +++ b/content/concepts/consensus-network/amendments/known-amendments.md @@ -119,7 +119,7 @@ When an account enables this flag, Payment transactions fail if the account is t As an exception, accounts with `DepositAuth` enabled can receive Payment transactions for small amounts of XRP (equal or less than the minimum [account reserve](reserves.html)) if their current XRP balance is below the account reserve. -Also fixes a bug in the EscrowCreate and PaymentChannelCreate transactions where they mistakenly enforced the DisallowXRP flag, which is meant to be a non-binding advisory flag. (By not enforcing DisallowXRP in the ledger itself an account can still receive the necessary XRP to meet its [account reserve](reserves.html) and pay [transaction costs](transaction-cost.html).) +Also fixes a bug in the EscrowCreate and PaymentChannelCreate transactions where they mistakenly enforced the Disallow XRP flag, which is meant to be a non-binding advisory flag. (By not enforcing Disallow XRP in the ledger itself an account can still receive the necessary XRP to meet its [account reserve](reserves.html) and pay [transaction costs](transaction-cost.html).) ## DepositPreauth @@ -133,7 +133,7 @@ Provides users of [deposit authorization](depositauth.html) with a way to preaut Adds a new transaction type, DepositPreauth for adding or removing preauthorization, and a DepositPreauth ledger object type for tracking preauthorizations from one account to another. Adds a JSON-RPC command, `deposit_authorized`, to query whether an account is authorized to send payments directly to another. -Also changes the behavior of cross-currency Payments from an account to itself when that account requires deposit authorization. Without this amendment, those payments always fail with the code tecNO_PERMISSION. With this amendment, those payments succeed as they would with Deposit Authorization disabled. +Also changes the behavior of cross-currency Payments from an account to itself when that account requires deposit authorization. Without this amendment, those payments always fail with the code `tecNO_PERMISSION`. With this amendment, those payments succeed as they would with Deposit Authorization disabled. ## EnforceInvariants @@ -326,7 +326,7 @@ Changes Escrow to fix the following issues: Changes the result codes returned by two transaction types: - Changes the [OfferCreate transaction][] to return a new result code, `tecKILLED`, if the offer used the `tfFillOrKill` flag and was killed. Without this amendment, the offer is killed but the transaction result is `tesSUCCESS`. -- Changes the [TrustSet transaction][] to fail with `tecNO_PERMISSION` if it tries to enable the [NoRipple flag](rippling.html#the-noripple-flag) but cannot because the trust line has a negative balance. Without this amendment, the transaction does not enable the NoRipple flag, but the transaction result is `tesSUCCESS` nonetheless. +- Changes the [TrustSet transaction][] to fail with `tecNO_PERMISSION` if it tries to enable the [No Ripple flag](rippling.html#the-no-ripple-flag) but cannot because the trust line has a negative balance. Without this amendment, the transaction does not enable the No Ripple flag, but the transaction result is `tesSUCCESS` nonetheless. ## fix1623 @@ -537,7 +537,7 @@ Implements a "Negative UNL" system, where the network can track which validators |:-----------------------------------------------------------------|:----------| | 9178256A980A86CF3D70D0260A7DA6402AAFE43632FDBCB88037978404188871 | In Development | -Fixes an inconsistency in the way [transfer fees](transfer-fees.html) are calculated between [OfferCreate](offercreate.html) and [Payment](payment.html) transaction types. Without this amendment, the holder of the issuances pays the transfer fee if an offer is executed in offer placement, but the initial sender of a transaction pays the transfer fees for offers that are executed as part of payment processing. With this amendment, the holder of the issuances always pays the transfer fee, regardless of whether the offer is executed as part of a Payment or an OfferCreate transaction. Offer processing outside of payments is unaffected. +Fixes an inconsistency in the way [transfer fees](transfer-fees.html) are calculated between [OfferCreate](offercreate.html) and [Payment](payment.html) transaction types. Without this amendment, the holder of the issued currency pays the transfer fee if an offer is executed in offer placement, but the initial sender of a transaction pays the transfer fees for offers that are executed as part of payment processing. With this amendment, the holder of the issued currency always pays the transfer fee, regardless of whether the offer is executed as part of a Payment or an OfferCreate transaction. Offer processing outside of payments is unaffected. This Amendment requires the [Flow Amendment](#flow) to be enabled. @@ -553,7 +553,7 @@ This Amendment requires the [Flow Amendment](#flow) to be enabled. Creates "Payment Channels" for XRP. Payment channels are a tool for facilitating repeated, unidirectional payments or temporary credit between two parties. Ripple expects this feature to be useful for the [Interledger Protocol](https://interledger.org/). One party creates a Payment Channel and sets aside some XRP in that channel for a predetermined expiration. Then, through off-ledger secure communications, the sender can send "Claim" messages to the receiver. The receiver can redeem the Claim messages before the expiration, or choose not to in case the payment is not needed. The receiver can verify Claims individually without actually distributing them to the network and waiting for the consensus process to redeem them, then redeem the combined content of many small Claims later, as long as it is within the expiration. -Creates three new transaction types: [PaymentChannelCreate][], [PaymentChannelClaim][], and [PaymentChannelFund][]. Creates a new ledger object type, [PayChannel](paychannel.html). Defines an off-ledger data structure called a `Claim`, used in the ChannelClaim transaction. Creates new `rippled` API methods: [`channel_authorize`](channel_authorize.html) (creates a signed Claim), [`channel_verify`](channel_verify.html) (verifies a signed Claim), and [`account_channels`](account_channels.html) (lists Channels associated with an account). +Creates three new transaction types: [PaymentChannelCreate][], [PaymentChannelClaim][], and [PaymentChannelFund][]. Creates a new ledger object type, [PayChannel](paychannel.html). Defines an off-ledger data structure called a `Claim`; the PaymentChannelClaim uses a signature for this data structure. Creates new `rippled` API methods: [`channel_authorize`](channel_authorize.html) (creates a signed Claim), [`channel_verify`](channel_verify.html) (verifies a signed Claim), and [`account_channels`](account_channels.html) (lists Channels associated with an account). For more information, see the [Payment Channels Tutorial](use-payment-channels.html). @@ -565,11 +565,11 @@ For more information, see the [Payment Channels Tutorial](use-payment-channels.h |:-----------------------------------------------------------------|:----------| | 00C1FC4A53E60AB02C864641002B3172F38677E29C26C5406685179B37E1EDAC | Enabled | -Changes the signature requirements for the XRP Ledger protocol so that non-fully-canonical signatures are no longer valid in any case. This protects against [transaction malleability](transaction-malleability.html) on _all_ transactions, instead of just transactions with the [tfFullyCanonicalSig flag](transaction-common-fields.html#global-flags) enabled. +Changes the signature requirements for the XRP Ledger protocol so that non-fully-canonical signatures are no longer valid in any case. This protects against [transaction malleability](transaction-malleability.html) on _all_ transactions, instead of only transactions with the [`tfFullyCanonicalSig` flag](transaction-common-fields.html#global-flags) enabled. -Without this amendment, a transaction is malleable if it uses a secp256k1 signature and does not have tfFullyCanonicalSig enabled. Most signing utilities enable tfFullyCanonicalSig by default, but there are exceptions. +Without this amendment, a transaction is malleable if it uses a secp256k1 signature and does not have `tfFullyCanonicalSig` enabled. Most signing utilities enable `tfFullyCanonicalSig` by default, but there are exceptions. -With this amendment, no single-signed transactions are malleable. ([Multi-signed transactions may still be malleable](transaction-malleability.html#malleability-with-multi-signatures) if signers provide more signatures than are necessary.) All transactions must use the fully canonical form of the signature, regardless of the tfFullyCanonicalSig flag. Signing utilities that do not create fully canonical signatures are not supported. All of Ripple's signing utilities have been providing fully-canonical signatures exclusively since at least 2014. +With this amendment, no single-signed transactions are malleable. ([Multi-signed transactions may still be malleable](transaction-malleability.html#malleability-with-multi-signatures) if signers provide more signatures than are necessary.) All transactions must use the fully canonical form of the signature, regardless of the `tfFullyCanonicalSig` flag. Signing utilities that do not create fully canonical signatures are not supported. All of Ripple's signing utilities have been providing fully-canonical signatures exclusively since at least 2014. For more information, see [`rippled` issue #3042](https://github.com/ripple/rippled/issues/3042). @@ -641,7 +641,7 @@ Introduces a `TickSize` field to accounts, which can be set with the [AccountSet Allows pre-authorization of accounting relationships (zero-balance trust lines) when using [Authorized Trust Lines](authorized-trust-lines.html). -With this amendment enabled, a `TrustSet` transaction with [`tfSetfAuth` enabled](trustset.html#trustset-flags) can create a new [`RippleState` ledger object](ripplestate.html) even if it keeps all the other values of the `RippleState` node in their default state. The new `RippleState` node has the [`lsfLowAuth` or `lsfHighAuth` flag](ripplestate.html#ripplestate-flags) enabled, depending on whether the sender of the transaction is considered the low node or the high node. The sender of the transaction must have already enabled [`lsfRequireAuth`](accountroot.html#accountroot-flags) by sending an [AccountSet transaction](accountset.html) with the [asfRequireAuth flag enabled](accountset.html#accountset-flags). +With this amendment enabled, a `TrustSet` transaction with [`tfSetfAuth` enabled](trustset.html#trustset-flags) can create a new [`RippleState` ledger object](ripplestate.html) even if it keeps all the other values of the `RippleState` node in their default state. The new `RippleState` node has the [`lsfLowAuth` or `lsfHighAuth` flag](ripplestate.html#ripplestate-flags) enabled, depending on whether the sender of the transaction is considered the low node or the high node. The sender of the transaction must have already enabled [`lsfRequireAuth`](accountroot.html#accountroot-flags) by sending an [AccountSet transaction](accountset.html) with the [`asfRequireAuth` flag enabled](accountset.html#accountset-flags). diff --git a/content/concepts/consensus-network/consensus-principles-and-rules.md b/content/concepts/consensus-network/consensus-principles-and-rules.md index 14a5b26e8f..5433fc8f3d 100644 --- a/content/concepts/consensus-network/consensus-principles-and-rules.md +++ b/content/concepts/consensus-network/consensus-principles-and-rules.md @@ -51,7 +51,7 @@ The primary role of consensus is for participants in the process to agree on whi 3. It is extremely rare for a participant to particularly care how the transactions were grouped. Agreement is easiest when everyone’s priority is reaching agreement and only challenging when there are diverging interests. 4. Deterministic rules can be used even to form the groupings, leading to disagreement only in edge cases. For example, if there are two conflicting transactions in a round, deterministic rules can be used to determine which is included in the next round. -Every participant’s top priority is correctness. They must first enforce the rules to be sure nothing violates the integrity of the shared ledger. For example, a transaction that is not properly signed must never be processed (even if other participants want to be processed). However, every honest participant’s second priority is agreement. A network with possible double spends has no utility at all. Agreement is facilitated by the fact that every honest participant values it above everything but correctness. +Every participant’s top priority is correctness. They must first enforce the rules to be sure nothing violates the integrity of the shared ledger. For example, a transaction that is not properly signed must never be processed (even if other participants want it to be processed). However, every honest participant’s second priority is agreement. A network with possible double spends has no utility at all, so every honest participant values agreement above everything but correctness. ### Consensus Rounds diff --git a/content/concepts/consensus-network/consensus-protections.md b/content/concepts/consensus-network/consensus-protections.md index 98a715bdf6..1160247577 100644 --- a/content/concepts/consensus-network/consensus-protections.md +++ b/content/concepts/consensus-network/consensus-protections.md @@ -1,6 +1,6 @@ # Consensus Protections Against Attacks and Failure Modes -The XRP Ledger Consensus Protocol is a _byzantine fault tolerant_ consensus mechanism, which means it's designed to operate even if all kinds of things can go wrong: participants depend on an unreliable open network to communicate, and malicious actors may be attempting to control or interrupt the system at any given time. On top of that, the set of participants in the XRP Ledger Consensus Protocol isn't known in advance and can change over time. +The XRP Ledger Consensus Protocol is a _byzantine fault tolerant_ consensus mechanism, which means it's designed to work even if all kinds of things can go wrong: participants depend on an unreliable open network to communicate, and malicious actors may be attempting to control or interrupt the system at any given time. On top of that, the set of participants in the XRP Ledger Consensus Protocol isn't known in advance and can change over time. Confirming transactions in a timely manner while maintaining [the desired properties of the network](intro-to-consensus.html#consensus-protocol-properties) is a complex challenge, and it's impossible to build a perfect system. The XRP Ledger Consensus Protocol is designed to work as well as it can in most situations, and to fail as gracefully as possible in the situations where it can't. @@ -25,7 +25,7 @@ The only way to confirm an invalid transaction would be to get at least 80% of t ## Software Vulnerabilities -As with any software system, bugs (or intentionally malicious code) in the implementation of the XRP Ledger Consensus Protocol, commonly deployed software packages, or their dependencies, are a problem to be taken seriously. Even bugs that simply cause a server to crash when it sees carefully crafted inputs can be abused to disrupt the progress of the network. Ripple has a number of precautions in place to address this threat, including: +As with any software system, bugs (or intentionally malicious code) in the implementation of the XRP Ledger Consensus Protocol, commonly deployed software packages, or their dependencies, are a problem to be taken seriously. Even bugs that cause a server to crash when it sees carefully crafted inputs can be abused to disrupt the progress of the network. Ripple has a number of precautions in place to address this threat, including: - An [open-source code base](https://github.com/ripple/rippled/), so any member of the public can review, compile, and independently test the relevant software. - A thorough and robust code review process for all changes to the official XRP Ledger repositories. diff --git a/content/concepts/consensus-network/consensus-research.md b/content/concepts/consensus-network/consensus-research.md index 5510ca7827..b936e610e9 100644 --- a/content/concepts/consensus-network/consensus-research.md +++ b/content/concepts/consensus-network/consensus-research.md @@ -7,3 +7,5 @@ Ripple researches both the theoretical and the practical limits of the XRP Ledge | 2018-02-20 | [Cobalt: BFT Governance in Open Networks](https://arxiv.org/abs/1802.07240) | MacBrough | Introduces a novel atomic broadcast algorithm called Cobalt that allows more flexibility in consensus UNLs. | | 2018-02-20 | [Analysis of the XRP Ledger Consensus Protocol](https://arxiv.org/abs/1802.07242) | Chase, MacBrough | A detailed and updated analysis of the XRP Ledger consensus algorithm and its safety and liveness properties. | | 2014 | [The Ripple Protocol Consensus Algorithm](https://ripple.com/files/ripple_consensus_whitepaper.pdf) | Schwartz, Youngs, Britto | Introduces the consensus algorithm behind the XRP Ledger. | + + diff --git a/content/concepts/consensus-network/consensus.md b/content/concepts/consensus-network/consensus.md index d2f5a25c76..a70b162346 100644 --- a/content/concepts/consensus-network/consensus.md +++ b/content/concepts/consensus-network/consensus.md @@ -51,7 +51,7 @@ In addition to the **`tes`** and **`tec`** class result codes, there are **`ter` When working with [`rippled` APIs](rippled-api.html), applications must distinguish between candidate transactions proposed for inclusion in a ledger versus validated transactions which are included in a validated ledger. Only transaction results found in a validated ledger are immutable. A candidate transaction may or may not ever be included in a validated ledger. -Important: Some [`rippled` APIs](rippled-api.html) provide provisional results, based on candidate transactions 2. Applications should never rely on provisional results to determine the final outcome of a transaction. The only way to know with certainty that a transaction finally succeeded is to check the status of the transaction until it is both in a validated ledger and has result code tesSUCCESS. If the transaction is in a validated ledger with any other result code, it has failed. If the ledger specified in a transaction’s [`LastLedgerSequence`](transaction-common-fields.html) has been validated, yet the transaction does not appear in that ledger or any before it, then that transaction has failed and can never appear in any ledger. An outcome is final only for transactions that appear in a validated ledger or can never appear because of `LastLedgerSequence` restrictions as explained later in this document. +Important: Some [`rippled` APIs](rippled-api.html) provide provisional results, based on candidate transactions 2. Applications should never rely on provisional results to determine the final outcome of a transaction. The only way to know with certainty that a transaction finally succeeded is to check the status of the transaction until it is both in a validated ledger and has result code `tesSUCCESS`. If the transaction is in a validated ledger with any other result code, it has failed. If the ledger specified in a transaction’s [`LastLedgerSequence`](transaction-common-fields.html) has been validated, yet the transaction does not appear in that ledger or any before it, then that transaction has failed and can never appear in any ledger. An outcome is final only for transactions that appear in a validated ledger or can never appear because of `LastLedgerSequence` restrictions as explained later in this document. ## The XRP Ledger Protocol – Consensus and Validation @@ -155,7 +155,7 @@ Best practices for applications submitting transactions include: - Use the `LastLedgerSequence` parameter to ensure that transactions validate or fail in a deterministic and prompt fashion. - Check the results of transactions in validated ledgers. - Until a ledger containing the transaction is validated, or `LastLedgerSequence` has passed, results are provisional. - - Transactions with result code **tesSUCCESS** and `"validated": true` have immutably succeeded. + - Transactions with result code **`tesSUCCESS`** and `"validated": true` have immutably succeeded. - Transactions with other result codes and `"validated": true` have immutably failed. - Transactions that fail to appear in any validated ledger up to and including the validated ledger identified by the transaction’s `LastLedgerSequence` have immutably failed. - Take care to use a server with a continuous ledger history to detect this case 10. @@ -185,7 +185,7 @@ Best practices for applications submitting transactions include: 1 – Transactions with [**tec** result codes](tec-codes.html) do not perform the requested action, but do have effects on the ledger. To prevent abuse of the network and to pay for the cost of distributing the transaction, they destroy the XRP [transaction cost](transaction-cost.html). To not block other transactions submitted by the same sender around the same time, they increment the sending account's [sequence number](basic-data-types.html#account-sequence). Transactions with `tec`-class results sometimes also perform maintenance such as deleting expired objects or unfunded trade offers. -2 – For example, consider a scenario where Alice has $100, and sends all of it to Bob. If an application first submits that payment transaction, then immediately after checks Alice’s balance, the API returns $0. This value is based on the provisional result of a candidate transaction. There are circumstances in which the payment fails and Alice’s balance remains $100 (or, due to other transactions, become some other amount). The only way to know with certainty that Alice’s payment to Bob succeeded is to check the status of the transaction until it is both in a validated ledger and has result code **tesSUCCESS**. If the transaction is in a validated ledger with any other result code, the payment has failed. +2 – For example, consider a scenario where Alice has $100, and sends all of it to Bob. If an application first submits that payment transaction, then immediately after checks Alice’s balance, the API returns $0. This value is based on the provisional result of a candidate transaction. There are circumstances in which the payment fails and Alice’s balance remains $100 (or, due to other transactions, become some other amount). The only way to know with certainty that Alice’s payment to Bob succeeded is to check the status of the transaction until it is both in a validated ledger and has result code **`tesSUCCESS`**. If the transaction is in a validated ledger with any other result code, the payment has failed. 3 – Strictly speaking, validators are a subset of tracking servers. They provide the same features and additionally send "validation" messages. Tracking servers may be further categorized by whether they keep full vs. partial ledger history. diff --git a/content/concepts/consensus-network/parallel-networks.md b/content/concepts/consensus-network/parallel-networks.md index 4075e0400c..96e7623ed5 100644 --- a/content/concepts/consensus-network/parallel-networks.md +++ b/content/concepts/consensus-network/parallel-networks.md @@ -2,13 +2,13 @@ There is one production XRP Ledger peer-to-peer network, and all business that takes place on the XRP Ledger occurs within the production network—the Mainnet. -To help members of the XRPL community interact with XRPL technology without affecting anything on the Mainnet, Ripple hosts two alternative networks, or altnets: the Testnet and the Devnet. Here's a breakdown of all three networks: +To help members of the XRP Ledger community interact with XRP Ledger technology without affecting anything on the Mainnet, Ripple hosts two alternative networks, or altnets: the Testnet and the Devnet. Here's a breakdown of all three networks: | Network | Upgrade Cadence | Description | |:--------|:----------------|:-------------------------------------------------| | Mainnet | Stable releases | _The_ [XRP Ledger](xrp-ledger-overview.html), a decentralized cryptographic ledger powered by a network of peer-to-peer servers and the home of [XRP](xrp.html). | | Testnet | Stable releases | An "alternate universe" network that acts as a testing ground for software built on the XRP Ledger, without impacting production XRP Ledger users and without risking real money. The [amendment status](known-amendments.html) of the Testnet is intended to closely mirror the Mainnet, although slight variations in timing may occur due to the unpredictable nature of decentralized systems. | -| Devnet | Beta releases | A preview of coming attractions, where unstable changes to the core XRP Ledger software may be tested out. Developers can use this altnet to interact with and learn about planned new XRPL features and amendments that are not yet enabled on the Mainnet. | +| Devnet | Beta releases | A preview of coming attractions, where unstable changes to the core XRP Ledger software may be tested out. Developers can use this altnet to interact with and learn about planned new XRP Ledger features and amendments that are not yet enabled on the Mainnet. | Testnet and Devnet each have their own separate supply of test XRP, which Ripple [gives away for free](xrp-testnet-faucet.html) to parties interested in experimenting with the XRP Ledger and developing applications and integrations. Test XRP does not have real-world value and is lost when the network is reset. @@ -19,7 +19,7 @@ Testnet and Devnet each have their own separate supply of test XRP, which Ripple There is no `rippled` setting that defines which network it uses. Instead, it uses the consensus of validators it trusts to know which ledger to accept as the truth. When different consensus groups of `rippled` instances only trust other members of the same group, each group continues as a parallel network. Even if malicious or misbehaving computers connect to both networks, the consensus process overrides the confusion as long as the members of each network are not configured to trust members of another network in excess of their quorum settings. -Ripple operates the main servers in the Testnet and Devnet; you can also [connect your own `rippled` server to the Testnet](connect-your-rippled-to-the-xrp-test-net.html). The Testnet and Devnet do not use diverse, censorship-resistant sets of validators. This makes it possible for Ripple to reset the Testnet or Devnet on a regular basis. +Ripple runs the main servers in the Testnet and Devnet; you can also [connect your own `rippled` server to the Testnet](connect-your-rippled-to-the-xrp-test-net.html). The Testnet and Devnet do not use diverse, censorship-resistant sets of validators. This makes it possible for Ripple to reset the Testnet or Devnet on a regular basis. ## See Also diff --git a/content/concepts/consensus-network/transaction-malleability.md b/content/concepts/consensus-network/transaction-malleability.md index 092d75e446..e6d53fe937 100644 --- a/content/concepts/consensus-network/transaction-malleability.md +++ b/content/concepts/consensus-network/transaction-malleability.md @@ -6,11 +6,11 @@ If vulnerable software submits malleable transactions and assumes they can only There are two circumstances that could lead to transaction malleability: -1. The transaction does not specify the tfFullyCanonicalSig flag on a transaction signed using the default signing algorithm (ECDSA with the secp256k1 curve). +1. The transaction does not specify the `tfFullyCanonicalSig` flag on a transaction signed using the default signing algorithm (ECDSA with the secp256k1 curve). **Use the [`tfFullyCanonicalSig` flag](transaction-common-fields.html#global-flags)** to guarantee that a transaction is not malleable in this way. Although transactions [signed with Ed25519 keys](cryptographic-keys.html#signing-algorithms) are not vulnerable to this problem, **there is no downside** to using this flag on _all_ transactions. - If the [RequireFullyCanonicalSig amendment][] :not_enabled: is enabled, all transactions are protected against malleability regardless of the tfFullyCanonicalSig flag. + If the [RequireFullyCanonicalSig amendment][] :not_enabled: is enabled, all transactions are protected against malleability regardless of the `tfFullyCanonicalSig` flag. 2. The transaction is [multi-signed](multi-signing.html) and has more signatures than necessary. Even if the transaction originally did not have more signatures than necessary, it could be malleable if an authorized signer provides an additional signature. @@ -43,16 +43,16 @@ An ECDSA signature consists of two integers, called R and S. The secp256k1 _grou 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 maintain compatibility with older software that did not always generate fully canonical signatures, the XRP Ledger accepts transactions that are not fully canonical. To protect new users from exploits, the XRP Ledger has a flag on transactions called [**tfFullyCanonicalSig**](transaction-common-fields.html#global-flags), which requires that the transaction use a _fully-canonical_ signature to be valid. If the [RequireFullyCanonicalSig amendment][] :not_enabled: is enabled, all transactions require fully-canonical signatures regardless of the tfFullyCanonicalSig flag, and legacy software that makes non-fully-canonical signatures is no longer compatible. +To maintain compatibility with older software that did not always generate fully canonical signatures, the XRP Ledger accepts transactions that are not fully canonical. To protect new users from exploits, the XRP Ledger has a flag on transactions called [**`tfFullyCanonicalSig`**](transaction-common-fields.html#global-flags), which requires that the transaction use a _fully-canonical_ signature to be valid. If the [RequireFullyCanonicalSig amendment][] :not_enabled: is enabled, all transactions require fully-canonical signatures regardless of the `tfFullyCanonicalSig` flag, and legacy software that makes non-fully-canonical signatures is no longer compatible. 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. -All XRP Ledger software that Ripple publishes (including `rippled`, and ripple-lib/RippleAPI) generates only fully-canonical signatures. To further protect users, Ripple has configured its code to enable the **tfFullyCanonicalSig** flag by default where possible. Ripple strongly encourages third-party implementations of XRP Ledger software to generate only fully-canonical signatures, and enable tfFullyCanonicalSig on transactions by default. +All XRP Ledger software that Ripple publishes (including `rippled`, and ripple-lib/RippleAPI) generates only fully-canonical signatures. To further protect users, Ripple has configured its code to enable the **`tfFullyCanonicalSig`** flag by default where possible. Ripple strongly encourages third-party implementations of XRP Ledger software to generate only fully-canonical signatures, and enable `tfFullyCanonicalSig` on transactions by default. -There are two cases where Ripple's signing implementations for the XRP Ledger do not automatically enable the tfFullyCanonicalSig flag. Users should take care to set the flag in these situations: +There are two cases where Ripple's signing implementations for the XRP Ledger do not automatically enable the `tfFullyCanonicalSig` flag. Users should take care to set the flag in these situations: -- When the user explicitly specifies the `Flags` field of the transaction. Use bitwise OR to apply tfFullyCanonicalSig _and_ any other desired flags. -- When the user provides a multi-signature for a transaction. Since different participants in a multi-signature must sign _exactly_ the same data, the signing code does not pre-process the transaction instructions to add the tfFullyCanonicalSig flag. For multi-signed transactions, always enable the tfFullyCanonicalSig flag explicitly. +- When the user explicitly specifies the `Flags` field of the transaction. Use bitwise OR to apply `tfFullyCanonicalSig` _and_ any other desired flags. +- When the user provides a multi-signature for a transaction. Since different participants in a multi-signature must sign _exactly_ the same data, the signing code does not pre-process the transaction instructions to add the `tfFullyCanonicalSig` flag. For multi-signed transactions, always enable the `tfFullyCanonicalSig` flag explicitly. ### Malleability with Multi-Signatures @@ -77,7 +77,7 @@ Even if your authorized signers are not intentionally malicious, confusion or po - Be prepared for the possibility that a transaction executes with a different hash and set of signatures than you expected. Carefully monitor your account's sent transactions (for example, using the [account_tx method][]). - Monitor the `Sequence` number of your account (for example, using the [account_info method][]). This number always increases by exactly one when your account sends a transaction successfully, and never any other way. If the number does not match what you expect, you should check your recent transactions to confirm why. (Aside from malleable transactions, there are other ways this could happen, too. Perhaps you configured another application to send transactions for you. Maybe a malicious user gained access to your secret key. Or perhaps your application lost data and forgot about a transaction you sent already.) - If you re-create transactions to be multi-signed, _do not_ change the `Sequence` number unless you have manually confirmed that the intended actions have not already executed. -- Confirm that the tfFullyCanonicalSig flag is enabled before signing. +- Confirm that the `tfFullyCanonicalSig` flag is enabled before signing. For greater security, these guidelines provide multiple layers of protection. @@ -86,19 +86,19 @@ For greater security, these guidelines provide multiple layers of protection. If the software you use to interface with the XRP Ledger sends malleable transactions, a malicious actor may be able to trick your software into losing track of a transaction's final outcome and potentially (in the worst case) sending equivalent payments multiple times. -If you use single-signatures and always enable the tfFullyCanonicalSig flag, you are not vulnerable to this exploit. If you use multi-signatures, you may be vulnerable if you or your signers provide more signatures than necessary. +If you use single-signatures and always enable the `tfFullyCanonicalSig` flag, you are not vulnerable to this exploit. If you use multi-signatures, you may be vulnerable if you or your signers provide more signatures than necessary. ### Exploit Scenario Steps The process to exploit a vulnerable system follows a series of steps similar to the following: -1. The vulnerable system constructs and signs a transaction without enabling tfFullyCanonicalSig. +1. The vulnerable system constructs and signs a transaction without enabling `tfFullyCanonicalSig`. - Three ways that a transaction may not enable the tfFullyCanonicalSig flag are: + Three ways that a transaction may not enable the `tfFullyCanonicalSig` flag are: - - The system explicitly specifies a `Flags` field that does not have the tfFullyCanonicalSig bit enabled. - - The transaction is multi-signed and does not explicitly enable the tfFullyCanonicalSig flag. - - The system omits the `Flags` field from the transaction fields, but uses a non-standard implementation that does not automatically enable tfFullyCanonicalSig when signing. + - The system explicitly specifies a `Flags` field that does not have the `tfFullyCanonicalSig` bit enabled. + - The transaction is multi-signed and does not explicitly enable the `tfFullyCanonicalSig` flag. + - The system omits the `Flags` field from the transaction fields, but uses a non-standard implementation that does not automatically enable `tfFullyCanonicalSig` when signing. To be vulnerable, the transaction must be signed with an ECDSA key pair. If multi-signed, the transaction must be signed by at least one ECDSA key pair. @@ -138,7 +138,7 @@ The process to exploit a vulnerable system follows a series of steps similar to 8. The vulnerable system takes action assuming that the transaction has failed. - For example, it may refund (or simply 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. + 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. diff --git a/content/concepts/decentralized-exchange/autobridging.md b/content/concepts/decentralized-exchange/autobridging.md index 90673c8b73..c62c1307ab 100644 --- a/content/concepts/decentralized-exchange/autobridging.md +++ b/content/concepts/decentralized-exchange/autobridging.md @@ -4,7 +4,7 @@ Any [Offer](offers.html) in the XRP Ledger's [decentralized exchange](decentrali Example: _Anita places an offer to sell GBP and buy BRL. She might find that this uncommon currency market has few offers. There is one offer with a good rate, but it has insufficient quantity to satisfy Anita's trade. However, both GBP and BRL have active, competitive markets to XRP. The XRP Ledger's auto-bridging system finds a way to complete Anita's offer by purchasing XRP with GBP from one trader, then selling the XRP to another trader to buy BRL. Anita automatically gets the best rate possible by combining the small offer in the direct GBP:BRL market with the better composite rates created by pairing GBP:XRP and XRP:BRL offers._ -Auto-bridging happens automatically on any [OfferCreate transaction][]. [Payment transactions](payment.html) _do not_ autobridge by default, but path-finding can find [paths](paths.html) that have the same effect. +Auto-bridging happens automatically on any [OfferCreate transaction][]. [Payment transactions](payment.html) _do not_ use auto-bridging by default, but path-finding can find [paths](paths.html) that have the same effect. ## See Also diff --git a/content/concepts/decentralized-exchange/offers.md b/content/concepts/decentralized-exchange/offers.md index 8ee582d4d6..51cb3d0d49 100644 --- a/content/concepts/decentralized-exchange/offers.md +++ b/content/concepts/decentralized-exchange/offers.md @@ -48,7 +48,7 @@ The limit values of trust lines (See [TrustSet](trustset.html)) do not affect of However, holding non-XRP balances still requires a trust line to the address issuing those balances. When an offer is taken, it automatically creates any necessary trust lines, setting their limits to 0. Because [trust lines increase the reserve an account must hold](reserves.html), any offers that would require a new trust line also require the address to have enough XRP to meet the reserve for that trust line. -A trust line indicates an issuer you trust enough to accept their issuances as payment, within limits. Offers are explicit instructions to acquire certain issuances, so they are allowed to go beyond those limits. +A trust line indicates an issuer you trust enough to accept their issued currencies as payment, within limits. Offers are explicit instructions to acquire certain issued currencies, so they are allowed to go beyond those limits. ## Offer Preference diff --git a/content/concepts/introduction/intro-to-consensus.md b/content/concepts/introduction/intro-to-consensus.md index 9c1a1165cf..a600d2eccb 100644 --- a/content/concepts/introduction/intro-to-consensus.md +++ b/content/concepts/introduction/intro-to-consensus.md @@ -46,7 +46,7 @@ As the network progresses, each server listens to its trusted validators[³](#fo [![Figure 2: Consensus rounds. Validators revise their proposals to match other validators they trust](img/consensus-rounds.png)](img/consensus-rounds.png) -It's OK if a small proportion of validators don't operate properly all the time. As long as fewer than 20% of trusted validators are faulty, consensus can continue unimpeded; and confirming an invalid transaction would require over 80% of trusted validators to collude. If more than 20% but less than 80% of trusted validators are faulty, the network simply stops making progress. +It's OK if a small proportion of validators don't work properly all the time. As long as fewer than 20% of trusted validators are faulty, consensus can continue unimpeded; and confirming an invalid transaction would require over 80% of trusted validators to collude. If more than 20% but less than 80% of trusted validators are faulty, the network stops making progress. For a longer exploration of how the XRP Ledger Consensus Protocol responds to various challenges, attacks, and failure cases, see [Consensus Protections Against Attacks and Failure Modes](consensus-protections.html). diff --git a/content/concepts/introduction/software-ecosystem.md b/content/concepts/introduction/software-ecosystem.md index c5a311537a..0f9bf17936 100644 --- a/content/concepts/introduction/software-ecosystem.md +++ b/content/concepts/introduction/software-ecosystem.md @@ -10,7 +10,7 @@ The XRP Ledger is home to a deep, layered ecosystem of software projects powerin - [_Programming Libraries_](#programming-libraries) exist in higher level software, where they are imported directly into program code, and contain methods to access the XRP Ledger. -- [_Middleware_](#middleware) provides indirect access to XRP Ledger data. Applications in this layer frequently have their own data storage and processing. +- [_Middleware_](#middleware) provides indirect access to XRP Ledger data. Applications in this layer often have their own data storage and processing. - [_Apps and Services_](#apps-and-services) provide user-level interaction with the XRP Ledger, or provide a basis for even higher-level apps and services. @@ -42,11 +42,11 @@ The [Data API](data-api.html) is an example of a middleware service on top of th ### Apps and Services -Atop the stack is where the truly exciting things happen. Apps and services provide a way for users and devices to connect to the XRP Ledger. At this level, [exchanges list XRP](list-xrp-in-your-exchange.html), [gateways issue other currencies](become-an-xrp-ledger-gateway.html) for use in the decentralized exchange, and wallets provide user interfaces for buying, selling, or just HODLing holding XRP. Many other possibilities exist, including additional services layered even higher. +Atop the stack is where the truly exciting things happen. Apps and services provide a way for users and devices to connect to the XRP Ledger. At this level, [exchanges list XRP](list-xrp-in-your-exchange.html), [gateways issue other currencies](become-an-xrp-ledger-gateway.html) for use in the decentralized exchange, and wallets provide user interfaces for buying, selling, or HODLing holding XRP. Many other possibilities exist, including additional services layered even higher. A great way to build applications that are compatible with not only XRP but lots of other ways of denominating value is to use the [Interledger Protocol][] with settlement in XRP. -There are numerous other examples of projects using XRP and adjacent technologies to interact with users. Ripple's enterprise customers already have the option to use XRP through [on-demand liquidity services](https://www.ripple.com/ripplenet/on-demand-liquidity/). For more examples of businesses and software built on the XRP Ledger, see [Xpring Partners](https://xpring.io/#partners) or XRPChat's excellent [Links & Resources](https://www.xrpchat.com/links/) listing. +There are many other examples of projects using XRP and adjacent technologies to interact with users. Ripple's enterprise customers already have the option to use XRP through [on-demand liquidity services](https://www.ripple.com/ripplenet/on-demand-liquidity/). For more examples of businesses and software built on the XRP Ledger, see [Xpring Partners](https://xpring.io/#partners) or XRPChat's excellent [Links & Resources](https://www.xrpchat.com/links/) listing. ## See Also diff --git a/content/concepts/introduction/technical-faq.md b/content/concepts/introduction/technical-faq.md index e857e7b41c..bb5cc7fe1a 100644 --- a/content/concepts/introduction/technical-faq.md +++ b/content/concepts/introduction/technical-faq.md @@ -22,7 +22,7 @@ They are the lists of transaction validators a given participant believes will n #### Which UNL should I select? -Since anybody can run a validator, the burden is on the network participants to choose a reliable set. Currently, Ripple provides a default and recommended list which we expand based on watching the history of validators operated by Ripple and third parties. Eventually, Ripple intends to remove itself from this process entirely by having network participants select their own lists based on publicly available data about validator quality. +Since anybody can run a validator, the burden is on the network participants to choose a reliable set. Currently, Ripple provides a default and recommended list which we expand based on watching the history of validators run by Ripple and third parties. Eventually, Ripple intends to remove itself from this process entirely by having network participants select their own lists based on publicly available data about validator quality. #### If Ripple recommends adoption of its UNL, doesn't that create a centralized system? @@ -34,12 +34,12 @@ No. The XRP Ledger network is opt-in. Each participant directly or indirectly ch The primary incentive to run a validator is to preserve and protect the stable operation and sensible evolution of the network. It is the validators who decide the evolution of the XRP Ledger, so any business that uses or depends on the XRP Ledger has an inherent incentive to ensure the reliability and stability of the network. -If you run an XRP Ledger server to participate in the network, the additional cost and effort to operate a validator is minimal. This means that additional incentives, such as the mining rewards in Bitcoin, are not necessary. Ripple avoids paying XRP as a reward for operating a validator so that such incentives do not warp the behavior of validators. +If you run an XRP Ledger server to participate in the network, the additional cost and effort to run a validator is minimal. This means that additional incentives, such as the mining rewards in Bitcoin, are not necessary. Ripple avoids paying XRP as a reward for operating a validator so that such incentives do not warp the behavior of validators. #### Can financial institutions set up transaction validators that will help them meet specific institutional standards and requirements? -No, institutions cannot set up customized validator policies for transaction selection. Validators either follow the protocol, or they do not. If software does not follow protocol rules, it will not function. Thus, it is not recommended that institutions seek out custom implementations without in-house expertise. +No, institutions cannot set up customized validator policies for choosing to allow some transactions and reject others. Validators either follow the protocol, or they do not. If software does not follow protocol rules, it will not function. Thus, it is not recommended that institutions seek out custom implementations without in-house expertise. #### What will happen if more than 20% of nodes within the network do not agree with the majority? How is the final version of the ledger chosen? @@ -63,7 +63,7 @@ For recommendations and best practices, see [Run `rippled` as a Validator](run-r #### Why does Ripple use XRP holdings? -Ripple's XRP holdings incentivize the company to make the XRP Ledger as useful as possible. XRP exists as a native asset in the XRP Ledger for anti-spam transaction purposes, and for currency bridging only if beneficial to users. Otherwise, the use of XRP in transactions is completely optional. +Ripple's XRP holdings incentivize the company to make the XRP Ledger as useful as possible. XRP exists as a native asset in the XRP Ledger for anti-spam transaction purposes, and for currency bridging only if beneficial to users. Otherwise, XRP is completely optional. #### How does the XRP Ledger respond to transaction floods? @@ -95,7 +95,7 @@ You don't need to use Ripple’s version of the XRP Ledger software to interact #### Does Ripple offer a secure method to download their software? -`rippled` source code is available at , where the tip of the `master`, `release` and `develop` branches always contains a version-setting commit signed by a `rippled` developer. The XRP Ledger also offers pre-built binary packages for CentOS, RedHat Enterprise Linux, Fedora, Ubuntu, and Debian Linux. Those packages are digitally signed by Ripple so that they are tamper-evident and their authenticity can be verified. Lastly, release bulletins are made available over a secure website, and include the commit ID of the repository, as well as the cryptographic hash values of the packages that are published. +`rippled` source code is available at , where the tip of the `master`, `release` and `develop` branches always contains a version-setting commit signed by a `rippled` developer. The XRP Ledger also offers pre-built binary packages for CentOS, RedHat Enterprise Linux, Fedora, Ubuntu, and Debian Linux. Those packages are digitally signed by Ripple so that they are tamper-evident and their authenticity can be verified. Lastly, release bulletins are made available over a secure website, and include the commit ID of the repository, as well as the cryptographic hash values of the packages that are published. #### Does Ripple distinguish between the codebase for validation and the one for user software? diff --git a/content/concepts/introduction/xrp-ledger-overview.md b/content/concepts/introduction/xrp-ledger-overview.md index 39c92de0f8..8c3e5acebc 100644 --- a/content/concepts/introduction/xrp-ledger-overview.md +++ b/content/concepts/introduction/xrp-ledger-overview.md @@ -4,7 +4,7 @@ The **XRP Ledger** is a decentralized cryptographic ledger powered by a network ## The Digital Asset for Payments -XRP is a digital asset native to the XRP Ledger. Anyone with a cryptographic key and an internet connection can receive, hold, and send XRP to anyone else. XRP's creators have developed it to be a desirable bridge currency that can facilitate trades in any other currency. XRP has many properties which make it an appealing asset for many other use cases, too: +XRP is a digital asset native to the XRP Ledger. Anyone with a cryptographic key and an internet connection can receive, hold, and send XRP to anyone else. XRP's creators have developed it to be a desirable bridge currency that can enable trades in any other currency. XRP has many properties which make it an appealing asset for many other use cases, too: - **[Censorship-Resistant Transaction Processing][]:** No single party decides which XRP transactions succeed or fail, and no one can "roll back" a transaction after it completes. As long as those who choose to participate in the network keep it healthy, they can send and receive XRP in seconds. - **[Fast, Efficient Consensus Algorithm][]:** The XRP Ledger's consensus algorithm settles transactions in 4 to 5 seconds, processing at a throughput of up to 1500 transactions per second. These properties put XRP at least an order of magnitude ahead of other top digital assets. @@ -28,7 +28,7 @@ This combines qualities of physical and centralized digital money. Prior to the **Note:** Users of the XRP Ledger _can_ freeze non-XRP currencies issued in the XRP Ledger. For more information, see the [Freeze documentation](freezes.html). -The XRP Ledger's system of trusted validators uses a small amount of human interaction to achieve better distribution of authority than other decentralized systems. Fully-automated systems for reaching consensus from an unknown set of participants are vulnerable to concentrations of voting power. For example, Bitcoin mining is disproportionately concentrated in places with cheap electricity. As Ripple curates a list of distinct validators operated by different entities in different jurisdictions, the XRP Ledger can become more resistant to censorship and outside pressures than proof-of-work mining. For more information on Ripple's plan to decentralize the recommended set of validators, see the [Decentralization Strategy Update](https://xrpl.org/blog/2017/decent-strategy-update.html). +The XRP Ledger's system of trusted validators uses a small amount of human interaction to achieve better distribution of authority than other decentralized systems. Fully-automated systems for reaching consensus from an unknown set of participants are vulnerable to concentrations of voting power. For example, Bitcoin mining is disproportionately concentrated in places with cheap electricity. As Ripple curates a list of distinct validators run by different entities in different jurisdictions, the XRP Ledger can become more resistant to censorship and outside pressures than proof-of-work mining. For more information on Ripple's plan to decentralize the recommended set of validators, see the [Decentralization Strategy Update](https://xrpl.org/blog/2017/decent-strategy-update.html). For more information about the XRP Ledger's ability to detect censorship, see [Transaction Censorship Detection](transaction-censorship-detection.html). @@ -79,7 +79,7 @@ For more information, see [Cryptographic Keys](cryptographic-keys.html) and [Mul ## Modern Features for Smart Contracts [Modern Features for Smart Contracts]: #modern-features-for-smart-contracts -Besides simple value transfer with [XRP payments](direct-xrp-payments.html), the XRP Ledger has advanced features specialized for the Internet of Value. This allows applications built on XRP to provide services and functionality that would have been impractical or impossible in the past. Rather than running applications as "smart contracts" in the network itself, the XRP Ledger provides tools for settling contracts, while letting the applications themselves run anywhere, in whatever environment or container is appropriate. This "keep it simple" approach is flexible, scalable, and powerful. +Besides direct value transfer with [XRP payments](direct-xrp-payments.html), the XRP Ledger has advanced features specialized for the Internet of Value. This allows applications built on XRP to provide services and functionality that would have been impractical or impossible in the past. Rather than running applications as "smart contracts" in the network itself, the XRP Ledger provides tools for settling contracts, while letting the applications themselves run anywhere, in whatever environment or container is appropriate. This "keep it simple" approach is flexible, scalable, and powerful. A sample of advanced features in the XRP Ledger: diff --git a/content/concepts/issued-currencies/authorized-trust-lines.md b/content/concepts/issued-currencies/authorized-trust-lines.md index 4cc6de80eb..910f662e8c 100644 --- a/content/concepts/issued-currencies/authorized-trust-lines.md +++ b/content/concepts/issued-currencies/authorized-trust-lines.md @@ -2,9 +2,9 @@ The XRP Ledger's Authorized Trust Lines feature enables a currency issuer to limit who can hold its issued (non-XRP) currencies, so that unknown XRP Ledger addresses cannot hold those currencies. The Authorized Trust Lines feature only applies to issued currencies and has no effect on XRP. -To use the Authorized Trust Lines feature, enable the RequireAuth flag on your issuing address. After doing so, your issuing address can send [TrustSet transactions][] to authorize trust lines from other addresses. While RequireAuth is enabled, other addresses can only hold funds issued by your address if the trust line to your issuing address has been authorized. +To use the Authorized Trust Lines feature, enable the `RequireAuth` flag on your issuing address. After doing so, your issuing address can send [TrustSet transactions][] to authorize trust lines from other addresses. While RequireAuth is enabled, other addresses can only hold funds issued by your address if the trust line to your issuing address has been authorized. -The transaction to authorize a trust line must be signed by the issuing address, which unfortunately means an increased risk exposure for that address. The process for sending funds into the XRP Ledger with RequireAuth enabled looks like the following: +The transaction to authorize a trust line must be signed by the issuing address, which unfortunately means an increased risk exposure for that address. The process for sending funds into the XRP Ledger with `RequireAuth` enabled looks like the following: 1. An issuing gateway publishes its issuing address to customers. 2. A customer sends a [TrustSet transaction][] to create a trust line from her XRP Ledger address to the gateway's issuing address. This indicates that she is willing to hold a specific currency issued by the gateway, up to a specific numeric limit. @@ -14,6 +14,8 @@ The transaction to authorize a trust line must be signed by the issuing address, ## RequireAuth Setting + + The `RequireAuth` setting (`requireAuthorization` in [RippleAPI](rippleapi-reference.html)) prevents all counterparties from holding balances issued by an address unless the issuing address has specifically approved a trust line with that counterparty for the currency in question. As a precaution, Ripple recommends that issuing gateways always enable `RequireAuth` on [operational addresses and standby addresses](issuing-and-operational-addresses.html), and then never approve any trust lines to those addresses. This prevents operational addresses and standby addresses from issuing currency in the XRP Ledger even by accident. This is a purely precautionary measure, and does not stop those addresses from transferring issued currency balances created by the issuing address, as they are intended to do. @@ -24,7 +26,7 @@ To use the Authorized Trust Lines feature, an issuer must also enable `RequireAu ### Enabling RequireAuth -The following is an example of using a locally-hosted `rippled`'s [submit method][] to send an [AccountSet transaction][] to enable the RequireAuth flag: (This method works the same way regardless of whether the address is an issuing address, operational address, or standby address.) +The following is an example of using a locally-hosted `rippled`'s [submit method][] to send an [AccountSet transaction][] to enable the `RequireAuth` flag: (This method works the same way regardless of whether the address is an issuing address, operational address, or standby address.) Request: @@ -52,22 +54,23 @@ POST http://localhost:5005/ ## Checking Whether an Account Has RequireAuth Enabled -To see whether an account has the RequireAuth setting enabled, use the [account_info method][] to look up the account. Compare the value of the `Flags` field (in the `result.account_data` object) with the [bitwise flags defined for an AccountRoot ledger object](accountroot.html). +To see whether an account has the `RequireAuth` setting enabled, use the [account_info method][] to look up the account. Compare the value of the `Flags` field (in the `result.account_data` object) with the [bitwise flags defined for an AccountRoot ledger object](accountroot.html). -If the result of the `Flags` value bitwise-AND the `lsfRequireAuth` flag value (0x00040000) is nonzero, then the account has RequireAuth enabled. If the result is zero, then the account has RequireAuth disabled. +If the result of the `Flags` value bitwise-AND the `lsfRequireAuth` flag value (`0x00040000`) is nonzero, then the account has `RequireAuth` enabled. If the result is zero, then the account has `RequireAuth` disabled. ## Authorizing Trust Lines If you are using the Authorized Trust Lines feature, others cannot hold balances you issue unless you first authorize their trust lines to you. If you issue more than one currency, you must separately authorize trust lines for each currency. -To authorize a trust line, submit a [TrustSet transaction][] from your issuing address, with the user to trust as the `issuer` of the `LimitAmount`. Leave the `value` (the amount to trust them for) as **0**, and enable the [tfSetfAuth](trustset.html#trustset-flags) flag for the transaction. +To authorize a trust line, submit a [TrustSet transaction][] from your issuing address, with the user to trust as the `issuer` of the `LimitAmount`. Leave the `value` (the amount to trust them for) as **0**, and enable the [`tfSetfAuth`](trustset.html#trustset-flags) flag for the transaction. -The following is an example of using a locally-hosted `rippled`'s [submit method][] to send a TrustSet transaction authorizing the customer address rf1BiGeXwwQoi8Z2ueFYTEXSwuJYfV2Jpn to hold issuances of USD from the issuing address rsA2LpzuawewSBQXkiju3YQTMzW13pAAdW: +The following is an example of using a locally-hosted `rippled`'s [submit method][] to send a TrustSet transaction authorizing the customer address `rf1BiGeXwwQoi8Z2ueFYTEXSwuJYfV2Jpn` to hold USD issued by the address `rsA2LpzuawewSBQXkiju3YQTMzW13pAAdW`: Request: -``` +```json POST http://localhost:8088/ + { "method": "submit", "params": [ diff --git a/content/concepts/issued-currencies/demurrage.md b/content/concepts/issued-currencies/demurrage.md index 12665fb337..edacd8288d 100644 --- a/content/concepts/issued-currencies/demurrage.md +++ b/content/concepts/issued-currencies/demurrage.md @@ -27,7 +27,7 @@ D = A × ( e ^ (t ÷ τ) ) - **A** is the pre-demurrage amount as recorded in the global ledger - **e** is Euler's number - **t** is the number of seconds since the Ripple Epoch (0:00 on January 1, 2000 UTC) -- **τ** is the e-folding time in seconds. This value is [calculated from the desired interest rate](#calculating-e-folding-time). +- **τ** is the e-folding time in seconds. This value is [calculated from the desired interest rate](#calculating-e-folding-time). To convert between display amounts and ledger amounts, you can use the following steps: diff --git a/content/concepts/issued-currencies/freezes.md b/content/concepts/issued-currencies/freezes.md index f6d21b0ff9..5581483029 100644 --- a/content/concepts/issued-currencies/freezes.md +++ b/content/concepts/issued-currencies/freezes.md @@ -2,7 +2,7 @@ XRP is not an issued currency. XRP is the only native asset on the XRP Ledger and is required in order to conduct transactions on the XRP Ledger. XRP is counterparty free, meaning that when someone holds XRP, they are not holding a liability, they are holding the actual currency, XRP. Due to this fact, _**XRP CANNOT be frozen by any entity or individual**_. -All non-XRP currencies can be represented in the XRP Ledger as issued currencies. These issued currencies (sometimes called "issuances" or "IOUs") are tracked in accounting relationships, called "trust lines," between addresses. Issued currencies are typically considered as liabilities from one perspective and assets from the other, so the balance of a trust line is negative or positive depending on which side you view it from. Any address may freely issue (non-XRP) currencies, limited only by how much other addresses are willing to hold. +All non-XRP currencies can be represented in the XRP Ledger as issued currencies. These issued currencies (sometimes called "IOUs") are tracked in accounting relationships, called "trust lines," between addresses. Issued currencies are typically considered as liabilities from one perspective and assets from the other, so the balance of a trust line is negative or positive depending on which side you view it from. Any address may freely issue (non-XRP) currencies, limited only by how much other addresses are willing to hold. In certain cases, to meet regulatory requirements, or while investigating suspicious activity, an exchange or gateway may want to quickly freeze non-XRP issued currency balances. @@ -24,15 +24,15 @@ All freeze settings can be enacted regardless of whether the balance(s) to be fr The **Individual Freeze** feature is a setting on a [trust line](trust-lines-and-issuing.html). When an issuing address enables the Individual Freeze setting, the following rules apply to the currency of that trust line: * Payments can still occur directly between the two parties of the frozen trust line. -* The counterparty of that trust line can no longer decrease its balance on the frozen trust line, except in direct payments to the issuer. The counterparty can only send the frozen issuances directly to the issuer. +* The counterparty of that trust line can no longer decrease its balance on the frozen trust line, except in direct payments to the issuer. The counterparty can only send the frozen currencies directly to the issuer. * The counterparty can still receive payments from others on the frozen trust line. * The counterparty's offers to sell the currency issued on the frozen trust line are [considered unfunded](offers.html#lifecycle-of-an-offer). Reminder: Trust lines do not hold XRP. XRP cannot be frozen. -A financial institution can freeze the trust line linking it to a counterparty if that counterparty shows suspicious activity or violates the financial institution's terms of use. The financial institution should also freeze the counterparty in any other systems the financial institution operates that are connected to the XRP Ledger. (Otherwise, an address might still be able to engage in undesired activity by sending payments through the financial institution.) +A financial institution can freeze the trust line linking it to a counterparty if that counterparty shows suspicious activity or violates the financial institution's terms of use. The financial institution should also freeze the counterparty in any other systems the financial institution uses that are connected to the XRP Ledger. (Otherwise, an address might still be able to engage in undesired activity by sending payments through the financial institution.) -An individual address can freeze its trust line to a financial institution. This has no effect on transactions between the institution and other users. It does, however, prevent other addresses, including [operational addresses](issuing-and-operational-addresses.html), from sending that financial institution's issuances to the individual address. This type of individual freeze has no effect on offers. +An individual address can freeze its trust line to a financial institution. This has no effect on transactions between the institution and other users. It does, however, prevent other addresses, including [operational addresses](issuing-and-operational-addresses.html), from sending that financial institution's issued currencies to the individual address. This type of individual freeze has no effect on offers. The Individual Freeze applies to a single currency only. To freeze multiple currencies with a particular counterparty, the address must enable Individual Freeze on the trust lines for each currency individually. @@ -336,12 +336,12 @@ To see if an address has enabled Global Freeze, No Freeze, or both, use the [acc Check the value of the `account_data.Flags` field of the response using the [bitwise-AND](https://en.wikipedia.org/wiki/Bitwise_operation#AND) operator: -* If `Flags` AND `0x00400000` ([lsfGlobalFreeze](accountroot.html#accountroot-flags)) is _nonzero_: Global Freeze is enabled. -* If `Flags` AND `0x00200000` ([lsfNoFreeze](accountroot.html#accountroot-flags)) is _nonzero_: No Freeze is enabled. +* If `Flags` AND `0x00400000` ([`lsfGlobalFreeze`](accountroot.html#accountroot-flags)) is _nonzero_: Global Freeze is enabled. +* If `Flags` AND `0x00200000` ([`lsfNoFreeze`](accountroot.html#accountroot-flags)) is _nonzero_: No Freeze is enabled. Example WebSocket request: -``` +```json { "id": 1, "command": "account_info", @@ -352,7 +352,7 @@ Example WebSocket request: WebSocket response: -``` +```json { "id": 4, "status": "success", @@ -382,7 +382,7 @@ WebSocket response: } ``` -In the above example, the `Flags` value is 12582912. This indicates that has the following flags enabled: lsfGlobalFreeze, lsfDefaultRipple, as demonstrated by the following JavaScript code: +In the above example, the `Flags` value is 12582912. This indicates that has the following flags enabled: `lsfGlobalFreeze`, `lsfDefaultRipple`, as demonstrated by the following JavaScript code: ```js var lsfGlobalFreeze = 0x00400000; diff --git a/content/concepts/issued-currencies/issued-currencies-overview.md b/content/concepts/issued-currencies/issued-currencies-overview.md index 6f02d738a7..6767bd39d1 100644 --- a/content/concepts/issued-currencies/issued-currencies-overview.md +++ b/content/concepts/issued-currencies/issued-currencies-overview.md @@ -2,7 +2,7 @@ All currencies other than XRP can be represented in the XRP Ledger as **issued currencies**. These digital assets (sometimes called "IOUs") are tracked in accounting relationships, called "trust lines," between addresses. Issued currencies are typically considered as liabilities from one perspective and assets from the other, so the balance of a trust line is negative or positive depending on which side you view it from. Any address may freely issue (non-XRP) currencies, limited only by how much other addresses are willing to hold. -Issued currencies can "ripple" through multiple issuers and holders if they use the same currency code. This is useful in some cases, but can cause unexpected and undesirable behavior in others. You can use the [NoRipple flag](rippling.html) on trust lines to prevent those trust lines from rippling. +Issued currencies can "ripple" through multiple issuers and holders if they use 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) on trust lines to prevent those trust lines from rippling. Issued currencies can be traded with XRP or each other in the XRP Ledger's decentralized exchange. diff --git a/content/concepts/issued-currencies/issuing-and-operational-addresses.md b/content/concepts/issued-currencies/issuing-and-operational-addresses.md index ed5ee0de10..1ece84b2c8 100644 --- a/content/concepts/issued-currencies/issuing-and-operational-addresses.md +++ b/content/concepts/issued-currencies/issuing-and-operational-addresses.md @@ -9,9 +9,9 @@ All non-XRP balances in the XRP Ledger are _issued currencies_ which are tied to [![Diagram: Funds flow from the issuing address to standby addresses, to operational addresses, to customer and partner addresses, and finally back to the issuing address.](img/funds_flow_diagram.png)](img/funds_flow_diagram.png) -When the issuing address sends payments, it creates balances in the accounting relationships in the XRP Ledger. Within the XRP Ledger, users can exchange balances across different accounting relationships, so we use the term _issuances_ to describe any non-XRP balance. Issuances have negative value from the perspective of the issuing address, since they represent obligations. The same issuances have positive value from the perspective of the issuing address's counterparties. When the issuing address receives a payment, this reduces its obligations, erasing the issuances that were sent. +When the issuing address sends payments, it creates balances in the accounting relationships in the XRP Ledger. Within the XRP Ledger, users can exchange balances across different accounting relationships, so we use the term _issued currency_ to describe any non-XRP balance. (These can represent any type of value, not only "currencies" in the traditional sense.) Issued currencies have negative value from the perspective of the issuing address, since they represent obligations. The same issued currencies have positive value from the perspective of the issuing address's counterparties. When the issuing address receives a payment, this reduces its obligations, erasing the issued currencies that were sent. -The issuing address sends issuances to a standby address, or directly to an operational address. The standby addresses send those issuances to operational addresses. Operational addresses send payments to other counterparties, such as liquidity providers, partners, and other customers. Because all issuances are tied to accounting relationships with the issuing address, payments and exchanges of issuances "ripple through" the issuing address. The payment debits the sender's balance in its accounting relationship with the issuing address and credits the recipient's balance in the recipient's accounting relationship with the issuing address. The XRP Ledger also supports more complicated [paths](paths.html) that connect multiple issuers through order books and [liquidity providers who allow their funds to ripple](rippling.html). +The issuing address sends issued currencies to a standby address, or directly to an operational address. The standby addresses send those issued currencies to operational addresses. Operational addresses send payments to other counterparties, such as liquidity providers, partners, and other customers. Because all issued currencies are tied to accounting relationships with the issuing address, payments and exchanges of issued currencies "ripple through" the issuing address. The payment debits the sender's balance in its accounting relationship with the issuing address and credits the recipient's balance in the recipient's accounting relationship with the issuing address. The XRP Ledger also supports more complicated [paths](paths.html) that connect multiple issuers through order books and [liquidity providers who allow their funds to ripple](rippling.html). ## Issuing Address @@ -21,7 +21,7 @@ Unlike a vault, the issuing address can receive payments directly from customers ### Issuing Address Compromise -If a malicious actor learns the secret key behind a institution's issuing address, that actor can create new issuances without limit and trade them in the decentralized exchange. This would make it difficult for the financial institution to distinguish legitimately-obtained issuances and redeem them fairly. If a financial institution loses control of its issuing address, the institution must create a new issuing address, and all users who have accounting relationships with the old issuing address must create new accounting relationships with the new address. +If a malicious actor learns the secret key behind a institution's issuing address, that actor can create new issued currencies without limit and trade them in the decentralized exchange. This would make it difficult for the financial institution to distinguish legitimately-obtained issued currencies and redeem them fairly. If a financial institution loses control of its issuing address, the institution must create a new issuing address, and all users who have accounting relationships with the old issuing address must create new accounting relationships with the new address. ### Multiple Issuing Addresses @@ -30,9 +30,9 @@ A financial institution can issue more than one currency in the XRP Ledger from ## Operational Addresses -An operational address is like a cash register. It makes payments on behalf of the institution by transferring issuances to customers and partners. To sign transactions automatically, the secret key for an operational address must be stored on a server that is connected to the internet. (The secret key can be stored encrypted, but the server must decrypt it to sign transactions.) Customers and partners do not, and should not, create accounting relationships with an operational address. +An operational address is like a cash register. It makes payments on behalf of the institution by transferring issued currencies to customers and partners. To sign transactions automatically, the secret key for an operational address must be stored on a server that is connected to the internet. (The secret key can be stored encrypted, but the server must decrypt it to sign transactions.) Customers and partners do not, and should not, create accounting relationships with an operational address. -Each operational address has a limited balance of issuances. When the balance of an operational address gets low, the financial institution refills it by sending a payment from the issuing address or a standby address. +Each operational address has a limited balance of issued currencies. When the balance of an operational address gets low, the financial institution refills it by sending a payment from the issuing address or a standby address. ### Operational Address Compromise diff --git a/content/concepts/issued-currencies/paths.md b/content/concepts/issued-currencies/paths.md index 04dda0ecaf..a832de6d14 100644 --- a/content/concepts/issued-currencies/paths.md +++ b/content/concepts/issued-currencies/paths.md @@ -13,7 +13,7 @@ A path is made of steps that connect the sender to the receiver of the payment. * Rippling through another address with the same currency * Exchanging currency at an order book -Rippling through another address is the process of moving debt around. In the typical case, this involves reducing an issuer's obligation to one party and increasing the obligation to another party. Rippling can occur between any addresses that are connected by trust lines. See [Understanding the NoRipple Flag](rippling.html) for more examples of rippling. +Rippling through another address is the process of moving debt around. In the typical case, this involves reducing an issuer's obligation to one party and increasing the obligation to another party. Rippling can occur between any addresses that are connected by trust lines. See [Understanding the No Ripple Flag](rippling.html) for more examples of rippling. In the case of a currency exchange step, the path step specifies which currency to change to, but does not record the state of the Offers in the order book. The canonical order of transactions is not final until a ledger is validated, so you cannot know for certain which Offers a transaction will take, until after the transaction has been validated. (You can make an educated guess, since each transaction takes the best available Offers at the time it executes in the final ledger.) @@ -42,7 +42,7 @@ By convention, several steps of a path are implied by the [fields of the Payment * The first step of a path is always implied to be the sender of the transaction, as defined by the transaction's `Account` field. * If the transaction includes a `SendMax` field with an `issuer` that is not the sender of the transaction, that issuer is implied to be the second step of the path. - * If `issuer` of the `SendMax` _is_ the sending address, then the path starts at the sending address, and may use any of that address's trust lines in the given currency. See [special values for SendMax and Amount](payment.html#special-issuer-values-for-sendmax-and-amount) for details. + * If `issuer` of the `SendMax` _is_ the sending address, then the path starts at the sending address, and may use any of that address's trust lines in the given currency. See [special values for `SendMax` and `Amount`](payment.html#special-issuer-values-for-sendmax-and-amount) for details. * If the `Amount` field of the transaction includes an `issuer` that is not the same as the `Destination` of the transaction, that issuer is implied to be the second-to-last step of the path. * Finally, last step of a path is always implied to be the receiver of a transaction, as defined by the transaction's `Destination` field. @@ -89,9 +89,9 @@ The `type` field, used for the binary serialization of a path set, is actually c | Value (Hex) | Value (Decimal) | Description | |-------------|-----------------|-------------| -| 0x01 | 1 | A change of address (rippling): the `account` field is present. | -| 0x10 | 16 | A change of currency: the `currency` field is present. | -| 0x20 | 32 | A change of issuer: the `issuer` field is present. | +| `0x01` | 1 | A change of address (rippling): the `account` field is present. | +| `0x10` | 16 | A change of currency: the `currency` field is present. | +| `0x20` | 32 | A change of issuer: the `issuer` field is present. | ## See Also diff --git a/content/concepts/issued-currencies/rippling.md b/content/concepts/issued-currencies/rippling.md index 2270375949..b3cf3bf61c 100644 --- a/content/concepts/issued-currencies/rippling.md +++ b/content/concepts/issued-currencies/rippling.md @@ -4,9 +4,9 @@ In the XRP Ledger, "rippling" describes a process of atomic net settlement betwe Rippling only occurs along the [paths](paths.html) of a payment. [Direct XRP-to-XRP payments](direct-xrp-payments.html) do not involve rippling. -For non-issuing accounts, rippling can be undesirable because it lets other users shift obligations between issuers of the same currency. Thus, the [NoRipple Flag](#the-noripple-flag) disables rippling on incoming trust lines by default, unless the account enables rippling by default by enabling the [DefaultRipple flag](#the-defaultripple-flag). +For non-issuing accounts, rippling can be undesirable because it lets other users shift obligations between issuers of the same currency. Thus, the [No Ripple Flag](#the-noripple-flag) disables rippling on incoming trust lines by default, unless the account enables rippling by default by enabling the [Default Ripple flag](#the-default-ripple-flag). -**Caution:** If you create a trust line to another address, you must explicitly enable the tfSetNoRipple flag to block rippling on your side of that trust line. +**Caution:** If you create a trust line to another address, you must explicitly enable the `tfSetNoRipple` flag to block rippling on your side of that trust line. ## Example of Rippling @@ -20,13 +20,13 @@ If Bob wants to pay $3 to Charlie, then he could say, "Alice, take $3 of the mon We call this process, where two addresses pay each other by adjusting the balances of trust lines in between them, "rippling". This is a useful and important feature of the XRP Ledger. Rippling occurs when addresses are linked by trust lines that use the same [currency code][]. The issuer does not need to be the same: in fact, larger chains always involve changing issuers. -## The NoRipple Flag +## The No Ripple Flag Non-issuing accounts, especially liquidity providers who may hold balances from different issuers with different fees and policies, usually do not want their balances to ripple. -The "NoRipple" flag is a setting on a trust line. When two trust lines both have NoRipple enabled by the same address, payments from third parties cannot "ripple" through that address on those trust lines. This protects liquidity providers from having balances shift unexpectedly between different issuers of the same currency. +The **No Ripple** flag is a setting on a trust line. When two trust lines both have No Ripple enabled by the same address, payments from third parties cannot "ripple" through that address on those trust lines. This protects liquidity providers from having balances shift unexpectedly between different issuers of the same currency. -An account can disable NoRipple on a single trust line, which can allow rippling through any pair that includes that trust line. The account can also enable rippling by default by enabling the [DefaultRipple flag](#the-defaultripple-flag). +An account can disable No Ripple on a single trust line, which can allow rippling through any pair that includes that trust line. The account can also enable rippling by default by enabling the [Default Ripple flag](#the-default-ripple-flag). For example, imagine Emily has money issued by two different financial institutions, like so @@ -36,49 +36,49 @@ Now Charlie can pay Daniel by rippling through Emily's address. For example, if ![Charlie --($0)-- Institution A --($11)-- Emily --($90)-- Institution B --($12)-- Daniel](img/noripple-04.png) -This may surprise Emily, who does not know Charlie or Daniel. Even worse, if Institution A charges her higher fees to withdraw her money than Institution B, this could cost Emily money. The NoRipple flag exists to avoid this scenario. If Emily sets it on both trust lines, then payments cannot ripple through her address using those two trust lines. +This may surprise Emily, who does not know Charlie or Daniel. Even worse, if Institution A charges her higher fees to withdraw her money than Institution B, this could cost Emily money. The No Ripple flag exists to avoid this scenario. If Emily sets it on both trust lines, then payments cannot ripple through her address using those two trust lines. For example: -![Charlie --($10)-- Institution A --($1, NoRipple)-- Emily --($100,NoRipple)-- Institution B --($2)-- Daniel](img/noripple-05.png) +![Charlie --($10)-- Institution A --($1, No Ripple)-- Emily --($100,No Ripple)-- Institution B --($2)-- Daniel](img/noripple-05.png) Now the above scenario, where Charlie pays Daniel while rippling through Emily's address, is no longer possible. ### Specifics -The NoRipple flag makes certain paths invalid, so that they cannot be used to make payments. A path is considered invalid if and only if it enters **and** exits an address node through trust lines where NoRipple has been enabled for that address. +The No Ripple flag makes certain paths invalid, so that they cannot be used to make payments. A path is considered invalid if and only if it enters **and** exits an address node through trust lines where No Ripple has been enabled for that address. -![Diagram demonstrating that NoRipple has to be set on both trust lines by the same address to do anything](img/noripple-06.png) +![Diagram demonstrating that No Ripple has to be set on both trust lines by the same address to do anything](img/noripple-06.png) -## The DefaultRipple Flag +## The Default Ripple Flag -The DefaultRipple flag is an account setting that enables rippling on all incoming trust lines by default. Gateways and other currency issuers MUST enable this flag for their customers to be able to send those currencies to each other. +The **Default Ripple** flag is an account setting that enables rippling on all incoming trust lines by default. Gateways and other currency issuers MUST enable this flag for their customers to be able to send those currencies to each other. -The DefaultRipple setting of your account does not affect trust lines that you create; only trust lines that others open to you. If you change the DefaultRipple setting of your account, trust lines that were created before the change keep their existing NoRipple settings. You can use a [TrustSet transaction][] to change the NoRipple setting of a trust line to match your address's new default. +The Default Ripple setting of your account does not affect trust lines that you create; only trust lines that others open to you. If you change the Default Ripple setting of your account, trust lines that were created before the change keep their existing No Ripple settings. You can use a [TrustSet transaction][] to change the No Ripple setting of a trust line to match your address's new default. -For more information, see [DefaultRipple in 'Becoming an XRP Ledger Gateway'](become-an-xrp-ledger-gateway.html#defaultripple). +For more information, see [Default Ripple in 'Becoming an XRP Ledger Gateway'](become-an-xrp-ledger-gateway.html#defaultripple). -## Using NoRipple +## Using No Ripple -### Enabling / Disabling NoRipple +### Enabling / Disabling No Ripple -The NoRipple flag can only be enabled on a trust line if the address has a positive or zero balance on that trust line. This is so that the feature cannot be abused to default on the obligation the trust line balance represents. (Of course, you can still default by abandoning the address.) +The No Ripple flag can only be enabled on a trust line if the address has a positive or zero balance on that trust line. This is so that the feature cannot be abused to default on the obligation the trust line balance represents. (Of course, you can still default by abandoning the address.) -In the [`rippled` APIs](rippled-api.html), you can enable the NoRipple flag by sending a [TrustSet transaction][] with the `tfSetNoRipple` flag. You can disable NoRipple (enable rippling) with the `tfClearNoRipple` flag. +In the [`rippled` APIs](rippled-api.html), you can enable the No Ripple flag by sending a [TrustSet transaction][] with the `tfSetNoRipple` flag. You can disable No Ripple (enable rippling) with the `tfClearNoRipple` flag. -In [RippleAPI](rippleapi-reference.html), you can enable the NoRipple flag by sending a [Trustline transaction](rippleapi-reference.html#preparetrustline) transaction with the `ripplingDisabled` field of the trust line set to `true`. +In [RippleAPI](rippleapi-reference.html), you can enable the No Ripple flag by sending a [Trustline transaction](rippleapi-reference.html#preparetrustline) transaction with the `ripplingDisabled` field of the trust line set to `true`. -### Looking Up NoRipple Status +### Looking Up No Ripple Status -In the case of two accounts that mutually trust each other, the NoRipple flag is tracked separately for each account. +In the case of two accounts that mutually trust each other, the No Ripple flag is tracked separately for each account. -In the [`rippled` APIs](rippled-api.html), you can use the [account_lines method][] to look up the trust lines associated with an address. For each trust line, the `no_ripple` field shows whether the current address has enabled the NoRipple flag on that trust line, and the `no_ripple_peer` field shows whether the counterparty has enabled the NoRipple flag. +In the [`rippled` APIs](rippled-api.html), you can use the [account_lines method][] to look up the trust lines associated with an address. For each trust line, the `no_ripple` field shows whether the current address has enabled the No Ripple flag on that trust line, and the `no_ripple_peer` field shows whether the counterparty has enabled the No Ripple flag. -In [RippleAPI](rippleapi-reference.html), you can use the [getTrustlines](rippleapi-reference.html#gettrustlines) method to look up the trust lines associated with an address. For each trust line, the `ripplingDisabled` field shows whether the current address has enabled the NoRipple flag on that trust line, and the `counterparty.ripplingDisabled` field shows whether the counterparty has enabled the NoRipple flag. +In [RippleAPI](rippleapi-reference.html), you can use the [`getTrustlines` method](rippleapi-reference.html#gettrustlines) to look up the trust lines associated with an address. For each trust line, the `ripplingDisabled` field shows whether the current address has enabled the No Ripple flag on that trust line, and the `counterparty.ripplingDisabled` field shows whether the counterparty has enabled the No Ripple flag. ## See Also diff --git a/content/concepts/issued-currencies/transfer-fees.md b/content/concepts/issued-currencies/transfer-fees.md index 1bad083325..7b7a41113d 100644 --- a/content/concepts/issued-currencies/transfer-fees.md +++ b/content/concepts/issued-currencies/transfer-fees.md @@ -7,7 +7,7 @@ The `TransferRate` setting in the XRP Ledger allows [financial institutions that XRP never has a transfer fee, because it never has an issuer. -For example, ACME Bank might set the transfer fee to 1% for ACME issuances. For the recipient of a payment to get 2 EUR.ACME, the sender must send 2.02 EUR.ACME. After the transaction, ACME's outstanding obligations in the XRP Ledger have decreased by 0.02€, which means that ACME no longer needs to hold that amount in the account backing its XRP Ledger issuances. +For example, ACME Bank might set the transfer fee to 1%. For the recipient of a payment to get 2 EUR.ACME, the sender must send 2.02 EUR.ACME. After the transaction, ACME's outstanding obligations in the XRP Ledger have decreased by 0.02€, which means that ACME no longer needs to hold that amount in the account backing its issued currencies. The following diagram shows an XRP Ledger payment of 2 EUR.ACME from Alice to Charlie with a transfer fee of 1%: @@ -17,7 +17,7 @@ The following diagram shows an XRP Ledger payment of 2 EUR.ACME from Alice to Ch -A transfer fee applies whenever an individual transfer would shift issuances from one party to another through the issuing account. In more complex transactions, this can occur multiple times. Transfer fees apply starting from the end and working backwards, so that ultimately the sender of a payment must send enough to account for all fees. For example: +A transfer fee applies whenever an individual transfer would move issued currency from one party to another through the issuing account. In more complex transactions, this can occur multiple times. Transfer fees apply starting from the end and working backwards, so that ultimately the sender of a payment must send enough to account for all fees. For example: ![Diagram of cross-currency payment with transfer fees](img/transfer_fees_example.png) @@ -27,25 +27,27 @@ In this scenario, Salazar (the sender) holds EUR issued by ACME, and wants to de * FXMaker's current ask is 90.18 EUR.ACME to send 100.20 USD.WayGate. * For FXMaker to receive 90.18 EUR.ACME, Salazar must send 91.0818 EUR.ACME. + + # Technical Details -The transfer fee is represented by a setting on the [issuing address][]. The transfer fee cannot be less than 0% or more than 100% and is rounded down to the nearest 0.0000001%. The TransferRate setting applies to all currencies issued by the same account. If you want to have different transfer fee percentages for different currencies, use different [issuing addresses][issuing address] for each currency. +The transfer fee is represented by a setting on the [issuing address][]. The transfer fee cannot be less than 0% or more than 100% and is rounded down to the nearest 0.0000001%. The transfer fee applies to all currencies issued by the same account. If you want to have different transfer fees for different currencies, use different [issuing addresses][issuing address] for each currency. -**Note:** The [fix1201 amendment](amendments.html), introduced in `rippled` v0.80.0 and enabled on 2017-11-14, lowered the maximum transfer fee to 100% from an effective limit of approximately 329% (based on the maximum size of a 32-bit integer). The ledger may still contain accounts with a transfer fee setting higher than 100% (a `TransferRate` of `2000000000`). Any transfer fees already set continue to operate at their stated rate. +**Note:** The [fix1201 amendment](amendments.html), introduced in `rippled` v0.80.0 and enabled on 2017-11-14, lowered the maximum transfer fee to 100% from an effective limit of approximately 329% (based on the maximum size of a 32-bit integer). The ledger may still contain accounts with a transfer fee setting higher than 100% (a `TransferRate` of `2000000000`). Any transfer fees already set continue to apply at their stated rate. ## RippleAPI In RippleAPI, the transfer fee is specified in the `transferRate` field, as a decimal which represents the amount you must send for the recipient to get 1 unit of the same currency. A `transferRate` of `1.005` is equivalent to a transfer fee of 0.5%. By default, the `transferRate` is set to no fee. The value of `transferRate` cannot be less than `1.0` or more than `2.0`. The transfer rate is rounded to 10 significant digits including the ones digit. The value `null` is a special case for no fee, equivalent to `1.0`. -A financial institution can send a [Settings transaction](rippleapi-reference.html#settings) from its [issuing address][] to change the `transferRate` for its issuances. +A financial institution can send a [Settings transaction](rippleapi-reference.html#settings) from its [issuing address][] to change the `transferRate` for all its issued currencies. -You can check an account's `transferRate` with the [getSettings method](rippleapi-reference.html#getsettings). +You can check an account's `transferRate` with the [`getSettings` method](rippleapi-reference.html#getsettings). ## rippled In `rippled`'s JSON-RPC and WebSocket APIs, the transfer fee is specified in the `TransferRate` field, as an integer which represents the amount you must send for the recipient to get 1 billion units of the same currency. A `TransferRate` of `1005000000` is equivalent to a transfer fee of 0.5%. By default, the `TransferRate` is set to no fee. The value of `TransferRate` cannot be set to less than `1000000000` ("0%" fee) or more than `2000000000` (a "100%" fee). The value `0` is special case for no fee, equivalent to `1000000000`. -A financial institution can submit an [AccountSet transaction][] from its [issuing address][] to change the `TransferRate` for its issuances. +A financial institution can submit an [AccountSet transaction][] from its [issuing address][] to change the `TransferRate` for all its issued currencies. You can check an account's `TransferRate` with the [account_info method][]. If the `TransferRate` is omitted, then that indicates no fee. diff --git a/content/concepts/issued-currencies/trust-lines-and-issuing.md b/content/concepts/issued-currencies/trust-lines-and-issuing.md index 7a839bb786..40d50503c7 100644 --- a/content/concepts/issued-currencies/trust-lines-and-issuing.md +++ b/content/concepts/issued-currencies/trust-lines-and-issuing.md @@ -1,6 +1,6 @@ # Trust Lines and Issuing -Frequently, [issued currencies](issued-currencies.html) in the XRP Ledger, represent value held by _gateways_ in the world outside the XRP Ledger. The address that issues those funds in the XRP Ledger is expected to pay the balance back, outside of the XRP Ledger, when users redeem their XRP Ledger balances by returning them to the issuer. +[Issued currencies](issued-currencies.html) in the XRP Ledger often represent value held by _gateways_ in the world outside the XRP Ledger. The address that issues those funds in the XRP Ledger is expected to pay the balance back, outside of the XRP Ledger, when users redeem their XRP Ledger balances by returning them to the issuer. Since a computer program cannot force a someone to keep a promise in the outside world, trust lines represent a way of configuring how much you trust an issuer to hold on your behalf. Since a large, reputable financial institution is more likely to be able to pay you back than, say, your broke roommate, you can set different limits on each trust line, to indicate the maximum amount you are willing to let the issuer "owe" you in the XRP Ledger. If the issuer defaults or goes out of business, you can lose up to that much money because the balances you hold in the XRP Ledger can no longer be exchanged for equivalent balances elsewhere. (You can still keep or trade the issued currency in the XRP Ledger, but there is probably no longer any reason to consider that issued currency to be worth anything.) @@ -16,7 +16,7 @@ Trust lines are represented in the ledger's state data as [RippleState objects]( A trust line with settings in the default state is equivalent to no trust line. -The default state of all trust line flags is off, except for the [No Ripple flag](rippling.html), whose default state depends on the `DefaultRipple` flag. +The default state of all trust line flags is off, except for the [No Ripple flag](rippling.html), whose default state depends on the Default Ripple flag. ## See Also diff --git a/content/concepts/payment-system-basics/accounts/accounts.md b/content/concepts/payment-system-basics/accounts/accounts.md index dcafa72758..4f6dd61584 100644 --- a/content/concepts/payment-system-basics/accounts/accounts.md +++ b/content/concepts/payment-system-basics/accounts/accounts.md @@ -27,7 +27,7 @@ The typical way to get an account in the XRP Ledger is as follows: 2. Have someone who already has an account in the XRP Ledger send XRP to the address you generated. - - For example, you can purchase XRP in a private exchange, then withdraw XRP from the exchange to the address you specified. + - 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](reserves.html) (currently 20 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. diff --git a/content/concepts/payment-system-basics/accounts/cryptographic-keys.md b/content/concepts/payment-system-basics/accounts/cryptographic-keys.md index 16a1a7fe64..4c63e4185d 100644 --- a/content/concepts/payment-system-basics/accounts/cryptographic-keys.md +++ b/content/concepts/payment-system-basics/accounts/cryptographic-keys.md @@ -97,14 +97,14 @@ After you assign a regular key pair to an account, the account has two key pairs You can assign one regular key pair to an account and use it to sign all transactions, except for the ones reserved for the [master key pair](#master-key-pair). -You can remove or change a regular key pair at any time. This means that if a regular secret key is compromised (but the master secret key is not), you can regain control of your account by simply removing or changing the regular key pair. +You can remove or change a regular key pair at any time. This means that if a regular secret key is compromised (but the master secret key is not), you can regain control of your account by removing or changing the regular key pair. For a tutorial on changing or removing a regular key pair, see [Assign a Regular Key Pair](assign-a-regular-key-pair.html). ## Signing Algorithms -Cryptographic key pairs are always tied to a specific signing algorithm, which defines the mathematical relationships between the secret key and the public key. Cryptographic signing algorithms have the property that, given the current state of cryptographic techniques, it is "easy" to use a secret key to calculate a matching public key, but it is effectively impossible to compute a matching secret key by starting from a public key. +Cryptographic key pairs are always tied to a specific signing algorithm, which defines the mathematical relationships between the secret key and the public key. Cryptographic signing algorithms have the property that, given the current state of cryptographic techniques, it is "easy" to use a secret key to calculate a matching public key, but it is effectively impossible to compute a matching secret key by starting from a public key. The XRP Ledger supports the following cryptographic signing algorithms: @@ -190,7 +190,7 @@ The steps to derive the XRP Ledger's secp256k1 account key pair from a seed valu 2. Convert the root public key to its 33-byte compressed form. - The uncompressed form of any ECDSA public key consists of a pair of 32-byte integers: an X coordinate, and a Y coordinate. The compressed form is just the X coordinate and a one-byte prefix: `0x02` if the Y coordinate is even, or `0x03` if the Y coordinate is odd. + The uncompressed form of any ECDSA public key consists of a pair of 32-byte integers: an X coordinate, and a Y coordinate. The compressed form is the X coordinate and a one-byte prefix: `0x02` if the Y coordinate is even, or `0x03` if the Y coordinate is odd. You can convert an uncompressed public key to the compressed form with the `openssl` commandline tool. For example, if the uncompressed public key is in the file `ec-pub.pem`, you can output the compressed form like this: @@ -211,7 +211,7 @@ The steps to derive the XRP Ledger's secp256k1 account key pair from a seed valu 4. Derive the master public key pair by adding the intermediate public key to the root public key. Similarly, derive the secret key by adding the intermediate secret key to the root secret key. - - An ECDSA secret key is just a very large integer, so you can calculate the sum of two secret keys by summing them modulo the secp256k1 group order. + - An ECDSA secret key is a very large integer, so you can calculate the sum of two secret keys by summing them modulo the secp256k1 group order. - An ECDSA public key is a point on the elliptic curve, so you should use elliptic curve math to sum the points. diff --git a/content/concepts/payment-system-basics/accounts/depositauth.md b/content/concepts/payment-system-basics/accounts/depositauth.md index 2c34907cfb..9ff4c6cd08 100644 --- a/content/concepts/payment-system-basics/accounts/depositauth.md +++ b/content/concepts/payment-system-basics/accounts/depositauth.md @@ -24,7 +24,7 @@ To receive money from [Payment transactions][] when you have Deposit Authorizati To get the full effect of Deposit Authorization, Ripple recommends also doing the following: - Always maintain an XRP balance higher than the minimum [reserve requirement](reserves.html). -- Keep the `DefaultRipple` flag in its default (disabled) state. Do not enable [rippling](rippling.html) on any trust lines. When sending [TrustSet transactions][], always use the [`tfSetNoRipple` flag](trustset.html). +- Keep the Default Ripple flag in its default (disabled) state. Do not enable [rippling](rippling.html) on any trust lines. When sending [TrustSet transactions][], always use the [`tfSetNoRipple` flag](trustset.html). - Do not place [Offers](offercreate.html). It is impossible to know in advance which matching offers will be consumed to execute such a trade. ## Precise Semantics @@ -43,7 +43,7 @@ An account with Deposit Authorization enabled: - **Can** receive XRP or issued currencies by sending a [CheckCash][] transaction. _(Added by the [Checks amendment][].)_ - **Can** receive XRP or issued currencies by sending [OfferCreate transactions][]. - If the account sends an OfferCreate transaction that is not fully executed immediately, it **can** receive the remainder of the ordered XRP or issued currency later when the offer is consumed by other accounts' [Payment][] and [OfferCreate][] transactions. -- If the account has created any trust lines without the [NoRipple flag](rippling.html) enabled, or has enabled the `DefaultRipple` flag and issued any currency, the account **can** receive the issued currencies of those trust lines in [Payment transactions][] as a result of rippling. It cannot be the destination of those transactions. +- If the account has created any trust lines without the [No Ripple flag](rippling.html) enabled, or has enabled the Default Ripple flag and issued any currency, the account **can** receive the issued currencies of those trust lines in [Payment transactions][] as a result of rippling. It cannot be the destination of those transactions. - In general, an account in the XRP Ledger **cannot** receive any non-XRP currencies in the XRP Ledger as long as all of the following are true. (This rule is not specific to the DepositAuth flag.) - The account has not created any trust lines with a nonzero limit. - The account has not issued currency on trust lines created by others diff --git a/content/concepts/payment-system-basics/fees.md b/content/concepts/payment-system-basics/fees.md index 8c2aaf87a8..3136dda294 100644 --- a/content/concepts/payment-system-basics/fees.md +++ b/content/concepts/payment-system-basics/fees.md @@ -1,6 +1,6 @@ # Fees (Disambiguation) -The XRP Ledger is a decentralized ledger, secured by cryptography and operated by a distributed peer-to-peer network of servers. This means that no one party, not even Ripple, can require a fee for access to the network. +The XRP Ledger is a decentralized ledger, secured by cryptography and powered by a distributed peer-to-peer network of servers. This means that no one party, not even Ripple, can require a fee for access to the network. However, the rules of the XRP Ledger include several types of fees, including neutral fees which protect the ledger against abuse. These neutral fees are not paid to anyone. There are also several optional ways that users can collect fees from each other, both inside and outside the XRP Ledger. diff --git a/content/concepts/payment-system-basics/transaction-basics/transaction-basics.md b/content/concepts/payment-system-basics/transaction-basics/transaction-basics.md index e4d1b2d2f0..46f9a298d4 100644 --- a/content/concepts/payment-system-basics/transaction-basics/transaction-basics.md +++ b/content/concepts/payment-system-basics/transaction-basics/transaction-basics.md @@ -2,7 +2,7 @@ A _Transaction_ is the only way to modify the XRP Ledger. Transactions are only final if signed, submitted, and accepted into a validated ledger version following the [consensus process](consensus.html). Some ledger rules also generate _[pseudo-transactions](pseudo-transaction-types.html)_, which aren't signed or submitted, but still must be accepted by consensus. Transactions that fail are also included in ledgers because they modify balances of XRP to pay for the anti-spam [transaction cost][]. -Transactions can do more than just send money. In addition to supporting various [Payment Types](payment-types.html), transactions in the XRP Ledger are also used to rotate [cryptographic keys](cryptographic-keys.html), manage other settings, and trade in the XRP Ledger's [decentralized exchange](decentralized-exchange.html). The [`rippled` API reference](rippled-api.html) has a complete [list of transaction types](transaction-types.html). +Transactions can do more than send money. In addition to supporting various [Payment Types](payment-types.html), transactions in the XRP Ledger are also used to rotate [cryptographic keys](cryptographic-keys.html), manage other settings, and trade in the XRP Ledger's [decentralized exchange](decentralized-exchange.html). The [`rippled` API reference](rippled-api.html) has a complete [list of transaction types](transaction-types.html). ### Identifying Transactions diff --git a/content/concepts/payment-types/checks.md b/content/concepts/payment-types/checks.md index b548ea1f63..aba6d50dc4 100644 --- a/content/concepts/payment-types/checks.md +++ b/content/concepts/payment-types/checks.md @@ -2,7 +2,7 @@ _(Added by the [Checks amendment][].)_ -The Checks feature in the XRP Ledger allows users to create deferred payments that can be canceled or cashed by the intended recipients. Like personal paper checks, XRP Ledger Checks start with the sender of the funds creating a Check that specifies an amount and a recipient. The recipient cashes the check to pull the funds from the sender's account into the recipient's account. No money moves until the recipient cashes the Check. Because funds are not put on hold when the Check is created, cashing a Check can fail if the sender doesn't have enough funds when the recipient tries to cash it, just like traditional checks. If there's a failure cashing the check, the check's recipient can retry until the Check expires. +The Checks feature in the XRP Ledger allows users to create deferred payments that can be canceled or cashed by the intended recipients. Like personal paper checks, XRP Ledger Checks start with the sender of the funds creating a Check that specifies an amount and a recipient. The recipient cashes the check to pull the funds from the sender's account into the recipient's account. No money moves until the recipient cashes the Check. Because funds are not put on hold when the Check is created, cashing a Check can fail if the sender doesn't have enough funds when the recipient tries to cash it, like traditional checks. If there's a failure cashing the check, the check's recipient can retry until the Check expires. XRP Ledger Checks have expiration times after which they may no longer be cashed. If the recipient doesn't successfully cash the Check before it expires, the Check object remains in the XRP Ledger until someone cancels it. Anyone may cancel the Check after it expires. Only the sender and recipient can cancel the Check before it expires or is cashed. The Check object is removed from the Ledger when the sender successfully cashes the check or someone cancels it. diff --git a/content/concepts/payment-types/cross-currency-payments.md b/content/concepts/payment-types/cross-currency-payments.md index fdec998f13..a54c2ed65d 100644 --- a/content/concepts/payment-types/cross-currency-payments.md +++ b/content/concepts/payment-types/cross-currency-payments.md @@ -10,7 +10,7 @@ By default, cross-currency payments deliver a fixed amount to their destination - By definition, a cross-currency payment involves at least two currencies, which means that at least one currency involved must be a non-XRP issued currency. - Typically, this means using one or more currencies issued by an [XRP Ledger Gateway](become-an-xrp-ledger-gateway.html). Such currencies are backed by funds outside the XRP Ledger, and can be withdrawn through the gateway. - Issued currencies can also be digital tokens that are only issued within the XRP Ledger, with no outside backing. Of course, the parties involved must be willing to send or receive those tokens and treat them as something of value. -- There must be at least one [Path](paths.html) between the sender and receiver, and the total liquidity across all paths must be enough to facilitate the payment. Cross-currency payments convert from one currency to another by consuming [Offers](offers.html) in the XRP Ledger's decentralized exchange. +- There must be at least one [Path](paths.html) between the sender and receiver, and the total liquidity across all paths must be enough to execute the payment. Cross-currency payments convert from one currency to another by consuming [Offers](offers.html) in the XRP Ledger's decentralized exchange. ## Auto-Bridging diff --git a/content/concepts/payment-types/partial-payments.md b/content/concepts/payment-types/partial-payments.md index 1c38def8d1..c44b1f5e2b 100644 --- a/content/concepts/payment-types/partial-payments.md +++ b/content/concepts/payment-types/partial-payments.md @@ -36,7 +36,7 @@ Partial Payments have the following limitations: - A partial payment cannot provide the XRP to fund an address; this case returns the [result code][] `telNO_DST_PARTIAL`. - Direct XRP-to-XRP payments cannot be partial payments; this case returns the [result code][] `temBAD_SEND_XRP_PARTIAL`. - - However, issuance-to-XRP payments or XRP-to-issuance payments _can_ be partial payments. + - However, cross-currency payments that involve XRP as one of the currencies _can_ be partial payments. [result code]: transaction-results.html @@ -80,7 +80,7 @@ If a financial institution's integration with the XRP Ledger assumes that the `A To exploit a vulnerable financial institution, a malicious actor does something like this: -1. The malicious actor sends a Payment transaction to the institution. This transaction has a large `Amount` field and has the **tfPartialPayment** flag enabled. +1. The malicious actor sends a Payment transaction to the institution. This transaction has a large `Amount` field and has the **`tfPartialPayment`** flag enabled. 2. The partial payment succeeds (result code `tesSUCCESS`) but actually delivers a very small amount of the currency specified. 3. The vulnerable institution reads the transaction's `Amount` field without looking at the `Flags` field or `delivered_amount` metadata field. 4. The vulnerable institution credits the malicious actor in an external system, such as the institution's own ledger, for the full `Amount`, despite only receiving a much smaller `delivered_amount` in the XRP Ledger. @@ -92,7 +92,7 @@ In the case of a merchant, the order of operations is slightly different, but th 1. The malicious actor requests to buy a large amount of goods or services. 2. The vulnerable merchant invoices the malicious actor for the price of those goods and services. -3. The malicious actor sends a Payment transaction to the merchant. This transaction has a large `Amount` field and has the **tfPartialPayment** flag enabled. +3. The malicious actor sends a Payment transaction to the merchant. This transaction has a large `Amount` field and has the **`tfPartialPayment`** flag enabled. 4. The partial payment succeeds (result code `tesSUCCESS`) but delivers only a very small amount of the currency specified. 5. The vulnerable merchant reads the transaction's `Amount` field without looking at the `Flags` field or `delivered_amount` metadata field. 6. The vulnerable merchant treats the invoice as paid and provides the goods or services to the malicious actor, despite only receiving a much smaller `delivered_amount` in the XRP Ledger. diff --git a/content/concepts/the-rippled-server/ledger-history/history-sharding.md b/content/concepts/the-rippled-server/ledger-history/history-sharding.md index 2f81085576..d6f70641a1 100644 --- a/content/concepts/the-rippled-server/ledger-history/history-sharding.md +++ b/content/concepts/the-rippled-server/ledger-history/history-sharding.md @@ -2,7 +2,7 @@ [Introduced in: rippled 0.90.0][] -As servers operate, they naturally produce a database containing data about the ledgers they witnessed or acquired during network runtime. Each `rippled` server stores that ledger data in its ledger store, but the online delete logic rotates these databases when the number of stored ledgers exceeds configured space limitations. +As servers run, they naturally produce a database containing data about the ledgers they witnessed or acquired during network runtime. Each `rippled` server stores that ledger data in its ledger store, but the online delete logic rotates these databases when the number of stored ledgers exceeds configured space limitations. Historical sharding distributes the transaction history of the XRP Ledger into segments, called shards, across servers in the XRP Ledger network. A shard is a range of ledgers. A `rippled` server stores ledgers in both the ledger store and the shard store in the same way. diff --git a/content/concepts/the-rippled-server/ledger-history/online-deletion.md b/content/concepts/the-rippled-server/ledger-history/online-deletion.md index 50c37d6ae6..43e94c40ee 100644 --- a/content/concepts/the-rippled-server/ledger-history/online-deletion.md +++ b/content/concepts/the-rippled-server/ledger-history/online-deletion.md @@ -22,7 +22,7 @@ Inside the ledger store, ledger data is "de-duplicated". In other words, data th The online deletion settings configure how many ledger versions the `rippled` server should keep available in the ledger store at a time. However, the specified number is a guideline, not a hard rule: - The server never deletes data more recent than the configured number of ledger versions, but it may have less than that amount available if it has not been running for long enough or if it lost sync with the network at any time. (The server attempts to backfill at least some history; see [fetching history](ledger-history.html#fetching-history) for details.) -- The server may store up to just over twice the configured number of ledger versions if online deletion is set to run automatically. (Each time it runs, it reduces the number of stored ledger versions to approximately the configured number.) +- The server may store up to slightly over twice the configured number of ledger versions if online deletion is set to run automatically. (Each time it runs, it reduces the number of stored ledger versions to approximately the configured number.) If online deletion is delayed because the server is busy, ledger versions can continue to accumulate. When functioning normally, online deletion begins when the server has twice the configured number of ledger versions, but it may not complete until after several more ledger versions have accumulated. @@ -82,9 +82,9 @@ The following settings relate to online deletion: The `fetch_depth` setting cannot be higher than `online_delete` if both are specified. If `fetch_depth` is set higher, the server treats it as equal to `online_delete` instead. - The following diagram shows how fetch_depth works: + The following diagram shows how `fetch_depth` works: - ![Ledger versions older than fetch_depth are not served to peers](img/fetch_depth.png) + ![Ledger versions older than `fetch_depth` are not served to peers](img/fetch_depth.png) For estimates of how much disk space is required to store different amounts of history, see [Capacity Planning](capacity-planning.html#disk-space). diff --git a/content/concepts/the-rippled-server/peer-protocol.md b/content/concepts/the-rippled-server/peer-protocol.md index f61e95ce8c..8426675bf2 100644 --- a/content/concepts/the-rippled-server/peer-protocol.md +++ b/content/concepts/the-rippled-server/peer-protocol.md @@ -55,7 +55,7 @@ The node key pair also identifies other servers for purposes of [clustering](clu Normally, a `rippled` server attempts to maintain a healthy number of peers, and automatically connects to untrusted peers up to a maximum number. You can configure a `rippled` server to remain connected to specific peer servers in several ways: - Use **Fixed Peers** to remain always connected to specific other peers based on their IP addresses. This only works if the peers have fixed IP addresses. Use the `[ips_fixed]` config stanza to configure fixed peers. This is a necessary part of [clustering](clustering.html) or [private peers](#private-peers). Fixed peers are defined in the config file, so changes only apply after restarting the server. Fixed peers are most useful for keeping servers connected if those servers are run by the same person or organization. -- Use **Peer Reservations** to prioritize specific peers. If your server has a peer reservation for a specific peer, then your server always accepts connection requests from that peer even if your server is already at its maximum number of connected peers. (This can cause your server to go _over_ the maximum number of peers.) You identify a reserved peer by its [node key pair](#node-key-pair), so you can do this even for peers with variable IP addresses. Peer reservations are configured through admin commands and saved in the server databases, so they can be adjusted while the server is online and are saved across restarts. Peer reservations are most useful for connecting servers operated by different people or organizations. [New in: rippled 1.4.0][] +- Use **Peer Reservations** to prioritize specific peers. If your server has a peer reservation for a specific peer, then your server always accepts connection requests from that peer even if your server is already at its maximum number of connected peers. (This can cause your server to go _over_ the maximum number of peers.) You identify a reserved peer by its [node key pair](#node-key-pair), so you can do this even for peers with variable IP addresses. Peer reservations are configured through admin commands and saved in the server databases, so they can be adjusted while the server is online and are saved across restarts. Peer reservations are most useful for connecting servers run by different people or organizations. [New in: rippled 1.4.0][] In the following cases, a `rippled` server does not connect to untrusted peers: @@ -98,12 +98,12 @@ The pros and cons of each configuration are as follows: Discovered Peers Private Server Using Proxies @@ -121,7 +121,7 @@ The pros and cons of each configuration are as follows: Private Server Using Public Hubs