algosdk 2.1.0 → 2.2.0

package/src/client/v2/algod/models/types.ts

@@ -3084,6 +3084,228 @@ export class PostTransactionsResponse extends BaseModel {
   }
 }
 
+/**
+ * Result of a transaction group simulation.
+ */
+export class SimulateResponse extends BaseModel {
+  /**
+   * The round immediately preceding this simulation. State changes through this
+   * round were used to run this simulation.
+   */
+  public lastRound: number | bigint;
+
+  /**
+   * A result object for each transaction group that was simulated.
+   */
+  public txnGroups: SimulateTransactionGroupResult[];
+
+  /**
+   * The version of this response object.
+   */
+  public version: number | bigint;
+
+  /**
+   * Indicates whether the simulated transactions would have succeeded during an
+   * actual submission. If any transaction fails or is missing a signature, this will
+   * be false.
+   */
+  public wouldSucceed: boolean;
+
+  /**
+   * Creates a new `SimulateResponse` object.
+   * @param lastRound - The round immediately preceding this simulation. State changes through this
+   * round were used to run this simulation.
+   * @param txnGroups - A result object for each transaction group that was simulated.
+   * @param version - The version of this response object.
+   * @param wouldSucceed - Indicates whether the simulated transactions would have succeeded during an
+   * actual submission. If any transaction fails or is missing a signature, this will
+   * be false.
+   */
+  constructor({
+    lastRound,
+    txnGroups,
+    version,
+    wouldSucceed,
+  }: {
+    lastRound: number | bigint;
+    txnGroups: SimulateTransactionGroupResult[];
+    version: number | bigint;
+    wouldSucceed: boolean;
+  }) {
+    super();
+    this.lastRound = lastRound;
+    this.txnGroups = txnGroups;
+    this.version = version;
+    this.wouldSucceed = wouldSucceed;
+
+    this.attribute_map = {
+      lastRound: 'last-round',
+      txnGroups: 'txn-groups',
+      version: 'version',
+      wouldSucceed: 'would-succeed',
+    };
+  }
+
+  // eslint-disable-next-line camelcase
+  static from_obj_for_encoding(data: Record<string, any>): SimulateResponse {
+    /* eslint-disable dot-notation */
+    if (typeof data['last-round'] === 'undefined')
+      throw new Error(
+        `Response is missing required field 'last-round': ${data}`
+      );
+    if (!Array.isArray(data['txn-groups']))
+      throw new Error(
+        `Response is missing required array field 'txn-groups': ${data}`
+      );
+    if (typeof data['version'] === 'undefined')
+      throw new Error(`Response is missing required field 'version': ${data}`);
+    if (typeof data['would-succeed'] === 'undefined')
+      throw new Error(
+        `Response is missing required field 'would-succeed': ${data}`
+      );
+    return new SimulateResponse({
+      lastRound: data['last-round'],
+      txnGroups: data['txn-groups'].map(
+        SimulateTransactionGroupResult.from_obj_for_encoding
+      ),
+      version: data['version'],
+      wouldSucceed: data['would-succeed'],
+    });
+    /* eslint-enable dot-notation */
+  }
+}
+
+/**
+ * Simulation result for an atomic transaction group
+ */
+export class SimulateTransactionGroupResult extends BaseModel {
+  /**
+   * Simulation result for individual transactions
+   */
+  public txnResults: SimulateTransactionResult[];
+
+  /**
+   * If present, indicates which transaction in this group caused the failure. This
+   * array represents the path to the failing transaction. Indexes are zero based,
+   * the first element indicates the top-level transaction, and successive elements
+   * indicate deeper inner transactions.
+   */
+  public failedAt?: (number | bigint)[];
+
+  /**
+   * If present, indicates that the transaction group failed and specifies why that
+   * happened
+   */
+  public failureMessage?: string;
+
+  /**
+   * Creates a new `SimulateTransactionGroupResult` object.
+   * @param txnResults - Simulation result for individual transactions
+   * @param failedAt - If present, indicates which transaction in this group caused the failure. This
+   * array represents the path to the failing transaction. Indexes are zero based,
+   * the first element indicates the top-level transaction, and successive elements
+   * indicate deeper inner transactions.
+   * @param failureMessage - If present, indicates that the transaction group failed and specifies why that
+   * happened
+   */
+  constructor({
+    txnResults,
+    failedAt,
+    failureMessage,
+  }: {
+    txnResults: SimulateTransactionResult[];
+    failedAt?: (number | bigint)[];
+    failureMessage?: string;
+  }) {
+    super();
+    this.txnResults = txnResults;
+    this.failedAt = failedAt;
+    this.failureMessage = failureMessage;
+
+    this.attribute_map = {
+      txnResults: 'txn-results',
+      failedAt: 'failed-at',
+      failureMessage: 'failure-message',
+    };
+  }
+
+  // eslint-disable-next-line camelcase
+  static from_obj_for_encoding(
+    data: Record<string, any>
+  ): SimulateTransactionGroupResult {
+    /* eslint-disable dot-notation */
+    if (!Array.isArray(data['txn-results']))
+      throw new Error(
+        `Response is missing required array field 'txn-results': ${data}`
+      );
+    return new SimulateTransactionGroupResult({
+      txnResults: data['txn-results'].map(
+        SimulateTransactionResult.from_obj_for_encoding
+      ),
+      failedAt: data['failed-at'],
+      failureMessage: data['failure-message'],
+    });
+    /* eslint-enable dot-notation */
+  }
+}
+
+/**
+ * Simulation result for an individual transaction
+ */
+export class SimulateTransactionResult extends BaseModel {
+  /**
+   * Details about a pending transaction. If the transaction was recently confirmed,
+   * includes confirmation details like the round and reward details.
+   */
+  public txnResult: PendingTransactionResponse;
+
+  /**
+   * A boolean indicating whether this transaction is missing signatures
+   */
+  public missingSignature?: boolean;
+
+  /**
+   * Creates a new `SimulateTransactionResult` object.
+   * @param txnResult - Details about a pending transaction. If the transaction was recently confirmed,
+   * includes confirmation details like the round and reward details.
+   * @param missingSignature - A boolean indicating whether this transaction is missing signatures
+   */
+  constructor({
+    txnResult,
+    missingSignature,
+  }: {
+    txnResult: PendingTransactionResponse;
+    missingSignature?: boolean;
+  }) {
+    super();
+    this.txnResult = txnResult;
+    this.missingSignature = missingSignature;
+
+    this.attribute_map = {
+      txnResult: 'txn-result',
+      missingSignature: 'missing-signature',
+    };
+  }
+
+  // eslint-disable-next-line camelcase
+  static from_obj_for_encoding(
+    data: Record<string, any>
+  ): SimulateTransactionResult {
+    /* eslint-disable dot-notation */
+    if (typeof data['txn-result'] === 'undefined')
+      throw new Error(
+        `Response is missing required field 'txn-result': ${data}`
+      );
+    return new SimulateTransactionResult({
+      txnResult: PendingTransactionResponse.from_obj_for_encoding(
+        data['txn-result']
+      ),
+      missingSignature: data['missing-signature'],
+    });
+    /* eslint-enable dot-notation */
+  }
+}
+
 /**
  * Represents a state proof and its corresponding message
  */

