The Ledger

The Ripple Consensus 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.

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:

• A header - The ledger index, hashes of its other contents, and other metadata.
• A transaction tree - The transactions that were applied to the previous ledger to make this one. Transactions are the only way to change the ledger.
• A state tree - All the ledger nodes that contain the settings, balances, and objects in the ledger as of this version.

Tree Format

As its name might suggest, a ledger's state tree is a tree data structure, with each node identified by a 256-bit value called an index. In JSON, a ledger node's index value is represented as a 64-character hexadecimal string like "193C591BF62482468422313F9D3274B5927CA80B4DD3707E42015DD609E39C94". Every node in the state tree has an index that you can use as a key to look up the node in the state tree; every transaction has an indentifying hash that you can use to look up the transaction in the transaction tree. Do not confuse the index (key) of a ledger node with the ledger_index (sequence number) of a ledger.

In the case of transactions, the identifying hash is based on the signed transaction instructions, but the contents of the transaction object when you look it up also contain the results and metadata of the transaction, which are not taken into account when generating the hash.

In the case of state nodes, rippled usually includes the index of the node along with its contents. However, the index itself is not part of the contents. The index is derived by hashing important contents of the node, along with a namespace identifier. The ledger node type determines which namespace identifier to use as well as which contents to include in the hash. This ensures every index is unique. For a hash function, rippled uses SHA-512 and then truncates the result to the first 256 bytes. This algorithm, informally called SHA-512Half, provides an output that has comparable security to SHA-256, but runs faster on 64-bit processors.

Header Format

[Source]

Every ledger version has a unique header that describes the contents. You can look up a ledger's header information with the ledger command. The contents of the ledger header are as follows:

Ledger Index

A ledger index is a 32-bit unsigned integer used to identify a ledger. The ledger index is also known as the ledger's sequence number. The very first ledger was ledger index 1, and each new ledger has a ledger index 1 higher than that of the ledger immediately before it.

The ledger index indicates the order of the ledgers; the Hash value identifies the exact contents of the ledger. Two ledgers with the same hash are always the same. For validated ledgers, hash values and sequence numbers are equally valid and correlate 1:1. However, this is not true for in-progress ledgers:

• Two different rippled servers may have different contents for a current ledger with the same ledger index, due to latency in propagating transactions throughout the network.
• There may be multiple closed ledger versions competing to be validated by consensus. These ledger versions have the same sequence number but different contents (and different hashes). Only one of these closed ledgers can become validated.
• A current ledger's contents change over time, which would cause its hash to change, even though its ledger index number stays the same. The hash of a ledger is not calculated until the ledger is closed.

Close Flags

The ledger has only one flag defined for closeFlags: sLCF_NoConsensusTime (value 1). If this flag is enabled, it means that validators had different close times for the ledger, but built otherwise the same ledger, so they declared consensus while "agreeing to disagree" on the close time. In this case, the consensus ledger contains a close_time value that is 1 second after that of the previous ledger. (In this case, there is no official close time, but the actual real-world close time is probably 3-6 seconds later than the specified close_time.)

The closeFlags field is not included in any JSON representations of a ledger, but is included in the binary representation of a ledger, and is one of the fields that determine the ledger's hash.

Ledger Node Types

There are several different kinds of nodes that can appear in the ledger's state tree:

• AccountRoot - The settings, XRP balance, and other metadata for one account.
• DirectoryNode - Contains links to other nodes.
• Escrow - Contains XRP held for a conditional payment
• Offer - An offer to exchange currencies, known in finance as an order.
• PayChannel - A channel for asynchronous XRP payments.
• RippleState - Links two accounts, tracking the balance of one currency between them. The concept of a trust line is really an abstraction of this node type.
• SignerList - A list of addresses for multi-signing transactions.

Each ledger node consists of several fields. In the peer protocol that rippled servers use to communicate with each other, ledger nodes are represented in their raw binary format. In other rippled APIs, ledger nodes are represented as JSON objects.

