@goplausible/algorand-mcp 3.0.7

package/dist/resources/knowledge/taxonomy/algokit:utils:python:markdown:capabilities:account.md

@@ -0,0 +1,32 @@
+# Account management
+
+Account management is one of the core capabilities provided by AlgoKit Utils. It allows you to create mnemonic, idempotent KMD and environment variable injected accounts
+that can be used to sign transactions as well as representing a sender address at the same time.
+
+<a id="account"></a>
+
+## `Account`
+
+Encapsulates a private key with convenience properties for `address`, `signer` and `public_key`.
+
+There are various methods of obtaining an `Account` instance
+
+* `get_account`: Returns an `Account` instance with the private key loaded by convention based on the given name identifier:
+  * from an environment variable containing a mnemonic `{NAME}_MNEMONIC` OR
+  * loading the account from KMD ny name if it exists (LocalNet only) OR
+  * creating the account in KMD with associated name (LocalNet only)
+
+  This allows you to have powerful code that will automatically create and fund an account by name locally and when deployed against
+  TestNet/MainNet will automatically resolve from environment variables
+* `Account.new_account`: Returns a new `Account` using `algosdk.account.generate_account()`
+* `Account(private_key)`: Load an existing account from a private key
+* `Account(private_key, address)`: Load an existing account from a private key and address, useful for re-keyed accounts
+* `get_account_from_mnemonic`: Load an existing account from a mnemonic
+* `get_dispenser_account`: Gets a dispenser account that is funded by either:
+  * Using the LocalNet default account (LocalNet only) OR
+  * Loading an account from `DISPENSER_MNEMONIC`
+
+If working with a LocalNet instance, there are some additional functions that rely on a KMD service being exposed:
+
+* `create_kmd_wallet_account`, `get_kmd_wallet_account` or `get_or_create_kmd_wallet_account`: These functions allow retrieving a KMD wallet account by name,
+* `get_localnet_default_account`: Gets default localnet account that is funded with algos

package/dist/resources/knowledge/taxonomy/algokit:utils:python:markdown:capabilities:app-client.md

