algokit-utils 5.0.0a3__py3-none-any.whl

algokit_algosdk/error.py

@@ -0,0 +1,180 @@
+# Vendored from py-algorand-sdk/algosdk/error.py (MIT License).
+
+
+class BadTxnSenderError(Exception):
+    def __init__(self) -> None:
+        super().__init__("transaction sender does not match multisig parameters")
+
+
+class InvalidThresholdError(Exception):
+    def __init__(self) -> None:
+        super().__init__("invalid multisig threshold")
+
+
+class InvalidSecretKeyError(Exception):
+    def __init__(self) -> None:
+        super().__init__("secret key has no corresponding public key in multisig")
+
+
+class MergeKeysMismatchError(Exception):
+    def __init__(self) -> None:
+        super().__init__("multisig parameters do not match")
+
+
+class MergeAuthAddrMismatchError(Exception):
+    def __init__(self) -> None:
+        super().__init__("multisig transaction auth addresses do not match")
+
+
+class DuplicateSigMismatchError(Exception):
+    def __init__(self) -> None:
+        super().__init__("mismatched duplicate signatures in multisig")
+
+
+class LogicSigOverspecifiedSignature(Exception):
+    def __init__(self) -> None:
+        super().__init__("LogicSig has too many signatures. At most one of sig or msig may be present")
+
+
+class LogicSigSigningKeyMissing(Exception):
+    def __init__(self) -> None:
+        super().__init__("LogicSigAccount is missing signing key")
+
+
+class WrongAmountType(Exception):
+    def __init__(self) -> None:
+        super().__init__("amount (amt) must be a non-negative integer")
+
+
+class WrongChecksumError(Exception):
+    def __init__(self) -> None:
+        super().__init__("checksum failed to validate")
+
+
+class WrongKeyLengthError(Exception):
+    def __init__(self) -> None:
+        super().__init__("key length must be 58")
+
+
+class WrongMnemonicLengthError(Exception):
+    def __init__(self) -> None:
+        super().__init__("mnemonic length must be 25")
+
+
+class WrongHashLengthError(Exception):
+    """General error that is normally changed to be more specific"""
+
+    def __init__(self) -> None:
+        super().__init__("length must be 32 bytes")
+
+
+class WrongKeyBytesLengthError(Exception):
+    def __init__(self) -> None:
+        super().__init__("key length in bytes must be 32")
+
+
+class UnknownMsigVersionError(Exception):
+    def __init__(self) -> None:
+        super().__init__("unknown multisig version != 1")
+
+
+class WrongMetadataLengthError(Exception):
+    def __init__(self) -> None:
+        super().__init__("metadata length must be 32 bytes")
+
+
+class WrongLeaseLengthError(Exception):
+    def __init__(self) -> None:
+        super().__init__("lease length must be 32 bytes")
+
+
+class WrongNoteType(Exception):
+    def __init__(self) -> None:
+        super().__init__('note must be of type "bytes"')
+
+
+class WrongNoteLength(Exception):
+    def __init__(self) -> None:
+        super().__init__("note length must be at most 1024")
+
+
+class InvalidProgram(Exception):
+    def __init__(self, message: str = "invalid program for logic sig") -> None:
+        super().__init__(message)
+
+
+class TransactionGroupSizeError(Exception):
+    def __init__(self) -> None:
+        super().__init__("transaction groups are limited to 16 transactions")
+
+
+class MultisigAccountSizeError(Exception):
+    def __init__(self) -> None:
+        super().__init__("multisig accounts are limited to 256 addresses")
+
+
+class OutOfRangeDecimalsError(Exception):
+    def __init__(self) -> None:
+        super().__init__("decimals must be between 0 and 19, inclusive")
+
+
+class EmptyAddressError(Exception):
+    def __init__(self) -> None:
+        super().__init__(
+            "manager, freeze, reserve, and clawback should not be empty unless strict_empty_address_check is set to False",
+        )
+
+
+class OverspecifiedRoundError(Exception):
+    def __init__(self) -> None:
+        super().__init__("Two arguments were given for the round or block number; please only give one")
+
+
+class UnderspecifiedRoundError(Exception):
+    def __init__(self) -> None:
+        super().__init__("Please specify a round number")
+
+
+class ZeroAddressError(Exception):
+    def __init__(self) -> None:
+        super().__init__(
+            "For the zero address, please specify AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAY5HFKQ"
+        )
+
+
+class KeyregOnlineTxnInitError(Exception):
+    def __init__(self, attr: str) -> None:
+        super().__init__(attr + " should not be None")
+
+
+class KMDHTTPError(Exception):
+    pass
+
+
+class AlgodRequestError(Exception):
+    def __init__(self, msg: str) -> None:
+        super().__init__(msg)
+
+
+class AlgodHTTPError(Exception):
+    def __init__(self, msg: str, code: int | None = None, data: str | None = None) -> None:
+        super().__init__(msg)
+        self.code = code
+        self.data = data
+
+
+class AlgodResponseError(Exception):
+    def __init__(self, msg: str) -> None:
+        super().__init__(msg)
+
+
+class IndexerHTTPError(Exception):
+    pass
+
+
+class ConfirmationTimeoutError(Exception):
+    pass
+
+
+class TransactionRejectedError(Exception):
+    pass

