Skip to content

Commit 6219bf4

Browse files
mDuo13mDuo13
authored
Merge pull request #2703 from mDuo13/clio_ledger_index_method
Add Clio ledger_index API method [draft]
2 parents 1b517c8 + da9d9f6 commit 6219bf4

File tree

8 files changed

+144
-15
lines changed

8 files changed

+144
-15
lines changed

‎_api-examples/ledger_index/jsonrpc-response.json

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,15 @@
1+
{
2+
"result": {
3+
"ledger_index": 3679660,
4+
"ledger_hash": "346C9211428A102081A3BFFCCBE1F698E7E56163BBD1DF81B446418B3213DBD7",
5+
"closed": "2024-08-28T23:00:00Z",
6+
"validated": true,
7+
"status": "success"
8+
},
9+
"warnings": [
10+
{
11+
"id": 2001,
12+
"message": "This is a clio server. clio only serves validated data. If you want to talk to rippled, include 'ledger_index':'current' in your request"
13+
}
14+
]
15+
}

‎_api-examples/ledger_index/ws-response.json

Lines changed: 17 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,17 @@
1+
{
2+
"result": {
3+
"ledger_index": 3679660,
4+
"ledger_hash": "346C9211428A102081A3BFFCCBE1F698E7E56163BBD1DF81B446418B3213DBD7",
5+
"closed": "2024-08-28T23:00:00Z",
6+
"validated": true
7+
},
8+
"id": "example_ledger_index",
9+
"status": "success",
10+
"type": "response",
11+
"warnings": [
12+
{
13+
"id": 2001,
14+
"message": "This is a clio server. clio only serves validated data. If you want to talk to rippled, include 'ledger_index':'current' in your request"
15+
}
16+
]
17+
}

‎docs/references/http-websocket-apis/public-api-methods/clio-methods/index.md

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,9 @@
1+
---
2+
metadata:
3+
indexPage: true
4+
---
5+
# Clio Methods
6+
7+
These API methods are provided only by the Clio server, not `rippled`.
8+
9+
{% child-pages /%}

‎docs/references/http-websocket-apis/public-api-methods/clio-methods/ledger_index.md

