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

Re-level non-docs content to top of repo and rename content→docs

Browse Source
This commit is contained in:
mDuo13
2024-01-31 16:24:01 -08:00
parent f841ef173c
commit c10beb85c2
2907 changed files with 1 additions and 1 deletions
Download Patch File Download Diff File Expand all files Collapse all files

88
docs/concepts/networks-and-servers/amendments.md Normal file
View File

@@ -0,0 +1,88 @@
---
html: amendments.html
parent: networks-and-servers.html
seo:
description: Amendments represent new features or other changes to transaction processing. Validators coordinate through consensus to apply these upgrades to the XRP Ledger in an orderly fashion.
labels:
- Blockchain
---
# Amendments
Amendments represent new features or other changes to transaction processing.
The amendment system uses the consensus process to approve any changes that affect transaction processing on the XRP Ledger. Fully-functional, transaction process changes are introduced as amendments; validators then vote on these changes. If an amendment receives more than 80% support for two weeks, the amendment passes and the change applies permanently to all subsequent ledger versions. Disabling a passed amendment requires a new amendment to do so.
**Note:** Bug fixes that change transaction processes also require amendments.
<!-- TODO: Move this to an amendment tutorial.
Every amendment has a unique identifying hex value and a short name. The short name is for readability only; servers can use different names to describe the same amendement ID, and the names aren't guaranteed to be unique. The amendment ID should be the SHA-512Half hash of the amendment's short name.
-->
## Amendment Process
The [Contributing Code to the XRP Ledger](../../resources/contribute-code/contribute-code.md) topic walks through the workflow to develop an amendment from an idea to activation on the XRP Ledger.
After the code for an amendment is built into a software release, the process to enable it happens within the XRP Ledger network, which checks the status of amendments every _flag_ ledger (typically about 15 minutes apart).
Every 256th ledger is called a **flag** ledger. The flag ledger doesn't have special contents, but the amendment process happens around it.
1. **Flag Ledger -1:** When `rippled` validators send validation messages, they also submit their amendment votes.
2. **Flag Ledger:** Servers interpret the votes from trusted validators.
3. **Flag Ledger +1:** Servers insert an `EnableAmendment` pseudo-transaction and flag based on what they think happened:
* The `tfGotMajority` flag means the amendment has more than 80% support.
* The `tfLostMajority` flag means support for the amendment has decreased to 80% or less.
* No flag means the amendment is enabled.
**Note:** It's possible for an amendment to lose 80% support on the same ledger it reaches the required two-week period to be enabled. In these cases, an `EnableAmendment` pseudo-transactions is added for both scenarios, but the amendment is ultimately enabled.
4. **Flag Ledger +2:** Enabled amendments apply to transactions on this ledger onwards.
## Amendment Voting
Each version of `rippled` is compiled with a list of [known amendments](../../resources/known-amendments.md) and the code to implement those amendments. Operators of `rippled` validators configure their servers to vote on each amendment and can change it at any time. If the operator doesn't choose a vote, the server uses a default vote defined by the source code.
**Note:** The default vote can change between software releases. {% badge href="https://github.com/XRPLF/rippled/releases/tag/1.8.1" %}Updated in: rippled 1.8.1{% /badge %}
Amendments must maintain two weeks of support from more than 80% of trusted validators to be enabled. If support drops below 80%, the amendment is temporarily rejected, and the two week period restarts. Amendments can gain and lose a majority any number of times before they become permanently enabled.
Amendments that have had their source code removed without being enabled are considered **Vetoed** by the network.
## Amendment Blocked Servers
<a id="amendment-blocked"></a>
Amendment blocking is a security feature to protect the accuracy of XRP Ledger data. When an amendment is enabled, servers running earlier versions of `rippled` without the amendment's source code no longer understand the rules of the network. Rather than guess and misinterpret ledger data, these servers become **amendment blocked** and can't:
* Determine the validity of a ledger.
* Submit or process transactions.
* Participate in the consensus process.
* Vote on future amendments.
The voting configuration of a `rippled` server has no impact on it becoming amendment blocked. A `rippled` server always follows the amendments enabled by the rest of the network, so blockages are based solely on having the code to understand rule changes. This means you can also become amendment blocked if you connect your server to a parallel network with different amendments enabled. For example, the XRP Ledger Devnet typically has experimental amendments enabled. If you are using the latest production release, your server likely won't have the code for those experimental amendments.
You can unblock amendment blocked servers by upgrading to the newest version of `rippled`.
### Amendment Blocked Clio Servers
The Clio server can become amendment blocked if it encounters an unknown field type while loading ledger data. This occurs if the field is newer than the `libxrpl` dependency that was used when building Clio. To unblock your Clio server, upgrade to a newer Clio release that was built with a compatible `libxrpl`.
## Retiring Amendments
When amendments are enabled, the source code for pre-amendment behaviors remain in `rippled`. While there are use-cases for keeping old code, such as reconstructing ledger outcomes for verification, tracking amendments and legacy code adds complexity over time.
The [XRP Ledger Standard 11d](https://github.com/XRPLF/XRPL-Standards/discussions/19) defines a process for retiring old amendments and associated pre-amendment code. After an amendment has been enabled on the Mainnet for two years, it can be retired. Retiring an amendment makes it part of the core protocol unconditionally; it's no longer tracked or treated as an amendment, and all pre-amendment code is removed.
## See Also
- **Concepts:**
- [Consensus](../consensus-protocol/index.md)
- **Tutorials:**
- [Run rippled as a Validator](../../infrastructure/configuration/server-modes/run-rippled-as-a-validator.md)
- [Configure Amendment Voting](../../infrastructure/configuration/configure-amendment-voting.md)
- [Contribute Code to the XRP Ledger](../../resources/contribute-code/contribute-code.md)
- **References:**
- [Known Amendments](../../resources/known-amendments.md)
{% raw-partial file="/_snippets/common-links.md" /%}

29
docs/concepts/networks-and-servers/clustering.md Normal file
View File

@@ -0,0 +1,29 @@
---
html: clustering.html
parent: networks-and-servers.html
seo:
description: Run rippled servers in a cluster to share the load of cryptography between them.
labels:
- Core Server
---
# Clustering
If you are running multiple `rippled` servers in a single datacenter, you can configure those servers into a cluster to maximize efficiency. Running your `rippled` servers in a cluster provides the following benefits:
- Clustered `rippled` servers share the work of cryptography. If one server has verified the authenticity of a message, the other servers in the cluster trust it and do not re-verify.
- Clustered servers share information about peers and API clients that are misbehaving or abusing the network. This makes it harder to attack all servers of the cluster at once.
- Clustered servers always propagate transactions throughout the cluster, even if the transaction does not meet the current load-based transaction fee on some of them.
If you are running a validator as a [private peer](peer-protocol.md#private-peers), Ripple recommends using a cluster of `rippled` servers as proxy servers.
## See Also
- **Tutorials:**
- [Cluster `rippled` Servers](../../infrastructure/configuration/peering/cluster-rippled-servers.md)
- [Run rippled as a Validator](../../infrastructure/configuration/server-modes/run-rippled-as-a-validator.md)
- **References:**
- [peers method][]
- [connect method][]
- [Peer Crawler](../../references/http-websocket-apis/peer-port-methods/peer-crawler.md)
{% raw-partial file="/_snippets/common-links.md" /%}

41
docs/concepts/networks-and-servers/index.md Normal file
View File

@@ -0,0 +1,41 @@
---
html: networks-and-servers.html
parent: concepts.html
seo:
description: rippled is the core peer-to-peer server that manages the XRP Ledger.
metadata:
indexPage: true
---
# Networks and Servers
There are two main types of server software that power the XRP Ledger:
- The core server, `rippled`, runs the the peer-to-peer network which processes transactions and reaches a consensus on their outcome.
- The API server, [Clio](the-clio-server.md), provides a powerful interface for fetching or querying data from the ledger.
Anyone can run instances of one or both of these types of servers based on their needs.
## Reasons to Run Your Own Server
For lighter use cases and individual servers, you can often rely on free [public servers][]. However, the more serious your use of the XRP Ledger becomes, the more important it becomes to have your own infrastructure.
There are lots of reasons you might want to run your own servers, but most of them can be summarized as: you can trust your own server, you have control over its workload, and you're not at the mercy of others to decide when and how you can access it. Of course, you must practice good network security to protect your server from malicious hackers.
You need to trust the server you use. If you connect to a malicious server, there are many ways that it can take advantage of you or cause you to lose money. For example:
* A malicious server could report that you were paid when no such payment was made.
* It could selectively show or hide payment paths and currency exchange offers to guarantee its own profit while not providing you the best deal.
* If you sent it your address's secret key, it could make arbitrary transactions on your behalf, and even transfer or destroy all the money your address holds.
Additionally, running your own server gives you [admin access](../../tutorials/get-started/get-started-using-http-websocket-apis.md#admin-access), 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 the server 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 network only accessible to the outside world through the stock server. This makes it more difficult to compromise the integrity of your validating server.
## Server Features and Topics
<!-- provided by the auto-generated table of children -->
{% raw-partial file="/_snippets/common-links.md" /%}
{% child-pages /%}

88
docs/concepts/networks-and-servers/ledger-history.md Normal file
View File

@@ -0,0 +1,88 @@
---
html: ledger-history.html
parent: networks-and-servers.html
seo:
description: rippled servers store a variable amount of transaction and state history locally.
labels:
- Data Retention
- Blockchain
- Core Server
---
# Ledger History
The [consensus process](../consensus-protocol/index.md) creates a chain of [validated ledger versions](../ledgers/index.md), each derived from the previous one by applying a set of [transactions](../transactions/index.md). Every [`rippled` server](index.md) stores ledger versions and transaction history locally. The amount of transaction history a server stores depends on how long that server has been online and how much history it is configured to fetch and keep.
Servers in the peer-to-peer XRP Ledger network share transactions and other data with each other as part of the consensus process. Each server independently builds each new ledger version and compares results with its trusted validators to ensure consistency. (If a consensus of trusted validators disagrees with a server's results, that server fetches the necessary data from its peers to achieve consistency.) Servers can download older data from their peers to fill gaps in their available history. The structure of the ledger uses cryptographic [hashes](../../references/protocol/data-types/basic-data-types.md#hashes) of the data so that any server can verify the integrity and consistency of the data.
## Databases
Servers keep ledger state data and transactions in a key-value store called the _ledger store_. Additionally, `rippled` maintains a few SQLite database files for more flexible access to things like transaction history, and to track certain settings changes.
It is generally safe to delete all of a `rippled` server's database files when that server is not running. (You may want to do this, for example, if you change the server's storage settings or if you are switching from a test net to the production network.)
## Available History
By design, all data and transactions in the XRP Ledger are public, and anyone can search or query anything. However, your server can only search data that it has available locally. If you try to query for a ledger version or transaction that your server does not have available, your server replies that it cannot find that data. Other servers that have the necessary history can respond successfully to the same query. If you have a business that uses XRP Ledger data, you should be mindful of how much history your server has available.
The [server_info method][] reports how many ledger versions your server has available in the `complete_ledgers` field.
## Fetching History
When an XRP Ledger server starts, its first priority is to get a complete copy of the latest validated ledger. From there, it keeps up with advances in the ledger progress. The server fills in any gaps in its ledger history that occur after syncing, and can backfill history from before it became synced. (Gaps in ledger history can occur if a server temporarily becomes too busy to keep up with the network, loses its network connection, or suffers other temporary issues.) When downloading ledger history, the server requests the missing data from its [peer servers](peer-protocol.md), and verifies the data's integrity using cryptographic [hashes][Hash].
Backfilling history is one of the server's lowest priorities, so it may take a long time to fill missing history, especially if the server is busy or its hardware and network specs aren't good enough. For recommendations on hardware specs, see [Capacity Planning](../../infrastructure/installation/capacity-planning.md). Backfilling history also requires that at least one of the server's direct peers has the history in question. For more information on managing your server's peer-to-peer connections, see [Configure Peering](../../infrastructure/configuration/peering/index.md).
The XRP Ledger identifies data (on several different levels) by a unique hash of its contents. The XRP Ledger's state data contains a short summary of the ledger's history, in the form of the [LedgerHashes object type](../../references/protocol/ledger-data/ledger-entry-types/ledgerhashes.md). Servers use the LedgerHashes objects to know which ledger versions to fetch, and to confirm that the ledger data they receive is correct and complete.
<a id="with-advisory-deletion"></a><!-- old anchor to this area -->
### Backfilling
{% badge href="https://github.com/XRPLF/rippled/releases/tag/1.6.0" %}Updated in: rippled 1.6.0{% /badge %}
The amount of history a server attempts to download depends on its configuration. The server automatically tries to fill gaps by downloading history up to **the oldest ledger it already has available**. You can use the `[ledger_history]` setting to make the server backfill history beyond that point. However, the server never downloads ledgers that would be scheduled for [deletion](../../infrastructure/configuration/data-retention/online-deletion.md).
The `[ledger_history]` setting defines a minimum number of ledgers to accumulate from before the current validated ledger. Use the special value `full` to download the [full history](#full-history) of the network. If you specify a number of ledgers, it must be equal to or more than the `online_deletion` setting; you cannot use `[ledger_history]` to make the server download _less_ history. To reduce the amount of history a server stores, change the [online deletion](../../infrastructure/configuration/data-retention/online-deletion.md) settings instead. <!-- STYLE_OVERRIDE: a number of -->
## Full History
Some servers in the XRP Ledger network are configured as "full-history" servers. These servers, which require significantly more disk space than other tracking servers, collect all available XRP Ledger history and **do not use online deletion**.
The XRP Ledger Foundation provides access to a set of full history servers operated by community members (see [xrplcluster.com](https://xrplcluster.com) for more details).
Ripple also provides a set of public full-history servers as a public service at `s2.ripple.com`. <!-- SPELLING_IGNORE: xrplcluster -->
Providers of Full History servers reserve the right to block access that is found to abuse resources, or put inordinate load on the systems.
**Tip:** Unlike some cryptocurrency networks, servers in the XRP Ledger do not need full history to know the current state and keep up with current transactions.
For instructions on setting up full history, see [Configure Full History](../../infrastructure/configuration/data-retention/configure-full-history.md).
## History Sharding
An alternative to storing the full history of the XRP Ledger on a single expensive machine is to configure many servers to each store a part of all ledger history. The [History Sharding](../../infrastructure/configuration/data-retention/history-sharding.md) feature makes this possible, storing ranges of ledger history in a separate storage area called the _shard store_. When a peer server asks for specific data (as described in [fetching history](#fetching-history) above), a server can answer using data from either its ledger store or shard store.
Online deletion **does not** delete from the shard store. However, if you configure online deletion to keep at least 32768 ledger versions in your server's ledger store, your server can copy full shards from the ledger store to the shard store before automatically deleting them from the ledger store.
For more information, see [Configure History Sharding](../../infrastructure/configuration/data-retention/configure-history-sharding.md).
## See Also
- **Concepts:**
- [Ledgers](../ledgers/index.md)
- [Consensus](../consensus-protocol/index.md)
- **Tutorials:**
- [Configure `rippled`](../../infrastructure/configuration/index.md)
- [Configure Online Deletion](../../infrastructure/configuration/data-retention/configure-online-deletion.md)
- [Configure Advisory Deletion](../../infrastructure/configuration/data-retention/configure-advisory-deletion.md)
- [Configure History Sharding](../../infrastructure/configuration/data-retention/configure-history-sharding.md)
- [Configure Full History](../../infrastructure/configuration/data-retention/configure-full-history.md)
- **References:**
- [ledger method][]
- [server_info method][]
- [ledger_request method][]
- [can_delete method][]
- [ledger_cleaner method][]
{% raw-partial file="/_snippets/common-links.md" /%}

52
docs/concepts/networks-and-servers/parallel-networks.md Normal file
View File

@@ -0,0 +1,52 @@
---
html: parallel-networks.html
parent: networks-and-servers.html
seo:
description: Understand how test networks and alternate ledger chains relate to the production XRP Ledger.
labels:
- Blockchain
---
# Parallel Networks
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 XRP Ledger community interact with XRP Ledger technology without affecting anything on the Mainnet, there are alternative networks, or altnets. Here's a breakdown of some public altnets:
| Network | Upgrade Cadence | Description |
|:--------|:----------------|:-------------------------------------------------|
| Mainnet | Stable releases | _The_ [XRP Ledger](/about/), a decentralized cryptographic ledger powered by a network of peer-to-peer servers and the home of [XRP](../../introduction/what-is-xrp.md). |
| 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](../../resources/known-amendments.md) 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 XRP Ledger features and amendments that are not yet enabled on the Mainnet. |
| [Hooks V3 Testnet](https://hooks-testnet-v3.xrpl-labs.com/) | [Hooks server](https://github.com/XRPL-Labs/xrpld-hooks) | A preview of on-chain smart contract functionality using [hooks](https://xrpl-hooks.readme.io/). |
| Sidechain-Devnet | Beta releases | A sidechain to test cross-chain bridge features. Devnet is treated as the locking chain and this sidechain is the issuing chain.<br>Library support:<br>- [xrpl.js 2.12.0](https://www.npmjs.com/package/xrpl/v/2.12.0)<br>- [xrpl-py 2.4.0](https://pypi.org/project/xrpl-py/2.4.0/)<br>**Note**: You can also use the [`xbridge-cli`](https://github.com/XRPLF/xbridge-cli) commandline tool to set up a cross-chain bridge on your local machine. |
Each altnet has its own separate supply of test XRP, which is [given away for free](/resources/dev-tools/xrp-faucets) 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.
**Caution:** Unlike the XRP Ledger Mainnet, test networks are usually _centralized_ and there are no guarantees about the stability and availability of these networks. They have been and continue to be used to test various properties of server configuration, network topology, and network performance.
## Parallel Networks and Consensus
The main factor in determining which network a server follows is its configured UNL—the list of validators it trusts not to collude. Each server uses its configured UNL 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 avoids 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 runs the main servers in the Testnet and Devnet; you can also [connect your own `rippled` server to these networks](../../infrastructure/configuration/connect-your-rippled-to-the-xrp-test-net.md). 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 at any time.
## See Also
- **Tools:**
- [XRP Testnet Faucet](/resources/dev-tools/xrp-faucets)
- **Concepts:**
- [Consensus](../consensus-protocol/index.md)
- [Amendments](amendments.md)
- **Tutorials:**
- [Connect Your `rippled` to the XRP Testnet](../../infrastructure/configuration/connect-your-rippled-to-the-xrp-test-net.md)
- [Use rippled in Stand-Alone Mode](../../infrastructure/testing-and-auditing/index.md)
- **References:**
- [server_info method][]
- [consensus_info method][]
- [validator_list_sites method][]
- [validators method][]
- [Daemon Mode Options](../../infrastructure/commandline-usage.md#daemon-mode-options)
{% raw-partial file="/_snippets/common-links.md" /%}

174
docs/concepts/networks-and-servers/peer-protocol.md Normal file
View File

@@ -0,0 +1,174 @@
---
html: peer-protocol.html
parent: networks-and-servers.html
seo:
description: The peer protocol specifies the language rippled servers speak to each other.
labels:
- Core Server
- Blockchain
---
# Peer Protocol
Servers in the XRP Ledger communicate to each other using the XRP Ledger peer protocol.
The peer protocol is the main mode of communication between servers in the XRP Ledger. All information about the behavior, progress, and connectivity of the XRP Ledger passes through the peer protocol. Examples of peer-to-peer communications include all of the following:
- Requesting a connection to other servers in the peer-to-peer network, or advertising that connection slots are available.
- Sharing candidate transactions with the rest of the network.
- Requesting ledger data from historical ledgers, or providing that data.
- Proposing a set of transactions for consensus, or sharing the calculated outcome of applying a consensus transaction set.
To set up a peer-to-peer connection, one server connects to another using HTTPS and requests an [HTTP upgrade](https://tools.ietf.org/html/rfc7230#section-6.7) to switch to the `XRPL/2.0` protocol (formerly `RTXP/1.2`). (For more information, see the [Overlay Network](https://github.com/XRPLF/rippled/blob/96bbabbd2ece106779bb544aa0e4ce174e99fdf6/src/ripple/overlay/README.md#handshake) article in the [`rippled` repository](https://github.com/ripple/rippled).)
## Peer Discovery
The XRP Ledger uses a "gossip" protocol to help find servers find others to connect to in the XRP Ledger network. Whenever a server starts up, it reconnects to any other peers it previously connected to. As a fallback, it uses the [hardcoded public hubs](https://github.com/XRPLF/rippled/blob/fa57859477441b60914e6239382c6fba286a0c26/src/ripple/overlay/impl/OverlayImpl.cpp#L518-L525). After a server successfully connects to a peer, it asks that peer for the contact information (generally, IP address and port) of other XRP Ledger servers that may also be seeking peers. The server can then connect to those servers, and ask them for the contact information of yet more XRP Ledger servers to peer with. Through this process, the server makes enough peer connections that it can remain reliably connected to the rest of the network even if it loses a connection to any single peer.
Typically, a server needs to connect to a public hub only once, for a short amount of time, to find other peers. After doing so, the server may or may not remain connected to the hub, depending on how stable its network connection is, how busy the hub is, and how many other high-quality peers the server finds. The server saves the addresses of these other peers so it can try reconnecting directly to those peers later, after a network outage or a restart.
The [peers method][] shows a list of peers your server is currently connected to.
For certain high-value servers (such as important [validators](rippled-server-modes.md#rippled-server-modes)) you may prefer not to have your server connect to untrusted peers through the peer discovery process. In this case, you can configure your server to use [private peers](#private-peers) only.
## Peer Protocol Port
To participate in the XRP Ledger, `rippled` servers connect to arbitrary peers using the peer protocol. (All peers are treated as untrusted, unless they are [clustered](clustering.md) with the current server.)
Ideally, the server should be able to send _and_ receive connections on the peer port. You should [forward the port used for the peer protocol through your firewall](../../infrastructure/configuration/peering/forward-ports-for-peering.md) to the `rippled` server.
IANA [has assigned port **2459**](https://www.iana.org/assignments/service-names-port-numbers/service-names-port-numbers.xhtml?search=2459) for the XRP Ledger peer protocol, but for compatibility with legacy systems, the [default `rippled` config file](https://github.com/XRPLF/rippled/blob/master/cfg/rippled-example.cfg) listens for incoming peer protocol connections on **port 51235** on all network interfaces. If you run a server, you can configure which port(s) your server listens on using the `rippled.cfg` file.
Example:
```
[port_peer]
port = 2459
ip = 0.0.0.0
protocol = peer
```
The peer protocol port also serves [special peer port methods](../../references/http-websocket-apis/peer-port-methods/index.md).
## Node Key Pair
When a server first starts up, it generates a _node key pair_ to use to identify itself in peer protocol communications. The server uses its key to sign all its peer protocol communications. This makes it possible to reliably identify and verify the integrity of messages from another server in the peer-to-peer network even if that server's messages are being relayed by untrusted peers.
The node key pair is saved in the database and reused when the server restarts. If you delete the server's databases, it creates a new node key pair, effectively coming online with a different identity. To reuse the same key pair even if the databases are deleted, you can configure the server with a `[node_seed]` stanza. To generate a value suitable for use in the `[node_seed]` stanza, use the [validation_create method][].
The node key pair also identifies other servers for purposes of [clustering](clustering.md) or [reserving peer slots](#fixed-peers-and-peer-reservations). If you have a cluster of servers, you should configure each server in the cluster with a unique `[node_seed]` setting. For more information on setting up a cluster, see [Cluster `rippled` Servers](../../infrastructure/configuration/peering/cluster-rippled-servers.md).
## Fixed Peers and Peer Reservations
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.md) 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 run by different people or organizations. <!-- STYLE_OVERRIDE: prioritize -->
In the following cases, a `rippled` server does not connect to untrusted peers:
- If the server is configured as a [private peer](#private-peers), it connects _only_ to its fixed peers.
- If the server is running in [stand-alone mode][] it does not connect to _any_ peers.
## Private Peers
You can configure a `rippled` server to act as a "private" server to keep its IP address hidden from the general public. This can be a useful precaution against denial of service attacks and intrusion attempts on important `rippled` servers such as trusted validators. To participate in the peer-to-peer network, a private server must be configured to connect to at least one non-private server, which relays its messages to the rest of the network.
**Caution:** If you configure a private server without any [fixed peers](#fixed-peers-and-peer-reservations), the server cannot connect to the network, so it cannot know network state, broadcast transactions, or participate in the consensus process.
Configuring a server as a private server has several effects:
- The server does not make outgoing connections to other servers in the peer-to-peer network unless it has been explicitly configured to connect to those servers.
- The server does not accept incoming connections from other servers unless it has been explicitly configured to accept connections from those servers.
- The server asks its direct peers not to reveal its IP address in untrusted communications, including the [peer crawler API response](../../references/http-websocket-apis/peer-port-methods/peer-crawler.md). This does not affect trusted communications such as the [peers admin method][peers method].
Validators always ask their peers to hide the validators' IP addresses, regardless of the private server settings. This helps protect validators from being overloaded by denial of service attacks.
**Caution:** It is possible to modify a server's source code so that it ignores this request and shares its immediate peers' IP addresses anyway. You should configure your private server to connect only to servers that you know are not modified in this way.
### Pros and Cons of Peering Configurations
To be part of the XRP Ledger, a `rippled` server must be connected to the rest of the open peer-to-peer network. Roughly speaking, there are three categories of configurations for how a `rippled` server connects to the network:
- Using **discovered peers**. The server connects to any untrusted servers it finds and stays connected as long as those servers behave appropriately. (For example, they don't request too much data, their network connections are stable, and they appear to be following the same [network](parallel-networks.md).) This is the default.
- As a **private server using proxies** run by the same person or organization. The proxies are stock `rippled` servers (also connected to discovered peers) that maintain a fixed peering connection with the private server.
- As a **private server using public hubs**. This is similar to using proxies, but it relies on specific third parties.
The pros and cons of each configuration are as follows:
<table>
<thead><tr>
<th>Configuration</th> <th>Pros</th> <th>Cons</th>
</tr></thead>
<tbody>
<tr><th>Discovered Peers</th>
<td><ul>
<li><p>Simplest configuration, with a low maintenance burden.</p></li>
<li><p>Creates the opportunity for a lot of direct peer connections. Having more direct peers comes with several benefits. Your server can <a href="ledger-history.html#fetching-history">fetch history</a> 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.</p></li>
<li><p>Lowers the possibility of disconnecting from the network because your server can replace disconnected peers with new ones.</p></li>
</ul></td>
<td><ul>
<li><p>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.</p></li>
<li><p>Your server's peers may disconnect or change often.</p></li>
</ul></td>
</tr>
<tr><th>Private Server Using Proxies</th>
<td><ul>
<li><p>Most secure and reliable configuration when implemented effectively.</p></li>
<li><p>As reliable and as redundant as you make it.</p></li>
<li><p>Can optimize the private server's performance with <a href="clustering.html">clustering</a>.</p></li>
<li><p>Enables you to create as many direct peer connections as you want. Your private server can <a href="ledger-history.html#fetching-history">fetch history</a> from multiple peers in parallel. Since you run the peers, you also control how much ledger history each peer keeps.</p></li>
</ul></td>
<td><ul>
<li><p>Higher maintenance burden and cost from running multiple servers.</p></li>
<li><p>Does not completely rule out the possibility of peer connection outages. No matter how many proxies you run, if they all exist on the same server rack, then one network or power outage can affect all of them.</p></li>
</ul></td>
</tr>
<tr><th>Private Server Using Public Hubs</th>
<td><ul>
<li><p>Low maintenance burden with a small amount of configuration.</p></li>
<li><p>Provides access to safe connections to the network.</p></li>
<li><p>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.</p></li>
</ul></td>
<td><ul>
<li><p>Depends on high-reputation third parties to remain reliable.</p></li>
<li>
<p>May cause your server to become disconnected from the network if the public hubs you rely on are too busy. Due to the nature of public hubs, they are the most popular and may not be able to keep a steady connection open to everyone.</p>
<p>To help avoid this issue, use more public hubs; the more the better. It can also help to use non-default hubs, which are less likely to be busy.</p>
</li>
</ul></td>
</tr>
</tbody>
</table>
### Configuring a Private Server
To configure your server as a private server, set the `[peer_private]` setting to `1` in the config file. For detailed instructions, see [Configure a Private Server](../../infrastructure/configuration/peering/configure-a-private-server.md).
## See Also
- **Concepts:**
- [Consensus](../consensus-protocol/index.md)
- [Parallel Networks](parallel-networks.md)
- **Tutorials:**
- [Cluster rippled Servers](../../infrastructure/configuration/peering/cluster-rippled-servers.md)
- [Configure a Private Server](../../infrastructure/configuration/peering/configure-a-private-server.md)
- [Configure the Peer Crawler](../../infrastructure/configuration/peering/configure-the-peer-crawler.md)
- [Forward Ports for Peering](../../infrastructure/configuration/peering/forward-ports-for-peering.md)
- [Manually Connect to a Specific Peer](../../infrastructure/configuration/peering/manually-connect-to-a-specific-peer.md)
- [Set Maximum Number of Peers](../../infrastructure/configuration/peering/set-max-number-of-peers.md)
- [Use a Peer Reservation](../../infrastructure/configuration/peering/use-a-peer-reservation.md)
- **References:**
- [peers method][]
- [peer_reservations_add method][]
- [peer_reservations_del method][]
- [peer_reservations_list method][]
- [connect method][]
- [fetch_info method][]
- [Peer Crawler](../../references/http-websocket-apis/peer-port-methods/peer-crawler.md)
{% raw-partial file="/_snippets/common-links.md" /%}

98
docs/concepts/networks-and-servers/rippled-server-modes.md Normal file
View File

@@ -0,0 +1,98 @@
---
html: rippled-server-modes.html
parent: networks-and-servers.html
seo:
description: Learn about rippled server modes, including stock servers, validator servers, and rippled servers run in stand-alone mode.
labels:
- Core Server
---
# rippled Server Modes
The `rippled` server software can run in several modes depending on its configuration, including:
- [**P2P Mode**](#p2p-mode) - This is the main mode of the server: it follows the peer-to-peer network, processes transactions, and maintains some amount of [ledger history](ledger-history.md). This mode can be configured to do any or all of the following roles:
- [**Validator**](#validators) - Helps secure the network by participating in consensus.
- [**API Server**](#api-servers) - Provides [API access](../../tutorials/get-started/get-started-using-http-websocket-apis.md) to read data from the shared ledger, submit transactions, and watch activity in the ledger. Optionally, this can be a [**Full History Server**](#full-history-servers), which keeps a complete record of transaction and ledger history.
- [**Hub Server**](#public-hubs) - Relays messages between many other members of the peer-to-peer network.
- [**Reporting mode**](#reporting-mode) - A specialized mode for serving API requests from a relational database. It does not participate in the peer-to-peer network, so you need to run a P2P Mode server and connect the reporting mode server using a trusted gRPC connection.
- [**Stand-alone mode**](#stand-alone-mode) - An offline mode for testing. Does not connect to the peer-to-peer network or use consensus.
You can also run the `rippled` executable as a client application for accessing [`rippled` APIs](../../references/http-websocket-apis/index.md) locally. (Two instances of the same binary can run side-by-side in this case; one as a server, and the other running briefly as a client and then terminating.)
For information on the commands to run `rippled` in each of these modes, see the [Commandline Reference](../../infrastructure/commandline-usage.md).
## P2P Mode
P2P Mode is the main and default mode of the `rippled` server, and it can handle almost anything you might want your server to do. These servers form a peer-to-peer network that processes transactions and maintains the shared state of the XRP Ledger. If you want to submit transactions, read ledger data, or otherwise participate in the network, your requests must go through a P2P Mode server at some point.
P2P Mode servers can be further configured to provide additional functionality. A server running in P2P Mode with a minimally-modified config file is also called a _stock server_. Other configurations include:
- [Validator](#validators)
- [API Server](#api-servers)
- [Public Hubs](#public-hubs)
P2P Mode servers connect to [Mainnet](parallel-networks.md) by default.
### API Servers
All P2P Mode servers provide [APIs](../../references/http-websocket-apis/index.md) for purposes like submitting transactions, checking balances and settings, and administering the server. If you query the XRP Ledger for data or submit transactions for business use, it can be useful to [run your own server](index.md#reasons-to-run-your-own-server).
#### Full History Servers
Unlike some other blockchains, the XRP Ledger does not require servers to have a complete transaction history to know the current state and process new transactions. As a server operator, you decide how much [ledger history](ledger-history.md) to store at a time. However, a P2P Mode server can only answer API requests using the ledger history it has locally available. For example, if you keep six months of history, your server can't describe the outcome of a transaction from a year ago. API servers with [full history](ledger-history.md#full-history) can report all transactions and balances since the start of the XRP Ledger.
### Public Hubs
A hub server is a P2P Mode server with lots of [peer protocol connections](peer-protocol.md) to other servers. Hub servers, especially _public hubs_ that allow connections from the open internet, help the XRP Ledger network maintain efficient connectivity. Successful public hubs embody the following traits:
- Good bandwidth.
- Connections with a lot of reliable peers.
- Ability to relay messages reliably.
To configure your server as a hub, increase the maximum number of peers allowed and make sure you've [forwarded the appropriate ports](../../infrastructure/configuration/peering/forward-ports-for-peering.md) through your firewall and NAT (network address translation) router as appropriate.
### Validators
The robustness of the XRP Ledger depends on an interconnected web of _validators_ who each trust some other validators _not to collude_. In addition to processing each transaction and calculating ledger state exactly like other P2P Mode servers, validators participate actively in the [consensus protocol](../consensus-protocol/index.md). If you or your organization relies on the XRP Ledger, it is in your interest to contribute to the consensus process by running _one_ server as a validator.
Validation uses only a small amount of computing resources, but there is not much benefit to a single entity or organization running multiple validators because doing so does not provide more protections against collusion. Each validator identifies itself with a unique cryptographic key pair that must be carefully managed; multiple validators must not share a key pair. For these reasons, validation is disabled by default.
You can safely enable validation on a server that is also used for other purposes; this type of configuration is called an _all-purpose server_. Alternatively, you can run a _dedicated validator_ that does not perform other tasks, possibly in a [cluster](clustering.md) with other P2P Mode `rippled` servers.
For more information about running a validator, see [Run `rippled` as a Validator](../../infrastructure/configuration/server-modes/run-rippled-as-a-validator.md).
## Reporting Mode
Reporting mode is specialized mode for serving API requests more efficiently. In this mode, the server gets the latest validated ledger data over [gRPC](../../infrastructure/configuration/configure-grpc.md) from a separate `rippled` server running in P2P Mode, then loads that data into a relational database ([PostgreSQL](https://www.postgresql.org/)). The reporting mode server does not directly participate in the peer-to-peer network, though it can forward requests such as transaction submission to the P2P Mode server it uses.
Multiple reporting mode servers can share access to a PostgreSQL database and [Apache Cassandra](https://cassandra.apache.org/) cluster to serve a large amount of history without each server needing a redundant copy of all the data. Reporting mode servers provide this data through the same [`rippled` APIs](../../references/http-websocket-apis/index.md) with some slight changes to accommodate for the differences in how they store the underlying data.
Most notably, reporting mode servers do not report pending, non-validated ledger data or transactions. This limitation is relevant to certain use cases that rely on rapid access to in-flux data, such as performing arbitrage in the [decentralized exchange](../tokens/decentralized-exchange/index.md).
<!-- TODO: link setup steps for Reporting Mode when those are ready -->
## Stand-Alone Mode
In stand-alone mode, the server operates without connecting to the network and participating in the consensus process. Without the consensus process, you have to manually advance the ledger and no distinction is made between "closed" and "validated" ledgers. However, the server still provides API access and processes transactions the same. This enables you to:
- [Test the effects of Amendments](../../infrastructure/testing-and-auditing/test-amendments.md) before those Amendments have gone into effect across the decentralized network.
- [Create a new genesis ledger](../../infrastructure/testing-and-auditing/start-a-new-genesis-ledger-in-stand-alone-mode.md) from scratch.
- [Load an existing ledger version](../../infrastructure/testing-and-auditing/load-a-saved-ledger-in-stand-alone-mode.md) from disk, then replay specific transactions to re-create their outcomes or test other possibilities.
## See Also
- **Tutorials:**
- [Configure `rippled`](../../infrastructure/configuration/index.md)
- [Use rippled in Stand-Alone Mode](../../infrastructure/testing-and-auditing/index.md)
{% raw-partial file="/_snippets/common-links.md" /%}

51
docs/concepts/networks-and-servers/the-clio-server.md Normal file
View File

@@ -0,0 +1,51 @@
---
html: the-clio-server.html
parent: networks-and-servers.html
seo:
description: Clio is an XRP Ledger server optimized for API calls.
---
# The Clio Server
Clio is an XRP Ledger API server optimized for WebSocket or HTTP API calls for validated ledger data.
A Clio server does not connect to the peer-to-peer network. Instead, it extracts data from a specified `rippled` server which is connected to the P2P network. By handling API calls efficiently, Clio servers can help reduce the load on `rippled` servers running in P2P mode.
Clio stores validated historical ledger and transaction data in a space efficient format, using up to 4 times less space than `rippled`. Clio uses Cassandra or ScyllaDB, allowing for scalable read throughput. Multiple Clio servers can share access to the same dataset, thereby enabling you to build a highly available cluster of Clio servers without the need for redundant data storage or computation.
Clio requires access to a `rippled` server, which can run on the same machine as Clio or separately.
While Clio offers the complete [HTTP / WebSocket APIs](../../references/http-websocket-apis/index.md), by default, it only returns validated data. For any requests that require access to the P2P network, Clio automatically forwards the request to the `rippled` server on the P2P network and passes the response back.
## Why Should I Run a Clio Server?
There are lots of reasons you might want to run your own Clio server, but most of them can be summarized as: reduced load on `rippled` server(s) connected to the P2P network, lower memory usage and storage overhead, easier horizontal scaling, and higher throughput for API requests.
* Reduced load on `rippled` server(s) - A Clio server does not connect to the peer-to-peer network. It uses gRPC to get validated data from one or more trusted `rippled` servers that are connected to the P2P network. Thus, a Clio server handles requests more efficiently and reduces the load on `rippled` servers running in P2P mode.
* Lower memory usage and storage overhead - Clio uses Cassandra as a database and stores data in a space efficient format, using up to 4 times less space than `rippled`.
* Easier horizontal scaling - Multiple Clio servers can share access to the same dataset, thus enabling you to build a highly available cluster of Clio servers.
* Higher throughput for API requests - A Clio server extracts validated data from one or more trusted `rippled` servers and stores this data efficiently. Thus, handling API calls efficiently, resulting in a higher throughput and in some cases, lower latency as well.
## How does a Clio Server Work?
[{% inline-svg file="/img/clio-basic-architecture.svg" /%}](/img/clio-basic-architecture.svg "Figure 1: How does a Clio server work?")
A Clio server stores validated ledger data such as transaction metadata, account states, and ledger headers in a persistent datastore.
When a Clio server receives an API request, it looks up data from these data stores. For requests that require data from the P2P network, the Clio server forwards the request to a P2P server, and then passes the response back to the client.
Clio will **always** forward to `rippled` if any of the following is true:
- `ledger_index` is set to `current` or `closed`.
- `accounts`, `queue` or `full` are set to `true` for the `ledger` API.
- `queue` is set to `true` for the `account_info` API.
- Requested API method (`"command"`) is `submit`, `submit_multisigned`, `fee`, `ledger_closed`, `ledger_current`, `ripple_path_find`, `manifest`, `channel_authorize` or `channel_verify`.
## See Also
- [Clio source code](https://github.com/XRPLF/clio)
- **Tutorials:**
- [Install Clio server on Ubuntu](../../infrastructure/installation/install-clio-on-ubuntu.md)

79
docs/concepts/networks-and-servers/transaction-censorship-detection.md Normal file
View File

@@ -0,0 +1,79 @@
---
html: transaction-censorship-detection.html
parent: networks-and-servers.html
seo:
description: XRP Ledger provides an automated transaction censorship detector that is available on all rippled servers.
labels:
- Blockchain
---
# Transaction Censorship Detection
{% badge href="https://github.com/XRPLF/rippled/releases/tag/1.2.0" %}New in: rippled 1.2.0{% /badge %}
The XRP Ledger is designed to be censorship resistant. In support of this design, the XRP Ledger provides an automated transaction censorship detector that is available on all `rippled` servers, enabling all participants to see if censorship is affecting the network.
While a `rippled` server is in sync with the network, the detector tracks all transactions that should have been accepted in the last round of [consensus](../consensus-protocol/index.md) and included in the last validated ledger. The detector issues log messages of increasing severity when it sees transactions that have not been included in a validated ledger after several rounds of consensus.
## How It Works
At a high-level, here’s how the transaction censorship detector works:
1. The detector adds all transactions in the server's initial consensus proposal to the tracker.
2. At the close of the consensus round, the detector removes all transactions included in the resulting validated ledger from the tracker.
3. The detector issues a [warning message](#example-warning-message) in the log for any transaction that remains in the tracker for 15 ledgers, surfacing it as a potentially censored transaction. The transaction's presence in the tracker at this time means that is has not been included in a validated ledger after 15 rounds of consensus. If the transaction remains in the tracker for another 15 ledgers, the detector issues another warning message in the log.
For as long as the transaction remains in the tracker, the detector continues to issue a warning message in the log every 15 ledgers, for up to five warning messages. After the fifth warning message, the detector issues a final [error message](#example-error-message) in the log and then stops issuing warning and error messages.
If you see these messages in your `rippled` server log, you should investigate why other servers are failing to include the transaction, starting with the assumption that the cause is more likely to be a [false positive](#potential-false-positives) (innocent bug) than malicious censorship.
## Example Warning Message
This is an example warning message issued by the transaction censorship detector after transaction E08D6E9754025BA2534A78707605E0601F03ACE063687A0CA1BDDACFCD1698C7 remained in the tracker for 15 ledgers, from ledger 18851530 to ledger 18851545.
```text
LedgerConsensus:WRN Potential Censorship: Eligible tx E08D6E9754025BA2534A78707605E0601F03ACE063687A0CA1BDDACFCD1698C7, which we are tracking since ledger 18851530 has not been included as of ledger 18851545.
```
## Example Error Message
This is an example error message issued by the transaction censorship detector after transaction E08D6E9754025BA2534A78707605E0601F03ACE063687A0CA1BDDACFCD1698C7 remained in the tracker for 75 ledgers (5 sets of 15 ledgers), from ledger 18851530 to ledger 18851605.
```text
LedgerConsensus:ERR Potential Censorship: Eligible tx E08D6E9754025BA2534A78707605E0601F03ACE063687A0CA1BDDACFCD1698C7, which we are tracking since ledger 18851530 has not been included as of ledger 18851605. Additional warnings suppressed.
```
## Potential False Positives
The transaction censorship detector may issue false positives in certain scenarios. In this case, a false positive means that the detector has flagged a transaction that has remained in the tracker for 15 ledgers or more, but for innocent reasons.
Here are some scenarios that could cause the detector to issue false positive messages:
- Your server is running a build with code that is different from the rest of the network. This may cause your server to apply transactions differently, resulting in false positives. While this type of false positive is unlikely, in general, it is crucial that you run a compatible version of the core XRP Ledger server.
- Your server is out of sync with the network and has not yet realized it.
- Servers in the network, including possibly your own server, have a bug that causes them to inconsistently relay transactions to other servers in the network.
Currently, there are no known bugs that cause this unexpected behavior. However, if you see the impact of what you suspect is a bug, consider reporting it to the [Ripple Bug Bounty](https://ripple.com/bug-bounty/) program.
## See Also
- **Concepts:**
- [Consensus Principles and Rules](../consensus-protocol/consensus-principles-and-rules.md)
- [Transaction Queue](../transactions/transaction-queue.md)
- **Tutorials:**
- [Reliable Transaction Submission](../transactions/reliable-transaction-submission.md)
- [Understanding Log Messages](../../infrastructure/troubleshooting/understanding-log-messages.md)
- **References:**
- [Transaction Results](../../references/protocol/transactions/transaction-results/transaction-results.md)
{% raw-partial file="/_snippets/common-links.md" /%}