algokit_algosdk/logic.py

@@ -0,0 +1,61 @@
+import base64
+
+from nacl.signing import SigningKey
+
+# Vendored from py-algorand-sdk/algosdk/logic.py (MIT License).
+
+from . import constants, encoding
+from .error import InvalidProgram
+
+__all__ = [
+    "address",
+    "get_application_address",
+    "teal_sign",
+    "teal_sign_from_program",
+]
+
+
+def address(program: bytes) -> str:
+    """Return the address of the program."""
+    to_sign = constants.logic_prefix + program
+    checksum = encoding.checksum(to_sign)
+    encoded = encoding.encode_address(checksum)
+    assert isinstance(encoded, str)
+    return encoded
+
+
+def teal_sign(private_key: str, data: bytes, contract_addr: str) -> bytes:
+    """
+    Return the signature suitable for ed25519verify TEAL opcode.
+    """
+    decoded_key = base64.b64decode(private_key)
+    signing_key = SigningKey(decoded_key[: constants.key_len_bytes])
+
+    contract_bytes = encoding.decode_address(contract_addr)
+    if not isinstance(contract_bytes, bytes):
+        raise InvalidProgram("contract address failed to decode")
+
+    to_sign = constants.logic_data_prefix + contract_bytes + data
+    signed = signing_key.sign(to_sign)
+    return signed.signature
+
+
+def teal_sign_from_program(private_key: str, data: bytes, program: bytes) -> bytes:
+    """
+    Return the signature suitable for ed25519verify TEAL opcode using the program hash.
+    """
+    return teal_sign(private_key, data, address(program))
+
+
+def get_application_address(app_id: int) -> str:
+    """
+    Return the escrow address of an application.
+    """
+    if not isinstance(app_id, int):
+        raise TypeError(f"Expected an int for app_id but received {type(app_id)}")
+
+    to_sign = constants.APPID_PREFIX + app_id.to_bytes(8, "big")
+    checksum = encoding.checksum(to_sign)
+    encoded = encoding.encode_address(checksum)
+    assert isinstance(encoded, str)
+    return encoded

algokit_algosdk/logicsig.py

