algokit-utils 2.4.0b1__py3-none-any.whl → 3.0.0__py3-none-any.whl

algokit_utils/transactions/transaction_composer.py

@@ -0,0 +1,2499 @@
+from __future__ import annotations
+
+import base64
+import json
+import re
+from copy import deepcopy
+from dataclasses import dataclass
+from typing import TYPE_CHECKING, Any, TypedDict, Union, cast
+
+import algosdk
+import algosdk.atomic_transaction_composer
+import algosdk.v2client.models
+from algosdk import logic, transaction
+from algosdk.atomic_transaction_composer import (
+    AtomicTransactionComposer,
+    SimulateAtomicTransactionResponse,
+    TransactionSigner,
+    TransactionWithSigner,
+)
+from algosdk.transaction import ApplicationCallTxn, OnComplete, SuggestedParams
+from algosdk.v2client.algod import AlgodClient
+from algosdk.v2client.models.simulate_request import SimulateRequest
+from typing_extensions import deprecated
+
+from algokit_utils.applications.abi import ABIReturn, ABIValue
+from algokit_utils.applications.app_manager import AppManager
+from algokit_utils.applications.app_spec.arc56 import Method as Arc56Method
+from algokit_utils.config import config
+from algokit_utils.models.state import BoxIdentifier, BoxReference
+from algokit_utils.models.transaction import SendParams, TransactionWrapper
+from algokit_utils.protocols.account import TransactionSignerAccountProtocol
+
+if TYPE_CHECKING:
+    from collections.abc import Callable
+
+    from algosdk.abi import Method
+    from algosdk.v2client.algod import AlgodClient
+    from algosdk.v2client.models import SimulateTraceConfig
+
+    from algokit_utils.models.amount import AlgoAmount
+    from algokit_utils.models.transaction import Arc2TransactionNote
+
+
+__all__ = [
+    "AppCallMethodCallParams",
+    "AppCallParams",
+    "AppCreateMethodCallParams",
+    "AppCreateParams",
+    "AppCreateSchema",
+    "AppDeleteMethodCallParams",
+    "AppDeleteParams",
+    "AppMethodCallTransactionArgument",
+    "AppUpdateMethodCallParams",
+    "AppUpdateParams",
+    "AssetConfigParams",
+    "AssetCreateParams",
+    "AssetDestroyParams",
+    "AssetFreezeParams",
+    "AssetOptInParams",
+    "AssetOptOutParams",
+    "AssetTransferParams",
+    "BuiltTransactions",
+    "MethodCallParams",
+    "OfflineKeyRegistrationParams",
+    "OnlineKeyRegistrationParams",
+    "PaymentParams",
+    "SendAtomicTransactionComposerResults",
+    "TransactionComposer",
+    "TransactionComposerBuildResult",
+    "TxnParams",
+    "calculate_extra_program_pages",
+    "populate_app_call_resources",
+    "prepare_group_for_sending",
+    "send_atomic_transaction_composer",
+]
+
+
+logger = config.logger
+
+MAX_TRANSACTION_GROUP_SIZE = 16
+MAX_APP_CALL_FOREIGN_REFERENCES = 8
+MAX_APP_CALL_ACCOUNT_REFERENCES = 4
+
+
+@dataclass(kw_only=True, frozen=True)
+class _CommonTxnParams:
+    sender: str
+    """The account that will send the transaction"""
+    signer: TransactionSigner | TransactionSignerAccountProtocol | None = None
+    """The signer for the transaction, defaults to None"""
+    rekey_to: str | None = None
+    """The account to rekey to, defaults to None"""
+    note: bytes | None = None
+    """The note for the transaction, defaults to None"""
+    lease: bytes | None = None
+    """The lease for the transaction, defaults to None"""
+    static_fee: AlgoAmount | None = None
+    """The static fee for the transaction, defaults to None"""
+    extra_fee: AlgoAmount | None = None
+    """The extra fee for the transaction, defaults to None"""
+    max_fee: AlgoAmount | None = None
+    """The maximum fee for the transaction, defaults to None"""
+    validity_window: int | None = None
+    """The validity window for the transaction, defaults to None"""
+    first_valid_round: int | None = None
+    """The first valid round for the transaction, defaults to None"""
+    last_valid_round: int | None = None
+    """The last valid round for the transaction, defaults to None"""
+
+
+@dataclass(kw_only=True, frozen=True)
+class AdditionalAtcContext:
+    max_fees: dict[int, AlgoAmount] | None = None
+    """The maximum fees for each transaction, defaults to None"""
+    suggested_params: SuggestedParams | None = None
+    """The suggested parameters for the transaction, defaults to None"""
+
+
+@dataclass(kw_only=True, frozen=True)
+class PaymentParams(_CommonTxnParams):
+    """Parameters for a payment transaction."""
+
+    receiver: str
+    """The account that will receive the ALGO"""
+    amount: AlgoAmount
+    """Amount to send"""
+    close_remainder_to: str | None = None
+    """If given, close the sender account and send the remaining balance to this address, defaults to None"""
+
+
+@dataclass(kw_only=True, frozen=True)
+class AssetCreateParams(_CommonTxnParams):
+    """Parameters for creating a new asset."""
+
+    total: int
+    """The total amount of the smallest divisible unit to create"""
+    asset_name: str | None = None
+    """The full name of the asset"""
+    unit_name: str | None = None
+    """The short ticker name for the asset"""
+    url: str | None = None
+    """The metadata URL for the asset"""
+    decimals: int | None = None
+    """The amount of decimal places the asset should have"""
+    default_frozen: bool | None = None
+    """Whether the asset is frozen by default in the creator address"""
+    manager: str | None = None
+    """The address that can change the manager, reserve, clawback, and freeze addresses"""
+    reserve: str | None = None
+    """The address that holds the uncirculated supply"""
+    freeze: str | None = None
+    """The address that can freeze the asset in any account"""
+    clawback: str | None = None
+    """The address that can clawback the asset from any account"""
+    metadata_hash: bytes | None = None
+    """Hash of the metadata contained in the metadata URL"""
+
+
+@dataclass(kw_only=True, frozen=True)
+class AssetConfigParams(_CommonTxnParams):
+    """Parameters for configuring an existing asset."""
+
+    asset_id: int
+    """The ID of the asset"""
+    manager: str | None = None
+    """The address that can change the manager, reserve, clawback, and freeze addresses, defaults to None"""
+    reserve: str | None = None
+    """The address that holds the uncirculated supply, defaults to None"""
+    freeze: str | None = None
+    """The address that can freeze the asset in any account, defaults to None"""
+    clawback: str | None = None
+    """The address that can clawback the asset from any account, defaults to None"""
+
+
+@dataclass(kw_only=True, frozen=True)
+class AssetFreezeParams(_CommonTxnParams):
+    """Parameters for freezing an asset."""
+
+    asset_id: int
+    """The ID of the asset"""
+    account: str
+    """The account to freeze or unfreeze"""
+    frozen: bool
+    """Whether the assets in the account should be frozen"""
+
+
+@dataclass(kw_only=True, frozen=True)
+class AssetDestroyParams(_CommonTxnParams):
+    """Parameters for destroying an asset."""
+
+    asset_id: int
+    """The ID of the asset"""
+
+
+@dataclass(kw_only=True, frozen=True)
+class OnlineKeyRegistrationParams(_CommonTxnParams):
+    """Parameters for online key registration."""
+
+    vote_key: str
+    """The root participation public key"""
+    selection_key: str
+    """The VRF public key"""
+    vote_first: int
+    """The first round that the participation key is valid"""
+    vote_last: int
+    """The last round that the participation key is valid"""
+    vote_key_dilution: int
+    """The dilution for the 2-level participation key"""
+    state_proof_key: bytes | None = None
+    """The 64 byte state proof public key commitment, defaults to None"""
+
+
+@dataclass(kw_only=True, frozen=True)
+class OfflineKeyRegistrationParams(_CommonTxnParams):
+    """Parameters for offline key registration."""
+
+    prevent_account_from_ever_participating_again: bool
+    """Whether to prevent the account from ever participating again"""
+
+
+@dataclass(kw_only=True, frozen=True)
+class AssetTransferParams(_CommonTxnParams):
+    """Parameters for transferring an asset."""
+
+    asset_id: int
+    """The ID of the asset"""
+    amount: int
+    """The amount of the asset to transfer (smallest divisible unit)"""
+    receiver: str
+    """The account to send the asset to"""
+    clawback_target: str | None = None
+    """The account to take the asset from, defaults to None"""
+    close_asset_to: str | None = None
+    """The account to close the asset to, defaults to None"""
+
+
+@dataclass(kw_only=True, frozen=True)
+class AssetOptInParams(_CommonTxnParams):
+    """Parameters for opting into an asset."""
+
+    asset_id: int
+    """The ID of the asset"""
+
+
+@dataclass(kw_only=True, frozen=True)
+class AssetOptOutParams(_CommonTxnParams):
+    """Parameters for opting out of an asset."""
+
+    asset_id: int
+    """The ID of the asset"""
+    creator: str
+    """The creator address of the asset"""
+
+
+@dataclass(kw_only=True, frozen=True)
+class AppCallParams(_CommonTxnParams):
+    """Parameters for calling an application."""
+
+    on_complete: OnComplete
+    """The OnComplete action, defaults to None"""
+    app_id: int | None = None
+    """The ID of the application, defaults to None"""
+    approval_program: str | bytes | None = None
+    """The program to execute for all OnCompletes other than ClearState, defaults to None"""
+    clear_state_program: str | bytes | None = None
+    """The program to execute for ClearState OnComplete, defaults to None"""
+    schema: dict[str, int] | None = None
+    """The state schema for the app, defaults to None"""
+    args: list[bytes] | None = None
+    """Application arguments, defaults to None"""
+    account_references: list[str] | None = None
+    """Account references, defaults to None"""
+    app_references: list[int] | None = None
+    """App references, defaults to None"""
+    asset_references: list[int] | None = None
+    """Asset references, defaults to None"""
+    extra_pages: int | None = None
+    """Number of extra pages required for the programs, defaults to None"""
+    box_references: list[BoxReference | BoxIdentifier] | None = None
+    """Box references, defaults to None"""
+
+
+class AppCreateSchema(TypedDict):
+    global_ints: int
+    """The number of global ints in the schema"""
+    global_byte_slices: int
+    """The number of global byte slices in the schema"""
+    local_ints: int
+    """The number of local ints in the schema"""
+    local_byte_slices: int
+    """The number of local byte slices in the schema"""
+
+
+@dataclass(kw_only=True, frozen=True)
+class AppCreateParams(_CommonTxnParams):
+    """Parameters for creating an application."""
+
+    approval_program: str | bytes
+    """The program to execute for all OnCompletes other than ClearState"""
+    clear_state_program: str | bytes
+    """The program to execute for ClearState OnComplete"""
+    schema: AppCreateSchema | None = None
+    """The state schema for the app, defaults to None"""
+    on_complete: OnComplete | None = None
+    """The OnComplete action, defaults to None"""
+    args: list[bytes] | None = None
+    """Application arguments, defaults to None"""
+    account_references: list[str] | None = None
+    """Account references, defaults to None"""
+    app_references: list[int] | None = None
+    """App references, defaults to None"""
+    asset_references: list[int] | None = None
+    """Asset references, defaults to None"""
+    box_references: list[BoxReference | BoxIdentifier] | None = None
+    """Box references, defaults to None"""
+    extra_program_pages: int | None = None
+    """Number of extra pages required for the programs, defaults to None"""
+
+
+@dataclass(kw_only=True, frozen=True)
+class AppUpdateParams(_CommonTxnParams):
+    """Parameters for updating an application."""
+
+    app_id: int
+    """The ID of the application"""
+    approval_program: str | bytes
+    """The program to execute for all OnCompletes other than ClearState"""
+    clear_state_program: str | bytes
+    """The program to execute for ClearState OnComplete"""
+    args: list[bytes] | None = None
+    """Application arguments, defaults to None"""
+    account_references: list[str] | None = None
+    """Account references, defaults to None"""
+    app_references: list[int] | None = None
+    """App references, defaults to None"""
+    asset_references: list[int] | None = None
+    """Asset references, defaults to None"""
+    box_references: list[BoxReference | BoxIdentifier] | None = None
+    """Box references, defaults to None"""
+    on_complete: OnComplete | None = None
+    """The OnComplete action, defaults to None"""
+
+
+@dataclass(kw_only=True, frozen=True)
+class AppDeleteParams(_CommonTxnParams):
+    """Parameters for deleting an application."""
+
+    app_id: int
+    """The ID of the application"""
+    args: list[bytes] | None = None
+    """Application arguments, defaults to None"""
+    account_references: list[str] | None = None
+    """Account references, defaults to None"""
+    app_references: list[int] | None = None
+    """App references, defaults to None"""
+    asset_references: list[int] | None = None
+    """Asset references, defaults to None"""
+    box_references: list[BoxReference | BoxIdentifier] | None = None
+    """Box references, defaults to None"""
+    on_complete: OnComplete = OnComplete.DeleteApplicationOC
+    """The OnComplete action, defaults to DeleteApplicationOC"""
+
+
+@dataclass(kw_only=True, frozen=True)
+class _BaseAppMethodCall(_CommonTxnParams):
+    app_id: int
+    """The ID of the application"""
+    method: Method
+    """The ABI method to call"""
+    args: list | None = None
+    """Arguments to the ABI method, defaults to None"""
+    account_references: list[str] | None = None
+    """Account references, defaults to None"""
+    app_references: list[int] | None = None
+    """App references, defaults to None"""
+    asset_references: list[int] | None = None
+    """Asset references, defaults to None"""
+    box_references: list[BoxReference | BoxIdentifier] | None = None
+    """Box references, defaults to None"""
+    schema: AppCreateSchema | None = None
+    """The state schema for the app, defaults to None"""
+    on_complete: OnComplete | None = None
+    """The OnComplete action, defaults to None"""
+
+
+@dataclass(kw_only=True, frozen=True)
+class AppMethodCallParams(_CommonTxnParams):
+    """Parameters for calling an application method."""
+
+    app_id: int
+    """The ID of the application"""
+    method: Method
+    """The ABI method to call"""
+    args: list[bytes] | None = None
+    """Arguments to the ABI method, defaults to None"""
+    on_complete: OnComplete | None = None
+    """The OnComplete action, defaults to None"""
+    account_references: list[str] | None = None
+    """Account references, defaults to None"""
+    app_references: list[int] | None = None
+    """App references, defaults to None"""
+    asset_references: list[int] | None = None
+    """Asset references, defaults to None"""
+    box_references: list[BoxReference | BoxIdentifier] | None = None
+    """Box references, defaults to None"""
+
+
+@dataclass(kw_only=True, frozen=True)
+class AppCallMethodCallParams(_BaseAppMethodCall):
+    """Parameters for a regular ABI method call."""
+
+    app_id: int
+    """The ID of the application"""
+    on_complete: OnComplete | None = None
+    """The OnComplete action, defaults to None"""
+
+
+@dataclass(kw_only=True, frozen=True)
+class AppCreateMethodCallParams(_BaseAppMethodCall):
+    """Parameters for an ABI method call that creates an application."""
+
+    approval_program: str | bytes
+    """The program to execute for all OnCompletes other than ClearState"""
+    clear_state_program: str | bytes
+    """The program to execute for ClearState OnComplete"""
+    schema: AppCreateSchema | None = None
+    """The state schema for the app, defaults to None"""
+    on_complete: OnComplete | None = None
+    """The OnComplete action (cannot be ClearState), defaults to None"""
+    extra_program_pages: int | None = None
+    """Number of extra pages required for the programs, defaults to None"""
+
+
+@dataclass(kw_only=True, frozen=True)
+class AppUpdateMethodCallParams(_BaseAppMethodCall):
+    """Parameters for an ABI method call that updates an application."""
+
+    app_id: int
+    """The ID of the application"""
+    approval_program: str | bytes
+    """The program to execute for all OnCompletes other than ClearState"""
+    clear_state_program: str | bytes
+    """The program to execute for ClearState OnComplete"""
+    on_complete: OnComplete = OnComplete.UpdateApplicationOC
+    """The OnComplete action"""
+
+
+@dataclass(kw_only=True, frozen=True)
+class AppDeleteMethodCallParams(_BaseAppMethodCall):
+    """Parameters for an ABI method call that deletes an application."""
+
+    app_id: int
+    """The ID of the application"""
+    on_complete: OnComplete = OnComplete.DeleteApplicationOC
+    """The OnComplete action"""
+
+
+MethodCallParams = (
+    AppCallMethodCallParams | AppCreateMethodCallParams | AppUpdateMethodCallParams | AppDeleteMethodCallParams
+)
+
+
+AppMethodCallTransactionArgument = (
+    TransactionWithSigner
+    | algosdk.transaction.Transaction
+    | AppCreateMethodCallParams
+    | AppUpdateMethodCallParams
+    | AppCallMethodCallParams
+)
+
+
+TxnParams = Union[  # noqa: UP007
+    PaymentParams,
+    AssetCreateParams,
+    AssetConfigParams,
+    AssetFreezeParams,
+    AssetDestroyParams,
+    OnlineKeyRegistrationParams,
+    AssetTransferParams,
+    AssetOptInParams,
+    AssetOptOutParams,
+    AppCallParams,
+    AppCreateParams,
+    AppUpdateParams,
+    AppDeleteParams,
+    MethodCallParams,
+    OfflineKeyRegistrationParams,
+]
+
+
+@dataclass(frozen=True, kw_only=True)
+class TransactionContext:
+    """Contextual information for a transaction."""
+
+    max_fee: AlgoAmount | None = None
+    abi_method: Method | None = None
+
+    @staticmethod
+    def empty() -> TransactionContext:
+        return TransactionContext(max_fee=None, abi_method=None)
+
+
+class TransactionWithContext:
+    """Combines Transaction with additional context."""
+
+    def __init__(self, txn: algosdk.transaction.Transaction, context: TransactionContext):
+        self.txn = txn
+        self.context = context
+
+
+class TransactionWithSignerAndContext(TransactionWithSigner):
+    """Combines TransactionWithSigner with additional context."""
+
+    def __init__(self, txn: algosdk.transaction.Transaction, signer: TransactionSigner, context: TransactionContext):
+        super().__init__(txn, signer)
+        self.context = context
+
+    @staticmethod
+    def from_txn_with_context(
+        txn_with_context: TransactionWithContext, signer: TransactionSigner
+    ) -> TransactionWithSignerAndContext:
+        return TransactionWithSignerAndContext(
+            txn=txn_with_context.txn, signer=signer, context=txn_with_context.context
+        )
+
+
+@dataclass(frozen=True)
+class BuiltTransactions:
+    """Set of transactions built by TransactionComposer."""
+
+    transactions: list[algosdk.transaction.Transaction]
+    """The built transactions"""
+    method_calls: dict[int, Method]
+    """Map of transaction index to ABI method"""
+    signers: dict[int, TransactionSigner]
+    """Map of transaction index to TransactionSigner"""
+
+
+@dataclass
+class TransactionComposerBuildResult:
+    """Result of building transactions with TransactionComposer."""
+
+    atc: AtomicTransactionComposer
+    """The AtomicTransactionComposer instance"""
+    transactions: list[TransactionWithSigner]
+    """The list of transactions with signers"""
+    method_calls: dict[int, Method]
+    """Map of transaction index to ABI method"""
+
+
+@dataclass
+class SendAtomicTransactionComposerResults:
+    """Results from sending an AtomicTransactionComposer transaction group."""
+
+    group_id: str
+    """The group ID if this was a transaction group"""
+    confirmations: list[algosdk.v2client.algod.AlgodResponseType]
+    """The confirmation info for each transaction"""
+    tx_ids: list[str]
+    """The transaction IDs that were sent"""
+    transactions: list[TransactionWrapper]
+    """The transactions that were sent"""
+    returns: list[ABIReturn]
+    """The ABI return values from any ABI method calls"""
+    simulate_response: dict[str, Any] | None = None
+    """The simulation response if simulation was performed, defaults to None"""
+
+
+class UnnamedResourcesAccessed:
+    """Information about unnamed resource access."""
+
+    def __init__(self, resources_accessed: dict[str, Any] | None = None):
+        resources = resources_accessed or {}
+
+        if not isinstance(resources, dict):
+            raise TypeError(f"Expected dictionary object, got {type(resources_accessed)}")
+
+        self.accounts: list[str] | None = resources.get("accounts", None)
+        self.app_locals: list[dict[str, Any]] | None = resources.get("app-locals", None)
+        self.apps: list[int] | None = resources.get("apps", None)
+        self.asset_holdings: list[dict[str, Any]] | None = resources.get("asset-holdings", None)
+        self.assets: list[int] | None = resources.get("assets", None)
+        self.boxes: list[dict[str, Any]] | None = resources.get("boxes", None)
+        self.extra_box_refs: int | None = resources.get("extra-box-refs", None)
+
+
+@dataclass
+class ExecutionInfoTxn:
+    """Execution info for a transaction."""
+
+    unnamed_resources_accessed: UnnamedResourcesAccessed | None = None
+    """The unnamed resources accessed in the transaction"""
+    required_fee_delta: int = 0
+    """The required fee delta for the transaction"""
+
+
+@dataclass
+class ExecutionInfo:
+    """Information about transaction execution from simulation."""
+
+    group_unnamed_resources_accessed: UnnamedResourcesAccessed | None = None
+    """The unnamed resources accessed in the group"""
+    txns: list[ExecutionInfoTxn] | None = None
+    """The execution info for each transaction"""
+
+
+@dataclass
+class _TransactionWithPriority:
+    txn: algosdk.transaction.Transaction
+    priority: int
+    fee_delta: int
+    index: int
+
+
+MAX_LEASE_LENGTH = 32
+NULL_SIGNER: TransactionSigner = algosdk.atomic_transaction_composer.EmptySigner()
+
+
+def _encode_lease(lease: str | bytes | None) -> bytes | None:
+    if lease is None:
+        return None
+    elif isinstance(lease, bytes):
+        if not (1 <= len(lease) <= MAX_LEASE_LENGTH):
+            raise ValueError(
+                f"Received invalid lease; expected something with length between 1 and {MAX_LEASE_LENGTH}, "
+                f"but received bytes with length {len(lease)}"
+            )
+        if len(lease) == MAX_LEASE_LENGTH:
+            return lease
+        lease32 = bytearray(32)
+        lease32[: len(lease)] = lease
+        return bytes(lease32)
+    elif isinstance(lease, str):
+        encoded = lease.encode("utf-8")
+        if not (1 <= len(encoded) <= MAX_LEASE_LENGTH):
+            raise ValueError(
+                f"Received invalid lease; expected something with length between 1 and {MAX_LEASE_LENGTH}, "
+                f"but received '{lease}' with length {len(lease)}"
+            )
+        lease32 = bytearray(MAX_LEASE_LENGTH)
+        lease32[: len(encoded)] = encoded
+        return bytes(lease32)
+    else:
+        raise TypeError(f"Unknown lease type received of {type(lease)}")
+
+
+def _get_group_execution_info(  # noqa: C901, PLR0912
+    atc: AtomicTransactionComposer,
+    algod: AlgodClient,
+    populate_app_call_resources: bool | None = None,
+    cover_app_call_inner_transaction_fees: bool | None = None,
+    additional_atc_context: AdditionalAtcContext | None = None,
+) -> ExecutionInfo:
+    # Create simulation request
+    suggested_params = additional_atc_context.suggested_params if additional_atc_context else None
+    max_fees = additional_atc_context.max_fees if additional_atc_context else None
+
+    simulate_request = SimulateRequest(
+        txn_groups=[],
+        allow_unnamed_resources=True,
+        allow_empty_signatures=True,
+    )
+
+    # Clone ATC with null signers
+    empty_signer_atc = atc.clone()
+
+    # Track app call indexes without max fees
+    app_call_indexes_without_max_fees = []
+
+    # Copy transactions with null signers
+    for i, txn in enumerate(empty_signer_atc.txn_list):
+        txn_with_signer = TransactionWithSigner(txn=txn.txn, signer=NULL_SIGNER)
+
+        if cover_app_call_inner_transaction_fees and isinstance(txn.txn, algosdk.transaction.ApplicationCallTxn):
+            if not suggested_params:
+                raise ValueError("suggested_params required when cover_app_call_inner_transaction_fees enabled")
+
+            max_fee = max_fees.get(i).micro_algo if max_fees and i in max_fees else None  # type: ignore[union-attr]
+            if max_fee is None:
+                app_call_indexes_without_max_fees.append(i)
+            else:
+                txn_with_signer.txn.fee = max_fee
+
+    if cover_app_call_inner_transaction_fees and app_call_indexes_without_max_fees:
+        raise ValueError(
+            f"Please provide a `max_fee` for each app call transaction when `cover_app_call_inner_transaction_fees` is enabled. "  # noqa: E501
+            f"Required for transactions: {', '.join(str(i) for i in app_call_indexes_without_max_fees)}"
+        )
+
+    # Get fee parameters
+    per_byte_txn_fee = suggested_params.fee if suggested_params else 0
+    min_txn_fee = int(suggested_params.min_fee) if suggested_params else 1000  # type: ignore[unused-ignore]
+
+    # Simulate transactions
+    result = empty_signer_atc.simulate(algod, simulate_request)
+
+    group_response = result.simulate_response["txn-groups"][0]
+
+    if group_response.get("failure-message"):
+        msg = group_response["failure-message"]
+        if cover_app_call_inner_transaction_fees and "fee too small" in msg:
+            raise ValueError(
+                "Fees were too small to resolve execution info via simulate. "
+                "You may need to increase an app call transaction maxFee."
+            )
+        failed_at = group_response.get("failed-at", [0])[0]
+        raise ValueError(
+            f"Error resolving execution info via simulate in transaction {failed_at}: "
+            f"{group_response['failure-message']}"
+        )
+
+    # Build execution info
+    txn_results = []
+    for i, txn_result_raw in enumerate(group_response["txn-results"]):
+        txn_result = txn_result_raw.get("txn-result")
+        if not txn_result:
+            continue
+
+        original_txn = atc.build_group()[i].txn
+
+        required_fee_delta = 0
+        if cover_app_call_inner_transaction_fees:
+            # Calculate parent transaction fee
+            parent_per_byte_fee = per_byte_txn_fee * (original_txn.estimate_size() + 75)
+            parent_min_fee = max(parent_per_byte_fee, min_txn_fee)
+            parent_fee_delta = parent_min_fee - original_txn.fee
+
+            if isinstance(original_txn, algosdk.transaction.ApplicationCallTxn):
+                # Calculate inner transaction fees recursively
+                def calculate_inner_fee_delta(inner_txns: list[dict], acc: int = 0) -> int:
+                    for inner_txn in reversed(inner_txns):
+                        current_fee_delta = (
+                            calculate_inner_fee_delta(inner_txn["inner-txns"], acc)
+                            if inner_txn.get("inner-txns")
+                            else acc
+                        ) + (min_txn_fee - inner_txn["txn"]["txn"].get("fee", 0))
+                        acc = max(0, current_fee_delta)
+                    return acc
+
+                inner_fee_delta = calculate_inner_fee_delta(txn_result.get("inner-txns", []))
+                required_fee_delta = inner_fee_delta + parent_fee_delta
+            else:
+                required_fee_delta = parent_fee_delta
+
+        txn_results.append(
+            ExecutionInfoTxn(
+                unnamed_resources_accessed=UnnamedResourcesAccessed(txn_result_raw.get("unnamed-resources-accessed"))
+                if populate_app_call_resources
+                else None,
+                required_fee_delta=required_fee_delta,
+            )
+        )
+
+    return ExecutionInfo(
+        group_unnamed_resources_accessed=UnnamedResourcesAccessed(group_response.get("unnamed-resources-accessed"))
+        if populate_app_call_resources
+        else None,
+        txns=txn_results,
+    )
+
+
+def _find_available_transaction_index(
+    txns: list[TransactionWithSigner], reference_type: str, reference: str | dict[str, Any] | int
+) -> int:
+    """Find index of first transaction that can accommodate the new reference."""
+
+    def check_transaction(txn: TransactionWithSigner) -> bool:
+        # Skip if not an application call transaction
+        if txn.txn.type != "appl":
+            return False
+
+        # Get current counts (using get() with default 0 for Pythonic null handling)
+        accounts = len(getattr(txn.txn, "accounts", []) or [])
+        assets = len(getattr(txn.txn, "foreign_assets", []) or [])
+        apps = len(getattr(txn.txn, "foreign_apps", []) or [])
+        boxes = len(getattr(txn.txn, "boxes", []) or [])
+
+        # For account references, only check account limit
+        if reference_type == "account":
+            return accounts < MAX_APP_CALL_ACCOUNT_REFERENCES
+
+        # For asset holdings or local state, need space for both account and other reference
+        if reference_type in ("asset_holding", "app_local"):
+            return (
+                accounts + assets + apps + boxes < MAX_APP_CALL_FOREIGN_REFERENCES - 1
+                and accounts < MAX_APP_CALL_ACCOUNT_REFERENCES
+            )
+
+        # For boxes with non-zero app ID, need space for box and app reference
+        if reference_type == "box" and reference and int(getattr(reference, "app", 0)) != 0:
+            return accounts + assets + apps + boxes < MAX_APP_CALL_FOREIGN_REFERENCES - 1
+
+        # Default case - just check total references
+        return accounts + assets + apps + boxes < MAX_APP_CALL_FOREIGN_REFERENCES
+
+    # Return first matching index or -1 if none found
+    return next((i for i, txn in enumerate(txns) if check_transaction(txn)), -1)
+
+
+def calculate_extra_program_pages(approval: bytes | None, clear: bytes | None) -> int:
+    """Calculate minimum number of extra_pages required for provided approval and clear programs"""
+    total = len(approval or b"") + len(clear or b"")
+    return max(0, (total - 1) // algosdk.constants.APP_PAGE_MAX_SIZE)
+
+
+def populate_app_call_resources(atc: AtomicTransactionComposer, algod: AlgodClient) -> AtomicTransactionComposer:
+    """Populate application call resources based on simulation results.
+
+    :param atc: The AtomicTransactionComposer containing transactions
+    :param algod: Algod client for simulation
+    :return: Modified AtomicTransactionComposer with populated resources
+    """
+    return prepare_group_for_sending(atc, algod, populate_app_call_resources=True)
+
+
+def prepare_group_for_sending(  # noqa: C901, PLR0912, PLR0915
+    atc: AtomicTransactionComposer,
+    algod: AlgodClient,
+    populate_app_call_resources: bool | None = None,
+    cover_app_call_inner_transaction_fees: bool | None = None,
+    additional_atc_context: AdditionalAtcContext | None = None,
+) -> AtomicTransactionComposer:
+    """Prepare a transaction group for sending by handling execution info and resources.
+
+    :param atc: The AtomicTransactionComposer containing transactions
+    :param algod: Algod client for simulation
+    :param populate_app_call_resources: Whether to populate app call resources
+    :param cover_app_call_inner_transaction_fees: Whether to cover inner txn fees
+    :param additional_atc_context: Additional context for the AtomicTransactionComposer
+    :return: Modified AtomicTransactionComposer ready for sending
+    """
+    # Get execution info via simulation
+    execution_info = _get_group_execution_info(
+        atc, algod, populate_app_call_resources, cover_app_call_inner_transaction_fees, additional_atc_context
+    )
+    max_fees = additional_atc_context.max_fees if additional_atc_context else None
+
+    group = atc.build_group()
+
+    # Handle transaction fees if needed
+    if cover_app_call_inner_transaction_fees:
+        # Sort transactions by fee priority
+        txns_with_priority: list[_TransactionWithPriority] = []
+        for i, txn_info in enumerate(execution_info.txns or []):
+            if not txn_info:
+                continue
+            txn = group[i].txn
+            max_fee = max_fees.get(i).micro_algo if max_fees and i in max_fees else None  # type: ignore[union-attr]
+            immutable_fee = max_fee is not None and max_fee == txn.fee
+            priority_multiplier = (
+                1000
+                if (
+                    txn_info.required_fee_delta > 0
+                    and (immutable_fee or not isinstance(txn, algosdk.transaction.ApplicationCallTxn))
+                )
+                else 1
+            )
+
+            txns_with_priority.append(
+                _TransactionWithPriority(
+                    txn=txn,
+                    index=i,
+                    fee_delta=txn_info.required_fee_delta,
+                    priority=txn_info.required_fee_delta * priority_multiplier
+                    if txn_info.required_fee_delta > 0
+                    else -1,
+                )
+            )
+
+        # Sort by priority descending
+        txns_with_priority.sort(key=lambda x: x.priority, reverse=True)
+
+        # Calculate surplus fees and additional fees needed
+        surplus_fees = sum(
+            txn_info.required_fee_delta * -1
+            for txn_info in execution_info.txns or []
+            if txn_info is not None and txn_info.required_fee_delta < 0
+        )
+
+        additional_fees = {}
+
+        # Distribute surplus fees to cover deficits
+        for txn_obj in txns_with_priority:
+            if txn_obj.fee_delta > 0:
+                if surplus_fees >= txn_obj.fee_delta:
+                    surplus_fees -= txn_obj.fee_delta
+                else:
+                    additional_fees[txn_obj.index] = txn_obj.fee_delta - surplus_fees
+                    surplus_fees = 0
+
+    def populate_group_resource(  # noqa: PLR0915, PLR0912, C901
+        txns: list[TransactionWithSigner], reference: str | dict[str, Any] | int, ref_type: str
+    ) -> None:
+        """Helper function to populate group-level resources."""
+
+        def is_appl_below_limit(t: TransactionWithSigner) -> bool:
+            if not isinstance(t.txn, transaction.ApplicationCallTxn):
+                return False
+
+            accounts = len(getattr(t.txn, "accounts", []) or [])
+            assets = len(getattr(t.txn, "foreign_assets", []) or [])
+            apps = len(getattr(t.txn, "foreign_apps", []) or [])
+            boxes = len(getattr(t.txn, "boxes", []) or [])
+
+            return accounts + assets + apps + boxes < MAX_APP_CALL_FOREIGN_REFERENCES
+
+        # Handle asset holding and app local references first
+        if ref_type in ("assetHolding", "appLocal"):
+            ref_dict = cast(dict[str, Any], reference)
+            account = ref_dict["account"]
+
+            # First try to find transaction with account already available
+            txn_idx = next(
+                (
+                    i
+                    for i, t in enumerate(txns)
+                    if is_appl_below_limit(t)
+                    and isinstance(t.txn, transaction.ApplicationCallTxn)
+                    and (
+                        account in (getattr(t.txn, "accounts", []) or [])
+                        or account
+                        in (
+                            logic.get_application_address(app_id)
+                            for app_id in (getattr(t.txn, "foreign_apps", []) or [])
+                        )
+                        or any(str(account) in str(v) for v in t.txn.__dict__.values())
+                    )
+                ),
+                -1,
+            )
+
+            if txn_idx >= 0:
+                app_txn = cast(transaction.ApplicationCallTxn, txns[txn_idx].txn)
+                if ref_type == "assetHolding":
+                    asset_id = ref_dict["asset"]
+                    app_txn.foreign_assets = [*list(getattr(app_txn, "foreign_assets", []) or []), asset_id]
+                else:
+                    app_id = ref_dict["app"]
+                    app_txn.foreign_apps = [*list(getattr(app_txn, "foreign_apps", []) or []), app_id]
+                return
+
+            # Try to find transaction that already has the app/asset available
+            txn_idx = next(
+                (
+                    i
+                    for i, t in enumerate(txns)
+                    if is_appl_below_limit(t)
+                    and isinstance(t.txn, transaction.ApplicationCallTxn)
+                    and len(getattr(t.txn, "accounts", []) or []) < MAX_APP_CALL_ACCOUNT_REFERENCES
+                    and (
+                        (
+                            ref_type == "assetHolding"
+                            and ref_dict["asset"] in (getattr(t.txn, "foreign_assets", []) or [])
+                        )
+                        or (
+                            ref_type == "appLocal"
+                            and (
+                                ref_dict["app"] in (getattr(t.txn, "foreign_apps", []) or [])
+                                or t.txn.index == ref_dict["app"]
+                            )
+                        )
+                    )
+                ),
+                -1,
+            )
+
+            if txn_idx >= 0:
+                app_txn = cast(transaction.ApplicationCallTxn, txns[txn_idx].txn)
+                accounts = list(getattr(app_txn, "accounts", []) or [])
+                accounts.append(account)
+                app_txn.accounts = accounts
+                return
+
+        # Handle box references
+        if ref_type == "box":
+            box_ref = (reference["app"], base64.b64decode(reference["name"]))  # type: ignore[index]
+
+            # Try to find transaction that already has the app available
+            txn_idx = next(
+                (
+                    i
+                    for i, t in enumerate(txns)
+                    if is_appl_below_limit(t)
+                    and isinstance(t.txn, transaction.ApplicationCallTxn)
+                    and (box_ref[0] in (getattr(t.txn, "foreign_apps", []) or []) or t.txn.index == box_ref[0])
+                ),
+                -1,
+            )
+
+            if txn_idx >= 0:
+                app_txn = cast(transaction.ApplicationCallTxn, txns[txn_idx].txn)
+                boxes = list(getattr(app_txn, "boxes", []) or [])
+                boxes.append(BoxReference.translate_box_reference(box_ref, app_txn.foreign_apps or [], app_txn.index))  # type: ignore[arg-type]
+                app_txn.boxes = boxes
+                return
+
+        # Find available transaction for the resource
+        txn_idx = _find_available_transaction_index(txns, ref_type, reference)
+
+        if txn_idx == -1:
+            raise ValueError("No more transactions below reference limit. Add another app call to the group.")
+
+        app_txn = cast(transaction.ApplicationCallTxn, txns[txn_idx].txn)
+
+        if ref_type == "account":
+            accounts = list(getattr(app_txn, "accounts", []) or [])
+            accounts.append(cast(str, reference))
+            app_txn.accounts = accounts
+        elif ref_type == "app":
+            app_id = int(cast(str | int, reference))
+            foreign_apps = list(getattr(app_txn, "foreign_apps", []) or [])
+            foreign_apps.append(app_id)
+            app_txn.foreign_apps = foreign_apps
+        elif ref_type == "box":
+            boxes = list(getattr(app_txn, "boxes", []) or [])
+            boxes.append(BoxReference.translate_box_reference(box_ref, app_txn.foreign_apps or [], app_txn.index))  # type: ignore[arg-type]
+            app_txn.boxes = boxes
+            if box_ref[0] != 0:
+                foreign_apps = list(getattr(app_txn, "foreign_apps", []) or [])
+                foreign_apps.append(box_ref[0])
+                app_txn.foreign_apps = foreign_apps
+        elif ref_type == "asset":
+            asset_id = int(cast(str | int, reference))
+            foreign_assets = list(getattr(app_txn, "foreign_assets", []) or [])
+            foreign_assets.append(asset_id)
+            app_txn.foreign_assets = foreign_assets
+        elif ref_type == "assetHolding":
+            ref_dict = cast(dict[str, Any], reference)
+            foreign_assets = list(getattr(app_txn, "foreign_assets", []) or [])
+            foreign_assets.append(ref_dict["asset"])
+            app_txn.foreign_assets = foreign_assets
+            accounts = list(getattr(app_txn, "accounts", []) or [])
+            accounts.append(ref_dict["account"])
+            app_txn.accounts = accounts
+        elif ref_type == "appLocal":
+            ref_dict = cast(dict[str, Any], reference)
+            foreign_apps = list(getattr(app_txn, "foreign_apps", []) or [])
+            foreign_apps.append(ref_dict["app"])
+            app_txn.foreign_apps = foreign_apps
+            accounts = list(getattr(app_txn, "accounts", []) or [])
+            accounts.append(ref_dict["account"])
+            app_txn.accounts = accounts
+
+    # Process transaction-level resources
+    for i, txn_info in enumerate(execution_info.txns or []):
+        if not txn_info:
+            continue
+
+        # Validate no unexpected resources
+        is_app_txn = isinstance(group[i].txn, algosdk.transaction.ApplicationCallTxn)
+        resources = txn_info.unnamed_resources_accessed
+        if resources and is_app_txn:
+            app_txn = group[i].txn
+            if resources.boxes or resources.extra_box_refs:
+                raise ValueError("Unexpected boxes at transaction level")
+            if resources.app_locals:
+                raise ValueError("Unexpected app local at transaction level")
+            if resources.asset_holdings:
+                raise ValueError("Unexpected asset holding at transaction level")
+
+            # Update application call fields
+            accounts = list(getattr(app_txn, "accounts", []) or [])
+            foreign_apps = list(getattr(app_txn, "foreign_apps", []) or [])
+            foreign_assets = list(getattr(app_txn, "foreign_assets", []) or [])
+            boxes = list(getattr(app_txn, "boxes", []) or [])
+
+            # Add new resources
+            accounts.extend(resources.accounts or [])
+            foreign_apps.extend(resources.apps or [])
+            foreign_assets.extend(resources.assets or [])
+            boxes.extend(resources.boxes or [])
+
+            # Validate limits
+            if len(accounts) > MAX_APP_CALL_ACCOUNT_REFERENCES:
+                raise ValueError(
+                    f"Account reference limit of {MAX_APP_CALL_ACCOUNT_REFERENCES} exceeded in transaction {i}"
+                )
+
+            total_refs = len(accounts) + len(foreign_assets) + len(foreign_apps) + len(boxes)
+            if total_refs > MAX_APP_CALL_FOREIGN_REFERENCES:
+                raise ValueError(
+                    f"Resource reference limit of {MAX_APP_CALL_FOREIGN_REFERENCES} exceeded in transaction {i}"
+                )
+
+            # Update transaction
+            app_txn.accounts = accounts  # type: ignore[attr-defined]
+            app_txn.foreign_apps = foreign_apps  # type: ignore[attr-defined]
+            app_txn.foreign_assets = foreign_assets  # type: ignore[attr-defined]
+            app_txn.boxes = boxes  # type: ignore[attr-defined]
+
+        # Update fees if needed
+        if cover_app_call_inner_transaction_fees and i in additional_fees:
+            cur_txn = group[i].txn
+            additional_fee = additional_fees[i]
+            if not isinstance(cur_txn, algosdk.transaction.ApplicationCallTxn):
+                raise ValueError(
+                    f"An additional fee of {additional_fee} µALGO is required for non app call transaction {i}"
+                )
+
+            transaction_fee = cur_txn.fee + additional_fee
+            max_fee = max_fees.get(i).micro_algo if max_fees and i in max_fees else None  # type: ignore[union-attr]
+
+            if max_fee is None or transaction_fee > max_fee:
+                raise ValueError(
+                    f"Calculated transaction fee {transaction_fee} µALGO is greater "
+                    f"than max of {max_fee or 'undefined'} "
+                    f"for transaction {i}"
+                )
+            cur_txn.fee = transaction_fee
+
+    # Process group-level resources
+    group_resources = execution_info.group_unnamed_resources_accessed
+    if group_resources:
+        # Handle cross-reference resources first
+        for app_local in group_resources.app_locals or []:
+            populate_group_resource(group, app_local, "appLocal")
+            # Remove processed resources
+            if group_resources.accounts:
+                group_resources.accounts = [acc for acc in group_resources.accounts if acc != app_local["account"]]
+            if group_resources.apps:
+                group_resources.apps = [app for app in group_resources.apps if int(app) != int(app_local["app"])]
+
+        for asset_holding in group_resources.asset_holdings or []:
+            populate_group_resource(group, asset_holding, "assetHolding")
+            # Remove processed resources
+            if group_resources.accounts:
+                group_resources.accounts = [acc for acc in group_resources.accounts if acc != asset_holding["account"]]
+            if group_resources.assets:
+                group_resources.assets = [
+                    asset for asset in group_resources.assets if int(asset) != int(asset_holding["asset"])
+                ]
+
+        # Handle remaining resources
+        for account in group_resources.accounts or []:
+            populate_group_resource(group, account, "account")
+
+        for box in group_resources.boxes or []:
+            populate_group_resource(group, box, "box")
+            if group_resources.apps:
+                group_resources.apps = [app for app in group_resources.apps if int(app) != int(box["app"])]
+
+        for asset in group_resources.assets or []:
+            populate_group_resource(group, asset, "asset")
+
+        for app in group_resources.apps or []:
+            populate_group_resource(group, app, "app")
+
+        # Handle extra box references
+        extra_box_refs = group_resources.extra_box_refs or 0
+        for _ in range(extra_box_refs):
+            populate_group_resource(group, {"app": 0, "name": ""}, "box")
+
+    # Create new ATC with updated transactions
+    new_atc = AtomicTransactionComposer()
+    for txn_with_signer in group:
+        txn_with_signer.txn.group = None
+        new_atc.add_transaction(txn_with_signer)
+    new_atc.method_dict = deepcopy(atc.method_dict)
+
+    return new_atc
+
+
+def send_atomic_transaction_composer(  # noqa: C901, PLR0912
+    atc: AtomicTransactionComposer,
+    algod: AlgodClient,
+    *,
+    max_rounds_to_wait: int | None = 5,
+    skip_waiting: bool = False,
+    suppress_log: bool | None = None,
+    populate_app_call_resources: bool | None = None,
+    cover_app_call_inner_transaction_fees: bool | None = None,
+    additional_atc_context: AdditionalAtcContext | None = None,
+) -> SendAtomicTransactionComposerResults:
+    """Send an AtomicTransactionComposer transaction group.
+
+    Executes a group of transactions atomically using the AtomicTransactionComposer.
+
+    :param atc: The AtomicTransactionComposer instance containing the transaction group to send
+    :param algod: The Algod client to use for sending the transactions
+    :param max_rounds_to_wait: Maximum number of rounds to wait for confirmation, defaults to 5
+    :param skip_waiting: If True, don't wait for transaction confirmation, defaults to False
+    :param suppress_log: If True, suppress logging, defaults to None
+    :param populate_app_call_resources: If True, populate app call resources, defaults to None
+    :param cover_app_call_inner_transaction_fees: If True, cover app call inner transaction fees, defaults to None
+    :param additional_atc_context: Additional context for the AtomicTransactionComposer
+    :return: Results from sending the transaction group
+    :raises Exception: If there is an error sending the transactions
+    :raises error: If there is an error from the Algorand node
+    """
+    from algokit_utils._debugging import simulate_and_persist_response, simulate_response
+
+    try:
+        # Build transactions
+        transactions_with_signer = atc.build_group()
+
+        populate_app_call_resources = (
+            populate_app_call_resources
+            if populate_app_call_resources is not None
+            else config.populate_app_call_resource
+        )
+
+        if (populate_app_call_resources or cover_app_call_inner_transaction_fees) and any(
+            isinstance(t.txn, algosdk.transaction.ApplicationCallTxn) for t in transactions_with_signer
+        ):
+            atc = prepare_group_for_sending(
+                atc,
+                algod,
+                populate_app_call_resources,
+                cover_app_call_inner_transaction_fees,
+                additional_atc_context,
+            )
+
+        transactions_to_send = [t.txn for t in transactions_with_signer]
+
+        # Get group ID if multiple transactions
+        group_id = None
+        if len(transactions_to_send) > 1:
+            group_id = (
+                base64.b64encode(transactions_to_send[0].group).decode("utf-8") if transactions_to_send[0].group else ""
+            )
+
+            if not suppress_log:
+                logger.info(
+                    f"Sending group of {len(transactions_to_send)} transactions ({group_id})",
+                    extra={"suppress_log": suppress_log or False},
+                )
+                logger.debug(
+                    f"Transaction IDs ({group_id}): {[t.get_txid() for t in transactions_to_send]}",
+                    extra={"suppress_log": suppress_log or False},
+                )
+
+        # Simulate if debug enabled
+        if config.debug and config.trace_all and config.project_root:
+            simulate_and_persist_response(
+                atc,
+                config.project_root,
+                algod,
+                config.trace_buffer_size_mb,
+            )
+
+        # Execute transactions
+        result = atc.execute(algod, wait_rounds=max_rounds_to_wait or 5)
+
+        # Log results
+        if not suppress_log:
+            if len(transactions_to_send) > 1:
+                logger.info(
+                    f"Group transaction ({group_id}) sent with {len(transactions_to_send)} transactions",
+                    extra={"suppress_log": suppress_log or False},
+                )
+            else:
+                logger.info(
+                    f"Sent transaction ID {transactions_to_send[0].get_txid()}",
+                    extra={"suppress_log": suppress_log or False},
+                )
+
+        # Get confirmations if not skipping
+        confirmations = None
+        if not skip_waiting:
+            confirmations = [algod.pending_transaction_info(t.get_txid()) for t in transactions_to_send]
+
+        # Return results
+        return SendAtomicTransactionComposerResults(
+            group_id=group_id or "",
+            confirmations=confirmations or [],
+            tx_ids=[t.get_txid() for t in transactions_to_send],
+            transactions=[TransactionWrapper(t) for t in transactions_to_send],
+            returns=[ABIReturn(r) for r in result.abi_results],
+        )
+
+    except Exception as e:
+        # Handle error with debug info if enabled
+        if config.debug:
+            logger.error(
+                "Received error executing Atomic Transaction Composer and debug flag enabled; "
+                "attempting simulation to get more information ",
+                extra={"suppress_log": suppress_log or False},
+                exc_info=e,
+            )
+
+            simulate = None
+            if config.project_root and not config.trace_all:
+                # Only simulate if trace_all is disabled and project_root is set
+                simulate = simulate_and_persist_response(atc, config.project_root, algod, config.trace_buffer_size_mb)
+            else:
+                simulate = simulate_response(atc, algod)
+
+            traces = []
+            if simulate and simulate.failed_at:
+                for txn_group in simulate.simulate_response["txn-groups"]:
+                    app_budget = txn_group.get("app-budget-added")
+                    app_budget_consumed = txn_group.get("app-budget-consumed")
+                    failure_message = txn_group.get("failure-message")
+                    txn_result = txn_group.get("txn-results", [{}])[0]
+                    exec_trace = txn_result.get("exec-trace", {})
+
+                    traces.append(
+                        {
+                            "trace": exec_trace,
+                            "app_budget": app_budget,
+                            "app_budget_consumed": app_budget_consumed,
+                            "failure_message": failure_message,
+                        }
+                    )
+
+            error = Exception(f"Transaction failed: {e}")
+            error.traces = traces  # type: ignore[attr-defined]
+            raise error from e
+
+        logger.error(
+            "Received error executing Atomic Transaction Composer, for more information enable the debug flag",
+            extra={"suppress_log": suppress_log or False},
+            exc_info=e,
+        )
+        raise e
+
+
+class TransactionComposer:
+    """A class for composing and managing Algorand transactions.
+
+    Provides a high-level interface for building and executing transaction groups using the Algosdk library.
+    Supports various transaction types including payments, asset operations, application calls, and key registrations.
+
+    :param algod: An instance of AlgodClient used to get suggested params and send transactions
+    :param get_signer: A function that takes an address and returns a TransactionSigner for that address
+    :param get_suggested_params: Optional function to get suggested transaction parameters,
+        defaults to using algod.suggested_params()
+    :param default_validity_window: Optional default validity window for transactions in rounds, defaults to 10
+    :param app_manager: Optional AppManager instance for compiling TEAL programs, defaults to None
+    """
+
+    def __init__(
+        self,
+        algod: AlgodClient,
+        get_signer: Callable[[str], TransactionSigner],
+        get_suggested_params: Callable[[], algosdk.transaction.SuggestedParams] | None = None,
+        default_validity_window: int | None = None,
+        app_manager: AppManager | None = None,
+    ):
+        # Map of transaction index in the atc to a max logical fee.
+        # This is set using the value of either maxFee or staticFee.
+        self._txn_max_fees: dict[int, AlgoAmount] = {}
+        self._txns: list[TransactionWithSigner | TxnParams | AtomicTransactionComposer] = []
+        self._atc: AtomicTransactionComposer = AtomicTransactionComposer()
+        self._algod: AlgodClient = algod
+        self._default_get_send_params = lambda: self._algod.suggested_params()
+        self._get_suggested_params = get_suggested_params or self._default_get_send_params
+        self._get_signer: Callable[[str], TransactionSigner] = get_signer
+        self._default_validity_window: int = default_validity_window or 10
+        self._default_validity_window_is_explicit: bool = default_validity_window is not None
+        self._app_manager = app_manager or AppManager(algod)
+
+    def add_transaction(
+        self, transaction: algosdk.transaction.Transaction, signer: TransactionSigner | None = None
+    ) -> TransactionComposer:
+        """Add a raw transaction to the composer.
+
+        :param transaction: The transaction to add
+        :param signer: Optional transaction signer, defaults to getting signer from transaction sender
+        :return: The transaction composer instance for chaining
+
+        :example:
+            >>> composer.add_transaction(transaction)
+        """
+        self._txns.append(TransactionWithSigner(txn=transaction, signer=signer or self._get_signer(transaction.sender)))
+        return self
+
+    def add_payment(self, params: PaymentParams) -> TransactionComposer:
+        """Add a payment transaction.
+
+        :example:
+            >>> params = PaymentParams(
+            ...     sender="SENDER_ADDRESS",
+            ...     receiver="RECEIVER_ADDRESS",
+            ...     amount=AlgoAmount.from_algo(1),
+            ...     close_remainder_to="CLOSE_ADDRESS"
+            ...     ... (see PaymentParams for more options)
+            ... )
+            >>> composer.add_payment(params)
+
+        :param params: The payment transaction parameters
+        :return: The transaction composer instance for chaining
+        """
+        self._txns.append(params)
+        return self
+
+    def add_asset_create(self, params: AssetCreateParams) -> TransactionComposer:
+        """Add an asset creation transaction.
+
+        :example:
+            >>> params = AssetCreateParams(
+            ...     sender="SENDER_ADDRESS",
+            ...     total=1000,
+            ...     asset_name="MyAsset",
+            ...     unit_name="MA",
+            ...     url="https://example.com",
+            ...     decimals=0,
+            ...     default_frozen=False,
+            ...     manager="MANAGER_ADDRESS",
+            ...     reserve="RESERVE_ADDRESS",
+            ...     freeze="FREEZE_ADDRESS",
+            ...     clawback="CLAWBACK_ADDRESS"
+            ...     ... (see AssetCreateParams for more options)
+            >>> composer.add_asset_create(params)
+
+        :param params: The asset creation parameters
+        :return: The transaction composer instance for chaining
+        """
+        self._txns.append(params)
+        return self
+
+    def add_asset_config(self, params: AssetConfigParams) -> TransactionComposer:
+        """Add an asset configuration transaction.
+
+        :example:
+            >>> params = AssetConfigParams(
+            ...     sender="SENDER_ADDRESS",
+            ...     asset_id=123456,
+            ...     manager="NEW_MANAGER_ADDRESS",
+            ...     reserve="NEW_RESERVE_ADDRESS",
+            ...     freeze="NEW_FREEZE_ADDRESS",
+            ...     clawback="NEW_CLAWBACK_ADDRESS"
+            ...     ... (see AssetConfigParams for more options)
+            ... )
+            >>> composer.add_asset_config(params)
+
+        :param params: The asset configuration parameters
+        :return: The transaction composer instance for chaining
+        """
+        self._txns.append(params)
+        return self
+
+    def add_asset_freeze(self, params: AssetFreezeParams) -> TransactionComposer:
+        """Add an asset freeze transaction.
+
+        :example:
+            >>> params = AssetFreezeParams(
+            ...     sender="SENDER_ADDRESS",
+            ...     asset_id=123456,
+            ...     account="ACCOUNT_TO_FREEZE",
+            ...     frozen=True
+            ...     ... (see AssetFreezeParams for more options)
+            ... )
+            >>> composer.add_asset_freeze(params)
+
+        :param params: The asset freeze parameters
+        :return: The transaction composer instance for chaining
+        """
+        self._txns.append(params)
+        return self
+
+    def add_asset_destroy(self, params: AssetDestroyParams) -> TransactionComposer:
+        """Add an asset destruction transaction.
+
+        :example:
+            >>> params = AssetDestroyParams(
+            ...     sender="SENDER_ADDRESS",
+            ...     asset_id=123456
+            ...     ... (see AssetDestroyParams for more options)
+            >>> composer.add_asset_destroy(params)
+
+        :param params: The asset destruction parameters
+        :return: The transaction composer instance for chaining
+        """
+        self._txns.append(params)
+        return self
+
+    def add_asset_transfer(self, params: AssetTransferParams) -> TransactionComposer:
+        """Add an asset transfer transaction.
+
+        :example:
+            >>> params = AssetTransferParams(
+            ...     sender="SENDER_ADDRESS",
+            ...     asset_id=123456,
+            ...     amount=10,
+            ...     receiver="RECEIVER_ADDRESS",
+            ...     clawback_target="CLAWBACK_TARGET_ADDRESS",
+            ...     close_asset_to="CLOSE_ADDRESS"
+            ...     ... (see AssetTransferParams for more options)
+            >>> composer.add_asset_transfer(params)
+
+        :param params: The asset transfer parameters
+        :return: The transaction composer instance for chaining
+        """
+        self._txns.append(params)
+        return self
+
+    def add_asset_opt_in(self, params: AssetOptInParams) -> TransactionComposer:
+        """Add an asset opt-in transaction.
+
+        :example:
+            >>> params = AssetOptInParams(
+            ...     sender="SENDER_ADDRESS",
+            ...     asset_id=123456
+            ...     ... (see AssetOptInParams for more options)
+            ... )
+            >>> composer.add_asset_opt_in(params)
+
+        :param params: The asset opt-in parameters
+        :return: The transaction composer instance for chaining
+        """
+        self._txns.append(params)
+        return self
+
+    def add_asset_opt_out(self, params: AssetOptOutParams) -> TransactionComposer:
+        """Add an asset opt-out transaction.
+
+        :example:
+            >>> params = AssetOptOutParams(
+            ...     sender="SENDER_ADDRESS",
+            ...     asset_id=123456,
+            ...     creator="CREATOR_ADDRESS"
+            ...     ... (see AssetOptOutParams for more options)
+            >>> composer.add_asset_opt_out(params)
+
+        :param params: The asset opt-out parameters
+        :return: The transaction composer instance for chaining
+        """
+        self._txns.append(params)
+        return self
+
+    def add_app_create(self, params: AppCreateParams) -> TransactionComposer:
+        """Add an application creation transaction.
+
+        :example:
+            >>> params = AppCreateParams(
+            ...     sender="SENDER_ADDRESS",
+            ...     approval_program="TEAL_APPROVAL_CODE",
+            ...     clear_state_program="TEAL_CLEAR_CODE",
+            ...     schema={'global_ints': 1, 'global_byte_slices': 1, 'local_ints': 1, 'local_byte_slices': 1},
+            ...     on_complete=OnComplete.NoOpOC,
+            ...     args=[b'arg1'],
+            ...     account_references=["ACCOUNT1"],
+            ...     app_references=[789],
+            ...     asset_references=[123],
+            ...     box_references=[],
+            ...     extra_program_pages=0
+            ...     ... (see AppCreateParams for more options)
+            ... )
+            >>> composer.add_app_create(params)
+
+        :param params: The application creation parameters
+        :return: The transaction composer instance for chaining
+        """
+        self._txns.append(params)
+        return self
+
+    def add_app_update(self, params: AppUpdateParams) -> TransactionComposer:
+        """Add an application update transaction.
+
+        :example:
+            >>> params = AppUpdateParams(
+            ...     sender="SENDER_ADDRESS",
+            ...     app_id=789,
+            ...     approval_program="TEAL_NEW_APPROVAL_CODE",
+            ...     clear_state_program="TEAL_NEW_CLEAR_CODE",
+            ...     args=[b'new_arg1'],
+            ...     account_references=["ACCOUNT1"],
+            ...     app_references=[789],
+            ...     asset_references=[123],
+            ...     box_references=[],
+            ...     on_complete=OnComplete.UpdateApplicationOC
+            ...     ... (see AppUpdateParams for more options)
+            >>> composer.add_app_update(params)
+
+        :param params: The application update parameters
+        :return: The transaction composer instance for chaining
+        """
+        self._txns.append(params)
+        return self
+
+    def add_app_delete(self, params: AppDeleteParams) -> TransactionComposer:
+        """Add an application deletion transaction.
+
+        :example:
+            >>> params = AppDeleteParams(
+            ...     sender="SENDER_ADDRESS",
+            ...     app_id=789,
+            ...     args=[b'delete_arg'],
+            ...     account_references=["ACCOUNT1"],
+            ...     app_references=[789],
+            ...     asset_references=[123],
+            ...     box_references=[],
+            ...     on_complete=OnComplete.DeleteApplicationOC
+            ...     ... (see AppDeleteParams for more options)
+            >>> composer.add_app_delete(params)
+
+        :param params: The application deletion parameters
+        :return: The transaction composer instance for chaining
+        """
+        self._txns.append(params)
+        return self
+
+    def add_app_call(self, params: AppCallParams) -> TransactionComposer:
+        """Add an application call transaction.
+
+        :example:
+            >>> params = AppCallParams(
+            ...     sender="SENDER_ADDRESS",
+            ...     on_complete=OnComplete.NoOpOC,
+            ...     app_id=789,
+            ...     approval_program="TEAL_APPROVAL_CODE",
+            ...     clear_state_program="TEAL_CLEAR_CODE",
+            ...     schema={'global_ints': 1, 'global_byte_slices': 1, 'local_ints': 1, 'local_byte_slices': 1},
+            ...     ... (see AppCallParams for more options)
+            ... )
+            >>> composer.add_app_call(params)
+
+        :param params: The application call parameters
+        :return: The transaction composer instance for chaining
+        """
+        self._txns.append(params)
+        return self
+
+    def add_app_create_method_call(self, params: AppCreateMethodCallParams) -> TransactionComposer:
+        """Add an application creation method call transaction.
+
+        :param params: The application creation method call parameters
+        :return: The transaction composer instance for chaining
+
+        :example:
+            >>> # Basic example
+            >>> method = algosdk.abi.Method(
+            ...     name="method",
+            ...     args=[...],
+            ...     returns="string"
+            ... )
+            >>> composer.add_app_create_method_call(
+            ...     AppCreateMethodCallParams(
+            ...         sender="CREATORADDRESS",
+            ...         approval_program="TEALCODE",
+            ...         clear_state_program="TEALCODE",
+            ...         method=method,
+            ...         args=["arg1_value"]
+            ...     )
+            ... )
+            >>>
+            >>> # Advanced example
+            >>> method = ABIMethod(
+            ...     name="method",
+            ...     args=[{"name": "arg1", "type": "string"}],
+            ...     returns={"type": "string"}
+            ... )
+            >>> composer.add_app_create_method_call(
+            ...     AppCreateMethodCallParams(
+            ...         sender="CREATORADDRESS",
+            ...         method=method,
+            ...         args=["arg1_value"],
+            ...         approval_program="TEALCODE",
+            ...         clear_state_program="TEALCODE",
+            ...         schema={
+            ...             "global_ints": 1,
+            ...             "global_byte_slices": 2,
+            ...             "local_ints": 3,
+            ...             "local_byte_slices": 4
+            ...         },
+            ...         extra_pages=1,
+            ...         on_complete=OnComplete.OptInOC,
+            ...         args=[bytes([1, 2, 3, 4])],
+            ...         account_references=["ACCOUNT_1"],
+            ...         app_references=[123, 1234],
+            ...         asset_references=[12345],
+            ...         box_references=["box1", {"app_id": 1234, "name": "box2"}],
+            ...         lease="lease",
+            ...         note="note",
+            ...         first_valid_round=1000,
+            ...         validity_window=10,
+            ...         extra_fee=AlgoAmount.from_micro_algos(1000),
+            ...         static_fee=AlgoAmount.from_micro_algos(1000),
+            ...         max_fee=AlgoAmount.from_micro_algos(3000)
+            ...     )
+            ... )
+        """
+        self._txns.append(params)
+        return self
+
+    def add_app_update_method_call(self, params: AppUpdateMethodCallParams) -> TransactionComposer:
+        """Add an application update method call transaction.
+
+        :param params: The application update method call parameters
+        :return: The transaction composer instance for chaining
+        """
+        self._txns.append(params)
+        return self
+
+    def add_app_delete_method_call(self, params: AppDeleteMethodCallParams) -> TransactionComposer:
+        """Add an application deletion method call transaction.
+
+        :param params: The application deletion method call parameters
+        :return: The transaction composer instance for chaining
+        """
+        self._txns.append(params)
+        return self
+
+    def add_app_call_method_call(self, params: AppCallMethodCallParams) -> TransactionComposer:
+        """Add an application call method call transaction.
+
+        :param params: The application call method call parameters
+        :return: The transaction composer instance for chaining
+        """
+        self._txns.append(params)
+        return self
+
+    def add_online_key_registration(self, params: OnlineKeyRegistrationParams) -> TransactionComposer:
+        """Add an online key registration transaction.
+
+        :param params: The online key registration parameters
+        :return: The transaction composer instance for chaining
+        """
+        self._txns.append(params)
+        return self
+
+    def add_offline_key_registration(self, params: OfflineKeyRegistrationParams) -> TransactionComposer:
+        """Add an offline key registration transaction.
+
+        :param params: The offline key registration parameters
+        :return: The transaction composer instance for chaining
+        """
+        self._txns.append(params)
+        return self
+
+    def add_atc(self, atc: AtomicTransactionComposer) -> TransactionComposer:
+        """Add an existing AtomicTransactionComposer's transactions.
+
+        :param atc: The AtomicTransactionComposer to add
+        :return: The transaction composer instance for chaining
+
+        :example:
+            >>> atc = AtomicTransactionComposer()
+            >>> atc.add_transaction(TransactionWithSigner(transaction, signer))
+            >>> composer.add_atc(atc)
+        """
+        self._txns.append(atc)
+        return self
+
+    def count(self) -> int:
+        """Get the total number of transactions.
+
+        :return: The number of transactions
+        """
+        return len(self.build_transactions().transactions)
+
+    def build(self) -> TransactionComposerBuildResult:
+        """Build the transaction group.
+
+        :return: The built transaction group result
+        """
+        if self._atc.get_status() == algosdk.atomic_transaction_composer.AtomicTransactionComposerStatus.BUILDING:
+            suggested_params = self._get_suggested_params()
+            txn_with_signers: list[TransactionWithSignerAndContext] = []
+
+            for txn in self._txns:
+                txn_with_signers.extend(self._build_txn(txn, suggested_params))
+
+            for ts in txn_with_signers:
+                self._atc.add_transaction(ts)
+                if ts.context.abi_method:
+                    self._atc.method_dict[len(self._atc.txn_list) - 1] = ts.context.abi_method
+                if ts.context.max_fee:
+                    self._txn_max_fees[len(self._atc.txn_list) - 1] = ts.context.max_fee
+
+        return TransactionComposerBuildResult(
+            atc=self._atc,
+            transactions=self._atc.build_group(),
+            method_calls=self._atc.method_dict,
+        )
+
+    def rebuild(self) -> TransactionComposerBuildResult:
+        """Rebuild the transaction group from scratch.
+
+        :return: The rebuilt transaction group result
+        """
+        self._atc = AtomicTransactionComposer()
+        return self.build()
+
+    def build_transactions(self) -> BuiltTransactions:
+        """Build and return the transactions without executing them.
+
+        :return: The built transactions result
+        """
+        suggested_params = self._get_suggested_params()
+
+        transactions: list[algosdk.transaction.Transaction] = []
+        method_calls: dict[int, Method] = {}
+        signers: dict[int, TransactionSigner] = {}
+
+        idx = 0
+
+        for txn in self._txns:
+            txn_with_signers: list[TransactionWithSigner] = []
+
+            if isinstance(txn, MethodCallParams):
+                txn_with_signers.extend(self._build_method_call(txn, suggested_params))
+            else:
+                txn_with_signers.extend(self._build_txn(txn, suggested_params))
+
+            for ts in txn_with_signers:
+                transactions.append(ts.txn)
+                if ts.signer and ts.signer != NULL_SIGNER:
+                    signers[idx] = ts.signer
+                if isinstance(ts, TransactionWithSignerAndContext) and ts.context.abi_method:
+                    method_calls[idx] = ts.context.abi_method
+                    if ts.context.max_fee:
+                        self._txn_max_fees[idx] = ts.context.max_fee
+                idx += 1
+
+        return BuiltTransactions(transactions=transactions, method_calls=method_calls, signers=signers)
+
+    @deprecated("Use send() instead")
+    def execute(
+        self,
+        *,
+        max_rounds_to_wait: int | None = None,
+    ) -> SendAtomicTransactionComposerResults:
+        return self.send(SendParams(max_rounds_to_wait=max_rounds_to_wait))
+
+    def send(
+        self,
+        params: SendParams | None = None,
+    ) -> SendAtomicTransactionComposerResults:
+        """Send the transaction group to the network.
+
+        :param params: Parameters for the send operation
+        :return: The transaction send results
+        :raises Exception: If the transaction fails
+        """
+        group = self.build().transactions
+
+        if not params:
+            has_app_call = any(isinstance(txn.txn, ApplicationCallTxn) for txn in group)
+            params = SendParams() if has_app_call else SendParams()
+
+        cover_app_call_inner_transaction_fees = params.get("cover_app_call_inner_transaction_fees")
+        populate_app_call_resources = params.get("populate_app_call_resources")
+        wait_rounds = params.get("max_rounds_to_wait")
+        sp = self._get_suggested_params() if not wait_rounds or cover_app_call_inner_transaction_fees else None
+
+        if wait_rounds is None:
+            last_round = max(txn.txn.last_valid_round for txn in group)
+            assert sp is not None
+            first_round = sp.first
+            wait_rounds = last_round - first_round + 1
+
+        try:
+            return send_atomic_transaction_composer(
+                self._atc,
+                self._algod,
+                max_rounds_to_wait=wait_rounds,
+                suppress_log=params.get("suppress_log"),
+                populate_app_call_resources=populate_app_call_resources,
+                cover_app_call_inner_transaction_fees=cover_app_call_inner_transaction_fees,
+                additional_atc_context=AdditionalAtcContext(
+                    suggested_params=sp,
+                    max_fees=self._txn_max_fees,
+                ),
+            )
+        except algosdk.error.AlgodHTTPError as e:
+            raise Exception(f"Transaction failed: {e}") from e
+
+    def _handle_simulate_error(self, simulate_response: SimulateAtomicTransactionResponse) -> None:
+        # const failedGroup = simulateResponse?.txnGroups[0]
+        failed_group = simulate_response.simulate_response.get("txn-groups", [{}])[0]
+        failure_message = failed_group.get("failure-message")
+        failed_at = [str(x) for x in failed_group.get("failed-at", [])]
+        if failure_message:
+            error_message = (
+                f"Transaction failed at transaction(s) {', '.join(failed_at) if failed_at else 'N/A'} in the group. "
+                f"{failure_message}"
+            )
+            raise Exception(error_message)
+
+    def simulate(
+        self,
+        allow_more_logs: bool | None = None,
+        allow_empty_signatures: bool | None = None,
+        allow_unnamed_resources: bool | None = None,
+        extra_opcode_budget: int | None = None,
+        exec_trace_config: SimulateTraceConfig | None = None,
+        simulation_round: int | None = None,
+        skip_signatures: bool | None = None,
+    ) -> SendAtomicTransactionComposerResults:
+        """Simulate transaction group execution with configurable validation rules.
+
+        :param allow_more_logs: Whether to allow more logs than the standard limit
+        :param allow_empty_signatures: Whether to allow transactions with empty signatures
+        :param allow_unnamed_resources: Whether to allow unnamed resources.
+        :param extra_opcode_budget: Additional opcode budget to allocate
+        :param exec_trace_config: Configuration for execution tracing
+        :param simulation_round: Round number to simulate at
+        :param skip_signatures: Whether to skip signature validation
+        :return: The simulation results
+
+        :example:
+            >>> result = composer.simulate(extra_opcode_budget=1000, skip_signatures=True, ...)
+        """
+        from algokit_utils._debugging import simulate_and_persist_response, simulate_response
+
+        atc = AtomicTransactionComposer() if skip_signatures else self._atc
+
+        if skip_signatures:
+            allow_empty_signatures = True
+            transactions = self.build_transactions()
+            for txn in transactions.transactions:
+                atc.add_transaction(TransactionWithSigner(txn=txn, signer=NULL_SIGNER))
+            atc.method_dict = transactions.method_calls
+        else:
+            self.build()
+
+        if config.debug and config.project_root and config.trace_all:
+            response = simulate_and_persist_response(
+                atc,
+                config.project_root,
+                self._algod,
+                config.trace_buffer_size_mb,
+                allow_more_logs,
+                allow_empty_signatures,
+                allow_unnamed_resources,
+                extra_opcode_budget,
+                exec_trace_config,
+                simulation_round,
+            )
+            self._handle_simulate_error(response)
+            return SendAtomicTransactionComposerResults(
+                confirmations=response.simulate_response.get("txn-groups", [{"txn-results": [{"txn-result": {}}]}])[0][
+                    "txn-results"
+                ],
+                transactions=[TransactionWrapper(txn.txn) for txn in atc.txn_list],
+                tx_ids=response.tx_ids,
+                group_id=atc.txn_list[-1].txn.group or "",
+                simulate_response=response.simulate_response,
+                returns=[ABIReturn(r) for r in response.abi_results],
+            )
+
+        response = simulate_response(
+            atc,
+            self._algod,
+            allow_more_logs,
+            allow_empty_signatures,
+            allow_unnamed_resources,
+            extra_opcode_budget,
+            exec_trace_config,
+            simulation_round,
+        )
+        self._handle_simulate_error(response)
+        confirmation_results = response.simulate_response.get("txn-groups", [{"txn-results": [{"txn-result": {}}]}])[0][
+            "txn-results"
+        ]
+
+        return SendAtomicTransactionComposerResults(
+            confirmations=[txn["txn-result"] for txn in confirmation_results],
+            transactions=[TransactionWrapper(txn.txn) for txn in atc.txn_list],
+            tx_ids=response.tx_ids,
+            group_id=atc.txn_list[-1].txn.group or "",
+            simulate_response=response.simulate_response,
+            returns=[ABIReturn(r) for r in response.abi_results],
+        )
+
+    @staticmethod
+    def arc2_note(note: Arc2TransactionNote) -> bytes:
+        """Create an encoded transaction note that follows the ARC-2 spec.
+
+        https://github.com/algorandfoundation/ARCs/blob/main/ARCs/arc-0002.md
+
+        :param note: The ARC-2 note to encode
+        :return: The encoded note bytes
+        :raises ValueError: If the dapp_name is invalid
+        """
+
+        pattern = r"^[a-zA-Z0-9][a-zA-Z0-9_/@.-]{4,31}$"
+        if not re.match(pattern, note["dapp_name"]):
+            raise ValueError(
+                "dapp_name must be 5-32 chars, start with alphanumeric, "
+                "and contain only alphanumeric, _, /, @, ., or -"
+            )
+
+        data = note["data"]
+        if note["format"] == "j" and isinstance(data, (dict | list)):
+            # Ensure JSON data uses double quotes
+            data = json.dumps(data)
+
+        arc2_payload = f"{note['dapp_name']}:{note['format']}{data}"
+        return arc2_payload.encode("utf-8")
+
+    def _build_atc(self, atc: AtomicTransactionComposer) -> list[TransactionWithSignerAndContext]:
+        group = atc.build_group()
+
+        txn_with_signers = []
+        for idx, ts in enumerate(group):
+            ts.txn.group = None
+            if atc.method_dict.get(idx):
+                txn_with_signers.append(
+                    TransactionWithSignerAndContext(
+                        txn=ts.txn,
+                        signer=ts.signer,
+                        context=TransactionContext(abi_method=atc.method_dict.get(idx)),
+                    )
+                )
+            else:
+                txn_with_signers.append(
+                    TransactionWithSignerAndContext(
+                        txn=ts.txn,
+                        signer=ts.signer,
+                        context=TransactionContext(abi_method=None),
+                    )
+                )
+
+        return txn_with_signers
+
+    def _common_txn_build_step(  # noqa: C901
+        self,
+        build_txn: Callable[[dict], algosdk.transaction.Transaction],
+        params: _CommonTxnParams,
+        txn_params: dict,
+    ) -> TransactionWithContext:
+        # Clone suggested params
+        txn_params["sp"] = (
+            algosdk.transaction.SuggestedParams(**txn_params["sp"].__dict__) if "sp" in txn_params else None
+        )
+
+        if params.lease:
+            txn_params["lease"] = _encode_lease(params.lease)
+        if params.rekey_to:
+            txn_params["rekey_to"] = params.rekey_to
+        if params.note:
+            txn_params["note"] = params.note
+
+        if txn_params["sp"]:
+            if params.first_valid_round:
+                txn_params["sp"].first = params.first_valid_round
+
+            if params.last_valid_round:
+                txn_params["sp"].last = params.last_valid_round
+            else:
+                # If the validity window isn't set in this transaction or by default and we are pointing at
+                #  LocalNet set a bigger window to avoid dead transactions
+                from algokit_utils.clients import ClientManager
+
+                is_localnet = ClientManager.genesis_id_is_localnet(txn_params["sp"].gen)
+                window = params.validity_window or (
+                    1000
+                    if is_localnet and not self._default_validity_window_is_explicit
+                    else self._default_validity_window
+                )
+                txn_params["sp"].last = txn_params["sp"].first + window
+
+        if params.static_fee is not None and txn_params["sp"]:
+            txn_params["sp"].fee = params.static_fee.micro_algo
+            txn_params["sp"].flat_fee = True
+
+        if isinstance(txn_params.get("method"), Arc56Method):
+            txn_params["method"] = txn_params["method"].to_abi_method()
+
+        txn = build_txn(txn_params)
+
+        if params.extra_fee:
+            txn.fee += params.extra_fee.micro_algo
+
+        if params.max_fee and txn.fee > params.max_fee.micro_algo:
+            raise ValueError(f"Transaction fee {txn.fee} is greater than max_fee {params.max_fee}")
+        use_max_fee = params.max_fee and params.max_fee.micro_algo > (
+            params.static_fee.micro_algo if params.static_fee else 0
+        )
+        logical_max_fee = params.max_fee if use_max_fee else params.static_fee
+
+        return TransactionWithContext(
+            txn=txn,
+            context=TransactionContext(max_fee=logical_max_fee),
+        )
+
+    def _build_method_call(  # noqa: C901, PLR0912, PLR0915
+        self, params: MethodCallParams, suggested_params: algosdk.transaction.SuggestedParams
+    ) -> list[TransactionWithSignerAndContext]:
+        method_args: list[ABIValue | TransactionWithSigner] = []
+        txns_for_group: list[TransactionWithSignerAndContext] = []
+
+        if params.args:
+            for arg in reversed(params.args):
+                if arg is None and len(txns_for_group) > 0:
+                    # Pull last transaction from group as placeholder
+                    placeholder_transaction = txns_for_group.pop()
+                    method_args.append(placeholder_transaction)
+                    continue
+                if self._is_abi_value(arg):
+                    method_args.append(arg)
+                    continue
+
+                if isinstance(arg, TransactionWithSigner):
+                    method_args.append(arg)
+                    continue
+
+                if isinstance(arg, algosdk.transaction.Transaction):
+                    # Wrap in TransactionWithSigner
+                    signer = (
+                        params.signer.signer
+                        if isinstance(params.signer, TransactionSignerAccountProtocol)
+                        else params.signer
+                    )
+                    method_args.append(
+                        TransactionWithSignerAndContext(
+                            txn=arg,
+                            signer=signer if signer is not None else self._get_signer(params.sender),
+                            context=TransactionContext(abi_method=None),
+                        )
+                    )
+                    continue
+                match arg:
+                    case (
+                        AppCreateMethodCallParams()
+                        | AppCallMethodCallParams()
+                        | AppUpdateMethodCallParams()
+                        | AppDeleteMethodCallParams()
+                    ):
+                        temp_txn_with_signers = self._build_method_call(arg, suggested_params)
+                        # Add all transactions except the last one in reverse order
+                        txns_for_group.extend(temp_txn_with_signers[:-1])
+                        # Add the last transaction to method_args
+                        method_args.append(temp_txn_with_signers[-1])
+                        continue
+                    case AppCallParams():
+                        txn = self._build_app_call(arg, suggested_params)
+                    case PaymentParams():
+                        txn = self._build_payment(arg, suggested_params)
+                    case AssetOptInParams():
+                        txn = self._build_asset_transfer(
+                            AssetTransferParams(**arg.__dict__, receiver=arg.sender, amount=0), suggested_params
+                        )
+                    case AssetCreateParams():
+                        txn = self._build_asset_create(arg, suggested_params)
+                    case AssetConfigParams():
+                        txn = self._build_asset_config(arg, suggested_params)
+                    case AssetDestroyParams():
+                        txn = self._build_asset_destroy(arg, suggested_params)
+                    case AssetFreezeParams():
+                        txn = self._build_asset_freeze(arg, suggested_params)
+                    case AssetTransferParams():
+                        txn = self._build_asset_transfer(arg, suggested_params)
+                    case OnlineKeyRegistrationParams() | OfflineKeyRegistrationParams():
+                        txn = self._build_key_reg(arg, suggested_params)
+                    case _:
+                        raise ValueError(f"Unsupported method arg transaction type: {arg!s}")
+
+                signer = (
+                    params.signer.signer
+                    if isinstance(params.signer, TransactionSignerAccountProtocol)
+                    else params.signer
+                )
+                method_args.append(
+                    TransactionWithSignerAndContext(
+                        txn=txn.txn,
+                        signer=signer or self._get_signer(params.sender),
+                        context=TransactionContext(abi_method=params.method),
+                    )
+                )
+
+                continue
+
+        method_atc = AtomicTransactionComposer()
+        max_fees: dict[int, AlgoAmount] = {}
+
+        # Process in reverse order
+        for arg in reversed(txns_for_group):
+            atc_index = method_atc.get_tx_count() - 1
+
+            if isinstance(arg, TransactionWithSignerAndContext) and arg.context:
+                if arg.context.abi_method:
+                    method_atc.method_dict[atc_index] = arg.context.abi_method
+
+                if arg.context.max_fee is not None:
+                    max_fees[atc_index] = arg.context.max_fee
+
+        # Process method args that are transactions with ABI method info
+        for i, arg in enumerate(reversed([a for a in method_args if isinstance(a, TransactionWithSignerAndContext)])):
+            atc_index = method_atc.get_tx_count() + i
+            if arg.context:
+                if arg.context.abi_method:
+                    method_atc.method_dict[atc_index] = arg.context.abi_method
+                if arg.context.max_fee is not None:
+                    max_fees[atc_index] = arg.context.max_fee
+
+        app_id = params.app_id or 0
+        approval_program = getattr(params, "approval_program", None)
+        clear_program = getattr(params, "clear_state_program", None)
+        extra_pages = None
+
+        if app_id == 0:
+            extra_pages = getattr(params, "extra_program_pages", None)
+            if extra_pages is None and approval_program is not None:
+                extra_pages = calculate_extra_program_pages(approval_program, clear_program)
+
+        txn_params = {
+            "app_id": app_id,
+            "method": params.method,
+            "sender": params.sender,
+            "sp": suggested_params,
+            "signer": params.signer
+            if params.signer is not None
+            else self._get_signer(params.sender) or algosdk.atomic_transaction_composer.EmptySigner(),
+            "method_args": list(reversed(method_args)),
+            "on_complete": params.on_complete or algosdk.transaction.OnComplete.NoOpOC,
+            "boxes": [AppManager.get_box_reference(ref) for ref in params.box_references]
+            if params.box_references
+            else None,
+            "foreign_apps": params.app_references,
+            "foreign_assets": params.asset_references,
+            "accounts": params.account_references,
+            "global_schema": algosdk.transaction.StateSchema(
+                num_uints=params.schema.get("global_ints", 0),
+                num_byte_slices=params.schema.get("global_byte_slices", 0),
+            )
+            if params.schema
+            else None,
+            "local_schema": algosdk.transaction.StateSchema(
+                num_uints=params.schema.get("local_ints", 0),
+                num_byte_slices=params.schema.get("local_byte_slices", 0),
+            )
+            if params.schema
+            else None,
+            "approval_program": approval_program,
+            "clear_program": clear_program,
+            "extra_pages": extra_pages,
+        }
+
+        def _add_method_call_and_return_txn(x: dict) -> algosdk.transaction.Transaction:
+            method_atc.add_method_call(**x)
+            return method_atc.build_group()[-1].txn
+
+        result = self._common_txn_build_step(lambda x: _add_method_call_and_return_txn(x), params, txn_params)
+
+        build_atc_resp = self._build_atc(method_atc)
+        response = []
+        for i, v in enumerate(build_atc_resp):
+            max_fee = result.context.max_fee if i == method_atc.get_tx_count() - 1 else max_fees.get(i)
+            context = TransactionContext(abi_method=v.context.abi_method, max_fee=max_fee)
+            response.append(TransactionWithSignerAndContext(txn=v.txn, signer=v.signer, context=context))
+
+        return response
+
+    def _build_payment(
+        self, params: PaymentParams, suggested_params: algosdk.transaction.SuggestedParams
+    ) -> TransactionWithContext:
+        txn_params = {
+            "sender": params.sender,
+            "sp": suggested_params,
+            "receiver": params.receiver,
+            "amt": params.amount.micro_algo,
+            "close_remainder_to": params.close_remainder_to,
+        }
+
+        return self._common_txn_build_step(lambda x: algosdk.transaction.PaymentTxn(**x), params, txn_params)
+
+    def _build_asset_create(
+        self, params: AssetCreateParams, suggested_params: algosdk.transaction.SuggestedParams
+    ) -> TransactionWithContext:
+        txn_params = {
+            "sender": params.sender,
+            "sp": suggested_params,
+            "total": params.total,
+            "default_frozen": params.default_frozen or False,
+            "unit_name": params.unit_name or "",
+            "asset_name": params.asset_name or "",
+            "manager": params.manager,
+            "reserve": params.reserve,
+            "freeze": params.freeze,
+            "clawback": params.clawback,
+            "url": params.url or "",
+            "metadata_hash": params.metadata_hash,
+            "decimals": params.decimals or 0,
+        }
+
+        return self._common_txn_build_step(lambda x: algosdk.transaction.AssetCreateTxn(**x), params, txn_params)
+
+    def _build_app_call(
+        self,
+        params: AppCallParams | AppUpdateParams | AppCreateParams | AppDeleteParams,
+        suggested_params: algosdk.transaction.SuggestedParams,
+    ) -> TransactionWithContext:
+        app_id = getattr(params, "app_id", 0)
+
+        approval_program = None
+        clear_program = None
+
+        if isinstance(params, AppUpdateParams | AppCreateParams):
+            if isinstance(params.approval_program, str):
+                approval_program = self._app_manager.compile_teal(params.approval_program).compiled_base64_to_bytes
+            elif isinstance(params.approval_program, bytes):
+                approval_program = params.approval_program
+
+            if isinstance(params.clear_state_program, str):
+                clear_program = self._app_manager.compile_teal(params.clear_state_program).compiled_base64_to_bytes
+            elif isinstance(params.clear_state_program, bytes):
+                clear_program = params.clear_state_program
+
+        sdk_params = {
+            "sender": params.sender,
+            "sp": suggested_params,
+            "app_args": params.args,
+            "on_complete": params.on_complete or algosdk.transaction.OnComplete.NoOpOC,
+            "accounts": params.account_references,
+            "foreign_apps": params.app_references,
+            "foreign_assets": params.asset_references,
+            "boxes": params.box_references,
+            "approval_program": approval_program,
+            "clear_program": clear_program,
+        }
+
+        txn_params = {**sdk_params, "index": app_id}
+
+        if not app_id and isinstance(params, AppCreateParams):
+            if not sdk_params["approval_program"] or not sdk_params["clear_program"]:
+                raise ValueError("approval_program and clear_program are required for application creation")
+
+            schema = params.schema
+            if not schema:
+                schema = AppCreateSchema(
+                    global_ints=0,
+                    global_byte_slices=0,
+                    local_ints=0,
+                    local_byte_slices=0,
+                )
+
+            txn_params = {
+                **txn_params,
+                "global_schema": algosdk.transaction.StateSchema(
+                    num_uints=schema["global_ints"],
+                    num_byte_slices=schema["global_byte_slices"],
+                ),
+                "local_schema": algosdk.transaction.StateSchema(
+                    num_uints=schema["local_ints"],
+                    num_byte_slices=schema["local_byte_slices"],
+                ),
+                "extra_pages": params.extra_program_pages
+                or calculate_extra_program_pages(approval_program, clear_program),
+            }
+
+        return self._common_txn_build_step(lambda x: algosdk.transaction.ApplicationCallTxn(**x), params, txn_params)
+
+    def _build_asset_config(
+        self, params: AssetConfigParams, suggested_params: algosdk.transaction.SuggestedParams
+    ) -> TransactionWithContext:
+        txn_params = {
+            "sender": params.sender,
+            "sp": suggested_params,
+            "index": params.asset_id,
+            "manager": params.manager,
+            "reserve": params.reserve,
+            "freeze": params.freeze,
+            "clawback": params.clawback,
+            "strict_empty_address_check": False,
+        }
+
+        return self._common_txn_build_step(lambda x: algosdk.transaction.AssetConfigTxn(**x), params, txn_params)
+
+    def _build_asset_destroy(
+        self, params: AssetDestroyParams, suggested_params: algosdk.transaction.SuggestedParams
+    ) -> TransactionWithContext:
+        txn_params = {
+            "sender": params.sender,
+            "sp": suggested_params,
+            "index": params.asset_id,
+        }
+
+        return self._common_txn_build_step(lambda x: algosdk.transaction.AssetDestroyTxn(**x), params, txn_params)
+
+    def _build_asset_freeze(
+        self, params: AssetFreezeParams, suggested_params: algosdk.transaction.SuggestedParams
+    ) -> TransactionWithContext:
+        txn_params = {
+            "sender": params.sender,
+            "sp": suggested_params,
+            "index": params.asset_id,
+            "target": params.account,
+            "new_freeze_state": params.frozen,
+        }
+
+        return self._common_txn_build_step(lambda x: algosdk.transaction.AssetFreezeTxn(**x), params, txn_params)
+
+    def _build_asset_transfer(
+        self, params: AssetTransferParams, suggested_params: algosdk.transaction.SuggestedParams
+    ) -> TransactionWithContext:
+        txn_params = {
+            "sender": params.sender,
+            "sp": suggested_params,
+            "receiver": params.receiver,
+            "amt": params.amount,
+            "index": params.asset_id,
+            "close_assets_to": params.close_asset_to,
+            "revocation_target": params.clawback_target,
+        }
+
+        return self._common_txn_build_step(lambda x: algosdk.transaction.AssetTransferTxn(**x), params, txn_params)
+
+    def _build_key_reg(
+        self,
+        params: OnlineKeyRegistrationParams | OfflineKeyRegistrationParams,
+        suggested_params: algosdk.transaction.SuggestedParams,
+    ) -> TransactionWithContext:
+        if isinstance(params, OnlineKeyRegistrationParams):
+            txn_params = {
+                "sender": params.sender,
+                "sp": suggested_params,
+                "votekey": params.vote_key,
+                "selkey": params.selection_key,
+                "votefst": params.vote_first,
+                "votelst": params.vote_last,
+                "votekd": params.vote_key_dilution,
+                "rekey_to": params.rekey_to,
+                "nonpart": False,
+                "sprfkey": params.state_proof_key,
+            }
+
+            return self._common_txn_build_step(lambda x: algosdk.transaction.KeyregTxn(**x), params, txn_params)
+
+        return self._common_txn_build_step(
+            lambda x: algosdk.transaction.KeyregTxn(**x),
+            params,
+            {
+                "sender": params.sender,
+                "sp": suggested_params,
+                "nonpart": params.prevent_account_from_ever_participating_again,
+                "votekey": None,
+                "selkey": None,
+                "votefst": None,
+                "votelst": None,
+                "votekd": None,
+            },
+        )
+
+    def _is_abi_value(self, x: bool | float | str | bytes | list | TxnParams) -> bool:
+        if isinstance(x, list | tuple):
+            return len(x) == 0 or all(self._is_abi_value(item) for item in x)
+
+        return isinstance(x, bool | int | float | str | bytes)
+
+    def _build_txn(  # noqa: C901, PLR0912, PLR0911
+        self,
+        txn: TransactionWithSigner | TxnParams | AtomicTransactionComposer,
+        suggested_params: algosdk.transaction.SuggestedParams,
+    ) -> list[TransactionWithSignerAndContext]:
+        match txn:
+            case TransactionWithSigner():
+                return [
+                    TransactionWithSignerAndContext(txn=txn.txn, signer=txn.signer, context=TransactionContext.empty())
+                ]
+            case AtomicTransactionComposer():
+                return self._build_atc(txn)
+            case algosdk.transaction.Transaction():
+                signer = self._get_signer(txn.sender)
+                return [TransactionWithSignerAndContext(txn=txn, signer=signer, context=TransactionContext.empty())]
+            case (
+                AppCreateMethodCallParams()
+                | AppCallMethodCallParams()
+                | AppUpdateMethodCallParams()
+                | AppDeleteMethodCallParams()
+            ):
+                return self._build_method_call(txn, suggested_params)
+
+        signer = txn.signer.signer if isinstance(txn.signer, TransactionSignerAccountProtocol) else txn.signer  # type: ignore[assignment]
+        signer = signer or self._get_signer(txn.sender)
+
+        match txn:
+            case PaymentParams():
+                payment = self._build_payment(txn, suggested_params)
+                return [TransactionWithSignerAndContext.from_txn_with_context(payment, signer)]
+            case AssetCreateParams():
+                asset_create = self._build_asset_create(txn, suggested_params)
+                return [TransactionWithSignerAndContext.from_txn_with_context(asset_create, signer)]
+            case AppCallParams() | AppUpdateParams() | AppCreateParams() | AppDeleteParams():
+                app_call = self._build_app_call(txn, suggested_params)
+                return [TransactionWithSignerAndContext.from_txn_with_context(app_call, signer)]
+            case AssetConfigParams():
+                asset_config = self._build_asset_config(txn, suggested_params)
+                return [TransactionWithSignerAndContext.from_txn_with_context(asset_config, signer)]
+            case AssetDestroyParams():
+                asset_destroy = self._build_asset_destroy(txn, suggested_params)
+                return [TransactionWithSignerAndContext.from_txn_with_context(asset_destroy, signer)]
+            case AssetFreezeParams():
+                asset_freeze = self._build_asset_freeze(txn, suggested_params)
+                return [TransactionWithSignerAndContext.from_txn_with_context(asset_freeze, signer)]
+            case AssetTransferParams():
+                asset_transfer = self._build_asset_transfer(txn, suggested_params)
+                return [TransactionWithSignerAndContext.from_txn_with_context(asset_transfer, signer)]
+            case AssetOptInParams():
+                asset_transfer = self._build_asset_transfer(
+                    AssetTransferParams(**txn.__dict__, receiver=txn.sender, amount=0), suggested_params
+                )
+                return [TransactionWithSignerAndContext.from_txn_with_context(asset_transfer, signer)]
+            case AssetOptOutParams():
+                txn_dict = txn.__dict__
+                creator = txn_dict.pop("creator")
+                asset_transfer = self._build_asset_transfer(
+                    AssetTransferParams(**txn_dict, receiver=txn.sender, amount=0, close_asset_to=creator),
+                    suggested_params,
+                )
+                return [TransactionWithSignerAndContext.from_txn_with_context(asset_transfer, signer)]
+            case OnlineKeyRegistrationParams() | OfflineKeyRegistrationParams():
+                key_reg = self._build_key_reg(txn, suggested_params)
+                return [TransactionWithSignerAndContext.from_txn_with_context(key_reg, signer)]
+            case _:
+                raise ValueError(f"Unsupported txn: {txn}")