Consensus

Written by Dave Cohen, David Schwartz, and Arthur Britto.

This article provides a high level overview of the XRP Ledger, the information it stores, and how transactions result in changes to the ledger.

When building applications on the XRP Ledger, it is important to understand this process, so as not to be surprised by the behavior of XRP Ledger APIs and their effects.

Introduction

The peer-to-peer XRP Ledger network provides a worldwide, shared ledger, which gives applications authoritative information about the state of its contents. This state information includes:

• settings for each account
• balances of XRP and tokens
• offers in the distributed exchange
• network settings, such as transaction costs and reserve amounts
• a timestamp

For a full, technical description of which data is included in a ledger version, see the Ledger Format Reference.

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.

Figure 2: XRP Ledger History

A ledger version has two identifiers. One identifier is its ledger index. Ledger versions are numbered incrementally. For example, if the current ledger version has ledger index of 100, the previous has ledger index 99 and the next has ledger index 101. The other identifier is a ledger hash, which is a digital fingerprint of the ledger's contents.

As servers propose transactions to apply to the ledger, they may create several candidate ledger versions with slightly different contents. These candidate ledger versions have the same ledger index but different ledger hashes. Of the many candidates, only one can become validated. All the other candidate ledger versions are discarded. Thus, there is exactly one validated ledger hash for each ledger index in history.

User level changes to the ledger are the results of transactions. Examples of transactions include payments, changes to account settings or trust lines, and offers to trade. Each transaction authorizes one or more changes to the ledger, and is cryptographically signed by an account owner. Transactions are the only way to authorize changes to an account, or to change anything else in the ledger.

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.