Merge pull request #39 from exploreriii/TokenFreezeTransaction

TokenFreezeTransaction

Author: exploreriii

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:

examples/token_create.py

@@ -21,7 +21,8 @@ def create_token():
     admin_key = PrivateKey.from_string(os.getenv('ADMIN_KEY'))
     supply_key = PrivateKey.from_string(os.getenv('ADMIN_KEY')) #Optional
 
-    
+    freeze_key = PrivateKey.from_string(os.getenv('FREEZE_KEY')) #Optional
+
     client.set_operator(operator_id, operator_key)
 
     transaction = (
@@ -33,9 +34,11 @@ def create_token():
         .set_treasury_account_id(operator_id)
         .set_admin_key(admin_key)
         .set_supply_key(supply_key)
+        .set_freeze_key(freeze_key)
         .freeze_with(client)
         .sign(operator_key)
         .sign(admin_key)
+
     )
 
     try:

examples/token_freeze.py

@@ -0,0 +1,48 @@
+import os
+import sys
+from dotenv import load_dotenv
+
+from hedera_sdk_python import (
+    Client,
+    AccountId,
+    PrivateKey,
+    TokenFreezeTransaction,
+    Network,
+    TokenId,
+)
+
+load_dotenv() 
+
+def freeze_token():
+    network = Network(network='testnet')  
+    client = Client(network)
+
+    operator_id = AccountId.from_string(os.getenv('OPERATOR_ID'))
+    operator_key = PrivateKey.from_string(os.getenv('OPERATOR_KEY'))
+    freeze_key = PrivateKey.from_string(os.getenv('FREEZE_KEY'))
+    token_id = TokenId.from_string(os.getenv('TOKEN_ID'))
+    account_id = AccountId.from_string(os.getenv('FREEZE_ACCOUNT_ID'))
+
+    client.set_operator(operator_id, operator_key)
+
+    transaction = (
+        TokenFreezeTransaction()
+        .set_token_id(token_id)
+        .set_account(account_id)
+        .freeze_with(client)
+        .sign(freeze_key)
+    )
+
+    try:
+        receipt = transaction.execute(client)
+        if receipt is not None and receipt.status == 'SUCCESS':
+            print(f"Token freeze successful")
+        else:
+            print(f"Token freeze failed.")
+            sys.exit(1)
+    except Exception as e:
+        print(f"Token freeze failed: {str(e)}")
+        sys.exit(1)
+
+if __name__ == "__main__":
+    freeze_token() 

src/hiero_sdk_python/__init__.py

@@ -16,6 +16,7 @@
 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 @@
     "TokenDissociateTransaction",
     "TokenDeleteTransaction",
     "TokenMintTransaction",
+    "TokenFreezeTransaction",
     "TokenId",
 
     # Transaction

src/hiero_sdk_python/crypto/private_key.py

@@ -3,13 +3,11 @@
 from cryptography.hazmat.backends import default_backend
 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):
+    def __init__(self, private_key: ec.EllipticCurvePrivateKey | ed25519.Ed25519PrivateKey):        
         """
         Initializes a PrivateKey from a cryptography PrivateKey object.
         """

src/hiero_sdk_python/crypto/public_key.py

@@ -5,8 +5,7 @@ class PublicKey:
     """
     Represents a public key that can be either Ed25519 or ECDSA (secp256k1).
     """
-
-    def __init__(self, public_key):
+    def __init__(self, public_key: ec.EllipticCurvePublicKey | ed25519.Ed25519PublicKey):
         """
         Initializes a PublicKey from a cryptography PublicKey object.
         """

src/hiero_sdk_python/tokens/token_create_transaction.py

@@ -15,7 +15,7 @@ class TokenCreateTransaction(Transaction):
     """
 
     def __init__(self, token_name=None, token_symbol=None, decimals=None, initial_supply=None, 
-                 treasury_account_id=None, admin_key=None, supply_key=None):
+                 treasury_account_id=None, admin_key=None, supply_key=None, freeze_key=None):
         """
         Initializes a new TokenCreateTransaction instance with optional keyword arguments.
 
