HIP-1313: High-Volume Entity Creation

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:

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
• FileAppend
• HookStore
• 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:

{
  "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:

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}). An example response is shown below with other fields omitted:

   {
     ...
     "high_volume": true
   }
   

2. Incorporate high volume as an estimation option in fee estimation. The existing fee estimate JSON response will be enhanced to add a new high_volume_multiplier field. The actual totals in the response will not be multiplied by the multiplier. If users want to see how their fees are impacted by high volume pricing they only need to multiply the fee total by the new multiplier to get the final pricing. This allows users to get both the regular and high-volume pricing with a single call and simplifies the API by not requiring another parameter.

   {
     ...
     "high_volume_multiplier": 100
   }
   

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):

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:

// 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

Copyright/license

This document is licensed under the Apache License, Version 2.0 — see LICENSE or https://www.apache.org/licenses/LICENSE-2.0.

Citation

Please cite this document as: