algokit-utils 5.0.0a3__py3-none-any.whl

algokit_transact/models/asset_transfer.py

@@ -0,0 +1,13 @@
+from dataclasses import dataclass, field
+
+from algokit_common.constants import ZERO_ADDRESS
+from algokit_transact.codec.serde import addr, wire
+
+
+@dataclass(slots=True, frozen=True)
+class AssetTransferTransactionFields:
+    asset_id: int = field(default=0, metadata=wire("xaid"))
+    receiver: str = field(default=ZERO_ADDRESS, metadata=addr("arcv"))
+    amount: int = field(default=0, metadata=wire("aamt"))
+    close_remainder_to: str | None = field(default=None, metadata=addr("aclose", omit_if_none=True))
+    asset_sender: str | None = field(default=None, metadata=addr("asnd", omit_if_none=True))

algokit_transact/models/common.py

@@ -0,0 +1,17 @@
+from dataclasses import dataclass, field
+from enum import Enum
+
+
+class OnApplicationComplete(Enum):
+    NoOp = 0
+    OptIn = 1
+    CloseOut = 2
+    ClearState = 3
+    UpdateApplication = 4
+    DeleteApplication = 5
+
+
+@dataclass(slots=True, frozen=True)
+class StateSchema:
+    num_uints: int = field(default=0, metadata={"kind": "wire", "alias": "nui"})
+    num_byte_slices: int = field(default=0, metadata={"kind": "wire", "alias": "nbs"})

algokit_transact/models/heartbeat.py

@@ -0,0 +1,21 @@
+from dataclasses import dataclass, field
+
+from algokit_transact.codec.serde import addr, nested, wire
+
+
+@dataclass(slots=True, frozen=True)
+class HeartbeatProof:
+    signature: bytes | None = field(default=None, metadata=wire("s"))
+    public_key: bytes | None = field(default=None, metadata=wire("p"))
+    public_key_2: bytes | None = field(default=None, metadata=wire("p2"))
+    public_key_1_signature: bytes | None = field(default=None, metadata=wire("p1s"))
+    public_key_2_signature: bytes | None = field(default=None, metadata=wire("p2s"))
+
+
+@dataclass(slots=True, frozen=True)
+class HeartbeatTransactionFields:
+    address: str | None = field(default=None, metadata=addr("a", omit_if_none=True))
+    proof: HeartbeatProof | None = field(default=None, metadata=nested("prf", HeartbeatProof))
+    seed: bytes | None = field(default=None, metadata=wire("sd"))
+    vote_id: bytes | None = field(default=None, metadata=wire("vid"))
+    key_dilution: int | None = field(default=None, metadata=wire("kd", keep_zero=True))

algokit_transact/models/key_registration.py

@@ -0,0 +1,14 @@
+from dataclasses import dataclass, field
+
+from algokit_transact.codec.serde import wire
+
+
+@dataclass(slots=True, frozen=True)
+class KeyRegistrationTransactionFields:
+    vote_key: bytes | None = field(default=None, metadata=wire("votekey"))
+    selection_key: bytes | None = field(default=None, metadata=wire("selkey"))
+    vote_first: int | None = field(default=None, metadata=wire("votefst"))
+    vote_last: int | None = field(default=None, metadata=wire("votelst"))
+    vote_key_dilution: int | None = field(default=None, metadata=wire("votekd"))
+    state_proof_key: bytes | None = field(default=None, metadata=wire("sprfkey"))
+    non_participation: bool | None = field(default=None, metadata=wire("nonpart"))

algokit_transact/models/payment.py

@@ -0,0 +1,14 @@
+from dataclasses import dataclass, field
+
+from algokit_common.constants import ZERO_ADDRESS
+from algokit_transact.codec.serde import addr, wire
+
+
+@dataclass(slots=True, frozen=True)
+class PaymentTransactionFields:
+    amount: int = field(default=0, metadata=wire("amt"))
+    receiver: str = field(default=ZERO_ADDRESS, metadata=addr("rcv"))
+    close_remainder_to: str | None = field(
+        default=None,
+        metadata=addr("close", omit_if_none=True),
+    )

algokit_transact/models/signed_transaction.py

@@ -0,0 +1,21 @@
+from dataclasses import dataclass, field
+
+from algokit_transact.codec.serde import addr, nested, wire
+from algokit_transact.models.transaction import Transaction
+from algokit_transact.signing.logic_signature import LogicSignature
+from algokit_transact.signing.types import MultisigSignature
+
+
+@dataclass(slots=True, frozen=True)
+class SignedTransaction:
+    txn: Transaction = field(metadata=nested("txn", Transaction))
+    sig: bytes | None = field(default=None, metadata=wire("sig"))
+    msig: MultisigSignature | None = field(
+        default=None,
+        metadata=nested("msig", MultisigSignature),
+    )
+    lsig: LogicSignature | None = field(
+        default=None,
+        metadata=nested("lsig", LogicSignature),
+    )
+    auth_address: str | None = field(default=None, metadata=addr("sgnr"))