AccountRoot

[Source]

The AccountRoot node type describes a single account object. Example AccountRoot node:

{
    "Account": "rf1BiGeXwwQoi8Z2ueFYTEXSwuJYfV2Jpn",
    "AccountTxnID": "0D5FB50FA65C9FE1538FD7E398FFFE9D1908DFA4576D8D7A020040686F93C77D",
    "Balance": "148446663",
    "Domain": "6D64756F31332E636F6D",
    "EmailHash": "98B4375E1D753E5B91627516F6D70977",
    "Flags": 8388608,
    "LedgerEntryType": "AccountRoot",
    "MessageKey": "0000000000000000000000070000000300",
    "OwnerCount": 3,
    "PreviousTxnID": "0D5FB50FA65C9FE1538FD7E398FFFE9D1908DFA4576D8D7A020040686F93C77D",
    "PreviousTxnLgrSeq": 14091160,
    "Sequence": 336,
    "TransferRate": 1004999999,
    "index": "13F1A95D7AAB7108D5CE7EEAF504B2894B8C674E6D68499076441C4837282BF8"
}

The AccountRoot node has the following fields:

AccountRoot Flags

There are several options which can be either enabled or disabled for an account. These options can be changed with an AccountSet transaction. In the ledger, flags are represented as binary values that can be combined with bitwise-or operations. The bit values for the flags in the ledger are different than the values used to enable or disable those flags in a transaction. Ledger flags have names that begin with lsf.

AccountRoot nodes can have the following flag values:

AccountRoot Index Format

The index of an AccountRoot node is the SHA-512Half of the following values put together:

• The Account space key (a)
• The AccountID of the account

DirectoryNode

[Source]

The DirectoryNode node type provides a list of links to other nodes in the ledger's state tree. A single conceptual Directory　takes the form of a doubly linked list, with one or more DirectoryNode objects each containing up to 32 indexes of other nodes. The first node is called the root of the directory, and all nodes other than the root node can be added or deleted as necessary.

There are two kinds of Directories:

• Owner directories list other nodes owned by an account, such as RippleState or Offer nodes.
• Offer directories list the offers available in the distributed exchange. A single Offer Directory contains all the offers that have the same exchange rate for the same issuances.

Example Directories:

{
    "ExchangeRate": "4F069BA8FF484000",
    "Flags": 0,
    "Indexes": [
        "AD7EAE148287EF12D213A251015F86E6D4BD34B3C4A0A1ED9A17198373F908AD"
    ],
    "LedgerEntryType": "DirectoryNode",
    "RootIndex": "1BBEF97EDE88D40CEE2ADE6FEF121166AFE80D99EBADB01A4F069BA8FF484000",
    "TakerGetsCurrency": "0000000000000000000000000000000000000000",
    "TakerGetsIssuer": "0000000000000000000000000000000000000000",
    "TakerPaysCurrency": "0000000000000000000000004A50590000000000",
    "TakerPaysIssuer": "5BBC0F22F61D9224A110650CFE21CC0C4BE13098",
    "index": "1BBEF97EDE88D40CEE2ADE6FEF121166AFE80D99EBADB01A4F069BA8FF484000"
}

{
    "Flags": 0,
    "Indexes": [
        "AD7EAE148287EF12D213A251015F86E6D4BD34B3C4A0A1ED9A17198373F908AD",
        "E83BBB58949A8303DF07172B16FB8EFBA66B9191F3836EC27A4568ED5997BAC5"
    ],
    "LedgerEntryType": "DirectoryNode",
    "Owner": "rpR95n1iFkTqpoy1e878f4Z1pVHVtWKMNQ",
    "RootIndex": "193C591BF62482468422313F9D3274B5927CA80B4DD3707E42015DD609E39C94",
    "index": "193C591BF62482468422313F9D3274B5927CA80B4DD3707E42015DD609E39C94"
}

Directory Index Formats

