Merge branch 'main' into update-file-handler

Author: anchit-goel

src/hiero_sdk_python/client/client.py

@@ -66,6 +66,8 @@ def __init__(self, network: Network = None) -> None:
         self._grpc_deadline: float = DEFAULT_GRPC_DEADLINE
         self._request_timeout: float = DEFAULT_REQUEST_TIMEOUT
 
+        self._allow_receipt_node_failover: bool = False
+
         self.logger: Logger = Logger(LogLevel.from_env(), "hiero_sdk_python")
 
     @property
@@ -424,6 +426,33 @@ def update_network(self) -> Client:
         self.network._set_network_nodes()
         return self
 
+    @property
+    def allow_receipt_node_failover(self) -> bool:
+        """
+        Return whether receipt and record queries can fail over to other nodes.
+        """
+        return self._allow_receipt_node_failover
+
+    def set_allow_receipt_node_failover(self, allow: bool) -> Client:
+        """
+        Enable or disable receipt and record query node failover.
+
+        Args:
+            allow (bool): Whether to allow receipt/record queries to fail over to
+                other nodes when the submitting node is unavailable.
+
+        Returns:
+            Client: This client instance for fluent chaining.
+
+        Raises:
+            TypeError: If allow is not a bool.
+        """
+        if not isinstance(allow, bool):
+            raise TypeError("allow must be an instance of bool")
+
+        self._allow_receipt_node_failover = allow
+        return self
+
     def __enter__(self) -> Client:
         """
         Allows the Client to be used in a 'with' statement for automatic resource management.

src/hiero_sdk_python/executable.py

@@ -382,7 +382,7 @@ def _calculate_backoff(self, attempt: int):
     def _handle_unhealthy_node(self, proto_request, attempt, logger, err) -> bool:
         """Handle node switching and backoff for unhealthy node."""
         # Check if the request is a transaction receipt or record because they are single node requests
-        if _is_transaction_receipt_or_record_request(proto_request):
+        if _is_transaction_receipt_or_record_request(proto_request) and len(self._node_account_ids) <= 1:
             _delay_for_attempt(
                 self._get_request_id(),
                 self._min_backoff,

src/hiero_sdk_python/transaction/transaction.py

@@ -109,6 +109,7 @@ def _map_response(self, response, node_id, proto_request):  # noqa: ARG002
         transaction_response.transaction_id = self.transaction_id
         transaction_response.node_id = node_id
         transaction_response.hash = tx_hash
+        transaction_response._transaction_node_ids = self._node_account_ids.get_list()
 
         return transaction_response
 
@@ -364,6 +365,18 @@ def execute(
         if self.batch_key and not isinstance(self, (BatchTransaction)):
             raise ValueError("Cannot execute batchified transaction outside of BatchTransaction.")
 
+        if timeout is not None and (isinstance(timeout, bool) or not isinstance(timeout, (int, float))):
+            raise TypeError("timeout must be a int or float")
+
+        if not isinstance(validate_status, bool):
+            raise TypeError("validate_status must be a boolean")
+
+        if not isinstance(wait_for_receipt, bool):
+            raise TypeError("wait_for_receipt must be a boolean")
+
+        if not isinstance(client, Client):
+            raise TypeError("client must be an instance of Client")
+
         if not self._transaction_body_bytes:
             self.freeze_with(client)
 
@@ -374,7 +387,7 @@ def execute(
             self.sign(client.operator_private_key)
 
         # Call the _execute function from executable.py to handle the actual execution
-        response = self._execute(client, timeout)
+        response: TransactionResponse = self._execute(client, timeout)
 
         response.validate_status = True
         response.transaction = self

src/hiero_sdk_python/transaction/transaction_response.py

@@ -33,23 +33,35 @@ def __init__(self) -> None:
         self.hash: bytes = b""
         self.validate_status: bool = False
         self.transaction: Transaction | None = None
+        self._transaction_node_ids: list[AccountId] | None = None
 
-    def get_receipt_query(self, validate_status: bool = False):
+    def get_receipt_query(self, validate_status: bool = False, client: Client | None = None):
         """
         Create a receipt query for this transaction.
 
         Args:
             validate_status (bool, optional): The query should automatically validate the transaction status. (default False)
+            client (Client, optional): The client to enable failover behavior.
 
         Returns:
             TransactionGetReceiptQuery: A configured receipt query.
+
+        Raises:
+            TypeError: If `validate_status` is not a bool or `client` is not a Client.
         """
         from hiero_sdk_python.query.transaction_get_receipt_query import TransactionGetReceiptQuery
 
+        if not isinstance(validate_status, bool):
+            raise TypeError("validate_status must be a boolean")
+
+        if client is not None and not isinstance(client, Client):
+            raise TypeError("client must be an instance of Client")
+
+        node_account_ids = self._resolve_node_account_ids(client)
         return (
             TransactionGetReceiptQuery()
             .set_transaction_id(self.transaction_id)
-            .set_node_account_ids([self.node_id])
+            .set_node_account_ids(node_account_ids)
             .set_validate_status(validate_status)
         )
 
@@ -68,18 +80,28 @@ def get_receipt(
             TransactionReceipt: The receipt from the network, containing the status
                                and any entities created by the transaction
         """
