From 8df7c0a18f05b6811292e222c3771caa3fb03710 Mon Sep 17 00:00:00 2001 From: tamirms Date: Sat, 11 Feb 2023 09:30:15 +0000 Subject: [PATCH] Update documentation to reflect recent getEvents changes (#293) In stellar/soroban-tools#385 we modified the getEvents endpoint to remove the endLedger param and changed the behavior of pagination --- api/methods/getEvents.mdx | 74 ++++++++++++++++++++------------------- api/pagination.mdx | 4 +-- 2 files changed, 40 insertions(+), 38 deletions(-) diff --git a/api/methods/getEvents.mdx b/api/methods/getEvents.mdx index 545133e2..0a2708af 100644 --- 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`: `` - Stringified ledger sequence number to fetch events after (inclusive). -- `endLedger`: `` - 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`: `` - 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`: `` - 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`: `` - (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 - `` + - `latestLedger`: `` - Stringified-number of the current latest ledger observed by the node when this response was generated. - `events`: `` - `ledger`: `` - String-ified sequence number of the ledger. - `ledgerClosedAt`: `` - 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 index c6b3026f..062dbab6 100644 --- 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: