diff --git a/docs.json b/docs.json index d6dcacdd..a1c021e4 100644 --- a/docs.json +++ b/docs.json @@ -344,6 +344,7 @@ }, "hedera/core-concepts/keys-and-signatures", "hedera/core-concepts/scheduled-transaction", + "hedera/core-concepts/fee-model", { "group": "Smart Contracts", "pages": [ @@ -640,6 +641,12 @@ "hedera/sdks-and-apis/sdks/client", "hedera/sdks-and-apis/sdks/set-up-your-local-network", "hedera/sdks-and-apis/sdks/address-book", + { + "group": "Fees", + "pages": [ + "hedera/sdks-and-apis/sdks/fees/fee-estimation" + ] + }, { "group": "Keys", "pages": [ @@ -684,6 +691,7 @@ }, "hedera/sdks-and-apis/sdks/queries", "hedera/sdks-and-apis/sdks/general-errors", + { "group": "Accounts and HBAR", "pages": [ diff --git a/hedera/core-concepts/fee-model.mdx b/hedera/core-concepts/fee-model.mdx new file mode 100644 index 00000000..28194932 --- /dev/null +++ b/hedera/core-concepts/fee-model.mdx @@ -0,0 +1,377 @@ +--- +title: "Fee Model" +description: "Understand the simplified `base-fee-plus-extras` model for Hedera transaction and query fees introduced by [HIP-1261](https://hips.hedera.com/hip/hip-1261)" +--- + +## Overview + +Hedera uses a simplified fee model where every transaction cost is calculated as a **base fee plus extras**. Introduced in [HIP-1261](https://hips.hedera.com/hip/hip-1261), this model replaces the previous resource-weighted fee schedule with transparent, predictable pricing. + +All fees are defined in **USD as tinycents** and converted to HBAR at the current network exchange rate before being charged. The fee schedule is stored as a JSON document in system file `0.0.113` on the network. + + + **What is a tinycent?** One cent USD = 10⁸ tinycents. One dollar USD = 10¹⁰ tinycents. Tinycents provide high precision for fee calculations without floating-point math. + + + + +| Term | Definition | +| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------ | +| **Base Fee** | The fixed minimum fee in tinycents for a transaction or query before any extras are applied. | +| **Extras** | Additional cost factors on top of the base fee, such as signatures, bytes, keys, or gas. Each has a per-unit fee and an optional included count. | +| **Included Count** | Units of an extra included for free in the base fee before additional charges apply. | +| **Tinycent** | The smallest fee unit. 10⁸ tinycents = 1 cent USD. 10¹⁰ tinycents = 1 USD. | +| **Node Fee** | Fee paid to the submitting node. Same calculation for all transaction types. | +| **Network Fee** | A multiplier of the node fee covering consensus and storage. | +| **Service Fee** | Covers execution costs. Varies by transaction type. | + + + +## Fee Components + +Every transaction fee is split into three components: + +| Component | What It Covers | How It's Calculated | +| ----------- | ------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------- | +| **Node** | Compensates the submitting node for pre-checking and forwarding the transaction | `baseFee` + extras (processing bytes, signatures). Identical formula for **all** transaction types. | +| **Network** | Covers gossip, consensus, signature verification, and blockchain storage | A configurable multiplier of the node fee (default: 9×). | +| **Service** | Covers execution costs, state changes, and blockstream output | `baseFee` + transaction-specific extras (keys, token types, gas, etc.). Varies by transaction type. | + +```text +totalFee = nodeFee + networkFee + serviceFee +``` + +The node and network fees are uniform across all transaction types — only the service fee varies per transaction. + +## Extras + +Extras are additional cost factors applied on top of a base fee. Each extra has a **name**, a **per-unit fee** (in tinycents), and an optional **included count** — the number of units included for free before additional charges apply. Hedera transaction and query fees follow a `base fee + extras` [fee model](/hedera/core-concepts/fee-model) defined by [HIP-1261 (Simple Fees)](https://hips.hedera.com/hip/hip-1261). For current per-unit fees in USD, see the [mainnet fees page](/hedera/networks/mainnet/fees#extras). + +The following extras are defined in the fee schedule: + +| Extra | Description | +| --------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| `Signatures` | Signature verifications on the transaction. 1 included in base fee. | +| `Keys` | Keys defined when creating or updating an entity. 1 included in base fee. | +| `Accounts` | Accounts loaded during handling. 2 included on `CryptoTransfer`. | +| `TokenTypes` | Distinct token types referenced in a transfer. 1 included in base fee. | +| `Gas` | Gas consumed by hook program execution within transfers and by `ContractCallLocal` queries. | +| `Allowances` | Allowances granted on `ApproveAllowance`, or NFT allowances deleted on `DeleteAllowance`. 1 included in base fee. | +| `Airdrops` | Pending airdrops created — applies only when the recipient hasn't pre-associated the token. | +| `TokenTransferBase` | Applies once per `CryptoTransfer` with one or more token transfers when no token has custom fees. | +| `TokenTransferBaseCustomFees` | Applies once per `CryptoTransfer` with at least one custom-fee token. | +| `TokenCreateWithCustomFee` | Added to `TokenCreate` when custom fees or a `fee_schedule_key` are defined. | +| `TokenMintNft` | NFT serials minted on `TokenMint`. 1 included in base fee. | +| `TokenMintNftBase` | Added once per `TokenMint` operation that mints NFTs (not fungible). | +| `NftUpdate` | NFTs updated on `TokenUpdateNfts`. 1 included in base fee. | +| `TokenAssociate` | Token associations on `TokenAssociate` or auto-associations during a transfer. 1 included in base fee. | +| `ConsensusCreateTopicWithCustomFee` | Added to `ConsensusCreateTopic` when the new topic has custom fees defined. | +| `ConsensusSubmitMessageWithCustomFee` | Per message submitted to a topic with custom fees. | +| `ConsensusSubmitMessageWithCustomFeeBytes` | Per byte of message payload on a custom-fee topic. First 1,024 bytes included in base fee. | +| `ConsensusSubmitMessageWithoutCustomFeeBytes` | Per byte of message payload on a regular topic. First 100 bytes included in base fee. | +| `ScheduleCreateContractCallBase` | Added to `ScheduleCreate` when the scheduled inner operation is a contract call. | +| `Records` | Records returned by `TransactionGetRecord`. 1 included in base fee. | +| `StateBytes` | Bytes persisted to state on `FileCreate`, `FileUpdate`, or `FileAppend`. 1,000 bytes included per transaction. | +| `ProcessingBytes` | Transaction body bytes processed by the node. 1,350 included in the base fee. | +| `EvmDispatchSurcharge` | A 20% premium added to the HAPI fee of any operation invoked from a smart contract via Hedera's system contracts (HTS, HAS, HSS). Does not apply to pure-EVM operations. | + + + Hedera transaction and query fees follow a `base fee + extras` [fee model](/hedera/core-concepts/fee-model) defined by [HIP-1261 (Simple Fees)](https://hips.hedera.com/hip/hip-1261). + + + + The **included count** means you don't pay extra for typical usage. For example, the node fee includes a default allotment of processing bytes and one signature — a small, single-signature transaction pays zero byte and signature extras on the node component. + + +## Fee Calculation Example + +Consider a basic `CryptoCreate` transaction with a single key and 150 bytes: + + + + + +The node fee applies the same formula to all transactions: + +```text wrap +Node baseFee: 100,000 tinycents +ProcessingBytes extra: 150 bytes used, 1,024 included → 0 charged → 0 +Signatures extra: 1 signature, 1 included → 0 charged → 0 +───────────────────────────────────────────────────────────────────── +Node fee total: 100,000 tinycents +``` + + + + + +The network fee is a multiplier of the node fee: + +```text +Network fee = 9 × 100,000 = 900,000 tinycents +``` + + + + + +The service fee is specific to `CryptoCreate`: + +```text wrap +Service baseFee: 499,000,000 tinycents +Keys extra: 1 key used, 1 included → 0 charged → 0 +────────────────────────────────────────────────────────── +Service fee total: 499,000,000 tinycents +``` + + + + + +```text wrap +Total = 100,000 + 900,000 + 499,000,000 = 500,000,000 tinycents ≈ $0.05 USD +``` + +This amount is converted to HBAR at the current exchange rate and charged to the payer. + + + + + +If the same transaction used **two** keys instead of one, the service fee would increase by the per-key extra fee (e.g., 10,000,000 tinycents), because the included count of 1 key is exceeded by 1. + +## Transaction Outcomes and Fees + +Not all transactions succeed. The fee charged depends on how far the transaction progresses: + +| Outcome | Description | Who Pays | Components Charged | +| -------------- | ---------------------------------------------------------------------------------------------------------------- | --------------- | ------------------------------- | +| **Successful** | Transaction executed normally | Payer | Node + Network + Service | +| **Bad** | Passed due-diligence but failed during execution (e.g., out of gas, semantically wrong, inconsistent with state) | Payer | Node + Network + Service (full) | +| **Unhandled** | Well-formed but not executed (e.g., throttled, duplicate, unexecuted portion of an atomic batch) | Payer | Node + Network | +| **Invalid** | Failed due-diligence checks by the submitting node (e.g., payer can't afford the fee, incompatible fields) | Submitting node | Network only | +| **Unreadable** | Bytes cannot be parsed as a valid protobuf `Transaction` | Submitting node | Punitive flat fee | + + + Bad transactions are charged full freight (node + network + service) to protect the network from denial-of-service attacks. This applies even if the transaction fails due to a bug (`FAIL_INVALID`). + + +## Congestion Pricing + +[HIP-1313](https://hips.hedera.com/hip/hip-1313#hip-1313) introduces an optional high-volume lane for entity-creation transactions above the standard throttle. When a transaction opts in with `setHighVolume(true)`, the network may apply a fee multiplier if the high-volume throttle bucket is under load. The multiplier scales with congestion level and is reflected in the `high_volume_multiplier` field of the fee estimate response. + +The `high_volume_multiplier` field uses a 1-based scale `(1 = 1×, 4 = 4×)`. `TransactionRecord.highVolumePricingMultiplier` — available after execution — uses a `1000-based scale (1000 = 1×, 4000 = 4×)`. Both represent the same multiplier. + +To simulate the fee at a specific congestion level before committing, use `setHighVolumeThrottle()` on `FeeEstimateQuery`. See [Estimating Fees](/hedera/sdks-and-apis/sdks/fees/fee-estimation) with the SDK for code examples. + +## Fee Schedule Configuration + +The fee schedule is a JSON document stored in system file **`0.0.113`**. It defines: + +| Section | Purpose | +| ------------ | --------------------------------------------------------------- | +| `extras` | All available extra fee definitions (name + per-unit fee) | +| `node` | Node fee configuration (base fee + extras with included counts) | +| `network` | Network fee configuration (multiplier) | +| `services` | Per-service groupings of transaction and query fee definitions | +| `unreadable` | Punitive fee for unparsable transaction bytes | + + + +```json +{ + "version": 0, + "extras": [ + { "name": "Signatures", "fee": 100000 }, + { "name": "ProcessingBytes", "fee": 10000 }, + { "name": "Keys", "fee": 10000000 } + ], + "node": { + "baseFee": 100000, + "extras": [ + { "name": "ProcessingBytes", "includedCount": 1024 }, + { "name": "Signatures", "includedCount": 1 } + ] + }, + "network": { "multiplier": 9 }, + "services": [ + { + "name": "CryptoService", + "transactions": [ + { + "name": "CryptoCreate", + "baseFee": 499000000, + "extras": [ + { "name": "Keys", "includedCount": 1 } + ] + } + ], + "queries": [] + } + ], + "unreadable": { "fee": 100000000000 } +} +``` + + + + +The legacy fee schedule in system file `0.0.111` remains available in its existing format for backward compatibility, but it will not receive further updates. + + +## Fee Estimation + +You can estimate transaction fees before submitting them using the Mirror Node REST API: + +```bash +POST /api/v1/network/fees?mode=intrinsic +Content-Type: application/protobuf + + +``` + +The endpoint supports two modes: + +| Mode | Behavior | +| --------------------- | ------------------------------------------------------------------------------------- | +| `intrinsic` (default) | Estimates based on the transaction's inherent properties (size, signatures, keys) | +| `state` | Estimates using the mirror node's latest known state (e.g., checks if accounts exist) | + +See [Mirror Node REST API Network](/hedera/sdks-and-apis/rest-api/network) for the full endpoint specification and response format. + +## Queries + +Queries follow the same base-fee-plus-extras structure as transactions. Some queries are marked as `free` in the fee schedule (e.g., `CryptoGetAccountBalance`, `TransactionGetReceipt`). For non-free queries, the SDK creates a `CryptoTransfer` payment transaction to pay the node, network, and service fees. + +## Fee Schedule Schema (Protobuf) + +The fee schedule is defined as a set of protobuf messages. The wire format is JSON, stored in system file `0.0.113`. + +### FeeSchedule + +Top-level message defining the complete fee configuration. + +| Field | Type | Description | +| ------------ | -------------------------------- | -------------------------------------------------------- | +| `node` | NodeFeeSchedule | How to compute the node fee component. **Required.** | +| `network` | NetworkFeeSchedule | How to compute the network fee component. **Required.** | +| `unreadable` | UnreadableTransactionFeeSchedule | Fee for unparsable transaction bytes. Optional. | +| `extras` | repeated ExtraFeeDefinition | All available extra fee definitions. No duplicate names. | +| `services` | repeated ServiceFeeSchedule | Fee configs per network service. No duplicate names. | + +### ExtraFeeDefinition + +Defines a single extra fee — an additional charge for a specific cost factor. + +| Field | Type | Description | +| ------ | ------ | --------------------------------------------------------------- | +| `name` | string | Unique name. Must match `[A-Za-z].*[A-Za-z0-9]*`. **Required.** | +| `fee` | uint64 | Fee per unit in tinycents. Must be > 0. **Required.** | + +### NodeFeeSchedule + +Node fee configuration. Applied identically to **all** transaction types. + +| Field | Type | Description | +| ---------- | -------------------------- | ----------------------------------------------------------- | +| `base_fee` | uint64 | Base fee in tinycents. Defaults to 0. | +| `extras` | repeated ExtraFeeReference | Extras for computing the node fee. No duplicate references. | + +### NetworkFeeSchedule + +Network fee configuration. Calculated as a multiplier of the node fee. + +| Field | Type | Description | +| ------------ | ------ | ------------------------------------------------------ | +| `multiplier` | uint32 | Multiplied by the node fee. Must be ≥ 1. **Required.** | + +### ServiceFeeSchedule + +Groups transaction and query fee configs for a single gRPC service. + +| Field | Type | Description | +| ---------- | ----------------------------- | --------------------------------------------------- | +| `name` | string | Service name (e.g., `CryptoService`). **Required.** | +| `schedule` | repeated ServiceFeeDefinition | Transaction/query fee configs. Must not be empty. | + +### ServiceFeeDefinition + +Fee definition for a single transaction or query. + +| Field | Type | Description | +| ---------- | -------------------------- | ----------------------------------------------------------------------- | +| `name` | string | Transaction/query name (e.g., `CryptoCreate`). **Required.** | +| `base_fee` | uint64 | Base fee in tinycents. Defaults to 0. | +| `extras` | repeated ExtraFeeReference | Extras for this transaction/query. No duplicate references. | +| `free` | bool | If `true`, `base_fee` and `extras` are ignored — the operation is free. | + +### ExtraFeeReference + +References an ExtraFeeDefinition with an optional included count. + +| Field | Type | Description | +| ---------------- | ------ | ----------------------------------------------------------------------- | +| `name` | string | Name of the referenced extra. Must match a defined extra. **Required.** | +| `included_count` | uint32 | Units included for free in the base fee. Defaults to 0. | + +### UnreadableTransactionFeeSchedule + +Punitive fee for nodes that submit unparsable bytes. + +| Field | Type | Description | +| ----- | ------ | ----------------------------------------------- | +| `fee` | uint64 | Punitive fee in tinycents. Optional (may be 0). | + +### Validation Rules + +Before a new fee schedule takes effect, the network validates it. If any rule fails, the schedule is rejected. + + + + +The JSON must parse and conform to the `FeeSchedule` protobuf message. All required fields must be present and types must match. No unrecognized fields. + + + +All `baseFee` and `fee` fields must be non-negative integers. For extras, `fee` must be strictly > 0. + + + +The `multiplier` in `network` must be a positive integer ≥ 1. + + + +All names must match `[A-Za-z].*[A-Za-z0-9]*`. Extra names, service names, and transaction/query names within each service must be unique. + + + +Every extra reference must point to a defined extra. No duplicate references within a single list. + + + +If `free` is `true`, `baseFee` and `extras` are ignored during calculation but must still comply with all validation rules if present. + + + + +## Related + + + + + The full Hiero Improvement Proposal specification. + + + + Fee tables for all transaction and query types on mainnet. + + + + Gas schedule and fee calculation for smart contracts. + + + + The fee collection account model that Simple Fees depends on. + + + \ No newline at end of file diff --git a/hedera/core-concepts/smart-contracts/gas-and-fees.mdx b/hedera/core-concepts/smart-contracts/gas-and-fees.mdx index cbff6b13..d1ee7513 100644 --- a/hedera/core-concepts/smart-contracts/gas-and-fees.mdx +++ b/hedera/core-concepts/smart-contracts/gas-and-fees.mdx @@ -23,7 +23,9 @@ As noted in [HIP-410](https://hips.hedera.com/hip/hip-410), this maximizes compa ## Gas Schedule and Fee Calculation -Gas charges apply to `ContractCall`, `ContractCreate`, and `EthereumTransaction`. Other smart contract-related transactions (e.g., `ContractDelete`, `ContractGetInfo`) use standard Hedera network, node, and service fees in HBAR. +Gas charges apply to `ContractCall`, `ContractCreate`, and `EthereumTransaction`. Other smart contract-related transactions (e.g., `ContractDelete`, `ContractGetInfo`) use the standard [Fee Model](/hedera/core-concepts/fee-model), a base fee plus extras for node, network, and service components, paid in HBAR. + +For gas-consuming transactions (`ContractCall`, `ContractCreate`, `EthereumTransaction`), gas is an "extra" in the service fee component. The gas extra covers EVM execution costs. All other fee components (node fee, network fee, and the non-gas portion of the service fee) follow the base-fee-plus-extras model. Gas fees for EVM transactions consist of: diff --git a/hedera/core-concepts/tokens/hedera-token-service-hts-native-tokenization/custom-fee-schedule.mdx b/hedera/core-concepts/tokens/hedera-token-service-hts-native-tokenization/custom-fee-schedule.mdx index a8d32f0c..ebcdc3db 100644 --- a/hedera/core-concepts/tokens/hedera-token-service-hts-native-tokenization/custom-fee-schedule.mdx +++ b/hedera/core-concepts/tokens/hedera-token-service-hts-native-tokenization/custom-fee-schedule.mdx @@ -78,11 +78,11 @@ Royalty fees function as a convenience feature, but the network cannot enforce r Understanding the difference between custom fees and standard transaction fees in HBAR is crucial for token issuers and developers working with Hedera. * **Custom fees** are designed to enforce complex fee structures, such as royalties and fractional ownership. These fees can be fixed, fractional, or royalty-based and are usually paid in the token being transferred, although other Hedera tokens or HBAR can also be used. You can configure up to 10 custom fees to be automatically disbursed to designated fee collector accounts. -* On the other hand, **transaction fees** in HBAR serve a different purpose: they compensate network nodes for processing transactions. These fees are uniform across all transaction types and are paid exclusively in HBAR. Unlike custom fees, which can be configured by the user, transaction fees are fixed by the network. +* **Transaction fees** in HBAR serve a different purpose: they compensate the network for processing transactions. These fees follow a [base fee + extras model](/hedera/core-concepts/fee-model) defined in the network's fee schedule (system file `0.0.113`). While the fee structure varies by transaction type (each has its own base fee and applicable extras), the fee schedule is set by the network's governing authority, not by individual users. Transaction fees are paid exclusively in HBAR. ### **Key Differences** -The table below summarizes the key differences between custom fees and transaction fees. +The key differences are that custom fees offer flexibility and can be paid in various tokens to any account, while transaction fees follow a network-defined schedule and go to the network and node operators, paid only in HBAR. The table below summarizes the key differences between custom fees and transaction fees.
FeatureCustom FeesTransaction Fees
PurposeEnforce token-specific fee structures (e.g., royalties, taxes)Compensate network nodes for transaction processing
Who Collects?Designated fee collector(s)Hedera network nodes
CurrencyHBAR or HTS fungible tokensHBAR only
ConfigurabilityFully configurable by token issuerFixed by the network
diff --git a/hedera/core-concepts/transactions-and-queries.mdx b/hedera/core-concepts/transactions-and-queries.mdx index 182cee1c..d67d5b0f 100644 --- a/hedera/core-concepts/transactions-and-queries.mdx +++ b/hedera/core-concepts/transactions-and-queries.mdx @@ -229,6 +229,10 @@ The transaction fee for the child transaction is included in the record of the p **Queries** are processed only by the single node to which they are sent. Clients send queries to retrieve some aspect of the current consensus state, like an account balance. Certain queries are free, but generally, they are subject to fees. The full list of queries can be found [here](/hedera/sdks-and-apis/sdks/queries). + +Under the [Fee Model](/hedera/core-concepts/fee-model), queries can have node, network, and service fee components. However, many common queries (e.g., `TransactionGetReceipt`, `CryptoGetAccountBalance`) are marked as **free** in the fee schedule. For non-free queries, the SDK creates a payment transaction to cover the fees. + + A query includes a header that includes a normal HBAR transfer transaction that will serve as how the client pays the node the appropriate fee. There is no way to give partial payment to a node for processing the query, meaning if a user overpaid for the query, the user will not receive a refund. The node processing the query will submit that payment transaction to the network for processing into a consensus statement to receive its fee. A client can determine the appropriate fee for a query by asking a node for the cost, not the actual data. Such a `COST_ANSWER` query is free to the client. diff --git a/hedera/faqs/network-governance.mdx b/hedera/faqs/network-governance.mdx index b6b7c312..4e702c88 100644 --- a/hedera/faqs/network-governance.mdx +++ b/hedera/faqs/network-governance.mdx @@ -174,9 +174,9 @@ title: "Network Governance" - Nodes calculate the fee for a transaction in USD but convert that value to HBAR using the current exchange rate before deducting that amount from the account paying for the transaction. Consequently, the fee in HBAR for the same transaction may vary from hour to hour, even as the fee in USD stays stable. If the client stipulates a max transaction fee for their transactions, a transaction may fail with an INSUFFICIENT_TX_FEE error if that stipulated max value is less than the value calculated by the nodes using the current exchange rate. Clients can protect themselves against this HBAR fee volatility by stipulating a sufficiently high max transaction fee (as they will only be charged the actual fee, not the max they stipulate) for transactions. + Fees are defined in USD as `tinycents` (`10⁸ tinycents` = 1 cent USD) in the fee schedule. Nodes convert the calculated USD fee to HBAR using the current exchange rate before charging the payer's account. This means the HBAR cost of the same transaction may vary from hour to hour as the exchange rate changes, even though the USD fee stays stable. - This applies to the payment transactions for queries as well. + If you set a `maxTransactionFee`, a transaction will fail with `INSUFFICIENT_TX_FEE` if the max is lower than the current calculated fee. To protect against volatility, set a sufficiently high max, you will only be charged the actual fee, not the maximum. @@ -272,7 +272,7 @@ title: "Network Governance" - Hedera council reviews pricing at every council meeting (once every three months), and approves all changes to the prices. The exchange rate that nodes use to determine the corresponding fees in hbars is updated frequently (currently every hour) . + The Hedera Council reviews pricing at every council meeting (approximately every three months) and approves all changes to the fee schedule. Fee updates are published to system file `0.0.113` on the network. The USD-to-HBAR exchange rate is updated frequently (currently every hour). @@ -290,7 +290,7 @@ title: "Network Governance" - Hedera transaction and query fees are denominated in USD and paid in HBAR. The network regularly updates the USD-to-HBAR exchange rate based on current market rates, subject to a defined minimum exchange rate. + Hedera transaction and query fees are denominated in **USD** and paid in **HBAR**. Specifically, fees are defined in `tinycents` (`10⁸ tinycents` = 1 cent USD) in the fee schedule stored in system file `0.0.113`. The network regularly updates the USD-to-HBAR exchange rate based on current market rates, subject to a defined minimum exchange rate. This model is designed to keep fees predictable in USD terms, even though the amount paid in HBAR may vary over time. By using a minimum exchange rate, the network limits how much the HBAR-denominated fee can increase during periods of significant price volatility. diff --git a/hedera/networks/mainnet.mdx b/hedera/networks/mainnet.mdx index 9f30a3d9..edfe8488 100644 --- a/hedera/networks/mainnet.mdx +++ b/hedera/networks/mainnet.mdx @@ -7,7 +7,7 @@ sidebarTitle: Overview The Hedera mainnet (short for main network) is where applications are run in production, with transaction fees paid in [HBAR](https://www.hedera.com/hbar). Any application or retail user can submit transactions to the Hedera mainnet; they're automatically consensus-timestamped and fairly ordered. -Any Hedera account can query data associated with Hedera's services and stored on-chain. Every transaction requires payment as a **transaction fee** denominated in **tinybars** (100,000,000 tℏ = 1 ℏ). You can learn more about transaction fees and estimate your application costs [here](https://www.hedera.com/fees). +Any Hedera account can query data associated with Hedera's services and stored on-chain. Every transaction requires payment of a fee. Fees follow a [base fee + extras model](/hedera/core-concepts/fee-model) defined in the network's fee schedule (system file `0.0.113`). Fees are denominated in USD (as tinycents) and paid in HBAR at the current exchange rate (100,000,000 tℏ = 1 ℏ). You can learn more about transaction fees [here](/hedera/core-concepts/fee-model) and estimate your application costs using the [fee tables](/hedera/networks/mainnet/fees) or the `POST /api/v1/network/fees` [Mirror Node endpoint](/hedera/sdks-and-apis/rest-api/network). If you're looking to test your application (or just experiment), please visit [Testnet Access](/hedera/networks/testnet/testnet-access). The Hedera testnet enables developers to prototype and test applications in a simulated mainnet environment that uses test *HBAR* for paying transaction fees. @@ -18,6 +18,16 @@ Transactions on the Hedera Mainnet are currently throttled. You will receive a ` ## Main Network Throttles +| Network Request Types | Throttle (TPS) | +| --- | --- | +| **Cryptocurrency Transactions** | `AccountCreateTransaction`: 2 tps
`TransferTransaction` (inc. tokens): 10,000 tps
`Other`: 10,000 tps | +| **Consensus Transactions** | `TopicCreateTransaction`: 5 tps
`Other`: 10,000 tps | +| **Token Transactions** | `TokenMintTransaction`: 125 tps (fungible mint), 50 tps (NFT mint)
`TokenAssociateTransaction`: 100 tps
`TransferTransaction` (inc. tokens): 10,000 tps
`Other`: 3,000 tps | +| **Schedule Transactions** | `ScheduleSignTransaction`: 100 tps
`ScheduleCreateTransaction`: 100 tps | +| **File Transactions** | 10 tps | +| **Smart Contract Transactions** | `ContractExecuteTransaction`: 15 million gas per second
`ContractCreateTransaction`: 15 million gas per second | +| **Queries (per node)** | `AccountBalanceQuery`: 1000 tps
`ContractGetInfo`: 700 tps
`ContractGetBytecode`: 700 tps
`ContractCallLocal`: 700 tps
`FileGetInfo`: 700 tps
`FileGetContents`: 700 tps
`Other`: 10,000 tps | +| **Receipts** | unlimited (no throttle) |
Network Request TypesThrottle (tps)
Cryptocurrency Transactions

AccountCreateTransaction: 2 tps

TransferTransaction (inc. tokens): 10,000 tps
Other: 10,000 tps

Consensus Transactions

TopicCreateTransaction: 5 tps

Other: 10,000 tps

Token Transactions

TokenMintTransaction:

  • 125 TPS for fungible mint
  • 50 TPS for NFT mint

TokenAssociateTransaction: 100 tps
TransferTransaction (inc. tokens): 10,000 tps

Other: 3,000 tps

Schedule TransactionsScheduleSignTransaction: 100 tps
ScheduleCreateTransaction: 100 tps
File Transactions10 tps
Smart Contract TransactionsContractExecuteTransaction: 15 million gas per second
ContractCreateTransaction: 15 million gas per second
Queries (per node)

AccountBalanceQuery: 1000 tps

ContractGetInfo: 700 tps
ContractGetBytecode: 700 tps
ContractCallLocal: 700 tps

FileGetInfo: 700 tps
FileGetContents: 700 tps

Other: 10,000 tps

Receiptsunlimited (no throttle)
### High-Volume Throttles @@ -41,4 +51,4 @@ response — the same behavior as the standard throttle system. High-volume transactions use **variable-rate pricing** that scales with utilization. See the [High-Volume Entity Creation](/hedera/core-concepts/high-volume-entity-creation) guide to understand how this affects your transaction fees before opting in. - \ No newline at end of file + diff --git a/hedera/networks/mainnet/fees.mdx b/hedera/networks/mainnet/fees.mdx index 1787ff73..1f240da4 100644 --- a/hedera/networks/mainnet/fees.mdx +++ b/hedera/networks/mainnet/fees.mdx @@ -6,7 +6,9 @@ sidebarTitle: Overview The Hedera testnet fees tables found below offer a low-end estimate of transaction and query fees for all network services. The tables below contain USD, HBAR, and Tinybar (tℏ) values per each API call. All operation fees on the Hedera testnet are paid in test HBAR, which is freely available and only useful for development purposes. -Fee estimates are based on assumptions about the details of a specific API call. For instance, the fee for an HBAR cryptocurrency transfer (CryptoTransfer) assumes a single signature on the transaction and the fee for storing a file assumes a 1,0000-byte sized file stored for 90 days. Transactions exceeding these base assumptions will be more expensive; we recommend increasing your maximum allowable fee to accommodate additional complexity. +Fee estimates are based on assumptions about the details of a specific API call. For instance, the fee for an HBAR cryptocurrency transfer (`CryptoTransfer`) assumes a single signature on the transaction and the fee for storing a file assumes a 1,000-byte sized file stored for 90 days. Transactions exceeding these base assumptions will be more expensive; we recommend increasing your maximum allowable fee to accommodate additional complexity. + +Hedera transaction and query fees follow a **base fee + extras** model defined by [**HIP-1261 (Simple Fees)**](https://hips.hedera.com/hip/hip-1261). The base fees in the tables below are the starting cost — extras add to that cost based on what the transaction does. See [**Fee Model**](/hedera/core-concepts/fee-model) for the full explanation, the complete extras list, and worked examples. ## Mainnet Fees @@ -56,9 +58,6 @@ All fees are subject to change. The fees below reflect a base price for the tran | CryptoAccountAutoRenew | $0.00022 | | CryptoDeleteAllowance | $0.05 | | CryptoApproveAllowance | $0.05 | -| CryptoAddLiveHash | $0.10 | -| CryptoDeleteLiveHash | $0.005 | -| CryptoGetLiveHash | $0.0001 | | CryptoUpdate | $0.00022 | | CryptoTransfer | $0.0001 | | CryptoTransfer (custom fees) | $0.002 | @@ -66,7 +65,6 @@ All fees are subject to change. The fees below reflect a base price for the tran | CryptoGetAccountRecords | $0.0001 | | CryptoGetAccountBalance | $0.00 | | CryptoGetInfo | $0.0001 | -| CryptoGetStakers | $0.0001 | ### Consensus Service @@ -102,7 +100,6 @@ All fees are subject to change. The fees below reflect a base price for the tran | TokenGrantKyc | $0.001 | | TokenMint (fungible) | $0.001 | | TokenMint (non-fungible) | $0.02 | -| TokenMint (bulk mint 10k NFTs) | $200.00 | | TokenPause | $0.001 | | TokenReject | $0.001 | | TokenRevokeKyc | $0.001 | @@ -145,7 +142,6 @@ All fees are subject to change. The fees below reflect a base price for the tran | ContractCallLocal | $0.001 | | ContractGetByteCode | $0.05 | | ContractGetInfo | $0.0001 | -| ContractGetRecords | $0.0001 | | ContractAutoRenew | $0.026 | | EthereumTransaction (successful transactions) | $0.00 | | EthereumTransaction (failed transactions) | $0.0001 | @@ -170,3 +166,40 @@ All fees are subject to change. The fees below reflect a base price for the tran | SystemUndelete | $0.00 | | TransactionGetReceipt | $0.00 | | TransactionGetRecord | $0.0001 | + +### Extras + +Under the [**Simple Fees model (HIP-1261)**](https://hips.hedera.com/hip/hip-1261), every transaction is calculated as a **base fee plus extras**. The base fees in the tables above are the starting cost — extras add to that cost based on what the transaction does (number of signatures, keys, NFT serials, gas used, etc.). Each extra has an included count that covers typical usage; you only pay for units above that count. See [**Fee Model**](/hedera/core-concepts/fee-model) for the full explanation and worked examples. + + + This table reflects the extras currently defined in the live fee schedule (system file `0.0.113`). The published [HIP-1261](https://hips.hedera.com/hip/hip-1261) lists an earlier version of this set; consult the live schedule as the source of truth. + + +| Extra | USD ($) | +| ------------------------------------------- | ------------- | +| Signatures | $0.00001 | +| Keys | $0.01 | +| Accounts | $0.0001 | +| TokenTypes | $0.0001 | +| Gas | $0.0000000852 | +| Allowances | $0.05 | +| Airdrops | $0.05 | +| TokenTransferBase | $0.0009 | +| TokenTransferBaseCustomFees | $0.0019 | +| TokenCreateWithCustomFee | $1.00 | +| TokenMintNft | $0.02 | +| TokenMintNftBase | $0.019 | +| NftUpdate | $0.001 | +| TokenAssociate | $0.05 | +| ConsensusCreateTopicWithCustomFee | $1.99 | +| ConsensusSubmitMessageWithCustomFee | $0.04983 | +| ConsensusSubmitMessageWithCustomFeeBytes | $0.0001 | +| ConsensusSubmitMessageWithoutCustomFeeBytes | $0.00000068 | +| ScheduleCreateContractCallBase | $0.09 | +| Records | $0.0001 | +| StateBytes | $0.0001 | +| ProcessingBytes | $0.000001 | +| EvmDispatchSurcharge | +20% | + + +Prices come from the configured fee schedule stored in system file `0.0.113` and may change. Fees are charged in HBAR, converted from USD at the live exchange rate. \ No newline at end of file diff --git a/hedera/sdks-and-apis/rest-api/network.mdx b/hedera/sdks-and-apis/rest-api/network.mdx index 2081f8b7..3c50614c 100644 --- a/hedera/sdks-and-apis/rest-api/network.mdx +++ b/hedera/sdks-and-apis/rest-api/network.mdx @@ -1,15 +1,46 @@ --- title: "Network" sidebarTitle: "Overview" +description: "Mirror Node REST API endpoints for querying network supply, fees, exchange rates, nodes, and staking information." --- - ## Overview -The **Network Object** in the Hedera Mirror Node REST API allows developers to query **network-related information**, such as network supply, fees, exchange rates, and node details. These object are essential for monitoring network status, estimating transaction costs, and retrieving staking information. +The Network Object in the Hedera Mirror Node REST API allows developers to query network-related information, such as network supply, fees, exchange rates, and node details. These endpoints are essential for monitoring network status, estimating transaction costs, and retrieving staking information. ## Endpoints The following endpoints are available for the Network object: +| Endpoint | Description | +| --- | --- | +| `GET /api/v1/network/supply` | Retrieves the current total supply of HBAR. | +| `GET /api/v1/network/fees` | Fetches the latest transaction fee schedules. | +| `POST /api/v1/network/fees` | Estimates fees for a specific transaction before submission. [HIP-1261](https://hips.hedera.com/hip/hip-1261) | +| `GET /api/v1/network/exchangerate` | Retrieves exchange rates to estimate transaction costs. | +| `GET /api/v1/network/nodes` | Lists the network address book nodes. | +| `GET /api/v1/network/stake` | Fetches staking-related information. | + +### Estimate Transaction Fees (POST) + +`POST /api/v1/network/fees` + +Introduced in [HIP-1261 (Simple Fees)](https://hips.hedera.com/hip/hip-1261), this endpoint estimates the node, network, and service fees for a transaction before it is submitted to the network. It accepts a serialized `Transaction` protobuf in the request body (`application/protobuf` or `application/x-protobuf` Content-Type) and returns a detailed fee breakdown in tinycents. + +Two estimation modes are available via the `mode` query parameter: + +| Mode | Behavior | +| --- | --- | +| `intrinsic` (default) | Estimates based on the transaction's inherent properties (size, signatures, keys). | +| `state` | Also considers the mirror node's latest known state (e.g., account existence, token associations). | + + + For `state` mode, if the required network state is unavailable (e.g., due to data pruning), the endpoint falls back to `intrinsic` mode and includes a note in the response explaining the fallback. + + + + This endpoint currently returns stubbed (dummy) data as of mirror node `v0.145.1`. The full fee estimation implementation using the upstream fee estimation library will ship in a future release. You can integrate against the stub now to be ready when the production implementation goes live. + + +For full request/response details, parameters, and the interactive API playground, see the [API reference page](/api-reference/network/estimate-network-fees). For an overview of the Simple Fees model, see [Fee Model](/hedera/core-concepts/fee-model).
EndpointDescription
GET /api/v1/network/supplyRetrieves the current total supply of HBAR.
GET /api/v1/network/feesFetches the latest transaction fee schedules.
POST /api/v1/network/feesEstimates fees for a specific protobuf-encoded transaction, including the [HIP-1313](https://hips.hedera.com/hip/hip-1313) high_volume_multiplier.
GET /api/v1/network/exchangerateRetrieves exchange rates to estimate transaction costs.
GET /api/v1/network/nodesLists the network address book nodes.
GET /api/v1/network/stakeFetches staking-related information.
diff --git a/hedera/sdks-and-apis/sdks/fees/fee-estimation.mdx b/hedera/sdks-and-apis/sdks/fees/fee-estimation.mdx new file mode 100644 index 00000000..406e4376 --- /dev/null +++ b/hedera/sdks-and-apis/sdks/fees/fee-estimation.mdx @@ -0,0 +1,248 @@ +--- +title: "Estimating Fees with the SDK" +description: "Use FeeEstimateQuery to estimate transaction fees before submission, gate spending, and simulate high-volume pricing." +sidebarTitle: "Estimate a fee" +--- + +`FeeEstimateQuery` lets you estimate the cost of a transaction before submitting it. Use it to gate spending against a budget, surface fee previews to users, or simulate execution under high-volume congestion. + +The query returns a structured breakdown of node, network, and service fees in tinycents (USD × 10⁻¹⁰). The same calculation runs on the consensus node at execution time, so the estimate reflects what you'll be charged — modulo the live HBAR exchange rate at consensus. + +## Basic Usage + +Freeze the transaction first, then pass it to `FeeEstimateQuery`. Either call the query directly or use the `estimateFee()` convenience method on the transaction. + + + +```java Java +// Freeze the transaction first — the body must be finalized before estimating +var transaction = new AccountCreateTransaction() + .setKeyWithoutAlias(newKey) + .setInitialBalance(new Hbar(1)) + .freezeWith(client); + +// Option 1: FeeEstimateQuery +FeeEstimateResponse response = new FeeEstimateQuery() + .setTransaction(transaction) + .setMode(FeeEstimateMode.INTRINSIC) // optional — INTRINSIC is the default + .execute(client); + +// or option 2: Convenience method +// FeeEstimateResponse response = transaction.estimateFee().execute(client); +``` + +```javascript JavaScript +const transaction = await new AccountCreateTransaction() + .setKeyWithoutAlias(newKey) + .setInitialBalance(new Hbar(1)) + .freezeWith(client); + +const response = await new FeeEstimateQuery() + .setTransaction(transaction) + .setMode(FeeEstimateMode.INTRINSIC) + .execute(client); + +// or: const response = await transaction.estimateFee().execute(client); +``` + +```go Go +tx, _ := hiero.NewAccountCreateTransaction(). + SetKeyWithoutAlias(newKey.PublicKey()). + SetInitialBalance(hiero.NewHbar(1)). + FreezeWith(client) + +response, err := hiero.NewFeeEstimateQuery(). + SetTransaction(tx). + SetMode(hiero.FeeEstimateModeIntrinsic). + Execute(client) + +// or: response, err := tx.EstimateFee().Execute(client) +``` + + + +## Estimation Modes + +| Mode | Behavior | +|------|----------| +| `INTRINSIC` (default) | Estimates based on the transaction's inherent properties (size, signatures, keys). Fast and stateless. | +| `STATE` | Estimates using the mirror node's latest known state (e.g., checks if accounts exist, includes state-dependent extras). Required for high-volume pricing simulation. | + +## Response Structure + +The response contains a structured breakdown of the fee components. + +```json +{ + "high_volume_multiplier": 1, + "network": { "multiplier": 3, "subtotal": }, + "node": { + "base": , + "extras": [ + { + "name": "Signatures", + "included": 1, + "count": 2, + "charged": 1, + "fee_per_unit": , + "subtotal": + } + ] + }, + "service": { "base": , "extras": [] }, + "total": +} +``` + +The components total according to: + +```text +node.subtotal = node.base + sum(node.extras[].subtotal) +network.subtotal = node.subtotal × network.multiplier +total = node.subtotal + network.subtotal + service.subtotal +``` + +## End-to-End: Estimate, Gate, Execute + +A common pattern: estimate the fee, check against a budget, then execute only if the estimate is acceptable. + + + +```java Java +var transaction = new AccountCreateTransaction() + .setKeyWithoutAlias(newKey) + .setInitialBalance(new Hbar(1)) + .setMaxTransactionFee(new Hbar(10)) // set before freezing + .freezeWith(client); + +FeeEstimateResponse estimate = transaction.estimateFee().execute(client); + +// Gate on budget — $1.50 = 15,000,000,000 tinycents +if (estimate.getTotal() > 15_000_000_000L) { + throw new RuntimeException("Fee estimate exceeds budget: " + estimate.getTotal()); +} + +var record = transaction + .execute(client) + .getRecord(client); +``` + +```javascript JavaScript +const transaction = await new AccountCreateTransaction() + .setKeyWithoutAlias(newKey) + .setInitialBalance(new Hbar(1)) + .setMaxTransactionFee(new Hbar(10)) // set before freezing + .freezeWith(client); + +const estimate = await transaction.estimateFee().execute(client); + +if (estimate.total.toBigInt() > 15_000_000_000n) { + throw new Error(`Fee estimate exceeds budget: ${estimate.total}`); +} + +const record = await (await transaction.execute(client)).getRecord(client); +``` + +```go Go +tx, _ := hiero.NewAccountCreateTransaction(). + SetKeyWithoutAlias(newKey.PublicKey()). + SetInitialBalance(hiero.NewHbar(1)). + SetMaxTransactionFee(hiero.NewHbar(10)). // set before freezing + FreezeWith(client) + +estimate, _ := tx.EstimateFee().Execute(client) + +if estimate.Total > 15_000_000_000 { + panic(fmt.Sprintf("fee estimate exceeds budget: %d", estimate.Total)) +} + +resp, _ := tx.Execute(client) +record, _ := resp.GetRecord(client) +``` + + +## High-Volume Pricing Simulation + +For entity-creation transactions opted into the high-volume lane via `setHighVolume(true)`, the network may apply a fee multiplier under congestion. To simulate this before submitting, use `setHighVolumeThrottle()` on `FeeEstimateQuery` with `STATE` mode. + + + +```java Java +FeeEstimateResponse hvResponse = new FeeEstimateQuery() + .setTransaction( + new AccountCreateTransaction() + .setKeyWithoutAlias(newKey) + .setHighVolume(true) + .freezeWith(client) + ) + .setMode(FeeEstimateMode.STATE) + .setHighVolumeThrottle(5000) // simulate 50% utilization + .execute(client); + +// high_volume_multiplier uses 1-based scale: 1 = 1×, 4 = 4× +System.out.printf("Multiplier at 50%% load: %dx%n", hvResponse.getHighVolumeMultiplier()); +``` + +```javascript JavaScript +const hvResponse = await new FeeEstimateQuery() + .setTransaction( + new AccountCreateTransaction() + .setKeyWithoutAlias(newKey) + .setHighVolume(true) + .freezeWith(client) + ) + .setMode(FeeEstimateMode.STATE) + .setHighVolumeThrottle(5000) + .execute(client); + +console.log(`Multiplier at 50% load: ${hvResponse.highVolumeMultiplier}x`); +``` + +```go Go +tx, _ := hiero.NewAccountCreateTransaction(). + SetKeyWithoutAlias(newKey.PublicKey()). + SetHighVolume(true). + FreezeWith(client) + +hvResponse, _ := hiero.NewFeeEstimateQuery(). + SetTransaction(tx). + SetMode(hiero.FeeEstimateModeState). + SetHighVolumeThrottle(5000). + Execute(client) + +fmt.Printf("Multiplier at 50%% load: %dx\n", hvResponse.HighVolumeMultiplier) +``` + + +## Developer Notes + +- **Freeze before estimating.** Call `freezeWith(client)` before `FeeEstimateQuery` — the transaction body must be finalized for the estimate to reflect your actual transaction. +- **Estimates are in tinycents; execution fees are in tinybars.** The response uses tinycents (USD × 10⁻¹⁰). The fee charged on execution is in tinybars (HBAR × 10⁻⁸), converted at the live exchange rate at consensus time. +- **Set `maxTransactionFee` with headroom.** Add 10–20% above the estimate — exchange rates shift between estimation and execution. +- **`high_volume_multiplier` scale differs from `TransactionRecord`.** The estimate response uses a 1-based scale (1 = 1×, 4 = 4×). `TransactionRecord.highVolumePricingMultiplier` after execution uses a 1000-based scale (1000 = 1×, 4000 = 4×). Both represent the same multiplier. + +## SDK Versions + +`FeeEstimateQuery` is available in: + +- **Java**: v2.71.0+ +- **Go**: v2.79.0+ +- **JavaScript** (`@hiero-ledger/sdk`): v2.83.0+ + +## Related + + + + The base-fee-plus-extras model that fee estimation calculates against. + + + The underlying REST endpoint backing `FeeEstimateQuery`. + + + The HIP defining the fee model. + + + The HIP defining the high-volume lane and congestion multiplier. + + + \ No newline at end of file diff --git a/hedera/sdks-and-apis/sdks/transactions.mdx b/hedera/sdks-and-apis/sdks/transactions.mdx index c2e28e6c..9954d388 100644 --- a/hedera/sdks-and-apis/sdks/transactions.mdx +++ b/hedera/sdks-and-apis/sdks/transactions.mdx @@ -4,10 +4,10 @@ sidebarTitle: "Overview" --- -Transactions are requests submitted by a client to a node in the Hedera network. Every transaction has a fee that will be paid for processing the transaction. The following table lists the transaction type requests for each service. +Transactions are requests submitted by a client to a node in the Hedera network. Every transaction has a fee calculated using the [Fee Model](/hedera/core-concepts/fee-model): a base fee plus extras for each of the node, network, and service components. Fees are denominated in USD (as tinycents) and paid in HBAR at the current exchange rate. You can estimate fees before submission using the `POST /api/v1/network/fees` [Mirror Node endpoint](/hedera/sdks-and-apis/rest-api/network) or the [Hedera Fee Estimator](https://www.hedera.com/fees). The following table lists the transaction type requests for each service. -Transactions have a 6,144-byte size limit, which includes all attached signatures. A single signature is ~80–100 bytes, depending on the key type and encoding. Privileged Hedera accounts, such as 0.0.2 and 0.0.50, set as the transaction fee payer are permitted to submit transactions up to 130 KB in size. +Transactions have a 6,144-byte size limit, which includes all attached signatures. A single signature is ~80–100 bytes, depending on the key type and encoding. Privileged Hedera accounts, such as `0.0.2` and `0.0.50`, set as the transaction fee payer are permitted to submit transactions up to 130 KB in size. diff --git a/openapi.yaml b/openapi.yaml index b74311ca..ee538dba 100644 --- a/openapi.yaml +++ b/openapi.yaml @@ -941,6 +941,8 @@ paths: schema: format: binary type: string + description: A protobuf encoded HAPI Transaction + required: true responses: 200: description: OK @@ -3509,6 +3511,12 @@ components: allOf: - $ref: "#/components/schemas/FeeEstimate" - description: The node fee component which is to be paid to the node that submitted the transaction to the network. This fee exists to compensate the node for the work it performed to pre-check the transaction before submitting it, and incentivizes the node to accept new transactions from users. + notes: + description: An array of strings for any caveats. + example: ["Fallback to worst-case due to missing state"] + items: + type: string + type: array service: allOf: - $ref: "#/components/schemas/FeeEstimate"