@stellar/stellar-sdk 12.0.0-rc.2 → 12.0.0-rc.3

package/lib/{contract_client → contract}/types.d.ts

@@ -1,4 +1,4 @@
-import { Memo, MemoType, Operation, Transaction, xdr } from "..";
+import { Memo, MemoType, Operation, Transaction, xdr } from "@stellar/stellar-base";
 export type XDR_BASE64 = string;
 export type u32 = number;
 export type i32 = number;
@@ -15,7 +15,7 @@ export type Duration = bigint;
  * A "regular" transaction, as opposed to a FeeBumpTransaction.
  */
 export type Tx = Transaction<Memo<MemoType>, Operation[]>;
-export type ContractClientOptions = {
+export type ClientOptions = {
     /**
      * The public key of the account that will send this transaction. You can
      * override this for specific methods later, like
@@ -59,15 +59,15 @@ export type ContractClientOptions = {
      */
     allowHttp?: boolean;
     /**
-     * This gets filled in automatically from the ContractSpec if you use
-     * {@link ContractClient.generate} to create your ContractClient.
+     * This gets filled in automatically from the ContractSpec when you
+     * instantiate a {@link Client}.
      *
      * Background: If the contract you're calling uses the `#[contracterror]`
      * macro to create an `Error` enum, then those errors get included in the
      * on-chain XDR that also describes your contract's methods. Each error will
      * have a specific number.
      *
-     * A ContractClient makes method calls with an {@link AssembledTransaction}.
+     * A Client makes method calls with an {@link AssembledTransaction}.
      * When one of these method calls encounters an error, `AssembledTransaction`
      * will first attempt to parse the error as an "official" `contracterror`
      * error, by using this passed-in `errorTypes` object. See
@@ -85,15 +85,17 @@ export type MethodOptions = {
      */
     fee?: string;
     /**
-     * The maximum amount of time to wait for the transaction to complete. Default: {@link DEFAULT_TIMEOUT}
+     * The maximum amount of time to wait for the transaction to complete.
+     * Default: {@link DEFAULT_TIMEOUT}
      */
     timeoutInSeconds?: number;
     /**
-     * Whether to automatically simulate the transaction when constructing the AssembledTransaction. Default: true
+     * Whether to automatically simulate the transaction when constructing the
+     * AssembledTransaction. Default: true
      */
     simulate?: boolean;
 };
-export type AssembledTransactionOptions<T = string> = MethodOptions & ContractClientOptions & {
+export type AssembledTransactionOptions<T = string> = MethodOptions & ClientOptions & {
     method: string;
     args?: any[];
     parseResultXdr: (xdr: xdr.ScVal) => T;

package/lib/contract/utils.d.ts

@@ -0,0 +1,40 @@
+import { xdr } from "@stellar/stellar-base";
+/**
+ * The default timeout for waiting for a transaction to be included in a block.
+ */
+export declare const DEFAULT_TIMEOUT: number;
+/**
+ * Keep calling a `fn` for `timeoutInSeconds` seconds, if `keepWaitingIf` is
+ * true. Returns an array of all attempts to call the function.
+ */
+export declare function withExponentialBackoff<T>(
+/** Function to call repeatedly */
+fn: (previousFailure?: T) => Promise<T>, 
+/** Condition to check when deciding whether or not to call `fn` again */
+keepWaitingIf: (result: T) => boolean, 
+/** How long to wait between the first and second call */
+timeoutInSeconds: number, 
+/** What to multiply `timeoutInSeconds` by, each subsequent attempt */
+exponentialFactor?: number, 
+/** Whether to log extra info */
+verbose?: boolean): Promise<T[]>;
+/**
+ * If contracts are implemented using the `#[contracterror]` macro, then the
+ * errors get included in the on-chain XDR that also describes your contract's
+ * methods. Each error will have a specific number. This Regular Expression
+ * matches these "expected error types" that a contract may throw, and helps
+ * {@link AssembledTransaction} parse these errors.
+ */
+export declare const contractErrorPattern: RegExp;
+/**
+ * A TypeScript type guard that checks if an object has a `toString` method.
+ */
+export declare function implementsToString(
+/** some object that may or may not have a `toString` method */
+obj: unknown): obj is {
+    toString(): string;
+};
+/**
+ * Reads a binary stream of ScSpecEntries into an array for processing by ContractSpec
+ */
+export declare function processSpecEntryStream(buffer: Buffer): xdr.ScSpecEntry[];

package/lib/{contract_client → contract}/utils.js

@@ -5,7 +5,9 @@ Object.defineProperty(exports, "__esModule", {
 });
 exports.contractErrorPattern = exports.DEFAULT_TIMEOUT = void 0;
 exports.implementsToString = implementsToString;
+exports.processSpecEntryStream = processSpecEntryStream;
 exports.withExponentialBackoff = withExponentialBackoff;
+var _stellarBase = require("@stellar/stellar-base");
 function _regeneratorRuntime() { "use strict"; _regeneratorRuntime = function _regeneratorRuntime() { return e; }; var t, e = {}, r = Object.prototype, n = r.hasOwnProperty, o = Object.defineProperty || function (t, e, r) { t[e] = r.value; }, i = "function" == typeof Symbol ? Symbol : {}, a = i.iterator || "@@iterator", c = i.asyncIterator || "@@asyncIterator", u = i.toStringTag || "@@toStringTag"; function define(t, e, r) { return Object.defineProperty(t, e, { value: r, enumerable: !0, configurable: !0, writable: !0 }), t[e]; } try { define({}, ""); } catch (t) { define = function define(t, e, r) { return t[e] = r; }; } function wrap(t, e, r, n) { var i = e && e.prototype instanceof Generator ? e : Generator, a = Object.create(i.prototype), c = new Context(n || []); return o(a, "_invoke", { value: makeInvokeMethod(t, r, c) }), a; } function tryCatch(t, e, r) { try { return { type: "normal", arg: t.call(e, r) }; } catch (t) { return { type: "throw", arg: t }; } } e.wrap = wrap; var h = "suspendedStart", l = "suspendedYield", f = "executing", s = "completed", y = {}; function Generator() {} function GeneratorFunction() {} function GeneratorFunctionPrototype() {} var p = {}; define(p, a, function () { return this; }); var d = Object.getPrototypeOf, v = d && d(d(values([]))); v && v !== r && n.call(v, a) && (p = v); var g = GeneratorFunctionPrototype.prototype = Generator.prototype = Object.create(p); function defineIteratorMethods(t) { ["next", "throw", "return"].forEach(function (e) { define(t, e, function (t) { return this._invoke(e, t); }); }); } function AsyncIterator(t, e) { function invoke(r, o, i, a) { var c = tryCatch(t[r], t, o); if ("throw" !== c.type) { var u = c.arg, h = u.value; return h && "object" == _typeof(h) && n.call(h, "__await") ? e.resolve(h.__await).then(function (t) { invoke("next", t, i, a); }, function (t) { invoke("throw", t, i, a); }) : e.resolve(h).then(function (t) { u.value = t, i(u); }, function (t) { return invoke("throw", t, i, a); }); } a(c.arg); } var r; o(this, "_invoke", { value: function value(t, n) { function callInvokeWithMethodAndArg() { return new e(function (e, r) { invoke(t, n, e, r); }); } return r = r ? r.then(callInvokeWithMethodAndArg, callInvokeWithMethodAndArg) : callInvokeWithMethodAndArg(); } }); } function makeInvokeMethod(e, r, n) { var o = h; return function (i, a) { if (o === f) throw Error("Generator is already running"); if (o === s) { if ("throw" === i) throw a; return { value: t, done: !0 }; } for (n.method = i, n.arg = a;;) { var c = n.delegate; if (c) { var u = maybeInvokeDelegate(c, n); if (u) { if (u === y) continue; return u; } } if ("next" === n.method) n.sent = n._sent = n.arg;else if ("throw" === n.method) { if (o === h) throw o = s, n.arg; n.dispatchException(n.arg); } else "return" === n.method && n.abrupt("return", n.arg); o = f; var p = tryCatch(e, r, n); if ("normal" === p.type) { if (o = n.done ? s : l, p.arg === y) continue; return { value: p.arg, done: n.done }; } "throw" === p.type && (o = s, n.method = "throw", n.arg = p.arg); } }; } function maybeInvokeDelegate(e, r) { var n = r.method, o = e.iterator[n]; if (o === t) return r.delegate = null, "throw" === n && e.iterator.return && (r.method = "return", r.arg = t, maybeInvokeDelegate(e, r), "throw" === r.method) || "return" !== n && (r.method = "throw", r.arg = new TypeError("The iterator does not provide a '" + n + "' method")), y; var i = tryCatch(o, e.iterator, r.arg); if ("throw" === i.type) return r.method = "throw", r.arg = i.arg, r.delegate = null, y; var a = i.arg; return a ? a.done ? (r[e.resultName] = a.value, r.next = e.nextLoc, "return" !== r.method && (r.method = "next", r.arg = t), r.delegate = null, y) : a : (r.method = "throw", r.arg = new TypeError("iterator result is not an object"), r.delegate = null, y); } function pushTryEntry(t) { var e = { tryLoc: t[0] }; 1 in t && (e.catchLoc = t[1]), 2 in t && (e.finallyLoc = t[2], e.afterLoc = t[3]), this.tryEntries.push(e); } function resetTryEntry(t) { var e = t.completion || {}; e.type = "normal", delete e.arg, t.completion = e; } function Context(t) { this.tryEntries = [{ tryLoc: "root" }], t.forEach(pushTryEntry, this), this.reset(!0); } function values(e) { if (e || "" === e) { var r = e[a]; if (r) return r.call(e); if ("function" == typeof e.next) return e; if (!isNaN(e.length)) { var o = -1, i = function next() { for (; ++o < e.length;) if (n.call(e, o)) return next.value = e[o], next.done = !1, next; return next.value = t, next.done = !0, next; }; return i.next = i; } } throw new TypeError(_typeof(e) + " is not iterable"); } return GeneratorFunction.prototype = GeneratorFunctionPrototype, o(g, "constructor", { value: GeneratorFunctionPrototype, configurable: !0 }), o(GeneratorFunctionPrototype, "constructor", { value: GeneratorFunction, configurable: !0 }), GeneratorFunction.displayName = define(GeneratorFunctionPrototype, u, "GeneratorFunction"), e.isGeneratorFunction = function (t) { var e = "function" == typeof t && t.constructor; return !!e && (e === GeneratorFunction || "GeneratorFunction" === (e.displayName || e.name)); }, e.mark = function (t) { return Object.setPrototypeOf ? Object.setPrototypeOf(t, GeneratorFunctionPrototype) : (t.__proto__ = GeneratorFunctionPrototype, define(t, u, "GeneratorFunction")), t.prototype = Object.create(g), t; }, e.awrap = function (t) { return { __await: t }; }, defineIteratorMethods(AsyncIterator.prototype), define(AsyncIterator.prototype, c, function () { return this; }), e.AsyncIterator = AsyncIterator, e.async = function (t, r, n, o, i) { void 0 === i && (i = Promise); var a = new AsyncIterator(wrap(t, r, n, o), i); return e.isGeneratorFunction(r) ? a : a.next().then(function (t) { return t.done ? t.value : a.next(); }); }, defineIteratorMethods(g), define(g, u, "Generator"), define(g, a, function () { return this; }), define(g, "toString", function () { return "[object Generator]"; }), e.keys = function (t) { var e = Object(t), r = []; for (var n in e) r.push(n); return r.reverse(), function next() { for (; r.length;) { var t = r.pop(); if (t in e) return next.value = t, next.done = !1, next; } return next.done = !0, next; }; }, e.values = values, Context.prototype = { constructor: Context, reset: function reset(e) { if (this.prev = 0, this.next = 0, this.sent = this._sent = t, this.done = !1, this.delegate = null, this.method = "next", this.arg = t, this.tryEntries.forEach(resetTryEntry), !e) for (var r in this) "t" === r.charAt(0) && n.call(this, r) && !isNaN(+r.slice(1)) && (this[r] = t); }, stop: function stop() { this.done = !0; var t = this.tryEntries[0].completion; if ("throw" === t.type) throw t.arg; return this.rval; }, dispatchException: function dispatchException(e) { if (this.done) throw e; var r = this; function handle(n, o) { return a.type = "throw", a.arg = e, r.next = n, o && (r.method = "next", r.arg = t), !!o; } for (var o = this.tryEntries.length - 1; o >= 0; --o) { var i = this.tryEntries[o], a = i.completion; if ("root" === i.tryLoc) return handle("end"); if (i.tryLoc <= this.prev) { var c = n.call(i, "catchLoc"), u = n.call(i, "finallyLoc"); if (c && u) { if (this.prev < i.catchLoc) return handle(i.catchLoc, !0); if (this.prev < i.finallyLoc) return handle(i.finallyLoc); } else if (c) { if (this.prev < i.catchLoc) return handle(i.catchLoc, !0); } else { if (!u) throw Error("try statement without catch or finally"); if (this.prev < i.finallyLoc) return handle(i.finallyLoc); } } } }, abrupt: function abrupt(t, e) { for (var r = this.tryEntries.length - 1; r >= 0; --r) { var o = this.tryEntries[r]; if (o.tryLoc <= this.prev && n.call(o, "finallyLoc") && this.prev < o.finallyLoc) { var i = o; break; } } i && ("break" === t || "continue" === t) && i.tryLoc <= e && e <= i.finallyLoc && (i = null); var a = i ? i.completion : {}; return a.type = t, a.arg = e, i ? (this.method = "next", this.next = i.finallyLoc, y) : this.complete(a); }, complete: function complete(t, e) { if ("throw" === t.type) throw t.arg; return "break" === t.type || "continue" === t.type ? this.next = t.arg : "return" === t.type ? (this.rval = this.arg = t.arg, this.method = "return", this.next = "end") : "normal" === t.type && e && (this.next = e), y; }, finish: function finish(t) { for (var e = this.tryEntries.length - 1; e >= 0; --e) { var r = this.tryEntries[e]; if (r.finallyLoc === t) return this.complete(r.completion, r.afterLoc), resetTryEntry(r), y; } }, catch: function _catch(t) { for (var e = this.tryEntries.length - 1; e >= 0; --e) { var r = this.tryEntries[e]; if (r.tryLoc === t) { var n = r.completion; if ("throw" === n.type) { var o = n.arg; resetTryEntry(r); } return o; } } throw Error("illegal catch attempt"); }, delegateYield: function delegateYield(e, r, n) { return this.delegate = { iterator: values(e), resultName: r, nextLoc: n }, "next" === this.method && (this.arg = t), y; } }, e; }
 function _typeof(o) { "@babel/helpers - typeof"; return _typeof = "function" == typeof Symbol && "symbol" == typeof Symbol.iterator ? function (o) { return typeof o; } : function (o) { return o && "function" == typeof Symbol && o.constructor === Symbol && o !== Symbol.prototype ? "symbol" : typeof o; }, _typeof(o); }
 function asyncGeneratorStep(gen, resolve, reject, _next, _throw, key, arg) { try { var info = gen[key](arg); var value = info.value; } catch (error) { reject(error); return; } if (info.done) { resolve(value); } else { Promise.resolve(value).then(_next, _throw); } }
@@ -51,7 +53,7 @@ function _withExponentialBackoff() {
             _context.next = 30;
             break;
           }
-          count++;
+          count += 1;
           if (verbose) {
             console.info("Waiting ".concat(waitTime, "ms before trying again (bringing the total wait time to ").concat(totalWaitTime, "ms so far, of total ").concat(timeoutInSeconds * 1000, "ms)"));
           }
@@ -60,7 +62,7 @@ function _withExponentialBackoff() {
             return setTimeout(res, waitTime);
           });
         case 19:
-          waitTime = waitTime * exponentialFactor;
+          waitTime *= exponentialFactor;
           if (new Date(Date.now() + waitTime).valueOf() > waitUntil) {
             waitTime = waitUntil - Date.now();
             if (verbose) {
@@ -92,4 +94,12 @@ function _withExponentialBackoff() {
 var contractErrorPattern = exports.contractErrorPattern = /Error\(Contract, #(\d+)\)/;
 function implementsToString(obj) {
   return _typeof(obj) === "object" && obj !== null && "toString" in obj;
+}
+function processSpecEntryStream(buffer) {
+  var reader = new _stellarBase.cereal.XdrReader(buffer);
+  var res = [];
+  while (!reader.eof) {
+    res.push(_stellarBase.xdr.ScSpecEntry.read(reader));
+  }
+  return res;
 }

package/lib/index.d.ts

@@ -6,8 +6,32 @@ export * as Federation from './federation';
 export * as WebAuth from './webauth';
 export * as Friendbot from './friendbot';
 export * as Horizon from './horizon';
-export * as SorobanRpc from './soroban';
-export * from './contract_spec';
+/**
+ * Tools for interacting with the Soroban RPC server, such as `Server`,
+ * `assembleTransaction`, and the `Api` types. You can import these from the
+ * `/rpc` entrypoint, if your version of Node and your TypeScript configuration
+ * allow it:
+ *
+ * ```ts
+ * import { Server } from '@stellar/stellar-sdk/rpc';
+ * ```
+ */
+export * as rpc from './rpc';
+/**
+ * @deprecated Use `rpc` instead
+ */
+export * as SorobanRpc from './rpc';
+/**
+ * Tools for interacting with smart contracts, such as `Client`, `Spec`, and
+ * `AssembledTransaction`. You can import these from the `/contract`
+ * entrypoint, if your version of Node and your TypeScript configuration allow
+ * it:
+ *
+ * ```ts
+ * import { Client } from '@stellar/stellar-sdk/contract';
+ * ```
+ */
+export * as contract from './contract';
 export * from '@stellar/stellar-base';
 declare const _default: any;
 export default _default;

package/lib/index.js

@@ -12,7 +12,9 @@ var _exportNames = {
   WebAuth: true,
   Friendbot: true,
   Horizon: true,
-  SorobanRpc: true
+  rpc: true,
+  SorobanRpc: true,
+  contract: true
 };
 Object.defineProperty(exports, "Config", {
   enumerable: true,
@@ -27,7 +29,7 @@ Object.defineProperty(exports, "Utils", {
     return _utils.Utils;
   }
 });
-exports.default = exports.WebAuth = void 0;
+exports.rpc = exports.default = exports.contract = exports.WebAuth = void 0;
 var _errors = require("./errors");
 Object.keys(_errors).forEach(function (key) {
   if (key === "default" || key === "__esModule") return;
@@ -52,20 +54,12 @@ var _Friendbot = _interopRequireWildcard(require("./friendbot"));
 exports.Friendbot = _Friendbot;
 var _Horizon = _interopRequireWildcard(require("./horizon"));
 exports.Horizon = _Horizon;
-var _SorobanRpc = _interopRequireWildcard(require("./soroban"));
-exports.SorobanRpc = _SorobanRpc;
-var _contract_spec = require("./contract_spec");
-Object.keys(_contract_spec).forEach(function (key) {
-  if (key === "default" || key === "__esModule") return;
-  if (Object.prototype.hasOwnProperty.call(_exportNames, key)) return;
-  if (key in exports && exports[key] === _contract_spec[key]) return;
-  Object.defineProperty(exports, key, {
-    enumerable: true,
-    get: function get() {
-      return _contract_spec[key];
-    }
-  });
-});
+var _rpc = _interopRequireWildcard(require("./rpc"));
+var _SorobanRpc = _rpc;
+exports.rpc = _rpc;
+exports.SorobanRpc = _rpc;
+var _contract = _interopRequireWildcard(require("./contract"));
+exports.contract = _contract;
 var _stellarBase = require("@stellar/stellar-base");
 Object.keys(_stellarBase).forEach(function (key) {
   if (key === "default" || key === "__esModule") return;

package/lib/rpc/index.d.ts

@@ -0,0 +1,7 @@
+export * from "./api";
+export { Server, Durability } from "./server";
+export { default as AxiosClient } from "./axios";
+export { parseRawSimulation, parseRawEvents } from "./parsers";
+export * from "./transaction";
+declare const _default: any;
+export default _default;

package/lib/{soroban → rpc}/server.d.ts

@@ -110,6 +110,55 @@ export declare class Server {
      * });
      */
     getContractData(contract: string | Address | Contract, key: xdr.ScVal, durability?: Durability): Promise<Api.LedgerEntryResult>;
+    /**
+     * Retrieves the WASM bytecode for a given contract.
+     *
+     * This method allows you to fetch the WASM bytecode associated with a contract
+     * 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<Buffer>}   a Buffer containing the WASM bytecode
+     *
+     * @throws {Error} If the contract or its associated WASM bytecode cannot be
+     *    found on the network.
+     *
+     * @example
+     * const contractId = "CCJZ5DGASBWQXR5MPFCJXMBI333XE5U3FSJTNQU7RIKE3P5GN2K2WYD5";
+     * server.getContractWasmByContractId(contractId).then(wasmBuffer => {
+     *   console.log("WASM bytecode length:", wasmBuffer.length);
+     *   // ... do something with the WASM bytecode ...
+     * }).catch(err => {
+     *   console.error("Error fetching WASM bytecode:", err);
+     * });
+     */
+    getContractWasmByContractId(contractId: string): Promise<Buffer>;
+    /**
+     * Retrieves the WASM bytecode for a given contract hash.
+     *
+     * This method allows you to fetch the WASM bytecode associated with a contract
+     * 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<Buffer>}   a Buffer containing the WASM bytecode
+     *
+     * @throws {Error} If the contract or its associated WASM bytecode cannot be
+     *    found on the network.
+     *
+     * @example
+     * const wasmHash = Buffer.from("...");
+     * server.getContractWasmByHash(wasmHash).then(wasmBuffer => {
+     *   console.log("WASM bytecode length:", wasmBuffer.length);
+     *   // ... do something with the WASM bytecode ...
+     * }).catch(err => {
+     *   console.error("Error fetching WASM bytecode:", err);
+     * });
+     */
+    getContractWasmByHash(wasmHash: Buffer | string, format?: undefined | "hex" | "base64"): Promise<Buffer>;
     /**
      * Reads the current value of arbitrary ledger entries directly.
      *