From 40f8bdc4a15e4f2efa339306284ce3b9ef788b11 Mon Sep 17 00:00:00 2001 From: mDuo13 Date: Tue, 13 Aug 2019 14:24:28 -0700 Subject: [PATCH] Interlinking: add missed concepts pages, etc. --- .../amendments/amendments.md | 14 +++++++ .../consensus-principles-and-rules.md | 37 ++++++++++++++----- .../concepts/consensus-network/consensus.md | 3 +- .../concepts/consensus-network/fee-voting.md | 16 ++++++++ .../consensus-network/parallel-networks.md | 14 +++++++ .../transaction-malleability.md | 14 +++++++ .../issued-currencies-overview.md | 23 +++++++++++- .../accounts/cryptographic-keys.md | 16 +++++++- .../transaction-basics/transaction-basics.md | 23 ++++++++++++ .../transaction-basics/transaction-cost.md | 15 ++++++++ .../payment-types/partial-payments.md | 18 +++++++++ 11 files changed, 179 insertions(+), 14 deletions(-) diff --git a/content/concepts/consensus-network/amendments/amendments.md b/content/concepts/consensus-network/amendments/amendments.md index 109e65641d..1035e3b7e7 100644 --- a/content/concepts/consensus-network/amendments/amendments.md +++ b/content/concepts/consensus-network/amendments/amendments.md @@ -232,6 +232,20 @@ TrustSetAuth ``` +## See Also + +- **Concepts:** + - [Known Amendments List](known-amendments.html) + - [Introduction to Consensus](intro-to-consensus.html) +- **Tutorials:** + - [Run rippled as a Validator](run-rippled-as-a-validator.html) + - [Contribute Code to rippled](contribute-code-to-rippled.html) +- **References:** + - [Amendments ledger object](amendments-object.html) + - [EnableAmendment pseudo-transaction][] + - [feature method][] + - [server_info method][] + {% include '_snippets/rippled-api-links.md' %} {% include '_snippets/tx-type-links.md' %} diff --git a/content/concepts/consensus-network/consensus-principles-and-rules.md b/content/concepts/consensus-network/consensus-principles-and-rules.md index 1cd408acef..11e13e7f3d 100644 --- a/content/concepts/consensus-network/consensus-principles-and-rules.md +++ b/content/concepts/consensus-network/consensus-principles-and-rules.md @@ -4,16 +4,16 @@ The XRP Ledger is a universal payment system enabling users to transfer funds ac The XRP Ledger's technology enables near real-time settlement (three to six seconds) and contains a decentralized exchange, where payments automatically use the cheapest currency trade orders available to bridge currencies. -# Background +## Background -## Mechanics +### Mechanics At the core, the XRP Ledger is a shared database that records information such as accounts, balances, and offers to trade assets. Signed instructions called "transactions" cause changes such as creating accounts, making payments, and trading assets. As a cryptographic system, the owners of XRP Ledger accounts are identified by _cryptographic identities_, which correspond to public/private key pairs. Transactions are authorized by cryptographic signatures matching these identities. Every server processes every transaction according to the same deterministic, known rules. Ultimately, the goal is for every server in the network to have a complete copy of the exact same ledger state, without needing a single central authority to arbitrate transactions. -## The Double Spend Problem +### The Double Spend Problem The "double spend" problem is a fundamental challenge to operating any sort of payment system. The problem comes from the requirement that when money is spent in one place, it can't also be spent in another place. More generally, the problem occurs when you have any two transactions such that either one is valid but not both together. @@ -26,9 +26,9 @@ Conventionally, payment systems solve the double spend problem by having a centr Distributed ledger technologies, like the XRP Ledger, have no central authority. They must solve the double spend problem in some other way. -# How Consensus Works +## How Consensus Works -## Simplifying the Problem +### Simplifying the Problem Much of the double spend problem can be solved by well-known rules such as prohibiting an account from spending funds it does not have. In fact, the double spend problem can be reduced to putting transactions in order. @@ -42,7 +42,7 @@ If we could collect transactions into groups and agree on those groupings, we co The XRP Ledger allows multiple conflicting transactions to be in the agreed group. The group of transactions is executed according to deterministic rules, so whichever transaction comes first according to the sorting rules succeeds and whichever conflicting transaction comes second fails. -## Consensus Rules +### Consensus Rules The primary role of consensus is for participants in the process to agree on which transactions are to be processed as a group to resolve the double spend problem. There are four reasons this agreement is easier to achieve than might be expected: @@ -53,7 +53,7 @@ The primary role of consensus is for participants in the process to agree on whi 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. -## Consensus Rounds +### Consensus Rounds A consensus round is an attempt to agree on a group of transactions so they can be processed. A consensus round starts with each participant who wishes to do so taking an initial position. This is the set of valid transactions they have seen. @@ -63,7 +63,7 @@ To prevent consensus from stalling near 50% and to reduce the overlap required f When a participant sees a supermajority that agrees on the set of transactions to next be processed, it declares a consensus to have been reached. -## Consensus Can Fail +### Consensus Can Fail It is not practical to develop a consensus algorithm that never fails to achieve perfect consensus. To understand why, consider how the consensus process finishes. At some point, each participant must declare that a consensus has been reached and that some set of transactions is known to be the result of the process. This declaration commits that participant irrevocably to some particular set of transactions as the result of the consensus process. @@ -75,7 +75,7 @@ Imagine a group of people in a room trying to agree which door they should use t The probability of this kind of failure can be made very low, but it cannot be reduced to zero. The engineering tradeoffs are such that driving this probability down below about one in a thousand makes consensus significantly slower, and less able to tolerate network and endpoint failures. -## How the XRP Ledger Handles Consensus Failure +### How the XRP Ledger Handles Consensus Failure After a consensus round completes, each participant applies the set of transactions that they believe were agreed to. This results in constructing what they believe the next state of the ledger should be. @@ -95,10 +95,27 @@ Case 3 results in the network losing a few seconds in which it could have made f On rare occasions, the network as a whole fails to make forward progress for a few seconds. In exchange, average transaction confirmation times are low. -# Philosophy +## Philosophy One form of reliability is the ability of a system to provide results even under conditions where some components have failed, some participants are malicious, and so on. While this is important, there is another form of reliability that is much more important in cryptographic payment systems — the ability of a system to produce results that can be relied upon. That is, when a system reports a result to us as reliable, we should be able to rely on that result. Real-world systems, however, face operational conditions in which both kinds of reliability can be compromised. These include hardware failures, communication failures, and even dishonest participants. Part of the XRP Ledger's design philosophy is to detect conditions where the reliability of results are impaired and report them, rather than providing results that must not be relied on. The XRP Ledger's consensus algorithm provides a robust alternative to proof of work systems, without consuming computational resources needlessly. Byzantine failures are possible, and do happen, but the consequence is only minor delays. In all cases, the XRP Ledger's consensus algorithm reports results as reliable only when they in fact are. + +## See Also + +- **Concepts:** + - [Introduction to Consensus](intro-to-consensus.html) + - [Consensus Research](consensus-research.html) + - [Ripple Consensus Video](https://www.youtube.com/watch?v=pj1QVb1vlC0) +- **Tutorials:** + - [Reliable Transaction Submission](reliable-transaction-submission.html) + - [Run `rippled` as a Validator](run-rippled-as-a-validator.html) +- **References:** + - [Ledger Format Reference](ledger-data-formats.html) + - [Transaction Format Reference](transaction-formats.html) + - [consensus_info method][] + - [validator_list_sites method][] + - [validators method][] + - [consensus_info method][] diff --git a/content/concepts/consensus-network/consensus.md b/content/concepts/consensus-network/consensus.md index e095075fd0..459a76a7e9 100644 --- a/content/concepts/consensus-network/consensus.md +++ b/content/concepts/consensus-network/consensus.md @@ -176,13 +176,12 @@ Best practices for applications submitting transactions include: - [consensus_info method][] - [validator_list_sites method][] - [validators method][] - - [consensus_info method][] -## End Notes +## Footnotes 1 – Transactions with **tec** result codes 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. To not block other transactions submitted by the same sender around the same time, they increment the sender's account sequence number. They sometimes also perform maintenance such as deleting expired objects or unfunded trade offers. diff --git a/content/concepts/consensus-network/fee-voting.md b/content/concepts/consensus-network/fee-voting.md index 99d104ede8..7c33a020f7 100644 --- a/content/concepts/consensus-network/fee-voting.md +++ b/content/concepts/consensus-network/fee-voting.md @@ -38,3 +38,19 @@ The maximum possible values for the fees are limited by the internal data types | `reference_fee` | 2**64 | (More XRP than has ever existed.) | | `account_reserve` | 2^32 drops | Approximately 4294 XRP | | `owner_reserve` | 2^32 drops | Approximately 4294 XRP | + + +## See Also + +- **Concepts:** + - [Amendments](amendments.html) + - [Transaction Cost](transaction-cost.html) + - [Reserves](reserves.html) + - [Transaction Queue](transaction-queue.html) +- **Tutorials:** + - [Configure `rippled`](configure-rippled.html) +- **References:** + - [fee method][] + - [server_info method][] + - [FeeSettings object](feesettings.html) + - [SetFee pseudo-transaction][] diff --git a/content/concepts/consensus-network/parallel-networks.md b/content/concepts/consensus-network/parallel-networks.md index 6e349b8125..417678cc27 100644 --- a/content/concepts/consensus-network/parallel-networks.md +++ b/content/concepts/consensus-network/parallel-networks.md @@ -11,3 +11,17 @@ Over time, there may also be smaller, temporary test networks for specific purpo ## Parallel Networks and Consensus 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. + +- **Tools:** + - [XRP Test Net Faucet](xrp-test-net-faucet.html) +- **Concepts:** + - [Introduction to Consensus](intro-to-consensus.html) + - [Amendments](amendments.html) +- **Tutorials:** + - [Connect Your `rippled` to the XRP Test Net](connect-your-rippled-to-the-xrp-test-net.html) + - [Use rippled in Stand-Alone Mode](use-stand-alone-mode.html) +- **References:** + - [server_info method][] + - [consensus_info method][] + - [validator_list_sites method][] + - [validators method][] diff --git a/content/concepts/consensus-network/transaction-malleability.md b/content/concepts/consensus-network/transaction-malleability.md index b99acb01e2..aaf6a4d328 100644 --- a/content/concepts/consensus-network/transaction-malleability.md +++ b/content/concepts/consensus-network/transaction-malleability.md @@ -141,6 +141,20 @@ The process to exploit a vulnerable system follows a series of steps similar to Worse, the vulnerable system might construct a new transaction to replace the transaction, picking new `Sequence`, `LastLedgerSequence`, and `Fee` parameters based on the current state of the network, but keeping the rest of the transaction the same as the original. If this new transaction is also malleable, the system could be exploited in the same way an indefinite number of times. +## See Also + +- **Concepts:** + - [Transaction Basics](transaction-basics.html) + - [Finality of Results](finality-of-results.html) +- **Tutorials:** + - [Look Up Transaction Results](look-up-transaction-results.html) + - [Reliable Transaction Submission](reliable-transaction-submission.html) +- **References:** + - [Basic Data Types - Hashes](basic-data-types.html#hashes) + - [Transaction Common Fields - Global Flags](transaction-common-fields.html#global-flags) + - [Transaction Results](transaction-results.html) + - [Serialization Format](serialization.html) + {% include '_snippets/rippled-api-links.md' %} {% include '_snippets/tx-type-links.md' %} diff --git a/content/concepts/issued-currencies/issued-currencies-overview.md b/content/concepts/issued-currencies/issued-currencies-overview.md index d14df685c4..e9d00b2ac5 100644 --- a/content/concepts/issued-currencies/issued-currencies-overview.md +++ b/content/concepts/issued-currencies/issued-currencies-overview.md @@ -24,4 +24,25 @@ Addresses can also [freeze](freezes.html) issued currencies, which may be useful Issued currencies are designed to be able to represent any kind of currency or asset, including those with very small or very large nominal values. For detailed technical information on the types of currency codes and the numeric limits of issued currency representation, see the [currency format reference](currency-formats.html). -{% include '_snippets/tx-type-links.md' %} +## See Also + +- **Concepts:** + - [XRP](xrp.html) + - [Cross-Currency Payments](cross-currency-payments.html) + - [Decentralized Exchange](decentralized-exchange.html) +- **Tutorials:** + - [Become an XRP Ledger Gateway](become-an-xrp-ledger-gateway.html) + - [Look Up Transaction Results](look-up-transaction-results.html) + - [Use Specialized Payment Types](use-specialized-payment-types.html) +- **References:** + - [Payment transaction][] + - [TrustSet transaction][] + - [RippleState object](ripplestate.html) + - [account_lines method][] + - [account_currencies method][] + - [gateway_balances method][] + + +{% include '_snippets/rippled-api-links.md' %} +{% include '_snippets/tx-type-links.md' %} +{% include '_snippets/rippled_versions.md' %} diff --git a/content/concepts/payment-system-basics/accounts/cryptographic-keys.md b/content/concepts/payment-system-basics/accounts/cryptographic-keys.md index 9a33bd06c3..a511e2c38d 100644 --- a/content/concepts/payment-system-basics/accounts/cryptographic-keys.md +++ b/content/concepts/payment-system-basics/accounts/cryptographic-keys.md @@ -113,7 +113,21 @@ The supported types of key pairs can be used interchangeably throughout the XRP ### Future Algorithms -In the future, Ripple expects to add new cryptographic signing algorithms to the XRP Ledger to keep up with developments in cryptography. For example, if it seems that quantum computers using [Shor's algorithm](https://en.wikipedia.org/wiki/Shor's_algorithm) (or something similar) will soon be practical enough to break elliptic curve cryptography, Ripple can add a cryptographic signing algorithm that isn't easily broken. As of early 2018, such "quantum-resistant" signing algorithms are relatively impractical and quantum computers are even more impractical, so Ripple has no immediate plans to add any specific algorithms. +In the future, it is likely that the XRP Ledger will need new cryptographic signing algorithms to keep up with developments in cryptography. For example, if quantum computers using [Shor's algorithm](https://en.wikipedia.org/wiki/Shor's_algorithm) (or something similar) will soon be practical enough to break elliptic curve cryptography, XRP Ledger developers can add a cryptographic signing algorithm that isn't easily broken. As of mid 2019, there's no clear first choice "quantum-resistant" signing algorithm and quantum computers are not yet practical enough to be a threat, so there are no immediate plans to add any specific algorithms. + + +## See Also + +- **Concepts:** + - [Issuing and Operational Addresses](issuing-and-operational-addresses.html) +- **Tutorials:** + - [Assign a Regular Key Pair](assign-a-regular-key-pair.html) + - [Change or Remove a Regular Key Pair](change-or-remove-a-regular-key-pair.html) +- **References:** + - [SetRegularKey transaction][] + - [AccountRoot ledger object](accountroot.html) + - [wallet_propose method][] + - [account_info method][] {% include '_snippets/rippled-api-links.md' %} 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 d8d3df69aa..84ed840e5c 100644 --- a/content/concepts/payment-system-basics/transaction-basics/transaction-basics.md +++ b/content/concepts/payment-system-basics/transaction-basics/transaction-basics.md @@ -189,6 +189,29 @@ Example response from the `tx` command: } ``` +## See Also + + +- **Concepts:** + - [Payment Types](payment-types.html) + - [Consensus Network](consensus-network.html) +- **Tutorials:** + - [Set Up Secure Signing](set-up-secure-signing.html) + - [Send XRP](send-xrp.html) + - [Look Up Transaction Results](look-up-transaction-results.html) + - [Monitor Incoming Payments with WebSocket](monitor-incoming-payments-with-websocket.html) + - [Cancel or Skip a Transaction](cancel-or-skip-a-transaction.html) + - [Reliable Transaction Submission](reliable-transaction-submission.html) +- **References:** + - [Transaction Common Fields](transaction-common-fields.html) + - [Transaction Types](transaction-types.html) + - [Transaction Metadata](transaction-metadata.html) + - [account_tx method][] + - [tx method][] + - [submit method][] + - [submit_multisigned method][] + + {% include '_snippets/rippled-api-links.md' %} {% include '_snippets/tx-type-links.md' %} diff --git a/content/concepts/payment-system-basics/transaction-basics/transaction-cost.md b/content/concepts/payment-system-basics/transaction-basics/transaction-cost.md index 96aaaf4618..c874579cf5 100644 --- a/content/concepts/payment-system-basics/transaction-basics/transaction-cost.md +++ b/content/concepts/payment-system-basics/transaction-basics/transaction-cost.md @@ -151,6 +151,21 @@ When the [FeeEscalation amendment][] is enabled, `rippled` prioritizes key reset The XRP Ledger has a mechanism for changing the minimum transaction cost to account for long-term changes in the value of XRP. Any changes have to be approved by the consensus process. See [Fee Voting](fee-voting.html) for more information. + +## See Also + +- **Concepts:** + - [Reserves](reserves.html) + - [Fee Voting](fee-voting.html) + - [Transaction Queue](transaction-queue.html) +- **Tutorials:** + - [Reliable Transaction Submission](reliable-transaction-submission.html) +- **References:** + - [fee method][] + - [server_info method][] + - [FeeSettings object](feesettings.html) + - [SetFee pseudo-transaction][] + {% include '_snippets/rippled-api-links.md' %} {% include '_snippets/tx-type-links.md' %} diff --git a/content/concepts/payment-types/partial-payments.md b/content/concepts/payment-types/partial-payments.md index 7cb67c049c..a90547f503 100644 --- a/content/concepts/payment-types/partial-payments.md +++ b/content/concepts/payment-types/partial-payments.md @@ -105,6 +105,24 @@ Using [the `delivered_amount` field](#the-delivered-amount-field) when processin - Add additional sanity checks to your business logic for processing withdrawals. Never process a withdrawal if the total balance you hold in the XRP Ledger does not match your expected assets and obligations. - Follow "Know Your Customer" guidelines and strictly verify your customers' identities. You may be able to recognize and block malicious users in advance, or pursue legal action against a malicious actor who exploits your system. + +## See Also + +- **Tools:** + - [Transaction Sender](tx-sender.html) +- **Concepts:** + - [Transaction Basics](transaction-basics.html) +- **Tutorials:** + - [Look Up Transaction Results](look-up-transaction-results.html) + - [Monitor Incoming Payments with WebSocket](monitor-incoming-payments-with-websocket.html) + - [Use Specialized Payment Types](use-specialized-payment-types.html) + - [List XRP as an Exchange](list-xrp-as-an-exchange.html) +- **References:** + - [Payment transaction][] + - [Transaction Metadata](transaction-metadata.html) + - [account_tx method][] + - [tx method][] + {% include '_snippets/rippled-api-links.md' %} {% include '_snippets/tx-type-links.md' %}