Implement HIP-1313 High-Volume Entity Creation

[aceppaluni]

🧑‍🔬 Advanced Issue

Welcome! This is an Advanced Issue touching core SDK architecture.

It is designed for expert contributors who have demonstrated deep architectural understanding and a proven track record of high-quality contributions.

🐞 Problem Description

The Hiero Python SDK does not currently support HIP-1313 which introduces high-volume throttles for entity creation transactions.

HIP-1313 introduces a parallel throttle system for high-volume entity creation. Users can opt into this system by setting a boolean flag on their transactions. When enabled:

Transactions use a separate set of high-volume throttles with dedicated capacity
Dynamic pricing applies based on throttle utilization (higher usage = higher fees)
Users should set maxTransactionFee to control costs
Standard throttles remain unchanged for users who don't opt in
Without this feature, developers cannot access additional entity creation capacity during peak times, which may slow down applications that need to create many items quickly (such as onboarding large groups of users).

Relevant files:

Sources/Hiero/Transaction.py (base class)
Protobuf bindings for TransactionBody

🛠️ Implementation Notes

1. Verify Protobuf Bindings
   • Check that TransactionBody protobuf includes the high_volume field (field number 25)
   • If not present, regenerate Swift protobuf bindings
2. Update Transaction Base Class
   • Add highVolume property with default value of false
   • Add highVolume(_ highVolume: Bool) -> Self fluent setter method
   • Add willSet { ensureNotFrozen() } guard to prevent modification after freezing
   • Update toTransactionBodyProtobuf to include highVolume in the protobuf output
   • Update init(protobuf:) to read highVolume from the protobuf
3. Add Unit Tests
   • Test that highVolume defaults to false
   • Test setting highVolume to true
   • Test that highVolume cannot be set after transaction is frozen
   • Test serialization/deserialization preserves highVolume flag
   • Test that highVolume is correctly included in protobuf output
4. Add Integration Tests
   • Test creating an account with highVolume enabled
   • Test that transaction succeeds with appropriate maxTransactionFee
   • Test that transaction fails with INSUFFICIENT_TX_FEE when maxTransactionFee is too low
5. Add Example
   • Create an example demonstrating high-volume account creation

Example Usage

from hiero_sdk_python import (
    AccountCreateTransaction,
    Hbar,
)

# Create an account using high-volume throttles
account_create_tx = (
    AccountCreateTransaction()
    .key(new_account_key.public_key)
    .initial_balance(Hbar(10))
    .set_high_volume(True)
    .max_transaction_fee(Hbar(5))  # Important: set a fee limit
    .freeze_with(client)
    .sign(new_account_key)
)

response = account_create_tx.execute(client)
receipt = response.get_receipt(client)

account_id = receipt.account_id

print(f"Created account {account_id} using high-volume throttles")

🧠 Advanced Contributors — Prerequisites & Expectations

Caution

Advanced issues are the highest-risk work in this project. We will reject PRs that do not meet these standards.

🏁 Concrete Prerequisites

• Advanced Language: Proficient with Python.
• Expertise: Deep architectural understanding of _Executable, Transaction, and Query base classes.
• Proven History: Successfully completed ≥ 10 intermediate issues in this repo.
• Consistency: ≥ 3–4 months of active, human-led contributions to this SDK.

Note

CI/CD Exception: For issues focused on GitHub Actions / Workflows, the repo-specific thresholds above may be waived if the contributor demonstrates advanced-level proficiency in CI/CD.

⚠️ AI Usage Policy

• Using AI to generate code for Advanced issues is strictly discouraged
• AI may be used to help explain file relationships, but cannot be the main source of research.
• Submitting AI-generated or unvalidated code is grounds for immediate closure

⏱️ Timeline & Workflow

• Typical time: ~1 month / ~50 hours.
• 🔴 Completing an advanced issue in 1–3 days is a red flag and will likely be rejected.
• Suggested: Post your proposed architectural approach as a comment and wait for explicit maintainer approval before writing any code.

🔬 Technical Domains