@@ -0,0 +1,218 @@
+import base64
+import binascii
+from collections import OrderedDict
+from typing import Sequence
+
+from nacl.exceptions import BadSignatureError
+from nacl.signing import SigningKey, VerifyKey
+
+from . import constants, encoding, error
+from .multisig import Multisig
+
+# Vendored from py-algorand-sdk/algosdk/transaction.py (logic sig sections) under MIT License.
+
+__all__ = ["LogicSig", "LogicSigAccount"]
+
+
+class LogicSig:
+    """
+    Represents a logic signature consisting of compiled TEAL bytes and optional arguments.
+    """
+
+    def __init__(self, program: bytes, args: Sequence[bytes] | None = None) -> None:
+        self._sanity_check_program(program)
+        self.logic = program
+        self.args = list(args) if args else None
+        self.sig: str | None = None
+        self.msig: Multisig | None = None
+        self.lmsig: Multisig | None = None
+
+    @staticmethod
+    def _sanity_check_program(program: bytes) -> None:
+        """
+        Reject common user mistakes (passing addresses or base64 strings instead of bytecode).
+        """
+
+        def is_ascii_printable(program_bytes: bytes) -> bool:
+            return all(x == ord("\n") or (ord(" ") <= x <= ord("~")) for x in program_bytes)
+
+        if not program:
+            raise error.InvalidProgram("empty program")
+
+        if is_ascii_printable(program):
+            try:
+                encoding.decode_address(program.decode("utf-8"))
+                raise error.InvalidProgram("requesting program bytes, got Algorand address")
+            except (error.WrongChecksumError, error.WrongKeyLengthError):
+                pass
+
+            try:
+                base64.b64decode(program.decode("utf-8"))
+                raise error.InvalidProgram("program should not be b64 encoded")
+            except binascii.Error:
+                pass
+
+            raise error.InvalidProgram("program bytes look ASCII, not compiled TEAL")
+
+    def dictify(self) -> OrderedDict[str, object]:
+        payload: OrderedDict[str, object] = OrderedDict()
+        if self.args:
+            payload["arg"] = self.args
+        payload["l"] = self.logic
+        if self.sig:
+            payload["sig"] = base64.b64decode(self.sig)
+        elif self.msig:
+            payload["msig"] = self.msig.dictify()
+        elif self.lmsig:
+            payload["lmsig"] = self.lmsig.dictify()
+        return payload
+
+    @staticmethod
+    def undictify(data: dict[str, object]) -> "LogicSig":
+        lsig = LogicSig(data["l"], data.get("arg"))  # type: ignore[arg-type]
+        if "sig" in data:
+            lsig.sig = base64.b64encode(data["sig"]).decode()  # type: ignore[arg-type]
+        elif "msig" in data:
+            lsig.msig = Multisig.undictify(data["msig"])  # type: ignore[arg-type]
+        elif "lmsig" in data:
+            lsig.lmsig = Multisig.undictify(data["lmsig"])  # type: ignore[arg-type]
+        return lsig
+
+    def sig_count(self) -> int:
+        return int(self.sig is not None) + int(self.msig is not None) + int(self.lmsig is not None)
+
+    def verify(self, public_key: bytes) -> bool:
+        """Verifies LogicSig against the provided sender address bytes."""
+        try:
+            self._sanity_check_program(self.logic)
+        except error.InvalidProgram:
+            return False
+
+        if self.sig_count() > 1:
+            return False
+
+        if self.sig:
+            verify_key = VerifyKey(public_key)
+            to_sign = constants.logic_prefix + self.logic
+            try:
+                verify_key.verify(to_sign, base64.b64decode(self.sig))
+                return True
+            except (BadSignatureError, ValueError, TypeError):
+                return False
+
+        if self.msig:
+            to_sign = constants.logic_prefix + self.logic
+            return self.msig.verify(to_sign)
+
+        if self.lmsig:
+            to_sign = constants.multisig_logic_prefix + self.logic
+            return self.lmsig.verify(to_sign)
+
+        addr = self.address()
+        encoded = encoding.encode_address(public_key)
+        return addr == encoded
+
+    def sign(self, private_key: str, multisig: Multisig | None = None) -> None:
+        """
+        Sign the program bytes. If `multisig` is provided, append the signature to that multisig.
+        """
+        if self.sig_count() > 0 and not multisig:
+            raise error.LogicSigOverspecifiedSignature
+
+        private_key_bytes = base64.b64decode(private_key)
+        signing_key = SigningKey(private_key_bytes[: constants.key_len_bytes])
+        to_sign = constants.logic_prefix + self.logic
+
+        if not multisig:
+            signature = signing_key.sign(to_sign).signature
+            self.sig = base64.b64encode(signature).decode()
+            self.msig = None
+            self.lmsig = None
+            return
+
+        # Multisig signing
+        sig = signing_key.sign(constants.logic_prefix + self.logic).signature
+        for idx, subsig in enumerate(multisig.subsigs):
+            if subsig.public_key == signing_key.verify_key.encode():
+                if not subsig.signature:
+                    subsig.signature = sig
+                    self.msig = multisig
+                    self.sig = None
+                    self.lmsig = None
+                    return
+                subsig.signature = sig
+                self.msig = multisig
+                self.sig = None
+                self.lmsig = None
+                return
+
+        raise error.InvalidSecretKeyError
+
+    def append_to_multisig(self, private_key: str) -> None:
+        if not self.msig:
+            raise error.InvalidSecretKeyError
+        self.sign(private_key, self.msig)
+
+    def address(self) -> str:
+        """Return the hash of the program bytes as an address."""
+        checksum = encoding.checksum(constants.logic_prefix + self.logic)
+        encoded = encoding.encode_address(checksum)
+        assert isinstance(encoded, str)
+        return encoded
+
+
+class LogicSigAccount:
+    """
+    Safe wrapper around LogicSig that tracks the signing key for delegated logic.
+    """
+
+    def __init__(self, program: bytes, args: Sequence[bytes] | None = None) -> None:
+        self.lsig = LogicSig(program, args)
+        self.sigkey: bytes | None = None
+
+    def dictify(self) -> OrderedDict[str, object]:
+        payload = OrderedDict()
+        payload["lsig"] = self.lsig.dictify()
+        if self.sigkey:
+            payload["sigkey"] = self.sigkey
+        return payload
+
+    @staticmethod
+    def undictify(data: dict[str, object]) -> "LogicSigAccount":
+        account = LogicSigAccount(b"", [])
+        account.lsig = LogicSig.undictify(data["lsig"])  # type: ignore[arg-type]
+        account.sigkey = data.get("sigkey")  # type: ignore[assignment]
+        return account
+
+    def verify(self, public_key: bytes) -> bool:
+        return self.lsig.verify(public_key)
+
+    def address(self) -> str:
+        if self.sigkey:
+            encoded = encoding.encode_address(self.sigkey)
+            assert isinstance(encoded, str)
+            return encoded
+        if self.lsig.msig:
+            return self.lsig.msig.address()
+        if self.lsig.lmsig:
+            return self.lsig.lmsig.address()
+        return self.lsig.address()
+
+    def sign_multisig(self, multisig: Multisig, private_key: str) -> None:
+        if self.lsig.sig:
+            raise error.LogicSigOverspecifiedSignature
+        self.lsig.sign(private_key, multisig)
+        self.sigkey = None
+
+    def append_to_multisig(self, private_key: str) -> None:
+        if not self.lsig.msig:
+            raise error.InvalidSecretKeyError
+        self.lsig.append_to_multisig(private_key)
+        self.sigkey = None
+
+    def sign(self, private_key: str) -> None:
+        if self.lsig.msig:
+            raise error.LogicSigOverspecifiedSignature
+        self.lsig.sign(private_key)
+        decoded = base64.b64decode(bytes(private_key, "utf-8"))
+        self.sigkey = decoded[constants.key_len_bytes :]

