algokit-utils 5.0.0a3__py3-none-any.whl

algokit_utils/transactions/types.py

@@ -0,0 +1,262 @@
+from dataclasses import dataclass
+from typing import TypedDict, Union
+
+from algokit_abi import arc56
+from algokit_transact import OnApplicationComplete
+from algokit_transact.signer import AddressWithTransactionSigner, TransactionSigner
+from algokit_utils.models.amount import AlgoAmount
+from algokit_utils.models.state import BoxIdentifier, BoxReference
+
+__all__ = [
+    "AppCallMethodCallParams",
+    "AppCallParams",
+    "AppCreateMethodCallParams",
+    "AppCreateParams",
+    "AppCreateSchema",
+    "AppDeleteMethodCallParams",
+    "AppDeleteParams",
+    "AppMethodCallParams",
+    "AppUpdateMethodCallParams",
+    "AppUpdateParams",
+    "AssetConfigParams",
+    "AssetCreateParams",
+    "AssetDestroyParams",
+    "AssetFreezeParams",
+    "AssetOptInParams",
+    "AssetOptOutParams",
+    "AssetTransferParams",
+    "CommonTxnParams",
+    "MethodCallParams",
+    "OfflineKeyRegistrationParams",
+    "OnlineKeyRegistrationParams",
+    "PaymentParams",
+    "TxnParams",
+]
+
+
+@dataclass(kw_only=True, frozen=True)
+class CommonTxnParams:
+    sender: str
+    signer: TransactionSigner | AddressWithTransactionSigner | None = None
+    rekey_to: str | None = None
+    note: bytes | None = None
+    lease: bytes | None = None
+    static_fee: AlgoAmount | None = None
+    extra_fee: AlgoAmount | None = None
+    max_fee: AlgoAmount | None = None
+    validity_window: int | None = None
+    first_valid_round: int | None = None
+    last_valid_round: int | None = None
+
+
+@dataclass(kw_only=True, frozen=True)
+class PaymentParams(CommonTxnParams):
+    receiver: str
+    amount: AlgoAmount
+    close_remainder_to: str | None = None
+
+
+@dataclass(kw_only=True, frozen=True)
+class AssetCreateParams(CommonTxnParams):
+    total: int
+    asset_name: str | None = None
+    unit_name: str | None = None
+    url: str | None = None
+    decimals: int | None = None
+    default_frozen: bool | None = None
+    manager: str | None = None
+    reserve: str | None = None
+    freeze: str | None = None
+    clawback: str | None = None
+    metadata_hash: bytes | None = None
+
+
+@dataclass(kw_only=True, frozen=True)
+class AssetConfigParams(CommonTxnParams):
+    asset_id: int
+    manager: str | None = None
+    reserve: str | None = None
+    freeze: str | None = None
+    clawback: str | None = None
+
+
+@dataclass(kw_only=True, frozen=True)
+class AssetFreezeParams(CommonTxnParams):
+    asset_id: int
+    account: str
+    frozen: bool
+
+
+@dataclass(kw_only=True, frozen=True)
+class AssetDestroyParams(CommonTxnParams):
+    asset_id: int
+
+
+@dataclass(kw_only=True, frozen=True)
+class OnlineKeyRegistrationParams(CommonTxnParams):
+    vote_key: str
+    selection_key: str
+    state_proof_key: bytes | None = None
+    vote_first: int = 0
+    vote_last: int = 0
+    vote_key_dilution: int = 0
+    nonparticipation: bool | None = None
+
+
+@dataclass(kw_only=True, frozen=True)
+class OfflineKeyRegistrationParams(CommonTxnParams):
+    prevent_account_from_ever_participating_again: bool = True
+
+
+@dataclass(kw_only=True, frozen=True)
+class AssetTransferParams(CommonTxnParams):
+    asset_id: int
+    amount: int
+    receiver: str
+    close_asset_to: str | None = None
+    clawback_target: str | None = None
+
+
+@dataclass(kw_only=True, frozen=True)
+class AssetOptInParams(CommonTxnParams):
+    asset_id: int
+
+
+@dataclass(kw_only=True, frozen=True)
+class AssetOptOutParams(CommonTxnParams):
+    asset_id: int
+    creator: str
+
+
+@dataclass(kw_only=True, frozen=True)
+class AppCallParams(CommonTxnParams):
+    app_id: int
+    args: list[bytes] | None = None
+    account_references: list[str] | None = None
+    app_references: list[int] | None = None
+    asset_references: list[int] | None = None
+    box_references: list[BoxReference | BoxIdentifier] | None = None
+    on_complete: OnApplicationComplete | None = None
+
+
+class AppCreateSchema(TypedDict):
+    global_ints: int
+    global_byte_slices: int
+    local_ints: int
+    local_byte_slices: int
+
+
+@dataclass(kw_only=True, frozen=True)
+class AppCreateParams(CommonTxnParams):
+    approval_program: str | bytes
+    clear_state_program: str | bytes
+    schema: AppCreateSchema | None = None
+    on_complete: OnApplicationComplete | None = None
+    args: list[bytes] | None = None
+    account_references: list[str] | None = None
+    app_references: list[int] | None = None
+    asset_references: list[int] | None = None
+    box_references: list[BoxReference | BoxIdentifier] | None = None
+    extra_program_pages: int | None = None
+
+
+@dataclass(kw_only=True, frozen=True)
+class AppUpdateParams(CommonTxnParams):
+    app_id: int
+    approval_program: str | bytes
+    clear_state_program: str | bytes
+    args: list[bytes] | None = None
+    account_references: list[str] | None = None
+    app_references: list[int] | None = None
+    asset_references: list[int] | None = None
+    box_references: list[BoxReference | BoxIdentifier] | None = None
+    on_complete: OnApplicationComplete = OnApplicationComplete.UpdateApplication
+
+
+@dataclass(kw_only=True, frozen=True)
+class AppDeleteParams(CommonTxnParams):
+    app_id: int
+    args: list[bytes] | None = None
+    account_references: list[str] | None = None
+    app_references: list[int] | None = None
+    asset_references: list[int] | None = None
+    box_references: list[BoxReference | BoxIdentifier] | None = None
+    on_complete: OnApplicationComplete | None = None
+
+
+@dataclass(kw_only=True, frozen=True)
+class _BaseAppMethodCall(CommonTxnParams):
+    app_id: int | None = None
+    method: arc56.Method
+    args: list | None = None
+    account_references: list[str] | None = None
+    app_references: list[int] | None = None
+    asset_references: list[int] | None = None
+    box_references: list[BoxReference | BoxIdentifier] | None = None
+    schema: AppCreateSchema | None = None
+    on_complete: OnApplicationComplete | None = None
+    extra_program_pages: int | None = None
+
+
+@dataclass(kw_only=True, frozen=True)
+class AppMethodCallParams(CommonTxnParams):
+    app_id: int
+    method: arc56.Method
+    args: list[bytes] | None = None
+    on_complete: OnApplicationComplete | None = None
+    account_references: list[str] | None = None
+    app_references: list[int] | None = None
+    asset_references: list[int] | None = None
+    box_references: list[BoxReference | BoxIdentifier] | None = None
+
+
+@dataclass(kw_only=True, frozen=True)
+class AppCallMethodCallParams(_BaseAppMethodCall):
+    app_id: int
+    on_complete: OnApplicationComplete | None = None
+
+
+@dataclass(kw_only=True, frozen=True)
+class AppCreateMethodCallParams(_BaseAppMethodCall):
+    approval_program: str | bytes
+    clear_state_program: str | bytes
+    schema: AppCreateSchema | None = None
+    on_complete: OnApplicationComplete | None = None
+
+
+@dataclass(kw_only=True, frozen=True)
+class AppUpdateMethodCallParams(_BaseAppMethodCall):
+    app_id: int
+    approval_program: str | bytes
+    clear_state_program: str | bytes
+    on_complete: OnApplicationComplete = OnApplicationComplete.UpdateApplication
+
+
+@dataclass(kw_only=True, frozen=True)
+class AppDeleteMethodCallParams(_BaseAppMethodCall):
+    app_id: int
+    on_complete: OnApplicationComplete = OnApplicationComplete.DeleteApplication
+
+
+MethodCallParams = (
+    AppCallMethodCallParams | AppCreateMethodCallParams | AppUpdateMethodCallParams | AppDeleteMethodCallParams
+)
+
+
+TxnParams = Union[  # noqa: UP007
+    PaymentParams,
+    AssetCreateParams,
+    AssetConfigParams,
+    AssetFreezeParams,
+    AssetDestroyParams,
+    OnlineKeyRegistrationParams,
+    AssetTransferParams,
+    AssetOptInParams,
+    AssetOptOutParams,
+    AppCallParams,
+    AppCreateParams,
+    AppUpdateParams,
+    AppDeleteParams,
+    MethodCallParams,
+    OfflineKeyRegistrationParams,
+]

