feat: add nft transfer in TransferTransaction (#99)

* feat: add serial_numbers property to TransactionReceipt

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

* feat: add _TokenNftTransfer class

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

* test: add unit test for _TokenNftTransfer

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

* feat: add nft_trasfers to TransferTransaction class

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

* docs: update docstring in TransferTransaction

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

* test: fix unit tests

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

* test: migrate token transfer integration test to transfer_transaction_e2e_test.py and add more tests

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

* docs: add transfer_nft.py example

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

* docs: add transferring NFTs documentation in README

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

* refactor: reduce cyclomatic complexity in TransferTransaction

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

* test: remove unnecessary freeze_with() and add new tests in transfer_transaction_e2e_test.py

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

* refactor: make _TokenNftTransfer class public

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

* fix: update instances/imports of TokenNftTransfer where necessary

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

* chore: add missing classes in  __init__.py exports

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

* revert: remove Duration from __all__

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

---------

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

Author: Dosik13

examples/README.md

@@ -20,6 +20,7 @@ You can choose either syntax or even mix both styles in your projects.
   - [Associating a Token](#associating-a-token)
   - [Dissociating a Token](#dissociating-a-token)
   - [Transferring Tokens](#transferring-tokens)
+  - [Transferring NFTs](#transferring-nfts)
   - [Wiping Tokens](#wiping-tokens)
   - [Deleting a Token](#deleting-a-token)
   - [Freezing a Token](#freezing-a-token)
@@ -262,6 +263,38 @@ transaction.execute(client)
     transaction.execute(client)
 ```
 
+### Transferring NFTs
+
+#### Pythonic Syntax:
+```
+transaction = TransferTransaction(
+    nft_transfers={
+        token_id: [
+            (
+                operator_id,
+                recipient_id,
+                serial_number
+            )
+        ]
+    }
+).freeze_with(client)
+
+transaction.sign(operator_key)
+transaction.execute(client)
+
+```
+#### Method Chaining:
+```
+    transaction = (
+        TransferTransaction()
+        .add_nft_transfer(nft_id, operator_id, recipient_id)
+        .freeze_with(client)
+        .sign(operator_key)
+    )
+
+    transaction.execute(client)
+```
+
 ### Wiping tokens
 
 #### Pythonic Syntax:

examples/transfer_nft.py

@@ -0,0 +1,165 @@
+import os
+import sys
+from dotenv import load_dotenv
+
+from hiero_sdk_python import (
+    Client,
+    AccountId,
+    PrivateKey,
+    Network,
+    TransferTransaction,
+)
+from hiero_sdk_python.account.account_create_transaction import AccountCreateTransaction
+from hiero_sdk_python.hapi.services.basic_types_pb2 import TokenType
+from hiero_sdk_python.hbar import Hbar
+from hiero_sdk_python.response_code import ResponseCode
+from hiero_sdk_python.tokens.nft_id import NftId
+from hiero_sdk_python.tokens.supply_type import SupplyType
+from hiero_sdk_python.tokens.token_associate_transaction import TokenAssociateTransaction
+from hiero_sdk_python.tokens.token_create_transaction import TokenCreateTransaction
+from hiero_sdk_python.tokens.token_mint_transaction import TokenMintTransaction
+
+load_dotenv()
+
+def setup_client():
+    """Initialize and set up the client with operator account"""
+    # Initialize network and client
+    network = Network(network='testnet')
+    client = Client(network)
+
+    # Set up operator account
+    operator_id = AccountId.from_string(os.getenv('OPERATOR_ID'))
+    operator_key = PrivateKey.from_string(os.getenv('OPERATOR_KEY'))
+    client.set_operator(operator_id, operator_key)
+    
+    return client, operator_id, operator_key
+
+def create_test_account(client):
+    """Create a new account for testing"""
+    # Generate private key for new account
+    new_account_private_key = PrivateKey.generate()
+    new_account_public_key = new_account_private_key.public_key()
+    
+    # Create new account with initial balance of 1 HBAR
+    transaction = (
+        AccountCreateTransaction()
+        .set_key(new_account_public_key)
+        .set_initial_balance(Hbar(1))
+        .freeze_with(client)
+    )
+    
+    receipt = transaction.execute(client)
+    
+    # Check if account creation was successful
+    if receipt.status != ResponseCode.SUCCESS:
+        print(f"Account creation failed with status: {ResponseCode.get_name(receipt.status)}")
+        sys.exit(1)
+    
+    # Get account ID from receipt
+    account_id = receipt.accountId
+    print(f"New account created with ID: {account_id}")
+    
+    return account_id, new_account_private_key
+
+def create_nft(client, operator_id, operator_key):
+    """Create a non-fungible token"""
+    transaction = (
+        TokenCreateTransaction()
+        .set_token_name("MyExampleNFT")
+        .set_token_symbol("EXNFT")
+        .set_decimals(0)
+        .set_initial_supply(0)
+        .set_treasury_account_id(operator_id)
+        .set_token_type(TokenType.NON_FUNGIBLE_UNIQUE)
+        .set_supply_type(SupplyType.FINITE)
+        .set_max_supply(100)
+        .set_admin_key(operator_key)
+        .set_supply_key(operator_key)
+        .set_freeze_key(operator_key)
+        .freeze_with(client)
+    )
+    
+    receipt = transaction.execute(client)
+    
+    # Check if nft creation was successful
+    if receipt.status != ResponseCode.SUCCESS:
+        print(f"NFT creation failed with status: {ResponseCode.get_name(receipt.status)}")
+        sys.exit(1)
+    
+    # Get token ID from receipt
+    nft_token_id = receipt.tokenId
+    print(f"NFT created with ID: {nft_token_id}")
+    
+    return nft_token_id
+
+def mint_nft(client, nft_token_id, operator_key):
+    """Mint a non-fungible token"""
+    transaction = (
+        TokenMintTransaction()
+        .set_token_id(nft_token_id)
+        .set_metadata(b"My NFT Metadata 1")
+        .freeze_with(client)
+    )
+
+    receipt = transaction.execute(client)
+    
+    if receipt.status != ResponseCode.SUCCESS:
+        print(f"NFT minting failed with status: {ResponseCode.get_name(receipt.status)}")
+        sys.exit(1)
+    
+    print(f"NFT minted with serial number: {receipt.serial_numbers[0]}")
+    
+    return NftId(nft_token_id, receipt.serial_numbers[0])
+
+def associate_nft(client, account_id, token_id, account_private_key):
+    """Associate a non-fungible token with an account"""
+    # Associate the token_id with the new account
+    associate_transaction = (
+        TokenAssociateTransaction()
+        .set_account_id(account_id)
+        .add_token_id(token_id)
+        .freeze_with(client)
+        .sign(account_private_key) # Has to be signed by new account's key
+    )
+    
+    receipt = associate_transaction.execute(client)
+    
+    if receipt.status != ResponseCode.SUCCESS:
+        print(f"NFT association failed with status: {ResponseCode.get_name(receipt.status)}")
+        sys.exit(1)
+    
+    print("NFT successfully associated with account")
+
+def transfer_nft():
+    """
+    Demonstrates the nft transfer functionality by:
+    1. Creating a new account
+    2. Creating a nft
+    3. Minting a nft
+    4. Associating the nft with the new account
+    5. Transferring the nft to the new account
+    """
+    client, operator_id, operator_key = setup_client()
+    account_id, new_account_private_key = create_test_account(client)
+    token_id = create_nft(client, operator_id, operator_key)
+    nft_id = mint_nft(client, token_id, operator_key)
+    associate_nft(client, account_id, token_id, new_account_private_key)
+    
+    # Transfer nft to the new account
+    transfer_transaction = (
+        TransferTransaction()
+        .add_nft_transfer(nft_id, operator_id, account_id)
+        .freeze_with(client)
+    )
+    
+    receipt = transfer_transaction.execute(client)
+    
+    # Check if nft transfer was successful
+    if receipt.status != ResponseCode.SUCCESS:
+        print(f"NFT transfer failed with status: {ResponseCode.get_name(receipt.status)}")
+        sys.exit(1)
+    
+    print(f"Successfully transferred NFT to account {account_id}")
+
+if __name__ == "__main__":
+    transfer_nft()

src/hiero_sdk_python/__init__.py

@@ -18,13 +18,16 @@
 from .tokens.token_mint_transaction import TokenMintTransaction
 from .tokens.token_freeze_transaction import TokenFreezeTransaction
 from .tokens.token_unfreeze_transaction import TokenUnfreezeTransaction
+from .tokens.token_wipe_transaction import TokenWipeTransaction
 from .tokens.token_id import TokenId
 from .tokens.nft_id import NftId
+from .tokens.token_nft_transfer import TokenNftTransfer
 
 # Transaction
 from .transaction.transfer_transaction import TransferTransaction
 from .transaction.transaction_id import TransactionId
 from .transaction.transaction_receipt import TransactionReceipt
+from .transaction.transaction_response import TransactionResponse
 
 # Response / Codes
 from .response_code import ResponseCode
@@ -51,6 +54,15 @@
 from .query.transaction_get_receipt_query import TransactionGetReceiptQuery
 from .query.account_balance_query import CryptoGetAccountBalanceQuery
 
+# Address book
+from .address_book.endpoint import Endpoint
+from .address_book.node_address import NodeAddress
+
+# Logger
+from .logger.logger import Logger
+from .logger.log_level import LogLevel
+
+
 __all__ = [
     # Client
     "Client",
@@ -72,13 +84,16 @@
     "TokenMintTransaction",
     "TokenFreezeTransaction",
     "TokenUnfreezeTransaction",
+    "TokenWipeTransaction",
     "TokenId",
     "NftId",
+    "TokenNftTransfer",
 
     # Transaction
     "TransferTransaction",
     "TransactionId",
     "TransactionReceipt",
+    "TransactionResponse",
 
     # Response
     "ResponseCode",
@@ -95,8 +110,18 @@
     "TopicMessageQuery",
     "TransactionGetReceiptQuery",
     "CryptoGetAccountBalanceQuery",
-
+    
+    # Address book
+    "Endpoint",
+    "NodeAddress",
+    
+    # Logger
+    "Logger",
+    "LogLevel",
+
+    # HBAR
     "Hbar",
-    "ResponseCode",
+    
+    # Timestamp
     "Timestamp"
 ]

src/hiero_sdk_python/tokens/token_nft_transfer.py

@@ -0,0 +1,48 @@
+from hiero_sdk_python.account.account_id import AccountId
+from hiero_sdk_python.hapi.services import basic_types_pb2
+
+class TokenNftTransfer:
+    """
+    Represents a transfer of a non-fungible token (NFT) from one account to another.
+    
+    This class encapsulates the details of an NFT transfer, including the sender,
+    receiver, serial number of the NFT, and whether the transfer is approved.
+    """
+    
+    def __init__(self, sender_id, receiver_id, serial_number, is_approved=False):
+        """
+        Initializes a new TokenNftTransfer instance.
+        
+        Args:
+            sender_id (AccountId): The account ID of the sender.
+            receiver_id (AccountId): The account ID of the receiver.
+            serial_number (int): The serial number of the NFT being transferred.
+            is_approved (bool, optional): Whether the transfer is approved. Defaults to False.
+        """
+        self.sender_id : AccountId = sender_id
+        self.receiver_id : AccountId = receiver_id
+        self.serial_number : int = serial_number
+        self.is_approved : bool = is_approved
+        
+    def to_proto(self):
+        """
+        Converts this TokenNftTransfer instance to its protobuf representation.
+        
+        Returns:
+            NftTransfer: The protobuf representation of this NFT transfer.
+        """
+        return basic_types_pb2.NftTransfer(
+            senderAccountID=self.sender_id.to_proto(),
+            receiverAccountID=self.receiver_id.to_proto(),
+            serialNumber=self.serial_number,
+            is_approval=self.is_approved
+        )
+    
+    def __str__(self):
+        """
+        Returns a string representation of this TokenNftTransfer instance.
+        
+        Returns:
+            str: A string representation of this NFT transfer.
+        """
+        return f"TokenNftTransfer(sender_id={self.sender_id}, receiver_id={self.receiver_id}, serial_number={self.serial_number}, is_approved={self.is_approved})"

src/hiero_sdk_python/transaction/transaction_receipt.py

@@ -64,6 +64,16 @@ def accountId(self):
         else:
             return None
 
+    @property
+    def serial_numbers(self):
+        """
+        Retrieves the serial numbers associated with the transaction receipt, if available.
+        
+        Returns:
+            list of int: The serial numbers if present; otherwise, an empty list.
+        """
+        return self._receipt_proto.serialNumbers
+
     def to_proto(self):
         """
         Returns the underlying protobuf transaction receipt.