algokit_algosdk/mnemonic.py

@@ -0,0 +1,216 @@
+from nacl import signing
+import base64
+from . import wordlist
+from . import error
+from . import constants
+from . import encoding
+import warnings
+
+
+word_to_index = {}
+index_to_word = {}
+for i, word in enumerate(wordlist.word_list_raw().split("\n")):
+    index_to_word[i] = word
+    # Put all prefixes of words at least four letters long into map,
+    # since they are guarenteed unique, so some people may only save
+    # that part, and expect to be able to recover.
+    for length in range(4, len(word)):
+        assert word[:length] not in word_to_index
+        word_to_index[word[:length]] = i
+    word_to_index[word] = i  # in case word is less than four letters long
+
+
+def from_master_derivation_key(key):
+    """
+    Return the mnemonic for the master derivation key.
+
+    Args:
+        key (str): master derivation key in base64
+
+    Returns:
+        str: mnemonic
+
+    """
+    key = base64.b64decode(key)
+    return _from_key(key)
+
+
+def to_master_derivation_key(mnemonic):
+    """
+    Return the master derivation key for the mnemonic.
+
+    Args:
+        mnemonic (str): mnemonic of the master derivation key
+
+    Returns:
+        str: master derivation key in base64
+    """
+    key_bytes = _to_key(mnemonic)
+    return base64.b64encode(key_bytes).decode()
+
+
+def from_private_key(key):
+    """
+    Return the mnemonic for the private key.
+
+    Args:
+        key (str): private key in base64
+
+    Returns:
+        str: mnemonic
+    """
+    key = base64.b64decode(key)
+    return _from_key(key[: constants.key_len_bytes])
+
+
+def to_private_key(mnemonic) -> str:
+    """
+    Return the private key for the mnemonic.
+
+    Args:
+        mnemonic (str): mnemonic of the private key
+
+    Returns:
+        str: private key in base64
+    """
+    key_bytes = _to_key(mnemonic)
+    key = signing.SigningKey(key_bytes)
+    return base64.b64encode(key.encode() + key.verify_key.encode()).decode()
+
+
+def _from_key(key):
+    """
+    Return the mnemonic for the key.
+
+    Args:
+        key (bytes): key to compute mnemonic of
+
+    Returns:
+        str: mnemonic
+    """
+    if not len(key) == constants.key_len_bytes:
+        raise error.WrongKeyBytesLengthError
+    chkword = index_to_word[_checksum(key)]
+    nums = _to_11_bit(key)
+    words = _apply_words(nums)
+    return " ".join(words) + " " + chkword
+
+
+def _to_key(mnemonic):
+    """
+    Give the corresponding key for the mnemonic.
+
+    Args:
+        mnemonic (str): mnemonic for the key
+
+    Returns:
+        bytes: key
+    """
+    mnemonic = mnemonic.lower().split()
+    if not len(mnemonic) == constants.mnemonic_len:
+        raise error.WrongMnemonicLengthError
+    try:
+        m_checksum = word_to_index[mnemonic[-1]]
+        mnemonic = _from_words(mnemonic[:-1])
+    except KeyError:  # We used to return ValueError, so keep it
+        raise ValueError(mnemonic)
+    m_bytes = _to_bytes(mnemonic)
+    if not m_bytes[-1 : len(m_bytes)] == b"\x00":
+        raise error.WrongChecksumError
+    chksum = _checksum(m_bytes[: constants.key_len_bytes])
+    if chksum == m_checksum:
+        return m_bytes[: constants.key_len_bytes]
+    else:
+        raise error.WrongChecksumError
+
+
+def _checksum(data):
+    """
+    Compute the mnemonic checksum.
+
+    Args:
+        data (bytes): data to compute checksum of
+
+    Returns:
+        int: checksum
+    """
+    chksum = encoding.checksum(data)
+    temp = chksum[0:2]
+    nums = _to_11_bit(temp)
+    return nums[0]
+
+
+def _apply_words(nums):
+    """
+    Get the corresponding words for a list of 11-bit numbers.
+
+    Args:
+        nums (int[]): list of 11-bit numbers
+
+    Returns:
+        str[]: list of words
+    """
+    return [index_to_word[n] for n in nums]
+
+
+def _from_words(words):
+    """
+    Get the corresponding 11-bit numbers for a list of words.
+
+    Args:
+        words (str[]): list of words
+
+    Returns:
+        int[]: list of 11-bit numbers
+    """
+    return [word_to_index[w] for w in words]
+
+
+def _to_11_bit(data):
+    """
+    Convert a bytearray to an list of 11-bit numbers.
+
+    Args:
+        data (bytes): bytearray to convert to 11-bit numbers
+
+    Returns:
+        int[]: list of 11-bit numbers
+    """
+    buffer = 0
+    num_of_bits = 0
+    output = []
+    for i in range(len(data)):
+        buffer |= data[i] << num_of_bits
+        num_of_bits += 8
+        if num_of_bits >= 11:
+            output.append(buffer & 2047)
+            buffer = buffer >> 11
+            num_of_bits -= 11
+    if num_of_bits != 0:
+        output.append(buffer & 2047)
+    return output
+
+
+def _to_bytes(nums):
+    """
+    Convert a list of 11-bit numbers to a bytearray.
+
+    Args:
+        nums (int[]): list of 11-bit numbers
+
+    Returns:
+        bytes: bytearray
+    """
+    buffer = 0
+    num_of_bits = 0
+    output = []
+    for i in range(len(nums)):
+        buffer |= nums[i] << num_of_bits
+        num_of_bits += 11
+        while num_of_bits >= 8:
+            output.append(buffer & 255)
+            buffer = buffer >> 8
+            num_of_bits -= 8
+    if num_of_bits != 0:
+        output.append(buffer & 255)
+    return bytes(output)