ARCHIVE/xrpl-dev-portal
1
0
Fork 0
mirror of https://github.com/XRPLF/xrpl-dev-portal.git synced 2025-11-21 20:25:51 +00:00
Code Issues Packages Projects Releases Wiki Activity

Merge pull request #2248 from XRPLF/ledger_remove_deprecated_fields

Browse Source 
ledger method: update for 1.12.0
This commit is contained in:
Rome Reginelli
2023-11-13 13:28:32 -08:00
committed by GitHub
parent 00d7aa087b d470a0b490
commit 443b48fb00
5 changed files with 84 additions and 122 deletions
Download Patch File Download Diff File Expand all files Collapse all files

22
content/_api-examples/ledger/jsonrpc-response.json Normal file
View File

@@ -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
}
}

24
content/_api-examples/ledger/ws-response.json Normal file
View File

@@ -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"
}

133
content/references/http-websocket-apis/public-api-methods/ledger-methods/ledger.md
View File

@@ -19,11 +19,9 @@ An example of the request format:
```json ```json
{ {
"id": 14, "id": "example_ledger_req",
"command": "ledger", "command": "ledger",
"ledger_index": "validated", "ledger_index": "validated",
"full": false,
"accounts": false,
"transactions": false, "transactions": false,
"expand": false, "expand": false,
"owner_funds": false "owner_funds": false
@@ -38,8 +36,6 @@ An example of the request format:
"params": [ "params": [
{ {
"ledger_index": "validated", "ledger_index": "validated",
"accounts": false,
"full": false,
"transactions": false, "transactions": false,
"expand": false, "expand": false,
"owner_funds": 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_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][]) | | `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. | | `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. | | `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. | | `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. | | `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 ## Response Format
@@ -88,34 +81,7 @@ An example of a successful response:
*WebSocket* *WebSocket*
```json ```json
{ {% include '_api-examples/ledger/ws-response.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"
}
``` ```
*JSON-RPC* *JSON-RPC*
@@ -123,66 +89,16 @@ An example of a successful response:
```json ```json
200 OK 200 OK
{ {% include '_api-examples/ledger/jsonrpc-response.json' %}
"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
}
}
``` ```
*Commandline* *Commandline*
```json ```json
Loading: "/etc/opt/ripple/rippled.cfg" 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
{ {% include '_api-examples/ledger/jsonrpc-response.json' %}
"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
}
}
``` ```
<!-- MULTICODE_BLOCK_END --> <!-- MULTICODE_BLOCK_END -->
@@ -191,27 +107,28 @@ The response follows the [standard format][], with a successful result containin
| `Field` | Type | Description | | `Field` | Type | Description |
|:-------------------------------|:--------|:----------------------------------| |:-------------------------------|:--------|:----------------------------------|
| `ledger` | Object | The complete header data of this ledger. | | `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 of all account state information in this ledger, as hex | | `ledger.account_hash` | String | [Hash](basic-data-types.html#hashes) of all account state information in this ledger, as hexadecimal. |
| `ledger.accountState` | Array | (Omitted unless requested) All the [account-state information](ledger-data-formats.html) in this ledger. | | `ledger.close_flags` | Number | A bit-map of [flags relating to the closing of this ledger](ledger-header.html#close-flags). |
| `ledger.close_flags` | Integer | 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` | 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. |
| `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` | Number | Ledger close times are rounded to within this many seconds. |
| `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.closed` | Boolean | Whether or not this ledger has been closed |
| `ledger.ledger_hash` | String | Unique identifying hash of the entire ledger. | | `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.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_close_time` | Number | 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.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.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.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.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_hash` | String | The unique identifying hash of the entire ledger, as hexadecimal. |
| `ledger_index` | Number | The [Ledger Index][] of this ledger. | | `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. | | `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: 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][]. * Any of the [universal error types][].
* `invalidParams` - One or more fields are specified incorrectly, or one or more required fields are missing. * `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. * `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 #}--> <!--{# common link defs #}-->

10
content/references/protocol/ledger-data/ledger-header.md
View File

@@ -12,17 +12,17 @@ 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: 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 | | 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_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. | | `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. | | `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`. | | [`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.) | | `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. | | `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. | | `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. | | `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. |
## Ledger Index ## 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 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 ## See Also

1
dactyl-config.yml
View File

@@ -3144,6 +3144,7 @@ pages:
- en - en
- md: "@i18n/ja/references/http-websocket-apis/public-api-methods/ledger-methods/ledger.md" - md: "@i18n/ja/references/http-websocket-apis/public-api-methods/ledger-methods/ledger.md"
outdated_translation: true
targets: targets:
- ja - ja