algosdk 2.8.0 → 3.0.0-beta.1

package/src/encoding/address.ts

@@ -1,83 +1,145 @@
-import { Buffer } from 'buffer';
 import base32 from 'hi-base32';
-import * as nacl from '../nacl/naclWrappers';
-import * as utils from '../utils/utils';
-import { encodeUint64 } from './uint64';
-import { Address } from '../types/address';
-import { MultisigMetadata } from '../types/multisig';
-
-const ALGORAND_ADDRESS_BYTE_LENGTH = 36;
-const ALGORAND_CHECKSUM_BYTE_LENGTH = 4;
-const ALGORAND_ADDRESS_LENGTH = 58;
+import * as nacl from '../nacl/naclWrappers.js';
+import * as utils from '../utils/utils.js';
+import { encodeUint64 } from './uint64.js';
+import { bytesToHex } from './binarydata.js';
+
+export const ALGORAND_ADDRESS_BYTE_LENGTH = 36;
+export const ALGORAND_CHECKSUM_BYTE_LENGTH = 4;
+export const ALGORAND_ADDRESS_LENGTH = 58;
 export const ALGORAND_ZERO_ADDRESS_STRING =
   'AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAY5HFKQ';
 
-// Convert "MultisigAddr" UTF-8 to byte array
-const MULTISIG_PREIMG2ADDR_PREFIX = new Uint8Array([
-  77,
-  117,
-  108,
-  116,
-  105,
-  115,
-  105,
-  103,
-  65,
-  100,
-  100,
-  114,
-]);
-
-const APP_ID_PREFIX = Buffer.from('appID');
-
 export const MALFORMED_ADDRESS_ERROR_MSG = 'address seems to be malformed';
 export const CHECKSUM_ADDRESS_ERROR_MSG = 'wrong checksum for address';
-export const INVALID_MSIG_VERSION_ERROR_MSG = 'invalid multisig version';
-export const INVALID_MSIG_THRESHOLD_ERROR_MSG = 'bad multisig threshold';
-export const INVALID_MSIG_PK_ERROR_MSG =
-  'bad multisig public key - wrong length';
-export const UNEXPECTED_PK_LEN_ERROR_MSG =
-  'nacl public key length is not 32 bytes';
+
+function checksumFromPublicKey(pk: Uint8Array): Uint8Array {
+  return Uint8Array.from(
+    nacl
+      .genericHash(pk)
+      .slice(
+        nacl.HASH_BYTES_LENGTH - ALGORAND_CHECKSUM_BYTE_LENGTH,
+        nacl.HASH_BYTES_LENGTH
+      )
+  );
+}
 
 /**
- * decodeAddress takes an Algorand address in string form and decodes it into a Uint8Array.
- * @param address - an Algorand address with checksum.
- * @returns the decoded form of the address's public key and checksum
+ * Represents an Algorand address
  */
