algokit-utils 1.4.0b2__py3-none-any.whl → 2.0.0b1__py3-none-any.whl

algokit_utils/__init__.py

@@ -1,4 +1,8 @@
-from algokit_utils._ensure_funded import EnsureBalanceParameters, ensure_funded
+from algokit_utils._ensure_funded import (
+    EnsureBalanceParameters,
+    EnsureFundedResponse,
+    ensure_funded,
+)
 from algokit_utils._transfer import TransferAssetParameters, TransferParameters, transfer, transfer_asset
 from algokit_utils.account import (
     create_kmd_wallet_account,
@@ -54,6 +58,13 @@ from algokit_utils.deploy import (
     get_creator_apps,
     replace_template_variables,
 )
+from algokit_utils.dispenser_api import (
+    DISPENSER_ACCESS_TOKEN_KEY,
+    DISPENSER_REQUEST_TIMEOUT,
+    DispenserApiTestnetClient,
+    DispenserFundResponse,
+    DispenserLimitResponse,
+)
 from algokit_utils.logic_error import LogicError
 from algokit_utils.models import (
     ABIArgsDict,
@@ -153,7 +164,13 @@ __all__ = [
     "is_localnet",
     "is_mainnet",
     "is_testnet",
+    "DispenserApiTestnetClient",
+    "DispenserFundResponse",
+    "DispenserLimitResponse",
+    "DISPENSER_ACCESS_TOKEN_KEY",
+    "DISPENSER_REQUEST_TIMEOUT",
     "EnsureBalanceParameters",
+    "EnsureFundedResponse",
     "TransferParameters",
     "ensure_funded",
     "transfer",

algokit_utils/_ensure_funded.py

@@ -1,23 +1,21 @@
-import dataclasses
-import logging
-from typing import TYPE_CHECKING
+from dataclasses import dataclass
 
 from algosdk.account import address_from_private_key
 from algosdk.atomic_transaction_composer import AccountTransactionSigner
-from algosdk.transaction import PaymentTxn, SuggestedParams
+from algosdk.transaction import SuggestedParams
+from algosdk.v2client.algod import AlgodClient
 
 from algokit_utils._transfer import TransferParameters, transfer
 from algokit_utils.account import get_dispenser_account
+from algokit_utils.dispenser_api import (
+    DispenserApiTestnetClient,
+    DispenserAssetName,
+)
 from algokit_utils.models import Account
+from algokit_utils.network_clients import is_testnet
 
-if TYPE_CHECKING:
-    from algosdk.v2client.algod import AlgodClient
 
-
-logger = logging.getLogger(__name__)
-
-
-@dataclasses.dataclass(kw_only=True)
+@dataclass(kw_only=True)
 class EnsureBalanceParameters:
     """Parameters for ensuring an account has a minimum number of µALGOs"""
 
@@ -32,9 +30,10 @@ class EnsureBalanceParameters:
     """When issuing a funding amount, the minimum amount to transfer (avoids many small transfers if this gets
     called often on an active account)"""
 
-    funding_source: Account | AccountTransactionSigner | None = None
+    funding_source: Account | AccountTransactionSigner | DispenserApiTestnetClient | None = None
     """The account (with private key) or signer that will send the µALGOs,
-    will use `get_dispenser_account` by default"""
+    will use `get_dispenser_account` by default. Alternatively you can pass an instance of [`DispenserApiTestnetClient`](https://github.com/algorandfoundation/algokit-utils-py/blob/main/docs/source/capabilities/dispenser-client.md)
+    which will allow you to interact with [AlgoKit TestNet Dispenser API](https://github.com/algorandfoundation/algokit-cli/blob/main/docs/features/dispenser.md)."""
 
     suggested_params: SuggestedParams | None = None
     """(optional) transaction parameters"""
@@ -50,51 +49,103 @@ class EnsureBalanceParameters:
     if this is set it's possible the transaction could get rejected during network congestion"""
 
 
+@dataclass(kw_only=True)
+class EnsureFundedResponse:
+    """Response for ensuring an account has a minimum number of µALGOs"""
+
+    """The transaction ID of the funding transaction"""
+    transaction_id: str
+    """The amount of µALGOs that were funded"""
+    amount: int
+
+
+def _get_address_to_fund(parameters: EnsureBalanceParameters) -> str:
+    if isinstance(parameters.account_to_fund, str):
+        return parameters.account_to_fund
+    else:
+        return str(address_from_private_key(parameters.account_to_fund.private_key))  # type: ignore[no-untyped-call]
+
+
+def _get_account_info(client: AlgodClient, address_to_fund: str) -> dict:
+    account_info = client.account_info(address_to_fund)
+    assert isinstance(account_info, dict)
+    return account_info
+
+
+def _calculate_fund_amount(
+    parameters: EnsureBalanceParameters, current_spending_balance_micro_algos: int
+) -> int | None:
+    if parameters.min_spending_balance_micro_algos > current_spending_balance_micro_algos:
+        min_fund_amount_micro_algos = parameters.min_spending_balance_micro_algos - current_spending_balance_micro_algos
+        return max(min_fund_amount_micro_algos, parameters.min_funding_increment_micro_algos)
+    else:
+        return None
+
+
+def _fund_using_dispenser_api(
+    dispenser_client: DispenserApiTestnetClient, address_to_fund: str, fund_amount_micro_algos: int
+) -> EnsureFundedResponse | None:
+    response = dispenser_client.fund(
+        address=address_to_fund, amount=fund_amount_micro_algos, asset_id=DispenserAssetName.ALGO
+    )
+
+    return EnsureFundedResponse(transaction_id=response.tx_id, amount=response.amount)
+
+
+def _fund_using_transfer(
+    client: AlgodClient, parameters: EnsureBalanceParameters, address_to_fund: str, fund_amount_micro_algos: int
+) -> EnsureFundedResponse:
+    if isinstance(parameters.funding_source, DispenserApiTestnetClient):
+        raise Exception(f"Invalid funding source: {parameters.funding_source}")
+
+    funding_source = parameters.funding_source or get_dispenser_account(client)
+    response = transfer(
+        client,
+        TransferParameters(
+            from_account=funding_source,
+            to_address=address_to_fund,
+            micro_algos=fund_amount_micro_algos,
+            note=parameters.note or "Funding account to meet minimum requirement",
+            suggested_params=parameters.suggested_params,
+            max_fee_micro_algos=parameters.max_fee_micro_algos,
+            fee_micro_algos=parameters.fee_micro_algos,
+        ),
+    )
+    transaction_id = response.get_txid()  # type: ignore[no-untyped-call]
+    return EnsureFundedResponse(transaction_id=transaction_id, amount=response.amt)
+
+
 def ensure_funded(
-    client: "AlgodClient",
+    client: AlgodClient,
     parameters: EnsureBalanceParameters,
-) -> None | PaymentTxn:
+) -> EnsureFundedResponse | None:
     """
     Funds a given account using a funding source such that it has a certain amount of algos free to spend
     (accounting for ALGOs locked in minimum balance requirement)
     see <https://developer.algorand.org/docs/get-details/accounts/#minimum-balance>
 
-    :return None | PaymentTxn: None if balance was sufficient or the payment transaction used to increase the balance
-    """
-    address_to_fund = (
-        parameters.account_to_fund
-        if isinstance(parameters.account_to_fund, str)
-        else address_from_private_key(parameters.account_to_fund.private_key)  # type: ignore[no-untyped-call]
-    )
 
-    account_info = client.account_info(address_to_fund)
-    assert isinstance(account_info, dict)
+    Args:
+        client (AlgodClient): An instance of the AlgodClient class from the AlgoSDK library.
+        parameters (EnsureBalanceParameters): An instance of the EnsureBalanceParameters class that
+        specifies the account to fund and the minimum spending balance.
 
+    Returns:
+        PaymentTxn | str | None: If funds are needed, the function returns a payment transaction or a
+        string indicating that the dispenser API was used. If no funds are needed, the function returns None.
+    """
+
+    address_to_fund = _get_address_to_fund(parameters)
+    account_info = _get_account_info(client, address_to_fund)
     balance_micro_algos = account_info.get("amount", 0)
-    minimum_balance_micro_algos = account_info.get("min-balance")
+    minimum_balance_micro_algos = account_info.get("min-balance", 0)
     current_spending_balance_micro_algos = balance_micro_algos - minimum_balance_micro_algos
-    if parameters.min_spending_balance_micro_algos > current_spending_balance_micro_algos:
-        funding_source = parameters.funding_source or get_dispenser_account(client)
-        sender_address = address_from_private_key(funding_source.private_key)  # type: ignore[no-untyped-call]
+    fund_amount_micro_algos = _calculate_fund_amount(parameters, current_spending_balance_micro_algos)
 
-        min_fund_amount_micro_algos = parameters.min_spending_balance_micro_algos - current_spending_balance_micro_algos
-        fund_amount_micro_algos = max(min_fund_amount_micro_algos, parameters.min_funding_increment_micro_algos)
-        logger.info(
-            f"Funding {address_to_fund} {fund_amount_micro_algos}µ from {sender_address} to reach "
-            f"minimum spend amount of {parameters.min_spending_balance_micro_algos}µ (balance = "
-            f"{balance_micro_algos}µ, requirement = {minimum_balance_micro_algos}µ)"
-        )
-        return transfer(
-            client,
-            TransferParameters(
-                from_account=funding_source,
-                to_address=address_to_fund,
-                micro_algos=fund_amount_micro_algos,
-                note=parameters.note or "Funding account to meet minimum requirement",
-                suggested_params=parameters.suggested_params,
-                max_fee_micro_algos=parameters.max_fee_micro_algos,
-                fee_micro_algos=parameters.fee_micro_algos,
-            ),
-        )
+    if fund_amount_micro_algos is not None:
+        if is_testnet(client) and isinstance(parameters.funding_source, DispenserApiTestnetClient):
+            return _fund_using_dispenser_api(parameters.funding_source, address_to_fund, fund_amount_micro_algos)
+        else:
+            return _fund_using_transfer(client, parameters, address_to_fund, fund_amount_micro_algos)
 
     return None

algokit_utils/dispenser_api.py

@@ -0,0 +1,178 @@
+import contextlib
+import enum
+import logging
+import os
+from dataclasses import dataclass
+
+import httpx
+
+logger = logging.getLogger(__name__)
+
+
+class DispenserApiConfig:
+    BASE_URL = "https://api.dispenser.algorandfoundation.tools"
+
+
+class DispenserAssetName(enum.IntEnum):
+    ALGO = 0
+
+
+@dataclass
+class DispenserAsset:
+    asset_id: int
+    decimals: int
+    description: str
+
+
+@dataclass
+class DispenserFundResponse:
+    tx_id: str
+    amount: int
+
+
+@dataclass
+class DispenserLimitResponse:
+    amount: int
+
+
+DISPENSER_ASSETS = {
+    DispenserAssetName.ALGO: DispenserAsset(
+        asset_id=0,
+        decimals=6,
+        description="Algo",
+    ),
+}
+DISPENSER_REQUEST_TIMEOUT = 15
+DISPENSER_ACCESS_TOKEN_KEY = "ALGOKIT_DISPENSER_ACCESS_TOKEN"
+
+
+class DispenserApiTestnetClient:
+    """
+    Client for interacting with the [AlgoKit TestNet Dispenser API](https://github.com/algorandfoundation/algokit/blob/main/docs/testnet_api.md).
+    To get started create a new access token via `algokit dispenser login --ci`
+    and pass it to the client constructor as `auth_token`.
+    Alternatively set the access token as environment variable `ALGOKIT_DISPENSER_ACCESS_TOKEN`,
+    and it will be auto loaded. If both are set, the constructor argument takes precedence.
+
+    Default request timeout is 15 seconds. Modify by passing `request_timeout` to the constructor.
+    """
+
+    auth_token: str
+    request_timeout = DISPENSER_REQUEST_TIMEOUT
+
+    def __init__(self, auth_token: str | None = None, request_timeout: int = DISPENSER_REQUEST_TIMEOUT):
+        auth_token_from_env = os.getenv(DISPENSER_ACCESS_TOKEN_KEY)
+
+        if auth_token:
+            self.auth_token = auth_token
+        elif auth_token_from_env:
+            self.auth_token = auth_token_from_env
+        else:
+            raise Exception(
+                f"Can't init AlgoKit TestNet Dispenser API client "
+                f"because neither environment variable {DISPENSER_ACCESS_TOKEN_KEY} or "
+                "the auth_token were provided."
+            )
+
+        self.request_timeout = request_timeout
+
+    def _process_dispenser_request(
+        self, *, auth_token: str, url_suffix: str, data: dict | None = None, method: str = "POST"
+    ) -> httpx.Response:
+        """
+        Generalized method to process http requests to dispenser API
+        """
+
+        headers = {"Authorization": f"Bearer {(auth_token)}"}
+
+        # Set request arguments
+        request_args = {
+            "url": f"{DispenserApiConfig.BASE_URL}/{url_suffix}",
+            "headers": headers,
+            "timeout": self.request_timeout,
+        }
+
+        if method.upper() != "GET" and data is not None:
+            request_args["json"] = data
+
+        try:
+            response: httpx.Response = getattr(httpx, method.lower())(**request_args)
+            response.raise_for_status()
+            return response
+
+        except httpx.HTTPStatusError as err:
+            error_message = f"Error processing dispenser API request: {err.response.status_code}"
+            error_response = None
+            with contextlib.suppress(Exception):
+                error_response = err.response.json()
+
+            if error_response and error_response.get("code"):
+                error_message = error_response.get("code")
+
+            elif err.response.status_code == httpx.codes.BAD_REQUEST:
+                error_message = err.response.json()["message"]
+
+            raise Exception(error_message) from err
+
+        except Exception as err:
+            error_message = "Error processing dispenser API request"
+            logger.debug(f"{error_message}: {err}", exc_info=True)
+            raise err
+
+    def fund(self, address: str, amount: int, asset_id: int) -> DispenserFundResponse:
+        """
+        Fund an account with Algos from the dispenser API
+        """
+
+        try:
+            response = self._process_dispenser_request(
+                auth_token=self.auth_token,
+                url_suffix=f"fund/{asset_id}",
+                data={"receiver": address, "amount": amount, "assetID": asset_id},
+                method="POST",
+            )
+
+            content = response.json()
+            return DispenserFundResponse(tx_id=content["txID"], amount=content["amount"])
+
+        except Exception as err:
+            logger.exception(f"Error funding account {address}: {err}")
+            raise err
+
+    def refund(self, refund_txn_id: str) -> None:
+        """
+        Register a refund for a transaction with the dispenser API
+        """
+
+        try:
+            self._process_dispenser_request(
+                auth_token=self.auth_token,
+                url_suffix="refund",
+                data={"refundTransactionID": refund_txn_id},
+                method="POST",
+            )
+
+        except Exception as err:
+            logger.exception(f"Error issuing refund for txn_id {refund_txn_id}: {err}")
+            raise err
+
+    def limit(
+        self,
+        address: str,
+    ) -> DispenserLimitResponse:
+        """
+        Get current limit for an account with Algos from the dispenser API
+        """
+
+        try:
+            response = self._process_dispenser_request(
+                auth_token=self.auth_token,
+                url_suffix=f"fund/{DISPENSER_ASSETS[DispenserAssetName.ALGO].asset_id}/limit",
+                method="GET",
+            )
+            content = response.json()
+
+            return DispenserLimitResponse(amount=content["amount"])
+        except Exception as err:
+            logger.exception(f"Error setting limit for account {address}: {err}")
+            raise err

algokit_utils/network_clients.py

@@ -87,13 +87,13 @@ def is_localnet(client: AlgodClient) -> bool:
 def is_mainnet(client: AlgodClient) -> bool:
     """Returns True if client genesis is `mainnet-v1`"""
     params = client.suggested_params()
-    return bool(params.gen == "mainnet-v1")
+    return params.gen in ["mainnet-v1.0", "mainnet-v1", "mainnet"]
 
 
 def is_testnet(client: AlgodClient) -> bool:
     """Returns True if client genesis is `testnet-v1`"""
     params = client.suggested_params()
-    return bool(params.gen == "testnet-v1")
+    return params.gen in ["testnet-v1.0", "testnet-v1", "testnet"]
 
 
 def get_kmd_client_from_algod_client(client: AlgodClient) -> KMDClient:

{algokit_utils-1.4.0b2.dist-info → algokit_utils-2.0.0b1.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: algokit-utils
-Version: 1.4.0b2
+Version: 2.0.0b1
 Summary: Utilities for Algorand development for use by AlgoKit
 License: MIT
 Author: Algorand Foundation
@@ -11,6 +11,7 @@ Classifier: Programming Language :: Python :: 3
 Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11
 Requires-Dist: deprecated (>=1.2.14,<2.0.0)
+Requires-Dist: httpx (>=0.23.1,<0.24.0)
 Requires-Dist: py-algorand-sdk (>=2.4.0,<3.0.0)
 Description-Content-Type: text/markdown
 

{algokit_utils-1.4.0b2.dist-info → algokit_utils-2.0.0b1.dist-info}/RECORD

@@ -1,16 +1,18 @@
-algokit_utils/__init__.py,sha256=KIqgpe_cj8Bc7QZIC2jNKSZj5nfKef4aZ8KPaiiq_Sw,4214
-algokit_utils/_ensure_funded.py,sha256=DjwGnCC_6USLQV5wIMJZRVQFlQ1uLrGDMxRF471atsQ,4410
+algokit_utils/__init__.py,sha256=zmNphGblbOciVTNTuNuovvIl64L2ue2kAiU_umwrPIw,4633
+algokit_utils/_ensure_funded.py,sha256=4KeLe76KGl01Z7Q8zpdy3d59lSPnEXmEZGKQceFDEB8,6786
 algokit_utils/_transfer.py,sha256=CyXGOR_Zy-2crQhk-78uUbB8Sj_ZeTzxPwOAHU7wwno,5947
 algokit_utils/account.py,sha256=UIuOQZe28pQxjEP9TzhtYlOU20tUdzzS-nIIZM9Bp6Y,7364
 algokit_utils/application_client.py,sha256=9YH4ecHsn0aXmDeaApraT5WeHaUlN4FPa27QdtN9tew,57878
 algokit_utils/application_specification.py,sha256=XusOe7VrGPun2UoNspC9Ei202NzPkxRNx5USXiABuXc,7466
 algokit_utils/config.py,sha256=V8010eUkbfcoB0bHtxsGQOymq1cqNRc1lDWnwcumQpM,567
 algokit_utils/deploy.py,sha256=sY6u0T39DuF6oLpal0eJAc76EmjPWdoCPk2OSKGccnM,34650
+algokit_utils/dispenser_api.py,sha256=eU2R37aAF5w06GBJx7XrBjriFrDe63jyrEECCHOreHo,5580
 algokit_utils/logic_error.py,sha256=vkLVdxv-XPnwRiIP4CWedgtIZcOPr_5wr7XVH02If9w,2615
 algokit_utils/models.py,sha256=KynZnM2YbOyTgr2NCT8CA-cYrO0eiyK6u48eeAzj82I,8246
-algokit_utils/network_clients.py,sha256=KmuSHG2kSdJfo9W4pIB_4RjnBL2yMQNGlF54lxXTnsQ,5267
+algokit_utils/network_clients.py,sha256=sj5y_g5uclddWCEyUCptA-KjWuAtLV06hZH4QIGM1yE,5313
 algokit_utils/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-algokit_utils-1.4.0b2.dist-info/LICENSE,sha256=J5i7U1Q9Q2c7saUzlvFRmrCCFhQyXb5Juz_LO5omNUw,1076
-algokit_utils-1.4.0b2.dist-info/METADATA,sha256=SjLMFQaF5wK-8SFEWMx5LhfBHwY7snuPjluwKhBjdM4,2116
-algokit_utils-1.4.0b2.dist-info/WHEEL,sha256=d2fvjOD7sXsVzChCqf0Ty0JbHKBaLYwDbGQDwQTnJ50,88
-algokit_utils-1.4.0b2.dist-info/RECORD,,
+algokit_utils/test_dispenser_api.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+algokit_utils-2.0.0b1.dist-info/LICENSE,sha256=J5i7U1Q9Q2c7saUzlvFRmrCCFhQyXb5Juz_LO5omNUw,1076
+algokit_utils-2.0.0b1.dist-info/METADATA,sha256=k_uevqLR0z0cRHwyJf-qk3oasQyTyHDBPI2PSjFJDno,2156
+algokit_utils-2.0.0b1.dist-info/WHEEL,sha256=d2fvjOD7sXsVzChCqf0Ty0JbHKBaLYwDbGQDwQTnJ50,88
+algokit_utils-2.0.0b1.dist-info/RECORD,,