feat: Adding in TokenUnfreezeTransaction (#54)

* Add tokenUnfreezeTransaction functionality

Signed-off-by: Angelina <[email protected]>

* Correct import name to hiero

Signed-off-by: Angelina <[email protected]>

* Corrected issues pertaining to testing

Signed-off-by: Angelina <[email protected]>

* Correcting typo

Signed-off-by: Angelina <[email protected]>

* correct token and account typo

Signed-off-by: Angelina <[email protected]>

* Correct typos for token ID

Signed-off-by: Angelina <[email protected]>

* fix: Token ID typos

Signed-off-by: Angelina <[email protected]>

* Typo and order corrections

Signed-off-by: Angelina <[email protected]>

* typo

Signed-off-by: Angelina <[email protected]>

* correct account_id

Signed-off-by: Angelina <[email protected]>

* fix: Correct Readmes and transaction

Signed-off-by: Angelina <[email protected]>

* Delete uv.lock

File meant to be ignored 

Signed-off-by: aceppaluni <[email protected]>

* fix: correct sync issues from merge

Signed-off-by: Angelina <[email protected]>

---------

Signed-off-by: Angelina <[email protected]>
Signed-off-by: aceppaluni <[email protected]>

Author: aceppaluni

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, Freeze & Delete
+- Manage Token Transactions like Create, Mint Fungible, Mint Non-Fungible, Associate, Dissociate, Transfer, Freeze, Unfreeze & Delete
 - Manage Consensus Transactions like Topic Create, Update, Delete
 - Submit Topic Messages
 - Query Account Balance, Transaction Receipts, Topic Infos and Messages
@@ -134,6 +134,7 @@ Token dissociation successful.
 Token minting successful.
 Token transfer successful.
 Token freeze successful.
+Token Unfreeze successful.
 Token deletion successful.
 Topic creation successful.
 Topic Message submitted.

examples/README.md

@@ -22,6 +22,7 @@ You can choose either syntax or even mix both styles in your projects.
   - [Transferring Tokens](#transferring-tokens)
   - [Deleting a Token](#deleting-a-token)
   - [Freezing a Token](#freezing-a-token)
+  - [Unfreezing a Token](#unfreezing-a-token)
 - [HBAR Transactions](#hbar-transactions)
   - [Transferring HBAR](#transferring-hbar)
 - [Topic Transactions](#topic-transactions)
@@ -309,6 +310,28 @@ transaction.execute(client)
     transaction.sign(freeze_key) # Freeze key must also have been set in Token Create
     transaction.execute(client)
 ```
+### Unfreezing a Token
+
+#### Pythonic Syntax:
+```
+transaction = TokenUnfreezeTransaction(
+    token_id=token_id
+    account_id=account_id
+).freeze_with(client)
+transaction.sign(freeze_key)
+transaction.execute(client)
+```
+#### Method Chaining:
+```
+transaction = (
+        TokenUnfreezeTransaction()
+        .set_token_id(token_id)
+        .set_account_id(account_id)
+        .freeze_with(client)
+    )
+    transaction.sign(freeze_key)
+    transaction.execute(client)
+```
 
 ## HBAR Transactions
 

examples/token_unfreeze.py

@@ -0,0 +1,47 @@
+import os 
+import sys 
+from dotenv import load_dotenv
+
+from hiero_sdk_python.client.client import Client
+from hiero_sdk_python.account.account_id import AccountId
+from hiero_sdk_python.crypto.private_key import PrivateKey
+from hiero_sdk_python.client.network import Network 
+from hiero_sdk_python.tokens.token_id import TokenId 
+from hiero_sdk_python.tokens.token_unfreeze_transaction import TokenUnfreezeTransaction
+
+load_dotenv()
+
+def unfreeze_token(): # Single 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 = (
+        TokenUnfreezeTransaction()
+        .set_token_id(token_id)
+        .set_account_id(account_id)
+        .freeze_with(client)
+        .sign(freeze_key)
+    )
+
+    try:
+        receipt = transaction.execute(client)
+        if receipt is not None and receipt.status == "SUCCESS":
+            print('Token unfreeze Successful')
+        else: 
+            print("Token freeze failed.")
+            sys.exit(1)
+    except Exception as e:
+        print(f"Token unfreeze failed: {str(e)}")
+        sys.exit(1)
+
+
+if __name__ == "__main__":
+    unfreeze_token() # For single token unfreeze

src/hiero_sdk_python/__init__.py

@@ -17,6 +17,7 @@
 from .tokens.token_delete_transaction import TokenDeleteTransaction
 from .tokens.token_mint_transaction import TokenMintTransaction
 from .tokens.token_freeze_transaction import TokenFreezeTransaction
+from .tokens.token_unfreeze_transaction import TokenUnfreezeTransaction
 from .tokens.token_id import TokenId
 from .tokens.nft_id import NftId
 
@@ -70,6 +71,7 @@
     "TokenDeleteTransaction",
     "TokenMintTransaction",
     "TokenFreezeTransaction",
+    "TokenUnfreezeTransaction",
     "TokenId",
     "NftId",
 

src/hiero_sdk_python/tokens/token_unfreeze_transaction.py

@@ -0,0 +1,86 @@
+from hiero_sdk_python.transaction.transaction import Transaction 
+from hiero_sdk_python.hapi.services import token_unfreeze_account_pb2
+from hiero_sdk_python.response_code import ResponseCode
+
+class TokenUnfreezeTransaction(Transaction):
+    """
+    Represents a token unfreeze transaction on the Hedera network.
+    
+    This transaction unfreezes specified tokens for a given account.
+    
+    Inherits from the base Transaction class and implements the required methods
+    to build and execute a token unfreeze transaction.
+    """
+
+    def __init__(self, account_id=None, token_id=None):
+        """
+        Initializes a new TokenUnfreezeTransaction instance with default values.
+        """
+        super().__init__()
+        self.token_id = token_id
+        self.account_id = account_id
+        self._default_transaction_fee = 3_000_000_000
+        self._is_frozen = False 
+    
+    def set_token_id(self, token_id):
+        self.__require_not_frozen()
+        self.token_id = token_id
+        return self
+    
+    def set_account_id(self, account_id):
+        self.__require_not_frozen()
+        self.account_id = account_id
+        return self
+    
+    def __require_not_frozen(self): 
+        if self._is_frozen:
+            raise ValueError("Transaction is already frozen and cannot be modified.")
+
+    def build_transaction_body(self):
+        """
+        Builds and returns the protobuf transaction body for token unfreeze.
+
+        Returns:
+            TransactionBody: The protobuf transaction body containing the token unfreeze details.
+        
+        Raises:
+            ValueError: If account ID or token IDs are not set.
+        
+        """
+        if not self.token_id:
+            raise ValueError("Missing required TokenID.")
+
+        if not self.account_id:
+            raise ValueError("Missing required AccountID.")
+        
+        token_unfreeze_body = token_unfreeze_account_pb2.TokenUnfreezeAccountTransactionBody(
+            account=self.account_id.to_proto(),
+            token=self.token_id.to_proto()
+        )
+
+        transaction_body = self.build_base_transaction_body()
+        transaction_body.tokenUnfreeze.CopyFrom(token_unfreeze_body)
+
+        return transaction_body
+    
+    def _execute_transaction(self, client, transaction_proto):
+        """
+        Executes the token unfreeze 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.unfreezeTokenAccount(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
+    

test.py

@@ -52,6 +52,8 @@
 from hiero_sdk_python.transaction.transfer_transaction import TransferTransaction
 
 # Topic related imports
+from hiero_sdk_python.tokens.token_unfreeze_transaction import TokenUnfreezeTransaction
+from hiero_sdk_python.response_code import ResponseCode
 from hiero_sdk_python.consensus.topic_create_transaction import TopicCreateTransaction
 from hiero_sdk_python.consensus.topic_message_submit_transaction import (
     TopicMessageSubmitTransaction
@@ -309,6 +311,24 @@ def freeze_token(client, token_id, account_id, freeze_key):
         print(traceback.format_exc())
         sys.exit(1)
 
+def unfreeze_token(client, token_id_1, recipient_id, freeze_key):
+    """Unfreeze the specified token with the given account."""
+    transaction =  TokenUnfreezeTransaction(account_id=recipient_id, token_id=token_id_1)
+
+    transaction.freeze_with(client)
+    transaction.sign(client.operator_private_key)
+    transaction.sign(freeze_key)
+
+    try:
+        receipt = transaction.execute(client)
+        if receipt.status != ResponseCode.SUCCESS:
+            status_message = ResponseCode.get_name(receipt.status)
+            raise Exception(f"Token unfreeze failed with status: {status_message}")
+        print("Token unfreeze successful.")
+    except Exception as e:
+        print(f"Token unfreeze failed: {str(e)}")
+        sys.exit(1)
+
 def mint_fungible_token(client, token_id, supply_key, amount=2000):
     """Tests fungible token minting"""
     transaction = TokenMintTransaction(token_id=token_id, amount=amount)
@@ -496,6 +516,10 @@ def main():
     freeze_token(client, token_id_1, recipient_id, freeze_key)
     freeze_token(client, token_id_nft_1, recipient_id, freeze_key)
 
+    # Test unfreezing fungible and nft tokens. In this case from the recipient that just received token 1.
+    unfreeze_token(client, token_id_1, recipient_id, freeze_key)
+    unfreeze_token(client, token_id_nft_1, recipient_id, freeze_key)
+
     # Test dissociating a fungible and nft token. In this case the tokens that were not transferred or frozen.
     dissociate_token(client, recipient_id, recipient_private_key, [token_id_2])
     dissociate_token(client, recipient_id, recipient_private_key, [token_id_nft_2])

tests/test_token_unfreeze_transaction.py

@@ -0,0 +1,105 @@
+import pytest
+from unittest.mock import MagicMock
+from hiero_sdk_python.tokens.token_unfreeze_transaction import TokenUnfreezeTransaction
+from hiero_sdk_python.hapi.services import timestamp_pb2
+from hiero_sdk_python.transaction.transaction_id import TransactionId
+
+def generate_transaction_id(account_id_proto):
+    """Generate a unique transaction ID based on the account ID and the current timestamp."""
+
+    import time
+    current_time = time.time()
+    timestamp_seconds = int(current_time)
+    timestamp_nanos = int((current_time - timestamp_seconds) * 1e9)
+
+    tx_timestamp = timestamp_pb2.Timestamp(seconds=timestamp_seconds, nanos=timestamp_nanos)
+    tx_id = TransactionId(
+        valid_start=tx_timestamp,
+        account_id=account_id_proto
+    )
+
+    return tx_id
+
+def test_build_transaction_body(mock_account_ids):
+    """Test building the token unfreeze transaction body with valid account ID and token ID."""
+
+    account_id, freeze_id, node_account_id, token_id, _= mock_account_ids
+
+    unfreeze_tx = TokenUnfreezeTransaction()
+    unfreeze_tx.set_token_id(token_id)
+    unfreeze_tx.set_account_id(freeze_id)
+    unfreeze_tx.transaction_id = generate_transaction_id(account_id)
+    unfreeze_tx.node_account_id = node_account_id
+    transaction_body = unfreeze_tx.build_transaction_body()
+
+    assert transaction_body.tokenUnfreeze.token.shardNum == 1
+    assert transaction_body.tokenUnfreeze.token.realmNum == 1
+    assert transaction_body.tokenUnfreeze.token.tokenNum == 1
+
+    proto_account = freeze_id.to_proto()
+    assert transaction_body.tokenUnfreeze.account == proto_account
+
+def test_missing_token_id(mock_account_ids):
+    """Test that building a transaction without setting 
+    TokenID raises a ValueError."""
+
+    account_id, freeze_id, node_account_id, token_id, _= mock_account_ids
+
+
+    unfreeze_tx = TokenUnfreezeTransaction()
+    unfreeze_tx.set_account_id(freeze_id) 
+    with pytest.raises(ValueError,match = "Missing required TokenID."):
+        unfreeze_tx.build_transaction_body()
+
+def test_missing_account_id(mock_account_ids):
+    """Test that building a transaction without setting AccountID raises a ValueError."""
+    account_id, freeze_id, node_account_id, token_id, _= mock_account_ids
+
+    unfreeze_tx = TokenUnfreezeTransaction()
+    unfreeze_tx.set_token_id(token_id)
+    with pytest.raises(ValueError, match="Missing required AccountID."):
+        unfreeze_tx.build_transaction_body()
+
+def test_sign_transaction(mock_account_ids):
+    """Test signing the token unfreeze transaction with a freeze key."""
+
+    account_id, freeze_id, node_account_id, token_id, _= mock_account_ids
+
+    unfreeze_tx = TokenUnfreezeTransaction()
+    unfreeze_tx.set_token_id(token_id)
+    unfreeze_tx.set_account_id(freeze_id)
+    unfreeze_tx.transaction_id = generate_transaction_id(account_id)
+    unfreeze_tx.node_account_id = node_account_id
+
+    freeze_key = MagicMock()
+    freeze_key.sign.return_value = b'signature'
+    freeze_key.public_key().to_bytes_raw.return_value = b'public_key'
+
+    unfreeze_tx.sign(freeze_key)
+
+    assert len(unfreeze_tx.signature_map.sigPair) == 1
+    sig_pair = unfreeze_tx.signature_map.sigPair[0]
+
+    assert sig_pair.pubKeyPrefix == b'public_key'
+    assert sig_pair.ed25519 == b'signature'
+
+def test_to_proto(mock_account_ids):
+    """Test converting the token unfreeze transaction to protobuf format after signing."""
+
+    account_id, freeze_id, node_account_id, token_id, _= mock_account_ids
+
+    unfreeze_tx = TokenUnfreezeTransaction()
+    unfreeze_tx.set_token_id(token_id)
+    unfreeze_tx.set_account_id(freeze_id)
+    unfreeze_tx.transaction_id = generate_transaction_id(account_id)
+    unfreeze_tx.node_account_id = node_account_id
+
+    freeze_key = MagicMock()
+    freeze_key.sign.return_value = b'signature'
+    freeze_key.public_key().to_bytes_raw.return_value = b'mock_pubkey'
+
+    unfreeze_tx.sign(freeze_key)
+    proto = unfreeze_tx.to_proto()
+
+    assert proto.signedTransactionBytes
+    assert len(proto.signedTransactionBytes) > 0