chore: enhance exception type safety and context (hiero-ledger#1594)

Signed-off-by: Adityarya11 <arya050411@gmail.com>

Author: Adityarya11

CHANGELOG.md

@@ -146,6 +146,7 @@ This changelog is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.
 - Added MirrorNode based population for `ContractId`, including parsing and serialization support.
 - Added `/working` command to reset the inactivity timer on issues and PRs. ([#1552](https://github.com/hiero-ledger/hiero-sdk-python/issues/1552))
 - Added `grpc_deadline` support for transaction and query execution.
+- Type hints to exception classes (`PrecheckError`, `MaxAttemptsError`, `ReceiptStatusError`) constructors and string methods.
 
 ### Documentation
 - Added comprehensive docstring to `compress_with_cryptography` function (#1626)

examples/errors/max_attempts_error.py

@@ -0,0 +1,59 @@
+#!/usr/bin/env python3
+"""
+Example demonstrating how to handle MaxAttemptsError in the Hiero SDK.
+
+run:
+uv run examples/errors/max_attempts_error.py
+python examples/errors/max_attempts_error.py
+"""
+
+from hiero_sdk_python import (
+    Client,
+    TransactionGetReceiptQuery,
+    TransactionId,
+)
+from hiero_sdk_python.exceptions import MaxAttemptsError
+
+def main() -> None:
+    # Initialize the client
+    client = Client.from_env()
+    operator_id = client.operator_account_id
+
+    # Configure client to fail quickly
+    # This sets the maximum number of attempts for any request to 1
+    client.set_max_attempts(1)
+
+    print("Attempting to fetch receipt with restricted max attempts...")
+
+    # We generate a random transaction ID that definitely doesn't exist.
+    # The network would normally return RECEIPT_NOT_FOUND, but depending on the
+    # node's state or if we simulate a network blip, the SDK's retry mechanism kicks in.
+    # By forcing max_attempts=1, we prevent retries.
+    # Note: Triggering a pure MaxAttemptsError usually requires a timeout or busy node.
+    # This example demonstrates the structure of handling the error.
+    
+
+    # Using a generated TransactionId
+    tx_id = TransactionId.generate(operator_id)
+
+    try:
+        TransactionGetReceiptQuery().set_transaction_id(tx_id).execute(client)
+        print("Query finished (unexpected for this example test).")
+
+    except MaxAttemptsError as e:
+        print("\nCaught MaxAttemptsError!")
+        print(f"Node ID: {e.node_id}")
+        print(f"Message: {e.message}")
+        print("This error means the SDK gave up after reaching the maximum number of retry attempts.")
+        
+    except Exception as e:
+        # Note: In a real network test with a made-up ID, we might get ReceiptStatusError 
+        # or PrecheckError (RECEIPT_NOT_FOUND). MaxAttemptsError typically happens 
+        # on network timeouts or BUSY responses.
+        print(f"\nCaught unexpected error (expected for this specific simulation): {type(e).__name__}")
+        print(f"Details: {e}")
+        print("\n(To verify MaxAttemptsError logic, this example relies on the client's retry configuration)")
+
+
+if __name__ == "__main__":
+    main()

examples/errors/precheck_error.py

@@ -0,0 +1,52 @@
+#!/usr/bin/env python3
+"""
+Example demonstrating how to handle PrecheckError in the Hiero SDK.
+
+run:
+uv run examples/errors/precheck_error.py
+python examples/errors/precheck_error.py
+"""
+
+from hiero_sdk_python.exceptions import PrecheckError
+from hiero_sdk_python import (
+    Client,
+    TransferTransaction,
+    AccountId
+)
+
+def main() -> None:
+    # Initialize the client
+    client = Client.from_env()
+    operator_id = client.operator_account_id
+    operator_key = client.operator_private_key
+
+    print("Creating transaction with invalid parameters to force PrecheckError...")
+
+    # Create a simple transfer transaction
+    # To trigger a PrecheckError, we set the transaction valid duration to 0.
+    # The node's precheck validation requires a valid duration, so this will fail immediately.
+    transaction = (
+        TransferTransaction()
+        .add_hbar_transfer(operator_id, -1)
+        .add_hbar_transfer(AccountId(0, 0, 3), 1)
+        .set_transaction_valid_duration(1) 
+        .freeze_with(client)
+        .sign(operator_key)
+    )
+
+    try:
+        print("Executing transaction...")
+        transaction.execute(client)
+        print("Transaction unexpectedly succeeded (this should not happen).")
+
+    except PrecheckError as e:
+        print("\nCaught PrecheckError!")
+        print(f"Status: {e.status.name} ({e.status})")
+        print(f"Transaction ID: {e.transaction_id}")
+        print("This error means the transaction failed validation at the node *before* reaching consensus.")
+
+    except Exception as e:
+        print(f"\nAn unexpected error occurred: {type(e).__name__}: {e}")
+
+if __name__ == "__main__":
+    main()

examples/errors/receipt_status_error.py

@@ -6,41 +6,19 @@
 uv run examples/errors/receipt_status_error.py
 python examples/errors/receipt_status_error.py
 """
-import os
-import dotenv
-
-from hiero_sdk_python.client.client import Client
-from hiero_sdk_python.account.account_id import AccountId
-from hiero_sdk_python.crypto.private_key import PrivateKey
-from hiero_sdk_python.response_code import ResponseCode
-from hiero_sdk_python.tokens.token_associate_transaction import (
+from hiero_sdk_python import (
+    Client,
+    ResponseCode,
     TokenAssociateTransaction,
+    TokenId
 )
-from hiero_sdk_python.tokens.token_id import TokenId
 from hiero_sdk_python.exceptions import ReceiptStatusError
 
-dotenv.load_dotenv()
-
-
-def main():
-    # Initialize the client
-    # For this example, we assume we are running against a local node or testnet
-    # You would typically load these from environment variables
-    operator_id_str = os.environ.get("OPERATOR_ID", "")
-    operator_key_str = os.environ.get("OPERATOR_KEY", "")
-
-    try:
-        operator_id = AccountId.from_string(operator_id_str)
-        operator_key = PrivateKey.from_string(operator_key_str)
-    except Exception as e:
-        print(f"Error parsing operator credentials: {e}")
-        return
-
-    client = Client()
-    client.set_operator(operator_id, operator_key)
-
-    # Create a  transaction that is likely to fail post-consensus
-    # Here we try to associate a non-existent token
+def main() -> None:
+    client = Client.from_env()
+    
+    operator_id = client.operator_account_id
+    operator_key = client.operator_private_key
 
     print("Creating transaction...")
     transaction = (
@@ -53,22 +31,21 @@ def main():
 
     try:
         print("Executing transaction...")
-        # execute() submits the transaction to the network and returns a receipt
-        # Note: this does NOT automatically raise an exception if the transaction fails post-consensus.
         receipt = transaction.execute(client)
         print(f"Transaction submitted. ID: {receipt.transaction_id}")
 
         # Check if the execution raised something other than SUCCESS
-        # If not, we raise our custom ReceiptStatusError for handling.
+        if receipt.status is None:
+            raise ValueError("Receipt missing status")
         if receipt.status != ResponseCode.SUCCESS:
             raise ReceiptStatusError(receipt.status, receipt.transaction_id, receipt)
-        # If we reach here, the transaction succeeded
+
         print("Transaction successful!")
 
     # This exception is raised when the transaction raised something other than SUCCESS
     except ReceiptStatusError as e:
         print("\nCaught ReceiptStatusError!")
-        print(f"Status: {e.status} ({ResponseCode(e.status).name})")
+        print(f"Status: {e.status.name} ({e.status})")
         print(f"Transaction ID: {e.transaction_id}")
         print(
             "This error means the transaction reached consensus but failed logic execution."
@@ -80,4 +57,4 @@ def main():
 
 
 if __name__ == "__main__":
-    main()
+    main()

src/hiero_sdk_python/exceptions.py

@@ -1,5 +1,14 @@
+from __future__ import annotations 
+from typing import TYPE_CHECKING, Optional, Union
+
 from hiero_sdk_python.response_code import ResponseCode
 
+if TYPE_CHECKING:
+    from hiero_sdk_python import (
+        TransactionId,
+        TransactionReceipt
+    )
+
 class PrecheckError(Exception):
     """
     Exception thrown when a transaction fails its precheck validation.
@@ -11,81 +20,97 @@ class PrecheckError(Exception):
         transaction_id (TransactionId): The ID of the transaction that failed.
         message (str): The message of the error. If not provided, a default message is generated.
     """
-    def __init__(self, status, transaction_id=None, message=None):
-        self.status = status
+
+    def __init__(
+        self,
+        status: Union[ResponseCode, int],
+        transaction_id: Optional[TransactionId] = None,
+        message: Optional[str] = None,
+    ) -> None:
+        self.status = ResponseCode(status)
         self.transaction_id = transaction_id
-        
+
         # Build a default message if none provided
         if message is None:
-            status_name = ResponseCode(status).name
-            message = f"Transaction failed precheck with status: {status_name} ({status})"
+            status_name = self.status.name
+            message = f"Transaction failed precheck with status: {status_name} ({int(self.status)})"
             if transaction_id:
                 message += f", transaction ID: {transaction_id}"
-        
+
         self.message = message
         super().__init__(self.message)
-    
-    def __str__(self):
+
+    def __str__(self) -> str:
         return self.message
-    
-    def __repr__(self):
+
+    def __repr__(self) -> str:
         return f"PrecheckError(status={self.status}, transaction_id={self.transaction_id})"
-    
-    
+
+
 class MaxAttemptsError(Exception):
     """
     Exception raised when the maximum number of attempts for a request has been reached.
-    
+
     Attributes:
         message (str): The error message explaining why the maximum attempts were reached
         node_id (str): The ID of the node that was being contacted when the max attempts were reached
-        last_error (Exception): The last error that occurred during the final attempt
+        last_error (BaseException): The last error that occurred during the final attempt
     """
-    
-    def __init__(self, message, node_id, last_error=None):
+
+    def __init__(self, message: str, node_id: str, last_error: Optional[BaseException] = None) -> None:
         self.node_id = node_id
         self.last_error = last_error
-        
+
         # Build a comprehensive error message
         error_message = message
         if last_error is not None:
             error_message += f"; last error: {str(last_error)}"
-            
+
         self.message = error_message
         super().__init__(self.message)
-    
-    def __str__(self):
+
+    def __str__(self) -> str:
         return self.message
-    
-    def __repr__(self):
+
+    def __repr__(self) -> str:
         return f"MaxAttemptsError(message='{self.message}', node_id='{self.node_id}')"
-    
+
+
 class ReceiptStatusError(Exception):
     """
     Exception raised when a transaction receipt contains an error status.
     
     Attributes:
         status (ResponseCode): The error status code from the receipt
-        transaction_id (TransactionId): The ID of the transaction that failed
+        transaction_id (TransactionId): The ID of the transaction that failed (Optional)
         transaction_receipt (TransactionReceipt): The receipt containing the error status
         message (str): The error message describing the failure
     """
 
-    def __init__(self, status, transaction_id, transaction_receipt, message=None):
-        self.status = status
+    def __init__(
+        self, 
+        status: Union[ResponseCode, int], 
+        transaction_id: Optional[TransactionId], 
+        transaction_receipt: TransactionReceipt, 
+        message: Optional[str] = None
+    ) -> None:
+        self.status = ResponseCode(status)
         self.transaction_id = transaction_id
         self.transaction_receipt = transaction_receipt
 
         # Build a default message if none provided
         if message is None:
-            status_name = ResponseCode(status).name
-            message = f"Receipt for transaction {transaction_id} contained error status: {status_name} ({status})"
+            status_name = self.status.name
+            if transaction_id:
+                message = f"Receipt for transaction {transaction_id} contained error status: {status_name} ({int(self.status)})"
+            else:
+                message = f"Receipt contained error status: {status_name} ({int(self.status)})"
 
         self.message = message
         super().__init__(self.message)
 
-    def __str__(self):
+    def __str__(self) -> str:
         return self.message
 
-    def __repr__(self):
-        return f"ReceiptStatusError(status={self.status}, transaction_id={self.transaction_id})"
+    def __repr__(self) -> str:
+        return f"ReceiptStatusError(status={self.status}, transaction_id={self.transaction_id})"

src/hiero_sdk_python/transaction/transaction.py

@@ -551,6 +551,22 @@ def set_transaction_memo(self, memo):
         self.memo = memo
         return self
 
+    def set_transaction_valid_duration(self, duration: int) -> "Transaction":
+        """
+        Sets the valid duration for the transaction.
+
+        Args:
+            duration (int): The duration in seconds.
+
+        Returns:
+            Transaction: The current transaction instance for method chaining.
+        """
+        self._require_not_frozen()
+        if duration <= 0:
+            raise ValueError("duration must be greater than 0")
+        self.transaction_valid_duration = duration
+        return self
+
     def set_transaction_id(self, transaction_id: TransactionId):
         """
         Sets the transaction ID for the transaction.