feat: allow tuples and objects to be stored in box, local, and global state

Author: boblat

src/impl/encoded-types.ts

@@ -782,7 +782,7 @@ export class StructImpl<T extends StructConstraint> extends (Struct<StructConstr
     return new Proxy(this, {
       get(target, prop) {
         const originalValue = Reflect.get(target, prop)
-        if (originalValue === undefined && target.uint8ArrayValue && Object.keys(target.genericArgs).includes(prop.toString())) {
+        if (originalValue === undefined && target.uint8ArrayValue?.length && Object.keys(target.genericArgs).includes(prop.toString())) {
           return target.items[prop.toString()]
         }
         return originalValue
@@ -1268,6 +1268,7 @@ export const arc4Encoders: Record<string, fromBytes<DeliberateAny>> = {
   'Struct(<.*>)?': StructImpl.fromBytesImpl,
   DynamicBytes: DynamicBytesImpl.fromBytesImpl,
   'StaticBytes<.*>': StaticBytesImpl.fromBytesImpl,
+  object: StructImpl.fromBytesImpl,
 }
 export const getArc4Encoder = <T>(typeInfo: TypeInfo, encoders?: Record<string, fromBytes<DeliberateAny>>): fromBytes<T> => {
   const encoder = Object.entries(encoders ?? arc4Encoders).find(([k, _]) => new RegExp(`^${k}$`, 'i').test(typeInfo.name))?.[1]

src/test-transformer/visitors.ts

@@ -407,6 +407,12 @@ const getGenericTypeInfo = (type: ptypes.PType): TypeInfo => {
     )
   } else if (type instanceof ptypes.ARC4TupleType || type instanceof ptypes.TuplePType) {
     genericArgs.push(...type.items.map(getGenericTypeInfo))
+  } else if (type instanceof ptypes.ObjectPType) {
+    genericArgs = Object.fromEntries(
+      Object.entries(type.properties)
+        .map(([key, value]) => [key, getGenericTypeInfo(value)])
+        .filter((x) => !!x),
+    )
   }
 
   const result: TypeInfo = { name: typeName }

tests/artifacts/state-ops/contract.algo.ts

@@ -605,6 +605,8 @@ export class GlobalStateContract extends arc4.Contract {
   implicitKeyArc4Address = GlobalState({ initialValue: new Address(Global.creatorAddress) })
   implicitKeyArc4UintN128 = GlobalState({ initialValue: new UintN128(2n ** 100n) })
   implicitKeyArc4DynamicBytes = GlobalState({ initialValue: new DynamicBytes('dynamic bytes') })
+  implicitKeyTuple = GlobalState<[uint64, bytes, boolean]>({ initialValue: [Uint64(42), Bytes('Hello'), false] })
+  implicitKeyObj = GlobalState<{ a: uint64; b: bytes; c: boolean }>({ initialValue: { a: 42, b: Bytes('World'), c: true } })
 
   // Explicit key state variables
   arc4UintN64 = GlobalState({ initialValue: new UintN64(1337), key: 'explicit_key_arc4_uintn64' })
@@ -651,6 +653,16 @@ export class GlobalStateContract extends arc4.Contract {
     return this.implicitKeyArc4DynamicBytes.value
   }
 
+  @arc4.abimethod()
+  get_implicit_key_tuple(): [uint64, bytes, boolean] {
+    return this.implicitKeyTuple.value
+  }
+
+  @arc4.abimethod()
+  get_implicit_key_obj(): { a: uint64; b: bytes; c: boolean } {
+    return this.implicitKeyObj.value
+  }
+
   // Getter methods for explicit key state variables
   @arc4.abimethod()
   get_arc4_uintn64(): UintN64 {
@@ -723,6 +735,16 @@ export class GlobalStateContract extends arc4.Contract {
     this.implicitKeyArc4DynamicBytes.value = value
   }
 
+  @arc4.abimethod()
+  set_implicit_key_tuple(value: [uint64, bytes, boolean]) {
+    this.implicitKeyTuple.value = value
+  }
+
+  @arc4.abimethod()
+  set_implicit_key_obj(value: { a: uint64; b: bytes; c: boolean }) {
+    this.implicitKeyObj.value = value
+  }
+
   // Setter methods for explicit key state variables
   @arc4.abimethod()
   set_arc4_uintn64(value: UintN64) {
@@ -769,6 +791,8 @@ export class LocalStateContract extends arc4.Contract {
   implicitKeyArc4Address = LocalState<Address>()
   implicitKeyArc4UintN128 = LocalState<UintN128>()
   implicitKeyArc4DynamicBytes = LocalState<DynamicBytes>()
+  implicitKeyTuple = LocalState<[uint64, bytes, boolean]>()
+  implicitKeyObj = LocalState<{ a: uint64; b: bytes; c: boolean }>()
 
   // Explicit key state variables
   arc4UintN64 = LocalState<UintN64>({ key: 'explicit_key_arc4_uintn64' })
@@ -788,6 +812,8 @@ export class LocalStateContract extends arc4.Contract {
     this.implicitKeyArc4Address(Global.creatorAddress).value = new Address(Global.creatorAddress)
     this.implicitKeyArc4UintN128(Global.creatorAddress).value = new UintN128(2n ** 100n)
     this.implicitKeyArc4DynamicBytes(Global.creatorAddress).value = new DynamicBytes('dynamic bytes')
+    this.implicitKeyTuple(Global.creatorAddress).value = [42, Bytes('dummy_bytes'), true]
+    this.implicitKeyObj(Global.creatorAddress).value = { a: Uint64(42), b: Bytes('dummy_bytes'), c: true }
 
     this.arc4UintN64(Global.creatorAddress).value = new UintN64(1337)
     this.arc4Str(Global.creatorAddress).value = new Str('Hello')
@@ -834,6 +860,16 @@ export class LocalStateContract extends arc4.Contract {
     return this.implicitKeyArc4DynamicBytes(a).value
   }
 
+  @arc4.abimethod()
+  get_implicit_key_tuple(a: Account): [uint64, bytes, boolean] {
+    return this.implicitKeyTuple(a).value
+  }
+
+  @arc4.abimethod()
+  get_implicit_key_obj(a: Account): { a: uint64; b: bytes; c: boolean } {
+    return this.implicitKeyObj(a).value
+  }
+
   // Getter methods for explicit key state variables
   @arc4.abimethod()
   get_arc4_uintn64(a: Account): arc4.UintN64 {

tests/global-state-arc4-values.spec.ts

@@ -1,4 +1,4 @@
-import { Bytes } from '@algorandfoundation/algorand-typescript'
+import { Bytes, Uint64 } from '@algorandfoundation/algorand-typescript'
 import { TestExecutionContext } from '@algorandfoundation/algorand-typescript-testing'
 import type {
   AddressImpl,
@@ -106,6 +106,22 @@ describe('ARC4 AppGlobal values', async () => {
         expect(arc4Value.native).toEqual(expectedValue)
       },
     },
+    {
+      nativeValue: [21, asUint8Array(Bytes('Hello')), true],
+      abiValue: [Uint64(21), Bytes('Hello'), true],
+      methodName: `get_implicit_key_tuple`,
+      assert: (value: DeliberateAny, expectedValue: DeliberateAny) => {
+        expect(value).toEqual(expectedValue)
+      },
+    },
+    {
+      nativeValue: { a: 12, b: asUint8Array(Bytes('world')), c: true },
+      abiValue: { a: 12, b: Bytes('world'), c: true },
+      methodName: `get_implicit_key_obj`,
+      assert: (value: DeliberateAny, expectedValue: DeliberateAny) => {
+        expect(value).toEqual(expectedValue)
+      },
+    },
   ])
 
   test.for(testData)('should be able to get arc4 state values', async (data, { appClientGlobalStateContract: appClient, testAccount }) => {

tests/local-state-arc4-values.spec.ts

@@ -93,6 +93,18 @@ describe('ARC4 AppLocal values', async () => {
         expect(arc4Value.native).toEqual(expectedValue)
       },
     },
+    {
+      methodName: `get_implicit_key_tuple`,
+      assert: (value: DeliberateAny, expectedValue: DeliberateAny) => {
+        expect(value).toEqual(expectedValue)
+      },
+    },
+    {
+      methodName: `get_implicit_key_obj`,
+      assert: (value: DeliberateAny, expectedValue: DeliberateAny) => {
+        expect(value).toEqual(expectedValue)
+      },
+    },
   ])
 
   test.for(testData)('should be able to get arc4 state values', async (data, { appClientLocalStateContract: appClient, testAccount }) => {

tests/references/box-map.spec.ts

@@ -1,14 +1,17 @@
 import type { biguint, bytes, uint64 } from '@algorandfoundation/algorand-typescript'
 import { BigUint, BoxMap, Bytes, op, Uint64 } from '@algorandfoundation/algorand-typescript'
 import { TestExecutionContext } from '@algorandfoundation/algorand-typescript-testing'
-import { ARC4Encoded, DynamicArray, interpretAsArc4, Str, UintN64 } from '@algorandfoundation/algorand-typescript/arc4'
+import type { Bool, DynamicBytes, Tuple } from '@algorandfoundation/algorand-typescript/arc4'
+import { ARC4Encoded, DynamicArray, interpretAsArc4, Str, Struct, UintN64 } from '@algorandfoundation/algorand-typescript/arc4'
 import { afterEach, describe, expect, it, test } from 'vitest'
 import { MAX_UINT64 } from '../../src/constants'
 import { toBytes } from '../../src/encoders'
 import { asBytes } from '../../src/util'
 
 const BOX_NOT_CREATED_ERROR = 'Box has not been created'
 
+class MyStruct extends Struct<{ a: Str; b: DynamicBytes; c: Bool }> {}
+
 describe('BoxMap', () => {
   const ctx = new TestExecutionContext()
   const keyPrefix = Bytes('test_key_prefix')
@@ -97,6 +100,30 @@ describe('BoxMap', () => {
         })
       },
     },
+    {
+      key: new Str('TTest'),
+      value: ['hello', Bytes('world'), true] as const,
+      newValue: ['world', Bytes('hello'), false] as const,
+      emptyValue: interpretAsArc4<Tuple<[Str, DynamicBytes, Bool]>>(Bytes('')),
+      withBoxContext: (test: (boxMap: BoxMap<Str, readonly [string, bytes, boolean]>) => void) => {
+        ctx.txn.createScope([ctx.any.txn.applicationCall()]).execute(() => {
+          const boxMap = BoxMap<Str, readonly [string, bytes, boolean]>({ keyPrefix })
+          test(boxMap)
+        })
+      },
+    },
+    {
+      key: new Str('OTest'),
+      value: { a: 'hello', b: Bytes('world'), c: true } as unknown as MyStruct,
+      newValue: { a: 'world', b: Bytes('hello'), c: false } as unknown as MyStruct,
+      emptyValue: interpretAsArc4<MyStruct>(Bytes('')),
+      withBoxContext: (test: (boxMap: BoxMap<Str, MyStruct>) => void) => {
+        ctx.txn.createScope([ctx.any.txn.applicationCall()]).execute(() => {
+          const boxMap = BoxMap<Str, MyStruct>({ keyPrefix })
+          test(boxMap)
+        })
+      },
+    },
   ]
 
   afterEach(() => {
@@ -199,6 +226,8 @@ describe('BoxMap', () => {
       expect(opContent).toEqual(newBytesValue)
       if (newValue instanceof ARC4Encoded) {
         expect((boxMap(key as never).value as ARC4Encoded).bytes).toEqual(newValue.bytes)
+      } else if (boxMap(key as never).value instanceof ARC4Encoded) {
+        expect((boxMap(key as never).value as ARC4Encoded).bytes).toEqual(newBytesValue)
       } else {
         expect(boxMap(key as never).value).toEqual(newValue)
       }

tests/references/box.spec.ts

@@ -1,13 +1,15 @@
 import type { biguint, bytes, uint64 } from '@algorandfoundation/algorand-typescript'
 import { BigUint, Box, Bytes, op, Uint64 } from '@algorandfoundation/algorand-typescript'
 import { TestExecutionContext } from '@algorandfoundation/algorand-typescript-testing'
+import type { DynamicBytes } from '@algorandfoundation/algorand-typescript/arc4'
 import {
   ARC4Encoded,
   Bool,
   DynamicArray,
   interpretAsArc4,
   StaticArray,
   Str,
+  Struct,
   Tuple,
   UintN32,
   UintN64,
@@ -22,6 +24,8 @@ import { BoxContract } from '../artifacts/box-contract/contract.algo'
 
 const BOX_NOT_CREATED_ERROR = 'Box has not been created'
 
+class MyStruct extends Struct<{ a: Str; b: DynamicBytes; c: Bool }> {}
+
 describe('Box', () => {
   const ctx = new TestExecutionContext()
   const key = Bytes('test_key')
@@ -103,6 +107,28 @@ describe('Box', () => {
         })
       },
     },
+    {
+      value: ['hello', Bytes('world'), true] as const,
+      newValue: ['world', Bytes('hello'), false] as const,
+      emptyValue: interpretAsArc4<Tuple<[Str, DynamicBytes, Bool]>>(Bytes('')),
+      withBoxContext: (test: (boxMap: Box<readonly [string, bytes, boolean]>) => void) => {
+        ctx.txn.createScope([ctx.any.txn.applicationCall()]).execute(() => {
+          const boxMap = Box<readonly [string, bytes, boolean]>({ key })
+          test(boxMap)
+        })
+      },
+    },
+    {
+      value: { a: 'hello', b: Bytes('world'), c: true },
+      newValue: { a: 'world', b: Bytes('hello'), c: false },
+      emptyValue: interpretAsArc4<MyStruct>(Bytes('')),
+      withBoxContext: (test: (boxMap: Box<{ a: string; b: bytes; c: boolean }>) => void) => {
+        ctx.txn.createScope([ctx.any.txn.applicationCall()]).execute(() => {
+          const boxMap = Box<{ a: string; b: bytes; c: boolean }>({ key })
+          test(boxMap)
+        })
+      },
+    },
   ]
 
   afterEach(() => {
@@ -211,6 +237,8 @@ describe('Box', () => {
       expect(opContent).toEqual(newBytesValue)
       if (newValue instanceof ARC4Encoded) {
         expect((box as DeliberateAny).get(key).bytes).toEqual(newValue.bytes)
+      } else if (box.value instanceof ARC4Encoded) {
+        expect(box.value.bytes).toEqual(newBytesValue)
       } else {
         expect(box.value).toEqual(newValue)
       }