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

algokit_utils/application_specification.py

@@ -1,206 +1,48 @@
-import base64
-import dataclasses
-import json
-from enum import IntFlag
-from pathlib import Path
-from typing import Any, Literal, TypeAlias, TypedDict
+import warnings
+
+from typing_extensions import deprecated
+
+warnings.warn(
+    """The legacy v2 application_specification module is deprecated and will be removed in a future version.
+    Use `from algokit_utils.applications.app_spec.arc32 import ...` to access Arc32 app spec instead.
+    By default, the ARC52Contract is a recommended app spec to use, serving as a replacement
+    for legacy 'ApplicationSpecification' class.
+    To convert legacy app specs to ARC52, use `Arc56Contract.from_arc32`.
+""",
+    DeprecationWarning,
+    stacklevel=2,
+)
+
+from algokit_utils.applications.app_spec.arc32 import (  # noqa: E402  # noqa: E402
+    AppSpecStateDict,
+    Arc32Contract,
+    CallConfig,
+    DefaultArgumentDict,
+    DefaultArgumentType,
+    MethodConfigDict,
+    MethodHints,
+    OnCompleteActionName,
+)
+
+
+@deprecated(
+    "Use `Arc32Contract` from algokit_utils.applications instead. Example:\n"
+    "```python\n"
+    "from algokit_utils.applications import Arc32Contract\n"
+    "app_spec = Arc32Contract.from_json(app_spec_json)\n"
+    "```"
+)
+class ApplicationSpecification(Arc32Contract):
+    """Deprecated class for ARC-0032 application specification"""
 
-from algosdk.abi import Contract
-from algosdk.abi.method import MethodDict
-from algosdk.transaction import StateSchema
 
 __all__ = [
+    "AppSpecStateDict",
+    "ApplicationSpecification",
     "CallConfig",
     "DefaultArgumentDict",
     "DefaultArgumentType",
     "MethodConfigDict",
-    "OnCompleteActionName",
     "MethodHints",
-    "ApplicationSpecification",
-    "AppSpecStateDict",
-]
-
-
-AppSpecStateDict: TypeAlias = dict[str, dict[str, dict]]
-"""Type defining Application Specification state entries"""
-
-
-class CallConfig(IntFlag):
-    """Describes the type of calls a method can be used for based on {py:class}`algosdk.transaction.OnComplete` type"""
-
-    NEVER = 0
-    """Never handle the specified on completion type"""
-    CALL = 1
-    """Only handle the specified on completion type for application calls"""
-    CREATE = 2
-    """Only handle the specified on completion type for application create calls"""
-    ALL = 3
-    """Handle the specified on completion type for both create and normal application calls"""
-
-
-class StructArgDict(TypedDict):
-    name: str
-    elements: list[list[str]]
-
-
-OnCompleteActionName: TypeAlias = Literal[
-    "no_op", "opt_in", "close_out", "clear_state", "update_application", "delete_application"
+    "OnCompleteActionName",
 ]
