feat: Checksum support for TokenId.from_string() (#380)

* feat: added ledger_id to network.py

Signed-off-by: Manish Dait <daitmanish88@gmail.com>

* feat: added entity_id_helper for checksum validation

Signed-off-by: Manish Dait <daitmanish88@gmail.com>

* test: added unit test for entity_id_helper

Signed-off-by: Manish Dait <daitmanish88@gmail.com>

* feat: added checksum sum field in token_id

Signed-off-by: Manish Dait <daitmanish88@gmail.com>

* fix: missing filed in nft_id_test

Signed-off-by: Manish Dait <daitmanish88@gmail.com>

* test: updated entity_id_helper unit test

Signed-off-by: Manish Dait <daitmanish88@gmail.com>

* chore: updated CHANGELOG.md

Signed-off-by: Manish Dait <daitmanish88@gmail.com>

* chore: updated method to get string representation

Signed-off-by: Manish Dait <daitmanish88@gmail.com>

* chore: updated str() to use format_to_string() in token_id

Signed-off-by: Manish Dait <daitmanish88@gmail.com>

* feat: added method to get string representation of nftid with checksum

Signed-off-by: Manish Dait <daitmanish88@gmail.com>

* fix: update checksum to be use by from_string() method only

Signed-off-by: Manish Dait <daitmanish88@gmail.com>

* test:added test for token id

Signed-off-by: Manish Dait <daitmanish88@gmail.com>

* test:updated nft_id test

Signed-off-by: Manish Dait <daitmanish88@gmail.com>

* chore: fix pylint issues

Signed-off-by: Manish Dait <daitmanish88@gmail.com>

* chore: updated token_id from_string()

Signed-off-by: Manish Dait <daitmanish88@gmail.com>

* chore: fix spelling mistake

Signed-off-by: Manish Dait <daitmanish88@gmail.com>

* fix rebase issue

Signed-off-by: Manish Dait <daitmanish88@gmail.com>

* fix: added check for null checksum in validate()

Signed-off-by: Manish Dait <daitmanish88@gmail.com>

---------

Signed-off-by: Manish Dait <daitmanish88@gmail.com>

Author: manishdait

CHANGELOG.md

@@ -12,6 +12,7 @@ This changelog is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.
 - add revenue generating topic tests/example
 - add fee_schedule_key, fee_exempt_keys, custom_fees fields in TopicCreateTransaction, TopicUpdateTransaction, TopicInfo classes
 - add CustomFeeLimit class
+- Added checksum validation for TokenId
 
 ### Fixed
 - Incompatible Types assignment in token_transfer_list.py

src/hiero_sdk_python/client/network.py

@@ -61,11 +61,19 @@ class Network:
         ],
     }
 
+    LEDGER_ID: Dict[str, bytes] = {
+        'mainnet': bytes.fromhex('00'),
+        'testnet': bytes.fromhex('01'),
+        'previewnet': bytes.fromhex('02'),
+        'solo': bytes.fromhex('03')
+    }
+
     def __init__(
         self,
         network: str = 'testnet',
         nodes: Optional[List[_Node]] = None,
         mirror_address: Optional[str] = None,
+        ledger_id: bytes | None = None
     ) -> None:
         """
         Initializes the Network with the specified network name or custom config.
@@ -84,6 +92,8 @@ def __init__(
             network, 'localhost:5600'
         )
 
+        self.ledger_id = ledger_id or self.LEDGER_ID.get(network, bytes.fromhex('03'))
+
         if nodes is not None:
             final_nodes = nodes
         elif self.network in ('solo', 'localhost', 'local'):

src/hiero_sdk_python/tokens/nft_id.py

@@ -11,6 +11,7 @@
 import warnings
 from dataclasses import dataclass, field
 from typing import Optional
+from hiero_sdk_python.client.client import Client
 from hiero_sdk_python.hapi.services import basic_types_pb2
 from hiero_sdk_python.tokens.token_id import TokenId
 from hiero_sdk_python._deprecated import _DeprecatedAliasesMixin
@@ -119,6 +120,13 @@ def from_string(cls, nft_id_str: str) -> "NftId":
             token_id=TokenId.from_string(token_part),
             serial_number=int(serial_part),
         )
+ 
+    def to_string_with_checksum(self, client:Client) -> str:
+        """
+        Returns the string representation of the NftId with 
+        checksum in the format 'shard.realm.num-checksum/serial'
+        """
+        return f"{self.token_id.to_string_with_checksum(client)}/{self.serial_number}"
 
     def __str__(self) -> str:
         """

