feat: implement AppGlobal and add tests for it

- Contract proxy returns original value without wrapping for all
  entries which are not ABI methods in an arc4 contract
- allow invocation of contract methods which return void

Author: boblat

.editorconfig

@@ -0,0 +1,9 @@
+[*]
+charset = utf-8
+insert_final_newline = true
+end_of_line = lf
+indent_style = space
+indent_size = 2
+tab_width = 2
+max_line_length = 140
+trim_trailing_whitespace = true

.gitattributes

@@ -0,0 +1,6 @@
+# Set the repository to show as TypeScript rather than JS in GitHub
+*.js linguist-detectable=false
+
+# Treat text as lf
+* text=auto
+* eol=lf

.vscode/settings.json

@@ -0,0 +1,20 @@
+{
+  "editor.formatOnSave": true,
+  "editor.defaultFormatter": "esbenp.prettier-vscode",
+  "editor.codeActionsOnSave": {
+    "source.fixAll.eslint": "explicit",
+    "source.organizeImports": "explicit"
+  },
+  "eslint.validate": ["typescript"],
+  "eslint.options": {
+    "extensions": [".ts"]
+  },
+  "typescript.preferences.quoteStyle": "single",
+  "yaml.schemas": {
+    "https://json.schemastore.org/github-workflow.json": "/.github/workflows/*.yml",
+    "https://json.schemastore.org/github-action.json": "/.github/actions/**/*.yml"
+  },
+  "files.associations": {
+    "*.mdx": "markdown"
+  }
+}

src/collections/custom-key-map.ts

@@ -1,6 +1,6 @@
-import { Account, internal } from '@algorandfoundation/algorand-typescript'
-import { encodingUtil } from '@algorandfoundation/puya-ts'
+import { Account, bytes } from '@algorandfoundation/algorand-typescript'
 import { DeliberateAny } from '../typescript-helpers'
+import { asBytesCls } from '../util'
 
 type Primitive = number | bigint | string | boolean
 export abstract class CustomKeyMap<TKey, TValue> implements Map<TKey, TValue> {
@@ -62,6 +62,12 @@ export class AccountMap<TValue> extends CustomKeyMap<Account, TValue> {
   }
 
   private static getAddressStrFromAccount = (acc: Account) => {
-    return encodingUtil.uint8ArrayToHex(internal.primitives.BytesCls.fromCompat(acc.bytes).asUint8Array())
+    return asBytesCls(acc.bytes).valueOf()
+  }
+}
+
+export class BytesMap<TValue> extends CustomKeyMap<bytes, TValue> {
+  constructor() {
+    super((bytes) => asBytesCls(bytes).valueOf())
   }
 }

src/impl/app-global.ts

@@ -0,0 +1,50 @@
+import { Application, Bytes, bytes, internal, Uint64, uint64 } from '@algorandfoundation/algorand-typescript'
+import { lazyContext } from '../context-helpers/internal-context'
+import { asBytes } from '../util'
+import { getApp } from './app-params'
+
+export const AppGlobal: internal.opTypes.AppGlobalType = {
+  delete: function (a: internal.primitives.StubBytesCompat): void {
+    lazyContext.ledger.setGlobalState(lazyContext.activeApplication, a, undefined)
+  },
+  getBytes: function (a: internal.primitives.StubBytesCompat): bytes {
+    return this.getExBytes(0, asBytes(a))[0]
+  },
+  getUint64: function (a: internal.primitives.StubBytesCompat): uint64 {
+    return this.getExUint64(0, asBytes(a))[0]
+  },
+  getExBytes: function (
+    a: Application | internal.primitives.StubUint64Compat,
+    b: internal.primitives.StubBytesCompat,
+  ): readonly [bytes, boolean] {
+    const app = getApp(a)
+    if (app === undefined) {
+      return [Bytes(), false]
+    }
+    const [state, exists] = lazyContext.ledger.getGlobalState(app, b)
+    if (!exists) {
+      return [Bytes(), false]
+    }
+    return [state!.value as bytes, exists]
+  },
+  getExUint64: function (
+    a: Application | internal.primitives.StubUint64Compat,
+    b: internal.primitives.StubBytesCompat,
+  ): readonly [uint64, boolean] {
+    const app = getApp(a)
+    if (app === undefined) {
+      return [Uint64(0), false]
+    }
+    const [state, exists] = lazyContext.ledger.getGlobalState(app, b)
+    if (!exists) {
+      return [Uint64(0), false]
+    }
+    return [state!.value as uint64, exists]
+  },
+  put: function (
+    a: internal.primitives.StubBytesCompat,
+    b: internal.primitives.StubUint64Compat | internal.primitives.StubBytesCompat,
+  ): void {
+    lazyContext.ledger.setGlobalState(lazyContext.activeApplication, a, b)
+  },
+}

