feat: add token metadata support to TokenCreateTransaction (#866)

AntonioCeppellini · web-flow · commit 289ce4587bc0 · 2025-11-21T22:14:35.000Z
Signed-off-by: Antonio Ceppellini &lt;antonio.ceppellini@gmail.com&gt;
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -26,6 +26,7 @@ This changelog is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.
 - `staked_account_id`, `staked_node_id` and `decline_staking_reward` fields to AccountInfo
 - Added `examples/token_create_transaction_supply_key.py` to demonstrate token creation with and without a supply key.
 - Added BatchTransaction class
+- Add support for token metadata (bytes, max 100 bytes) in `TokenCreateTransaction`, including a new `set_metadata` setter, example, and tests. [#799]
 
 
 ### Changed
diff --git a/examples/token_create_transaction_token_metadata.py b/examples/token_create_transaction_token_metadata.py
@@ -0,0 +1,248 @@
+"""
+This example creates a fungible token with on-ledger metadata using Hiero SDK Python.
+
+It demonstrates:
+1. Creating a token with on-ledger metadata.
+2. Attempting to update metadata WITHOUT a metadata_key: expected to fail.
+3. Attempting to update metadata WITH a metadata_key: expected to succed.
+4. Demonstrates that metadata longer than 100 bytes is rejected.
+
+Required environment variables:
+- OPERATOR_ID, OPERATOR_KEY
+
+Usage:
+uv run examples/token_create_transaction_token_metadata.py
+python examples/token_create_transaction_token_metadata.py
+"""
+
+import os
+import sys
+from dotenv import load_dotenv
+from hiero_sdk_python import (
+    Client,
+    AccountId,
+    PrivateKey,
+    TokenCreateTransaction,
+    TokenUpdateTransaction,
+    Network,
+    TokenType,
+    SupplyType,
+)
+from hiero_sdk_python.query.token_info_query import TokenInfoQuery
+from hiero_sdk_python.response_code import ResponseCode
+
+load_dotenv()
+network_name = os.getenv("NETWORK", "testnet").lower()
+
+
+def setup_client():
+    """Initialize and set up the client with operator account"""
+    network = Network(network_name)
+    print(f"Connecting to Hedera {network_name} network!")
+    client = Client(network)
+
+    try:
+        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)
+        print(f"Client set up with operator id {client.operator_account_id}")
+        return client, operator_id, operator_key
+
+    except (TypeError, ValueError):
+        print("Error: Please check OPERATOR_ID and OPERATOR_KEY in your .env file.")
+        sys.exit(1)
+
+
+def generate_metadata_key():
+    """Generate a new metadata key for the token."""
+    print("\nGenerating a new metadata key for the token...")
+    metadata_key = PrivateKey.generate_ed25519()
+    print("✅ Metadata key generated successfully.")
+    return metadata_key
+
+
+def create_token_without_metadata_key(client, operator_key, operator_id):
+    """
+    Creating token with on-ledger metadata WITHOUT metadata_key (max 100 bytes)
+    """
+    print("\nCreating token WITHOUT metadata_key")
+
+    metadata = b"Initial on-ledger metadata"  # < 100 bytes
+
+    try:
+        transaction = (
+            TokenCreateTransaction()
+            .set_token_name("MetadataToken_NoKey")
+            .set_token_symbol("MDN")
+            .set_treasury_account_id(operator_id)
+            .set_token_type(TokenType.FUNGIBLE_COMMON)
+            .set_supply_type(SupplyType.INFINITE)
+            .set_initial_supply(10)
+            .set_metadata(metadata)
+            .freeze_with(client)
+        )
+
+        # Sign + execute
+        transaction.sign(operator_key)
+        receipt = transaction.execute(client)
+    except Exception as e:
+        print(f"❌ Error while building create transaction: {e}")
+        sys.exit(1)
+
+    token_id = receipt.token_id
+    print(f"✅ Token {token_id} successfully created without metadata_key")
+    return token_id
+
+
+def try_update_metadata_without_key(client, operator_key, token_id):
+    print(f"\nAttempting token {token_id} metadata update WITHOUT metadata_key...")
+    updated_metadata = b"updated metadata (without metadata_key)"
+    try:
+        update_transaction = (
+            TokenUpdateTransaction()
+            .set_token_id(token_id)
+            .set_metadata(updated_metadata)
+            .freeze_with(client)
+        )
+        update_transaction.sign(operator_key)
+        receipt = update_transaction.execute(client)
+        status = ResponseCode(receipt.status).name
+
+        if receipt.status == ResponseCode.SUCCESS:
+            print(
+                f"❌ Unexpected SUCCESS. Status: {receipt.status}"
+                "(this should normally fail when metadata_key is missing)"
+            )
+            sys.exit(1)
+        else:
+                print(f"✅ Expected failure: metadata update rejected -> status={status}")
+
+    except Exception as e:
+        print(f"Failed: {e}")
+
+
+def create_token_with_metadata_key(client, metadata_key, operator_id, operator_key):
+    """
+    Create token with metadata_key and on-ledger metadata (max 100 bytes)
+    """
+    metadata = b"Example on-ledger token metadata"
+
+    print("\nCreating token with metadata and metadata_key...")
+    try:
+        transaction = (
+            TokenCreateTransaction()
+            .set_token_name("Metadata Fungible Token")
+            .set_token_symbol("MFT")
+            .set_decimals(2)
+            .set_initial_supply(1000)
+            .set_treasury_account_id(operator_id)
+            .set_token_type(TokenType.FUNGIBLE_COMMON)
+            .set_supply_type(SupplyType.INFINITE)
+            .set_metadata_key(metadata_key)
+            .set_metadata(metadata)
+            .freeze_with(client)
+        )
+
+        transaction.sign(operator_key)
+        transaction.sign(metadata_key)
+        receipt = transaction.execute(client)
+    except Exception as e:
+        print(f"❌ Error while creating transaction: {e}")
+        sys.exit(1)
+
+    if receipt.status != ResponseCode.SUCCESS:
+        print(
+            f"❌ Token creation failed with status: {ResponseCode(receipt.status).name}"
+        )
+        sys.exit(1)
+
+    token_id = receipt.token_id
+    print(f"✅ Token {token_id} created with metadat_key: {metadata_key.public_key()}")
+    print(f"Metadata: {metadata!r}")
+    return token_id, metadata_key
+
+
+def update_metadata_with_key(client, token_id, metadata_key, operator_key):
+    """
+    Update token metadata with metadata_key
+    """
+    print(f"\nUpdating token {token_id} metadata WITH metadata_key...")
+    updated_metadata = b"Updated metadata (with key)"
+
+    try:
+        update_transaction = (
+            TokenUpdateTransaction()
+            .set_token_id(token_id)
+            .set_metadata(updated_metadata)
+            .freeze_with(client)
+            .sign(metadata_key)
+        )
+        receipt = update_transaction.execute(client)
+        if receipt.status != ResponseCode.SUCCESS:
+            print(
+                f"❌ Token update failed with status: {ResponseCode(receipt.status).name}"
+            )
+            sys.exit(1)
+    except Exception as e:
+        print(f"Error while freezing update transaction: {e}")
+        sys.exit(1)
+
+    print(f"✅ Token {token_id} metadata successfully updated")
+    print(f"Updated metadata: {updated_metadata}")
+
+
+def demonstrate_metadata_length_validation(client, operator_key, operator_id):
+    """
+    Demonstrate that metadata longer than 100 bytes trigger a ValueError
+    in the TokenCreateTransaction.set_metadata() validation.
+    """
+    print("\nDemonstrating metadata length validation (> 100 bytes)...")
+    too_long_metadata = b"x" * 101
+
+    try:
+        transaction = (
+            TokenCreateTransaction()
+            .set_token_name("TooLongMetadataToken")
+            .set_token_symbol("TLM")
+            .set_treasury_account_id(operator_id)
+            .set_metadata(too_long_metadata)
+        )
+
+        transaction.sign(operator_key)
+        receipt = transaction.execute(client)
+        if receipt.status == ResponseCode.SUCCESS:
+            print(f"❌ Unexpected success for this operation!")
+        else:
+            print(
+                "Error: Expected ValueError for metadata > 100 bytes, but none was raised."
+            )
+            
+        sys.exit(1)
+    except ValueError as exc:
+        print("Expected error raised for metadata > 100 bytes")
+        print(f"✅ Error raised: {exc}")
+
+
+def create_token_with_metadata():
+    """
+    Main function to create and update fungible token with metadata with two scenarios:
+    - create token WITHOUT metadata_key (expected to fail)
+    - create token WITH metadat_key (expected to succed)
+    and validate metadata length
+    """
+    client, operator_id, operator_key = setup_client()
+    metadata_key = generate_metadata_key()
+
+    token_a = create_token_without_metadata_key(client, operator_key, operator_id)
+    try_update_metadata_without_key(client, operator_key, token_a)
+
+    token_b, metadata_key = create_token_with_metadata_key(
+        client, metadata_key, operator_id, operator_key
+    )
+    update_metadata_with_key(client, token_b, metadata_key, operator_key)
+
+    demonstrate_metadata_length_validation(client, operator_key, operator_id)
+
+
+if __name__ == "__main__":
+    create_token_with_metadata()
diff --git a/src/hiero_sdk_python/tokens/token_create_transaction.py b/src/hiero_sdk_python/tokens/token_create_transaction.py
@@ -50,6 +50,7 @@ class TokenParams:
         max_supply (optional): The max tokens or NFT serial numbers.
         supply_type (optional): The token supply status as finite or infinite.
         freeze_default (optional): An initial Freeze status for accounts associated to this token.
+        metadata (optional): The on-ledger token metadata as bytes (max 100 bytes).
     """
 
     token_name: str
@@ -66,6 +67,7 @@ class TokenParams:
     auto_renew_account_id: Optional[AccountId] = None
     auto_renew_period: Optional[Duration] = AUTO_RENEW_PERIOD # Default around ~90 days
     memo: Optional[str] = None
+    metadata: Optional[bytes] = None
 
 
 @dataclass
@@ -426,6 +428,24 @@ def set_fee_schedule_key(self, key: Key) -> "TokenCreateTransaction":
         self._keys.fee_schedule_key = key
         return self
 
+    def set_metadata(self, metadata: bytes | str) -> "TokenCreateTransaction":
+        """Sets the metadata for the token (max 100 bytes)"""
+        self._require_not_frozen()
+
+        # accept stringt and converts to bytes
+        if isinstance(metadata, str):
+            metadata = metadata.encode("utf-8")
+
+        # type validation, if users pass something that is not a str or a byte
+        if not isinstance(metadata, (bytes, bytearray)):
+            raise TypeError("Metadata must be bytes or string")
+
+        if len(metadata) > 100:
+            raise ValueError("Metadata must not exceed 100 bytes")
+
+        self._token_params.metadata = metadata
+        return self
+
     def _to_proto_key(self, key: Optional[Key]) -> Optional[basic_types_pb2.Key]:
         """
         Helper method to convert a PrivateKey or PublicKey to the protobuf Key format.
@@ -546,6 +566,7 @@ def _build_proto_body(self) -> token_create_pb2.TokenCreateTransactionBody:
                 else None
             ),
             memo=self._token_params.memo,