src/hiero_sdk_python/tokens/token_id.py

@@ -5,17 +5,25 @@
 Defines TokenId, a frozen dataclass for representing Hedera token identifiers
 (shard, realm, num) with validation and protobuf conversion utilities.
 """
-from dataclasses import dataclass
-from typing import List, Optional
+from dataclasses import dataclass, field
+from typing import Optional
 
 from hiero_sdk_python.hapi.services import basic_types_pb2
+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,
+    format_to_string_with_checksum
+)
 
 @dataclass(frozen=True, eq=True, init=True, repr=True)
 class TokenId:
     """Immutable token identifier (shard, realm, num) with validation and protobuf conversion."""
     shard: int
     realm: int
     num: int
+    checksum: str | None = field(default=None, init=False)
 
     def __post_init__(self) -> None:
         if self.shard < 0:
@@ -54,28 +62,40 @@ def from_string(cls, token_id_str: Optional[str] = None) -> "TokenId":
         """
         Parses a string in the format 'shard.realm.num' to create a TokenId instance.
         """
-        if token_id_str is None:
-            raise ValueError("TokenId string must be provided")
+        shard, realm, num, checksum = parse_from_string(token_id_str)
 
-        token_id_str = token_id_str.strip()
-        if not token_id_str:
-            raise ValueError("TokenId cannot be empty or whitespace")
+        token_id = cls(int(shard), int(realm), int(num))
+        object.__setattr__(token_id, 'checksum', checksum)
 
-        parts: List[str] = token_id_str.split(".")
-        if len(parts) != 3:
-            raise ValueError("Invalid TokenId format. Expected 'shard.realm.num'")
+        return token_id
 
-        return cls(
-            shard=int(parts[0]),
-            realm=int(parts[1]),
-            num=int(parts[2])
+    def validate_checksum(self, client: Client) -> None:
+        """Validate the checksum for the TokenId instance"""
+        validate_checksum(
+            shard=self.shard,
+            realm=self.realm,
+            num=self.num,
+            checksum=self.checksum,
+            client=client
+        )
+
+    def to_string_with_checksum(self, client:Client) -> str:
+        """
+        Returns the string representation of the TokenId with checksum 
+        in the format 'shard.realm.num-checksum'
+        """
+        return format_to_string_with_checksum(
+            shard=self.shard,
+            realm=self.realm,
+            num=self.num,
+            client=client
         )
 
     def __str__(self) -> str:
         """
         Returns the string representation of the TokenId in the format 'shard.realm.num'.
         """
-        return f"{self.shard}.{self.realm}.{self.num}"
+        return format_to_string(self.shard, self.realm, self.num)
 
     def __hash__(self) -> int:
         """ Returns a hash of the TokenId instance. """

src/hiero_sdk_python/utils/entity_id_helper.py

@@ -0,0 +1,122 @@
+import re
+
+from hiero_sdk_python.client.client import Client
+
+ID_REGEX = re.compile(r"^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-([a-z]{5}))?$")
+
+MULTIPLIER = 1000003
+P3 = 26**3
+P5 = 26**5
+
+def parse_from_string(address: str):
+    """
+    Parse an address string of the form: <shard>.<realm>.<num>[-<checksum>]
+    Examples:
+        "0.0.123"
+        "0.0.123-abcde"
+
+    Returns:
+        An instance of cls with shard, realm, num, and optional checksum.
+    """
+    match = ID_REGEX.match(address)
+    if not match:
+        raise ValueError("Invalid address format")
+
+    shard, realm, num, checksum = match.groups()
+
+    return shard, realm, num, checksum
+
+def generate_checksum(ledger_id: bytes, address: str) -> str:
+    """
+    Compute the 5-character checksum for a Hiero entity ID string (HIP-15).
+    
+    Args:
+        ledger_id: The ledger identifier as raw bytes (e.g., b"\x00" for mainnet).
+        address: A string of the form "shard.realm.num" (e.g., "0.0.123").
+    
+    Returns:
+        A 5-letter checksum string (e.g., "kfmza").
+    """
+    # Convert "0.0.123" into a digit list with '.' as 10
+    d = []
+    for ch in address:
+        if ch == '.':
+            d.append(10)
+        else:
+            d.append(int(ch))
+
+    # Initialize running sums
+    sd0 = 0  # sum of digits at even indices mod 11
+    sd1 = 0  # sum of digits at odd indices mod 11
+    sd = 0   # weight sum of all position mod P3
+
+    for i in range(len(d)):
+        sd = (sd * 31 + d[i]) % P3
+        if i % 2 == 0:
+            sd0 = (sd0 + d[i]) % 11
+        else:
+            sd1 = (sd1 + d[i]) % 11
+
+    # Compute hash of ledger ID bytes (padded with six zeros)
+    sh = 0
+    h = list(ledger_id or b"")
+    h += [0] * 6
+
+    for i in range(len(h)):
+        sh = (sh * 31 + h[i]) % P5
+
+    cp = ((((len(address) % 5) * 11 + sd0) * 11 + sd1) * P3 + sd + sh) % P5
+    cp = (cp * MULTIPLIER) % P5
+
+    letter = []
+
+    for _ in range(5):
+        letter.append(chr(ord('a') + (cp % 26)))
+        cp //= 26
+
+    return "".join(reversed(letter))
+
+def validate_checksum(shard: int, realm: int, num: int, checksum: str | None, client: Client) -> None:
+    """
+    Validate a Hiero entity ID checksum against the current client's ledger.
+
+    Args:
+        shard: Shard number of the entity ID.
+        realm: Realm number of the entity ID.
+        num: Entity number (account, token, topic, etc.).
+        checksum: The 5-letter checksum string to validate.
+        client: The Hiero client, which holds the target ledger_id.
+
+    Raises:
+        ValueError: If the ledger ID is missing or if the checksum is invalid.
+    """
+    # If no checksum present then return.
+    if (checksum is None):
+        return
+
+    ledger_id = client.network.ledger_id
+    if not ledger_id:
+        raise ValueError("Missing ledger ID in client")
+
+    address = format_to_string(shard, realm, num)
+    expected_checksum = generate_checksum(ledger_id, address)
+
+    if expected_checksum != checksum:
+        raise ValueError(f"Checksum mismatch for {address}")
+
+def format_to_string(shard: int, realm: int, num: int) -> str:
+    """
+    Convert an entity ID into its standard string representation.
+    """
+    return f"{shard}.{realm}.{num}"
+
+def format_to_string_with_checksum(shard: int, realm: int, num: int,client: Client) -> str:
+    """
+    Convert an entity ID into its string representation with checksum.
+    """
+    ledger_id = client.network.ledger_id
+    if not ledger_id:
+        raise ValueError("Missing ledger ID in client")
+
+    base_str = format_to_string(shard, realm, num)
+    return f"{base_str}-{generate_checksum(ledger_id, format_to_string(shard, realm, num))}"

tests/unit/nft_id_test.py

@@ -11,7 +11,7 @@ def test_nft_id():
     nftid_constructor_test = NftId(token_id=nftid_constructor_tokenid, serial_number=1234)
 
     assert str(nftid_constructor_test) == "0.1.2/1234"
-    assert repr(nftid_constructor_test) == "NftId(token_id=TokenId(shard=0, realm=1, num=2), serial_number=1234)"
+    assert repr(nftid_constructor_test) == "NftId(token_id=TokenId(shard=0, realm=1, num=2, checksum=None), serial_number=1234)"
     assert nftid_constructor_test._to_proto().__eq__(
         basic_types_pb2.NftID(
             token_ID=basic_types_pb2.TokenID(shardNum=0, realmNum=1, tokenNum=2),
@@ -65,3 +65,13 @@ def test_nft_id():
     fail_str = "a.3.3/19"
     with pytest.raises(ValueError):
         NftId.from_string(fail_str)
+
+def test_get_nft_id_with_checksum(mock_client):
+    """Should return string with checksum when ledger id is provided."""
+    client = mock_client
+    client.network.ledger_id = bytes.fromhex("00")
+
+    token_id = TokenId.from_string("0.0.1")
+    nft_id = NftId(token_id, 1)
+
+    assert nft_id.to_string_with_checksum(client) == "0.0.1-dfkxr/1"