@@ -28,6 +28,7 @@ def __init__(self, token_name=None, token_symbol=None, decimals=None, initial_su
             admin_key (PrivateKey, optional): The admin key for the token.
             supply_key (PrivateKey, optional): The supply key for the token.
 
+            freeze_key (PrivateKey, optional): The freeze key for the token.
         """
         super().__init__()
         self.token_name = token_name
@@ -37,6 +38,7 @@ def __init__(self, token_name=None, token_symbol=None, decimals=None, initial_su
         self.treasury_account_id = treasury_account_id
         self.admin_key = admin_key
         self.supply_key = supply_key
+        self.freeze_key = freeze_key
 
         self._default_transaction_fee = 3_000_000_000
 
@@ -75,6 +77,12 @@ def set_supply_key(self, supply_key):
         self.supply_key = supply_key
         return self
 
+    def set_freeze_key(self, freeze_key): 
+        self._require_not_frozen()
+        self.freeze_key = freeze_key
+        return self
+    
+    
     def build_transaction_body(self):
         """
         Builds and returns the protobuf transaction body for token creation.
@@ -104,14 +112,21 @@ def build_transaction_body(self):
             supply_public_key_bytes = self.supply_key.public_key().to_bytes_raw()
             supply_key_proto = basic_types_pb2.Key(ed25519=supply_public_key_bytes)
 
+        freeze_key_proto = None
+        if self.freeze_key:
+            freeze_public_key_bytes = self.freeze_key.public_key().to_bytes_raw()
+            freeze_key_proto = basic_types_pb2.Key(ed25519=freeze_public_key_bytes)
+
         token_create_body = token_create_pb2.TokenCreateTransactionBody(
             name=self.token_name,
             symbol=self.token_symbol,
             decimals=self.decimals,
             initialSupply=self.initial_supply,
             treasury=self.treasury_account_id.to_proto(),
             adminKey=admin_key_proto,
-            supplyKey=supply_key_proto
+            supplyKey=supply_key_proto,
+            freezeKey=freeze_key_proto
+
         )
 
         transaction_body = self.build_base_transaction_body()

src/hiero_sdk_python/tokens/token_freeze_transaction.py

@@ -0,0 +1,126 @@
+from hiero_sdk_python.transaction.transaction import Transaction
+from hiero_sdk_python.hapi.services import token_freeze_account_pb2
+from hiero_sdk_python.response_code import ResponseCode
+ 
+class TokenFreezeTransaction(Transaction):
+    """
+    Represents a token freeze transaction on the Hedera network.
+
+    This transaction freezes a specified token for a given account.
+
+    Inherits from the base Transaction class and implements the required methods
+    to build and execute a token freeze transaction.
+    """
+
+    def __init__(self, token_id=None, account_id=None):
+        """
+        Initializes a new TokenFreezeTransaction instance with optional token_id and account_id.
+
+        Args:
+            token_id (TokenId, optional): The ID of the token to be frozen.
+            account_id (AccountId, optional): The ID of the account to have their token frozen.
+        """
+        super().__init__()
+        self.token_id = token_id
+        self.account_id = account_id
+        self._default_transaction_fee = 3_000_000_000
+
+    def set_token_id(self, token_id):
+        """
+        Sets the ID of the token to be frozen.
+
+        Args:
+            token_id (TokenId): The ID of the token to be frozen.
+
+        Returns:
+            TokenFreezeTransaction: Returns self for method chaining.
+        """
+        self._require_not_frozen()
+        self.token_id = token_id
+        return self
+    
+    def set_account_id(self, account_id):
+        """
+        Sets the ID of the account to be frozen.
+
+        Args:
+            account_id (AccountId): The ID of the account to have their token frozen.
+
+        Returns:
+            TokenFreezeTransaction: Returns self for method chaining.
+        """
+        self._require_not_frozen()
+        self.account_id = account_id
+        return self
+
+    def build_transaction_body(self):
+        """
+        Builds and returns the protobuf transaction body for token freeze.
+
+        Returns:
+            TransactionBody: The protobuf transaction body containing the token freeze details.
+
+        Raises:
+            ValueError: If the token ID is missing.
+            ValueError: If the account ID is missing.
+        """
+
+        if not self.token_id:
+            raise ValueError("Missing required TokenID.")
+        
+        if not self.account_id:
+            raise ValueError("Missing required AccountID.")
+
+        token_freeze_body = token_freeze_account_pb2.TokenFreezeAccountTransactionBody(
+            token=self.token_id.to_proto(),
+            account=self.account_id.to_proto()
+        )
+
+        transaction_body = self.build_base_transaction_body()
+        transaction_body.tokenFreeze.CopyFrom(token_freeze_body)
+
+        return transaction_body
+
+    def _execute_transaction(self, client, transaction_proto):
+        """
+        Executes the token freeze transaction using the provided client.
+
+        Args:
+            client (Client): The client instance to use for execution.
+            transaction_proto (Transaction): The protobuf Transaction message.
+
+        Returns:
+            TransactionReceipt: The receipt from the network after transaction execution.
+
+        Raises:
+            Exception: If the transaction submission fails or receives an error response.
+        """
+        response = client.token_stub.freezeTokenAccount(transaction_proto)
+
+        if response.nodeTransactionPrecheckCode != ResponseCode.OK:
+            error_code = response.nodeTransactionPrecheckCode
+            error_message = ResponseCode.get_name(error_code)
+            raise Exception(f"Error during transaction submission: {error_code} ({error_message})")
+
+        receipt = self.get_receipt(client)
+        return receipt
+
+    def get_receipt(self, client, timeout=60):
+        """
+        Retrieves the receipt for the transaction.
+
+        Args:
+            client (Client): The client instance.
+            timeout (int): Maximum time in seconds to wait for the receipt.
+
+        Returns:
+            TransactionReceipt: The transaction receipt from the network.
+
+        Raises:
+            Exception: If the transaction ID is not set or if receipt retrieval fails.
+        """
+        if self.transaction_id is None:
+            raise Exception("Transaction ID is not set.")
+
+        receipt = client.get_transaction_receipt(self.transaction_id, timeout)
+        return receipt