From e2707c497c64713f1448837ccaf5a7bd9c161abc Mon Sep 17 00:00:00 2001 From: Elliot Voris Date: Tue, 4 Jun 2024 16:02:37 -0500 Subject: [PATCH] fixes to rpc server links, types, etc. --- src/rpc/api.ts | 13 +++ src/rpc/parsers.ts | 2 + src/rpc/server.ts | 201 +++++++++++++++++++++++------------------ src/rpc/transaction.ts | 6 +- 4 files changed, 129 insertions(+), 93 deletions(-) diff --git a/src/rpc/api.ts b/src/rpc/api.ts index da73c4c14..23a28a4ec 100644 --- a/src/rpc/api.ts +++ b/src/rpc/api.ts @@ -361,3 +361,16 @@ export namespace Api { stateChanges?: RawLedgerEntryChange[]; } } + +/** + * @namespace Api + * @memberof module:rpc + */ + +/** + * @typedef {Object} EventFilter + * @property {('contract' | 'system' | 'diagnostic')} [type] Type of contract event that must match in order for the event to pass through the filter. + * @property {Array.} [contractIds] Contract addresses (`C...`) that must match in order for the event to pass through the filter. + * @property {Array.>} [topics] Array of topics arrays that must match in order for the event to pass through the filter. + * @memberof module:rpc.Api + */ diff --git a/src/rpc/parsers.ts b/src/rpc/parsers.ts index e439bbf18..38412b4e2 100644 --- a/src/rpc/parsers.ts +++ b/src/rpc/parsers.ts @@ -4,6 +4,7 @@ import { Api } from './api'; /** * Parse the response from invoking the `submitTransaction` method of a Soroban RPC server. * @memberof module:rpc + * @private * * @param {Api.RawSendTransactionResponse} raw the raw `submitTransaction` response from the Soroban RPC server to parse * @returns {Api.SendTransactionResponse} transaction response parsed from the Soroban RPC server's response @@ -63,6 +64,7 @@ export function parseRawEvents( /** * Parse and return the retrieved ledger entries, if any, from a raw response from a Soroban RPC server. * @memberof module:rpc + * @private * * @param {Api.RawGetLedgerEntriesResponse} raw he raw `getLedgerEntries` response from the Soroban RPC server to parse * @returns {Api.GetLedgerEntriesResponse} ledger entries parsed from the Soroban RPC server's response diff --git a/src/rpc/server.ts b/src/rpc/server.ts index faa249514..8cb4cb7d5 100644 --- a/src/rpc/server.ts +++ b/src/rpc/server.ts @@ -36,16 +36,38 @@ export const SUBMIT_TRANSACTION_TIMEOUT = 60 * 1000; * @enum {('temporary' | 'persistent')} * @memberof module:rpc * - * @see {@link https://developers.stellar.org/docs/learn/smart-contract-internals/state-archival|State Archival docs} - * @see {@link https://docs.rs/soroban-sdk/latest/soroban_sdk/storage/struct.Storage.html|Rust SDK Storage docs} + * @see {@link https://developers.stellar.org/docs/learn/smart-contract-internals/state-archival | State Archival docs} + * @see {@link https://docs.rs/soroban-sdk/latest/soroban_sdk/storage/struct.Storage.html | Rust SDK Storage docs} */ export enum Durability { Temporary = 'temporary', Persistent = 'persistent' } +/** + * @typedef {Object} GetEventsRequest Describes the complex filter combinations available for event queries. + * @property {Array.} 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. + * @memberof module:rpc.Server + */ + +/** + * @typedef {Object} Options Options for configuring connections to RPC servers. + * @property {boolean} [allowHttp=false] Allow connecting to http servers, default: `false`. This must be set to false in production deployments! + * @property {number} [timeout=0] Allow a timeout, default: 0. Allows user to avoid nasty lag. You can also use {@link Config} class to set this globally. + * @property {Record} [headers] Additional headers that should be added to any requests to the RPC server. + * @memberof module:rpc.Server + */ + export namespace Server { - /** Describes the complex filter combinations available for event queries. */ export interface GetEventsRequest { filters: Api.EventFilter[]; startLedger?: number; // either this or cursor @@ -53,7 +75,6 @@ export namespace Server { limit?: number; } - /** Describes additional resource leeways for transaction simulation. */ export interface ResourceLeeway { cpuInstructions: number; } @@ -72,21 +93,23 @@ export namespace Server { * @constructor * @memberof module:rpc * - * @param {string} serverURL Soroban-RPC Server URL (ex. - * `http://localhost:8000/soroban/rpc`). - * @param {Server.Options} [opts] Options object - * @param {boolean} [opts.allowHttp] allows connecting to insecure http servers + * @param {string} serverURL Soroban-RPC Server URL (ex. `http://localhost:8000/soroban/rpc`). + * @param {module:rpc.Server.Options} [opts] Options object + * @param {boolean} [opts.allowHttp] Allows connecting to insecure http servers * (default: `false`). This must be set to false in production deployments! * You can also use {@link Config} class to set this globally. - * @param {Record} [opts.headers] allows setting custom headers + * @param {Record} [opts.headers] Allows setting custom headers * - * @see https://developers.stellar.org/network/soroban-rpc/api-reference/methods + * @see {@link https://developers.stellar.org/network/soroban-rpc/api-reference/methods | API reference docs} */ export class Server { - /** Soroban RPC Server URL (ex. `http://localhost:8000/soroban/rpc`). */ public readonly serverURL: URI; constructor(serverURL: string, opts: Server.Options = {}) { + /** + * RPC Server URL (ex. `http://localhost:8000/soroban/rpc`). + * @member {URI} + */ this.serverURL = URI(serverURL); if (opts.headers && Object.keys(opts.headers).length === 0) { @@ -110,12 +133,12 @@ export class Server { * Needed to get the current sequence number for the account so you can build * a successful transaction with {@link TransactionBuilder}. * - * @param {string} address - The public address of the account to load. + * @param {string} address The public address of the account to load. + * @returns {Promise} A promise which resolves to the {@link Account} + * object with a populated sequence number * - * @returns {Promise} a promise to the {@link Account} object with - * a populated sequence number + * @see {@link https://developers.stellar.org/network/soroban-rpc/api-reference/methods/getLedgerEntries | getLedgerEntries docs} * - * @see https://developers.stellar.org/network/soroban-rpc/api-reference/methods/getLedgerEntries * @example * const accountId = "GBZC6Y2Y7Q3ZQ2Y4QZJ2XZ3Z5YXZ6Z7Z2Y4QZJ2XZ3Z5YXZ6Z7Z2Y4"; * server.getAccount(accountId).then((account) => { @@ -144,11 +167,12 @@ export class Server { /** * General node health check. * - * @returns {Promise} a promise to the - * {@link Api.GetHealthResponse} object with the status of the - * server (e.g. "healthy"). + * @returns {Promise} A promise which resolves to the + * {@link Api.GetHealthResponse} object with the status of the + * server (e.g. "healthy"). + * + * @see {@link https://developers.stellar.org/network/soroban-rpc/api-reference/methods/getHealth | getLedgerEntries docs} * - * @see https://developers.stellar.org/network/soroban-rpc/api-reference/methods/getHealth * @example * server.getHealth().then((health) => { * console.log("status:", health.status); @@ -166,22 +190,22 @@ export class Server { * * Allows you to directly inspect the current state of a contract. This is a * backup way to access your contract data which may not be available via - * events or {@link SorobanRpc.Server#simulateTransaction}. + * events or {@link module:rpc.Server#simulateTransaction}. * - * @param {string|Address|Contract} contract the contract ID containing the + * @param {string|Address|Contract} contract The contract ID containing the * data to load as a strkey (`C...` form), a {@link Contract}, or an * {@link Address} instance - * @param {xdr.ScVal} key the key of the contract data to load - * @param {Durability} [durability=Durability.Persistent] the "durability + * @param {xdr.ScVal} key The key of the contract data to load + * @param {module:rpc.Durability} [durability=Durability.Persistent] The "durability * keyspace" that this ledger key belongs to, which is either 'temporary' - * or 'persistent' (the default), see {@link Durability}. - * - * @returns {Promise} the current data value + * or 'persistent' (the default), see {@link module:rpc.Durability}. + * @returns {Promise} The current data value * * @warning If the data entry in question is a 'temporary' entry, it's * entirely possible that it has expired out of existence. * - * @see https://developers.stellar.org/network/soroban-rpc/api-reference/methods/getLedgerEntries + * @see {@link https://developers.stellar.org/network/soroban-rpc/api-reference/methods/getLedgerEntries | getLedgerEntries docs} + * * @example * const contractId = "CCJZ5DGASBWQXR5MPFCJXMBI333XE5U3FSJTNQU7RIKE3P5GN2K2WYD5"; * const key = xdr.ScVal.scvSymbol("counter"); @@ -256,13 +280,10 @@ export class Server { * deployed on the Soroban network. The WASM bytecode represents the executable * code of the contract. * - * @param {string} contractId the contract ID containing the - * WASM bytecode to retrieve - * - * @returns {Promise} a Buffer containing the WASM bytecode - * + * @param {string} contractId The contract ID containing the WASM bytecode to retrieve + * @returns {Promise} A Buffer containing the WASM bytecode * @throws {Error} If the contract or its associated WASM bytecode cannot be - * found on the network. + * found on the network. * * @example * const contractId = "CCJZ5DGASBWQXR5MPFCJXMBI333XE5U3FSJTNQU7RIKE3P5GN2K2WYD5"; @@ -299,12 +320,10 @@ export class Server { * deployed on the Soroban network using the contract's WASM hash. The WASM bytecode * represents the executable code of the contract. * - * @param {Buffer} wasmHash the WASM hash of the contract - * - * @returns {Promise} a Buffer containing the WASM bytecode - * + * @param {Buffer} wasmHash The WASM hash of the contract + * @returns {Promise} A Buffer containing the WASM bytecode * @throws {Error} If the contract or its associated WASM bytecode cannot be - * found on the network. + * found on the network. * * @example * const wasmHash = Buffer.from("..."); @@ -346,13 +365,12 @@ export class Server { * {@link xdr.LedgerKeyContractCode} ledger entry key (or see * {@link Contract.getFootprint}). * - * @param {xdr.ScVal[]} keys one or more ledger entry keys to load + * @param {xdr.ScVal[]} keys One or more ledger entry keys to load + * @returns {Promise} The current on-chain + * values for the given ledger keys * - * @returns {Promise} the current - * on-chain values for the given ledger keys + * @see {@link https://developers.stellar.org/network/soroban-rpc/api-reference/methods/getLedgerEntries | getLedgerEntries docs} * - * @see Server._getLedgerEntries - * @see https://developers.stellar.org/network/soroban-rpc/api-reference/methods/getLedgerEntries * @example * const contractId = "CAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAD2KM"; * const key = xdr.LedgerKey.contractData(new xdr.LedgerKeyContractData({ @@ -391,12 +409,12 @@ export class Server { * After submitting a transaction, clients should poll this to tell when the * transaction has completed. * - * @param {string} hash hex-encoded hash of the transaction to check - * - * @returns {Promise} the status, + * @param {string} hash Hex-encoded hash of the transaction to check + * @returns {Promise} The status, * result, and other details about the transaction * - * @see https://developers.stellar.org/network/soroban-rpc/api-reference/methods/getTransaction + * @see {@link https://developers.stellar.org/network/soroban-rpc/api-reference/methods/getTransaction | getTransaction docs} + * * @example * const transactionHash = "c4515e3bdc0897f21cc5dbec8c82cf0a936d4741cb74a8e158eb51b9fb00411a"; * server.getTransaction(transactionHash).then((tx) => { @@ -458,18 +476,19 @@ export class Server { /** * Fetch all events that match a given set of filters. * - * 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. + * The given filters (see {@link module:rpc.Api.EventFilter | 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 {Server.GetEventsRequest} request event filters - * @returns {Promise} a paginatable set of the - * events matching the given event filters + * @param {module:rpc.Server.GetEventsRequest} request Event filters + * @returns {Promise} A paginatable set of the events + * matching the given event filters + * + * @see {@link https://developers.stellar.org/network/soroban-rpc/api-reference/methods/getEvents | getEvents docs} * - * @see https://developers.stellar.org/network/soroban-rpc/api-reference/methods/getEvents * @example * server.getEvents({ * startLedger: 1000, @@ -517,10 +536,11 @@ export class Server { /** * Fetch metadata about the network this Soroban RPC server is connected to. * - * @returns {Promise} metadata about the - * current network this RPC server is connected to + * @returns {Promise} Metadata about the current + * network this RPC server is connected to + * + * @see {@link https://developers.stellar.org/network/soroban-rpc/api-reference/methods/getNetwork | getNetwork docs} * - * @see https://developers.stellar.org/network/soroban-rpc/api-reference/methods/getNetwork * @example * server.getNetwork().then((network) => { * console.log("friendbotUrl:", network.friendbotUrl); @@ -539,7 +559,8 @@ export class Server { * @returns {Promise} metadata about the * latest ledger on the network that this RPC server is connected to * - * @see https://developers.stellar.org/network/soroban-rpc/api-reference/methods/getLatestLedger + * @see {@link https://developers.stellar.org/network/soroban-rpc/api-reference/methods/getLatestLedger | getLatestLedger docs} + * * @example * server.getLatestLedger().then((response) => { * console.log("hash:", response.id); @@ -555,20 +576,19 @@ export class Server { * Submit a trial contract invocation to get back return values, expected * ledger footprint, expected authorizations, and expected costs. * - * @param {Transaction | FeeBumpTransaction} transaction the transaction to + * @param {Transaction | FeeBumpTransaction} transaction The transaction to * simulate, which should include exactly one operation (one of * {@link xdr.InvokeHostFunctionOp}, {@link xdr.ExtendFootprintTTLOp}, or * {@link xdr.RestoreFootprintOp}). Any provided footprint or auth * information will be ignored. - * - * @returns {Promise} an object with the + * @returns {Promise} An object with the * cost, footprint, result/auth requirements (if applicable), and error of * the transaction * - * @see https://developers.stellar.org/docs/glossary/transactions/ - * @see https://developers.stellar.org/network/soroban-rpc/api-reference/methods/simulateTransaction - * @see Server.prepareTransaction - * @see assembleTransaction + * @see {@link https://developers.stellar.org/docs/learn/fundamentals/stellar-data-structures/operations-and-transactions | transaction docs} + * @see {@link https://developers.stellar.org/network/soroban-rpc/api-reference/methods/simulateTransaction | simulateTransaction docs} + * @see module:rpc.Server#prepareTransaction + * @see module:rpc.assembleTransaction * * @example * const contractId = 'CA3D5KRYM6CB7OWQ6TWYRR3Z4T7GNZLKERYNZGGA5SOAOPIFY6YQGAXE'; @@ -628,15 +648,16 @@ export class Server { * * The returned transaction will also have an updated fee that is the sum of * fee set on incoming transaction with the contract resource fees estimated - * from simulation. It is adviseable to check the fee on returned transaction + * from simulation. It is advisable to check the fee on returned transaction * and validate or take appropriate measures for interaction with user to * confirm it is acceptable. * - * You can call the {@link SorobanRpc.Server#simulateTransaction} method directly first - * if you want to inspect estimated fees for a given transaction in detail - * first, then re-assemble it manually or via {@link assembleTransaction}. + * You can call the {@link module:rpc.Server#simulateTransaction} method + * directly first if you want to inspect estimated fees for a given + * transaction in detail first, then re-assemble it manually or via + * {@link module:rpc.assembleTransaction}. * - * @param {Transaction | FeeBumpTransaction} transaction the transaction to + * @param {Transaction | FeeBumpTransaction} transaction The transaction to * prepare. It should include exactly one operation, which must be one of * {@link xdr.InvokeHostFunctionOp}, {@link xdr.ExtendFootprintTTLOp}, * or {@link xdr.RestoreFootprintOp}. @@ -646,17 +667,17 @@ export class Server { * from the simulation. In other words, if you include auth entries, you * don't care about the auth returned from the simulation. Other fields * (footprint, etc.) will be filled as normal. - * - * @returns {Promise} a copy of the + * @returns {Promise} A copy of the * transaction with the expected authorizations (in the case of * invocation), resources, and ledger footprints added. The transaction fee * will also automatically be padded with the contract's minimum resource * fees discovered from the simulation. - * - * @see assembleTransaction - * @see https://developers.stellar.org/network/soroban-rpc/api-reference/methods/simulateTransaction * @throws {jsonrpc.Error|Error|Api.SimulateTransactionErrorResponse} - * if simulation fails + * If simulation fails + * + * @see module:rpc.assembleTransaction + * @see {@link https://developers.stellar.org/network/soroban-rpc/api-reference/methods/simulateTransaction | simulateTransaction docs} + * * @example * const contractId = 'CA3D5KRYM6CB7OWQ6TWYRR3Z4T7GNZLKERYNZGGA5SOAOPIFY6YQGAXE'; * const contract = new StellarSdk.Contract(contractId); @@ -702,15 +723,16 @@ export class Server { * * Unlike Horizon, Soroban RPC does not wait for transaction completion. It * simply validates the transaction and enqueues it. Clients should call - * {@link SorobanRpc.Server#getTransaction} to learn about transaction + * {@link module:rpc.Server#getTransaction} to learn about transaction * success/failure. * * @param {Transaction | FeeBumpTransaction} transaction to submit * @returns {Promise} the * transaction id, status, and any error if available * - * @see https://developers.stellar.org/docs/glossary/transactions/ - * @see https://developers.stellar.org/network/soroban-rpc/api-reference/methods/sendTransaction + * @see {@link https://developers.stellar.org/docs/learn/fundamentals/stellar-data-structures/operations-and-transactions | transaction docs} + * @see {@link https://developers.stellar.org/network/soroban-rpc/api-reference/methods/sendTransaction | sendTransaction docs} + * * @example * const contractId = 'CA3D5KRYM6CB7OWQ6TWYRR3Z4T7GNZLKERYNZGGA5SOAOPIFY6YQGAXE'; * const contract = new StellarSdk.Contract(contractId); @@ -757,24 +779,23 @@ export class Server { } /** - * Fund a new account using the network's friendbot faucet, if any. + * Fund a new account using the network's Friendbot faucet, if any. * - * @param {string | Account} address the address or account instance that we - * want to create and fund with friendbot - * @param {string} [friendbotUrl] optionally, an explicit address for + * @param {string | Account} address The address or account instance that we + * want to create and fund with Friendbot + * @param {string} [friendbotUrl] Optionally, an explicit address for * friendbot (by default: this calls the Soroban RPC - * {@link SorobanRpc.Server#getNetwork} method to try to discover this network's - * Friendbot url). - * - * @returns {Promise} an {@link Account} object for the created + * {@link module:rpc.Server#getNetwork | getNetwork} method to try to + * discover this network's Friendbot url). + * @returns {Promise} An {@link Account} object for the created * account, or the existing account if it's already funded with the * populated sequence number (note that the account will not be "topped * off" if it already exists) + * @throws If Friendbot is not configured on this network or request failure * - * @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 module:Friendbot.Api.Response} * - * @see https://developers.stellar.org/docs/fundamentals-and-concepts/testnet-and-pubnet#friendbot - * @see Friendbot.Response * @example * server * .requestAirdrop("GBZC6Y2Y7Q3ZQ2Y4QZJ2XZ3Z5YXZ6Z7Z2Y4QZJ2XZ3Z5YXZ6Z7Z2Y4") diff --git a/src/rpc/transaction.ts b/src/rpc/transaction.ts index f6e24c269..b73a05307 100644 --- a/src/rpc/transaction.ts +++ b/src/rpc/transaction.ts @@ -16,12 +16,12 @@ import { parseRawSimulation } from './parsers'; * entries are ignored**. * * @param {Transaction|FeeBumpTransaction} raw the initial transaction, w/o simulation applied - * @param {Api.SimulateTransactionResponse|Api.RawSimulateTransactionResponse} simulation the Soroban RPC simulation result (see {@link rpc.Server#simulateTransaction}) + * @param {Api.SimulateTransactionResponse|Api.RawSimulateTransactionResponse} simulation the Soroban RPC simulation result (see {@link module:rpc.Server#simulateTransaction}) * @returns {TransactionBuilder} a new, cloned transaction with the proper auth and resource (fee, footprint) simulation data applied * * @memberof module:rpc - * @see {@link rpc.Server#simulateTransaction} - * @see {@link rpc.Server#prepareTransaction} + * @see {@link module:rpc.Server#simulateTransaction} + * @see {@link module:rpc.Server#prepareTransaction} */ export function assembleTransaction( raw: Transaction | FeeBumpTransaction,