algokit_transact/models/state_proof.py

@@ -0,0 +1,150 @@
+from collections.abc import Iterable, Mapping
+from dataclasses import dataclass, field
+from typing import cast
+
+from algokit_transact.codec.serde import bytes_seq, from_wire, int_seq, nested, to_wire, wire
+
+
+@dataclass(slots=True, frozen=True)
+class HashFactory:
+    hash_type: int | None = field(default=None, metadata=wire("t"))
+
+
+@dataclass(slots=True, frozen=True)
+class MerkleArrayProof:
+    path: list[bytes] | None = field(default=None, metadata=bytes_seq("pth"))
+    hash_factory: HashFactory | None = field(default=None, metadata=nested("hsh", HashFactory))
+    tree_depth: int | None = field(default=None, metadata=wire("td"))
+
+
+@dataclass(slots=True, frozen=True)
+class MerkleSignatureVerifier:
+    commitment: bytes | None = field(default=None, metadata=wire("cmt"))
+    key_lifetime: int | None = field(default=None, metadata=wire("lf"))
+
+
+@dataclass(slots=True, frozen=True)
+class Participant:
+    verifier: MerkleSignatureVerifier | None = field(default=None, metadata=nested("p", MerkleSignatureVerifier))
+    weight: int | None = field(default=None, metadata=wire("w"))
+
+
+@dataclass(slots=True, frozen=True)
+class FalconVerifier:
+    public_key: bytes | None = field(default=None, metadata=wire("k"))
+
+
+@dataclass(slots=True, frozen=True)
+class FalconSignatureStruct:
+    signature: bytes | None = field(default=None, metadata=wire("sig"))
+    vector_commitment_index: int | None = field(default=None, metadata=wire("idx"))
+    proof: MerkleArrayProof | None = field(default=None, metadata=nested("prf", MerkleArrayProof))
+    verifying_key: FalconVerifier | None = field(default=None, metadata=nested("vkey", FalconVerifier))
+
+
+@dataclass(slots=True, frozen=True)
+class SigslotCommit:
+    sig: FalconSignatureStruct | None = field(default=None, metadata=nested("s", FalconSignatureStruct))
+    lower_sig_weight: int | None = field(default=None, metadata=wire("l"))
+
+
+@dataclass(slots=True, frozen=True)
+class Reveal:
+    participant: Participant | None = field(default=None, metadata=nested("p", Participant))
+    sigslot: SigslotCommit | None = field(default=None, metadata=nested("s", SigslotCommit))
+
+
+@dataclass(slots=True, frozen=True)
+class StateProof:
+    sig_commit: bytes | None = field(default=None, metadata=wire("c"))
+    signed_weight: int | None = field(default=None, metadata=wire("w", keep_zero=True))
+    sig_proofs: MerkleArrayProof | None = field(default=None, metadata=nested("S", MerkleArrayProof))
+    part_proofs: MerkleArrayProof | None = field(default=None, metadata=nested("P", MerkleArrayProof))
+    merkle_signature_salt_version: int | None = field(default=None, metadata=wire("v"))
+    reveals: dict[int, Reveal] | None = field(
+        default=None,
+        metadata=wire(
+            "r",
+            encode=lambda obj: _encode_reveals(cast(dict[int, Reveal] | None, obj)),
+            decode=lambda obj: _decode_reveals(obj),
+        ),
+    )
+    positions_to_reveal: list[int] | None = field(default=None, metadata=int_seq("pr"))
+
+
+@dataclass(slots=True, frozen=True)
+class StateProofMessage:
+    block_headers_commitment: bytes | None = field(default=None, metadata=wire("b"))
+    voters_commitment: bytes | None = field(default=None, metadata=wire("v"))
+    ln_proven_weight: int | None = field(default=None, metadata=wire("P"))
+    first_attested_round: int | None = field(default=None, metadata=wire("f"))
+    last_attested_round: int | None = field(default=None, metadata=wire("l"))
+
+
+@dataclass(slots=True, frozen=True)
+class StateProofTransactionFields:
+    state_proof_type: int | None = field(default=None, metadata=wire("sptype"))
+    # Flatten state proof and message at the transaction level (aliases under root: sp and spmsg)
+    state_proof: StateProof | None = field(default=None, metadata=nested("sp", StateProof))
+    message: StateProofMessage | None = field(default=None, metadata=nested("spmsg", StateProofMessage))
+
+
+def _encode_reveals(mapping: Mapping[int, Reveal] | Iterable[Reveal] | None) -> dict[int, dict[str, object]] | None:
+    if mapping is None:
+        return None
+    entries: Iterable[tuple[int, Reveal]]
+    if isinstance(mapping, Mapping):
+        entries = (
+            (key if isinstance(key, int) else _coerce_reveal_position(key, idx), reveal)
+            for idx, (key, reveal) in enumerate(mapping.items())
+        )
+    else:
+        entries = ((_coerce_reveal_position(None, idx), reveal) for idx, reveal in enumerate(mapping))
+    encoded: dict[int, dict[str, object]] = {}
+    for position, reveal in entries:
+        data = to_wire(reveal)
+        payload = {key: value for key in ("p", "s") if (value := data.get(key)) is not None}
+        if payload:
+            encoded[int(position)] = payload
+    return encoded or None
+
+
+def _decode_reveals(obj: object | None) -> dict[int, Reveal] | None:
+    if obj is None:
+        return None
+
+    if isinstance(obj, Mapping):
+        decoded: dict[int, Reveal] = {}
+        for key, value in obj.items():
+            if not isinstance(value, Mapping):
+                continue
+            position = _coerce_reveal_position(key, len(decoded))
+            payload = {k: v for k, v in value.items() if k in {"p", "s"}}
+            if payload:
+                decoded[position] = from_wire(Reveal, payload)
+        return decoded or None
+
+    if isinstance(obj, list):
+        decoded_list: dict[int, Reveal] = {}
+        for idx, value in enumerate(obj):
+            if not isinstance(value, Mapping):
+                continue
+            position = _coerce_reveal_position(value.get("pos"), idx)
+            payload = {k: v for k, v in value.items() if k in {"p", "s"}}
+            if payload:
+                decoded_list[position] = from_wire(Reveal, payload)
+        return decoded_list or None
+
+    return None
+
+
+def _coerce_reveal_position(raw: object, fallback: int) -> int:
+    if isinstance(raw, int):
+        return raw
+    if isinstance(raw, str):
+        try:
+            return int(raw)
+        except ValueError:
+            return fallback
+    # Fallback silently to preserve legacy behavior when nodes omit this field.
+    return fallback

