algosdk 2.9.0 → 3.0.0-beta.1

package/src/encoding/schema/optional.ts

@@ -0,0 +1,72 @@
+import {
+  Schema,
+  MsgpackEncodingData,
+  MsgpackRawStringProvider,
+  JSONEncodingData,
+  PrepareJSONOptions,
+} from '../encoding.js';
+
+/* eslint-disable class-methods-use-this */
+
+/**
+ * OptionalSchema allows for another schema-defined value to be optional.
+ *
+ * This expands the set of values which can be represented by the given schema to include `undefined`.
+ *
+ * Note that this schema considers `undefined` _and_ any default values from the underlying schema
+ * to all be default values. This means that when using NamedMapSchema to omit default values, an
+ * `undefined` value is indistinguishable from the given schema's default value; in this respect,
+ * OptionalSchema does not affect the encoding of NamedMapSchema values, but rather allows the
+ * application to restore omitted values as `undefined` instead of their default value.
+ *
+ * Upon decoding, this schema also allows null/undefined values to be acceptable as values.
+ */
+export class OptionalSchema extends Schema {
+  constructor(public readonly valueSchema: Schema) {
+    super();
+  }
+
+  public defaultValue(): undefined {
+    return undefined;
+  }
+
+  public isDefaultValue(data: unknown): boolean {
+    return data === undefined || this.valueSchema.isDefaultValue(data);
+  }
+
+  public prepareMsgpack(data: unknown): MsgpackEncodingData {
+    if (data === undefined) {
+      return undefined;
+    }
+    return this.valueSchema.prepareMsgpack(data);
+  }
+
+  public fromPreparedMsgpack(
+    encoded: MsgpackEncodingData,
+    rawStringProvider: MsgpackRawStringProvider
+  ): unknown {
+    // JS undefined is encoded as msgpack nil, which may be decoded as JS null
+    if (encoded === undefined || encoded === null) {
+      return undefined;
+    }
+    return this.valueSchema.fromPreparedMsgpack(encoded, rawStringProvider);
+  }
+
+  public prepareJSON(
+    data: unknown,
+    options: PrepareJSONOptions
+  ): JSONEncodingData {
+    if (data === undefined) {
+      // JSON representation does not have undefined, only null
+      return null;
+    }
+    return this.valueSchema.prepareJSON(data, options);
+  }
+
+  public fromPreparedJSON(encoded: JSONEncodingData): unknown {
+    if (encoded === undefined || encoded === null) {
+      return undefined;
+    }
+    return this.valueSchema.fromPreparedJSON(encoded);
+  }
+}

package/src/encoding/schema/string.ts

@@ -0,0 +1,55 @@
+import {
+  Schema,
+  MsgpackEncodingData,
+  MsgpackRawStringProvider,
+  JSONEncodingData,
+  PrepareJSONOptions,
+} from '../encoding.js';
+
+/* eslint-disable class-methods-use-this */
+
+export class StringSchema extends Schema {
+  public defaultValue(): string {
+    return '';
+  }
+
+  public isDefaultValue(data: unknown): boolean {
+    return data === '';
+  }
+
+  public prepareMsgpack(data: unknown): MsgpackEncodingData {
+    if (typeof data === 'string') {
+      return data;
+    }
+    throw new Error(`Invalid string: (${typeof data}) ${data}`);
+  }
+
+  public fromPreparedMsgpack(
+    encoded: MsgpackEncodingData,
+    // eslint-disable-next-line @typescript-eslint/no-unused-vars
+    _rawStringProvider: MsgpackRawStringProvider
+  ): string {
+    if (typeof encoded === 'string') {
+      return encoded;
+    }
+    throw new Error(`Invalid string: (${typeof encoded}) ${encoded}`);
+  }
+
+  public prepareJSON(
+    data: unknown,
+    // eslint-disable-next-line @typescript-eslint/no-unused-vars
+    _options: PrepareJSONOptions
+  ): JSONEncodingData {
+    if (typeof data === 'string') {
+      return data;
+    }
+    throw new Error(`Invalid string: (${typeof data}) ${data}`);
+  }
+
+  public fromPreparedJSON(encoded: JSONEncodingData): string {
+    if (typeof encoded === 'string') {
+      return encoded;
+    }
+    throw new Error(`Invalid string: (${typeof encoded}) ${encoded}`);
+  }
+}

package/src/encoding/schema/uint64.ts

