Specifying a Ledger

Many API methods require you to specify a ledger instance that includes the correct data to be retrieved and the latest data for a specific version of the shared ledger. Commands that accept a version of the ledger all work the same way. Here are three ways you can specify which ledger you want to use:

1. Specify the ledger via the serial number in the ledger_index parameter. Each closed ledger has an identifiable sequence number that is one greater than the previous validated ledger. (The origin ledger sequence number is 0)
2. Specify the ledger via the hash value in the ledger_hash parameter.
3. Specify the ledger via one of the shortcuts in the ledger_index parameter:
   • validated : For most recent ledgers that have been verified by the entire network
   • closed : For most recent ledgers that have been closed for modification and raised by nodes for verification
   • current: The ledger of the current running version of the node

There is also a deprecated ledger parameter that accepts all three formats above. Do not use it; it may be removed without notice. If you do not specify a ledger, the current (in-progress) ledger is selected by default. If you specify a ledger in more than one way, the deprecated ledger field takes precedence, followed by ledger_hash. The ledger_index field is used only if neither of the other fields is present. Note: do not rely on this default behavior, which may change. Specify a ledger version explicitly in each call. Sequence numbers identify the order of ledgers. A hash identifies the exact contents of a ledger, so two ledgers with the same hash are identical. For closed ledgers, hashes and sequence numbers have a one-to-one relationship and are equally valid identifiers. This does not apply to an in-progress ledger:

• Because transactions are not fully propagated throughout the network, two different radard servers may have different contents of the existing ledger with the same sequence number.
• The contents of the existing ledger change over time, even if the sequence number is the same, this will cause the hash to change. Therefore, its hash cannot be calculated until the ledger is closed.