+            metadata=self._token_params.metadata,
             adminKey=admin_key_proto,
             supplyKey=supply_key_proto,
             freezeKey=freeze_key_proto,
diff --git a/tests/integration/token_create_transaction_e2e_test.py b/tests/integration/token_create_transaction_e2e_test.py
@@ -236,3 +236,42 @@ def test_token_create_non_custodial_flow():
     finally:
         # Clean up the environment
         env.close()
+
+def test_fungible_token_create_with_metadata():
+    """
+    Test creating a fungible token with on-ledger metadata and verifying
+    the metadata via TokenInfoQuery.
+    """
+    env = IntegrationTestEnv()
+
+    try:
+        # On-ledger token metadata bytes (must not exceed 100 bytes)
+        metadata = b"Integration test token metadata"
+
+        params = TokenParams(
+            token_name="Hiero FT Metadata",
+            token_symbol="HFTM",
+            initial_supply=1,
+            treasury_account_id=env.client.operator_account_id,
+            token_type=TokenType.FUNGIBLE_COMMON,
+        )
+
+        # Build, freeze and execute the token creation transaction with metadata
+        receipt = (
+            TokenCreateTransaction(params)
+            .set_metadata(metadata)
+            .freeze_with(env.client)
+            .execute(env.client)
+        )
+
+        assert receipt.token_id is not None, "TokenID not found in receipt. Token may not have been created."
+
+        token_id = receipt.token_id
+
+        # Query the created token to verify that metadata has been set
+        token_info = TokenInfoQuery(token_id=token_id).execute(env.client)
+
+        assert token_info.metadata == metadata, "Token metadata mismatch"
+
+    finally:
+        env.close()
diff --git a/tests/unit/test_token_create_transaction.py b/tests/unit/test_token_create_transaction.py
@@ -145,6 +145,38 @@ def test_build_transaction_body(mock_account_ids):
     assert transaction_body.tokenCreation.kycKey == private_key_kyc.public_key()._to_proto()
     assert transaction_body.tokenCreation.fee_schedule_key == private_key_fee_schedule.public_key()._to_proto()
 
