algosdk 1.23.2 → 1.24.1

package/src/encoding/encoding.ts

@@ -0,0 +1,56 @@
+/**
+ * This file is a wrapper of msgpack.js.
+ * The wrapper was written in order to ensure correct encoding of Algorand Transaction and other formats.
+ * In particular, it matches go-algorand blockchain client, written in go (https://www.github.com/algorand/go-algorand.
+ * Algorand's msgpack encoding follows to following rules -
+ *  1. Every integer must be encoded to the smallest type possible (0-255-\>8bit, 256-65535-\>16bit, etx)
+ *  2. All fields names must be sorted
+ *  3. All empty and 0 fields should be omitted
+ *  4. Every positive number must be encoded as uint
+ *  5. Binary blob should be used for binary data and string for strings
+ *  */
+
+import * as msgpack from 'algo-msgpack-with-bigint';
+
+// Errors
+export const ERROR_CONTAINS_EMPTY_STRING =
+  'The object contains empty or 0 values. First empty or 0 value encountered during encoding: ';
+
+/**
+ * containsEmpty returns true if any of the object's values are empty, false otherwise.
+ * Empty arrays considered empty
+ * @param obj - The object to check
+ * @returns \{true, empty key\} if contains empty, \{false, undefined\} otherwise
+ */
+function containsEmpty(obj: Record<string | number | symbol, any>) {
+  for (const key in obj) {
+    if (Object.prototype.hasOwnProperty.call(obj, key)) {
+      if (!obj[key] || obj[key].length === 0) {
+        return { containsEmpty: true, firstEmptyKey: key };
+      }
+    }
+  }
+  return { containsEmpty: false, firstEmptyKey: undefined };
+}
+
+/**
+ * encode encodes objects using msgpack
+ * @param obj - a dictionary to be encoded. Must not contain empty or 0 values.
+ * @returns msgpack representation of the object
+ * @throws Error containing ERROR_CONTAINS_EMPTY_STRING if the object contains empty or zero values
+ */
+export function encode(obj: Record<string | number | symbol, any>) {
+  // Check for empty values
+  const emptyCheck = containsEmpty(obj);
+  if (emptyCheck.containsEmpty) {
+    throw new Error(ERROR_CONTAINS_EMPTY_STRING + emptyCheck.firstEmptyKey);
+  }
+
+  // enable the canonical option
+  const options = { sortKeys: true };
+  return msgpack.encode(obj, options);
+}
+
+export function decode(buffer: ArrayLike<number>) {
+  return msgpack.decode(buffer);
+}

package/src/encoding/uint64.ts

@@ -0,0 +1,84 @@
+/**
+ * encodeUint64 converts an integer to its binary representation.
+ * @param num - The number to convert. This must be an unsigned integer less than
+ *   2^64.
+ * @returns An 8-byte typed array containing the big-endian encoding of the input
+ *   integer.
+ */
+export function encodeUint64(num: number | bigint) {
+  const isInteger = typeof num === 'bigint' || Number.isInteger(num);
+
+  if (!isInteger || num < 0 || num > BigInt('0xffffffffffffffff')) {
+    throw new Error('Input is not a 64-bit unsigned integer');
+  }
+
+  const buf = Buffer.allocUnsafe(8);
+
+  buf.writeBigUInt64BE(BigInt(num));
+
+  return new Uint8Array(buf);
+}
+
+/**
+ * decodeUint64 produces an integer from a binary representation.
+ * @param data - An typed array containing the big-endian encoding of an unsigned integer
+ *   less than 2^64. This array must be at most 8 bytes long.
+ * @param decodingMode - Configure how the integer will be
+ *   decoded.
+ *
+ *   The options are:
+ *   * "safe": The integer will be decoded as a Number, but if it is greater than
+ *     Number.MAX_SAFE_INTEGER an error will be thrown.
+ *   * "mixed": The integer will be decoded as a Number if it is less than or equal to
+ *     Number.MAX_SAFE_INTEGER, otherwise it will be decoded as a BigInt.
+ *   * "bigint": The integer will always be decoded as a BigInt.
+ *
+ *   Defaults to "safe" if not included.
+ * @returns The integer that was encoded in the input data. The return type will
+ *   be determined by the parameter decodingMode.
+ */
+export function decodeUint64(data: Uint8Array, decodingMode: 'safe'): number;
+export function decodeUint64(
+  data: Uint8Array,
+  decodingMode: 'mixed'
+): number | bigint;
+export function decodeUint64(data: Uint8Array, decodingMode: 'bigint'): bigint;
+export function decodeUint64(data: any, decodingMode: any = 'safe') {
+  if (
+    decodingMode !== 'safe' &&
+    decodingMode !== 'mixed' &&
+    decodingMode !== 'bigint'
+  ) {
+    throw new Error(`Unknown decodingMode option: ${decodingMode}`);
+  }
+
+  if (data.byteLength === 0 || data.byteLength > 8) {
+    throw new Error(
+      `Data has unacceptable length. Expected length is between 1 and 8, got ${data.byteLength}`
+    );
+  }
+
+  // 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 num = buf.readBigUInt64BE();
+  const isBig = num > Number.MAX_SAFE_INTEGER;
+
+  if (decodingMode === 'safe') {
+    if (isBig) {
+      throw new Error(
+        `Integer exceeds maximum safe integer: ${num.toString()}. Try decoding with "mixed" or "safe" decodingMode.`
+      );
+    }
+    return Number(num);
+  }
+
+  if (decodingMode === 'mixed' && !isBig) {
+    return Number(num);
+  }
+
+  return num;
+}

package/src/group.ts

@@ -0,0 +1,97 @@
+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';
+
+const ALGORAND_MAX_TX_GROUP_SIZE = 16;
+
+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;
+  }
+
+  // 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());
+  }
+}
+
+/**
+ * computeGroupID returns group ID for a group of transactions
+ * @param txns - array of transactions (every element is a dict or Transaction)
+ * @returns Buffer
+ */
+export function computeGroupID(txns: txnBuilder.TransactionLike[]) {
+  const hashes = [];
+  for (const txn of txns) {
+    const tx = txnBuilder.instantiateTxnIfNeeded(txn);
+    hashes.push(tx.rawTxID());
+  }
+
+  const txgroup = new TxGroup(hashes);
+
+  const bytes = txgroup.toByte();
+  const toBeHashed = Buffer.from(utils.concatArrays(txgroup.tag, bytes));
+  const gid = nacl.genericHash(toBeHashed);
+  return Buffer.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
+ */
+export function assignGroupID(
+  txns: txnBuilder.TransactionLike[],
+  from?: string
+) {
+  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);
+    }
+  }
+  return result;
+}
+
+export default TxGroup;

package/src/index.ts

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