HIP-1313: Enable a new high volume entity creation option

HIP/hip-1313.md

@@ -0,0 +1,381 @@
+---
+hip: 1313
+title: High-Volume Entity Creation
+author: Richard Bair (@rbair23), Joseph Sinclair (@jsync-swirlds)
+type: Standards Track
+category: Core
+requested-by: Hashgraph
+discussions-to: https://github.com/hiero-ledger/hiero-improvement-proposals/pull/1313
+needs-hiero-approval: Yes
+needs-hedera-review: Yes
+status: Last Call
+last-call-date-time: 2025-12-30T07:00:00Z
+created: 2025-10-17
+updated: 2025-12-16
+requires: 1261
+---
+
+## Abstract
+This proposal introduces a second set of limits on how quickly new entities,
+like accounts or tokens, can be created on the Hiero network. These new limits,
+called **high-volume throttles**, sit alongside the existing standard throttles.
+Users can choose to use these high-volume throttles by setting a simple flag in
+their transaction. When they do this, they agree to pay extra during busy times
+to access this additional capacity. The standard throttles remain unchanged,
+with their own capacity and fixed prices, ensuring regular users experience no
+disruptions.
+
+## Motivation
+Networks like Hiero use limits, or throttles, to manage the flow of
+transactions. This prevents any single activity from overwhelming the system,
+protecting against overuse of storage, processing power, or network bandwidth.
+For instance, creating new accounts might be limited to a few per second across
+the entire network, while transferring tokens could allow thousands per second.
+
+These throttles work well for everyday use but can slow down applications that
+need to create many items quickly, such as onboarding large groups of users.
+During peak times, these applications face delays as they wait for available
+slots under the standard throttles. This proposal adds a way for users to access
+extra capacity when needed, without affecting those using the standard throttle
+system.
+
+## Rationale
+The design creates a new parallel system for handling transactions that create
+new items, without changing the existing throttle system.
+
+### Standard Throttle System (Unchanged)
+Transactions without the special flag use the existing throttles and prices:
+- Fixed costs based on the current fee schedule.
+- Predictable capacity that operates independently of the high-volume system.
+- No need for any changes in existing applications, unless they want to take
+  advantage of enhanced throttles.
+
+### High-Volume Throttle System (New)
+Transactions with the flag set use a separate set of throttles with the
+following characteristics:
+- Dedicated capacity that does not overlap with the standard system.
+   - Transactions that use the high volume throttle do not use the "normal"
+     throttle capacity at all.
+- Prices that increase based on how busy this high-volume capacity is,
+  encouraging efficient use.
+   - Even when the high-volume capacity is idle, prices may be higher than the
+     standard throttle system.
+   - Prices in the high-volume system follow a clear formula set by network
+     governance, avoiding surprises from market fluctuations or hidden rules.
+      - This does not mean prices are static; other transactions in the network
+        can change the price paid by increasing throttle usage.
+   - The duration during which a high volume throttle applies is also set by
+     network governance.
+- Users must actively choose this option and can set a maximum price they're
+  willing to pay.
+
+Importantly, choosing high-volume does not give transactions priority over
+others; all are processed in the order they arrive, maintaining fairness.
+
+## User Stories
+- **As a developer**, I can opt to pay more during busy periods to create items
+  at a higher rate without being blocked by standard throttles.
+- **As a developer**, I can set a maximum fee for high-volume transactions to
+  control costs.
+- **As a developer**, I can estimate costs in advance to plan my operations
+  effectively when not using high volume throttles.
+- **As a developer**, I can roughly estimate costs in advance and coordinate
+  with my operations budget effectively when using high volume throttles.
+- **As a developer**, my existing applications continue working unchanged using
+  standard throttles.
+- **As a developer**, my transactions are processed fairly alongside all others,
+  regardless of the limit system used.
+- **As a new user**, I pay standard prices by default and only encounter higher
+  costs if I explicitly choose the high-volume throttle system **and** during
+  peak periods for the specific transaction I’m submitting.
+- **As a network operator**, high-volume capacity is protected from abuse
+  through increasing costs, making prolonged attacks expensive.
+
+## Specification
+
+### Key Concepts
+- **Throttle**: A limit on the volume of transactions to protect network
+  resources.
+- **Entity Creation**: Making new items like accounts, tokens, or files on the
+  network.
+- **Utilization Percentage**: How much of the available capacity is currently in
+  use (0% empty, 100% full).
+- **Pricing Curve**: A formula that determines how much extra to charge based on
+  utilization.
+
+### Transaction Changes
+A new optional field is added to the basic transaction structure:
+
+```protobuf
+syntax = "proto3";
+message TransactionBody {
+  // Existing fields remain unchanged...
+  /**
+   * If set to true, this transaction uses high-volume throttles and pricing
+   * for entity creation. It only affects supported transaction types; otherwise,
+   * it is ignored.
+   */
+  bool high_volume = 25;
+}
+```
+
+This field applies to transactions involving entity creation, such as:
+- `ConsensusCreateTopic`
+- `ContractCreate` (HAPI call)
+- `CryptoApproveAllowance`
+- `CryptoCreate`
+- `CryptoTransfer` (when creating new accounts)
+- `FileCreate`
+- `LambdaSStore`
+- `ScheduleCreate`
+- `TokenAirdrop`
+- `TokenAssociateToAccount`
+- `TokenCreate`
+- `TokenClaimAirdrop`
+- `TokenMint`
+
+For example, a `CryptoTransfer` that creates accounts uses high-volume pricing
+for those creations but standard throttles for the transfers themselves.
+Note that EVM transactions which create entities are not included in this HIP.
+EVM specific behavior will be defined in a subsequent HIP for greater clarity.
+
+### High-Volume Throttles Configuration
+High-volume throttles are defined separately in the network's throttle settings.
+Each has its own capacity, marked as high-volume:
+
+```json
+{
+  "buckets": [
+    {
+      "burstPeriodMs": 15000,
+      "name": "HighVolumeCryptoThrottles",
+      "highVolume": true,
+      "throttleGroups": [
+        {
+          "milliOpsPerSec": 10500000,
+          "operations": [
+            "ScheduleCreate",
+            "CryptoCreate"
+          ]
+        }
+      ]
+    },
+    {
+      "burstPeriodMs": 15000,
+      "name": "HighVolumeTotalThrottles",
+      "highVolume": true,
+      "throttleGroups": [
+        {
+          "milliOpsPerSec": 31500000,
+          "operations": [
+            "ScheduleCreate",
+            "CryptoCreate",
+            // all entity create transactions listed here
+          ]
+        }
+      ]
+    }
+  ]
+}
+```
+Notes on this example:
+- The burstPeriodMs should not be too short or too long.
+    - We have demonstrated 15s here as a reasonable value for a public network.
+- There are two levels of throttles. Closely related groups of transactions, or
+  individual transactions, have a particular throttle and pricing curve. At the
+  same time there is a maximum total entity creation rate for all transactions
+  combined that has a separate pricing curve that generally has effect only
+  if the total of all entity creation transactions exceeds the maximum for any
+  one entity class.
+
+### Pricing Configuration
+Pricing for high-volume is set in the fee definitions as a variable rate pricing
+structure:
+
+```protobuf
+syntax = "proto3";
+
+message ServiceFeeDefinition {
+  // ... existing fields ...
+
+  /**
+   * Variable rate pricing configuration for this fee definition.
+   * If not specified, variable rates are not supported for this
+   * transaction type, and the transaction will be charged the standard fee.
+   */
+  VariableRateDefinition high_volume_rates = 5;
+}
+
+/**
+ * Defines the configuration for variable rate pricing.
+ * If variable rate pricing is in effect, the resulting fee multiplier will be a
+ * value between 1 (standard fee) and `max_multiplier` (cost ceiling). If a
+ * `pricing_curve` is specified, then the multiplier will be determined by the
+ * utilization percentage of the variable rate throttle and the pricing curve. If
+ * no `pricing_curve` is specified, then the multiplier will be interpolated
+ * on an _effective_ pricing curve described by a straight line
+ * between the standard fee and `max_multiplier` * `standard_fee`.
+ */
+message VariableRateDefinition {
+  /**
+   * Maximum multiplier to prevent extreme pricing (cost ceiling).
+   * Given the normal price of the transaction, the computed variable price
+   * will not exceed `max_multiplier` * `standard_fee`. Provides predictability
+   * for users regardless of utilization. The minimum price will be the
+   * `standard_fee`. This value is divided by 1,000,000 and then added to the
+   * minimum value of 1.
+   * <p>
+   * ##Example
+   * A value of `2,450,300` results in an _effective_ floating point multiplier
+   * of `3.4503`.<br/>
+   * A value of `0` results in an _effective_ floating point
+   * multiplier of `1.0`.
+   */
+  uint32 max_multiplier = 2;
+
+  /**
+   * Pricing curve configuration defining how fees scale with variable rate
+   * capacity utilization. Given a utilization percentage (0.0 to 1.0), the
+   * pricing curve determines the multiplier to use. If the curve returns a
+   * multiplier greater than `max_multiplier`, then `max_multiplier`
+   * will be used.
+   * <p>
+   * If the pricing_curve is not specified, then the multiplier will be linearly
+   * interpolated between 1 and `max_multiplier`.
+   */
+  PricingCurve pricing_curve = 3;
+}
+
+/**
+ * Defines the pricing curve used for variable rate calculations.
+ * This can be one of several types of curves, each with its own formula for
+ * calculating the multiplier based on the utilization percentage of the
+ * variable rate throttle.
+ */
+message PricingCurve {
+  oneof curve_type {
+    PiecewiseLinearCurve piecewise_linear = 1;
+  }
+}
+
+/**
+ * Contains a set of points (utilization, multiplier) that define a piecewise
+ * linear curve for variable pricing. Each point represents a linear segment
+ * between two utilization thresholds. The multiplier to use is interpolated
+ * between these points based on the current utilization percentage.
+ *
+ * For example, given points
+ *  - (0.0, 1.0)
+ *  - (0.5, 2.0)
+ *  - (1.0, 5.0)
+ * The multiplier for a utilization of 0.75 would be interpolated between the
+ * second and third points, resulting in a multiplier of 3.5.
+ */
+message PiecewiseLinearCurve {
+  /**
+   * A list of points defining the piecewise linear curve.
+   * Each point is a pair of (utilization_percentage, multiplier). The list
+   * must be sorted by utilization_percentage in ascending order, and
+   * sub-ordered by multiplier in ascending order for points with the same
+   * utilization percentage. It is legal to have two points with the same
+   * utilization percentage, but they must have different multipliers.
+   * This allows the creation of stepped pricing curves.
+   */
+  repeated PiecewiseLinearPoint points = 1;
+}
+
+/**
+ * Represents a single point in a piecewise linear curve, with a utilization
+ * percentage and the corresponding multiplier.
+ */
+message PiecewiseLinearPoint {
+  /**
+   * The utilization percentage for this point, in thousandths of one percent.
+   * This value must be between 0 and 100,000, inclusive.
+   */
+  uint32 utilization_percentage = 1;
+
+  /**
+   * The multiplier to apply at this utilization percentage.
+   * This value is divided by 1,000,000 then added to 1.
+   */
+  uint32 multiplier = 2;
+}
+```
+
+Limits and pricing are configured independently for flexibility.
+
+### Fee Calculation Steps
+For high-volume transactions:
+1. Measure current utilization of high-volume throttles.
+2. Compute standard fee.
+3. Determine multiplier from pricing curve (capped at `max_multiplier`).
+4. Final `fee = standard fee × multiplier` (but not exceeding user's
+   `maxTransactionFee`).
+
+## Mirror Node Changes
+1. Add high volume fields to relevant APIs (e.g. `/api/v1/transactions`,
+   `/api/v1/transactions/{id}` and the list of transactions
+   within `/api/v1/accounts/{id}`)
+2. Incorporate high volume as an estimation option in fee estimation.
+
+## Backwards Compatibility
+No changes for transactions without the `high_volume` flag. Existing
+applications work as before.
+
+## Security Implications
+High-volume does not alter transaction order or bypass total network limits on
+storage. Increasing prices deter abuse, as sustaining high utilization becomes
+costly.
+
+## How to Teach This
+
+### For Developers
+Use high-volume like this (Java SDK example):
+
+```java
+AccountCreateTransaction tx = new AccountCreateTransaction()
+    .setKey(publicKey)
+    .setInitialBalance(Hbar.from(10))
+    .setHighVolume(true)  // Opt in
+    .setMaxTransactionFee(Hbar.from(5));  // Set cost limit
+```
+
+Always check current rates:
+
+```java
+// Query the Mirror Node for a fee estimate
+HighVolumeRateInfo info = client.getHighVolumeRate(HieroFunctionality.CRYPTO_CREATE);
+if (info.getCurrentHighVolumeFee().compareTo(Hbar.from(3)) <= 0) {
+    // Use high-volume
+} else {
+    // Fall back to standard
+}
+```
+
+Use high-volume for bursts or time-sensitive tasks; stick to standard for
+routine work.
+
+### For SDK Maintainers
+Add methods for setting `high_volume`. Enforce fee limits and provide helpers
+for estimation.
+Add methods to query and estimate costs for transactions using the `high_volume`
+setting.
+
+### For Users
+High-volume throttles open a new avenue to unblock use cases that require entity
+creation during peak times while maintaining fair ordering. Always set price
+limits when using high-volume throttles.
+
+### For Operators
+Allocate capacity, set pricing curves, and monitor usage to balance
+accessibility and protection.
+
+## References
+- [HIP-1261 Simple Fees](https://hips.hedera.com/hip/hip-1261)
+
+## Copyright/license
+This document is licensed under the Apache License, Version 2.0 — see LICENSE
+or https://www.apache.org/licenses/LICENSE-2.0.
+
+