feat: Add support for include_children in TransactionGetReceiptQuery (#1114)

Signed-off-by: Antonio Ceppellini <[email protected]>
Signed-off-by: AntonioCeppellini <[email protected]>

Author: AntonioCeppellini

CHANGELOG.md

@@ -46,6 +46,7 @@ This changelog is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.
 - Enhanced `.github/ISSUE_TEMPLATE/01_good_first_issue.yml` with welcoming message and acceptance criteria sections to guide contributors in creating quality GFIs (#1052)
 - Add workflow to notify team about P0 issues `bot-p0-issues-notify-team.yml`
 - Added Issue Reminder (no-PR) bot, .github/scripts/issue_reminder_no_pr.sh and .github/workflows/bot-issue-reminder-no-pr.yml to automatically detect assigned issues with no linked pull requests for 7+ days and post a gentle ReminderBot comment.(#951)
+- Add support for include_children in TransactionGetReceiptQuery (#1100)(https://github.com/hiero-ledger/hiero-sdk-python/issues/1100)
 - Add new `.github/ISSUE_TEMPLATE/05_intermediate_issue.yml` file (1072)(https://github.com/hiero-ledger/hiero-sdk-python/issues/1072)
 - Add a workflow to notify the team when issues are labeled as “good first issues” or identified as candidates for that label: `bot-gfi-notify-team.yml`(#1115)
 

examples/query/transaction_get_receipt_query.py

@@ -62,9 +62,26 @@ def create_account(client, operator_key):
         sys.exit(1)
 
 
+def _print_receipt_with_children(queried_receipt):
+    """Pretty-print receipt status and any child receipts."""
+    print(f"✅ Queried transaction status: {ResponseCode(queried_receipt.status).name}")
+
+    children = queried_receipt.children
+    print(f"Child receipts count: {len(children)}")
+
+    if not children:
+        print("No child receipts returned (this can be normal depending on transaction type).")
+        return
+
+    print("Child receipts:")
+    for idx, child in enumerate(children, start=1):
+        print(f"  {idx}. status={ResponseCode(child.status).name}")
+
+
 def query_receipt():
     """
-    A full example that include account creation, Hbar transfer, and receipt querying
+    A full example that include account creation, Hbar transfer, and receipt querying.
+    Demonstrates include_child_receipts support (SDK API: set_include_children).
     """
     # Config Client
     client, operator_id, operator_key = setup_client()
@@ -80,7 +97,7 @@ def query_receipt():
         .add_hbar_transfer(operator_id, -Hbar(amount).to_tinybars())
         .add_hbar_transfer(recipient_id, Hbar(amount).to_tinybars())
         .freeze_with(client)
-        .sign(operator_key)
+       .sign(operator_key)
     )
 
     receipt = transaction.execute(client)
@@ -91,13 +108,15 @@ def query_receipt():
     )
 
     # Query Transaction Receipt
-    print("\nSTEP 3: Querying transaction receipt...")
-    receipt_query = TransactionGetReceiptQuery().set_transaction_id(transaction_id)
+    print("\nSTEP 3: Querying transaction receipt (include child receipts)...")
+    receipt_query = TransactionGetReceiptQuery().set_transaction_id(transaction_id).set_include_children(True)
     queried_receipt = receipt_query.execute(client)
     print(
         f"✅ Success! Queried transaction status: {ResponseCode(queried_receipt.status).name}"
     )
 
 
+    _print_receipt_with_children(queried_receipt)
+
 if __name__ == "__main__":
     query_receipt()

src/hiero_sdk_python/query/transaction_get_receipt_query.py

@@ -24,7 +24,11 @@ class TransactionGetReceiptQuery(Query):
 
     """
 
-    def __init__(self, transaction_id: Optional[TransactionId] = None) -> None:
+    def __init__(
+        self,
+        transaction_id: Optional[TransactionId] = None,
+        include_children: bool = False,
+    ) -> None:
         """
         Initializes a new instance of the TransactionGetReceiptQuery class.
 
@@ -34,6 +38,7 @@ def __init__(self, transaction_id: Optional[TransactionId] = None) -> None:
         super().__init__()
         self.transaction_id: Optional[TransactionId] = transaction_id
         self._frozen: bool = False
+        self.include_children = include_children
 
     def _require_not_frozen(self) -> None:
         """
@@ -62,6 +67,25 @@ def set_transaction_id(self, transaction_id: TransactionId) -> "TransactionGetRe
         self.transaction_id = transaction_id
         return self
 
+    def set_include_children(
+        self, include_children: bool
+    ) -> "TransactionGetReceiptQuery":
+        """
+        Sets include_children for which to retrieve the child transaction receipts.
+
+        Args:
+            include_children: bool.
+
+        Returns:
+            TransactionGetReceiptQuery: The current instance for method chaining.
+
+        Raises:
+            ValueError: If the query is frozen and cannot be modified.
+        """
+        self._require_not_frozen()
+        self.include_children = include_children
+        return self
+
     def freeze(self) -> "TransactionGetReceiptQuery":
         """
         Marks the query as frozen, preventing further modification.
@@ -100,6 +124,8 @@ def _make_request(self) -> query_pb2.Query:
             transaction_get_receipt.header.CopyFrom(query_header)
             transaction_get_receipt.transactionID.CopyFrom(self.transaction_id._to_proto())
 
+            transaction_get_receipt.include_child_receipts = self.include_children
+
             query = query_pb2.Query()
             if not hasattr(query, "transactionGetReceipt"):
                 raise AttributeError("Query object has no attribute 'transactionGetReceipt'")
@@ -219,8 +245,18 @@ def execute(self, client: Client) -> TransactionReceipt:
         """
         self._before_execute(client)
         response = self._execute(client)
+        parent = TransactionReceipt._from_proto(response.transactionGetReceipt.receipt, self.transaction_id)
+
+        if self.include_children:
+            children = []
+
+            for child_proto in response.transactionGetReceipt.child_transaction_receipts:
+                child_receipt = TransactionReceipt._from_proto(child_proto, self.transaction_id)
+                children.append(child_receipt)
+
+            parent._set_children(children)
 
-        return TransactionReceipt._from_proto(response.transactionGetReceipt.receipt, self.transaction_id)
+        return parent 
 
     def _get_query_response(
         self, response: response_pb2.Response

src/hiero_sdk_python/transaction/transaction_receipt.py

@@ -16,8 +16,6 @@
 from hiero_sdk_python.contract.contract_id import ContractId
 from hiero_sdk_python.schedule.schedule_id import ScheduleId
 from hiero_sdk_python.tokens.token_id import TokenId
-from hiero_sdk_python.transaction.transaction_id import TransactionId
-
 from hiero_sdk_python.transaction.transaction_id import TransactionId
 from hiero_sdk_python.hapi.services import transaction_receipt_pb2, response_code_pb2
 from hiero_sdk_python.account.account_id import AccountId
@@ -39,7 +37,8 @@ class TransactionReceipt:
     def __init__(
         self,
         receipt_proto: transaction_receipt_pb2.TransactionReceipt,
-        transaction_id: Optional[TransactionId] = None
+        transaction_id: Optional[TransactionId] = None,
+        children: Optional[list["TransactionReceipt"]] = None,
     ) -> None:
         """
         Initializes the TransactionReceipt with the provided protobuf receipt.
@@ -51,6 +50,7 @@ def __init__(
         self._transaction_id: Optional[TransactionId] = transaction_id
         self.status: Optional[response_code_pb2.ResponseCodeEnum] = receipt_proto.status
         self._receipt_proto: transaction_receipt_pb2.TransactionReceipt = receipt_proto
+        self._children: list["TransactionReceipt"] = children or []
 
     @property
     def token_id(self) -> Optional[TokenId]:
@@ -183,7 +183,7 @@ def node_id(self):
             int: The node ID if present; otherwise, 0.
         """
         return self._receipt_proto.node_id
-    
+
     @property
     def topic_sequence_number(self) -> int:
         """
@@ -207,6 +207,25 @@ def topic_running_hash(self) -> Optional[bytes]:
 
         return None
 
+    @property
+    def children(self) -> list["TransactionReceipt"]:
+        """
+        Returns the child transaction receipts associated with this receipt.
+
+        Returns:
+            list[TransactionReceipt]: Child receipts (empty if not requested or none exist).
+        """
+        return self._children
+
+    def _set_children(self, children: list["TransactionReceipt"]) -> None:
+        """
+        Internal setter for child receipts (used by receipt queries).
+
+        Args:
+            children (list[TransactionReceipt]): Child receipts.
+        """
+        self._children = children
+
     def _to_proto(self):
         """
         Returns the underlying protobuf transaction receipt.

tests/integration/transaction_get_receipt_query_children_e2e_test.py

@@ -0,0 +1,184 @@
+"""
+E2E integration tests for TransactionGetReceiptQuery include_child_receipts support.
+
+These tests validate the full SDK flow against a real Hedera network:
+- submit a real transaction
+- query its receipt
+- verify children behavior with and without include_children flag
+
+NOTE:
+The contract used in these tests (StatefulContract) does NOT deterministically
+produce child receipts, so we only assert API correctness and stability,
+not children count > 0.
+"""
+
+import pytest
+
+from hiero_sdk_python.hbar import Hbar
+from hiero_sdk_python.query.transaction_get_receipt_query import TransactionGetReceiptQuery
+from hiero_sdk_python.response_code import ResponseCode
+from hiero_sdk_python.transaction.transfer_transaction import TransferTransaction
+
+from tests.integration.utils import env
+
+
+def _extract_tx_id(tx, receipt):
+    """
+    Best-effort extraction of TransactionId for E2E tests.
+    """
+    tx_id = getattr(receipt, "transaction_id", None)
+    if tx_id is not None:
+        return tx_id
+
+    tx_id = getattr(tx, "transaction_id", None)
+    if tx_id is not None:
+        return tx_id
+
+    tx_id = getattr(tx, "_transaction_id", None)
+    if tx_id is not None:
+        return tx_id
+
+    tx_ids = getattr(tx, "_transaction_ids", None)
+    if tx_ids:
+        return tx_ids[0]
+
+    raise AssertionError(
+        "Unable to extract TransactionId from transaction or receipt."
+    )
+
+
+def _submit_simple_transfer(env):
+    """
+    Submit a simple transfer transaction and return its TransactionId.
+    """
+    receiver = env.create_account(initial_hbar=0.0)
+
+    tx = (
+        TransferTransaction()
+        .add_hbar_transfer(env.operator_id, Hbar(-0.01).to_tinybars())
+        .add_hbar_transfer(receiver.id, Hbar(0.01).to_tinybars())
+    )
+
+    receipt = tx.execute(env.client)
+    assert receipt.status == ResponseCode.SUCCESS
+
+    return _extract_tx_id(tx, receipt)
+
+
+@pytest.mark.integration
+def test_get_receipt_query_children_empty_when_not_requested_e2e(env):
+    """
+    E2E:
+    When include_children is NOT requested, receipt.children must be empty.
+    """
+    tx_id = _submit_simple_transfer(env)
+
+    receipt = (
+        TransactionGetReceiptQuery()
+        .set_transaction_id(tx_id)
+        .execute(env.client)
+    )
+
+    assert receipt.status == ResponseCode.SUCCESS
+    assert receipt.children == []
+
+
+@pytest.mark.integration
+def test_get_receipt_query_children_list_when_requested_e2e(env):
+    """
+    E2E:
+    When include_children IS requested, receipt.children must exist and be a list.
+    The list may be empty depending on transaction type.
+    """
+    tx_id = _submit_simple_transfer(env)
+
+    receipt = (
+        TransactionGetReceiptQuery()
+        .set_transaction_id(tx_id)
+        .set_include_children(True)
+        .execute(env.client)
+    )
+
+    assert receipt.status == ResponseCode.SUCCESS
+    assert isinstance(receipt.children, list)
+
+
+@pytest.mark.integration
+def test_get_receipt_query_children_with_contract_execute_e2e(env):
+    """
+    E2E:
+    Execute a real contract transaction and query its receipt with include_children enabled.
+
+    We assert:
+    - no crash
+    - receipt.children exists and is a list
+    """
+    from examples.contract.contracts.contract_utils import (
+        CONTRACT_DEPLOY_GAS,
+        STATEFUL_CONTRACT_BYTECODE,
+    )
+    from hiero_sdk_python.file.file_create_transaction import FileCreateTransaction
+    from hiero_sdk_python.contract.contract_create_transaction import ContractCreateTransaction
+    from hiero_sdk_python.contract.contract_execute_transaction import ContractExecuteTransaction
+    from hiero_sdk_python.contract.contract_function_parameters import ContractFunctionParameters
+
+    # Upload contract bytecode
+    file_receipt = (
+        FileCreateTransaction()
+        .set_keys(env.operator_key.public_key())
+        .set_contents(STATEFUL_CONTRACT_BYTECODE)
+        .set_file_memo("transaction receipt children test")
+        .execute(env.client)
+    )
+    assert file_receipt.status == ResponseCode.SUCCESS
+    file_id = file_receipt.file_id
+    assert file_id is not None
+
+    # Deploy contract
+    constructor_params = ContractFunctionParameters().add_bytes32(
+        b"Initial message from constructor"
+    )
+    contract_receipt = (
+        ContractCreateTransaction()
+        .set_admin_key(env.operator_key.public_key())
+        .set_gas(CONTRACT_DEPLOY_GAS)
+        .set_constructor_parameters(constructor_params)
+        .set_bytecode_file_id(file_id)
+        .execute(env.client)
+    )
+    assert contract_receipt.status == ResponseCode.SUCCESS
+    contract_id = contract_receipt.contract_id
+    assert contract_id is not None
+
+    # Execute contract function
+    execute_tx = (
+        ContractExecuteTransaction()
+        .set_contract_id(contract_id)
+        .set_gas(1_000_000)
+        .set_function(
+            "setMessage",
+            ContractFunctionParameters().add_bytes32(b"Updated message".ljust(32, b"\x00")),
+        )
+    )
+    execute_receipt = execute_tx.execute(env.client)
+    assert execute_receipt.status == ResponseCode.SUCCESS
+
+    try:
+        tx_id = _extract_tx_id(execute_tx, execute_receipt)
+    except AssertionError as e:
+        pytest.skip(str(e))
+
+    queried = (
+        TransactionGetReceiptQuery()
+        .set_transaction_id(tx_id)
+        .set_include_children(True)
+        .execute(env.client)
+    )
+
+    assert queried.status == ResponseCode.SUCCESS
+
+    if len(queried.children) > 0:
+        for child in queried.children:
+            assert child.status is not None
+
+    assert isinstance(queried.children, list)