ledger method: update for 1.12.0

2025-11-21 20:25:51 +00:00 · 2023-11-01 16:12:42 -07:00
parent 4e1449dcf9
commit d470a0b490
5 changed files with 84 additions and 122 deletions
--- a/content/references/http-websocket-apis/public-api-methods/ledger-methods/ledger.md
+++ b/content/references/http-websocket-apis/public-api-methods/ledger-methods/ledger.md
@@ -19,11 +19,9 @@ An example of the request format:

 ```json
 {
-    "id": 14,
+    "id": "example_ledger_req",
    "command": "ledger",
    "ledger_index": "validated",
-    "full": false,
-    "accounts": false,
    "transactions": false,
    "expand": false,
    "owner_funds": false
@@ -38,8 +36,6 @@ An example of the request format:
    "params": [
        {
            "ledger_index": "validated",
-            "accounts": false,
-            "full": false,
            "transactions": false,
            "expand": false,
            "owner_funds": false
@@ -67,17 +63,14 @@ The request can contain the following parameters:
 |:---------------|:-----------------|:----------|-------------|
 | `ledger_hash`  | [Hash][]         | No        | A 20-byte hex string for the ledger version to use. (See [Specifying Ledgers][]). |
 | `ledger_index` | [Ledger Index][] | No        | The [ledger index][] of the ledger to use, or a shortcut string to choose a ledger automatically. (See [Specifying Ledgers][]) |
-| `full`         | Boolean          | No        | **Admin only** If `true`, return full information on the entire ledger. Ignored if you did not specify a ledger version. The default is `false`. (Equivalent to enabling `transactions`, `accounts`, and `expand`.) The [Clio server](the-clio-server.html) does not support this field. **Caution:** On Mainnet, this can be gigabytes worth of data, so the request is likely to time out. |
-| `accounts`     | Boolean          | No        | **Admin only.** If `true`, return the ledger's entire state data. Ignored if you did not specify a ledger version. The default is `false`. **Caution:** On Mainnet, this can be gigabytes worth of data, so the request is likely to time out. Use [ledger_data][ledger_data method] instead to fetch state data across multiple paginated requests. |
 | `transactions` | Boolean          | No        | If `true`, return information on transactions in the specified ledger version. The default is `false`. Ignored if you did not specify a ledger version. |
 | `expand`       | Boolean          | No        | Provide full JSON-formatted information for transaction/account information instead of only hashes. The default is `false`. Ignored unless you request transactions, accounts, or both. |
 | `owner_funds`  | Boolean          | No        | If `true`, include `owner_funds` field in the metadata of OfferCreate transactions in the response. The default is `false`. Ignored unless transactions are included and `expand` is true. |
-| `binary`       | Boolean          | No        | If `true`, and `transactions` and `expand` are both also `true`, return transaction information in binary format (hexadecimal string) instead of JSON format. [New in: rippled 0.28.0][] |
+| `binary`       | Boolean          | No        | If `true`, and `transactions` and `expand` are both also `true`, return transaction information in binary format (hexadecimal string) instead of JSON format. |
 | `queue`        | Boolean          | No        | If `true`, and the command is requesting the `current` ledger, includes an array of [queued transactions](transaction-cost.html#queued-transactions) in the results. |
-| `type`         | String           | No        | Filter by a ledger entry type. {% include '_snippets/lowercase-types.md' %} Ignored unless you request `accounts` (state data). |


-The `ledger` field is deprecated and may be removed without further notice.
+The `ledger` field is deprecated and may be removed without further notice. The `full`, `accounts`, and `type` fields (admin-only) are also deprecated; the Clio server does not implement these parameters.

 ## Response Format

@@ -88,34 +81,7 @@ An example of a successful response:
 *WebSocket*

 ```json
-{
-  "id": 14,
-  "result": {
-    "ledger": {
-      "accepted": true,
-      "account_hash": "53BD4650A024E27DEB52DBB6A52EDB26528B987EC61C895C48D1EB44CEDD9AD3",
-      "close_flags": 0,
-      "close_time": 638329241,
-      "close_time_human": "2020-Mar-24 01:40:41.000000000 UTC",
-      "close_time_resolution": 10,
-      "closed": true,
-      "hash": "1723099E269C77C4BDE86C83FA6415D71CF20AA5CB4A94E5C388ED97123FB55B",
-      "ledger_hash": "1723099E269C77C4BDE86C83FA6415D71CF20AA5CB4A94E5C388ED97123FB55B",
-      "ledger_index": "54300932",
-      "parent_close_time": 638329240,
-      "parent_hash": "DF68B3BCABD31097634BABF0BDC87932D43D26E458BFEEFD36ADF2B3D94998C0",
-      "seqNum": "54300932",
-      "totalCoins": "99991024049648900",
-      "total_coins": "99991024049648900",
-      "transaction_hash": "50B3A8FE2C5620E43AA57564209AEDFEA3E868CFA2F6E4AB4B9E55A7A62AAF7B"
-    },
-    "ledger_hash": "1723099E269C77C4BDE86C83FA6415D71CF20AA5CB4A94E5C388ED97123FB55B",
-    "ledger_index": 54300932,
-    "validated": true
-  },
-  "status": "success",
-  "type": "response"
-}
+{% include '_api-examples/ledger/ws-response.json' %}
 ```

 *JSON-RPC*
@@ -123,66 +89,16 @@ An example of a successful response:
 ```json
 200 OK