algokit_transact/models/transaction.py

@@ -0,0 +1,88 @@
+from collections.abc import Mapping
+from dataclasses import dataclass, field
+from enum import Enum
+
+from algokit_common.constants import ZERO_ADDRESS
+from algokit_transact.codec.serde import addr, enum_value, flatten, nested, wire
+from algokit_transact.models.app_call import AppCallTransactionFields
+from algokit_transact.models.asset_config import AssetConfigTransactionFields
+from algokit_transact.models.asset_freeze import AssetFreezeTransactionFields
+from algokit_transact.models.asset_transfer import AssetTransferTransactionFields
+from algokit_transact.models.heartbeat import HeartbeatTransactionFields
+from algokit_transact.models.key_registration import KeyRegistrationTransactionFields
+from algokit_transact.models.payment import PaymentTransactionFields
+from algokit_transact.models.state_proof import StateProofTransactionFields
+
+
+class TransactionType(Enum):
+    Payment = "pay"
+    AssetTransfer = "axfer"
+    AssetFreeze = "afrz"
+    AssetConfig = "acfg"
+    KeyRegistration = "keyreg"
+    AppCall = "appl"
+    StateProof = "stpf"
+    Heartbeat = "hb"
+    # Unknown transaction type - used when decoding transactions with unrecognized type values.
+    # This should not be used when creating new transactions.
+    Unknown = "unknown"
+
+
+def _get_tx_type(payload: Mapping[str, object]) -> str | None:
+    """Helper to extract transaction type from payload, normalizing bytes to str."""
+    type_val = payload.get("type")
+    if type_val is None:
+        return None
+    if isinstance(type_val, bytes | bytearray | memoryview):
+        return bytes(type_val).decode("utf-8")
+    return str(type_val)
+
+
+@dataclass(slots=True, frozen=True)
+class Transaction:
+    transaction_type: TransactionType = field(
+        metadata=enum_value("type", TransactionType, fallback=TransactionType.Unknown)
+    )
+    sender: str = field(default=ZERO_ADDRESS, metadata=addr("snd"))
+    first_valid: int = field(default=0, metadata=wire("fv"))
+    last_valid: int = field(default=0, metadata=wire("lv"))
+
+    fee: int | None = field(default=None, metadata=wire("fee"))
+    genesis_hash: bytes | None = field(default=None, metadata=wire("gh"))
+    genesis_id: str | None = field(default=None, metadata=wire("gen"))
+    note: bytes | None = field(default=None, metadata=wire("note"))
+    rekey_to: str | None = field(default=None, metadata=addr("rekey"))
+    lease: bytes | None = field(default=None, metadata=wire("lx"))
+    group: bytes | None = field(default=None, metadata=wire("grp"))
+
+    payment: PaymentTransactionFields | None = field(
+        default=None, metadata=flatten(PaymentTransactionFields, present_if=lambda p: _get_tx_type(p) == "pay")
+    )
+    asset_transfer: AssetTransferTransactionFields | None = field(
+        default=None, metadata=flatten(AssetTransferTransactionFields, present_if=lambda p: _get_tx_type(p) == "axfer")
+    )
+    asset_config: AssetConfigTransactionFields | None = field(
+        default=None, metadata=flatten(AssetConfigTransactionFields, present_if=lambda p: _get_tx_type(p) == "acfg")
+    )
+    application_call: AppCallTransactionFields | None = field(
+        default=None, metadata=flatten(AppCallTransactionFields, present_if=lambda p: _get_tx_type(p) == "appl")
+    )
+    key_registration: KeyRegistrationTransactionFields | None = field(
+        default=None,
+        metadata=flatten(KeyRegistrationTransactionFields, present_if=lambda p: _get_tx_type(p) == "keyreg"),
+    )
+    asset_freeze: AssetFreezeTransactionFields | None = field(
+        default=None, metadata=flatten(AssetFreezeTransactionFields, present_if=lambda p: _get_tx_type(p) == "afrz")
+    )
+    heartbeat: HeartbeatTransactionFields | None = field(
+        default=None, metadata=nested("hb", HeartbeatTransactionFields)
+    )
+    state_proof: StateProofTransactionFields | None = field(
+        default=None, metadata=flatten(StateProofTransactionFields, present_if=lambda p: _get_tx_type(p) == "stpf")
+    )
+
+    def tx_id(self) -> str:
+        """Return the transaction ID."""
+        from algokit_transact.ops.ids import get_transaction_id
+
+        return get_transaction_id(self)

