7.2 KiB
Invariant Checking
This article provides a high-level overview of invariant checking, why it exist, how it works, and lists active invariants.
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.
Introduction
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.
Invariants should not trigger, but they ensure the XRP Ledger's integrity from bugs yet to be discovered or even created.
| Term | Description |
|---|---|
| Invariant | A rule that should always, without exception, be true. For example, "New XRP cannot be created". |
| Invariant Checking | In the XRP Ledger, a system where code automatically confirms that transaction processing does not break the invariants. If a transaction's execution would break an invariant, the invariant checking system fails the transaction. |
Why it Exists
- The overarching code for the XRP Ledger is complicated and vast; therefore, 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.
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:
Transaction Fee Check
- Invariant Condition(s):
- Transaction fees should never be negative nor larger than the transaction itself.
XRP Not Created
- Invariant Condition(s):
- A transaction must not create XRP and should only destroy the XRP transaction cost.
Account Roots Not Deleted
- Invariant Condition(s):
- An account ledger entry can be removed by an AccountDelete transaction, but this invariant checks that exactly 1 is deleted by a successful AccountDelete.
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.
No XRP Trust Lines
- Invariant Condition(s):
- Trust lines using XRP are not allowed.
No Bad Offers
- Invariant Condition(s):
- Offers should be for non-negative amounts and must not be XRP to XRP.
No Zero Escrow
- Invariant Condition(s):
- An escrow entry must hold a quantity of XRP between 0 and 99.99 billion.
Valid New Account Root
- Invariant Condition(s):
- A new account root must be the consequence of a payment.
- A new account root must have the right starting sequence.
- A new account may not create more than one new account root.
See Also
-
Blog:
-
Repository:
-
Other:
{% include '_snippets/rippled-api-links.md' %} {% include '_snippets/tx-type-links.md' %} {% include '_snippets/rippled_versions.md' %}