Update documentation to reflect recent getEvents changes (#293)

In stellar/stellar-cli#385 we modified the getEvents endpoint to remove the endLedger param and changed the behavior of pagination
stellar-deprecated · Feb 11, 2023 · 8df7c0a · 8df7c0a
1 parent a28b3e3
commit 8df7c0a
Show file tree

Hide file tree

Showing 2 changed files with 40 additions and 38 deletions.
diff --git a/api/methods/getEvents.mdx b/api/methods/getEvents.mdx
@@ -12,8 +12,7 @@ By default soroban-rpc retains the most recent 24 hours of events.
 
 ## Parameters
 
-- `startLedger`: `<string>` - Stringified ledger sequence number to fetch events after (inclusive).
-- `endLedger`: `<string>` - Stringified ledger sequence number to fetch events before (inclusive). endLedger must be less than or equal to startLedger + 4320 (about 6 hours of ledgers).
+- `startLedger`: `<string>` - Stringified ledger sequence number to fetch events after (inclusive). This method will return an error if `startLedger` is less than the oldest ledger stored in this node, or greater than the latest ledger seen by this node. If a [cursor](../pagination) is included in the request, `startLedger` must be omitted.
 - `filters`: `<object[]>` - List of filters for the returned events. Events matching any of the filters are included. To match a filter, an event must match both a contractId and a topic. Maximum 5 filters are allowed per request.
   - `type`: `<"system"|"contract">` - (optional) Filter to only system or only contract type events. If omitted, return all.
   - `contractIds`: `<string[]>` - (optional) List of contract ids to query for events. If omitted, return events for all contracts. Maximum 5 contract IDs are allowed per request.
@@ -35,6 +34,7 @@ By default soroban-rpc retains the most recent 24 hours of events.
 ## Returns
 
 - `<object>`
+  - `latestLedger`: `<string>` - Stringified-number of the current latest ledger observed by the node when this response was generated.
   - `events`: `<object[]>`
     - `ledger`: `<string>` - String-ified sequence number of the ledger.
     - `ledgerClosedAt`: `<string>` - ISO8601 timestamp of the ledger closing time.
@@ -70,7 +70,6 @@ The examples below only returns two transfer events that took place to/from the
   "method": "getEvents",
   "params": {
     "startLedger": "227000",
-    "endLedger": "230200",
     "filters": [
       {
         "type": "contract",
@@ -95,40 +94,43 @@ The examples below only returns two transfer events that took place to/from the
 {
   "jsonrpc": "2.0",
   "id": 8675309,
-  "result": [
-    {
-      "type": "contract",
-      "ledger": "230010",
-      "ledgerClosedAt": "2023-01-23T18:54:41Z",
-      "contractId": "d93f5c7bb0ebc4a9c8f727c5cebc4e41194d38257e1d0d910356b43bfc528813",
-      "id": "0000987885427757056-0000000001",
-      "pagingToken": "0000987885427757056-0000000001",
-      "topic": [
-        "AAAABQAAAAh0cmFuc2Zlcg==",
-        "AAAABAAAAAEAAAAAAAAAAgAAAAUAAAAHQWNjb3VudAAAAAAEAAAAAQAAAAgAAAAAHavpBsZgRv4pEDXWB0NnwQBvvAL/8adWXz2fV7eNq2o=",
-        "AAAABAAAAAEAAAAAAAAAAgAAAAUAAAAHQWNjb3VudAAAAAAEAAAAAQAAAAgAAAAAHavpBsZgRv4pEDXWB0NnwQBvvAL/8adWXz2fV7eNq2o="
-      ],
-      "value": {
-        "xdr": "AAAABAAAAAEAAAAFAAAAAAABhqAAAAAAAAAAAA=="
-      }
-    },
-    {
-      "type": "contract",
-      "ledger": "230170",
-      "ledgerClosedAt": "2023-01-23T19:08:37Z",
-      "contractId": "d93f5c7bb0ebc4a9c8f727c5cebc4e41194d38257e1d0d910356b43bfc528813",
-      "id": "0000988572622524416-0000000001",
-      "pagingToken": "0000988572622524416-0000000001",
-      "topic": [
-        "AAAABQAAAAh0cmFuc2Zlcg==",
-        "AAAABAAAAAEAAAAAAAAAAgAAAAUAAAAHQWNjb3VudAAAAAAEAAAAAQAAAAgAAAAAHavpBsZgRv4pEDXWB0NnwQBvvAL/8adWXz2fV7eNq2o=",
-        "AAAABAAAAAEAAAAAAAAAAgAAAAUAAAAHQWNjb3VudAAAAAAEAAAAAQAAAAgAAAAAHavpBsZgRv4pEDXWB0NnwQBvvAL/8adWXz2fV7eNq2o="
-      ],
-      "value": {
-        "xdr": "AAAABAAAAAEAAAAFAAAAAAAHoSAAAAAAAAAAAA=="
+  "result": {
+    "latestLedger": "230473",
+    "events": [
+      {
+        "type": "contract",
+        "ledger": "230010",
+        "ledgerClosedAt": "2023-01-23T18:54:41Z",
+        "contractId": "d93f5c7bb0ebc4a9c8f727c5cebc4e41194d38257e1d0d910356b43bfc528813",
+        "id": "0000987885427757056-0000000001",
+        "pagingToken": "0000987885427757056-0000000001",
+        "topic": [
+          "AAAABQAAAAh0cmFuc2Zlcg==",
+          "AAAABAAAAAEAAAAAAAAAAgAAAAUAAAAHQWNjb3VudAAAAAAEAAAAAQAAAAgAAAAAHavpBsZgRv4pEDXWB0NnwQBvvAL/8adWXz2fV7eNq2o=",
+          "AAAABAAAAAEAAAAAAAAAAgAAAAUAAAAHQWNjb3VudAAAAAAEAAAAAQAAAAgAAAAAHavpBsZgRv4pEDXWB0NnwQBvvAL/8adWXz2fV7eNq2o="
+        ],
+        "value": {
+          "xdr": "AAAABAAAAAEAAAAFAAAAAAABhqAAAAAAAAAAAA=="
+        }
+      },
+      {
+        "type": "contract",
+        "ledger": "230170",
+        "ledgerClosedAt": "2023-01-23T19:08:37Z",
+        "contractId": "d93f5c7bb0ebc4a9c8f727c5cebc4e41194d38257e1d0d910356b43bfc528813",
+        "id": "0000988572622524416-0000000001",
+        "pagingToken": "0000988572622524416-0000000001",
+        "topic": [
+          "AAAABQAAAAh0cmFuc2Zlcg==",
+          "AAAABAAAAAEAAAAAAAAAAgAAAAUAAAAHQWNjb3VudAAAAAAEAAAAAQAAAAgAAAAAHavpBsZgRv4pEDXWB0NnwQBvvAL/8adWXz2fV7eNq2o=",
+          "AAAABAAAAAEAAAAAAAAAAgAAAAUAAAAHQWNjb3VudAAAAAAEAAAAAQAAAAgAAAAAHavpBsZgRv4pEDXWB0NnwQBvvAL/8adWXz2fV7eNq2o="
+        ],
+        "value": {
+          "xdr": "AAAABAAAAAEAAAAFAAAAAAAHoSAAAAAAAAAAAA=="
+        }
       }
-    }
-  ]
+    ]
+  }
 }
 ```
 

diff --git a/api/pagination.mdx b/api/pagination.mdx
@@ -7,8 +7,8 @@ Pagination in soroban-rpc is similar to pagination in Horizon.
 
 For methods which support it, the pagination arguments are passed as a final object argument with two values:
 
-- `cursor`: string - (optional) A string ID that points to a specific location in a collection of responses and is pulled from the paging_token value of a record.
-- `limit`: number - (optional) The maximum number of records returned. The limit can range from 1 to 200 - an upper limit that is hardcoded in Soroban-RPC for performance reasons. If this argument isn't designated, it defaults to 10.
+- `cursor`: string - (optional) A string ID that points to a specific location in a collection of responses and is pulled from the paging_token value of a record. When a cursor is provided Soroban-RPC will *not* include the element whose id matches the cursor in the response. Only elements which appear *after* the cursor are included.
+- `limit`: number - (optional) The maximum number of records returned. The limit for [getEvents](methods/getEvents) can range from 1 to 10000 - an upper limit that is hardcoded in Soroban-RPC for performance reasons. If this argument isn't designated, it defaults to 100.
 
 For example, calling a method with pagination parameter set: