mirror of
https://github.com/XRPLF/xrpl-dev-portal.git
synced 2025-11-28 23:55:49 +00:00
fixed merge conflict
This commit is contained in:
Calvin Jhunjhnuwala
@@ -92,6 +92,8 @@ The amendments that a `rippled` server is configured to vote for or against have
|
||||
|
||||
If your server is amendment blocked, you must [upgrade to a new version](install-rippled.html) to sync with the network.
|
||||
|
||||
It is also possible to be amendment blocked because you connected your server to a [parallel network](parallel-networks.html) that has different amendments enabled. For example, the XRP Ledger Devnet typically has upcoming and experimental amendments enabled. If you are using the latest production release, your server is likely to be amendment blocked when connecting to Devnet. You could resolve this issue by upgrading to an unstable pre-release or nightly build, or you could [connect to a different network such as Testnet](connect-your-rippled-to-the-xrp-test-net.html) instead.
|
||||
|
||||
|
||||
#### How to Tell If Your `rippled` Server Is Amendment Blocked
|
||||
|
||||
|
||||
149
content/concepts/consensus-network/invariant-checking.md
Normal file
149
content/concepts/consensus-network/invariant-checking.md
Normal file
@@ -0,0 +1,149 @@
|
||||
# Invariant Checking
|
||||
|
||||
Invariant checking is a safety feature of the XRP Ledger. It consists of a set of checks, separate from normal transaction processing, that guarantee that certain _invariants_ hold true across all transactions.
|
||||
|
||||
Like many safety features, we all hope that invariant checking never actually needs to do anything. However, it can be useful to understand the XRP Ledger's invariants because they define hard limits on the XRP Ledger's transaction processing, and to recognize the problem in the unlikely event that a transaction fails because it violated an invariant check.
|
||||
|
||||
Invariants should not trigger, but they ensure the XRP Ledger's integrity from bugs yet to be discovered or even created.
|
||||
|
||||
|
||||
## Why it Exists
|
||||
|
||||
- The source code for the XRP Ledger is complicated and vast; there is a high potential for code to execute incorrectly.
|
||||
- The cost of incorrectly executing a transaction is high and not acceptable by any standards.
|
||||
|
||||
Specifically, incorrect transaction executions could create invalid or corrupt data that later consistently crashes servers in the network by sending them into an "impossible" state which could halt the entire network.
|
||||
|
||||
The processing of incorrect transaction would undermine the value of trust in the XRP Ledger. Invariant checking provides value to the entire XRP Ledger because it adds the feature of reliability.
|
||||
|
||||
|
||||
|
||||
## How it Works
|
||||
|
||||
The invariant checker is a second layer of code that runs automatically in real-time after each transaction. Before the transaction's results are committed to the ledger, the invariant checker examines those changes for correctness. If the transaction's results would break one of the XRP Ledger's strict rules, the invariant checker rejects the transaction. Transactions that are rejected this way have the result code `tecINVARIANT_FAILED` and are included in the ledger with no effects.
|
||||
|
||||
To include the transaction in the ledger with a `tec`-class code, some minimal processing is necessary. If this minimal processing still breaks an invariant, the transaction fails with the code `tefINVARIANT_FAILED` instead, and is not included in the ledger at all.
|
||||
|
||||
|
||||
## Active Invariants
|
||||
|
||||
The XRP Ledger checks all the following invariants on each transaction:
|
||||
|
||||
[[Source]](https://github.com/ripple/rippled/blob/023f5704d07d09e70091f38a0d4e5df213a3144b/src/ripple/app/tx/impl/InvariantCheck.h#L92 "Source")
|
||||
|
||||
- [Transaction Fee Check](#transaction-fee-check)
|
||||
|
||||
[[Source]](https://github.com/ripple/rippled/blob/023f5704d07d09e70091f38a0d4e5df213a3144b/src/ripple/app/tx/impl/InvariantCheck.h#L118 "Source")
|
||||
|
||||
- [XRP Not Created](#xrp-not-created)
|
||||
|
||||
[[Source]](https://github.com/ripple/rippled/blob/023f5704d07d09e70091f38a0d4e5df213a3144b/src/ripple/app/tx/impl/InvariantCheck.h#L146 "Source")
|
||||
|
||||
- [Account Roots Not Deleted](#account-roots-not-deleted)
|
||||
|
||||
[[Source]](https://github.com/ripple/rippled/blob/023f5704d07d09e70091f38a0d4e5df213a3144b/src/ripple/app/tx/impl/InvariantCheck.h#L173 "Source")
|
||||
|
||||
- [XRP Balance Checks](#xrp-balance-checks)
|
||||
|
||||
[[Source]](https://github.com/ripple/rippled/blob/023f5704d07d09e70091f38a0d4e5df213a3144b/src/ripple/app/tx/impl/InvariantCheck.h#L197 "Source")
|
||||
|
||||
- [Ledger Entry Types Match](#ledger-entry-types-match)
|
||||
|
||||
[[Source]](https://github.com/ripple/rippled/blob/023f5704d07d09e70091f38a0d4e5df213a3144b/src/ripple/app/tx/impl/InvariantCheck.h#L224 "Source")
|
||||
|
||||
- [No XRP Trust Lines](#no-xrp-trust-lines)
|
||||
|
||||
[[Source]](https://github.com/ripple/rippled/blob/023f5704d07d09e70091f38a0d4e5df213a3144b/src/ripple/app/tx/impl/InvariantCheck.h#L251 "Source")
|
||||
|
||||
- [No Bad Offers](#no-bad-offers)
|
||||
|
||||
[[Source]](https://github.com/ripple/rippled/blob/023f5704d07d09e70091f38a0d4e5df213a3144b/src/ripple/app/tx/impl/InvariantCheck.h#L275 "Source")
|
||||
|
||||
- [No Zero Escrow](#no-zero-escrow)
|
||||
|
||||
[[Source]](https://github.com/ripple/rippled/blob/023f5704d07d09e70091f38a0d4e5df213a3144b/src/ripple/app/tx/impl/InvariantCheck.h#L300 "Source")
|
||||
|
||||
- [Valid New Account Root](#valid-new-account-root)
|
||||
|
||||
|
||||
### Transaction Fee Check
|
||||
|
||||
- **Invariant Condition(s):**
|
||||
- The [transaction cost](transaction-cost.html) amount must never be negative, nor larger than the cost specified in the transaction.
|
||||
|
||||
|
||||
### XRP Not Created
|
||||
|
||||
- **Invariant Condition(s):**
|
||||
- A transaction must not create XRP and should only destroy the XRP [transaction cost](transaction-cost.html).
|
||||
|
||||
|
||||
### Account Roots Not Deleted
|
||||
|
||||
- **Invariant Condition(s):**
|
||||
- An [account](accounts.html) cannot be deleted from the ledger except by an [AccountDelete transaction][].
|
||||
- A successful AccountDelete transaction always deletes exactly 1 account.
|
||||
|
||||
|
||||
### XRP Balance Checks
|
||||
|
||||
- **Invariant Condition(s):**
|
||||
- An account's XRP balance must be of type XRP, and it cannot be less than 0 or more than 100 billion XRP exactly.
|
||||
|
||||
|
||||
### Ledger Entry Types Match
|
||||
|
||||
- **Invariant Condition(s):**
|
||||
- Corresponding modified ledger entries should match in type and added entries should be a [valid type](ledger-object-types.html).
|
||||
|
||||
|
||||
### No XRP Trust Lines
|
||||
|
||||
- **Invariant Condition(s):**
|
||||
- [Trust lines](trust-lines-and-issuing.html) using XRP are not allowed.
|
||||
|
||||
|
||||
### No Bad Offers
|
||||
|
||||
- **Invariant Condition(s):**
|
||||
- [Offers](offer.html#offer) should be for non-negative amounts and must not be XRP to XRP.
|
||||
|
||||
|
||||
### No Zero Escrow
|
||||
|
||||
- **Invariant Condition(s):**
|
||||
- An [escrow](escrow-object.html) entry must hold more than 0 XRP and less than 100 billion XRP.
|
||||
|
||||
|
||||
### Valid New Account Root
|
||||
|
||||
- **Invariant Condition(s):**
|
||||
- A new [account root](accountroot.html) must be the consequence of a payment.
|
||||
- A new account root must have the right starting [sequence](basic-data-types.html#account-sequence).
|
||||
- A transaction must not create more than one new [account](accounts.html).
|
||||
|
||||
|
||||
## See Also
|
||||
|
||||
- **Blog:**
|
||||
- [Protecting the Ledger: Invariant Checking](https://xrpl.org/blog/2017/invariant-checking.html)
|
||||
|
||||
- **Repository:**
|
||||
- [Invariant Check.h](https://github.com/ripple/rippled/blob/023f5704d07d09e70091f38a0d4e5df213a3144b/src/ripple/app/tx/impl/InvariantCheck.h)
|
||||
- [Invariant Check.cpp](https://github.com/ripple/rippled/blob/023f5704d07d09e70091f38a0d4e5df213a3144b/src/ripple/app/tx/impl/InvariantCheck.cpp)
|
||||
- [System Parameters](https://github.com/ripple/rippled/blob/develop/src/ripple/protocol/SystemParameters.h#L43)
|
||||
- [XRP Amount](https://github.com/ripple/rippled/blob/develop/src/ripple/basics/XRPAmount.h#L244)
|
||||
- [Ledger Formats](https://github.com/ripple/rippled/blob/023f5704d07d09e70091f38a0d4e5df213a3144b/src/ripple/protocol/LedgerFormats.h#L36-L94)
|
||||
|
||||
|
||||
- **Other:**
|
||||
- [Authorized Trust Lines](authorized-trust-lines.html)
|
||||
- [XRP Properties](xrp.html#xrp-properties)
|
||||
- [Calculating Balance Changes for a Transaction](https://xrpl.org/blog/2015/calculating-balance-changes-for-a-transaction.html#calculating-balance-changes-for-a-transaction)
|
||||
|
||||
|
||||
|
||||
<!--{# common link defs #}-->
|
||||
{% include '_snippets/rippled-api-links.md' %}
|
||||
{% include '_snippets/tx-type-links.md' %}
|
||||
{% include '_snippets/rippled_versions.md' %}
|
||||
@@ -18,17 +18,21 @@ The [server_info method][] reports how many ledger versions your server has avai
|
||||
|
||||
## Fetching History
|
||||
|
||||
When it starts, a `rippled` server's first priority is to get a complete copy of the latest validated ledger. From there, it keeps up with advances in the ledger progress. If configured to do so, the server also backfills ledger history up to a configured amount, which must be equal to or less than the cutoff beyond which online deletion is configured to delete.
|
||||
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.html), and verifies the data's integrity using cryptographic [hashes][Hash].
|
||||
|
||||
The server can backfill history from before it became synced, as well as filling in any gaps in the history it has collected after syncing. (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.) To backfill history, the server requests data from its peer `rippled` servers. The amount the server tries to backfill is defined by the `[ledger_history]` setting.
|
||||
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 has less than sufficient hardware and network specs. For recommendations on hardware specs, see [Capacity Planning](capacity-planning.html). 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](configure-peering.html).
|
||||
|
||||
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](ledgerhashes.html). 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.
|
||||
|
||||
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 has less than sufficient hardware and network specs. For recommendations on hardware specs, see [Capacity Planning](capacity-planning.html). Backfilling history also requires that at least one of the server's direct peers has the history in question. <!--{# TODO: link some info for managing your peer connections when that exists #}-->
|
||||
|
||||
### With Advisory Deletion
|
||||
<a id="with-advisory-deletion"></a><!-- old anchor to this area -->
|
||||
### Backfilling
|
||||
[Updated in: rippled 1.6.0][]
|
||||
|
||||
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](online-deletion.html).
|
||||
|
||||
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](online-deletion.html) settings instead.
|
||||
|
||||
If [online deletion](online-deletion.html) and advisory deletion are both enabled, the server automatically backfills data up to the oldest ledger it has not been allowed to delete yet. This can fetch data beyond the number of ledger versions configured in the `[ledger_history]` and `online_delete` settings. The [can_delete method][] tells the server what ledger versions it is allowed to delete.
|
||||
|
||||
|
||||
## Full History
|
||||
|
||||
@@ -28,18 +28,18 @@ To participate in the XRP Ledger, `rippled` servers connect to arbitrary peers u
|
||||
|
||||
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](forward-ports-for-peering.html) to the `rippled` server.
|
||||
|
||||
The [default `rippled` config file](https://github.com/ripple/rippled/blob/master/cfg/rippled-example.cfg) listens for incoming peer protocol connections on port 51235 on all network interfaces. You can change the port used by editing the appropriate stanza in your `rippled.cfg` file.
|
||||
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/ripple/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 = 51235
|
||||
port = 2459
|
||||
ip = 0.0.0.0
|
||||
protocol = peer
|
||||
```
|
||||
|
||||
The peer protocol port also serves the [special Peer Crawler API method](peer-crawler.html).
|
||||
The peer protocol port also serves [special peer port methods](peer-port-methods.html).
|
||||
|
||||
## Node Key Pair
|
||||
|
||||
|
||||
Reference in New Issue
Block a user