From c63d10d116806e4b7900b88b3d35db5765e49cfb Mon Sep 17 00:00:00 2001 From: mDuo13 Date: Fri, 24 Jul 2020 03:25:39 -0700 Subject: [PATCH] Most spelling, more style cleanup --- assets/js/apitool-methods-ws.js | 2 +- assets/js/tx-sender.js | 4 +- content/_img-sources/noripple-05.uxf | 4 +- content/_img-sources/noripple-06.uxf | 12 +- .../depositauth-semantics-table.html | 4 +- content/_snippets/gateways-intro.md | 2 +- content/_snippets/tutorial-submit-step.md | 2 +- .../amendments/known-amendments.md | 18 +-- .../consensus-principles-and-rules.md | 2 +- .../consensus-protections.md | 4 +- .../consensus-network/consensus-research.md | 2 + .../concepts/consensus-network/consensus.md | 6 +- .../consensus-network/parallel-networks.md | 6 +- .../transaction-malleability.md | 30 ++--- .../decentralized-exchange/autobridging.md | 2 +- .../concepts/decentralized-exchange/offers.md | 2 +- .../introduction/intro-to-consensus.md | 2 +- .../introduction/software-ecosystem.md | 6 +- .../concepts/introduction/technical-faq.md | 10 +- .../introduction/xrp-ledger-overview.md | 6 +- .../authorized-trust-lines.md | 19 ++-- .../concepts/issued-currencies/demurrage.md | 2 +- content/concepts/issued-currencies/freezes.md | 18 +-- .../issued-currencies-overview.md | 2 +- .../issuing-and-operational-addresses.md | 10 +- content/concepts/issued-currencies/paths.md | 10 +- .../concepts/issued-currencies/rippling.md | 44 +++---- .../issued-currencies/transfer-fees.md | 16 +-- .../trust-lines-and-issuing.md | 4 +- .../accounts/accounts.md | 2 +- .../accounts/cryptographic-keys.md | 8 +- .../accounts/depositauth.md | 4 +- .../concepts/payment-system-basics/fees.md | 2 +- .../transaction-basics/transaction-basics.md | 2 +- content/concepts/payment-types/checks.md | 2 +- .../payment-types/cross-currency-payments.md | 2 +- .../payment-types/partial-payments.md | 6 +- .../ledger-history/history-sharding.md | 2 +- .../ledger-history/online-deletion.md | 6 +- .../the-rippled-server/peer-protocol.md | 8 +- .../rippled-server-modes.md | 2 +- .../can_delete.md | 2 +- .../ledger-object-types/accountroot.md | 2 +- .../ledger-object-types/ripplestate.md | 14 +-- .../ledger-object-types/signerlist.md | 2 +- .../references/rippled-api/peer-crawler.md | 2 +- .../account-methods/account_lines.md | 12 +- .../account-methods/noripple_check.md | 11 +- .../public-rippled-methods.md | 2 +- .../server-info-methods/server_info.md | 2 +- .../server-info-methods/server_state.md | 2 +- .../subscription-methods/subscribe.md | 2 +- .../transaction-common-fields.md | 16 +-- .../transaction-types/accountset.md | 2 +- .../transaction-types/checkcash.md | 2 +- .../transaction-types/payment.md | 16 +-- .../references/rippled-api/validator-list.md | 2 +- content/references/xrp-ledger-toml.md | 10 +- ...t-started-with-rippleapi-for-javascript.md | 48 ++++---- .../get-started-with-the-rippled-api.md | 2 +- .../look-up-transaction-results.md | 36 +++--- ...tor-incoming-payments-with-websocket.ja.md | 22 ++-- ...onitor-incoming-payments-with-websocket.md | 2 +- .../get-started/set-up-secure-signing.md | 6 +- .../change-or-remove-a-regular-key-pair.md | 6 +- .../disable-master-key-pair.md | 4 +- .../offline-account-setup.md | 10 +- .../set-up-multi-signing.md | 14 +-- .../configure-advisory-deletion.md | 2 +- .../configuration/configure-grpc.md | 2 +- ...onnect-your-rippled-to-the-xrp-test-net.md | 92 +++++++-------- .../run-rippled-as-a-validator.md | 10 +- .../run-rippled-as-a-wallet-server.md | 6 +- .../installation/build-run-rippled-macos.md | 4 +- .../installation/capacity-planning.md | 4 +- .../installation/system-requirements.md | 2 +- .../troubleshooting/diagnosing-problems.md | 6 +- .../fix-sqlite-tx-db-page-size-issue.md | 2 +- .../troubleshooting/server-doesnt-sync.md | 2 +- .../understanding-log-messages.md | 4 +- .../cash-a-check-for-a-flexible-amount.md | 2 +- .../use-checks/send-a-check.md | 10 +- .../send-a-conditionally-held-escrow.md | 2 +- .../use-payment-channels.md | 2 +- .../reliable-transaction-submission.md | 4 +- .../send-a-multi-signed-transaction.md | 2 +- .../use-simple-xrp-payments/send-xrp.ja.md | 4 +- .../use-simple-xrp-payments/send-xrp.md | 14 +-- .../become-an-xrp-ledger-gateway.md | 107 ++++++++++-------- .../list-xrp-as-an-exchange.md | 2 +- .../list-your-exchange-on-xrp-charts.md | 4 +- .../contribute-code-to-ripple-lib.md | 4 +- .../use-cases/contribute-code-to-rippled.md | 4 +- ...nel-to-enable-an-inter-exchange-network.md | 6 +- dactyl-config.yml | 2 +- .../template-openapi_data_type.md | 2 +- .../template-openapi_data_types_toc.md | 2 +- .../template-openapi_endpoint.md | 2 +- .../template-openapi_endpoint_tag_toc.md | 2 +- .../template-openapi_endpoint_toc.md | 2 +- tool/spelling.txt | 19 +++- tool/word_substitutions.yaml | 2 +- 102 files changed, 463 insertions(+), 421 deletions(-) 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

  • Simplest configuration, with a low maintenance burden.

    • -

  • Creates the opportunity for a lot of direct peer connections. Having more direct peers comes with several benefits. Your server can fetch history from multiple peers in parallel, both when syncing and when backfilling history. Since not all peers maintain full history, having access to more peers can also provide access to a wider selection of historical data.

    • +

  • Creates the opportunity for a lot of direct peer connections. Having more direct peers comes with several benefits. Your server can fetch history from multiple peers in parallel, both when syncing and when backfilling history. Since not all peers maintain full history, having access to more peers can also provide access to a wider range of historical data.

  • Lowers the possibility of disconnecting from the network because your server can replace disconnected peers with new ones.

  • Doesn't allow you to select your server's peers, which means that you have no idea whether your peers may decide to act maliciously. Although `rippled` servers are designed to protect against malicious peers, there is always a risk that malicious peers could exploit software flaws to affect your server.

    • -

  • Your server's peers may disconnect or change frequently.

    • +

  • Your server's peers may disconnect or change often.

