feat: add TokenUpdateNftsTransaction (#108)

* feat: add metadata_key attribute to TokenCreateTransaction

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

* feat: implement TokenUpdateNftsTransaction class

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

* test: add integration tests for TokenUpdateNftsTransaction

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

* test: add unit tests for TokenUpdateNftsTransaction

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

* docs: add token update nfts example

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

* docs: add token update nfts transaction documentation to README

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

* chore: add TokenUpdateNftsTransaction to __init__.py

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

* test: add wipe_key and metadata_key to TokenCreateTransaction unit tests

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

* test: add integration test for NFT metadata update failure on unminted serials

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

* test: address PR comments for TokenUpdateNftsTransaction integration tests

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

* refactor: simplify TokenUpdateNftsTransactionBody construction with direct initialization

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

* docs: simplify token update nfts example

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

---------

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

Author: Dosik13

examples/README.md

@@ -27,6 +27,7 @@ You can choose either syntax or even mix both styles in your projects.
   - [Unfreezing a Token](#unfreezing-a-token)
   - [Rejecting a Token](#rejecting-a-token)
   - [Rejecting a Non-Fungible Token](#rejecting-a-non-fungible-token)
+  - [Token Update NFTs](#token-update-nfts)
   - [Querying NFT Info](#querying-nft-info)
 - [HBAR Transactions](#hbar-transactions)
   - [Transferring HBAR](#transferring-hbar)
@@ -448,6 +449,35 @@ transaction.execute(client)
     transaction.execute(client)
 ```
 
+### Token Update NFTs
+
+#### Pythonic Syntax:
+```
+transaction = TokenUpdateNftsTransaction(
+    token_id=nft_token_id,
+    serial_numbers=serial_numbers,
+    metadata=new_metadata
+).freeze_with(client)
+
+transaction.sign(metadata_key)
+transaction.execute(client)
+
+```
+#### Method Chaining:
+```
+    transaction = (
+        TokenUpdateNftsTransaction()
+        .set_token_id(nft_token_id)
+        .set_serial_numbers(serial_numbers) 
+        .set_metadata(new_metadata)
+        .freeze_with(client)
+        .sign(metadata_key)
+    )
+
+    transaction.execute(client)
+
+```
+
 ### Querying NFT Info
 
 #### Pythonic Syntax:

examples/token_update_nfts.py

@@ -0,0 +1,153 @@
+import os
+import sys
+from dotenv import load_dotenv
+
+from hiero_sdk_python import (
+    Client,
+    AccountId,
+    PrivateKey,
+    Network,
+)
+from hiero_sdk_python.hapi.services.basic_types_pb2 import TokenType
+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_create_transaction import TokenCreateTransaction
+from hiero_sdk_python.tokens.token_mint_transaction import TokenMintTransaction
+from hiero_sdk_python.tokens.token_update_nfts_transaction import TokenUpdateNftsTransaction
+from hiero_sdk_python.query.token_nft_info_query import TokenNftInfoQuery
+
+load_dotenv()
+
+def setup_client():
+    """Initialize and set up the client with operator account"""
+    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'))
+    client.set_operator(operator_id, operator_key)
+    
+    return client, operator_id, operator_key
+
+def create_nft(client, operator_id, operator_key, metadata_key):
+    """Create a non-fungible token"""
+    receipt = (
+        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_freeze_key(operator_key)
+        .set_supply_key(operator_key)
+        .set_metadata_key(metadata_key)  # Needed to update NFTs
+        .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_nfts(client, nft_token_id, metadata_list):
+    """Mint a non-fungible token"""
+    receipt = (
+        TokenMintTransaction()
+        .set_token_id(nft_token_id)
+        .set_metadata(metadata_list)
+        .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 numbers: {receipt.serial_numbers}")
+    
+    return [NftId(nft_token_id, serial_number) for serial_number in receipt.serial_numbers], receipt.serial_numbers
+
+def get_nft_info(client, nft_id):
+    """Get information about an NFT"""
+    info = (
+        TokenNftInfoQuery()
+        .set_nft_id(nft_id)
+        .execute(client)
+    )
+    
+    return info
+
+def update_nft_metadata(client, nft_token_id, serial_numbers, new_metadata, metadata_private_key):
+    """Update metadata for NFTs in a collection"""
+    receipt = (
+        TokenUpdateNftsTransaction()
+        .set_token_id(nft_token_id)
+        .set_serial_numbers(serial_numbers) 
+        .set_metadata(new_metadata)
+        .freeze_with(client)
+        .sign(metadata_private_key)  # Has to be signed here by metadata_key
+        .execute(client)
+    )
+
+    if receipt.status != ResponseCode.SUCCESS:
+        print(f"NFT metadata update failed with status: {ResponseCode.get_name(receipt.status)}")
+        sys.exit(1)
+
+    print(f"Successfully updated metadata for NFTs with serial numbers: {serial_numbers}")
+
+def token_update_nfts():
+    """
+    Demonstrates the NFT token update functionality by:
+    1. Setting up client with operator account
+    2. Creating a non-fungible token with metadata key
+    3. Minting two NFTs with initial metadata
+    4. Checking the current NFT info
+    5. Updating metadata for the first NFT
+    6. Verifying the updated NFT metadata
+    """
+    client, operator_id, operator_key = setup_client()
+    
+    # Create metadata key
+    metadata_private_key = PrivateKey.generate_ed25519()
+    
+    # Create a new NFT collection with the treasury account as owner
+    nft_token_id = create_nft(client, operator_id, operator_key, metadata_private_key)
+    
+    # Initial metadata for our NFTs
+    initial_metadata = [b"Initial metadata 1", b"Initial metadata 2"]
+    
+    # New metadata to update the first NFT
+    new_metadata = b"Updated metadata1"
+    
+    # Mint 2 NFTs in the collection with initial metadata
+    nft_ids, serial_numbers = mint_nfts(client, nft_token_id, initial_metadata)
+    
+    # Get and print information about the NFTs
+    print("\nCheck that the NFTs have the initial metadata")
+    for nft_id in nft_ids:
+        nft_info = get_nft_info(client, nft_id)
+        print(f"NFT ID: {nft_info.nft_id}, Metadata: {nft_info.metadata}")
+    
+    # Update metadata for specific NFTs by providing their id and serial numbers
+    # Only the NFTs with the provided serial numbers will have their metadata updated
+    serial_numbers_to_update = [serial_numbers[0]]
+    update_nft_metadata(client, nft_token_id, serial_numbers_to_update, new_metadata, metadata_private_key)
+    
+    # Get and print information about the NFTs
+    print("\nCheck that only the first NFT has the updated metadata")
+    for nft_id in nft_ids:
+        nft_info = get_nft_info(client, nft_id)
+        print(f"NFT ID: {nft_info.nft_id}, Metadata: {nft_info.metadata}")
+    
+if __name__ == "__main__":
+    token_update_nfts()

src/hiero_sdk_python/__init__.py

@@ -21,6 +21,7 @@
 from .tokens.token_unfreeze_transaction import TokenUnfreezeTransaction
 from .tokens.token_wipe_transaction import TokenWipeTransaction
 from .tokens.token_reject_transaction import TokenRejectTransaction
+from .tokens.token_update_nfts_transaction import TokenUpdateNftsTransaction
 from .tokens.token_id import TokenId
 from .tokens.nft_id import NftId
 from .tokens.token_nft_transfer import TokenNftTransfer
@@ -95,6 +96,7 @@
     "TokenNftTransfer",
     "TokenNftInfo",
     "TokenRejectTransaction",
+    "TokenUpdateNftsTransaction",
 
     # Transaction
     "TransferTransaction",

src/hiero_sdk_python/tokens/token_create_transaction.py

@@ -178,12 +178,14 @@ class TokenKeys:
         supply_key: The supply key for the token to mint and burn.
         freeze_key: The freeze key for the token to freeze and unfreeze.
         wipe_key: The wipe key for the token to wipe tokens from an account.
+        metadata_key: The metadata key for the token to update NFT metadata.
     """
 
     admin_key: Optional[PrivateKey] = None
     supply_key: Optional[PrivateKey] = None
     freeze_key: Optional[PrivateKey] = None
     wipe_key: Optional[PrivateKey] = None
+    metadata_key: Optional[PrivateKey] = None
 
 class TokenCreateTransaction(Transaction):
     """
@@ -319,6 +321,11 @@ def set_wipe_key(self, key):
         self._require_not_frozen()
         self._keys.wipe_key = key
         return self
+    
+    def set_metadata_key(self, key):
+        self._require_not_frozen()
+        self._keys.metadata_key = key
+        return self
 
     def build_transaction_body(self):
         """
@@ -357,6 +364,11 @@ def build_transaction_body(self):
             wipe_public_key_bytes = self._keys.wipe_key.public_key().to_bytes_raw()
             wipe_key_proto = basic_types_pb2.Key(ed25519=wipe_public_key_bytes)
 
+        metadata_key_proto = None
+        if self._keys.metadata_key:
+            metadata_public_key_bytes = self._keys.metadata_key.public_key().to_bytes_raw()
+            metadata_key_proto = basic_types_pb2.Key(ed25519=metadata_public_key_bytes)
+
         # Ensure token type is correctly set with default to fungible
         if self._token_params.token_type is None:
             token_type_value = 0  # default FUNGIBLE_COMMON
@@ -387,7 +399,8 @@ def build_transaction_body(self):
             adminKey=admin_key_proto,
             supplyKey=supply_key_proto,
             freezeKey=freeze_key_proto,
-            wipeKey=wipe_key_proto
+            wipeKey=wipe_key_proto,
+            metadata_key=metadata_key_proto
         )
         # Build the base transaction body and attach the token creation details
         transaction_body = self.build_base_transaction_body()

src/hiero_sdk_python/tokens/token_update_nfts_transaction.py

@@ -0,0 +1,107 @@
+from operator import le
+from hiero_sdk_python.tokens.token_id import TokenId
+from hiero_sdk_python.transaction.transaction import Transaction
+from hiero_sdk_python.channels import _Channel
+from hiero_sdk_python.executable import _Method
+from hiero_sdk_python.hapi.services.token_update_nfts_pb2 import TokenUpdateNftsTransactionBody
+from google.protobuf.wrappers_pb2 import BytesValue
+
+class TokenUpdateNftsTransaction(Transaction):
+    """
+    Represents a token update NFTs transaction on the Hedera network.
+    
+    This transaction updates the metadata of NFTs.
+    
+    Inherits from the base Transaction class and implements the required methods
+    to build and execute a token update NFTs transaction.
+    """
+    def __init__(self, token_id=None, serial_numbers=None, metadata=None):
+        """
+        Initializes a new TokenUpdateNftsTransaction instance with optional token_id, serial_numbers, and metadata.
+
+        Args:
+            token_id (TokenId, optional): The ID of the token whose NFTs will be updated.
+            serial_numbers (list[int], optional): The serial numbers of the NFTs to update.
+            metadata (bytes, optional): The new metadata for the NFTs.
+        """
+        super().__init__()
+        self.token_id : TokenId = token_id
+        self.serial_numbers : list[int] = serial_numbers if serial_numbers else []
+        self.metadata : bytes = metadata
+
+    def set_token_id(self, token_id):
+        self._require_not_frozen()
+        self.token_id = token_id
+        return self
+    
+    def set_serial_numbers(self, serial_numbers):
+        self._require_not_frozen()
+        self.serial_numbers = serial_numbers
+        return self
+    
+    def set_metadata(self, metadata):
+        self._require_not_frozen()
+        self.metadata = metadata
+        return self
+    
+    def build_transaction_body(self):
+        """
+        Builds and returns the protobuf transaction body for token update NFTs.
+
+        Returns:
+            TransactionBody: The protobuf transaction body containing the token update NFTs details.
+        
+        Raises:
+            ValueError: If the token ID and serial numbers are not set or metadata is greater than 100 bytes.
+        """
+        if not self.token_id:
+            raise ValueError("Missing token ID")
+        
+        if not self.serial_numbers:
+            raise ValueError("Missing serial numbers")
+        
+        if self.metadata and len(self.metadata) > 100:
+            raise ValueError("Metadata must be less than 100 bytes")
+        
+        token_update_body = TokenUpdateNftsTransactionBody(
+            token=self.token_id.to_proto(),
+            serial_numbers=self.serial_numbers,
+            metadata=BytesValue(value=self.metadata)
+        )
+        
+        transaction_body = self.build_base_transaction_body()
+        transaction_body.token_update_nfts.CopyFrom(token_update_body)
+        return transaction_body
+    
+    def _get_method(self, channel: _Channel) -> _Method:
+        """
+        Gets the method to execute the token update NFTs transaction.
+
+        This internal method returns a _Method object containing the appropriate gRPC
+        function to call when executing this transaction on the Hedera network.
+
+        Args:
+            channel (_Channel): The channel containing service stubs
+        
+        Returns:
+            _Method: An object containing the transaction function to update NFTs.
+        """
+        return _Method(
+            transaction_func=channel.token.updateNfts,
+            query_func=None
+        )
+        
+    def _from_proto(self, proto: TokenUpdateNftsTransactionBody):
+        """
+        Deserializes a TokenUpdateNftsTransactionBody from a protobuf object.
+
+        Args:
+            proto (TokenUpdateNftsTransactionBody): The protobuf object to deserialize.
+
+        Returns:
+            TokenUpdateNftsTransaction: Returns self for method chaining.
+        """
+        self.token_id = TokenId.from_proto(proto.token)
+        self.serial_numbers = proto.serial_numbers
+        self.metadata = proto.metadata.value
+        return self