-"""String literals representing on completion transaction types"""
-MethodConfigDict: TypeAlias = dict[OnCompleteActionName, CallConfig]
-"""Dictionary of `dict[OnCompletionActionName, CallConfig]` representing allowed actions for each on completion type"""
-DefaultArgumentType: TypeAlias = Literal["abi-method", "local-state", "global-state", "constant"]
-"""Literal values describing the types of default argument sources"""
-
-
-class DefaultArgumentDict(TypedDict):
-    """
-    DefaultArgument is a container for any arguments that may
-    be resolved prior to calling some target method
-    """
-
-    source: DefaultArgumentType
-    data: int | str | bytes | MethodDict
-
-
-StateDict = TypedDict(  # need to use function-form of TypedDict here since "global" is a reserved keyword
-    "StateDict", {"global": AppSpecStateDict, "local": AppSpecStateDict}
-)
-
-
-@dataclasses.dataclass(kw_only=True)
-class MethodHints:
-    """MethodHints provides hints to the caller about how to call the method"""
-
-    #: hint to indicate this method can be called through Dryrun
-    read_only: bool = False
-    #: hint to provide names for tuple argument indices
-    #: method_name=>param_name=>{name:str, elements:[str,str]}
-    structs: dict[str, StructArgDict] = dataclasses.field(default_factory=dict)
-    #: defaults
-    default_arguments: dict[str, DefaultArgumentDict] = dataclasses.field(default_factory=dict)
-    call_config: MethodConfigDict = dataclasses.field(default_factory=dict)
-
-    def empty(self) -> bool:
-        return not self.dictify()
-
-    def dictify(self) -> dict[str, Any]:
-        d: dict[str, Any] = {}
-        if self.read_only:
-            d["read_only"] = True
-        if self.default_arguments:
-            d["default_arguments"] = self.default_arguments
-        if self.structs:
-            d["structs"] = self.structs
-        if any(v for v in self.call_config.values() if v != CallConfig.NEVER):
-            d["call_config"] = _encode_method_config(self.call_config)
-        return d
-
-    @staticmethod
-    def undictify(data: dict[str, Any]) -> "MethodHints":
-        return MethodHints(
-            read_only=data.get("read_only", False),
-            default_arguments=data.get("default_arguments", {}),
-            structs=data.get("structs", {}),
-            call_config=_decode_method_config(data.get("call_config", {})),
-        )
-
-
-def _encode_method_config(mc: MethodConfigDict) -> dict[str, str | None]:
-    return {k: mc[k].name for k in sorted(mc) if mc[k] != CallConfig.NEVER}
-
-
-def _decode_method_config(data: dict[OnCompleteActionName, Any]) -> MethodConfigDict:
-    return {k: CallConfig[v] for k, v in data.items()}
-
-
-def _encode_source(teal_text: str) -> str:
-    return base64.b64encode(teal_text.encode()).decode("utf-8")
-
-
-def _decode_source(b64_text: str) -> str:
-    return base64.b64decode(b64_text).decode("utf-8")
-
-
-def _encode_state_schema(schema: StateSchema) -> dict[str, int]:
-    return {
-        "num_byte_slices": schema.num_byte_slices,
-        "num_uints": schema.num_uints,
-    }
-
-
-def _decode_state_schema(data: dict[str, int]) -> StateSchema:
-    return StateSchema(  # type: ignore[no-untyped-call]
-        num_byte_slices=data.get("num_byte_slices", 0),
-        num_uints=data.get("num_uints", 0),
-    )
-
-
-@dataclasses.dataclass(kw_only=True)
-class ApplicationSpecification:
-    """ARC-0032 application specification
-
-    See <https://github.com/algorandfoundation/ARCs/pull/150>"""
-
-    approval_program: str
-    clear_program: str
-    contract: Contract
-    hints: dict[str, MethodHints]
-    schema: StateDict
-    global_state_schema: StateSchema
-    local_state_schema: StateSchema
-    bare_call_config: MethodConfigDict
-
-    def dictify(self) -> dict:
-        return {
-            "hints": {k: v.dictify() for k, v in self.hints.items() if not v.empty()},
-            "source": {
-                "approval": _encode_source(self.approval_program),
-                "clear": _encode_source(self.clear_program),
-            },
-            "state": {
-                "global": _encode_state_schema(self.global_state_schema),
-                "local": _encode_state_schema(self.local_state_schema),
-            },
-            "schema": self.schema,
-            "contract": self.contract.dictify(),
-            "bare_call_config": _encode_method_config(self.bare_call_config),
-        }
-
-    def to_json(self) -> str:
-        return json.dumps(self.dictify(), indent=4)
-
-    @staticmethod
-    def from_json(application_spec: str) -> "ApplicationSpecification":
-        json_spec = json.loads(application_spec)
-        return ApplicationSpecification(
-            approval_program=_decode_source(json_spec["source"]["approval"]),
-            clear_program=_decode_source(json_spec["source"]["clear"]),
-            schema=json_spec["schema"],
-            global_state_schema=_decode_state_schema(json_spec["state"]["global"]),
-            local_state_schema=_decode_state_schema(json_spec["state"]["local"]),
-            contract=Contract.undictify(json_spec["contract"]),
-            hints={k: MethodHints.undictify(v) for k, v in json_spec["hints"].items()},
-            bare_call_config=_decode_method_config(json_spec.get("bare_call_config", {})),
-        )
-
-    def export(self, directory: Path | str | None = None) -> None:
-        """write out the artifacts generated by the application to disk
-
-        Args:
-            directory(optional): path to the directory where the artifacts should be written
-        """
-        if directory is None:
-            output_dir = Path.cwd()
-        else:
-            output_dir = Path(directory)
-            output_dir.mkdir(exist_ok=True, parents=True)
-
-        (output_dir / "approval.teal").write_text(self.approval_program)
-        (output_dir / "clear.teal").write_text(self.clear_program)
-        (output_dir / "contract.json").write_text(json.dumps(self.contract.dictify(), indent=4))
-        (output_dir / "application.json").write_text(self.to_json())
-
-
-def _state_schema(schema: dict[str, int]) -> StateSchema:
-    return StateSchema(schema.get("num-uint", 0), schema.get("num-byte-slice", 0))  # type: ignore[no-untyped-call]

