mirror of
https://github.com/XRPLF/xrpl-dev-portal.git
synced 2025-11-24 13:45:49 +00:00
Support theme-aware diagrams:
- SVG diagrams can adapt to the visual theme of the site through CSS. - Use the include_svg filter to include a diagram that adapts to the theme. - The styles/_diagrams.scss file controls the color mappings for theme-aware digrams. - Theme-aware diagrams are limited to specific colors and diagram styles. Use UMLet or Google Draw and confirm that the diagram is still legible when you build it. - This commit updates existing diagrams in most places to be theme-aware.
This commit is contained in:
mDuo13
@@ -19,13 +19,13 @@ The peer-to-peer XRP Ledger network provides a worldwide, shared ledger, which g
|
||||
|
||||
For a full, technical description of which data is included in a ledger version, see the [Ledger Format Reference](ledger-data-formats.html).
|
||||
|
||||
[](img/anatomy-of-a-ledger-complete.png)
|
||||
{{ include_svg("img/anatomy-of-a-ledger-complete.svg", "Figure 1: XRP Ledger Elements") }}
|
||||
|
||||
_Figure 1: XRP Ledger Elements_
|
||||
|
||||
The XRP Ledger has a new ledger version every several seconds. When the network agrees on the contents of a ledger version, that ledger version is _validated_, and its contents can never change. The validated ledger versions that preceded it form the ledger history. Even the most recent validated ledger is part of history, as it represents the state of the network as of a short time ago. In the present, the network is evaluating transactions which may be applied and finalized in the next ledger version. While this evaluation is happening, the network has candidate ledger versions that are not yet validated.
|
||||
|
||||
[](img/ledger-history.png)
|
||||
{{ include_svg("img/ledger-history.svg", "Figure 2: XRP Ledger History")}}
|
||||
|
||||
_Figure 2: XRP Ledger History_
|
||||
|
||||
@@ -37,7 +37,7 @@ User level changes to the ledger are the results of transactions. Examples of [t
|
||||
|
||||
Each ledger version also contains a set of transactions and metadata about those transactions. The transactions it includes are only the ones that have been applied to the previous ledger version to create the new ledger version. The metadata records the exact effects of the transaction on the ledger's state data.
|
||||
|
||||
[](img/ledger-changes.png)
|
||||
{{ include_svg("img/ledger-changes.svg", "Figure 3: Transactions Applied to Ledger Version")}}
|
||||
|
||||
_Figure 3: Transactions Applied to Ledger Version_
|
||||
|
||||
@@ -57,7 +57,7 @@ Important: Some [`rippled` APIs](rippled-api.html) provide provisional results,
|
||||
|
||||
The peer-to-peer XRP Ledger network consists of many independent XRP Ledger servers (typically running [`rippled`](the-rippled-server.html)) that accept and process transactions. Client applications sign and send transactions to XRP Ledger servers, which relay these candidate transactions throughout the network for processing. Examples of client applications include mobile and web wallets, gateways to financial institutions, and electronic trading platforms.
|
||||
|
||||
[](img/xrp-ledger-network.png)
|
||||
{{ include_svg("img/xrp-ledger-network.svg", "Figure 4: Participants in the XRP Ledger Protocol") }}
|
||||
|
||||
_Figure 4: Participants in the XRP Ledger Protocol_
|
||||
|
||||
@@ -71,7 +71,7 @@ The servers on the network share information about candidate transactions. Throu
|
||||
|
||||
During consensus, each server evaluates proposals from a specific set of servers, known as that server's trusted validators, or _Unique Node List (UNL)_.<a href="#footnote_5" id="from_footnote_5"><sup>5</sup></a> Trusted validators represent a subset of the network which, when taken collectively, is "trusted" not to collude in an attempt to defraud the server evaluating the proposals. This definition of "trust" does not require that each individual chosen validator is trusted. Rather, validators are chosen based on the expectation they will not collude in a coordinated effort to falsify data relayed to the network <a href="#footnote_6" id="from_footnote_6"><sup>6</sup></a>. <!-- STYLE_OVERRIDE: will -->
|
||||
|
||||
[](img/consensus-rounds.png)
|
||||
{{ include_svg("img/consensus-rounds.svg", "Figure 5: Validators Propose and Revise Transaction Sets") }}
|
||||
|
||||
_Figure 5: Validators Propose and Revise Transaction Sets — At the start of consensus, validators may have different sets of transactions. In later rounds, servers modify their proposals to match what their trusted validators proposed. This process determines which transactions they should apply to the ledger version currently being discussed, and which they should postpone for later ledger versions._
|
||||
|
||||
@@ -110,8 +110,7 @@ When the consensus process completes, each server independently computes a new l
|
||||
|
||||
5. Calculate the identifying hash of the new ledger version.
|
||||
|
||||
|
||||
[](img/consensus-calculate-validation.png)
|
||||
{{ include_svg("img/consensus-calculate-validation.svg", "Figure 7: An XRP Ledger Server Calculates a Ledger Validation") }}
|
||||
|
||||
_Figure 7: An XRP Ledger Server Calculates a Ledger Validation — Each server applies agreed-upon transactions to the previous validated ledger. Validators send their results to the entire network._
|
||||
|
||||
@@ -119,7 +118,7 @@ _Figure 7: An XRP Ledger Server Calculates a Ledger Validation — Each server a
|
||||
|
||||
Validators each relay their results in the form of a signed message containing the hash of the ledger version they calculated. These messages, called _validations_, allow each server to compare the ledger it computed with those of its peers.
|
||||
|
||||
[](img/consensus-declare-validation.png)
|
||||
{{ include_svg("img/consensus-declare-validation.svg", "Figure 8: Ledger is Validated When Supermajority of Peers Calculate the Same Result Result") }}
|
||||
|
||||
_Figure 8: Ledger is Validated When Supermajority of Peers Calculate the Same Result — Each server compares its calculated ledger with the hashes received from its chosen validators. If not in agreement, the server must recalculate or retrieve the correct ledger._
|
||||
|
||||
|
||||
@@ -6,7 +6,7 @@ The `rippled` server uses a transaction queue to help enforce the [open ledger c
|
||||
|
||||
The transaction queue plays an important role in selecting the transactions that are included or excluded from a given ledger version in the consensus process. The following steps describe how the transaction queue relates to the [consensus process](consensus.html).
|
||||
|
||||
[](img/consensus-with-queue.png)
|
||||
{{ include_svg("img/consensus-with-queue.svg", "Transaction queue and consensus diagram") }}
|
||||
|
||||
1. **Consensus Round 1** - Each validator proposes a set of transactions to be included in the next ledger version. Each also keeps a queue of candidate transactions not currently proposed.
|
||||
|
||||
|
||||
@@ -30,8 +30,7 @@ The XRP Ledger processes transactions in blocks called "ledger versions", or "le
|
||||
- The set of transactions that have been applied to the previous ledger to result in this one.
|
||||
- Metadata about the current ledger version, such as its ledger index, a [cryptographic hash](https://en.wikipedia.org/wiki/Cryptographic_hash_function) that uniquely identifies its contents, and information about the parent ledger that was used as a basis for building this one.
|
||||
|
||||
[](img/anatomy-of-a-ledger-simplified.png)
|
||||
<!--{# Diagram source: https://docs.google.com/presentation/d/1mg2jZQwgfLCIhOU8Mr5aOiYpIgbIgk3ymBoDb2hh7_s/ #}-->
|
||||
{{ include_svg("img/anatomy-of-a-ledger-simplified.svg", "Figure 1: Anatomy of a ledger version, which includes transactions, state, and metadata") }}
|
||||
|
||||
Each ledger version is numbered with a _ledger index_ and builds on a previous ledger version whose index is one less, going all the way back to a starting point called the _genesis ledger_ with ledger index 1.[¹](#footnote-1) Like Bitcoin and other blockchain technologies, this forms a public history of all transactions and their results. Unlike many blockchain technologies, each new "block" in the XRP Ledger contains the entirety of the current state, so you don't need to collect the entire history to know what's happening now.[²](#footnote-2)
|
||||
|
||||
@@ -44,7 +43,7 @@ The core principle behind the XRP Ledger's consensus mechanism is that a little
|
||||
|
||||
As the network progresses, each server listens to its trusted validators[³](#footnote-3); as long as a large enough percentage of them agree that a set of transactions should occur and that a given ledger is the result, the server declares a consensus. If they don't agree, validators modify their proposals to more closely match the other validators they trust, repeating the process in several rounds until they reach a consensus.
|
||||
|
||||
[](img/consensus-rounds.png)
|
||||
{{ include_svg("img/consensus-rounds.svg", "Figure 2: Consensus rounds. Validators revise their proposals to match other validators they trust") }}
|
||||
|
||||
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.
|
||||
|
||||
|
||||
@@ -4,7 +4,7 @@ The XRP Ledger is home to a deep, layered ecosystem of software projects powerin
|
||||
|
||||
## Stack Levels
|
||||
|
||||
[](img/ecosystem.png)
|
||||
{{ include_svg("img/ecosystem.svg", "Ecosystem diagram with the four layers: XRP Ledger peer-to-peer network on the bottom, Programming Libraries above that, Middleware next, and Apps and Services at the top") }}
|
||||
|
||||
- The [basis of the XRP Ledger](#rippled-the-core-server) is a peer-to-peer network of always-on servers sharing transactions, engaging in the [consensus process](consensus.html) and processing [transactions](transaction-basics.html). Everything else in the XRP Ledger ecosystem is ultimately built on top of this peer-to-peer network, directly or indirectly.
|
||||
|
||||
|
||||
@@ -7,7 +7,7 @@
|
||||
|
||||
All non-XRP balances in the XRP Ledger are _issued currencies_ which are tied to accounting relationships between two XRP Ledger addresses. When a financial institution uses Ripple's recommended separation of roles, funds relating to that institution tend to flow in a cycle.
|
||||
|
||||
[](img/funds_flow_diagram.png)
|
||||
{{ include_svg("img/issued-currency-funds-flow.svg", "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.")}}
|
||||
|
||||
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.
|
||||
|
||||
|
||||
@@ -19,7 +19,7 @@ In the case of a currency exchange step, the path step specifies which currency
|
||||
|
||||
In both types of steps, each intermediate address gains and loses approximately equal value: either a balance ripples from a trust line to another trust line in the same currency, or they exchange currencies according to a previously-placed order. In some cases, the amounts gained and lost may not be exactly equivalent, due to [transfer fees](transfer-fees.html), trust line quality, or rounding.
|
||||
|
||||
[](img/paths-examples.png)
|
||||
{{ include_svg("img/paths-examples.svg", "Diagram of three example paths") }}
|
||||
|
||||
|
||||
|
||||
@@ -59,7 +59,8 @@ The default path could be any of the following:
|
||||
* For cross-currency transactions, the default path uses the order book between the source currency (as specified in the `SendMax` field) and the destination currency (as specified in the `Amount` field).
|
||||
|
||||
The following diagram enumerates all possible default paths:
|
||||
[](img/paths-default_paths.png)
|
||||
|
||||
{{ include_svg("img/default-paths.svg", "Diagram of default paths") }}
|
||||
|
||||
You can use the [`tfNoDirectRipple` flag](payment.html#payment-flags) to disable the default path. In this case, the transaction can only execute using the paths explicitly included in the transaction. Traders can use this option to take arbitrage opportunities.
|
||||
|
||||
|
||||
@@ -12,11 +12,11 @@ For non-issuing accounts, rippling can be undesirable because it lets other user
|
||||
|
||||
"Rippling" occurs when more than one trust line is adjusted to make a payment. For example, if Alice owes Charlie money, and Alice also owes Bob money, then you could represent that in the XRP Ledger with trust lines like so:
|
||||
|
||||
|
||||
{{ include_svg("img/noripple-01.svg", "Charlie --($10)-- Alice -- ($20) -- Bob") }}
|
||||
|
||||
If Bob wants to pay $3 to Charlie, then he could say, "Alice, take $3 of the money you owe me, and pay it to Charlie." Alice transfers some of the debt from Bob to Charlie. In the end, the trust lines work out like so:
|
||||
|
||||
|
||||
{{ include_svg("img/noripple-02.svg", "Charlie --($13)-- Alice --($17)-- Bob") }}
|
||||
|
||||
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.
|
||||
|
||||
@@ -30,17 +30,17 @@ An account can disable No Ripple on a single trust line, which can allow ripplin
|
||||
|
||||
For example, imagine Emily has money issued by two different financial institutions, like so
|
||||
|
||||
|
||||
{{ include_svg("img/noripple-03.svg", "Charlie --($10)-- Institution A --($1)-- Emily --($100)-- Institution B --($2)-- Daniel") }}
|
||||
|
||||
Now Charlie can pay Daniel by rippling through Emily's address. For example, if Charlie pays Daniel $10:
|
||||
|
||||
|
||||
{{ include_svg("img/noripple-04.svg", "Charlie --($0)-- Institution A --($11)-- Emily --($90)-- Institution B --($12)-- Daniel") }}
|
||||
|
||||
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:
|
||||
|
||||
|
||||
{{ include_svg("img/noripple-05.svg", "Charlie --($10)-- Institution A --($1, No Ripple)-- Emily --($100, No Ripple)-- Institution B --($2)-- Daniel") }}
|
||||
|
||||
Now the above scenario, where Charlie pays Daniel while rippling through Emily's address, is no longer possible.
|
||||
|
||||
@@ -48,7 +48,7 @@ Now the above scenario, where Charlie pays Daniel while rippling through Emily's
|
||||
|
||||
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.
|
||||
|
||||
|
||||
{{ include_svg("img/noripple-06.svg", "Diagram demonstrating that No Ripple has to be set on both trust lines by the same address to do anything") }}
|
||||
|
||||
|
||||
## The Default Ripple Flag
|
||||
|
||||
@@ -11,15 +11,21 @@ For example, ACME Bank might set the transfer fee to 1%. For the recipient of a
|
||||
|
||||
The following diagram shows an XRP Ledger payment of 2 EUR.ACME from Alice to Charlie with a transfer fee of 1%:
|
||||
|
||||
|
||||
{{ include_svg("img/transfer-fees.svg", "Alice sends 2,02€, Charlie receives 2,00€, and ACME owes 0,02€ less in the XRP Ledger") }}
|
||||
|
||||
In accounting terms, Alice's, ACME's, and Charlie's balance sheets may have changed like this:
|
||||
|
||||
{{ include_svg("img/transfer-fees-balance-sheets.svg", "Alice's assets are down 2,02€, Charlie's are up 2,00€, and ACME's liabilities are down 0,02€") }}
|
||||
|
||||
|
||||
|
||||
## Transfer Fees in Payment Paths
|
||||
|
||||
<!--{# TODO: Update this for OnwerPaysFee amendment when that gets added #}-->
|
||||
<!--{# TODO: Update this for OwnerPaysFee amendment when that gets added #}-->
|
||||
|
||||
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:
|
||||
|
||||
|
||||
{{ include_svg("img/transfer-fees-in-paths.svg", "Diagram of cross-currency payment with transfer fees") }}
|
||||
|
||||
In this scenario, Salazar (the sender) holds EUR issued by ACME, and wants to deliver 100 USD issued by WayGate to Rosa (the recipient). FXMaker is a currency trader with the best offer in the order book, at a rate of 1 USD.WayGate for every 0.9 EUR.ACME. If there were no transfer fees, Salazar could deliver 100 USD to Rosa by sending 90 EUR. However, ACME has a transfer fee of 1% and WayGate has a transfer fee of 0.2%. This means:
|
||||
|
||||
|
||||
@@ -110,7 +110,7 @@ XRP Ledger addresses are encoded using [base58][] with the _dictionary_ `rpshnaf
|
||||
|
||||
The following diagram shows the relationship between keys and addresses:
|
||||
|
||||
[](img/address-encoding.png)
|
||||
{{ include_svg("img/address-encoding.svg", "Master Public Key + Type Prefix → Account ID + Checksum → Address") }}
|
||||
|
||||
The formula for calculating an XRP Ledger address from a public key is as follows. For the complete example code, see [`encode_address.js`](https://github.com/ripple/ripple-dev-portal/blob/master/content/_code-samples/address_encoding/encode_address.js). For the process of deriving a public key from a passphrase or seed value, see [Key Derivation](cryptographic-keys.html#key-derivation).
|
||||
|
||||
|
||||
@@ -156,7 +156,7 @@ The key derivation processes described here are implemented in multiple places a
|
||||
### Ed25519 Key Derivation
|
||||
[[Source]](https://github.com/ripple/rippled/blob/fc7ecd672a3b9748bfea52ce65996e324553c05f/src/ripple/protocol/impl/SecretKey.cpp#L203 "Source")
|
||||
|
||||
[](img/key-derivation-ed25519.png)
|
||||
{{ include_svg("img/key-derivation-ed25519.svg", "Passphrase → Seed → Secret Key → Prefix + Public Key") }}
|
||||
|
||||
1. Calculate the [SHA-512Half][] of the seed value. The result is the 32-byte secret key.
|
||||
|
||||
@@ -177,7 +177,7 @@ The key derivation processes described here are implemented in multiple places a
|
||||
### secp256k1 Key Derivation
|
||||
[[Source]](https://github.com/ripple/rippled/blob/develop/src/ripple/crypto/impl/GenerateDeterministicKey.cpp "Source")
|
||||
|
||||
[](img/key-derivation-secp256k1.png)
|
||||
{{ include_svg("img/key-derivation-secp256k1.svg", "Passphrase → Seed → Root Key Pair → Intermediate Key Pair → Master Key Pair") }}
|
||||
|
||||
Key derivation for secp256k1 XRP Ledger account keys involves more steps than Ed25519 key derivation for a couple reasons:
|
||||
|
||||
|
||||
@@ -2,13 +2,13 @@
|
||||
|
||||
The XRP Ledger is a shared, global ledger that is open to all. Individual participants can trust the integrity of the ledger without having to trust any single institution to manage it. The `rippled` server software accomplishes this by managing a ledger database that can only be updated according to very specific rules. Each instance of `rippled` keeps a full copy of the ledger, and the peer-to-peer network of `rippled` servers distributes candidate transactions among themselves. The consensus process determines which transactions get applied to each new version of the ledger. See also: [The Consensus Process](consensus.html).
|
||||
|
||||
|
||||
{{ include_svg("img/ledger-changes.svg", "Diagram: Each ledger is the result of applying transactions to the previous ledger version.") }}
|
||||
|
||||
The shared global ledger is actually a series of individual ledgers, or ledger versions, which `rippled` keeps in its internal database. Every ledger version has a [Ledger Index][] which identifies the order in which ledgers occur. Each closed ledger version also has an identifying hash value, which uniquely identifies the contents of that ledger. At any given time, a `rippled` instance has an in-progress "current" open ledger, plus some number of closed ledgers that have not yet been approved by consensus, and any number of historical ledgers that have been validated by consensus. Only the validated ledgers are certain to be correct and immutable.
|
||||
|
||||
A single ledger version consists of several parts:
|
||||
|
||||
|
||||
{{ include_svg("img/anatomy-of-a-ledger-simplified.svg", "Diagram: A ledger has transactions, a state tree, and a header with the close time and validation info") }}
|
||||
|
||||
* A **header** - The [Ledger Index][], hashes of its other contents, and other metadata.
|
||||
* A **transaction tree** - The [transactions](transaction-formats.html) that were applied to the previous ledger to make this one. Transactions are the _only_ way to change the ledger.
|
||||
|
||||
@@ -22,7 +22,7 @@ Payment Channels do not intrinsically specify anything about what you can buy an
|
||||
|
||||
The following diagram summarizes the lifecycle of a payment channel:
|
||||
|
||||
[](img/paychan-flow.png)
|
||||
{{ include_svg("img/paychan-flow.svg", "Payment Channel Flow Diagram") }}
|
||||
|
||||
|
||||
## See Also
|
||||
|
||||
@@ -70,7 +70,7 @@ The following settings relate to online deletion:
|
||||
|
||||
The following diagram shows the relationship between `online_delete` and `ledger_history` settings:
|
||||
|
||||
|
||||
{{ include_svg("img/online_delete-vs-ledger_history.svg", "Ledgers older than `online_delete` are automatically deleted. Ledgers newer than `ledger_history` are backfilled. Ledgers in between are kept if available but not backfilled") }}
|
||||
|
||||
- **`advisory_delete`** - If enabled, online deletion is not scheduled automatically. Instead, an administrator must manually trigger online deletion. Use the value `0` for disabled or `1` for enabled.
|
||||
|
||||
@@ -84,7 +84,7 @@ The following settings relate to online deletion:
|
||||
|
||||
The following diagram shows how `fetch_depth` works:
|
||||
|
||||
|
||||
{{ include_svg("img/fetch_depth.svg", "Ledger versions older than fetch_depth are not served to peers") }}
|
||||
|
||||
For estimates of how much disk space is required to store different amounts of history, see [Capacity Planning](capacity-planning.html#disk-space).
|
||||
|
||||
@@ -105,7 +105,7 @@ Online deletion works by creating two databases: at any given time, there is an
|
||||
|
||||
When it comes time for online deletion, the server first walks through the oldest ledger version to keep, and copies all objects in that ledger version from the read-only "old" database into the "current" database. This guarantees that the "current" database now contains all objects used in the chosen ledger version and all newer versions. Then, the server deletes the "old" database, and changes the existing "current" database to become "old" and read-only. The server starts a new "current" database to contain any newer changes after this point.
|
||||
|
||||
|
||||
{{ include_svg('img/online-deletion-process.svg', "Diagram showing how online deletion uses two databases") }}
|
||||
|
||||
## See Also
|
||||
|
||||
|
||||
Reference in New Issue
Block a user