feat: Add generic version of itxnCompose.begin and next, plus methodSelector helper which works with type only imports

Author: tristanmenzel

packages/algo-ts/src/arc4/index.ts

@@ -216,7 +216,16 @@ export function methodSelector(methodSignature: InstanceMethod<Contract>): bytes
  * @returns The ARC4 method selector. Eg. `02BECE11`
  */
 export function methodSelector(methodSignature: string): bytes<4>
-export function methodSelector(methodSignature: string | InstanceMethod<Contract>): bytes<4> {
+/**
+ * Returns the ARC4 method selector for a given ARC4 method signature. The method selector is the first
+ * 4 bytes of the SHA512/256 hash of the method signature.
+ * @typeParam TMethod The type of an ARC4 method signature (eg. `typeof MyContract.prototype.myMethod`)
+ * @returns The ARC4 method selector. Eg. `02BECE11`
+ * @remarks This overload can be used in conjunction with type only import (eg. `import type { MyContract } from './my-contract'`) to
+ * work around what would otherwise be a circular reference in the event two contracts need to call each other.
+ */
+export function methodSelector<TMethod>(): bytes<4>
+export function methodSelector<TMethod>(methodSignature?: string | InstanceMethod<Contract>): bytes<4> {
   throw new NoImplementation()
 }
 

packages/algo-ts/src/itxn-compose.ts

@@ -1,4 +1,4 @@
-import { Contract, TypedApplicationCallFields } from './arc4'
+import { AbiCallOptions, Contract, TypedApplicationCallFields } from './arc4'
 import { NoImplementation } from './internal/errors'
 import { DeliberateAny, InstanceMethod } from './internal/typescript-helpers'
 import { itxn } from './itxn'
@@ -42,27 +42,138 @@ export type ComposeItxnParams =
   | itxn.ApplicationCallItxnParams
 
 export type ItxnCompose = {
+  /**
+   * Begin a transaction group with a payment transaction
+   * @param fields Specifies any transaction fields which should differ from their defaults
+   */
   begin(fields: PaymentComposeFields): void
+  /**
+   * Begin a transaction group with a key registration transaction
+   * @param fields Specifies any transaction fields which should differ from their defaults
+   */
   begin(fields: KeyRegistrationComposeFields): void
+  /**
+   * Begin a transaction group with an asset config transaction
+   * @param fields Specifies any transaction fields which should differ from their defaults
+   */
   begin(fields: AssetConfigComposeFields): void
+  /**
+   * Begin a transaction group with an asset transfer transaction
+   * @param fields Specifies any transaction fields which should differ from their defaults
+   */
   begin(fields: AssetTransferComposeFields): void
+  /**
+   * Begin a transaction group with an asset freeze transaction
+   * @param fields Specifies any transaction fields which should differ from their defaults
+   */
   begin(fields: AssetFreezeComposeFields): void
+  /**
+   * Begin a transaction group with an application call transaction
+   * @param fields Specifies any transaction fields which should differ from their defaults
+   */
   begin(fields: ApplicationCallComposeFields): void
+  /**
+   * Begin a transaction group with a new transaction with the specified fields
+   * @param fields Specifies the type, and any transaction fields which should differ from their defaults
+   */
   begin(fields: AnyTransactionComposeFields): void
+  /**
+   * Begin a transaction group with a new transaction from the specified itxn params object
+   * @param fields
+   */
   begin(fields: ComposeItxnParams): void
+  /**
+   * Begin a transaction group with a typed application call transaction.
+   * @param method The ABI method to call
+   * @param fields Specifies any transaction fields which should differ from their defaults
+   *
+   * @deprecated This overload has been deprecated in favour of the single arg overload where method is specified as a property of the fields
+   * object, or via an explicit generic param. (`itxnCompose.begin({ method: MyContract.prototype.myMethod, ... })` or
+   * `itxnCompose.begin<typeof MyContract.prototype.myMethod>({ ... })`)
+   */
   begin<TArgs extends DeliberateAny[]>(method: InstanceMethod<Contract, TArgs>, fields: TypedApplicationCallFields<TArgs>): void
+  /**
+   * Begin a transaction group with a typed application call transaction. The method can be specified by options.method, or
+   * by explicitly defining the type of the generic parameter TMethod.
+   * @param options Specifies any transaction fields which should differ from their defaults
+   * @typeParam TMethod  The type of an ARC4 method signature (eg. `typeof MyContract.prototype.myMethod`)
+   */
+  begin<TMethod>(options: AbiCallOptions<TMethod>): void
 
+  /**
+   * Continue a transaction group with a payment transaction
+   * @param fields Specifies any transaction fields which should differ from their defaults
+   */
   next(fields: PaymentComposeFields): void
+  /**
+   * Continue a transaction group with a key registration transaction
+   * @param fields Specifies any transaction fields which should differ from their defaults
+   */
   next(fields: KeyRegistrationComposeFields): void
+  /**
+   * Continue a transaction group with an asset config transaction
+   * @param fields Specifies any transaction fields which should differ from their defaults
+   */
   next(fields: AssetConfigComposeFields): void
+  /**
+   * Continue a transaction group with an asset transfer transaction
+   * @param fields Specifies any transaction fields which should differ from their defaults
+   */
   next(fields: AssetTransferComposeFields): void
+  /**
+   * Continue a transaction group with an asset freeze transaction
+   * @param fields Specifies any transaction fields which should differ from their defaults
+   */
   next(fields: AssetFreezeComposeFields): void
+  /**
+   * Continue a transaction group with an application call transaction
+   * @param fields Specifies any transaction fields which should differ from their defaults
+   */
   next(fields: ApplicationCallComposeFields): void
+  /**
+   * Continue a transaction group with a new transaction with the specified fields
+   * @param fields Specifies the type, and any transaction fields which should differ from their defaults
+   */
   next(fields: AnyTransactionComposeFields): void
+  /**
+   * Continue a transaction group with a new transaction from the specified itxn params object
+   * @param fields
+   */
   next(fields: ComposeItxnParams): void
+  /**
+   * Continue a transaction group with a typed application call transaction.
+   * @param method The ABI method to call
+   * @param fields Specifies any transaction fields which should differ from their defaults
+   *
+   * @deprecated This overload has been deprecated in favour of the single arg overload where method is specified as a property of the fields
+   * object, or via an explicit generic param. (`itxnCompose.next({ method: MyContract.prototype.myMethod, ... })` or
+   * `itxnCompose.next<typeof MyContract.prototype.myMethod>({ ... })`)
+   */
   next<TArgs extends DeliberateAny[]>(method: InstanceMethod<Contract, TArgs>, fields: TypedApplicationCallFields<TArgs>): void
+  /**
+   * Continue a transaction group with a typed application call transaction. The method can be specified by options.method, or
+   * by explicitly defining the type of the generic parameter TMethod.
+   * @param options Specifies any transaction fields which should differ from their defaults
+   * @typeParam TMethod  The type of an ARC4 method signature (eg. `typeof MyContract.prototype.myMethod`)
+   */
+  next<TMethod>(options: AbiCallOptions<TMethod>): void
 
+  /**
+   * Submit all transactions in the group
+   *
+   * @remarks `op.GITxn.lastLog(n)` (and other methods on the GITxn object) can be used to read fields from the most recently submitted
+   * transaction group where `n` is a compile time constant representing the index of the transaction in the group.
+   */
   submit(): void
 }
 
+/**
+ * The itxnCompose helper can be used to build dynamically sized itxn groups which aren't supported by the stronger typed itxn paradigm. The
+ * first transaction in a group must be 'staged' with `itxnCompose.begin` whilst all other transactions in the group should use `itxnCompose.next`.
+ * When the group is complete it can be submitted using `itxnCompose.submit`.
+ *
+ * @remarks The itxn API offered by teal opcodes has some rough edges which are not fully abstracted over by this compose API, but it hoped that use
+ * cases for it are limited and that most transaction groups can be composed with a static size relying on the atomic nature of the outer transaction
+ * to ensure multiple smaller itxn groups are committed atomically.
+ */
 export const itxnCompose: ItxnCompose = NoImplementation.value()

src/awst_build/arc4-util.ts

@@ -1,10 +1,11 @@
 import type { ResourceEncoding } from '../awst'
 import { nodeFactory } from '../awst/node-factory'
-import type { ARC4ABIMethodConfig } from '../awst/nodes'
+import { ARC4ABIMethodConfig } from '../awst/nodes'
 import type { SourceLocation } from '../awst/source-location'
 import { wtypes } from '../awst/wtypes'
 import { CodeError } from '../errors'
 import { codeInvariant, invariant } from '../util'
+import { AwstBuildContext } from './context/awst-build-context'
 import type { ABICompatiblePType, FunctionPType, PType } from './ptypes'
 import {
   ABICompatibleInstanceType,
@@ -84,6 +85,29 @@ export function ptypeToAbiPType(
   throw new CodeError(`${ptype} cannot be used as an ABI ${direction === 'in' ? 'param' : 'return'} type`, { sourceLocation })
 }
 
+export function arc4ConfigFromType(functionType: FunctionPType, sourceLocation: SourceLocation) {
+  codeInvariant(
+    functionType.declaredIn,
+    `${functionType.name} does not appear to be a contract method. Ensure you are calling a function defined on a contract class eg. abiCall<typeof YourContract.prototype.yourMethod>`,
+    sourceLocation,
+  )
+
+  const contractType = AwstBuildContext.current.getContractTypeByName(functionType.declaredIn)
+  invariant(contractType, `${functionType.declaredIn} has not been visited`)
+
+  const arc4Config = AwstBuildContext.current.getArc4Config(contractType, functionType.name)
+  codeInvariant(
+    arc4Config instanceof ARC4ABIMethodConfig,
+    `${functionType.name} is not an ABI method. Only ABI compatible methods can be called with this helper.`,
+    sourceLocation,
+  )
+  const methodSelector = buildArc4MethodConstant(functionType, arc4Config, sourceLocation)
+  return {
+    arc4Config,
+    methodSelector,
+  }
+}
+
 /**
  * Generate a methodConstant node for the given function, making use of the ARC4ABIMethodConfig
  * @param functionType The function ptype

src/awst_build/eb/arc4/c2c.ts

@@ -10,7 +10,7 @@ import { Constants } from '../../../constants'
 import { logger } from '../../../logger'
 import { codeInvariant, enumFromValue, hexToUint8Array, invariant } from '../../../util'
 import { parseArc4Method } from '../../../util/arc4-signature-parser'
-import { buildArc4MethodConstant, ptypeToArc4EncodedType } from '../../arc4-util'
+import { arc4ConfigFromType, buildArc4MethodConstant, ptypeToArc4EncodedType } from '../../arc4-util'
 import { AwstBuildContext } from '../../context/awst-build-context'
 import type { PType } from '../../ptypes'
 import {
@@ -66,22 +66,7 @@ export class AbiCallFunctionBuilder extends FunctionBuilder {
       'Generic type variable TMethod must be a contract method. eg. abiCall<typeof YourContract.prototype.yourMethod>',
       sourceLocation,
     )
-    codeInvariant(
-      functionType.declaredIn,
-      `${functionType.name} does not appear to be a contract method. Ensure you are calling a function defined on a contract class eg. abiCall<typeof YourContract.prototype.yourMethod>`,
-      sourceLocation,
-    )
-
-    const contractType = AwstBuildContext.current.getContractTypeByName(functionType.declaredIn)
-    invariant(contractType, `${functionType.declaredIn} has not been visited`)
-
-    const arc4Config = AwstBuildContext.current.getArc4Config(contractType, functionType.name)
-    codeInvariant(
-      arc4Config instanceof ARC4ABIMethodConfig,
-      `${functionType.name} is not an ABI method. Only ABI compatible methods can be called with this helper.`,
-      sourceLocation,
-    )
-    const methodSelector = buildArc4MethodConstant(functionType, arc4Config, sourceLocation)
+    const { methodSelector, arc4Config } = arc4ConfigFromType(functionType, sourceLocation)
 
     const itxnResult = makeApplicationCall({
       fields: options,

src/awst_build/eb/arc4/util.ts

@@ -8,9 +8,9 @@ import { Constants } from '../../../constants'
 import { CodeError } from '../../../errors'
 import { logger } from '../../../logger'
 import { codeInvariant, hexToUint8Array } from '../../../util'
-import { isArc4EncodableType, ptypeToArc4EncodedType } from '../../arc4-util'
+import { arc4ConfigFromType, isArc4EncodableType, ptypeToArc4EncodedType } from '../../arc4-util'
 import type { PType } from '../../ptypes'
-import { BytesPType, bytesPType, stringPType, uint64PType } from '../../ptypes'
+import { BytesPType, bytesPType, FunctionPType, stringPType, uint64PType } from '../../ptypes'
 import {
   ARC4EncodedType,
   convertBytesFunction,
@@ -202,39 +202,52 @@ export class MethodSelectorFunctionBuilder extends FunctionBuilder {
   readonly ptype = methodSelectorFunction
 
   call(args: ReadonlyArray<NodeBuilder>, typeArgs: ReadonlyArray<PType>, sourceLocation: SourceLocation<ts.CallExpression>): NodeBuilder {
-    const {
-      args: [methodSignature],
-    } = parseFunctionArgs({
-      args,
-      typeArgs,
-      genericTypeArgs: 0,
-      callLocation: sourceLocation,
-      funcName: this.typeDescription,
-      argSpec: (a) => [a.passthrough()],
-    })
     const methodConstantType = new BytesPType({ length: 4n })
-    if (methodSignature instanceof SubroutineExpressionBuilder) {
+
+    if (typeArgs.length === 1 && args.length === 0) {
+      const [functionType] = typeArgs
       codeInvariant(
-        methodSignature instanceof ContractMethodExpressionBuilder,
-        `Expected contract instance method, found ${methodSignature.typeDescription}`,
-        methodSignature.sourceLocation,
+        functionType instanceof FunctionPType,
+        'Generic type variable TMethod must be a contract method. eg. abiCall<typeof YourContract.prototype.yourMethod>',
+        sourceLocation,
       )
-      return instanceEb(methodSignature.getMethodSelector(sourceLocation), methodConstantType)
+      const { methodSelector } = arc4ConfigFromType(functionType, sourceLocation)
+      return instanceEb(methodSelector, methodConstantType)
     } else {
-      if (methodSignature === undefined) {
-        throw new CodeError(
-          `${this.typeDescription} expects exactly 1 argument that is either a string literal, or a contract function reference`,
-          { sourceLocation },
+      const {
+        args: [methodSignature],
+      } = parseFunctionArgs({
+        args,
+        typeArgs,
+        genericTypeArgs: 0,
+        callLocation: sourceLocation,
+        funcName: this.typeDescription,
+        argSpec: (a) => [a.passthrough()],
+      })
+
+      if (methodSignature instanceof SubroutineExpressionBuilder) {
+        codeInvariant(
+          methodSignature instanceof ContractMethodExpressionBuilder,
+          `Expected contract instance method, found ${methodSignature.typeDescription}`,
+          methodSignature.sourceLocation,
+        )
+        return instanceEb(methodSignature.getMethodSelector(sourceLocation), methodConstantType)
+      } else {
+        if (methodSignature === undefined) {
+          throw new CodeError(
+            `${this.typeDescription} expects exactly 1 argument that is either a string literal, or a contract function reference`,
+            { sourceLocation },
+          )
+        }
+        return instanceEb(
+          nodeFactory.methodConstant({
+            value: requireStringConstant(methodSignature).value,
+            wtype: methodConstantType.wtype,
+            sourceLocation,
+          }),
+          methodConstantType,
         )
       }
-      return instanceEb(
-        nodeFactory.methodConstant({
-          value: requireStringConstant(methodSignature).value,
-          wtype: methodConstantType.wtype,
-          sourceLocation,
-        }),
-        methodConstantType,
-      )
     }
   }
 }