package/src/client/v2/algod/simulateTransaction.ts

@@ -0,0 +1,74 @@
+import { Buffer } from 'buffer';
+import * as encoding from '../../../encoding/encoding';
+import { concatArrays } from '../../../utils/utils';
+import HTTPClient from '../../client';
+import JSONRequest from '../jsonrequest';
+import { SimulateResponse } from './models/types';
+
+/**
+ * Sets the default header (if not previously set) for simulating a raw
+ * transaction.
+ * @param headers - A headers object
+ */
+export function setSimulateTransactionsHeaders(headers = {}) {
+  let hdrs = headers;
+  if (Object.keys(hdrs).every((key) => key.toLowerCase() !== 'content-type')) {
+    hdrs = { ...headers };
+    hdrs['Content-Type'] = 'application/x-binary';
+  }
+  return hdrs;
+}
+
+function isByteArray(array: any): array is Uint8Array {
+  return array && array.byteLength !== undefined;
+}
+
+/**
+ * Simulates signed txns.
+ */
+export default class SimulateRawTransactions extends JSONRequest<
+  SimulateResponse,
+  Uint8Array
+> {
+  private txnBytesToPost: Uint8Array;
+
+  constructor(c: HTTPClient, stxOrStxs: Uint8Array | Uint8Array[]) {
+    super(c);
+    this.query.format = 'msgpack';
+
+    let forPosting = stxOrStxs;
+    if (Array.isArray(stxOrStxs)) {
+      if (!stxOrStxs.every(isByteArray)) {
+        throw new TypeError('Array elements must be byte arrays');
+      }
+      // Flatten into a single Uint8Array
+      forPosting = concatArrays(...stxOrStxs);
+    } else if (!isByteArray(forPosting)) {
+      throw new TypeError('Argument must be byte array');
+    }
+    this.txnBytesToPost = forPosting;
+  }
+
+  // eslint-disable-next-line class-methods-use-this
+  path() {
+    return '/v2/transactions/simulate';
+  }
+
+  async do(headers = {}) {
+    const txHeaders = setSimulateTransactionsHeaders(headers);
+    const res = await this.c.post(
+      this.path(),
+      Buffer.from(this.txnBytesToPost),
+      txHeaders,
+      this.query,
+      false
+    );
+    return this.prepare(res.body);
+  }
+
+  // eslint-disable-next-line class-methods-use-this
+  prepare(body: Uint8Array): SimulateResponse {
+    const decoded = encoding.decode(body);
+    return SimulateResponse.from_obj_for_encoding(decoded);
+  }
+}

