ledger_request

[Source]

The ledger_request command tells server to fetch a specific ledger version from its connected peers. This only works if one of the server's immediately-connected peers has that ledger. You may need to run the command several times to completely fetch a ledger.

The ledger_request method is an admin method that cannot be run by unprivileged users!

Request Format

An example of the request format:

{
    "id": 102,
    "command": "ledger_request",
    "ledger_index": 13800000
}

The request includes the following parameters:

`Field`	Type	Description
`ledger_index`	Number	(Optional) Retrieve the specified ledger by its Ledger Index.
`ledger_hash`	String	(Optional) Retrieve the specified ledger by its identifying Hash.

You must provide either ledger_index or ledger_hash but not both.

Response Format

The response follows the standard format. However, the request returns a failure response if it does not have the specified ledger even if it successfully instructed the rippled server to start retrieving the ledger.

Note

To retrieve a ledger, the rippled server must have a direct peer with that ledger in its history. If none of the peers have the requested ledger, you can use the connect method or the fixed_ips section of the config file to add Ripple's full-history server at s2.ripple.com and then make the ledger_request request again.

A failure response indicates the status of fetching the ledger. A successful response contains the information for the ledger in a similar format to the ledger method.

Loading: "/etc/rippled.cfg"
Connecting to 127.0.0.1:5005

{
   "result" : {
      "acquiring" : {
         "hash" : "01DDD89B6605E20338B8EEB8EB2B0E0DD2F685A2B164F3790C4D634B5734CC26",
         "have_header" : false,
         "peers" : 2,
         "timeouts" : 0
      },
      "error" : "lgrNotFound",
      "error_code" : 20,
      "error_message" : "acquiring ledger containing requested index",
      "request" : {
         "command" : "ledger_request",
         "ledger_index" : 18851277
      },
      "status" : "error"
   }
}

The three possible response formats are as follows:

When returning a lgrNotFound error, the response has a field, acquiring with a Ledger Request Object indicating the progress of fetching the ledger from the peer-to-peer network.
When the response shows the server is currently fetching the ledger, the body of the result is a Ledger Request Object indicating the progress of fetching the ledger from the peer-to-peer network.
When the ledger is fully available, the response is a representation of the ledger header.

Ledger Request Object

When the server is in the progress of fetching a ledger, but has not yet finished, the rippled server returns a ledger request object indicating its progress towards fetching the ledger. This object has the following fields:

`Field`	Type	Description
`hash`	String	(May be omitted) The Hash of the requested ledger, if the server knows it.
`have_header`	Boolean	Whether the server has the header section of the requested ledger.
`have_state`	Boolean	(May be omitted) Whether the server has the full state data of the requested ledger.
`have_transactions`	Boolean	(May be omitted) Whether the server has the full transaction set of the requested ledger.
`needed_state_hashes`	Array of Strings	(May be omitted) Up to 16 hashes of objects in the state data that the server still needs to retrieve.
`needed_transaction_hashes`	Array of Strings	(May be omitted) Up to 16 hashes of objects in the transaction set that the server still needs to retrieve.
`peers`	Number	How many peers the server is querying to find this ledger.
`timeouts`	Number	Number of times fetching this ledger has timed out so far.

Possible Errors

Any of the universal error types.
invalidParams - One or more fields are specified incorrectly, or one or more required fields are missing. This error can also occur if you specify a ledger index equal or higher than the current in-progress ledger.
lgrNotFound - If the ledger is not yet available. This indicates that the server has started fetching the ledger, although it may fail if none of its connected peers have the requested ledger. (Previously, this error used the code ledgerNotFound instead.)
reportingUnsupported - (Reporting Mode servers only) This method is not available in Reporting Mode.