src/impl/application.ts

@@ -1,13 +1,18 @@
-import { Account, Application, Bytes, bytes, uint64 } from '@algorandfoundation/algorand-typescript'
+import { Account, Application, Bytes, bytes, internal, uint64 } from '@algorandfoundation/algorand-typescript'
 import algosdk from 'algosdk'
+import { BytesMap } from '../collections/custom-key-map'
 import { ALWAYS_APPROVE_TEAL_PROGRAM } from '../constants'
 import { lazyContext } from '../context-helpers/internal-context'
 import { Mutable } from '../typescript-helpers'
 import { asBigInt, asUint64 } from '../util'
 import { Uint64BackedCls } from './base'
 
 export class ApplicationData {
-  application: Mutable<Omit<Application, 'id' | 'address'>> & { appLogs: bytes[] }
+  application: Mutable<Omit<Application, 'id' | 'address'>> & {
+    appLogs: bytes[]
+    globalStates: BytesMap<internal.state.GlobalStateCls<unknown>>
+    localStates: BytesMap<internal.state.LocalStateMapCls<unknown>>
+  }
   isCreating: boolean = false
 
   get appLogs() {
@@ -25,6 +30,8 @@ export class ApplicationData {
       extraProgramPages: 0,
       creator: lazyContext.defaultSender,
       appLogs: [],
+      globalStates: new BytesMap(),
+      localStates: new BytesMap(),
     }
   }
 }

src/impl/index.ts

@@ -1,12 +1,13 @@
 export { AcctParams, balance, minBalance } from './acct-params'
+export { AppGlobal } from './app-global'
 export { AppParams } from './app-params'
 export { AssetHolding } from './asset-holding'
 export { AssetParams } from './asset-params'
 export * from './crypto'
 export { Global } from './global'
 export { GTxn } from './gtxn'
-export * from './pure'
-export { Txn, gaid } from './txn'
 export { GITxn, ITxn, ITxnCreate } from './itxn'
+export * from './pure'
 export { Scratch, gloadBytes, gloadUint64 } from './scratch'
 export { Block } from './block'
+export { Txn, gaid } from './txn'

src/subcontexts/contract-context.ts

@@ -1,5 +1,6 @@
 import { Account, Application, Asset, BaseContract, Bytes, bytes, Contract, internal } from '@algorandfoundation/algorand-typescript'
 import { getAbiMetadata } from '../abi-metadata'
+import { BytesMap } from '../collections/custom-key-map'
 import { lazyContext } from '../context-helpers/internal-context'
 import { AccountCls } from '../impl/account'
 import { ApplicationCls } from '../impl/application'
@@ -15,7 +16,7 @@ import {
 } from '../impl/transactions'
 import { getGenericTypeInfo } from '../runtime-helpers'
 import { DeliberateAny } from '../typescript-helpers'
