Skip to content

Commit

Permalink
doc: improve documentation of BlockParams.MaxBytes (cometbft#1405)
Browse files Browse the repository at this point in the history
* spec: comment on BlockParams.MaxBytes and timeouts

* spec/abci: link to consensus timeouts doc fixed

* spec/abci: comment on timeout parameters moved down

* spec: advice to wind down default BlockParams.MaxBytes

* spec: more on winding down default BlockParams.MaxBytes

* spec: fixes on winding down default BlockParams.MaxBytes

* spec: nit pic on winding down default BlockParams.MaxBytes

* Applying @sergio-mena suggestion

Co-authored-by: Sergio Mena <sergio@informal.systems>

* Applying @sergio-mena suggestion

Co-authored-by: Sergio Mena <sergio@informal.systems>

* Update spec/abci/abci++_app_requirements.md

Co-authored-by: glnro <8335464+glnro@users.noreply.github.com>

---------

Co-authored-by: Sergio Mena <sergio@informal.systems>
Co-authored-by: glnro <8335464+glnro@users.noreply.github.com>
  • Loading branch information
3 people authored Sep 28, 2023
1 parent 0459474 commit 80648c4
Showing 1 changed file with 14 additions and 0 deletions.
14 changes: 14 additions & 0 deletions spec/abci/abci++_app_requirements.md
Original file line number Diff line number Diff line change
Expand Up @@ -601,6 +601,13 @@ This is enforced by the consensus algorithm.
This implies a maximum transaction size that is this `MaxBytes`, less the expected size of
the header, the validator set, and any included evidence in the block.

The Application should be aware that honest validators _may_ produce and
broadcast blocks with up to the configured `MaxBytes` size.
As a result, the consensus
[timeout parameters](../../docs/core/configuration.md#consensus-timeouts-explained)
adopted by nodes should be configured so as to account for the worst-case
latency for the delivery of a full block with `MaxBytes` size to all validators.

If the Application wants full control over the size of blocks,
it can do so by enforcing a byte limit set up at the Application level.
This Application-internal limit is used by `PrepareProposal` to bound the total size
Expand All @@ -615,6 +622,13 @@ If the Application sets value -1, consensus will:

Must have `MaxBytes == -1` OR `0 < MaxBytes <= 100 MB`.

> Bear in mind that the default value for the `BlockParams.MaxBytes` consensus
> parameter accepts as valid blocks with size up to 21 MB.
> If the Application's use case does not need blocks of that size,
> or if the impact (specially on bandwidth consumption and block latency)
> of propagating blocks of that size was not evaluated,
> it is strongly recommended to wind down this default value.
##### BlockParams.MaxGas

The maximum of the sum of `GasWanted` that will be allowed in a proposed block.
Expand Down

0 comments on commit 80648c4

Please sign in to comment.