algokit_transact/multisig.py

@@ -0,0 +1,93 @@
+from __future__ import annotations
+
+import dataclasses
+from collections.abc import Callable, Sequence
+from functools import cached_property
+
+from algokit_common import address_from_public_key
+from algokit_transact.codec.signed import encode_signed_transaction
+from algokit_transact.codec.transaction import encode_transaction
+from algokit_transact.models.signed_transaction import SignedTransaction
+from algokit_transact.models.transaction import Transaction as AlgokitTransaction
+from algokit_transact.signer import AddressWithSigners, TransactionSigner
+from algokit_transact.signing.multisig import (
+    address_from_multisig_signature,
+    apply_multisig_subsignature,
+    new_multisig_signature,
+)
+from algokit_transact.signing.types import MultisigSignature
+
+__all__ = [
+    "MultisigAccount",
+    "MultisigMetadata",
+]
+
+
+@dataclasses.dataclass(kw_only=True)
+class MultisigMetadata:
+    """Metadata for a multisig account."""
+
+    version: int
+    threshold: int
+    addrs: list[str]
+
+
+@dataclasses.dataclass(frozen=True)
+class MultisigAccount:
+    """Account wrapper for multisig signing. Supports secretless signing."""
+
+    params: MultisigMetadata
+    """The multisig account parameters."""
+    sub_signers: Sequence[AddressWithSigners]
+    """The list of signing accounts."""
+
+    @cached_property
+    def _multisig_signature(self) -> MultisigSignature:
+        return new_multisig_signature(
+            self.params.version,
+            self.params.threshold,
+            self.params.addrs,
+        )
+
+    @cached_property
+    def signer(self) -> TransactionSigner:
+        address_to_signer: dict[str, Callable[[bytes], bytes]] = {
+            account.addr: account.bytes_signer for account in self.sub_signers
+        }
+        msig_address = self.address
+        base_multisig = self._multisig_signature
+
+        def signer(txn_group: Sequence[AlgokitTransaction], indexes_to_sign: Sequence[int]) -> list[bytes]:
+            blobs: list[bytes] = []
+            for index in indexes_to_sign:
+                txn = txn_group[index]
+                payload = encode_transaction(txn)
+
+                multisig_sig = base_multisig
+                for subsig in base_multisig.subsigs:
+                    subsig_addr = address_from_public_key(subsig.public_key)
+                    if subsig_addr in address_to_signer:
+                        signature = address_to_signer[subsig_addr](payload)
+                        multisig_sig = apply_multisig_subsignature(multisig_sig, subsig_addr, signature)
+
+                signed = SignedTransaction(
+                    txn=txn,
+                    sig=None,
+                    msig=multisig_sig,
+                    lsig=None,
+                    auth_address=msig_address if txn.sender != msig_address else None,
+                )
+                blobs.append(encode_signed_transaction(signed))
+            return blobs
+
+        return signer
+
+    @cached_property
+    def address(self) -> str:
+        """The multisig account address."""
+        return address_from_multisig_signature(self._multisig_signature)
+
+    @property
+    def addr(self) -> str:
+        """Alias for address property (matching TypeScript's get addr())."""
+        return self.address

