algokit-utils 3.0.0b1__py3-none-any.whl → 3.0.0b3__py3-none-any.whl

algokit_utils/__init__.py

@@ -1,184 +1,24 @@
-from algokit_utils._debugging import PersistSourceMapInput, persist_sourcemaps, simulate_and_persist_response
-from algokit_utils._ensure_funded import EnsureBalanceParameters, EnsureFundedResponse, ensure_funded
-from algokit_utils._transfer import TransferAssetParameters, TransferParameters, transfer, transfer_asset
-from algokit_utils.account import (
-    create_kmd_wallet_account,
-    get_account,
-    get_account_from_mnemonic,
-    get_dispenser_account,
-    get_kmd_wallet_account,
-    get_localnet_default_account,
-    get_or_create_kmd_wallet_account,
-)
-from algokit_utils.application_client import (
-    ApplicationClient,
-    execute_atc_with_logic_error,
-    get_next_version,
-    get_sender_from_signer,
-    num_extra_program_pages,
-)
-from algokit_utils.application_specification import (
-    ApplicationSpecification,
-    AppSpecStateDict,
-    CallConfig,
-    DefaultArgumentDict,
-    DefaultArgumentType,
-    MethodConfigDict,
-    MethodHints,
-    OnCompleteActionName,
-)
-from algokit_utils.asset import opt_in, opt_out
-from algokit_utils.common import Program
-from algokit_utils.deploy import (
-    DELETABLE_TEMPLATE_NAME,
-    NOTE_PREFIX,
-    UPDATABLE_TEMPLATE_NAME,
-    ABICallArgs,
-    ABICallArgsDict,
-    ABICreateCallArgs,
-    ABICreateCallArgsDict,
-    AppDeployMetaData,
-    AppLookup,
-    AppMetaData,
-    AppReference,
-    DeployCallArgs,
-    DeployCallArgsDict,
-    DeployCreateCallArgs,
-    DeployCreateCallArgsDict,
-    DeploymentFailedError,
-    DeployResponse,
-    OnSchemaBreak,
-    OnUpdate,
-    OperationPerformed,
-    TemplateValueDict,
-    TemplateValueMapping,
-    get_app_id_from_tx_id,
-    get_creator_apps,
-    replace_template_variables,
-)
-from algokit_utils.dispenser_api import (
-    DISPENSER_ACCESS_TOKEN_KEY,
-    DISPENSER_REQUEST_TIMEOUT,
-    DispenserFundResponse,
-    DispenserLimitResponse,
-    TestNetDispenserApiClient,
-)
-from algokit_utils.logic_error import LogicError
-from algokit_utils.models import (
-    ABIArgsDict,
-    ABIMethod,
-    ABITransactionResponse,
-    Account,
-    CommonCallParameters,  # noqa: F401
-    CommonCallParametersDict,  # noqa: F401
-    CreateCallParameters,
-    CreateCallParametersDict,
-    CreateTransactionParameters,
-    OnCompleteCallParameters,
-    OnCompleteCallParametersDict,
-    RawTransactionParameters,  # noqa: F401
-    TransactionParameters,
-    TransactionParametersDict,
-    TransactionResponse,
-)
-from algokit_utils.network_clients import (
-    AlgoClientConfig,
-    get_algod_client,
-    get_algonode_config,
-    get_default_localnet_config,
-    get_indexer_client,
-    get_kmd_client_from_algod_client,
-    get_purestake_config,
-    is_localnet,
-    is_mainnet,
-    is_testnet,
-)
+"""AlgoKit Python Utilities - a set of utilities for building solutions on Algorand
 
-__all__ = [
-    "create_kmd_wallet_account",
-    "get_account_from_mnemonic",
-    "get_or_create_kmd_wallet_account",
-    "get_localnet_default_account",
-    "get_dispenser_account",
-    "get_kmd_wallet_account",
-    "get_account",
-    "UPDATABLE_TEMPLATE_NAME",
-    "DELETABLE_TEMPLATE_NAME",
-    "NOTE_PREFIX",
-    "DeploymentFailedError",
-    "AppReference",
-    "AppDeployMetaData",
-    "AppMetaData",
-    "AppLookup",
-    "get_creator_apps",
-    "replace_template_variables",
-    "ABIArgsDict",
-    "ABICallArgs",
-    "ABICallArgsDict",
-    "ABICreateCallArgs",
-    "ABICreateCallArgsDict",
-    "ABIMethod",
-    "CreateCallParameters",
-    "CreateCallParametersDict",
-    "CreateTransactionParameters",
-    "DeployCallArgs",
-    "DeployCreateCallArgs",
-    "DeployCallArgsDict",
-    "DeployCreateCallArgsDict",
-    "OnCompleteCallParameters",
-    "OnCompleteCallParametersDict",
-    "TransactionParameters",
-    "TransactionParametersDict",
-    "ApplicationClient",
-    "DeployResponse",
-    "OnUpdate",
-    "OnSchemaBreak",
-    "OperationPerformed",
-    "TemplateValueDict",
-    "TemplateValueMapping",
-    "Program",
-    "execute_atc_with_logic_error",
-    "get_app_id_from_tx_id",
-    "get_next_version",
-    "get_sender_from_signer",
-    "num_extra_program_pages",
-    "AppSpecStateDict",
-    "ApplicationSpecification",
-    "CallConfig",
-    "DefaultArgumentDict",
-    "DefaultArgumentType",
-    "MethodConfigDict",
-    "OnCompleteActionName",
-    "MethodHints",
-    "LogicError",
-    "ABITransactionResponse",
-    "Account",
-    "TransactionResponse",
-    "AlgoClientConfig",
-    "get_algod_client",
-    "get_algonode_config",
-    "get_default_localnet_config",
-    "get_indexer_client",
-    "get_kmd_client_from_algod_client",
-    "get_purestake_config",
-    "is_localnet",
-    "is_mainnet",
-    "is_testnet",
-    "TestNetDispenserApiClient",
-    "DispenserFundResponse",
-    "DispenserLimitResponse",
-    "DISPENSER_ACCESS_TOKEN_KEY",
-    "DISPENSER_REQUEST_TIMEOUT",
-    "EnsureBalanceParameters",
-    "EnsureFundedResponse",
-    "TransferParameters",
-    "ensure_funded",
-    "transfer",
-    "TransferAssetParameters",
-    "transfer_asset",
-    "opt_in",
-    "opt_out",
-    "persist_sourcemaps",
-    "PersistSourceMapInput",
-    "simulate_and_persist_response",
-]
+This module provides commonly used utilities and types at the root level for convenience.
+For more specific functionality, import directly from the relevant submodules:
+
+    from algokit_utils.accounts import KmdAccountManager
+    from algokit_utils.applications import AppClient
+    from algokit_utils.applications.app_spec import Arc52Contract
+    etc.
+"""
+
+# Core types and utilities that are commonly used
+from algokit_utils.applications import *  # noqa: F403
+from algokit_utils.assets import *  # noqa: F403
+from algokit_utils.protocols import *  # noqa: F403
+from algokit_utils.models import *  # noqa: F403
+from algokit_utils.accounts import *  # noqa: F403
+from algokit_utils.clients import *  # noqa: F403
+from algokit_utils.transactions import *  # noqa: F403
+from algokit_utils.errors import *  # noqa: F403
+from algokit_utils.algorand import *  # noqa: F403
+
+# Legacy types and utilities
+from algokit_utils._legacy_v2 import *  # noqa: F403

