feat: very rough notes (temp hold while other transactions finish)

Author: exploreriii

README.md

@@ -97,8 +97,9 @@ Create a .env file in the root of your project with the following (replace with
 OPERATOR_ID=0.0.1234xx
 OPERATOR_KEY=302e020100300506032b657004220420...
 ADMIN_KEY=302a300506032b65700321009308ecfdf...
-SUPPLY_KEY =302a300506032b6570032100c5e4af5..."
+SUPPLY_KEY =302a300506032b6570032100c5e4af5...
 FREEZE_KEY=302a300306072b65700321009308ecfdf...
+PAUSE_KEY=302a300306072b6570032100af12b3c4d...
 RECIPIENT_ID=0.0.789xx
 TOKEN_ID=0.0.100xx
 TOPIC_ID=0.0.200xx
@@ -134,6 +135,7 @@ Token dissociation successful.
 Token minting successful.
 Token transfer successful.
 Token freeze successful.
+Token pause succesful.
 Token deletion successful.
 Topic creation successful.
 Topic Message submitted.

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)
+  - [Pausing a Token](#pausing-a-token)
   - [Deleting a Token](#deleting-a-token)
   - [Freezing a Token](#freezing-a-token)
 - [HBAR Transactions](#hbar-transactions)
@@ -256,6 +257,31 @@ transaction.execute(client)
     transaction.execute(client)
 ```
 
+### Pausing a Token
+
+#### Pythonic Syntax:
+```
+transaction = TokenPauseTransaction(
+    token_id=token_id
+).freeze_with(client)
+
+transaction.sign(pause_key) # Pause key must have been set during token creation
+transaction.sign(operator_key)
+transaction.execute(client)
+```
+#### Method Chaining:
+```
+    transaction = (
+        TokenPauseTransaction()
+        .set_token_id(token_id)
+        .freeze_with(client)
+    )
+
+    transaction.sign(pause_key) # Pause key must have been set during token creation
+    transaction.sign(operator_key)
+    transaction.execute(client)
+```
+
 ### Deleting a Token
 
 #### Pythonic Syntax:

examples/token_create.py

@@ -46,6 +46,7 @@ def create_token():
     admin_key = PrivateKey.from_string(os.getenv('ADMIN_KEY'))# Optional
     supply_key = PrivateKey.from_string(os.getenv('SUPPLY_KEY')) # Optional
     freeze_key = PrivateKey.from_string(os.getenv('FREEZE_KEY')) # Optional
+    pause_key = PrivateKey.from_string(os.getenv('PAUSE_KEY')) # Optional
 
     # Set the operator for the client
     client.set_operator(operator_id, operator_key)
@@ -63,6 +64,7 @@ def create_token():
         .set_admin_key(admin_key) # Optional
         .set_supply_key(supply_key) # Optional
         .set_freeze_key(freeze_key) # Optional
+        .set_pause_key(pause_key)  # Optional
         .freeze_with(client) # Freeze the transaction. Returns self so we can sign.
         .sign(operator_key) # Required signature of treasury account
         .sign(admin_key) if admin_key else None  # Only sign if admin_key is present. No need to sign with the supply or freeze keys to create the token.

examples/token_pause.py

@@ -0,0 +1,82 @@
+"""
+pause_token.py
+
+This script demonstrates how to pause an existing token.
+
+It:
+1. Loads environment variables for operator and pause key
+2. Sets up a client
+3. Pauses the token specified by TOKEN_ID
+4. Prints the result or error
+
+Required environment variables:
+- OPERATOR_ID, OPERATOR_KEY (mandatory)
+- TOKEN_ID (the ID of the token to pause)
+- PAUSE_KEY (the key authorized to pause this token)
+
+Dependencies:
+- dotenv
+- hiero_sdk_python
+"""
+
+import os
+import sys
+from dotenv import load_dotenv
+
+# Hiero SDK imports
+from hiero_sdk_python.client.network import Network
+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.tokens.token_id import TokenId
+from hiero_sdk_python.tokens.token_pause_transaction import TokenPauseTransaction
+from hiero_sdk_python.response_code import ResponseCode
+
+load_dotenv()
+
+
+def pause_token():
+    """Function to pause a token."""
+
+    # Network Setup
+    network = Network(network='testnet')
+    client = Client(network)
+
+    # Operator credentials (must be present)
+    operator_id = AccountId.from_string(os.getenv('OPERATOR_ID'))
+    operator_key = PrivateKey.from_string(os.getenv('OPERATOR_KEY'))
+
+    # Required Pause Key
+    pause_key = PrivateKey.from_string(os.getenv('PAUSE_KEY')) # Optional
+
+    # Set the operator for the client
+    client.set_operator(operator_id, operator_key)
+
+    # Create the token pause transaction
+    transaction = TokenPauseTransaction(token_id=token_id)
+
+    transaction.freeze_with(client)
+
+    # The operator (fee payer) signs first
+    transaction.sign(operator_key)
+
+    # The pause key must sign
+    transaction.sign(pause_key)
+
+    try:
+
+        # Execute the transaction and get the receipt
+        receipt = transaction.execute(client)
+
+        if receipt and receipt.tokenId:
+            print(f"Token paused with ID: {receipt.tokenId}")
+        else:
+            print("Token paused failed: Token ID not returned in receipt.")
+            sys.exit(1)
+
+    except Exception as e:
+        print(f"Token paused failed: {str(e)}")
+        sys.exit(1)
+
+if __name__ == "__main__":
+    pause_token()

src/hiero_sdk_python/tokens/token_create_transaction.py

@@ -146,11 +146,13 @@ class TokenKeys:
         admin_key: The admin key for the token to update and delete.
         supply_key: The supply key for the token to mint and burn.
         freeze_key: The freeze key for the token to freeze and unfreeze.
+        pause_key: The pause key for the token to pause and unpause.
     """
 
     admin_key: Optional[PrivateKey] = None
     supply_key: Optional[PrivateKey] = None
     freeze_key: Optional[PrivateKey] = None
+    pause_key: Optional[PrivateKey] = None
 
 class TokenCreateTransaction(Transaction):
     """
@@ -265,7 +267,12 @@ def set_freeze_key(self, key):
         self._require_not_frozen()
         self._keys.freeze_key = key
         return self
-
+    
+    def set_pause_key(self, key):
+        self._require_not_frozen()
+        self._keys.pause_key = key
+        return self
+    
     def freeze(self):
         """Marks the transaction as frozen to prevent further modifications."""
         self._is_frozen = True
@@ -309,6 +316,11 @@ def build_transaction_body(self):
             freeze_public_key_bytes = self._keys.freeze_key.public_key().to_bytes_raw()
             freeze_key_proto = basic_types_pb2.Key(ed25519=freeze_public_key_bytes)
 
+        pause_key_proto = None
+        if self._keys.pause_key:
+            pause_public_key_bytes = self._keys.pause_key.public_key().to_bytes_raw()
+            pause_key_proto = basic_types_pb2.Key(ed25519=pause_public_key_bytes)
+
 
         # Ensure token type is correctly set with default to fungible
         if self._token_params.token_type is None:
@@ -329,6 +341,7 @@ def build_transaction_body(self):
             adminKey=admin_key_proto,
             supplyKey=supply_key_proto,
             freezeKey=freeze_key_proto,
+            pause_key=pause_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_pause_transaction.py

@@ -0,0 +1,151 @@
+from hiero_sdk_python.transaction.transaction import Transaction
+from hiero_sdk_python.hapi.services import token_pause_pb2
+from hiero_sdk_python.response_code import ResponseCode
+
+class TokenPauseValidator:
+    """
+    Validates prerequisites and constraints for a TokenPauseTransaction.
+    """
+
+    @staticmethod
+    def validate_token_id(token_id):
+        """
+        Ensures a valid token ID was provided.
+        
+        Args:
+            token_id (TokenId): The ID of the token to be paused.
+
+        Raises:
+            ValueError: If the token ID is not provided.
+        """
+        if not token_id:
+            raise ValueError("Token ID is required for pausing a token.")
+        
+    @staticmethod
+    def validate_token_pause(token_info):
+        """
+        Validate that the provided token can be paused.
+        
+        Args:
+            token_info (TokenInfo): A structure containing metadata about the token
+                                   (e.g. whether the token is deleted, paused, or
+                                   has a pause key, etc.).
+
+        Raises:
+            ValueError: If the token is missing, already deleted, or has no valid pause key.
+        """
+        TokenPauseValidator._validate_token_not_deleted(token_info)
+        TokenPauseValidator._validate_has_pause_key(token_info)
+        # It is NOT an error if the token is already paused
+
+    @staticmethod
+    def _validate_token_not_deleted(token_info):
+        """
+        Ensures the token is not already deleted.
+
+        Args:
+            token_info (TokenInfo): Contains token metadata (including 'deleted' status).
+
+        Raises:
+            ValueError: If the token is marked deleted.
+        """
+        if getattr(token_info, "deleted", False):
+            raise ValueError("Cannot pause a deleted token.")
+
+    @staticmethod
+    def _validate_has_pause_key(token_info):
+        """
+        Ensures the token has a valid pause key.
+
+        Args:
+            token_info (TokenInfo): Contains token metadata (including 'pause_key').
+
+        Raises:
+            ValueError: If the token has no pause key or the pause key is invalid/empty.
+        """
+        if not hasattr(token_info, "pause_key") or not token_info.pause_key:
+            raise ValueError("Token has no valid pause key and cannot be paused.")
+        
+
+class TokenPauseTransaction(Transaction):
+    """
+    Represents a token pause transaction.
+
+    This transaction pauses a specified token.
+
+    Inherits from the base Transaction class and implements the required methods
+    to build and execute a token pause transaction.
+    """
+
+    def __init__(self, token_id=None):
+        """
+        Initializes a new TokenPauseTransaction instance with optional token_id.
+
+        Args:
+            token_id (TokenId, optional): The ID of the token to be paused.
+        """
+        super().__init__()
+        self.token_id = token_id
+        self._default_transaction_fee = 3_000_000_000
+
+    def set_token_id(self, token_id):
+        self._require_not_frozen()
+        self.token_id = token_id
+        return self
+    
+    def build_transaction_body(self):
+        """
+        Builds and returns the protobuf transaction body for token pause.
+
+        Returns:
+            TransactionBody: The protobuf transaction body containing the token pause details.
+
+        Raises:
+            ValueError: If the token ID is missing.
+        """
+
+        # Validation checks
+        TokenPauseValidator.validate_token_id(self.token_id)
+        
+        token_pause_body = token_pause_pb2.TokenPauseTransactionBody(
+            token=self.token_id.to_proto(),
+        )
+
+        transaction_body = self.build_base_transaction_body()
+        transaction_body.token_pause.CopyFrom(token_pause_body)
+
+        return transaction_body
+
+    def _execute_transaction(self, client, transaction_proto):
+        """
+        Executes the token pause 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.
+        """
+        # Retrieve token info and run pause-specific validations
+        token_info = client.get_token_info(self.token_id)
+        TokenPauseValidator.validate_token_pause(token_info)
+
+        # Log if the token is already paused:
+        if getattr(token_info, "paused", False):
+            print("Token is already paused.")
+            pass
+
+        # Submit the token pause transaction
+        response = client.token_stub.pauseToken(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