Merge branch 'hiero-ledger:main' into main

Author: aceppaluni

.env.example

@@ -1,5 +1,5 @@
-OPERATOR_ID=<YOUR_OPERATOR_ID> #your private key, can be retrived from https://portal.hedera.com/dashboard
-OPERATOR_KEY=<YOUR_PRIVATE_KEY> # your account id, can be retrieved from https://portal.hedera.com/dashboard
+OPERATOR_ID=<YOUR_OPERATOR_ID> #your account id, can be retrived from https://portal.hedera.com/dashboard
+OPERATOR_KEY=<YOUR_PRIVATE_KEY> #your testnet private key, can be retrieved from https://portal.hedera.com/dashboard
 NETWORK=<NETWORK> #eg testnet/previewnet/mainnet
 
 # RECIPIENT_ID=<RECIPIENT_ID> #optional

CHANGELOG.md

@@ -9,17 +9,21 @@ This changelog is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.
 ### Added
 
 - Add Google-style docstrings to `AccountInfo` class and its methods in `account_info.py`.
-
+- Added comprehensive Google-style docstrings to the `Logger` class and all utility functions in `src/hiero_sdk_python/logger/logger.py` (#639).
 - add AccountRecordsQuery class
 
-### Changed
+- docs: Add Google-style docstrings to `ContractId` class and methods in `contract_id.py`.
 
+### Changed
+- chore: validate that token airdrop transactions require an available token service on the channel (#632) 
+- chore: update local environment configuration in env.example (#649)
 - chore: fix type hint for TokenCancelAirdropTransaction pending_airdrops parameter
 - chore: Moved documentation file `common_issues.md` from `examples/sdk_developers/` to `docs/sdk_developers/` for unified documentation management (#516).
 
 ### Fixed
 
 - Added explicit read permissions to examples.yml (#623)
+- Improved type hinting in `file_append_transaction.py` to resolve 'mypy --strict` errors. ([#495](https://github.com/hiero-ledger/hiero-sdk-python/issues/495))
 
 ### Breaking Changes
 

src/hiero_sdk_python/contract/contract_id.py

@@ -1,5 +1,8 @@
 """
-Contract ID class.
+Represents a Contract ID on the Hedera network.
+
+Provides utilities for creating, parsing from strings, converting to protobuf
+format, and validating checksums associated with a contract.
 """
 
 import re
@@ -18,19 +21,24 @@
 
 EVM_ADDRESS_REGEX = re.compile(r"^(0|[1-9]\d*)\.(0|[1-9]\d*)\.([a-fA-F0-9]{40}$)")
 
+
 @dataclass(frozen=True)
 class ContractId:
     """
-    Represents a contract ID on the network.
+    Represents a unique contract ID on the Hedera network.
 
-    A contract ID consists of three components: shard, realm, and contract (number).
-    These components uniquely identify a contract in the network.
+    A contract ID can be represented by its shard, realm, and contract number,
+    or by a 20-byte EVM address.
 
     Attributes:
-        shard (int): The shard number. Defaults to 0.
-        realm (int): The realm number. Defaults to 0.
-        contract (int): The contract number. Defaults to 0.
-        evm_address (bytes): The EVM address of the contract. Defaults to None.
+        shard (int): The shard number (non-negative). Defaults to 0.
+        realm (int): The realm number (non-negative). Defaults to 0.
+        contract (int): The contract number (non-negative). Defaults to 0.
+        evm_address (Optional[bytes]): The 20-byte EVM address of the contract.
+            Defaults to None.
+        checksum (Optional[str]): A network-specific checksum computed from
+            the shard, realm, and contract numbers. Not used if `evm_address`
+            is set.
     """
 
     shard: int = 0
@@ -43,6 +51,14 @@ class ContractId:
     def _from_proto(cls, contract_id_proto: basic_types_pb2.ContractID) -> "ContractId":
         """
         Creates a ContractId instance from a protobuf ContractID object.
+
+        Args:
+            contract_id_proto (basic_types_pb2.ContractID): The protobuf
+                ContractID object to convert from.
+
+        Returns:
+            ContractId: A new ContractId instance populated with data from
+            the protobuf object.
         """
         return cls(
             shard=contract_id_proto.shardNum,
@@ -53,6 +69,10 @@ def _from_proto(cls, contract_id_proto: basic_types_pb2.ContractID) -> "Contract
     def _to_proto(self):
         """
         Converts the ContractId instance to a protobuf ContractID object.
+
+        Returns:
+            basic_types_pb2.ContractID: The corresponding protobuf
+            ContractID object.
         """
         return basic_types_pb2.ContractID(
             shardNum=self.shard,
@@ -64,7 +84,21 @@ def _to_proto(self):
     @classmethod
     def from_string(cls, contract_id_str: str) -> "ContractId":
         """
-        Parses a string in the format 'shard.realm.contract' to create a ContractId instance.
+        Parses a string to create a ContractId instance.
+
+        The string can be in the format 'shard.realm.contract' (e.g., "0.0.123"),
+        'shard.realm.contract-checksum' (e.g., "0.0.123-vfmkw"),
+        or 'shard.realm.evm_address' (e.g., "0.0.a...f").
+
+        Args:
+            contract_id_str (str): The contract ID string to parse.
+
+        Returns:
+            ContractId: A new ContractId instance.
+
+        Raises:
+            ValueError: If the contract ID string is None, not a string,
+                or in an invalid format.
         """
         if contract_id_str is None or not isinstance(contract_id_str, str):
             raise ValueError(
@@ -86,7 +120,7 @@ def from_string(cls, contract_id_str: str) -> "ContractId":
             try:
                 shard, realm, contract, checksum = parse_from_string(contract_id_str)
 
-                contract_id: ContractId =  cls(
+                contract_id: ContractId = cls(
                     shard=int(shard),
                     realm=int(realm),
                     contract=int(contract)
@@ -102,16 +136,29 @@ def from_string(cls, contract_id_str: str) -> "ContractId":
 
     def __str__(self):
         """
-        Returns the string representation of the ContractId in the format 'shard.realm.contract'.
+        Returns the string representation of the ContractId.
+
+        Format will be 'shard.realm.contract' or 'shard.realm.evm_address_hex'
+        if evm_address is set. Does not include a checksum.
+
+        Returns:
+            str: The string representation of the ContractId.
         """
         if self.evm_address is not None:
             return f"{self.shard}.{self.realm}.{self.evm_address.hex()}"
-        
+
         return f"{self.shard}.{self.realm}.{self.contract}"
 
     def to_evm_address(self) -> str:
         """
-        Converts the ContractId to an EVM address.
+        Converts the ContractId to a 20-byte EVM address string (hex).
+
+        If the `evm_address` attribute is set, it returns that.
+        Otherwise, it computes the 20-byte EVM address from the shard, realm,
+        and contract numbers (e.g., [4-byte shard][8-byte realm][8-byte contract]).
+
+        Returns:
+            str: The 20-byte EVM address as a hex-encoded string.
         """
         if self.evm_address is not None:
             return self.evm_address.hex()
@@ -127,7 +174,20 @@ def to_evm_address(self) -> str:
         return evm_bytes.hex()
 
     def validate_checksum(self, client: "Client") -> None:
-        """Validate the checksum for the contractId"""
+        """
+        Validates the checksum (if present) against a client's network.
+
+        The checksum is validated against the ledger ID of the provided client.
+        This method does nothing if no checksum is present on the ContractId.
+
+        Args:
+            client (Client): The client instance, which contains the network
+                ledger ID used for checksum validation.
+
+        Raises:
+            ValueError: If the checksum is present but invalid or does not
+                match the client's network.
+        """
         validate_checksum(
             self.shard,
             self.realm,
@@ -138,8 +198,20 @@ def validate_checksum(self, client: "Client") -> None:
 
     def to_string_with_checksum(self, client: "Client") -> str:
         """
-        Returns the string representation of the ContractId with checksum 
-        in 'shard.realm.contract-checksum' format.
+        Generates a string representation with a network-specific checksum.
+
+        Format: 'shard.realm.contract-checksum' (e.g., "0.0.123-vfmkw").
+
+        Args:
+            client (Client): The client instance used to generate the
+                network-specific checksum.
+
+        Returns:
+            str: The string representation with checksum.
+
+        Raises:
+            ValueError: If the ContractId has an `evm_address` set,
+                as checksums cannot be applied to EVM addresses.
         """
         if self.evm_address is not None:
             raise ValueError("to_string_with_checksum cannot be applied to ContractId with evm_address")
@@ -149,4 +221,4 @@ def to_string_with_checksum(self, client: "Client") -> str:
             self.realm,
             self.contract,
             client
-        )
+        )