feat: added the support for the include dups for tx receipt query (#1166) (#1186)

Signed-off-by: HusseinYasser <[email protected]>

Author: HusseinYasser

CHANGELOG.md

@@ -64,6 +64,7 @@ This changelog is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.
 - Added `coding_token_transactions.md` for a high level overview training on how token transactions are created in the python sdk.
 - Added prompt for codeRabbit on how to review /examples ([#1180](https://github.com/hiero-ledger/hiero-sdk-python/issues/1180)) 
 - Add Linked Issue Enforcer to automatically close PRs without linked issues `.github/workflows/bot-linked-issue-enforcer.yml`.
+- Added support for include duplicates in get transaction receipt query (#1166)
 
 ### Changed
 - Refactored `account_create_transaction_evm_alias.py` to improve readability by splitting the monolithic function into smaller helper functions. [#1017](https://github.com/hiero-ledger/hiero-sdk-python/issues/1017)

examples/query/transaction_get_receipt_query.py

@@ -62,22 +62,38 @@ def create_account(client, operator_key):
         sys.exit(1)
 
 
-def _print_receipt_with_children(queried_receipt):
+def _print_receipt_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(f"Child receipts count: {len(children)}")
+
     print("Child receipts:")
     for idx, child in enumerate(children, start=1):
         print(f"  {idx}. status={ResponseCode(child.status).name}")
 
 
+def _print_receipt_duplicates(queried_receipt):
+    """Pretty-print receipt status and any duplicate receipts."""
+
+    duplicates = queried_receipt.duplicates
+
+    if not duplicates:
+        print("No duplicate receipts returned (this can be normal depending on transaction type).")
+        return
+    
+    print(f"Duplicate receipts count: {len(duplicates)}")
+
+    print("Duplicate receipts:")
+    for idx, duplicate in enumerate(duplicates, start=1):
+        print(f"  {idx}. status={ResponseCode(duplicate.status).name}")
+
+
 def query_receipt():
     """
     A full example that include account creation, Hbar transfer, and receipt querying.
@@ -109,14 +125,20 @@ def query_receipt():
 
     # Query Transaction Receipt
     print("\nSTEP 3: Querying transaction receipt (include child receipts)...")
-    receipt_query = TransactionGetReceiptQuery().set_transaction_id(transaction_id).set_include_children(True)
+    receipt_query = (
+        TransactionGetReceiptQuery()
+        .set_transaction_id(transaction_id)
+        .set_include_children(True)
+        .set_include_duplicates(True)
+    )
     queried_receipt = receipt_query.execute(client)
     print(
         f"✅ Success! Queried transaction status: {ResponseCode(queried_receipt.status).name}"
     )
 
 
-    _print_receipt_with_children(queried_receipt)
+    _print_receipt_children(queried_receipt)
+    _print_receipt_duplicates(queried_receipt)
 
 if __name__ == "__main__":
     query_receipt()

src/hiero_sdk_python/query/transaction_get_receipt_query.py

@@ -1,11 +1,11 @@
 import traceback
-from typing import Optional, Union
+from typing import List, Optional, Union
 
 from hiero_sdk_python.channels import _Channel
 from hiero_sdk_python.client.client import Client
 from hiero_sdk_python.exceptions import PrecheckError, ReceiptStatusError
 from hiero_sdk_python.executable import _ExecutionState, _Method
-from hiero_sdk_python.hapi.services import query_header_pb2, query_pb2, response_pb2, transaction_get_receipt_pb2
+from hiero_sdk_python.hapi.services import query_header_pb2, query_pb2, response_pb2, transaction_get_receipt_pb2, transaction_receipt_pb2
 from hiero_sdk_python.query.query import Query
 from hiero_sdk_python.response_code import ResponseCode
 from hiero_sdk_python.transaction.transaction_id import TransactionId
@@ -28,17 +28,21 @@ def __init__(
         self,
         transaction_id: Optional[TransactionId] = None,
         include_children: bool = False,
+        include_duplicates: bool = False,
     ) -> None:
         """
         Initializes a new instance of the TransactionGetReceiptQuery class.
 
         Args:
             transaction_id (TransactionId, optional): The ID of the transaction.
+            include_children (bool): Whether to include child transaction receipts.
+            include_duplicates (bool): Whether to include duplicate transaction receipts.
         """
         super().__init__()
         self.transaction_id: Optional[TransactionId] = transaction_id
         self._frozen: bool = False
         self.include_children = include_children
+        self.include_duplicates = include_duplicates
 
     def _require_not_frozen(self) -> None:
         """
@@ -86,6 +90,25 @@ def set_include_children(
         self.include_children = include_children
         return self
 
+    def set_include_duplicates(
+        self, include_duplicates: bool
+    ) -> "TransactionGetReceiptQuery":
+        """
+        Sets include_duplicates for which to retrieve the duplicate transaction receipts.
+
+        Args:
+            include_duplicates: 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_duplicates = include_duplicates
+        return self
+
     def freeze(self) -> "TransactionGetReceiptQuery":
         """
         Marks the query as frozen, preventing further modification.
@@ -125,6 +148,7 @@ def _make_request(self) -> query_pb2.Query:
             transaction_get_receipt.transactionID.CopyFrom(self.transaction_id._to_proto())
 
             transaction_get_receipt.include_child_receipts = self.include_children
+            transaction_get_receipt.includeDuplicates = self.include_duplicates
 
             query = query_pb2.Query()
             if not hasattr(query, "transactionGetReceipt"):
@@ -223,6 +247,22 @@ def _map_status_error(self, response: response_pb2.Response) -> Union[PrecheckEr
             TransactionReceipt._from_proto(response.transactionGetReceipt.receipt, self.transaction_id),
         )
 
+    def _map_receipt_list(self, receipts:  List[transaction_receipt_pb2.TransactionReceipt]) -> List["TransactionReceipt"]:
+        """
+        Maps a list of protobuf transaction receipts to TransactionReceipt objects.
+
+        Args:
+            receipts: A list of protobuf TransactionReceipt objects
+
+        Returns:
+            A list of TransactionReceipt objects
+        """
+        return [
+            TransactionReceipt._from_proto(receipt_proto, self.transaction_id)
+            for receipt_proto in receipts
+        ]
+
+
     def execute(self, client: Client) -> TransactionReceipt:
         """
         Executes the transaction receipt query.
@@ -248,13 +288,18 @@ def execute(self, client: Client) -> TransactionReceipt:
         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)
+            children = self._map_receipt_list(
+                response.transactionGetReceipt.child_transaction_receipts
+            )
 
             parent._set_children(children)
+        
+        if self.include_duplicates:
+            duplicates = self._map_receipt_list(
+                response.transactionGetReceipt.duplicateTransactionReceipts
+            )
+
+            parent._set_duplicates(duplicates)
 
         return parent 
 

src/hiero_sdk_python/transaction/transaction_receipt.py

@@ -39,6 +39,7 @@ def __init__(
         receipt_proto: transaction_receipt_pb2.TransactionReceipt,
         transaction_id: Optional[TransactionId] = None,
         children: Optional[list["TransactionReceipt"]] = None,
+        duplicates: Optional[list["TransactionReceipt"]] = None,
     ) -> None:
         """
         Initializes the TransactionReceipt with the provided protobuf receipt.
@@ -51,6 +52,7 @@ def __init__(
         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 []
+        self._duplicates: list["TransactionReceipt"] = duplicates or []
 
     @property
     def token_id(self) -> Optional[TokenId]:
@@ -226,6 +228,25 @@ def _set_children(self, children: list["TransactionReceipt"]) -> None:
         """
         self._children = children
 
+    @property
+    def duplicates(self) -> list["TransactionReceipt"]:
+        """
+        Returns the duplicate transaction receipts associated with this receipt.
+
+        Returns:
+            list[TransactionReceipt]: Duplicate receipts (empty if not requested or none exist).
+        """
+        return self._duplicates
+    
+    def _set_duplicates(self, duplicates: list["TransactionReceipt"]) -> None:
+        """
+        Internal setter for duplicate receipts (used by receipt queries).
+
+        Args:
+            duplicates (list[TransactionReceipt]): Duplicate receipts.
+        """
+        self._duplicates = duplicates
+
     def _to_proto(self):
         """
         Returns the underlying protobuf transaction receipt.

…n_get_receipt_query_children_e2e_test.py …ransaction_get_receipt_query_e2e_test.pytests/integration/transaction_get_receipt_query_children_e2e_test.py renamed to tests/integration/transaction_get_receipt_query_e2e_test.py tests/integration/transaction_get_receipt_query_children_e2e_test.py renamed to tests/integration/transaction_get_receipt_query_e2e_test.py

@@ -1,18 +1,21 @@
 """
-E2E integration tests for TransactionGetReceiptQuery include_child_receipts support.
+E2E integration tests for TransactionGetReceiptQuery 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
+- verify duplicate transactions returned with include_duplicates 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.
 """
 
+from hiero_sdk_python.transaction.transaction_id import TransactionId
 import pytest
+import threading
 
 from hiero_sdk_python.hbar import Hbar
 from hiero_sdk_python.query.transaction_get_receipt_query import TransactionGetReceiptQuery
@@ -47,7 +50,7 @@ def _extract_tx_id(tx, receipt):
     )
 
 
-def _submit_simple_transfer(env):
+def _submit_simple_transfer(env, node_ids=None, tx_id=None):
     """
     Submit a simple transfer transaction and return its TransactionId.
     """
@@ -58,7 +61,10 @@ def _submit_simple_transfer(env):
         .add_hbar_transfer(env.operator_id, Hbar(-0.01).to_tinybars())
         .add_hbar_transfer(receiver.id, Hbar(0.01).to_tinybars())
     )
-
+    if tx_id is not None:
+        tx.set_transaction_id(tx_id)
+    if node_ids is not None:
+        tx.set_node_account_ids(node_ids)
     receipt = tx.execute(env.client)
     assert receipt.status == ResponseCode.SUCCESS
 
@@ -182,3 +188,34 @@ def test_get_receipt_query_children_with_contract_execute_e2e(env):
             assert child.status is not None
 
     assert isinstance(queried.children, list)
+
+@pytest.mark.integration
+@pytest.mark.xfail(reason="Flaky test due to network conditions causing no duplicates to be created. Python Virtual Threads compete too quickly.")
+def test_get_receipt_query_include_duplicates_execute_e2e(env):
+    """
+    E2E:
+    Execute a real contract transaction and query its receipt with include_duplicates enabled.
+
+    We assert:
+    - no crash
+    - receipt.duplicates exists and is a list
+    """
+    tx_id = TransactionId.generate(env.operator_id)
+    nodes = env.client.network.nodes
+    nodes = [nodes[0]._account_id, nodes[1]._account_id]
+    tx1 = threading.Thread(target=_submit_simple_transfer, args=(env, [nodes[0]], tx_id))
+    tx2 = threading.Thread(target=_submit_simple_transfer, args=(env, [nodes[1]], tx_id))
+    tx1.start()
+    tx2.start()
+    tx1.join()
+    tx2.join()
+    queried = (
+        TransactionGetReceiptQuery()
+        .set_transaction_id(tx_id)
+        .set_include_duplicates(True)
+        .execute(env.client)
+    )
+
+    assert queried.status == ResponseCode.SUCCESS
+    assert isinstance(queried.duplicates, list)
+    assert len(queried.duplicates) == 1