@@ -0,0 +1,46 @@
+import {
+  Schema,
+  MsgpackEncodingData,
+  MsgpackRawStringProvider,
+  JSONEncodingData,
+  PrepareJSONOptions,
+} from '../encoding.js';
+import { ensureUint64 } from '../../utils/utils.js';
+
+/* eslint-disable class-methods-use-this */
+
+export class Uint64Schema extends Schema {
+  public defaultValue(): bigint {
+    return BigInt(0);
+  }
+
+  public isDefaultValue(data: unknown): boolean {
+    if (typeof data === 'bigint') return data === BigInt(0);
+    if (typeof data === 'number') return data === 0;
+    return false;
+  }
+
+  public prepareMsgpack(data: unknown): MsgpackEncodingData {
+    return ensureUint64(data);
+  }
+
+  public fromPreparedMsgpack(
+    encoded: MsgpackEncodingData,
+    // eslint-disable-next-line @typescript-eslint/no-unused-vars
+    _rawStringProvider: MsgpackRawStringProvider
+  ): bigint {
+    return ensureUint64(encoded);
+  }
+
+  public prepareJSON(
+    data: unknown,
+    // eslint-disable-next-line @typescript-eslint/no-unused-vars
+    _options: PrepareJSONOptions
+  ): JSONEncodingData {
+    return ensureUint64(data);
+  }
+
+  public fromPreparedJSON(encoded: JSONEncodingData): bigint {
+    return ensureUint64(encoded);
+  }
+}

package/src/encoding/schema/untyped.ts

@@ -0,0 +1,47 @@
+import {
+  Schema,
+  MsgpackEncodingData,
+  MsgpackRawStringProvider,
+  JSONEncodingData,
+  PrepareJSONOptions,
+  msgpackEncodingDataToJSONEncodingData,
+  jsonEncodingDataToMsgpackEncodingData,
+} from '../encoding.js';
+
+/* eslint-disable class-methods-use-this */
+
+export class UntypedSchema extends Schema {
+  public defaultValue(): undefined {
+    return undefined;
+  }
+
+  public isDefaultValue(data: unknown): boolean {
+    return data === undefined;
+  }
+
+  public prepareMsgpack(data: unknown): MsgpackEncodingData {
+    // Value is already MsgpackEncodingData, since it is returned as such from
+    // fromPreparedMsgpack and fromPreparedJSON
+    return data as MsgpackEncodingData;
+  }
+
+  public fromPreparedMsgpack(
+    encoded: MsgpackEncodingData,
+    // eslint-disable-next-line @typescript-eslint/no-unused-vars
+    _rawStringProvider: MsgpackRawStringProvider
+  ): MsgpackEncodingData {
+    return encoded;
+  }
+
+  public prepareJSON(
+    data: unknown,
+    // eslint-disable-next-line @typescript-eslint/no-unused-vars
+    _options: PrepareJSONOptions
+  ): JSONEncodingData {
+    return msgpackEncodingDataToJSONEncodingData(data as MsgpackEncodingData);
+  }
+
+  public fromPreparedJSON(encoded: JSONEncodingData): MsgpackEncodingData {
+    return jsonEncodingDataToMsgpackEncodingData(encoded);
+  }
+}

package/src/encoding/uint64.ts

@@ -1,4 +1,4 @@
-import { concatArrays } from '../utils/utils';
+import { concatArrays } from '../utils/utils.js';
 
 // NOTE: at the moment we specifically do not use Buffer.writeBigUInt64BE and
 // Buffer.readBigUInt64BE. This is because projects using webpack v4
@@ -50,6 +50,7 @@ export function decodeUint64(
   decodingMode: 'mixed'
 ): number | bigint;
 export function decodeUint64(data: Uint8Array, decodingMode: 'bigint'): bigint;
