algokit-utils 5.0.0a3__py3-none-any.whl

algokit_algosdk/app_access.py

@@ -0,0 +1,228 @@
+from collections import OrderedDict
+from typing import List, Optional, Tuple, Union
+
+from . import encoding
+from .box_reference import BoxReference
+
+
+def translate_to_resource_references(
+    app_id: int,
+    accounts: Optional[List[str]] = None,
+    foreign_assets: Optional[List[int]] = None,
+    foreign_apps: Optional[List[int]] = None,
+    boxes: Optional[List[Tuple[int, bytes]]] = None,
+    holdings: Optional[List[Tuple[int, str]]] = None,
+    locals: Optional[List[Tuple[int, str]]] = None,
+) -> List["ResourceReference"]:
+    """
+    Convert accounts, apps, assets, boxes, holdings, locals into list of ResourceReference
+    that is suitable for txn.Access field creation.
+
+    Args:
+        app_id (int): current application id
+        accounts (list[string], optional): list of additional accounts involved in call
+        foreign_apps (list[int], optional): list of other applications (identified by index) involved in call
+        foreign_assets (list[int], optional): list of assets involved in call
+        boxes(list[(int, bytes)], optional): list of tuples specifying app id and key for boxes the app may access
+        holdings (list[int, str], optional): lists of tuples specifying the asset holdings to be accessed during evaluation of the application;
+            zero (empty) address means sender
+        locals (list[int, str], optional): lists of tuples specifying the local states to be accessed during evaluation of the application;
+            zero (empty) address means sender
+    """
+    access: List["ResourceReference"] = []
+
+    def ensure(target: "ResourceReference") -> int:
+        for idx, a in enumerate(access):
+            if (
+                a.address == target.address
+                and a.asset_id == target.asset_id
+                and a.app_id == target.app_id
+            ):
+                return idx + 1
+        access.append(target)
+        return len(access)
+
+    for account in accounts or []:
+        ensure(ResourceReference(address=account))
+
+    for asset in foreign_assets or []:
+        ensure(ResourceReference(asset_id=asset))
+
+    for app in foreign_apps or []:
+        ensure(ResourceReference(app_id=app))
+
+    for asset, addr in holdings or []:
+        addr_idx = 0
+        if addr:
+            addr_idx = ensure(ResourceReference(address=addr))
+        asset_idx = ensure(ResourceReference(asset_id=asset))
+        access.append(
+            ResourceReference(
+                holding_reference=HoldingRef(
+                    asset_index=asset_idx, addr_index=addr_idx
+                )
+            )
+        )
+
+    for app, addr in locals or []:
+        app_idx = 0
+        if app and app != app_id:
+            app_idx = ensure(ResourceReference(app_id=app))
+        addr_idx = 0
+        if addr:
+            addr_idx = ensure(ResourceReference(address=addr))
+        access.append(
+            ResourceReference(
+                locals_reference=LocalsRef(
+                    app_index=app_idx, addr_index=addr_idx
+                )
+            )
+        )
+
+    for app, name in boxes or []:
+        app_idx = 0
+        if app and app != app_id:
+            app_idx = ensure(ResourceReference(app_id=app))
+        access.append(
+            ResourceReference(
+                box_reference=BoxReference(app_index=app_idx, name=name)
+            )
+        )
+
+    return access
+
+
+class ResourceReference:
+    def __init__(
+        self,
+        address: Optional[str] = None,
+        asset_id: Optional[int] = None,
+        app_id: Optional[int] = None,
+        box_reference: Optional[BoxReference] = None,
+        holding_reference: Optional["HoldingRef"] = None,
+        locals_reference: Optional["LocalsRef"] = None,
+    ):
+        self.app_id = app_id
+        self.address = address
+        self.asset_id = asset_id
+        self.box_reference = box_reference
+        self.holding_reference = holding_reference
+        self.locals_reference = locals_reference
+
+    def dictify(self):
+        d = dict()
+        if self.address:
+            d["d"] = encoding.decode_address(self.address)
+        if self.asset_id:
+            d["s"] = self.asset_id
+        if self.app_id:
+            d["p"] = self.app_id
+        if self.box_reference:
+            d["b"] = self.box_reference.dictify()
+        if self.holding_reference:
+            d["h"] = self.holding_reference.dictify()
+        if self.locals_reference:
+            d["l"] = self.locals_reference.dictify()
+        od = OrderedDict(sorted(d.items()))
+        return od
+
+    @staticmethod
+    def undictify(d):
+        return ResourceReference(
+            address=encoding.encode_address(d["d"]) if "d" in d else "",
+            asset_id=d["s"] if "s" in d else None,
+            app_id=d["p"] if "p" in d else None,
+            box_reference=BoxReference.undictify(d["b"]) if "b" in d else None,
+            holding_reference=(
+                HoldingRef.undictify(d["h"]) if "h" in d else None
+            ),
+            locals_reference=LocalsRef.undictify(d["l"]) if "l" in d else None,
+        )
+
+    def __eq__(self, value):
+        if not isinstance(value, ResourceReference):
+            return False
+        return (
+            self.address == value.address
+            and self.asset_id == value.asset_id
+            and self.app_id == value.app_id
+            and self.box_reference == value.box_reference
+            and self.holding_reference == value.holding_reference
+            and self.locals_reference == value.locals_reference
+        )
+
+
+class LocalsRef:
+    """
+    Represents a local reference in txn.Access with an app index and address index.
+
+    Args:
+        app_index (int): index of the application in the access array
+        addr_index (int): index of the address in the access array
+    """
+
+    def __init__(self, app_index: int, addr_index: int):
+        self.app_index = app_index
+        self.addr_index = addr_index
+
+    def dictify(self):
+        d = dict()
+        if self.app_index:
+            d["p"] = self.app_index
+        if self.addr_index:
+            d["d"] = self.addr_index
+        od = OrderedDict(sorted(d.items()))
+        return od
+
+    @staticmethod
+    def undictify(d):
+        return LocalsRef(
+            d["p"] if "p" in d else 0,
+            d["d"] if "d" in d else 0,
+        )
+
+    def __eq__(self, other):
+        if not isinstance(other, LocalsRef):
+            return False
+        return (
+            self.app_index == other.app_index
+            and self.addr_index == other.addr_index
+        )
+
+
+class HoldingRef:
+    """
+    Represents a holding reference in txn.Access with an asset index and address index.
+
+    Args:
+        asset_index (int): index of the asset in the access array
+        addr_index (int): index of the address in the access array
+    """
+
+    def __init__(self, asset_index: int, addr_index: int):
+        self.asset_index = asset_index
+        self.addr_index = addr_index
+
+    def dictify(self):
+        d = dict()
+        if self.asset_index:
+            d["s"] = self.asset_index
+        if self.addr_index:
+            d["d"] = self.addr_index
+        od = OrderedDict(sorted(d.items()))
+        return od
+
+    @staticmethod
+    def undictify(d):
+        return HoldingRef(
+            d["s"] if "s" in d else 0,
+            d["d"] if "d" in d else 0,
+        )
+
+    def __eq__(self, other):
+        if not isinstance(other, HoldingRef):
+            return False
+        return (
+            self.asset_index == other.asset_index
+            and self.addr_index == other.addr_index
+        )

