Merge main into release

Author: github-actions[bot]

docs/capabilities/algorand-client.md

@@ -54,7 +54,7 @@ The `AlgorandClient` has a number of manager class instances that help you quick
 
 ### Creating transactions
 
-You can compose a transaction via `algorand.createTransaction...`, which gives you an instance of the [`AlgorandClientTransactionCreator`](../code/classes/types_algorand_client_transaction_creator.AlgorandClientTransactionCreator.md) class. Intellisense will guide you on the different options.
+You can compose a transaction via `algorand.createTransaction.`, which gives you an instance of the [`AlgorandClientTransactionCreator`](../code/classes/types_algorand_client_transaction_creator.AlgorandClientTransactionCreator.md) class. Intellisense will guide you on the different options.
 
 The signature for the calls to send a single transaction usually look like:
 
@@ -147,8 +147,10 @@ There are two common base interfaces that get reused:
 - [`SendParams`](../code/interfaces/types_transaction.SendParams.md)
   - `maxRoundsToWaitForConfirmation?: number` - The number of rounds to wait for confirmation. By default until the latest lastValid has past.
   - `suppressLog?: boolean` - Whether to suppress log messages from transaction send, default: do not suppress.
+  - `populateAppCallResources?: boolean` - Whether to use simulate to automatically populate app call resources in the txn objects. Defaults to `Config.populateAppCallResources`.
+  - `coverAppCallInnerTransactionFees?: boolean` - Whether to use simulate to automatically calculate required app call inner transaction fees and cover them in the parent app call transaction fee
 
-Then on top of that the base type gets extended for the specific type of transaction you are issuing. These are all defined as part of [`TransactionComposer`](./transaction-composer.md).
+Then on top of that the base type gets extended for the specific type of transaction you are issuing. These are all defined as part of [`TransactionComposer`](./transaction-composer.md) and we recommend reading these docs, especially when leveraging either `populateAppCallResources` or `coverAppCallInnerTransactionFees`.
 
 ### Transaction configuration
 

docs/capabilities/app-client.md

@@ -258,8 +258,8 @@ The ARC4 ABI specification supports ABI method calls as arguments to other ABI m
 
 To illustrate this, let's consider an example of two ABI methods with the following signatures:
 
-- `myMethod(pay, appl): void`
-- `myOtherMethod(pay): void`
+- `myMethod(pay,appl)void`
+- `myOtherMethod(pay)void`
 
 These signatures are compatible, so `myOtherMethod` can be passed as an ABI method call argument to `myMethod`, which would look like:
 

docs/capabilities/testing.md

@@ -24,15 +24,37 @@ import { algorandFixture } from '@algorandfoundation/algokit-utils/testing'
 
 ### Using with Jest
 