-        return self.get_receipt_query(validate_status=validate_status).execute(client, timeout)
+        return self.get_receipt_query(validate_status=validate_status, client=client).execute(client, timeout)
 
-    def get_record_query(self):
+    def get_record_query(self, client: Client | None = None):
         """
         Create a record query for this transaction.
 
+        Args:
+            client (Client, optional): The client to enable failover behavior.
+
         Returns:
             TransactionRecordQuery: A configured record query.
+
+        Raises:
+            TypeError: If `client` is not a Client.
         """
         from hiero_sdk_python.query.transaction_record_query import TransactionRecordQuery
 
-        return TransactionRecordQuery().set_transaction_id(self.transaction_id).set_node_account_ids([self.node_id])
+        if client is not None and not isinstance(client, Client):
+            raise TypeError("client must be an instance of Client")
+
+        node_account_ids = self._resolve_node_account_ids(client)
+        return TransactionRecordQuery().set_transaction_id(self.transaction_id).set_node_account_ids(node_account_ids)
 
     def get_record(self, client: Client, timeout: int | float | None = None) -> TransactionRecord:
         """
@@ -92,4 +114,15 @@ def get_record(self, client: Client, timeout: int | float | None = None) -> Tran
         Returns:
             TransactionRecord: The full transaction record.
         """
-        return self.get_record_query().execute(client, timeout)
+        return self.get_record_query(client).execute(client, timeout)
+
+    def _resolve_node_account_ids(self, client: Client) -> list[AccountId]:
+        """Resolve node account IDs for receipt or record query failover."""
+        node_account_ids = [self.node_id]
+
+        if client is None or not client.allow_receipt_node_failover:
+            return node_account_ids
+
+        available_node_ids = self._transaction_node_ids if self._transaction_node_ids else client.get_node_account_ids()
+        node_account_ids.extend(node_id for node_id in available_node_ids if node_id != self.node_id)
+        return node_account_ids

tests/integration/transaction_e2e_test.py

@@ -258,3 +258,41 @@ def test_get_receipt_raises_exception_on_failure_with_validation(env):
         response.get_receipt(env.client, validate_status=True)
 
     assert e.value.status == ResponseCode.INVALID_ACCOUNT_ID
+
+
+@pytest.mark.integration
+def test_get_receipt_with_allow_failover(env):
+    """Test that a transaction receipt can be retrieved with node failover enabled."""
+    env.client.set_allow_receipt_node_failover(True)
+
+    tx = AccountCreateTransaction().set_key_without_alias(PrivateKey.generate_ecdsa())
+    response = tx.execute(env.client, wait_for_receipt=False)
+
+    assert response is not None
+
+    receipt = response.get_receipt(env.client)
+    assert receipt is not None
+    assert receipt.account_id is not None
+
+    AccountDeleteTransaction().set_transfer_account_id(env.operator_id).set_account_id(receipt.account_id).execute(
+        env.client
+    )
+
+
+@pytest.mark.integration
+def test_get_record_with_allow_failover(env):
+    """Test that a transaction record can be retrieved with node failover enabled."""
+    env.client.set_allow_receipt_node_failover(True)
+
+    tx = AccountCreateTransaction().set_key_without_alias(PrivateKey.generate_ecdsa())
+    response = tx.execute(env.client, wait_for_receipt=False)
+
+    assert response is not None
+
+    record = response.get_record(env.client)
+    assert record is not None
+    assert record.receipt.account_id is not None
+
+    AccountDeleteTransaction().set_transfer_account_id(env.operator_id).set_account_id(
+        record.receipt.account_id
+    ).execute(env.client)

tests/unit/client_test.py

@@ -604,3 +604,22 @@ def test_for_network_invalid_shard_realm_raises_error(invalid_map, error_msg):
     """Test that for_network catches mismatched shards or realms."""
     with pytest.raises(ValueError, match=error_msg):
         Client.for_network(invalid_map)
+
+
+def test_set_receipt_failover_set_values():
+    """Test that receipt failover is set to the provided value."""
+    client = Client.for_testnet()
+    # default
+    assert client.allow_receipt_node_failover is False
+
+    return_value = client.set_allow_receipt_node_failover(True)
+    assert client.allow_receipt_node_failover is True
+    assert return_value is client
+
+
+@pytest.mark.parametrize("allow", ["true", 1, 0.1, [], {}, None])
+def test_set_receipt_failover_rejects_non_bool(allow):
+    """Test that non-boolean values are rejected."""
+    client = Client.for_testnet()
+    with pytest.raises(TypeError, match="allow must be an instance of bool"):
+        client.set_allow_receipt_node_failover(allow)