• API Client Architecture (request → serialization → execution → response mapping)
• Backward Compatibility (preserving method signatures, defaults, and return types)
• Protobuf Alignment (reading .proto files, _to_proto() / _from_proto() correctness)
• State & Immutability (correct usage of guards like _require_not_frozen)
• Execution Boundaries (retry logic, backoff, node selection, gRPC deadlines)
• Testing (unit, integration, mocking, test coverage for edge cases and failure modes)

🛡️ Quality & Review Standards

Advanced PRs must be "safe, maintainable, architecturally sound, and production-ready."

1. Architectural Fit: The solution must fit naturally into the existing SDK abstractions.
2. Security & Correctness: Evaluate all logic for injection risks, state corruption, or thread-safety issues.
3. Maintainability: Code must be short and clear enough for any other maintainer to debug without your assistance.
4. Backward Compatibility: Public API signatures must be preserved. If a breaking change is required, it must be explicitly managed through a deprecation cycle.
5. Comprehensive Testing: Must include unit and integration tests covering all new logic paths, edge cases, and failure modes. AI generated tests based on AI generated code is grounds for immediate rejection.

✅ PR Quality Checklist

Before opening your PR, the contributor must confirm:

• I have spent the majority of my time researching the problem and solution space extensively, including reviewing relevant code, documentation, and external resources.
• I understand the system-wide impact of these changes on affected modules and performance.
• The system design fits with current Hiero SDK architectural approaches.
• I have tested my changes extensively against both local and network environments.
• I have verified naming, types, and field ordering against pinned Protobufs.
• Every line of code is personally understood and explainable.

📚 Resources & Support

References:

• Hedera Protobufs

Python SDK References:

• SDK Project Structure
• Transaction Lifecycle
• Executable Architecture
• Hedera Protobufs (services)
• Browse closed advanced PRs — see how others did it

🆘 Stuck?

• Community Calls
• Discord

[github-actions]

@coderabbitai plan

[coderabbitai]

Coding Plan

Summary

• Follow the generate_record boolean field pattern exactly for high_volume initialization, serialization, and deserialization
• Follow the batch_key setter pattern for the set_high_volume() method with freeze guard
• Reuse existing test infrastructure (mock_client, mock_account_ids, env fixtures) rather than creating new abstractions
• Mirror the structure of account_create_transaction.py for the example to maintain consistency

Design Choices

Design Choice 1: Protobuf field naming convention for `high_volume`

Options Considered:

1. Use camelCase highVolume (like older fields: generateRecord, transactionFee)
2. Use snake_case high_volume (like newer fields: batch_key, max_custom_fees)

Chosen Option: 2

Rationale: Use snake_case high_volume because the field number 1002 indicates it's a newer addition, and recent proto fields in the SDK use snake_case naming.

💡 User Tips

Regenerate the plan with different choices with @coderabbitai <feedback>.

Implementation Steps

Phase 1: Core Transaction Base Class Changes

Add the high_volume boolean field to the Transaction base class following the established pattern of generate_record for boolean fields and batch_key for setters with freeze guards.

Task 1: Add Instance Variable

Add the high_volume boolean instance variable to the Transaction.__init__() method.

• Add self.high_volume = False in src/hiero_sdk_python/transaction/transaction.py __init__ method, positioned after self.generate_record = False
• Follow the exact pattern of generate_record (bare boolean, no type annotation, default False)

Task 2: Add Setter Method

Add a fluent setter method set_high_volume() with proper freeze guard validation.

• Add set_high_volume(self, high_volume: bool) method in src/hiero_sdk_python/transaction/transaction.py
• First line must call self._require_not_frozen() to prevent mutation after freezing
• Validate that high_volume is a boolean type, raise TypeError if not
• Set self.high_volume = high_volume and return self for method chaining
• Position the method near other base-class setters (after set_transaction_id() around line 600)

Task 3: Wire Protobuf Serialization

Add high_volume to the protobuf body during transaction serialization.