package/src/composer.ts

@@ -1,31 +1,32 @@
 import { Buffer } from 'buffer';
 import {
-  ABIType,
-  ABITupleType,
-  ABIUintType,
   ABIAddressType,
-  ABIValue,
+  abiCheckTransactionType,
   ABIMethod,
   ABIReferenceType,
-  abiTypeIsTransaction,
-  abiCheckTransactionType,
+  ABITupleType,
+  ABIType,
   abiTypeIsReference,
+  abiTypeIsTransaction,
+  ABIUintType,
+  ABIValue,
 } from './abi';
-import { Transaction, decodeSignedTransaction } from './transaction';
-import { makeApplicationCallTxnFromObject } from './makeTxn';
-import { assignGroupID } from './group';
-import { waitForConfirmation } from './wait';
 import Algodv2 from './client/v2/algod/algod';
+import { SimulateResponse } from './client/v2/algod/models/types';
+import { assignGroupID } from './group';
+import { makeApplicationCallTxnFromObject } from './makeTxn';
 import {
+  isTransactionWithSigner,
   TransactionSigner,
   TransactionWithSigner,
-  isTransactionWithSigner,
 } from './signer';
+import { decodeSignedTransaction, Transaction } from './transaction';
 import {
   BoxReference,
   OnApplicationComplete,
   SuggestedParams,
 } from './types/transactions/base';
+import { waitForConfirmation } from './wait';
 
 // First 4 bytes of SHA-512/256 hash of "return"
 const RETURN_PREFIX = Buffer.from([21, 31, 124, 117]);
@@ -600,6 +601,60 @@ export class AtomicTransactionComposer {
     return this.txIDs;
   }
 