algokit_transact/ops/fees.py

@@ -0,0 +1,47 @@
+from dataclasses import replace
+
+from algokit_common.constants import SIGNATURE_ENCODING_INCR
+from algokit_transact.codec.transaction import encode_transaction_raw
+from algokit_transact.models.transaction import Transaction
+
+
+def estimate_transaction_size(tx: Transaction) -> int:
+    raw = encode_transaction_raw(tx)
+    return len(raw) + SIGNATURE_ENCODING_INCR
+
+
+def calculate_fee(
+    tx: Transaction,
+    *,
+    fee_per_byte: int,
+    min_fee: int,
+    extra_fee: int | None = None,
+    max_fee: int | None = None,
+) -> int:
+    fee = 0
+    if fee_per_byte > 0:
+        fee = fee_per_byte * estimate_transaction_size(tx)
+    fee = max(fee, min_fee)
+    if extra_fee is not None:
+        fee += extra_fee
+    if max_fee is not None and fee > max_fee:
+        raise ValueError(f"Transaction fee {fee} µALGO is greater than max fee {max_fee} µALGO")
+    return fee
+
+
+def assign_fee(
+    tx: Transaction,
+    *,
+    fee_per_byte: int,
+    min_fee: int,
+    extra_fee: int | None = None,
+    max_fee: int | None = None,
+) -> Transaction:
+    fee = calculate_fee(
+        tx,
+        fee_per_byte=fee_per_byte,
+        min_fee=min_fee,
+        extra_fee=extra_fee,
+        max_fee=max_fee,
+    )
+    return replace(tx, fee=fee)

algokit_transact/ops/group.py

@@ -0,0 +1,28 @@
+from collections.abc import Iterable
+from dataclasses import replace
+
+from algokit_common import sha512_256
+from algokit_common.constants import MAX_TRANSACTION_GROUP_SIZE, TRANSACTION_GROUP_DOMAIN_SEPARATOR
+from algokit_transact.codec.msgpack import encode_msgpack
+from algokit_transact.models.transaction import Transaction
+from algokit_transact.ops.ids import get_transaction_id_raw
+
+
+def group_transactions(transactions: Iterable[Transaction]) -> list[Transaction]:
+    txs = list(transactions)
+
+    if not txs:
+        raise ValueError("Transaction group cannot be empty")
+    if len(txs) > MAX_TRANSACTION_GROUP_SIZE:
+        raise ValueError(f"Transaction group size exceeds the max limit of {MAX_TRANSACTION_GROUP_SIZE}")
+
+    tx_hashes = []
+    for tx in txs:
+        if tx.group is not None:
+            raise ValueError("Transactions must not already be grouped")
+        tx_hashes.append(get_transaction_id_raw(tx))
+
+    encoded = encode_msgpack({"txlist": tx_hashes})
+    group = sha512_256(TRANSACTION_GROUP_DOMAIN_SEPARATOR.encode() + encoded)
+
+    return [replace(tx, group=group) for tx in txs]

algokit_transact/ops/ids.py

@@ -0,0 +1,14 @@
+from algokit_common import base32_nopad_encode, sha512_256
+from algokit_common.constants import TRANSACTION_ID_LENGTH
+from algokit_transact.codec.transaction import encode_transaction
+from algokit_transact.models.transaction import Transaction
+
+
+def get_transaction_id_raw(transaction: Transaction) -> bytes:
+    encoded = encode_transaction(transaction)
+    return sha512_256(encoded)
+
+
+def get_transaction_id(transaction: Transaction) -> str:
+    raw = get_transaction_id_raw(transaction)
+    return base32_nopad_encode(raw)[:TRANSACTION_ID_LENGTH]