refactor: move all implementation logic from algo-ts to algo-ts-testing

Author: boblat

examples/calculator/contract.spec.ts

@@ -1,5 +1,5 @@
-import { internal, Uint64 } from '@algorandfoundation/algorand-typescript'
-import { TestExecutionContext } from '@algorandfoundation/algorand-typescript-testing'
+import { Uint64 } from '@algorandfoundation/algorand-typescript'
+import { AvmError, TestExecutionContext } from '@algorandfoundation/algorand-typescript-testing'
 import { afterEach, describe, expect, it } from 'vitest'
 import MyContract from './contract.algo'
 
@@ -19,7 +19,7 @@ describe('Calculator', () => {
           }),
         ])
         .execute(() => {
-          expect(() => contract.approvalProgram()).toThrowError(new internal.errors.AvmError('Unknown operation'))
+          expect(() => contract.approvalProgram()).toThrowError(new AvmError('Unknown operation'))
         })
     })
   })

examples/voting/contract.spec.ts

@@ -1,5 +1,5 @@
 import { Bytes, Uint64 } from '@algorandfoundation/algorand-typescript'
-import { encodingUtil, TestExecutionContext } from '@algorandfoundation/algorand-typescript-testing'
+import { TestExecutionContext, toExternalValue } from '@algorandfoundation/algorand-typescript-testing'
 import { DynamicArray, UintN8 } from '@algorandfoundation/algorand-typescript/arc4'
 import nacl from 'tweetnacl'
 import { afterEach, describe, expect, it } from 'vitest'
