algosdk 1.24.0 → 1.24.1

package/src/dryrun.ts

@@ -0,0 +1,468 @@
+import AlgodClient from './client/v2/algod/algod';
+import {
+  AccountStateDelta,
+  Application,
+  ApplicationParams,
+  ApplicationStateSchema,
+  DryrunRequest,
+  DryrunSource,
+  EvalDeltaKeyValue,
+  TealValue,
+} from './client/v2/algod/models/types';
+import { SignedTransaction } from './transaction';
+import { TransactionType } from './types/transactions';
+import { encodeAddress, getApplicationAddress } from './encoding/address';
+
+const defaultAppId = 1380011588;
+const defaultMaxWidth = 30;
+
+// When writing the DryrunRequest object as msgpack the output needs to be the byte arrays not b64 string
+interface AppParamsWithPrograms {
+  ['approval-program']: string | Uint8Array;
+  ['clear-state-program']: string | Uint8Array;
+  ['creator']: string;
+}
+
+interface AppWithAppParams {
+  ['params']: AppParamsWithPrograms;
+}
+
+function decodePrograms(ap: AppWithAppParams): AppWithAppParams {
+  // eslint-disable-next-line no-param-reassign
+  ap.params['approval-program'] = Buffer.from(
+    ap.params['approval-program'].toString(),
+    'base64'
+  );
+  // eslint-disable-next-line no-param-reassign
+  ap.params['clear-state-program'] = Buffer.from(
+    ap.params['clear-state-program'].toString(),
+    'base64'
+  );
+
+  return ap;
+}
+
+/**
+ * createDryrun takes an Algod Client (from algod.AlgodV2Client) and an array of Signed Transactions
+ * from (transaction.SignedTransaction) and creates a DryrunRequest object with relevant balances
+ * @param client - the AlgodClient to make requests against
+ * @param txns - the array of SignedTransaction to use for generating the DryrunRequest object
+ * @param protocolVersion - the string representing the protocol version to use
+ * @param latestTimestamp - the timestamp
+ * @returns the DryrunRequest object constructed from the SignedTransactions passed
+ */
+export async function createDryrun({
+  client,
+  txns,
+  protocolVersion,
+  latestTimestamp,
+  round,
+  sources,
+}: {
+  client: AlgodClient;
+  txns: SignedTransaction[];
+  protocolVersion?: string;
+  latestTimestamp?: number | bigint;
+  round?: number | bigint;
+  sources?: DryrunSource[];
+}): Promise<DryrunRequest> {
+  const appInfos = [];
+  const acctInfos = [];
+
+  const apps: number[] = [];
+  const assets: number[] = [];
+  const accts: string[] = [];
+
+  for (const t of txns) {
+    if (t.txn.type === TransactionType.appl) {
+      accts.push(encodeAddress(t.txn.from.publicKey));
+
+      if (t.txn.appAccounts)
+        accts.push(...t.txn.appAccounts.map((a) => encodeAddress(a.publicKey)));
+
+      if (t.txn.appForeignApps) {
+        apps.push(...t.txn.appForeignApps);
+        accts.push(
+          ...t.txn.appForeignApps.map((aidx) => getApplicationAddress(aidx))
+        );
+      }
+
+      if (t.txn.appForeignAssets) assets.push(...t.txn.appForeignAssets);
+
+      // Create application,
+      if (t.txn.appIndex === undefined || t.txn.appIndex === 0) {
+        appInfos.push(
+          new Application(
+            defaultAppId,
+            new ApplicationParams({
+              creator: encodeAddress(t.txn.from.publicKey),
+              approvalProgram: t.txn.appApprovalProgram,
+              clearStateProgram: t.txn.appClearProgram,
+              localStateSchema: new ApplicationStateSchema(
+                t.txn.appLocalInts,
+                t.txn.appLocalByteSlices
+              ),
+              globalStateSchema: new ApplicationStateSchema(
+                t.txn.appGlobalInts,
+                t.txn.appGlobalByteSlices
+              ),
+            })
+          )
+        );
+      } else {
+        apps.push(t.txn.appIndex);
+        accts.push(getApplicationAddress(t.txn.appIndex));
+      }
+    }
+  }
+
+  // Dedupe and add creator to accts array
+  const assetPromises = [];
+  for (const assetId of [...new Set(assets)]) {
+    assetPromises.push(
+      client
+        .getAssetByID(assetId)
+        .do()
+        .then((assetInfo) => {
+          accts.push(assetInfo.params.creator);
+        })
+    );
+  }
+  // Wait for assets to finish since we append to accts array
+  await Promise.all(assetPromises);
+
+  // Dedupe and get app info for all apps
+  const appPromises = [];
+  for (const appId of [...new Set(apps)]) {
+    appPromises.push(
+      client
+        .getApplicationByID(appId)
+        .do()
+        .then((appInfo) => {
+          const ai = decodePrograms(appInfo as AppWithAppParams);
+          appInfos.push(ai);
+          accts.push(ai.params.creator);
+        })
+    );
+  }
+  await Promise.all(appPromises);
+
+  const acctPromises = [];
+  for (const acct of [...new Set(accts)]) {
+    acctPromises.push(
+      client
+        .accountInformation(acct)
+        .do()
+        .then((acctInfo) => {
+          if ('created-apps' in acctInfo) {
+            // eslint-disable-next-line no-param-reassign
+            acctInfo['created-apps'] = acctInfo['created-apps'].map((app) =>
+              decodePrograms(app)
+            );
+          }
+          acctInfos.push(acctInfo);
+        })
+    );
+  }
+  await Promise.all(acctPromises);
+
+  return new DryrunRequest({
+    txns: txns.map((st) => ({ ...st, txn: st.txn.get_obj_for_encoding() })),
+    accounts: acctInfos,
+    apps: appInfos,
+    latestTimestamp,
+    round,
+    protocolVersion,
+    sources,
+  });
+}
+
+interface StackValueResponse {
+  type: number;
+  bytes: string;
+  uint: number;
+}
+
+class DryrunStackValue {
+  type: number = 0;
+  bytes: string = '';
+  uint: number = 0;
+
+  constructor(sv: StackValueResponse) {
+    this.type = sv.type;
+    this.bytes = sv.bytes;
+    this.uint = sv.uint;
+  }
+
+  toString(): string {
+    if (this.type === 1) {
+      return `0x${Buffer.from(this.bytes, 'base64').toString('hex')}`;
+    }
+    return this.uint.toString();
+  }
+}
+
+interface DryrunTraceLineResponse {
+  error: string;
+  line: number;
+  pc: number;
+  scratch: TealValue[];
+  stack: StackValueResponse[];
+}
+
+class DryrunTraceLine {
+  error: string = '';
+  line: number = 0;
+  pc: number = 0;
+  scratch: TealValue[] = [];
+  stack: DryrunStackValue[] = [];
+
+  constructor(line: DryrunTraceLineResponse) {
+    this.error = line.error === undefined ? '' : line.error;
+    this.line = line.line;
+    this.pc = line.pc;
+    this.scratch = line.scratch;
+    this.stack = line.stack.map(
+      (sv: StackValueResponse) => new DryrunStackValue(sv)
+    );
+  }
+}
+
+class DryrunTrace {
+  trace: DryrunTraceLine[] = [];
+  constructor(t: DryrunTraceLineResponse[]) {
+    if (t == null) return;
+    this.trace = t.map((line) => new DryrunTraceLine(line));
+  }
+}
+
+interface DryrunTransactionResultResponse {
+  disassembly: string[];
+  appCallMessages: string[] | undefined;
+  localDeltas: AccountStateDelta[] | undefined;
+  globalDelta: EvalDeltaKeyValue[] | undefined;
+  cost: number | undefined;
+  logicSigMessages: string[] | undefined;
+  logicSigDisassembly: string[] | undefined;
+  logs: string[] | undefined;
+  appCallTrace: DryrunTrace | undefined;
+  logicSigTrace: DryrunTrace | undefined;
+}
+
+interface StackPrinterConfig {
+  maxValueWidth: number | undefined;
+  topOfStackFirst: boolean | undefined;
+}
+
+function truncate(str: string, maxValueWidth: number): string {
+  if (str.length > maxValueWidth && maxValueWidth > 0) {
+    return `${str.slice(0, maxValueWidth)}...`;
+  }
+  return str;
+}
+
+function scratchToString(
+  prevScratch: TealValue[],
+  currScratch: TealValue[]
+): string {
+  if (currScratch.length === 0) return '';
+
+  let newScratchIdx = null;
+  for (let idx = 0; idx < currScratch.length; idx++) {
+    if (idx > prevScratch.length) {
+      newScratchIdx = idx;
+      continue;
+    }
+
+    if (JSON.stringify(prevScratch[idx]) !== JSON.stringify(currScratch[idx])) {
+      newScratchIdx = idx;
+    }
+  }
+
+  if (newScratchIdx == null) return '';
+
+  const newScratch = currScratch[newScratchIdx];
+  if (newScratch.bytes.length > 0) {
+    return `${newScratchIdx} = 0x${Buffer.from(
+      newScratch.bytes,
+      'base64'
+    ).toString('hex')}`;
+  }
+  return `${newScratchIdx} = ${newScratch.uint.toString()}`;
+}
+
+function stackToString(stack: DryrunStackValue[], reverse: boolean): string {
+  const svs = reverse ? stack.reverse() : stack;
+  return `[${svs
+    .map((sv: DryrunStackValue) => {
+      switch (sv.type) {
+        case 1:
+          return `0x${Buffer.from(sv.bytes, 'base64').toString('hex')}`;
+        case 2:
+          return `${sv.uint.toString()}`;
+        default:
+          return '';
+      }
+    })
+    .join(', ')}]`;
+}
+
+class DryrunTransactionResult {
+  disassembly: string[] = [];
+  appCallMessages: string[] | undefined = [];
+  localDeltas: AccountStateDelta[] | undefined = [];
+  globalDelta: EvalDeltaKeyValue[] | undefined = [];
+  cost: number | undefined = 0;
+  logicSigMessages: string[] | undefined = [];
+  logicSigDisassembly: string[] | undefined = [];
+  logs: string[] | undefined = [];
+
+  appCallTrace: DryrunTrace | undefined = undefined;
+  logicSigTrace: DryrunTrace | undefined = undefined;
+
+  required = ['disassembly'];
+  optionals = [
+    'app-call-messages',
+    'local-deltas',
+    'global-delta',
+    'cost',
+    'logic-sig-messages',
+    'logic-sig-disassembly',
+    'logs',
+  ];
+
+  traces = ['app-call-trace', 'logic-sig-trace'];
+
+  constructor(dtr: DryrunTransactionResultResponse) {
+    this.disassembly = dtr.disassembly;
+    this.appCallMessages = dtr['app-call-messages'];
+    this.localDeltas = dtr['local-deltas'];
+    this.globalDelta = dtr['global-delta'];
+    this.cost = dtr.cost;
+    this.logicSigMessages = dtr['logic-sig-messages'];
+    this.logicSigDisassembly = dtr['logic-sig-disassembly'];
+    this.logs = dtr.logs;
+    this.appCallTrace = new DryrunTrace(dtr['app-call-trace']);
+    this.logicSigTrace = new DryrunTrace(dtr['logic-sig-trace']);
+  }
+
+  appCallRejected(): boolean {
+    return (
+      this.appCallMessages !== undefined &&
+      this.appCallMessages.includes('REJECT')
+    );
+  }
+
+  logicSigRejected(): boolean {
+    return (
+      this.logicSigMessages !== undefined &&
+      this.logicSigMessages.includes('REJECT')
+    );
+  }
+
+  static trace(
+    drt: DryrunTrace,
+    disassembly: string[],
+    spc: StackPrinterConfig
+  ): string {
+    const maxWidth = spc.maxValueWidth || defaultMaxWidth;
+
+    // Create the array of arrays, each sub array contains N columns
+    const lines = [['pc#', 'ln#', 'source', 'scratch', 'stack']];
+    for (let idx = 0; idx < drt.trace.length; idx++) {
+      const { line, error, pc, scratch, stack } = drt.trace[idx];
+
+      const currScratch = scratch !== undefined ? scratch : [];
+      const prevScratch =
+        idx > 0 && drt.trace[idx - 1].scratch !== undefined
+          ? drt.trace[idx - 1].scratch
+          : [];
+
+      const src = error === '' ? disassembly[line] : `!! ${error} !!`;
+
+      lines.push([
+        pc.toString().padEnd(3, ' '),
+        line.toString().padEnd(3, ' '),
+        truncate(src, maxWidth),
+        truncate(scratchToString(prevScratch, currScratch), maxWidth),
+        truncate(stackToString(stack, spc.topOfStackFirst), maxWidth),
+      ]);
+    }
+
+    // Get the max length for each column
+    const maxLengths = lines.reduce((prev, curr) => {
+      const newVal = new Array(lines[0].length).fill(0);
+      for (let idx = 0; idx < prev.length; idx++) {
+        newVal[idx] =
+          curr[idx].length > prev[idx] ? curr[idx].length : prev[idx];
+      }
+      return newVal;
+    }, new Array(lines[0].length).fill(0));
+
+    return `${lines
+      .map((line) =>
+        line
+          .map((v, idx) => v.padEnd(maxLengths[idx] + 1, ' '))
+          .join('|')
+          .trim()
+      )
+      .join('\n')}\n`;
+  }
+
+  appTrace(spc?: StackPrinterConfig): string {
+    if (this.appCallTrace === undefined || !this.disassembly) return '';
+
+    let conf = spc;
+    if (spc === undefined)
+      conf = {
+        maxValueWidth: defaultMaxWidth,
+        topOfStackFirst: false,
+      } as StackPrinterConfig;
+
+    return DryrunTransactionResult.trace(
+      this.appCallTrace,
+      this.disassembly,
+      conf
+    );
+  }
+
+  lsigTrace(spc?: StackPrinterConfig): string {
+    if (
+      this.logicSigTrace === undefined ||
+      this.logicSigDisassembly === undefined
+    )
+      return '';
+
+    let conf = spc;
+    if (spc === undefined)
+      conf = {
+        maxValueWidth: defaultMaxWidth,
+        topOfStackFirst: true,
+      } as StackPrinterConfig;
+
+    return DryrunTransactionResult.trace(
+      this.logicSigTrace,
+      this.logicSigDisassembly,
+      conf
+    );
+  }
+}
+
+interface DryrunResultResponse {
+  ['error']: string;
+  ['protocol-version']: string;
+  ['txns']: DryrunTransactionResultResponse[];
+}
+
+export class DryrunResult {
+  error: string = '';
+  protocolVersion: string = '';
+  txns: DryrunTransactionResult[] = [];
+  constructor(drrResp: DryrunResultResponse) {
+    this.error = drrResp.error;
+    this.protocolVersion = drrResp['protocol-version'];
+    this.txns = drrResp.txns.map(
+      (txn: DryrunTransactionResultResponse) => new DryrunTransactionResult(txn)
+    );
+  }
+}

