Add getLedgers method to Rpc Server (#1231)

* add getLedgers method to Rpc Server

* move GetEventsRequest to api file and make start/end ledger and cursor mutually exclusive

* create alias for Api.GetEventsRequest in Server for backward compatibility

Author: Ryang-21

.git-blame-ignore-revs

@@ -1 +1 @@
-030c448da30ff159419dcc92e2921ef578cca426
+2c766e53ca4c47995905f43110719538c0d946b6

CHANGELOG.md

@@ -8,8 +8,14 @@ A breaking change will get clearly marked in this log.
 
 ### Added
 * `Spec.scValToNative` now supports parsing `Option`s ([#1228](https://github.com/stellar/js-stellar-sdk/pull/1228)).
+*  Added `getLedgers` method to `rpc.Server` for retreiving ledger data. ([#1231](https://github.com/stellar/js-stellar-sdk/pull/1231)).
+
 ### Fixed
 * `Spec.scValToNative` returns `null` for `void`s or `Option`als instead of the ambiguous `undefined` ([#1228](https://github.com/stellar/js-stellar-sdk/pull/1228)).
+* The `getEvents` API now requires either a start and end ledger or a cursor to be provided ([#1231](https://github.com/stellar/js-stellar-sdk/pull/1231)).
+
+### Deprecated
+* `GetEventsRequest` interface moved from `server.ts` to `api.ts` ([#1231](https://github.com/stellar/js-stellar-sdk/pull/1231)).
 
 ## [v14.2.0](https://github.com/stellar/js-stellar-sdk/compare/v14.1.1...v14.2.0)
 

src/rpc/api.ts

@@ -224,6 +224,58 @@ export namespace Api {
     oldestLedgerCloseTime: string;
   }
 
+  /**
+   * Request parameters for fetching events from the Stellar network.
+   *
+   * **Important**: This type enforces mutually exclusive pagination modes:
+   * - **Ledger range mode**: Use `startLedger` and `endLedger` (cursor must be omitted)
+   * - **Cursor pagination mode**: Use `cursor` (startLedger and endLedger must be omitted)
+   *
+   * @example
+   * // ✅ Correct: Ledger range mode
+   * const rangeRequest: GetEventsRequest = {
+   *   filters: [],
+   *   startLedger: 1000,
+   *   endLedger: 2000,
+   *   limit: 100
+   * };
+   *
+   * @example
+   * // ✅ Correct: Cursor pagination mode
+   * const cursorRequest: GetEventsRequest = {
+   *   filters: [],
+   *   cursor: "some-cursor-value",
+   *   limit: 100
+   * };
+   *
+   * @example
+   * // ❌ Invalid: Cannot mix cursor with ledger range
+   * const invalidRequest = {
+   *   filters: [],
+   *   startLedger: 1000,  // ❌ Cannot use with cursor
+   *   endLedger: 2000,    // ❌ Cannot use with cursor
+   *   cursor: "cursor",   // ❌ Cannot use with ledger range
+   *   limit: 100
+   * };
+   *
+   * @see {@link https://developers.stellar.org/docs/data/rpc/api-reference/methods/getEvents | getEvents API reference}
+   */
+  export type GetEventsRequest =
+    | {
+        filters: Api.EventFilter[];
+        startLedger: number;
+        endLedger: number;
+        cursor?: never; // explicitly exclude cursor
+        limit?: number;
+      }
+    | {
+        filters: Api.EventFilter[];
+        cursor: string;
+        startLedger?: never; // explicitly exclude startLedger
+        endLedger?: never; // explicitly exclude endLedger
+        limit?: number;
+      };
+
   export interface GetEventsResponse extends RetentionState {
     events: EventResponse[];
     cursor: string;
@@ -508,4 +560,94 @@ export namespace Api {
       liveUntilLedgerSeq?: number;
     };
   }
+
+  /**
+   * Request parameters for fetching a sequential list of ledgers.
+   *
+   * This type supports two distinct pagination modes that are mutually exclusive:
+   * - **Ledger-based pagination**: Use `startLedger` to begin fetching from a specific ledger sequence
+   * - **Cursor-based pagination**: Use `cursor` to continue from a previous response's pagination token
+   *
+   * @typedef {object} GetLedgersRequest
+   * @property {number} [startLedger] - Ledger sequence number to start fetching from (inclusive).
+   *   Must be omitted if cursor is provided. Cannot be less than the oldest ledger or greater
+   *   than the latest ledger stored on the RPC node.
+   * @property {object} [pagination] - Pagination configuration for the request.
+   * @property {string} [pagination.cursor] - Page cursor for continuing pagination from a previous
+   *   response. Must be omitted if startLedger is provided.
+   * @property {number} [pagination.limit=100] - Maximum number of ledgers to return per page.
+   *   Valid range: 1-10000. Defaults to 100 if not specified.
+   *
+   * @example
+   * // Ledger-based pagination - start from specific ledger
+   * const ledgerRequest: GetLedgersRequest = {
+   *   startLedger: 36233,
+   *   pagination: {
+   *     limit: 10
+   *   }
+   * };
+   *
+   * @example
+   * // Cursor-based pagination - continue from previous response
+   * const cursorRequest: GetLedgersRequest = {
+   *   pagination: {
+   *     cursor: "36234",
+   *     limit: 5
+   *   }
+   * };
+   *
+   * @see {@link https://developers.stellar.org/docs/data/rpc/api-reference/methods/getLedgers | getLedgers API reference}
+   */
+  export type GetLedgersRequest =
+    | {
+        startLedger: number;
+        pagination?: {
+          cursor?: never;
+          limit?: number;
+        };
+      }
+    | {
+        startLedger?: never;
+        pagination: {
+          cursor: string;
+          limit?: number;
+        };
+      };
+
+  /** @see https://developers.stellar.org/docs/data/rpc/api-reference/methods/getLedgers */
+  export interface GetLedgersResponse {
+    ledgers: LedgerResponse[];
+    latestLedger: number;
+    latestLedgerCloseTime: number;
+    oldestLedger: number;
+    oldestLedgerCloseTime: number;
+    cursor: string;
+  }
+
+  export interface RawGetLedgersResponse {
+    ledgers: RawLedgerResponse[];
+    latestLedger: number;
+    latestLedgerCloseTime: number;
+    oldestLedger: number;
+    oldestLedgerCloseTime: number;
+    cursor: string;
+  }
+
+  export interface LedgerResponse {
+    hash: string;
+    sequence: number;
+    ledgerCloseTime: string;
+    headerXdr: xdr.LedgerHeaderHistoryEntry;
+    metadataXdr: xdr.LedgerCloseMeta;
+  }
+
+  export interface RawLedgerResponse {
+    hash: string;
+    sequence: number;
+    ledgerCloseTime: string;
+    /** a base-64 encoded {@link xdr.LedgerHeaderHistoryEntry} instance */
+    headerXdr: string;
+    /** a base-64 encoded {@link xdr.LedgerCloseMeta} instance */
+    metadataXdr: string;
+  }
 }

src/rpc/parsers.ts

@@ -267,3 +267,30 @@ export function parseRawSimulation(
 
   return parseSuccessful(sim, base);
 }
+
+export function parseRawLedger(raw: Api.RawLedgerResponse): Api.LedgerResponse {
+  if (!raw.metadataXdr || !raw.headerXdr) {
+    let missingFields: string;
+    if (!raw.metadataXdr && !raw.headerXdr) {
+      missingFields = "metadataXdr and headerXdr";
+    } else if (!raw.metadataXdr) {
+      missingFields = "metadataXdr";
+    } else {
+      missingFields = "headerXdr";
+    }
+    throw new TypeError(`invalid ledger missing fields: ${missingFields}`);
+  }
+
+  const metadataXdr = xdr.LedgerCloseMeta.fromXDR(raw.metadataXdr, "base64");
+  const headerXdr = xdr.LedgerHeaderHistoryEntry.fromXDR(
+    raw.headerXdr,
+    "base64",
+  );
+  return {
+    hash: raw.hash,
+    sequence: raw.sequence,
+    ledgerCloseTime: raw.ledgerCloseTime,
+    metadataXdr,
+    headerXdr,
+  };
+}

src/rpc/server.ts

@@ -29,6 +29,7 @@ import {
   parseRawEvents,
   parseRawTransactions,
   parseTransactionInfo,
+  parseRawLedger,
 } from "./parsers";
 import { Utils } from "../utils";
 
@@ -53,15 +54,6 @@ export enum Durability {
   Persistent = "persistent",
 }
 
-/**
- * @typedef {object} GetEventsRequest Describes the complex filter combinations available for event queries.
- * @property {Array.<module:rpc.Api.EventFilter>} filters Filters to use when querying events from the RPC server.
- * @property {number} [startLedger] Ledger number (inclusive) to begin querying events.
- * @property {string} [cursor] Page cursor (exclusive) to begin querying events.
- * @property {number} [limit=100] The maximum number of events that should be returned in the RPC response.
- * @memberof module:rpc.Server
- */
-
 /**
  * @typedef {object} ResourceLeeway Describes additional resource leeways for transaction simulation.
  * @property {number} cpuInstructions Simulate the transaction with more CPU instructions available.
@@ -77,13 +69,11 @@ export enum Durability {
  */
 
 export namespace RpcServer {
-  export interface GetEventsRequest {
-    filters: Api.EventFilter[];
-    startLedger?: number; // either this or cursor
-    endLedger?: number; // either this or cursor
-    cursor?: string; // either this or startLedger
-    limit?: number;
-  }
+  /**
+   * @deprecated Use `Api.GetEventsRequest` instead.
+   * @see {@link Api.GetEventsRequest}
+   */
+  export type GetEventsRequest = Api.GetEventsRequest;
 
   export interface PollingOptions {
     attempts?: number;
@@ -755,20 +745,21 @@ export class RpcServer {
   /**
    * Fetch all events that match a given set of filters.
    *
-   * The given filters (see {@link module:rpc.Api.EventFilter | Api.EventFilter}
+   * The given filters (see {@link Api.EventFilter}
    * for detailed fields) are combined only in a logical OR fashion, and all of
    * the fields in each filter are optional.
    *
    * To page through events, use the `pagingToken` field on the relevant
    * {@link Api.EventResponse} object to set the `cursor` parameter.
    *
-   * @param {module:rpc.Server.GetEventsRequest} request Event filters
+   * @param {Api.GetEventsRequest} request Event filters {@link Api.GetEventsRequest},
    * @returns {Promise<Api.GetEventsResponse>} A paginatable set of the events
    * matching the given event filters
    *
    * @see {@link https://developers.stellar.org/docs/data/rpc/api-reference/methods/getEvents | getEvents docs}
    *
    * @example
+   *
    * server.getEvents({
    *    startLedger: 1000,
    *    endLedger: 2000,
@@ -794,14 +785,14 @@ export class RpcServer {
    */
   // eslint-disable-next-line require-await
   public async getEvents(
-    request: RpcServer.GetEventsRequest,
+    request: Api.GetEventsRequest,
   ): Promise<Api.GetEventsResponse> {
     return this._getEvents(request).then(parseRawEvents);
   }
 
   // eslint-disable-next-line require-await
   public async _getEvents(
-    request: RpcServer.GetEventsRequest,
+    request: Api.GetEventsRequest,
   ): Promise<Api.RawGetEventsResponse> {
     return jsonrpc.postObject(this.serverURL.toString(), "getEvents", {
       filters: request.filters ?? [],
@@ -1279,4 +1270,66 @@ export class RpcServer {
       },
     };
   }
+
+  /**
+   * Fetch a detailed list of ledgers starting from a specified point.
+   *
+   * Returns ledger data with support for pagination as long as the requested
+   * pages fall within the history retention of the RPC provider.
+   *
+   * @param {Api.GetLedgersRequest} request - The request parameters for fetching ledgers. {@link Api.GetLedgersRequest}
+   * @returns {Promise<Api.GetLedgersResponse>} A promise that resolves to the
+   *    ledgers response containing an array of ledger data and pagination info. {@link Api.GetLedgersResponse}
+   *
+   * @throws {Error} If startLedger is less than the oldest ledger stored in this
+   *    node, or greater than the latest ledger seen by this node.
+   *
+   * @see {@link https://developers.stellar.org/docs/data/rpc/api-reference/methods/getLedgers | getLedgers docs}
+   *
+   * @example
+   * // Fetch ledgers starting from a specific sequence number
+   * server.getLedgers({
+   *   startLedger: 36233,
+   *   limit: 10
+   * }).then((response) => {
+   *   console.log("Ledgers:", response.ledgers);
+   *   console.log("Latest Ledger:", response.latestLedger);
+   *   console.log("Cursor:", response.cursor);
+   * });
+   *
+   * @example
+   * // Paginate through ledgers using cursor
+   * const firstPage = await server.getLedgers({
+   *   startLedger: 36233,
+   *   limit: 5
+   * });
+   *
+   * const nextPage = await server.getLedgers({
+   *   cursor: firstPage.cursor,
+   *   limit: 5
+   * });
+   */
+  // eslint-disable-next-line require-await
+  public async getLedgers(
+    request: Api.GetLedgersRequest,
+  ): Promise<Api.GetLedgersResponse> {
+    return this._getLedgers(request).then((raw) => {
+      const result: Api.GetLedgersResponse = {
+        ledgers: (raw.ledgers || []).map(parseRawLedger),
+        latestLedger: raw.latestLedger,
+        latestLedgerCloseTime: raw.latestLedgerCloseTime,
+        oldestLedger: raw.oldestLedger,
+        oldestLedgerCloseTime: raw.oldestLedgerCloseTime,
+        cursor: raw.cursor,
+      };
+      return result;
+    });
+  }
+
+  // eslint-disable-next-line require-await
+  public async _getLedgers(
+    request: Api.GetLedgersRequest,
+  ): Promise<Api.RawGetLedgersResponse> {
+    return jsonrpc.postObject(this.serverURL.toString(), "getLedgers", request);
+  }
 }