algosdk 2.9.0 → 3.0.0-beta.1

package/src/abi/abi_type.ts

@@ -13,10 +13,9 @@
     // | string
     // | (T1, ..., Tn)
 */
-import { Buffer } from 'buffer';
-import { encodeAddress, decodeAddress } from '../encoding/address';
-import { bigIntToBytes, bytesToBigInt } from '../encoding/bigint';
-import { concatArrays } from '../utils/utils';
+import { encodeAddress, decodeAddress } from '../encoding/address.js';
+import { bigIntToBytes, bytesToBigInt } from '../encoding/bigint.js';
+import { concatArrays } from '../utils/utils.js';
 
 export const MAX_LEN = 2 ** 16 - 1;
 export const ADDR_BYTE_SIZE = 32;
@@ -62,7 +61,7 @@ export abstract class ABIType {
     if (str.endsWith(']')) {
       const stringMatches = str.match(staticArrayRegexp);
       // Match the string itself, array element type, then array length
-      if (stringMatches.length !== 3) {
+      if (!stringMatches || stringMatches.length !== 3) {
         throw new Error(`malformed static array string: ${str}`);
       }
       // Parse static array using regex
@@ -77,8 +76,8 @@ export abstract class ABIType {
     }
     if (str.startsWith('uint')) {
       // Checks if the parsed number contains only digits, no whitespaces
-      const digitsOnly = (string) =>
-        [...string].every((c) => '0123456789'.includes(c));
+      const digitsOnly = (s: string) =>
+        [...s].every((c) => '0123456789'.includes(c));
       const typeSizeStr = str.slice(4, str.length);
       if (!digitsOnly(typeSizeStr)) {
         throw new Error(`malformed uint string: ${typeSizeStr}`);
@@ -94,7 +93,7 @@ export abstract class ABIType {
     }
     if (str.startsWith('ufixed')) {
       const stringMatches = str.match(ufixedRegexp);
-      if (stringMatches.length !== 3) {
+      if (!stringMatches || stringMatches.length !== 3) {
         throw new Error(`malformed ufixed type: ${str}`);
       }
       const ufixedSize = parseInt(stringMatches[1], 10);
@@ -380,7 +379,12 @@ export class ABIStringType extends ABIType {
     if (typeof value !== 'string' && !(value instanceof Uint8Array)) {
       throw new Error(`Cannot encode value as string: ${value}`);
     }
-    const encodedBytes = Buffer.from(value);
+    let encodedBytes: Uint8Array;
+    if (typeof value === 'string') {
+      encodedBytes = new TextEncoder().encode(value);
+    } else {
+      encodedBytes = value;
+    }
     const encodedLength = bigIntToBytes(
       encodedBytes.length,
       LENGTH_ENCODE_BYTE_SIZE
@@ -399,8 +403,12 @@ export class ABIStringType extends ABIType {
         `byte string is too short to be decoded. Actual length is ${byteString.length}, but expected at least ${LENGTH_ENCODE_BYTE_SIZE}`
       );
     }
-    const buf = Buffer.from(byteString);
-    const byteLength = buf.readUIntBE(0, LENGTH_ENCODE_BYTE_SIZE);
+    const view = new DataView(
+      byteString.buffer,
+      byteString.byteOffset,
+      LENGTH_ENCODE_BYTE_SIZE
+    );
+    const byteLength = view.getUint16(0);
     const byteValue = byteString.slice(
       LENGTH_ENCODE_BYTE_SIZE,
       byteString.length
@@ -410,7 +418,7 @@ export class ABIStringType extends ABIType {
         `string length bytes do not match the actual length of string. Expected ${byteLength}, got ${byteValue.length}`
       );
     }
-    return Buffer.from(byteValue).toString('utf-8');
+    return new TextDecoder('utf-8').decode(byteValue);
   }
 }
 
@@ -517,8 +525,8 @@ export class ABIArrayDynamicType extends ABIType {
   }
 
   decode(byteString: Uint8Array): ABIValue[] {
-    const buf = Buffer.from(byteString);
-    const byteLength = buf.readUIntBE(0, LENGTH_ENCODE_BYTE_SIZE);
+    const view = new DataView(byteString.buffer, 0, LENGTH_ENCODE_BYTE_SIZE);
+    const byteLength = view.getUint16(0);
     const convertedTuple = this.toABITupleType(byteLength);
     return convertedTuple.decode(
       byteString.slice(LENGTH_ENCODE_BYTE_SIZE, byteString.length)
@@ -657,10 +665,10 @@ export class ABITupleType extends ABIType {
   decode(byteString: Uint8Array): ABIValue[] {
     const tupleTypes = this.childTypes;
     const dynamicSegments: Segment[] = [];
-    const valuePartition: Uint8Array[] = [];
+    const valuePartition: Array<Uint8Array | null> = [];
     let i = 0;
     let iterIndex = 0;
-    const buf = Buffer.from(byteString);
+    const view = new DataView(byteString.buffer);
 
     while (i < tupleTypes.length) {
       const tupleType = tupleTypes[i];
@@ -671,7 +679,9 @@ export class ABITupleType extends ABIType {
         ) {
           throw new Error('dynamic type in tuple is too short to be decoded');
         }
-        const dynamicIndex = buf.readUIntBE(iterIndex, LENGTH_ENCODE_BYTE_SIZE);
+        // Since LENGTH_ENCODE_BYTE_SIZE is 2 and indices are at most 2 bytes,
+        // we can use getUint16 using the iterIndex offset.
+        const dynamicIndex = view.getUint16(iterIndex);
         if (dynamicSegments.length > 0) {
           dynamicSegments[dynamicSegments.length - 1].right = dynamicIndex;
           // Check that right side of segment is greater than the left side
@@ -761,7 +771,7 @@ export class ABITupleType extends ABIType {
     // Decode each tuple element
     const returnValues: ABIValue[] = [];
     for (let j = 0; j < tupleTypes.length; j++) {
-      const valueTi = tupleTypes[j].decode(valuePartition[j]);
+      const valueTi = tupleTypes[j].decode(valuePartition[j]!);
       returnValues.push(valueTi);
     }
     return returnValues;

package/src/abi/contract.ts

@@ -1,5 +1,5 @@
-import { ABIMethod, ABIMethodParams, getMethodByName } from './method';
-import { ARC28Event } from './event';
+import { ABIMethod, ABIMethodParams, getMethodByName } from './method.js';
+import { ARC28Event } from './event.js';
 
 export interface ABIContractNetworkInfo {
   appID: number;

package/src/abi/index.ts

@@ -1,6 +1,6 @@
-export * from './abi_type';
-export * from './contract';
-export * from './interface';
-export * from './method';
-export * from './transaction';
-export * from './reference';
+export * from './abi_type.js';
+export * from './contract.js';
+export * from './interface.js';
+export * from './method.js';
+export * from './transaction.js';
+export * from './reference.js';

package/src/abi/interface.ts

@@ -1,4 +1,4 @@
-import { ABIMethod, ABIMethodParams, getMethodByName } from './method';
+import { ABIMethod, ABIMethodParams, getMethodByName } from './method.js';
 
 export interface ABIInterfaceParams {
   name: string;

package/src/abi/method.ts

@@ -1,12 +1,14 @@
-import { genericHash } from '../nacl/naclWrappers';
-import { ABIType, ABITupleType } from './abi_type';
-import { ABITransactionType, abiTypeIsTransaction } from './transaction';
-import { ABIReferenceType, abiTypeIsReference } from './reference';
-import { ARC28Event } from './event';
-
-function parseMethodSignature(
-  signature: string
-): { name: string; args: string[]; returns: string } {
+import { genericHash } from '../nacl/naclWrappers.js';
+import { ABIType, ABITupleType } from './abi_type.js';
+import { ABITransactionType, abiTypeIsTransaction } from './transaction.js';
+import { ABIReferenceType, abiTypeIsReference } from './reference.js';
+import { ARC28Event } from './event.js';
+
+function parseMethodSignature(signature: string): {
+  name: string;
+  args: string[];
+  returns: string;
+} {
   const argsStart = signature.indexOf('(');
   if (argsStart === -1) {
     throw new Error(`Invalid method signature: ${signature}`);

package/src/abi/transaction.ts

@@ -1,4 +1,4 @@
-import { Transaction } from '../transaction';
+import { Transaction } from '../transaction.js';
 
 export enum ABITransactionType {
   /**
@@ -57,5 +57,5 @@ export function abiCheckTransactionType(
     return true;
   }
 
-  return txn.type && txn.type.toString() === type.toString();
+  return txn.type ? txn.type.toString() === type.toString() : false;
 }

package/src/account.ts

@@ -1,12 +1,12 @@
-import * as nacl from './nacl/naclWrappers';
-import * as address from './encoding/address';
-import Account from './types/account';
+import * as nacl from './nacl/naclWrappers.js';
+import { Address } from './encoding/address.js';
+import Account from './types/account.js';
 
 /**
  * generateAccount returns a new Algorand address and its corresponding secret key
  */
 export default function generateAccount(): Account {
   const keys = nacl.keyPair();
-  const encodedPk = address.encodeAddress(keys.publicKey);
-  return { addr: encodedPk, sk: keys.secretKey };
+  const addr = new Address(keys.publicKey);
+  return { addr, sk: keys.secretKey };
 }

package/src/boxStorage.ts

@@ -1,20 +1,17 @@
-import { EncodedBoxReference } from './types';
-import { BoxReference } from './types/transactions/base';
+import { BoxReference } from './types/transactions/base.js';
 
-function translateBoxReference(
+function boxReferenceToEncodingData(
   reference: BoxReference,
-  foreignApps: number[],
-  appIndex: number
-): EncodedBoxReference {
-  const referenceId = reference.appIndex;
+  foreignApps: bigint[],
+  appIndex: bigint
+): Map<string, unknown> {
+  const referenceId = BigInt(reference.appIndex);
   const referenceName = reference.name;
-  const isOwnReference = referenceId === 0 || referenceId === appIndex;
-  let index = 0;
+  const isOwnReference = referenceId === BigInt(0) || referenceId === appIndex;
+
+  // Foreign apps start from index 1; index 0 is its own app ID.
+  const index = foreignApps.indexOf(referenceId) + 1;
 
-  if (foreignApps != null) {
-    // Foreign apps start from index 1; index 0 is its own app ID.
-    index = foreignApps.indexOf(referenceId) + 1;
-  }
   // Check if the app referenced is itself after checking the foreign apps array.
   // If index is zero, then the app ID was not found in the foreign apps array
   // or the foreign apps array was null.
@@ -23,20 +20,25 @@ function translateBoxReference(
     // its own foreign apps array.
     throw new Error(`Box ref with appId ${referenceId} not in foreign-apps`);
   }
-  return { i: index, n: referenceName };
+
+  return new Map<string, number | Uint8Array>([
+    ['i', index],
+    ['n', referenceName],
+  ]);
 }
 
 /**
- * translateBoxReferences translates an array of BoxReferences with app IDs
- * into an array of EncodedBoxReferences with foreign indices.
+ * boxReferencesToEncodingData translates an array of BoxReferences into an array of encoding data
+ * maps.
  */
-export function translateBoxReferences(
-  references: BoxReference[] | undefined,
-  foreignApps: number[],
-  appIndex: number
-): EncodedBoxReference[] {
-  if (references == null) return [];
+export function boxReferencesToEncodingData(
+  references: ReadonlyArray<BoxReference>,
+  foreignApps: ReadonlyArray<number | bigint>,
+  appIndex: number | bigint
+): Array<Map<string, unknown>> {
+  const appIndexBigInt = BigInt(appIndex);
+  const foreignAppsBigInt = foreignApps.map(BigInt);
   return references.map((bx) =>
-    translateBoxReference(bx, foreignApps, appIndex)
+    boxReferenceToEncodingData(bx, foreignAppsBigInt, appIndexBigInt)
   );
 }

package/src/client/baseHTTPClient.ts

@@ -26,8 +26,11 @@ export interface BaseHTTPClientError {
  * wallets to provide access to paid API services without leaking
  * the secret tokens/URLs.
  *
- * Note that post and delete also have an optional query parameter
- * This is to allow future extension where post and delete may have queries
+ * The parameter `customOptions` is an object that can be used to configure
+ * individual requests with specific specific to the BaseHTTPClient implementation.
+ *
+ * Note that DELETE requests have an optional query parameter.
+ * This is to allow future extension where DELETE may have queries
  * Currently however HTTPClient does not make use of it
  *
  * Compared to HTTPClient, BaseHTTPClient does not deal with serialization/deserialization
@@ -41,18 +44,21 @@ export interface BaseHTTPClient {
   get(
     relativePath: string,
     query?: Query<string>,
-    requestHeaders?: Record<string, string>
+    requestHeaders?: Record<string, string>,
+    customOptions?: Record<string, unknown>
   ): Promise<BaseHTTPClientResponse>;
   post(
     relativePath: string,
     data: Uint8Array,
     query?: Query<string>,
-    requestHeaders?: Record<string, string>
+    requestHeaders?: Record<string, string>,
+    customOptions?: Record<string, unknown>
   ): Promise<BaseHTTPClientResponse>;
   delete(
     relativePath: string,
-    data: Uint8Array,
+    data?: Uint8Array,
     query?: Query<string>,
-    requestHeaders?: Record<string, string>
+    requestHeaders?: Record<string, string>,
+    customOptions?: Record<string, unknown>
   ): Promise<BaseHTTPClientResponse>;
 }

package/src/client/client.ts

@@ -1,23 +1,73 @@
-import { Buffer } from 'buffer';
-import * as utils from '../utils/utils';
+import * as utils from '../utils/utils.js';
 import {
   BaseHTTPClient,
   BaseHTTPClientResponse,
   Query,
-} from './baseHTTPClient';
-import { TokenHeader, URLTokenBaseHTTPClient } from './urlTokenBaseHTTPClient';
+} from './baseHTTPClient.js';
+import {
+  TokenHeader,
+  URLTokenBaseHTTPClient,
+} from './urlTokenBaseHTTPClient.js';
 
 interface ErrorWithAdditionalInfo extends Error {
   rawResponse: string | null;
   statusCode: number;
 }
 
-export interface HTTPClientResponse {
-  body: Uint8Array | any; // when content-type=JSON, body is a JSON object, otherwise it's a Uint8Array
+export class HTTPClientResponse {
+  /**
+   * The raw response bytes
+   */
+  body: Uint8Array;
+  /**
+   * If the expected response type is JSON, this is the response bytes converted to a string.
+   */
   text?: string;
+  format: 'application/msgpack' | 'application/json';
   headers: Record<string, string>;
   status: number;
   ok: boolean;
+
+  constructor(options: {
+    body: Uint8Array;
+    text?: string;
+    format: 'application/msgpack' | 'application/json';
+    headers: Record<string, string>;
+    status: number;
+    ok: boolean;
+  }) {
+    this.body = options.body;
+    this.text = options.text;
+    this.format = options.format;
+    this.headers = options.headers;
+    this.status = options.status;
+    this.ok = options.ok;
+  }
+
+  /**
+   * Returns the response body as a string, ready to be parsed as JSON.
+   */
+  getJSONText(): string {
+    if (this.text === undefined) {
+      throw new Error(
+        `Response body does not contain JSON data. Format is ${this.format}`
+      );
+    }
+    return this.text;
+  }
+
+  /**
+   * Parses the response body as JSON with the given options.
+   */
+  parseBodyAsJSON(jsonOptions: utils.ParseJSONOptions) {
+    if (this.text === undefined) {
+      throw new Error(
+        `Response body does not contain JSON data. Format is ${this.format}`
+      );
+    }
+    // eslint-disable-next-line no-use-before-define
+    return HTTPClient.parseJSON(this.text, this.status, jsonOptions);
+  }
 }
 
 /**
@@ -38,9 +88,12 @@ function removeFalsyOrEmpty(obj: Record<string, any>) {
  * See https://codereview.stackexchange.com/a/162418
  * Used to ensure all headers are lower-case and to work more easily with them
  */
-function tolowerCaseKeys(o: object): object {
+function tolowerCaseKeys(o: Record<string, any>): Record<string, any> {
   /* eslint-disable no-param-reassign,no-return-assign,no-sequences */
-  return Object.keys(o).reduce((c, k) => ((c[k.toLowerCase()] = o[k]), c), {});
+  return Object.keys(o).reduce(
+    (c, k) => ((c[k.toLowerCase()] = o[k]), c),
+    {} as Record<string, any>
+  );
   /* eslint-enable no-param-reassign,no-return-assign,no-sequences */
 }
 
@@ -70,7 +123,7 @@ function getAcceptFormat(
  * It takes care of setting the proper "Accept" header and of
  * decoding the JSON outputs.
  */
-export default class HTTPClient {
+export class HTTPClient {
   private bc: BaseHTTPClient;
 
   /**
@@ -107,8 +160,7 @@ export default class HTTPClient {
   }
 
   /**
-   * Parse JSON using either the built-in JSON.parse or utils.parseJSON
-   * depending on whether jsonOptions are provided or not
+   * Parse JSON using utils.parseJSON
    *
    * @param text - JSON data
    * @param status - Status of the response (used in case parseJSON fails)
@@ -118,15 +170,15 @@ export default class HTTPClient {
   public static parseJSON(
     text: string,
     status: number,
-    jsonOptions: utils.JSONOptions = {}
+    jsonOptions: utils.ParseJSONOptions
   ) {
     try {
-      if (Object.keys(jsonOptions).length === 0) {
-        return text && JSON.parse(text);
+      if (!text) {
+        return null;
       }
-      return text && utils.parseJSON(text, jsonOptions);
+      return utils.parseJSON(text, jsonOptions);
     } catch (err_) {
-      const err: ErrorWithAdditionalInfo = err_;
+      const err = err_ as ErrorWithAdditionalInfo;
       // return the raw response if the response parsing fails
       err.rawResponse = text || null;
       // return the http status code if the response parsing fails
@@ -151,10 +203,10 @@ export default class HTTPClient {
       return new Uint8Array(0); // empty Uint8Array
     }
     if (requestHeaders['content-type'] === 'application/json') {
-      return new Uint8Array(Buffer.from(JSON.stringify(data)));
+      return new TextEncoder().encode(utils.stringifyJSON(data));
     }
     if (typeof data === 'string') {
-      return new Uint8Array(Buffer.from(data));
+      return new TextEncoder().encode(data);
     }
     if (data instanceof Uint8Array) {
       return data;
@@ -171,27 +223,21 @@ export default class HTTPClient {
    */
   private static prepareResponse(
     res: BaseHTTPClientResponse,
-    format: 'application/msgpack' | 'application/json',
-    parseBody: boolean,
-    jsonOptions: utils.JSONOptions = {}
+    format: 'application/msgpack' | 'application/json'
   ): HTTPClientResponse {
-    let { body } = res;
-    let text;
+    const { body } = res;
+    let text: string | undefined;
 
     if (format !== 'application/msgpack') {
-      text = (body && Buffer.from(body).toString()) || '';
-    }
-
-    if (parseBody && format === 'application/json') {
-      body = HTTPClient.parseJSON(text, res.status, jsonOptions);
+      text = (body && new TextDecoder().decode(body)) || '';
     }
 
-    return {
+    return new HTTPClientResponse({
       ...res,
-      body,
+      format,
       text,
       ok: Math.trunc(res.status / 100) === 2,
-    };
+    });
   }
 
   /**
@@ -200,13 +246,12 @@ export default class HTTPClient {
    * by adding the status and preparing the internal response
    * @private
    */
-  private static prepareResponseError(err) {
+  private static prepareResponseError(err: any) {
     if (err.response) {
       // eslint-disable-next-line no-param-reassign
       err.response = HTTPClient.prepareResponse(
         err.response,
-        'application/json',
-        true
+        'application/json'
       );
       // eslint-disable-next-line no-param-reassign
       err.status = err.response.status;
@@ -216,33 +261,39 @@ export default class HTTPClient {
 
   /**
    * Send a GET request.
-   * @param relativePath - The path of the request.
-   * @param query - An object containing the query parameters of the request.
-   * @param requestHeaders - An object containing additional request headers to use.
-   * @param jsonOptions - Options object to use to decode JSON responses. See
-   *   utils.parseJSON for the options available.
-   * @param parseBody - An optional boolean indicating whether the response body should be parsed
+   *
+   * @param options - The options to use for the request.
+   * @param options.relativePath - The path of the request.
+   * @param options.query - An object containing the query parameters of the request.
+   * @param options.requestHeaders - An object containing additional request headers to use.
    *   or not.
+   * @param options.customOptions - An object containing additional options to pass to the
+   *   underlying BaseHTTPClient instance.
    * @returns Response object.
    */
-  async get(
-    relativePath: string,
-    query?: Query<any>,
-    requestHeaders: Record<string, string> = {},
-    jsonOptions: utils.JSONOptions = {},
-    parseBody: boolean = true
-  ): Promise<HTTPClientResponse> {
+  async get({
+    relativePath,
+    query,
+    requestHeaders,
+    customOptions,
+  }: {
+    relativePath: string;
+    query?: Query<any>;
+    requestHeaders?: Record<string, string>;
+    customOptions?: Record<string, unknown>;
+  }): Promise<HTTPClientResponse> {
     const format = getAcceptFormat(query);
-    const fullHeaders = { ...requestHeaders, accept: format };
+    const fullHeaders = { ...(requestHeaders ?? {}), accept: format };
 
     try {
       const res = await this.bc.get(
         relativePath,
-        removeFalsyOrEmpty(query),
-        fullHeaders
+        query ? removeFalsyOrEmpty(query) : undefined,
+        fullHeaders,
+        customOptions
       );
 
-      return HTTPClient.prepareResponse(res, format, parseBody, jsonOptions);
+      return HTTPClient.prepareResponse(res, format);
     } catch (err) {
       throw HTTPClient.prepareResponseError(err);
     }
@@ -252,17 +303,24 @@ export default class HTTPClient {
    * Send a POST request.
    * If no content-type present, adds the header "content-type: application/json"
    * and data is serialized in JSON (if not empty)
+   * @param options - The options to use for the request.
    */
-  async post(
-    relativePath: string,
-    data: any,
-    requestHeaders: Record<string, string> = {},
-    query?: Query<any>,
-    parseBody: boolean = true
-  ): Promise<HTTPClientResponse> {
+  async post({
+    relativePath,
+    data,
+    query,
+    requestHeaders,
+    customOptions,
+  }: {
+    relativePath: string;
+    data: any;
+    query?: Query<any>;
+    requestHeaders?: Record<string, string>;
+    customOptions?: Record<string, unknown>;
+  }): Promise<HTTPClientResponse> {
     const fullHeaders = {
       'content-type': 'application/json',
-      ...tolowerCaseKeys(requestHeaders),
+      ...tolowerCaseKeys(requestHeaders ?? {}),
     };
 
     try {
@@ -270,10 +328,11 @@ export default class HTTPClient {
         relativePath,
         HTTPClient.serializeData(data, fullHeaders),
         query,
-        fullHeaders
+        fullHeaders,
+        customOptions
       );
 
-      return HTTPClient.prepareResponse(res, 'application/json', parseBody);
+      return HTTPClient.prepareResponse(res, 'application/json');
     } catch (err) {
       throw HTTPClient.prepareResponseError(err);
     }
@@ -283,25 +342,38 @@ export default class HTTPClient {
    * Send a DELETE request.
    * If no content-type present, adds the header "content-type: application/json"
    * and data is serialized in JSON (if not empty)
+   * @param options - The options to use for the request.
    */
-  async delete(
-    relativePath: string,
-    data: any,
-    requestHeaders: Record<string, string> = {},
-    parseBody: boolean = true
-  ) {
+  async delete({
+    relativePath,
+    data,
+    requestHeaders,
+    customOptions,
+  }: {
+    relativePath: string;
+    data: any;
+    requestHeaders?: Record<string, string>;
+    customOptions?: Record<string, unknown>;
+  }) {
     const fullHeaders = {
       'content-type': 'application/json',
-      ...tolowerCaseKeys(requestHeaders),
+      ...tolowerCaseKeys(requestHeaders ?? {}),
     };
 
-    const res = await this.bc.delete(
-      relativePath,
-      HTTPClient.serializeData(data, fullHeaders),
-      undefined,
-      fullHeaders
-    );
+    try {
+      const res = await this.bc.delete(
+        relativePath,
+        typeof data !== 'undefined'
+          ? HTTPClient.serializeData(data, fullHeaders)
+          : undefined,
+        undefined,
+        fullHeaders,
+        customOptions
+      );
 
-    return HTTPClient.prepareResponse(res, 'application/json', parseBody);
+      return HTTPClient.prepareResponse(res, 'application/json');
+    } catch (err) {
+      throw HTTPClient.prepareResponseError(err);
+    }
   }
 }