From d470a0b490568866956894f17b43767775c3eb24 Mon Sep 17 00:00:00 2001 From: mDuo13 Date: Wed, 1 Nov 2023 16:12:42 -0700 Subject: [PATCH] ledger method: update for 1.12.0 --- .../ledger/jsonrpc-response.json | 22 +++ content/_api-examples/ledger/ws-response.json | 24 ++++ .../ledger-methods/ledger.md | 133 ++++-------------- .../protocol/ledger-data/ledger-header.md | 26 ++-- dactyl-config.yml | 1 + 5 files changed, 84 insertions(+), 122 deletions(-) create mode 100644 content/_api-examples/ledger/jsonrpc-response.json create mode 100644 content/_api-examples/ledger/ws-response.json diff --git a/content/_api-examples/ledger/jsonrpc-response.json b/content/_api-examples/ledger/jsonrpc-response.json new file mode 100644 index 0000000000..b8730a95fb --- /dev/null +++ b/content/_api-examples/ledger/jsonrpc-response.json @@ -0,0 +1,22 @@ +{ + "result": { + "ledger": { + "account_hash": "23C1C8F8ACCEFACBDD9A1804CC25E652A324F9EABD7D0BEF103DA56D6E0306E7", + "close_flags": 0, + "close_time": 752188801, + "close_time_human": "2023-Nov-01 21:20:01.000000000 UTC", + "close_time_resolution": 10, + "closed": true, + "ledger_hash": "140B769E9ED61FCD675A6EEC1F005084614314C1D675C2CFDD11A1024BBD2C96", + "ledger_index": "83626952", + "parent_close_time": 752188800, + "parent_hash": "7D169A530960AFA8A0E38D036D8EF960BC2C2E02C4A0CE848A4200B9376AC99C", + "total_coins": "99988256304478252", + "transaction_hash": "77226182F58D9B5C798262F0E9D8C575D174E434F0C3C7119FB658BA70004CE9" + }, + "ledger_hash": "140B769E9ED61FCD675A6EEC1F005084614314C1D675C2CFDD11A1024BBD2C96", + "ledger_index": 83626952, + "status": "success", + "validated": true + } +} diff --git a/content/_api-examples/ledger/ws-response.json b/content/_api-examples/ledger/ws-response.json new file mode 100644 index 0000000000..129103171b --- /dev/null +++ b/content/_api-examples/ledger/ws-response.json @@ -0,0 +1,24 @@ +{ + "id": "example_ledger_req", + "result": { + "ledger": { + "account_hash": "B8B2C0C3F9E75E3AEE31D467B2544AB56244E618890BA58679707D6BFC0AF41D", + "close_flags": 0, + "close_time": 752188602, + "close_time_human": "2023-Nov-01 21:16:42.000000000 UTC", + "close_time_resolution": 10, + "closed": true, + "ledger_hash": "1BEECD5D21592EABDEF98D8E4BC038AD10B5700FF7E98011870DF5D6C2A2F39B", + "ledger_index": "83626901", + "parent_close_time": 752188601, + "parent_hash": "6B32CFC42B32C5FB90019AE17F701D96B499A4C8E148A002E18135A434A19D98", + "total_coins": "99988256314388830", + "transaction_hash": "21586C664DC47E12AF34F22EBF1DB55D23F8C98972542BAC0C39B1009CAC84D4" + }, + "ledger_hash": "1BEECD5D21592EABDEF98D8E4BC038AD10B5700FF7E98011870DF5D6C2A2F39B", + "ledger_index": 83626901, + "validated": true + }, + "status": "success", + "type": "response" +} diff --git 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 index 0d055b0d80..b37bb0674c 100644 --- 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' %} ``` @@ -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). diff --git a/content/references/protocol/ledger-data/ledger-header.md b/content/references/protocol/ledger-data/ledger-header.md index 3b927c78fc..eb4c3f7e59 100644 --- a/content/references/protocol/ledger-data/ledger-header.md +++ b/content/references/protocol/ledger-data/ledger-header.md @@ -11,18 +11,18 @@ labels: Every [ledger version](ledgers.html) has a unique header that describes the contents. You can look up a ledger's header information with the [ledger method][]. The contents of the ledger header are as follows: -| Field | JSON Type | [Internal Type][] | Description | -|:-----------------------------|:----------|:------------------|:--------------| -| `ledger_index` | String | UInt32 | The [ledger index][Ledger Index] of the ledger. Some API methods display this as a quoted integer; some display it as a native JSON number. | -| `ledger_hash` | String | Hash256 | The [SHA-512Half][] of this ledger version. This serves as a unique identifier for this ledger and all its contents. | -| `account_hash` | String | Hash256 | The [SHA-512Half][] of this ledger's state tree information. | -| `close_time` | Number | UInt32 | The approximate time this ledger version closed, as the number of seconds since the Ripple Epoch of 2000-01-01 00:00:00. This value is rounded based on the `close_time_resolution`. | -| `closed` | Boolean | Boolean | If `true`, this ledger version is no longer accepting new transactions. (However, unless this ledger version is validated, it might be replaced by a different ledger version with a different set of transactions.) | -| `parent_hash` | String | Hash256 | The `ledger_hash` value of the previous ledger version that is the direct predecessor of this one. If there are different versions of the previous ledger index, this indicates from which one the ledger was derived. | -| `total_coins` | String | UInt64 | The total number of [drops of XRP][] owned by accounts in the ledger. This omits XRP that has been destroyed by transaction fees. The actual amount of XRP in circulation is lower because some accounts are "black holes" whose keys are not known by anyone. | -| `transaction_hash` | String | Hash256 | The [SHA-512Half][] of the transactions included in this ledger. | -| `close_time_resolution` | Number | Uint8 | An integer in the range \[2,120\] indicating the maximum number of seconds by which the `close_time` could be rounded. | -| [`closeFlags`](#close-flags) | (Omitted) | UInt8 | A bit-map of flags relating to the closing of this ledger. | +| Field | JSON Type | [Internal Type][] | Description | +|:------------------------------|:----------|:------------------|:--------------| +| `ledger_index` | String | UInt32 | The [ledger index][Ledger Index] of the ledger. Some API methods display this as a quoted integer; some display it as a native JSON number. | +| `ledger_hash` | String | Hash256 | The [SHA-512Half][] of this ledger version. This serves as a unique identifier for this ledger and all its contents. | +| `account_hash` | String | Hash256 | The [SHA-512Half][] of this ledger's state tree information. | +| [`close_flags`](#close-flags) | Number | UInt8 | A bit-map of flags relating to the closing of this ledger. | +| `close_time` | Number | UInt32 | The [approximate time this ledger version closed](ledger-close-times.html), as the number of seconds since the Ripple Epoch of 2000-01-01 00:00:00 UTC. This value is rounded based on the `close_time_resolution`. | +| `close_time_resolution` | Number | Uint8 | An integer in the range \[2,120\] indicating the maximum number of seconds by which the `close_time` could be rounded. | +| `closed` | Boolean | Boolean | If `true`, this ledger version is no longer accepting new transactions. (However, unless this ledger version is validated, it might be replaced by a different ledger version with a different set of transactions.) | +| `parent_hash` | String | Hash256 | The `ledger_hash` value of the previous ledger version that is the direct predecessor of this one. If there are different versions of the previous ledger index, this indicates from which one the ledger was derived. | +| `total_coins` | String | UInt64 | The total number of [drops of XRP][] owned by accounts in the ledger. This omits XRP that has been destroyed by transaction fees. The actual amount of XRP in circulation is lower because some accounts are "black holes" whose keys are not known by anyone. | +| `transaction_hash` | String | Hash256 | The [SHA-512Half][] of the transactions included in this ledger. | ## Ledger Index @@ -34,8 +34,6 @@ Every [ledger version](ledgers.html) has a unique header that describes the cont 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](ledger-close-times.html), but built otherwise the same ledger, so they declared consensus while "agreeing to disagree" on the close time. In this case, official `close_time` value of the ledger is 1 second after that of the parent ledger. -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. - ## See Also diff --git a/dactyl-config.yml b/dactyl-config.yml index 33060c8cae..e6e7d802de 100644 --- a/dactyl-config.yml +++ b/dactyl-config.yml @@ -3144,6 +3144,7 @@ pages: - en - md: "@i18n/ja/references/http-websocket-apis/public-api-methods/ledger-methods/ledger.md" + outdated_translation: true targets: - ja