@@ -0,0 +1,154 @@
+# App client
+
+Application client that works with ARC-0032 application spec defined smart contracts (e.g. via Beaker).
+
+App client is a high productivity application client that works with ARC-0032 application spec defined smart contracts, which you can use to create, update, delete, deploy and call a smart contract and access state data for it.
+
+To see some usage examples check out the [automated tests](https://github.com/algorandfoundation/algokit-utils-py/blob/main/tests/test_app_client_call.py).
+
+## Design
+
+The design for the app client is based on a wrapper for parsing an [ARC-0032](https://github.com/algorandfoundation/ARCs/pull/150) application spec and wrapping the [App deployment](app-deploy.md) functionality and corresponding [design](app-deploy.md#id1).
+
+## Creating an application client
+
+There are two key ways of instantiating an ApplicationClient:
+
+1. By app ID - When needing to call an existing app by app ID or unconditionally create a new app.
+   The signature `ApplicationClient(algod_client, app_spec, app_id=..., ...)` requires:
+   * `algod_client`: An `AlgodClient`
+   * `app_spec`: An `ApplicationSpecification`
+   * `app_id`: The app_id of an existing application, or 0 if creating a new app
+2. By creator and app name - When needing to deploy or find an app associated with a specific creator account and app name.
+   The signature `ApplicationClient(algod_client, app_spec, creator=..., indexer=..., app_lookup)` requires:
+   * `algod_client`: An `AlgodClient`
+   * `app_spec`: An `ApplicationSpecification`
+   * `creator`: The address or `Account` of the creator of the app for which to search for the deployed app under
+   * `indexer`:
+   * `app_lookup`: Optional if an indexer is provided,
+   * `app_name`: An overridden name to identify the contract with, otherwise `contract.name` is used from the app spec
+
+Both approaches also allow specifying the following parameters that will be used as defaults for all application calls:
+
+* `signer`: `TransactionSigner` to sign transactions with.
+* `sender`: Address to use for transaction signing, will be derived from the signer if not provided.
+* `suggested_params`: Default `SuggestedParams` to use, will use current network suggested params by default
+
+Both approaches also allow specifying a mapping of template values via the `template_values` parameter, this will be used before compiling the application to replace any
+`TMPL_` variables that may be in the TEAL. The `TMPL_UPDATABLE` and `TMPL_DELETABLE` variables used in some AlgoKit templates are handled by the `deploy` method, but should be included if
+using `create` or `update` directly.
+
+## Calling methods on the app
+
+There are various methods available on `ApplicationClient` that can be used to call an app:
+
+* `call`: Used to call methods with an on complete action of `no_op`
+* `create`: Used to create an instance of the app, by using an `app_id` of 0, includes the approval and clear programs in the call
+* `update`: Used to update an existing app, includes the approval and clear programs in the call, and is called with an on complete action of `update_application`
+* `delete`: Used to remove an existing app, is called with an on complete action of `delete_application`
+* `opt_in`: Used to opt in to an existing app, is called with an on complete action of `opt_in`
+* `close_out`: Used to close out of an existing app, is called with an on complete action of `opt_in`
+* `clear_state`: Used to unconditionally close out from an app, calls the clear program of an app
+
+### Specifying which method
+
+All methods for calling an app that support ABI methods (everything except `clear_state`) take a parameter `call_abi_method` which can be used to specify which method to call.
+The method selected can be specified explicitly, or allow the client to infer the method where possible, supported values are:
+
+* `None`: The default value, when `None` is passed the client will attempt to find any ABI method or bare method that is compatible with the provided arguments
+* `False`: Indicates that an ABI method should not be used, and instead a bare method call is made
+* `True`: Indicates that an ABI method should be used, and the client will attempt to find an ABI method that is compatible with the provided arguments
+* `str`: If a string is provided, it will be interpreted as either an ABI signature specifying a method, or as an ABI method name
+* `algosdk.abi.Method`: The specified ABI method will be called
+* `ABIReturnSubroutine`: Any type that has a `method_spec` function that returns an `algosd.abi.Method`
+
+### ABI arguments
+
+ABI arguments are passed as python keyword arguments e.g. to pass the ABI parameter `name` for the ABI method `hello` the following syntax is used `client.call("hello", name="world")`
+
+### Transaction Parameters
+
+All methods for calling an app take an optional `transaction_parameters` argument, with the following supported parameters:
+
+* `signer`: The `TransactionSigner` to use on the call. This overrides any signer specified on the client
+* `sender`: The address of the sender to use on the call, must be able to be signed for by the `signer`. This overrides any sender specified on the client
+* `suggested_params`: `SuggestedParams` to use on the call. This overrides any suggested_params specified on the client
+* `note`: Note to include in the transaction
+* `lease`: Lease parameter for the transaction
+* `boxes`: A sequence of boxes to use in the transaction, this is a list of (app_index, box_name) tuples `[(0, "box_name"), (0, ...)]`
+* `accounts`: Account references to include in the transaction
+* `foreign_apps`: Foreign apps to include in the transaction
+* `foreign_assets`: Foreign assets to include in the transaction
+* `on_complete`: The on complete action to use for the transaction, only available when using `call` or `create`
+* `extra_pages`: Additional pages to allocate when calling `create`, by default a sufficient amount will be calculated based on the current approval and clear. This can be overridden, if more is required
+  for a future update
+
+Parameters can be passed as one of the dataclasses `CommonCallParameters`, `OnCompleteCallParameters`, `CreateCallParameters` (exact type depends on method used)
+
+```python
+client.call("hello", transaction_parameters=algokit_utils.OnCompleteCallParameters(signer=...))
+```
+
+Alternatively, parameters can be passed as a dictionary e.g.
+
+```python
+client.call("hello", transaction_parameters={"signer":...})
+```
+
+## Composing calls
+
+If multiple calls need to be made in a single transaction, the `compose_` method variants can be used. All these methods take an `AtomicTransactionComposer` as their first argument.
+Once all the calls have been added to the ATC, it can then be executed. For example:
+
+```python
+from algokit_utils import ApplicationClient
+from algosdk.atomic_transaction_composer import AtomicTransactionComposer
+
+client = ApplicationClient(...)
+atc = AtomicTransactionComposer()
+client.compose_call(atc, "hello", name="world")
+... # additional compose calls
+
+response = client.execute_atc(atc)
+```
+
+## Reading state
+
+There are various methods defined that let you read state from the smart contract app:
+
+* `get_global_state` - Gets the current global state of the app
+* `get_local_state` - Gets the current local state for the given account address
+
+## Handling logic errors and diagnosing errors
+
+Often when calling a smart contract during development you will get logic errors that cause an exception to throw. This may be because of a failing assertion, a lack of fees,
+exhaustion of opcode budget, or any number of other reasons.
+
+When this occurs, you will generally get an error that looks something like: `TransactionPool.Remember: transaction {TRANSACTION_ID}: logic eval error: {ERROR_MESSAGE}. Details: pc={PROGRAM_COUNTER_VALUE}, opcodes={LIST_OF_OP_CODES}`.
+
+The information in that error message can be parsed and when combined with the [source map from compilation](app-deploy.md#id2) you can expose debugging
+information that makes it much easier to understand what’s happening.
+
+When an error is thrown then the resulting error that is re-thrown will be a `LogicError`, which has the following fields:
+
+* `logic_error`: Original exception
+* `program`: Program source (if available)
+* `source_map`: Source map used (if available)
+* `transaction_id`: Transaction ID of failing transaction
+* `message`: The error message
+* `line_no`: The line number in the TEAL program that
+* `traces`: A list of Trace objects providing additional insights on simulation when debug mode is active.
+
+The function `trace()` will provide a formatted output of the surrounding TEAL where the error occurred.
+
+#### NOTE
+The extended information will only show if the Application Client has a source map. This will occur if:
+
+1.) The ApplicationClient instance has already called, `create, `update`or`deploy`OR 2.)`template_values`are provided when creating the ApplicationClient, so a SourceMap can be obtained automatically OR 3.)`approval_source_map`on`ApplicationClient`has been set from a previously compiled approval program OR 4.) A source map has been exported/imported using`export_source_map`/`import_source_map\`”””
+
+### Debug Mode and traces Field
+
+When debug mode is active, the LogicError will contain a field named traces. This field will include raw simulate execution traces, providing a detailed account of the transaction simulation. These traces are crucial for diagnosing complex issues and are automatically included in all application client calls when debug mode is active.
+
+#### NOTE
+Remember to enable debug mode (`config.debug = True`) to include raw simulate execution traces in the `LogicError`.

package/dist/resources/knowledge/taxonomy/algokit:utils:python:markdown:capabilities:app-deploy.md

@@ -0,0 +1,121 @@
+# App deployment
+
+Idempotent (safely retryable) deployment of an app, including deploy-time immutability and permanence control and TEAL template substitution
+
+App deployment is a higher-order use case capability provided by AlgoKit Utils that builds on top of the core capabilities,
+particularly [App management](app-client.md). It allows you to idempotently (with safe retryability) deploy an app, including deploy-time immutability and permanence control and
+TEAL template substitution.
+
+To see some usage examples check out the [automated tests](https://github.com/algorandfoundation/algokit-utils-py/blob/main/tests/test_deploy_scenarios.py).
+
+<a id="design"></a>
+
+## Design
+
+The architecture design behind app deployment is articulated in an [architecture decision record](https://github.com/algorandfoundation/algokit-cli/blob/main/docs/architecture-decisions/2023-01-12_smart-contract-deployment.md).
+While the implementation will naturally evolve over time and diverge from this record, the principles and design goals behind the design are comprehensively explained.
+
+Namely, it described the concept of a smart contract development lifecycle:
+
+1. Development
+   1. **Write** smart contracts
+   2. **Transpile** smart contracts with development-time parameters (code configuration) to TEAL Templates
+   3. **Verify** the TEAL Templates maintain [output stability](https://github.com/algorandfoundation/algokit-cli/blob/main/docs/articles/output_stability.md) and any other static code quality checks
+2. Deployment
+   1. **Substitute** deploy-time parameters into TEAL Templates to create final TEAL code
+   2. **Compile** the TEAL to create byte code using algod
+   3. **Deploy** the byte code to one or more Algorand networks (e.g. LocalNet, TestNet, MainNet) to create Deployed Application(s)
+3. Runtime
+   1. **Validate** the deployed app via automated testing of the smart contracts to provide confidence in their correctness
+   2. **Call** deployed smart contract with runtime parameters to utilise it
+
+![App deployment lifecycle](images/lifecycle.jpg)
+
+The App deployment capability provided by AlgoKit Utils helps implement **#2 Deployment**.
+
+Furthermore, the implementation contains the following implementation characteristics per the original architecture design:
+
+- Deploy-time parameters can be provided and substituted into a TEAL Template by convention (by replacing `TMPL_{KEY}`)
+- Contracts can be built by any smart contract framework that supports [ARC-0032](https://arc.algorand.foundation/ARCs/arc-0032) and
+  [ARC-0004](https://arc.algorand.foundation/ARCs/arc-0004) ([Beaker](https://beaker.algo.xyz/) or otherwise), which also means the deployment language can be
+  different to the development language e.g. you can deploy a Python smart contract with TypeScript for instance
+- There is explicit control of the immutability (updatability / upgradeability) and permanence (deletability) of the smart contract, which can be varied per environment to allow for easier
+  development and testing in non-MainNet environments (by replacing `TMPL_UPDATABLE` and `TMPL_DELETABLE` at deploy-time by convention, if present)
+- Contracts are resolvable by a string “name” for a given creator to allow automated determination of whether that contract had been deployed previously or not, but can also be resolved by ID
+  instead
+
+## Finding apps by creator
+
+There is a method `algokit.get_creator_apps(creatorAccount, indexer)`, which performs a series of indexer lookups that return all apps created by the given creator. These are indexed by the name it
+was deployed under if the creation transaction contained the following payload in the transaction note field:
+
+```default
+ALGOKIT_DEPLOYER:j{name:string, version:string, updatable?:boolean, deletable?:boolean}
+```
+
+Any creation transactions or update transactions are then retrieved and processed in chronological order to result in an `AppLookup` object
+
+Given there are a number of indexer calls to retrieve this data it’s a non-trivial object to create, and it’s recommended that for the duration you are performing a single deployment
+you hold a value of it rather than recalculating it. Most AlgoKit Utils functions that need it will also take an optional value of it that will be used in preference to retrieving a
+fresh version.
+
+## Deploying an application
+
+The method that performs the deployment logic is the instance method `ApplicationClient.deploy`. It performs an idempotent (safely retryable) deployment. It will detect if the app already
+exists and if it doesn’t it will create it. If the app does already exist then it will:
+
+- Detect if the app has been updated (i.e. the logic has changed) and either fail or perform either an update or a replacement based on the deployment configuration.
+- Detect if the app has a breaking schema change (i.e. more global or local storage is needed than was originally requested) and either fail or perform a replacement based on the
+  deployment configuration.
+
+It will automatically add metadata to the transaction note of the create or update calls that indicates the name, version, updatability and deletability of the contract.
+This metadata works in concert with `get_creator_apps` to allow the app to be reliably retrieved against that creator in it’s currently deployed state.
+
+`deploy` automatically executes [template substitution]() including deploy-time control of permanence and immutability.
+
+### Input parameters
+
+The following inputs are used when deploying an App
+
+- `version`: The version string for the app defined in app_spec, if not specified the version will automatically increment for existing apps that are updated, and set to 1.0 for new apps
+- `signer`, `sender`: Optional signer and sender for deployment operations, sender must be the same as the creator specified
+- `allow_update`, `allow_delete`: Control the updatability and deletability of the app, used to populate `TMPL_UPDATABLE` and `TMPL_DELETABLE` template values
+- `on_update`: Determines what should happen if an update to the smart contract is detected (e.g. the TEAL code has changed since last deployment)
+- `on_schema_break`: Determines what should happen if a breaking change to the schema is detected (e.g. if you need more global or local state that was previously requested when the contract was originally created)
+- `create_args`: Args to use if a create operation is performed
+- `update_args`: Args to use if an update operation is performed
+- `delete_args`: Args to use if a delete operation is performed
+- `template_values`: Values to use for automatic substitution of [deploy-time parameter values]() is mapping of `key: value` that will result in `TMPL_{key}` being replaced with `value`
+
+### Idempotency
+
+`deploy` is idempotent which means you can safely call it again multiple times, and it will only apply any changes it detects. If you call it again straight after calling it then it will
+do nothing. This also means it can be used to find an existing app based on the supplied creator and app_spec or name.
+
+<a id="compilation-and-template-substitution"></a>
+
+### Compilation and template substitution
+
+When compiling TEAL template code, the capabilities described in the [design above]() are present, namely the ability to supply deploy-time parameters and the ability to control immutability and permanence of the smart contract at deploy-time.
+
+In order for a smart contract to be able to use this functionality, it must have a TEAL Template that contains the following:
+
+- `TMPL_{key}` - Which can be replaced with a number or a string / byte array which wil be automatically hexadecimal encoded
+- `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 [beaker_production AlgoKit template](https://github.com/algorandfoundation/algokit-beaker-default-template) if provides a reference implementation out of the box for the deploy-time immutability and permanence control.
+
+### Return value
+
+`deploy` returns a `DeployResponse` object, that describes the action taken.
+
+- `action_taken`: Describes what happened during deployment
+  - `Create` - The smart contract app is created.
+  - `Update` - The smart contract app is updated
+  - `Replace` - The smart contract app was deleted and created again (in an atomic transaction)
+  - `Nothing` - Nothing was done since an existing up-to-date app was found
+- `create_response`: If action taken was `Create` or `Replace`, the result of the create transaction. Can be a `TransactionResponse` or `ABITransactionResponse` depending on the method used
+- `update_response`: If action taken was `Update`, the result of the update transaction. Can be a `TransactionResponse` or `ABITransactionResponse` depending on the method used
+- `delete_response`: If action taken was `Replace`, the result of the delete transaction. Can be a `TransactionResponse` or `ABITransactionResponse` depending on the method used
+- `app`: An `AppMetaData` object, describing the final app state

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

@@ -0,0 +1,29 @@
+# Client management
+
+Client management is one of the core capabilities provided by AlgoKit Utils.
+It allows you to create [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.v2client.algod.AlgodClient`, `algosdk.v2client.indexer.IndexerClient`,
+`algosdk.kmd.KMDClient`) so inline with the [Modularity](../index.md#id1) principle you can use existing logic to get instances of these clients without needing to use the
+Client management capability if you prefer.
+
+To see some usage examples check out the [automated tests](https://github.com/algorandfoundation/algokit-utils-py/blob/main/tests/test_network_clients.py).
+
+## Network configuration
+
+The network configuration is specified using the `AlgoClientConfig` class. This same interface is used to specify the config for algod, indexer and kmd clients.
+
+There are a number of ways to produce one of these configuration objects:
+
+- Manually creating the object, e.g. `AlgoClientConfig(server="https://myalgodnode.com", token="SECRET_TOKEN")`
+- `algokit_utils.get_algonode_config(network, config, token)`: Loads an Algod or indexer config against [Nodely](https://nodely.io/docs/free/start) to either MainNet or TestNet
+- `algokit_utils.get_default_localnet_config(configOrPort)`: 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
+
+Once you have the configuration for a client, to get the client you can use the following functions:
+
+- `algokit_utils.get_algod_client(config)`: Returns an Algod client for the given configuration or if none is provided retrieves a configuration from the environment using `ALGOD_SERVER`, `ALGOD_TOKEN` and optionally `ALGOD_PORT`.
+- `algokit_utils.get_indexer_client(config)`: Returns an Indexer client for given configuration or if none is provided retrieves a configuration from the environment using `INDEXER_SERVER`, `INDEXER_TOKEN` and optionally `INDEXER_PORT`
+- `algokit_utils.get_kmd_client_from_algod_client(config)`: - Returns a Kmd client based on the provided algod client configuration, with the assumption the KMD services is running on the same host but a different port (either `KMD_PORT` environment variable or `4002` by default)

package/dist/resources/knowledge/taxonomy/algokit:utils:python:markdown:capabilities:debugger.md

@@ -0,0 +1,45 @@
+# Debugger
+
+The AlgoKit Python 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://marketplace.visualstudio.com/items?itemName=algorandfoundation.algokit-avm-vscode-debugger).
+
+## Configuration
+
+The `config.py` file contains the `UpdatableConfig` class which manages and updates configuration settings for the AlgoKit project. The class has the following attributes:
+
+- `debug`: Indicates whether debug mode is enabled.
+- `project_root`: The path to the project root directory. Can be ignored if you are using `algokit_utils` inside an `algokit` compliant project (containing `.algokit.toml` file). For non algokit compliant projects, simply provide the path to the folder where you want to store sourcemaps and traces to be used with [`AlgoKit AVM Debugger`](https://github.com/algorandfoundation/algokit-avm-vscode-debugger). Alternatively you can also set the value via the `ALGOKIT_PROJECT_ROOT` environment variable.
+- `trace_all`: Indicates whether to trace all operations. Defaults to false, this means that when debug mode is enabled, any (or all) application client calls performed via `algokit_utils` will store responses from `simulate` endpoint. These files are called traces, and can be used with `AlgoKit AVM Debugger` to debug TEAL source codes, transactions in the atomic group and etc.
+- `trace_buffer_size_mb`: The size of the trace buffer in megabytes. By default uses 256 megabytes. When output folder containing debug trace files exceedes the size, oldest files are removed to optimize for storage consumption.
+- `max_search_depth`: The maximum depth to search for a an `algokit` config file. By default it will traverse at most 10 folders searching for `.algokit.toml` file which will be used to assume algokit compliant project root path.
+
+The `configure` method can be used to set these attributes.
+
+To enable debug mode in your project you can configure it as follows:
+
+```py
+from algokit_utils.config import config
+
+config.configure(debug=True)
+```
+
+## Debugging Utilities
+
+Debugging utilities can be used to simplify gathering artifacts to be used with [AlgoKit AVM Debugger](https://github.com/algorandfoundation/algokit-avm-vscode-debugger) in non algokit compliant projects. The following methods are provided:
+
+- `simulate_and_persist_response`: This method simulates the atomic transactions using the provided `AtomicTransactionComposer` object and `AlgodClient` object, and persists the simulation response to an AVM Debugger compliant JSON file. It takes an `AtomicTransactionComposer` object representing the atomic transactions to be simulated and persisted, a `Path` object representing the root directory of the project, an `AlgodClient` object representing the Algorand client, and a float representing the size of the trace buffer in megabytes.
+
+### Trace filename format
+
+The trace files are named in a specific format to provide useful information about the transactions they contain. The format is as follows:
+
+```ts
+`${timestamp}_lr${last_round}_${transaction_types}.trace.avm.json`;
+```
+
+Where:
+
+- `timestamp`: The time when the trace file was created, in ISO 8601 format, with colons and periods removed.
+- `last_round`: The last round when the simulation was performed.
+- `transaction_types`: A string representing the types and counts of transactions in the atomic group. Each transaction type is represented as `${count}${type}`, and different transaction types are separated by underscores.
+
+For example, a trace file might be named `20220301T123456Z_lr1000_2pay_1axfer.trace.avm.json`, indicating that the trace file was created at `2022-03-01T12:34:56Z`, the last round was `1000`, and the atomic group contained 2 payment transactions and 1 asset transfer transaction.

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

@@ -0,0 +1,60 @@
+# 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 `auth_token`.
+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.
+
+```py
+from algokit_utils import TestNetDispenserApiClient
+
+# Using constructor argument
+
+client = TestNetDispenserApiClient(auth_token="your_auth_token")
+
+# Using environment variable
+
+import os
+os.environ["ALGOKIT_DISPENSER_ACCESS_TOKEN"] = "your_auth_token"
+client = TestNetDispenserApiClient()
+```
+
+## Funding an Account
+
+To fund an account with Algos from the dispenser API, use the `fund` method. This method requires the receiver’s address, the amount to be funded, and the asset ID.
+
+```py
+response = client.fund(address="receiver_address", amount=1000, asset_id=0)
+```
+
+The `fund` method returns a `FundResponse` object, which contains the transaction ID (`tx_id`) 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.
+
+```py
+client.refund(refund_txn_id="transaction_id")
+```
+
+> Keep in mind, to perform a refund you need to perform a payment transaction yourself first by send 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`]().
+
+## Getting Current Limit
+
+To get the current limit for an account with Algos from the dispenser API, use the `get_limit` method. This method requires the account address.
+
+```py
+response = client.get_limit(address="account_address")
+```
+
+The `get_limit` method returns a `LimitResponse` 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`.

package/dist/resources/knowledge/taxonomy/algokit:utils:python:markdown:capabilities:transfer.md

@@ -0,0 +1,58 @@
+# Algo transfers
+
+Algo transfers is a higher-order use case capability provided by AlgoKit Utils allows you to easily initiate algo transfers between accounts, including dispenser management and
+idempotent account funding.
+
+To see some usage examples check out the [automated tests](https://github.com/algorandfoundation/algokit-utils-py/blob/main/tests/test_transfer.py).
+
+## Transferring Algos
+
+The key function to facilitate Algo transfers is `algokit.transfer(algod_client, transfer_parameters)`, which returns the underlying `EnsureFundedResponse` and takes a `TransferParameters`
+
+The following fields on `TransferParameters` are required to transfer ALGOs:
+
+- `from_account`: The account or signer that will send the ALGOs
+- `to_address`: The address of the account that will receive the ALGOs
+- `micro_algos`: The amount of micro ALGOs to send
+
+## Ensuring minimum Algos
+
+The ability to automatically fund an account to have a minimum amount of disposable ALGOs to spend is incredibly useful for automation and deployment scripts.
+The function to facilitate this is `ensure_funded(client, parameters)`, which takes an `EnsureBalanceParameters` instance and returns the underlying `EnsureFundedResponse` if a payment was made, a string if the dispenser API was used, or None otherwise.
+
+The following fields on `EnsureBalanceParameters` are required to ensure minimum ALGOs:
+
+- `account_to_fund`: The account address that will receive the ALGOs. This can be an `Account` instance, an `AccountTransactionSigner` instance, or a string.
+- `min_spending_balance_micro_algos`: The minimum balance of micro ALGOs that the account should have available to spend (i.e. on top of minimum balance requirement).
+- `min_funding_increment_micro_algos`: When issuing a funding amount, the minimum amount to transfer (avoids many small transfers if this gets called often on an active account). Default is 0.
+- `funding_source`: The account (with private key) or signer that will send the ALGOs. If not set, it will use `get_dispenser_account`. This can be an `Account` instance, an `AccountTransactionSigner` instance, [`TestNetDispenserApiClient`](https://github.com/algorandfoundation/algokit-utils-py/blob/main/docs/source/capabilities/dispenser-client.md) instance, or None.
+- `suggested_params`: (optional) Transaction parameters, an instance of `SuggestedParams`.
+- `note`: (optional) The transaction note, default is “Funding account to meet minimum requirement”.
+- `fee_micro_algos`: (optional) The flat fee you want to pay, useful for covering extra fees in a transaction group or app call.
+- `max_fee_micro_algos`: (optional) The maximum fee that you are happy to pay (default: unbounded). If this is set it’s possible the transaction could get rejected during network congestion.
+
+The function calls Algod to find the current balance and minimum balance requirement, gets the difference between those two numbers and checks to see if it’s more than the `min_spending_balance_micro_algos`. If so, it will send the difference, or the `min_funding_increment_micro_algos` if that is specified. If the account is on TestNet and `use_dispenser_api` is True, the [AlgoKit TestNet Dispenser API](https://github.com/algorandfoundation/algokit-cli/blob/main/docs/features/dispenser.md) will be used to fund the account.
+
+> Please note, if you are attempting to fund via Dispenser API, make sure to set `ALGOKIT_DISPENSER_ACCESS_TOKEN` environment variable prior to invoking `ensure_funded`. To generate the token refer to [AlgoKit CLI documentation](https://github.com/algorandfoundation/algokit-cli/blob/main/docs/features/dispenser.md#login)
+
+## Transfering Assets
+
+The key function to facilitate asset transfers is `transfer_asset(algod_client, transfer_parameters)`, which returns a `AssetTransferTxn` and takes a `TransferAssetParameters`:
+
+The following fields on `TransferAssetParameters` are required to transfer assets:
+
+- `from_account`: The account or signer that will send the ALGOs
+- `to_address`: The address of the account that will receive the ALGOs
+- `asset_id`: The asset id that will be transfered
+- `amount`: The amount to send as the smallest divisible unit value
+
+## Dispenser
+
+If you want to programmatically send funds then you will often need a “dispenser” account that has a store of ALGOs that can be sent and a private key available for that dispenser account.
+
+There is a standard AlgoKit Utils function to get access to a [dispenser account](account.md#id1): `get_dispenser_account`. When running against
+[LocalNet](https://github.com/algorandfoundation/algokit-cli/blob/main/docs/features/localnet.md), the dispenser account can be automatically determined using the
+[Kmd API](https://developer.algorand.org/docs/rest-apis/kmd). When running against other networks like TestNet or MainNet the mnemonic of the dispenser account can be provided via environment
+variable `DISPENSER_MNEMONIC`
+
+Please note that this does not refer to the [AlgoKit TestNet Dispenser API](dispenser-client.md) which is a separate abstraction that can be used to fund accounts on TestNet via dedicated API service.

package/dist/resources/knowledge/taxonomy/algokit:utils:python:markdown:index.md

@@ -0,0 +1,123 @@
+# AlgoKit Python Utilities
+
+A set of core Algorand utilities written in Python and released via PyPi that make it easier to build solutions on Algorand.
+This project is part of [AlgoKit](https://github.com/algorandfoundation/algokit-cli).
+
+The goal of this library is to provide intuitive, productive utility functions that make it easier, quicker and safer to build applications on Algorand.
+Largely these functions wrap the underlying Algorand SDK, but provide a higher level interface with sensible defaults and capabilities for common tasks.
+
+#### NOTE
+If you prefer TypeScript there’s an equivalent [TypeScript utility library](https://github.com/algorandfoundation/algokit-utils-ts).
+
+[Core principles]() | [Installation]() | [Usage]() | [Capabilities]() | [Reference docs]()
+
+# Contents
+
+* [Account management](capabilities/account.md)
+  * [`Account`](capabilities/account.md#account)
+* [Client management](capabilities/client.md)
+  * [Network configuration](capabilities/client.md#network-configuration)
+  * [Clients](capabilities/client.md#clients)
+* [App client](capabilities/app-client.md)
+  * [Design](capabilities/app-client.md#design)
+  * [Creating an application client](capabilities/app-client.md#creating-an-application-client)
+  * [Calling methods on the app](capabilities/app-client.md#calling-methods-on-the-app)
+  * [Composing calls](capabilities/app-client.md#composing-calls)
+  * [Reading state](capabilities/app-client.md#reading-state)
+  * [Handling logic errors and diagnosing errors](capabilities/app-client.md#handling-logic-errors-and-diagnosing-errors)
+* [App deployment](capabilities/app-deploy.md)
+  * [Design](capabilities/app-deploy.md#design)
+  * [Finding apps by creator](capabilities/app-deploy.md#finding-apps-by-creator)
+  * [Deploying an application](capabilities/app-deploy.md#deploying-an-application)
+* [Algo transfers](capabilities/transfer.md)
+  * [Transferring Algos](capabilities/transfer.md#transferring-algos)
+  * [Ensuring minimum Algos](capabilities/transfer.md#ensuring-minimum-algos)
+  * [Transfering Assets](capabilities/transfer.md#transfering-assets)
+  * [Dispenser](capabilities/transfer.md#dispenser)
+* [TestNet Dispenser Client](capabilities/dispenser-client.md)
+  * [Creating a Dispenser Client](capabilities/dispenser-client.md#creating-a-dispenser-client)
+  * [Funding an Account](capabilities/dispenser-client.md#funding-an-account)
+  * [Registering a Refund](capabilities/dispenser-client.md#registering-a-refund)
+  * [Getting Current Limit](capabilities/dispenser-client.md#getting-current-limit)
+  * [Error Handling](capabilities/dispenser-client.md#error-handling)
+* [Debugger](capabilities/debugger.md)
+  * [Configuration](capabilities/debugger.md#configuration)
+  * [Debugging Utilities](capabilities/debugger.md#debugging-utilities)
+* [`algokit_utils`](apidocs/algokit_utils/algokit_utils.md)
+  * [Data](apidocs/algokit_utils/algokit_utils.md#data)
+  * [Classes](apidocs/algokit_utils/algokit_utils.md#classes)
+  * [Functions](apidocs/algokit_utils/algokit_utils.md#functions)
+
+<a id="core-principles"></a>
+
+# Core principles
+
+This library is designed with the following principles:
+
+- **Modularity** - This library is a thin wrapper of modular building blocks over the Algorand SDK; the primitives from the underlying Algorand SDK are
+  exposed and used wherever possible so you can opt-in to which parts of this library you want to use without having to use an all or nothing approach.
+- **Type-safety** - This library provides strong TypeScript support with effort put into creating types that provide good type safety and intellisense.
+- **Productivity** - This library is built to make solution developers highly productive; it has a number of mechanisms to make common code easier and terser to write
+
+<a id="installation"></a>
+
+# Installation
+
+This library can be installed from PyPi using pip or poetry, e.g.:
+
+```default
+pip install algokit-utils
+poetry add algokit-utils
+```
+
+<a id="usage"></a>
+
+# Usage
+
+To use this library simply include the following at the top of your file:
+
+```python
+import algokit_utils
+```
+
+Then you can use intellisense to auto-complete the various functions and types that are available by typing `algokit_utils.` in your favourite Integrated Development Environment (IDE),
+or you can refer to the [reference documentation](apidocs/algokit_utils/algokit_utils.md).
+
+## Types
+
+The library contains extensive type hinting combined with a tool like MyPy this can help identify issues where incorrect types have been used, or used incorrectly.
+
+<a id="capabilities"></a>
+
+# Capabilities
+
+The library helps you with the following capabilities:
+
+- Core capabilities
+  - [**Client management**](capabilities/client.md) - Creation of algod, indexer and kmd clients against various networks resolved from environment or specified configuration
+  - [**Account management**](capabilities/account.md) - Creation and use of accounts including mnemonic, multisig, transaction signer, idempotent KMD accounts and environment variable injected
+- Higher-order use cases
+  - [**ARC-0032 Application Spec client**](capabilities/app-client.md) - Builds on top of the App management and App deployment capabilities to provide a high productivity application client that works with ARC-0032 application spec defined smart contracts (e.g. via Beaker)
+  - [**App deployment**](capabilities/app-deploy.md) - Idempotent (safely retryable) deployment of an app, including deploy-time immutability and permanence control and TEAL template substitution
+  - [**Algo transfers**](capabilities/transfer.md) - Ability to easily initiate algo transfers between accounts, including dispenser management and idempotent account funding
+  - [**Debugger**](capabilities/debugger.md) - 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 [AVM Debugger extension](https://github.com/algorandfoundation/algokit-avm-vscode-debugger).
+
+<a id="reference-documentation"></a>
+
+# Reference documentation
+
+We have [auto-generated reference documentation for the code](apidocs/algokit_utils/algokit_utils.md).
+
+# Roadmap
+
+This library will naturally evolve with any logical developer experience improvements needed to facilitate the [AlgoKit](https://github.com/algorandfoundation/algokit-cli) roadmap as it evolves.
+
+Likely future capability additions include:
+
+- Typed application client
+- Asset management
+- Expanded indexer API wrapper support
+
+# Indices and tables
+
+- [Index](genindex.md)