There are three different formulas for creating the index of a DirectoryNode, depending on whether the DirectoryNode represents:

• The first page (also called the root) of an Owner Directory,
• The first page of an Offer Directory, or
• Later pages of either type

The first page of an Owner Directory has an index that is the SHA-512Half of the following values put together:

• The Owner Directory space key (O, capital letter O)
• The AccountID from the Owner field.

The first page of an Offer Directory has a special index: the higher 192 bits define the order book, and the remaining 64 bits define the exchange rate of the offers in that directory. (An index is big-endian, so the book is in the more significant bits, which come first, and the quality is in the less significant bits which come last.) This provides a way to iterate through an order book from best offers to worst. Specifically: the first 192 bits are the first 192 bits of the SHA-512Half of the following values put together:

• The Book Directory space key (B)
• The 160-bit currency code from the TakerPaysCurrency
• The 160-bit currency code from the TakerGetsCurrency
• The AccountID from the TakerPaysIssuer
• The AccountID from the TakerGetsIssuer

The lower 64 bits of an Offer Directory's index represent the TakerPays amount divided by TakerGets amount from the offer(s) in that directory as a 64-bit number in Ripple's internal amount format.

If the DirectoryNode is not the first page in the Directory (regardless of whether it is an Owner Directory or an Offer Directory), then it has an index that is the SHA-512Half of the following values put together:

• The Directory Node space key (d)
• The index of the root DirectoryNode
• The page number of this node. (Since 0 is the root DirectoryNode, this value is an integer 1 or higher.)

Escrow

[Source]

(Requires the Escrow Amendment.)

The Escrow node type represents a held payment of XRP waiting to be executed or canceled. An EscrowCreate transaction creates an Escrow node in the ledger. A successful EscrowFinish or EscrowCancel transaction deletes the node. If the Escrow node has a crypto-condition, the payment can only succeed if an EscrowFinish transaction provides the corresponding fulfillment that satisfies the condition. (The only supported crypto-condition type is PREIMAGE-SHA-256.) If the Escrow node has a FinishAfter time, the held payment can only execute after that time.

An Escrow node is associated with two addresses:

• The owner, who provides the XRP when creating the Escrow node. If the held payment is canceled, the XRP returns to the owner.
• The destination, where the XRP is paid when the held payment succeeds. The destination can be the same as the owner.

Example Escrow node:

{
    "Account": "rf1BiGeXwwQoi8Z2ueFYTEXSwuJYfV2Jpn",
    "Amount": "10000",
    "CancelAfter": 545440232,
    "Condition": "A0258020A82A88B2DF843A54F58772E4A3861866ECDB4157645DD9AE528C1D3AEEDABAB6810120",
    "Destination": "ra5nK24KXen9AHvsdFTKHSANinZseWnPcX",
    "DestinationTag": 23480,
    "FinishAfter": 545354132,
    "Flags": 0,
    "LedgerEntryType": "Escrow",
    "OwnerNode": "0000000000000000",
    "PreviousTxnID": "C44F2EB84196B9AD820313DBEBA6316A15C9A2D35787579ED172B87A30131DA7",
    "PreviousTxnLgrSeq": 28991004,
    "SourceTag": 11747,
    "index": "DC5F3851D8A1AB622F957761E5963BC5BD439D5C24AC6AD7AC4523F0640244AC"
}

An Escrow node has the following fields:

Escrow Index Format

The index of an Escrow node is the SHA-512Half of the following values put together:

• The Escrow space key (u)
• The AccountID of the sender of the EscrowCreate transaction that created the Escrow node
• The Sequence number of the EscrowCreate transaction that created the Escrow node

Offer

[Source]

The Offer node type describes an offer to exchange currencies, more traditionally known as an order, in Ripple's distributed exchange. An OfferCreate transaction only creates an Offer node in the ledger when the offer cannot be fully executed immediately by consuming other offers already in the ledger.