-export function decodeAddress(address: string): Address {
-  if (typeof address !== 'string' || address.length !== ALGORAND_ADDRESS_LENGTH)
-    throw new Error(MALFORMED_ADDRESS_ERROR_MSG);
-
-  // try to decode
-  const decoded = base32.decode.asBytes(address.toString());
-  // Sanity check
-  if (decoded.length !== ALGORAND_ADDRESS_BYTE_LENGTH)
-    throw new Error(MALFORMED_ADDRESS_ERROR_MSG);
-
-  // Find publickey and checksum
-  const pk = new Uint8Array(
-    decoded.slice(
-      0,
+export class Address {
+  /**
+   * The binary form of the address. For standard accounts, this is the public key.
+   */
+  public readonly publicKey: Uint8Array;
+
+  /**
+   * Create a new Address object from its binary form.
+   * @param publicKey - The binary form of the address. Must be 32 bytes.
+   */
+  constructor(publicKey: Uint8Array) {
+    if (!(publicKey instanceof Uint8Array)) {
+      throw new Error(
+        `${MALFORMED_ADDRESS_ERROR_MSG}: ${publicKey} is not Uint8Array, type ${typeof publicKey}`
+      );
+    }
+    if (
+      publicKey.length !==
       ALGORAND_ADDRESS_BYTE_LENGTH - ALGORAND_CHECKSUM_BYTE_LENGTH
     )
-  );
-  const cs = new Uint8Array(
-    decoded.slice(nacl.PUBLIC_KEY_LENGTH, ALGORAND_ADDRESS_BYTE_LENGTH)
-  );
+      throw new Error(
+        `${MALFORMED_ADDRESS_ERROR_MSG}: 0x${bytesToHex(publicKey)}, length ${publicKey.length}`
+      );
+    this.publicKey = publicKey;
+  }
 
-  // Compute checksum
-  const checksum = nacl
-    .genericHash(pk)
-    .slice(
-      nacl.HASH_BYTES_LENGTH - ALGORAND_CHECKSUM_BYTE_LENGTH,
-      nacl.HASH_BYTES_LENGTH
+  /**
+   * Check if the address is equal to another address.
+   */
+  equals(other: Address): boolean {
+    return (
+      other instanceof Address &&
+      utils.arrayEqual(this.publicKey, other.publicKey)
     );
+  }
+
+  /**
+   * Compute the 4 byte checksum of the address.
+   */
+  checksum(): Uint8Array {
+    return checksumFromPublicKey(this.publicKey);
+  }
+
+  /**
+   * Encode the address into a string form.
+   */
+  toString(): string {
+    const addr = base32.encode(
+      utils.concatArrays(this.publicKey, this.checksum())
+    );
+    return addr.slice(0, ALGORAND_ADDRESS_LENGTH); // removing the extra '===='
+  }
 
-  // Check if the checksum and the address are equal
-  if (!utils.arrayEqual(checksum, cs))
-    throw new Error(CHECKSUM_ADDRESS_ERROR_MSG);
+  /**
+   * Decode an address from a string.
+   * @param address - The address to decode. Must be 58 bytes long.
+   * @returns An Address object corresponding to the input string.
+   */
+  static fromString(address: string): Address {
+    if (typeof address !== 'string')
+      throw new Error(
+        `${MALFORMED_ADDRESS_ERROR_MSG}: expected string, got ${typeof address}, ${address}`
+      );
+    if (address.length !== ALGORAND_ADDRESS_LENGTH)
+      throw new Error(
+        `${MALFORMED_ADDRESS_ERROR_MSG}: expected length ${ALGORAND_ADDRESS_LENGTH}, got ${address.length}: ${address}`
+      );
+
+    // try to decode
+    const decoded = base32.decode.asBytes(address);
+    // Sanity check
+    if (decoded.length !== ALGORAND_ADDRESS_BYTE_LENGTH)
+      throw new Error(
+        `${MALFORMED_ADDRESS_ERROR_MSG}: expected byte length ${ALGORAND_ADDRESS_BYTE_LENGTH}, got ${decoded.length}`
+      );
+
+    // Find publickey and checksum
+    const pk = new Uint8Array(
+      decoded.slice(
+        0,
+        ALGORAND_ADDRESS_BYTE_LENGTH - ALGORAND_CHECKSUM_BYTE_LENGTH
+      )
+    );
+    const cs = new Uint8Array(
+      decoded.slice(nacl.PUBLIC_KEY_LENGTH, ALGORAND_ADDRESS_BYTE_LENGTH)
+    );
+    const checksum = checksumFromPublicKey(pk);
+    // Check if the checksum and the address are equal
+    if (!utils.arrayEqual(checksum, cs))
+      throw new Error(CHECKSUM_ADDRESS_ERROR_MSG);
+
+    return new Address(pk);
+  }
 
-  return { publicKey: pk, checksum: cs };
+  /**
+   * Get the zero address.
+   */
+  static zeroAddress(): Address {
+    return new Address(
+      new Uint8Array(
+        ALGORAND_ADDRESS_BYTE_LENGTH - ALGORAND_CHECKSUM_BYTE_LENGTH
+      )
+    );
+  }
+}
+
+/**
+ * decodeAddress takes an Algorand address in string form and decodes it into a Uint8Array.
+ * @param address - an Algorand address with checksum.
+ * @returns the decoded form of the address's public key and checksum
+ */
+export function decodeAddress(address: string): Address {
+  return Address.fromString(address);
 }
 
 /**
@@ -85,10 +147,10 @@ export function decodeAddress(address: string): Address {
  * @param address - an Algorand address with checksum.
  * @returns true if valid, false otherwise
  */
-export function isValidAddress(address: string) {
+export function isValidAddress(address: string): boolean {
   // Try to decode
   try {
-    decodeAddress(address);
+    Address.fromString(address);
   } catch (e) {
     return false;
   }
@@ -100,93 +162,19 @@ export function isValidAddress(address: string) {
  * @param address - a raw Algorand address
  * @returns the address and checksum encoded as a string.
  */
-export function encodeAddress(address: Uint8Array) {
-  // compute checksum
-  const checksum = nacl
-    .genericHash(address)
-    .slice(
-      nacl.PUBLIC_KEY_LENGTH - ALGORAND_CHECKSUM_BYTE_LENGTH,
-      nacl.PUBLIC_KEY_LENGTH
-    );
-  const addr = base32.encode(utils.concatArrays(address, checksum));
-
-  return addr.toString().slice(0, ALGORAND_ADDRESS_LENGTH); // removing the extra '===='
+export function encodeAddress(address: Uint8Array): string {
+  return new Address(address).toString();
 }
 
-/**
- * fromMultisigPreImg takes multisig parameters and returns a 32 byte typed array public key,
- * representing an address that identifies the "exact group, version, and public keys" that are required for signing.
- * Hash("MultisigAddr" || version uint8 || threshold uint8 || PK1 || PK2 || ...)
- * Encoding this output yields a human readable address.
- * @param version - multisig version
- * @param threshold - multisig threshold
- * @param pks - array of typed array public keys
- */
-export function fromMultisigPreImg({
-  version,
-  threshold,
-  pks,
-}: Omit<MultisigMetadata, 'addrs'> & {
-  pks: Uint8Array[];
-}) {
-  if (version !== 1 || version > 255 || version < 0) {
-    // ^ a tad redundant, but in case in the future version != 1, still check for uint8
-    throw new Error(INVALID_MSIG_VERSION_ERROR_MSG);
-  }
-  if (
-    threshold === 0 ||
-    pks.length === 0 ||
-    threshold > pks.length ||
-    threshold > 255
-  ) {
-    throw new Error(INVALID_MSIG_THRESHOLD_ERROR_MSG);
-  }
-  const pkLen = ALGORAND_ADDRESS_BYTE_LENGTH - ALGORAND_CHECKSUM_BYTE_LENGTH;
-  if (pkLen !== nacl.PUBLIC_KEY_LENGTH) {
-    throw new Error(UNEXPECTED_PK_LEN_ERROR_MSG);
-  }
-  const merged = new Uint8Array(
-    MULTISIG_PREIMG2ADDR_PREFIX.length + 2 + pkLen * pks.length
-  );
-  merged.set(MULTISIG_PREIMG2ADDR_PREFIX, 0);
-  merged.set([version], MULTISIG_PREIMG2ADDR_PREFIX.length);
-  merged.set([threshold], MULTISIG_PREIMG2ADDR_PREFIX.length + 1);
-  for (let i = 0; i < pks.length; i++) {
-    if (pks[i].length !== pkLen) {
-      throw new Error(INVALID_MSIG_PK_ERROR_MSG);
-    }
-    merged.set(pks[i], MULTISIG_PREIMG2ADDR_PREFIX.length + 2 + i * pkLen);
-  }
-  return new Uint8Array(nacl.genericHash(merged));
-}
-
-/**
- * fromMultisigPreImgAddrs takes multisig parameters and returns a human readable Algorand address.
- * This is equivalent to fromMultisigPreImg, but interfaces with encoded addresses.
- * @param version - multisig version
- * @param threshold - multisig threshold
- * @param addrs - array of encoded addresses
- */
-export function fromMultisigPreImgAddrs({
-  version,
-  threshold,
-  addrs,
-}: {
-  version: number;
-  threshold: number;
-  addrs: string[];
-}) {
-  const pks = addrs.map((addr) => decodeAddress(addr).publicKey);
-  return encodeAddress(fromMultisigPreImg({ version, threshold, pks }));
-}
+const APP_ID_PREFIX = new TextEncoder().encode('appID');
 
 /**
  * Get the escrow address of an application.
  * @param appID - The ID of the application.
  * @returns The address corresponding to that application's escrow account.
  */
-export function getApplicationAddress(appID: number | bigint): string {
+export function getApplicationAddress(appID: number | bigint): Address {
   const toBeSigned = utils.concatArrays(APP_ID_PREFIX, encodeUint64(appID));
   const hash = nacl.genericHash(toBeSigned);
-  return encodeAddress(new Uint8Array(hash));
+  return new Address(Uint8Array.from(hash));
 }

package/src/encoding/bigint.ts

@@ -1,5 +1,3 @@
-import { Buffer } from 'buffer';
-
 /**
  * bigIntToBytes converts a BigInt to a big-endian Uint8Array for encoding.
  * @param bi - The bigint to convert.
@@ -27,9 +25,9 @@ export function bigIntToBytes(bi: bigint | number, size: number) {
  */
 export function bytesToBigInt(bytes: Uint8Array) {
   let res = BigInt(0);
-  const buf = Buffer.from(bytes);
+  const buf = new DataView(bytes.buffer, bytes.byteOffset);
   for (let i = 0; i < bytes.length; i++) {
-    res = BigInt(Number(buf.readUIntBE(i, 1))) + res * BigInt(256);
+    res = BigInt(Number(buf.getUint8(i))) + res * BigInt(256);
   }
   return res;
 }

package/src/encoding/binarydata.ts

@@ -0,0 +1,80 @@
+import { isNode } from '../utils/utils.js';
+
+/**
+ * Convert a base64 string to a Uint8Array for Node.js and browser environments.
+ * @returns A Uint8Array
+ */
+export function base64ToBytes(base64String: string): Uint8Array {
+  if (isNode()) {
+    return new Uint8Array(Buffer.from(base64String, 'base64'));
+  }
+  /* eslint-env browser */
+  const binString = atob(base64String);
+  return Uint8Array.from(binString, (m) => m.codePointAt(0)!);
+}
+
+/**
+ * Convert a Uint8Array to a base64 string for Node.js and browser environments.
+ * @returns A base64 string
+ */
+export function bytesToBase64(byteArray: Uint8Array): string {
+  if (isNode()) {
+    return Buffer.from(byteArray).toString('base64');
+  }
+  /* eslint-env browser */
+  const binString = Array.from(byteArray, (x) => String.fromCodePoint(x)).join(
+    ''
+  );
+  return btoa(binString);
+}
+
+/**
+ * Convert a byte array to a UTF-8 string. Warning: not all byte arrays are valid UTF-8.
+ * @returns A decoded string
+ */
+export function bytesToString(byteArray: Uint8Array): string {
+  return new TextDecoder().decode(byteArray);
+}
+
+/**
+ * Returns a Uint8Array given an input string or Uint8Array.
+ * @returns A base64 string
+ */
+export function coerceToBytes(input: Uint8Array | string): Uint8Array {
+  if (typeof input === 'string') {
+    return new TextEncoder().encode(input);
+  }
+  return input;
+}
+
+/**
+ * Convert a Uint8Array to a hex string for Node.js and browser environments.
+ * @returns A hex string
+ */
+export function bytesToHex(byteArray: Uint8Array): string {
+  if (isNode()) {
+    return Buffer.from(byteArray).toString('hex');
+  }
+  return Array.from(byteArray)
+    .map((i) => i.toString(16).padStart(2, '0'))
+    .join('');
+}
+
+/**
+ * Convert a hex string to Uint8Array for Node.js and browser environments.
+ * @returns A Uint8Array
+ */
+export function hexToBytes(hexString: string): Uint8Array {
+  if (isNode()) {
+    return Buffer.from(hexString, 'hex');
+  }
+  let hex = hexString;
+  if (hexString.length % 2 !== 0) {
+    hex = hexString.padStart(1, '0');
+  }
+  const byteArray = new Uint8Array(hex.length / 2);
+  for (let i = 0; i < hex.length / 2; i++) {
+    byteArray[i] = parseInt(hex.slice(2 * i, 2 * i + 2), 16);
+  }
+  return byteArray;
+}