-import { extractGenericTypeArgs } from '../util'
+import { asUint64Cls, extractGenericTypeArgs } from '../util'
 
 interface IConstructor<T> {
   new (...args: DeliberateAny[]): T
@@ -24,8 +25,8 @@ interface IConstructor<T> {
 type StateTotals = Pick<Application, 'globalNumBytes' | 'globalNumUint' | 'localNumBytes' | 'localNumUint'>
 
 interface States {
-  globalStates: Map<bytes, internal.state.GlobalStateCls<unknown>>
-  localStates: Map<bytes, internal.state.LocalStateMapCls<unknown>>
+  globalStates: BytesMap<internal.state.GlobalStateCls<unknown>>
+  localStates: BytesMap<internal.state.LocalStateMapCls<unknown>>
   totals: StateTotals
 }
 
@@ -38,8 +39,8 @@ const isUint64GenericType = (typeName: string | undefined) => {
 const extractStates = (contract: BaseContract): States => {
   const stateTotals = { globalNumBytes: 0, globalNumUint: 0, localNumBytes: 0, localNumUint: 0 }
   const states = {
-    globalStates: new Map<bytes, internal.state.GlobalStateCls<unknown>>(),
-    localStates: new Map<bytes, internal.state.LocalStateMapCls<unknown>>(),
+    globalStates: new BytesMap<internal.state.GlobalStateCls<unknown>>(),
+    localStates: new BytesMap<internal.state.LocalStateMapCls<unknown>>(),
     totals: stateTotals,
   }
   Object.entries(contract).forEach(([key, value]) => {
@@ -50,7 +51,7 @@ const extractStates = (contract: BaseContract): States => {
       if (value.key === undefined) value.key = Bytes(key)
 
       // capture state into the context
-      if (isLocalState) states.localStates.set(value.key, value.map)
+      if (isLocalState) states.localStates.set(value.key, value)
       else states.globalStates.set(value.key, value)
 
       // populate state totals
@@ -64,23 +65,31 @@ const extractStates = (contract: BaseContract): States => {
   return states
 }
 
-const extractArraysFromArgs = (args: DeliberateAny[]) => {
+const extractArraysFromArgs = (app: Application, args: DeliberateAny[]) => {
   const transactions: Transaction[] = []
   const accounts: Account[] = []
-  const apps: Application[] = []
+  const apps: Application[] = [app]
   const assets: Asset[] = []
+  const appArgs: bytes[] = []
+
+  // TODO: replace `asUint64Cls(accounts.length).toBytes().asAlgoTs()` with `arc4.Uint8(account.length).toBytes().asAlgoTs()`
   for (const arg of args) {
     if (isTransaction(arg)) {
       transactions.push(arg)
     } else if (arg instanceof AccountCls) {
+      appArgs.push(asUint64Cls(accounts.length).toBytes().asAlgoTs())
       accounts.push(arg as Account)
     } else if (arg instanceof ApplicationCls) {
+      appArgs.push(asUint64Cls(apps.length).toBytes().asAlgoTs())
       apps.push(arg as Application)
     } else if (arg instanceof AssetCls) {
+      appArgs.push(asUint64Cls(assets.length).toBytes().asAlgoTs())
       assets.push(arg as Asset)
     }
   }
-  return { accounts, apps, assets, transactions }
+
+  // TODO: use actual method selector in appArgs
+  return { accounts, apps, assets, transactions, appArgs: [Bytes('method_selector'), ...appArgs] }
 }
 
 function isTransaction(obj: unknown): obj is Transaction {
@@ -96,7 +105,6 @@ function isTransaction(obj: unknown): obj is Transaction {
 
 export class ContractContext {
   create<T extends BaseContract>(type: IConstructor<T>, ...args: DeliberateAny[]): T {
-    Object.getPrototypeOf(type)
     const proxy = new Proxy(type, this.getContractProxyHandler<T>(this.isArc4(type)))
     return new proxy(...args)
   }
@@ -114,10 +122,12 @@ export class ContractContext {
   }
 
   private getContractProxyHandler<T extends BaseContract>(isArc4: boolean): ProxyHandler<IConstructor<T>> {
-    const onConstructed = (instance: BaseContract) => {
+    const onConstructed = (instance: T) => {
       const states = extractStates(instance)
 
       const application = lazyContext.any.application({
+        globalStates: states.globalStates,
+        localStates: states.localStates,
         ...states.totals,
       })
       lazyContext.ledger.addAppIdContractMap(application.id, instance)
@@ -127,12 +137,13 @@ export class ContractContext {
         const instance = new Proxy(new target(...args), {
           get(target, prop, receiver) {
             const orig = Reflect.get(target, prop, receiver)
+            const abiMetadata = getAbiMetadata(target, prop as string)
             const isProgramMethod = prop === 'approvalProgram' || prop === 'clearStateProgram'
-            if (isArc4 || isProgramMethod) {
+            const isAbiMethod = isArc4 && abiMetadata
+            if (isAbiMethod || isProgramMethod) {
               return (...args: DeliberateAny[]): DeliberateAny => {
                 const app = lazyContext.ledger.getApplicationForContract(receiver)
-                const { transactions, ...appCallArgs } = extractArraysFromArgs(args)
-                const abiMetadata = getAbiMetadata(target, prop as string)
+                const { transactions, ...appCallArgs } = extractArraysFromArgs(app, args)
                 const appTxn = lazyContext.any.txn.applicationCall({
                   appId: app,
                   ...appCallArgs,
@@ -142,7 +153,7 @@ export class ContractContext {
                 const txns = [...(transactions ?? []), appTxn]
                 return lazyContext.txn.ensureScope(txns).execute(() => {
                   const returnValue = (orig as DeliberateAny).apply(target, args)
-                  if (!isProgramMethod && isArc4 && returnValue !== undefined) {
+                  if (!isProgramMethod && isAbiMethod && returnValue !== undefined) {
                     appTxn.logArc4ReturnValue(returnValue)
                   }
                   return returnValue
@@ -152,6 +163,7 @@ export class ContractContext {
             return orig
           },
         })
+
         onConstructed(instance)
 
         return instance

src/subcontexts/ledger-context.ts

@@ -5,7 +5,7 @@ import { AccountData, AssetHolding } from '../impl/account'
 import { ApplicationData } from '../impl/application'
 import { AssetData } from '../impl/asset'
 import { GlobalData } from '../impl/global'
-import { asBigInt, asMaybeUint64Cls, asUint64, asUint64Cls, iterBigInt } from '../util'
+import { asBigInt, asBytes, asMaybeBytesCls, asMaybeUint64Cls, asUint64, asUint64Cls, iterBigInt } from '../util'
 
 interface BlockData {
   seed: bigint
@@ -102,4 +102,36 @@ export class LedgerContext {
     }
     throw internal.errors.internalError(`Block ${i} not set`)
   }
+
+  getGlobalState(
+    app: Application,
+    key: internal.primitives.StubBytesCompat,
+  ): [internal.state.GlobalStateCls<unknown> | undefined, boolean] {
+    const appId = asBigInt(app.id)
+    const keyBytes = asBytes(key)
+    if (!this.applicationDataMap.has(appId)) {
+      return [undefined, false]
+    }
+    const appData = this.applicationDataMap.get(appId)!
+    if (!appData.application.globalStates.has(keyBytes)) {
+      return [undefined, false]
+    }
+    return [appData.application.globalStates.get(keyBytes), true]
+  }
+
+  setGlobalState(
+    app: Application,
+    key: internal.primitives.StubBytesCompat,
+    value: internal.primitives.StubUint64Compat | internal.primitives.StubBytesCompat | undefined,
+  ): void {
+    const appId = asBigInt(app.id)
+    const keyBytes = asBytes(key)
+    const appData = this.applicationDataMap.get(appId)!
+    const globalState = appData.application.globalStates.get(keyBytes)!
+    if (value === undefined) {
+      globalState.delete()
+    } else {
+      globalState.value = asMaybeUint64Cls(value) ?? asMaybeBytesCls(value)
+    }
+  }
 }

src/test-execution-context.ts

@@ -21,7 +21,6 @@ import { TransactionContext } from './subcontexts/transaction-context'
 import { ValueGenerator } from './value-generators'
 
 export class TestExecutionContext implements internal.ExecutionContext {
-  #applicationLogs: Map<bigint, bytes[]>
   #contractContext: ContractContext
   #ledgerContext: LedgerContext
   #txnContext: TransactionContext
@@ -30,7 +29,6 @@ export class TestExecutionContext implements internal.ExecutionContext {
 
   constructor() {
     internal.ctxMgr.instance = this
-    this.#applicationLogs = new Map()
     this.#contractContext = new ContractContext()
     this.#ledgerContext = new LedgerContext()
     this.#txnContext = new TransactionContext()
@@ -112,7 +110,6 @@ export class TestExecutionContext implements internal.ExecutionContext {
   }
 
   reset() {
-    this.#applicationLogs.clear()
     this.#contractContext = new ContractContext()
     this.#ledgerContext = new LedgerContext()
     this.#txnContext = new TransactionContext()