Add Clio ledger_index API method [draft]

_api-examples/ledger_index/jsonrpc-response.json

@@ -0,0 +1,15 @@
+{
+  "result": {
+    "ledger_index": 3679660,
+    "ledger_hash": "346C9211428A102081A3BFFCCBE1F698E7E56163BBD1DF81B446418B3213DBD7",
+    "closed": "2024-08-28T23:00:00Z",
+    "validated": true,
+    "status": "success"
+  },
+  "warnings": [
+    {
+      "id": 2001,
+      "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"
+    }
+  ]
+}

_api-examples/ledger_index/ws-response.json

@@ -0,0 +1,17 @@
+{
+  "result": {
+    "ledger_index": 3679660,
+    "ledger_hash": "346C9211428A102081A3BFFCCBE1F698E7E56163BBD1DF81B446418B3213DBD7",
+    "closed": "2024-08-28T23:00:00Z",
+    "validated": true
+  },
+  "id": "example_ledger_index",
+  "status": "success",
+  "type": "response",
+  "warnings": [
+    {
+      "id": 2001,
+      "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"
+    }
+    ]
+}

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

@@ -0,0 +1,9 @@
+---
+metadata:
+  indexPage: true
+---
+# Clio Methods
+
+These API methods are provided only by the Clio server, not `rippled`.
+
+{% child-pages /%}

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

@@ -0,0 +1,88 @@
+---
+seo:
+    description: Look up a ledger by its close time.
+labels:
+  - Blockchain
+---
+# ledger_index
+[[Source]](https://github.com/XRPLF/clio/blob/develop/src/rpc/handlers/LedgerIndex.cpp "Source")
+
+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 %}
+
+This method is only available from the Clio server, not `rippled`.
+
+## Request Format
+An example of the request format:
+
+{% tabs %}
+
+{% tab label="WebSocket" %}
+```json
+{
+    "id": "example_ledger_index",
+    "command": "ledger_index",
+    "date": "2024-08-28T22:59:00Z"
+}
+```
+{% /tab %}
+
+{% tab label="JSON-RPC" %}
+```json
+{
+    "method": "ledger_index",
+    "params": [
+        {
+            "date": "2024-08-28T22:59:00Z"
+        }
+    ]
+}
+```
+{% /tab %}
+
+{% /tabs %}
+
+[Try it! >](/resources/dev-tools/websocket-api-tool#ledger_index)
+
+The request can contain the following parameters:
+
+| `Field` | Type   | Required? | Description |
+|:--------|:-------|:----------|-------------|
+| `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. |
+
+## Response Format
+
+An example of a successful response:
+
+{% tabs %}
+
+{% tab label="WebSocket" %}
+{% code-snippet file="/_api-examples/ledger_index/ws-response.json" language="json" /%}
+{% /tab %}
+
+{% tab label="JSON-RPC" %}
+{% code-snippet file="/_api-examples/ledger_index/jsonrpc-response.json" language="json" prefix="200 OK\n\n" /%}
+{% /tab %}
+
+{% /tabs %}
+
+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:
+
+| Field          | Type    | Description                         |
+|:---------------|:--------|:------------------------------------|
+| `ledger_index` | Number  | The [Ledger Index][] of the most recently closed ledger at the specified time. |
+| `ledger_hash`  | String  | The identifying [Hash][] of the most recently closed ledger at the specified time. |
+| `closed`       | String  | The official close time of the most recently closed ledger at the specified time. |
+| `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. |
+
+{% admonition type="info" name="Note" %}
+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).
+{% /admonition %}
+
+## Possible Errors
+
+* Any of the [universal error types][].
+* `invalidParams` - One or more fields are specified incorrectly, or one or more required fields are missing.
+    * For example, this can occur if the specified `date` included a microseconds component.
+* `lgrNotFound` - The server does not have ledger history for the specified point in time.
+
+{% raw-partial file="/docs/_snippets/common-links.md" /%}

redirects.yaml

@@ -1,3 +1,6 @@
+'/docs/references/http-websocket-apis/public-api-methods/clio-server':
+    to: /docs/references/http-websocket-apis/public-api-methods/clio-methods
+    type: 301
 '/docs/references/protocol/transactions/transaction-results/transaction-results/':
     to: /docs/references/protocol/transactions/transaction-results/
     type: 301

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

@@ -129,8 +129,6 @@
         "body": {
           "command": "ledger",
           "ledger_index": "validated",
-          "full": false,
-          "accounts": false,
           "transactions": false,
           "expand": false,
           "owner_funds": false
@@ -162,6 +160,16 @@
           "limit": 5,
           "binary": true
         }
+      },
+      {
+        "name": "ledger_index",
+        "description": "Looks up the most recently closed ledger at a specific time.",
+        "link": "/docs/references/http-websocket-apis/public-api-methods/clio-methods/ledger_index",
+        "body": {
+          "command": "ledger_index",
+          "date": "2024-06-20T09:00:42.000Z"
+        },
+        "clio_only": true
       }
     ]
   },

sidebars.yaml

@@ -495,11 +495,12 @@
                     - page: docs/references/http-websocket-apis/public-api-methods/server-info-methods/server_state.md
                     - page: docs/references/http-websocket-apis/public-api-methods/server-info-methods/version.md
 
-                - page: docs/references/http-websocket-apis/public-api-methods/clio-server/index.md
+                - page: docs/references/http-websocket-apis/public-api-methods/clio-methods/index.md
                   expanded: false
                   items:
                     - page: docs/references/http-websocket-apis/public-api-methods/clio-methods/server_info-clio.md
                     - page: docs/references/http-websocket-apis/public-api-methods/clio-methods/ledger-clio.md
+                    - page: docs/references/http-websocket-apis/public-api-methods/clio-methods/ledger_index.md
                     - page: docs/references/http-websocket-apis/public-api-methods/clio-methods/nft_history.md
                     - page: docs/references/http-websocket-apis/public-api-methods/clio-methods/nft_info.md
                     - page: docs/references/http-websocket-apis/public-api-methods/clio-methods/nfts_by_issuer.md