feat: Add support for include_children to TransactionRecordQuery (hiero-ledger#1959)

Signed-off-by: Antonio Ceppellini <antonio.ceppellini@gmail.com>

Author: AntonioCeppellini

CHANGELOG.md

@@ -8,6 +8,7 @@ This changelog is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.
 
 ### Added
 - Added CodeRabbit review instructions in `.coderabbit.yaml` for account module `src/hiero_sdk_python/account/`.
+- Add support for `include_children` to TransactionRecordQuery ([#1512](https://github.com/hiero-ledger/hiero-sdk-python/issues/1512))
 
 ### Changed
 - Changed pytest version to "pytest>=8.3.4,<10" (#1917)

examples/query/transaction_record_query_with_children.py

@@ -0,0 +1,94 @@
+"""
+Example demonstrating transaction record query with child records.
+
+To run the example run:
+- uv run examples/query/transaction_record_query_with_children.py
+- python examples/query/transaction_record_query_with_children.py
+"""
+
+import sys
+
+from hiero_sdk_python import (
+    AccountId,
+    Client,
+    Hbar,
+    PrivateKey,
+    ResponseCode,
+    TransactionRecordQuery,
+    TransferTransaction,
+)
+
+
+def submit_alias_auto_create_transfer(client):
+    """Transfer HBAR to a fresh EVM alias to trigger auto-account creation."""
+    try:
+        alias_key = PrivateKey.generate_ecdsa()
+        alias_account_id = AccountId.from_evm_address(
+            alias_key.public_key().to_evm_address(), 0, 0
+        )
+
+        transaction = (
+            TransferTransaction()
+            .add_hbar_transfer(alias_account_id, Hbar(1).to_tinybars())
+            .add_hbar_transfer(client.operator_account_id, Hbar(-1).to_tinybars())
+        )
+        receipt = transaction.execute(client)
+
+        return transaction.transaction_id
+    except Exception as e:
+        print(f"Error submitting alias auto-create transfer: {e}")
+        sys.exit(1)
+
+
+def print_transaction_record(record, title):
+    """Print a full transaction record, including child details."""
+    print(f"\n{title}")
+    print(f"Transaction ID: {record.transaction_id}")
+    print(f"Transaction Fee: {record.transaction_fee}")
+    print(f"Transaction Hash: {record.transaction_hash.hex()}")
+    print(f"Transaction Memo: {record.transaction_memo}")
+    print(f"Receipt Status: {ResponseCode(record.receipt.status).name}")
+    print(f"Receipt Account ID: {record.receipt.account_id}")
+    print(f"Children: {record.children}")
+    print(f"Duplicates Count: {len(record.duplicates)}")
+
+
+def print_child_records(record):
+    """Print all child transaction records in detail."""
+    print(f"\nChild records count: {len(record.children)}")
+
+    if not record.children:
+        sys.exit(1)
+
+    print_transaction_record(record.children[0], f"Child record")
+
+
+def main():
+    try:
+        client = Client.from_env()
+
+        print(
+            "\nSTEP 1: Create a parent transaction with child records"
+        )
+        transaction_id = submit_alias_auto_create_transfer(client)
+        print(f"Parent transaction ID: {transaction_id}")
+
+        print(
+            "\nSTEP 2: Querying parent transaction record with include_children=True..."
+        )
+        record = (
+            TransactionRecordQuery()
+            .set_transaction_id(transaction_id)
+            .set_include_children(True)
+            .execute(client)
+        )
+
+        print_transaction_record(record, "Parent Transaction Record")
+        print_child_records(record)
+    except Exception as e:
+        print(f"Error running example: {e}")
+        sys.exit(1)
+
+
+if __name__ == "__main__":
+    main()

src/hiero_sdk_python/query/transaction_record_query.py

@@ -25,23 +25,35 @@ class TransactionRecordQuery(Query):
     def __init__(
         self,
         transaction_id: Optional[TransactionId] = None,
+        include_children: bool = False,
         include_duplicates: bool = False,
     ) -> None:
         """
         Initializes the TransactionRecordQuery with the provided transaction ID.
+
+        Args:
+            transaction_id (TransactionId, optional): The ID of the transaction.
+            include_children (bool): Whether to include child transaction records.
+            include_duplicates (bool): Whether to include duplicate transaction records.
         """
         super().__init__()
         if not isinstance(include_duplicates, bool):
             raise TypeError(
                 f"include_duplicates must be a bool (True or False), got {type(include_duplicates).__name__}"
             )
-        
+
         if transaction_id is not None and not isinstance(transaction_id, TransactionId):
             raise TypeError(
                 f"transaction_id must be TransactionId or None, got {type(transaction_id).__name__}"
             )
 
+        if not isinstance(include_children, bool):
+            raise TypeError(
+                f"include_children must be a bool (True or False), got {type(include_children).__name__}"
+            )
+
         self.transaction_id: Optional[TransactionId] = transaction_id
+        self.include_children: bool = bool(include_children)
         self.include_duplicates: bool = bool(include_duplicates)
 
     def set_include_duplicates(
@@ -57,10 +69,12 @@ def set_include_duplicates(
             TransactionRecordQuery: The current instance for method chaining.
         """
         if not isinstance(include_duplicates, bool):
-            raise TypeError(f"include_duplicates must be a boolean, got {type(include_duplicates).__name__}")
+            raise TypeError(
+                f"include_duplicates must be a boolean, got {type(include_duplicates).__name__}"
+            )
         self.include_duplicates = include_duplicates
         return self
-    
+
     def set_transaction_id(
         self,
         transaction_id: Optional[TransactionId],
@@ -76,7 +90,7 @@ def set_transaction_id(
         Returns:
             TransactionRecordQuery: This query instance for chaining.
         """
-        
+
         if transaction_id is not None and not isinstance(transaction_id, TransactionId):
             raise TypeError(
                 f"transaction_id must be TransactionId or None, got {type(transaction_id).__name__}"
@@ -85,6 +99,24 @@ def set_transaction_id(
         self.transaction_id = transaction_id
         return self
 
+    def set_include_children(self, include_children: bool) -> "TransactionRecordQuery":
+        """
+        Sets include_children for which to retrieve the child transaction records.
+
+        Args:
+            include_children: bool.
+
+        Returns:
+            TransactionRecordQuery: The current instance for method chaining.
+        """
+        if not isinstance(include_children, bool):
+            raise TypeError(
+                f"include_children must be a boolean, got {type(include_children).__name__}"
+            )
+
+        self.include_children = include_children
+        return self
+
     def _make_request(self):
         """
         Constructs the protobuf request for the transaction record query.
@@ -108,6 +140,7 @@ def _make_request(self):
         transaction_get_record.header.CopyFrom(query_header)
         transaction_get_record.transactionID.CopyFrom(self.transaction_id._to_proto())
         transaction_get_record.includeDuplicates = self.include_duplicates
+        transaction_get_record.include_child_records = self.include_children
 
         query = query_pb2.Query()
         query.transactionGetRecord.CopyFrom(transaction_get_record)
@@ -236,9 +269,13 @@ def _map_status_error(
             return PrecheckError(status)
 
         receipt = response.transactionGetRecord.transactionRecord.receipt
-        
-        return ReceiptStatusError(status, self.transaction_id, TransactionReceipt._from_proto(receipt, self.transaction_id))
-        
+
+        return ReceiptStatusError(
+            status,
+            self.transaction_id,
+            TransactionReceipt._from_proto(receipt, self.transaction_id),
+        )
+
     def execute(self, client: Client, timeout: Optional[Union[int, float]] = None):
         """
         Executes the transaction record query.
@@ -263,14 +300,24 @@ def execute(self, client: Client, timeout: Optional[Union[int, float]] = None):
         self._before_execute(client)
         response = self._execute(client, timeout)
         primary_proto = response.transactionGetRecord.transactionRecord
+        children = []
         if self.include_duplicates:
             duplicates = self._map_record_list(
                 response.transactionGetRecord.duplicateTransactionRecords
             )
         else:
             duplicates = []
+
+        if self.include_children:
+            children = self._map_record_list(
+                response.transactionGetRecord.child_transaction_records
+            )
+
         return TransactionRecord._from_proto(
-            primary_proto, transaction_id=self.transaction_id, duplicates=duplicates
+            primary_proto,
+            transaction_id=self.transaction_id,
+            duplicates=duplicates,
+            children=children,
         )
 
     def _get_query_response(self, response: Any):

src/hiero_sdk_python/transaction/transaction_record.py

@@ -58,6 +58,9 @@ class TransactionRecord:
         prng_bytes (Optional[bytes]):                     A pseudo-random byte array generated by the network (if applicable).
         duplicates (list[TransactionRecord]):             A list of duplicate transaction records returned when queried
                                                           with include_duplicates=True. Empty by default.
+
+        children (list[TransactionRecord]):               A list of children transaction records returned when queried
+                                                          with include_children=True. Empty by default.
     """
 
     transaction_id: Optional[TransactionId] = None
@@ -75,6 +78,7 @@ class TransactionRecord:
     prng_number: Optional[int] = None
     prng_bytes: Optional[bytes] = None
     duplicates: list['TransactionRecord'] = field(default_factory=list)
+    children: list['TransactionRecord'] = field(default_factory=list)
 
     def __repr__(self) -> str:
         """Returns a human-readable string representation of the TransactionRecord.
@@ -107,14 +111,16 @@ def __repr__(self) -> str:
                 f"call_result={self.call_result}, "
                 f"prng_number={self.prng_number}, "
                 f"prng_bytes={self.prng_bytes}, "
-                f"duplicates_count={len(self.duplicates)})")
+                f"duplicates_count={len(self.duplicates)}, "
+                f"children_count={len(self.children)})")
 
     @classmethod
     def _from_proto(
         cls,
         proto: transaction_record_pb2.TransactionRecord,
         transaction_id: Optional[TransactionId] = None,
         duplicates: Optional[list['TransactionRecord']] = None,
+        children: Optional[list['TransactionRecord']] = None,
     ) -> 'TransactionRecord':
         """Creates a TransactionRecord instance from a protobuf transaction record.
 
@@ -136,12 +142,15 @@ def _from_proto(
             transaction_id: The transaction ID to associate with this record (required).
             duplicates: Optional list of duplicate transaction records to attach.
                         Defaults to an empty list.
+            children: Optional list of child transaction records to attach.
+                      Defaults to an empty list.
 
         Returns:
             TransactionRecord: A new instance containing all processed and structured data.
         """
         tx_id = cls._resolve_transaction_id(proto, transaction_id)
         duplicates = duplicates or []
+        children = children or []
 
         token_transfers, nft_transfers = cls._parse_token_transfers(proto)
         transfers = cls._parse_hbar_transfers(proto)
@@ -162,6 +171,7 @@ def _from_proto(
             prng_number=proto.prng_number,
             prng_bytes=proto.prng_bytes,
             duplicates=duplicates,
+            children=children,
         )
 
     @staticmethod
@@ -294,4 +304,4 @@ def _to_proto(self) -> transaction_record_pb2.TransactionRecord:
             record_proto.new_pending_airdrops.add().CopyFrom(pending_airdrop._to_proto())
 
         return record_proto
-    
+    

tests/integration/transaction_record_query_e2e_test.py

@@ -1,6 +1,6 @@
 import pytest
 import os
-from hiero_sdk_python import Client, TransactionRecord
+from hiero_sdk_python import AccountId, Client, TransactionRecord
 from hiero_sdk_python.crypto.private_key import PrivateKey
 from hiero_sdk_python.hbar import Hbar
 from hiero_sdk_python.account.account_create_transaction import AccountCreateTransaction
@@ -16,9 +16,29 @@
     IntegrationTestEnv,
     create_fungible_token,
     create_nft_token,
+    env,
 )
 
 
+def _submit_alias_auto_create_transfer(env: IntegrationTestEnv):
+    """Submit a transfer to an EVM alias to trigger child auto-account creation."""
+    alias_key = PrivateKey.generate_ecdsa()
+    alias_account_id = AccountId.from_evm_address(
+        alias_key.public_key().to_evm_address(), 0, 0
+    )
+
+    transaction = (
+        TransferTransaction()
+        .add_hbar_transfer(alias_account_id, Hbar(1).to_tinybars())
+        .add_hbar_transfer(env.operator_id, Hbar(-1).to_tinybars())
+    )
+    receipt = transaction.execute(env.client)
+
+    assert receipt.status == ResponseCode.SUCCESS
+
+    return transaction.transaction_id
+
+
 @pytest.mark.integration
 def test_transaction_record_query_can_execute():
     env = IntegrationTestEnv()
@@ -54,6 +74,40 @@ def test_transaction_record_query_can_execute():
         env.close()
 
 
+@pytest.mark.integration
+def test_transaction_record_query_include_children_returns_child_records(env):
+    """Querying an alias auto-create parent record should return parsed child records."""
+    parent_transaction_id = _submit_alias_auto_create_transfer(env)
+    parent_account_id = parent_transaction_id.account_id
+
+    parent_record = (
+        TransactionRecordQuery()
+        .set_transaction_id(parent_transaction_id)
+        .set_include_children(True)
+        .execute(env.client)
+    )
+
+    assert parent_record.transaction_id == parent_transaction_id
+    assert parent_record.receipt.status == ResponseCode.SUCCESS
+    assert len(parent_record.children) > 0
+    assert parent_record.transfers[parent_account_id] < 0
+
+    child_record = parent_record.children[0]
+    created_account_id = child_record.receipt.account_id
+
+    assert isinstance(child_record, TransactionRecord)
+    assert child_record.receipt.status == ResponseCode.SUCCESS
+    assert child_record.transaction_id == parent_transaction_id
+    assert created_account_id is not None
+    assert created_account_id.shard == 0
+    assert created_account_id.realm == 0
+    assert created_account_id.num > 0
+    assert child_record.transaction_hash != parent_record.transaction_hash
+    assert child_record.transaction_memo == ""
+    assert child_record.children == []
+    assert child_record.duplicates == []
+
+
 @pytest.mark.integration
 def test_transaction_record_query_can_execute_nft_transfer():
     env = IntegrationTestEnv()
@@ -274,4 +328,4 @@ def test_query_with_include_duplicates():
         # print(f"Found {len(record.duplicates)} duplicates")  # for debug
     finally:
         env.close()
-        
+