Merge pull request #7 from algorandfoundation/feat-app-local

feat: implement AppLocal and add tests for it

Author: boblat

package-lock.json

@@ -63,7 +63,7 @@
   },
   "dependencies": {
     "@algorandfoundation/algokit-utils": "^6.2.1",
-    "@algorandfoundation/algorand-typescript": "^0.0.1-alpha.12",
+    "@algorandfoundation/algorand-typescript": "^0.0.1-alpha.13",
     "@algorandfoundation/puya-ts": "^1.0.0-alpha.14",
     "algosdk": "^2.9.0",
     "elliptic": "^6.5.7",

package.json

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

src/impl/app-local.ts

@@ -1,18 +1,18 @@
-import { Account, Application, Bytes, bytes, uint64 } from '@algorandfoundation/algorand-typescript'
+import { Account, Application, Bytes, bytes, LocalState, 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'
-import { GlobalStateCls, LocalStateMapCls } from './state'
+import { GlobalStateCls } from './state'
 
 export class ApplicationData {
   application: Mutable<Omit<Application, 'id' | 'address'>> & {
     appLogs: bytes[]
     globalStates: BytesMap<GlobalStateCls<unknown>>
-    localStates: BytesMap<LocalStateMapCls<unknown>>
+    localStates: BytesMap<LocalState<unknown>>
   }
   isCreating: boolean = false
 

src/impl/application.ts

@@ -1,5 +1,6 @@
 export { AcctParams, balance, minBalance } from './acct-params'
 export { AppGlobal } from './app-global'
+export { AppLocal } from './app-local'
 export { AppParams } from './app-params'
 export { AssetHolding } from './asset-holding'
 export { AssetParams } from './asset-params'

src/impl/index.ts

@@ -8,7 +8,8 @@ import {
   LocalStateForAccount,
   Uint64,
 } from '@algorandfoundation/algorand-typescript'
-import { asBytes, asBytesCls } from '../util'
+import { AccountMap } from '../collections/custom-key-map'
+import { asBytes } from '../util'
 
 export class GlobalStateCls<ValueType> {
   private readonly _type: string = GlobalStateCls.name
@@ -75,14 +76,13 @@ export class LocalStateCls<ValueType> {
 }
 
 export class LocalStateMapCls<ValueType> {
-  #value = new Map<string, LocalStateCls<ValueType>>()
+  #value = new AccountMap<LocalStateCls<ValueType>>()
 
   getValue(account: Account): LocalStateCls<ValueType> {
-    const accountString = asBytesCls(account.bytes).valueOf()
-    if (!this.#value.has(accountString)) {
-      this.#value.set(accountString, new LocalStateCls<ValueType>())
+    if (!this.#value.has(account)) {
+      this.#value.set(account, new LocalStateCls<ValueType>())
     }
-    return this.#value.get(accountString)!
+    return this.#value.getOrFail(account)!
   }
 }
 

src/impl/state.ts

@@ -1,11 +1,11 @@
-import { Account, Application, Asset, BaseContract, Bytes, bytes, Contract } from '@algorandfoundation/algorand-typescript'
+import { Account, Application, Asset, BaseContract, Bytes, bytes, Contract, LocalState } 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'
 import { AssetCls } from '../impl/asset'
-import { GlobalStateCls, LocalStateMapCls } from '../impl/state'
+import { GlobalStateCls } from '../impl/state'
 import {
   ApplicationTransaction,
   AssetConfigTransaction,
@@ -27,7 +27,7 @@ type StateTotals = Pick<Application, 'globalNumBytes' | 'globalNumUint' | 'local
 
 interface States {
   globalStates: BytesMap<GlobalStateCls<unknown>>
-  localStates: BytesMap<LocalStateMapCls<unknown>>
+  localStates: BytesMap<LocalState<unknown>>
   totals: StateTotals
 }
 
@@ -41,7 +41,7 @@ const extractStates = (contract: BaseContract): States => {
   const stateTotals = { globalNumBytes: 0, globalNumUint: 0, localNumBytes: 0, localNumUint: 0 }
   const states = {
     globalStates: new BytesMap<GlobalStateCls<unknown>>(),
-    localStates: new BytesMap<LocalStateMapCls<unknown>>(),
+    localStates: new BytesMap<LocalState<unknown>>(),
     totals: stateTotals,
   }
   Object.entries(contract).forEach(([key, value]) => {

src/subcontexts/contract-context.ts

@@ -1,4 +1,4 @@
-import { Account, Application, Asset, BaseContract, internal } from '@algorandfoundation/algorand-typescript'
+import { Account, Application, Asset, BaseContract, internal, LocalStateForAccount } from '@algorandfoundation/algorand-typescript'
 import { AccountMap, Uint64Map } from '../collections/custom-key-map'
 import { MAX_UINT64 } from '../constants'
 import { AccountData, AssetHolding } from '../impl/account'
@@ -123,4 +123,33 @@ export class LedgerContext {
       globalState.value = asMaybeUint64Cls(value) ?? asMaybeBytesCls(value)
     }
   }
+
+  getLocalState(
+    app: Application,
+    account: Account,
+    key: internal.primitives.StubBytesCompat,
+  ): [LocalStateForAccount<unknown>, true] | [undefined, false] {
+    const appData = this.applicationDataMap.get(app.id)
+    if (!appData?.application.localStates.has(key)) {
+      return [undefined, false]
+    }
+    const localState = appData.application.localStates.getOrFail(key)
+    return [localState(account), true]
+  }
+
+  setLocalState(
+    app: Application,
+    account: Account,
+    key: internal.primitives.StubBytesCompat,
+    value: internal.primitives.StubUint64Compat | internal.primitives.StubBytesCompat | undefined,
+  ): void {
+    const appData = this.applicationDataMap.getOrFail(app.id)
+    const localState = appData.application.localStates.getOrFail(key)
+    const accountLocalState = localState(account)
+    if (value === undefined) {
+      accountLocalState.delete()
+    } else {
+      accountLocalState.value = asMaybeUint64Cls(value) ?? asMaybeBytesCls(value)
+    }
+  }
 }

src/subcontexts/ledger-context.ts

@@ -10,6 +10,7 @@ import {
   Global,
   GlobalState,
   itxn,
+  LocalState,
   op,
   TransactionType,
   Txn,
@@ -405,6 +406,78 @@ export class StateAppGlobalContract extends arc4.Contract {
   }
 }
 
+export class StateAppLocalExContract extends arc4.Contract {
+  localUint64 = LocalState<uint64>({ key: 'local_uint64' })
+  localBytes = LocalState<bytes>({ key: 'local_bytes' })
+
+  // TODO: uncomment when arc4 types are ready
+  // localArc4Bytes = LocalState<arc4.DynamicBytes>({ key: "local_arc4_bytes" })
+
+  @arc4.abimethod({ allowActions: ['OptIn'] })
+  optIn(): void {
+    this.localBytes(Global.creatorAddress).value = Bytes('dummy_bytes_from_external_contract')
+    this.localUint64(Global.creatorAddress).value = Uint64(99)
+    // TODO: uncomment when arc4 types are ready
+    // this.localArc4Bytes(Global.creatorAddress).value = arc4.DynamicBytes("dummy_arc4_bytes")
+  }
+}
+
+export class StateAppLocalContract extends arc4.Contract {
+  localUint64 = LocalState<uint64>({ key: 'local_uint64' })
+  localBytes = LocalState<bytes>({ key: 'local_bytes' })
+
+  @arc4.abimethod({ allowActions: ['OptIn'] })
+  opt_in() {
+    this.localBytes(Global.creatorAddress).value = Bytes('dummy_bytes')
+    this.localUint64(Global.creatorAddress).value = Uint64(999)
+  }
+
+  @arc4.abimethod()
+  verify_get_bytes(a: Account, b: bytes): bytes {
+    const value = op.AppLocal.getBytes(a, b)
+    return value
+  }
+
+  @arc4.abimethod()
+  verify_get_uint64(a: Account, b: bytes): uint64 {
+    const value = op.AppLocal.getUint64(a, b)
+    return value
+  }
+
+  @arc4.abimethod()
+  verify_get_ex_bytes(a: Account, b: Application, c: bytes): bytes {
+    const [value, _val] = op.AppLocal.getExBytes(a, b, c)
+    return value
+  }
+
+  @arc4.abimethod()
+  verify_get_ex_uint64(a: Account, b: Application, c: bytes): uint64 {
+    const [value, _val] = op.AppLocal.getExUint64(a, b, c)
+    return value
+  }
+
+  @arc4.abimethod()
+  verify_delete(a: Account, b: bytes): void {
+    op.AppLocal.delete(a, b)
+  }
+
+  @arc4.abimethod()
+  verify_exists(a: Account, b: bytes): boolean {
+    const [_value, exists] = op.AppLocal.getExUint64(a, 0, b)
+    return exists
+  }
+
+  @arc4.abimethod()
+  verify_put_uint64(a: Account, b: bytes, c: uint64): void {
+    op.AppLocal.put(a, b, c)
+  }
+
+  @arc4.abimethod()
+  verify_put_bytes(a: Account, b: bytes, c: bytes): void {
+    op.AppLocal.put(a, b, c)
+  }
+}
+
 export class ITxnOpsContract extends arc4.Contract {
   @arc4.abimethod()
   public verify_itxn_ops() {