package/src/encoding/address.ts

@@ -0,0 +1,191 @@
+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;
+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';
+
+/**
+ * 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 {
+  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,
+      ALGORAND_ADDRESS_BYTE_LENGTH - ALGORAND_CHECKSUM_BYTE_LENGTH
+    )
+  );
+  const cs = new Uint8Array(
+    decoded.slice(nacl.PUBLIC_KEY_LENGTH, ALGORAND_ADDRESS_BYTE_LENGTH)
+  );
+
+  // Compute checksum
+  const checksum = nacl
+    .genericHash(pk)
+    .slice(
+      nacl.HASH_BYTES_LENGTH - ALGORAND_CHECKSUM_BYTE_LENGTH,
+      nacl.HASH_BYTES_LENGTH
+    );
+
+  // Check if the checksum and the address are equal
+  if (!utils.arrayEqual(checksum, cs))
+    throw new Error(CHECKSUM_ADDRESS_ERROR_MSG);
+
+  return { publicKey: pk, checksum: cs };
+}
+
+/**
+ * isValidAddress checks if a string is a valid Algorand address.
+ * @param address - an Algorand address with checksum.
+ * @returns true if valid, false otherwise
+ */
+export function isValidAddress(address: string) {
+  // Try to decode
+  try {
+    decodeAddress(address);
+  } catch (e) {
+    return false;
+  }
+  return true;
+}
+
+/**
+ * encodeAddress takes an Algorand address as a Uint8Array and encodes it into a string with checksum.
+ * @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 '===='
+}
+
+/**
+ * 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 }));
+}
+
+/**
+ * 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 {
+  const toBeSigned = utils.concatArrays(APP_ID_PREFIX, encodeUint64(appID));
+  const hash = nacl.genericHash(toBeSigned);
+  return encodeAddress(new Uint8Array(hash));
+}

package/src/encoding/bigint.ts

@@ -0,0 +1,33 @@
+/**
+ * bigIntToBytes converts a BigInt to a big-endian Uint8Array for encoding.
+ * @param bi - The bigint to convert.
+ * @param size - The size of the resulting byte array.
+ * @returns A byte array containing the big-endian encoding of the input bigint
+ */
+export function bigIntToBytes(bi: bigint | number, size: number) {
+  let hex = bi.toString(16);
+  // Pad the hex with zeros so it matches the size in bytes
+  if (hex.length !== size * 2) {
+    hex = hex.padStart(size * 2, '0');
+  }
+  const byteArray = new Uint8Array(hex.length / 2);
+  for (let i = 0, j = 0; i < hex.length / 2; i++, j += 2) {
+    byteArray[i] = parseInt(hex.slice(j, j + 2), 16);
+  }
+  return byteArray;
+}
+
+/**
+ * bytesToBigInt produces a bigint from a binary representation.
+ *
+ * @param bytes - The Uint8Array to convert.
+ * @returns The bigint that was encoded in the input data.
+ */
+export function bytesToBigInt(bytes: Uint8Array) {
+  let res = BigInt(0);
+  const buf = Buffer.from(bytes);
+  for (let i = 0; i < bytes.length; i++) {
+    res = BigInt(Number(buf.readUIntBE(i, 1))) + res * BigInt(256);
+  }
+  return res;
+}