algokit_utils-5.0.0a3.dist-info/METADATA

@@ -0,0 +1,105 @@
+Metadata-Version: 2.4
+Name: algokit-utils
+Version: 5.0.0a3
+Summary: Utilities for Algorand development for use by AlgoKit
+Author: Algorand Foundation
+Author-email: Algorand Foundation <contact@algorand.foundation>
+License-Expression: MIT
+Requires-Dist: httpx>=0.23.1,<=0.28.1
+Requires-Dist: msgpack>=1.0.0,<2
+Requires-Dist: msgpack-types>=0.2.0,<=0.5.0
+Requires-Dist: pynacl>=1.4.0,<2
+Requires-Dist: pycryptodomex>=3.19,<4
+Requires-Dist: typing-extensions>=4.6.0
+Requires-Python: >=3.10, <4
+Description-Content-Type: text/markdown
+
+# AlgoKit Python Utilities
+
+A set of core Algorand utilities written in Python and released via PyPi that make it easier to build solutions on Algorand.
+This project is part of [AlgoKit](https://github.com/algorandfoundation/algokit-cli).
+
+The goal of this library is to provide intuitive, productive utility functions that make it easier, quicker and safer to build applications on Algorand.
+Largely these functions wrap the underlying Algorand SDK, but provide a higher level interface with sensible defaults and capabilities for common tasks.
+
+> **Note**
+> If you prefer TypeScript there's an equivalent [TypeScript utility library](https://github.com/algorandfoundation/algokit-utils-ts).
+
+[Install](https://github.com/algorandfoundation/algokit-utils-py#install) | [Documentation](https://algorandfoundation.github.io/algokit-utils-py)
+
+## Install
+
+This library can be installed using pip, e.g.:
+
+```
+pip install algokit-utils
+```
+
+## Migration from `v2.x` to `v3.x`
+
+Refer to the [v3 migration](./docs/source/v3-migration-guide.md) for more information on how to migrate to latest version of `algokit-utils-py`.
+
+## Guiding principles
+
+This library follows the [Guiding Principles of AlgoKit](https://github.com/algorandfoundation/algokit-cli/blob/main/docs/algokit.md#guiding-principles).
+
+## Contributing
+
+This is an open source project managed by the Algorand Foundation.
+See the [AlgoKit contributing page](https://github.com/algorandfoundation/algokit-cli/blob/main/CONTRIBUTING.MD) to learn about making improvements.
+
+To successfully run the tests in this repository you need to be running LocalNet via [AlgoKit](https://github.com/algorandfoundation/algokit-cli):
+
+```
+algokit localnet start
+```
+
+### Mock Server Tests
+
+Tests under `tests/modules/` use a mock server for deterministic API testing against pre-recorded HAR files. The mock server is managed externally (not by pytest).
+
+**In CI:** Mock servers are automatically started via the [algokit-polytest](https://github.com/algorandfoundation/algokit-polytest) GitHub Action.
+
+**Local development:**
+
+1. Clone algokit-polytest and start the mock servers:
+
+```bash
+# Clone algokit-polytest (if not already)
+git clone https://github.com/algorandfoundation/algokit-polytest.git
+
+# Start all mock servers (recommended)
+cd algokit-polytest/resources/mock-server
+./scripts/start_all_servers.sh
+```
+
+This starts algod (port 8000), kmd (port 8001), and indexer (port 8002) in the background.
+
+2. Set environment variables and run tests:
+
+```bash
+export MOCK_ALGOD_URL=http://localhost:8000
+export MOCK_INDEXER_URL=http://localhost:8002
+export MOCK_KMD_URL=http://localhost:8001
+
+# Run all module tests
+pytest tests/modules/
+
+# Or run specific client tests
+pytest tests/modules/algod_client/
+```
+
+3. Stop servers when done:
+
+```bash
+cd algokit-polytest/resources/mock-server
+./scripts/stop_all_servers.sh
+```
+
+| Environment Variable | Description | Default Port |
+|---------------------|-------------|--------------|
+| `MOCK_ALGOD_URL` | Algod mock server URL | 8000 |
+| `MOCK_INDEXER_URL` | Indexer mock server URL | 8002 |
+| `MOCK_KMD_URL` | KMD mock server URL | 8001 |
+
+Environment variables can also be set via `.env` file in project root (copy from `.env.template`).