+  /**
+   * Simulates the transaction group in the network.
+   *
+   * The composer will try to sign any transactions in the group, then simulate
+   * the results.
+   * Simulating the group will not change the composer's status.
+   *
+   * @param client - An Algodv2 client
+   *
+   * @returns A promise that, upon success, resolves to an object containing an
+   *   array of results containing one element for each method call transaction
+   *   in this group (ABIResult[]) and the SimulateResponse object.
+   */
+  async simulate(
+    client: Algodv2
+  ): Promise<{
+    methodResults: ABIResult[];
+    simulateResponse: SimulateResponse;
+  }> {
+    if (this.status > AtomicTransactionComposerStatus.SUBMITTED) {
+      throw new Error(
+        'Simulated Transaction group has already been submitted to the network'
+      );
+    }
+
+    const stxns = await this.gatherSignatures();
+
+    const simulateResponse = await client.simulateRawTransactions(stxns).do();
+
+    // Parse method response
+    const methodResults: ABIResult[] = [];
+    for (const [txnIndex, method] of this.methodCalls) {
+      const txID = this.txIDs[txnIndex];
+      const pendingInfo =
+        simulateResponse.txnGroups[0].txnResults[txnIndex].txnResult;
+
+      const methodResult: ABIResult = {
+        txID,
+        rawReturnValue: new Uint8Array(),
+        method,
+      };
+
+      methodResults.push(
+        AtomicTransactionComposer.parseMethodResponse(
+          method,
+          methodResult,
+          pendingInfo.get_obj_for_encoding()
+        )
+      );
+    }
+
+    return { methodResults, simulateResponse };
+  }
+
   /**
    * Send the transaction group to the network and wait until it's committed to a block. An error
    * will be thrown if submission or execution fails.
@@ -653,7 +708,7 @@ export class AtomicTransactionComposer {
     for (const [txnIndex, method] of this.methodCalls) {
       const txID = txIDs[txnIndex];
 
-      const methodResult: ABIResult = {
+      let methodResult: ABIResult = {
         txID,
         rawReturnValue: new Uint8Array(),
         method,
@@ -665,26 +720,12 @@ export class AtomicTransactionComposer {
             ? confirmedTxnInfo
             : // eslint-disable-next-line no-await-in-loop
               await client.pendingTransactionInformation(txID).do();
-        methodResult.txInfo = pendingInfo;
-        if (method.returns.type !== 'void') {
-          const logs: string[] = pendingInfo.logs || [];
-          if (logs.length === 0) {
-            throw new Error('App call transaction did not log a return value');
-          }
-
-          const lastLog = Buffer.from(logs[logs.length - 1], 'base64');
-          if (
-            lastLog.byteLength < 4 ||
-            !lastLog.slice(0, 4).equals(RETURN_PREFIX)
-          ) {
-            throw new Error('App call transaction did not log a return value');
-          }
 
-          methodResult.rawReturnValue = new Uint8Array(lastLog.slice(4));
-          methodResult.returnValue = method.returns.type.decode(
-            methodResult.rawReturnValue
-          );
-        }
+        methodResult = AtomicTransactionComposer.parseMethodResponse(
+          method,
+          methodResult,
+          pendingInfo
+        );
       } catch (err) {
         methodResult.decodeError = err;
       }
@@ -698,4 +739,46 @@ export class AtomicTransactionComposer {
       methodResults,
     };
   }
+
+  /**
+   * Parses a single ABI Method transaction log into a ABI result object.
+   *
+   * @param method
+   * @param methodResult
+   * @param pendingInfo
+   * @returns An ABIResult object
+   */
+  static parseMethodResponse(
+    method: ABIMethod,
+    methodResult: ABIResult,
+    pendingInfo: Record<string, any>
+  ): ABIResult {
+    const returnedResult: ABIResult = methodResult;
+    try {
+      returnedResult.txInfo = pendingInfo;
+      if (method.returns.type !== 'void') {
+        const logs: string[] = pendingInfo.logs || [];
+        if (logs.length === 0) {
+          throw new Error('App call transaction did not log a return value');
+        }
+
+        const lastLog = Buffer.from(logs[logs.length - 1], 'base64');
+        if (
+          lastLog.byteLength < 4 ||
+          !lastLog.slice(0, 4).equals(RETURN_PREFIX)
+        ) {
+          throw new Error('App call transaction did not log a return value');
+        }
+
+        returnedResult.rawReturnValue = new Uint8Array(lastLog.slice(4));
+        returnedResult.returnValue = method.returns.type.decode(
+          methodResult.rawReturnValue
+        );
+      }
+    } catch (err) {
+      returnedResult.decodeError = err;
+    }
+
+    return returnedResult;
+  }
 }

package/src/encoding/encoding.ts

@@ -33,6 +33,18 @@ function containsEmpty(obj: Record<string | number | symbol, any>) {
   return { containsEmpty: false, firstEmptyKey: undefined };
 }
 
