Merge pull request #77 from algorandfoundation/feat/itxn-compose

feat: implement ItxnCompose type for composing variable length transaction groups

Author: boblat

docs/code/subcontexts/transaction-context/classes/ItxnGroup.md

@@ -6,7 +6,7 @@
 
 # Class: ItxnGroup
 
-Defined in: [src/subcontexts/transaction-context.ts:485](https://github.com/algorandfoundation/algorand-typescript-testing/blob/main/src/subcontexts/transaction-context.ts#L485)
+Defined in: [src/subcontexts/transaction-context.ts:496](https://github.com/algorandfoundation/algorand-typescript-testing/blob/main/src/subcontexts/transaction-context.ts#L496)
 
 Represents a group of inner transactions.
 
@@ -16,7 +16,7 @@ Represents a group of inner transactions.
 
 > **new ItxnGroup**(`itxns`): `ItxnGroup`
 
-Defined in: [src/subcontexts/transaction-context.ts:487](https://github.com/algorandfoundation/algorand-typescript-testing/blob/main/src/subcontexts/transaction-context.ts#L487)
+Defined in: [src/subcontexts/transaction-context.ts:498](https://github.com/algorandfoundation/algorand-typescript-testing/blob/main/src/subcontexts/transaction-context.ts#L498)
 
 #### Parameters
 
@@ -34,15 +34,15 @@ Defined in: [src/subcontexts/transaction-context.ts:487](https://github.com/algo
 
 > **itxns**: `InnerTxn`[] = `[]`
 
-Defined in: [src/subcontexts/transaction-context.ts:486](https://github.com/algorandfoundation/algorand-typescript-testing/blob/main/src/subcontexts/transaction-context.ts#L486)
+Defined in: [src/subcontexts/transaction-context.ts:497](https://github.com/algorandfoundation/algorand-typescript-testing/blob/main/src/subcontexts/transaction-context.ts#L497)
 
 ## Methods
 
 ### getApplicationCallInnerTxn()
 
 > **getApplicationCallInnerTxn**(`index`?): `ApplicationCallInnerTxn`
 
-Defined in: [src/subcontexts/transaction-context.ts:496](https://github.com/algorandfoundation/algorand-typescript-testing/blob/main/src/subcontexts/transaction-context.ts#L496)
+Defined in: [src/subcontexts/transaction-context.ts:507](https://github.com/algorandfoundation/algorand-typescript-testing/blob/main/src/subcontexts/transaction-context.ts#L507)
 
 Gets an application inner transaction by index.
 
@@ -66,7 +66,7 @@ The application inner transaction.
 
 > **getAssetConfigInnerTxn**(`index`?): `AssetConfigInnerTxn`
 
-Defined in: [src/subcontexts/transaction-context.ts:505](https://github.com/algorandfoundation/algorand-typescript-testing/blob/main/src/subcontexts/transaction-context.ts#L505)
+Defined in: [src/subcontexts/transaction-context.ts:516](https://github.com/algorandfoundation/algorand-typescript-testing/blob/main/src/subcontexts/transaction-context.ts#L516)
 
 Gets an asset configuration inner transaction by index.
 
@@ -90,7 +90,7 @@ The asset configuration inner transaction.
 
 > **getAssetFreezeInnerTxn**(`index`?): `AssetFreezeInnerTxn`
 
-Defined in: [src/subcontexts/transaction-context.ts:523](https://github.com/algorandfoundation/algorand-typescript-testing/blob/main/src/subcontexts/transaction-context.ts#L523)
+Defined in: [src/subcontexts/transaction-context.ts:534](https://github.com/algorandfoundation/algorand-typescript-testing/blob/main/src/subcontexts/transaction-context.ts#L534)
 
 Gets an asset freeze inner transaction by index.
 
@@ -114,7 +114,7 @@ The asset freeze inner transaction.
 
 > **getAssetTransferInnerTxn**(`index`?): `AssetTransferInnerTxn`
 
-Defined in: [src/subcontexts/transaction-context.ts:514](https://github.com/algorandfoundation/algorand-typescript-testing/blob/main/src/subcontexts/transaction-context.ts#L514)
+Defined in: [src/subcontexts/transaction-context.ts:525](https://github.com/algorandfoundation/algorand-typescript-testing/blob/main/src/subcontexts/transaction-context.ts#L525)
 
 Gets an asset transfer inner transaction by index.
 
@@ -138,7 +138,7 @@ The asset transfer inner transaction.
 
 > **getInnerTxn**(`index`?): `InnerTxn`
 
-Defined in: [src/subcontexts/transaction-context.ts:550](https://github.com/algorandfoundation/algorand-typescript-testing/blob/main/src/subcontexts/transaction-context.ts#L550)
+Defined in: [src/subcontexts/transaction-context.ts:561](https://github.com/algorandfoundation/algorand-typescript-testing/blob/main/src/subcontexts/transaction-context.ts#L561)
 
 Gets an inner transaction by index.
 
@@ -162,7 +162,7 @@ The inner transaction.
 
 > **getKeyRegistrationInnerTxn**(`index`?): `KeyRegistrationInnerTxn`
 
-Defined in: [src/subcontexts/transaction-context.ts:532](https://github.com/algorandfoundation/algorand-typescript-testing/blob/main/src/subcontexts/transaction-context.ts#L532)
+Defined in: [src/subcontexts/transaction-context.ts:543](https://github.com/algorandfoundation/algorand-typescript-testing/blob/main/src/subcontexts/transaction-context.ts#L543)
 
 Gets a key registration inner transaction by index.
 
@@ -186,7 +186,7 @@ The key registration inner transaction.
 
 > **getPaymentInnerTxn**(`index`?): `PaymentInnerTxn`
 
-Defined in: [src/subcontexts/transaction-context.ts:541](https://github.com/algorandfoundation/algorand-typescript-testing/blob/main/src/subcontexts/transaction-context.ts#L541)
+Defined in: [src/subcontexts/transaction-context.ts:552](https://github.com/algorandfoundation/algorand-typescript-testing/blob/main/src/subcontexts/transaction-context.ts#L552)
 
 Gets a payment inner transaction by index.
 

docs/code/subcontexts/transaction-context/classes/TransactionGroup.md

@@ -196,7 +196,7 @@ If there is already an inner transaction group being constructed or the active t
 
 > **getApplicationCallTransaction**(`index`?): `ApplicationCallTransaction`
 
-Defined in: [src/subcontexts/transaction-context.ts:394](https://github.com/algorandfoundation/algorand-typescript-testing/blob/main/src/subcontexts/transaction-context.ts#L394)
+Defined in: [src/subcontexts/transaction-context.ts:405](https://github.com/algorandfoundation/algorand-typescript-testing/blob/main/src/subcontexts/transaction-context.ts#L405)
 
 Gets an application transaction by index.
 
@@ -220,7 +220,7 @@ The application transaction.
 
 > **getAssetConfigTransaction**(`index`?): `AssetConfigTransaction`
 
-Defined in: [src/subcontexts/transaction-context.ts:403](https://github.com/algorandfoundation/algorand-typescript-testing/blob/main/src/subcontexts/transaction-context.ts#L403)
+Defined in: [src/subcontexts/transaction-context.ts:414](https://github.com/algorandfoundation/algorand-typescript-testing/blob/main/src/subcontexts/transaction-context.ts#L414)
 
 Gets an asset configuration transaction by index.
 
@@ -244,7 +244,7 @@ The asset configuration transaction.
 
 > **getAssetFreezeTransaction**(`index`?): `AssetFreezeTransaction`
 
-Defined in: [src/subcontexts/transaction-context.ts:421](https://github.com/algorandfoundation/algorand-typescript-testing/blob/main/src/subcontexts/transaction-context.ts#L421)
+Defined in: [src/subcontexts/transaction-context.ts:432](https://github.com/algorandfoundation/algorand-typescript-testing/blob/main/src/subcontexts/transaction-context.ts#L432)
 
 Gets an asset freeze transaction by index.
 
@@ -268,7 +268,7 @@ The asset freeze transaction.
 
 > **getAssetTransferTransaction**(`index`?): `AssetTransferTransaction`
 
-Defined in: [src/subcontexts/transaction-context.ts:412](https://github.com/algorandfoundation/algorand-typescript-testing/blob/main/src/subcontexts/transaction-context.ts#L412)
+Defined in: [src/subcontexts/transaction-context.ts:423](https://github.com/algorandfoundation/algorand-typescript-testing/blob/main/src/subcontexts/transaction-context.ts#L423)
 
 Gets an asset transfer transaction by index.
 
@@ -292,7 +292,7 @@ The asset transfer transaction.
 
 > **getItxnGroup**(`index`?): [`ItxnGroup`](ItxnGroup.md)
 
-Defined in: [src/subcontexts/transaction-context.ts:376](https://github.com/algorandfoundation/algorand-typescript-testing/blob/main/src/subcontexts/transaction-context.ts#L376)
+Defined in: [src/subcontexts/transaction-context.ts:387](https://github.com/algorandfoundation/algorand-typescript-testing/blob/main/src/subcontexts/transaction-context.ts#L387)
 
 Gets an inner transaction group by index.
 
@@ -320,7 +320,7 @@ If the index is invalid or there are no previous inner transactions.
 
 > **getKeyRegistrationTransaction**(`index`?): `KeyRegistrationTransaction`
 
-Defined in: [src/subcontexts/transaction-context.ts:430](https://github.com/algorandfoundation/algorand-typescript-testing/blob/main/src/subcontexts/transaction-context.ts#L430)
+Defined in: [src/subcontexts/transaction-context.ts:441](https://github.com/algorandfoundation/algorand-typescript-testing/blob/main/src/subcontexts/transaction-context.ts#L441)
 
 Gets a key registration transaction by index.
 
@@ -344,7 +344,7 @@ The key registration transaction.
 
 > **getPaymentTransaction**(`index`?): `PaymentTransaction`
 
-Defined in: [src/subcontexts/transaction-context.ts:439](https://github.com/algorandfoundation/algorand-typescript-testing/blob/main/src/subcontexts/transaction-context.ts#L439)
+Defined in: [src/subcontexts/transaction-context.ts:450](https://github.com/algorandfoundation/algorand-typescript-testing/blob/main/src/subcontexts/transaction-context.ts#L450)
 
 Gets a payment transaction by index.
 
@@ -408,7 +408,7 @@ The scratch space.
 
 > **getTransaction**(`index`?): `Transaction`
 
-Defined in: [src/subcontexts/transaction-context.ts:448](https://github.com/algorandfoundation/algorand-typescript-testing/blob/main/src/subcontexts/transaction-context.ts#L448)
+Defined in: [src/subcontexts/transaction-context.ts:459](https://github.com/algorandfoundation/algorand-typescript-testing/blob/main/src/subcontexts/transaction-context.ts#L459)
 
 Gets a transaction by index.
 
@@ -432,7 +432,7 @@ The transaction.
 
 > **lastItxnGroup**(): [`ItxnGroup`](ItxnGroup.md)
 
-Defined in: [src/subcontexts/transaction-context.ts:366](https://github.com/algorandfoundation/algorand-typescript-testing/blob/main/src/subcontexts/transaction-context.ts#L366)
+Defined in: [src/subcontexts/transaction-context.ts:377](https://github.com/algorandfoundation/algorand-typescript-testing/blob/main/src/subcontexts/transaction-context.ts#L377)
 
 Gets the last inner transaction group.
 

docs/coverage.md

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

package.json

@@ -23,7 +23,7 @@
     "test:ci": "vitest run --coverage --reporter junit --outputFile test-results.xml",
     "script:documentation": "typedoc",
     "script:build-examples": "rollup --config examples/rollup.config.ts --configPlugin typescript",
-    "script:compile-examples": "puya-ts --out-dir data ./examples/*/",
+    "script:compile-examples": "puya-ts --out-dir data ./examples/*/ --puya-path=/home/parallels/.local/bin/puya",
     "script:refresh-test-artifacts": "puya-ts --out-dir data ./tests/artifacts/*/"
   },
   "devDependencies": {

src/impl/c2c.ts

@@ -43,7 +43,7 @@ export function compileArc4<TContract extends Contract>(
             },
             selector,
           )
-          invokeCallback(itxnContext)
+          invokeAbiCall(itxnContext)
           return {
             itxn: itxnContext,
             returnValue: itxnContext.loggedReturnValue,
@@ -57,7 +57,7 @@ export function compileArc4<TContract extends Contract>(
         ...getCommonApplicationCallFields(app, options),
         ...methodArgs,
       })
-      invokeCallback(itxnContext)
+      invokeAbiCall(itxnContext)
       return itxnContext
     },
     approvalProgram: app?.application.approvalProgram ?? [lazyContext.any.bytes(10), lazyContext.any.bytes(10)],
@@ -70,7 +70,7 @@ export function compileArc4<TContract extends Contract>(
   } as unknown as ContractProxy<TContract>
 }
 
-const invokeCallback = (itxnContext: ApplicationCallInnerTxnContext) => {
+export const invokeAbiCall = (itxnContext: ApplicationCallInnerTxnContext) => {
   lazyContext.value.notifyApplicationSpies(itxnContext)
   lazyContext.txn.activeGroup.addInnerTransactionGroup(...(itxnContext.itxns ?? []), itxnContext)
 }
@@ -84,21 +84,29 @@ const getCommonApplicationCallFields = (app: ApplicationData | undefined, option
   localNumBytes: options?.localBytes ?? app?.application.localNumBytes ?? lazyContext.any.uint64(),
 })
 
-export function abiCall<TArgs extends DeliberateAny[], TReturn>(
+export function getApplicationCallInnerTxnContext<TArgs extends DeliberateAny[], TReturn = void>(
   method: InstanceMethod<Contract, TArgs, TReturn>,
   methodArgs: TypedApplicationCallFields<TArgs>,
   contract?: Contract | { new (): Contract },
-): { itxn: ApplicationCallInnerTxn; returnValue: TReturn | undefined } {
+) {
   const abiMetadata = contract ? getContractMethodAbiMetadata(contract, method.name) : undefined
   const selector = methodSelector(method, contract)
-  const itxnContext = ApplicationCallInnerTxnContext.createFromTypedApplicationCallFields<TReturn>(
+  return ApplicationCallInnerTxnContext.createFromTypedApplicationCallFields<TReturn>(
     {
       ...methodArgs,
       onCompletion: methodArgs.onCompletion ?? abiMetadata?.allowActions?.map((action) => OnCompleteAction[action])[0],
     },
     selector,
   )
-  invokeCallback(itxnContext)
+}
+export function abiCall<TArgs extends DeliberateAny[], TReturn>(
+  method: InstanceMethod<Contract, TArgs, TReturn>,
+  methodArgs: TypedApplicationCallFields<TArgs>,
+  contract?: Contract | { new (): Contract },
+): { itxn: ApplicationCallInnerTxn; returnValue: TReturn | undefined } {
+  const itxnContext = getApplicationCallInnerTxnContext(method, methodArgs, contract)
+
+  invokeAbiCall(itxnContext)
 
   return {
     itxn: itxnContext,

src/impl/inner-transactions.ts

@@ -12,7 +12,7 @@ import { lazyContext } from '../context-helpers/internal-context'
 import { InternalError, invariant } from '../errors'
 import { extractArraysFromArgs } from '../subcontexts/contract-context'
 import type { DeliberateAny } from '../typescript-helpers'
-import { asBytes, asNumber, asUint8Array } from '../util'
+import { asBytes, asNumber, asUint64, asUint8Array } from '../util'
 import { getApp } from './app-params'
 import { getAsset } from './asset-params'
 import { encodeArc4Impl } from './encoded-types'
@@ -247,16 +247,27 @@ export class ItxnParams<TFields extends InnerTxnFields, TTransaction extends Inn
     return this.#fields.type === TransactionType.ApplicationCall
   }
 
-  submit(): TTransaction {
+  createInnerTxns(): TTransaction[] {
     let itxnContext: ApplicationCallInnerTxnContext | undefined
-
     if (this.isApplicationCall()) {
       itxnContext = ApplicationCallInnerTxnContext.createFromFields(this.#fields)
-      lazyContext.value.notifyApplicationSpies(itxnContext)
     }
-    const innerTxn = (itxnContext ?? createInnerTxn<InnerTxnFields>(this.#fields)) as unknown as TTransaction
-    lazyContext.txn.activeGroup.addInnerTransactionGroup(innerTxn)
-    return innerTxn
+    const innerTxns = [
+      ...(itxnContext?.itxns ?? []),
+      itxnContext ?? createInnerTxn<InnerTxnFields>(this.#fields),
+    ] as unknown as TTransaction[]
+    return innerTxns
+  }
+
+  submit(): TTransaction {
+    const innerTxns = this.createInnerTxns()
+    innerTxns.forEach((itxn, index) => Object.assign(itxn, { groupIndex: asUint64(index) }))
+    const lastInnerTxn = innerTxns.at(-1)
+    if (lastInnerTxn instanceof ApplicationCallInnerTxnContext) {
+      lazyContext.value.notifyApplicationSpies(lastInnerTxn)
+    }
+    lazyContext.txn.activeGroup.addInnerTransactionGroup(...innerTxns)
+    return lastInnerTxn as TTransaction
   }
 
   set(p: Partial<TFields>) {

src/impl/itxn-compose.ts

@@ -0,0 +1,70 @@
+import {
+  type AnyTransactionComposeFields,
+  type ApplicationCallComposeFields,
+  type AssetConfigComposeFields,
+  type AssetFreezeComposeFields,
+  type AssetTransferComposeFields,
+  type ComposeItxnParams,
+  type Contract,
+  type ItxnCompose,
+  type KeyRegistrationComposeFields,
+  type PaymentComposeFields,
+} from '@algorandfoundation/algorand-typescript'
+import type { TypedApplicationCallFields } from '@algorandfoundation/algorand-typescript/arc4'
+import { lazyContext } from '../context-helpers/internal-context'
+import type { DeliberateAny, InstanceMethod } from '../typescript-helpers'
+import { getApplicationCallInnerTxnContext } from './c2c'
+
+class ItxnComposeImpl {
+  begin(fields: PaymentComposeFields): void
+  begin(fields: KeyRegistrationComposeFields): void
+  begin(fields: AssetConfigComposeFields): void
+  begin(fields: AssetTransferComposeFields): void
+  begin(fields: AssetFreezeComposeFields): void
+  begin(fields: ApplicationCallComposeFields): void
+  begin(fields: AnyTransactionComposeFields): void
+  begin(fields: ComposeItxnParams): void
+  begin<TArgs extends DeliberateAny[]>(
+    method: InstanceMethod<Contract, TArgs>,
+    fields: TypedApplicationCallFields<TArgs>,
+    contract?: Contract | { new (): Contract },
+  ): void
+  begin<TArgs extends DeliberateAny[]>(...args: unknown[]): void {
+    lazyContext.txn.activeGroup.constructingItxnGroup.push(
+      args.length === 1
+        ? (args[0] as AnyTransactionComposeFields)
+        : getApplicationCallInnerTxnContext(
+            args[0] as InstanceMethod<Contract, TArgs>,
+            args[1] as TypedApplicationCallFields<TArgs>,
+            args[2] as Contract | { new (): Contract },
+          ),
+    )
+  }
+
+  next(fields: PaymentComposeFields): void
+  next(fields: KeyRegistrationComposeFields): void
+  next(fields: AssetConfigComposeFields): void
+  next(fields: AssetTransferComposeFields): void
+  next(fields: AssetFreezeComposeFields): void
+  next(fields: ApplicationCallComposeFields): void
+  next(fields: AnyTransactionComposeFields): void
+  next(fields: ComposeItxnParams): void
+  next<TArgs extends DeliberateAny[]>(_method: InstanceMethod<Contract, TArgs>, _fields: TypedApplicationCallFields<TArgs>): void
+  next<TArgs extends DeliberateAny[]>(...args: unknown[]): void {
+    lazyContext.txn.activeGroup.constructingItxnGroup.push(
+      args.length === 1
+        ? (args[0] as AnyTransactionComposeFields)
+        : getApplicationCallInnerTxnContext(
+            args[0] as InstanceMethod<Contract, TArgs>,
+            args[1] as TypedApplicationCallFields<TArgs>,
+            args[2] as Contract | { new (): Contract },
+          ),
+    )
+  }
+
+  submit(): void {
+    lazyContext.txn.activeGroup.submitInnerTransactionGroup()
+  }
+}
+
+export const itxnCompose: ItxnCompose = new ItxnComposeImpl()

src/internal/index.ts

@@ -45,3 +45,5 @@ export const itxn = {
   assetFreeze,
   applicationCall,
 }
+
+export { itxnCompose } from '../impl/itxn-compose'

src/subcontexts/transaction-context.ts

@@ -15,7 +15,7 @@ import type {
   KeyRegistrationInnerTxn,
   PaymentInnerTxn,
 } from '../impl/inner-transactions'
-import { createInnerTxn } from '../impl/inner-transactions'
+import { ApplicationCallInnerTxnContext, createInnerTxn, ItxnParams } from '../impl/inner-transactions'
 import type { InnerTxn, InnerTxnFields } from '../impl/itxn'
 import type { StubBytesCompat, StubUint64Compat } from '../impl/primitives'
 import type {
@@ -353,8 +353,19 @@ export class TransactionGroup {
     if (this.constructingItxnGroup.length > TRANSACTION_GROUP_MAX_SIZE) {
       throw new InternalError(`Cannot submit more than ${TRANSACTION_GROUP_MAX_SIZE} inner transactions at once`)
     }
-    const itxns = this.constructingItxnGroup.map((t) => createInnerTxn(t))
+    const itxns = this.constructingItxnGroup.flatMap((t) =>
+      t instanceof ApplicationCallInnerTxnContext
+        ? [...(t.itxns ?? []), t]
+        : t instanceof ItxnParams
+          ? t.createInnerTxns()
+          : [createInnerTxn(t)],
+    )
     itxns.forEach((itxn, index) => Object.assign(itxn, { groupIndex: asUint64(index) }))
+    for (const itxn of itxns) {
+      if (itxn instanceof ApplicationCallInnerTxnContext) {
+        lazyContext.value.notifyApplicationSpies(itxn)
+      }
+    }
     this.itxnGroups.push(new ItxnGroup(itxns))
     this.constructingItxnGroup = []
   }