@goplausible/algorand-mcp 3.0.7

package/dist/resources/knowledge/taxonomy/algokit:utils:typescript:capabilities:event-emitter.md

@@ -0,0 +1,97 @@
+# Event Emitter
+
+The Event Emitter is a capability provided by AlgoKit Utils that allows for asynchronous event handling of lifecycle events. It provides a flexible mechanism for emitting and listening to custom events, which can be particularly useful for debugging and extending functionality not available in the `algokit-utils-ts` package.
+
+## `AsyncEventEmitter`
+
+The [`AsyncEventEmitter`](../code/classes/types_async_event_emitter.AsyncEventEmitter.md) is a class that manages asynchronous event emission and subscription.
+
+To use the `AsyncEventEmitter`, you can import it directly:
+
+```typescript
+import { AsyncEventEmitter } from '@algorandfoundation/algokit-utils/types/async-event-emitter'
+
+const emitter = new AsyncEventEmitter()
+```
+
+## Event Types
+
+The `EventType` enum defines the built-in event types:
+
+```typescript
+enum EventType {
+  TxnGroupSimulated = 'TxnGroupSimulated',
+  AppCompiled = 'AppCompiled',
+}
+```
+
+## Emitting Events
+
+To emit an event, use the `emitAsync` method:
+
+```typescript
+await emitter.emitAsync(EventType.AppCompiled, compilationData)
+```
+
+## Listening to Events
+
+There are two ways to listen to events:
+
+### Using `on`
+
+The `on` method adds a listener that will be called every time the specified event is emitted:
+
+```typescript
+emitter.on(EventType.AppCompiled, async (data) => {
+  console.log('App compiled:', data)
+})
+```
+
+### Using `once`
+
+The `once` method adds a listener that will be called only once for the specified event:
+
+```typescript
+emitter.once(EventType.TxnGroupSimulated, async (data) => {
+  console.log('Transaction group simulated:', data)
+})
+```
+
+## Removing Listeners
+
+To remove a listener, use the `removeListener` or `off` method:
+
+```typescript
+const listener = async (data) => {
+  console.log('Event received:', data)
+}
+
+emitter.on(EventType.AppCompiled, listener)
+
+// Later, when you want to remove the listener:
+emitter.removeListener(EventType.AppCompiled, listener)
+// or
+emitter.off(EventType.AppCompiled, listener)
+```
+
+## Custom Events
+
+While the current implementation primarily focuses on debugging events, the `AsyncEventEmitter` is designed to be extensible. You can emit and listen to custom events by using string keys:
+
+```typescript
+emitter.on('customEvent', async (data) => {
+  console.log('Custom event received:', data)
+})
+
+await emitter.emitAsync('customEvent', { foo: 'bar' })
+```
+
+## Integration with `algokit-utils-ts-debug`
+
+The events emitted by `AsyncEventEmitter` are particularly useful when used in conjunction with the `algokit-utils-ts-debug` package. This package listens for these events and persists relevant debugging information to the user's AlgoKit project filesystem, facilitating integration with the AVM debugger extension.
+
+## Extending Functionality
+
+The `AsyncEventEmitter` can serve as a foundation for building custom AlgoKit Utils extensions. By listening to the activity events emitted by the utils-ts package, you can create additional functionality tailored to your specific needs.
+
+If you have suggestions for new event types or additional functionality, please open a PR or submit an issue on the AlgoKit Utils GitHub repository.

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

