feat: Add Hip1313 (hiero-ledger#2308)

Signed-off-by: aceppaluni <aceppaluni@gmail.com>

Author: aceppaluni

examples/account/account_create_transaction_with_high_volume_throttle.py

@@ -0,0 +1,83 @@
+"""
+Example demonstrating high-volume account creation functionality.
+
+Run:
+uv run examples/account/high_volume_account_create_transaction.py
+python examples/account/high_volume_account_create_transaction.py
+"""
+
+import sys
+
+from hiero_sdk_python import (
+    AccountCreateTransaction,
+    AccountDeleteTransaction,
+    Client,
+    Hbar,
+    PrivateKey,
+    ResponseCode,
+)
+
+
+def create_account_high_volume(client):
+    """Create a test account using high-volume throttles."""
+    account_private_key = PrivateKey.generate_ed25519()
+    account_public_key = account_private_key.public_key()
+
+    tx = (
+        AccountCreateTransaction()
+        .set_key_without_alias(account_public_key)
+        .set_initial_balance(Hbar(1))
+        .set_account_memo("High-volume test account")
+        .set_high_volume(True)
+    )
+
+    # Set max transaction fee before freezing
+    tx.transaction_fee = Hbar(5)
+
+    receipt = tx.freeze_with(client).sign(account_private_key).execute(client)
+
+    if receipt.status != ResponseCode.SUCCESS:
+        print(f"Account creation failed with status: {ResponseCode(receipt.status).name}")
+        sys.exit(1)
+
+    account_id = receipt.account_id
+    print(f"\nAccount created with ID: {account_id}")
+
+    return account_id, account_private_key
+
+
+def main():
+    """
+    Demonstrates high-volume account creation functionality by:
+
+    1. Setting up client with operator account
+    2. Creating an account using high-volume throttles
+    3. Setting a max transaction fee for dynamic pricing protection
+    4. Deleting the created account
+    """
+    client = Client.from_env()
+
+    # Create an account using high-volume throttles
+    account_id, account_private_key = create_account_high_volume(client)
+
+    print("Account created successfully using high-volume throttles!")
+
+    # Delete the account
+    receipt = (
+        AccountDeleteTransaction()
+        .set_account_id(account_id)
+        .set_transfer_account_id(client.operator_account_id)
+        .freeze_with(client)
+        .sign(account_private_key)
+        .execute(client)
+    )
+
+    if receipt.status != ResponseCode.SUCCESS:
+        print(f"Account delete failed with status: {ResponseCode(receipt.status).name}")
+        sys.exit(1)
+
+    print("Account deleted successfully!")
+
+
+if __name__ == "__main__":
+    main()

src/hiero_sdk_python/transaction/transaction.py

@@ -47,9 +47,10 @@ def __init__(self) -> None:
         super().__init__()
 
         self.transaction_id = None
-        self.transaction_fee: int | None = None
+        self._transaction_fee: int | None = None
         self.transaction_valid_duration = 120
         self.generate_record = False
+        self._high_volume = False
         self.memo = ""
         self.custom_fee_limits: list[CustomFeeLimit] = []
         # Maps each node's AccountId to its corresponding transaction body bytes
@@ -466,14 +467,15 @@ def build_base_transaction_body(self) -> transaction_pb2.TransactionBody:
         transaction_body.transactionID.CopyFrom(transaction_id_proto)
         transaction_body.nodeAccountID.CopyFrom(selected_node._to_proto())
 
-        fee = self.transaction_fee or self._default_transaction_fee
+        fee = self._transaction_fee or self._default_transaction_fee
         if hasattr(fee, "to_tinybars"):
             transaction_body.transactionFee = int(fee.to_tinybars())
         else:
             transaction_body.transactionFee = int(fee)
 
         transaction_body.transactionValidDuration.seconds = self.transaction_valid_duration
         transaction_body.generateRecord = self.generate_record
+        transaction_body.high_volume = self._high_volume
         transaction_body.memo = self.memo
         custom_fee_limits = [custom_fee._to_proto() for custom_fee in self.custom_fee_limits]
         transaction_body.max_custom_fees.extend(custom_fee_limits)
@@ -493,7 +495,7 @@ def build_base_scheduled_body(self) -> SchedulableTransactionBody:
         """
         schedulable_body = SchedulableTransactionBody()
 
-        fee = self.transaction_fee or self._default_transaction_fee
+        fee = self._transaction_fee or self._default_transaction_fee
         if hasattr(fee, "to_tinybars"):
             schedulable_body.transactionFee = int(fee.to_tinybars())
         else:
@@ -604,6 +606,33 @@ def set_transaction_id(self, transaction_id: TransactionId):
         self.transaction_id = transaction_id
         return self
 
+    # this will preserves original behavior
+    @property
+    def transaction_fee(self):
+        """
+        Set the maximum transaction fee for this transaction.
+        """
+        return self._transaction_fee
+
+    @transaction_fee.setter
+    def transaction_fee(self, fee: Hbar | int):
+        """
+        Set the maximum transaction fee for this transaction.
+        """
+        self._require_not_frozen()
+
+        if isinstance(fee, Hbar):
+            tinybars = fee.to_tinybars()
+        elif isinstance(fee, bool) or not isinstance(fee, int):
+            raise TypeError("fee must be of type Hbar or int")
+        else:
+            tinybars = fee
+
+        if tinybars < 0:
+            raise ValueError("fee must be greater than or equal to 0")
+
+        self._transaction_fee = tinybars
+
     def to_bytes(self) -> bytes:
         """
         Serializes the frozen transaction into its protobuf-encoded byte representation.
@@ -853,6 +882,7 @@ def _from_protobuf(cls, transaction_body, body_bytes: bytes, sig_map):
         transaction.transaction_fee = transaction_body.transactionFee
         transaction.transaction_valid_duration = transaction_body.transactionValidDuration.seconds
         transaction.generate_record = transaction_body.generateRecord
+        transaction._high_volume = transaction_body.high_volume
         transaction.memo = transaction_body.memo
 
         if transaction_body.max_custom_fees:
@@ -886,6 +916,31 @@ def set_batch_key(self, key: Key):
         self.batch_key = key
         return self
 
+    def set_high_volume(self, high_volume: bool) -> Transaction:
+        """
+        Enables or disables high-volume throttles for this transaction.
+
+        When enabled, the transaction may use high-volume capacity with
+        dynamic pricing as defined by HIP-1313.
+
+        Args:
+            high_volume (bool): Whether to enable high-volume throttles.
+
+        Returns:
+            Transaction: The current transaction instance for method chaining.
+
+        Raises:
+            TypeError: If high_volume is not a bool.
+            Exception: If the transaction has already been frozen.
+        """
+        self._require_not_frozen()
+
+        if not isinstance(high_volume, bool):
+            raise TypeError("high_volume must be of type bool")
+
+        self._high_volume = high_volume
+        return self
+
     def batchify(self, client: Client, batch_key: Key):
         """
         Marks the current transaction as an inner (batched) transaction.
@@ -935,3 +990,13 @@ def body_size(self) -> int:
         """Returns just the transaction body size in bytes after encoding"""
         self._require_frozen()
         return self.build_transaction_body().ByteSize()
+
+    @property
+    def high_volume(self) -> bool:
+        """
+        Returns whether high-volume throttles are enabled for this transaction.
+
+        Returns:
+            bool: True if high-volume throttles are enabled.
+        """
+        return self._high_volume

src/hiero_sdk_python/transaction/transaction_record.py

@@ -89,6 +89,7 @@ class TransactionRecord:
     transaction_hash: bytes | None = None
     transaction_memo: str | None = None
     transaction_fee: int | None = None
+    high_volume_pricing_multiplier: int | None = None
     receipt: TransactionReceipt | None = None
     call_result: ContractFunctionResult | None = None
 
@@ -144,6 +145,7 @@ def __repr__(self) -> str:
             f"transaction_hash={self.transaction_hash}, "
             f"transaction_memo='{self.transaction_memo}', "
             f"transaction_fee={self.transaction_fee}, "
+            f"high_volume_pricing_multiplier={self.high_volume_pricing_multiplier}, "
             f"receipt_status='{status}', "
             f"token_transfers={dict(self.token_transfers)}, "
             f"nft_transfers={dict(self.nft_transfers)}, "
@@ -240,6 +242,7 @@ def _from_proto(
             if proto.HasField("contractCreateResult")
             else None
         )
+
         alias = proto.alias if proto.alias else None
         ethereum_hash = proto.ethereum_hash if proto.ethereum_hash else None
         evm_address = proto.evm_address if proto.evm_address else None
@@ -279,6 +282,7 @@ def _from_proto(
             paid_staking_rewards=paid_staking_rewards,
             evm_address=evm_address,
             contract_create_result=contract_create_result,
+            high_volume_pricing_multiplier=proto.high_volume_pricing_multiplier,
         )
 
     @staticmethod
@@ -459,4 +463,7 @@ def _to_proto(self) -> transaction_record_pb2.TransactionRecord:
         if self.contract_create_result is not None:
             record_proto.contractCreateResult.CopyFrom(self.contract_create_result._to_proto())
 
+        if self.high_volume_pricing_multiplier is not None:
+            record_proto.high_volume_pricing_multiplier = self.high_volume_pricing_multiplier
+
         return record_proto

tests/integration/account_create_transaction_e2e_test.py

@@ -7,6 +7,7 @@
 from hiero_sdk_python.exceptions import PrecheckError
 from hiero_sdk_python.hbar import Hbar
 from hiero_sdk_python.query.account_info_query import AccountInfoQuery
+from hiero_sdk_python.query.transaction_record_query import TransactionRecordQuery
 from hiero_sdk_python.response_code import ResponseCode
 
 
@@ -355,3 +356,71 @@ def test_create_account_with_negative_initial_balance(env):
         tx.execute(env.client)
 
     assert e.value.status == ResponseCode.INVALID_INITIAL_BALANCE
+
+
+def test_can_create_account_with_high_volume(env):
+    """
+    Test creation of an account with high-volume pricing enabled and verify
+    the resulting pricing multiplier and account properties.
+    """
+    key = PrivateKey.generate_ed25519()
+
+    tx = AccountCreateTransaction().set_key_without_alias(key).set_initial_balance(Hbar(1)).set_high_volume(True)
+
+    tx.transaction_fee = Hbar(10)
+    tx.freeze_with(env.client)
+
+    receipt = tx.execute(env.client)
+
+    assert receipt.status == ResponseCode.SUCCESS, f"Unexpected status: {ResponseCode(receipt.status).name}"
+
+    account_id = receipt.account_id
+    assert account_id is not None
+
+    record = TransactionRecordQuery(tx.transaction_id).execute(env.client)
+
+    assert record.high_volume_pricing_multiplier >= 1000
+
+    info = AccountInfoQuery().set_account_id(account_id).execute(env.client)
+
+    assert info.account_id == account_id
+    assert info.is_deleted is False
+    assert str(info.key) == str(key.public_key())
+    assert info.balance == Hbar(1)
+
+
+def test_can_create_account_with_high_volume_and_valid_max_fee(env):
+    """
+    Verify that a high-volume account can be created when the transaction
+    maximum fee is set high enough to cover the increased cost.
+    """
+    key = PrivateKey.generate_ed25519()
+
+    tx = AccountCreateTransaction().set_key_without_alias(key).set_initial_balance(Hbar(1)).set_high_volume(True)
+
+    tx.transaction_fee = Hbar(10)
+
+    receipt = tx.execute(env.client)
+    account_id = receipt.account_id
+
+    assert receipt.status == ResponseCode.SUCCESS
+    assert account_id is not None
+
+    info = AccountInfoQuery().set_account_id(account_id).execute(env.client)
+
+    assert info.account_id == account_id
+
+
+def test_create_account_with_high_volume_fails_with_insufficient_tx_fee(env):
+    """
+    Verify that an account creation transaction with high-volume pricing
+    fails with INSUFFICIENT_TX_FEE when the transaction fee is too low.
+    """
+    key = PrivateKey.generate_ed25519()
+
+    tx = AccountCreateTransaction().set_key_without_alias(key).set_initial_balance(Hbar(1)).set_high_volume(True)
+
+    tx.transaction_fee = Hbar(1)
+    receipt = tx.execute(env.client)
+
+    assert receipt.status == ResponseCode.INSUFFICIENT_TX_FEE