An offer can become unfunded through other activities in the network, while remaining in the ledger. However, rippled automatically prunes any unfunded offers it happens across in the course of transaction processing (and only transaction processing, because the ledger state must only be changed by transactions). For more information, see lifecycle of an offer.

Example Offer node:

{
    "Account": "rBqb89MRQJnMPq8wTwEbtz4kvxrEDfcYvt",
    "BookDirectory": "ACC27DE91DBA86FC509069EAF4BC511D73128B780F2E54BF5E07A369E2446000",
    "BookNode": "0000000000000000",
    "Flags": 131072,
    "LedgerEntryType": "Offer",
    "OwnerNode": "0000000000000000",
    "PreviousTxnID": "F0AB71E777B2DA54B86231E19B82554EF1F8211F92ECA473121C655BFC5329BF",
    "PreviousTxnLgrSeq": 14524914,
    "Sequence": 866,
    "TakerGets": {
        "currency": "XAG",
        "issuer": "r9Dr5xwkeLegBeXq6ujinjSBLQzQ1zQGjH",
        "value": "37"
    },
    "TakerPays": "79550000000",
    "index": "96F76F27D8A327FC48753167EC04A46AA0E382E6F57F32FD12274144D00F1797"
}

An Offer node has the following fields:

Offer Flags

There are several options which can be either enabled or disabled when an OfferCreate transaction creates an offer node. In the ledger, flags are represented as binary values that can be combined with bitwise-or operations. The bit values for the flags in the ledger are different than the values used to enable or disable those flags in a transaction. Ledger flags have names that begin with lsf.

Offer nodes can have the following flag values:

Offer Index Format

The index of an Offer node is the SHA-512Half of the following values put together:

• The Offer space key (o)
• The AccountID of the account placing the offer
• The Sequence number of the transaction that created the offer

PayChannel

[Source]

(Requires the PayChan Amendment.)

The PayChannel node type represents a payment channel. Payment channels enable small, rapid off-ledger payments of XRP that can be later reconciled with the consensus ledger. A payment channel holds a balance of XRP that can only be paid out to a specific destination address until the channel is closed. Any unspent XRP is returned to the channel's owner (the source address that created and funded it) when the channel closes.

The PaymentChannelCreate transaction type creates a PayChannel node. The PaymentChannelFund and PaymentChannelClaim transaction types modify existing PayChannel nodes.

When a payment channel expires, at first it remains on the ledger, because only new transactions can modify ledger contents. Transaction processing automatically closes a payment channel when any transaction accesses it after the expiration. Therefore, to "finalize" the closing of an expired channel and return the unspent XRP to the owner, some address must send a new PaymentChannelClaim or PaymentChannelFund transaction accessing the channel.

Example PayChannel node:

{
    "Account": "rBqb89MRQJnMPq8wTwEbtz4kvxrEDfcYvt",
    "Destination": "rf1BiGeXwwQoi8Z2ueFYTEXSwuJYfV2Jpn",
    "Amount": "4325800",
    "Balance": "2323423",
    "PublicKey": "32D2471DB72B27E3310F355BB33E339BF26F8392D5A93D3BC0FC3B566612DA0F0A",
    "SettleDelay": 3600,
    "Expiration": 536027313,
    "CancelAfter": 536891313,
    "SourceTag": 0,
    "DestinationTag": 1002341,
    "Flags": 0,
    "LedgerEntryType": "PayChannel",
    "OwnerNode": "0000000000000000",
    "PreviousTxnID": "F0AB71E777B2DA54B86231E19B82554EF1F8211F92ECA473121C655BFC5329BF",
    "PreviousTxnLgrSeq": 14524914,
    "index": "96F76F27D8A327FC48753167EC04A46AA0E382E6F57F32FD12274144D00F1797"
}

A PayChannel node has the following fields:

Setting Channel Expiration

