algorand-python-testing 1.2.0b2__tar.gz → 1.2.0b3__tar.gz

{algorand_python_testing-1.2.0b2 → algorand_python_testing-1.2.0b3}/CHANGELOG.md

@@ -1,4 +1,10 @@
 # CHANGELOG
+## v1.2.0-beta.3 (2025-12-08)
+
+### Features
+
+* add stage and submit_staged functions to support submitting dynamic number of inner transactions in a group ([`84ad031`](https://github.com/algorandfoundation/algorand-python-testing/commit/84ad03166442dadc10c7c1fe70e4cd07a63600cc))
+
 ## v1.2.0-beta.2 (2025-12-08)
 
 ### Features

{algorand_python_testing-1.2.0b2 → algorand_python_testing-1.2.0b3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: algorand-python-testing
-Version: 1.2.0b2
+Version: 1.2.0b3
 Summary: Algorand Python testing library
 Project-URL: Documentation, https://github.com/algorandfoundation/puya/tree/main/algopy_testing#README.md
 Project-URL: Issues, https://github.com/algorandfoundation/puya/issues

{algorand_python_testing-1.2.0b2 → algorand_python_testing-1.2.0b3}/docs/coverage.md

@@ -96,6 +96,7 @@ See which `algorand-python` stubs are implemented by the `algorand-python-testin
 | algopy.itxn.KeyRegistrationInnerTransaction | Emulated            |
 | algopy.itxn.Payment                         | Emulated            |
 | algopy.itxn.PaymentInnerTransaction         | Emulated            |
+| algopy.itxn.submit_staged                   | Emulated            |
 | algopy.itxn.submit_txns                     | Emulated            |
 | algopy.op.Base64                            | Native              |
 | algopy.op.EC                                | Native              |

{algorand_python_testing-1.2.0b2 → algorand_python_testing-1.2.0b3}/docs/testing-guide/transactions.md

@@ -190,6 +190,75 @@ To access the submitted inner transactions:
 
 These methods provide type validation and will raise an error if the requested transaction type doesn't match the actual type of the inner transaction.
 
+### Submitting a group with dynamic number of inner transactions
+
+`algorand-python` supports composing inner transaction groups with a dynamic number of transactions. To use this feature, call the `.stage()` method on inner transaction classes to queue transactions, then call `algopy.itxn.submit_staged()` to submit all staged transactions as a group.
+
+The following example demonstrates how to test this functionality using the `algorand-python-testing` package.
+
+```{testcode}
+from algopy import Application, ARC4Contract, Array, Global, arc4, gtxn, itxn, TransactionType, Txn, UInt64, urange
+
+class DynamicItxnGroup(ARC4Contract):
+    @arc4.abimethod
+    def distribute(
+        self, addresses: Array[arc4.Address], funds: gtxn.PaymentTransaction, verifier: Application
+    ) -> None:
+        assert funds.receiver == Global.current_application_address, "Funds must be sent to app"
+
+        assert addresses.length, "must provide some accounts"
+
+        share = funds.amount // addresses.length
+
+        itxn.Payment(amount=share, receiver=addresses[0].native).stage(begin_group=True)
+
+        for i in urange(1, addresses.length):
+            addr = addresses[i]
+            itxn.Payment(amount=share, receiver=addr.native).stage()
+
+        itxn.ApplicationCall(
+            app_id=verifier.id, app_args=(arc4.arc4_signature("verify()void"),)
+        ).stage()
+
+        itxn.AssetConfig(asset_name="abc").stage()
+
+        itxn.submit_staged()
+
+class VerifierContract(ARC4Contract):
+    @arc4.abimethod
+    def verify(self) -> None:
+        for i in urange(Txn.group_index):
+            txn = gtxn.Transaction(i)
+            assert txn.type == TransactionType.Payment, "Txn must be pay"
+
+
+# create contract instaces
+verifier = VerifierContract()
+dynamic_itxn_group = DynamicItxnGroup()
+
+# get application id for contract instances
+verifier_app = context.ledger.get_app(verifier)
+dynamic_itxn_group_app = context.ledger.get_app(dynamic_itxn_group)
+
+# create test accounts to distribute funds to and initial fund
+addresses = Array([arc4.Address(context.any.account()) for _ in range(3)])
+payment = context.any.txn.payment(
+    amount=UInt64(9),
+    receiver=dynamic_itxn_group_app.address,
+)
+
+# call contract method which creates inner transactions according to number of addresses passed in
+dynamic_itxn_group.distribute(addresses, payment, verifier_app)
+
+# get inner transaction group to assert the details
+itxns = context.txn.last_group.get_itxn_group(-1)
+assert len(itxns) == 5
+for i in range(3):
+    assert itxns.payment(i).amount == 3
+assert itxns.application_call(3).app_id == verifier_app
+assert itxns.asset_config(4).asset_name == b"abc"
+```
+
 ## References
 
 -   [API](../api.md) for more details on the test context manager and inner transactions related methods that perform implicit inner transaction type validation.

{algorand_python_testing-1.2.0b2 → algorand_python_testing-1.2.0b3}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "algorand-python-testing"
-version = "1.2.0-beta.2"
+version = "1.2.0-beta.3"
 description = 'Algorand Python testing library'
 readme = "README.md"
 requires-python = ">=3.12"

{algorand_python_testing-1.2.0b2 → algorand_python_testing-1.2.0b3}/src/_algopy_testing/context_helpers/txn_context.py

@@ -326,19 +326,19 @@ class TransactionGroup:
         except ValueError:
             raise ValueError("Transaction is not part of this group") from None
 
-    def _begin_itxn_group(self) -> None:
+    def _begin_itxn_group(self, itxn: InnerTransaction | None = None) -> None:
         if self._constructing_itxn_group:
             raise RuntimeError("itxn begin without itxn submit")
 
         if self.active_txn.on_completion == OnCompleteAction.ClearState:
             raise RuntimeError("Cannot begin inner transaction group in a clear state call")
 
-        self._constructing_itxn_group.append(InnerTransaction())
+        self._constructing_itxn_group.append(itxn or InnerTransaction())
 
-    def _append_itxn_group(self) -> None:
+    def _append_itxn_group(self, itxn: InnerTransaction | None = None) -> None:
         if not self._constructing_itxn_group:
             raise RuntimeError("itxn next without itxn begin")
-        self._constructing_itxn_group.append(InnerTransaction())
+        self._constructing_itxn_group.append(itxn or InnerTransaction())
 
     def _submit_itxn_group(self) -> None:
         if not self._constructing_itxn_group:

{algorand_python_testing-1.2.0b2 → algorand_python_testing-1.2.0b3}/src/_algopy_testing/itxn.py

@@ -33,6 +33,7 @@ __all__ = [
     "KeyRegistrationInnerTransaction",
     "Payment",
     "PaymentInnerTransaction",
+    "submit_staged",
     "submit_txns",
 ]
 
@@ -113,6 +114,12 @@ class _BaseInnerTransactionFields(typing.Protocol[_TResult_co]):
         _narrow_covariant_types(fields)
         self.fields.update(fields)
 
+    def stage(self, *, begin_group: bool = False) -> None:
+        if begin_group:
+            lazy_context.active_group._begin_itxn_group(self)  # type: ignore[arg-type]
+        else:
+            lazy_context.active_group._append_itxn_group(self)  # type: ignore[arg-type]
+
     def submit(self) -> _TResult_co:
         result = _get_itxn_result(self)
         lazy_context.active_group._add_itxn_group([result])  # type: ignore[list-item]
@@ -170,6 +177,10 @@ def submit_txns(
     return results
 
 
+def submit_staged() -> None:
+    lazy_context.active_group._submit_itxn_group()
+
+
 def _get_itxn_result(
     itxn: _BaseInnerTransactionFields[_TResult_co],
 ) -> _BaseInnerTransactionResult:

algorand_python_testing-1.2.0b3/tests/artifacts/DynamicITxnGroup/contract.py

@@ -0,0 +1,63 @@
+from algopy import (
+    Application,
+    ARC4Contract,
+    Array,
+    Global,
+    arc4,
+    gtxn,
+    itxn,
+    urange,
+)
+
+
+class DynamicItxnGroup(ARC4Contract):
+    @arc4.abimethod
+    def test_firstly(
+        self, addresses: Array[arc4.Address], funds: gtxn.PaymentTransaction, verifier: Application
+    ) -> None:
+        assert funds.receiver == Global.current_application_address, "Funds must be sent to app"
+
+        assert addresses.length, "must provide some accounts"
+
+        share = funds.amount // addresses.length
+
+        itxn.Payment(amount=share, receiver=addresses[0].native).stage(begin_group=True)
+
+        for i in urange(1, addresses.length):
+            addr = addresses[i]
+            itxn.Payment(amount=share, receiver=addr.native).stage()
+
+        itxn.ApplicationCall(
+            app_id=verifier.id, app_args=(arc4.arc4_signature("verify()void"),)
+        ).stage()
+
+        itxn.AssetConfig(asset_name="abc").stage()
+
+        itxn.submit_staged()
+
+    @arc4.abimethod
+    def test_looply(
+        self,
+        addresses: Array[arc4.Address],
+        funds: gtxn.PaymentTransaction,
+        verifier: Application,
+    ) -> None:
+        assert funds.receiver == Global.current_application_address, "Funds must be sent to app"
+
+        assert addresses.length, "must provide some accounts"
+
+        share = funds.amount // addresses.length
+
+        is_first = True
+        for addr in addresses:
+            my_txn = itxn.Payment(amount=share, receiver=addr.native)
+            my_txn.stage(begin_group=is_first)
+            is_first = False
+
+        itxn.ApplicationCall(
+            app_id=verifier.id, app_args=(arc4.arc4_signature("verify()void"),)
+        ).stage()
+
+        itxn.AssetConfig(asset_name="abc").stage()
+
+        itxn.submit_staged()

algorand_python_testing-1.2.0b3/tests/artifacts/DynamicITxnGroup/data/DynamicItxnGroup.approval.teal

@@ -0,0 +1,284 @@
+#pragma version 11
+#pragma typetrack false
+
+// algopy.arc4.ARC4Contract.approval_program() -> uint64:
+main:
+    intcblock 1 0 32 6
+    bytecblock 0x65a9aecc "abc"
+    // tests/artifacts/dynamic_itxn_group/contract.py:13
+    // class DynamicItxnGroup(ARC4Contract):
+    txn NumAppArgs
+    bz main___algopy_default_create@9
+    txn OnCompletion
+    !
+    assert
+    txn ApplicationID
+    assert
+    pushbytess 0x17391784 0x3f10aea7 // method "test_firstly(address[],pay,uint64)void", method "test_looply(address[],pay,uint64)void"
+    txna ApplicationArgs 0
+    match test_firstly test_looply
+    err
+
+main___algopy_default_create@9:
+    txn OnCompletion
+    !
+    txn ApplicationID
+    !
+    &&
+    return
+
+
+// tests.artifacts.dynamic_itxn_group.contract.DynamicItxnGroup.test_firstly[routing]() -> void:
+test_firstly:
+    // tests/artifacts/dynamic_itxn_group/contract.py:14
+    // @arc4.abimethod
+    txna ApplicationArgs 1
+    txn GroupIndex
+    intc_0 // 1
+    -
+    dup
+    gtxns TypeEnum
+    intc_0 // pay
+    ==
+    assert // transaction type is pay
+    txna ApplicationArgs 2
+    btoi
+    cover 2
+    // tests/artifacts/dynamic_itxn_group/contract.py:18
+    // assert funds.receiver == Global.current_application_address, "Funds must be sent to app"
+    dup
+    gtxns Receiver
+    global CurrentApplicationAddress
+    ==
+    assert // Funds must be sent to app
+    // tests/artifacts/dynamic_itxn_group/contract.py:20
+    // assert addresses.length, "must provide some accounts"
+    dig 1
+    intc_1 // 0
+    extract_uint16 // on error: invalid array length header
+    dup
+    cover 3
+    dup
+    assert // must provide some accounts
+    // tests/artifacts/dynamic_itxn_group/contract.py:22
+    // share = funds.amount // addresses.length
+    swap
+    gtxns Amount
+    swap
+    /
+    dup
+    cover 2
+    // tests/artifacts/dynamic_itxn_group/contract.py:24
+    // itxn.Payment(amount=share, receiver=addresses[0].native).stage(begin_group=True)
+    itxn_begin
+    dig 1
+    extract 2 0
+    cover 2
+    swap
+    extract 2 32
+    itxn_field Receiver
+    itxn_field Amount
+    intc_0 // pay
+    itxn_field TypeEnum
+    intc_1 // 0
+    itxn_field Fee
+    // tests/artifacts/dynamic_itxn_group/contract.py:26
+    // for i in urange(1, addresses.length):
+    intc_0 // 1
+
+test_firstly_for_header@2:
+    // tests/artifacts/dynamic_itxn_group/contract.py:26
+    // for i in urange(1, addresses.length):
+    dup
+    dig 4
+    <
+    bz test_firstly_after_for@5
+    // tests/artifacts/dynamic_itxn_group/contract.py:27
+    // addr = addresses[i]
+    dupn 2
+    intc_2 // 32
+    *
+    dig 3
+    swap
+    intc_2 // 32
+    extract3 // on error: index access is out of bounds
+    // tests/artifacts/dynamic_itxn_group/contract.py:28
+    // itxn.Payment(amount=share, receiver=addr.native).stage()
+    itxn_next
+    itxn_field Receiver
+    dig 3
+    itxn_field Amount
+    intc_0 // pay
+    itxn_field TypeEnum
+    intc_1 // 0
+    itxn_field Fee
+    // tests/artifacts/dynamic_itxn_group/contract.py:26
+    // for i in urange(1, addresses.length):
+    intc_0 // 1
+    +
+    bury 1
+    b test_firstly_for_header@2
+
+test_firstly_after_for@5:
+    // tests/artifacts/dynamic_itxn_group/contract.py:30-32
+    // itxn.ApplicationCall(
+    //     app_id=verifier.id, app_args=(arc4.arc4_signature("verify()void"),)
+    // ).stage()
+    itxn_next
+    // tests/artifacts/dynamic_itxn_group/contract.py:31
+    // app_id=verifier.id, app_args=(arc4.arc4_signature("verify()void"),)
+    bytec_0 // method "verify()void"
+    itxn_field ApplicationArgs
+    dig 4
+    itxn_field ApplicationID
+    // tests/artifacts/dynamic_itxn_group/contract.py:30
+    // itxn.ApplicationCall(
+    intc_3 // appl
+    itxn_field TypeEnum
+    intc_1 // 0
+    itxn_field Fee
+    // tests/artifacts/dynamic_itxn_group/contract.py:34
+    // itxn.AssetConfig(asset_name="abc").stage()
+    itxn_next
+    bytec_1 // "abc"
+    itxn_field ConfigAssetName
+    pushint 3 // acfg
+    itxn_field TypeEnum
+    intc_1 // 0
+    itxn_field Fee
+    // tests/artifacts/dynamic_itxn_group/contract.py:36
+    // itxn.submit_staged()
+    itxn_submit
+    // tests/artifacts/dynamic_itxn_group/contract.py:14
+    // @arc4.abimethod
+    intc_0 // 1
+    return
+
+
+// tests.artifacts.dynamic_itxn_group.contract.DynamicItxnGroup.test_looply[routing]() -> void:
+test_looply:
+    intc_1 // 0
+    // tests/artifacts/dynamic_itxn_group/contract.py:38
+    // @arc4.abimethod
+    txna ApplicationArgs 1
+    dup
+    txn GroupIndex
+    intc_0 // 1
+    -
+    dup
+    gtxns TypeEnum
+    intc_0 // pay
+    ==
+    assert // transaction type is pay
+    txna ApplicationArgs 2
+    btoi
+    cover 2
+    // tests/artifacts/dynamic_itxn_group/contract.py:45
+    // assert funds.receiver == Global.current_application_address, "Funds must be sent to app"
+    dup
+    gtxns Receiver
+    global CurrentApplicationAddress
+    ==
+    assert // Funds must be sent to app
+    // tests/artifacts/dynamic_itxn_group/contract.py:47
+    // assert addresses.length, "must provide some accounts"
+    swap
+    intc_1 // 0
+    extract_uint16 // on error: invalid array length header
+    dup
+    cover 2
+    dup
+    assert // must provide some accounts
+    // tests/artifacts/dynamic_itxn_group/contract.py:49
+    // share = funds.amount // addresses.length
+    swap
+    gtxns Amount
+    swap
+    /
+    // tests/artifacts/dynamic_itxn_group/contract.py:51
+    // is_first = True
+    intc_0 // 1
+    intc_1 // 0
+
+test_looply_for_header@2:
+    // tests/artifacts/dynamic_itxn_group/contract.py:52
+    // for addr in addresses:
+    dup
+    dig 4
+    <
+    bz test_looply_after_for@8
+    dig 5
+    extract 2 0
+    dig 1
+    intc_2 // 32
+    *
+    intc_2 // 32
+    extract3 // on error: index access is out of bounds
+    bury 7
+    // tests/artifacts/dynamic_itxn_group/contract.py:54
+    // my_txn.stage(begin_group=is_first)
+    dig 1
+    bz test_looply_itxn_next@5
+    itxn_begin
+
+test_looply_after_itxn_begin_next@6:
+    dig 6
+    itxn_field Receiver
+    dig 2
+    itxn_field Amount
+    // tests/artifacts/dynamic_itxn_group/contract.py:53
+    // my_txn = itxn.Payment(amount=share, receiver=addr.native)
+    intc_0 // pay
+    itxn_field TypeEnum
+    intc_1 // 0
+    itxn_field Fee
+    // tests/artifacts/dynamic_itxn_group/contract.py:55
+    // is_first = False
+    intc_1 // 0
+    bury 2
+    dup
+    intc_0 // 1
+    +
+    bury 1
+    b test_looply_for_header@2
+
+test_looply_itxn_next@5:
+    // tests/artifacts/dynamic_itxn_group/contract.py:54
+    // my_txn.stage(begin_group=is_first)
+    itxn_next
+    b test_looply_after_itxn_begin_next@6
+
+test_looply_after_for@8:
+    // tests/artifacts/dynamic_itxn_group/contract.py:57-59
+    // itxn.ApplicationCall(
+    //     app_id=verifier.id, app_args=(arc4.arc4_signature("verify()void"),)
+    // ).stage()
+    itxn_next
+    // tests/artifacts/dynamic_itxn_group/contract.py:58
+    // app_id=verifier.id, app_args=(arc4.arc4_signature("verify()void"),)
+    bytec_0 // method "verify()void"
+    itxn_field ApplicationArgs
+    dig 4
+    itxn_field ApplicationID
+    // tests/artifacts/dynamic_itxn_group/contract.py:57
+    // itxn.ApplicationCall(
+    intc_3 // appl
+    itxn_field TypeEnum
+    intc_1 // 0
+    itxn_field Fee
+    // tests/artifacts/dynamic_itxn_group/contract.py:61
+    // itxn.AssetConfig(asset_name="abc").stage()
+    itxn_next
+    bytec_1 // "abc"
+    itxn_field ConfigAssetName
+    pushint 3 // acfg
+    itxn_field TypeEnum
+    intc_1 // 0
+    itxn_field Fee
+    // tests/artifacts/dynamic_itxn_group/contract.py:63
+    // itxn.submit_staged()
+    itxn_submit
+    // tests/artifacts/dynamic_itxn_group/contract.py:38
+    // @arc4.abimethod
+    intc_0 // 1
+    return