feat: Added checksum field to remaining IDs (#422)

Signed-off-by: Manish Dait <[email protected]>

Author: manishdait

CHANGELOG.md

@@ -10,7 +10,6 @@ This changelog is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.
 - Unified balance and transfer logging format — both now consistently display values in hbars for clarity.
 
 ### Added
-
 - Refactored `examples/topic_create.py` into modular functions for better readability and reuse.
 - Add Rebasing and Signing section to signing.md with instructions for maintaining commit verification during rebase operations (#556)
 - Add `examples/account_id.py` demonstrating AccountId class usage including creating standard AccountIds, parsing from strings, comparing instances, and creating AccountIds with public key aliases
@@ -24,6 +23,7 @@ This changelog is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.
 - docs: Add Google-style docstrings to `AbstractTokenTransferTransaction` class and its methods in `abstract_token_transfer_transaction.py`.
 - docs: Add Google-style docstrings to `TokenRelationship` class and its methods in `token_relationship.py`.
 - feat: add initial testing guide structure
+- Added `checksum` filed for TopicId, FileId, ContractId, ScheduleId class
 
 ### Changed
 

src/hiero_sdk_python/account/account_id.py

@@ -2,11 +2,21 @@
 AccountId class.
 """
 
-from typing import List
+import re
+from typing import TYPE_CHECKING
 
 from hiero_sdk_python.crypto.public_key import PublicKey
 from hiero_sdk_python.hapi.services import basic_types_pb2
+from hiero_sdk_python.utils.entity_id_helper import (
+    parse_from_string,
+    validate_checksum,
+    format_to_string_with_checksum
+)
 
+if TYPE_CHECKING:
+    from hiero_sdk_python.client.client import Client
+
+ALIAS_REGEX = re.compile(r"^(0|[1-9]\d*)\.(0|[1-9]\d*)\.((?:[0-9a-fA-F][0-9a-fA-F])+)$")
 
 class AccountId:
     """
@@ -37,17 +47,42 @@ def __init__(
         self.realm = realm
         self.num = num
         self.alias_key = alias_key
+        self.__checksum: str | None = None
 
     @classmethod
     def from_string(cls, account_id_str: str) -> "AccountId":
         """
         Creates an AccountId instance from a string in the format 'shard.realm.num'.
         """
-        parts: List[str] = account_id_str.strip().split(".")
-        if len(parts) != 3:
-            raise ValueError("Invalid account ID string format. Expected 'shard.realm.num'")
-        shard, realm, num = map(int, parts)
-        return cls(shard, realm, num)
+        if account_id_str is None or not isinstance(account_id_str, str):
+            raise ValueError(f"Invalid account ID string '{account_id_str}'. Expected format 'shard.realm.num'.")
+
+        try:
+            shard, realm, num, checksum = parse_from_string(account_id_str)
+
+            account_id: AccountId = cls(
+                shard=int(shard),
+                realm=int(realm),
+                num=int(num)
+            )
+            account_id.__checksum = checksum
+
+            return account_id
+        except Exception as e:
+            alias_match = ALIAS_REGEX.match(account_id_str)
+            
+            if alias_match:
+                shard, realm, alias = alias_match.groups()
+                return cls(
+                    shard=int(shard),
+                    realm=int(realm),
+                    num=0,
+                    alias_key=PublicKey.from_bytes(bytes.fromhex(alias))
+                )
+            
+            raise ValueError(
+                f"Invalid account ID string '{account_id_str}'. Expected format 'shard.realm.num'."
+            ) from e
 
     @classmethod
     def _from_proto(cls, account_id_proto: basic_types_pb2.AccountID) -> "AccountId":
@@ -89,6 +124,24 @@ def _to_proto(self) -> basic_types_pb2.AccountID:
 
         return account_id_proto
 
+    @property
+    def checksum(self) -> str | None:
+        """Checksum of the accountId"""
+        return self.__checksum
+
+    def validate_checksum(self, client: "Client") -> None:
+        """Validate the checksum for the accountId"""
+        if self.alias_key is not None:
+            raise ValueError("Cannot calculate checksum with an account ID that has a aliasKey")
+
+        validate_checksum(
+            self.shard,
+            self.realm,
+            self.num,
+            self.__checksum,
+            client,
+        )
+
     def __str__(self) -> str:
         """
         Returns the string representation of the AccountId in 'shard.realm.num' format.
@@ -97,6 +150,21 @@ def __str__(self) -> str:
             return f"{self.shard}.{self.realm}.{self.alias_key.to_string()}"
         return f"{self.shard}.{self.realm}.{self.num}"
 
+    def to_string_with_checksum(self, client: "Client") -> str:
+        """
+        Returns the string representation of the AccountId with checksum 
+        in 'shard.realm.num-checksum' format.
+        """
+        if self.alias_key is not None:
+            raise ValueError("Cannot calculate checksum with an account ID that has a aliasKey")
+
+        return format_to_string_with_checksum(
+            self.shard,
+            self.realm,
+            self.num,
+            client
+        )
+
     def __repr__(self):
         """
         Returns the repr representation of the AccountId.

src/hiero_sdk_python/consensus/topic_id.py

@@ -7,11 +7,17 @@
 formats within the Hiero SDK.
 """
 
-from dataclasses import dataclass
+from dataclasses import dataclass, field
 
 from hiero_sdk_python.hapi.services import basic_types_pb2
-
-@dataclass
+from hiero_sdk_python.client.client import Client
+from hiero_sdk_python.utils.entity_id_helper import (
+    parse_from_string,
+    validate_checksum,
+    format_to_string_with_checksum
+)
+
+@dataclass(frozen=True)
 class TopicId:
     """
     Represents the unique identifier of a topic in the Hedera Consensus Service (HCS).
@@ -28,6 +34,7 @@ class TopicId:
     shard: int = 0
     realm: int = 0
     num: int = 0
+    checksum: str | None = field(default=None, init=False)
 
     @classmethod
     def _from_proto(cls, topic_id_proto: basic_types_pb2.TopicID) -> "TopicId":
@@ -82,7 +89,40 @@ def from_string(cls, topic_id_str: str) -> "TopicId":
         Raises:
             ValueError: If the string format is invalid.
         """
-        parts = topic_id_str.strip().split(".")
-        if len(parts) != 3:
-            raise ValueError("Invalid TopicId format. Expected 'shard.realm.num'")
-        return cls(shard=int(parts[0]), realm=int(parts[1]), num=int(parts[2]))
+        try:
+            shard, realm, num, checksum = parse_from_string(topic_id_str)
+
+            topic_id: TopicId = cls(
+                shard=int(shard),
+                realm=int(realm),
+                num=int(num)
+            )
+            object.__setattr__(topic_id, "checksum", checksum)
+
+            return topic_id
+        except Exception as e:
+            raise ValueError(
+                f"Invalid topic ID string '{topic_id_str}'. Expected format 'shard.realm.num'."
+            ) from e
+
+    def validate_checksum(self, client: Client) -> None:
+        """Validate the checksum for the topicId"""
+        validate_checksum(
+            self.shard,
+            self.realm,
+            self.num,
+            self.checksum,
+            client,
+        )
+
+    def to_string_with_checksum(self, client: Client) -> str:
+        """
+        Returns the string representation of the TopicId with checksum 
+        in 'shard.realm.num-checksum' format.
+        """
+        return format_to_string_with_checksum(
+            self.shard,
+            self.realm,
+            self.num,
+            client
+        )

src/hiero_sdk_python/contract/contract_id.py

@@ -2,11 +2,21 @@
 Contract ID class.
 """
 
-from dataclasses import dataclass
-from typing import Optional
+import re
+from dataclasses import dataclass, field
+from typing import TYPE_CHECKING, Optional
 
 from hiero_sdk_python.hapi.services import basic_types_pb2
+from hiero_sdk_python.utils.entity_id_helper import (
+    parse_from_string,
+    validate_checksum,
+    format_to_string_with_checksum
+)
 
+if TYPE_CHECKING:
+    from hiero_sdk_python.client.client import Client
+
+EVM_ADDRESS_REGEX = re.compile(r"^(0|[1-9]\d*)\.(0|[1-9]\d*)\.([a-fA-F0-9]{40}$)")
 
 @dataclass(frozen=True)
 class ContractId:
@@ -27,6 +37,7 @@ class ContractId:
     realm: int = 0
     contract: int = 0
     evm_address: Optional[bytes] = None
+    checksum: str | None = field(default=None, init=False)
 
     @classmethod
     def _from_proto(cls, contract_id_proto: basic_types_pb2.ContractID) -> "ContractId":
@@ -55,17 +66,47 @@ def from_string(cls, contract_id_str: str) -> "ContractId":
         """
         Parses a string in the format 'shard.realm.contract' to create a ContractId instance.
         """
-        parts = contract_id_str.strip().split(".")
-        if len(parts) != 3:
+        if contract_id_str is None or not isinstance(contract_id_str, str):
             raise ValueError(
-                "Invalid ContractId format. Expected 'shard.realm.contract'"
+                f"Invalid contract ID string '{contract_id_str}'. "
+                f"Expected format 'shard.realm.contract'."
+            )
+
+        evm_address_match = EVM_ADDRESS_REGEX.match(contract_id_str)
+
+        if evm_address_match:
+            shard, realm, evm_address = evm_address_match.groups()
+            return cls(
+                shard=int(shard),
+                realm=int(realm),
+                evm_address=bytes.fromhex(evm_address)
             )
-        return cls(shard=int(parts[0]), realm=int(parts[1]), contract=int(parts[2]))
+
+        else:
+            try:
+                shard, realm, contract, checksum = parse_from_string(contract_id_str)
+
+                contract_id: ContractId =  cls(
+                    shard=int(shard),
+                    realm=int(realm),
+                    contract=int(contract)
+                )
+                object.__setattr__(contract_id, "checksum", checksum)
+                return contract_id
+
+            except Exception as e:
+                raise ValueError(
+                    f"Invalid contract ID string '{contract_id_str}'. "
+                    f"Expected format 'shard.realm.contract'."
+                ) from e
 
     def __str__(self):
         """
         Returns the string representation of the ContractId in the format 'shard.realm.contract'.
         """
+        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:
@@ -84,3 +125,28 @@ def to_evm_address(self) -> str:
         evm_bytes = shard_bytes + realm_bytes + contract_bytes
 
         return evm_bytes.hex()
+
+    def validate_checksum(self, client: "Client") -> None:
+        """Validate the checksum for the contractId"""
+        validate_checksum(
+            self.shard,
+            self.realm,
+            self.contract,
+            self.checksum,
+            client,
+        )
+
+    def to_string_with_checksum(self, client: "Client") -> str:
+        """
+        Returns the string representation of the ContractId with checksum 
+        in 'shard.realm.contract-checksum' format.
+        """
+        if self.evm_address is not None:
+            raise ValueError("to_string_with_checksum cannot be applied to ContractId with evm_address")
+
+        return format_to_string_with_checksum(
+            self.shard,
+            self.realm,
+            self.contract,
+            client
+        )