@@ -0,0 +1,83 @@
+# Indexer lookups / searching
+
+Indexer lookups / searching is a higher-order use case capability provided by AlgoKit Utils that builds on top of the core capabilities. It provides type-safe indexer API wrappers (no more `Record<string, any>` pain), including automatic pagination control.
+
+To see some usage examples check out the [automated tests](../../src/indexer-lookup.spec.ts).
+
+To import the indexer functions you can:
+
+```typescript
+import { indexer } from '@algorandfoundation/algokit-utils'
+```
+
+All of the indexer functions require you to pass in an indexer SDK client, which you can get from [`AlgorandClient`](./algorand-client.md) via `algorand.client.indexer`. These calls are not made more easy to call by exposing via `AlgorandClient` and thus not requiring the indexer SDK client to be passed in. This is because we want to add a tiny bit of friction to using indexer, given it's an expensive API to run for node providers, the data from it can sometimes be slow and stale, and there are alternatives [that](https://github.com/algorandfoundation/algokit-subscriber-ts) [allow](https://github.com/algorand/conduit) individual projects to index subsets of chain data specific to them as a preferred option. In saying that, it's a very useful API for doing ad hoc data retrieval, writing automated tests, and many other uses.
+
+## Indexer wrapper functions
+
+There is a subset of [indexer API calls](https://developer.algorand.org/docs/rest-apis/indexer) that are exposed as easy to use methods with correct typing exposed and automatic pagination for multi item returns.
+
+- [`indexer.lookupTransactionById(transactionId, algorand.client.indexer)`](../code/modules/index.md#lookuptransactionbyid) - Finds a transaction by ID
+- [`indexer.lookupAccountByAddress(accountAddress, algorand.client.indexer)`](../code/modules/index.md#lookupaccountbyaddress) - Finds an account by address
+- [`indexer.lookupAccountCreatedApplicationByAddress(algorand.client.indexer, address, getAll?, paginationLimit?)`](../code/modules/index.md#lookupaccountcreatedapplicationbyaddress) - Finds all applications created for an account
+- [`indexer.lookupAssetHoldings(algorand.client.indexer, assetId, options?, paginationLimit?)`](../code/modules/index.md#lookupassetholdings) - Finds all asset holdings for the given asset
+- [`indexer.searchTransactions(algorand.client.indexer, searchCriteria, paginationLimit?)`](../code/modules/index.md#searchtransactions) - Search for transactions with a given set of criteria
+- [`indexer.executePaginatedRequest(extractItems, buildRequest)`](../code/modules/index.md#executepaginatedrequest) - Execute the given indexer request with automatic pagination
+
+### Search transactions example
+
+To use the `indexer.searchTransaction` method, you can follow this example as a starting point:
+
+```typescript
+const transactions = await indexer.searchTransactions(algorand.client.indexer, (s) =>
+  s.txType('pay').addressRole('sender').address(myAddress),
+)
+```
+
+### Automatic pagination example
+
+To use the `indexer.executePaginatedRequest` method, you can follow this example as a starting point:
+
+```typescript
+const transactions = await executePaginatedRequest(
+  (response: TransactionSearchResults) => {
+    return response.transactions
+  },
+  (nextToken) => {
+    let s = algorand.client.indexer.searchForTransactions().txType('pay').address(myAddress).limit(1000)
+    if (nextToken) {
+      s = s.nextToken(nextToken)
+    }
+    return s
+  },
+)
+```
+
+It takes the first lambda to translate the raw response into the array that should keep getting appended as the pagination is followed and the second lambda constructs the request (without the `.do()` call), including populating the pagination token.
+
+## Indexer API response types
+
+The response model type definitions for the majority of [indexer API](https://developer.algorand.org/docs/rest-apis/indexer) are exposed from the `types/indexer` namespace in AlgoKit Utils. This is so that you can have a much better experience than the default response type of `Record<string, any>` from the indexer client in `algosdk`. If there is a type you want to use that is missing feel free to [submit a pull request](https://github.com/algorandfoundation/algokit-utils-ts/pulls) to [add the type(s)](https://github.com/algorandfoundation/algokit-utils-ts/blob/main/src/types/indexer.ts).
+
+To access these types you can import them:
+
+```typescript
+import { /* ... */ } '@algorandfoundation/algokit-utils/types/indexer'
+```
+
+As a general convention, the response types are named `{TypeName}Result` for a single item result and `{TypeName}Results` for a multiple item result where `{TypeName}` is:
+
+- `{Entity}Lookup` for an API call response that returns a lookup for a single entity e.g. `AssetLookupResult`
+- `{Entity}Search` for an API call response that searches for a type of entity e.g. `TransactionSearchResults`
+- The `UpperCamelCase` name of a given model type as specified in the [official documentation](https://developer.algorand.org/docs/rest-apis/indexer) for any sub-types within a response e.g. `ApplicationResult`
+
+The reason `Result/Results` is suffixed to the type is to avoid type name clashes for commonly used types from `algosdk` like `Transaction`.
+
+To use these types with an indexer call you simply need to find the right result type and cast the response from `.do()` for the call in question, e.g.:
+
+```typescript
+import { TransactionLookupResult } from '@algorandfoundation/algokit-utils/types/indexer'
+
+...
+
+const transaction = (await algorand.client.indexer.lookupTransactionByID(transactionId).do()) as TransactionLookupResult
+```

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

@@ -0,0 +1,207 @@
+# Automated testing
+
+Automated testing is a higher-order use case capability provided by AlgoKit Utils that builds on top of the core capabilities. It allows you to use terse, robust automated testing primitives that work across any testing framework (including jest and vitest) to facilitate fixture management, quickly generating isolated and funded test accounts, transaction logging, indexer wait management and log capture.
+
+To see some usage examples check out the all of the [automated tests](../../src/) and the various \*.spec.ts files (AlgoKit Utils [dogfoods](https://en.wikipedia.org/wiki/Eating_your_own_dog_food) it's own testing library). Alternatively, you can see an example of using this library to test a smart contract with [the tests](https://github.com/algorandfoundation/nft_voting_tool/blob/main/src/algorand/smart_contracts/tests/voting.spec.ts) for the [on-chain voting tool](https://github.com/algorandfoundation/nft_voting_tool#readme).
+
+## Module import
+
+The testing capability is not exposed from the [root algokit module](../code/modules/index.md) so there is a clear separation between testing functionality and non-testing functionality.
+
+To access all of the functionality in the testing capability individually, you can import the [testing module](../code/modules/testing.md):
+
+```typescript
+import * as algotesting from '@algorandfoundation/algokit-utils/testing'
+```
+
+## Algorand fixture
+
+In general, the only entrypoint you will need to use the testing capability is just by importing the `algorandFixture` since it exposes the rest of the functionality in a manner that is easy to integrate with an underlying test framework like Jest or vitest:
+
+```typescript
+import { algorandFixture } from '@algorandfoundation/algokit-utils/testing'
+```
+
+### Using with Jest
+
+To integrate with [Jest](https://jestjs.io/) you need to pass the `fixture.beforeEach` method into Jest's `beforeEach` method and then within each test you can access `fixture.context` to access per-test isolated fixture values.
+
+```typescript
+import { describe, test, beforeEach } from '@jest/globals'
+import { algorandFixture } from './testing'
+
+describe('MY MODULE', () => {
+  const fixture = algorandFixture()
+  beforeEach(fixture.beforeEach, 10_000)
+
+  test('MY TEST', async () => {
+    const { algorand, testAccount /* ... */ } = fixture.context
+
+    // Test stuff!
+  })
+})
+```
+
+Occasionally there may be a delay when first running the fixture setup so we add a 10s timeout to avoid intermittent test failures (`10_000`).
+
+### Using with vitest
+
+To integrate with [vitest](https://vitest.dev/) you need to pass the `fixture.beforeEach` method into vitest's `beforeEach` method and then within each test you can access `fixture.context` to access per-test isolated fixture values.
+
+```typescript
+import { describe, test, beforeEach } from 'vitest'
+import { algorandFixture } from './testing'
+
+describe('MY MODULE', () => {
+  const fixture = algorandFixture()
+  beforeEach(fixture.beforeEach, 10_000)
+
+  test('MY TEST', async () => {
+    const { algorand, testAccount /* ... */ } = fixture.context
+
+    // Test stuff!
+  })
+})
+```
+
+### Fixture configuration
+
+When calling `algorandFixture()` you can optionally pass in some fixture configuration, with any of these properties (all optional):
+
+- `algod?: Algodv2` - An optional algod client, if not specified then it will create one against environment variables defined network (if present) or default LocalNet
+- `indexer?: Indexer` - An optional indexer client, if not specified then it will create one against environment variables defined network (if present) or default LocalNet
+- `kmd?: Kmd` - An optional kmd client, if not specified then it will create one against environment variables defined network (if present) or default LocalNet
+- `testAccountFunding?: AlgoAmount` - The [amount](./amount.md) of funds to allocate to the default testing account, if not specified then it will get `10` ALGO
+
+### Using the fixture context
+
+The `fixture.context` property is of type [`AlgorandTestAutomationContext`](../code/interfaces/types_testing.AlgorandTestAutomationContext.md) exposes the following properties from which you can pick which ones you want in a given test using an object [destructuring assignment](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/Destructuring_assignment):
+
+- `algorand: AlgorandClient` - An [`AlgorandClient`](./algorand-client.md) instance
+- `algod: Algodv2` - Proxy Algod client instance that will log sent transactions in `transactionLogger`
+- `indexer: Indexer` - Indexer client instance
+- `kmd: Kmd` - KMD client instance
+- `transactionLogger: TransactionLogger` - Transaction logger that will log transaction IDs for all transactions issued by `algod`
+- `testAccount: Account` - Funded test account that is ephemerally created for each test
+- `generateAccount: (params: GetTestAccountParams) => Promise<Account>` - Generate and fund an additional ephemerally created account
+- `waitForIndexer: () => Promise<void>` - Wait for the indexer to catch up with all transactions logged by transactionLogger
+- `waitForIndexerTransaction: (transactionId: string) => Promise<TransactionLookupResult>` - Wait for the indexer to catch up with the given transaction ID
+
+## Log capture fixture
+
+If you want to capture log messages from AlgoKit that are issued within your test so that you can assert on them or parse them for debugging information etc. then you can use the log capture fixture.
+
+```typescript
+import { algoKitLogCaptureFixture } from '@algorandfoundation/algokit-utils/testing'
+```
+
+The log capture fixture works by setting the logger within the AlgoKit configuration to be a [`TestLogger`](../code/classes/testing.TestLogger.md) during the test run.
+
+### Using with Jest
+
+To integrate with [Jest](https://jestjs.io/) you need to pass the `fixture.beforeEach` method into Jest's `beforeEach` method and then within each test you can access `fixture.context` to access per-test isolated fixture values.
+
+```typescript
+import { describe, test, beforeEach, afterEach } from '@jest/globals'
+import { algoKitLogCaptureFixture } from './testing'
+
+describe('MY MODULE', () => {
+  const logs = algoKitLogCaptureFixture()
+  beforeEach(logs.beforeEach)
+  afterEach(logs.afterEach)
+
+  test('MY TEST', async () => {
+    const { algorand, testAccount } = fixture.context
+    // Test stuff!
+
+    const capturedLogs = logs.testLogger.capturedLogs
+    // do stuff with the logs
+  })
+})
+```
+
+### Using with vitest
+
+To integrate with [vitest](https://vitest.dev/) you need to pass the `fixture.beforeEach` method into vitest's `beforeEach` method and then within each test you can access `fixture.context` to access per-test isolated fixture values.
+
+```typescript
+import { describe, test, beforeEach, afterEach } from 'vitest'
+import { algoKitLogCaptureFixture } from './testing'
+
+describe('MY MODULE', () => {
+  const logs = algoKitLogCaptureFixture()
+  beforeEach(logs.beforeEach)
+  afterEach(logs.afterEach)
+
+  test('MY TEST', async () => {
+    const { algorand, testAccount } = fixture.context
+    // Test stuff!
+
+    const capturedLogs = logs.testLogger.capturedLogs
+    // do stuff with the logs
+  })
+})
+```
+
+### Snapshot testing the logs
+
+If you want to quickly pin some behaviour of what logic you have does in terms of invoking AlgoKit methods you can do a [snapshot test](https://jestjs.io/docs/snapshot-testing) / [approval test](https://approvaltests.com/) of the captured log output. The only problem is this output will contain identifiers that will change for every test run and thus will constantly break the snapshot. In order to work around this you can use the `getLogSnapshot` method on the `TestLogger`, which will replace those changing values with predictable strings to keep the snapshot integrity intact.
+
+This might look something like this:
+
+```typescript
+const { algorand, testAccount } = fixture.context
+const result = await algorand.client.getTypedClientById(HelloWorldContractClient, { id: 0 }).deploy()
+expect(
+  logging.testLogger.getLogSnapshot({
+    accounts: [testAccount],
+    transactions: [result.transaction],
+    apps: [result.appId],
+  }),
+).toMatchSnapshot()
+```
+
+## Waiting for indexer
+
+Often there will be things that you do in your test that you may want to assert in using data that is exclusively in indexer such as transaction notes. The problem is indexer asynchronously indexes the data in algod, even when devmode is turned on and algod instantly confirms transactions.
+
+This means it's easy to create tests that are flaky and have intermittent test failures (sometimes indexer is up to date and other times it hasn't caught up yet).
+
+The testing capability provides mechanisms for waiting for indexer to catch up, namely:
+
+- `algotesting.runWhenIndexerCaughtUp(run: () => Promise<T>)` - Executes the given action every 200ms up to 20 times until there is no longer an error with a `status` property with `404` and then returns the result of the action; this will work for any call that calls indexer APIs expecting to return a single record
+- `algorandFixture.waitForIndexer()` - Waits for indexer to catch up with all transactions that have been captured by the `transactionLogger` in the Algorand fixture
+- `algorandFixture.waitForIndexerTransaction(transactionId)` - Waits for indexer to catch up with the single transaction of the given ID
+
+## Logging transactions
+
+When testing, it can be useful to capture all of the transactions that have been issued with a given test run. They can then be asserted on, or used for [waiting for indexer](#waiting-for-indexer), etc.
+
+The testing capability provides the ability to capture transactions via the [`TransactionLogger`](../code/classes/testing.TransactionLogger.md) class.
+
+The `TransactionLogger` has the following methods:
+
+- `logRawTransaction(signedTransactions: Uint8Array | Uint8Array[])` - Logs the IDs of the given signed transaction(s)
+- `capture(algod)` - Returns a proxy `algosdk.Algodv2` instance that wraps the given `algod` client that will call `logRawTransaction` for every call to `sendRawTransaction` on that algod instance
+- `sentTransactionIds` - Returns the currently captured list of transaction IDs that have been logged
+- `clear()` - Clears the current list of transaction IDs
+- `waitForIndexer(indexer)` - [Waits for the given indexer instance to catch up](#waiting-for-indexer) with the currently logged transaction IDs
+
+The easiest way to use this functionality is via the [Algorand fixture](#algorand-fixture), which automatically provides a `transactionLogger` and a proxy `algod` connected to that `transactionLogger`.
+
+## Getting a test account
+
+When testing, it's often useful to ephemerally generate random accounts, fund them with some number of Algo and then use that account to perform transactions. By creating an ephemeral, random account you naturally get isolation between tests and test runs and don't need to start from a specific blockchain network state. This makes test less flakey, and also means the same test can be run against LocalNet and (say) TestNet.
+
+The key when generating a test account is getting hold of a [dispenser](./transfer.md#dispenser) and then [ensuring the test account is funded](./transfer.md#ensurefunded).
+
+To make it easier to quickly get a test account the testing capability provides the following mechanisms:
+
+- [`algotesting.getTestAccount(testAccountParams, algod, kmd?)`](../code/modules/testing.md#gettestaccount) - Generates a random new account, logs the mnemonic of the account (unless suppressed), funds it from the [dispenser](./transfer.md#dispenser)
+- `algorandFixture.testAccount` - A test account that is always generated for every test (log output suppressed to reduce noise, but worth noting that means the mnemonic isn't logged for this account), by default it is given 10 Algo unless overridden in the [fixture config](#fixture-configuration)
+- [`algorandFixture.generateAccount(testAccountParams)`](../code/interfaces/types_testing.AlgorandTestAutomationContext.md#generateaccount) - Allows you to quickly generate a test account with the `algod` and `kmd` instances that are part of the given fixture
+
+The parameters object that controls test account generation, [`GetTestAccountParams`](../code/interfaces/types_testing.GetTestAccountParams.md), has the following properties:
+
+- `initialFunds: AlgoAmount` - Initial funds to ensure the account has
+- `suppressLog?: boolean` - Whether to suppress the log (which includes a mnemonic) or not (default: do not suppress the log)

package/dist/resources/knowledge/taxonomy/algokit:utils:typescript:capabilities:transaction-composer.md

@@ -0,0 +1,89 @@
+# Transaction composer
+
+The `TransactionComposer` class allows you to easily compose one or more compliant Algorand transactions and execute and/or simulate them.
+
+It's the core of how the [`AlgorandClient`](./algorand-client.md) class composes and sends transactions.
+
+To get an instance of `TransactionComposer` you can either get it from an [app client](./app-client.md), from an [`AlgorandClient`](./algorand-client.md), or by new-ing up via the constructor.
+
+```typescript
+const composerFromAlgorand = algorand.newGroup()
+const composerFromAppClient = appClient.algorand.newGroup()
+const composerFromConstructor = new TransactionComposer({
+  algod,
+  /* Return the algosdk.TransactionSigner for this address*/
+  getSigner: (address: string) => signer,
+})
+const composerFromConstructorWithOptionalParams = new TransactionComposer({
+  algod,
+  /* Return the algosdk.TransactionSigner for this address*/
+  getSigner: (address: string) => signer,
+  getSuggestedParams: () => algod.getTransactionParams().do(),
+  defaultValidityWindow: 1000,
+  appManager: new AppManager(algod),
+})
+```
+
+## Constructing a transaction
+
+To construct a transaction you need to add it to the composer, passing in the relevant [params object](../code/modules/types_composer.md#type-aliases) for that transaction. Params are normal JavaScript objects and all of them extend the [common call parameters](./algorand-client.md#transaction-parameters).
+
+The [methods to construct a transaction](../code/classes/types_composer.default.md#methods) are all named `add{TransactionType}` and return an instance of the composer so they can be chained together fluently to construct a transaction group.
+
+For example:
+
+```typescript
+const result = algorand
+  .newGroup()
+  .addPayment({ sender: 'SENDER', receiver: 'RECEIVER', amount: (100).microAlgo() })
+  .addAppCallMethodCall({
+    sender: 'SENDER',
+    appId: 123n,
+    method: abiMethod,
+    args: [1, 2, 3],
+  })
+```
+
+## Simulating a transaction
+
+Transactions can be simulated using the simulate endpoint in algod, which enables evaluating the transaction on the network without it actually being commited to a block.
+This is a powerful feature, which has a number of options which are detailed in the [simulate API docs](https://developer.algorand.org/docs/rest-apis/algod/#post-v2transactionssimulate).
+
+For example you can simulate a transaction group like below:
+
+```typescript
+const result = await algorand
+  .newGroup()
+  .addPayment({ sender: 'SENDER', receiver: 'RECEIVER', amount: (100).microAlgo() })
+  .addAppCallMethodCall({
+    sender: 'SENDER',
+    appId: 123n,
+    method: abiMethod,
+    args: [1, 2, 3],
+  })
+  .simulate()
+```
+
+The above will execute a simulate request asserting that all transactions in the group are correctly signed.
+
+### Simulate without signing
+
+There are situations where you may not be able to (or want to) sign the transactions when executing simulate.
+In these instances you should set `skipSignatures: true` which automatically builds empty transaction signers and sets both `fix-signers` and `allow-empty-signatures` to `true` when sending the algod API call.
+
+For example:
+
+```typescript
+const result = await algorand
+  .newGroup()
+  .addPayment({ sender: 'SENDER', receiver: 'RECEIVER', amount: (100).microAlgo() })
+  .addAppCallMethodCall({
+    sender: 'SENDER',
+    appId: 123n,
+    method: abiMethod,
+    args: [1, 2, 3],
+  })
+  .simulate({
+    skipSignatures: true,
+  })
+```

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

@@ -0,0 +1,23 @@
+# Transaction management
+
+Transaction management is one of the core capabilities provided by AlgoKit Utils. It allows you to construct, simulate and send single, or grouped transactions with consistent and highly configurable semantics, including configurable control of transaction notes, logging, fees, multiple sender account types, and sending behaviour.
+
+## `ConfirmedTransactionResult`
+
+All AlgoKit Utils functions that send a transaction will generally return a variant of the [`ConfirmedTransactionResult` interface](../code/interfaces/types_transaction.ConfirmedTransactionResult.md) or some superset of that. This provides a consistent mechanism to interpret the results of a transaction send.
+
+It consists of two properties:
+
+- `transaction`: An `algosdk.Transaction` object that is either ready to send or represents the transaction that was sent
+- `confirmation`: An `algosdk.modelsv2.PendingTransactionResponse` object, which is a type-safe wrapper of the return from the algod pending transaction API noting that it will only be returned if the transaction was able to be confirmed (so won't represent a "pending" transaction)
+
+There are various variations of the `ConfirmedTransactionResult` that are exposed by various functions within AlgoKit Utils, including:
+
+- [`ConfirmedTransactionResults`](../code/interfaces/types_transaction.ConfirmedTransactionResults.md) - Where it's both guaranteed that a confirmation will be returned, there is a primary driving transaction, but multiple transactions may be sent (e.g. when making an ABI app call which has dependant transactions)
+- [`SendTransactionResults`](../code/interfaces/types_transaction.SendTransactionResults.md) - Where multiple transactions are being sent (`transactions` and `confirmations` are arrays that replace the singular `transaction` and `confirmation`)
+- [`SendAtomicTransactionComposerResults`](../code/interfaces/types_transaction.SendAtomicTransactionComposerResults.md) - The result from sending the transactions within an `AtomicTransactionComposer`, it extends `SendTransactionResults` and adds a few other useful properties
+- [`AppCallTransactionResult`](../code/interfaces/types_app.AppCallTransactionResult.md) - Result from calling a single app call (which potentially may result in multiple other transaction calls if it was an ABI method with dependant transactions)
+
+## Further reading
+
+To understand how to create, simulate and send transactions consult the [`AlgorandClient`](./algorand-client.md) and [`AlgorandClient`](./algokit-composer.md) documentation.

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

@@ -0,0 +1,129 @@
+# Algo transfers (payments)
+
+Algo transfers, or [payments](https://developer.algorand.org/docs/get-details/transactions/#payment-transaction), is a higher-order use case capability provided by AlgoKit Utils that builds on top of the core capabilities, particularly [Algo amount handling](./amount.md) and [Transaction management](./transaction.md). It 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](../../src/types/algorand-client.transfer.spec.ts).
+
+## `payment`
+
+The key function to facilitate Algo transfers is `algorand.send.payment(params)` (immediately send a single payment transaction), `algorand.createTransaction.payment(params)` (construct a payment transaction), or `algorand.newGroup().addPayment(params)` (add payment to a group of transactions) per [`AlgorandClient`](./algorand-client.md) [transaction semantics](./algorand-client.md#creating-and-issuing-transactions).
+
+The base type for specifying a payment transaction is [`PaymentParams`](../code/modules/types_composer.md#paymentparams), which has the following parameters in addition to the [common transaction parameters](./algorand-client.md#transaction-parameters):
+
+- `receiver: string` - The address of the account that will receive the Algo
+- `amount: AlgoAmount` - The amount of Algo to send
+- `closeRemainderTo?: string` - If given, close the sender account and send the remaining balance to this address (**warning:** use this carefully as it can result in loss of funds if used incorrectly)
+
+```typescript
+// Minimal example
+const result = await algorand.send.payment({
+  sender: 'SENDERADDRESS',
+  receiver: 'RECEIVERADDRESS',
+  amount: (4).algo(),
+})
+
+// Advanced example
+const result2 = await algorand.send.payment({
+  sender: 'SENDERADDRESS',
+  receiver: 'RECEIVERADDRESS',
+  amount: (4).algo(),
+  closeRemainderTo: 'CLOSEREMAINDERTOADDRESS',
+  lease: 'lease',
+  note: 'note',
+  // Use this with caution, it's generally better to use algorand.account.rekeyAccount
+  rekeyTo: 'REKEYTOADDRESS',
+  // 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,
+})
+```
+
+## `ensureFunded`
+
+The `ensureFunded` function automatically funds an account to maintain a minimum amount of [disposable Algo](https://developer.algorand.org/docs/get-details/accounts/#minimum-balance). This is particularly useful for automation and deployment scripts that get run multiple times and consume Algo when run.
+
+There are 3 variants of this function:
+
+- [`algorand.account.ensureFunded(accountToFund, dispenserAccount, minSpendingBalance, options?)`](../code/classes/types_account_manager.AccountManager.md#ensurefunded) - Funds a given account using a dispenser account as a funding source such that the given account has a certain amount of Algo free to spend (accounting for Algo locked in minimum balance requirement).
+- [`algorand.account.ensureFundedFromEnvironment(accountToFund, minSpendingBalance, options?)`](../code/classes/types_account_manager.AccountManager.md#ensurefundedfromenvironment) - Funds a given account using a dispenser account retrieved from the environment, per the [`dispenserFromEnvironment`](#dispenser) method, as a funding source such that the given account has a certain amount of Algo free to spend (accounting for Algo locked in minimum balance requirement).
+  - **Note:** requires a Node.js environment to execute.
+  - The dispenser account is retrieved from the account mnemonic stored in `process.env.DISPENSER_MNEMONIC` and optionally `process.env.DISPENSER_SENDER`
+    if it's a rekeyed account, or against default LocalNet if no environment variables present.
+- [`algorand.account.ensureFundedFromTestNetDispenserApi(accountToFund, dispenserClient, minSpendingBalance, options)`](../code/classes/types_account_manager.AccountManager.md#ensurefundedfromtestnetdispenserapi) - Funds a given account using the [TestNet Dispenser API](https://github.com/algorandfoundation/algokit/blob/main/docs/testnet_api.md) as a funding source such that the account has a certain amount of Algo free to spend (accounting for Algo locked in minimum balance requirement).
+
+The general structure of these calls is similar, they all take:
+
+- `accountToFund: string | TransactionSignerAccount` - Address or signing account of the account to fund
+- The source (dispenser):
+  - In `ensureFunded`: `dispenserAccount: string | TransactionSignerAccount` - the address or signing account of the account to use as a dispenser
+  - In `ensureFundedFromEnvironment`: Not specified, loaded automatically from the ephemeral environment
+  - In `ensureFundedFromTestNetDispenserApi`: `dispenserClient: TestNetDispenserApiClient` - a client instance of the [TestNet dispenser API](./dispenser-client.md)
+- `minSpendingBalance: AlgoAmount` - The minimum balance of Algo that the account should have available to spend (i.e., on top of the minimum balance requirement)
+- An `options` object, which has:
+  - [Common transaction parameters](./algorand-client.md#transaction-parameters) (not for TestNet Dispenser API)
+  - [Execution parameters](./algorand-client.md#sending-a-single-transaction) (not for TestNet Dispenser API)
+  - `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
+
+### Examples
+
+```typescript
+// From account
+
+// Basic example
+await algorand.account.ensureFunded('ACCOUNTADDRESS', 'DISPENSERADDRESS', (1).algo())
+// With configuration
+await algorand.account.ensureFunded('ACCOUNTADDRESS', 'DISPENSERADDRESS', (1).algo(), {
+  minFundingIncrement: (2).algo(),
+  fee: (1000).microAlgo(),
+  suppressLog: true,
+})
+
+// From environment
+
+// Basic example
+await algorand.account.ensureFundedFromEnvironment('ACCOUNTADDRESS', (1).algo())
+// With configuration
+await algorand.account.ensureFundedFromEnvironment('ACCOUNTADDRESS', (1).algo(), {
+  minFundingIncrement: (2).algo(),
+  fee: (1000).microAlgo(),
+  suppressLog: true,
+})
+
+// TestNet Dispenser API
+
+// Basic example
+await algorand.account.ensureFundedUsingDispenserAPI('ACCOUNTADDRESS', algorand.client.getTestNetDispenserFromEnvironment(), (1).algo())
+// With configuration
+await algorand.account.ensureFundedUsingDispenserAPI('ACCOUNTADDRESS', algorand.client.getTestNetDispenserFromEnvironment(), (1).algo(), {
+  minFundingIncrement: (2).algo(),
+})
+```
+
+All 3 variants return an [`EnsureFundedReturnType`](../code/modules/types_account_manager.md#) (and the first two also return a [single transaction result](./algorand-client.md#sending-a-single-transaction)) if a funding transaction was needed, or `undefined` if no transaction was required:
+
+- `amountFunded: AlgoAmount` - The number of Algo that was paid
+- `transactionId: string` - The ID of the transaction that funded the account
+
+If you are using the TestNet Dispenser API then the `transactionId` is useful if you want to use the [refund functionality](./dispenser-client.md#registering-a-refund).
+
+## Dispenser
+
+If you want to programmatically send funds to an account so it can transact then you will often need a "dispenser" account that has a store of Algo that can be sent and a private key available for that dispenser account.
+
+There's a number of ways to get a dispensing account in AlgoKit Utils:
+
+- Get a dispenser via [account manager](./account.md#dispenser) - either automatically from [LocalNet](https://github.com/algorandfoundation/algokit-cli/blob/main/docs/features/localnet.md) or from the environment
+- By programmatically creating one of the many account types via [account manager](./account.md#accounts)
+- By programmatically interacting with [KMD](./account.md#kmd-account-management) if running against LocalNet
+- By using the [AlgoKit TestNet Dispenser API client](./dispenser-client.md) which can be used to fund accounts on TestNet via a dedicated API service