+export function decodeUint64(data: Uint8Array): number;
 export function decodeUint64(data: any, decodingMode: any = 'safe') {
   if (
     decodingMode !== 'safe' &&

package/src/group.ts

@@ -1,98 +1,50 @@
-import { Buffer } from 'buffer';
-import * as txnBuilder from './transaction';
-import * as nacl from './nacl/naclWrappers';
-import * as encoding from './encoding/encoding';
-import * as address from './encoding/address';
-import * as utils from './utils/utils';
+import { Transaction } from './transaction.js';
+import * as nacl from './nacl/naclWrappers.js';
+import { msgpackRawEncode } from './encoding/encoding.js';
+import * as utils from './utils/utils.js';
 
 const ALGORAND_MAX_TX_GROUP_SIZE = 16;
+const TX_GROUP_TAG = new TextEncoder().encode('TG');
 
-interface EncodedTxGroup {
-  txlist: Buffer[];
-}
-
-/**
- * Aux class for group id calculation of a group of transactions
- */
-export class TxGroup {
-  name = 'Transaction group';
-  tag = Buffer.from('TG');
-  txGroupHashes: Buffer[];
-
-  constructor(hashes: Buffer[]) {
-    if (hashes.length > ALGORAND_MAX_TX_GROUP_SIZE) {
-      const errorMsg = `${hashes.length.toString()} transactions grouped together but max group size is ${ALGORAND_MAX_TX_GROUP_SIZE.toString()}`;
-      throw Error(errorMsg);
-    }
-
-    this.txGroupHashes = hashes;
+function txGroupPreimage(txnHashes: Uint8Array[]): Uint8Array {
+  if (txnHashes.length > ALGORAND_MAX_TX_GROUP_SIZE) {
+    throw new Error(
+      `${txnHashes.length} transactions grouped together but max group size is ${ALGORAND_MAX_TX_GROUP_SIZE}`
+    );
   }
-
-  // eslint-disable-next-line camelcase
-  get_obj_for_encoding() {
-    const txgroup: EncodedTxGroup = {
-      txlist: this.txGroupHashes,
-    };
-    return txgroup;
-  }
-
-  // eslint-disable-next-line camelcase
-  static from_obj_for_encoding(txgroupForEnc: EncodedTxGroup) {
-    const txn = Object.create(this.prototype);
-    txn.name = 'Transaction group';
-    txn.tag = Buffer.from('TG');
-    txn.txGroupHashes = [];
-    for (const hash of txgroupForEnc.txlist) {
-      txn.txGroupHashes.push(Buffer.from(hash));
-    }
-    return txn;
-  }
-
-  toByte() {
-    return encoding.encode(this.get_obj_for_encoding());
+  if (txnHashes.length === 0) {
+    throw new Error('Cannot compute group ID of zero transactions');
   }
+  const bytes = msgpackRawEncode({
+    txlist: txnHashes,
+  });
+  return utils.concatArrays(TX_GROUP_TAG, bytes);
 }
 
 /**
  * computeGroupID returns group ID for a group of transactions
- * @param txns - array of transactions (every element is a dict or Transaction)
- * @returns Buffer
+ * @param txns - array of transactions
+ * @returns Uint8Array
  */
-export function computeGroupID(txns: txnBuilder.TransactionLike[]) {
-  const hashes = [];
+export function computeGroupID(txns: ReadonlyArray<Transaction>) {
+  const hashes: Uint8Array[] = [];
   for (const txn of txns) {
-    const tx = txnBuilder.instantiateTxnIfNeeded(txn);
-    hashes.push(tx.rawTxID());
+    hashes.push(txn.rawTxID());
   }
 
-  const txgroup = new TxGroup(hashes);
-
-  const bytes = txgroup.toByte();
-  const toBeHashed = Buffer.from(utils.concatArrays(txgroup.tag, bytes));
+  const toBeHashed = txGroupPreimage(hashes);
   const gid = nacl.genericHash(toBeHashed);
-  return Buffer.from(gid);
+  return Uint8Array.from(gid);
 }
 
 /**
  * assignGroupID assigns group id to a given list of unsigned transactions
- * @param txns - array of transactions (every element is a dict or Transaction)
- * @param from - optional sender address specifying which transaction return
- * @returns possible list of matching transactions
+ * @param txns - array of transactions. The array elements will be modified with the group id
  */
-export function assignGroupID(
-  txns: txnBuilder.TransactionLike[],
-  from?: string
-) {
+export function assignGroupID(txns: Transaction[]) {
   const gid = computeGroupID(txns);
-  const result: txnBuilder.Transaction[] = [];
   for (const txn of txns) {
-    const tx = txnBuilder.instantiateTxnIfNeeded(txn);
-    if (!from || address.encodeAddress(tx.from.publicKey) === from) {
-      tx.group = gid;
-      result.push(tx);
-    }
+    txn.group = gid;
   }
-  return result;
+  return txns;
 }
-
-export default TxGroup;

package/src/index.ts

@@ -1,4 +1,4 @@
-import * as algosdk from './main';
+import * as algosdk from './main.js';
 
-export * from './main';
+export * from './main.js';
 export default algosdk;

package/src/logic/sourcemap.ts

@@ -1,13 +1,46 @@
 import * as vlq from 'vlq';
 
-export class SourceMap {
-  version: number;
-  sources: string[];
-  names: string[];
-  mappings: string;
+/**
+ * Represents a location in a source file.
+ */
+export interface SourceLocation {
+  line: number;
+  column: number;
+  sourceIndex: number;
+  nameIndex?: number;
+}
+
+/**
+ * Represents the location of a specific PC in a source line.
+ */
+export interface PcLineLocation {
+  pc: number;
+  column: number;
+  nameIndex?: number;
+}
+
+/**
+ * Contains a mapping from TEAL program PC to source file location.
+ */
+export class ProgramSourceMap {
+  public readonly version: number;
+  /**
+   * A list of original sources used by the "mappings" entry.
+   */
+  public readonly sources: string[];
+  /**
+   * A list of symbol names used by the "mappings" entry.
+   */
+  public readonly names: string[];
+  /**
+   * A string with the encoded mapping data.
+   */
+  public readonly mappings: string;
 
-  pcToLine: { [key: number]: number };
-  lineToPc: { [key: number]: number[] };
+  private pcToLocation: Map<number, SourceLocation>;
+
+  // Key is `${sourceIndex}:${line}`
+  private sourceAndLineToPc: Map<string, PcLineLocation[]>;
 
   constructor({
     version,
@@ -33,35 +66,67 @@ export class SourceMap {
         'mapping undefined, cannot build source map without `mapping`'
       );
 
-    const pcList = this.mappings.split(';').map((m) => {
-      const decoded = vlq.decode(m);
-      if (decoded.length > 2) return decoded[2];
-      return undefined;
-    });
-
-    this.pcToLine = {};
-    this.lineToPc = {};
-
-    let lastLine = 0;
-    for (const [pc, lineDelta] of pcList.entries()) {
-      // If the delta is not undefined, the lastLine should be updated with
-      // lastLine + the delta
-      if (lineDelta !== undefined) {
-        lastLine += lineDelta;
+    const pcList = this.mappings.split(';').map(vlq.decode);
+
+    this.pcToLocation = new Map();
+    this.sourceAndLineToPc = new Map();
+
+    const lastLocation = {
+      line: 0,
+      column: 0,
+      sourceIndex: 0,
+      nameIndex: 0,
+    } satisfies SourceLocation;
+    for (const [pc, data] of pcList.entries()) {
+      if (data.length < 4) continue;
+
+      const nameDelta = data.length > 4 ? data[4] : undefined;
+      const [, sourceDelta, lineDelta, columnDelta] = data;
+
+      lastLocation.sourceIndex += sourceDelta;
+      lastLocation.line += lineDelta;
+      lastLocation.column += columnDelta;
+      if (typeof nameDelta !== 'undefined') {
+        lastLocation.nameIndex += nameDelta;
       }
 
-      if (!(lastLine in this.lineToPc)) this.lineToPc[lastLine] = [];
+      const sourceAndLineKey = `${lastLocation.sourceIndex}:${lastLocation.line}`;
+      let pcsForSourceAndLine = this.sourceAndLineToPc.get(sourceAndLineKey);
+      if (pcsForSourceAndLine === undefined) {
+        pcsForSourceAndLine = [];
+        this.sourceAndLineToPc.set(sourceAndLineKey, pcsForSourceAndLine);
+      }
 
-      this.lineToPc[lastLine].push(pc);
-      this.pcToLine[pc] = lastLine;
+      const pcInLine: PcLineLocation = {
+        pc,
+        column: lastLocation.column,
+      };
+      const pcLocation: SourceLocation = {
+        line: lastLocation.line,
+        column: lastLocation.column,
+        sourceIndex: lastLocation.sourceIndex,
+      };
+      if (typeof nameDelta !== 'undefined') {
+        pcInLine.nameIndex = lastLocation.nameIndex;
+        pcLocation.nameIndex = lastLocation.nameIndex;
+      }
+
+      pcsForSourceAndLine.push(pcInLine);
+      this.pcToLocation.set(pc, pcLocation);
     }
   }
 
-  getLineForPc(pc: number): number | undefined {
-    return this.pcToLine[pc];
+  getPcs(): number[] {
+    return Array.from(this.pcToLocation.keys());
+  }
+
+  getLocationForPc(pc: number): SourceLocation | undefined {
+    return this.pcToLocation.get(pc);
   }
 
-  getPcsForLine(line: number): number[] | undefined {
-    return this.lineToPc[line];
+  getPcsOnSourceLine(sourceIndex: number, line: number): PcLineLocation[] {
+    const pcs = this.sourceAndLineToPc.get(`${sourceIndex}:${line}`);
+    if (pcs === undefined) return [];
+    return pcs;
   }
 }