Merge pull request #94 from algorandfoundation/refactor/rename-interpret-as-arc4

refactor: rename `interpretAsArc4` function as `convertBytes` with `strategy` option

Author: boblat

docs/coverage.md

@@ -42,7 +42,7 @@ See which `algorand-typescript` stubs are implemented by the `algorand-typescrip
 | encodeArc4                   | Native              |
 | ensureBudget                 | Emulated            |
 | err                          | Native              |
-| interpretAsArc4              | Native              |
+| convertBytes                 | Native              |
 | itxnCompose                  | Emulated            |
 | log                          | Emulated            |
 | logicSig                     | Emulated            |

examples/marketplace/contract.algo.spec.ts

@@ -1,6 +1,6 @@
 import { arc4, Bytes } from '@algorandfoundation/algorand-typescript'
 import { TestExecutionContext } from '@algorandfoundation/algorand-typescript-testing'
-import { interpretAsArc4 } from '@algorandfoundation/algorand-typescript/arc4'
+import { convertBytes } from '@algorandfoundation/algorand-typescript/arc4'
 import { afterEach, describe, expect, test } from 'vitest'
 import DigitalMarketplace, { ListingKey, ListingValue } from './contract.algo'
 
@@ -39,7 +39,9 @@ describe('DigitalMarketplace', () => {
       asset: new arc4.Uint64(testAsset.id),
       nonce: testNonce,
     })
-    const listingValue = interpretAsArc4<ListingValue>(Bytes(ctx.ledger.getBox(contract, Bytes('listings').concat(listingKey.bytes))))
+    const listingValue = convertBytes<ListingValue>(Bytes(ctx.ledger.getBox(contract, Bytes('listings').concat(listingKey.bytes))), {
+      strategy: 'unsafe-cast',
+    })
     expect(listingValue.deposited.asUint64()).toEqual(10)
   })
 
@@ -100,7 +102,9 @@ describe('DigitalMarketplace', () => {
     contract.setPrice(testAsset, testNonce, testUnitaryPrice)
 
     // Assert
-    const updatedListing = interpretAsArc4<ListingValue>(Bytes(ctx.ledger.getBox(contract, Bytes('listings').concat(listingKey.bytes))))
+    const updatedListing = convertBytes<ListingValue>(Bytes(ctx.ledger.getBox(contract, Bytes('listings').concat(listingKey.bytes))), {
+      strategy: 'unsafe-cast',
+    })
     expect(updatedListing.unitaryPrice.asUint64()).toEqual(testUnitaryPrice.asUint64())
   })
 
@@ -136,7 +140,9 @@ describe('DigitalMarketplace', () => {
     )
 
     // Assert
-    const updatedListing = interpretAsArc4<ListingValue>(Bytes(ctx.ledger.getBox(contract, Bytes('listings').concat(listingKey.bytes))))
+    const updatedListing = convertBytes<ListingValue>(Bytes(ctx.ledger.getBox(contract, Bytes('listings').concat(listingKey.bytes))), {
+      strategy: 'unsafe-cast',
+    })
     expect(updatedListing.deposited.asUint64()).toEqual(initialDeposit.asUint64() - testBuyQuantity.asUint64())
     expect(ctx.txn.lastGroup.getItxnGroup(0).getAssetTransferInnerTxn(0).assetReceiver).toEqual(ctx.defaultSender)
   })

examples/zk-whitelist/contract.algo.ts

@@ -56,7 +56,9 @@ export default class ZkWhitelistContract extends arc4.Contract {
     // The verifier expects public inputs to be in the curve field, but an
     // Algorand address might represent a number larger than the field
     // modulus, so to be safe we take the address modulo the field modulus
-    const addressMod = arc4.interpretAsArc4<arc4.Address>(op.bzero(32).bitwiseOr(Bytes(BigUint(address.bytes) % curveMod)))
+    const addressMod = arc4.convertBytes<arc4.Address>(op.bzero(32).bitwiseOr(Bytes(BigUint(address.bytes) % curveMod)), {
+      strategy: 'unsafe-cast',
+    })
     // Verify the proof by calling the deposit verifier app
     const verified = this.verifyProof(TemplateVar<uint64>('VERIFIER_APP_ID'), proof, new arc4.DynamicArray(addressMod))
     if (!verified.native) {
@@ -93,6 +95,6 @@ export default class ZkWhitelistContract extends arc4.Contract {
         onCompletion: OnCompleteAction.NoOp,
       })
       .submit().lastLog
-    return arc4.interpretAsArc4<arc4.Bool>(verified, 'log')
+    return arc4.convertBytes<arc4.Bool>(verified, { prefix: 'log', strategy: 'unsafe-cast' })
   }
 }

package-lock.json

@@ -68,8 +68,8 @@
     "vitest": "3.2.4"
   },
   "dependencies": {
-    "@algorandfoundation/algorand-typescript": "1.0.0-alpha.82",
-    "@algorandfoundation/puya-ts": "1.0.0-alpha.82",
+    "@algorandfoundation/algorand-typescript": "1.0.0-alpha.83",
+    "@algorandfoundation/puya-ts": "1.0.0-alpha.83",
     "elliptic": "^6.6.1",
     "js-sha256": "^0.11.0",
     "js-sha3": "^0.9.3",

package.json

@@ -1217,13 +1217,13 @@ export function decodeArc4<T>(
 }
 
 /** @internal */
-export function interpretAsArc4<T extends _ARC4Encoded>(
+export function convertBytes<T extends _ARC4Encoded>(
   typeInfoString: string,
   bytes: StubBytesCompat,
-  prefix: 'none' | 'log' = 'none',
+  options: { prefix?: 'none' | 'log'; strategy: 'unsafe-cast' },
 ): T {
   const typeInfo = JSON.parse(typeInfoString)
-  return getEncoder<T>(typeInfo)(bytes, typeInfo, prefix)
+  return getEncoder<T>(typeInfo)(bytes, typeInfo, options.prefix)
 }
 
 /** @internal */

src/impl/encoded-types/encoded-types.ts

@@ -3,14 +3,14 @@ export {
   Address,
   Bool,
   Byte,
+  convertBytes,
   decodeArc4,
   DynamicArray,
   DynamicBytes,
   encodeArc4,
   FixedArray,
   getArc4Encoded,
   getEncoder,
-  interpretAsArc4,
   ReferenceArray,
   StaticArray,
   StaticBytes,

src/impl/encoded-types/index.ts

@@ -9,12 +9,12 @@ export {
   Address,
   Bool,
   Byte,
+  convertBytes,
   decodeArc4,
   DynamicArray,
   DynamicBytes,
   encodeArc4,
   FixedArray,
-  interpretAsArc4,
   ReferenceArray,
   sizeOf,
   StaticArray,

src/internal/arc4.ts

@@ -506,17 +506,7 @@ const tryGetStubbedFunctionName = (node: ts.CallExpression, helper: VisitorHelpe
     : (node.expression as ts.Identifier)
   const functionName = tryGetAlgoTsSymbolName(identityExpression, helper)
   if (functionName === undefined) return undefined
-  const stubbedFunctionNames = [
-    'interpretAsArc4',
-    'decodeArc4',
-    'encodeArc4',
-    'emit',
-    'methodSelector',
-    'sizeOf',
-    'abiCall',
-    'clone',
-    'Bytes',
-  ]
+  const stubbedFunctionNames = ['convertBytes', 'decodeArc4', 'encodeArc4', 'emit', 'methodSelector', 'sizeOf', 'abiCall', 'clone', 'Bytes']
 
   if (stubbedFunctionNames.includes(functionName)) {
     if (ts.isPropertyAccessExpression(node.expression)) {

src/test-transformer/visitors.ts

@@ -1,7 +1,7 @@
 import { getABIEncodedValue } from '@algorandfoundation/algokit-utils/types/app-arc56'
 import { Account, Bytes } from '@algorandfoundation/algorand-typescript'
 import { TestExecutionContext } from '@algorandfoundation/algorand-typescript-testing'
-import { Address, interpretAsArc4 } from '@algorandfoundation/algorand-typescript/arc4'
+import { Address, convertBytes } from '@algorandfoundation/algorand-typescript/arc4'
 import { afterEach, describe, expect, test } from 'vitest'
 import { ABI_RETURN_VALUE_LOG_PREFIX } from '../../src/constants'
 import { encodeAddress } from '../../src/impl/reference'
@@ -71,14 +71,14 @@ describe('arc4.Address', () => {
 
   test.each(testData)('fromBytes method', (value) => {
     const sdkResult = getABIEncodedValue(asUint8Array(value), abiTypeString, {})
-    const result = interpretAsArc4<Address>(value)
+    const result = convertBytes<Address>(value, { strategy: 'unsafe-cast' })
     expect(result.bytes).toEqual(sdkResult)
   })
 
   test.each(testData)('fromLog method', (value) => {
     const sdkResult = getABIEncodedValue(asUint8Array(value), abiTypeString, {})
     const paddedValue = Bytes([...asUint8Array(ABI_RETURN_VALUE_LOG_PREFIX), ...asUint8Array(value)])
-    const result = interpretAsArc4<Address>(paddedValue, 'log')
+    const result = convertBytes<Address>(paddedValue, { prefix: 'log', strategy: 'unsafe-cast' })
     expect(result.bytes).toEqual(sdkResult)
   })
 })