algokit_algosdk/box_reference.py

@@ -0,0 +1,100 @@
+from collections import OrderedDict
+from typing import List, Tuple, Union
+
+from . import encoding, error
+
+
+class BoxReference:
+    """
+    Represents a box reference with a foreign app index and the box name.
+
+    Args:
+        app_index (int): index of the application in the foreign app array
+        name (bytes): key for the box in bytes
+    """
+
+    def __init__(self, app_index: int, name: bytes):
+        if app_index < 0:
+            raise ValueError(
+                f"Box app index must be a non-negative integer: {app_index}"
+            )
+        self.app_index = app_index
+        self.name = name
+
+    @staticmethod
+    def translate_box_reference(
+        ref: Union[
+            Tuple[int, Union[bytes, bytearray, str, int]], "BoxReference"
+        ],
+        foreign_apps: List[int],
+        this_app_id: int,
+    ) -> "BoxReference":
+        # Do not need to translate the references if they are already BoxReference type.
+        if isinstance(ref, BoxReference):
+            return ref
+
+        # Try checking reference id and name type.
+        ref_id, ref_name = ref[0], encoding.encode_as_bytes(ref[1])
+        if not isinstance(ref_id, int):
+            raise TypeError("Box reference ID must be an int")
+
+        index = 0
+        try:
+            # Foreign apps start from index 1; index 0 is its own app ID.
+            index = foreign_apps.index(ref_id) + 1
+        except (ValueError, AttributeError):
+            # Check if the app referenced is itself after checking the
+            # foreign apps array (in case its own app id is in its own
+            # foreign apps array).
+            if ref_id != 0 and ref_id != this_app_id:
+                raise error.InvalidForeignIndexError(
+                    f"Box ref with appId {ref_id} not in foreign-apps"
+                )
+        return BoxReference(index, ref_name)
+
+    @staticmethod
+    def translate_box_references(
+        references: List[Tuple[int, Union[bytes, bytearray, str, int]]],
+        foreign_apps: List[int],
+        this_app_id: int,
+    ) -> List["BoxReference"]:
+        """
+        Translates a list of tuples with app IDs and names into an array of
+        BoxReferences with foreign indices.
+
+        Args:
+            references (list[(int, bytes)]): list of tuples specifying app id
+                and key for boxes the app may access
+            foreign_apps (list[int]): list of other applications in appl call
+            this_app_id (int): app ID of the box being references
+        """
+        if not references:
+            return []
+
+        return [
+            BoxReference.translate_box_reference(
+                ref, foreign_apps, this_app_id
+            )
+            for ref in references
+        ]
+
+    def dictify(self):
+        d = dict()
+        if self.app_index:
+            d["i"] = self.app_index
+        if self.name:
+            d["n"] = self.name
+        od = OrderedDict(sorted(d.items()))
+        return od
+
+    @staticmethod
+    def undictify(d):
+        return BoxReference(
+            d["i"] if "i" in d else 0,
+            d["n"] if "n" in d else b"",
+        )
+
+    def __eq__(self, other):
+        if not isinstance(other, BoxReference):
+            return False
+        return self.app_index == other.app_index and self.name == other.name

