feat: make ABI call arguments kwargs instead of a dict (#6)

src/algokit_utils/__init__.py

@@ -3,35 +3,28 @@
  transfer,
 )
 from algokit_utils.account import (
+ create_kmd_wallet_account,
  get_account,
  get_account_from_mnemonic,
  get_dispenser_account,
  get_kmd_wallet_account,
  get_or_create_kmd_wallet_account,
  get_sandbox_default_account,
 )
-from algokit_utils.app import (
- DELETABLE_TEMPLATE_NAME,
- NOTE_PREFIX,
- UPDATABLE_TEMPLATE_NAME,
- AppDeployMetaData,
- AppLookup,
- AppMetaData,
- AppReference,
- DeploymentFailedError,
- get_creator_apps,
- replace_template_variables,
-)
 from algokit_utils.application_client import (
  ABICallArgs,
- ABITransactionResponse,
+ ABICallArgsDict,
+ ABICreateCallArgs,
+ ABICreateCallArgsDict,
  ApplicationClient,
- DeployResponse,
- OnSchemaBreak,
- OnUpdate,
- OperationPerformed,
+ CommonCallParameters,
+ CommonCallParametersDict,
+ CreateCallParameters,
+ CreateCallParametersDict,
+ OnCompleteCallParameters,
+ OnCompleteCallParametersDict,
  Program,
- TransactionResponse,
+ execute_atc_with_logic_error,
  get_app_id_from_tx_id,
  get_next_version,
  num_extra_program_pages,
@@ -46,8 +39,24 @@
  MethodHints,
  OnCompleteActionName,
 )
+from algokit_utils.deploy import (
+ DELETABLE_TEMPLATE_NAME,
+ NOTE_PREFIX,
+ UPDATABLE_TEMPLATE_NAME,
+ AppDeployMetaData,
+ AppLookup,
+ AppMetaData,
+ AppReference,
+ DeploymentFailedError,
+ DeployResponse,
+ OnSchemaBreak,
+ OnUpdate,
+ OperationPerformed,
+ get_creator_apps,
+ replace_template_variables,
+)
 from algokit_utils.logic_error import LogicError
