feat: add support for ABI validation

docs/testing-guide/concepts.md

@@ -64,3 +64,8 @@ As explained in the [introduction](index.md), `algorand-typescript-testing` _inj
 3. **Mockable**: Not implemented, but can be mocked or patched. For example, `op.onlineStake` can be mocked to return specific values or behaviors; otherwise, it raises a `NotImplementedError`. This category covers cases where native or emulated implementation in a unit test context is impractical or overly complex.
 
 For a full list of all public `algorand-typescript` types and their corresponding implementation category, refer to the [Coverage](../coverage.md) section.
+
+## Data Validation
+
+Algorand TypeScript and the puya compiler have functionality to perform validation of transaction inputs via the `--validate-abi-args`, `--validate-abi-return` CLI arguments, `arc4.abimethod({validateEncoding: ...})` decorator, and `validateEncoding(...)` method.
+The Algorand TypeScript Testing library does _NOT_ implement this validation behaviour, as you should test invalid inputs using an integrated test against a real Algorand network.

package.json

@@ -66,8 +66,8 @@
     "vitest": "3.2.4"
   },
   "dependencies": {
-    "@algorandfoundation/algorand-typescript": "1.0.0-beta.65",
-    "@algorandfoundation/puya-ts": "1.0.0-beta.65",
+    "@algorandfoundation/algorand-typescript": "1.0.0-beta.73",
+    "@algorandfoundation/puya-ts": "1.0.0-beta.73",
     "elliptic": "^6.6.1",
     "js-sha256": "^0.11.0",
     "js-sha3": "^0.9.3",

src/encoders.ts

@@ -3,7 +3,7 @@ import { ARC4Encoded } from '@algorandfoundation/algorand-typescript/arc4'
 import { encodingUtil } from '@algorandfoundation/puya-ts'
 import { InternalError } from './errors'
 import { BytesBackedCls, Uint64BackedCls } from './impl/base'
-import { arc4Encoders, encodeArc4Impl, getArc4Encoder } from './impl/encoded-types'
+import { arc4Encoders, encodeArc4Impl, getArc4Encoder, tryArc4EncodedLengthImpl } 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'
@@ -89,3 +89,8 @@ export const toBytes = (val: unknown): bytes => {
   }
   throw new InternalError(`Invalid type for bytes: ${nameOfType(val)}`)
 }
+
+export const minLengthForType = (typeInfo: TypeInfo): number => {
+  const minArc4StaticLength = tryArc4EncodedLengthImpl(typeInfo)
+  return minArc4StaticLength ?? 0
+}

src/impl/encoded-types.ts

@@ -2,6 +2,7 @@ import type {
   Account as AccountType,
   BigUintCompat,
   bytes,
+  NTuple,
   StringCompat,
   uint64,
   Uint64Compat,
@@ -417,8 +418,8 @@ export class StaticArrayImpl<TItem extends ARC4Encoded, TLength extends number>
     )
   }
 
