@goplausible/algorand-mcp 3.0.7

package/dist/resources/knowledge/taxonomy/algokit:utils:typescript:capabilities:asset.md

@@ -0,0 +1,331 @@
+# Assets
+
+The Algorand Standard Asset (asset) management functions include creating, opting in and transferring assets, which are fundamental to asset interaction in a blockchain environment.
+
+To see some usage examples check out the [automated tests](../../src/types/algorand-client.asset.spec.ts).
+
+## `AssetManager`
+
+The [`AssetManager`](../code/classes/types_asset_manager.AssetManager.md) is a class that is used to manage asset information.
+
+To get an instance of `AssetManager`, you can use either [`AlgorandClient`](./algorand-client.md) via `algorand.asset` or instantiate it directly:
+
+```typescript
+import { AssetManager } from '@algorandfoundation/algokit-utils/types/asset-manager'
+import {TransactionComposer } from '@algorandfoundation/algokit-utils/types/composer'
+
+const assetManager = new AssetManager(algod, () => new TransactionComposer({algod, () => signer, () => suggestedParams}))
+```
+
+## Creation
+
+To create an asset you can use `algorand.send.assetCreate(params)` (immediately send a single asset creation transaction), `algorand.createTransaction.assetCreate(params)` (construct an asset creation transaction), or `algorand.newGroup().addAssetCreate(params)` (add asset creation to a group of transactions) per [`AlgorandClient`](./algorand-client.md) [transaction semantics](./algorand-client.md#creating-and-issuing-transactions).
+
+The base type for specifying an asset creation transaction is [`AssetCreateParams`](../code/modules/types_composer.md#assetcreateparams), which has the following parameters in addition to the [common transaction parameters](./algorand-client.md#transaction-parameters):
+
+- `total: bigint` - The total amount of the smallest divisible (decimal) unit to create. For example, if `decimals` is, say, 2, then for every 100 `total` there would be 1 whole unit. This field can only be specified upon asset creation.
+- `decimals: number` - The amount of decimal places the asset should have. If unspecified then the asset will be in whole units (i.e. `0`). If 0, the asset is not divisible. If 1, the base unit of the asset is in tenths, and so on up to 19 decimal places. This field can only be specified upon asset creation.
+- `assetName?: string` - The optional name of the asset. Max size is 32 bytes. This field can only be specified upon asset creation.
+- `unitName?: string` - The optional name of the unit of this asset (e.g. ticker name). Max size is 8 bytes. This field can only be specified upon asset creation.
+- `url?: string` - Specifies an optional URL where more information about the asset can be retrieved. Max size is 96 bytes. This field can only be specified upon asset creation.
+- `metadataHash?: string | Uint8Array` - 32-byte hash of some metadata that is relevant to your asset and/or asset holders. The format of this metadata is up to the application. This field can only be specified upon asset creation.
+- `defaultFrozen?: boolean` - Whether to freeze holdings for this asset by default. Defaults to `false`. If `true` then for anyone apart from the creator to hold the asset it needs to be unfrozen using an asset freeze transaction from the `freeze` account, which must be set on creation. This field can only be specified upon asset creation.
+- `manager?: string` - The address of the optional account that can manage the configuration of the asset and destroy it. The configuration fields it can change are `manager`, `reserve`, `clawback`, and `freeze`. If not set (`undefined` or `""`) at asset creation or subsequently set to empty by the `manager` the asset becomes permanently immutable.
+- `reserveAccount?: string` - The address of the optional account that holds the reserve (uncirculated supply) units of the asset. This address has no specific authority in the protocol itself and is informational only. Some standards like [ARC-19](https://github.com/algorandfoundation/ARCs/blob/main/ARCs/arc-0019.md) rely on this field to hold meaningful data. It can be used in the case where you want to signal to holders of your asset that the uncirculated units of the asset reside in an account that is different from the default creator account. If not set (`undefined` or `""`) at asset creation or subsequently set to empty by the manager the field is permanently empty.
+- `freezeAccount?: string` - The address of the optional account that can be used to freeze or unfreeze holdings of this asset for any account. If empty, freezing is not permitted. If not set (`undefined` or `""`) at asset creation or subsequently set to empty by the manager the field is permanently empty.
+- `clawbackAccount?: string` - The address of the optional account that can clawback holdings of this asset from any account. **This field should be used with caution** as the clawback account has the ability to **unconditionally take assets from any account**. If empty, clawback is not permitted. If not set (`undefined` or `""`) at asset creation or subsequently set to empty by the manager the field is permanently empty.
+
+### Examples
+
+```typescript
+// Basic example
+const result = await algorand.send.assetCreate({ sender: 'CREATORADDRESS', total: 100n })
+const createdAssetId = result.assetId
+
+// Advanced example
+await algorand.send.assetCreate({
+  sender: 'CREATORADDRESS',
+  total: 100n,
+  decimals: 2,
+  assetName: 'asset',
+  unitName: 'unit',
+  url: 'url',
+  metadataHash: 'metadataHash',
+  defaultFrozen: false,
+  manager: 'MANAGERADDRESS',
+  reserve: 'RESERVEADDRESS',
+  freeze: 'FREEZEADDRESS',
+  clawback: 'CLAWBACKADDRESS',
+  lease: 'lease',
+  note: 'note',
+  // You wouldn't normally set this field
+  firstValidRound: 1000n,
+  validityWindow: 10,
+  extraFee: (1000).microAlgo(),
+  staticFee: (1000).microAlgo(),
+  // Max fee doesn't make sense with extraFee AND staticFee
+  //  already specified, but here for completeness
+  maxFee: (3000).microAlgo(),
+  // Signer only needed if you want to provide one,
+  //  generally you'd register it with AlgorandClient
+  //  against the sender and not need to pass it in
+  signer: transactionSigner,
+  maxRoundsToWaitForConfirmation: 5,
+  suppressLog: true,
+})
+```
+
+## Reconfigure
+
+If you have a `manager` address set on an asset, that address can send a reconfiguration transaction to change the `manager`, `reserve`, `freeze` and `clawback` fields of the asset if they haven't been set to empty.
+
+> [!WARNING]
+> If you issue a reconfigure transaction and don't set the _existing_ values for any of the below fields then that field will be permanently set to empty.
+
+To reconfigure an asset you can use `algorand.send.assetConfig(params)` (immediately send a single asset config transaction), `algorand.createTransaction.assetConfig(params)` (construct an asset config transaction), or `algorand.newGroup().addAssetConfig(params)` (add asset config to a group of transactions) per [`AlgorandClient`](./algorand-client.md) [transaction semantics](./algorand-client.md#creating-and-issuing-transactions).
+
+The base type for specifying an asset creation transaction is [`AssetConfigParams`](../code/modules/types_composer.md#assetconfigparams), which has the following parameters in addition to the [common transaction parameters](./algorand-client.md#transaction-parameters):
+
+- `assetId: bigint` - ID of the asset to reconfigure
+- `manager: string | undefined` - The address of the optional account that can manage the configuration of the asset and destroy it. The configuration fields it can change are `manager`, `reserve`, `clawback`, and `freeze`. If not set (`undefined` or `""`) the asset will become permanently immutable.
+- `reserve?: string` - The address of the optional account that holds the reserve (uncirculated supply) units of the asset. This address has no specific authority in the protocol itself and is informational only. Some standards like [ARC-19](https://github.com/algorandfoundation/ARCs/blob/main/ARCs/arc-0019.md) rely on this field to hold meaningful data. It can be used in the case where you want to signal to holders of your asset that the uncirculated units of the asset reside in an account that is different from the default creator account. If not set (`undefined` or `""`) the field will become permanently empty.
+- `freeze?: string` - The address of the optional account that can be used to freeze or unfreeze holdings of this asset for any account. If empty, freezing is not permitted. If not set (`undefined` or `""`) the field will become permanently empty.
+- `clawback?: string` - The address of the optional account that can clawback holdings of this asset from any account. **This field should be used with caution** as the clawback account has the ability to **unconditionally take assets from any account**. If empty, clawback is not permitted. If not set (`undefined` or `""`) the field will become permanently empty.
+
+### Examples
+
+```typescript
+// Basic example
+
+await algorand.send.assetConfig({ sender: 'MANAGERADDRESS', assetId: 123456n, manager: 'MANAGERADDRESS' })
+
+// Advanced example
+
+await algorand.send.assetConfig({
+  sender: 'MANAGERADDRESS',
+  assetId: 123456n,
+  manager: 'MANAGERADDRESS',
+  reserve: 'RESERVEADDRESS',
+  freeze: 'FREEZEADDRESS',
+  clawback: 'CLAWBACKADDRESS',
+  lease: 'lease',
+  note: 'note',
+  // You wouldn't normally set this field
+  firstValidRound: 1000n,
+  validityWindow: 10,
+  extraFee: (1000).microAlgo(),
+  staticFee: (1000).microAlgo(),
+  // Max fee doesn't make sense with extraFee AND staticFee
+  //  already specified, but here for completeness
+  maxFee: (3000).microAlgo(),
+  // Signer only needed if you want to provide one,
+  //  generally you'd register it with AlgorandClient
+  //  against the sender and not need to pass it in
+  signer: transactionSigner,
+  maxRoundsToWaitForConfirmation: 5,
+  suppressLog: true,
+})
+```
+
+## Transfer
+
+To transfer unit(s) of an asset between accounts you can use `algorand.send.assetTransfer(params)` (immediately send a single asset transfer transaction), `algorand.createTransaction.assetTransfer(params)` (construct an asset transfer transaction), or `algorand.newGroup().addAssetTransfer(params)` (add asset transfer to a group of transactions) per [`AlgorandClient`](./algorand-client.md) [transaction semantics](./algorand-client.md#creating-and-issuing-transactions).
+
+**Note:** For an account to receive an asset it needs to have [opted-in](#opt-inout).
+
+The base type for specifying an asset transfer transaction is [`AssetTransferParams`](../code/modules/types_composer.md#assettransferparams), which has the following parameters in addition to the [common transaction parameters](./algorand-client.md#transaction-parameters):
+
+- `assetId: bigint` - ID of the asset to transfer.
+- `amount: bigint` - Amount of the asset to transfer (in smallest divisible (decimal) units).
+- `receiver: string` - The address of the account that will receive the asset unit(s).
+- `clawbackTarget?: string` - Optional address of an account to clawback the asset from. Requires the sender to be the clawback account. **Warning:** Be careful with this parameter as it can lead to unexpected loss of funds if not used correctly.
+- `closeAssetTo?: string` - Optional address of an account to close the asset position to. **Warning:** Be careful with this parameter as it can lead to loss of funds if not used correctly.
+
+### Examples
+
+```typescript
+// Basic example
+
+await algorand.send.assetTransfer({sender: 'HOLDERADDRESS', assetId: 123456n, amount: 1n, receiver: 'RECEIVERADDRESS' })
+
+// Advanced example (with clawback and close asset to)
+
+await algorand.send.assetTransfer({
+  sender: 'CLAWBACKADDRESS',
+  assetId: 123456n,
+  amount: 1n,
+  receiver: 'RECEIVERADDRESS',
+  clawbackTarget: 'HOLDERADDRESS',
+  // This field needs to be used with caution
+  closeAssetTo: 'ADDRESSTOCLOSETO'
+  lease: 'lease',
+  note: 'note',
+  // You wouldn't normally set this field
+  firstValidRound: 1000n,
+  validityWindow: 10,
+  extraFee: (1000).microAlgo(),
+  staticFee: (1000).microAlgo(),
+  // Max fee doesn't make sense with extraFee AND staticFee
+  //  already specified, but here for completeness
+  maxFee: (3000).microAlgo(),
+  // Signer only needed if you want to provide one,
+  //  generally you'd register it with AlgorandClient
+  //  against the sender and not need to pass it in
+  signer: transactionSigner,
+  maxRoundsToWaitForConfirmation: 5,
+  suppressLog: true,
+})
+```
+
+## Opt-in/out
+
+Before an account can receive a specific asset, it must [`opt-in`](https://developer.algorand.org/docs/get-details/asa/#receiving-an-asset) to receive it. An opt-in transaction places an asset holding of 0 into the account and increases the [minimum balance](https://developer.algorand.org/docs/get-details/accounts/#minimum-balance) of that account by [100,000 microAlgos](https://developer.algorand.org/docs/get-details/asa/#assets-overview).
+
+An account can opt out of an asset at any time by closing out it's asset position to another account (usually to the asset creator). 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. AlgoKit Utils can protect 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 and opt-outs 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 of 16 at a time.
+
+### `assetOptIn`
+
+To opt-in to an asset you can use `algorand.send.assetOptIn(params)` (immediately send a single asset opt-in transaction), `algorand.createTransaction.assetOptIn(params)` (construct an asset opt-in transaction), or `algorand.newGroup().addAssetOptIn(params)` (add asset opt-in to a group of transactions) per [`AlgorandClient`](./algorand-client.md) [transaction semantics](./algorand-client.md#creating-and-issuing-transactions).
+
+The base type for specifying an asset opt-in transaction is [`AssetOptInParams`](../code/modules/types_composer.md#assetoptinparams), which has the following parameters in addition to the [common transaction parameters](./algorand-client.md#transaction-parameters):
+
+- `assetId: bigint` - The ID of the asset that will be opted-in to
+
+```typescript
+// Basic example
+
+await algorand.send.assetOptIn({ sender: 'SENDERADDRESS', assetId: 123456n })
+
+// Advanced example
+
+await algorand.send.assetOptIn({
+  sender: 'SENDERADDRESS',
+  assetId: 123456n,
+  lease: 'lease',
+  note: 'note',
+  // You wouldn't normally set this field
+  firstValidRound: 1000n,
+  validityWindow: 10,
+  extraFee: (1000).microAlgo(),
+  staticFee: (1000).microAlgo(),
+  // Max fee doesn't make sense with extraFee AND staticFee
+  //  already specified, but here for completeness
+  maxFee: (3000).microAlgo(),
+  // Signer only needed if you want to provide one,
+  //  generally you'd register it with AlgorandClient
+  //  against the sender and not need to pass it in
+  signer: transactionSigner,
+  maxRoundsToWaitForConfirmation: 5,
+  suppressLog: true,
+})
+```
+
+### `assetOptOut`
+
+To opt-out to an asset you can use `algorand.send.assetOptOut(params)` (immediately send a single asset opt-out transaction), `algorand.createTransaction.assetOptOut(params)` (construct an asset opt-out transaction), or `algorand.newGroup().addAssetOptOut(params)` (add asset opt-out to a group of transactions) per [`AlgorandClient`](./algorand-client.md) [transaction semantics](./algorand-client.md#creating-and-issuing-transactions).
+
+The base type for specifying an asset opt-out transaction is [`AssetOptOutParams`](../code/modules/types_composer.md#assetoptoutparams), which has the following parameters in addition to the [common transaction parameters](./algorand-client.md#transaction-parameters):
+
+- `assetId: bigint` - The ID of the asset that will be opted-out of
+- `creator: string` - The address of the asset creator account to close the asset position to (any remaining asset units will be sent to this account).
+
+If you are using the `send` variant then there is an additional parameter:
+
+- `ensureZeroBalance: boolean` - Whether or not to check if the account has a zero balance first or not. If this is set to `true` and the account has an asset balance it will throw an error. If this is set to `false` and the account has an asset balance it will lose those assets to the asset creator.
+
+> [!WARNING]
+> If you are using the `transaction` or `addAssetOptOut` variants then you need to take responsibility to ensure the asset holding balance is `0` to avoid losing assets.
+
+```typescript
+// Basic example (without creator)
+
+await algorand.send.assetOptOut({ sender: 'SENDERADDRESS', assetId: 123456n, ensureZeroBalance: true })
+
+// Basic example (with creator)
+
+await algorand.send.assetOptOut({ sender: 'SENDERADDRESS', creator: 'CREATORADDRESS', assetId: 123456n, ensureZeroBalance: true })
+
+// Advanced example
+
+await algorand.send.assetOptOut({
+  sender: 'SENDERADDRESS',
+  assetId: 123456n,
+  creator: 'CREATORADDRESS',
+  ensureZeroBalance: true,
+  lease: 'lease',
+  note: 'note',
+  // You wouldn't normally set this field
+  firstValidRound: 1000n,
+  validityWindow: 10,
+  extraFee: (1000).microAlgo(),
+  staticFee: (1000).microAlgo(),
+  // Max fee doesn't make sense with extraFee AND staticFee
+  //  already specified, but here for completeness
+  maxFee: (3000).microAlgo(),
+  // Signer only needed if you want to provide one,
+  //  generally you'd register it with AlgorandClient
+  //  against the sender and not need to pass it in
+  signer: transactionSigner,
+  maxRoundsToWaitForConfirmation: 5,
+  suppressLog: true,
+})
+```
+
+### `asset.bulkOptIn`
+
+The [`asset.bulkOptIn`](../code/classes/types_asset_manager.AssetManager.md#bulkoptin) function facilitates the opt-in process for an account to multiple assets, allowing the account to receive and hold those assets.
+
+```typescript
+// Basic example
+
+algorand.asset.bulkOptIn('ACCOUNTADDRESS', [12345n, 67890n])
+
+// Advanced example
+
+algorand.asset.bulkOptIn('ACCOUNTADDRESS', [12345n, 67890n], {
+  maxFee: (1000).microAlgo(),
+  suppressLog: true,
+})
+```
+
+### `asset.bulkOptOut`
+
+The [`asset.bulkOptOut`](../code/classes/types_asset_manager.AssetManager.md#bulkoptout) function facilitates the opt-out process for an account from multiple assets, permitting the account to discontinue holding a group of assets.
+
+```typescript
+// Basic example
+
+algorand.asset.bulkOptOut('ACCOUNTADDRESS', [12345n, 67890n])
+
+// Advanced example
+
+algorand.asset.bulkOptOut('ACCOUNTADDRESS', [12345n, 67890n], {
+  ensureZeroBalance: true,
+  maxFee: (1000).microAlgo(),
+  suppressLog: true,
+})
+```
+
+## Get information
+
+### Getting current parameters for an asset
+
+You can get the current parameters of an asset from algod by using `algorand.asset.getById(assetId)`.
+
+```typescript
+const assetInfo = await assetManager.getById(12353n)
+```
+
+### Getting current holdings of an asset for an account
+
+You can get the current holdings of an asset for a given account from algod by using `algorand.asset.getAccountInformation(accountAddress, assetId)`.
+
+```typescript
+const address = 'XBYLS2E6YI6XXL5BWCAMOA4GTWHXWENZMX5UHXMRNWWUQ7BXCY5WC5TEPA'
+const assetId = 123345n
+const accountInfo = await algorand.asset.getAccountInformation(address, assetId)
+```

package/dist/resources/knowledge/taxonomy/algokit:utils:typescript:capabilities:client.md

@@ -0,0 +1,115 @@
+# Client management
+
+Client management is one of the core capabilities provided by AlgoKit Utils. It allows you to create (auto-retry) [algod](https://developer.algorand.org/docs/rest-apis/algod), [indexer](https://developer.algorand.org/docs/rest-apis/indexer) and [kmd](https://developer.algorand.org/docs/rest-apis/kmd) clients against various networks resolved from environment or specified configuration.
+
+Any AlgoKit Utils function that needs one of these clients will take the underlying algosdk classes (`algosdk.Algodv2`, `algosdk.Indexer`, `algosdk.Kmd`) so inline with the [Modularity](../README.md#core-principles) principle you can use existing logic to get instances of these clients without needing to use the Client management capability if you prefer, including use of libraries like [useWallet](https://github.com/TxnLab/use-wallet) that have their own configuration mechanism.
+
+To see some usage examples check out the [automated tests](../../src/types/client-manager.spec.ts).
+
+## `ClientManager`
+
+The [`ClientManager`](../code/classes/types_client_manager.ClientManager.md) is a class that is used to manage client instances.
+
+To get an instance of `ClientManager` you can get it from either [`AlgorandClient`](./algorand-client.md) via `algorand.client` or instantiate it directly:
+
+```typescript
+import { ClientManager } from '@algorandfoundation/algokit-utils/types/client-manager'
+
+// Algod client only
+const clientManager = new ClientManager({ algod: algodClient })
+// All clients
+const clientManager = new ClientManager({ algod: algodClient, indexer: indexerClient, kmd: kmdClient })
+// Algod config only
+const clientManager = new ClientManager({ algodConfig })
+// All client configs
+const clientManager = new ClientManager({ algodConfig, indexerConfig, kmdConfig })
+```
+
+## Network configuration
+
+The network configuration is specified using the [`AlgoClientConfig`](../code/interfaces/types_network_client.AlgoClientConfig.md) interface. This same interface is used to specify the config for [algod](https://algorand.github.io/js-algorand-sdk/classes/Algodv2.html), [indexer](https://algorand.github.io/js-algorand-sdk/classes/Indexer.html) and [kmd](https://algorand.github.io/js-algorand-sdk/classes/Kmd.html) SDK clients.
+
+There are a number of ways to produce one of these configuration objects:
+
+- Manually specifying an object that conforms with the interface, e.g.
+  ```typescript
+  {
+    server: 'https://myalgodnode.com'
+  }
+  // Or with the optional values:
+  {
+    server: 'https://myalgodnode.com',
+    port: 443,
+    token: 'SECRET_TOKEN'
+  }
+  ```
+- [`ClientManager.getConfigFromEnvironmentOrLocalNet()`](../code/classes/types_client_manager.ClientManager.md#getconfigfromenvironmentorlocalnet) - Loads the Algod client config, the Indexer client config and the Kmd config from well-known environment variables or if not found then default LocalNet; this is useful to have code that can work across multiple blockchain environments (including LocalNet), without having to change
+- [`ClientManager.getAlgodConfigFromEnvironment()`](../code/classes/types_client_manager.ClientManager.md#getalgodconfigfromenvironment) - Loads an Algod client config from well-known environment variables
+- [`ClientManager.getIndexerConfigFromEnvironment()`](../code/classes/types_client_manager.ClientManager.md#getindexerconfigfromenvironment) - Loads an Indexer client config from well-known environment variables; useful to have code that can work across multiple blockchain environments (including LocalNet), without having to change
+- [`ClientManager.getAlgoNodeConfig(network, config)`](../code/classes/types_client_manager.ClientManager.md#getalgonodeconfig) - Loads an Algod or indexer config against [AlgoNode free tier](https://nodely.io/docs/free/start) to either MainNet or TestNet
+- [`ClientManager.getDefaultLocalNetConfig(configOrPort)`](../code/classes/types_client_manager.ClientManager.md#getdefaultlocalnetconfig) - Loads an Algod, Indexer or Kmd config against [LocalNet](https://github.com/algorandfoundation/algokit-cli/blob/main/docs/features/localnet.md) using the default configuration
+
+## Clients
+
+### Creating an SDK client instance
+
+Once you have the configuration for a client, to get a new client you can use the following functions:
+
+- [`ClientManager.getAlgoClient(config)`](../code/classes/types_client_manager.ClientManager.md#getalgoclient) - Returns an Algod client for the given configuration; the client automatically retries on transient HTTP errors
+- [`ClientManager.getIndexerClient(config, overrideIntDecoding)`](../code/classes/types_client_manager.ClientManager.md#getindexerclient) - Returns an Indexer client for given configuration
+- [`ClientManager.getKmdClient(config)`](../code/classes/types_client_manager.ClientManager.md#getkmdclient) - Returns a Kmd client for the given configuration
+
+You can also shortcut needing to write the likes of `ClientManager.getAlgoClient(ClientManager.getAlgodConfigFromEnvironment())` with environment shortcut methods:
+
+- [`ClientManager.getAlgodClientFromEnvironment(config)`](../code/classes/types_client_manager.ClientManager.md#getalgodclientfromenvironment) - Returns an Algod client by loading the config from environment variables
+- [`ClientManager.getIndexerClientFromEnvironment(config)`](../code/classes/types_client_manager.ClientManager.md#getindexerclientfromenvironment) - Returns an indexer client by loading the config from environment variables
+- [`ClientManager.getKmdClientFromEnvironment(config)`](../code/classes/types_client_manager.ClientManager.md#getkmdclientfromenvironment) - Returns a kmd client by loading the config from environment variables
+
+### Accessing SDK clients via ClientManager instance
+
+Once you have a `ClientManager` instance, you can access the SDK clients for the various Algorand APIs from it (expressed here as `algorand.client` to denote the syntax via an [`AlgorandClient`](./algorand-client.md)):
+
+```typescript
+const algorand = AlgorandClient.defaultLocalNet()
+
+const algodClient = algorand.client.algod
+const indexerClient = algorand.client.indexer
+const kmdClient = algorand.client.kmd
+```
+
+If the method to create the `ClientManager` doesn't configure indexer or kmd ([both of which are optional](#client-management)), then accessing those clients will trigger an error to be thrown:
+
+```typescript
+const algorand = AlgorandClient.fromClients({ algod })
+
+const algodClient = algorand.client.algod // OK
+algorand.client.indexer // Throws error
+algorand.client.kmd // Throws error
+```
+
+### Creating an app client instance
+
+See [how to create app clients via ClientManager via AlgorandClient](./app-client.md#via-algorandclient).
+
+### Creating a TestNet dispenser API client instance
+
+You can also create a [TestNet dispenser API client instance](./dispenser-client.md#creating-a-dispenser-client) from `ClientManager` too.
+
+## Automatic retry
+
+When receiving an Algod or Indexer client from AlgoKit Utils, it will be a special wrapper client that handles retrying transient failures. This is done via the [`AlgoHttpClientWithRetry`](../code/classes/types_algo_http_client_with_retry.AlgoHttpClientWithRetry.md) class.
+
+## Network information
+
+To get information about the current network you are connected to, you can use the [`network()`](../code/classes/types_client_manager.ClientManager.md#network) method on `ClientManager` or the `is{Network}()` methods (which in turn call `network()`) as shown below (expressed here as `algorand.client` to denote the syntax via an [`AlgorandClient`](./algorand-client.md)):
+
+```typescript
+const algorand = AlgorandClient.defaultLocalNet()
+
+const { isTestNet, isMainNet, isLocalNet, genesisId, genesisHash } = await algorand.client.network()
+const testNet = await algorand.client.isTestNet()
+const mainNet = await algorand.client.isMainNet()
+const localNet = await algorand.client.isLocalNet()
+```
+
+The first time `network()` is called it will make a HTTP call to algod to get the network parameters, but from then on it will be cached within that `ClientManager` instance for subsequent calls.

package/dist/resources/knowledge/taxonomy/algokit:utils:typescript:capabilities:debugging.md

@@ -0,0 +1,54 @@
+# Debugger
+
+The AlgoKit TypeScript Utilities package provides a set of debugging tools that can be used to simulate and trace transactions on the Algorand blockchain. These tools and methods are optimized for developers who are building applications on Algorand and need to test and debug their smart contracts via [AlgoKit AVM Debugger extension](https://github.com/algorandfoundation/algokit-avm-vscode-debugger).
+
+## Configuration
+
+The `config.ts` file contains the `UpdatableConfig` class which manages and updates configuration settings for the AlgoKit project.
+
+To enable debug mode in your project you can configure it as follows:
+
+```ts
+import { Config } from '@algorandfoundation/algokit-utils'
+Config.configure({
+  debug: true,
+})
+```
+
+## Debugging in `node` environment (recommended)
+
+Refer to the [algokit-utils-ts-debug](https://github.com/algorandfoundation/algokit-utils-ts-debug) for more details on how to activate the addon package with `algokit-utils` in your project.
+
+> Note: Config also contains a set of flags that affect behaviour of [algokit-utils-ts-debug](https://github.com/algorandfoundation/algokit-utils-ts-debug). Those include `projectRoot`, `traceAll`, `traceBufferSizeMb`, and `maxSearchDepth`. Refer to addon package documentation for details.
+
+### Why are the debug utilities in a separate package?
+
+To keep the `algokit-utils-ts` package lean and isomporphic, the debugging utilities are located in a separate package. This eliminates various error cases with bundlers (e.g. `webpack`, `esbuild`) when building for the browser.
+
+## Debugging in `browser` environment
+
+Note: `algokit-utils-ts-debug` cannot be used in browser environments. However, you can still obtain and persist simulation traces from the browser's `Console` tab when submitting transactions using the algokit-utils-ts package. To enable this functionality, activate debug mode in the algokit-utils-ts config as described in the [getting started](./docs/code/getting-started.md) guide.
+
+### Subscribe to the `simulate` response event
+
+After setting the `debug` flag to true in the [configuration](#configuration) section, subscribe to the `TxnGroupSimulated` event as follows:
+
+```ts
+import { AVMTracesEventData, Config, EventType } from '@algorandfoundation/algokit-utils'
+
+Config.events.on(EventType.TxnGroupSimulated, (eventData: AVMTracesEventData) => {
+  Config.logger.info(JSON.stringify(eventData.simulateResponse.get_obj_for_encoding(), null, 2))
+})
+```
+
+This will output any simulation traces that have been emitted whilst calling your app. Place this code immediately after the `Config.configure` call to ensure it executes before any transactions are submitted for simulation.
+
+### Save simulation trace responses from the browser
+
+With the event handler configured, follow these steps to save simulation trace responses:
+
+1. Open your browser's `Console` tab
+2. Submit the transaction
+3. Copy the simulation request `JSON` and save it to a file with the extension `.trace.avm.json`
+4. Place the file in the `debug_traces` folder of your AlgoKit contract project
+   - Note: If you're not using an AlgoKit project structure, the extension will present a file picker as long as the trace file is within your VSCode workspace

package/dist/resources/knowledge/taxonomy/algokit:utils:typescript:capabilities:dispenser-client.md

@@ -0,0 +1,85 @@
+# TestNet Dispenser Client
+
+The TestNet Dispenser Client is a utility for interacting with the AlgoKit TestNet Dispenser API. It provides methods to fund an account, register a refund for a transaction, and get the current limit for an account.
+
+## Creating a Dispenser Client
+
+To create a Dispenser Client, you need to provide an authorization token. This can be done in two ways:
+
+1. Pass the token directly to the client constructor as `authToken`.
+2. Set the token as an environment variable `ALGOKIT_DISPENSER_ACCESS_TOKEN` (see [docs](https://github.com/algorandfoundation/algokit/blob/main/docs/testnet_api.md#error-handling) on how to obtain the token).
+
+If both methods are used, the constructor argument takes precedence.
+
+The recommended way to get a TestNet dispenser API client is [via `ClientManager`](./client.md):
+
+```typescript
+// With auth token
+const dispenserClient = algorand.client.getTestNetDispenser({
+  authToken: 'your_auth_token',
+})
+
+// With auth token and timeout
+const dispenserClient = algorand.client.getTestNetDispenser({
+  authToken: 'your_auth_token',
+  requestTimeout: 2 /* seconds */,
+})
+
+// From environment variables
+// i.e. process.env['ALGOKIT_DISPENSER_ACCESS_TOKEN'] = 'your_auth_token'
+const dispenserClient = algorand.client.getTestNetDispenserFromEnvironment()
+
+// From environment variables with request timeout
+const dispenserClient = algorand.client.getTestNetDispenserFromEnvironment({
+  requestTimeout: 2 /* seconds */,
+})
+```
+
+Alternatively, you can construct it directly.
+
+```ts
+import { TestNetDispenserApiClient } from '@algorandfoundation/algokit-utils/types/dispenser-client'
+
+// Using constructor argument
+const client = new TestNetDispenserApiClient({ authToken: 'your_auth_token' })
+const clientFromAlgorandClient = algorand.client.getTestNetDispenser({ authToken: 'your_auth_token' })
+
+// Using environment variable
+process.env['ALGOKIT_DISPENSER_ACCESS_TOKEN'] = 'your_auth_token'
+const client = new TestNetDispenserApiClient()
+const clientFromAlgorandClient = algorand.client.getTestNetDispenserFromEnvironment()
+```
+
+## Funding an Account
+
+To fund an account with Algo from the dispenser API, use the `fund` method. This method requires the receiver's address, the amount to be funded, and the asset ID.
+
+```ts
+const response = await client.fund('receiver_address', 1000)
+```
+
+The `fund` method returns a `DispenserFundResponse` object, which contains the transaction ID (`txId`) and the amount funded.
+
+## Registering a Refund
+
+To register a refund for a transaction with the dispenser API, use the `refund` method. This method requires the transaction ID of the refund transaction.
+
+```ts
+await client.refund('transaction_id')
+```
+
+> Keep in mind, to perform a refund you need to perform a payment transaction yourself first by sending funds back to TestNet Dispenser, then you can invoke this refund endpoint and pass the txn_id of your refund txn. You can obtain dispenser address by inspecting the sender field of any issued fund transaction initiated via [fund](#funding-an-account).
+
+## Getting Current Limit
+
+To get the current limit for an account with Algo from the dispenser API, use the `getLimit` method. This method requires the account address.
+
+```ts
+const response = await client.getLimit()
+```
+
+The `limit` method returns a `DispenserLimitResponse` object, which contains the current limit amount.
+
+## Error Handling
+
+If an error occurs while making a request to the dispenser API, an exception will be raised with a message indicating the type of error. Refer to [Error Handling docs](https://github.com/algorandfoundation/algokit/blob/main/docs/testnet_api.md#error-handling) for details on how you can handle each individual error `code`.