algokit_algosdk/constants.py

@@ -0,0 +1,147 @@
+# Vendored from py-algorand-sdk/algosdk/constants.py (MIT License).
+
+"""
+Contains useful constants.
+"""
+KMD_AUTH_HEADER = "X-KMD-API-Token"
+"""str: header key for kmd requests"""
+ALGOD_AUTH_HEADER = "X-Algo-API-Token"
+"""str: header key for algod requests"""
+INDEXER_AUTH_HEADER = "X-Indexer-API-Token"
+"""str: header key for indexer requests"""
+UNVERSIONED_PATHS = ["/health", "/versions", "/metrics", "/genesis", "/ready"]
+"""str[]: paths that don't use the version path prefix"""
+NO_AUTH: list[str] = []
+"""str[]: requests that don't require authentication"""
+
+
+# transaction types
+PAYMENT_TXN = "pay"
+"""str: indicates a payment transaction"""
+KEYREG_TXN = "keyreg"
+"""str: indicates a key registration transaction"""
+ASSETCONFIG_TXN = "acfg"
+"""str: indicates an asset configuration transaction"""
+ASSETFREEZE_TXN = "afrz"
+"""str: indicates an asset freeze transaction"""
+ASSETTRANSFER_TXN = "axfer"
+"""str: indicates an asset transfer transaction"""
+APPCALL_TXN = "appl"
+"""str: indicates an app call transaction, allows creating, deleting, and interacting with an application"""
+STATEPROOF_TXN = "stpf"
+"""str: indicates an state proof transaction"""
+HEARTBEAT_TXN = "hb"
+"""str: indicates a heartbeat transaction"""
+
+# note field types
+NOTE_FIELD_TYPE_DEPOSIT = "d"
+"""str: indicates a signed deposit in NoteField"""
+NOTE_FIELD_TYPE_BID = "b"
+"""str: indicates a signed bid in NoteField"""
+NOTE_FIELD_TYPE_SETTLEMENT = "s"
+"""str: indicates a signed settlement in NoteField"""
+NOTE_FIELD_TYPE_PARAMS = "p"
+"""str: indicates signed params in NoteField"""
+
+# prefixes
+TXID_PREFIX = b"TX"
+"""bytes: transaction prefix when signing"""
+TGID_PREFIX = b"TG"
+"""bytes: transaction group prefix when computing the group ID"""
+BID_PREFIX = b"aB"
+"""bytes: bid prefix when signing"""
+BYTES_PREFIX = b"MX"
+"""bytes: bytes prefix when signing"""
+MSIG_ADDR_PREFIX = "MultisigAddr"
+"""str: prefix for multisig addresses"""
+LOGIC_PREFIX = b"Program"
+"""bytes: program (logic) prefix when signing"""
+MULTISIG_LOGIC_PREFIX = b"MsigProgram"
+"""bytes: program (logic) prefix when signing"""
+LOGIC_DATA_PREFIX = b"ProgData"
+"""bytes: program (logic) data prefix when signing"""
+APPID_PREFIX = b"appID"
+"""bytes: application ID prefix when signing"""
+
+
+HASH_LEN = 32
+"""int: how long various hash-like fields should be"""
+CHECK_SUM_LEN_BYTES = 4
+"""int: how long checksums should be"""
+KEN_LEN_BYTES = 32
+"""int: how long addresses are in bytes"""
+ADDRESS_LEN = 58
+"""int: how long addresses are in base32, including the checksum"""
+MNEMONIC_LEN = 25
+"""int: how long mnemonic phrases are"""
+MIN_TXN_FEE = 1000
+"""int: minimum transaction fee"""
+MICROALGOS_TO_ALGOS_RATIO = 1000000
+"""int: how many microalgos per algo"""
+METADATA_LENGTH = 32
+"""int: length of asset metadata"""
+NOTE_MAX_LENGTH = 1024
+"""int: maximum length of note field"""
+LEASE_LENGTH = 32
+"""int: byte length of leases"""
+MULTISIG_ACCOUNT_LIMIT = 255
+"""int: maximum number of addresses in a multisig account"""
+TX_GROUP_LIMIT = 16
+"""int: maximum number of transaction in a transaction group"""
+MAX_ASSET_DECIMALS = 19
+"""int: maximum value for decimals in assets"""
+
+# logic sig related
+LOGIC_SIG_MAX_COST = 20000
+"""int: max execution cost of a teal program"""
+LOGIC_SIG_MAX_SIZE = 1000
+"""int: max size of a teal program and its arguments in bytes"""
+
+APP_PAGE_MAX_SIZE = 2048
+"""int: max size of a page for an application in bytes"""
+
+ZERO_ADDRESS = "AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAY5HFKQ"
+"""str: algorand encoded address of 32 zero bytes"""
+
+# for backward compatibility:
+kmd_auth_header = KMD_AUTH_HEADER
+algod_auth_header = ALGOD_AUTH_HEADER
+indexer_auth_header = INDEXER_AUTH_HEADER
+unversioned_paths = UNVERSIONED_PATHS
+no_auth = NO_AUTH
+payment_txn = PAYMENT_TXN
+keyreg_txn = KEYREG_TXN
+assetconfig_txn = ASSETCONFIG_TXN
+assetfreeze_txn = ASSETFREEZE_TXN
+assettransfer_txn = ASSETTRANSFER_TXN
+appcall_txn = APPCALL_TXN
+note_field_type_deposit = NOTE_FIELD_TYPE_DEPOSIT
+note_field_type_bid = NOTE_FIELD_TYPE_BID
+note_field_type_settlement = NOTE_FIELD_TYPE_SETTLEMENT
+note_field_type_params = NOTE_FIELD_TYPE_PARAMS
+txid_prefix = TXID_PREFIX
+tgid_prefix = TGID_PREFIX
+bid_prefix = BID_PREFIX
+bytes_prefix = BYTES_PREFIX
+msig_addr_prefix = MSIG_ADDR_PREFIX
+logic_prefix = LOGIC_PREFIX
+multisig_logic_prefix = MULTISIG_LOGIC_PREFIX
+logic_data_prefix = LOGIC_DATA_PREFIX
+hash_len = HASH_LEN
+check_sum_len_bytes = CHECK_SUM_LEN_BYTES
+key_len_bytes = KEN_LEN_BYTES
+address_len = ADDRESS_LEN
+mnemonic_len = MNEMONIC_LEN
+min_txn_fee = MIN_TXN_FEE
+microalgos_to_algos_ratio = MICROALGOS_TO_ALGOS_RATIO
+metadata_length = METADATA_LENGTH
+note_max_length = NOTE_MAX_LENGTH
+lease_length = LEASE_LENGTH
+multisig_account_limit = MULTISIG_ACCOUNT_LIMIT
+tx_group_limit = TX_GROUP_LIMIT
+max_asset_decimals = MAX_ASSET_DECIMALS
+logic_sig_max_cost = LOGIC_SIG_MAX_COST
+logic_sig_max_size = LOGIC_SIG_MAX_SIZE
+app_page_max_size = APP_PAGE_MAX_SIZE
+stateproof_txn = STATEPROOF_TXN
+heartbeat_txn = HEARTBEAT_TXN

