hiero-sdk-python 0.0.1.dev2__tar.gz → 0.1.0__tar.gz

{hiero_sdk_python-0.0.1.dev2 → hiero_sdk_python-0.1.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: hiero-sdk-python
-Version: 0.0.1.dev2
+Version: 0.1.0
 Summary: A Hiero SDK in pure Python
 Author-Email: Nadine Loepfe <nadine.loepfe@hashgraph.com>, Richard Bair <rbair23@users.noreply.github.com>
 Maintainer-Email: Nadine Loepfe <nadine.loepfe@hashgraph.com>
@@ -225,7 +225,7 @@ Description-Content-Type: text/markdown
 
 This is a Python SDK for interacting with the Hedera Hashgraph platform. It allows developers to:
 
-- Manage Token Transactions like Create, Mint Fungible, Mint Non-Fungible, Associate, Dissociate, Transfer & Delete
+- Manage Token Transactions like Create, Mint Fungible, Mint Non-Fungible, Associate, Dissociate, Transfer, Freeze & Delete
 - Manage Consensus Transactions like Topic Create, Update, Delete
 - Submit Topic Messages
 - Query Account Balance, Transaction Receipts, Topic Infos and Messages
@@ -248,6 +248,7 @@ This is a Python SDK for interacting with the Hedera Hashgraph platform. It allo
   - [Dissociating a Token](#dissociating-a-token)
   - [Transferring Tokens](#transferring-tokens)
   - [Deleting a Token](#deleting-a-token)
+  - [Freezing a Token](#freezing-a-token)
   - [Transferring HBAR](#transferring-hbar)
   - [Creating a Topic](#creating-a-topic)
   - [Submitting a Topic Message](#submitting-a-topic-message)
@@ -338,9 +339,11 @@ OPERATOR_ID=0.0.1234xx
 OPERATOR_KEY=302e020100300506032b657004220420...
 ADMIN_KEY=302a300506032b65700321009308ecfdf...
 SUPPLY_KEY =302a300506032b6570032100c5e4af5..."
+FREEZE_KEY=302a300306072b65700321009308ecfdf...
 RECIPIENT_ID=0.0.789xx
 TOKEN_ID=0.0.100xx
 TOPIC_ID=0.0.200xx
+FREEZE_ACCOUNT_ID=0.0.100
 NETWORK=testnet
 ```
 
@@ -371,6 +374,7 @@ Token association successful.
 Token dissociation successful.
 Token minting successful.
 Token transfer successful.
+Token freeze successful.
 Token deletion successful.
 Topic creation successful.
 Topic Message submitted.
@@ -627,6 +631,32 @@ transaction.execute(client)
     transaction.execute(client)
 ```
 
+### Freezing a Token
+
+#### Pythonic Syntax:
+```
+transaction = TokenFreezeTransaction(
+    token_id=token_id
+    account_id=account_id
+).freeze_with(client)
+
+transaction.sign(freeze_key)  # Freeze key must have been set during token creation.
+transaction.execute(client)
+```
+#### Method Chaining:
+```
+    transaction = (
+        TokenFreezeTransaction()
+        .set_token_id(token_id)
+        .set_account_id(account_id)
+        .freeze_with(client)
+    )
+
+    transaction.sign(freeze_key) # Freeze key must also have been set in Token Create
+    transaction.execute(client)
+```
+
+
 ### Transferring HBAR
 
 #### Pythonic Syntax:

{hiero_sdk_python-0.0.1.dev2 → hiero_sdk_python-0.1.0}/README.md

@@ -2,7 +2,7 @@
 
 This is a Python SDK for interacting with the Hedera Hashgraph platform. It allows developers to:
 
-- Manage Token Transactions like Create, Mint Fungible, Mint Non-Fungible, Associate, Dissociate, Transfer & Delete
+- Manage Token Transactions like Create, Mint Fungible, Mint Non-Fungible, Associate, Dissociate, Transfer, Freeze & Delete
 - Manage Consensus Transactions like Topic Create, Update, Delete
 - Submit Topic Messages
 - Query Account Balance, Transaction Receipts, Topic Infos and Messages
@@ -25,6 +25,7 @@ This is a Python SDK for interacting with the Hedera Hashgraph platform. It allo
   - [Dissociating a Token](#dissociating-a-token)
   - [Transferring Tokens](#transferring-tokens)
   - [Deleting a Token](#deleting-a-token)
+  - [Freezing a Token](#freezing-a-token)
   - [Transferring HBAR](#transferring-hbar)
   - [Creating a Topic](#creating-a-topic)
   - [Submitting a Topic Message](#submitting-a-topic-message)
@@ -115,9 +116,11 @@ OPERATOR_ID=0.0.1234xx
 OPERATOR_KEY=302e020100300506032b657004220420...
 ADMIN_KEY=302a300506032b65700321009308ecfdf...
 SUPPLY_KEY =302a300506032b6570032100c5e4af5..."
+FREEZE_KEY=302a300306072b65700321009308ecfdf...
 RECIPIENT_ID=0.0.789xx
 TOKEN_ID=0.0.100xx
 TOPIC_ID=0.0.200xx
+FREEZE_ACCOUNT_ID=0.0.100
 NETWORK=testnet
 ```
 
@@ -148,6 +151,7 @@ Token association successful.
 Token dissociation successful.
 Token minting successful.
 Token transfer successful.
+Token freeze successful.
 Token deletion successful.
 Topic creation successful.
 Topic Message submitted.
@@ -404,6 +408,32 @@ transaction.execute(client)
     transaction.execute(client)
 ```
 
+### Freezing a Token
+
+#### Pythonic Syntax:
+```
+transaction = TokenFreezeTransaction(
+    token_id=token_id
+    account_id=account_id
+).freeze_with(client)
+
+transaction.sign(freeze_key)  # Freeze key must have been set during token creation.
+transaction.execute(client)
+```
+#### Method Chaining:
+```
+    transaction = (
+        TokenFreezeTransaction()
+        .set_token_id(token_id)
+        .set_account_id(account_id)
+        .freeze_with(client)
+    )
+
+    transaction.sign(freeze_key) # Freeze key must also have been set in Token Create
+    transaction.execute(client)
+```
+
+
 ### Transferring HBAR
 
 #### Pythonic Syntax:

{hiero_sdk_python-0.0.1.dev2 → hiero_sdk_python-0.1.0}/pyproject.toml

@@ -27,7 +27,7 @@ classifiers = [
     "Intended Audience :: Developers",
     "Topic :: Software Development :: Libraries :: Python Modules",
 ]
-version = "0.0.1.dev2"
+version = "0.1.0"
 
 [project.license]
 file = "LICENSE"
@@ -40,6 +40,18 @@ lint = [
     "ruff>=0.8.3",
 ]
 
+[build-system]
+requires = [
+    "pdm-backend",
+    "setuptools",
+    "setuptools_scm",
+]
+build-backend = "pdm.backend"
+
+[tool.setuptools_scm]
+version_scheme = "python-simplified-semver"
+local_scheme = "dirty-tag"
+
 [tool.pdm.version]
 source = "scm"
 
@@ -49,11 +61,20 @@ excludes = [
     "**/.pytest_cache",
 ]
 
+[tool.pytest.ini_options]
+pythonpath = [
+    "src",
+]
+
 [tool.ruff]
 line-length = 120
 
-[build-system]
-requires = [
-    "pdm-backend",
+[tool.ruff.lint]
+select = [
+    "E",
+    "W",
+    "F",
+    "C",
+    "I",
+    "D",
 ]
-build-backend = "pdm.backend"

{hiero_sdk_python-0.0.1.dev2 → hiero_sdk_python-0.1.0}/src/hiero_sdk_python/__init__.py

@@ -16,6 +16,7 @@ from .tokens.token_associate_transaction import TokenAssociateTransaction
 from .tokens.token_dissociate_transaction import TokenDissociateTransaction
 from .tokens.token_delete_transaction import TokenDeleteTransaction
 from .tokens.token_mint_transaction import TokenMintTransaction
+from .tokens.token_freeze_transaction import TokenFreezeTransaction
 from .tokens.token_id import TokenId
 
 # Transaction
@@ -64,6 +65,7 @@ __all__ = [
     "TokenDissociateTransaction",
     "TokenDeleteTransaction",
     "TokenMintTransaction",
+    "TokenFreezeTransaction",
     "TokenId",
 
     # Transaction

{hiero_sdk_python-0.0.1.dev2 → hiero_sdk_python-0.1.0}/src/hiero_sdk_python/client/client.py

@@ -10,7 +10,6 @@ from hiero_sdk_python.hapi.services import (
 
 from hiero_sdk_python.hapi.mirror import (
     consensus_service_pb2_grpc as mirror_consensus_grpc,
-    mirror_network_service_pb2_grpc as mirror_network_grpc
 )
 
 from .network import Network
@@ -46,7 +45,7 @@ class Client:
         if not node_account_ids:
             raise ValueError("No nodes available in the network configuration.")
 
-        initial_node_id = node_account_ids[0] 
+        initial_node_id = node_account_ids[0]
         self._switch_node(initial_node_id)
 
         self._init_mirror_stub()
@@ -61,16 +60,26 @@ class Client:
         self.mirror_stub = mirror_consensus_grpc.ConsensusServiceStub(self.mirror_channel)
 
     def set_operator(self, account_id, private_key):
+        """
+        Sets the operator credentials (account ID and private key).
+        """
         self.operator_account_id = account_id
         self.operator_private_key = private_key
 
     @property
     def operator(self):
+        """
+        Returns an Operator namedtuple if both account ID and private key are set,
+        otherwise None.
+        """
         if self.operator_account_id and self.operator_private_key:
             return Operator(account_id=self.operator_account_id, private_key=self.operator_private_key)
         return None
 
     def generate_transaction_id(self):
+        """
+        Generates a new transaction ID, requiring that the operator_account_id is set.
+        """
         if self.operator_account_id is None:
             raise ValueError("Operator account ID must be set to generate transaction ID.")
         return TransactionId.generate(self.operator_account_id)
@@ -85,6 +94,9 @@ class Client:
             raise ValueError("No nodes available in the network configuration.")
 
     def get_transaction_receipt(self, transaction_id, max_attempts=10, sleep_seconds=2):
+        """
+        Repeatedly queries for a transaction receipt until SUCCESS or certain retryable statuses.
+        """
         for attempt in range(max_attempts):
             receipt_query = TransactionGetReceiptQuery()
             receipt_query.set_transaction_id(transaction_id)
@@ -93,7 +105,13 @@ class Client:
 
             if status == ResponseCode.SUCCESS:
                 return receipt
-            elif status in (ResponseCode.UNKNOWN, ResponseCode.BUSY, ResponseCode.RECEIPT_NOT_FOUND, ResponseCode.RECORD_NOT_FOUND, ResponseCode.PLATFORM_NOT_ACTIVE):
+            elif status in (
+                ResponseCode.UNKNOWN,
+                ResponseCode.BUSY,
+                ResponseCode.RECEIPT_NOT_FOUND,
+                ResponseCode.RECORD_NOT_FOUND,
+                ResponseCode.PLATFORM_NOT_ACTIVE
+            ):
                 time.sleep(sleep_seconds)
                 continue
             else:
@@ -137,3 +155,30 @@ class Client:
         self.crypto_stub = crypto_service_pb2_grpc.CryptoServiceStub(self.channel)
         self.topic_stub = consensus_service_pb2_grpc.ConsensusServiceStub(self.channel)
         self.node_account_id = node_account_id
+
+    def close(self):
+        """
+        Closes any open gRPC channels and frees resources.
+        Call this when you are done using the Client to ensure a clean shutdown.
+        """
+        if self.channel is not None:
+            self.channel.close()
+            self.channel = None
+
+        if self.mirror_channel is not None:
+            self.mirror_channel.close()
+            self.mirror_channel = None
+
+        self.token_stub = None
+        self.crypto_stub = None
+        self.topic_stub = None
+        self.mirror_stub = None
+
+    def __enter__(self):
+        return self
+
+    def __exit__(self, exc_type, exc_value, traceback):
+        """
+        Automatically close channels when exiting 'with' block.
+        """
+        self.close()

{hiero_sdk_python-0.0.1.dev2 → hiero_sdk_python-0.1.0}/src/hiero_sdk_python/client/network.py

@@ -18,7 +18,7 @@ class Network:
         'mainnet': 'https://mainnet-public.mirrornode.hedera.com',
         'testnet': 'https://testnet.mirrornode.hedera.com',
         'previewnet': 'https://previewnet.mirrornode.hedera.com',
-        'solo': 'http://localhost:8080'  
+        'solo': 'http://localhost:8080'
     }
 
     DEFAULT_NODES = {

hiero_sdk_python-0.1.0/src/hiero_sdk_python/consensus/topic_message.py

@@ -0,0 +1,176 @@
+from datetime import datetime
+from typing import Optional, List, Union, Dict
+from hiero_sdk_python.hapi.mirror import consensus_service_pb2 as mirror_proto
+
+def _to_datetime(ts_proto) -> datetime:
+    """
+    Convert a protobuf Timestamp to a Python datetime (UTC).
+    """
+    return datetime.utcfromtimestamp(ts_proto.seconds + ts_proto.nanos / 1e9)
+
+
+class TopicMessageChunk:
+    """
+    Represents a single chunk within a chunked topic message.
+    Mirrors the Java 'TopicMessageChunk'.
+    """
+
+    def __init__(self, response: mirror_proto.ConsensusTopicResponse):
+        self.consensus_timestamp = _to_datetime(response.consensusTimestamp)
+        self.content_size = len(response.message)
+        self.running_hash = response.runningHash
+        self.sequence_number = response.sequenceNumber
+
+
+class TopicMessage:
+    """
+    Represents a Hedera TopicMessage, possibly composed of multiple chunks.
+    """
+
+    def __init__(
+        self,
+        consensus_timestamp: datetime,
+        message_data: Dict[str, Union[bytes, int]],
+        chunks: List[TopicMessageChunk],
+        transaction_id: Optional[str] = None,
+    ):
+        """
+        Args:
+            consensus_timestamp: The final consensus timestamp.
+            message_data: Dict with required fields:
+                          {
+                              "contents": bytes,
+                              "running_hash": bytes,
+                              "sequence_number": int
+                          }
+            chunks: All individual chunks that form this message.
+            transaction_id: The transaction ID string if available.
+        """
+        self.consensus_timestamp = consensus_timestamp
+        self.contents = message_data["contents"]
+        self.running_hash = message_data["running_hash"]
+        self.sequence_number = message_data["sequence_number"]
+        self.chunks = chunks
+        self.transaction_id = transaction_id
+
+    @classmethod
+    def of_single(cls, response: mirror_proto.ConsensusTopicResponse) -> "TopicMessage":
+        """
+        Build a TopicMessage from a single-chunk response.
+        """
+        chunk = TopicMessageChunk(response)
+        consensus_timestamp = chunk.consensus_timestamp
+        contents = response.message
+        running_hash = response.runningHash
+        sequence_number = chunk.sequence_number
+
+        transaction_id = None
+        if response.HasField("chunkInfo") and response.chunkInfo.HasField("initialTransactionID"):
+            tx_id = response.chunkInfo.initialTransactionID
+            transaction_id = (
+                f"{tx_id.shardNum}.{tx_id.realmNum}.{tx_id.accountNum}-"
+                f"{tx_id.transactionValidStart.seconds}.{tx_id.transactionValidStart.nanos}"
+            )
+
+        return cls(
+            consensus_timestamp,
+            {
+                "contents": contents,
+                "running_hash": running_hash,
+                "sequence_number": sequence_number,
+            },
+            [chunk],
+            transaction_id
+        )
+
+    @classmethod
+    def of_many(cls, responses: List[mirror_proto.ConsensusTopicResponse]) -> "TopicMessage":
+        """
+        Reassemble multiple chunk responses into a single TopicMessage.
+        """
+        sorted_responses = sorted(responses, key=lambda r: r.chunkInfo.number)
+
+        chunks = []
+        total_size = 0
+        transaction_id = None
+
+        for r in sorted_responses:
+            c = TopicMessageChunk(r)
+            chunks.append(c)
+            total_size += len(r.message)
+
+            if (
+                transaction_id is None
+                and r.HasField("chunkInfo")
+                and r.chunkInfo.HasField("initialTransactionID")
+            ):
+                tx_id = r.chunkInfo.initialTransactionID
+                transaction_id = (
+                    f"{tx_id.shardNum}.{tx_id.realmNum}.{tx_id.accountNum}-"
+                    f"{tx_id.transactionValidStart.seconds}.{tx_id.transactionValidStart.nanos}"
+                )
+
+        contents = bytearray(total_size)
+        offset = 0
+        for r in sorted_responses:
+            end = offset + len(r.message)
+            contents[offset:end] = r.message
+            offset = end
+
+        last_r = sorted_responses[-1]
+        consensus_timestamp = _to_datetime(last_r.consensusTimestamp)
+        running_hash = last_r.runningHash
+        sequence_number = last_r.sequenceNumber
+
+        return cls(
+            consensus_timestamp,
+            {
+                "contents": bytes(contents),
+                "running_hash": running_hash,
+                "sequence_number": sequence_number,
+            },
+            chunks,
+            transaction_id
+        )
+
+    @classmethod
+    def from_proto(
+        cls,
+        response_or_responses: Union[mirror_proto.ConsensusTopicResponse, List[mirror_proto.ConsensusTopicResponse]],
+        chunking_enabled: bool = False
+    ) -> "TopicMessage":
+        """
+        Creates a TopicMessage from either:
+         - A single ConsensusTopicResponse
+         - A list of responses (for multi-chunk)
+
+        If chunking is enabled and multiple chunks are detected, they are reassembled
+        into one combined TopicMessage. Otherwise, a single chunk is returned as-is.
+        """
+        if not isinstance(response_or_responses, mirror_proto.ConsensusTopicResponse):
+            if not response_or_responses:
+                raise ValueError("Empty response list provided to from_proto().")
+
+            if not chunking_enabled and len(response_or_responses) == 1:
+                return cls.of_single(response_or_responses[0])
+
+            return cls.of_many(response_or_responses)
+
+        response = response_or_responses
+        if chunking_enabled and response.HasField("chunkInfo") and response.chunkInfo.total > 1:
+            raise ValueError(
+                "Cannot handle multi-chunk in a single response. Pass all chunk responses in a list."
+            )
+        return cls.of_single(response)
+
+    def __str__(self):
+        contents_str = self.contents.decode("utf-8", errors="replace")
+        return (
+            f"TopicMessage("
+            f"consensus_timestamp={self.consensus_timestamp}, "
+            f"sequence_number={self.sequence_number}, "
+            f"contents='{contents_str[:40]}{'...' if len(contents_str) > 40 else ''}', "
+            f"chunk_count={len(self.chunks)}, "
+            f"transaction_id={self.transaction_id}"
+            f")"
+        )

hiero_sdk_python-0.1.0/src/hiero_sdk_python/crypto/private_key.py

@@ -0,0 +1,152 @@
+from cryptography.hazmat.primitives.asymmetric import ed25519, ec
+from cryptography.hazmat.primitives import serialization
+from cryptography.hazmat.backends import default_backend
+from typing import Optional, Union
+from hiero_sdk_python.crypto.public_key import PublicKey
+
+class PrivateKey:
+    """
+    Represents a private key that can be either Ed25519 or ECDSA (secp256k1).
+    """
+
+    def __init__(
+        self, private_key: Union[ec.EllipticCurvePrivateKey, ed25519.Ed25519PrivateKey]):
+        """
+        Initializes a PrivateKey from a cryptography PrivateKey object.
+        """
+        self._private_key = private_key
+
+    @classmethod
+    def from_string(cls, key_str: str) -> "PrivateKey":
+        """
+        Load a private key from a hex-encoded string.
+        - If key_str starts with '0x', that prefix is removed.
+        - Then the remainder is decoded as hex -> bytes.
+        - Calls from_bytes to interpret raw or DER.
+
+        Raises ValueError if the hex is invalid or the bytes are not a valid key.
+        """
+        key_str = key_str.removeprefix("0x")
+
+        try:
+            key_bytes = bytes.fromhex(key_str)
+        except ValueError:
+            raise ValueError(f"Invalid hex string for private key: {key_str}")
+
+        return cls.from_bytes(key_bytes)
+
+    @classmethod
+    def generate(cls, key_type: str = "ed25519"):
+        if key_type.lower() == "ed25519":
+            return cls.generate_ed25519()
+        elif key_type.lower() == "ecdsa":
+            return cls.generate_ecdsa()
+        else:
+            raise ValueError("Invalid key_type. Use 'ed25519' or 'ecdsa'.")
+
+    @classmethod
+    def generate_ed25519(cls):
+        return cls(ed25519.Ed25519PrivateKey.generate())
+
+    @classmethod
+    def generate_ecdsa(cls):
+        private_key = ec.generate_private_key(ec.SECP256K1(), default_backend())
+        return cls(private_key)
+
+    @classmethod
+    def from_bytes(cls, key_bytes: bytes) -> "PrivateKey":
+        """
+        Load a private key from bytes. For Ed25519, expects 32 bytes (raw).
+        For ECDSA (secp256k1), also expects 32 bytes (raw scalar).
+        If the key is DER-encoded, tries to parse Ed25519 vs ECDSA.
+        """
+        if len(key_bytes) == 32:
+            ed_priv = cls._try_load_ed25519(key_bytes)
+            if ed_priv:
+                return cls(ed_priv)
+
+            ec_priv = cls._try_load_ecdsa(key_bytes)
+            if ec_priv:
+                return cls(ec_priv)
+
+        der_key = cls._try_load_der(key_bytes)
+        if der_key:
+            return cls(der_key)
+
+        raise ValueError("Failed to load private key from bytes.")
+
+    @staticmethod
+    def _try_load_ed25519(key_bytes: bytes) -> Optional[ed25519.Ed25519PrivateKey]:
+        try:
+            return ed25519.Ed25519PrivateKey.from_private_bytes(key_bytes)
+        except Exception:
+            return None
+
+    @staticmethod
+    def _try_load_ecdsa(key_bytes: bytes) -> Optional[ec.EllipticCurvePrivateKey]:
+        try:
+            private_int = int.from_bytes(key_bytes, "big")
+            return ec.derive_private_key(private_int, ec.SECP256K1(), default_backend())
+        except Exception:
+            return None
+
+    @staticmethod
+    def _try_load_der(key_bytes: bytes) -> Optional[Union[ed25519.Ed25519PrivateKey, ec.EllipticCurvePrivateKey]]:
+        try:
+            private_key = serialization.load_der_private_key(key_bytes, password=None)
+            if isinstance(private_key, ed25519.Ed25519PrivateKey):
+                return private_key
+            if isinstance(private_key, ec.EllipticCurvePrivateKey):
+                if not isinstance(private_key.curve, ec.SECP256K1):
+                    raise ValueError("Only secp256k1 ECDSA is supported.")
+                return private_key
+            return None
+        except Exception:
+            return None
+
+    def sign(self, data: bytes) -> bytes:
+        return self._private_key.sign(data)
+
+    def public_key(self) -> PublicKey:
+        return PublicKey(self._private_key.public_key())
+
+    def to_bytes_raw(self) -> bytes:
+        if self.is_ed25519():
+            return self._private_key.private_bytes(
+                encoding=serialization.Encoding.Raw,
+                format=serialization.PrivateFormat.Raw,
+                encryption_algorithm=serialization.NoEncryption()
+            )
+        else:
+            return self._private_key.private_numbers().private_value.to_bytes(32, "big")
+
+    def to_string(self) -> str:
+        """
+        Returns the private key as a hex string (raw).
+        Matches old usage that calls to_string().
+        """
+        return self.to_string_raw()
+
+    def to_string_raw(self) -> str:
+        return self.to_bytes_raw().hex()
+
+    def to_bytes_der(self) -> bytes:
+        return self._private_key.private_bytes(
+            encoding=serialization.Encoding.DER,
+            format=serialization.PrivateFormat.PKCS8,
+            encryption_algorithm=serialization.NoEncryption()
+        )
+
+    def to_string_der(self) -> str:
+        return self.to_bytes_der().hex()
+
+    def is_ed25519(self) -> bool:
+        return isinstance(self._private_key, ed25519.Ed25519PrivateKey)
+
+    def is_ecdsa(self) -> bool:
+        return isinstance(self._private_key, ec.EllipticCurvePrivateKey)
+
+    def __repr__(self):
+        if self.is_ed25519():
+            return f"<PrivateKey (Ed25519) hex={self.to_string_raw()}>"
+        return f"<PrivateKey (ECDSA) hex={self.to_string_raw()}>"