@stellar/stellar-sdk 16.0.1 → 16.2.0

package/lib/cjs/rpc/server.js

@@ -61,6 +61,12 @@ function findCreatedAccountSequenceInTransactionMeta(meta) {
   }
   throw new Error("No account created in transaction");
 }
+function contractSpecTypeName(td) {
+  if (td.switch().value === curr_generated.default.ScSpecType.scSpecTypeUdt().value) {
+    return td.udt().name().toString();
+  }
+  return td.switch().name.replace(/^scSpecType/, "");
+}
 class RpcServer {
   serverURL;
   /**
@@ -397,6 +403,35 @@ class RpcServer {
       };
     }
   }
+  /**
+   * Retrieves the deployed contract instance for a given contract ID.
+   *
+   * The instance describes the contract's executable — either a Wasm hash or
+   * the built-in Stellar Asset Contract — along with its instance storage.
+   *
+   * @param contractId - The contract ID (`C...`) to look up
+   * @returns The contract's `xdr.ScContractInstance`
+   * @throws If the contract instance cannot be found on the network.
+   *
+   * @example
+   * ```ts
+   * const instance = await server.getContractInstance(
+   *   "CCJZ5DGASBWQXR5MPFCJXMBI333XE5U3FSJTNQU7RIKE3P5GN2K2WYD5",
+   * );
+   * console.log(instance.executable().switch().name);
+   * ```
+   */
+  async getContractInstance(contractId) {
+    const contractLedgerKey = new contract.Contract(contractId).getFootprint();
+    const response = await this.getLedgerEntries(contractLedgerKey);
+    if (!response.entries.length || !response.entries[0]?.val) {
+      return Promise.reject({
+        code: 404,
+        message: "Could not obtain contract instance from server"
+      });
+    }
+    return response.entries[0].val.contractData().val().instance();
+  }
   /**
    * Retrieves the WASM bytecode for a given contract.
    *
@@ -404,10 +439,14 @@ class RpcServer {
    * deployed on the Soroban network. The WASM bytecode represents the executable
    * code of the contract.
    *
+   * This only works for Wasm-based contracts. A built-in Stellar Asset Contract
+   * (SAC) has no Wasm bytecode on-chain, so this throws for a SAC; use
+   * {@link contract.Client.from} to build a client from the embedded SAC spec.
+   *
    * @param contractId - The contract ID containing the WASM bytecode to retrieve
    * @returns A Buffer containing the WASM bytecode
    * @throws If the contract or its associated WASM bytecode cannot be
-   * found on the network.
+   * found on the network, or if the contract is a Stellar Asset Contract (SAC).
    *
    * @example
    * ```ts
@@ -421,16 +460,14 @@ class RpcServer {
    * ```
    */
   async getContractWasmByContractId(contractId) {
-    const contractLedgerKey = new contract.Contract(contractId).getFootprint();
-    const response = await this.getLedgerEntries(contractLedgerKey);
-    if (!response.entries.length || !response.entries[0]?.val) {
+    const instance = await this.getContractInstance(contractId);
+    if (instance.executable().switch() === curr_generated.default.ContractExecutableType.contractExecutableStellarAsset()) {
       return Promise.reject({
-        code: 404,
-        message: `Could not obtain contract hash from server`
+        code: 400,
+        message: `Contract ${contractId} is a Stellar Asset Contract (SAC), which has no Wasm bytecode. Use contract.Client.from() to build a client from the built-in SAC spec instead.`
       });
     }
-    const wasmHash = response.entries[0].val.contractData().val().instance().executable().wasmHash();
-    return this.getContractWasmByHash(wasmHash);
+    return this.getContractWasmByHash(instance.executable().wasmHash());
   }
   /**
    * Retrieves the WASM bytecode for a given contract hash.
@@ -472,6 +509,124 @@ class RpcServer {
     const wasmBuffer = responseWasm.entries[0].val.contractCode().code();
     return wasmBuffer;
   }
+  /**
+   * Performs a read-only call to a contract method and returns the decoded result.
+   *
+   * This is a convenience wrapper for one-line contract state queries: it builds
+   * a {@link contract.Client} for the contract, simulates the method call, and
+   * returns the spec-decoded return value — no manual transaction assembly,
+   * signing, or submission required.
+   *
+   * Works for both Wasm contracts and built-in Stellar Asset Contracts (SACs):
+   * the embedded SAC spec is used automatically for SACs (see
+   * {@link contract.Client.from}). The query reuses this server's transport
+   * (headers, interceptors, `allowHttp`).
+   *
+   * @typeParam T - the expected (decoded) return type of the method
+   * @param contractId - the contract to query (`C...`)
+   * @param method - the contract method to call
+   * @param args - named arguments for the method, keyed by parameter name
+   *    (omit for methods that take no arguments)
+   * @param networkPassphrase - (optional) the network passphrase. If omitted, a
+   *    request about network information will be made (see {@link getNetwork}).
+   *    You can refer to {@link Networks} for a list of built-in passphrases,
+   *    e.g., `Networks.TESTNET`.
+   * @returns An object with the method's decoded return value (`result`) and
+   *    `isReadCall`: whether this specific call is a side-effect-free read that
+   *    needs no signature (it wrote no state and required no authorization).
+   *    `isReadCall` is per-call, not per-method: it reflects the given `args`.
+   *    Since `queryContract` never signs or sends, `isReadCall: false` means the
+   *    `result` is a simulation preview of a call that would change state.
+   * @throws If the contract has no such method, or if the simulation fails.
+   *
+   * @example
+   * ```ts
+   * const { result: decimals, isReadCall } = await server.queryContract<number>(
+   *   "CCJZ5DGASBWQXR5MPFCJXMBI333XE5U3FSJTNQU7RIKE3P5GN2K2WYD5",
+   *   "decimals",
+   * );
+   * const { result: balance } = await server.queryContract<bigint>(
+   *   "CCJZ5DGASBWQXR5MPFCJXMBI333XE5U3FSJTNQU7RIKE3P5GN2K2WYD5",
+   *   "balance",
+   *   { id: "GA7QYNF7SOWQ3GLR2BGMZEHXAVIRZA4KVWLTJJFC7MGXUA74P7UJVSGZ" },
+   * );
+   * ```
+   */
+  async queryContract(contractId, method, args = {}, networkPassphrase) {
+    const passphrase = networkPassphrase ?? (await this.getNetwork()).passphrase;
+    const { Client } = await Promise.resolve().then(function () { return require('../contract/client.js'); });
+    const client = await Client.from({
+      contractId,
+      rpcUrl: this.serverURL.toString(),
+      networkPassphrase: passphrase,
+      server: this
+    });
+    const isContractMethod = client.spec.funcs().some((fn) => fn.name().toString() === method);
+    const { sanitizeIdentifier } = await Promise.resolve().then(function () { return require('../bindings/utils.js'); });
+    const invoke = client[sanitizeIdentifier(method)];
+    if (!isContractMethod || typeof invoke !== "function") {
+      throw new TypeError(`Contract ${contractId} has no method '${method}'`);
+    }
+    const assembled = await invoke(args);
+    return { result: assembled.result, isReadCall: assembled.isReadCall };
+  }
+  /**
+   * Lists a contract's callable methods and their signatures.
+   *
+   * A discovery helper for tooling, dapps, and agents that need to inspect an
+   * arbitrary contract without knowing its interface up front. It resolves the
+   * contract's spec (embedded in the Wasm for regular contracts, or the
+   * built-in spec for Stellar Asset Contracts — see {@link contract.Client.from})
+   * and reports each declared function's name, inputs, and outputs. No method
+   * is invoked or simulated; this performs only the spec lookup.
+   *
+   * The complement to {@link queryContract}: list methods here, then call a
+   * read-only one with `server.queryContract(contractId, method, args?)`.
+   *
+   * @param contractId - the contract to inspect (`C...`)
+   * @param networkPassphrase - (optional) the network passphrase. If omitted, a
+   *    request about network information will be made (see {@link getNetwork}).
+   *    You can refer to {@link Networks} for a list of built-in passphrases,
+   *    e.g., `Networks.TESTNET`.
+   * @returns The contract's methods, in the order they appear in the spec
+   *
+   * @example
+   * ```ts
+   * const methods = await server.getContractMethods(
+   *   "CCJZ5DGASBWQXR5MPFCJXMBI333XE5U3FSJTNQU7RIKE3P5GN2K2WYD5",
+   * );
+   * // [
+   * //   { name: "decimals", inputs: [], outputs: ["U32"] },
+   * //   { name: "balance", inputs: [{ name: "id", type: "Address" }], outputs: ["I128"] },
+   * //   { name: "transfer", inputs: [...], outputs: [] },
+   * // ]
+   * ```
+   */
+  async getContractMethods(contractId, networkPassphrase) {
+    const passphrase = networkPassphrase ?? (await this.getNetwork()).passphrase;
+    const { Client } = await Promise.resolve().then(function () { return require('../contract/client.js'); });
+    const client = await Client.from({
+      contractId,
+      rpcUrl: this.serverURL.toString(),
+      networkPassphrase: passphrase,
+      server: this
+    });
+    return client.spec.funcs().map((fn) => {
+      const doc = fn.doc().toString();
+      const method = {
+        name: fn.name().toString(),
+        inputs: fn.inputs().map((input) => ({
+          name: input.name().toString(),
+          type: contractSpecTypeName(input.type())
+        })),
+        outputs: fn.outputs().map(contractSpecTypeName)
+      };
+      if (doc) {
+        method.doc = doc;
+      }
+      return method;
+    });
+  }
   /**
    * Reads the current value of arbitrary ledger entries directly.
    *
@@ -798,6 +953,15 @@ class RpcServer {
    *    auth mode to use for simulation: `enforce` for enforcement mode,
    *    `record` for recording mode, or `record_allow_nonroot` for recording
    *    mode that allows non-root authorization
+   * @param useUpgradedAuth - (optional) opt simulation into recording
+   *    v2 address credentials (CAP-71) instead of the legacy v1 address
+   *    credentials. Best-effort: it only affects the recording auth modes and
+   *    is silently ignored on protocol versions whose host cannot emit v2
+   *    credentials.
+   *
+   *    **Deprecated**: this flag is transitional. Once the network returns v2
+   *    credentials by default (protocol 28), it becomes a no-op — do not rely
+   *    on omitting it to keep receiving the legacy v1 format.
    *
    * @returns An object with the
    *    cost, footprint, result/auth requirements (if applicable), and error of
@@ -837,12 +1001,15 @@ class RpcServer {
    * });
    * ```
    */
-  async simulateTransaction(tx, addlResources, authMode) {
-    return this._simulateTransaction(tx, addlResources, authMode).then(
-      parsers.parseRawSimulation
-    );
+  async simulateTransaction(tx, addlResources, authMode, useUpgradedAuth) {
+    return this._simulateTransaction(
+      tx,
+      addlResources,
+      authMode,
+      useUpgradedAuth
+    ).then(parsers.parseRawSimulation);
   }
-  async _simulateTransaction(transaction, addlResources, authMode) {
+  async _simulateTransaction(transaction, addlResources, authMode, useUpgradedAuth) {
     return jsonrpc.postObject(
       this.httpClient,
       this.serverURL.toString(),
@@ -850,6 +1017,7 @@ class RpcServer {
       {
         transaction: transaction.toXDR(),
         authMode,
+        ...useUpgradedAuth !== void 0 && { useUpgradedAuth },
         ...addlResources !== void 0 && {
           resourceConfig: {
             instructionLeeway: addlResources.cpuInstructions