The Expiration field of a payment channel is the mutable expiration time, in contrast to the immutable expiration time represented by the CancelAfter field. The expiration of a channel is always considered relative to the close_time field of the previous ledger. The Expiration field is omitted when a PayChannel node is created. There are several ways the Expiration field of a PayChannel node can be updated, which can be summarized as follows: a channel's source address can set the Expiration of the channel freely as long as the channel always remains open at least SettleDelay seconds after the first attempt to close it.

Source Address

The source address can set the Expiration directly with the PaymentChannelFund transaction type. The new value must not be earlier than whichever of the following values is earliest:

• The current Expiration value (if one is set)
• The previous ledger's close time plus the SettleDelay of the channel

In other words, the source address can always make the Expiration later if an expiration is already set. The source can make an Expiration value earlier or set an Expiration if one isn't currently set, as long as the new value is at least SettleDelay seconds in the future. If the source address attempts to set an invalid Expiration date, the transaction fails with the temBAD_EXPIRATION error code.

The source address can also set the Expiration with the tfClose flag of the PaymentChannelClaim transaction type. If the flag is enabled, the ledger automatically sets the Expiration to whichever of the following values is earlier:

• The current Expiration value (if one is set)
• The previous ledger's close time plus the SettleDelay of the channel

The source address can remove the Expiration with the tfRenew flag of the PaymentChannelClaim transaction type.

Destination Address

The destination address cannot set the Expiration field. However, the destination address can use the PaymentChannelClaim's tfClose flag to close a channel immediately.

Other Addresses

If any other address attempts to set an Expiration field, the transaction fails with the tecNO_PERMISSION error code. However, if the channel is already expired, the transaction causes the channel to close and results in tesSUCCESS instead.

PayChannel Index Format

The index of a PayChannel node is the SHA-512Half of the following values put together:

• The PayChannel space key (x)
• The AccountID of the source account
• The AccountID of the destination account
• The Sequence number of the transaction that created the channel

RippleState

[Source]

The RippleState node type connects two accounts in a single currency. Conceptually, a RippleState node represents two trust lines between the accounts, one from each side. Each account can change the settings for its side of the RippleState node, but the balance is a single shared value. A trust line that is entirely in its default state is considered the same as trust line that does not exist, so rippled deletes RippleState nodes when their properties are entirely default.

Since no account is privileged in the Ripple ledger, a RippleState node sorts their account addresses numerically, to ensure a canonical form. Whichever address is numerically lower is deemed the "low account" and the other is the "high account".

Example RippleState node:

{
    "Balance": {
        "currency": "USD",
        "issuer": "rrrrrrrrrrrrrrrrrrrrBZbvji",
        "value": "-10"
    },
    "Flags": 393216,
    "HighLimit": {
        "currency": "USD",
        "issuer": "rf1BiGeXwwQoi8Z2ueFYTEXSwuJYfV2Jpn",
        "value": "110"
    },
    "HighNode": "0000000000000000",
    "LedgerEntryType": "RippleState",
    "LowLimit": {
        "currency": "USD",
        "issuer": "rsA2LpzuawewSBQXkiju3YQTMzW13pAAdW",
        "value": "0"
    },
    "LowNode": "0000000000000000",
    "PreviousTxnID": "E3FE6EA3D48F0C2B639448020EA4F03D4F4F8FFDB243A852A0F59177921B4879",
    "PreviousTxnLgrSeq": 14090896,
    "index": "9CA88CDEDFF9252B3DE183CE35B038F57282BC9503CDFA1923EF9A95DF0D6F7B"
}

A RippleState node has the following fields:

RippleState Flags

There are several options which can be either enabled or disabled for a trust line. These options can be changed with a TrustSet transaction. In the ledger, flags are represented as binary values that can be combined with bitwise-or operations. The bit values for the flags in the ledger are different than the values used to enable or disable those flags in a transaction. Ledger flags have names that begin with lsf.

RippleState nodes can have the following flag values:

Contributing to the Owner Reserve

