Skip to content

Commit 251d676

Browse files
updates from PR review
Signed-off-by: krystal <56278409+theekrystallee@users.noreply.github.com>
1 parent daa45ef commit 251d676

File tree

1 file changed

+75
-49
lines changed

1 file changed

+75
-49
lines changed

hedera/core-concepts/high-volume-entity-creation.mdx

Lines changed: 75 additions & 49 deletions
Original file line numberDiff line numberDiff line change
@@ -15,8 +15,8 @@ supported transaction, you opt into dedicated capacity with higher throughput li
1515
tradeoff: **fees are variable and increase with utilization.**
1616

1717
<Info>
18-
The standard throttle system is completely unaffected. Existing applications that do not
19-
set the `high_volume` flag will work exactly as before — same capacity, same pricing.
18+
The standard throttle system is completely unaffected. Existing applications that do not
19+
set the `high_volume` flag will work exactly as before — same capacity, same pricing.
2020
</Info>
2121

2222
---
@@ -81,28 +81,43 @@ cost more than the same transaction sent through the standard throttle — even
8181
there is no congestion. Always check the current multiplier before committing to a batch.
8282
</Warning>
8383

84-
### Pricing Curve Example
84+
### Pricing Curve
85+
86+
The base curve below is set by Hedera governance and defines how the fee
87+
multiplier scales with throughput in the high-volume lane. The multiplier is
88+
expressed relative to the standard base fee, and the throughput rate is
89+
expressed as a multiplier of the base entity creation rate.
90+
91+
| **High-Volume Throughput (× base create rate)** | **Fee Multiplier (× base price)** |
92+
|---|---|
93+
| 1 ||
94+
| 1.5 ||
95+
| 2.5 | 10× |
96+
| 3.5 | 15× |
97+
| 5 | 20× |
98+
| 7.5 | 30× |
99+
| 10 | 40× |
100+
| 25 | 60× |
101+
| 50 | 80× |
102+
| 100 | 100× |
103+
| 250 | 150× |
104+
| 500 | 200× |
105+
| 5,000 | 200× |
106+
107+
Between breakpoints, the multiplier is linearly interpolated. The curve
108+
assumes the standard (low-throughput) lane is running at its maximum rate
109+
concurrently.
85110

86-
The actual curve values are set by network governance and may change. The HIP provides
87-
this example of a piecewise linear curve with three breakpoints:
88-
89-
| Utilization | Multiplier | Effect on a $0.05 Base Fee |
90-
|---|---|---|
91-
| 0% | 1.0× | $0.05 |
92-
| 50% | 2.0× | $0.10 |
93-
| 100% | 5.0× | $0.25 |
94-
95-
Between breakpoints, the multiplier is linearly interpolated. For example, at 75%
96-
utilization, the multiplier would be 3.5× (halfway between 2.0× and 5.0×). If no
97-
pricing curve is explicitly configured, the multiplier defaults to linear interpolation
98-
between 1.0× and `max_multiplier`.
111+
<Warning>
112+
At the base create rate (1×), high-volume transactions already cost **4× the
113+
standard fee**. At 100× throughput, the multiplier reaches **100×**. The curve
114+
caps at **200×** regardless of how much higher throughput goes. Always set
115+
`maxTransactionFee` to protect against unexpected costs.
116+
</Warning>
99117

100118
<Note>
101-
These values are from the HIP specification as an example. Actual pricing curve
102-
breakpoints will be configured by Hedera governance before launch. The `max_multiplier`
103-
value (also governance-configured) caps how high the multiplier can go regardless of
104-
the curve. Use the Mirror Node fee estimation endpoint to see the **current** multiplier
105-
in effect.
119+
This curve may be updated by Hedera governance. Use the Mirror Node fee
120+
estimation endpoint to see the **current** multiplier in effect.
106121
</Note>
107122

108123
---
@@ -113,8 +128,8 @@ The `high_volume` flag is supported on the following entity creation transaction
113128

114129
<Accordion title="View all 14 supported transaction types">
115130

116-
| Transaction Type | SDK Class | Notes |
117-
|---|---|---|
131+
| **Transaction Type** | **SDK Class** | **Notes** |
132+
|----|---|---|
118133
| `ConsensusCreateTopic` | `TopicCreateTransaction` | |
119134
| `ContractCreate` | `ContractCreateTransaction` | HAPI only, not EVM |
120135
| `CryptoApproveAllowance` | `AccountAllowanceApproveTransaction` | |
@@ -132,13 +147,17 @@ The `high_volume` flag is supported on the following entity creation transaction
132147

133148
</Accordion>
134149

135-
Setting `high_volume = true` on any other transaction type has no effect — the flag
136-
is silently ignored and the transaction processes through the standard system.
150+
The official Hedera SDKs expose `setHighVolume()` only on the transaction types
151+
listed above. If you are using a custom SDK or constructing protobuf transactions
152+
directly and set `high_volume = true` on a transaction type not in this list, the
153+
transaction **will not fail**. The flag is silently ignored and the transaction
154+
processes through the standard throttle system at standard pricing.
137155

