@stellar/stellar-sdk 14.1.1 → 14.3.0

package/lib/rpc/server.d.ts

@@ -1,6 +1,6 @@
-import URI from 'urijs';
-import { Account, Address, Asset, Contract, FeeBumpTransaction, Transaction, xdr } from '@stellar/stellar-base';
-import { Api } from './api';
+import URI from "urijs";
+import { Account, Address, Asset, Contract, FeeBumpTransaction, Transaction, xdr } from "@stellar/stellar-base";
+import { Api } from "./api";
 /**
  * Default transaction submission timeout for RPC requests, in milliseconds
  * @constant {number}
@@ -20,14 +20,6 @@ export declare enum Durability {
     Temporary = "temporary",
     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.
@@ -41,13 +33,11 @@ export declare enum Durability {
  * @memberof module:rpc.Server
  */
 export declare namespace RpcServer {
-    interface GetEventsRequest {
-        filters: Api.EventFilter[];
-        startLedger?: number;
-        endLedger?: number;
-        cursor?: string;
-        limit?: number;
-    }
+    /**
+     * @deprecated Use `Api.GetEventsRequest` instead.
+     * @see {@link Api.GetEventsRequest}
+     */
+    type GetEventsRequest = Api.GetEventsRequest;
     interface PollingOptions {
         attempts?: number;
         sleepStrategy?: SleepStrategy;
@@ -106,6 +96,66 @@ export declare class RpcServer {
      * });
      */
     getAccount(address: string): Promise<Account>;
+    /**
+     * Fetch the full account entry for a Stellar account.
+     *
+     * @param {string} address The public address of the account to load.
+     * @returns {Promise<xdr.AccountEntry>} Resolves to the full on-chain account
+     *    entry
+     *
+     * @see
+     * {@link https://developers.stellar.org/docs/data/rpc/api-reference/methods/getLedgerEntries | getLedgerEntries docs}
+     *
+     * @example
+     * const accountId = "GBZC6Y2Y7Q3ZQ2Y4QZJ2XZ3Z5YXZ6Z7Z2Y4QZJ2XZ3Z5YXZ6Z7Z2Y4";
+     * server.getAccountEntry(accountId).then((account) => {
+     *   console.log("sequence:", account.balance().toString());
+     * });
+     */
+    getAccountEntry(address: string): Promise<xdr.AccountEntry>;
+    /**
+     * Fetch the full trustline entry for a Stellar account.
+     *
+     * @param {string} account  The public address of the account whose trustline it is
+     * @param {string} asset    The trustline's asset
+     * @returns {Promise<xdr.TrustLineEntry>} Resolves to the full on-chain trustline
+     *    entry
+     *
+     * @see
+     * {@link https://developers.stellar.org/docs/data/rpc/api-reference/methods/getLedgerEntries | getLedgerEntries docs}
+     *
+     * @example
+     * const accountId = "GBZC6Y2Y7Q3ZQ2Y4QZJ2XZ3Z5YXZ6Z7Z2Y4QZJ2XZ3Z5YXZ6Z7Z2Y4";
+     * const asset = new Asset(
+     *  "USDC",
+     *  "GBBD47IF6LWK7P7MDEVSCWR7DPUWV3NY3DTQEVFL4NAT4AQH3ZLLFLA5"
+     * );
+     * server.getTrustline(accountId, asset).then((entry) => {
+     *   console.log(`{asset.toString()} balance for ${accountId}:", entry.balance().toString());
+     * });
+     */
+    getTrustline(account: string, asset: Asset): Promise<xdr.TrustLineEntry>;
+    /**
+     * Fetch the full claimable balance entry for a Stellar account.
+     *
+     * @param {string} id   The strkey (`B...`) or hex (`00000000abcde...`) (both
+     *    IDs with and without the 000... version prefix are accepted) of the
+     *    claimable balance to load
+     * @returns {Promise<xdr.ClaimableBalanceEntry>} Resolves to the full on-chain
+     *    claimable balance entry
+     *
+     * @see
+     * {@link https://developers.stellar.org/docs/data/rpc/api-reference/methods/getLedgerEntries | getLedgerEntries docs}
+     *
+     * @example
+     * const id = "00000000178826fbfe339e1f5c53417c6fedfe2c05e8bec14303143ec46b38981b09c3f9";
+     * server.getClaimableBalance(id).then((entry) => {
+     *   console.log(`Claimable balance {id.substr(0, 12)} has:`);
+     *   console.log(`  asset:  ${Asset.fromXDRObject(entry.asset()).toString()}`;
+     *   console.log(`  amount: ${entry.amount().toString()}`;
+     * });
+     */
+    getClaimableBalance(id: string): Promise<xdr.ClaimableBalanceEntry>;
     /**
      * General node health check.
      *
@@ -231,6 +281,7 @@ export declare class RpcServer {
      */
     getLedgerEntries(...keys: xdr.LedgerKey[]): Promise<Api.GetLedgerEntriesResponse>;
     _getLedgerEntries(...keys: xdr.LedgerKey[]): Promise<Api.RawGetLedgerEntriesResponse>;
+    getLedgerEntry(key: xdr.LedgerKey): Promise<Api.LedgerEntryResult>;
     /**
      * Poll for a particular transaction with certain parameters.
      *
@@ -304,20 +355,21 @@ export declare 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,
@@ -341,8 +393,8 @@ export declare class RpcServer {
      *    limit: 10,
      * });
      */
-    getEvents(request: RpcServer.GetEventsRequest): Promise<Api.GetEventsResponse>;
-    _getEvents(request: RpcServer.GetEventsRequest): Promise<Api.RawGetEventsResponse>;
+    getEvents(request: Api.GetEventsRequest): Promise<Api.GetEventsResponse>;
+    _getEvents(request: Api.GetEventsRequest): Promise<Api.RawGetEventsResponse>;
     /**
      * Fetch metadata about the network this Soroban RPC server is connected to.
      *
@@ -563,7 +615,7 @@ export declare class RpcServer {
      *    off" if it already exists)
      * @throws If Friendbot is not configured on this network or request failure
      *
-     * @see {@link https://developers.stellar.org/docs/learn/networks#friendbot | Friendbot docs}
+     * @see {@link https://developers.stellar.org/docs/learn/fundamentals/networks#friendbot | Friendbot docs}
      * @see {@link module:Friendbot.Api.Response}
      *
      * @example
@@ -575,7 +627,7 @@ export declare class RpcServer {
      *      console.error("error:", error);
      *    });
      */
-    requestAirdrop(address: string | Pick<Account, 'accountId'>, friendbotUrl?: string): Promise<Account>;
+    requestAirdrop(address: string | Pick<Account, "accountId">, friendbotUrl?: string): Promise<Account>;
     /**
      * Provides an analysis of the recent fee stats for regular and smart
      * contract operations.
@@ -596,8 +648,8 @@ export declare class RpcServer {
      *
      * This is a convenience wrapper around {@link Server.getLedgerEntries}.
      *
-     * @param {string}  contractId    the contract ID (string `C...`) whose
-     *    balance of `sac` you want to know
+     * @param {string}  address the contract (string `C...`) or account ID
+     *    (`G...`) whose balance of `sac` you want to know
      * @param {Asset}   sac     the built-in SAC token (e.g. `USDC:GABC...`) that
      *    you are querying from the given `contract`.
      * @param {string}  [networkPassphrase] optionally, the network passphrase to
@@ -610,16 +662,16 @@ export declare class RpcServer {
      *    entry details if and only if the request returned a valid balance ledger
      *    entry. If it doesn't, the `balanceEntry` field will not exist.
      *
-     * @throws {TypeError} If `contractId` is not a valid contract strkey (C...).
+     * @throws {TypeError} If `address` is not a valid contract ID (C...).
      *
      * @see getLedgerEntries
      * @see https://developers.stellar.org/docs/tokens/stellar-asset-contract
      *
      * @example
-     * // assume `contractId` is some contract with an XLM balance
+     * // assume `address` is some contract or account with an XLM balance
      * // assume server is an instantiated `Server` instance.
      * const entry = (await server.getSACBalance(
-     *   new Address(contractId),
+     *   new Address(address),
      *   Asset.native(),
      *   Networks.PUBLIC
      * ));
@@ -628,7 +680,47 @@ export declare class RpcServer {
      * console.log(
      *   entry.balanceEntry ?
      *   BigInt(entry.balanceEntry.amount) :
-     *   "Contract has no XLM");
+     *   "Address has no XLM");
+     */
+    getSACBalance(address: string | Address, sac: Asset, networkPassphrase?: string): Promise<Api.BalanceResponse>;
+    /**
+     * 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
+     * });
      */
-    getSACBalance(contractId: string, sac: Asset, networkPassphrase?: string): Promise<Api.BalanceResponse>;
+    getLedgers(request: Api.GetLedgersRequest): Promise<Api.GetLedgersResponse>;
+    _getLedgers(request: Api.GetLedgersRequest): Promise<Api.RawGetLedgersResponse>;
 }