If an account modifies a trust line to put it in a non-default state, then that trust line counts towards the account's owner reserve. In a RippleState node, the lsfLowReserve and lsfHighReserve flags indicate which account(s) are responsible for the owner reserve. The rippled server automatically sets these flags when it modifies a trust line.

The values that count towards a trust line's non-default state are as follows:

The lsfLowAuth and lsfHighAuth flags do not count against the default state, because they cannot be disabled.

The default state of the two NoRipple flags depends on the state of the lsfDefaultRipple flag in their corresponding AccountRoot nodes. If DefaultRipple is disabled (the default), then the default state of the lsfNoRipple flag is enabled for all of an account's trust lines. If an account enables DefaultRipple, then the lsfNoRipple flag is disabled (rippling is enabled) for an account's trust lines by default. Note: Prior to the introduction of the DefaultRipple flags in rippled version 0.27.3 (March 10, 2015), the default state for all trust lines was with lsfNoRipple disabled (rippling enabled).

Fortunately, rippled uses lazy evaluation to calculate the owner reserve. This means that even if an account changes the default state of all its trust lines by changing the DefaultRipple flag, that account's reserve stays the same initially. If an account modifies a trust line, rippled re-evaluates whether that individual trust line is in its default state and should contribute the owner reserve.

RippleState Index Format

The index of a RippleState node is the SHA-512Half of the following values put together:

• The RippleState space key (r)
• The AccountID of the low account
• The AccountID of the high account
• The 160-bit currency code of the trust line(s)

SignerList

[Source]

The SignerList node type represents a list of parties that, as a group, are authorized to sign a transaction in place of an individual account. You can create, replace, or remove a SignerList using the SignerListSet transaction type This node type is introduced by the MultiSign amendment.

Example SignerList node:

{
    "Flags": 0,
    "LedgerEntryType": "SignerList",
    "OwnerNode": "0000000000000000",
    "PreviousTxnID": "5904C0DC72C58A83AEFED2FFC5386356AA83FCA6A88C89D00646E51E687CDBE4",
    "PreviousTxnLgrSeq": 16061435,
    "SignerEntries": [
        {
            "SignerEntry": {
                "Account": "rsA2LpzuawewSBQXkiju3YQTMzW13pAAdW",
                "SignerWeight": 2
            }
        },
        {
            "SignerEntry": {
                "Account": "raKEEVSGnKSD9Zyvxu4z6Pqpm4ABH8FS6n",
                "SignerWeight": 1
            }
        },
        {
            "SignerEntry": {
                "Account": "rUpy3eEg8rqjqfUoLeBnZkscbKbFsKXC3v",
                "SignerWeight": 1
            }
        }
    ],
    "SignerListID": 0,
    "SignerQuorum": 3,
    "index": "A9C28A28B85CD533217F5C0A0C7767666B093FA58A0F2D80026FCC4CD932DDC7"
}

A SignerList node has the following fields:

The SignerEntries may be any combination of funded and unfunded addresses that use either secp256k1 or ed25519 keys.

SignerEntry Object

Each member of the SignerEntries field is an object that describes that signer in the list. A SignerEntry has the following fields:

When processing a multi-signed transaction, the server dereferences the Account values with respect to the ledger at the time of transaction execution. If the address does not correspond to a funded AccountRoot node, then only the master secret associated with that address can be used to produce a valid signature. If the account does exist in the ledger, then it depends on the state of that account. If the account has a Regular Key configured, the Regular Key can be used. The account's master key can only be used if it is not disabled. A multi-signature cannot be used as part of another multi-signature.

SignerLists and Reserves

A SignerList contributes to its owner's reserve requirement. The SignerList itself counts as two objects, and each member of the list counts as one. As a result, the total owner reserve associated with a SignerList is anywhere from 3 times to 10 times the reserve required by a single trust line (RippleState) or Offer node in the ledger.

SignerList Index Format

The index of a SignerList node is the SHA-512Half of the following values put together:

• The RippleState space key (S)
• The AccountID of the owner of the SignerList
• The SignerListID (currently always 0)