Merge pull request #157 from algorandfoundation/advanced-avm-features

Advanced AVM features

docs/capabilities/account.md

@@ -38,3 +38,31 @@ In order to get the accounts you can use the underlying algosdk methods where re
 ### Dispenser
 
 - [`algokit.getDispenserAccount(algod, kmd?)`](../code/modules/index.md#getdispenseraccount) - Returns an account that can act as a dispenser to fund other accounts either via Kmd (when targeting LocalNet) or by convention from environment variable via `process.env.DISPENSER_MNEMONIC` (and optionally `process.env.DISPENSER_SENDER` if rekeyed)
+
+## Rekey account
+
+One of the unique features of Algorand is the ability to change the private key that can authorise transactions for an account. This is called [rekeying](https://developer.algorand.org/docs/get-details/accounts/rekey/).
+
+You can issue a transaction to rekey an account by using the `algokit.rekeyAccount(rekey, algod)` function. The `rekey` parameter is an [`AlgoRekeyParams`](../code/interfaces/types_transfer.AlgoRekeyParams.md) object with the following properties:
+
+- All properties in [`SendTransactionParams`](./transaction.md#sendtransactionparams)
+- `from: SendTransactionFrom` - The account that will be rekeyed
+- `rekeyTo: SendTransactionFrom | string` - The address of the account that will be used to authorise transactions for the rekeyed account going forward
+- `transactionParams?: SuggestedParams` - The optional [transaction parameters](./transaction.md#transaction-params)
+- `note?: TransactionNote` - The [transaction note](./transaction.md#transaction-notes)
+- `lease?: string | Uint8Array`: A [lease](https://developer.algorand.org/articles/leased-transactions-securing-advanced-smart-contract-design/) to assign to the transaction to enforce a mutually exclusive transaction (useful to prevent double-posting and other scenarios)
+
+```typescript
+// Example
+await algokit.rekeyAccount(
+  {
+    from: account,
+    rekeyTo: newAccount,
+    // Optionally specify transactionParams, note, lease and transaction sending parameters
+  },
+  algod,
+)
+
+const rekeyedAccount = algokit.rekeyedAccount(newAccount, account.addr)
+// rekeyedAccount can be used to sign transactions on behalf of account...
+```

docs/capabilities/app.md

@@ -18,6 +18,7 @@ This [type](../code/modules/types_app.md#appcallargs) is a union of two types: `
 - `apps: number[]`: The ID of any apps to load to the [foreign apps array](https://developer.algorand.org/docs/get-details/dapps/smart-contracts/apps/#reference-arrays)
 - `assets: number[]`: The ID of any assets to load to the [foreign assets array](https://developer.algorand.org/docs/get-details/dapps/smart-contracts/apps/#reference-arrays)
 - `lease: string | Uint8Array`: A [lease](https://developer.algorand.org/articles/leased-transactions-securing-advanced-smart-contract-design/) to assign to the transaction to enforce a mutually exclusive transaction (useful to prevent double-posting and other scenarios)
+- `rekeyTo: string | SendTransactionFrom`: An account or account address that should be authorised to transact on behalf of the account the app call is sent from after the app transaction is processed; **note:** use with extreme caution and review the [official rekey guidance](https://developer.algorand.org/docs/get-details/accounts/rekey/) first
 
 ### `ABIAppCallArgs`
 
@@ -38,6 +39,7 @@ This [type](../code/modules/types_app.md#appcallargs) is a union of two types: `
   - `Promise<SendTransactionResult>` - which allows you to use an AlgoKit Utils method call that [returns a transaction](transaction.md#sendtransactionresult) without needing to await the call and extract the transaction, if you do this be sure to use `skipWaiting: true` when specifying the [sending parameters](transaction.md#sendtransactionparams) so you get the transaction without sending it to the network
 - `boxes: (BoxReference | BoxIdentifier | algosdk.BoxReference)[]` - Any [boxes](#referencing-boxes) to load to the [boxes array](https://developer.algorand.org/docs/get-details/dapps/smart-contracts/apps/#reference-arrays)
 - `lease: string | Uint8Array`: A [lease](https://developer.algorand.org/articles/leased-transactions-securing-advanced-smart-contract-design/) to assign to the transaction to enforce a mutually exclusive transaction (useful to prevent double-posting and other scenarios)
+- `rekeyTo: string | SendTransactionFrom`: An account or account address that should be authorised to transact on behalf of the account the app call is sent from after the app transaction is processed; **note:** use with extreme caution and review the [official rekey guidance](https://developer.algorand.org/docs/get-details/accounts/rekey/) first
 
 ### Utility methods
 

docs/capabilities/asset.md

@@ -3,14 +3,98 @@
 The asset management functions include opting in and out of assets, which are fundamental to asset interaction in a blockchain environment.
 To see some usage examples check out the [automated tests](../../src/asset.spec.ts).
 
-## `optIn`
+## Transfer
+
+### `transferAsset`
+
+The key function to facilitate asset transfers is `transferAsset(transfer, algod)`, which returns a [`SendTransactionResult`](./transaction.md#sendtransactionresult) and takes a [`TransferAssetParams`](../code/interfaces/types_transfer.TransferAssetParams.md):
+
+- All properties in [`SendTransactionParams`](./transaction.md#sendtransactionparams)
+- `from: SendTransactionFrom` - The account that will send the asset
+- `to: SendTransactionFrom | string` - The account / account address that will receive the asset
+- `assetId: number` - The asset id that will be transfered
+- `amount: number | bigint` - The amount to send in the smallest divisible unit
+- `transactionParams?: SuggestedParams` - The optional [transaction parameters](./transaction.md#transaction-params)
+- `clawbackFrom: SendTransactionFrom | string` - An optional address of a target account from which to perform a clawback operation. Please note, in such cases senderAccount must be equal to clawback field on ASA metadata.
+- `note?: TransactionNote` - The [transaction note](./transaction.md#transaction-notes)
+- `lease?: string | Uint8Array`: A [lease](https://developer.algorand.org/articles/leased-transactions-securing-advanced-smart-contract-design/) to assign to the transaction to enforce a mutually exclusive transaction (useful to prevent double-posting and other scenarios)
+
+## Opt-in/out
 
 Before an account can receive a specific asset, it must `opt-in` to receive it. An opt-in transaction places an asset holding of 0 into the account and increases its minimum balance by [100,000 microAlgos](https://developer.algorand.org/docs/get-details/asa/#assets-overview).
-The `optIn` function facilitates the opt-in process for an account to multiple assets, allowing the account to receive and hold those assets.
 
-## `optOut`
+An account can opt out of an asset at any time. This means that the account will no longer hold the asset, and the account will no longer be able to receive the asset. The account also recovers the Minimum Balance Requirement for the asset (100,000 microAlgos).
+
+When opting-out you generally want to be careful to ensure you have a zero-balance otherwise you will forfeit the balance you do have. By default, AlgoKit Utils protects you from making this mistake by checking you have a zero-balance before issuing the opt-out transaction. You can turn this check off if you want to avoid the extra calls to Algorand and are confident in what you are doing.
+
+AlgoKit Utils gives you functions that allow you to do opt-ins in bulk or as a single operation. The bulk operations give you less control over the sending semantics as they automatically send the transactions to Algorand in the most optimal way using transaction groups.
+
+### `assetOptIn`
+
+To opt-in an account to a single asset you can use the [`algokit.assetOptIn(optIn, algod)`](../code/modules/index.md#assetoptin) function. The `optIn` argument is an object [containing](../code/interfaces/types_asset.AssetOptInParams.md):
+
+- All properties in [`SendTransactionParams`](./transaction.md#sendtransactionparams)
+- `account: SendTransactionFrom` - The account that will opt-in to the asset
+- `assetId: number` - The asset id that will be opted-in to
+- `transactionParams: SuggestedParams` - The optional [transaction parameters](./transaction.md#transaction-params)
+- `note: TransactionNote` - The optional [transaction note](./transaction.md#transaction-notes)
+- `lease: string | Uint8Array`: A [lease](https://developer.algorand.org/articles/leased-transactions-securing-advanced-smart-contract-design/) to assign to the transaction to enforce a mutually exclusive transaction (useful to prevent double-posting and other scenarios)
+
+```typescript
+// Example
+await algokit.assetOptIn({
+  account: account,
+  assetId: 12345,
+  // Can optionally also specify transactionParams, note, lease and other send params
+})
+```
+
+### `assetOptOut`
+
+To opt-out an account from a single asset you can use the [`algokit.assetOptOut(optOut, algod)`](../code/modules/index.md#assetoptout) function. The `optOut` argument is an object [containing](../code/interfaces/types_asset.AssetOptOutParams.md):
+
+- All properties from [`assetOptIn`](#assetoptin)
+- `assetCreatorAddress: string` - The address of the creator account for the asset; if unspecified then it looks it up using algod
+- `ensureZeroBalance: boolean` - Whether or not to validate the account has a zero-balance before issuing the opt-out; defaults to true
+
+```typescript
+// Example
+await algokit.assetOptOut({
+  account: account,
+  assetId: 12345,
+  assetCreatorAddress: creator,
+  // Can optionally also specify ensureZeroBalance, transactionParams, note, lease and other send params
+})
+```
+
+### `assetBulkOptIn`
+
+The [`assetBulkOptIn`](../code/modules/index.md#assetbulkoptin) function facilitates the opt-in process for an account to multiple assets, allowing the account to receive and hold those assets.
+
+```typescript
+// Example
+await algokit.assetBulkOptIn(
+  {
+    account: account,
+    assetIds: [12354, 673453],
+    // Can optionally also specify validateBalances, transactionParams, note
+  },
+  algod,
+)
+```
+
+### `assetBulkOptOut`
 
-An account can opt out of an asset at any time. This means that the account will no longer hold the asset, and the account will no longer be able to receive the asset. The account also recovers the Minimum Balance Requirement for the asset (100,000 microAlgos)
-The `optOut` function manages the opt-out process, permitting the account to discontinue holding a group of assets.
+The `assetBulkOptOut` function manages the opt-out process for a number of assets, permitting the account to discontinue holding a group of assets.
 
-> **Note**:It's essential to note that an account can only opt-out of an asset if its balance of that asset is zero.
+```typescript
+// Example
+await algokit.assetBulkOptOut(
+  {
+    account: account,
+    assetIds: [12354, 673453],
+    // Can optionally also specify validateBalances, transactionParams, note
+  },
+  algod,
+)
+```

docs/capabilities/transfer.md

@@ -14,6 +14,7 @@ The key function to facilitate Algo transfers is `algokit.transferAlgos(transfer
 - `amount: AlgoAmount` - The [amount](./amount.md) of ALGOs to send
 - `transactionParams?: SuggestedParams` - The optional [transaction parameters](./transaction.md#transaction-params)
 - `note?: TransactionNote` - The [transaction note](./transaction.md#transaction-notes)
+- `lease?: string | Uint8Array`: A [lease](https://developer.algorand.org/articles/leased-transactions-securing-advanced-smart-contract-design/) to assign to the transaction to enforce a mutually exclusive transaction (useful to prevent double-posting and other scenarios)
 
 ## `ensureFunded`
 
@@ -26,6 +27,7 @@ The `ensureFunded` function automatically funds an account to maintain a minimum
 - `minFundingIncrement?: AlgoAmount` - When issuing a funding amount, the minimum amount to transfer. This avoids many small transfers if this function gets called often on an active account
 - `transactionParams?: SuggestedParams` - The optional [transaction parameters](./transaction.md#transaction-params)
 - `note?: TransactionNote` - The [transaction note](./transaction.md#transaction-notes)
+- `lease?: string | Uint8Array`: A [lease](https://developer.algorand.org/articles/leased-transactions-securing-advanced-smart-contract-design/) to assign to the transaction to enforce a mutually exclusive transaction (useful to prevent double-posting and other scenarios)
 
 The function calls Algod to find the current balance and minimum balance requirement, calculates the difference between those two numbers, and checks to see if it's more than the `minSpendingBalance`. If so, it will send the difference, or the `minFundingIncrement` if that is specified. If the `fundingSource` is an instance of `TestNetDispenserApiClient`, the function will use the dispenser API to fund the account. Refer to [algokit-cli documentation](https://github.com/algorandfoundation/algokit-cli/blob/main/docs/features/dispenser.md#ci-access-token) for details on obtaining an access token for AlgoKit TestNet Dispenser API.
 
@@ -41,6 +43,7 @@ The key function to facilitate asset transfers is `transferAsset(transfer, algod
 - `transactionParams?: SuggestedParams` - The optional [transaction parameters](./transaction.md#transaction-params)
 - `clawbackFrom: SendTransactionFrom | string` - An optional address of a target account from which to perform a clawback operation. Please note, in such cases senderAccount must be equal to clawback field on ASA metadata.
 - `note?: TransactionNote` - The [transaction note](./transaction.md#transaction-notes)
+- `lease?: string | Uint8Array`: A [lease](https://developer.algorand.org/articles/leased-transactions-securing-advanced-smart-contract-design/) to assign to the transaction to enforce a mutually exclusive transaction (useful to prevent double-posting and other scenarios)
 
 ## Dispenser
 

docs/code/README.md

@@ -16,6 +16,7 @@
 - [types/app-client](modules/types_app_client.md)
 - [types/app-client.spec](modules/types_app_client_spec.md)
 - [types/app-spec](modules/types_app_spec.md)
+- [types/asset](modules/types_asset.md)
 - [types/config](modules/types_config.md)
 - [types/dispenser-client](modules/types_dispenser_client.md)
 - [types/dispenser-client.spec](modules/types_dispenser_client_spec.md)

docs/code/enums/types_app.OnSchemaBreak.md

@@ -24,7 +24,7 @@ Create a new app
 
 #### Defined in
 
-[src/types/app.ts:283](https://github.com/algorandfoundation/algokit-utils-ts/blob/main/src/types/app.ts#L283)
+[src/types/app.ts:288](https://github.com/algorandfoundation/algokit-utils-ts/blob/main/src/types/app.ts#L288)
 
 ___
 
@@ -36,7 +36,7 @@ Fail the deployment
 
 #### Defined in
 
-[src/types/app.ts:279](https://github.com/algorandfoundation/algokit-utils-ts/blob/main/src/types/app.ts#L279)
+[src/types/app.ts:284](https://github.com/algorandfoundation/algokit-utils-ts/blob/main/src/types/app.ts#L284)
 
 ___
 
@@ -48,4 +48,4 @@ Delete the app and create a new one in its place
 
 #### Defined in
 
-[src/types/app.ts:281](https://github.com/algorandfoundation/algokit-utils-ts/blob/main/src/types/app.ts#L281)
+[src/types/app.ts:286](https://github.com/algorandfoundation/algokit-utils-ts/blob/main/src/types/app.ts#L286)

docs/code/enums/types_app.OnUpdate.md

@@ -25,7 +25,7 @@ Create a new app
 
 #### Defined in
 
-[src/types/app.ts:273](https://github.com/algorandfoundation/algokit-utils-ts/blob/main/src/types/app.ts#L273)
+[src/types/app.ts:278](https://github.com/algorandfoundation/algokit-utils-ts/blob/main/src/types/app.ts#L278)
 
 ___
 
@@ -37,7 +37,7 @@ Fail the deployment
 
 #### Defined in
 
-[src/types/app.ts:267](https://github.com/algorandfoundation/algokit-utils-ts/blob/main/src/types/app.ts#L267)
+[src/types/app.ts:272](https://github.com/algorandfoundation/algokit-utils-ts/blob/main/src/types/app.ts#L272)
 
 ___
 
@@ -49,7 +49,7 @@ Delete the app and create a new one in its place
 
 #### Defined in
 
-[src/types/app.ts:271](https://github.com/algorandfoundation/algokit-utils-ts/blob/main/src/types/app.ts#L271)
+[src/types/app.ts:276](https://github.com/algorandfoundation/algokit-utils-ts/blob/main/src/types/app.ts#L276)
 
 ___
 
@@ -61,4 +61,4 @@ Update the app
 
 #### Defined in
 
-[src/types/app.ts:269](https://github.com/algorandfoundation/algokit-utils-ts/blob/main/src/types/app.ts#L269)
+[src/types/app.ts:274](https://github.com/algorandfoundation/algokit-utils-ts/blob/main/src/types/app.ts#L274)

docs/code/interfaces/types_app.AppCallParams.md

@@ -40,7 +40,7 @@ The id of the app to call
 
 #### Defined in
 
-[src/types/app.ts:162](https://github.com/algorandfoundation/algokit-utils-ts/blob/main/src/types/app.ts#L162)
+[src/types/app.ts:167](https://github.com/algorandfoundation/algokit-utils-ts/blob/main/src/types/app.ts#L167)
 
 ___
 
@@ -52,7 +52,7 @@ The arguments passed in to the app call
 
 #### Defined in
 
-[src/types/app.ts:172](https://github.com/algorandfoundation/algokit-utils-ts/blob/main/src/types/app.ts#L172)
+[src/types/app.ts:177](https://github.com/algorandfoundation/algokit-utils-ts/blob/main/src/types/app.ts#L177)
 
 ___
 
@@ -80,7 +80,7 @@ The type of call, everything except create (see `createApp`) and update (see `up
 
 #### Defined in
 
-[src/types/app.ts:164](https://github.com/algorandfoundation/algokit-utils-ts/blob/main/src/types/app.ts#L164)
+[src/types/app.ts:169](https://github.com/algorandfoundation/algokit-utils-ts/blob/main/src/types/app.ts#L169)
 
 ___
 
@@ -108,7 +108,7 @@ The account to make the call from
 
 #### Defined in
 
-[src/types/app.ts:166](https://github.com/algorandfoundation/algokit-utils-ts/blob/main/src/types/app.ts#L166)
+[src/types/app.ts:171](https://github.com/algorandfoundation/algokit-utils-ts/blob/main/src/types/app.ts#L171)
 
 ___
 
@@ -152,7 +152,7 @@ The (optional) transaction note
 
 #### Defined in
 
-[src/types/app.ts:170](https://github.com/algorandfoundation/algokit-utils-ts/blob/main/src/types/app.ts#L170)
+[src/types/app.ts:175](https://github.com/algorandfoundation/algokit-utils-ts/blob/main/src/types/app.ts#L175)
 
 ___
 
@@ -213,4 +213,4 @@ Optional transaction parameters
 
 #### Defined in
 
-[src/types/app.ts:168](https://github.com/algorandfoundation/algokit-utils-ts/blob/main/src/types/app.ts#L168)
+[src/types/app.ts:173](https://github.com/algorandfoundation/algokit-utils-ts/blob/main/src/types/app.ts#L173)

docs/code/interfaces/types_app.AppCallTransactionResult.md

@@ -69,7 +69,7 @@ If an ABI method was called the processed return value
 
 #### Defined in
 
-[src/types/app.ts:205](https://github.com/algorandfoundation/algokit-utils-ts/blob/main/src/types/app.ts#L205)
+[src/types/app.ts:210](https://github.com/algorandfoundation/algokit-utils-ts/blob/main/src/types/app.ts#L210)
 
 ___
 

docs/code/interfaces/types_app.AppCallTransactionResultOfType.md

@@ -75,7 +75,7 @@ If an ABI method was called the processed return value
 
 #### Defined in
 
-[src/types/app.ts:205](https://github.com/algorandfoundation/algokit-utils-ts/blob/main/src/types/app.ts#L205)
+[src/types/app.ts:210](https://github.com/algorandfoundation/algokit-utils-ts/blob/main/src/types/app.ts#L210)
 
 ___
 

docs/code/interfaces/types_app.AppCompilationResult.md

@@ -23,7 +23,7 @@ The compilation result of approval
 
 #### Defined in
 
-[src/types/app.ts:312](https://github.com/algorandfoundation/algokit-utils-ts/blob/main/src/types/app.ts#L312)
+[src/types/app.ts:317](https://github.com/algorandfoundation/algokit-utils-ts/blob/main/src/types/app.ts#L317)
 
 ___
 
@@ -35,4 +35,4 @@ The compilation result of clear
 
 #### Defined in
 
-[src/types/app.ts:314](https://github.com/algorandfoundation/algokit-utils-ts/blob/main/src/types/app.ts#L314)
+[src/types/app.ts:319](https://github.com/algorandfoundation/algokit-utils-ts/blob/main/src/types/app.ts#L319)