-To integrate with [Jest](https://jestjs.io/) you need to pass the `fixture.beforeEach` method into Jest's `beforeEach` method and then within each test you can access `fixture.context` to access per-test isolated fixture values.
+To integrate with [Jest](https://jestjs.io/) you need to pass the `fixture.newScope` method into Jest's `beforeEach` method (for per test isolation) or `beforeAll` method (for test suite isolation) and then within each test you can access `fixture.context` to access the isolated fixture values.
+
+#### Per-test isolation
 
 ```typescript
 import { describe, test, beforeEach } from '@jest/globals'
 import { algorandFixture } from './testing'
 
 describe('MY MODULE', () => {
   const fixture = algorandFixture()
-  beforeEach(fixture.beforeEach, 10_000)
+  beforeEach(fixture.newScope, 10_000) // Add a 10s timeout to cater for occasionally slow LocalNet calls
+
+  test('MY TEST', async () => {
+    const { algorand, testAccount /* ... */ } = fixture.context
+
+    // Test stuff!
+  })
+})
+```
+
+Occasionally there may be a delay when first running the fixture setup so we add a 10s timeout to avoid intermittent test failures (`10_000`).
+
+#### Test suite isolation
+
+```typescript
+import { describe, test, beforeAll } from '@jest/globals'
+import { algorandFixture } from './testing'
+
+describe('MY MODULE', () => {
+  const fixture = algorandFixture()
+  beforeAll(fixture.newScope, 10_000) // Add a 10s timeout to cater for occasionally slow LocalNet calls
 
   test('MY TEST', async () => {
     const { algorand, testAccount /* ... */ } = fixture.context
@@ -46,15 +68,37 @@ Occasionally there may be a delay when first running the fixture setup so we add
 
 ### Using with vitest
 
-To integrate with [vitest](https://vitest.dev/) you need to pass the `fixture.beforeEach` method into vitest's `beforeEach` method and then within each test you can access `fixture.context` to access per-test isolated fixture values.
+To integrate with [vitest](https://vitest.dev/) you need to pass the `fixture.beforeEach` method into vitest's `beforeEach` method (for per test isolation) or `beforeAll` method (for test suite isolation) and then within each test you can access `fixture.context` to access the isolated fixture values.
+
+#### Per-test isolation
 
 ```typescript
 import { describe, test, beforeEach } from 'vitest'
 import { algorandFixture } from './testing'
 
 describe('MY MODULE', () => {
   const fixture = algorandFixture()
-  beforeEach(fixture.beforeEach, 10_000)
+  beforeEach(fixture.newScope, 10_000) // Add a 10s timeout to cater for occasionally slow LocalNet calls
+
+  test('MY TEST', async () => {
+    const { algorand, testAccount /* ... */ } = fixture.context
+
+    // Test stuff!
+  })
+})
+```
+
+Occasionally there may be a delay when first running the fixture setup so we add a 10s timeout to avoid intermittent test failures (`10_000`).
+
+#### Test suite isolation
+
+```typescript
+import { describe, test, beforeAll } from 'vitest'
+import { algorandFixture } from './testing'
+
+describe('MY MODULE', () => {
+  const fixture = algorandFixture()
+  beforeAll(fixture.newScope, 10_000) // Add a 10s timeout to cater for occasionally slow LocalNet calls
 
   test('MY TEST', async () => {
     const { algorand, testAccount /* ... */ } = fixture.context
@@ -64,6 +108,8 @@ describe('MY MODULE', () => {
 })
 ```
 
+Occasionally there may be a delay when first running the fixture setup so we add a 10s timeout to avoid intermittent test failures (`10_000`).
+
 ### Fixture configuration
 
 When calling `algorandFixture()` you can optionally pass in some fixture configuration, with any of these properties (all optional):
@@ -72,6 +118,7 @@ When calling `algorandFixture()` you can optionally pass in some fixture configu
 - `indexer?: Indexer` - An optional indexer client, if not specified then it will create one against environment variables defined network (if present) or default LocalNet
 - `kmd?: Kmd` - An optional kmd client, if not specified then it will create one against environment variables defined network (if present) or default LocalNet
 - `testAccountFunding?: AlgoAmount` - The [amount](./amount.md) of funds to allocate to the default testing account, if not specified then it will get `10` ALGO
+- `accountGetter?: (algod: Algodv2, kmd?: Kmd) => Promise<Account>` - Optional override for how to get an account; this allows you to retrieve test accounts from a known or cached list of accounts.
 
 ### Using the fixture context
 
@@ -84,7 +131,7 @@ The `fixture.context` property is of type [`AlgorandTestAutomationContext`](../c
 - `transactionLogger: TransactionLogger` - Transaction logger that will log transaction IDs for all transactions issued by `algod`
 - `testAccount: Account` - Funded test account that is ephemerally created for each test
 - `generateAccount: (params: GetTestAccountParams) => Promise<Account>` - Generate and fund an additional ephemerally created account
-- `waitForIndexer: () => Promise<void>` - Wait for the indexer to catch up with all transactions logged by transactionLogger
+- `waitForIndexer()` - Waits for indexer to catch up with the latest transaction that has been captured by the `transactionLogger` in the Algorand fixture
 - `waitForIndexerTransaction: (transactionId: string) => Promise<TransactionLookupResult>` - Wait for the indexer to catch up with the given transaction ID
 
 ## Log capture fixture
@@ -170,7 +217,7 @@ This means it's easy to create tests that are flaky and have intermittent test f
 The testing capability provides mechanisms for waiting for indexer to catch up, namely:
 
 - `algotesting.runWhenIndexerCaughtUp(run: () => Promise<T>)` - Executes the given action every 200ms up to 20 times until there is no longer an error with a `status` property with `404` and then returns the result of the action; this will work for any call that calls indexer APIs expecting to return a single record
-- `algorandFixture.waitForIndexer()` - Waits for indexer to catch up with all transactions that have been captured by the `transactionLogger` in the Algorand fixture
+- `algorandFixture.waitForIndexer()` - Waits for indexer to catch up with the latest transaction that has been captured by the `transactionLogger` in the Algorand fixture
 - `algorandFixture.waitForIndexerTransaction(transactionId)` - Waits for indexer to catch up with the single transaction of the given ID
 
 ## Logging transactions

docs/capabilities/transaction-composer.md

@@ -8,7 +8,7 @@ To get an instance of `TransactionComposer` you can either get it from an [app c
 
 ```typescript
 const composerFromAlgorand = algorand.newGroup()
-const composerFromAppClient = appClient.newGroup()
+const composerFromAppClient = appClient.algorand.newGroup()
 const composerFromConstructor = new TransactionComposer({
   algod,
   /* Return the algosdk.TransactionSigner for this address*/
@@ -33,17 +33,152 @@ The [methods to construct a transaction](../code/classes/types_composer.default.
 For example:
 
 ```typescript
+const myMethod = algosdk.ABIMethod.fromSignature('my_method()void')
 const result = algorand
   .newGroup()
   .addPayment({ sender: 'SENDER', receiver: 'RECEIVER', amount: (100).microAlgo() })
   .addAppCallMethodCall({
     sender: 'SENDER',
     appId: 123n,
-    method: abiMethod,
+    method: myMethod,
     args: [1, 2, 3],
   })
 ```
 
+## Sending a transaction
+
+Once you have constructed all the required transactions, they can be sent by calling `send()` on the `TransactionComposer`.
+Additionally `send()` takes a number of parameters which allow you to opt-in to some additional behaviours as part of sending the transaction or transaction group, mostly significantly `populateAppCallResources` and `coverAppCallInnerTransactionFees`.
+
+### Populating App Call Resource
+
+`populateAppCallResources` automatically updates the relevant app call transactions in the group to include the account, app, asset and box resources required for the transactions to execute successfully. It leverages the simulate endpoint to discover the accessed resources, which have not been explicitly specified. This setting only applies when you have constucted at least one app call transaction. You can read more about [resources and the reference arrays](https://developer.algorand.org/docs/get-details/dapps/smart-contracts/apps/?from_query=resources#reference-arrays) in the docs.
+
+For example:
+
+```typescript
+const myMethod = algosdk.ABIMethod.fromSignature('my_method()void')
+const result = algorand
+  .newGroup()
+  .addAppCallMethodCall({
+    sender: 'SENDER',
+    appId: 123n,
+    method: myMethod,
+    args: [1, 2, 3],
+  })
+  .send({
+    populateAppCallResources: true,
+  })
+```
+
+If `my_method` in the above example accesses any resources, they will be automatically discovered and added before sending the transaction to the network.
+
+### Covering App Call Inner Transaction Fees
+
+`coverAppCallInnerTransactionFees` automatically calculate the required fee for a parent app call transaction that sends inner transactions. It leverages the simulate endpoint to discover the inner transactions sent and calculates a fee delta to resolve the optimal fee. This feature also takes care of accounting for any surplus transaction fee at the various levels, so as to effectively minimise the fees needed to successfully handle complex scenarios. This setting only applies when you have constucted at least one app call transaction.
+
+For example:
+
+```typescript
+const myMethod = algosdk.ABIMethod.fromSignature('my_method()void')
+const result = algorand
+  .newGroup()
+  .addAppCallMethodCall({
+    sender: 'SENDER',
+    appId: 123n,
+    method: myMethod,
+    args: [1, 2, 3],
+    maxFee: microAlgo(5000), // NOTE: a maxFee value is required when enabling coverAppCallInnerTransactionFees
+  })
+  .send({
+    coverAppCallInnerTransactionFees: true,
+  })
+```
+
+Assuming the app account is not covering any of the inner transaction fees, if `my_method` in the above example sends 2 inner transactions, then the fee calculated for the parent transaction will be 3000 µALGO when the transaction is sent to the network.
+
+The above example also has a `maxFee` of 5000 µALGO specified. An exception will be thrown if the transaction fee execeeds that value, which allows you to set fee limits. The `maxFee` field is required when enabling `coverAppCallInnerTransactionFees`.
+
+Because `maxFee` is required and an `algosdk.Transaction` does not hold any max fee information, you cannot use the generic `addTransaction()` method on the composer with `coverAppCallInnerTransactionFees` enabled. Instead use the below, which provides a better overall experience:
+
+```typescript
+const myMethod = algosdk.ABIMethod.fromSignature('my_method()void')
+
+// Does not work
+const result = algorand
+  .newGroup()
+  .addTransaction((await localnet.algorand.createTransaction.appCallMethodCall({
+    sender: 'SENDER',
+    appId: 123n,
+    method: myMethod,
+    args: [1, 2, 3],
+    maxFee: microAlgo(5000), // This is only used to create the algosdk.Transaction object and isn't made available to the composer.
+  })).transactions[0]),
+  .send({
+    coverAppCallInnerTransactionFees: true,
+  })
+
+// Works as expected
+const result = algorand
+  .newGroup()
+  .addAppCallMethodCall({
+    sender: 'SENDER',
+    appId: 123n,
+    method: myMethod,
+    args: [1, 2, 3],
+    maxFee: microAlgo(5000),
+  })
+  .send({
+    coverAppCallInnerTransactionFees: true,
+  })
+```
+
+A more complex valid scenario which leverages an app client to send an ABI method call with ABI method call transactions argument is below:
+
+```typescript
+const appFactory = algorand.client.getAppFactory({
+  appSpec: 'APP_SPEC',
+  defaultSender: sender.addr,
+})
+
+const { appClient: appClient1 } = await appFactory.send.bare.create()
+const { appClient: appClient2 } = await appFactory.send.bare.create()
+
+const paymentArg = algorand.createTransaction.payment({
+  sender: sender.addr,
+  receiver: receiver.addr,
+  amount: microAlgo(1),
+})
+
+// Note the use of .params. here, this ensure that maxFee is still available to the composer
+const appCallArg = await appClient2.params.call({
+  method: 'my_other_method',
+  args: [],
+  maxFee: microAlgo(2000),
+})
+
+const result = await appClient1.algorand
+  .newGroup()
+  .addAppCallMethodCall(
+    await appClient1.params.call({
+      method: 'my_method',
+      args: [paymentArg, appCallArg],
+      maxFee: microAlgo(5000),
+    }),
+  )
+  .send({
+    coverAppCallInnerTransactionFees: true,
+  })
+```
+
+This feature should efficiently calculate the minimum fee needed to execute an app call transaction with inners, however we always recommend testing your specific scenario behaves as expected before releasing.
+
+### Covering App Call Op Budget
+
+The high level Algorand contract authoring languages all have support for ensuring appropriate app op budget is available via `ensure_budget` in Algorand Python, `ensureBudget` in Algorand TypeScript and `increaseOpcodeBudget` in TEALScript. This is great, as it allows contract authors to ensure appropriate budget is available by automatically sending op-up inner transactions to increase the budget available. These op-up inner transactions require the fees to be covered by an account, which is generally the responsibility of the application consumer.
+
+Application consumers may not be immediately aware of the number of op-up inner transactions sent, so it can be difficult for them to determine the exact fees required to successfully execute an application call. Fortunately the `coverAppCallInnerTransactionFees` setting above can be leveraged to automatically cover the fees for any op-up inner transaction that an application sends. Additionally if a contract author decides to cover the fee for an op-up inner transaction, then the application consumer will not be charged a fee for that transaction.
+
 ## Simulating a transaction
 
 Transactions can be simulated using the simulate endpoint in algod, which enables evaluating the transaction on the network without it actually being commited to a block.

docs/capabilities/transaction.md

@@ -20,4 +20,4 @@ There are various variations of the `ConfirmedTransactionResult` that are expose
 
 ## Further reading
 
-To understand how to create, simulate and send transactions consult the [`AlgorandClient`](./algorand-client.md) and [`AlgorandClient`](./algokit-composer.md) documentation.
+To understand how to create, simulate and send transactions consult the [`AlgorandClient`](./algorand-client.md) and [`TransactionComposer`](./transaction-composer.md) documentation.

docs/capabilities/typed-app-clients.md

@@ -21,7 +21,7 @@ To generate a typed client from an app spec file you can use [AlgoKit CLI](https
 > algokit generate client application.json --output /absolute/path/to/client.ts
 ```
 
-Note: If you are using a version of AlgoKit Utils >= 7.0.0 in your project, you will need to generate using >= 4.0.0. See [AlgoKit CLI generator version pinning](https://github.com/algorandfoundation/algokit-cli/blob/main/docs/features/generate.md#version-pinning) for more information on how to lock to a specific version.
+Note: AlgoKit Utils >= 7.0.0 is compatible with the older 3.0.0 generated typed clients, however if you want to utilise the new features or leverage ARC-56 support, you will need to generate using >= 4.0.0. See [AlgoKit CLI generator version pinning](https://github.com/algorandfoundation/algokit-cli/blob/main/docs/features/generate.md#version-pinning) for more information on how to lock to a specific version.
 
 ## Getting a typed client instance
 
@@ -193,7 +193,7 @@ const factory = algorand.client.getTypedAppFactory(HelloWorldAppFactory, {
 // Create the app and get a typed app client for the created app (note: this creates a new instance of the app every time,
 //  you can use .deploy() to deploy idempotently if the app wasn't previously
 //  deployed or needs to be updated if that's allowed)
-const { appClient } = await factory.create()
+const { appClient } = await factory.send.create()
 
 // Make a call to an ABI method and print the result
 const response = await appClient.hello({ name: 'world' })

docs/code/README.md

@@ -43,6 +43,7 @@
 - [types/dispenser-client.spec](modules/types_dispenser_client_spec.md)
 - [types/expand](modules/types_expand.md)
 - [types/indexer](modules/types_indexer.md)
+- [types/interface-of](modules/types_interface_of.md)
 - [types/kmd-account-manager](modules/types_kmd_account_manager.md)
 - [types/lifecycle-events](modules/types_lifecycle_events.md)
 - [types/logging](modules/types_logging.md)