• Update build_base_transaction_body() in src/hiero_sdk_python/transaction/transaction.py
• Add transaction_body.high_volume = self.high_volume after the generateRecord assignment (around line 478)
• Follow the direct assignment pattern used by generateRecord (no conditional guard needed since it's always a boolean)

Task 4: Wire Protobuf Deserialization

Add high_volume restoration in the _from_protobuf() class method.

• Update _from_protobuf() in src/hiero_sdk_python/transaction/transaction.py
• Add transaction.high_volume = transaction_body.high_volume after the generate_record restoration (around line 854)
• Follow the symmetric pattern used by generate_record (direct assignment without guards)

🤖 Prompt for AI agents

Implement the `high_volume` boolean field on the `Transaction` base class in
`src/hiero_sdk_python/transaction/transaction.py`. The goal is to add full
support for the field: initialization, a fluent setter with freeze guard,
protobuf serialization, and deserialization.

**Task 1 — Add Instance Variable in `__init__`:**
- Add `self.high_volume = False` after `self.generate_record = False`
- Use the same pattern as `generate_record`: bare boolean, no type annotation,
default `False`

**Task 2 — Add Setter Method `set_high_volume()`:**
- Add the method `set_high_volume(self, high_volume: bool)` near other
base-class setters (after `set_transaction_id()`, around line 600)
- First line: call `self._require_not_frozen()` to prevent mutation after
freezing
- Validate `high_volume` is a `bool`; raise `TypeError` if not
- Assign `self.high_volume = high_volume` and `return self` for fluent chaining

**Task 3 — Wire Serialization in `build_base_transaction_body()`:**
- Add `transaction_body.high_volume = self.high_volume` after the
`generateRecord` assignment (around line 478)
- Use direct assignment with no conditional guard (always a boolean)

**Task 4 — Wire Deserialization in `_from_protobuf()`:**
- Add `transaction.high_volume = transaction_body.high_volume` after the
`generate_record` restoration (around line 854)
- Use direct assignment, symmetric with the `generate_record` pattern

Phase 2: Testing

Add comprehensive unit tests and integration tests following established patterns from batch_transaction_test.py and account_create_transaction_e2e_test.py.

Task 1: Create Unit Test File

Create a dedicated unit test file for the high_volume transaction field.

• Create tests/unit/high_volume_transaction_test.py
• Add pytestmark = pytest.mark.unit at module level
• Import required fixtures from conftest.py (mock_account_ids, mock_client, private_key)
• Import TransferTransaction (or AccountCreateTransaction) as the test subject
• Import TransactionId for manual transaction ID generation

Task 2: Implement Default Value Test

Test that high_volume defaults to False on new transactions.

• Add test function test_high_volume_defaults_to_false()
• Create a new AccountCreateTransaction() instance
• Assert transaction.high_volume is False

Task 3: Implement Setter Tests

Test the setter method behavior including return value and type validation.

• Add test_set_high_volume_returns_self() — verify fluent chaining works
• Add test_set_high_volume_to_true() — verify value is stored correctly
• Add test_set_high_volume_to_false() — verify can set back to False
• Add test_set_high_volume_validates_boolean_type() — verify TypeError raised for non-boolean values

Task 4: Implement Freeze Guard Test

Test that set_high_volume() raises an exception after the transaction is frozen.

• Add test_cannot_set_high_volume_after_freeze(mock_client, mock_account_ids)
• Build and freeze a transaction using freeze_with(mock_client)
• Use pytest.raises(Exception, match="Transaction is immutable") to verify the guard

Task 5: Implement Round-Trip Serialization Test

Test that high_volume survives to_bytes() / from_bytes() serialization.

• Add test_high_volume_round_trip_serialization(mock_account_ids, private_key)
• Build a transaction with set_high_volume(True)
• Set transaction_id and node_account_id manually, then freeze() and sign()
• Call to_bytes() then from_bytes() to restore
• Assert restored_transaction.high_volume is True
• Assert transaction.to_bytes() == restored_transaction.to_bytes() for byte identity

Task 6: Implement Integration Test

Add integration test for account creation with high_volume=True.

• Add test function to tests/integration/account_create_transaction_e2e_test.py
• Name: test_create_account_with_high_volume_enabled(env)
• Create an AccountCreateTransaction with set_high_volume(True) and set_initial_balance(Hbar(2))
• Set a reasonable transaction_fee (e.g., Hbar(5)) to accommodate dynamic pricing
• Execute and assert receipt.status == ResponseCode.SUCCESS
• Verify the account was created by checking receipt.account_id is not None

🤖 Prompt for AI agents

Create unit and integration tests for the `high_volume` field. Follow patterns
from `batch_transaction_test.py` and `account_create_transaction_e2e_test.py`.

**Task 1 — Create `tests/unit/high_volume_transaction_test.py`:**
- Set `pytestmark = pytest.mark.unit` at module level
- Import fixtures from `conftest.py`: `mock_account_ids`, `mock_client`,
`private_key`
- Import `AccountCreateTransaction` (or `TransferTransaction`) as the test
subject
- Import `TransactionId`

**Task 2 — Default Value Test (`test_high_volume_defaults_to_false`):**
- Instantiate `AccountCreateTransaction()`
- Assert `transaction.high_volume is False`

**Task 3 — Setter Tests:**
- `test_set_high_volume_returns_self()`: verify fluent chaining
(`set_high_volume()` returns `self`)
- `test_set_high_volume_to_true()`: verify value is stored as `True`
- `test_set_high_volume_to_false()`: verify value can be set back to `False`
- `test_set_high_volume_validates_boolean_type()`: verify `TypeError` is raised
for non-boolean input

**Task 4 — Freeze Guard Test (`test_cannot_set_high_volume_after_freeze`):**
- Accepts `mock_client`, `mock_account_ids` fixtures
- Build and freeze a transaction using `freeze_with(mock_client)`
- Use `pytest.raises(Exception, match="Transaction is immutable")` to verify the
guard

**Task 5 — Round-Trip Serialization Test
(`test_high_volume_round_trip_serialization`):**
- Accepts `mock_account_ids`, `private_key` fixtures
- Build a transaction with `set_high_volume(True)`, set `transaction_id` and
`node_account_id` manually, then `freeze()` and `sign()`
- Call `to_bytes()` then `from_bytes()` and restore
- Assert `restored_transaction.high_volume is True`
- Assert `transaction.to_bytes() == restored_transaction.to_bytes()`

**Task 6 — Integration Test in
`tests/integration/account_create_transaction_e2e_test.py`:**
- Add `test_create_account_with_high_volume_enabled(env)`
- Create an `AccountCreateTransaction` with `set_high_volume(True)` and
`set_initial_balance(Hbar(2))`
- Set `transaction_fee` to `Hbar(5)` to accommodate dynamic pricing
- Execute and assert `receipt.status == ResponseCode.SUCCESS`
- Assert `receipt.account_id is not None`

Phase 3: Example

Create a practical example demonstrating high-volume account creation following the existing example patterns.

Task 1: Create High-Volume Example File

Create a new example demonstrating the high-volume account creation pattern.

• Create examples/transaction/high_volume_account_creation.py
• Add module docstring explaining HIP-1313, high-volume throttles, and the importance of setting max_transaction_fee
• Document environment variables: OPERATOR_ID, OPERATOR_KEY, NETWORK (optional)
• Import AccountCreateTransaction, Client, PrivateKey, Hbar, ResponseCode

Task 2: Implement Example Logic

Implement the example function demonstrating the usage pattern from the ticket.

• Create create_high_volume_account(client: Client) function
• Generate a new Ed25519 key pair for the account
• Build transaction using fluent pattern: AccountCreateTransaction() → set_key_without_alias() → set_initial_balance() → set_high_volume(True)
• Set transaction fee to Hbar(5) to handle dynamic pricing (use transaction.transaction_fee = Hbar(5).to_tinybars())
• Execute with freeze_with(client).sign(operator_key).execute(client)
• Handle success (print account ID and keys) and failure (print error, sys.exit(1))
• Add if __name__ == "__main__" block with Client.from_env(), function call, and client.close()

🤖 Prompt for AI agents

Create a new example file at
`examples/transaction/high_volume_account_creation.py` demonstrating HIP-1313
high-volume account creation. Mirror the structure of
`account_create_transaction.py`.

**Task 1 — Create File and Imports:**
- Add a module docstring explaining HIP-1313, high-volume throttles, and the
importance of setting `max_transaction_fee`
- Document environment variables: `OPERATOR_ID`, `OPERATOR_KEY`, `NETWORK`
(optional)
- Import `AccountCreateTransaction`, `Client`, `PrivateKey`, `Hbar`,
`ResponseCode`

**Task 2 — Implement `create_high_volume_account(client: Client)`:**
- Generate a new Ed25519 key pair for the account
- Build the transaction using the fluent pattern: `AccountCreateTransaction()` →
`set_key_without_alias()` → `set_initial_balance()` → `set_high_volume(True)`
- Set transaction fee to `Hbar(5)` for dynamic pricing:
`transaction.transaction_fee = Hbar(5).to_tinybars()`
- Execute with `freeze_with(client).sign(operator_key).execute(client)`
- On success: print account ID and keys
- On failure: print error and call `sys.exit(1)`
- Add `if __name__ == "__main__"` block using `Client.from_env()`, call the
function, then `client.close()`

Research

The hiero-sdk-python SDK is organized into sub-packages under src/hiero_sdk_python/, with the Transaction base class in transaction/transaction.py extending _Executable from executable.py. The SDK uses protobuf bindings generated from hiero-consensus-node v0.72.1, which includes the high_volume field (field number 1002) in TransactionBody. Existing boolean fields like generate_record and cross-cutting fields like batch_key provide clear implementation patterns. Unit tests in tests/unit/ use the mock_hedera_servers context manager for network simulation, while integration tests in tests/integration/ use the env fixture providing a real IntegrationTestEnv client. Examples in examples/ follow a consistent structure with module docstrings, Client.from_env(), and domain-specific functions.

---

🚀 Next Steps

🤖 All AI agent prompts combined

Task: 1

Implement the `high_volume` boolean field on the `Transaction` base class in
`src/hiero_sdk_python/transaction/transaction.py`. The goal is to add full
support for the field: initialization, a fluent setter with freeze guard,
protobuf serialization, and deserialization.

**Task 1 — Add Instance Variable in `__init__`:**
- Add `self.high_volume = False` after `self.generate_record = False`
- Use the same pattern as `generate_record`: bare boolean, no type annotation,
default `False`

**Task 2 — Add Setter Method `set_high_volume()`:**
- Add the method `set_high_volume(self, high_volume: bool)` near other
base-class setters (after `set_transaction_id()`, around line 600)
- First line: call `self._require_not_frozen()` to prevent mutation after
freezing
- Validate `high_volume` is a `bool`; raise `TypeError` if not
- Assign `self.high_volume = high_volume` and `return self` for fluent chaining

**Task 3 — Wire Serialization in `build_base_transaction_body()`:**
- Add `transaction_body.high_volume = self.high_volume` after the
`generateRecord` assignment (around line 478)
- Use direct assignment with no conditional guard (always a boolean)

**Task 4 — Wire Deserialization in `_from_protobuf()`:**
- Add `transaction.high_volume = transaction_body.high_volume` after the
`generate_record` restoration (around line 854)
- Use direct assignment, symmetric with the `generate_record` pattern
===============================================================================

Task: 2

Create unit and integration tests for the `high_volume` field. Follow patterns
from `batch_transaction_test.py` and `account_create_transaction_e2e_test.py`.

**Task 1 — Create `tests/unit/high_volume_transaction_test.py`:**
- Set `pytestmark = pytest.mark.unit` at module level
- Import fixtures from `conftest.py`: `mock_account_ids`, `mock_client`,
`private_key`
- Import `AccountCreateTransaction` (or `TransferTransaction`) as the test
subject
- Import `TransactionId`

**Task 2 — Default Value Test (`test_high_volume_defaults_to_false`):**
- Instantiate `AccountCreateTransaction()`
- Assert `transaction.high_volume is False`

**Task 3 — Setter Tests:**
- `test_set_high_volume_returns_self()`: verify fluent chaining
(`set_high_volume()` returns `self`)
- `test_set_high_volume_to_true()`: verify value is stored as `True`
- `test_set_high_volume_to_false()`: verify value can be set back to `False`
- `test_set_high_volume_validates_boolean_type()`: verify `TypeError` is raised
for non-boolean input

**Task 4 — Freeze Guard Test (`test_cannot_set_high_volume_after_freeze`):**
- Accepts `mock_client`, `mock_account_ids` fixtures
- Build and freeze a transaction using `freeze_with(mock_client)`
- Use `pytest.raises(Exception, match="Transaction is immutable")` to verify the
guard

**Task 5 — Round-Trip Serialization Test
(`test_high_volume_round_trip_serialization`):**
- Accepts `mock_account_ids`, `private_key` fixtures
- Build a transaction with `set_high_volume(True)`, set `transaction_id` and
`node_account_id` manually, then `freeze()` and `sign()`
- Call `to_bytes()` then `from_bytes()` and restore
- Assert `restored_transaction.high_volume is True`
- Assert `transaction.to_bytes() == restored_transaction.to_bytes()`

**Task 6 — Integration Test in
`tests/integration/account_create_transaction_e2e_test.py`:**
- Add `test_create_account_with_high_volume_enabled(env)`
- Create an `AccountCreateTransaction` with `set_high_volume(True)` and
`set_initial_balance(Hbar(2))`
- Set `transaction_fee` to `Hbar(5)` to accommodate dynamic pricing
- Execute and assert `receipt.status == ResponseCode.SUCCESS`
- Assert `receipt.account_id is not None`
===============================================================================

Task: 3

Create a new example file at
`examples/transaction/high_volume_account_creation.py` demonstrating HIP-1313
high-volume account creation. Mirror the structure of
`account_create_transaction.py`.

**Task 1 — Create File and Imports:**
- Add a module docstring explaining HIP-1313, high-volume throttles, and the
importance of setting `max_transaction_fee`
- Document environment variables: `OPERATOR_ID`, `OPERATOR_KEY`, `NETWORK`
(optional)
- Import `AccountCreateTransaction`, `Client`, `PrivateKey`, `Hbar`,
`ResponseCode`

**Task 2 — Implement `create_high_volume_account(client: Client)`:**
- Generate a new Ed25519 key pair for the account
- Build the transaction using the fluent pattern: `AccountCreateTransaction()` →
`set_key_without_alias()` → `set_initial_balance()` → `set_high_volume(True)`
- Set transaction fee to `Hbar(5)` for dynamic pricing:
`transaction.transaction_fee = Hbar(5).to_tinybars()`
- Execute with `freeze_with(client).sign(operator_key).execute(client)`
- On success: print account ID and keys
- On failure: print error and call `sys.exit(1)`
- Add `if __name__ == "__main__"` block using `Client.from_env()`, call the
function, then `client.close()`

💡 Iterate on the plan with: @coderabbitai <feedback>

Example Feedback
- `@coderabbitai` You can skip phase 3. Add a simple unit test case for phase 2.
- `@coderabbitai` For design choice 1 go ahead with option 3 and replan.

---

💬 Have feedback or questions? Drop into our discord!

[github-actions]

Hello, this is CommunityCallBot.

This is a reminder that the Hiero Python SDK Community Call will begin in approximately 3 hours and 3 minutes (14:00 UTC).

The call is an open forum where contributors and users can discuss topics, raise issues, and influence the direction of the Python SDK.

Details:

• Time: 14:00 UTC
• Join Link: Zoom Meeting

Disclaimer: This is an automated reminder. Please verify the schedule here for any changes.

[bhuvan-somisetty]

/assign

[exploreriii]

Bhuvan this is assigned to @aceppaluni please can you try another available issue

[github-actions]

Hi @aceppaluni 👋

This issue has been assigned but no pull request has been created yet.
Are you still planning on working on it?
If you are, please create a draft PR linked to this issue or comment /working to let us know.
If you’re no longer able to work on this issue, you can comment /unassign to release it.

From the Python SDK Team

[aceppaluni]

/working