-  get native(): TItem[] {
-    return this.items
+  get native(): NTuple<TItem, TLength> {
+    return this.items as NTuple<TItem, TLength>
   }
 
   static fromBytesImpl(
@@ -433,7 +434,7 @@ export class StaticArrayImpl<TItem extends ARC4Encoded, TLength extends number>
     }
     const result = new StaticArrayImpl(typeInfo)
     result.uint8ArrayValue = asUint8Array(bytesValue)
-    return result
+    return result as StaticArrayImpl<ARC4Encoded, number>
   }
 
   static getMaxBytesLength(typeInfo: TypeInfo): number {
@@ -1086,6 +1087,8 @@ const getMaxLengthOfStaticContentType = (type: TypeInfo): number => {
     case 'biguint':
       return UINT512_SIZE / BITS_IN_BYTE
     case 'boolean':
+      return 8
+    case 'Bool':
       return 1
     case 'Address':
       return AddressImpl.getMaxBytesLength(type)
@@ -1103,8 +1106,9 @@ const getMaxLengthOfStaticContentType = (type: TypeInfo): number => {
       return TupleImpl.getMaxBytesLength(type)
     case 'Struct':
       return StructImpl.getMaxBytesLength(type)
+    default:
+      throw new CodeError(`unsupported type ${type.name}`)
   }
-  throw new CodeError(`unsupported type ${type.name}`)
 }
 
 const encode = (values: ARC4Encoded[]) => {
@@ -1359,3 +1363,17 @@ export const arc4EncodedLengthImpl = (typeInfoString: string): uint64 => {
   const typeInfo = JSON.parse(typeInfoString)
   return getMaxLengthOfStaticContentType(typeInfo)
 }
+
+export const tryArc4EncodedLengthImpl = (typeInfoString: string | TypeInfo): uint64 | undefined => {
+  const typeInfo = typeof typeInfoString === 'string' ? JSON.parse(typeInfoString) : typeInfoString
+
+  try {
+    return getMaxLengthOfStaticContentType(typeInfo)
+  } catch (e) {
+    if (e instanceof CodeError && e.message.startsWith('unsupported type')) {
+      return undefined
+    }
+
+    throw e
+  }
+}

src/impl/pure.ts

@@ -45,7 +45,7 @@ export const bsqrt = (a: StubBigUintCompat): biguint => {
 export const btoi = (a: StubBytesCompat): uint64 => {
   const bytesValue = BytesCls.fromCompat(a)
   if (bytesValue.length.asAlgoTs() > BITS_IN_BYTE) {
-    throw new AvmError(`btoi arg too long, got [${bytesValue.length.valueOf()}]bytes`)
+    throw new AvmError(`btoi arg too long, got ${bytesValue.length.valueOf()} bytes`)
   }
   return bytesValue.toUint64().asAlgoTs()
 }

src/impl/state.ts

@@ -15,9 +15,9 @@ import { AccountMap } from '../collections/custom-key-map'
 import { MAX_BOX_SIZE } from '../constants'
 import { lazyContext } from '../context-helpers/internal-context'
 import type { TypeInfo } from '../encoders'
-import { getEncoder, toBytes } from '../encoders'
-import { AssertError, InternalError } from '../errors'
-import { getGenericTypeInfo } from '../runtime-helpers'
+import { getEncoder, minLengthForType, toBytes } from '../encoders'
+import { AssertError, CodeError, InternalError } from '../errors'
+import { getGenericTypeInfo, tryArc4EncodedLengthImpl } from '../runtime-helpers'
 import { asBytes, asBytesCls, asNumber, asUint8Array, conactUint8Arrays } from '../util'
 import type { StubBytesCompat, StubUint64Compat } from './primitives'
 import { Bytes, Uint64, Uint64Cls } from './primitives'
@@ -136,6 +136,17 @@ export class BoxCls<TValue> {
 
   private readonly _type: string = BoxCls.name
 
+  private get valueType(): TypeInfo {
+    if (this.#valueType === undefined) {
+      const typeInfo = getGenericTypeInfo(this)
+      if (typeInfo === undefined || typeInfo.genericArgs === undefined || typeInfo.genericArgs.length !== 1) {
+        throw new InternalError('Box value type is not set')
+      }
+      this.#valueType = (typeInfo.genericArgs as TypeInfo[])[0]
+    }
+    return this.#valueType
+  }
+
   static [Symbol.hasInstance](x: unknown): x is BoxCls<unknown> {
     return x instanceof Object && '_type' in x && (x as { _type: string })['_type'] === BoxCls.name
   }
@@ -151,6 +162,35 @@ export class BoxCls<TValue> {
     return (val: Uint8Array) => getEncoder<TValue>(valueType)(val, valueType)
   }
 
+  create(options?: { size?: StubUint64Compat }): boolean {
+    const optionSize = options?.size !== undefined ? asNumber(options.size) : undefined
+    const valueTypeSize = tryArc4EncodedLengthImpl(this.valueType)
+
+    if (valueTypeSize === undefined && optionSize === undefined) {
+      throw new InternalError(`${this.valueType.name} does not have a fixed byte size. Please specify a size argument`)
+    }
+
+    if (valueTypeSize !== undefined && optionSize !== undefined) {
+      if (optionSize < valueTypeSize) {
+        throw new InternalError(`Box size cannot be less than ${valueTypeSize}`)
+      }
+
+      if (optionSize > valueTypeSize) {
+        process.emitWarning(
+          `Box size is set to ${optionSize} but the value type ${this.valueType.name} has a fixed size of ${valueTypeSize}`,
+        )
+      }
+    }
+
+    lazyContext.ledger.setBox(
+      this.#app,
+      this.key,
+      new Uint8Array(Math.max(asNumber(options?.size ?? 0), this.valueType ? minLengthForType(this.valueType) : 0)),
+    )
+
+    return true
+  }
+
   get value(): TValue {
     if (!this.exists) {
       throw new InternalError('Box has not been created')
@@ -164,8 +204,17 @@ export class BoxCls<TValue> {
     lazyContext.ledger.setMatrialisedBox(this.#app, this.key, materialised)
     return materialised
   }
+
   set value(v: TValue) {
-    lazyContext.ledger.setBox(this.#app, this.key, asUint8Array(toBytes(v)))
+    const isStaticValueType = tryArc4EncodedLengthImpl(this.valueType) !== undefined
+    const newValueBytes = asUint8Array(toBytes(v))
+    if (isStaticValueType && this.exists) {
+      const originalValueBytes = lazyContext.ledger.getBox(this.#app, this.key)
+      if (originalValueBytes.length !== newValueBytes.length) {
+        throw new CodeError(`attempt to box_put wrong size ${originalValueBytes.length} != ${newValueBytes.length}`)
+      }
+    }
+    lazyContext.ledger.setBox(this.#app, this.key, newValueBytes)
     lazyContext.ledger.setMatrialisedBox(this.#app, this.key, v)
   }
 

src/impl/validate-encoding.ts

@@ -0,0 +1,2 @@
+/** @internal */
+export function validateEncoding<T>(_value: T) {}

src/internal/index.ts

@@ -13,6 +13,7 @@ export { Box, BoxMap, BoxRef, GlobalState, LocalState } from '../impl/state'
 export { TemplateVarImpl as TemplateVar } from '../impl/template-var'
 export { Txn } from '../impl/txn'
 export { urangeImpl as urange } from '../impl/urange'
+export { validateEncoding } from '../impl/validate-encoding'
 export { assert, err } from '../util'
 export * as arc4 from './arc4'
 export * as op from './op'

tests/arc4/encode-decode-arc4.spec.ts

@@ -145,7 +145,8 @@ describe('arc4EncodedLength', () => {
   test('should return the correct length', () => {
     expect(arc4EncodedLength<uint64>()).toEqual(8)
     expect(arc4EncodedLength<biguint>()).toEqual(64)
-    expect(arc4EncodedLength<boolean>()).toEqual(1)
+    expect(arc4EncodedLength<Bool>()).toEqual(1)
+    expect(arc4EncodedLength<boolean>()).toEqual(8)
     expect(arc4EncodedLength<UintN<512>>()).toEqual(64)
     expect(arc4EncodedLength<[uint64, uint64, boolean]>()).toEqual(17)
     expect(arc4EncodedLength<[uint64, uint64, boolean, boolean]>()).toEqual(17)

tests/artifacts/arc4-primitive-ops/contract.algo.ts

@@ -1,15 +1,16 @@
 import type { bytes } from '@algorandfoundation/algorand-typescript'
-import { arc4, BigUint, emit } from '@algorandfoundation/algorand-typescript'
+import { arc4, BigUint, emit, validateEncoding } from '@algorandfoundation/algorand-typescript'
 import type { Bool, UFixedNxM } from '@algorandfoundation/algorand-typescript/arc4'
 import { Byte, Contract, interpretAsArc4, Str, UintN } from '@algorandfoundation/algorand-typescript/arc4'
 
 export class Arc4PrimitiveOpsContract extends Contract {
-  @arc4.abimethod()
+  @arc4.abimethod({ validateEncoding: 'unsafe-disabled' })
   public verify_uintn_uintn_eq(a: bytes, b: bytes): boolean {
     const aBiguint = BigUint(a)
     const bBiguint = BigUint(b)
     const aUintN = new UintN<64>(aBiguint)
     const bUintN = new UintN<64>(bBiguint)
+    validateEncoding(aUintN)
     return aUintN === bUintN
   }
   @arc4.abimethod()

tests/pure-op-codes.spec.ts

@@ -185,7 +185,7 @@ describe('Pure op codes', async () => {
       Bytes(encodingUtil.bigIntToUint8Array(MAX_UINT512 * MAX_UINT512, 128)),
       Bytes(Array(5).fill(0x00).concat(Array(4).fill(0x0f))),
     ])('should throw error when input overflows', async (a, { appClientMiscellaneousOpsContract: appClient }) => {
-      const errorRegex = new RegExp(`btoi arg too long, got \\[${a.length.valueOf()}\\]bytes`)
+      const errorRegex = new RegExp(`btoi arg too long, got ${a.length.valueOf()} bytes`)
       await expect(getAvmResultRaw({ appClient }, 'verify_btoi', asUint8Array(a))).rejects.toThrow(errorRegex)
       expect(() => op.btoi(a)).toThrow(errorRegex)
     })