Lines changed: 88 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,88 @@
1+
---
2+
seo:
3+
description: Look up a ledger by its close time.
4+
labels:
5+
- Blockchain
6+
---
7+
# ledger_index
8+
[[Source]](https://github.com/XRPLF/clio/blob/develop/src/rpc/handlers/LedgerIndex.cpp "Source")
9+
10+
The `ledger_index` command looks up information about the last closed ledger at a given real-world time. This may be useful for correlating events that happened off-chain with historical data in the XRP Ledger. {% badge href="https://github.com/XRPLF/clio/releases/tag/2.3.0" date="TBD" %}New in: Clio v2.3.0{% /badge %}
11+
12+
This method is only available from the Clio server, not `rippled`.
13+
14+
## Request Format
15+
An example of the request format:
16+
17+
{% tabs %}
18+
19+
{% tab label="WebSocket" %}
20+
```json
21+
{
22+
"id": "example_ledger_index",
23+
"command": "ledger_index",
24+
"date": "2024-08-28T22:59:00Z"
25+
}
26+
```
27+
{% /tab %}
28+
29+
{% tab label="JSON-RPC" %}
30+
```json
31+
{
32+
"method": "ledger_index",
33+
"params": [
34+
{
35+
"date": "2024-08-28T22:59:00Z"
36+
}
37+
]
38+
}
39+
```
40+
{% /tab %}
41+
42+
{% /tabs %}
43+
44+
[Try it! >](/resources/dev-tools/websocket-api-tool#ledger_index)
45+
46+
The request can contain the following parameters:
47+
48+
| `Field` | Type | Required? | Description |
49+
|:--------|:-------|:----------|-------------|
50+
| `date` | String | No | An ISO 8601 timestamp of the time to look up. Must be formatted without microseconds, and using `Z` as the time zone marker. For example, `2024-08-28T22:59:00Z`. If omitted, use the current time. |
51+
52+
## Response Format
53+
54+
An example of a successful response:
55+
56+
{% tabs %}
57+
58+
{% tab label="WebSocket" %}
59+
{% code-snippet file="/_api-examples/ledger_index/ws-response.json" language="json" /%}
60+
{% /tab %}
61+
62+
{% tab label="JSON-RPC" %}
63+
{% code-snippet file="/_api-examples/ledger_index/jsonrpc-response.json" language="json" prefix="200 OK\n\n" /%}
64+
{% /tab %}
65+
66+
{% /tabs %}
67+
68+
The response follows the [standard format][], with a successful result containing information about the most recently closed ledger at the requested time, including the following fields:
69+
70+
| Field | Type | Description |
71+
|:---------------|:--------|:------------------------------------|
72+
| `ledger_index` | Number | The [Ledger Index][] of the most recently closed ledger at the specified time. |
73+
| `ledger_hash` | String | The identifying [Hash][] of the most recently closed ledger at the specified time. |
74+
| `closed` | String | The official close time of the most recently closed ledger at the specified time. |
75+
| `validated` | Boolean | If `true`, the ledger has been validated by the consensus process and is immutable. Otherwise, the contents of the ledger are not final and may change. |
76+
77+
{% admonition type="info" name="Note" %}
78+
Due to the rounding on ledger close times, there may be a difference of up to 10 seconds between the "official" close time of a ledger and the real-world clock time when the ledger was closed. For more details, see [Ledger Close Times](../../../../concepts/ledgers/ledger-close-times.md).
79+
{% /admonition %}
80+
81+
## Possible Errors
82+
83+
* Any of the [universal error types][].
84+
* `invalidParams` - One or more fields are specified incorrectly, or one or more required fields are missing.
85+
* For example, this can occur if the specified `date` included a microseconds component.
86+
* `lgrNotFound` - The server does not have ledger history for the specified point in time.
87+
88+
{% raw-partial file="/docs/_snippets/common-links.md" /%}

‎docs/references/http-websocket-apis/public-api-methods/clio-server/index.md

Lines changed: 0 additions & 12 deletions
This file was deleted.

‎redirects.yaml

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -22,6 +22,9 @@
2222
/docs/tutorials/how-tos/use-specialized-payment-types/use-checks/use-checks:
2323
to: /docs/tutorials/how-tos/use-specialized-payment-types/use-checks
2424
type: 301
25+
/docs/references/http-websocket-apis/public-api-methods/clio-server:
26+
to: /docs/references/http-websocket-apis/public-api-methods/clio-methods
27+
type: 301
2528
/docs/references/protocol/transactions/transaction-results/transaction-results:
2629
to: /docs/references/protocol/transactions/transaction-results
2730
type: 301

‎resources/dev-tools/components/websocket-api/data/command-list.json

Lines changed: 10 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -130,8 +130,6 @@
130130
"body": {
131131
"command": "ledger",
132132
"ledger_index": "validated",
133-
"full": false,
134-
"accounts": false,
135133
"transactions": false,
136134
"expand": false,
137135
"owner_funds": false
@@ -163,6 +161,16 @@
163161
"limit": 5,
164162
"binary": true
165163
}
164+
},
165+
{
166+
"name": "ledger_index",
167+
"description": "Looks up the most recently closed ledger at a specific time.",
168+
"link": "/docs/references/http-websocket-apis/public-api-methods/clio-methods/ledger_index",
169+
"body": {
170+
"command": "ledger_index",
171+
"date": "2024-06-20T09:00:42.000Z"
172+
},
173+
"clio_only": true
166174
}
167175
]
168176
},

‎sidebars.yaml

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -505,11 +505,12 @@
505505
- page: docs/references/http-websocket-apis/public-api-methods/server-info-methods/server_state.md
506506
- page: docs/references/http-websocket-apis/public-api-methods/server-info-methods/version.md
507507

508-
- page: docs/references/http-websocket-apis/public-api-methods/clio-server/index.md
508+
- page: docs/references/http-websocket-apis/public-api-methods/clio-methods/index.md
509509
expanded: false
510510
items:
511511
- page: docs/references/http-websocket-apis/public-api-methods/clio-methods/server_info-clio.md
512512
- page: docs/references/http-websocket-apis/public-api-methods/clio-methods/ledger-clio.md
513+
- page: docs/references/http-websocket-apis/public-api-methods/clio-methods/ledger_index.md
513514
- page: docs/references/http-websocket-apis/public-api-methods/clio-methods/nft_history.md
514515
- page: docs/references/http-websocket-apis/public-api-methods/clio-methods/nft_info.md
515516
- page: docs/references/http-websocket-apis/public-api-methods/clio-methods/nfts_by_issuer.md

0 commit comments

Comments
 (0)