-{
-  "result": {
-    "ledger": {
-      "accepted": true,
-      "account_hash": "B258A8BB4743FB74CBBD6E9F67E4A56C4432EA09E5805E4CC2DA26F2DBE8F3D1",
-      "close_flags": 0,
-      "close_time": 638329271,
-      "close_time_human": "2020-Mar-24 01:41:11.000000000 UTC",
-      "close_time_resolution": 10,
-      "closed": true,
-      "hash": "3652D7FD0576BC452C0D2E9B747BDD733075971D1A9A1D98125055DEF428721A",
-      "ledger_hash": "3652D7FD0576BC452C0D2E9B747BDD733075971D1A9A1D98125055DEF428721A",
-      "ledger_index": "54300940",
-      "parent_close_time": 638329270,
-      "parent_hash": "AE996778246BC81F85D5AF051241DAA577C23BCA04C034A7074F93700194520D",
-      "seqNum": "54300940",
-      "totalCoins": "99991024049618156",
-      "total_coins": "99991024049618156",
-      "transaction_hash": "FC6FFCB71B2527DDD630EE5409D38913B4D4C026AA6C3B14A3E9D4ED45CFE30D"
-    },
-    "ledger_hash": "3652D7FD0576BC452C0D2E9B747BDD733075971D1A9A1D98125055DEF428721A",
-    "ledger_index": 54300940,
-    "status": "success",
-    "validated": true
-  }
-}
+{% include '_api-examples/ledger/jsonrpc-response.json' %}
 ```

 *Commandline*

 ```json
 Loading: "/etc/opt/ripple/rippled.cfg"
-2020-Mar-24 01:42:42.622264591 UTC HTTPClient:NFO Connecting to 127.0.0.1:5005
+2023-Nov-01 21:38:14.638871262 UTC HTTPClient:NFO Connecting to 127.0.0.1:5005