@@ -50,7 +50,7 @@ describe('VotingRoundApp', () => {
     contract.bootstrap(ctx.any.txn.payment({ receiver: app.address, amount: boostrapMinBalanceReq }))
 
     const account = ctx.any.account()
-    const signature = nacl.sign.detached(encodingUtil.toExternalValue(account.bytes), keyPair.secretKey)
+    const signature = nacl.sign.detached(toExternalValue(account.bytes), keyPair.secretKey)
     ctx.txn.createScope([ctx.any.txn.applicationCall({ sender: account })]).execute(() => {
       const preconditions = contract.getPreconditions(Bytes(signature))
 
@@ -67,7 +67,7 @@ describe('VotingRoundApp', () => {
     contract.bootstrap(ctx.any.txn.payment({ receiver: app.address, amount: boostrapMinBalanceReq }))
 
     const account = ctx.any.account()
-    const signature = nacl.sign.detached(encodingUtil.toExternalValue(account.bytes), keyPair.secretKey)
+    const signature = nacl.sign.detached(toExternalValue(account.bytes), keyPair.secretKey)
     const answerIds = new DynamicArray<UintN8>(
       ...Array(13)
         .fill(0)

src/collections/custom-key-map.ts

@@ -1,5 +1,6 @@
 import type { Account } from '@algorandfoundation/algorand-typescript'
-import { internal } from '@algorandfoundation/algorand-typescript'
+import { internalError } from '../errors'
+import type { StubBytesCompat, StubUint64Compat } from '../impl/primitives'
 import type { DeliberateAny } from '../typescript-helpers'
 import { asBytesCls, asUint64Cls } from '../util'
 
@@ -29,7 +30,7 @@ export abstract class CustomKeyMap<TKey, TValue> implements Map<TKey, TValue> {
   getOrFail(key: TKey): TValue {
     const value = this.get(key)
     if (value === undefined) {
-      throw internal.errors.internalError('Key not found')
+      throw internalError('Key not found')
     }
     return value
   }
@@ -74,13 +75,13 @@ export class AccountMap<TValue> extends CustomKeyMap<Account, TValue> {
   }
 }
 
-export class BytesMap<TValue> extends CustomKeyMap<internal.primitives.StubBytesCompat, TValue> {
+export class BytesMap<TValue> extends CustomKeyMap<StubBytesCompat, TValue> {
   constructor() {
     super((bytes) => asBytesCls(bytes).valueOf())
   }
 }
 
-export class Uint64Map<TValue> extends CustomKeyMap<internal.primitives.StubUint64Compat, TValue> {
+export class Uint64Map<TValue> extends CustomKeyMap<StubUint64Compat, TValue> {
   constructor() {
     super((uint64) => asUint64Cls(uint64).valueOf())
   }

src/constants.ts

@@ -1,4 +1,4 @@
-import { Bytes } from '@algorandfoundation/algorand-typescript'
+import { Bytes } from './impl/primitives'
 
 export const UINT64_SIZE = 64
 export const UINT512_SIZE = 512

src/context-helpers/context-manager.ts

@@ -0,0 +1,22 @@
+import type { TestExecutionContext } from '../test-execution-context'
+
+declare global {
+  // eslint-disable-next-line no-var
+  var puyaTsExecutionContext: TestExecutionContext | undefined
+}
+
+export const ctxMgr = {
+  set instance(ctx: TestExecutionContext) {
+    const instance = global.puyaTsExecutionContext
+    if (instance != undefined) throw new Error('Execution context has already been set')
+    global.puyaTsExecutionContext = ctx
+  },
+  get instance() {
+    const instance = global.puyaTsExecutionContext
+    if (instance == undefined) throw new Error('No execution context has been set')
+    return instance
+  },
+  reset() {
+    global.puyaTsExecutionContext = undefined
+  },
+}

src/context-helpers/context-util.ts

@@ -1,22 +1,20 @@
 import type { uint64 } from '@algorandfoundation/algorand-typescript'
-import { internal } from '@algorandfoundation/algorand-typescript'
 import type { AbiMetadata } from '../abi-metadata'
+import { CodeError } from '../errors'
 import { ApplicationTransaction } from '../impl/transactions'
 import { lazyContext } from './internal-context'
 
 export const checkRoutingConditions = (appId: uint64, metadata: AbiMetadata) => {
   const appData = lazyContext.getApplicationData(appId)
   const isCreating = appData.isCreating
   if (isCreating && metadata.onCreate === 'disallow') {
-    throw new internal.errors.CodeError('method can not be called while creating')
+    throw new CodeError('method can not be called while creating')
   }
   if (!isCreating && metadata.onCreate === 'require') {
-    throw new internal.errors.CodeError('method can only be called while creating')
+    throw new CodeError('method can only be called while creating')
   }
   const txn = lazyContext.activeGroup.activeTransaction
   if (txn instanceof ApplicationTransaction && metadata.allowActions && !metadata.allowActions.includes(txn.onCompletion)) {
-    throw new internal.errors.CodeError(
-      `method can only be called with one of the following on_completion values: ${metadata.allowActions.join(', ')}`,
-    )
+    throw new CodeError(`method can only be called with one of the following on_completion values: ${metadata.allowActions.join(', ')}`)
   }
 }

src/context-helpers/internal-context.ts

@@ -1,9 +1,13 @@
 import type { Account } from '@algorandfoundation/algorand-typescript'
-import { BaseContract, internal } from '@algorandfoundation/algorand-typescript'
+import { internalError } from '../errors'
+import { BaseContract } from '../impl/base-contract'
+import type { StubUint64Compat } from '../impl/primitives'
+import { Uint64Cls } from '../impl/primitives'
 import type { AccountData, ApplicationData, AssetData } from '../impl/reference'
 import type { VoterData } from '../impl/voter-params'
 import type { TransactionGroup } from '../subcontexts/transaction-context'
 import type { TestExecutionContext } from '../test-execution-context'
+import { ctxMgr } from './context-manager'
 
 /**
  * For accessing implementation specific functions, with a convenient single entry
@@ -12,7 +16,7 @@ import type { TestExecutionContext } from '../test-execution-context'
  */
 class InternalContext {
   get value() {
-    return internal.ctxMgr.instance as TestExecutionContext
+    return ctxMgr.instance as TestExecutionContext
   }
 
   get defaultSender() {
@@ -46,34 +50,33 @@ class InternalContext {
   getAccountData(account: Account): AccountData {
     const data = this.ledger.accountDataMap.get(account)
     if (!data) {
-      throw internal.errors.internalError('Unknown account, check correct testing context is active')
+      throw internalError('Unknown account, check correct testing context is active')
     }
     return data
   }
 
-  getAssetData(id: internal.primitives.StubUint64Compat): AssetData {
-    const key = internal.primitives.Uint64Cls.fromCompat(id)
+  getAssetData(id: StubUint64Compat): AssetData {
+    const key = Uint64Cls.fromCompat(id)
     const data = this.ledger.assetDataMap.get(key.asBigInt())
     if (!data) {
-      throw internal.errors.internalError('Unknown asset, check correct testing context is active')
+      throw internalError('Unknown asset, check correct testing context is active')
     }
     return data
   }
 
-  getApplicationData(id: internal.primitives.StubUint64Compat | BaseContract): ApplicationData {
-    const uint64Id =
-      id instanceof BaseContract ? this.ledger.getApplicationForContract(id).id : internal.primitives.Uint64Cls.fromCompat(id)
+  getApplicationData(id: StubUint64Compat | BaseContract): ApplicationData {
+    const uint64Id = id instanceof BaseContract ? this.ledger.getApplicationForContract(id).id : Uint64Cls.fromCompat(id)
     const data = this.ledger.applicationDataMap.get(uint64Id)
     if (!data) {
-      throw internal.errors.internalError('Unknown application, check correct testing context is active')
+      throw internalError('Unknown application, check correct testing context is active')
     }
     return data
   }
 
   getVoterData(account: Account): VoterData {
     const data = this.ledger.voterDataMap.get(account)
     if (!data) {
-      throw internal.errors.internalError('Unknown voter, check correct testing context is active')
+      throw internalError('Unknown voter, check correct testing context is active')
     }
     return data
   }

src/encoders.ts

@@ -1,9 +1,11 @@
 import type { biguint, bytes, TransactionType, uint64 } from '@algorandfoundation/algorand-typescript'
-import { BigUint, internal, Uint64 } from '@algorandfoundation/algorand-typescript'
 import type { OnCompleteAction } from '@algorandfoundation/algorand-typescript/arc4'
 import { ARC4Encoded } from '@algorandfoundation/algorand-typescript/arc4'
+import { uint8ArrayToBigInt } from './encoding-util'
+import { internalError } from './errors'
 import { BytesBackedCls, Uint64BackedCls } from './impl/base'
 import { arc4Encoders, encodeArc4Impl, getArc4Encoder } from './impl/encoded-types'
+import { BigUint, Uint64, type StubBytesCompat } from './impl/primitives'
 import { AccountCls, ApplicationCls, AssetCls } from './impl/reference'
 import type { DeliberateAny } from './typescript-helpers'
 import { asBytes, asMaybeBigUintCls, asMaybeBytesCls, asMaybeUint64Cls, asUint64Cls, asUint8Array, nameOfType } from './util'
@@ -13,14 +15,14 @@ export type TypeInfo = {
   genericArgs?: TypeInfo[] | Record<string, TypeInfo>
 }
 
-export type fromBytes<T> = (val: Uint8Array | internal.primitives.StubBytesCompat, typeInfo: TypeInfo, prefix?: 'none' | 'log') => T
+export type fromBytes<T> = (val: Uint8Array | StubBytesCompat, typeInfo: TypeInfo, prefix?: 'none' | 'log') => T
 
 const booleanFromBytes: fromBytes<boolean> = (val) => {
-  return internal.encodingUtil.uint8ArrayToBigInt(asUint8Array(val)) > 0n
+  return uint8ArrayToBigInt(asUint8Array(val)) > 0n
 }
 
 const bigUintFromBytes: fromBytes<biguint> = (val) => {
-  return BigUint(internal.encodingUtil.uint8ArrayToBigInt(asUint8Array(val)))
+  return BigUint(uint8ArrayToBigInt(asUint8Array(val)))
 }
 
 const bytesFromBytes: fromBytes<bytes> = (val) => {
@@ -32,15 +34,15 @@ const stringFromBytes: fromBytes<string> = (val) => {
 }
 
 const uint64FromBytes: fromBytes<uint64> = (val) => {
-  return Uint64(internal.encodingUtil.uint8ArrayToBigInt(asUint8Array(val)))
+  return Uint64(uint8ArrayToBigInt(asUint8Array(val)))
 }
 
 const onCompletionFromBytes: fromBytes<OnCompleteAction> = (val) => {
-  return Uint64(internal.encodingUtil.uint8ArrayToBigInt(asUint8Array(val))) as OnCompleteAction
+  return Uint64(uint8ArrayToBigInt(asUint8Array(val))) as OnCompleteAction
 }
 
 const transactionTypeFromBytes: fromBytes<TransactionType> = (val) => {
-  return Uint64(internal.encodingUtil.uint8ArrayToBigInt(asUint8Array(val))) as TransactionType
+  return Uint64(uint8ArrayToBigInt(asUint8Array(val))) as TransactionType
 }
 
 export const encoders: Record<string, fromBytes<DeliberateAny>> = {
@@ -86,5 +88,5 @@ export const toBytes = (val: unknown): bytes => {
   if (Array.isArray(val) || typeof val === 'object') {
     return encodeArc4Impl('', val)
   }
-  internal.errors.internalError(`Invalid type for bytes: ${nameOfType(val)}`)
+  internalError(`Invalid type for bytes: ${nameOfType(val)}`)
 }

src/encoding-util.ts

@@ -0,0 +1,67 @@
+import { AvmError } from './errors'
+
+export const uint8ArrayToNumber = (value: Uint8Array): number => {
+  return value.reduce((acc, x) => acc * 256 + x, 0)
+}
+
+export const uint8ArrayToBigInt = (v: Uint8Array): bigint => {
+  // Assume big-endian
+  return Array.from(v)
+    .toReversed()
+    .map((byte_value, i): bigint => BigInt(byte_value) << BigInt(i * 8))
+    .reduce((a, b) => a + b, 0n)
+}
+
+export const hexToUint8Array = (value: string): Uint8Array => {
+  if (value.length % 2 !== 0) {
+    throw new AvmError('Hex string must have even number of characters')
+  }
+  return Uint8Array.from(Buffer.from(value, 'hex'))
+}
+
+export const base64ToUint8Array = (value: string): Uint8Array => {
+  return Uint8Array.from(Buffer.from(value, 'base64'))
+}
+
+export const bigIntToUint8Array = (val: bigint, fixedSize: number | 'dynamic' = 'dynamic'): Uint8Array => {
+  if (val === 0n && fixedSize === 'dynamic') {
+    return new Uint8Array(0)
+  }
+  const maxBytes = fixedSize === 'dynamic' ? undefined : fixedSize
+
+  let hex = val.toString(16)
+
+  // Pad the hex with zeros so it matches the size in bytes
+  if (fixedSize !== 'dynamic' && hex.length !== fixedSize * 2) {
+    hex = hex.padStart(fixedSize * 2, '0')
+  } else if (hex.length % 2 == 1) {
+    // Pad to 'whole' byte
+    hex = `0${hex}`
+  }
+  if (maxBytes && hex.length > maxBytes * 2) {
+    throw new AvmError(`Cannot encode ${val} as ${maxBytes} bytes as it would overflow`)
+  }
+  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
+}
+
+export const utf8ToUint8Array = (value: string): Uint8Array => {
+  const encoder = new TextEncoder()
+  return encoder.encode(value)
+}
+
+export const uint8ArrayToUtf8 = (value: Uint8Array): string => {
+  const decoder = new TextDecoder()
+  return decoder.decode(value)
+}
+
+export const uint8ArrayToHex = (value: Uint8Array): string => Buffer.from(value).toString('hex')
+
+export const uint8ArrayToBase64 = (value: Uint8Array): string => Buffer.from(value).toString('base64')
+
+export const uint8ArrayToBase64Url = (value: Uint8Array): string => Buffer.from(value).toString('base64url')
+
+export { uint8ArrayToBase32 } from './impl/base-32'

src/errors.ts

@@ -1,4 +1,55 @@
-import { internal } from '@algorandfoundation/algorand-typescript'
+/**
+ * Raised when an `err` op is encountered, or when the testing VM is asked to do something that would cause
+ * the AVM to fail.
+ */
+export class AvmError extends Error {
+  constructor(message: string) {
+    super(message)
+  }
+}
+export function avmError(message: string): never {
+  throw new AvmError(message)
+}
+
+export function avmInvariant(condition: unknown, message: string): asserts condition {
+  if (!condition) {
+    throw new AvmError(message)
+  }
+}
+/**
+ * Raised when an assertion fails
+ */
+export class AssertError extends AvmError {
+  constructor(message: string) {
+    super(message)
+  }
+}
+
+/**
+ * Raised when testing code errors
+ */
+export class InternalError extends Error {
+  constructor(message: string, options?: ErrorOptions) {
+    super(message, options)
+  }
+}
+
+export function internalError(message: string): never {
+  throw new InternalError(message)
+}
+
+/**
+ * Raised when unsupported user code is encountered
+ */
+export class CodeError extends Error {
+  constructor(message: string, options?: ErrorOptions) {
+    super(message, options)
+  }
+}
+
+export function codeError(message: string): never {
+  throw new CodeError(message)
+}
 
 export class NotImplementedError extends Error {
   constructor(feature: string) {
@@ -12,6 +63,6 @@ export function notImplementedError(feature: string): never {
 
 export function testInvariant(condition: unknown, message: string): asserts condition {
   if (!condition) {
-    throw new internal.errors.InternalError(message)
+    throw new InternalError(message)
   }
 }