Skip to content

Commit 3437fd5

Browse files
docs(gas/fees): Update block gas documentation (backport #20128) (#20131)
Co-authored-by: samricotta <37125168+samricotta@users.noreply.github.com>
1 parent a42a85a commit 3437fd5

File tree

1 file changed

+12
-8
lines changed

1 file changed

+12
-8
lines changed

docs/docs/learn/beginner/04-gas-fees.md

Lines changed: 12 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -56,21 +56,25 @@ Gas consumption can be done manually, generally by the module developer in the [
5656

5757
### Block Gas Meter
5858

59-
`ctx.BlockGasMeter()` is the gas meter used to track gas consumption per block and make sure it does not go above a certain limit. A new instance of the `BlockGasMeter` is created each time [`FinalizeBlock`](../advanced/00-baseapp.md#finalizeblock) is called. The `BlockGasMeter` is finite, and the limit of gas per block is defined in the application's consensus parameters. By default, Cosmos SDK applications use the default consensus parameters provided by CometBFT:
59+
`ctx.BlockGasMeter()` is the gas meter used to track gas consumption per block and make sure it does not go above a certain limit.
6060

61-
```go reference
62-
https://github.com/cometbft/cometbft/blob/v0.37.0/types/params.go#L66-L105
61+
During the genesis phase, gas consumption is unlimited to accommodate initialisation transactions.
62+
63+
```go
64+
app.finalizeBlockState.SetContext(app.finalizeBlockState.Context().WithBlockGasMeter(storetypes.NewInfiniteGasMeter()))
6365
```
6466

65-
When a new [transaction](../advanced/01-transactions.md) is being processed via `FinalizeBlock`, the current value of `BlockGasMeter` is checked to see if it is above the limit. If it is, the transaction fails and returned to the consensus engine as a failed transaction. This can happen even with the first transaction in a block, as `FinalizeBlock` itself can consume gas. If not, the transaction is processed normally. At the end of `FinalizeBlock`, the gas tracked by `ctx.BlockGasMeter()` is increased by the amount consumed to process the transaction:
67+
Following the genesis block, the block gas meter is set to a finite value by the SDK. This transition is facilitated by the consensus engine (e.g., CometBFT) calling the `RequestFinalizeBlock` function, which in turn triggers the SDK's `FinalizeBlock` method. Within `FinalizeBlock`, `internalFinalizeBlock` is executed, performing necessary state updates and function executions. The block gas meter, initialised each with a finite limit, is then incorporated into the context for transaction execution, ensuring gas consumption does not exceed the block's gas limit and is reset at the end of each block.
68+
69+
Modules within the Cosmos SDK can consume block gas at any point during their execution by utilising the `ctx`. This gas consumption primarily occurs during state read/write operations and transaction processing. The block gas meter, accessible via `ctx.BlockGasMeter()`, monitors the total gas usage within a block, enforcing the gas limit to prevent excessive computation. This ensures that gas limits are adhered to on a per-block basis, starting from the first block post-genesis.
6670

6771
```go
68-
ctx.BlockGasMeter().ConsumeGas(
69-
ctx.GasMeter().GasConsumedToLimit(),
70-
"block gas meter",
71-
)
72+
gasMeter := app.getBlockGasMeter(app.finalizeBlockState.Context())
73+
app.finalizeBlockState.SetContext(app.finalizeBlockState.Context().WithBlockGasMeter(gasMeter))
7274
```
7375

76+
This above shows the general mechanism for setting the block gas meter with a finite limit based on the block's consensus parameters.
77+
7478
## AnteHandler
7579

7680
The `AnteHandler` is run for every transaction during `CheckTx` and `FinalizeBlock`, before a Protobuf `Msg` service method for each `sdk.Msg` in the transaction.

0 commit comments

Comments
 (0)