-{
-   "result" : {
-      "ledger" : {
-         "accepted" : true,
-         "account_hash" : "6B3101BE8F1431C5AC5B43D9731F1F3A747D24B3BEF89B687F0F3039E10EB65A",
-         "close_flags" : 0,
-         "close_time" : 638329360,
-         "close_time_human" : "2020-Mar-24 01:42:40.000000000 UTC",
-         "close_time_resolution" : 10,
-         "closed" : true,
-         "hash" : "C88A0EEC0E785A4C3E99F2A8B8EE0D7BDF3DE6C786C39B1B01547F6DAE5A4B7F",
-         "ledger_hash" : "C88A0EEC0E785A4C3E99F2A8B8EE0D7BDF3DE6C786C39B1B01547F6DAE5A4B7F",
-         "ledger_index" : "54300962",
-         "parent_close_time" : 638329352,
-         "parent_hash" : "96D2D70DC540BA4614A00C77FCFDED20E7D58AF3238E36655C38C407A56982A3",
-         "seqNum" : "54300962",
-         "totalCoins" : "99991024049218063",
-         "total_coins" : "99991024049218063",
-         "transaction_hash" : "47AC79011652D2A56AE04D3DD618C60A6669E3F94308C803554E890D2BD94481"
-      },
-      "ledger_hash" : "C88A0EEC0E785A4C3E99F2A8B8EE0D7BDF3DE6C786C39B1B01547F6DAE5A4B7F",
-      "ledger_index" : 54300962,
-      "status" : "success",
-      "validated" : true
-   }
-}
+{% include '_api-examples/ledger/jsonrpc-response.json' %}
 ```

 <!-- MULTICODE_BLOCK_END -->
@@ -191,27 +107,28 @@ The response follows the [standard format][], with a successful result containin

 | `Field`                        | Type    | Description                       |
 |:-------------------------------|:--------|:----------------------------------|
-| `ledger`                       | Object  | The complete header data of this ledger. |
-| `ledger.account_hash`          | String  | Hash of all account state information in this ledger, as hex |
-| `ledger.accountState`          | Array   | (Omitted unless requested) All the [account-state information](ledger-data-formats.html) in this ledger. |
-| `ledger.close_flags`           | Integer | A bit-map of [flags relating to the closing of this ledger](ledger-header.html#close-flags). |
-| `ledger.close_time`            | Integer | The time this ledger was closed, in [seconds since the Ripple Epoch][] |
-| `ledger.close_time_human`      | String  | The time this ledger was closed, in human-readable format. Always uses the UTC time zone. [Updated in: rippled 1.5.0][] |
-| `ledger.close_time_resolution` | Integer | Ledger close times are rounded to within this many seconds. |
-| `ledger.closed`                | Boolean | Whether or not this ledger has been closed |
+| `ledger`                       | Object  | The complete [ledger header data](ledger-header.html) of this ledger, with some additional fields added for convenience. |
+| `ledger.account_hash`          | String  | [Hash](basic-data-types.html#hashes) of all account state information in this ledger, as hexadecimal. |
+| `ledger.close_flags`           | Number  | A bit-map of [flags relating to the closing of this ledger](ledger-header.html#close-flags). |
+| `ledger.close_time`            | Number  | The time this ledger was closed, in [seconds since the Ripple Epoch][]. |
+| `ledger.close_time_human`      | String  | The time this ledger was closed, in human-readable format. Always uses the UTC time zone. |
+| `ledger.close_time_resolution` | Number  | Ledger close times are rounded to within this many seconds. |
+| `ledger.closed`                | Boolean | Whether or not this ledger has been closed. |
 | `ledger.ledger_hash`           | String  | Unique identifying hash of the entire ledger. |
-| `ledger.ledger_index`          | String  | The [Ledger Index][] of this ledger, as a quoted integer |
-| `ledger.parent_close_time`     | Integer | The time at which the previous ledger was closed. |
-| `ledger.parent_hash`           | String  | Unique identifying hash of the ledger that came immediately before this one. |
+| `ledger.ledger_index`          | String  | The [Ledger Index][] of this ledger, as a quoted integer. |
+| `ledger.parent_close_time`     | Number  | The time at which the previous ledger was closed. |
+| `ledger.parent_hash`           | String  | The unique identifying hash of the ledger that came immediately before this one, as hexadecimal. |
 | `ledger.total_coins`           | String  | Total number of XRP drops in the network, as a quoted integer. (This decreases as transaction costs destroy XRP.) |
-| `ledger.transaction_hash`      | String  | Hash of the transaction information included in this ledger, as hex |
-| `ledger.transactions`          | Array   | (Omitted unless requested) Transactions applied in this ledger version. By default, members are the transactions' identifying [Hash][] strings. If the request specified `expand` as true, members are full representations of the transactions instead, in either JSON or binary depending on whether the request specified `binary` as true. |
-| `ledger_hash`                  | String  | Unique identifying hash of the entire ledger. |
+| `ledger.transaction_hash`      | String  | [Hash](basic-data-types.html#hashes) of the transaction information included in this ledger. |
+| `ledger.transactions`          | Array   | _(Omitted unless requested)_ Transactions applied in this ledger version. By default, members are the transactions' identifying [Hash][] strings. If the request specified `expand` as true, members are full representations of the transactions instead, in either JSON or binary depending on whether the request specified `binary` as true. |
+| `ledger_hash`                  | String  | The unique identifying hash of the entire ledger, as hexadecimal. |
 | `ledger_index`                 | Number  | The [Ledger Index][] of this ledger. |
 | `validated`                    | Boolean | _(May be omitted)_ If `true`, this is a validated ledger version. If omitted or set to `false`, this ledger's data is not final. |
-| `queue_data`                   | Array   | _(Omitted unless requested with the `queue` parameter)_ Array of objects describing queued transactions, in the same order as the queue. If the request specified `expand` as true, members contain full representations of the transactions, in either JSON or binary depending on whether the request specified `binary` as true. Added by the [FeeEscalation amendment][]. [New in: rippled 0.70.0][] |
+| `queue_data`                   | Array   | _(Omitted unless requested with the `queue` parameter)_ Array of objects describing queued transactions, in the same order as the queue. If the request specified `expand` as true, members contain full representations of the transactions, in either JSON or binary depending on whether the request specified `binary` as true. |

-The following fields are deprecated and may be removed without further notice: `accepted`, `hash` (use `ledger_hash` instead), `seqNum` (use `ledger_index` instead), `totalCoins` (use `total_coins` instead).
+The `ledger.accountState` field (omitted unless requested with `"full": true` or `"accounts": true`) is deprecated.
+
+The following deprecated fields have been removed: `accepted`, `hash` (use `ledger_hash` instead), `seqNum` (use `ledger_index` instead), `totalCoins` (use `total_coins` instead). [Updated in: rippled 1.12.0][]

 Each member of the `queue_data` array represents one transaction in the queue. Some fields of this object may be omitted because they have not yet been calculated. The fields of this object are as follows:

@@ -238,7 +155,7 @@ If the request specified `"owner_funds": true` and expanded transactions, the re
 * Any of the [universal error types][].
 * `invalidParams` - One or more fields are specified incorrectly, or one or more required fields are missing.
 * `lgrNotFound` - The ledger specified by the `ledger_hash` or `ledger_index` does not exist, or it does exist but the server does not have it.
-* `noPermission` - If you specified `full` or `accounts` as true, but are not connected to the server as an admin (usually, admin requires connecting on a local port).
+* `noPermission` - If you specified `full` or `accounts` as true, but are not connected to the server as an admin (usually, admin requires connecting on localhost).


 <!--{# common link defs #}-->