algosdk 2.0.0 → 2.2.0

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

@@ -3,6 +3,7 @@
  */
 
 /* eslint-disable no-use-before-define */
+import { Buffer } from 'buffer';
 import BaseModel from '../../basemodel';
 import { EncodedSignedTransaction } from '../../../../types/transactions/encoded';
 import BlockHeader from '../../../../types/blockHeader';
@@ -3083,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/sendRawTransaction.ts

@@ -1,3 +1,4 @@
+import { Buffer } from 'buffer';
 import JSONRequest from '../jsonrequest';
 import HTTPClient from '../../client';
 import { concatArrays } from '../../../utils/utils';

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/client/v2/basemodel.ts

@@ -1,3 +1,5 @@
+import { Buffer } from 'buffer';
+
 /**
  * Base class for models
  */

package/src/client/v2/indexer/lookupAccountTransactions.ts

@@ -1,3 +1,4 @@
+import { Buffer } from 'buffer';
 import JSONRequest from '../jsonrequest';
 import HTTPClient from '../../client';
 import IntDecoding from '../../../types/intDecoding';

package/src/client/v2/indexer/lookupApplicationBoxByIDandName.ts

@@ -1,3 +1,4 @@
+import { Buffer } from 'buffer';
 import JSONRequest from '../jsonrequest';
 import HTTPClient from '../../client';
 import IntDecoding from '../../../types/intDecoding';

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

@@ -3,6 +3,7 @@
  */
 
 /* eslint-disable no-use-before-define */
+import { Buffer } from 'buffer';
 import BaseModel from '../../basemodel';
 
 /**

package/src/composer.ts

@@ -1,30 +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]);
@@ -202,6 +204,9 @@ export class AtomicTransactionComposer {
     numLocalInts,
     numLocalByteSlices,
     extraPages,
+    appAccounts,
+    appForeignApps,
+    appForeignAssets,
     boxes,
     note,
     lease,
@@ -234,6 +239,12 @@ export class AtomicTransactionComposer {
     numLocalByteSlices?: number;
     /** The number of extra pages to allocate for the application's programs. Only set this if this is an application creation call. If omitted, defaults to 0. */
     extraPages?: number;
+    /** Array of Address strings that represent external accounts supplied to this application. If accounts are provided here, the accounts specified in the method args will appear after these. */
+    appAccounts?: string[];
+    /** Array of App ID numbers that represent external apps supplied to this application. If apps are provided here, the apps specified in the method args will appear after these. */
+    appForeignApps?: number[];
+    /** Array of Asset ID numbers that represent external assets supplied to this application. If assets are provided here, the assets specified in the method args will appear after these. */
+    appForeignAssets?: number[];
     /** The box references for this application call */
     boxes?: BoxReference[];
     /** The note value for this application call */
@@ -370,9 +381,12 @@ export class AtomicTransactionComposer {
     }
 
     const resolvedRefIndexes: number[] = [];
-    const foreignAccounts: string[] = [];
-    const foreignApps: number[] = [];
-    const foreignAssets: number[] = [];
+    const foreignAccounts: string[] =
+      appAccounts == null ? [] : appAccounts.slice();
+    const foreignApps: number[] =
+      appForeignApps == null ? [] : appForeignApps.slice();
+    const foreignAssets: number[] =
+      appForeignAssets == null ? [] : appForeignAssets.slice();
     for (let i = 0; i < refArgTypes.length; i++) {
       const refType = refArgTypes[i];
       const refValue = refArgValues[i];
@@ -587,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.
@@ -640,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,
@@ -652,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;
       }
@@ -685,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/dryrun.ts

@@ -1,3 +1,4 @@
+import { Buffer } from 'buffer';
 import AlgodClient from './client/v2/algod/algod';
 import {
   AccountStateDelta,

package/src/encoding/address.ts

@@ -1,3 +1,4 @@
+import { Buffer } from 'buffer';
 import base32 from 'hi-base32';
 import * as nacl from '../nacl/naclWrappers';
 import * as utils from '../utils/utils';

package/src/encoding/bigint.ts

@@ -1,3 +1,5 @@
+import { Buffer } from 'buffer';
+
 /**
  * bigIntToBytes converts a BigInt to a big-endian Uint8Array for encoding.
  * @param bi - The bigint to convert.

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/encoding/uint64.ts

@@ -1,3 +1,10 @@
+import { concatArrays } from '../utils/utils';
+
+// NOTE: at the moment we specifically do not use Buffer.writeBigUInt64BE and
+// Buffer.readBigUInt64BE. This is because projects using webpack v4
+// automatically include an old version of the npm `buffer` package (v4.9.2 at
+// the time of writing), and this old version does not have these methods.
+
 /**
  * encodeUint64 converts an integer to its binary representation.
  * @param num - The number to convert. This must be an unsigned integer less than
@@ -12,11 +19,11 @@ export function encodeUint64(num: number | bigint) {
     throw new Error('Input is not a 64-bit unsigned integer');
   }
 
-  const buf = Buffer.allocUnsafe(8);
+  const encoding = new Uint8Array(8);
+  const view = new DataView(encoding.buffer);
+  view.setBigUint64(0, BigInt(num));
 
-  buf.writeBigUInt64BE(BigInt(num));
-
-  return new Uint8Array(buf);
+  return encoding;
 }
 
 /**
@@ -59,13 +66,12 @@ export function decodeUint64(data: any, decodingMode: any = 'safe') {
   }
 
   // insert 0s at the beginning if data is smaller than 8 bytes
-  const padding = Buffer.allocUnsafe(8 - data.byteLength);
-  padding.fill(0);
-
-  const buf = Buffer.concat([padding, Buffer.from(data)]);
+  const padding = new Uint8Array(8 - data.byteLength);
+  const encoding = concatArrays(padding, data);
+  const view = new DataView(encoding.buffer);
 
-  const num = buf.readBigUInt64BE();
-  const isBig = num > Number.MAX_SAFE_INTEGER;
+  const num = view.getBigUint64(0);
+  const isBig = num > BigInt(Number.MAX_SAFE_INTEGER);
 
   if (decodingMode === 'safe') {
     if (isBig) {

package/src/group.ts

@@ -1,3 +1,4 @@
+import { Buffer } from 'buffer';
 import * as txnBuilder from './transaction';
 import * as nacl from './nacl/naclWrappers';
 import * as encoding from './encoding/encoding';