Private Server Using Proxies @@ -121,7 +121,7 @@ The pros and cons of each configuration are as follows: Private Server Using Public Hubs

  • Low maintenance burden with a small amount of configuration.

    • -

  • Provides easy access to safe connections to the network.

    • +

  • Provides access to safe connections to the network.

  • Compared to connecting using proxies, may be less likely to cause your private server to disconnect from the network due to a simultaneous peer outage.

    diff --git a/content/concepts/the-rippled-server/rippled-server-modes.md b/content/concepts/the-rippled-server/rippled-server-modes.md index e221e50b70..2302fe6df4 100644 --- a/content/concepts/the-rippled-server/rippled-server-modes.md +++ b/content/concepts/the-rippled-server/rippled-server-modes.md @@ -23,7 +23,7 @@ You need to trust the `rippled` you use. If you connect to a malicious server, t Additionally, running your own server gives you admin control over it, which allows you to run important admin-only and load-intensive commands. If you use a shared server, you have to worry about other users of the same server competing with you for the server's computing power. Many of the commands in the WebSocket API can put a lot of strain on the server, so `rippled` has the option to scale back its responses when it needs to. If you share a server with others, you may not always get the best results possible. -Finally, if you run a validating server, you can use a stock server as a proxy to the public network while keeping your validating server on a private subnet only accessible to the outside world through the stock server. This makes it more difficult to compromise the integrity of your validating server. +Finally, if you run a validating server, you can use a stock server as a proxy to the public network while keeping your validating server on a private network only accessible to the outside world through the stock server. This makes it more difficult to compromise the integrity of your validating server. ### Public Hubs diff --git a/content/references/rippled-api/admin-rippled-methods/logging-and-data-management-methods/can_delete.md b/content/references/rippled-api/admin-rippled-methods/logging-and-data-management-methods/can_delete.md index dcada9f546..ccf2e39bb1 100644 --- a/content/references/rippled-api/admin-rippled-methods/logging-and-data-management-methods/can_delete.md +++ b/content/references/rippled-api/admin-rippled-methods/logging-and-data-management-methods/can_delete.md @@ -65,7 +65,7 @@ Use this command with no parameter to query the existing `can_delete` setting. - `invalidParams` - One or more fields are specified incorrectly, or one or more required fields are missing. - `lgrNotFound` - The ledger specified by the `can_delete` field of the request does not exist, or it does exist but the server does not have it. - `notEnabled` - If either online deletion or advisory deletion are not enabled in the server's configuration. -- `notReady` - The server is not ready to run online deletion at the moment. This usually means the server has just started up and has not yet acquired a validated ledger. +- `notReady` - The server is not ready to run online deletion at the moment. This usually means the server has recently started up and has not yet acquired a validated ledger. ## See Also diff --git a/content/references/rippled-api/ledger-data-formats/ledger-object-types/accountroot.md b/content/references/rippled-api/ledger-data-formats/ledger-object-types/accountroot.md index e166548742..3ff2f6fd29 100644 --- a/content/references/rippled-api/ledger-data-formats/ledger-object-types/accountroot.md +++ b/content/references/rippled-api/ledger-data-formats/ledger-object-types/accountroot.md @@ -63,7 +63,7 @@ AccountRoot objects can have the following flag values: | `lsfGlobalFreeze` | `0x00400000` | 4194304 | `asfGlobalFreeze` | All assets issued by this address are frozen. | | `lsfNoFreeze` | `0x00200000` | 2097152 | `asfNoFreeze` | This address cannot freeze trust lines connected to it. Once enabled, cannot be disabled. | | `lsfPasswordSpent` | `0x00010000` | 65536 | (None) | The account has used its free SetRegularKey transaction. | -| `lsfRequireAuth` | `0x00040000` | 262144 | `asfRequireAuth` | This account must individually approve other users for those users to hold this account's issuances. | +| `lsfRequireAuth` | `0x00040000` | 262144 | `asfRequireAuth` | This account must individually approve other users for those users to hold this account's issued currencies. | | `lsfRequireDestTag` | `0x00020000` | 131072 | `asfRequireDest` | Requires incoming payments to specify a Destination Tag. | ## AccountRoot ID Format diff --git a/content/references/rippled-api/ledger-data-formats/ledger-object-types/ripplestate.md b/content/references/rippled-api/ledger-data-formats/ledger-object-types/ripplestate.md index 24adb9b05c..8ca91b84cc 100644 --- a/content/references/rippled-api/ledger-data-formats/ledger-object-types/ripplestate.md +++ b/content/references/rippled-api/ledger-data-formats/ledger-object-types/ripplestate.md @@ -7,7 +7,7 @@ The `RippleState` object type connects two accounts in a single currency. Concep There can only be one `RippleState` object per currency for any given pair of accounts. Since no account is privileged in the XRP Ledger, a `RippleState` object sorts account addresses numerically, to ensure a canonical form. Whichever address is numerically lower when [decoded](accounts.html#address-encoding) is deemed the "low account" and the other is the "high account". The net balance of the trust line is stored from the low account's perspective. -The ["issuer"](trust-lines-and-issuing.html) for the balance in a trust line depends on whether the balance is positive or negative. If a `RippleState` object shows a positive balance, the high account is the issuer. If the balance is negative, the low account is the issuer. Frequently, the issuer has its limit set to 0 and the other account has a positive limit, but this is not reliable because limits can change without affecting an existing balance. +The ["issuer"](trust-lines-and-issuing.html) for the balance in a trust line depends on whether the balance is positive or negative. If a `RippleState` object shows a positive balance, the high account is the issuer. If the balance is negative, the low account is the issuer. Often, the issuer has its limit set to 0 and the other account has a positive limit, but this is not reliable because limits can change without affecting an existing balance. ## Example {{currentpage.name}} JSON @@ -88,16 +88,16 @@ The values that count towards a trust line's non-default state are as follows: | `HighLimit` is not `0` | `LowLimit` is not `0` | | `LowQualityIn` is not `0` and not `1000000000` | `HighQualityIn` is not `0` and not `1000000000` | | `LowQualityOut` is not `0` and not `1000000000` | `HighQualityOut` is not `0` and not `1000000000` | -| **lsfHighNoRipple** flag is not in its default state | **lsfLowNoRipple** flag is not in its default state | -| **lsfHighFreeze** flag is enabled | **lsfLowFreeze** flag is enabled | +| `lsfHighNoRipple` flag is not in its default state | `lsfLowNoRipple` flag is not in its default state | +| `lsfHighFreeze` flag is enabled | `lsfLowFreeze` flag is enabled | -The **lsfLowAuth** and **lsfHighAuth** flags do not count against the default state, because they cannot be disabled. +The **`lsfLowAuth`** and **`lsfHighAuth`** flags do not count against the default state, because they cannot be disabled. -The default state of the two NoRipple flags depends on the state of the [lsfDefaultRipple flag](accountroot.html#accountroot-flags) in their corresponding AccountRoot objects. If `DefaultRipple` is disabled (the default), then the default state of the `lsfNoRipple` flag is _enabled_ for all of an account's trust lines. If an account enables `DefaultRipple`, then the `lsfNoRipple` flag is _disabled_ (rippling is enabled) for an account's trust lines by default. +The default state of the two No Ripple flags depends on the state of the [`lsfDefaultRipple` flag](accountroot.html#accountroot-flags) in their corresponding AccountRoot objects. If Default Ripple is disabled (the default), then the default state of the `lsfNoRipple` flag is _enabled_ for all of an account's trust lines. If an account enables Default Ripple, then the `lsfNoRipple` flag is _disabled_ (rippling is enabled) for an account's trust lines by default. -**Note:** Prior to the introduction of the `DefaultRipple` flags in `rippled` version 0.27.3 (March 10, 2015), the default state for all trust lines was with both No Ripple flags disabled (rippling enabled). +**Note:** Prior to the introduction of the Default Ripple flag in `rippled` version 0.27.3 (March 10, 2015), the default state for all trust lines was with both No Ripple flags disabled (rippling enabled). -Fortunately, `rippled` uses lazy evaluation to calculate the owner reserve. This means that even if an account changes the default state of all its trust lines by changing the `DefaultRipple` flag, that account's reserve stays the same initially. If an account modifies a trust line, `rippled` re-evaluates whether that individual trust line is in its default state and should contribute to the owner reserve. +Fortunately, `rippled` uses lazy evaluation to calculate the owner reserve. This means that even if an account changes the default state of all its trust lines by changing the Default Ripple flag, that account's reserve stays the same initially. If an account modifies a trust line, `rippled` re-evaluates whether that individual trust line is in its default state and should contribute to the owner reserve. ## RippleState ID Format diff --git a/content/references/rippled-api/ledger-data-formats/ledger-object-types/signerlist.md b/content/references/rippled-api/ledger-data-formats/ledger-object-types/signerlist.md index 4c3520e019..80f6c1a984 100644 --- a/content/references/rippled-api/ledger-data-formats/ledger-object-types/signerlist.md +++ b/content/references/rippled-api/ledger-data-formats/ledger-object-types/signerlist.md @@ -67,7 +67,7 @@ Each member of the `SignerEntries` field is an object that describes that signer | `Account` | String | AccountID | An XRP Ledger address whose signature contributes to the multi-signature. It does not need to be a funded address in the ledger. | | `SignerWeight` | Number | UInt16 | The weight of a signature from this signer. A multi-signature is only valid if the sum weight of the signatures provided meets or exceeds the signer list's `SignerQuorum` value. | -When processing a multi-signed transaction, the server dereferences the `Account` values with respect to the ledger at the time of transaction execution. If the address _does not_ correspond to a funded [AccountRoot object](accountroot.html), then only the master secret associated with that address can be used to produce a valid signature. If the account _does_ exist in the ledger, then it depends on the state of that account. If the account has a Regular Key configured, the Regular Key can be used. The account's master key can only be used if it is not disabled. A multi-signature cannot be used as part of another multi-signature. +When processing a multi-signed transaction, the server looks up the `Account` values with respect to the ledger at the time of transaction execution. If the address _does not_ correspond to a funded [AccountRoot object](accountroot.html), then only the [master private key](cryptographic-keys.html) associated with that address can be used to produce a valid signature. If the account _does_ exist in the ledger, then it depends on the state of that account. If the account has a Regular Key configured, the Regular Key can be used. The account's master key can only be used if it is not disabled. A multi-signature cannot be used as part of another multi-signature. ## {{currentpage.name}} Flags diff --git a/content/references/rippled-api/peer-crawler.md b/content/references/rippled-api/peer-crawler.md index b97157f778..9f63b667f4 100644 --- a/content/references/rippled-api/peer-crawler.md +++ b/content/references/rippled-api/peer-crawler.md @@ -15,7 +15,7 @@ To request the Peer Crawler information, make the following HTTP request: - **Path:** `/crawl` - **Security:** Most `rippled` servers use a self-signed certificate to respond to the request. By default, most tools (including web browsers) flag or block such responses for being untrusted. You must ignore the certificate checking (for example, if using cURL, add the `--insecure` flag) to display a response from those servers. -**Tip:** Since this request uses the GET method, you can test this request using just the URL bar of your web browser. For example, requests peer crawler information from one of Ripple's public servers. +**Tip:** Since this request uses the GET method, you can test this request using the URL bar of your web browser. For example, requests peer crawler information from one of Ripple's public servers. ## Response Format diff --git a/content/references/rippled-api/public-rippled-methods/account-methods/account_lines.md b/content/references/rippled-api/public-rippled-methods/account-methods/account_lines.md index db16206d93..b405a1b0a2 100644 --- a/content/references/rippled-api/public-rippled-methods/account-methods/account_lines.md +++ b/content/references/rippled-api/public-rippled-methods/account-methods/account_lines.md @@ -176,12 +176,12 @@ Each trust line object has some combination of the following fields: | `limit_peer` | String | The maximum amount of currency that the counterparty account is willing to owe the perspective account | | `quality_in` | Unsigned Integer | Rate at which the account values incoming balances on this trust line, as a ratio of this value per 1 billion units. (For example, a value of 500 million represents a 0.5:1 ratio.) As a special case, 0 is treated as a 1:1 ratio. | | `quality_out` | Unsigned Integer | Rate at which the account values outgoing balances on this trust line, as a ratio of this value per 1 billion units. (For example, a value of 500 million represents a 0.5:1 ratio.) As a special case, 0 is treated as a 1:1 ratio. | -| `no_ripple` | Boolean | (May be omitted) `true` if this account has enabled the [NoRipple flag](rippling.html) for this line. If omitted, that is the same as `false`. | -| `no_ripple_peer` | Boolean | (May be omitted) `true` if the peer account has enabled the [NoRipple flag](rippling.html). If omitted, that is the same as `false`. | -| `authorized` | Boolean | (May be omitted) `true` if this account has [authorized this trust line](authorized-trust-lines.html). If omitted, that is the same as `false`. | -| `peer_authorized`| Boolean | (May be omitted) `true` if the peer account has [authorized this trust line](authorized-trust-lines.html). If omitted, that is the same as `false`. | -| `freeze` | Boolean | (May be omitted) `true` if this account has [frozen](freezes.html) this trust line. If omitted, that is the same as `false`. | -| `freeze_peer` | Boolean | (May be omitted) `true` if the peer account has [frozen](freezes.html) this trust line. If omitted, that is the same as `false`. | +| `no_ripple` | Boolean | _(May be omitted)_ `true` if this account has enabled the [No Ripple flag](rippling.html) for this line. If omitted, that is the same as `false`. | +| `no_ripple_peer` | Boolean | _(May be omitted)_ `true` if the peer account has enabled the [No Ripple flag](rippling.html). If omitted, that is the same as `false`. | +| `authorized` | Boolean | _(May be omitted)_ `true` if this account has [authorized this trust line](authorized-trust-lines.html). If omitted, that is the same as `false`. | +| `peer_authorized`| Boolean | _(May be omitted)_ `true` if the peer account has [authorized this trust line](authorized-trust-lines.html). If omitted, that is the same as `false`. | +| `freeze` | Boolean | _(May be omitted)_ `true` if this account has [frozen](freezes.html) this trust line. If omitted, that is the same as `false`. | +| `freeze_peer` | Boolean | _(May be omitted)_ `true` if the peer account has [frozen](freezes.html) this trust line. If omitted, that is the same as `false`. | ## Possible Errors diff --git a/content/references/rippled-api/public-rippled-methods/account-methods/noripple_check.md b/content/references/rippled-api/public-rippled-methods/account-methods/noripple_check.md index 1520407a6b..74fe09e31f 100644 --- a/content/references/rippled-api/public-rippled-methods/account-methods/noripple_check.md +++ b/content/references/rippled-api/public-rippled-methods/account-methods/noripple_check.md @@ -1,7 +1,7 @@ # noripple_check [[Source]](https://github.com/ripple/rippled/blob/9111ad1a9dc37d49d085aa317712625e635197c0/src/ripple/rpc/handlers/NoRippleCheck.cpp "Source") -The `noripple_check` command provides a quick way to check the status of [the `DefaultRipple` field for an account and the No Ripple flag of its trust lines](rippling.html), compared with the recommended settings. +The `noripple_check` command provides a quick way to check the status of [the Default Ripple field for an account and the No Ripple flag of its trust lines](rippling.html), compared with the recommended settings. ## Request Format An example of the request format: @@ -48,7 +48,7 @@ The request includes the following parameters: | `Field` | Type | Description | |:---------------|:---------------------------|:-------------------------------| | `account` | String | A unique identifier for the account, most commonly the account's address. | -| `role` | String | Whether the address refers to a `gateway` or `user`. Recommendations depend on the role of the account. Issuers must have DefaultRipple enabled and must disable NoRipple on all trust lines. Users should have DefaultRipple disabled, and should enable NoRipple on all trust lines. | +| `role` | String | Whether the address refers to a `gateway` or `user`. Recommendations depend on the role of the account. Issuers must have Default Ripple enabled and must disable No Ripple on all trust lines. Users should have Default Ripple disabled, and should enable No Ripple on all trust lines. | | `transactions` | Boolean | _(Optional)_ If `true`, include an array of suggested [transactions](transaction-formats.html), as JSON objects, that you can sign and submit to fix the problems. Defaults to false. | | `limit` | Unsigned Integer | _(Optional)_ The maximum number of trust line problems to include in the results. Defaults to 300. | | `ledger_hash` | String | _(Optional)_ A 20-byte hex string for the ledger version to use. (See [Specifying Ledgers][]) | @@ -62,7 +62,7 @@ An example of a successful response: *WebSocket* -``` +```json { "id": 0, "status": "success", @@ -114,8 +114,9 @@ An example of a successful response: *JSON-RPC* -``` +```json 200 OK + { "result": { "ledger_current_index": 14380381, @@ -170,7 +171,7 @@ The response follows the [standard format][], with a successful result containin | `Field` | Type | Description | |:-----------------------|:-------|:-------------------------------------------| | `ledger_current_index` | Number | The [ledger index][] of the ledger used to calculate these results. | -| `problems` | Array | Array of strings with human-readable descriptions of the problems. This includes up to one entry if the account's DefaultRipple setting is not as recommended, plus up to `limit` entries for trust lines whose NoRipple setting is not as recommended. | +| `problems` | Array | Array of strings with human-readable descriptions of the problems. This includes up to one entry if the account's Default Ripple setting is not as recommended, plus up to `limit` entries for trust lines whose No Ripple setting is not as recommended. | | `transactions` | Array | (May be omitted) If the request specified `transactions` as `true`, this is an array of JSON objects, each of which is the JSON form of a [transaction](transaction-formats.html) that should fix one of the described problems. The length of this array is the same as the `problems` array, and each entry is intended to fix the problem described at the same index into that array. | ## Possible Errors diff --git a/content/references/rippled-api/public-rippled-methods/public-rippled-methods.md b/content/references/rippled-api/public-rippled-methods/public-rippled-methods.md index 4bba5b92da..2c94ee8bd5 100644 --- a/content/references/rippled-api/public-rippled-methods/public-rippled-methods.md +++ b/content/references/rippled-api/public-rippled-methods/public-rippled-methods.md @@ -15,7 +15,7 @@ An account in the XRP Ledger represents a holder of XRP and a sender of transact * **[`account_offers`](account_offers.html)** - Get info about an account's currency exchange offers. * **[`account_tx`](account_tx.html)** - Get info about an account's transactions. * **[`gateway_balances`](gateway_balances.html)** - Calculate total amounts issued by an account. -* **[`noripple_check`](noripple_check.html)** - Get recommended changes to an account's `DefaultRipple` and No Ripple settings. +* **[`noripple_check`](noripple_check.html)** - Get recommended changes to an account's Default Ripple and No Ripple settings. ## [Ledger Methods](ledger-methods.html) diff --git a/content/references/rippled-api/public-rippled-methods/server-info-methods/server_info.md b/content/references/rippled-api/public-rippled-methods/server-info-methods/server_info.md index dae08ef865..5a69c7f832 100644 --- a/content/references/rippled-api/public-rippled-methods/server-info-methods/server_info.md +++ b/content/references/rippled-api/public-rippled-methods/server-info-methods/server_info.md @@ -491,7 +491,7 @@ The `info` object may have some arrangement of the following fields: | `amendment_blocked` | Boolean | _(May be omitted)_ If `true`, this server is [amendment blocked](amendments.html#amendment-blocked). If the server is not amendment blocked, the response omits this field. [New in: rippled 0.80.0][] | | `build_version` | String | The version number of the running `rippled` version. | | `closed_ledger` | Object | (May be omitted) Information on the most recently closed ledger that has not been validated by consensus. If the most recently validated ledger is available, the response omits this field and includes `validated_ledger` instead. The member fields are the same as the `validated_ledger` field. | -| `complete_ledgers` | String | Range expression indicating the sequence numbers of the ledger versions the local `rippled` has in its database. This may be a disjoint sequence such as `24900901-24900984,24901116-24901158`. If the server does not have any complete ledgers (for example, it just started syncing with the network), this is the string `empty`. | +| `complete_ledgers` | String | Range expression indicating the sequence numbers of the ledger versions the local `rippled` has in its database. This may be a disjoint sequence such as `24900901-24900984,24901116-24901158`. If the server does not have any complete ledgers (for example, it recently started syncing with the network), this is the string `empty`. | | `hostid` | String | On an admin request, returns the hostname of the server running the `rippled` instance; otherwise, returns a single [RFC-1751][] word based on the node public key. | | `io_latency_ms` | Number | Amount of time spent waiting for I/O operations, in milliseconds. If this number is not very, very low, then the `rippled` server is probably having serious load issues. | | `jq_trans_overflow` | String - Number | The number of times (since starting up) that this server has had over 250 transactions waiting to be processed at once. A large number here may mean that your server is unable to handle the transaction load of the XRP Ledger network. For detailed recommendations of future-proof server specifications, see [Capacity Planning](capacity-planning.html). [New in: rippled 0.90.0][] | diff --git a/content/references/rippled-api/public-rippled-methods/server-info-methods/server_state.md b/content/references/rippled-api/public-rippled-methods/server-info-methods/server_state.md index 4eddb47a83..d0d8b0c8db 100644 --- a/content/references/rippled-api/public-rippled-methods/server-info-methods/server_state.md +++ b/content/references/rippled-api/public-rippled-methods/server-info-methods/server_state.md @@ -527,7 +527,7 @@ The `state` object may have some arrangement of the following fields: |:---------------------------------|:----------------|:------------------------| | `amendment_blocked` | Boolean | _(May be omitted)_ If `true`, this server is [amendment blocked](amendments.html#amendment-blocked). If the server is not amendment blocked, the response omits this field. [New in: rippled 0.80.0][] | | `build_version` | String | The version number of the running `rippled` version. | -| `complete_ledgers` | String | Range expression indicating the sequence numbers of the ledger versions the local `rippled` has in its database. It is possible to be a disjoint sequence, e.g. "2500-5000,32570-7695432". If the server does not have any complete ledgers (for example, it just started syncing with the network), this is the string `empty`. | +| `complete_ledgers` | String | Range expression indicating the sequence numbers of the ledger versions the local `rippled` has in its database. It is possible to be a disjoint sequence, e.g. "2500-5000,32570-7695432". If the server does not have any complete ledgers (for example, it recently started syncing with the network), this is the string `empty`. | | `closed_ledger` | Object | _(May be omitted)_ Information on the most recently closed ledger that has not been validated by consensus. If the most recently validated ledger is available, the response omits this field and includes `validated_ledger` instead. The member fields are the same as the `validated_ledger` field. | | `io_latency_ms` | Number | Amount of time spent waiting for I/O operations, in milliseconds. If this number is not very, very low, then the `rippled` server is probably having serious load issues. | | `jq_trans_overflow` | String - Number | The number of times this server has had over 250 transactions waiting to be processed at once. A large number here may mean that your server is unable to handle the transaction load of the XRP Ledger network. For detailed recommendations of future-proof server specifications, see [Capacity Planning](capacity-planning.html). [New in: rippled 0.90.0][] | diff --git a/content/references/rippled-api/public-rippled-methods/subscription-methods/subscribe.md b/content/references/rippled-api/public-rippled-methods/subscription-methods/subscribe.md index b60b264d2b..b36018eff3 100644 --- a/content/references/rippled-api/public-rippled-methods/subscription-methods/subscribe.md +++ b/content/references/rippled-api/public-rippled-methods/subscription-methods/subscribe.md @@ -204,7 +204,7 @@ The fields from a validations stream message are as follows: | `type` | String | The value `validationReceived` indicates this is from the validations stream. | | `amendments` | Array of Strings | (May be omitted) The [amendments](amendments.html) this server wants to be added to the protocol. [New in: rippled 0.32.0][] | | `base_fee` | Integer | (May be omitted) The unscaled transaction cost (`reference_fee` value) this server wants to set by [Fee Voting](fee-voting.html). [New in: rippled 0.32.0][] | -| `flags` | Number | Bit-mask of flags added to this validation message. The flag 0x80000000 indicates that the validation signature is fully-canonical. The flag 0x00000001 indicates that this is a full validation; otherwise it's a partial validation. Partial validations are not meant to vote for any particular ledger. A partial validation indicates that the validator is still online but not keeping up with consensus. [New in: rippled 0.32.0][] | +| `flags` | Number | Bit-mask of flags added to this validation message. The flag `0x80000000` indicates that the validation signature is fully-canonical. The flag `0x00000001` indicates that this is a full validation; otherwise it's a partial validation. Partial validations are not meant to vote for any particular ledger. A partial validation indicates that the validator is still online but not keeping up with consensus. [New in: rippled 0.32.0][] | | `full` | Boolean | If `true`, this is a full validation. Otherwise, this is a partial validation. Partial validations are not meant to vote for any particular ledger. A partial validation indicates that the validator is still online but not keeping up with consensus. [New in: rippled 0.32.0][] | | `ledger_hash` | String | The identifying hash of the proposed ledger is being validated. | | `ledger_index` | String - Integer | The [Ledger Index][] of the proposed ledger. [New in: rippled 0.31.0][] | diff --git a/content/references/rippled-api/transaction-formats/transaction-common-fields.md b/content/references/rippled-api/transaction-formats/transaction-common-fields.md index ddf6a8fc27..cc22130212 100644 --- a/content/references/rippled-api/transaction-formats/transaction-common-fields.md +++ b/content/references/rippled-api/transaction-formats/transaction-common-fields.md @@ -70,7 +70,7 @@ The only flag that applies globally to all transactions is as follows: When using the [sign method][] (or [submit method][] in "sign-and-submit" mode), `rippled` adds a `Flags` field with `tfFullyCanonicalSig` enabled unless the `Flags` field is already present. The `tfFullyCanonicalSig` flag ***is not*** automatically enabled if `Flags` is explicitly specified. The flag ***is not*** automatically enabled when using the [sign_for method][] to add a signature to a multi-signed transaction. -**Warning:** If you do not enable `tfFullyCanonicalSig`, it is theoretically possible for a malicious actor to modify your transaction signature so that the transaction may succeed with a different hash than expected. In the worst case, this could [trick your integration into submitting the same payment multiple times](transaction-malleability.html#exploit-with-malleable-transactions). To avoid this problem, enable the `tfFullyCanonicalSig` flag on all transactions you sign. If the [RequireFullyCanonicalSig amendment][] :not_enabled: is enabled, all single-signed transactions are protected regardless of the tfFullyCanonicalSig flag. +**Warning:** If you do not enable `tfFullyCanonicalSig`, it is theoretically possible for a malicious actor to modify your transaction signature so that the transaction may succeed with a different hash than expected. In the worst case, this could [trick your integration into submitting the same payment multiple times](transaction-malleability.html#exploit-with-malleable-transactions). To avoid this problem, enable the `tfFullyCanonicalSig` flag on all transactions you sign. If the [RequireFullyCanonicalSig amendment][] :not_enabled: is enabled, all single-signed transactions are protected regardless of the `tfFullyCanonicalSig` flag. ### Flag Ranges @@ -95,7 +95,7 @@ The `Memos` field includes arbitrary messaging data with the transaction. It is | `MemoFormat` | String | Blob | Hex value representing characters allowed in URLs. Conventionally containing information on how the memo is encoded, for example as a [MIME type](http://www.iana.org/assignments/media-types/media-types.xhtml). | | `MemoType` | String | Blob | Hex value representing characters allowed in URLs. Conventionally, a unique relation (according to [RFC 5988](http://tools.ietf.org/html/rfc5988#section-4)) that defines the format of this memo. | -The MemoType and MemoFormat fields should only consist of the following characters: `ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789-._~:/?#[]@!$&'()*+,;=%` +The `MemoType` and `MemoFormat` fields should only consist of the following characters: `ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789-._~:/?#[]@!$&'()*+,;=%` The `Memos` field is limited to no more than 1 KB in size (when serialized in binary format). @@ -123,13 +123,13 @@ Example of a transaction with a Memos field: The `Signers` field contains a [multi-signature](multi-signing.html), which has signatures from up to 8 key pairs, that together should authorize the transaction. The `Signers` list is an array of objects, each with one field, `Signer`. The `Signer` field has the following nested fields: -| Field | Type | [Internal Type][] | Description | -|:--------------|:-------|:------------------|:--------------------------------| -| Account | String | AccountID | The address associated with this signature, as it appears in the SignerList. | -| TxnSignature | String | Blob | A signature for this transaction, verifiable using the `SigningPubKey`. | -| SigningPubKey | String | Blob | The public key used to create this signature. | +| Field | Type | [Internal Type][] | Description | +|:----------------|:-------|:------------------|:--------------------------------| +| `Account` | String | AccountID | The address associated with this signature, as it appears in the signer list. | +| `TxnSignature` | String | Blob | A signature for this transaction, verifiable using the `SigningPubKey`. | +| `SigningPubKey` | String | Blob | The public key used to create this signature. | -The `SigningPubKey` must be a key that is associated with the `Account` address. If the referenced `Account` is a funded account in the ledger, then the SigningPubKey can be that account's current Regular Key if one is set. It could also be that account's Master Key, unless the [`lsfDisableMaster`](accountroot.html#accountroot-flags) flag is enabled. If the referenced `Account` address is not a funded account in the ledger, then the `SigningPubKey` must be the master key associated with that address. +The `SigningPubKey` must be a key that is associated with the `Account` address. If the referenced `Account` is a funded account in the ledger, then the `SigningPubKey` can be that account's current Regular Key if one is set. It could also be that account's Master Key, unless the [`lsfDisableMaster`](accountroot.html#accountroot-flags) flag is enabled. If the referenced `Account` address is not a funded account in the ledger, then the `SigningPubKey` must be the master key associated with that address. Because signature verification is a compute-intensive task, multi-signed transactions cost additional XRP to relay to the network. Each signature included in the multi-signature increases the [transaction cost][] required for the transaction. For example, if the current minimum transaction cost to relay a transaction to the network is `10000` drops, then a multi-signed transaction with 3 entries in the `Signers` array would need a `Fee` value of at least `40000` drops to relay. diff --git a/content/references/rippled-api/transaction-formats/transaction-types/accountset.md b/content/references/rippled-api/transaction-formats/transaction-types/accountset.md index 18c656da76..3560aba540 100644 --- a/content/references/rippled-api/transaction-formats/transaction-types/accountset.md +++ b/content/references/rippled-api/transaction-formats/transaction-types/accountset.md @@ -63,7 +63,7 @@ The available AccountSet flags are: | Flag Name | Decimal Value | Corresponding Ledger Flag | Description | |:-------------------|:--------------|:--------------------------|:--------------| -| `asfAccountTxnID` | 5 | (None) | Track the ID of this account's most recent transaction. Required for [AccountTxnID](transaction-common-fields.html#accounttxnid) | +| `asfAccountTxnID` | 5 | (None) | Track the ID of this account's most recent transaction. Required for [`AccountTxnID`](transaction-common-fields.html#accounttxnid) | | `asfDefaultRipple` | 8 | `lsfDefaultRipple` | Enable [rippling](rippling.html) on this account's trust lines by default. [New in: rippled 0.27.3][] | | `asfDepositAuth` | 9 | `lsfDepositAuth` | Enable [Deposit Authorization](depositauth.html) on this account. _(Added by the [DepositAuth amendment][].)_ | | `asfDisableMaster` | 4 | `lsfDisableMaster` | Disallow use of the master key pair. Can only be enabled if the account has configured another way to sign transactions, such as a [Regular Key](cryptographic-keys.html) or a [Signer List](multi-signing.html). | diff --git a/content/references/rippled-api/transaction-formats/transaction-types/checkcash.md b/content/references/rippled-api/transaction-formats/transaction-types/checkcash.md index 88037af138..9da3042568 100644 --- a/content/references/rippled-api/transaction-formats/transaction-types/checkcash.md +++ b/content/references/rippled-api/transaction-formats/transaction-types/checkcash.md @@ -35,7 +35,7 @@ The transaction ***must*** include either `Amount` or `DeliverMin`, but not both - If the sender of the CheckCash transaction is not the `Destination` of the check, the transaction fails with the result code `tecNO_PERMISSION`. - If the Check identified by the `CheckID` field does not exist, the transaction fails with the result `tecNO_ENTRY`. - If the Check identified by the `CheckID` field has already expired, the transaction fails with the result `tecEXPIRED`. -- If the destination of the Check has the RequireDest flag enabled but the Check, as created, does not have a destination tag, the transaction fails with the result code `tecDST_TAG_NEEDED`. +- If the destination of the Check has the `RequireDest` flag enabled but the Check, as created, does not have a destination tag, the transaction fails with the result code `tecDST_TAG_NEEDED`. - If the transaction specifies both `Amount` and `DeliverMin`, or omits both, the transaction fails with the result `temMALFORMED`. - If the `Amount` or `DeliverMin` does not match the currency (and issuer, if not XRP) of the Check, the transaction fails with the result `temBAD_CURRENCY`. diff --git a/content/references/rippled-api/transaction-formats/transaction-types/payment.md b/content/references/rippled-api/transaction-formats/transaction-types/payment.md index aaf058485d..3c279cdd21 100644 --- a/content/references/rippled-api/transaction-formats/transaction-types/payment.md +++ b/content/references/rippled-api/transaction-formats/transaction-types/payment.md @@ -29,7 +29,7 @@ Payments are also the only way to [create accounts](#creating-accounts). | Field | JSON Type | [Internal Type][] | Description | |:-----------------|:---------------------|:------------------|:---------------| -| `Amount` | [Currency Amount][] | Amount | The amount of currency to deliver. For non-XRP amounts, the nested field names MUST be lower-case. If the [**tfPartialPayment** flag](#payment-flags) is set, deliver _up to_ this amount instead. | +| `Amount` | [Currency Amount][] | Amount | The amount of currency to deliver. For non-XRP amounts, the nested field names MUST be lower-case. If the [`tfPartialPayment` flag](#payment-flags) is set, deliver _up to_ this amount instead. | | `Destination` | String | Account | The unique address of the account receiving the payment. | | `DestinationTag` | Number | UInt32 | _(Optional)_ Arbitrary tag that identifies the reason for the payment to the destination, or a hosted recipient to pay. | | `InvoiceID` | String | Hash256 | _(Optional)_ Arbitrary 256-bit hash representing a specific reason or identifier for this payment. | @@ -57,6 +57,8 @@ The Payment transaction type is a general-purpose tool that can represent severa ## Special issuer Values for SendMax and Amount + + Most of the time, the `issuer` field of a non-XRP [Currency Amount][] indicates a financial institution's [issuing address](issuing-and-operational-addresses.html). However, when describing payments, there are special rules for the `issuer` field in the `Amount` and `SendMax` fields of a payment. * There is only ever one balance for the same currency between two addresses. This means that, sometimes, the `issuer` field of an amount actually refers to a counterparty that is redeeming the issued currency, instead of the address that issued the currency. @@ -98,7 +100,7 @@ Transactions of the Payment type support additional values in the [`Flags` field A partial payment allows a payment to succeed by reducing the amount received. Partial payments are useful for [returning payments](become-an-xrp-ledger-gateway.html#bouncing-payments) without incurring additional costs to oneself. However, partial payments can also be used to exploit integrations that naively assume the `Amount` field of a successful transaction always describes the exact amount delivered. -A partial payment is any [Payment transaction][] with the **tfPartialPayment** flag enabled. A partial payment can be successful if it delivers any positive amount greater than or equal to its `DeliverMin` field (or any positive amount at all if `DeliverMin` is not specified) without sending more than the `SendMax` value. +A partial payment is any [Payment transaction][] with the `tfPartialPayment` flag enabled. A partial payment can be successful if it delivers any positive amount greater than or equal to its `DeliverMin` field (or any positive amount at all if `DeliverMin` is not specified) without sending more than the `SendMax` value. The [`delivered_amount`](transaction-metadata.html#delivered_amount) field of a payment's metadata indicates the amount of currency actually received by the destination account. @@ -109,17 +111,17 @@ For more information, see the full article on [Partial Payments](partial-payment The XRP Ledger defines the "quality" of a currency exchange as the ratio of the numeric amount in to the numeric amount out. For example, if you spend $2 USD to receive £1 GBP, then the "quality" of that exchange is `0.5`. -The [*tfLimitQuality* flag](#payment-flags) allows you to set a minimum quality of conversions that you are willing to take. This limit quality is defined as the destination `Amount` divided by the `SendMax` amount (the numeric amounts only, regardless of currency). When set, the payment processing engine avoids using any paths whose quality (conversion rate) is worse (numerically lower) than the limit quality. +The [`tfLimitQuality` flag](#payment-flags) allows you to set a minimum quality of conversions that you are willing to take. This limit quality is defined as the destination `Amount` divided by the `SendMax` amount (the numeric amounts only, regardless of currency). When set, the payment processing engine avoids using any paths whose quality (conversion rate) is worse (numerically lower) than the limit quality. -By itself, the tfLimitQuality flag reduces the number of situations in which a transaction can succeed. Specifically, it rejects payments where some part of the payment uses an unfavorable conversion, even if the overall average *average* quality of conversions in the payment is equal or better than the limit quality. If a payment is rejected in this way, the [transaction result](transaction-results.html) is `tecPATH_DRY`. +By itself, the `tfLimitQuality` flag reduces the number of situations in which a transaction can succeed. Specifically, it rejects payments where some part of the payment uses an unfavorable conversion, even if the overall average *average* quality of conversions in the payment is equal or better than the limit quality. If a payment is rejected in this way, the [transaction result](transaction-results.html) is `tecPATH_DRY`. Consider the following example. If I am trying to send you 100 Chinese Yuan (`Amount` = 100 CNY) for 20 United States dollars (`SendMax` = 20 USD) or less, then the limit quality is `5`. Imagine one trader is offering ¥95 for $15 (a ratio of about `6.3` CNY per USD), but the next best offer in the market is ¥5 for $2 (a ratio of `2.5` CNY per USD). If I were to take both offers to send you 100 CNY, then it would cost me 17 USD, for an average quality of about `5.9`. -Without the tfLimitQuality flag set, this transaction would succeed, because the $17 it costs me is within my specified `SendMax`. However, with the tfLimitQuality flag enabled, the transaction would fail instead, because the path to take the second offer has a quality of `2.5`, which is worse than the limit quality of `5`. +Without the `tfLimitQuality` flag set, this transaction would succeed, because the $17 it costs me is within my specified `SendMax`. However, with the `tfLimitQuality` flag enabled, the transaction would fail instead, because the path to take the second offer has a quality of `2.5`, which is worse than the limit quality of `5`. -The tfLimitQuality flag is most useful when combined with [partial payments](partial-payments.html). When both *tfPartialPayment* and *tfLimitQuality* are set on a transaction, then the transaction delivers as much of the destination `Amount` as it can, without using any conversions that are worse than the limit quality. +The `tfLimitQuality` flag is most useful when combined with [partial payments](partial-payments.html). When both `tfPartialPayment` and `tfLimitQuality` are set on a transaction, then the transaction delivers as much of the destination `Amount` as it can, without using any conversions that are worse than the limit quality. -In the above example with a ¥95/$15 offer and a ¥5/$2 offer, the situation is different if my transaction has both tfPartialPayment and tfLimitQuality enabled. If we keep my `SendMax` of 20 USD and a destination `Amount` of 100 CNY, then the limit quality is still `5`. However, because I am doing a partial payment, the transaction sends as much as it can instead of failing if the full destination amount cannot be sent. This means that my transaction consumes the ¥95/$15 offer, whose quality is about `6.3`, but it rejects the ¥5/$2 offer because that offer's quality of `2.5` is worse than the quality limit of `5`. In the end, my transaction only delivers ¥95 instead of the full ¥100, but it avoids wasting money on poor exchange rates. +In the above example with a ¥95/$15 offer and a ¥5/$2 offer, the situation is different if my transaction has both `tfPartialPayment` and `tfLimitQuality` enabled. If we keep my `SendMax` of 20 USD and a destination `Amount` of 100 CNY, then the limit quality is still `5`. However, because I am doing a partial payment, the transaction sends as much as it can instead of failing if the full destination amount cannot be sent. This means that my transaction consumes the ¥95/$15 offer, whose quality is about `6.3`, but it rejects the ¥5/$2 offer because that offer's quality of `2.5` is worse than the quality limit of `5`. In the end, my transaction only delivers ¥95 instead of the full ¥100, but it avoids wasting money on poor exchange rates. {% include '_snippets/rippled-api-links.md' %} diff --git a/content/references/rippled-api/validator-list.md b/content/references/rippled-api/validator-list.md index 451298b1c0..72b3c40156 100644 --- a/content/references/rippled-api/validator-list.md +++ b/content/references/rippled-api/validator-list.md @@ -20,7 +20,7 @@ To request the Peer Crawler information, make the following HTTP request: The validator list contents are signed with a separate cryptographic key, so you can verify their integrity regardless of the TLS certificate used. -**Tip:** Since this request uses the GET method, you can test this request using just the URL bar of your web browser. For example, requests Ripple's recommended list from one of Ripple's public servers. +**Tip:** Since this request uses the GET method, you can test this request using the URL bar of your web browser. For example, requests Ripple's recommended list from one of Ripple's public servers. ## Response Format diff --git a/content/references/xrp-ledger-toml.md b/content/references/xrp-ledger-toml.md index f42fd413df..ffa44978f5 100644 --- a/content/references/xrp-ledger-toml.md +++ b/content/references/xrp-ledger-toml.md @@ -160,9 +160,9 @@ The specification does not define a `domain` field; the field should be determin ### Validators -The validators list provides information about validating servers you operate. If present, the validators list MUST BE presented as an array of tables, with each entry using the header `[[VALIDATORS]]`, including double square brackets. Each entry describes a separate validating server. +The validators list provides information about validating servers you run. If present, the validators list MUST BE presented as an array of tables, with each entry using the header `[[VALIDATORS]]`, including double square brackets. Each entry describes a separate validating server. -The _first_ `[[VALIDATORS]]` entry in the file is treated as your primary validator. If you operate one or more validators for the production XRP Ledger, you should put the one you want others to trust first. +The _first_ `[[VALIDATORS]]` entry in the file is treated as your primary validator. If you run one or more validators for the production XRP Ledger, you should put the one you want others to trust first. For _each_ `[[VALIDATORS]]` entry, you MAY provide any of the following fields: @@ -275,7 +275,7 @@ For other web servers, see [I want to add CORS support to my server](https://ena ## Domain Verification -One use for the `xrp-ledger.toml` file is verifying that the same entity that operates a particular domain also operates a particular validator, as identified by the validator's public key. Verifying that a domain and a validator are owned by the same entity provides greater assurances of the identity of the validator operator and is a recommended step for becoming a trusted validator. (For other recommendations, see [Properties of a Good Validator](run-rippled-as-a-validator.html#1-understand-the-traits-of-a-good-validator).) +One use for the `xrp-ledger.toml` file is verifying that the same entity that runs a particular domain also runs a particular validator, as identified by the validator's public key. Verifying that a domain and a validator are owned by the same entity provides greater assurances of the identity of the validator operator and is a recommended step for becoming a trusted validator. (For other recommendations, see [Properties of a Good Validator](run-rippled-as-a-validator.html#1-understand-the-traits-of-a-good-validator).) Domain verification requires establishing a two-way link between the domain operator and the validator: @@ -340,7 +340,7 @@ Update [the contents of your `xrp-ledger.toml` file](#contents) with the `attest ## Account Verification -Similar to [Domain Verification](#domain-verification), account verification is the idea of proving that the same entity operates a particular domain and a particular XRP Ledger address. Account verification is not necessary for using the XRP Ledger or providing an `xrp-ledger.toml` file, but you may desire to verify your accounts in the name of transparency. +Similar to [Domain Verification](#domain-verification), account verification is the idea of proving that the same entity controls a particular domain and a particular XRP Ledger address. Account verification is not necessary for using the XRP Ledger or providing an `xrp-ledger.toml` file, but you may desire to verify your accounts in the name of transparency. Account verification requires establishing a two-way link between the domain operator and the address: @@ -356,7 +356,7 @@ Account verification requires establishing a two-way link between the domain ope Since setting the `Domain` requires sending a transaction, whoever set the `Domain` value must have possessed the account's secret key when the transaction was sent. -Either of these two links, on their own, SHOULD NOT be considered authoritative. Anyone could host an `xrp-ledger.toml` file claiming ownership of any account, and any account operator could set its `Domain` field to any string it wants. If the two match, it provides strong evidence that the same entity operates both. +Either of these two links, on their own, SHOULD NOT be considered authoritative. Anyone could host an `xrp-ledger.toml` file claiming ownership of any account, and any account operator could set its `Domain` field to any string it wants. If the two match, it provides strong evidence that the same entity controls both. ## Acknowledgements diff --git a/content/tutorials/get-started/get-started-with-rippleapi-for-javascript.md b/content/tutorials/get-started/get-started-with-rippleapi-for-javascript.md index 835b0b233c..dc82e45f56 100644 --- a/content/tutorials/get-started/get-started-with-rippleapi-for-javascript.md +++ b/content/tutorials/get-started/get-started-with-rippleapi-for-javascript.md @@ -20,13 +20,13 @@ This step depends on your operating system. Ripple recommends using [the officia After you have installed Node.js, you can check the version of the `node` binary from a command line: -``` +```sh node --version ``` On some platforms, the binary is named `nodejs` instead: -``` +```sh nodejs --version ``` @@ -40,7 +40,7 @@ This step depends on your operating system. Ripple recommends using [the officia After you have installed Yarn, you can check the version of the `yarn` binary from a command line: -``` +```sh yarn --version ``` @@ -55,13 +55,13 @@ Complete these steps to use Yarn to install RippleAPI and dependencies. Create a folder called (for example) `my_ripple_experiment`: -``` +```sh mkdir my_ripple_experiment && cd my_ripple_experiment ``` Optionally, start a [Git](https://git-scm.com/book/en/v2/Getting-Started-Installing-Git) repository in that directory so you can track changes to your code. -``` +```sh git init ``` @@ -75,16 +75,17 @@ Use the following template, which includes: - RippleAPI itself (`ripple-lib`) - (Optional) [ESLint](http://eslint.org/) (`eslint`) for checking code quality. -``` +```json {% include '_code-samples/rippleapi_quickstart/package.json' %} ``` + ### 3. Use Yarn to install RippleAPI and dependencies Use Yarn to install RippleAPI and the dependencies defined in the `package.json` file you created for your project. -``` +```sh yarn ``` @@ -92,7 +93,7 @@ This installs RippleAPI and the dependencies into the local folder `node_modules The install process may end with a few warnings. You may safely ignore the following warnings: -``` +```text warning eslint > file-entry-cache > flat-cache > circular-json@0.3.3: CircularJSON is in maintenance only, flatted is its successor. npm WARN optional Skipping failed optional dependency /chokidar/fsevents: @@ -106,7 +107,7 @@ npm WARN notsup Not compatible with your operating system or architecture: fseve This script, `get-account-info.js`, fetches information about a hard-coded account. Use it to test that RippleAPI works: -``` +```js {% include '_code-samples/rippleapi_quickstart/get-account-info.js' %} ``` @@ -116,13 +117,13 @@ This script, `get-account-info.js`, fetches information about a hard-coded accou Run your first RippleAPI script using this command: -``` +```sh node get-account-info.js ``` Output: -``` +```text getting account info for rf1BiGeXwwQoi8Z2ueFYTEXSwuJYfV2Jpn { sequence: 359, xrpBalance: '75.181663', @@ -143,7 +144,7 @@ In addition to RippleAPI-specific code, this script uses syntax and conventions ### Script opening -``` +```js 'use strict'; const RippleAPI = require('ripple-lib').RippleAPI; ``` @@ -155,7 +156,7 @@ The second line imports RippleAPI into the current scope using Node.js's require ### Instantiating the API -``` +```js const api = new RippleAPI({ server: 'wss://s1.ripple.com' // Public rippled server }); @@ -165,7 +166,7 @@ This section creates a new instance of the RippleAPI class, assigning it to the The one argument to the constructor is an options object, which has [a variety of options](rippleapi-reference.html#parameters). The `server` parameter tells it where it should connect to a `rippled` server. -- The example `server` setting uses a secure WebSocket connection to connect to one of the public servers that Ripple (the company) operates. +- The example `server` setting uses a secure WebSocket connection to connect to one of the public servers that Ripple (the company) runs. - If you don't include the `server` option, RippleAPI runs in [offline mode](rippleapi-reference.html#offline-functionality) instead, which only provides methods that don't need network connectivity. - You can specify a [XRP Ledger Test Net](xrp-test-net-faucet.html) server instead to connect to the parallel-world Test Network instead of the production XRP Ledger. - If you [run your own `rippled`](install-rippled.html), you can instruct it to connect to your local server. For example, you might say `server: 'ws://localhost:5005'` instead. @@ -173,7 +174,7 @@ The one argument to the constructor is an options object, which has [a variety o ### Connecting and Promises -``` +```js api.connect().then(() => { ``` @@ -188,7 +189,7 @@ The example uses [arrow function](https://developer.mozilla.org/en-US/docs/Web/J ### Custom code -``` +```js /* begin custom code ------------------------------------ */ const myAddress = 'rf1BiGeXwwQoi8Z2ueFYTEXSwuJYfV2Jpn'; @@ -215,7 +216,7 @@ The `getAccountInfo` API method returns another Promise, so the line `}).then( i ### Cleanup -``` +```js }).then(() => { return api.disconnect(); }).then(() => { @@ -223,7 +224,7 @@ The `getAccountInfo` API method returns another Promise, so the line `}).then( i }).catch(console.error); ``` -The rest of the sample code is mostly more [boilerplate code](rippleapi-reference.html#boilerplate). The first line ends the previous callback function, then chains to another callback to run when it ends. That method disconnects cleanly from the XRP Ledger, and has yet another callback which writes to the console when it finishes. If your script waits on [RippleAPI events](rippleapi-reference.html#api-events), do not disconnect until you are done waiting for events. +The rest of the sample code is more [standard setup code](rippleapi-reference.html#boilerplate). The first line ends the previous callback function, then chains to another callback to run when it ends. That method disconnects cleanly from the XRP Ledger, and has yet another callback which writes to the console when it finishes. If your script waits on [RippleAPI events](rippleapi-reference.html#api-events), do not disconnect until you are done waiting for events. The `catch` method ends this Promise chain. The callback provided here runs if any of the Promises or their callback functions encounters an error. In this case, we pass the standard `console.error` function, which writes to the console, instead of defining a custom callback. You could define a smarter callback function here to intelligently catch certain error types. @@ -237,7 +238,7 @@ One of the biggest challenges in using the XRP Ledger (or any decentralized syst {% include '_code-samples/rippleapi_quickstart/submit-and-verify.js' %} ``` -This code creates and submits an order transaction, although the same principles apply to other types of transactions as well. After submitting the transaction, the code uses a new Promise, which queries the ledger again after using setTimeout to wait a fixed amount of time, to see if the transaction has been verified. If it hasn't been verified, the process repeats until either the transaction is found in a validated ledger or the returned ledger is higher than the LastLedgerSequence parameter. +This code creates and submits an order transaction, although the same principles apply to other types of transactions as well. After submitting the transaction, the code uses a new Promise, which queries the ledger again after using `setTimeout` to wait a fixed amount of time, to see if the transaction has been verified. If it hasn't been verified, the process repeats until either the transaction is found in a validated ledger or the returned ledger is higher than the `LastLedgerSequence` parameter. In rare cases (particularly with a large delay or a loss of power), the `rippled` server may be missing a ledger version between when you submitted the transaction and when you determined that the network has passed the `maxLedgerVersion`. In this case, you cannot be definitively sure whether the transaction has failed, or has been included in one of the missing ledger versions. RippleAPI returns `MissingLedgerHistoryError` in this case. @@ -251,6 +252,7 @@ See [Reliable Transaction Submission](reliable-transaction-submission.html) for RippleAPI can also be used in a web browser if you compile a browser-compatible version and include [lodash](https://www.npmjs.com/package/lodash) as a dependency before the RippleAPI script. + ## Build a Browser-Compatible Version of RippleAPI @@ -268,7 +270,7 @@ cd ripple-lib git checkout master ``` -Alternatively, you can download an archive (.zip or .tar.gz) of a specific release from the [RippleAPI releases page](https://github.com/ripple/ripple-lib/releases) and extract it. +Alternatively, you can download an archive (`.zip` or `.tar.gz`) of a specific release from the [RippleAPI releases page](https://github.com/ripple/ripple-lib/releases) and extract it. ### 2. Install Yarn @@ -285,7 +287,7 @@ yarn ### 4. Use Gulp to build a single JavaScript output -RippleAPI comes with code to use the [gulp](http://gulpjs.com/) package to compile all its source code into browser-compatible JavaScript files. Gulp is automatically installed as one of the dependencies, so all you have to do is run it. RippleAPI's configuration makes this easy: +RippleAPI comes with code to use the [gulp](http://gulpjs.com/) package to compile all its source code into browser-compatible JavaScript files. Gulp is automatically installed as one of the dependencies, so all you have to do is run it, such as with following command: ``` yarn run build @@ -310,7 +312,7 @@ Output: This may take a while. At the end, the build process creates a new `build/` folder, which contains the files you want. -The file `build/ripple-.js` is a straight export of RippleAPI (whatever version you built) ready to be used in browsers. The file ending in `-min.js` is the same thing, but with the content [minified](https://en.wikipedia.org/wiki/Minification_%28programming%29) for faster loading. +The file `build/ripple-.js` is a straight export of RippleAPI (whatever version you built) ready to be used in browsers. The file ending in `-min.js` is the same thing, but with the content [minified](https://en.wikipedia.org/wiki/Minification_%28programming%29) for faster loading. @@ -326,7 +328,7 @@ To use this example, you must first [build a browser-compatible version of Rippl {% include '_code-samples/rippleapi_quickstart/browser-demo.html' %} ``` -This demo HTML loads Lodash v4.17.11 from CDNJS on Cloudflare and then loads ripple-lib v1.1.2, but you could also download and load a variant of Lodash locally. +This demo HTML loads Lodash v4.17.11 from CDNJS on Cloudflare and then loads ripple-lib v1.1.2, but you could also download and load a variant of Lodash locally. ## See Also diff --git a/content/tutorials/get-started/get-started-with-the-rippled-api.md b/content/tutorials/get-started/get-started-with-the-rippled-api.md index 075b50c762..8124df2228 100644 --- a/content/tutorials/get-started/get-started-with-the-rippled-api.md +++ b/content/tutorials/get-started/get-started-with-the-rippled-api.md @@ -47,7 +47,7 @@ The response to [this command][server_info method] shows you the current status ## JSON-RPC -You can use any HTTP client (like [RESTED for Firefox](https://addons.mozilla.org/en-US/firefox/addon/rested/), [Postman for Chrome](https://chrome.google.com/webstore/detail/postman/fhbjgbiflinjbdggehcddcbncdddomop?hl=en) or [Online HTTP client ExtendsClass](https://extendsclass.com/rest-client-online.html)) to make JSON-RPC calls a `rippled` server. Most programming languages have a library for making HTTP requests built in. +You can use any HTTP client (like [RESTED for Firefox](https://addons.mozilla.org/en-US/firefox/addon/rested/), [Postman for Chrome](https://chrome.google.com/webstore/detail/postman/fhbjgbiflinjbdggehcddcbncdddomop?hl=en) or [Online HTTP client ExtendsClass](https://extendsclass.com/rest-client-online.html)) to make JSON-RPC calls a `rippled` server. Most programming languages have a library for making HTTP requests built in. Example JSON-RPC request: diff --git a/content/tutorials/get-started/look-up-transaction-results.md b/content/tutorials/get-started/look-up-transaction-results.md index 607bd89197..85ee6b8f50 100644 --- a/content/tutorials/get-started/look-up-transaction-results.md +++ b/content/tutorials/get-started/look-up-transaction-results.md @@ -54,14 +54,14 @@ The following example shows a successful transaction, as returned by the [tx met } ``` -This example shows an [AccountSet transaction][] sent by the [account](accounts.html) with address rf1BiGeXwwQoi8Z2ueFYTEXSwuJYfV2Jpn, using [Sequence number][] 376. The transaction's [identifying hash][] is `017DED8F5E20F0335C6F56E3D5EE7EF5F7E83FB81D2904072E665EEA69402567` and its [result](transaction-results.html) is `tesSUCCESS`. The transaction was included in ledger version 46447423, which has been validated, so these results are final. +This example shows an [AccountSet transaction][] sent by the [account](accounts.html) with address `rf1BiGeXwwQoi8Z2ueFYTEXSwuJYfV2Jpn`, using [Sequence number][] 376. The transaction's [identifying hash][] is `017DED8F5E20F0335C6F56E3D5EE7EF5F7E83FB81D2904072E665EEA69402567` and its [result](transaction-results.html) is `tesSUCCESS`. The transaction was included in ledger version 46447423, which has been validated, so these results are final. ### Case: Not Included in a Validated Ledger **If a transaction is not included in a validated ledger, it cannot possibly have had _any_ effect on the shared XRP Ledger state.** If the transaction's failure to be included in a ledger is [_final_](finality-of-results.html), then it cannot have any future effect, either. -If the transaction's failure is not final, it may still become included in a _future_ validated ledger. You can use the provisional results of applying the transaction to the current open ledger as a preview of the likely effects the transaction may have in a final ledger, but those results can change due to [numerous factors](finality-of-results.html#how-can-non-final-results-change). +If the transaction's failure is not final, it may still become included in a _future_ validated ledger. You can use the provisional results of applying the transaction to the current open ledger as a preview of the likely effects the transaction may have in a final ledger, but those results can change due to [many factors](finality-of-results.html#how-can-non-final-results-change). ### Case: Included in a Validated Ledger @@ -148,7 +148,7 @@ The _only_ changes made by this [no-op transaction](cancel-or-skip-a-transaction **Note:** Although the metadata does not explicitly show it, any time a transaction modifies a ledger object, it updates that object's `PreviousTxnID` and `PreviousTxnLgrSeq` fields with the current transaction's information. If the same sender has multiple transactions in a single ledger version, each one after the first provides a `PreviousTxnLgrSeq` whose value is the [ledger index](basic-data-types.html#ledger-index) of the ledger version that included all those transactions. -Since the `ModifiedNode` entry for rf1BiGeXwwQoi8Z2ueFYTEXSwuJYfV2Jpn's account is the only object in the `AffectedNodes` array, no other changes were made to the ledger as a result of this transaction. +Since the `ModifiedNode` entry for `rf1BiGeXwwQoi8Z2ueFYTEXSwuJYfV2Jpn`'s account is the only object in the `AffectedNodes` array, no other changes were made to the ledger as a result of this transaction. **Tip:** If the transaction sends or receives XRP, the sender's balance changes are combined with the transaction cost, resulting in a single change to the `Balance` field in the net amount. For example, if you sent 1 XRP (1,000,000 drops) and destroyed 10 drops for the transaction cost, the metadata shows your `Balance` decreasing by 1,000,010 drops of XRP. @@ -187,7 +187,7 @@ Example of increasing an Account's `OwnerCount`: Many transaction types create or modify [DirectoryNode objects](directorynode.html). These objects are for bookkeeping: tracking all objects owned by an account, or all Offers to exchange currency at the same exchange rate. If the transaction created new objects in the ledger, it may need to add entries to an existing DirectoryNode object, or add another DirectoryNode object to represent another page of the directory. If the transaction removed objects from the ledger, it may delete one or more DirectoryNode objects that are no longer needed. -Example of a CreatedNode representing a new Offer Directory: +Example of a `CreatedNode` representing a new Offer Directory: ```json { @@ -212,9 +212,9 @@ A [Payment transaction][] can represent a direct XRP-to-XRP transaction, a [cros XRP amounts are tracked in the `Balance` field of `AccountRoot` objects. (XRP can also exist in [Escrow objects](escrow-object.html) and [PayChannel objects](paychannel.html), but Payment transactions cannot affect those.) -You should always use [the delivered_amount field](partial-payments.html#the-delivered_amount-field) to see how much a payment delivered. +You should always use [the `delivered_amount` field](partial-payments.html#the-delivered_amount-field) to see how much a payment delivered. -If the payment contains a `CreatedNode` of LedgerEntryType `AccountRoot`, that means the payment [funded a new account](accounts.html#creating-accounts) in the ledger. +If the payment contains a `CreatedNode` with `"LedgerEntryType": "AccountRoot"`, that means the payment [funded a new account](accounts.html#creating-accounts) in the ledger. #### Issued Currency Payments @@ -232,11 +232,11 @@ The [`QualityIn` and `QualityOut` settings of trust lines](trustset.html) can af If the amount to be sent or received is outside of the [issued currency precision](currency-formats.html#issued-currency-precision), it is possible that one side may be debited for an amount that is rounded to nothing on the other side of the transaction. Therefore, when two parties transact while their balances are different by a factor of 1016, it is possible that rounding may effectively "create" or "destroy" small amounts of the issued currency. (XRP is never rounded, so this is not possible with XRP.) -Depending on the length of the [paths](paths.html), the metadata for cross-currency payments can be _long_. For example, [transaction 8C55AFC2A2AA42B5CE624AEECDB3ACFDD1E5379D4E5BF74A8460C5E97EF8706B](https://xrpcharts.ripple.com/#/transactions/8C55AFC2A2AA42B5CE624AEECDB3ACFDD1E5379D4E5BF74A8460C5E97EF8706B) delivered 2.788 GCB issued by rHaaans..., spending XRP but passing through USD from 2 issuers, paying XRP to 2 accounts, removing an unfunded offer from r9ZoLsJ to trade EUR for ETH, plus bookkeeping for a total of 17 different ledger objects modified. +Depending on the length of the [paths](paths.html), the metadata for cross-currency payments can be _long_. For example, [transaction 8C55AFC2A2AA42B5CE624AEECDB3ACFDD1E5379D4E5BF74A8460C5E97EF8706B](https://xrpcharts.ripple.com/#/transactions/8C55AFC2A2AA42B5CE624AEECDB3ACFDD1E5379D4E5BF74A8460C5E97EF8706B) delivered 2.788 GCB issued by `rHaaans...`, spending XRP but passing through USD from 2 issuers, paying XRP to 2 accounts, removing an unfunded offer from `r9ZoLsJ...` to trade EUR for ETH, plus bookkeeping for a total of 17 different ledger objects modified. ### Offers -An [OfferCreate transaction][] may or may not create an object in the ledger, depending on how much was matched and whether the transaction used flags such as `tfImmediateOrCancel`. Look for a `CreatedNode` entry with LedgerEntryType `Offer` to see if the transaction added a new Offer to the ledger's order books. For example: +An [OfferCreate transaction][] may or may not create an object in the ledger, depending on how much was matched and whether the transaction used flags such as `tfImmediateOrCancel`. Look for a `CreatedNode` entry with `"LedgerEntryType": "Offer"` to see if the transaction added a new Offer to the ledger's order books. For example: ```json { @@ -261,7 +261,7 @@ An [OfferCreate transaction][] may or may not create an object in the ledger, de A `ModifiedNode` of type `Offer` indicates an Offer that was matched and partially consumed. A single transaction can consume a large number of Offers. An Offer to trade two issued currencies might also consume Offers to trade XRP because of [auto-bridging](autobridging.html). All or part of an exchange can be auto-bridged. -A `DeletedNode` of LedgerEntryType `Offer` can indicate a matching Offer that was fully consumed, an Offer that was found to be [expired or unfunded](offers.html#lifecycle-of-an-offer) at the time of processing, or an Offer that was canceled as part of placing a new Offer. You can recognize a canceled Offer because the `Account` that placed it is the sender of the transaction that deleted it. +A `DeletedNode` of type `Offer` can indicate a matching Offer that was fully consumed, an Offer that was found to be [expired or unfunded](offers.html#lifecycle-of-an-offer) at the time of processing, or an Offer that was canceled as part of placing a new Offer. You can recognize a canceled Offer because the `Account` that placed it is the sender of the transaction that deleted it. Example of a deleted Offer: @@ -293,23 +293,23 @@ Example of a deleted Offer: Offers can create, delete, and modify both types of [DirectoryNode objects](directorynode.html), to keep track of who placed which Offers and which Offers are available at which exchange rates. Generally, users don't need to pay close attention to this bookkeeping. -An [OfferCancel transaction][] may have the code `tesSUCCESS` even if there was no Offer to delete. Look for a `DeletedNode` of LedgerEntryType `Offer` to confirm that the transaction actually deleted an Offer. If not, the Offer may already have been removed by a previous transaction, or the OfferCancel transaction may have used the wrong sequence number in the `OfferSequence` field. +An [OfferCancel transaction][] may have the code `tesSUCCESS` even if there was no Offer to delete. Look for a `DeletedNode` of type `Offer` to confirm that the transaction actually deleted an Offer. If not, the Offer may already have been removed by a previous transaction, or the OfferCancel transaction may have used the wrong sequence number in the `OfferSequence` field. If an OfferCreate transaction shows a `CreatedNode` of type `RippleState`, that indicates that [the Offer created a trust line](offers.html#offers-and-trust) to hold an issued currency received in the trade. ### Escrows -A successful [EscrowCreate transaction][] creates an [Escrow object](escrow-object.html) in the ledger. Look for a `CreatedNode` entry of LedgerEntryType `Escrow`. The `NewFields` should show an `Amount` equal to the amount of XRP escrowed, and other properties as specified. +A successful [EscrowCreate transaction][] creates an [Escrow object](escrow-object.html) in the ledger. Look for a `CreatedNode` entry of type `Escrow`. The `NewFields` should show an `Amount` equal to the amount of XRP escrowed, and other properties as specified. -A successful EscrowCreate transaction also debits the same amount of XRP from the sender. Look for a `ModifiedNode` of LedgerEntryType `AccountRoot`, where the `Account` in the final fields matches the address from the `Account` in the transaction instructions. The `Balance` should show the decrease in XRP due to the escrowed XRP (in addition to the XRP destroyed to pay the transaction cost). +A successful EscrowCreate transaction also debits the same amount of XRP from the sender. Look for a `ModifiedNode` of type `AccountRoot`, where the `Account` in the final fields matches the address from the `Account` in the transaction instructions. The `Balance` should show the decrease in XRP due to the escrowed XRP (in addition to the XRP destroyed to pay the transaction cost). -A successful [EscrowFinish transaction][] modifies the `AccountRoot` of the recipient to increase their XRP balance (in the `Balance` field), deletes the `Escrow` object, and reduces the owner count of the escrow creator. Since the escrow's creator, recipient, and finisher may all be different accounts or the same, this can result in _one to three_ `ModifiedNode` objects of LedgerEntryType `AccountRoot`. A successful [EscrowCancel transaction][] is very similar, except it sends the XRP back to the original creator of the escrow. +A successful [EscrowFinish transaction][] modifies the `AccountRoot` of the recipient to increase their XRP balance (in the `Balance` field), deletes the `Escrow` object, and reduces the owner count of the escrow creator. Since the escrow's creator, recipient, and finisher may all be different accounts or the same, this can result in _one to three_ `ModifiedNode` objects of type `AccountRoot`. A successful [EscrowCancel transaction][] is very similar, except it sends the XRP back to the original creator of the escrow. Of course, an EscrowFinish can only be successful if it meets the conditions of the escrow, and an EscrowCancel can only be successful if the expiration of the Escrow object is before the close time of the previous ledger. Escrow transactions also do normal [bookkeeping](#general-purpose-bookkeeping) for adjusting the sender's owner reserve and the directories of the accounts involved. -In the following excerpt, we see that r9UUEX...'s balance increases by 1 billion XRP and its owner count decreases by 1 because an escrow from that account to itself finished successfully. The `Sequence` number does not change because [a third party completed the escrow](https://xrpcharts.ripple.com/#/transactions/C4FE7F5643E20E7C761D92A1B8C98320614DD8B8CD8A04CFD990EBC5A39DDEA2): +In the following excerpt, we see that `r9UUEX...`'s balance increases by 1 billion XRP and its owner count decreases by 1 because an escrow from that account to itself finished successfully. The `Sequence` number does not change because [a third party completed the escrow](https://xrpcharts.ripple.com/#/transactions/C4FE7F5643E20E7C761D92A1B8C98320614DD8B8CD8A04CFD990EBC5A39DDEA2): ```json { @@ -351,11 +351,11 @@ In the following excerpt, we see that r9UUEX...'s balance increases by 1 billion ### Payment Channels -Look for a `CreatedNode` of LedgerEntryType `PayChannel` when creating a payment channel. You should also find a `ModifiedNode` of LedgerEntryType `AccountRoot` showing the decrease in the sender's balance. Look for an `Account` field in the `FinalFields` to confirm that the address matches the sender, and look at the difference in the `Balance` fields to see the change in XRP balance. +Look for a `CreatedNode` of type `PayChannel` when creating a payment channel. You should also find a `ModifiedNode` of type `AccountRoot` showing the decrease in the sender's balance. Look for an `Account` field in the `FinalFields` to confirm that the address matches the sender, and look at the difference in the `Balance` fields to see the change in XRP balance. The metadata also lists the newly-created payment channel in the destination's [owner directory](directorynode.html). This prevents an account from [being deleted](accounts.html#deletion-of-accounts) if it is the destination of an open payment channel. (This behavior was added by the [fixPayChanRecipientOwnerDir amendment](known-amendments.html#fixpaychanrecipientownerdir).) -There are several ways to request to close a payment channel, aside from the immutable `CancelAfter` time of the channel (which is only set on creation). If a transaction schedules a channel to close, there is a `ModifiedNode` entry of LedgerEntryType `PayChannel` for the channel, with the newly-added close time in the `Expiration` field of the `FinalFields`. The following example shows the changes to a `PayChannel` in a case where the sender requested to close the channel without redeeming a claim: +There are several ways to request to close a payment channel, aside from the immutable `CancelAfter` time of the channel (which is only set on creation). If a transaction schedules a channel to close, there is a `ModifiedNode` entry of type `PayChannel` for the channel, with the newly-added close time in the `Expiration` field of the `FinalFields`. The following example shows the changes to a `PayChannel` in a case where the sender requested to close the channel without redeeming a claim: ```json { @@ -385,7 +385,7 @@ There are several ways to request to close a payment channel, aside from the imm TrustSet transactions create, modify, or delete [trust lines](trust-lines-and-issuing.html), which are represented as [`RippleState` objects](ripplestate.html). A single `RippleState` object contains settings for both parties involved, including their limits, [rippling settings](rippling.html), and more. Creating and modifying trust lines can also [adjust the sender's owner reserve and owner directory](#general-purpose-bookkeeping). -The following example shows a new trust line, where **rf1BiG...** is willing to hold up to 110 USD issued by **rsA2Lp...**: +The following example shows a new trust line, where **`rf1BiG...`** is willing to hold up to 110 USD issued by **`rsA2Lp...`**: ```json { @@ -426,7 +426,7 @@ Most other transactions create a specific type of ledger entry and [adjust the s ### Pseudo-Transactions -[Pseudo-transactions](pseudo-transaction-types.html) also have metadata, but they do not follow all the rules of normal transactions. They are not tied to a real account (the `Account` value is just the [base58-encoded form of the number 0](accounts.html#special-addresses)), so they do not modify an AccountRoot object in the ledger to increase the `Sequence` number or destroy XRP. Pseudo-transactions only make specific changes to special ledger objects: +[Pseudo-transactions](pseudo-transaction-types.html) also have metadata, but they do not follow all the rules of normal transactions. They are not tied to a real account (the `Account` value is the [base58-encoded form of the number 0](accounts.html#special-addresses)), so they do not modify an AccountRoot object in the ledger to increase the `Sequence` number or destroy XRP. Pseudo-transactions only make specific changes to special ledger objects: - [EnableAmendment pseudo-transactions][] modify the [Amendments ledger object](amendments-object.html) to track which amendments are enabled, and which ones are pending with majority support and for how long. - [SetFee pseudo-transactions][] modify the [FeeSettings ledger object](feesettings.html) to change the base levels for the [transaction cost](transaction-cost.html) and [reserve requirements](reserves.html). diff --git a/content/tutorials/get-started/monitor-incoming-payments-with-websocket.ja.md b/content/tutorials/get-started/monitor-incoming-payments-with-websocket.ja.md index 5b74b5588b..133bad492f 100644 --- a/content/tutorials/get-started/monitor-incoming-payments-with-websocket.ja.md +++ b/content/tutorials/get-started/monitor-incoming-payments-with-websocket.ja.md @@ -110,11 +110,11 @@ $("#connect-button").click((event) => { WebSocket接続では、複数のメッセージをどちらの方向にも送信することが可能で、要求と応答の間に厳密な1:1の相互関係がないため、各着信メッセージに対応する処理を識別する必要があります。この処理をコーディングする際の優れたモデルとして、「ディスパッチャー」関数の設定が挙げられます。この関数は着信メッセージを読み取り、各メッセージを正しいコードのパスに中継して処理します。メッセージを適切にディスパッチできるように、`rippled`サーバーでは、すべてのWebSocketメッセージで`type`フィールドを使用できます。 - クライアント側からの要求への直接の応答となるメッセージの場合、`type`は文字列の`response`です。この場合、サーバーは以下も提供します。 - + - この応答に対する要求で指定された`id`に一致する`id`フィールド（応答が順序どおりに到着しない可能性があるため、これは重要です）。 - + - APIが要求の処理に成功したかどうかを示す`status`フィールド。文字列値`success`は、[成功した応答](response-formatting.html)を示します。文字列値`error`は、[エラー](error-formatting.html)を示します。 - + **警告:** トランザクションを送信する際、WebSocketメッセージの先頭にある`success`の`status`は、必ずしもトランザクション自体が成功したことを意味しません。これは、サーバーによって要求が理解されたということのみを示します。トランザクションの実際の結果を確認するには、[トランザクションの結果の確認](look-up-transaction-results.html)を参照してください。 - [サブスクリプション](subscribe.html)からのフォローアップメッセージの場合、`type`は、新しいトランザクション、レジャーまたは検証の通知など、フォローアップメッセージのタイプを示します。または継続している[pathfinding要求](path_find.html)のフォローアップを示します。クライアントがこれらのメッセージを受信するのは、それらをサブスクライブしている場合のみです。 @@ -335,19 +335,19 @@ WS_HANDLERS["transaction"] = log_tx - **`transaction.Account`** フィールドはトランザクションの送信元です。他の人が送信したトランザクションのみを探している場合は、このフィールドがあなたのアドレスと一致するトランザクションを無視できます（自身に対する複数通貨間の支払いが _可能である_ 点に注意してください）。 - **`transaction.TransactionType`フィールド**はトランザクションのタイプです。アカウントに通貨を送金できる可能性があるトランザクションのタイプは以下のとおりです。 - + - **[Paymentトランザクション][]** はXRPまたは[発行済み通貨](issued-currencies.html)を送金できます。受取人のアドレスを含んでいる`transaction.Destination`フィールドによってこれらを絞り込み、必ず`meta.delivered_amount`を使用して実際に支払われた額を確認します。XRPの額は、[文字列のフォーマットで記述されます](basic-data-types.html#通貨額の指定)。 - + **警告:** 代わりに`transaction.Amount`フィールドを使用すると、[Partial Paymentの悪用](partial-payments.html#partial-paymentの悪用)に対して脆弱になる可能性があります。不正使用者はこの悪用を行ってあなたをだまし、あなたが支払ったよりも多くの金額を交換または引き出すことができます。 - + - **[CheckCashトランザクション][]** :not_enabled: では、アカウントは別のアカウントの[CheckCreateトランザクション][]によって承認された金額を受け取ることができます。**CheckCashトランザクション**のメタデータを確認すると、アカウントが受け取った通貨の額を確認できます。 - + - **[EscrowFinishトランザクション][]** は、以前の[EscrowCreateトランザクション][]によって作成された[Escrow](escrow.html)を終了することでXRPを送金できます。**EscrowFinishトランザクション**のメタデータを確認すると、escrowからXRPを受け取ったアカウントと、その額を確認できます。 - + - **[OfferCreateトランザクション][]** はアカウントがXRP Ledgerの[分散型取引所](decentralized-exchange.html)で以前発行したオファーを消費することで、XRPまたは発行済み通貨を送金できます。オファーを発行しないと、この方法で金額を受け取ることはできません。メタデータを確認して、アカウントが受け取った通貨（この情報がある場合）と、金額を確認します。 - + - **[PaymentChannelClaimトランザクション][]** では、[Payment Channel](payment-channels.html)からXRPを送金できます。メタデータを確認して、トランザクションからXRPを受け取ったアカウント（この情報がある場合）を確認します。 - + - **[PaymentChannelFundトランザクション][]** は、閉鎖された（期限切れの）Payment Channelから送金元にXRPを返金することができます。 - **`meta`フィールド**には、1つまたは複数の通貨の種類とその正確な金額、その送金先などを示す[トランザクションメタデータ](transaction-metadata.html)が示されています。トランザクションメタデータを理解する方法の詳細は、[トランザクションの結果の確認](look-up-transaction-results.html)を参照してください。 @@ -397,7 +397,7 @@ function CountXRPDifference(affected_nodes, address) { } } } else if ((affected_nodes[i].hasOwnProperty("CreatedNode"))) { - // created a ledger entry. maybe the account just got funded? + // created a ledger entry. maybe the account got funded? let ledger_entry = affected_nodes[i].CreatedNode if (ledger_entry.LedgerEntryType === "AccountRoot" && ledger_entry.NewFields.Account === address) { diff --git a/content/tutorials/get-started/monitor-incoming-payments-with-websocket.md b/content/tutorials/get-started/monitor-incoming-payments-with-websocket.md index 1cb2b6722b..66a43c8deb 100644 --- a/content/tutorials/get-started/monitor-incoming-payments-with-websocket.md +++ b/content/tutorials/get-started/monitor-incoming-payments-with-websocket.md @@ -394,7 +394,7 @@ function CountXRPDifference(affected_nodes, address) { } } } else if ((affected_nodes[i].hasOwnProperty("CreatedNode"))) { - // created a ledger entry. maybe the account just got funded? + // created a ledger entry. maybe the account got funded? let ledger_entry = affected_nodes[i].CreatedNode if (ledger_entry.LedgerEntryType === "AccountRoot" && ledger_entry.NewFields.Account === address) { diff --git a/content/tutorials/get-started/set-up-secure-signing.md b/content/tutorials/get-started/set-up-secure-signing.md index ddd316644c..ab2d221740 100644 --- a/content/tutorials/get-started/set-up-secure-signing.md +++ b/content/tutorials/get-started/set-up-secure-signing.md @@ -2,7 +2,7 @@ To submit [transactions](transaction-basics.html) to the XRP Ledger, you need a way to digitally sign them without compromising the security of your [secret keys](cryptographic-keys.html). (If others gain access to your secret keys, they have as much control over your accounts as you do, and can steal or destroy all your money.) This page summarizes how to set up such an environment so you can sign transactions securely. -**Tip:** If you are not submitting transactions to the network, you can safely use a trustworthy public server, such as the ones run by Ripple, to monitor for incoming transactions or just to read other network activity. All transactions, balances, and data in the XRP Ledger are public. +**Tip:** If you are not submitting transactions to the network, you can safely use a trustworthy public server, such as the ones run by Ripple, to monitor for incoming transactions or read other network activity. All transactions, balances, and data in the XRP Ledger are public. There are several configurations with varying levels of security that may be acceptable for your situation. Choose one of the following that best fits your needs: @@ -38,7 +38,7 @@ In this configuration, you run `rippled` on the machine that generates the trans The [example config file](https://github.com/ripple/rippled/blob/8429dd67e60ba360da591bfa905b58a35638fda1/cfg/rippled-example.cfg#L1050-L1073) listens for connections on the local loopback network (127.0.0.1), with JSON-RPC (HTTP) on port 5005 and WebSocket (WS) on port 6006, and treats all connected clients as admin. - **Caution:** Using the [commandline API](request-formatting.html#commandline-format) for signatures is less secure than [using the Websocket or JSON-RPC APIs](get-started-with-the-rippled-api.html) through non-commandline clients. When using the commandline syntax, your secret key may be visible to other users in the system's process listing, and your shell history may save the key in plaintext. + **Caution:** Using the [commandline API](request-formatting.html#commandline-format) for signatures is less secure than [using the Websocket or JSON-RPC APIs](get-started-with-the-rippled-api.html) through non-commandline clients. When using the commandline syntax, your secret key may be visible to other users in the system's process listing, and your shell history may save the key in plain text. 3. Maintain the server to keep it running, updated, and in sync with the network while you're using it. @@ -70,7 +70,7 @@ This configuration uses a client library in the programming language you are usi - **Signing Library for C++** (included with `rippled`) - [Documentation](https://github.com/ripple/rippled/tree/develop/Builds/linux#signing-library) -If you use a client library not published by Ripple, make sure it uses proper, secure implementations of the signing algorithm(s) it implements. (For example, if it uses the default ECDSA algorithm, it should also use deterministic nonces as described in [RFC6979](https://tools.ietf.org/html/rfc6979).) All of Ripple's published libraries listed above follow industry best practices. +If you use a client library not published by Ripple, make sure it uses proper, secure implementations of the signing algorithm(s) it implements. (For example, if it uses the default ECDSA algorithm, it should also use deterministic nonces as described in [RFC-6979](https://tools.ietf.org/html/rfc6979).) All of Ripple's published libraries listed above follow industry best practices. For best security, be sure to keep your client library updated to the latest stable version. diff --git a/content/tutorials/manage-account-settings/change-or-remove-a-regular-key-pair.md b/content/tutorials/manage-account-settings/change-or-remove-a-regular-key-pair.md index d12ca425a1..242bdc9264 100644 --- a/content/tutorials/manage-account-settings/change-or-remove-a-regular-key-pair.md +++ b/content/tutorials/manage-account-settings/change-or-remove-a-regular-key-pair.md @@ -1,6 +1,6 @@ # Change or Remove a Regular Key Pair -The XRP Ledger allows an account to authorize a secondary key pair, called a _[regular key pair](cryptographic-keys.html)_, to sign future transactions. If your [account](accounts.html)'s regular key pair is compromised, or if you just want to periodically change the regular key pair as a security measure, use a [SetRegularKey transaction][] to remove or change the regular key pair for your account. +The XRP Ledger allows an account to authorize a secondary key pair, called a _[regular key pair](cryptographic-keys.html)_, to sign future transactions. If your [account](accounts.html)'s regular key pair is compromised, or if you want to periodically change the regular key pair as a security measure, use a [SetRegularKey transaction][] to remove or change the regular key pair for your account. For more information about master and regular key pairs, see [Cryptographic Keys](cryptographic-keys.html). @@ -14,7 +14,7 @@ For more information about master and regular key pairs, see [Cryptographic Keys ## Removing a Regular Key Pair -If you want to simply remove a compromised regular key pair from your account, you don't need to generate a key pair first. Use a [SetRegularKey transaction][], omitting the `RegularKey` field. Note that the transaction fails if you don't have another way of signing for your account currently enabled (either the master key pair or a [signer list](multi-signing.html)). +If you want to remove a compromised regular key pair from your account, you don't need to generate a key pair first. Use a [SetRegularKey transaction][], omitting the `RegularKey` field. Note that the transaction fails if you don't have another way of signing for your account currently enabled (either the master key pair or a [signer list](multi-signing.html)). When removing a regular key pair to your account, the `SetRegularKey` transaction requires signing by your account's master private key (secret) or existing regular key pair. Transmitting your master or regular private key is dangerous, so we'll complete this transaction in two steps to keep transaction signing separate from transaction submission to the network. @@ -353,7 +353,7 @@ An example of a successful response: -In some cases, you can even use the `SetRegularKey` transaction to send a [key reset transaction](transaction-cost.html#key-reset-transaction) without paying the [transaction cost](transaction-cost.html). With the enablement of the FeeEscalation amendment, `rippled` prioritizes key reset transactions above other transactions even though the nominal transaction cost of a key reset transaction is zero. +In some cases, you can even use the `SetRegularKey` transaction to send a [key reset transaction](transaction-cost.html#key-reset-transaction) without paying the [transaction cost](transaction-cost.html). The XRP Ledger's [transaction queue](transaction-queue.html) prioritizes key reset transactions above other transactions even though the nominal transaction cost of a key reset transaction is zero. - **Concepts:** diff --git a/content/tutorials/manage-account-settings/disable-master-key-pair.md b/content/tutorials/manage-account-settings/disable-master-key-pair.md index 400936a9cd..67dbe3961b 100644 --- a/content/tutorials/manage-account-settings/disable-master-key-pair.md +++ b/content/tutorials/manage-account-settings/disable-master-key-pair.md @@ -451,7 +451,7 @@ Loading: "/etc/opt/ripple/rippled.cfg" -In the response's `account_data` object, compare the `Flags` field with the lsfDisableMaster flag value (`0x00100000` in hex, or `1048576` in decimal) using bitwise-AND (the `&` operator in most common programming languages). +In the response's `account_data` object, compare the `Flags` field with the `lsfDisableMaster` flag value (`0x00100000` in hex, or `1048576` in decimal) using bitwise-AND (the `&` operator in most common programming languages). Example code: @@ -487,7 +487,7 @@ else: This operation has only two possible outcomes: -- A nonzero result, equal to the lsfDisableMaster value, indicates **the master key has been successfully disabled**. +- A nonzero result, equal to the `lsfDisableMaster` value, indicates **the master key has been successfully disabled**. - A zero result indicates the account's master key is not disabled. If the result does not match your expectations, check whether the transaction you sent in the previous steps has executed successfully. It should be the most recent entry in the account's transaction history ([account_tx method][]) and it should have the result code `tesSUCCESS`. If you see any other [result code](transaction-results.html), the transaction was not executed successfully. Depending on the cause of the error, you may want to restart these steps from the beginning. diff --git a/content/tutorials/manage-account-settings/offline-account-setup.md b/content/tutorials/manage-account-settings/offline-account-setup.md index 335d3d829e..0cb3c033a3 100644 --- a/content/tutorials/manage-account-settings/offline-account-setup.md +++ b/content/tutorials/manage-account-settings/offline-account-setup.md @@ -30,7 +30,7 @@ Software options for signing on the XRP Ledger include: - Install [ripple-lib](rippleapi-reference.html) and its dependencies offline. The Yarn package manager, for example, has [recommended instructions for offline usage](https://yarnpkg.com/blog/2016/11/24/offline-mirror/). - See also: [Set Up Secure Signing](set-up-secure-signing.html) -You may want to set up custom software to facilitate the process of constructing transaction instructions on the offline machine. For example, your software may track what [sequence number][] to use next, or contain preset templates for certain types of transactions you expect to send. +You may want to set up custom software to help construct transaction instructions on the offline machine. For example, your software may track what [sequence number][] to use next, or contain preset templates for certain types of transactions you expect to send. ### {{n.next()}}. Generate cryptographic keys @@ -70,6 +70,8 @@ Take note of the following values: **Do not** share the `master_key`, `master_seed`, or `master_seed_hex` values anywhere. Any of these can be used to reconstruct the private key associated with this address. + + ### {{n.next()}}. Fund the new address @@ -137,14 +139,14 @@ On the offline machine, prepare and sign transactions for configuring your accou - [Require destination tags](require-destination-tags.html) so that users can't send you payments without tagging the reason they sent it or the customer it's intended for. - [Set Up Multi-Signing](set-up-multi-signing.html) for a higher bar of account security. - [Enable DepositAuth](depositauth.html) so you can only receive payments you've explicitly accepted or from parties you've pre-approved. -- [Enable RequireAuth](become-an-xrp-ledger-gateway.html#enabling-requireauth) so that users can't open [trust lines](trust-lines-and-issuing.html) to you without your permission. If you don't plan to use the XRP Ledger's decentralized exchange or issued currency features, you may want to do this as a precaution. +- [Require Auth](become-an-xrp-ledger-gateway.html#enabling-requireauth) so that users can't open [trust lines](trust-lines-and-issuing.html) to you without your permission. If you don't plan to use the XRP Ledger's decentralized exchange or issued currency features, you may want to do this as a precaution. - Issued currency [Gateways](become-an-xrp-ledger-gateway.html) may have additional setup, such as: - - [Set a TransferRate](become-an-xrp-ledger-gateway.html#transferrate) for users transferring your issued currencies. + - [Set a Transfer Fee](become-an-xrp-ledger-gateway.html#transferrate) for users transferring your issued currencies. - [Disallow XRP payments](become-an-xrp-ledger-gateway.html#disallowxrp) if you plan to use this address for issued currencies only. At this stage, you are only signing the transactions, not submitting them. For each transaction, you must provide all fields, including fields that are normally auto-fillable such as the `Fee` ([transaction cost](transaction-cost.html)) and `Sequence` ([sequence number][]). If you prepare multiple transactions at the same time, you must use sequentially increasing `Sequence` numbers in the order you want the transactions to execute. -Example (enable RequireAuth): +Example (enable Require Auth): diff --git a/content/tutorials/manage-account-settings/set-up-multi-signing.md b/content/tutorials/manage-account-settings/set-up-multi-signing.md index ee2704abf0..0ed61d9c01 100644 --- a/content/tutorials/manage-account-settings/set-up-multi-signing.md +++ b/content/tutorials/manage-account-settings/set-up-multi-signing.md @@ -51,9 +51,9 @@ Take note of the `account_id` (XRP Ledger Address) and `master_seed` (secret key ## 3. Send SignerListSet transaction -[Sign and submit](transaction-basics.html#signing-and-submitting-transactions) a [SignerListSet transaction][] in the normal (single-signature) way. This associates a SignerList with your XRP Ledger address, so that a combination of signatures from the members of that SignerList can multi-sign later transactions on your behalf. +[Sign and submit](transaction-basics.html#signing-and-submitting-transactions) a [SignerListSet transaction][] in the normal (single-signature) way. This associates a signer list with your XRP Ledger address, so that a combination of signatures from the members of that signer list can multi-sign later transactions on your behalf. -In this example, the SignerList has 3 members, with the weights and quorum set up such that multi-signed transactions need a signature from rsA2LpzuawewSBQXkiju3YQTMzW13pAAdW plus at least one signature from the other two members of the list. +In this example, the signer list has 3 members, with the weights and quorum set up such that multi-signed transactions need a signature from `rsA2LpzuawewSBQXkiju3YQTMzW13pAAdW` plus at least one signature from the other two members of the list. {% include '_snippets/secret-key-warning.md' %} @@ -128,9 +128,9 @@ In this example, the SignerList has 3 members, with the weights and quorum set u } } -Make sure that the [Transaction Result](transaction-results.html) is [**tesSUCCESS**](tes-success.html). Otherwise, the transaction failed. If you have a problem in stand-alone mode or a non-production network, check that [multi-sign is enabled](start-a-new-genesis-ledger-in-stand-alone-mode.html#settings-in-new-genesis-ledgers). +Make sure that the [Transaction Result](transaction-results.html) is [**`tesSUCCESS`**](tes-success.html). Otherwise, the transaction failed. If you have a problem in stand-alone mode or a non-production network, check that [multi-sign is enabled](start-a-new-genesis-ledger-in-stand-alone-mode.html#settings-in-new-genesis-ledgers). -**Note:** Without the [MultiSignReserve amendment][], the more members in the SignerList, the more XRP your address must have for purposes of the [owner reserve](reserves.html#owner-reserves). If your address does not have enough XRP, the transaction fails with [tecINSUFFICIENT_RESERVE](tec-codes.html). With the [MultiSignReserve amendment][] enabled, the XRP your address must have for purposes of the [owner reserve](reserves.html#owner-reserves) is 5 XRP, regardless of the number of members in the SignerList. See also: [SignerLists and Reserves](signerlist.html#signerlists-and-reserves). +**Note:** Without the [MultiSignReserve amendment][], the more members in the signer list, the more XRP your address must have for purposes of the [owner reserve](reserves.html#owner-reserves). If your address does not have enough XRP, the transaction fails with [`tecINSUFFICIENT_RESERVE`](tec-codes.html). With the [MultiSignReserve amendment][] enabled, the XRP your address must have for purposes of the [owner reserve](reserves.html#owner-reserves) is 5 XRP, regardless of the number of members in the signer list. See also: [Signer Lists and Reserves](signerlist.html#signer-lists-and-reserves). ## 4. Wait for validation @@ -140,9 +140,9 @@ Make sure that the [Transaction Result](transaction-results.html) is [**tesSUCCE ## 5. Confirm the new signer list -Use the [account_objects method][] to confirm that the SignerList is associated with the address in the latest validated ledger. +Use the [account_objects method][] to confirm that the signer list is associated with the address in the latest validated ledger. -Normally, an account can own many objects of different types (such as trust lines and offers). If you funded a new address for this tutorial, the SignerList is the only object in the response. +Normally, an account can own many objects of different types (such as trust lines and offers). If you funded a new address for this tutorial, the signer list is the only object in the response. $ rippled account_objects rEuLyBCvcw4CFmzv8RepSiAoNgF8tTGJQC validated Loading: "/etc/opt/ripple/rippled.cfg" @@ -189,7 +189,7 @@ Normally, an account can own many objects of different types (such as trust line } } -If the SignerList is present with the expected contents, then your address is ready to multi-sign. +If the signer list is present with the expected contents, then your address is ready to multi-sign. ## 6. Further steps diff --git a/content/tutorials/manage-the-rippled-server/configuration/configure-advisory-deletion.md b/content/tutorials/manage-the-rippled-server/configuration/configure-advisory-deletion.md index 8cab617624..d1028dbde4 100644 --- a/content/tutorials/manage-the-rippled-server/configuration/configure-advisory-deletion.md +++ b/content/tutorials/manage-the-rippled-server/configuration/configure-advisory-deletion.md @@ -88,7 +88,7 @@ To configure advisory deletion with a daily schedule, perform the following step If online deletion does not seem to be running after configuring it, try the following: - Check that the user who configured the `cron` job has permissions to run the `rippled` server as a commandline client. -- Check the syntax of your cron job and the time when it is supposed to run. +- Check the syntax of your `cron` job and the time when it is supposed to run. - Check that the `rippled` executable is available at the path specified in your `cron` configuration. If necessary, specify the absolute path to the executable, such as `/opt/ripple/bin/rippled`. - Check your `rippled` logs for messages that begin with `SHAMapStore::WRN`. This can indicate that [online deletion is being interrupted](online-deletion.html#interrupting-online-deletion) because your server fell out of sync with the network. diff --git a/content/tutorials/manage-the-rippled-server/configuration/configure-grpc.md b/content/tutorials/manage-the-rippled-server/configuration/configure-grpc.md index 51661e8d88..a688ad7799 100644 --- a/content/tutorials/manage-the-rippled-server/configuration/configure-grpc.md +++ b/content/tutorials/manage-the-rippled-server/configuration/configure-grpc.md @@ -25,7 +25,7 @@ To enable gRPC on your server, complete the following steps: The configurable fields are as follows: - `port` field defines the port the server listens on for gRPC connections from client applications. The recommended port is `50051`. - - `ip` defines which interfaces the server listens on. The value `0.0.0.0` listens on all available network interfaces. To limit connections to just the local loopback network (same machine), use `127.0.0.1` instead. + - `ip` defines which interfaces the server listens on. The value `0.0.0.0` listens on all available network interfaces. To limit connections to the local loopback network (same machine), use `127.0.0.1` instead. {% include '_snippets/conf-file-location.md' %} diff --git a/content/tutorials/manage-the-rippled-server/configuration/connect-your-rippled-to-the-xrp-test-net.md b/content/tutorials/manage-the-rippled-server/configuration/connect-your-rippled-to-the-xrp-test-net.md index 413de1ecee..df457c3712 100644 --- a/content/tutorials/manage-the-rippled-server/configuration/connect-your-rippled-to-the-xrp-test-net.md +++ b/content/tutorials/manage-the-rippled-server/configuration/connect-your-rippled-to-the-xrp-test-net.md @@ -1,77 +1,77 @@ -# Connect Your rippled to an XRPL Altnet +# Connect Your rippled to an XRP Ledger Altnet -Ripple has created [alternative test and development networks](parallel-networks.html) for developers to test their apps on the latest non-production version of the XRP Ledger (Testnet) or to test and experiment with features on the latest beta version (Devnet). **The funds used on these networks are not real funds and are intended for testing only.** You can connect your [`rippled` server](the-rippled-server.html) to either the Testnet or Devnet. +Ripple hosts [alternative test and development networks](parallel-networks.html) for developers to test their apps on the latest non-production version of the XRP Ledger (Testnet) or to test and experiment with features on the latest beta version (Devnet). **The funds used on these networks are not real funds and are intended for testing only.** You can connect your [`rippled` server](the-rippled-server.html) to either the Testnet or Devnet. **Note:** The XRP Testnet and Devnet ledger and balances are reset on a regular basis. To connect your `rippled` server to the XRP Testnet or Devnet, set the following configurations: -1. In your `rippled.cfg` file: +1. Edit your `rippled.cfg` file to connect to a hub server in the network you want to connect to. - a. To connect to the [Testnet](xrp-testnet-faucet.html), uncomment the following section and add: + 1. To connect to the [Testnet](xrp-testnet-faucet.html), uncomment or add the following section: - [ips] - s.altnet.rippletest.net 51235 + [ips] + s.altnet.rippletest.net 51235 - b. To connect to the [Devnet](xrp-testnet-faucet.html), uncomment the following section and add: + 2. To connect to the [Devnet](xrp-testnet-faucet.html), uncomment or add the following section: - [ips] - s.devnet.rippletest.net 51235 + [ips] + s.devnet.rippletest.net 51235 - c. Comment out the following section, as follows: + 3. Comment out the existing `[ips]` stanza: - # [ips] - # r.ripple.com 51235 + # [ips] + # r.ripple.com 51235 -2. In your `validators.txt` file: +2. Edit your `validators.txt` file. - 2a. Changes to connect to the Testnet + - To connect to the Testnet: - a. Uncomment the following sections, as follows to connect to the altnet: + 1. Uncomment the following sections: - [validator_list_sites] - https://vl.altnet.rippletest.net + [validator_list_sites] + https://vl.altnet.rippletest.net - [validator_list_keys] - ED264807102805220DA0F312E71FC2C69E1552C9C5790F6C25E3729DEB573D5860 + [validator_list_keys] + ED264807102805220DA0F312E71FC2C69E1552C9C5790F6C25E3729DEB573D5860 - b. Comment out the following sections, as follows: + 1. Comment out the following sections, as follows: - # [validator_list_sites] - # https://vl.ripple.com - # - # [validator_list_keys] - # ED2677ABFFD1B33AC6FBC3062B71F1E8397C1505E1C42C64D11AD1B28FF73F4734 + # [validator_list_sites] + # https://vl.ripple.com + # + # [validator_list_keys] + # ED2677ABFFD1B33AC6FBC3062B71F1E8397C1505E1C42C64D11AD1B28FF73F4734 - 2b. Changes to connect to the Devnet + - To connect to the Devnet: - a. Comment out the following sections as follows: + 1. Comment out the following sections: - # [validator_list_sites] - # https://vl.altnet.rippletest.net + # [validator_list_sites] + # https://vl.altnet.rippletest.net - # [validator_list_keys] - # ED264807102805220DA0F312E71FC2C69E1552C9C5790F6C25E3729DEB573D5860 + # [validator_list_keys] + # ED264807102805220DA0F312E71FC2C69E1552C9C5790F6C25E3729DEB573D5860 - # [validator_list_sites] - # https://vl.ripple.com - # - # [validator_list_keys] - # ED2677ABFFD1B33AC6FBC3062B71F1E8397C1505E1C42C64D11AD1B28FF73F4734 + # [validator_list_sites] + # https://vl.ripple.com + # + # [validator_list_keys] + # ED2677ABFFD1B33AC6FBC3062B71F1E8397C1505E1C42C64D11AD1B28FF73F4734 - b. Add the following trusted validators to the validator.txt file: + 2. Add the following trusted validators to the `validator.txt` file: - # Hard-coded List of Devnet Validators - [validators] - n9Mo4QVGnMrRN9jhAxdUFxwvyM4aeE1RvCuEGvMYt31hPspb1E2c - n9MEwP4LSSikUnhZJNQVQxoMCgoRrGm6GGbG46AumH2KrRrdmr6B - n9M1pogKUmueZ2r3E3JnZyM3g6AxkxWPr8Vr3zWtuRLqB7bHETFD - n9MX7LbfHvPkFYgGrJmCyLh8Reu38wsnnxA4TKhxGTZBuxRz3w1U - n94aw2fof4xxd8g3swN2qJCmooHdGv1ajY8Ae42T77nAQhZeYGdd - n9LiE1gpUGws1kFGKCM9rVFNYPVS4QziwkQn281EFXX7TViCp2RC - n9Jq9w1R8UrvV1u2SQqGhSXLroeWNmPNc3AVszRXhpUr1fmbLyhS + # Hard-coded List of Devnet Validators + [validators] + n9Mo4QVGnMrRN9jhAxdUFxwvyM4aeE1RvCuEGvMYt31hPspb1E2c + n9MEwP4LSSikUnhZJNQVQxoMCgoRrGm6GGbG46AumH2KrRrdmr6B + n9M1pogKUmueZ2r3E3JnZyM3g6AxkxWPr8Vr3zWtuRLqB7bHETFD + n9MX7LbfHvPkFYgGrJmCyLh8Reu38wsnnxA4TKhxGTZBuxRz3w1U + n94aw2fof4xxd8g3swN2qJCmooHdGv1ajY8Ae42T77nAQhZeYGdd + n9LiE1gpUGws1kFGKCM9rVFNYPVS4QziwkQn281EFXX7TViCp2RC + n9Jq9w1R8UrvV1u2SQqGhSXLroeWNmPNc3AVszRXhpUr1fmbLyhS 3. Restart `rippled`. diff --git a/content/tutorials/manage-the-rippled-server/configuration/run-rippled-as-a-validator.md b/content/tutorials/manage-the-rippled-server/configuration/run-rippled-as-a-validator.md index ec94f92886..a4cd22c370 100644 --- a/content/tutorials/manage-the-rippled-server/configuration/run-rippled-as-a-validator.md +++ b/content/tutorials/manage-the-rippled-server/configuration/run-rippled-as-a-validator.md @@ -34,7 +34,7 @@ Strive to have your validator always embody the following properties. Being a go - **Identified** - A good validator has a clearly identified owner. Providing [domain verification](#6-provide-domain-verification) is a good start. Ideally, XRP Ledger network UNLs include validators operated by different owners in multiple legal jurisdictions and geographic areas. This reduces the chance that any localized events could interfere with the impartial operations of trusted validators. + A good validator has a clearly identified owner. Providing [domain verification](#6-provide-domain-verification) is a good start. Ideally, XRP Ledger network UNLs include validators run by different owners in multiple legal jurisdictions and geographic areas. This reduces the chance that any localized events could interfere with the impartial operations of trusted validators. Ripple (the company) publishes a [validator list](https://github.com/ripple/rippled/blob/develop/cfg/validators-example.txt) with a set of recommended validators. Ripple strongly recommends using exactly this list for production servers. @@ -80,7 +80,7 @@ In a location **not** on your validator: $ validator-keys create_token --keyfile /PATH/TO/YOUR/validator-keys.json - Sample output: + Sample output: Update rippled.cfg file with these values: @@ -133,7 +133,7 @@ For a comparison of these approaches, see [Pros and Cons of Peering Configuratio This configuration connects your validator to the XRP Ledger network using [discovered peers](peer-protocol.html#peer-discovery). This is the default behavior for `rippled` servers. -_**To connect your validator to the XRP Ledger network using discovered peers,**_ omit the `[peer_private]` stanza or set it to `0` in your validator's `rippled.cfg` file. The [example rippled.cfg file](https://github.com/ripple/rippled/blob/develop/cfg/rippled-example.cfg) is delivered with this configuration. +_**To connect your validator to the XRP Ledger network using discovered peers,**_ omit the `[peer_private]` stanza or set it to `0` in your validator's `rippled.cfg` file. The [example `rippled.cfg` file](https://github.com/ripple/rippled/blob/develop/cfg/rippled-example.cfg) is delivered with this configuration. ### Connect using proxies @@ -225,13 +225,13 @@ Here are some methods you can use to verify that your validator has a healthy co ## 6. Provide domain verification -To help validation list publishers and other participants in the XRP Ledger network understand who operates your validator, provide domain verification for your validator. At a high level, domain verification is a two-way link: +To help validation list publishers and other participants in the XRP Ledger network understand who runs your validator, provide domain verification for your validator. At a high level, domain verification is a two-way link: - Use your domain to claim ownership of a validator key. - Use your validator key to claim ownership of a domain. -Creating this link establishes strong evidence that you own both the validator key and the domain. Providing this evidence is just one aspect of [being a good validator](#1-understand-the-traits-of-a-good-validator). +Creating this link establishes strong evidence that you own both the validator key and the domain. Providing this evidence is one aspect of [being a good validator](#1-understand-the-traits-of-a-good-validator). To provide domain verification: diff --git a/content/tutorials/manage-the-rippled-server/configuration/run-rippled-as-a-wallet-server.md b/content/tutorials/manage-the-rippled-server/configuration/run-rippled-as-a-wallet-server.md index 1aa8dc5346..506215eabc 100644 --- a/content/tutorials/manage-the-rippled-server/configuration/run-rippled-as-a-wallet-server.md +++ b/content/tutorials/manage-the-rippled-server/configuration/run-rippled-as-a-wallet-server.md @@ -18,14 +18,12 @@ A wallet server does all of the following: For more information, see [Install `rippled`](install-rippled.html). - - ## 2. Enable validation on your wallet server For more information, see [Enable validation on your `rippled` server](run-rippled-as-a-validator.html#3-enable-validation-on-your-rippled-server). -**Warning:** Validators should not be accessible to the public. Do not allow public websockets access to your wallet server or any other form of public access. - +**Warning:** Validators should not be accessible to the public. Do not allow public WebSocket access to your wallet server or any other form of public access. + ## 3. Provide domain verification For more information, see [Provide domain verification](run-rippled-as-a-validator.html#6-provide-domain-verification). diff --git a/content/tutorials/manage-the-rippled-server/installation/build-run-rippled-macos.md b/content/tutorials/manage-the-rippled-server/installation/build-run-rippled-macos.md index 75f08430d3..2f4a7f8a4c 100644 --- a/content/tutorials/manage-the-rippled-server/installation/build-run-rippled-macos.md +++ b/content/tutorials/manage-the-rippled-server/installation/build-run-rippled-macos.md @@ -6,7 +6,7 @@ That said, macOS is suitable for many development and testing tasks. `rippled` h For development purposes, run `rippled` as a non-admin user, not using `sudo`. -1. Install [Xcode](https://developer.apple.com/download/). +1. Install [Xcode](https://developer.apple.com/download/). 0. Install Xcode command line tools. @@ -65,7 +65,7 @@ For development purposes, run `rippled` as a non-admin user, not using `sudo`. Or, you can checkout one of the tagged releases listed on [GitHub](https://github.com/ripple/rippled/releases). -0. In the `rippled` directory you just cloned, create your build directory and access it. For example: +0. In the `rippled` directory you cloned, create your build directory and access it. For example: $ mkdir my_build $ cd my_build diff --git a/content/tutorials/manage-the-rippled-server/installation/capacity-planning.md b/content/tutorials/manage-the-rippled-server/installation/capacity-planning.md index 9c8bfcd022..ffff1bbcca 100644 --- a/content/tutorials/manage-the-rippled-server/installation/capacity-planning.md +++ b/content/tutorials/manage-the-rippled-server/installation/capacity-planning.md @@ -47,7 +47,7 @@ You can set the value to either `RocksDB` or `NuDB`. - For most cases, use `NuDB` because its performance is constant even with large amounts of data on disk. A fast SSD is required. [Learn more](#more-about-using-nudb) -- If you are using rotational disks (not recommended) or even just a slow SSD, use `RocksDB`. [Learn more](#more-about-using-rocksdb) +- If you are using rotational disks (not recommended) or an unusually slow SSD, use `RocksDB`. [Learn more](#more-about-using-rocksdb) The example `rippled-example.cfg` file has the `type` field in the `[node_db]` stanza set to `RocksDB`. @@ -121,7 +121,7 @@ For best performance in enterprise production environments, Ripple recommends ru - CPU: Intel Xeon 3+ GHz processor with 4 cores and hyperthreading enabled - Disk speed: SSD (7000+ writes/second, 10,000+ reads/second) - Disk space: Varies. At least 50 GB recommended. -- RAM: 32GB +- RAM: 32 GB - Network: Enterprise data center network with a gigabit network interface on the host #### CPU Utilization and Virtualization diff --git a/content/tutorials/manage-the-rippled-server/installation/system-requirements.md b/content/tutorials/manage-the-rippled-server/installation/system-requirements.md index 3e0c14db79..bc578d4b8c 100644 --- a/content/tutorials/manage-the-rippled-server/installation/system-requirements.md +++ b/content/tutorials/manage-the-rippled-server/installation/system-requirements.md @@ -8,7 +8,7 @@ A `rippled` server should run comfortably on commodity hardware, to make it inex - Production: CentOS or RedHat Enterprise Linux (latest release), Ubuntu (16.04+), or Debian (9.x) supported - Development: Mac OS X, Windows (64-bit), or most Linux distributions - CPU: 64-bit x86_64, 2+ cores -- Disk: Minimum 50GB for the database partition. SSD strongly recommended (minimum 1000 IOPS, more is better) +- Disk: Minimum 50 GB for the database partition. SSD strongly recommended (minimum 1000 IOPS, more is better) - RAM: 8 GB+ diff --git a/content/tutorials/manage-the-rippled-server/troubleshooting/diagnosing-problems.md b/content/tutorials/manage-the-rippled-server/troubleshooting/diagnosing-problems.md index c6cff0df34..8040ad85cb 100644 --- a/content/tutorials/manage-the-rippled-server/troubleshooting/diagnosing-problems.md +++ b/content/tutorials/manage-the-rippled-server/troubleshooting/diagnosing-problems.md @@ -80,7 +80,7 @@ For troubleshooting purposes, the most important fields are (from most commonly - **`peers`** - This field indicates how many other servers in the XRP Ledger peer-to-peer network your server is connected to. Healthy servers typically show between 5 and 50 peers, unless explicitly configured to connect only to certain peers. - - If you have 0 peers, your server may be unable to contact the network, or your system clock may be wrong. (Ripple recommends running an [NTP](http://www.ntp.org/) daemon on all servers to keep their clocks synced.) + - If you have 0 peers, your server may be unable to contact the network, or your system clock may be wrong. (Ripple recommends running an [NTP](http://www.ntp.org/) daemon on all servers to keep their clocks synced.) - If you have exactly 10 peers, that may indicate that your `rippled` is unable to receive incoming connections through a router using [NAT](https://en.wikipedia.org/wiki/Network_address_translation). You can improve connectivity by configuring your router's firewall to forward the port used for peer-to-peer connections (port 51235 [by default](https://github.com/ripple/rippled/blob/8429dd67e60ba360da591bfa905b58a35638fda1/cfg/rippled-example.cfg#L1065)). @@ -99,7 +99,7 @@ The `rippled` executable returns the following message if it wasn't able to conn This generally indicates one of several problems: -- The `rippled` server is just starting up, or is not running at all. Check the status of the service; if it is running, wait a few seconds and try again. +- The `rippled` server is starting up, or is not running at all. Check the status of the service; if it is running, wait a few seconds and try again. - You may need to pass different [parameters to the `rippled` commandline client](commandline-usage.html#client-mode-options) to connect to your server. - The `rippled` server may be configured not to accept JSON-RPC connections. @@ -138,7 +138,7 @@ To use the script: should verify before posting. #################################################### - The script collects the output of numerous commands and writes them to a temporary file. The filename is randomized with a string of letters and numbers (case-sensitive), for example: `/tmp/ripple_info.Xo8Xr/rippled_info.md` + The script collects the output of many commands and writes them to a temporary file. The filename is randomized with a string of letters and numbers (case-sensitive), for example: `/tmp/ripple_info.Xo8Xr/rippled_info.md` 2. Look over the output file for sensitive information. diff --git a/content/tutorials/manage-the-rippled-server/troubleshooting/fix-sqlite-tx-db-page-size-issue.md b/content/tutorials/manage-the-rippled-server/troubleshooting/fix-sqlite-tx-db-page-size-issue.md index 80805b70f8..80f92971b5 100644 --- a/content/tutorials/manage-the-rippled-server/troubleshooting/fix-sqlite-tx-db-page-size-issue.md +++ b/content/tutorials/manage-the-rippled-server/troubleshooting/fix-sqlite-tx-db-page-size-issue.md @@ -10,7 +10,7 @@ This document describes steps to detect and correct this problem if it occurs. The capacity of the SQLite database is a result of the database's _page size_ parameter, which cannot be easily changed after the database is created. (For more information on SQLite's internals, see [the official SQLite documentation](https://www.sqlite.org/fileformat.html).) The database can reach its capacity even if there is still free space on the disk and filesystem where it is stored. As described in the [Fix](#fix) below, reconfiguring the page size to avoid this problem requires a somewhat time-consuming migration process. -**Tip:** Full history is not necessary to operate a `rippled` server for most use cases. Servers with full transaction history may be useful for long-term analysis and archive purposes or as a precaution against disasters. For a less resource-intense way to contribute to the storage of transaction history, see [History Sharding](history-sharding.html). +**Tip:** Full history is not necessary for most use cases. Servers with full transaction history may be useful for long-term analysis and archive purposes or as a precaution against disasters. For a less resource-intense way to contribute to the storage of transaction history, see [History Sharding](history-sharding.html). ## Detection diff --git a/content/tutorials/manage-the-rippled-server/troubleshooting/server-doesnt-sync.md b/content/tutorials/manage-the-rippled-server/troubleshooting/server-doesnt-sync.md index dd28bfa4a4..f9b7d724b8 100644 --- a/content/tutorials/manage-the-rippled-server/troubleshooting/server-doesnt-sync.md +++ b/content/tutorials/manage-the-rippled-server/troubleshooting/server-doesnt-sync.md @@ -32,7 +32,7 @@ If the problem persists, check the other possibilities listed on this page. If n The most common cause of syncing issues is not meeting the [system requirements](system-requirements.html). The three most common shortfalls are: - **Slow disks.** You need a consistently fast solid state disk (SSD). Cloud providers like AWS usually don't guarantee disk performance, which may be impacted by other users of shared hardware. -- **Insufficient RAM.** The memory requirements vary depending on several factors including ones that are hard to predict like network load and how people use the XRP Ledger, so it's good to have more than the minimum system requirements just in case. +- **Insufficient RAM.** The memory requirements vary depending on several factors including ones that are hard to predict like network load and how people use the XRP Ledger, so it's good to have more than the minimum system requirements. - **Poor network connection.** Network requirements vary the most based on how people use the XRP Ledger, but a slow or unstable connection can make it impossible to keep up with new transactions and data added to the XRP Ledger. If you are having trouble remaining synced, double-check that your server meets the system requirements. Depending on how you use your server, you may need to meet the higher "Recommended" requirements instead of just the "Minimum" requirements. If you meet the "Recommended" requirements and still cannot sync, try the other possibilities on this page. diff --git a/content/tutorials/manage-the-rippled-server/troubleshooting/understanding-log-messages.md b/content/tutorials/manage-the-rippled-server/troubleshooting/understanding-log-messages.md index 15b2942551..0c77f429df 100644 --- a/content/tutorials/manage-the-rippled-server/troubleshooting/understanding-log-messages.md +++ b/content/tutorials/manage-the-rippled-server/troubleshooting/understanding-log-messages.md @@ -35,7 +35,7 @@ Log messages such as the following indicate that a server received validations f 2018-Aug-28 22:55:58.316094260 Validations:WRN Val for 2137ACEFC0D137EFA1D84C2524A39032802E4B74F93C130A289CD87C9C565011 trusted/full from nHUeUNSn3zce2xQZWNghQvd9WRH6FWEnCBKYVJu2vAizMxnXegfJ signing key n9KcRZYHLU9rhGVwB9e4wEMYsxXvUfgFxtmX25pc1QPNgweqzQf5 already validated sequence at or past 12133663 src=1 ``` -Occasional messages of this type do not usually indicate a problem. If this type of message occurs frequently with the same sending validator, it could indicate a problem, including any of the following (roughly in order of most to least likely): +Occasional messages of this type do not usually indicate a problem. If this type of message occurs often with the same sending validator, it could indicate a problem, including any of the following (roughly in order of most to least likely): - The server writing the message is having network issues. - The validator described in the message is having network issues. @@ -57,7 +57,7 @@ This could mean: Check the `[insight]` stanza in your `rippled`'s config file and confirm that you have network connectivity from your `rippled` server to your StatsD server. -This error has no other impact on the `rippled` server, which should continue to operate as normal except for the sending of StatsD metrics. +This error has no other impact on the `rippled` server, which should continue to work as normal except for the sending of StatsD metrics. ## Connection reset by peer diff --git a/content/tutorials/use-complex-payment-types/use-checks/cash-a-check-for-a-flexible-amount.md b/content/tutorials/use-complex-payment-types/use-checks/cash-a-check-for-a-flexible-amount.md index ee37ee87cf..9605407336 100644 --- a/content/tutorials/use-complex-payment-types/use-checks/cash-a-check-for-a-flexible-amount.md +++ b/content/tutorials/use-complex-payment-types/use-checks/cash-a-check-for-a-flexible-amount.md @@ -4,7 +4,7 @@ _Added by the [Checks amendment][]._ As long as the Check is in the ledger and not expired, the specified recipient can cash it to receive a flexible amount by sending a [CheckCash transaction][] with a `DeliverMin` field. When cashing a Check in this way, the receiver gets as much as is possible to deliver, debiting the Check's sender for the Check's full `SendMax` amount or as much as is available. Cashing fails if it doesn't deliver at least the `DeliverMin` amount to the Check's recipient. -You might cash a Check for a flexible amount if you just want to get as much as possible from the Check. +You might cash a Check for a flexible amount if you want to get as much as possible from the Check. The specified recipient can also [cash the check for an exact amount](cash-a-check-for-a-flexible-amount.html). diff --git a/content/tutorials/use-complex-payment-types/use-checks/send-a-check.md b/content/tutorials/use-complex-payment-types/use-checks/send-a-check.md index 6ebe7800af..d268278621 100644 --- a/content/tutorials/use-complex-payment-types/use-checks/send-a-check.md +++ b/content/tutorials/use-complex-payment-types/use-checks/send-a-check.md @@ -6,9 +6,9 @@ Sending a Check is like writing permission for an intended recipient to pull a p In many cases, you want to send a [Payment][] instead of a Check, since that delivers the money directly to the recipient in one step. However, if your intended recipient uses [DepositAuth](depositauth.html), you cannot send them Payments directly, so a Check is a good alternative. -This tutorial uses the example of a fictitious company, BoxSend SG (whose XRP Ledger address is rBXsgNkPcDN2runsvWmwxk3Lh97zdgo9za) paying a fictitious cryptocurrency consulting company named Grand Payments (with XRP Ledger address rGPnRH1EBpHeTF2QG8DCAgM7z5pb75LAis) for some consulting work. Grand Payments prefers be paid in XRP, but to simplify their taxes and regulation, only accepts payments they've explicitly approved. +This tutorial uses the example of a fictitious company, BoxSend SG (whose XRP Ledger address is `rBXsgNkPcDN2runsvWmwxk3Lh97zdgo9za`) paying a fictitious cryptocurrency consulting company named Grand Payments (with XRP Ledger address `rGPnRH1EBpHeTF2QG8DCAgM7z5pb75LAis`) for some consulting work. Grand Payments prefers be paid in XRP, but to simplify their taxes and regulation, only accepts payments they've explicitly approved. -Outside of the XRP Ledger, Grand Payments sends an invoice to BoxSend SG with the ID `46060241FABCF692D4D934BA2A6C4427CD4279083E38C77CBE642243E43BE291`, and requests a Check for 100 XRP be sent to Grand Payments' XRP Ledger address of rGPnRH1EBpHeTF2QG8DCAgM7z5pb75LAis. +Outside of the XRP Ledger, Grand Payments sends an invoice to BoxSend SG with the ID `46060241FABCF692D4D934BA2A6C4427CD4279083E38C77CBE642243E43BE291`, and requests a Check for 100 XRP be sent to Grand Payments' XRP Ledger address of `rGPnRH1EBpHeTF2QG8DCAgM7z5pb75LAis`. {% set send_n = cycler(* range(1,99)) %} @@ -40,7 +40,7 @@ If you are using [RippleAPI](rippleapi-reference.html), you can use the `prepare ### Example CheckCreate Preparation -The following example shows a prepared Check from BoxSend SG (rBXsgNkPcDN2runsvWmwxk3Lh97zdgo9za) to Grand Payments (rGPnRH1EBpHeTF2QG8DCAgM7z5pb75LAis) for 100 XRP. As additional (optional) metadata, BoxSend SG adds the ID of the invoice from Grand Payments so Grand Payments knows which invoice this Check is intended to pay. +The following example shows a prepared Check from BoxSend SG (`rBXsgNkPcDN2runsvWmwxk3Lh97zdgo9za`) to Grand Payments (`rGPnRH1EBpHeTF2QG8DCAgM7z5pb75LAis`) for 100 XRP. As additional (optional) metadata, BoxSend SG adds the ID of the invoice from Grand Payments so Grand Payments knows which invoice this Check is intended to pay. @@ -52,7 +52,7 @@ The following example shows a prepared Check from BoxSend SG (rBXsgNkPcDN2runsvW *JSON-RPC, WebSocket, or Commandline* -``` +```json { "TransactionType": "CheckCreate", "Account": "rBXsgNkPcDN2runsvWmwxk3Lh97zdgo9za", @@ -183,7 +183,7 @@ Use the [tx method][] with the CheckCreate transaction's identifying hash to che Look for a `CreatedNode` object in the transaction metadata with a `LedgerEntryType` of `"Check"`. This indicates that the transaction created a [Check ledger object](check.html). The `LedgerIndex` of this object is the ID of the Check. In the following example, the Check's ID is `84C61BE9B39B2C4A2267F67504404F1EC76678806C1B901EA781D1E3B4CE0CD9`. -**Note:** RippleAPI does not report the Check's ID when you look up a CheckCreate transaction. You can work around this by calculating the Check's ID from the [Check ID format](check.html#check-id-format), as in the example RippleAPI code below, or you can use the [getAccountObjects() method](rippleapi-reference.html#getaccountobjects) to look up the Check and find its ID. +**Note:** RippleAPI does not report the Check's ID when you look up a CheckCreate transaction. You can work around this by calculating the Check's ID from the [Check ID format](check.html#check-id-format), as in the example RippleAPI code below, or you can use the [`getAccountObjects()` method](rippleapi-reference.html#getaccountobjects) to look up the Check and find its ID. ### Example Request diff --git a/content/tutorials/use-complex-payment-types/use-escrows/send-a-conditionally-held-escrow.md b/content/tutorials/use-complex-payment-types/use-escrows/send-a-conditionally-held-escrow.md index cad7702c72..a920dcba7e 100644 --- a/content/tutorials/use-complex-payment-types/use-escrows/send-a-conditionally-held-escrow.md +++ b/content/tutorials/use-complex-payment-types/use-escrows/send-a-conditionally-held-escrow.md @@ -5,7 +5,7 @@ XRP Ledger escrows require PREIMAGE-SHA-256 [crypto-conditions][]. To calculate a condition and fulfillment in the proper format, you should use a crypto-conditions library such as [five-bells-condition](https://github.com/interledgerjs/five-bells-condition). To generate the fulfillment: - Use a cryptographically secure source of randomness to generate at least 32 random bytes. -- Follow Interledger Protocol's [PSK specification](https://github.com/interledger/rfcs/blob/master/deprecated/0016-pre-shared-key/0016-pre-shared-key.md) and use an HMAC-SHA-256 of the ILP packet as the fulfillment. +- Follow Interledger Protocol's [PSK specification](https://github.com/interledger/rfcs/blob/master/deprecated/0016-pre-shared-key/0016-pre-shared-key.md) and use an HMAC-SHA-256 of the ILP packet as the fulfillment. Example JavaScript code for a random fulfillment and condition: diff --git a/content/tutorials/use-complex-payment-types/use-payment-channels.md b/content/tutorials/use-complex-payment-types/use-payment-channels.md index f275a8cde7..50fc3746c6 100644 --- a/content/tutorials/use-complex-payment-types/use-payment-channels.md +++ b/content/tutorials/use-complex-payment-types/use-payment-channels.md @@ -49,7 +49,7 @@ This is a [PaymentChannelCreate transaction][]. As part of this process, the pay **Tip:** The "settlement delay" does not delay the settlement, which can happen as fast as a ledger version closes (3-5 seconds). The "settlement delay" is a forced delay on closing the channel so that the payee has a chance to finish with settlement. -The following example shows creation of a payment channel by [submitting](submit.html#sign-and-submit-mode) to a local `rippled` server with the JSON-RPC API. The payment channel allocates 100 XRP from the [example payer](#example-values) (rN7n7...) to the [example payee](#example-values) (rf1Bi...) with a settlement delay of 1 day. The public key is the example payer's master public key, in hexadecimal. +The following example shows creation of a payment channel by [submitting](submit.html#sign-and-submit-mode) to a local `rippled` server with the JSON-RPC API. The payment channel allocates 100 XRP from the [example payer](#example-values) (`rN7n7...`) to the [example payee](#example-values) (`rf1Bi...`) with a settlement delay of 1 day. The public key is the example payer's master public key, in hexadecimal. **Note:** A payment channel counts as one object toward the payer's [owner reserve](reserves.html#owner-reserves). The owner must keep at least enough XRP to satisfy the reserve after subtracting the XRP allocated to the payment channel. diff --git a/content/tutorials/use-simple-xrp-payments/reliable-transaction-submission.md b/content/tutorials/use-simple-xrp-payments/reliable-transaction-submission.md index b76d369da0..1dbf5745e4 100644 --- a/content/tutorials/use-simple-xrp-payments/reliable-transaction-submission.md +++ b/content/tutorials/use-simple-xrp-payments/reliable-transaction-submission.md @@ -1,6 +1,6 @@ # Reliable Transaction Submission -Financial institutions and other services using the XRP Ledger should use the best practices described here to make sure that transactions are validated or rejected in a verifiable and prompt way. You should submit transactions to trusted (locally operated) `rippled` servers. +Financial institutions and other services using the XRP Ledger should use the best practices described here to make sure that transactions are validated or rejected in a verifiable and prompt way. You should submit transactions to trusted `rippled` servers. The best practices detailed in this document allow applications to submit transactions to the XRP Ledger while achieving: @@ -54,6 +54,8 @@ Each validated ledger has a canonical order in which transactions apply. This or ### LastLedgerSequence + + `LastLedgerSequence` is an optional [parameter of all transactions](transaction-common-fields.html). This instructs the XRP Ledger that a transaction must be validated on or before a specific ledger version. The XRP Ledger never includes a transaction in a ledger version whose ledger index is higher than the transaction's `LastLedgerSequence` parameter. Use the `LastLedgerSequence` parameter to prevent undesirable cases where a transaction is not confirmed promptly but could be included in a future ledger. You should specify the `LastLedgerSequence` parameter on every transaction. Automated processes should use a value of 4 greater than the last validated ledger index to make sure that a transaction is validated or rejected in a predictable and prompt way. diff --git a/content/tutorials/use-simple-xrp-payments/send-a-multi-signed-transaction.md b/content/tutorials/use-simple-xrp-payments/send-a-multi-signed-transaction.md index 30a71eb40f..01a9a82cfd 100644 --- a/content/tutorials/use-simple-xrp-payments/send-a-multi-signed-transaction.md +++ b/content/tutorials/use-simple-xrp-payments/send-a-multi-signed-transaction.md @@ -31,7 +31,7 @@ Here's an example transaction ready to be multi-signed: "Fee": "30000" } -(This transaction creates an accounting relationship from rEuLyBCvcw4CFmzv8RepSiAoNgF8tTGJQC to rHb9CJAWyB4rj91VRWn96DkukG4bwdtyTh with a maximum balance of 100 USD.) +(This transaction creates an accounting relationship from `rEuLyBCvcw4CFmzv8RepSiAoNgF8tTGJQC` to `rHb9CJAWyB4rj91VRWn96DkukG4bwdtyTh` with a maximum balance of 100 USD.) ## 2. Get one signature diff --git a/content/tutorials/use-simple-xrp-payments/send-xrp.ja.md b/content/tutorials/use-simple-xrp-payments/send-xrp.ja.md index 8763ffd81f..2cb3c59823 100644 --- a/content/tutorials/use-simple-xrp-payments/send-xrp.ja.md +++ b/content/tutorials/use-simple-xrp-payments/send-xrp.ja.md @@ -301,7 +301,7 @@ async function doSubmit(txBlob) { const earliestLedgerVersion = doSubmit(txBlob) ``` -このメソッドは、ローカルでトランザクションを適用しようと試みたときの**一時的な**結果を返します。この結果は、トランザクションが検証済みレジャーに含まれた時点で変わる_可能性があります_。当初は成功していたトランザクションが最終的に失敗となったり、当初失敗していたトランザクションが最終的に成功する場合があります。しかしながら、一時的な結果はほとんどの場合は最終結果と一致するため、ここで`tesSUCCESS`が表示されたらひとまず安心しても問題ありません。😁 +このメソッドは、ローカルでトランザクションを適用しようと試みたときの**一時的な**結果を返します。この結果は、トランザクションが検証済みレジャーに含まれた時点で変わる_可能性があります_。当初は成功していたトランザクションが最終的に失敗となったり、当初失敗していたトランザクションが最終的に成功する場合があります。しかしながら、一時的な結果はほとんどの場合は最終結果と一致するため、ここで`tesSUCCESS`が表示されたらひとまず安心しても問題ありません。😁 他の結果が表示された場合は、以下の点を確認します。 @@ -357,7 +357,7 @@ RippleAPIの`ledger`イベントタイプを使用して、新しい検証済み ```js api.on('ledger', ledger => { - console.log("Ledger version", ledger.ledgerVersion, "was just validated.") + console.log("Ledger version", ledger.ledgerVersion, "was validated.") if (ledger.ledgerVersion > maxLedgerVersion) { console.log("If the transaction hasn't succeeded by now, it's expired") } diff --git a/content/tutorials/use-simple-xrp-payments/send-xrp.md b/content/tutorials/use-simple-xrp-payments/send-xrp.md index d5b7c0a775..278375ae63 100644 --- a/content/tutorials/use-simple-xrp-payments/send-xrp.md +++ b/content/tutorials/use-simple-xrp-payments/send-xrp.md @@ -87,7 +87,7 @@ $(document).ready( () => { }) -**Caution:** Ripple operates the XRP Test Net for testing purposes only, and regularly resets the state of the test net along with all balances. As a precaution, Ripple recommends **not** using the same addresses on the test net and production. +**Caution:** Ripple provides the XRP Test Net for testing purposes only, and regularly resets the state of the test net along with all balances. As a precaution, Ripple recommends **not** using the same addresses on the test net and production. ## Send a Payment on the Test Net @@ -283,7 +283,7 @@ The signing API also returns the transaction's ID, or identifying hash, which yo ### {{n.next()}}. Submit the Signed Blob -Use the [submit() method](rippleapi-reference.html#submit) to submit a transaction to the network. It's also a good idea to use the [getLedgerVersion() method](rippleapi-reference.html#getledgerversion) to take note of the latest validated ledger index before you submit. The earliest ledger version that your transaction could get into as a result of this submission is one higher than the latest validated ledger when you submit it. +Use the [submit() method](rippleapi-reference.html#submit) to submit a transaction to the network. It's also a good idea to use the [`getLedgerVersion()` method](rippleapi-reference.html#getledgerversion) to take note of the latest validated ledger index before you submit. The earliest ledger version that your transaction could get into as a result of this submission is one higher than the latest validated ledger when you submit it. Of course, if the same transaction was previously submitted, it could already be in a previous ledger. (It can't succeed a second time, but you may not realize it succeeded if you aren't looking in the right ledger versions.) @@ -363,7 +363,7 @@ You use the `ledger` event type in RippleAPI to trigger your code to run wheneve ```js api.on('ledger', ledger => { - console.log("Ledger version", ledger.ledgerVersion, "was just validated.") + console.log("Ledger version", ledger.ledgerVersion, "was validated.") if (ledger.ledgerVersion > maxLedgerVersion) { console.log("If the transaction hasn't succeeded by now, it's expired") } @@ -381,7 +381,7 @@ api.on('ledger', ledger => { (Not submitted) - Transaction LastLedgerSequence: + Transaction LastLedgerSequence: @@ -402,7 +402,7 @@ api.on('ledger', ledger => { ### {{n.next()}}. Check Transaction Status -To know for sure what a transaction did, you must look up the outcome of the transaction when it appears in a validated ledger version. For example, you can use the [getTransaction() method](rippleapi-reference.html#gettransaction) to check the status of a transaction: +To know for sure what a transaction did, you must look up the outcome of the transaction when it appears in a validated ledger version. For example, you can use the [`getTransaction()` method](rippleapi-reference.html#gettransaction) to check the status of a transaction: ```js // Continues from previous examples. @@ -464,7 +464,7 @@ To send an XRP payment on the production XRP Ledger, the steps you take are larg ### Getting a Real XRP Account -This tutorial uses a button to get an address that's already funded with Test Net XRP, which only works because Test Net XRP is not worth anything. For actual XRP, you need to get XRP from someone who already has some. (For example, you might buy it on an exchange.) You can generate an address and secret that'll work on either production or the test net using RippleAPI's [generateAddress() method](rippleapi-reference.html#generateaddress): +This tutorial uses a button to get an address that's already funded with Test Net XRP, which only works because Test Net XRP is not worth anything. For actual XRP, you need to get XRP from someone who already has some. (For example, you might buy it on an exchange.) You can generate an address and secret that'll work on either production or the test net using RippleAPI's [`generateAddress()` method](rippleapi-reference.html#generateaddress): ```js const generated = api.generateAddress() @@ -474,7 +474,7 @@ console.log(generated.secret) // Example: sp6JS7f14BuwFY8Mw6bTtLKWauoUs **Warning:** You should only use an address and secret that you generated securely, on your local machine. If another computer generated the address and secret and sent it to you over a network, it's possible that someone else on the network may see that information. If they do, they'll have as much control over your XRP as you do. It's also recommended not to use the same address for the test net and for production, because transactions that you created for use on one network could potentially also be viable on the other network, depending on the parameters you provided. -Generating an address and secret doesn't get you XRP directly; it's just choosing a random number. You must also receive XRP at that address to [fund the account](accounts.html#creating-accounts). A common way to acquire XRP is to buy it from an exchange, then withdraw it to your own address. For more information, see Ripple's [XRP Buying Guide](https://ripple.com/xrp/buy-xrp/). +Generating an address and secret doesn't get you XRP directly; it's only choosing a random number. You must also receive XRP at that address to [fund the account](accounts.html#creating-accounts). A common way to acquire XRP is to buy it from an exchange, then withdraw it to your own address. For more information, see Ripple's [XRP Buying Guide](https://ripple.com/xrp/buy-xrp/). ### Connecting to the Production XRP Ledger diff --git a/content/tutorials/xrp-ledger-businesses/become-an-xrp-ledger-gateway.md b/content/tutorials/xrp-ledger-businesses/become-an-xrp-ledger-gateway.md index acba69d38b..13657a9745 100644 --- a/content/tutorials/xrp-ledger-businesses/become-an-xrp-ledger-gateway.md +++ b/content/tutorials/xrp-ledger-businesses/become-an-xrp-ledger-gateway.md @@ -74,7 +74,7 @@ Main article: [Issuing and Operational Addresses](issuing-and-operational-addres There are several ways in which a gateway can seek to profit from XRP Ledger integration. These can include: * Withdrawal and Deposit fees. Gateways typically charge a small fee (such as 1%) for the service of adding or removing money from the XRP Ledger. You have the power to determine the rate you credit people when they move money onto and off of the XRP Ledger through your gateway. -* Transfer fees. You can set a percentage fee to charge automatically when customers send each other issued currencies created by your issuing address. This amount is debited from the XRP Ledger, decreasing your obligation each time your issued currencies change hands. See [TransferRate](#transferrate) for details. +* Transfer fees. You can set a percentage fee to charge automatically when customers send each other issued currencies created by your issuing address. This amount is debited from the XRP Ledger, decreasing your obligation each time your issued currencies change hands. See [Transfer Fees](#transfer-fees) for details. * Indirect revenue from value added. XRP Ledger integration can provide valuable functionality for your customers that distinguishes your business from your competitors. * Interest on XRP Ledger-backed funds. You can keep the collateral for the funds you issue in XRP Ledger in a bank account that earns interest. Make sure you can always access enough funds to service customer withdrawals. * [Financial Exchange](#liquidity-and-currency-exchange). A gateway can also make offers to buy and sell its issued currencies for other issued currencies in the XRP Ledger, providing liquidity to cross-currency payments and possibly making a profit. (As with all financial exchange, profits are not guaranteed.) @@ -109,6 +109,8 @@ See also: - [The Non-US Standard on KYC set by the Financial Action Task Force (FATF)](http://www.fatf-gafi.org/topics/fatfrecommendations/documents/fatf-recommendations.html) + + ### Anti-Money Laundering (AML) and Combating the Financing of Terrorism (CFT) Money laundering is the process of moving illegal funds by disguising the source, nature or ownership so that funds can be legally accessed or distributed via legitimate financial channels and credible institutions. In short, it is converting “dirty money” into “clean money.” Anti-Money Laundering (AML) refers to the laws and procedures designed to stop money laundering from occurring. @@ -121,6 +123,8 @@ See also: - [“Virtual Currencies: Key Definitions and Potential AML/CFT Risks.” FATF, 2014](http://www.fatf-gafi.org/topics/methodsandtrends/documents/virtual-currency-definitions-aml-cft-risk.html) + + ### Source of Funds To prevent illicit funds from passing through their systems, financial institutions must be able to determine within reason if the source of a customer’s funds is linked to criminal activity. @@ -151,9 +155,11 @@ The Travel Rule is a Bank Secrecy Act (BSA) rule requiring funds-transmitting fi - The execution date of the transmittal order, and - The identity of the recipient's financial institution. + + See also: -- [Additional information and background on the Travel Rule](http://www.fincen.gov/news_room/rp/advisory/html/advissu7.html) +- [Funds “Travel” Regulations: Questions & Answers ](https://www.fincen.gov/resources/statutes-regulations/guidance/funds-travel-regulations-questions-answers) ### Fee Disclosure and Tracing Funds @@ -179,6 +185,8 @@ See also: - [A list of OFAC resources](https://www.treasury.gov/resource-center/faqs/Sanctions/Pages/ques_index.aspx) + + ### Guidance on Virtual Currency and Money Service Business - United States: @@ -242,11 +250,11 @@ There are several prerequisites that ACME must meet for this to happen: - ACME can store the funds allocated to the XRP Ledger in a separate bank account. - If ACME is a cryptocurrency exchange, ACME can create a separate wallet to hold the funds allocated to the XRP Ledger, as publicly-verifiable proof to customers that the gateway is solvent. - ACME must control an address in the XRP Ledger. Ripple's best practices recommend using a separate issuing address and operational address. See [Issuing and Operational Addresses](issuing-and-operational-addresses.html) for details. - - ACME must enable the [DefaultRipple Flag](#defaultripple) on its issuing address for customers to send and receive its issued currencies. + - ACME must enable the [`DefaultRipple` Flag](#default-ripple) on its issuing address for customers to send and receive its issued currencies. - Alice must create an accounting relationship (trust line) from her XRP Ledger address to ACME's issuing address. She can do this from any XRP Ledger client application as long as she knows ACME's issuing address. - ACME should publicize its issuing address on its website where customers can find it. It can also use an [`xrp-ledger.toml` file](xrp-ledger-toml.html) to publish the issuing address to automated systems. - ACME must create a user interface for Alice to send funds from ACME into the XRP Ledger. - - ACME needs to know Alice's XRP Ledger address. ACME can have Alice input her XRP Ledger addresss as part of the interface, or ACME can require Alice to input and verify her XRP Ledger address in advance. + - ACME needs to know Alice's XRP Ledger address. ACME can have Alice input her XRP Ledger address as part of the interface, or ACME can require Alice to input and verify her XRP Ledger address in advance. See [Sending Payments to Customers](#sending-payments-to-customers) for an example of how to send payments into the XRP Ledger. @@ -278,15 +286,15 @@ Processing payments to and from the XRP Ledger naturally comes with some risks, - Protect yourself against reversible deposits. XRP Ledger payments are irreversible, but many electronic money systems like credit cards or PayPal are not. Scammers can abuse this to take their fiat money back by canceling a deposit after receiving issued currencies in the XRP Ledger. - When sending into the XRP Ledger, specify the issuing address as the issuer of the currency. Otherwise, you might accidentally use paths that deliver the same currency issued by other addresses. -- Before sending a payment into the XRP Ledger, double check the cost of the payment. A payment from your operational address to a customer should not cost more than the destination amount plus any [transfer fee](#transferrate) you have set. +- Before sending a payment into the XRP Ledger, double check the cost of the payment. A payment from your operational address to a customer should not cost more than the destination amount plus any [transfer fee](#transfer-fees) you have set. - Before processing a payment out of Ripple, make sure you know the customer's identity. This makes it harder for anonymous attackers to scam you. Most anti-money-laundering regulations require this anyway. This is especially important because the users sending money from the XRP Ledger could be different than the ones that initially received the money in the XRP Ledger. - Follow the guidelines for [reliable transaction submission](#reliable-transaction-submission) when sending XRP Ledger transactions. - [Robustly monitor for incoming payments](#robustly-monitoring-for-payments), and read the correct amount. Don't mistakenly credit someone the full amount if they only sent a [partial payment](partial-payments.html). - Track your obligations and balances within the XRP Ledger, and compare with the assets in your collateral account. If they do not match up, stop processing withdrawals and deposits until you resolve the discrepancy. - Avoid ambiguous situations. We recommend the following: - - Enable the [`DisallowXRP` flag](#disallowxrp) for the issuing address and all operational addresses, so customers do not accidentally send you XRP. (Private exchanges should *not* set this flag, since they trade XRP normally.) + - Enable the [Disallow XRP flag](#disallow-xrp) for the issuing address and all operational addresses, so customers do not accidentally send you XRP. (Private exchanges should *not* set this flag, since they trade XRP normally.) - Enable the [`RequireDest` flag](require-destination-tags.html) for the issuing address and all operational addresses, so customers do not accidentally send a payment without the destination tag to indicate who should be credited. - - Enable the [`RequireAuth` flag](#requireauth) on all operational addresses so they cannot issue currency by accident. + - Enable the [`RequireAuth` flag](#require-auth) on all operational addresses so they cannot issue currency by accident. - Monitor for suspicious or abusive behavior. For example, a user could repeatedly send funds into and out of the XRP Ledger, as a denial of service attack that effectively empties an operational address's balance. Suspend customers whose addresses are involved in suspicious behavior by not processing their XRP Ledger payments. ## Trading on Ripple @@ -300,7 +308,7 @@ After the issued currencies have been created in the XRP Ledger, they can be fre - XRP Ledger users trading and sending EUR.ACME to one another requires no intervention by ACME. - All exchanges and balances in the XRP Ledger are publicly viewable. -The following diagram depicts an XRP Ledger payment sending 2EUR.ACME from Alice to Charlie. ACME can query the XRP Ledger to see updates to its balances any time after the transaction has occurred: +The following diagram depicts an XRP Ledger payment sending 2 EUR.ACME from Alice to Charlie. ACME can query the XRP Ledger to see updates to its balances any time after the transaction has occurred: ![Diagram: Alice's sends 2 EUR.ACME from her trust line to Charlie's](img/e2g-03.png) @@ -332,7 +340,7 @@ Similarly, *Source Tags* indicate the originator or source of a payment. Most co Ripple recommends making a user interface to generate a destination tag on-demand when a customer intends to send money to the gateway. You should consider that destination tag valid only for a payment with the expected amount. Later, bounce any other transactions that reuse the same destination tag. -Enable the [RequireDest](require-destination-tags.html) flag on your issuing and operational addresses so that customers must use a destination tag to indicate where funds should go when they send XRP Ledger payments to your gateway. +[Enable the `RequireDest` flag](require-destination-tags.html) on your issuing and operational addresses so that customers must use a destination tag to indicate where funds should go when they send XRP Ledger payments to your gateway. For more information, see [Source and Destination Tags](source-and-destination-tags.html). @@ -344,14 +352,14 @@ Historically, Ripple (the company) issued gateway bulletins to introduce new fea - May 13, 2015 - [GB-2015-06 Gateway Bulletin: Corrections to Autobridging (PDF)](assets/pdf/GB-2015-06.pdf) - April 17, 2015 - [GB-2015-05 Historical Ledger Query Migration](assets/pdf/GB-2015-05.pdf) - March 13, 2015 - [GB-2015-04 Action Required: Default Ripple Flag (PDF)](https://ripple.com/files/GB-2015-04.pdf) -- March 3, 2015 - [GB-2015-03 Gateway Advisory: FinCEN Ruling on MoneyGram Compliance Program (PDF)](https://ripple.com/files/GB-2015-03.pdf) +- March 3, 2015 - [GB-2015-03 Gateway Advisory: FinCEN Ruling on MoneyGram Compliance Program (PDF)](https://ripple.com/files/GB-2015-03.pdf) - March 2, 2015 (Updated) - [GB-2015-02 New Standards: How to be Featured on Ripple Trade and Ripple Charts (PDF)](https://ripple.com/files/GB-2015-02.pdf) - January 5, 2015 - [GB-2015-01 Gateway Advisory: Reliable Transaction Submission (PDF)](https://ripple.com/files/GB-2015-01.pdf) - December 18, 2014 - [GB-2014-08 Gateway Advisory: Recent FinCEN Rulings (PDF)](https://ripple.com/files/GB-2014-08.pdf) - November 4, 2014 -[GB-2014-07 Gateway Advisory: FATF Standards (PDF)](https://ripple.com/files/GB-2014-07.pdf) - October 17, 2014 -[GB-2014-06 Gateway Advisory: Partial Payment Flag (PDF)](https://ripple.com/files/GB-2014-06.pdf) -- September 24, 2014 - [GB-2014-05 Gateway Advisory: EBA Opinion On Virtual Currency (PDF)](https://ripple.com/files/GB-2014-05.pdf) -- September 11, 2014 - [GB-2014-04 Gateway Advisory: CFPB Opinion on Virtual Currency (PDF)](https://ripple.com/files/GB-2014-04.pdf) +- September 24, 2014 - [GB-2014-05 Gateway Advisory: EBA Opinion On Virtual Currency (PDF)](https://ripple.com/files/GB-2014-05.pdf) +- September 11, 2014 - [GB-2014-04 Gateway Advisory: CFPB Opinion on Virtual Currency (PDF)](https://ripple.com/files/GB-2014-04.pdf) - August 19, 2014 - [GB-2014-03 Updated Feature: Trust Lines UI (PDF)](https://ripple.com/files/GB-2014-03.pdf) - August 1, 2014 - [GB-2014-02 New Feature: Balance Freeze (PDF)](https://ripple.com/files/GB-2014-02.pdf) - April 23, 2014, Updated August 14, 2014 -[GB-2014-01 New Feature: Ripple Names (PDF)](https://ripple.com/files/GB-2014-01.pdf) @@ -375,23 +383,24 @@ There are several interfaces you can use to connect to the XRP Ledger, depending ## Tool Security -Any time you submit an XRP Ledger transaction, it must be signed using your secret key. The secret key gives full control over your XRP Ledger address. **Never** send your secret key to a server operated by someone else. Either use your own `rippled` server, or sign the transactions locally before sending them to a `rippled` server. +Any time you submit an XRP Ledger transaction, it must be signed using your secret key. The secret key gives full control over your XRP Ledger address. **Never** send your secret key to a server run by someone else. Either use your own `rippled` server, or sign the transactions locally before sending them to a `rippled` server. -The examples in this document show API methods that include a secret key. This is only safe if you control `rippled` server yourself, *and* you connect to it over a connection that is secure from outside listeners. (For example, you could connect over a loopback (localhost) network, a private subnet, or an encrypted VPN.) Alternatively, you could use [RippleAPI](rippleapi-reference.html) to sign transactions locally before submitting them to a third-party server. +The examples in this document show API methods that include a secret key. This is only safe if you control `rippled` server yourself, *and* you connect to it over a connection that is secure from outside listeners. (For example, you could connect over a loopback (`localhost`) network, a private network, or an encrypted VPN.) Alternatively, you could use [RippleAPI](rippleapi-reference.html) to sign transactions locally before submitting them to a third-party server. -## DefaultRipple +## Default Ripple -The DefaultRipple flag controls whether the balances in an accounting relationship [allowed to ripple](rippling.html) by default. Rippling is what allows customers to trade issued currencies, so a gateway must allow rippling on all the accounting relationships to its issuing address. +The Default Ripple flag controls whether the balances in an accounting relationship [allowed to ripple](rippling.html) by default. Rippling is what allows customers to trade issued currencies, so a gateway must allow rippling on all the accounting relationships to its issuing address. -Before asking customers to create accounting relationships to its issuing address, a gateway should enable the DefaultRipple flag on that address. Otherwise, the gateway must individually disable the NoRipple flag for each accounting relationship that other addresses have created. +Before asking customers to create accounting relationships to its issuing address, a gateway should enable the Default Ripple flag on that address. Otherwise, the gateway must individually disable the No Ripple flag for each accounting relationship that other addresses have created. -The following is an example of using a locally-hosted `rippled`'s [submit method][] to send an AccountSet transaction to enable the DefaultRipple flag: +The following is an example of using a locally-hosted `rippled`'s [submit method][] to send an AccountSet transaction to enable the Default Ripple flag: Request: -``` +```json POST http://localhost:8088/ + { "method": "submit", "params": [ @@ -414,7 +423,7 @@ POST http://localhost:8088/ Response: -``` +```json { "result": { "engine_result": "tesSUCCESS", @@ -437,22 +446,23 @@ Response: } ``` -To confirm that an address has DefaultRipple enabled, look up the address using the [account_info method][], specifying a validated ledger version. Use [a bitwise-AND operator](https://en.wikipedia.org/wiki/Bitwise_operation#AND) to compare the `Flags` field with 0x00800000 (the [ledger flag lsfDefaultRipple](accountroot.html#accountroot-flags)). If the result of the bitwise-AND operation is nonzero, then the address has DefaultRipple enabled. +To confirm that an address has Default Ripple enabled, look up the address using the [account_info method][], specifying a validated ledger version. Use [a bitwise-AND operator](https://en.wikipedia.org/wiki/Bitwise_operation#AND) to compare the `Flags` field with `0x00800000` (the [ledger flag `lsfDefaultRipple`](accountroot.html#accountroot-flags)). If the result of the bitwise-AND operation is nonzero, then the address has Default Ripple enabled. -## DisallowXRP +## Disallow XRP -The DisallowXRP setting (`disallowIncomingXRP` in RippleAPI) is designed to discourage XRP Ledger users from sending XRP to an address by accident. This reduces the costs and effort of bouncing undesired payments, if your gateway does not trade XRP. The DisallowXRP flag is not strictly enforced, because doing so could allow addresses to become permanently unusable if they run out of XRP. Client applications should honor the DisallowXRP flag by default. +The Disallow XRP setting (`disallowIncomingXRP` in RippleAPI) is designed to discourage XRP Ledger users from sending XRP to an address by accident. This reduces the costs and effort of bouncing undesired payments, if your gateway does not trade XRP. The Disallow XRP flag is not strictly enforced, because doing so could allow addresses to become permanently unusable if they run out of XRP. Client applications should honor the Disallow XRP flag by default. -An issuing gateway that does not trade XRP should enable the DisallowXRP flag on the gateway's issuing and operational addresses. A private exchange that trades in XRP should only enable the DisallowXRP flag on addresses that are not expected to receive XRP. +An issuing gateway that does not trade XRP should enable the Disallow XRP flag on the gateway's issuing and operational addresses. A private exchange that trades in XRP should only enable the Disallow XRP flag on addresses that are not expected to receive XRP. -The following is an example of using a locally-hosted `rippled`'s [submit method][] to send an AccountSet transaction to enable the DisallowXRP flag: +The following is an example of using a locally-hosted `rippled`'s [submit method][] to send an AccountSet transaction to enable the Disallow XRP flag: Request: -``` +```json POST http://localhost:8088/ + { "method": "submit", "params": [ @@ -475,7 +485,7 @@ POST http://localhost:8088/ Response: -``` +```json { "result": { "engine_result": "tesSUCCESS", @@ -499,18 +509,19 @@ Response: ``` -## RequireAuth +## Require Auth -The `RequireAuth` setting prevents all counterparties from holding balances issued by an address unless the address has specifically approved an accounting relationship with that counterparty. For more information, see [Authorized Trust Lines](authorized-trust-lines.html). +The Require Auth setting prevents all counterparties from holding balances issued by an address unless the address has specifically approved an accounting relationship with that counterparty. For more information, see [Authorized Trust Lines](authorized-trust-lines.html). -### Enabling RequireAuth +### Enabling Require Auth -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 Require Auth flag: (This method works the same way regardless of whether the address is an issuing address, operational address, or standby address.) Request: -``` +```json POST http://localhost:5005/ + { "method": "submit", "params": [ @@ -535,14 +546,15 @@ POST http://localhost:5005/ If you are using the [Authorized Trust Lines](authorized-trust-lines.html) feature, customers cannot hold balances you issue unless you first authorize their accounting relationships to you in the XRP Ledger. -To authorize an accounting relationship, 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 an accounting relationship, 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` flag](trustset.html#trustset-flags) 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 issued 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": [ @@ -577,26 +589,25 @@ To robustly check for incoming payments, gateways should do the following: * [Look out for Partial Payments](https://ripple.com/files/GB-2014-06.pdf "Partial Payment Flag Gateway Bulletin"). Payments with the partial-payment flag enabled can be considered "successful" if any non-zero amount is delivered, even miniscule amounts. * In `rippled`, check the transaction for a `meta.delivered_amount` field. If present, that field indicates how much money *actually* got delivered to the `Destination` address. * In RippleAPI, you can search the `outcome.BalanceChanges` field to see how much the destination address received. In some cases, this can be divided into multiple parts on different trust lines. -* Some transactions change your balances without being payments directly to or from one of your addresses. For example, if ACME sets a nonzero [TransferRate](#transferrate), then ACME's issuing address's outstanding obligations decrease each time Bob and Charlie exchange ACME's issued currencies. See [TransferRate](#transferrate) for more information. +* Some transactions change your balances without being payments directly to or from one of your addresses. For example, if ACME sets a nonzero [transfer fee](#transfer-fees), then ACME's issuing address's outstanding obligations decrease each time Bob and Charlie exchange ACME's issued currencies. See [Transfer Fees](#transfer-fees) for more information. To make things simpler for your customers, we recommend accepting payments to either operational addresses and issuing addresses. As an added precaution, we recommend comparing the balances of your issuing address with the collateral funds in your internal accounting system as of each new XRP Ledger ledger version. The issuing address's negative balances should match the assets you have allocated to XRP Ledger outside the network. If the two do not match up, then you should suspend processing payments into and out of the XRP Ledger until you have resolved the discrepancy. * Use `rippled`'s [gateway_balances method][] or [RippleAPI's `getTrustlines` method](rippleapi-reference.html#gettrustlines) to check your balances. -* If you have a [TransferRate](#transferrate) set, then your obligations within the XRP Ledger decrease slightly whenever other XRP Ledger addresses transfer your issued currencies among themselves. +* If you have a [Transfer Fee](#transfer-fees) set, then your obligations within the XRP Ledger decrease slightly whenever other XRP Ledger addresses transfer your issued currencies among themselves. -## TransferRate +## Transfer Fees -The *TransferRate* setting (`transferRate` in RippleAPI) defines a fee to charge for transferring issued currencies from one XRP Ledger address to another. See [Transfer Fees](transfer-fees.html) for more information. +The `TransferRate` setting (`transferRate` in RippleAPI) defines a fee to charge for transferring issued currencies from one XRP Ledger address to another. See [Transfer Fees](transfer-fees.html) for more information. -The following is an example of using a locally-hosted `rippled`'s [submit method][] to send an AccountSet transaction for the issuing address rsA2LpzuawewSBQXkiju3YQTMzW13pAAdW, setting the TransferRate to charge a fee of 0.5%. +The following is an example of using a locally-hosted `rippled`'s [submit method][] to send an AccountSet transaction for the issuing address `rsA2LpzuawewSBQXkiju3YQTMzW13pAAdW`, setting the `TransferRate` to charge a fee of 0.5%. Request: -``` - +```json { "method": "submit", "params": [ @@ -639,14 +650,14 @@ Response: } ``` -### TransferRate with Operational and Standby Addresses +### Transfer Fees with Operational and Standby Addresses -All XRP Ledger addresses, including operational and standby addresses, are subject to the transfer fee. If you set a nonzero transfer fee, then you must send extra (to pay the TransferRate) when making payments from your operational address or standby address. In other words, your addresses must pay back a little of the balance your issuing address created, each time you make a payment. +All XRP Ledger addresses, including operational and standby addresses, are subject to the issuer's transfer fees when sending issued currency. If you set a nonzero transfer fee, then you must send extra (to pay the transfer fee) when making payments from your operational address or standby address. In other words, your addresses must pay back a little of the balance your issuing address created, each time you make a payment. * In `rippled`'s APIs, you should set the [`SendMax` transaction parameter][Payment] higher than the destination `Amount` parameter. * In RippleAPI, you should set the `source.maxAmount` parameter higher than the `destination.amount` parameter; or, set the `source.amount` parameter higher than the `destination.minAmount` parameter. -**Note:** The TransferRate does not apply when sending issued currencies directly to the issuing address. The issuing address must always accept its issued currencies at face value in the XRP Ledger. This means that customers don't have to pay the TransferRate if they send payments to the issuing address directly, but they do when sending to an operational address. If you accept payments at both addresses, you may want to adjust the amount you credit customers in your system of record when customers send payments to the operational address, to compensate for the TransferRate the customer pays. +**Note:** Transfer fees do not apply when sending issued currencies directly to the issuing address. The issuing address must always accept its issued currencies at face value in the XRP Ledger. This means that customers don't have to pay the transfer fee if they send payments to the issuing address directly, but they do when sending to an operational address. If you accept payments at both addresses, you may want to adjust the amount you credit customers in your system of record when customers send payments to the operational address, to compensate for the transfer fee the customer pays. For example: If ACME sets a transfer fee of 1%, an XRP Ledger payment to deliver 5 EUR.ACME from a customer address to ACME's issuing address would cost exactly 5 EUR.ACME. However, the customer would need to send 5.05 EUR.ACME to deliver 5 EUR.ACME to ACME's operational address. (The issuing address's total obligations in the XRP Ledger decrease by 0.05 EUR.ACME.) When ACME credits customers for payments to ACME's operational address, ACME credits the customer for the amount delivered to the operational address _and_ the transfer fee, giving the customer €5,05 in ACME's systems. @@ -657,7 +668,7 @@ When you build an automated system to send payments into the XRP Ledger for your One common pitfall is performing pathfinding before sending sending a payment to customers in the XRP Ledger. If you specify the issuers correctly, the [default paths](paths.html#default-paths) can deliver the currency as intended. -The following is an example of using a locally-hosted `rippled`'s [submit method][] to send a payment from the operational address rf1BiGeXwwQoi8Z2ueFYTEXSwuJYfV2Jpn to the customer address raKEEVSGnKSD9Zyvxu4z6Pqpm4ABH8FS6n, sending and delivering funds issued by the issuing address rsA2LpzuawewSBQXkiju3YQTMzW13pAAdW. +The following is an example of using a locally-hosted `rippled`'s [submit method][] to send a payment from the operational address `rf1BiGeXwwQoi8Z2ueFYTEXSwuJYfV2Jpn` to the customer address `raKEEVSGnKSD9Zyvxu4z6Pqpm4ABH8FS6n`, sending and delivering funds issued by the issuing address `rsA2LpzuawewSBQXkiju3YQTMzW13pAAdW`. Request: @@ -727,7 +738,7 @@ In particular, note the following features of the [Payment transaction][]: - No `Paths` field. The payment only succeeds if it can use a [default path](paths.html#default-paths), which is preferable. Using less direct paths can become much more expensive. - The `issuer` of both the `SendMax` and the `Amount` is the issuing address. This ensures that the transaction sends and delivers issued currencies from the issuing address, and not from some other gateway. -- The `value` of the `SendMax` amount is slightly higher than the destination `Amount`, to compensate for the [transfer fee](#transferrate). In this case, the transfer fee is 0.5%, so the `SendMax` amount is exactly 1.005 times the destination `Amount`. +- The `value` of the `SendMax` amount is slightly higher than the destination `Amount`, to compensate for the [transfer fee](#transfer-fees). In this case, the transfer fee is 0.5%, so the `SendMax` amount is exactly 1.005 times the destination `Amount`. ## Bouncing Payments @@ -738,7 +749,7 @@ The first requirement to bouncing payments is [robustly monitoring for incoming Second, you should send bounced payments as Partial Payments. Since third parties can manipulate the cost of pathways between addresses, Partial Payments allow you to divest yourself of the full amount without being concerned about exchange rates within the XRP Ledger. You should publicize your bounced payments policy as part of your terms of use. Send the bounced payment from either an operational address or a standby address. -* To send a Partial Payment using `rippled`, enable the [tfPartialPayment flag](payment.html#payment-flags) on the transaction. Set the `Amount` field to the amount you received and omit the `SendMax` field. +* To send a Partial Payment using `rippled`, enable the [`tfPartialPayment` flag](payment.html#payment-flags) on the transaction. Set the `Amount` field to the amount you received and omit the `SendMax` field. * To send a Partial Payment using RippleAPI, set the `allowPartialPayment` field of the [Payment object](rippleapi-reference.html#payment) to `true`. Set the `source.maxAmount` and `destination.amount` both equal to the amount you received. You should use the `SourceTag` value (`source.tag` in RippleAPI) from the incoming payment as the `DestinationTag` value (`destination.tag` in RippleAPI) for the return payment. diff --git a/content/tutorials/xrp-ledger-businesses/list-xrp-as-an-exchange.md b/content/tutorials/xrp-ledger-businesses/list-xrp-as-an-exchange.md index 7b94a90e8f..9ce7ee7625 100644 --- a/content/tutorials/xrp-ledger-businesses/list-xrp-as-an-exchange.md +++ b/content/tutorials/xrp-ledger-businesses/list-xrp-as-an-exchange.md @@ -56,7 +56,7 @@ When the [`tfPartialPayment` flag](payment.html#payment-flags) is enabled, the ` XRP is held in _accounts_ (also referred to as _wallets_ or _addresses_ ) on the XRP Ledger. Accounts on the XRP Ledger are different than accounts on other blockchain ledgers, such as Bitcoin, where accounts incur little to no overhead. In the XRP Ledger, account state is stored per ledger and accounts are [not easy to delete](accounts.html#deletion-of-accounts). To offset the costs associated with storing accounts, each account must hold a separate [reserve of XRP](reserves.html) that cannot be sent to others. For these reasons, Ripple recommends that institutions not create excessive or needless accounts. - + To follow Ripple's recommended best practices, Alpha Exchange should create at least two new accounts on the XRP Ledger. To minimize the risks associated with a compromised secret key, Ripple recommends creating [_cold_, _hot_, and _warm_ accounts](issuing-and-operational-addresses.html) (these are sometimes referred to, respectively, as cold, hot, and warm wallets). The hot/warm/cold model is intended to balance security and convenience. Exchanges listing XRP should create the following accounts: diff --git a/content/tutorials/xrp-ledger-businesses/list-your-exchange-on-xrp-charts.md b/content/tutorials/xrp-ledger-businesses/list-your-exchange-on-xrp-charts.md index 75c3fbe0e0..74a5f62757 100644 --- a/content/tutorials/xrp-ledger-businesses/list-your-exchange-on-xrp-charts.md +++ b/content/tutorials/xrp-ledger-businesses/list-your-exchange-on-xrp-charts.md @@ -17,7 +17,7 @@ If you have any questions about endpoint specifications, contact {{n.next()}} ## Access the `ripple-lib` repo -`ripple-lib` is an open-source project. You can take a look at `ripple-lib` code simply by accessing the `ripple-lib` GitHub repo. Before contributing or reporting bugs, we recommend that you get to know the code and developer experience by performing the following tasks. +`ripple-lib` is an open-source project. You can take a look at `ripple-lib` code by accessing the `ripple-lib` GitHub repo. Before contributing or reporting bugs, we recommend that you get to know the code and developer experience by performing the following tasks. [Access the `ripple-lib` repo](https://github.com/ripple/ripple-lib) @@ -61,4 +61,4 @@ As you explore `ripple-lib`, you may find code that you don’t think is working If the bug you wish to report is security-related, we urge you to disclose it responsibly through Ripple's [Bug Bounty program](https://ripple.com/bug-bounty/). -[Report bugs](https://github.com/ripple/ripple-lib/issues) \ No newline at end of file +[Report bugs](https://github.com/ripple/ripple-lib/issues) diff --git a/content/use-cases/contribute-code-to-rippled.md b/content/use-cases/contribute-code-to-rippled.md index ec2ce55287..d5ccf7084f 100644 --- a/content/use-cases/contribute-code-to-rippled.md +++ b/content/use-cases/contribute-code-to-rippled.md @@ -8,7 +8,7 @@ Want to contribute code or a bug report to help improve `rippled`, the core peer {{n.next()}} ## Access the `rippled` repo -`rippled` is an open-source project. You can take a look at `rippled` code simply by accessing the `rippled` GitHub repo. Before contributing or reporting bugs, we recommend that you get to know the code and developer experience by performing the following tasks. +`rippled` is an open-source project. You can take a look at `rippled` code by accessing the `rippled` GitHub repo. Before contributing or reporting bugs, we recommend that you get to know the code and developer experience by performing the following tasks. [Access the repo](https://github.com/ripple/rippled) @@ -60,4 +60,4 @@ As you explore `rippled`, you may find code that you don’t think is working as If the bug you wish to report is security-related, we urge you to disclose it responsibly through Ripple's [Bug Bounty program](https://ripple.com/bug-bounty/). -[Report bugs](https://github.com/ripple/rippled/issues) \ No newline at end of file +[Report bugs](https://github.com/ripple/rippled/issues) diff --git a/content/use-cases/open-a-payment-channel-to-enable-an-inter-exchange-network.md b/content/use-cases/open-a-payment-channel-to-enable-an-inter-exchange-network.md index 89a64a99f4..88f8425126 100644 --- a/content/use-cases/open-a-payment-channel-to-enable-an-inter-exchange-network.md +++ b/content/use-cases/open-a-payment-channel-to-enable-an-inter-exchange-network.md @@ -1,6 +1,6 @@ # Open a Payment Channel to Enable an Inter-Exchange Network -A payment channel enables you to send one-way, "asynchronous" XRP payments that can be divided into very small increments and settled later. As a digital asset exchange, if you frequently send XRP to another exchange, you can improve the efficiency of these payments by opening an XRP Ledger [payment channel](payment-channels.html) between your exchange (the _payer_ exchange) and the other exchange (the _payee_ exchange). In the case of a two-way flow with another exchange, you can simply open two payment channels (one for each direction). +A payment channel enables you to send one-way, "asynchronous" XRP payments that can be divided into very small increments and settled later. As a digital asset exchange, if you send many payments of XRP to another exchange, you can improve the efficiency of these payments by opening an XRP Ledger [payment channel](payment-channels.html) between your exchange (the _payer_ exchange) and the other exchange (the _payee_ exchange). In the case of a two-way flow with another exchange, you can open two payment channels (one for each direction). @@ -20,7 +20,7 @@ Here are some of the benefits of using a payment channel to send XRP instead of - **Connect to the Internet of Value:** One of the key requirements of the [Internet of Value](https://ripple.com/insights/the-internet-of-value-what-it-means-and-how-it-benefits-everyone/) is interoperability. The [Interledger Protocol](https://interledger.org/) (ILP), which plays a large role in driving this interoperability, works best when it [uses payment channels](https://interledger.org/rfcs/0027-interledger-protocol-4) as its method for rebalancing accounts. In effect, when you open a payment channel from your exchange to another, you are connecting to the Internet of Value and helping to create the inter-exchange network that is fundamental to the success of the Internet of Value and the apps that are built on it. - Connecting your exchange to other exchanges by way of payment channels is another differentiator. For customers who are moving XRP to purchase various currencies across exchanges, knowing that they can move XRP at a moment's notice from your exchange to any number of exchanges in the Internet of Value can make your exchange a preferred place to custody their assets. + Connecting your exchange to other exchanges by way of payment channels is another differentiator. For customers who are moving XRP to buy various currencies across exchanges, knowing that they can move XRP at a moment's notice from your exchange to any number of exchanges in the Internet of Value can make your exchange a preferred place to custody their assets. Here’s a roadmap to the high-level tasks you’ll need to perform to implement this payment channel use case. To go directly to a full payment channels tutorial, see [Use Payment Channels](use-payment-channels.html). @@ -51,7 +51,7 @@ If not, a great way for an exchange to get access to a `rippled` server is to se {{n.next()}} ## Payer and payee: Fund XRP Ledger accounts with enough XRP -If your exchange processes XRP deposits and withdrawals directly, you probably have existing funded XRP Ledger accounts that you can use for this purpose. Just ensure that they are funded with enough XRP as described here. +If your exchange processes XRP deposits and withdrawals directly, you probably have existing funded XRP Ledger accounts that you can use for this purpose. Ensure that they are funded with enough XRP as described here. Along these lines, there's a good chance that you are following industry best practices and have a cold account plus one or more hot accounts. Use the hot accounts for your payment channels. diff --git a/dactyl-config.yml b/dactyl-config.yml index 2f55dd6702..8e52a742a4 100644 --- a/dactyl-config.yml +++ b/dactyl-config.yml @@ -3359,7 +3359,7 @@ pages: supercategory: rippled API category: Public rippled Methods subcategory: Account Methods - blurb: Get recommended changes to an account's DefaultRipple and NoRipple settings. + blurb: Get recommended changes to an account's Default Ripple and No Ripple settings. targets: - en diff --git a/tool/openapi_templates_alpha/template-openapi_data_type.md b/tool/openapi_templates_alpha/template-openapi_data_type.md index b095cf1caa..887e4ff9ea 100644 --- a/tool/openapi_templates_alpha/template-openapi_data_type.md +++ b/tool/openapi_templates_alpha/template-openapi_data_type.md @@ -2,7 +2,7 @@ {{description}} -**Warning:** {{spec.info.title}} is early alpha software. API methods and data formats are likely to change frequently in ways that break backwards compatibility. +**Warning:** {{spec.info.title}} is early alpha software. API methods and data formats are likely to change often in ways that break backwards compatibility. {% if type is defined %}- **Type:** {{type|title}} {% elif oneOf is defined %}- **Possible Types:** diff --git a/tool/openapi_templates_alpha/template-openapi_data_types_toc.md b/tool/openapi_templates_alpha/template-openapi_data_types_toc.md index 2b396ac3dd..33ba5141b2 100644 --- a/tool/openapi_templates_alpha/template-openapi_data_types_toc.md +++ b/tool/openapi_templates_alpha/template-openapi_data_types_toc.md @@ -1,6 +1,6 @@ # {{api_title}} Data Types -**Warning:** {{spec.info.title}} is early alpha software. API methods and data formats are likely to change frequently in ways that break backwards compatibility. +**Warning:** {{spec.info.title}} is early alpha software. API methods and data formats are likely to change often, in ways that break backwards compatibility. The following data types are defined for this API: diff --git a/tool/openapi_templates_alpha/template-openapi_endpoint.md b/tool/openapi_templates_alpha/template-openapi_endpoint.md index d9a11c2d9d..fbc12d2699 100644 --- a/tool/openapi_templates_alpha/template-openapi_endpoint.md +++ b/tool/openapi_templates_alpha/template-openapi_endpoint.md @@ -2,7 +2,7 @@ {{description}} -**Warning:** {{spec.info.title}} is early alpha software. API methods and data formats are likely to change frequently in ways that break backwards compatibility. +**Warning:** {{spec.info.title}} is early alpha software. API methods and data formats are likely to change often in ways that break backwards compatibility. ## Request Format diff --git a/tool/openapi_templates_alpha/template-openapi_endpoint_tag_toc.md b/tool/openapi_templates_alpha/template-openapi_endpoint_tag_toc.md index 875b7f1b15..40edc915d0 100644 --- a/tool/openapi_templates_alpha/template-openapi_endpoint_tag_toc.md +++ b/tool/openapi_templates_alpha/template-openapi_endpoint_tag_toc.md @@ -2,7 +2,7 @@ {{tag.description}} -**Warning:** {{info.title}} is early alpha software. API methods and data formats are likely to change frequently in ways that break backwards compatibility. +**Warning:** {{info.title}} is early alpha software. API methods and data formats are likely to change often in ways that break backwards compatibility. | Summary | Path | |:--------|:-----| diff --git a/tool/openapi_templates_alpha/template-openapi_endpoint_toc.md b/tool/openapi_templates_alpha/template-openapi_endpoint_toc.md index 659f972357..0c5ac43204 100644 --- a/tool/openapi_templates_alpha/template-openapi_endpoint_toc.md +++ b/tool/openapi_templates_alpha/template-openapi_endpoint_toc.md @@ -2,7 +2,7 @@ {{info.description}} -**Warning:** {{spec.info.title}} is early alpha software. API methods and data formats are likely to change frequently in ways that break backwards compatibility. +**Warning:** {{spec.info.title}} is early alpha software. API methods and data formats are likely to change often in ways that break backwards compatibility. {% if tags %} View API methods by category: diff --git a/tool/spelling.txt b/tool/spelling.txt index b9c1cad1d2..b198728d68 100644 --- a/tool/spelling.txt +++ b/tool/spelling.txt @@ -99,6 +99,7 @@ mbps md5 metadata mitigations +modeled modulo namespace nonces @@ -149,6 +150,7 @@ sharding smartphone spamming sqlite +streamlines subdomain subfolder subfolders @@ -199,12 +201,15 @@ url urls utc validator +verifiability versioning virtualization virtualized wasn't we'll won't +webpage +webpages website websites websocket @@ -220,13 +225,16 @@ zeroes bitcoin centos +cloudflare debian firefox github google linux nginx +ntp openssl +paypal redhat rhel ubuntu @@ -239,16 +247,19 @@ cny eur mxn usd +xau xrp hash128 hash160 hash256 +starray uint16 uint256 uint32 uint64 uint8 +vector256 512half account_channels @@ -282,6 +293,7 @@ consensus_info cors crawl_shards crypto +cryptoconditions cryptoconditionssuite deletableaccounts deposit_authorized @@ -330,6 +342,7 @@ gateway_balances get_counts gravatar grpc +hardenedvalidations hmac interledger kyc @@ -364,6 +377,7 @@ paymentchannelfund peer_reservations_add peer_reservations_del peer_reservations_list +preemptively offercancel offercreate requirefullycanonicalsig @@ -381,6 +395,7 @@ setfee setregularkey shamapv2 shor +sorteddirectories sign_for signerlist signerlistset @@ -401,6 +416,8 @@ validation_create validation_seed validator_info validator_list_sites -vector256 xpring xrpchat + +britto +macbrough diff --git a/tool/word_substitutions.yaml b/tool/word_substitutions.yaml index 4bf9e17d55..36a08b4df5 100644 --- a/tool/word_substitutions.yaml +++ b/tool/word_substitutions.yaml @@ -71,7 +71,7 @@ exhibit: show expedite: hasten, speed up expeditious: fast, quick expend: spend -expertise: ability +# expertise: ability #expiration: end facilitate: ease, help feasible: can be done, workable