ledger_request
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 codeledgerNotFound
instead.)reportingUnsupported
- (Reporting Mode servers only) This method is not available in Reporting Mode.