Merge main into release

Author: github-actions[bot]

docs/capabilities/app-deploy.md

@@ -245,8 +245,6 @@ In order for a smart contract to opt-in to use this functionality, it must have
 - `TMPL_UPDATABLE` - Which will be replaced with a `1` if an app should be updatable and `0` if it shouldn't (immutable)
 - `TMPL_DELETABLE` - Which will be replaced with a `1` if an app should be deletable and `0` if it shouldn't (permanent)
 
-If you are building a smart contract using the production [AlgoKit init templates](https://github.com/algorandfoundation/algokit-cli/blob/main/docs/features/init.md) provide a reference implementation out of the box for the deploy-time immutability and permanence control.
-
 If you passed in a TEAL template for the approvalProgram or clearStateProgram (i.e. a `string` rather than a `Uint8Array`) then `deploy` will return the [compilation result](../code/interfaces/types_app.CompiledTeal.md) of substituting then compiling the TEAL template(s) in the following properties of the return value:
 
 - `compiledApproval?: CompiledTeal`
@@ -259,6 +257,48 @@ Template substitution is done by executing `algorand.app.compileTealTemplate(tea
 - `AppManager.replaceTealTemplateDeployTimeControlParams(tealTemplateCode, deploymentMetadata)` - If `deploymentMetadata` is provided, it allows for deploy-time immutability and permanence control by replacing `TMPL_UPDATABLE` with `deploymentMetadata.updatable` if it's not `undefined` and replacing `TMPL_DELETABLE` with `deploymentMetadata.deletable` if it's not `undefined`
 - `algorand.app.compileTeal(tealCode)` - Sends the final TEAL to algod for compilation and returns the result including the source map and caches the compilation result within the `AppManager` instance
 
+#### Making updatable/deletable apps
+
+Below is a sample in [Algorand Python SDK](https://github.com/algorandfoundation/puya) that demonstrates how to make an app updatable/deletable smart contract with the use of `TMPL_UPDATABLE` and `TMPL_DELETABLE` template parameters.
+
+```python
+# ... your contract code ...
+@arc4.baremethod(allow_actions=["UpdateApplication"])
+def update(self) -> None:
+    assert TemplateVar[bool]("UPDATABLE")
+
+@arc4.baremethod(allow_actions=["DeleteApplication"])
+def delete(self) -> None:
+    assert TemplateVar[bool]("DELETABLE")
+# ... your contract code ...
+```
+
+Alternative example in [Algorand TypeScript SDK](https://github.com/algorandfoundation/puya-ts):
+
+```typescript
+// ... your contract code ...
+@baremethod({ allowActions: 'UpdateApplication' })
+public onUpdate() {
+    assert(TemplateVar<boolean>('UPDATABLE'))
+}
+
+@baremethod({ allowActions: 'DeleteApplication' })
+public onDelete() {
+    assert(TemplateVar<boolean>('DELETABLE'))
+}
+// ... your contract code ...
+```
+
+With the above code, when deploying your application, you can pass in the following deploy-time parameters:
+
+```typescript
+myFactory.deploy({
+  ... // other deployment parameters
+  updatable: true, // resulting app will be updatable, and this metadata will be set in the ARC-2 transaction note
+  deletable: false, // resulting app will not be deletable, and this metadata will be set in the ARC-2 transaction note
+})
+```
+
 ### Return value
 
 When `deploy` executes it will return a [comprehensive result](../code/modules/types_app_deployer.md#appdeployresult) object that describes exactly what it did and has comprehensive metadata to describe the end result of the deployed app.

docs/code/modules/index.md

@@ -575,7 +575,7 @@ the estimated rate.
 
 #### Defined in
 
-[src/transaction/transaction.ts:1056](https://github.com/algorandfoundation/algokit-utils-ts/blob/main/src/transaction/transaction.ts#L1056)
+[src/transaction/transaction.ts:1058](https://github.com/algorandfoundation/algokit-utils-ts/blob/main/src/transaction/transaction.ts#L1058)
 
 ___
 
@@ -639,7 +639,7 @@ Allows for control of fees on a `Transaction` or `SuggestedParams` object
 
 #### Defined in
 
-[src/transaction/transaction.ts:1083](https://github.com/algorandfoundation/algokit-utils-ts/blob/main/src/transaction/transaction.ts#L1083)
+[src/transaction/transaction.ts:1085](https://github.com/algorandfoundation/algokit-utils-ts/blob/main/src/transaction/transaction.ts#L1085)
 
 ___
 
@@ -966,7 +966,7 @@ Converts `bigint`'s for Uint's < 64 to `number` for easier use.
 
 #### Defined in
 
-[src/transaction/transaction.ts:926](https://github.com/algorandfoundation/algokit-utils-ts/blob/main/src/transaction/transaction.ts#L926)
+[src/transaction/transaction.ts:928](https://github.com/algorandfoundation/algokit-utils-ts/blob/main/src/transaction/transaction.ts#L928)
 
 ___
 
@@ -1942,7 +1942,7 @@ Returns the array of transactions currently present in the given `AtomicTransact
 
 #### Defined in
 
-[src/transaction/transaction.ts:1132](https://github.com/algorandfoundation/algokit-utils-ts/blob/main/src/transaction/transaction.ts#L1132)
+[src/transaction/transaction.ts:1134](https://github.com/algorandfoundation/algokit-utils-ts/blob/main/src/transaction/transaction.ts#L1134)
 
 ___
 
@@ -2329,7 +2329,7 @@ Returns suggested transaction parameters from algod unless some are already prov
 
 #### Defined in
 
-[src/transaction/transaction.ts:1110](https://github.com/algorandfoundation/algokit-utils-ts/blob/main/src/transaction/transaction.ts#L1110)
+[src/transaction/transaction.ts:1112](https://github.com/algorandfoundation/algokit-utils-ts/blob/main/src/transaction/transaction.ts#L1112)
 
 ___
 
@@ -2770,7 +2770,8 @@ ___
 ▸ **prepareGroupForSending**(`atc`, `algod`, `sendParams`, `additionalAtcContext?`): `Promise`\<`AtomicTransactionComposer`\>
 
 Take an existing Atomic Transaction Composer and return a new one with changes applied to the transactions
-based on the supplied sendParams to ensure the transaction group is ready for sending.
+based on the supplied sendParams to prepare it for sending.
+Please note, that before calling `.execute()` on the returned ATC, you must call `.buildGroup()`.
 
 #### Parameters
 
@@ -2789,7 +2790,7 @@ A new ATC with the changes applied
 
 #### Defined in
 
-[src/transaction/transaction.ts:401](https://github.com/algorandfoundation/algokit-utils-ts/blob/main/src/transaction/transaction.ts#L401)
+[src/transaction/transaction.ts:402](https://github.com/algorandfoundation/algokit-utils-ts/blob/main/src/transaction/transaction.ts#L402)
 
 ___
 
@@ -2939,7 +2940,7 @@ An object with transaction IDs, transactions, group transaction ID (`groupTransa
 
 #### Defined in
 
-[src/transaction/transaction.ts:776](https://github.com/algorandfoundation/algokit-utils-ts/blob/main/src/transaction/transaction.ts#L776)
+[src/transaction/transaction.ts:777](https://github.com/algorandfoundation/algokit-utils-ts/blob/main/src/transaction/transaction.ts#L777)
 
 ___
 
@@ -2968,7 +2969,7 @@ Signs and sends a group of [up to 16](https://developer.algorand.org/docs/get-de
 
 #### Defined in
 
-[src/transaction/transaction.ts:955](https://github.com/algorandfoundation/algokit-utils-ts/blob/main/src/transaction/transaction.ts#L955)
+[src/transaction/transaction.ts:957](https://github.com/algorandfoundation/algokit-utils-ts/blob/main/src/transaction/transaction.ts#L957)
 
 ___
 
@@ -3241,4 +3242,4 @@ Throws an error if the transaction is not confirmed or rejected in the next `tim
 
 #### Defined in
 
-[src/transaction/transaction.ts:999](https://github.com/algorandfoundation/algokit-utils-ts/blob/main/src/transaction/transaction.ts#L999)
+[src/transaction/transaction.ts:1001](https://github.com/algorandfoundation/algokit-utils-ts/blob/main/src/transaction/transaction.ts#L1001)

src/transaction/transaction.spec.ts

@@ -460,6 +460,13 @@ describe('transaction', () => {
       expect(result.transactions[0].fee).toBe(1500n)
       expect(result.transactions[1].fee).toBe(7500n)
       expect(result.transactions[2].fee).toBe(0n)
+      expect(result.groupId).not.toBe('')
+      await Promise.all(
+        result.transactions.map(async (txn) => {
+          expect(Buffer.from(txn.group!).toString('base64')).toBe(result.groupId)
+          await localnet.context.waitForIndexerTransaction(txn.txID())
+        }),
+      )
     })
 
     test('alters fee, handling nested abi method calls', async () => {

src/transaction/transaction.ts

@@ -386,7 +386,8 @@ export async function populateAppCallResources(atc: algosdk.AtomicTransactionCom
 
 /**
  * Take an existing Atomic Transaction Composer and return a new one with changes applied to the transactions
- * based on the supplied sendParams to ensure the transaction group is ready for sending.
+ * based on the supplied sendParams to prepare it for sending.
+ * Please note, that before calling `.execute()` on the returned ATC, you must call `.buildGroup()`.
  *
  * @param algod The algod client to use for the simulation
  * @param atc The ATC containing the txn group
@@ -799,7 +800,8 @@ export const sendAtomicTransactionComposer = async function (atcSend: AtomicTran
       )
     }
 
-    const transactionsToSend = transactionsWithSigner.map((t) => {
+    // atc.buildGroup() is needed to ensure that any changes made by prepareGroupForSending are reflected and the group id is set
+    const transactionsToSend = atc.buildGroup().map((t) => {
       return t.txn
     })
     let groupId: string | undefined = undefined