algokit_algosdk/encoding.py

@@ -0,0 +1,89 @@
+import base64
+
+# Derived from py-algorand-sdk/algosdk/encoding.py (MIT License).
+
+from Cryptodome.Hash import SHA512
+
+from . import constants, error
+
+__all__ = [
+    "checksum",
+    "decode_address",
+    "encode_address",
+    "is_valid_address",
+]
+
+
+def is_valid_address(addr: str | bytes | None) -> bool:
+    """
+    Check if the string address is a valid Algorand address.
+
+    Args:
+        addr: base32 address
+    """
+    if not isinstance(addr, str):
+        return False
+
+    if len(_undo_padding(addr)) != constants.address_len:
+        return False
+
+    try:
+        decoded = decode_address(addr)
+        return isinstance(decoded, bytes)
+    except Exception:
+        return False
+
+
+def decode_address(addr: str | None) -> bytes | str | None:
+    """
+    Decode a string address into its address bytes and checksum.
+    """
+    if not addr:
+        return addr
+    if len(addr) != constants.address_len:
+        raise error.WrongKeyLengthError
+
+    decoded = base64.b32decode(_correct_padding(addr))
+    addr_bytes = decoded[: -constants.check_sum_len_bytes]
+    expected_checksum = decoded[-constants.check_sum_len_bytes :]
+    chksum = _checksum(addr_bytes)
+
+    if chksum == expected_checksum:
+        return addr_bytes
+    raise error.WrongChecksumError
+
+
+def encode_address(addr_bytes: bytes | None) -> bytes | str | None:
+    """
+    Encode a byte address into a string composed of the encoded bytes and the checksum.
+    """
+    if not addr_bytes:
+        return addr_bytes
+    if len(addr_bytes) != constants.key_len_bytes:
+        raise error.WrongKeyBytesLengthError
+    chksum = _checksum(addr_bytes)
+    addr = base64.b32encode(addr_bytes + chksum)
+    return _undo_padding(addr.decode())
+
+
+def checksum(data: bytes) -> bytes:
+    """
+    Compute the checksum of arbitrary binary input.
+    """
+    digest = SHA512.new(truncate="256")
+    digest.update(data)
+    return digest.digest()
+
+
+def _checksum(addr_bytes: bytes) -> bytes:
+    return checksum(addr_bytes)[-constants.check_sum_len_bytes :]
+
+
+def _correct_padding(value: str) -> str:
+    if len(value) % 8 == 0:
+        return value
+    return value + "=" * (8 - len(value) % 8)
+
+
+def _undo_padding(value: str) -> str:
+    return value.strip("=")