algosdk 2.1.0 → 2.3.0

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

@@ -0,0 +1,8 @@
+import JSONRequest from '../jsonrequest';
+
+export default class Ready extends JSONRequest {
+  // eslint-disable-next-line class-methods-use-this
+  path() {
+    return `/ready`;
+  }
+}

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

@@ -0,0 +1,20 @@
+import JSONRequest from '../jsonrequest';
+import HTTPClient from '../../client';
+import IntDecoding from '../../../types/intDecoding';
+
+export default class SetBlockOffsetTimestamp extends JSONRequest {
+  constructor(c: HTTPClient, intDecoding: IntDecoding, private offset: number) {
+    super(c, intDecoding);
+
+    this.offset = offset;
+  }
+
+  path() {
+    return `/v2/devmode/blocks/offset/${this.offset}`;
+  }
+
+  async do(headers = {}) {
+    const res = await this.c.post(this.path(), headers);
+    return res.body;
+  }
+}

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

@@ -0,0 +1,20 @@
+import JSONRequest from '../jsonrequest';
+import HTTPClient from '../../client';
+import IntDecoding from '../../../types/intDecoding';
+
+export default class SetSyncRound extends JSONRequest {
+  constructor(c: HTTPClient, intDecoding: IntDecoding, private round: number) {
+    super(c, intDecoding);
+
+    this.round = round;
+  }
+
+  path() {
+    return `/v2/ledger/sync/${this.round}`;
+  }
+
+  async do(headers = {}) {
+    const res = await this.c.post(this.path(), headers);
+    return res.body;
+  }
+}

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

@@ -0,0 +1,58 @@
+import { Buffer } from 'buffer';
+import * as encoding from '../../../encoding/encoding';
+import HTTPClient from '../../client';
+import JSONRequest from '../jsonrequest';
+import { SimulateRequest, 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/msgpack';
+  }
+  return hdrs;
+}
+
+/**
+ * Simulates signed txns.
+ */
+export default class SimulateRawTransactions extends JSONRequest<
+  SimulateResponse,
+  Uint8Array
+> {
+  private requestBytes: Uint8Array;
+
+  constructor(c: HTTPClient, request: SimulateRequest) {
+    super(c);
+    this.query.format = 'msgpack';
+    this.requestBytes = encoding.rawEncode(request.get_obj_for_encoding(true));
+  }
+
+  // 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.requestBytes),
+      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/algod/suggestedParams.ts

@@ -1,16 +1,16 @@
 import JSONRequest from '../jsonrequest';
-import { SuggestedParams } from '../../../types/transactions/base';
+import { SuggestedParamsWithMinFee } from '../../../types/transactions/base';
 
 /**
  * Returns the common needed parameters for a new transaction, in a format the transaction builder expects
  */
-export default class SuggestedParamsRequest extends JSONRequest<SuggestedParams> {
+export default class SuggestedParamsRequest extends JSONRequest<SuggestedParamsWithMinFee> {
   /* eslint-disable class-methods-use-this */
   path() {
     return '/v2/transactions/params';
   }
 
-  prepare(body: Record<string, any>): SuggestedParams {
+  prepare(body: Record<string, any>): SuggestedParamsWithMinFee {
     return {
       flatFee: false,
       fee: body.fee,
@@ -18,6 +18,7 @@ export default class SuggestedParamsRequest extends JSONRequest<SuggestedParams>
       lastRound: body['last-round'] + 1000,
       genesisID: body['genesis-id'],
       genesisHash: body['genesis-hash'],
+      minFee: body['min-fee'],
     };
   }
   /* eslint-enable class-methods-use-this */

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

@@ -0,0 +1,13 @@
+import JSONRequest from '../jsonrequest';
+
+export default class UnsetSyncRound extends JSONRequest {
+  // eslint-disable-next-line class-methods-use-this
+  path() {
+    return `/v2/ledger/sync`;
+  }
+
+  async do(headers = {}) {
+    const res = await this.c.delete(this.path(), headers);
+    return res.body;
+  }
+}

package/src/composer.ts

@@ -1,31 +1,38 @@
 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,
+  SimulateRequest,
+  SimulateRequestTransactionGroup,
+} from './client/v2/algod/models/types';
+import { EncodedSignedTransaction } from './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';
+import * as encoding from './encoding/encoding';
 
 // First 4 bytes of SHA-512/256 hash of "return"
 const RETURN_PREFIX = Buffer.from([21, 31, 124, 117]);
@@ -600,6 +607,78 @@ 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
+   * @param request - SimulateRequest with options in simulation.
+   *   If provided, the request's transaction group will be overrwritten by the composer's group,
+   *   only simulation related options will be used.
+   *
+   * @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,
+    request?: SimulateRequest
+  ): 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 txnObjects: EncodedSignedTransaction[] = stxns.map(
+      (stxn) => encoding.decode(stxn) as EncodedSignedTransaction
+    );
+
+    const currentRequest: SimulateRequest =
+      request == null ? new SimulateRequest({ txnGroups: [] }) : request;
+
+    currentRequest.txnGroups = [
+      new SimulateRequestTransactionGroup({
+        txns: txnObjects,
+      }),
+    ];
+
+    const simulateResponse = await client
+      .simulateTransactions(currentRequest)
+      .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 +732,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 +744,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 +763,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/main.ts

@@ -127,6 +127,13 @@ export {
   BaseHTTPClientResponse,
   BaseHTTPClientError,
 } from './client/baseHTTPClient';
+export {
+  AlgodTokenHeader,
+  IndexerTokenHeader,
+  KMDTokenHeader,
+  CustomTokenHeader,
+  TokenHeader,
+} from './client/urlTokenBaseHTTPClient';
 export { waitForConfirmation } from './wait';
 export {
   isValidAddress,

package/src/makeTxn.ts

@@ -200,10 +200,8 @@ export function makeKeyRegistrationTxnWithSuggestedParamsFromObject(
         'reKeyTo',
         'rekeyTo'
       >,
-      'from' | 'note' | 'suggestedParams' | 'rekeyTo'
-    > & {
-      nonParticipation: true;
-    }
+      'from' | 'note' | 'suggestedParams' | 'rekeyTo' | 'nonParticipation'
+    >
   >
 ): txnBuilder.Transaction;
 export function makeKeyRegistrationTxnWithSuggestedParamsFromObject(o: any) {

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,23 @@ 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 = {
+    txn: transactionObject.get_obj_for_encoding(),
+  };
+  return encoding.encode(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/base.ts

@@ -130,6 +130,13 @@ export interface SuggestedParams {
   genesisHash: string;
 }
 
+export type SuggestedParamsWithMinFee = SuggestedParams & {
+  /**
+   * Minimum fee (not per byte) required for the transaction to be confirmed
+   */
+  minFee: number;
+};
+
 /**
  * A grouping of the app ID and name of the box in an Uint8Array
  */

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;