+# This test uses fixture mock_account_ids as parameter
+def test_build_transaction_body_with_metadata(mock_account_ids):
+    """Test building a token creation transaction body with metadata bytes set."""
+    treasury_account, _, node_account_id, _, _ = mock_account_ids
+
+    token_tx = TokenCreateTransaction()
+    token_tx.set_token_name("MyTokenWithMetadata")
+    token_tx.set_token_symbol("MTKM")
+    token_tx.set_decimals(2)
+    token_tx.set_initial_supply(1000)
+    token_tx.set_treasury_account_id(treasury_account)
+
+    metadata = b"Example on-ledger token metadata"
+    token_tx.set_metadata(metadata)
+
+    token_tx.transaction_id = generate_transaction_id(treasury_account)
+    token_tx.node_account_id = node_account_id
+
+    transaction_body = token_tx.build_transaction_body()
+
+    assert transaction_body.tokenCreation.name == "MyTokenWithMetadata"
+    assert transaction_body.tokenCreation.symbol == "MTKM"
+    assert transaction_body.tokenCreation.metadata == metadata
+
+def test_set_metadata_raises_when_over_100_bytes():
+    """set_metadata must reject metadata longer than 100 bytes."""
+    token_tx = TokenCreateTransaction()
+    too_long_metadata = b"x" * 101  # 101 bytes
+
+    with pytest.raises(ValueError, match="Metadata must not exceed 100 bytes"):
+        token_tx.set_metadata(too_long_metadata)
+
 @pytest.mark.parametrize(
     "token_name, token_symbol, decimals, initial_supply, token_type, expected_error",
     [
@@ -1222,4 +1254,4 @@ def test_to_proto_key_with_invalid_string_raises_error():
     with pytest.raises(TypeError) as e:
         tx._to_proto_key("this is not a key")
         
-    assert "Key must be of type PrivateKey or PublicKey" in str(e.value)
+    assert "Key must be of type PrivateKey or PublicKey" in str(e.value)