algokit_utils/applications/__init__.py

@@ -0,0 +1,7 @@
+from algokit_utils.applications.abi import *  # noqa: F403
+from algokit_utils.applications.app_client import *  # noqa: F403
+from algokit_utils.applications.app_deployer import *  # noqa: F403
+from algokit_utils.applications.app_factory import *  # noqa: F403
+from algokit_utils.applications.app_manager import *  # noqa: F403
+from algokit_utils.applications.app_spec import *  # noqa: F403
+from algokit_utils.applications.enums import *  # noqa: F403

algokit_utils/applications/abi.py

@@ -0,0 +1,275 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import TYPE_CHECKING, Any, TypeAlias
+
+import algosdk
+from algosdk.abi.method import Method as AlgorandABIMethod
+from algosdk.atomic_transaction_composer import ABIResult
+
+from algokit_utils.applications.app_spec.arc56 import Arc56Contract, StructField
+from algokit_utils.applications.app_spec.arc56 import Method as Arc56Method
+
+if TYPE_CHECKING:
+    from algokit_utils.models.state import BoxName
+
+ABIValue: TypeAlias = (
+    bool | int | str | bytes | bytearray | list["ABIValue"] | tuple["ABIValue"] | dict[str, "ABIValue"]
+)
+ABIStruct: TypeAlias = dict[str, list[dict[str, "ABIValue"]]]
+Arc56ReturnValueType: TypeAlias = ABIValue | ABIStruct | None
+
+
+ABIType: TypeAlias = algosdk.abi.ABIType
+ABIArgumentType: TypeAlias = algosdk.abi.ABIType | algosdk.abi.ABITransactionType | algosdk.abi.ABIReferenceType
+
+__all__ = [
+    "ABIArgumentType",
+    "ABIReturn",
+    "ABIStruct",
+    "ABIType",
+    "ABIValue",
+    "Arc56ReturnValueType",
+    "BoxABIValue",
+    "get_abi_decoded_value",
+    "get_abi_encoded_value",
+    "get_abi_struct_from_abi_tuple",
+    "get_abi_tuple_from_abi_struct",
+    "get_abi_tuple_type_from_abi_struct_definition",
+    "get_arc56_value",
+]
+
+
+@dataclass(kw_only=True)
+class ABIReturn:
+    """Represents the return value from an ABI method call.
+
+    Wraps the raw return value and decoded value along with any decode errors.
+    """
+
+    raw_value: bytes | None = None
+    """The raw return value from the method call"""
+    value: ABIValue | None = None
+    """The decoded return value from the method call"""
+    method: AlgorandABIMethod | None = None
+    """The ABI method definition"""
+    decode_error: Exception | None = None
+    """The exception that occurred during decoding, if any"""
+    tx_info: dict[str, Any] | None = None
+    """The transaction info for the method call from raw algosdk `ABIResult`"""
+
+    def __init__(self, result: ABIResult) -> None:
+        self.decode_error = result.decode_error
+        if not self.decode_error:
+            self.raw_value = result.raw_value
+            self.value = result.return_value
+            self.method = result.method
+            self.tx_info = result.tx_info
+
+    @property
+    def is_success(self) -> bool:
+        """Returns True if the ABI call was successful (no decode error)
+
+        :return: True if no decode error occurred, False otherwise
+        """
+        return self.decode_error is None
+
+    def get_arc56_value(
+        self, method: Arc56Method | AlgorandABIMethod, structs: dict[str, list[StructField]]
+    ) -> Arc56ReturnValueType:
+        """Gets the ARC-56 formatted return value.
+
+        :param method: The ABI method definition
+        :param structs: Dictionary of struct definitions
+        :return: The decoded return value in ARC-56 format
+        """
+        return get_arc56_value(self, method, structs)
+
+
+def get_arc56_value(
+    abi_return: ABIReturn, method: Arc56Method | AlgorandABIMethod, structs: dict[str, list[StructField]]
+) -> Arc56ReturnValueType:
+    """Gets the ARC-56 formatted return value from an ABI return.
+
+    :param abi_return: The ABI return value to decode
+    :param method: The ABI method definition
+    :param structs: Dictionary of struct definitions
+    :raises ValueError: If there was an error decoding the return value
+    :return: The decoded return value in ARC-56 format
+    """
+    if isinstance(method, AlgorandABIMethod):
+        type_str = method.returns.type
+        struct = None  # AlgorandABIMethod doesn't have struct info
+    else:
+        type_str = method.returns.type
+        struct = method.returns.struct
+
+    if type_str == "void" or abi_return.value is None:
+        return None
+
+    if abi_return.decode_error:
+        raise ValueError(abi_return.decode_error)
+
+    raw_value = abi_return.raw_value
+
+    # Handle AVM types
+    if type_str == "AVMBytes":
+        return raw_value
+    if type_str == "AVMString" and raw_value:
+        return raw_value.decode("utf-8")
+    if type_str == "AVMUint64" and raw_value:
+        return ABIType.from_string("uint64").decode(raw_value)  # type: ignore[no-any-return]
+
+    # Handle structs
+    if struct and struct in structs:
+        return_tuple = abi_return.value
+        return Arc56Contract.get_abi_struct_from_abi_tuple(return_tuple, structs[struct], structs)
+
+    # Return as-is
+    return abi_return.value
+
+
+def get_abi_encoded_value(value: Any, type_str: str, structs: dict[str, list[StructField]]) -> bytes:  # noqa: PLR0911, ANN401
+    """Encodes a value according to its ABI type.
+
+    :param value: The value to encode
+    :param type_str: The ABI type string
+    :param structs: Dictionary of struct definitions
+    :raises ValueError: If the value cannot be encoded for the given type
+    :return: The ABI encoded bytes
+    """
+    if isinstance(value, (bytes | bytearray)):
+        return value
+    if type_str == "AVMUint64":
+        return ABIType.from_string("uint64").encode(value)
+    if type_str in ("AVMBytes", "AVMString"):
+        if isinstance(value, str):
+            return value.encode("utf-8")
+        if not isinstance(value, (bytes | bytearray)):
+            raise ValueError(f"Expected bytes value for {type_str}, but got {type(value)}")
+        return value
+    if type_str in structs:
+        tuple_type = get_abi_tuple_type_from_abi_struct_definition(structs[type_str], structs)
+        if isinstance(value, (list | tuple)):
+            return tuple_type.encode(value)  # type: ignore[arg-type]
+        else:
+            tuple_values = get_abi_tuple_from_abi_struct(value, structs[type_str], structs)
+            return tuple_type.encode(tuple_values)
+    else:
+        abi_type = ABIType.from_string(type_str)
+        return abi_type.encode(value)
+
+
+def get_abi_decoded_value(
+    value: bytes | int | str, type_str: str | ABIArgumentType, structs: dict[str, list[StructField]]
+) -> ABIValue:
+    """Decodes a value according to its ABI type.
+
+    :param value: The value to decode
+    :param type_str: The ABI type string or type object
+    :param structs: Dictionary of struct definitions
+    :return: The decoded ABI value
+    """
+    type_value = str(type_str)
+
+    if type_value == "AVMBytes" or not isinstance(value, bytes):
+        return value
+    if type_value == "AVMString":
+        return value.decode("utf-8")
+    if type_value == "AVMUint64":
+        return ABIType.from_string("uint64").decode(value)  # type: ignore[no-any-return]
+    if type_value in structs:
+        tuple_type = get_abi_tuple_type_from_abi_struct_definition(structs[type_value], structs)
+        decoded_tuple = tuple_type.decode(value)
+        return get_abi_struct_from_abi_tuple(decoded_tuple, structs[type_value], structs)
+    return ABIType.from_string(type_value).decode(value)  # type: ignore[no-any-return]
+
+
+def get_abi_tuple_from_abi_struct(
+    struct_value: dict[str, Any],
+    struct_fields: list[StructField],
+    structs: dict[str, list[StructField]],
+) -> list[Any]:
+    """Converts an ABI struct to a tuple representation.
+
+    :param struct_value: The struct value as a dictionary
+    :param struct_fields: List of struct field definitions
+    :param structs: Dictionary of struct definitions
+    :raises ValueError: If a required field is missing from the struct
+    :return: The struct as a tuple
+    """
+    result = []
+    for field in struct_fields:
+        key = field.name
+        if key not in struct_value:
+            raise ValueError(f"Missing value for field '{key}'")
+        value = struct_value[key]
+        field_type = field.type
+        if isinstance(field_type, str):
+            if field_type in structs:
+                value = get_abi_tuple_from_abi_struct(value, structs[field_type], structs)
+        elif isinstance(field_type, list):
+            value = get_abi_tuple_from_abi_struct(value, field_type, structs)
+        result.append(value)
+    return result
+
+
+def get_abi_tuple_type_from_abi_struct_definition(
+    struct_def: list[StructField], structs: dict[str, list[StructField]]
+) -> algosdk.abi.TupleType:
+    """Creates a TupleType from a struct definition.
+
+    :param struct_def: The struct field definitions
+    :param structs: Dictionary of struct definitions
+    :raises ValueError: If a field type is invalid
+    :return: The TupleType representing the struct
+    """
+    types = []
+    for field in struct_def:
+        field_type = field.type
+        if isinstance(field_type, str):
+            if field_type in structs:
+                types.append(get_abi_tuple_type_from_abi_struct_definition(structs[field_type], structs))
+            else:
+                types.append(ABIType.from_string(field_type))  # type: ignore[arg-type]
+        elif isinstance(field_type, list):
+            types.append(get_abi_tuple_type_from_abi_struct_definition(field_type, structs))
+        else:
+            raise ValueError(f"Invalid field type: {field_type}")
+    return algosdk.abi.TupleType(types)
+
+
+def get_abi_struct_from_abi_tuple(
+    decoded_tuple: Any,  # noqa: ANN401
+    struct_fields: list[StructField],
+    structs: dict[str, list[StructField]],
+) -> dict[str, Any]:
+    """Converts a decoded tuple to an ABI struct.
+
+    :param decoded_tuple: The tuple to convert
+    :param struct_fields: List of struct field definitions
+    :param structs: Dictionary of struct definitions
+    :return: The tuple as a struct dictionary
+    """
+    result = {}
+    for i, field in enumerate(struct_fields):
+        key = field.name
+        field_type = field.type
+        value = decoded_tuple[i]
+        if isinstance(field_type, str):
+            if field_type in structs:
+                value = get_abi_struct_from_abi_tuple(value, structs[field_type], structs)
+        elif isinstance(field_type, list):
+            value = get_abi_struct_from_abi_tuple(value, field_type, structs)
+        result[key] = value
+    return result
+
+
+@dataclass(kw_only=True, frozen=True)
+class BoxABIValue:
+    """Represents an ABI value stored in a box."""
+
+    name: BoxName
+    """The name of the box"""
+    value: ABIValue
+    """The ABI value stored in the box"""