You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Add Gas Model documentation for Polkadot Hub (new IA) (#1049)
* Add Gas Model documentation for Polkadot Hub
* fix: llms
* fix: update terminology in gas model documentation from PolkaVM to Pallet revive
* fix: clarify base transaction overhead description in gas model documentation
* fix: llms
* fix: update terminology for transaction length fees in gas model documentation
* fix: enhance gas model documentation by detailing weight as a two-dimensional tuple for fee calculation
* formatting
* fresh llms
---------
Co-authored-by: 0xlukem <[email protected]>
description: Learn how gas estimation, pricing, and weight mapping work in the Polkadot Hub.
28472
+
---
28473
+
28474
+
# Gas Model
28475
+
28476
+
## Overview
28477
+
28478
+
The Polkadot Hub implements a gas model that bridges Ethereum's familiar gas concept with Polkadot's more sophisticated resource metering system. This page explains how gas works in the Polkadot Hub and what developers need to know when building smart contracts.
28479
+
28480
+
## Understanding Resources in the Polkadot Hub
28481
+
28482
+
Unlike Ethereum, which uses a single gas value to measure everything, the Polkadot Hub tracks three separate resources:
28483
+
28484
+
- **`ref_time`**: Measures computational time. It is the closest equivalent to traditional gas and represents the amount of CPU time your contract execution consumes.
28485
+
- **`proof_size`**: Measures the amount of state data that validators need to verify. When your contract reads from storage or makes state queries, this metric tracks the size of the proofs needed to validate those operations.
28486
+
- **`storage_deposit`**: Is a native balance that gets temporarily locked when your contract creates new storage entries. This prevents state bloat by requiring contracts to pay for the storage they use. The deposit is returned when the storage is freed.
28487
+
28488
+
For Ethereum wallet compatibility, the Polkadot Hub's RPC layer automatically maps these three dimensions into a single gas value that wallets can understand and display to users.
28489
+
28490
+
## Gas vs Weight
28491
+
28492
+
When you interact with the Polkadot Hub through an Ethereum wallet, you see familiar gas values. Under the hood, the runtime works with `weight` - a two-dimensional metric that combines `ref_time` and `proof_size`.
28493
+
28494
+
The system continuously translates between these representations: converting `weight` to gas when estimating costs, and converting gas back to `weight` when executing transactions.
28495
+
28496
+
## How Gas Estimation Works
28497
+
28498
+
When your wallet requests a gas estimate (`eth_estimateGas`), the Polkadot Hub performs a dry-run of your transaction. This test execution discovers:
28499
+
28500
+
- How much computational time the contract will consume (`ref_time`).
28501
+
- How much state data needs to be verified (`proof_size`).
28502
+
- Whether any storage deposits are required (`storage_deposit`).
28503
+
28504
+
The system then calculates a gas estimate that covers all these costs, including:
28505
+
28506
+
- Base transaction overhead (intrinsic costs like signature verification, nonce/account checks, and dispatch setup).
28507
+
- Transaction length fees (charges for the transaction size in bytes).
28508
+
- The actual contract execution costs.
28509
+
- Any storage deposits.
28510
+
28511
+
The gas estimate also includes a small safety buffer to account for slight differences between the test run and actual execution.
28512
+
28513
+
## Dynamic Gas Pricing
28514
+
28515
+
Pallet revive uses dynamic pricing through a "fee multiplier" that adjusts based on network congestion:
28516
+
28517
+
- When blocks are full, the multiplier increases, making transactions more expensive.
28518
+
- When blocks are empty, the multiplier decreases, making transactions cheaper.
28519
+
- The multiplier updates after every block based on utilization.
28520
+
28521
+
This creates a market-based pricing mechanism similar to Ethereum's base fee, helping to manage network resources efficiently.
28522
+
28523
+
The gas price returned during estimation is simply the current fee multiplier value.
28524
+
28525
+
!!! warning "Important for Users"
28526
+
Because the fee multiplier can change between when you estimate gas and when your transaction executes, you can add a safety buffer (10-20%) to both your gas limit and gas price. This ensures your transaction will execute successfully even if network conditions change slightly.
28527
+
28528
+
## Transaction Execution Flow
28529
+
28530
+
The following diagram illustrates the complete lifecycle of a transaction from submission to settlement:
28531
+
28532
+
```mermaid
28533
+
graph TD
28534
+
U[User/Wallet] --> M[Transaction pool]
28535
+
M --> P[Pre-dispatch convert gas to weight and create hold]
28536
+
P --> C{Sufficient funds}
28537
+
C -->|No| R[Rejected]
28538
+
C -->|Yes| X[Execute contract within limits]
28539
+
X --> S[Settle fee from actual weight and length; refund]
28540
+
S --> B[Included in block]
28541
+
```
28542
+
28543
+
The transaction execution flow is as follows:
28544
+
28545
+
- **Pool and pre-dispatch**: The transaction enters the pool, `gas` is mapped to `weight`, and a temporary hold is created for the maximum fee exposure. Weight is a two-dimensional tuple (`ref_time`, `proof_size`). Each dimension is tracked independently. The [`WeightToFee`](https://docs.rs/pallet-transaction-payment/latest/pallet_transaction_payment/pallet/trait.Config.html#associatedtype.WeightToFee){target=\_blank} conversion takes the maximum of the two dimensions (after applying their respective coefficients) to determine the fee.
28546
+
- **Funds check**: If the hold is insufficient, the transaction is rejected before any execution.
28547
+
- **Execution**: If sufficient, the contract runs within the derived weight limits; a `storage_deposit` may be reserved when new storage is created.
28548
+
- **Settlement**: Fees are charged from the actual `weight` used plus the length fee; any unused hold is refunded.
28549
+
- **Inclusion**: After settlement, the transaction is included in the block.
28550
+
28551
+
## Conclusion
28552
+
28553
+
The Polkadot Hub's gas model is designed to be Ethereum-compatible while providing the flexibility and efficiency of Polkadot's resource metering system. Developers can build on Ethereum tooling while leveraging Polkadot's advanced features like multi-dimensional resource tracking.
Copy file name to clipboardExpand all lines: llms.txt
+1-1Lines changed: 1 addition & 1 deletion
Original file line number
Diff line number
Diff line change
@@ -207,7 +207,7 @@
207
207
- [Transactions and Fees on Asset Hub](https://raw.githubusercontent.com/polkadot-developers/polkadot-docs/refs/heads/master/smart-contracts/for-eth-devs/blocks-transactions-fees.md): Explore how Asset Hub smart contracts handle blocks, transactions, and fees with EVM compatibility, supporting various Ethereum transaction types.
208
208
- [Untitled](https://raw.githubusercontent.com/polkadot-developers/polkadot-docs/refs/heads/master/smart-contracts/for-eth-devs/contract-deployment.md): No description available.
209
209
- [PolkaVM Design](https://raw.githubusercontent.com/polkadot-developers/polkadot-docs/refs/heads/master/smart-contracts/for-eth-devs/dual-vm-stack.md): Discover PolkaVM, a high-performance smart contract VM for Polkadot, enabling Ethereum compatibility via pallet_revive, Solidity support & optimized execution.
210
-
- [Untitled](https://raw.githubusercontent.com/polkadot-developers/polkadot-docs/refs/heads/master/smart-contracts/for-eth-devs/gas-model.md): No description available.
210
+
- [Gas Model on the Polkadot Hub](https://raw.githubusercontent.com/polkadot-developers/polkadot-docs/refs/heads/master/smart-contracts/for-eth-devs/gas-model.md): Learn how gas estimation, pricing, and weight mapping work in the Polkadot Hub.
211
211
- [JSON-RPC APIs](https://raw.githubusercontent.com/polkadot-developers/polkadot-docs/refs/heads/master/smart-contracts/for-eth-devs/json-rpc-apis.md): JSON-RPC APIs guide for Polkadot Hub, covering supported methods, parameters, and examples for interacting with the chain.
212
212
- [Untitled](https://raw.githubusercontent.com/polkadot-developers/polkadot-docs/refs/heads/master/smart-contracts/for-eth-devs/migration.md): No description available.
213
213
- [Get Started with Smart Contracts](https://raw.githubusercontent.com/polkadot-developers/polkadot-docs/refs/heads/master/smart-contracts/get-started.md): Practical examples for building and deploying smart contracts on Polkadot Hub, from connecting and tooling to deployment, integrations, and precompiles.
description: Learn how gas estimation, pricing, and weight mapping work in the Polkadot Hub.
4
+
---
5
+
6
+
# Gas Model
7
+
8
+
## Overview
9
+
10
+
The Polkadot Hub implements a gas model that bridges Ethereum's familiar gas concept with Polkadot's more sophisticated resource metering system. This page explains how gas works in the Polkadot Hub and what developers need to know when building smart contracts.
11
+
12
+
## Understanding Resources in the Polkadot Hub
13
+
14
+
Unlike Ethereum, which uses a single gas value to measure everything, the Polkadot Hub tracks three separate resources:
15
+
16
+
-**`ref_time`**: Measures computational time. It is the closest equivalent to traditional gas and represents the amount of CPU time your contract execution consumes.
17
+
-**`proof_size`**: Measures the amount of state data that validators need to verify. When your contract reads from storage or makes state queries, this metric tracks the size of the proofs needed to validate those operations.
18
+
-**`storage_deposit`**: Is a native balance that gets temporarily locked when your contract creates new storage entries. This prevents state bloat by requiring contracts to pay for the storage they use. The deposit is returned when the storage is freed.
19
+
20
+
For Ethereum wallet compatibility, the Polkadot Hub's RPC layer automatically maps these three dimensions into a single gas value that wallets can understand and display to users.
21
+
22
+
## Gas vs Weight
23
+
24
+
When you interact with the Polkadot Hub through an Ethereum wallet, you see familiar gas values. Under the hood, the runtime works with `weight` - a two-dimensional metric that combines `ref_time` and `proof_size`.
25
+
26
+
The system continuously translates between these representations: converting `weight` to gas when estimating costs, and converting gas back to `weight` when executing transactions.
27
+
28
+
## How Gas Estimation Works
29
+
30
+
When your wallet requests a gas estimate (`eth_estimateGas`), the Polkadot Hub performs a dry-run of your transaction. This test execution discovers:
31
+
32
+
- How much computational time the contract will consume (`ref_time`).
33
+
- How much state data needs to be verified (`proof_size`).
34
+
- Whether any storage deposits are required (`storage_deposit`).
35
+
36
+
The system then calculates a gas estimate that covers all these costs, including:
37
+
38
+
- Base transaction overhead (intrinsic costs like signature verification, nonce/account checks, and dispatch setup).
39
+
- Transaction length fees (charges for the transaction size in bytes).
40
+
- The actual contract execution costs.
41
+
- Any storage deposits.
42
+
43
+
The gas estimate also includes a small safety buffer to account for slight differences between the test run and actual execution.
44
+
45
+
## Dynamic Gas Pricing
46
+
47
+
Pallet revive uses dynamic pricing through a "fee multiplier" that adjusts based on network congestion:
48
+
49
+
- When blocks are full, the multiplier increases, making transactions more expensive.
50
+
- When blocks are empty, the multiplier decreases, making transactions cheaper.
51
+
- The multiplier updates after every block based on utilization.
52
+
53
+
This creates a market-based pricing mechanism similar to Ethereum's base fee, helping to manage network resources efficiently.
54
+
55
+
The gas price returned during estimation is simply the current fee multiplier value.
56
+
57
+
!!! warning "Important for Users"
58
+
Because the fee multiplier can change between when you estimate gas and when your transaction executes, you can add a safety buffer (10-20%) to both your gas limit and gas price. This ensures your transaction will execute successfully even if network conditions change slightly.
59
+
60
+
## Transaction Execution Flow
61
+
62
+
The following diagram illustrates the complete lifecycle of a transaction from submission to settlement:
63
+
64
+
```mermaid
65
+
graph TD
66
+
U[User/Wallet] --> M[Transaction pool]
67
+
M --> P[Pre-dispatch convert gas to weight and create hold]
68
+
P --> C{Sufficient funds}
69
+
C -->|No| R[Rejected]
70
+
C -->|Yes| X[Execute contract within limits]
71
+
X --> S[Settle fee from actual weight and length; refund]
72
+
S --> B[Included in block]
73
+
```
74
+
75
+
The transaction execution flow is as follows:
76
+
77
+
-**Pool and pre-dispatch**: The transaction enters the pool, `gas` is mapped to `weight`, and a temporary hold is created for the maximum fee exposure. Weight is a two-dimensional tuple (`ref_time`, `proof_size`). Each dimension is tracked independently. The [`WeightToFee`](https://docs.rs/pallet-transaction-payment/latest/pallet_transaction_payment/pallet/trait.Config.html#associatedtype.WeightToFee){target=\_blank} conversion takes the maximum of the two dimensions (after applying their respective coefficients) to determine the fee.
78
+
-**Funds check**: If the hold is insufficient, the transaction is rejected before any execution.
79
+
-**Execution**: If sufficient, the contract runs within the derived weight limits; a `storage_deposit` may be reserved when new storage is created.
80
+
-**Settlement**: Fees are charged from the actual `weight` used plus the length fee; any unused hold is refunded.
81
+
-**Inclusion**: After settlement, the transaction is included in the block.
82
+
83
+
## Conclusion
84
+
85
+
The Polkadot Hub's gas model is designed to be Ethereum-compatible while providing the flexibility and efficiency of Polkadot's resource metering system. Developers can build on Ethereum tooling while leveraging Polkadot's advanced features like multi-dimensional resource tracking.
0 commit comments