138156
<Note>
139-
**EVM transactions are excluded.** Contract creations via `CREATE` / `CREATE2` opcodes
140-
in the EVM do not participate in the high-volume system. A subsequent HIP will address
141-
EVM-specific high-volume behavior.
157+
#### **EVM transactions are excluded**
158+
Contract creations via `CREATE` / `CREATE2` opcodes
159+
in the EVM do not participate in the high-volume system. A subsequent HIP will address
160+
EVM-specific high-volume behavior.
142161
</Note>
143162

144163
---
@@ -154,8 +173,8 @@ following example configuration (actual mainnet values will be set by governance
154173
| HighVolumeTotalThrottles | All 14 supported types combined | 31,500 ops/sec |
155174

156175
<Note>
157-
These values are from the HIP's example throttle configuration. Final mainnet and
158-
testnet capacity values will be set by Hedera governance and may differ.
176+
These values are from the HIP's example throttle configuration. Final mainnet and
177+
testnet capacity values will be set by Hedera governance and may differ.
159178
</Note>
160179

161180
A transaction must pass **both** its per-type bucket and the total bucket to be accepted.
@@ -175,7 +194,7 @@ Before submitting high-volume transactions, query the Mirror Node fee estimation
175194
to see the current `high_volume_multiplier`. The HIP specifies that this field will be
176195
added to the existing fee estimation response:
177196

178-
```bash
197+
```bash wrap
179198
curl "https://mainnet.mirrornode.hedera.com/api/v1/network/fees"
180199
```
181200

@@ -186,17 +205,15 @@ The fee totals in the response are **not** pre-multiplied — multiply the fee t
186205

187206
### Step 2: Set the Flag and a Fee Cap
188207

189-
<Tabs>
208+
<CodeGroup>
190209

191-
<Tab title="Java">
192-
193-
```java
210+
```java Java wrap
194211
// Create an account using high-volume throttles
195212
AccountCreateTransaction tx = new AccountCreateTransaction()
196213
.setKey(publicKey)
197214
.setInitialBalance(Hbar.from(10))
198-
.setHighVolume(true) // Opt into high-volume throttles
199-
.setMaxTransactionFee(Hbar.from(5)); // ALWAYS set a fee cap
215+
.setHighVolume(true) // Opt into high-volume throttles
216+
.setMaxTransactionFee(Hbar.from(5)); // ALWAYS set a fee cap
200217

201218
TransactionResponse response = tx.execute(client);
202219
TransactionReceipt receipt = response.getReceipt(client);
@@ -205,11 +222,8 @@ AccountId newAccountId = receipt.accountId;
205222
System.out.println("Account created: " + newAccountId);
206223
```
207224

208-
</Tab>
209-
210-
<Tab title="JavaScript">
211225

212-
```javascript
226+
```javascript JavaScript wrap
213227
// Create an account using high-volume throttles
214228
const tx = new AccountCreateTransaction()
215229
.setKey(publicKey)
@@ -224,11 +238,7 @@ const newAccountId = receipt.accountId;
224238
console.log("Account created: " + newAccountId);
225239
```
226240

227-
</Tab>
228-
229-
<Tab title="Go">
230-
231-
```go
241+
```go Go wrap
232242
// Create an account using high-volume throttles
233243
tx := hedera.NewAccountCreateTransaction().
234244
SetKey(publicKey).
@@ -249,9 +259,25 @@ if err != nil {
249259
fmt.Printf("Account created: %v\n", receipt.AccountID)
250260
```
251261

252-
</Tab>
262+
```rust Rust wrap
263+
// Create an account using high-volume throttle
264+
let tx = AccountCreateTransaction::new()
265+
.key(public_key)
266+
.initial_balance(Hbar::new(10))
267+
.high_volume(true) // Opt into high-volume throttles
268+
.max_transaction_fee(Hbar::new(5)) // ALWAYS set a fee cap
269+
.freeze_with(&client)?;
270+
271+
let response = tx.execute(&client).await?;
272+
let receipt = response.get_receipt(&client).await?;
273+
let new_account_id = receipt.account_id.unwrap();
274+
275+
println!("Account created: {:?}", new_account_id);
276+
277+
```
278+
279+
</CodeGroup>
253280

254-
</Tabs>
255281

256282
### Step 3: Handle Fee Failures Gracefully
257283

@@ -296,7 +322,7 @@ may follow patterns. Off-peak hours may offer lower multipliers.
296322
After a high-volume transaction reaches consensus, you can confirm its status via the
297323
Mirror Node REST API:
298324

299-
```bash
325+
```bash wrap
300326
curl "https://mainnet.mirrornode.hedera.com/api/v1/transactions/{transactionId}"
301327
```
302328

0 commit comments

Comments
 (0)