-from algokit_utils.models import Account
+from algokit_utils.models import ABITransactionResponse, Account, TransactionResponse
 from algokit_utils.network_clients import (
  AlgoClientConfig,
  get_algod_client,
@@ -57,6 +66,7 @@
 )
 
 __all__ = [
+ "create_kmd_wallet_account",
  "get_account_from_mnemonic",
  "get_or_create_kmd_wallet_account",
  "get_sandbox_default_account",
@@ -74,14 +84,23 @@
  "get_creator_apps",
  "replace_template_variables",
  "ABICallArgs",
- "ABITransactionResponse",
+ "ABICallArgsDict",
+ "ABICreateCallArgs",
+ "ABICreateCallArgsDict",
+ "ApplicationClient",
+ "CommonCallParameters",
+ "CommonCallParametersDict",
+ "CreateCallParameters",
+ "CreateCallParametersDict",
+ "OnCompleteCallParameters",
+ "OnCompleteCallParametersDict",
  "ApplicationClient",
  "DeployResponse",
  "OnUpdate",
  "OnSchemaBreak",
  "OperationPerformed",
  "Program",
- "TransactionResponse",
+ "execute_atc_with_logic_error",
  "get_app_id_from_tx_id",
  "get_next_version",
  "num_extra_program_pages",
@@ -94,7 +113,9 @@
  "OnCompleteActionName",
  "MethodHints",
  "LogicError",
+ "ABITransactionResponse",
  "Account",
+ "TransactionResponse",
  "AlgoClientConfig",
  "get_algod_client",
  "get_indexer_client",

src/algokit_utils/_transfer.py

@@ -1,7 +1,10 @@
 import dataclasses
 import logging
 
-from algosdk.transaction import PaymentTxn
+import algosdk.transaction
+from algosdk.account import address_from_private_key
+from algosdk.atomic_transaction_composer import AccountTransactionSigner
+from algosdk.transaction import PaymentTxn, SuggestedParams
 from algosdk.v2client.algod import AlgodClient
 
 from algokit_utils.models import Account
@@ -12,30 +15,63 @@
 
 @dataclasses.dataclass(kw_only=True)
 class TransferParameters:
- from_account: Account
+ from_account: Account | AccountTransactionSigner
+ """The account (with private key) or signer that will send the µALGOs"""
  to_address: str
- amount: int
- note: str | None = None
- max_fee_in_algos: float | None = None
+ """The account address that will receive the µALGOs"""
+ micro_algos: int
+ """The amount of µALGOs to send"""
+ suggested_params: SuggestedParams | None = None
+ """(optional) transaction parameters"""
+ note: str | bytes | None = None
+ """(optional) transaction note"""
+ fee_micro_algos: int | None = None
+ """(optional) The flat fee you want to pay, useful for covering extra fees in a transaction group or app call"""
+ max_fee_micro_algos: int | None = None
+ """(optional)The maximum fee that you are happy to pay (default: unbounded) - 
+ if this is set it's possible the transaction could get rejected during network congestion"""
 
 
-def transfer(transfer_parameters: TransferParameters, client: AlgodClient) -> tuple[PaymentTxn, str]:
- suggested_params = client.suggested_params()
+def _check_fee(transaction: PaymentTxn, max_fee: int | None) -> None:
+ if max_fee is not None:
+ # Once a transaction has been constructed by algosdk, transaction.fee indicates what the total transaction fee
+ # Will be based on the current suggested fee-per-byte value.
+ if transaction.fee > max_fee:
+ raise Exception(
+ f"Cancelled transaction due to high network congestion fees. "
+ f"Algorand suggested fees would cause this transaction to cost {transaction.fee} µALGOs. "
+ f"Cap for this transaction is {max_fee} µALGOs."
+ )
+ elif transaction.fee > algosdk.constants.MIN_TXN_FEE:
+ logger.warning(
+ f"Algorand network congestion fees are in effect. "
+ f"This transaction will incur a fee of {transaction.fee} µALGOs."
+ )
+
+
+def transfer(client: AlgodClient, parameters: TransferParameters) -> PaymentTxn:
+ suggested_params = parameters.suggested_params or client.suggested_params()
+ from_account = parameters.from_account
+ sender = address_from_private_key(from_account.private_key) # type: ignore[no-untyped-call]
  transaction = PaymentTxn(
- sender=transfer_parameters.from_account.address,
+ sender=sender,
+ receiver=parameters.to_address,
+ amt=parameters.micro_algos,
+ note=parameters.note.encode("utf-8") if isinstance(parameters.note, str) else parameters.note,
  sp=suggested_params,
- receiver=transfer_parameters.to_address,
- amt=transfer_parameters.amount,
- close_remainder_to=None,
- note=transfer_parameters.note.encode("utf-8") if transfer_parameters.note else None,
- rekey_to=None,
  ) # type: ignore[no-untyped-call]
- # TODO: max fee
- from_account = transfer_parameters.from_account
+ if parameters.fee_micro_algos:
+ transaction.fee = parameters.fee_micro_algos
+
+ if not suggested_params.flat_fee:
+ _check_fee(transaction, parameters.max_fee_micro_algos)
  signed_transaction = transaction.sign(from_account.private_key) # type: ignore[no-untyped-call]
- send_response = client.send_transaction(signed_transaction)
+ client.send_transaction(signed_transaction)
 
  txid = transaction.get_txid() # type: ignore[no-untyped-call]
- logger.debug(f"Sent transaction {txid} type={transaction.type} from {from_account.address}")
+ logger.debug(
+ f"Sent transaction {txid} type={transaction.type} from "
+ f"{address_from_private_key(from_account.private_key)}" # type: ignore[no-untyped-call]
+ )
 
- return transaction, send_response
+ return transaction

src/algokit_utils/account.py

@@ -1,7 +1,7 @@
 import logging
 import os
 from collections.abc import Callable
-from typing import Any, cast
+from typing import Any
 
 from algosdk.account import address_from_private_key
 from algosdk.kmd import KMDClient
@@ -31,40 +31,49 @@ def get_account_from_mnemonic(mnemonic: str) -> Account:
  return Account(private_key, address)
 
 
+def create_kmd_wallet_account(kmd_client: KMDClient, name: str) -> Account:
+ wallet_id = kmd_client.create_wallet(name, "")["id"] # type: ignore[no-untyped-call]
+ wallet_handle = kmd_client.init_wallet_handle(wallet_id, "") # type: ignore[no-untyped-call]
+ kmd_client.generate_key(wallet_handle) # type: ignore[no-untyped-call]
+
+ key_ids: list[str] = kmd_client.list_keys(wallet_handle) # type: ignore[no-untyped-call]
+ account_key = key_ids[0]
+
+ private_account_key = kmd_client.export_key(wallet_handle, "", account_key) # type: ignore[no-untyped-call]
+ return get_account_from_mnemonic(from_private_key(private_account_key)) # type: ignore[no-untyped-call]
+
+
 def get_or_create_kmd_wallet_account(
- client: AlgodClient, name: str, fund_with: int | None, kmd_client: KMDClient | None = None
+ client: AlgodClient, name: str, fund_with_algos: float = 1000, kmd_client: KMDClient | None = None
 ) -> Account:
  kmd_client = kmd_client or get_kmd_client_from_algod_client(client)
- fund_with = 1000 if fund_with is None else fund_with
  account = get_kmd_wallet_account(client, kmd_client, name)
 
  if account:
- account_info = cast(dict[str, Any], client.account_info(account.address))
+ account_info = client.account_info(account.address)
+ assert isinstance(account_info, dict)
  if account_info["amount"] > 0:
  return account
- logger.debug(f"Found existing account in Sandbox with name '{name}'." f"But no funds in the account.")
+ logger.debug(f"Found existing account in Sandbox with name '{name}', but no funds in the account.")
  else:
- wallet_id = kmd_client.create_wallet(name, "")["id"] # type: ignore[no-untyped-call]
- wallet_handle = kmd_client.init_wallet_handle(wallet_id, "") # type: ignore[no-untyped-call]
- kmd_client.generate_key(wallet_handle) # type: ignore[no-untyped-call]
+ account = create_kmd_wallet_account(kmd_client, name)
 
- account = get_kmd_wallet_account(client, kmd_client, name)
- assert account
  logger.debug(
  f"Couldn't find existing account in Sandbox with name '{name}'. "
  f"So created account {account.address} with keys stored in KMD."
  )
 
- logger.debug(f"Funding account {account.address} with {fund_with} ALGOs")
+ logger.debug(f"Funding account {account.address} with {fund_with_algos} ALGOs")
 
- transfer(
- TransferParameters(
- from_account=get_dispenser_account(client),
- to_address=account.address,
- amount=algos_to_microalgos(fund_with), # type: ignore[no-untyped-call]
- ),
- client,
- )
+ if fund_with_algos:
+ transfer(
+ client,
+ TransferParameters(
+ from_account=get_dispenser_account(client),
+ to_address=account.address,
+ micro_algos=algos_to_microalgos(fund_with_algos), # type: ignore[no-untyped-call]
+ ),
+ )
 
  return account
 
@@ -105,7 +114,8 @@ def get_kmd_wallet_account(
  matched_account_key = None
  if predicate:
  for key in key_ids:
- account = cast(dict[str, Any], client.account_info(key))
+ account = client.account_info(key)
+ assert isinstance(account, dict)
  if predicate(account):
  matched_account_key = key
  else:
@@ -119,15 +129,15 @@ def get_kmd_wallet_account(
 
 
 def get_account(
- client: AlgodClient, name: str, fund_with: int | None = None, kmd_client: KMDClient | None = None
+ client: AlgodClient, name: str, fund_with_algos: float = 1000, kmd_client: KMDClient | None = None
 ) -> Account:
  mnemonic_key = f"{name.upper()}_MNEMONIC"
  mnemonic = os.getenv(mnemonic_key)
  if mnemonic:
  return get_account_from_mnemonic(mnemonic)
 
  if is_sandbox(client):
- account = get_or_create_kmd_wallet_account(client, name, fund_with, kmd_client)
+ account = get_or_create_kmd_wallet_account(client, name, fund_with_algos, kmd_client)
  os.environ[mnemonic_key] = from_private_key(account.private_key) # type: ignore[no-untyped-call]
  return account