+/**
+ * rawEncode encodes objects using msgpack, regardless of whether there are
+ * empty or 0 value fields.
+ * @param obj - a dictionary to be encoded. May or may not contain empty or 0 values.
+ * @returns msgpack representation of the object
+ */
+export function rawEncode(obj: Record<string | number | symbol, any>) {
+  // enable the canonical option
+  const options = { sortKeys: true };
+  return msgpack.encode(obj, options);
+}
+
 /**
  * encode encodes objects using msgpack
  * @param obj - a dictionary to be encoded. Must not contain empty or 0 values.
@@ -47,8 +59,7 @@ export function encode(obj: Record<string | number | symbol, any>) {
   }
 
   // enable the canonical option
-  const options = { sortKeys: true };
-  return msgpack.encode(obj, options);
+  return rawEncode(obj);
 }
 
 export function decode(buffer: ArrayLike<number>) {

package/src/signer.ts

@@ -1,4 +1,4 @@
-import { Transaction } from './transaction';
+import { encodeUnsignedSimulateTransaction, Transaction } from './transaction';
 import Account from './types/account';
 import { LogicSigAccount, signLogicSigTransactionObject } from './logicsig';
 import { MultisigMetadata } from './types/multisig';
@@ -80,6 +80,23 @@ export function makeMultiSigAccountTransactionSigner(
   };
 }
 
+/**
+ * Create a makeEmptyTransactionSigner that does not specify any signer or
+ * signing capabilities. This should only be used to simulate transactions.
+ */
+export function makeEmptyTransactionSigner(): TransactionSigner {
+  // eslint-disable-next-line @typescript-eslint/no-unused-vars
+  return (txnGroup: Transaction[], indexesToSign: number[]) => {
+    const unsigned: Uint8Array[] = [];
+
+    for (const index of indexesToSign) {
+      unsigned.push(encodeUnsignedSimulateTransaction(txnGroup[index]));
+    }
+
+    return Promise.resolve(unsigned);
+  };
+}
+
 /** Represents an unsigned transactions and a signer that can authorize that transaction. */
 export interface TransactionWithSigner {
   /** An unsigned transaction */

package/src/transaction.ts

@@ -1278,6 +1278,24 @@ export class Transaction implements TransactionStorageStructure {
   }
 }
 
+/**
+ * encodeUnsignedSimulateTransaction takes a txnBuilder.Transaction object,
+ * converts it into a SignedTransaction-like object, and converts it to a Buffer.
+ *
+ * Note: this function should only be used to simulate unsigned transactions.
+ *
+ * @param transactionObject - Transaction object to simulate.
+ */
+export function encodeUnsignedSimulateTransaction(
+  transactionObject: Transaction
+) {
+  const objToEncode: EncodedSignedTransaction = {
+    sig: null,
+    txn: transactionObject.get_obj_for_encoding(),
+  };
+  return encoding.rawEncode(objToEncode);
+}
+
 /**
  * encodeUnsignedTransaction takes a completed txnBuilder.Transaction object, such as from the makeFoo
  * family of transactions, and converts it to a Buffer

package/src/types/transactions/builder.ts

@@ -45,10 +45,10 @@ export type TransactionBase =
  * - A: Additional parameters on top of the base transaction parameters
  * - O: A set of overwrites for transaction parameters
  */
-export type ConstructTransaction<A = {}, O = {}> = DistributiveOverwrite<
-  TransactionBase & A,
-  O
->;
+export type ConstructTransaction<
+  A = {},
+  O extends Partial<TransactionBase & A> = {}
+> = DistributiveOverwrite<TransactionBase & A, O>;
 
 /**
  * Only accept transaction objects that include suggestedParams as an object

package/src/types/utils.ts

@@ -27,7 +27,7 @@ export type Overwrite<T, U extends Partial<T>> = Pick<
 /**
  * Same as Overwrite, but will distribute the Overwrite over unions
  */
-export type DistributiveOverwrite<T, K> = T extends unknown
+export type DistributiveOverwrite<T, K extends Partial<T>> = T extends unknown
   ? Overwrite<T, K>
   : never;