algokit_utils/_debugging.py

@@ -14,7 +14,8 @@ from algosdk.atomic_transaction_composer import (
 from algosdk.encoding import checksum
 from algosdk.v2client.models import SimulateRequest, SimulateRequestTransactionGroup, SimulateTraceConfig
 
-from algokit_utils.common import Program
+from algokit_utils._legacy_v2.common import Program
+from algokit_utils.models.application import CompiledTeal
 
 if typing.TYPE_CHECKING:
     from algosdk.v2client.algod import AlgodClient
@@ -27,7 +28,7 @@ SOURCES_FILE = "sources.avm.json"
 TRACES_FILE_EXT = ".trace.avm.json"
 DEBUG_TRACES_DIR = "debug_traces"
 TEAL_FILE_EXT = ".teal"
-TEAL_SOURCEMAP_EXT = ".teal.tok.map"
+TEAL_SOURCEMAP_EXT = ".teal.map"
 
 
 @dataclass
@@ -64,7 +65,11 @@ class AVMDebuggerSourceMap:
 @dataclass
 class PersistSourceMapInput:
     def __init__(
-        self, app_name: str, file_name: str, raw_teal: str | None = None, compiled_teal: Program | None = None
+        self,
+        app_name: str,
+        file_name: str,
+        raw_teal: str | None = None,
+        compiled_teal: CompiledTeal | Program | None = None,
     ):
         self.compiled_teal = compiled_teal
         self.app_name = app_name
@@ -76,7 +81,9 @@ class PersistSourceMapInput:
         return cls(app_name, file_name, raw_teal=raw_teal)
 
     @classmethod
-    def from_compiled_teal(cls, compiled_teal: Program, app_name: str, file_name: str) -> "PersistSourceMapInput":
+    def from_compiled_teal(
+        cls, compiled_teal: CompiledTeal | Program, app_name: str, file_name: str
+    ) -> "PersistSourceMapInput":
         return cls(app_name, file_name, compiled_teal=compiled_teal)
 
     @property
@@ -107,60 +114,40 @@ def _load_or_create_sources(sources_path: Path) -> AVMDebuggerSourceMap:
         return AVMDebuggerSourceMap.from_dict(json.load(f))
 
 
-def _upsert_debug_sourcemaps(sourcemaps: list[AVMDebuggerSourceMapEntry], project_root: Path) -> None:
-    """
-    This function updates or inserts debug sourcemaps. If path in the sourcemap during iteration leads to non
-    existing file, removes it. Otherwise upserts.
-
-    Args:
-        sourcemaps (list[AVMDebuggerSourceMapEntry]): A list of AVMDebuggerSourceMapEntry objects.
-        project_root (Path): The root directory of the project.
-
-    Returns:
-        None
-    """
-
-    sources_path = project_root / ALGOKIT_DIR / SOURCES_DIR / SOURCES_FILE
-    sources = _load_or_create_sources(sources_path)
-
-    for sourcemap in sourcemaps:
-        source_file_path = Path(sourcemap.location)
-        if not source_file_path.exists() and sourcemap in sources.txn_group_sources:
-            sources.txn_group_sources.remove(sourcemap)
-        elif source_file_path.exists():
-            if sourcemap not in sources.txn_group_sources:
-                sources.txn_group_sources.append(sourcemap)
-            else:
-                index = sources.txn_group_sources.index(sourcemap)
-                sources.txn_group_sources[index] = sourcemap
-
-    with sources_path.open("w") as f:
-        json.dump(sources.to_dict(), f)
-
-
 def _write_to_file(path: Path, content: str) -> None:
     path.parent.mkdir(parents=True, exist_ok=True)
     path.write_text(content)
 
 
-def _build_avm_sourcemap(  # noqa: PLR0913
+def _build_avm_sourcemap(
     *,
     app_name: str,
     file_name: str,
     output_path: Path,
     client: "AlgodClient",
     raw_teal: str | None = None,
-    compiled_teal: Program | None = None,
+    compiled_teal: CompiledTeal | Program | None = None,
     with_sources: bool = True,
 ) -> AVMDebuggerSourceMapEntry:
     if not raw_teal and not compiled_teal:
         raise ValueError("Either raw teal or compiled teal must be provided")
 
-    result = compiled_teal if compiled_teal else Program(str(raw_teal), client=client)
-    program_hash = base64.b64encode(
-        checksum(result.raw_binary)  # type: ignore[no-untyped-call]
-    ).decode()
-    source_map = result.source_map.__dict__
+    # Handle both legacy Program and new CompiledTeal
+    if isinstance(compiled_teal, Program):
+        program_hash = base64.b64encode(checksum(compiled_teal.raw_binary)).decode()
+        source_map = compiled_teal.source_map.__dict__
+        teal_content = compiled_teal.teal
+    elif isinstance(compiled_teal, CompiledTeal):
+        program_hash = base64.b64encode(checksum(compiled_teal.compiled_base64_to_bytes)).decode()
+        source_map = compiled_teal.source_map.__dict__ if compiled_teal.source_map else {}
+        teal_content = compiled_teal.teal
+    else:
+        # Handle raw TEAL case
+        result = Program(str(raw_teal), client=client)
+        program_hash = base64.b64encode(checksum(result.raw_binary)).decode()
+        source_map = result.source_map.__dict__
+        teal_content = result.teal
+
     source_map["sources"] = [f"{file_name}{TEAL_FILE_EXT}"] if with_sources else []
 
     output_dir_path = output_path / ALGOKIT_DIR / SOURCES_DIR / app_name
@@ -169,25 +156,45 @@ def _build_avm_sourcemap(  # noqa: PLR0913
     _write_to_file(source_map_output_path, json.dumps(source_map))
 
     if with_sources:
-        _write_to_file(teal_output_path, result.teal)
+        _write_to_file(teal_output_path, teal_content)
 
     return AVMDebuggerSourceMapEntry(str(source_map_output_path), program_hash)
 
 
+def cleanup_old_trace_files(output_dir: Path, buffer_size_mb: float) -> None:
+    """
+    Cleanup old trace files if total size exceeds buffer size limit.
+
+    Args:
+        output_dir (Path): Directory containing trace files
+        buffer_size_mb (float): Maximum allowed size in megabytes
+    """
+    total_size = sum(f.stat().st_size for f in output_dir.glob("*") if f.is_file())
+    if total_size > buffer_size_mb * 1024 * 1024:
+        sorted_files = sorted(output_dir.glob("*"), key=lambda p: p.stat().st_mtime)
+        while total_size > buffer_size_mb * 1024 * 1024 and sorted_files:
+            oldest_file = sorted_files.pop(0)
+            total_size -= oldest_file.stat().st_size
+            oldest_file.unlink()
+
+
 def persist_sourcemaps(
-    *, sources: list[PersistSourceMapInput], project_root: Path, client: "AlgodClient", with_sources: bool = True
+    *,
+    sources: list[PersistSourceMapInput],
+    project_root: Path,
+    client: "AlgodClient",
+    with_sources: bool = True,
 ) -> None:
     """
     Persist the sourcemaps for the given sources as an AlgoKit AVM Debugger compliant artifacts.
-    Args:
-        sources (list[PersistSourceMapInput]): A list of PersistSourceMapInput objects.
-        project_root (Path): The root directory of the project.
-        client (AlgodClient): An AlgodClient object for interacting with the Algorand blockchain.
-        with_sources (bool): If True, it will dump teal source files along with sourcemaps.
-        Default is True, as needed by an AlgoKit AVM debugger.
+
+    :param sources: A list of PersistSourceMapInput objects.
+    :param project_root: The root directory of the project.
+    :param client: An AlgodClient object for interacting with the Algorand blockchain.
+    :param with_sources: If True, it will dump teal source files along with sourcemaps.
     """
 
-    sourcemaps = [
+    for source in sources:
         _build_avm_sourcemap(
             raw_teal=source.raw_teal,
             compiled_teal=source.compiled_teal,
@@ -197,54 +204,68 @@ def persist_sourcemaps(
             client=client,
             with_sources=with_sources,
         )
-        for source in sources
-    ]
-
-    _upsert_debug_sourcemaps(sourcemaps, project_root)
 
 
-def simulate_response(atc: AtomicTransactionComposer, algod_client: "AlgodClient") -> SimulateAtomicTransactionResponse:
-    """
-    Simulate and fetch response for the given AtomicTransactionComposer and AlgodClient.
-
-    Args:
-        atc (AtomicTransactionComposer): An AtomicTransactionComposer object.
-        algod_client (AlgodClient): An AlgodClient object for interacting with the Algorand blockchain.
-
-    Returns:
-        SimulateAtomicTransactionResponse: The simulated response.
-    """
+def simulate_response(
+    atc: AtomicTransactionComposer,
+    algod_client: "AlgodClient",
+    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,
+) -> SimulateAtomicTransactionResponse:
+    """Simulate atomic transaction group execution"""
 
     unsigned_txn_groups = atc.build_group()
     empty_signer = EmptySigner()
     txn_list = [txn_group.txn for txn_group in unsigned_txn_groups]
     fake_signed_transactions = empty_signer.sign_transactions(txn_list, [])
     txn_group = [SimulateRequestTransactionGroup(txns=fake_signed_transactions)]
-    trace_config = SimulateTraceConfig(enable=True, stack_change=True, scratch_change=True)
+    trace_config = SimulateTraceConfig(enable=True, stack_change=True, scratch_change=True, state_change=True)
 
     simulate_request = SimulateRequest(
-        txn_groups=txn_group, allow_more_logs=True, allow_empty_signatures=True, exec_trace_config=trace_config
+        txn_groups=txn_group,
+        allow_more_logs=allow_more_logs if allow_more_logs is not None else True,
+        round=simulation_round,
+        extra_opcode_budget=extra_opcode_budget if extra_opcode_budget is not None else 0,
+        allow_unnamed_resources=allow_unnamed_resources if allow_unnamed_resources is not None else True,
+        allow_empty_signatures=allow_empty_signatures if allow_empty_signatures is not None else True,
+        exec_trace_config=exec_trace_config if exec_trace_config is not None else trace_config,
     )
+
     return atc.simulate(algod_client, simulate_request)
 
 
 def simulate_and_persist_response(
-    atc: AtomicTransactionComposer, project_root: Path, algod_client: "AlgodClient", buffer_size_mb: float = 256
+    atc: AtomicTransactionComposer,
+    project_root: Path,
+    algod_client: "AlgodClient",
+    buffer_size_mb: float = 256,
+    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,
 ) -> SimulateAtomicTransactionResponse:
-    """
-    Simulates the atomic transactions using the provided `AtomicTransactionComposer` object and `AlgodClient` object,
-    and persists the simulation response to an AlgoKit AVM Debugger compliant JSON file.
-
-    :param atc: An `AtomicTransactionComposer` object representing the atomic transactions to be
-    simulated and persisted.
-    :param project_root: A `Path` object representing the root directory of the project.
-    :param algod_client: An `AlgodClient` object representing the Algorand client.
-    :param buffer_size_mb: The size of the trace buffer in megabytes. Defaults to 256mb.
-    :return: None
-
-    Returns:
-        SimulateAtomicTransactionResponse: The simulated response after persisting it
-        for AlgoKit AVM Debugger consumption.
+    """Simulates atomic transactions and persists simulation response to a JSON file.
+
+    Simulates the atomic transactions using the provided AtomicTransactionComposer and AlgodClient,
+    then persists the simulation response to an AlgoKit AVM Debugger compliant JSON file.
+
+    :param atc: AtomicTransactionComposer containing transactions to simulate and persist
+    :param project_root: Root directory path of the project
+    :param algod_client: Algorand client instance
+    :param buffer_size_mb: Size of trace buffer in megabytes, defaults to 256
+    :param allow_more_logs: Flag to allow additional logs, defaults to None
+    :param allow_empty_signatures: Flag to allow empty signatures, defaults to None
+    :param allow_unnamed_resources: Flag to allow unnamed resources, defaults to None
+    :param extra_opcode_budget: Additional opcode budget, defaults to None
+    :param exec_trace_config: Execution trace configuration, defaults to None
+    :param simulation_round: Round number for simulation, defa  ults to None
+    :return: Simulated response after persisting for AlgoKit AVM Debugger consumption
     """
     atc_to_simulate = atc.clone()
     sp = algod_client.suggested_params()
@@ -254,27 +275,32 @@ def simulate_and_persist_response(
         txn_with_sign.txn.last_valid_round = sp.last
         txn_with_sign.txn.genesis_hash = sp.gh
 
-    response = simulate_response(atc_to_simulate, algod_client)
+    response = simulate_response(
+        atc_to_simulate,
+        algod_client,
+        allow_more_logs,
+        allow_empty_signatures,
+        allow_unnamed_resources,
+        extra_opcode_budget,
+        exec_trace_config,
+        simulation_round,
+    )
     txn_results = response.simulate_response["txn-groups"]
 
-    txn_types = [txn_result["txn-results"][0]["txn-result"]["txn"]["txn"]["type"] for txn_result in txn_results]
-    txn_types_count = {txn_type: txn_types.count(txn_type) for txn_type in set(txn_types)}
-    txn_types_str = "_".join([f"{count}#{txn_type}" for txn_type, count in txn_types_count.items()])
+    txn_types = [
+        txn["txn-result"]["txn"]["txn"]["type"] for txn_result in txn_results for txn in txn_result["txn-results"]
+    ]
+    txn_types_count = {}
+    for txn_type in txn_types:
+        if txn_type not in txn_types_count:
+            txn_types_count[txn_type] = txn_types.count(txn_type)
+    txn_types_str = "_".join([f"{count}{txn_type}" for txn_type, count in txn_types_count.items()])
 
     last_round = response.simulate_response["last-round"]
     timestamp = datetime.now(tz=timezone.utc).strftime("%Y%m%d_%H%M%S")
     output_file = project_root / DEBUG_TRACES_DIR / f"{timestamp}_lr{last_round}_{txn_types_str}{TRACES_FILE_EXT}"
 
     output_file.parent.mkdir(parents=True, exist_ok=True)
-
-    # cleanup old files if buffer size is exceeded
-    total_size = sum(f.stat().st_size for f in output_file.parent.glob("*") if f.is_file())
-    if total_size > buffer_size_mb * 1024 * 1024:
-        sorted_files = sorted(output_file.parent.glob("*"), key=lambda p: p.stat().st_mtime)
-        while total_size > buffer_size_mb * 1024 * 1024:
-            oldest_file = sorted_files.pop(0)
-            total_size -= oldest_file.stat().st_size
-            oldest_file.unlink()
-
+    cleanup_old_trace_files(output_file.parent, buffer_size_mb)
     output_file.write_text(json.dumps(response.simulate_response, indent=2))
     return response