Skip to content

docs: update CIP-48 parameters for v9 with ~3s block time #395

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
rootulp merged 3 commits into from
Apr 8, 2026
Merged

docs: update CIP-48 parameters for v9 with ~3s block time #395

Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
be9890a
docs: update CIP-48 parameters for v9 with ~2.6s block time
rach-id Apr 8, 2026
fc90ed2
docs: round up block-count parameters to ensure full duration coverage
rach-id Apr 8, 2026
f9ffd39
docs: update MaxAgeNumBlocks to 559,940
rach-id Apr 8, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
56 changes: 28 additions & 28 deletions cips/cip-048.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -12,7 +12,7 @@

## Abstract

This CIP proposes reducing the Celestia block time from 6 seconds to 3 seconds. This is achieved by adjusting the consensus timeout parameters (`TimeoutPropose`, `DelayedPrecommitTimeout`, `TimeoutPrevote`, and `TimeoutPrecommit`), doubling block-count-based parameters (`MaxAgeNumBlocks` and upgrade height delays) so they continue to represent the same wall-clock durations at the faster block rate, and correcting the IBC `MaxExpectedTimePerBlock` parameter. The `GoalBlockTime` constant is deprecated and removed as it is no longer accurate or necessary.
This CIP proposes reducing the Celestia block time from 6 seconds to 3 seconds. This is achieved by adjusting the consensus timeout parameters (`TimeoutPropose`, `DelayedPrecommitTimeout`, `TimeoutPrevote`, and `TimeoutCommit`), scaling block-count-based parameters (`MaxAgeNumBlocks` and upgrade height delays) to account for the ~2.6-second effective block time so they continue to represent the same wall-clock durations, and correcting the IBC `MaxExpectedTimePerBlock` parameter. The `GoalBlockTime` constant is deprecated and removed as it is no longer accurate or necessary.

## Motivation

Expand All @@ -28,21 +28,21 @@ CIP-26 previously reduced the block time from 12 seconds to 6 seconds and demons

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC 2119 and RFC 8174.

1. **Consensus timeout adjustments**: The following consensus timeout parameters MUST be updated to target a 3-second block time:
1. `TimeoutPropose` SHALL be reduced from 8500 milliseconds to 4500 milliseconds.
1. `DelayedPrecommitTimeout` SHALL be reduced from 5850 milliseconds to 2790 milliseconds.
1. `TimeoutPrevote` SHALL be reduced from 3000 milliseconds to 1500 milliseconds.
1. `TimeoutPrecommit` SHALL be reduced from 3000 milliseconds to 1500 milliseconds.
1. All other timeout parameters (`TimeoutProposeDelta`, `TimeoutPrevoteDelta`, `TimeoutPrecommitDelta`, `TimeoutCommit`) remain unchanged.
1. **Consensus timeout adjustments**: The following consensus timeout parameters MUST be updated to target a ~3-second block time:
1. `TimeoutPropose` SHALL be reduced from 8500 milliseconds to 3000 milliseconds.
1. `DelayedPrecommitTimeout` SHALL be reduced from 5850 milliseconds to 2100 milliseconds.
1. `TimeoutPrevote` SHALL be reduced from 3000 milliseconds to 2000 milliseconds.
1. `TimeoutCommit` SHALL be increased from 1 millisecond to 500 milliseconds.
1. All other timeout parameters (`TimeoutProposeDelta`, `TimeoutPrevoteDelta`, `TimeoutPrecommitDelta`, `TimeoutPrecommit`) remain unchanged.

1. **Evidence parameter adjustment**: The `MaxAgeNumBlocks` parameter MUST be doubled from 242,640 to 485,280 blocks so that it continues to represent approximately the same wall-clock duration (~16.8 days) at the new 3-second block time. The `MaxAgeDuration` parameter (337 hours) remains unchanged as it is defined in wall-clock time rather than block count.
1. **Evidence parameter adjustment**: The `MaxAgeNumBlocks` parameter MUST be increased from 242,640 to 559,940 blocks so that it continues to represent approximately the same wall-clock duration (~16.8 days) at the ~2.6-second effective block time. The `MaxAgeDuration` parameter (337 hours) remains unchanged as it is defined in wall-clock time rather than block count.

1. **Upgrade height delay adjustments**: All upgrade height delay parameters MUST be doubled to maintain the same wall-clock durations at the new block rate:
1. `ArabicaUpgradeHeightDelay` SHALL be increased from 14,400 to 28,800 blocks (1 day at 3 seconds per block).
1. `MochaUpgradeHeightDelay` SHALL be increased from 28,800 to 57,600 blocks (2 days at 3 seconds per block).
1. `MainnetUpgradeHeightDelay` SHALL be increased from 100,800 to 201,600 blocks (7 days at 3 seconds per block).
1. **Upgrade height delay adjustments**: All upgrade height delay parameters MUST be scaled to maintain the same wall-clock durations at the ~2.6-second effective block time:
1. `ArabicaUpgradeHeightDelay` SHALL be increased from 14,400 to 33,231 blocks (~1 day at ~2.6 seconds per block).
1. `MochaUpgradeHeightDelay` SHALL be increased from 28,800 to 66,462 blocks (~2 days at ~2.6 seconds per block).
1. `MainnetUpgradeHeightDelay` SHALL be increased from 100,800 to 232,616 blocks (~7 days at ~2.6 seconds per block).

1. **IBC `MaxExpectedTimePerBlock` correction**: The IBC `ConnectionGenesis.Params.MaxExpectedTimePerBlock` parameter MUST be reduced from 75 seconds to 15 seconds. Per IBC documentation, this value should be 3-5x the expected block time. The previous value of 75 seconds was based on the outdated `GoalBlockTime` of 15 seconds. With a ~3-second block time, a value of 15 seconds (5x the block time) is appropriate. An on-chain migration via the v8 upgrade handler MUST update this parameter for existing chains.
1. **IBC `MaxExpectedTimePerBlock` correction**: The IBC `ConnectionGenesis.Params.MaxExpectedTimePerBlock` parameter MUST be reduced from 75 seconds to 13 seconds. Per IBC documentation, this value should be 3-5x the expected block time. The previous value of 75 seconds was based on the outdated `GoalBlockTime` of 15 seconds. With a ~2.6-second effective block time, a value of 13 seconds (5x the block time) is appropriate. An on-chain migration via the v9 upgrade handler MUST update this parameter for existing chains.

1. **Deprecation of `GoalBlockTime`**: The `GoalBlockTime` constant (currently set to 15 seconds) is inaccurate and SHOULD be deprecated and removed. The actual target block time is determined by the consensus timeout parameters listed above rather than by this constant.

Expand All @@ -54,34 +54,34 @@ The following parameter changes are proposed:

| Parameter | Current value | Proposed value | Description | Changeable via Governance |
|-----------|---------------|----------------|-------------|---------------------------|
| `TimeoutPropose` | 8500 ms | 4500 ms | Maximum time to wait for a block proposal before prevoting nil | No |
| `DelayedPrecommitTimeout` | 5850 ms | 2790 ms | Time delay before sending a precommit vote | No |
| `TimeoutPrevote` | 3000 ms | 1500 ms | Timeout for the prevote step before prevoting nil | No |
| `TimeoutPrecommit` | 3000 ms | 1500 ms | Timeout for the precommit step before precommitting nil | No |
| `consensus.evidence.MaxAgeNumBlocks` | 242,640 blocks | 485,280 blocks | Maximum number of blocks for which evidence can be submitted for slashing | No |
| `ArabicaUpgradeHeightDelay` | 14,400 blocks | 28,800 blocks | Number of blocks Arabica waits after a MsgTryUpgrade to activate the next version (~1 day) | No |
| `MochaUpgradeHeightDelay` | 28,800 blocks | 57,600 blocks | Number of blocks Mocha waits after a MsgTryUpgrade to activate the next version (~2 days) | No |
| `MainnetUpgradeHeightDelay` | 100,800 blocks | 201,600 blocks | Number of blocks Mainnet waits after a MsgTryUpgrade to activate the next version (~7 days) | No |
| `ibc.ConnectionGenesis.Params.MaxExpectedTimePerBlock` | 75 seconds | 15 seconds | Maximum expected time per block used by IBC connection verification (should be 3-5x block time) | Yes |
| `TimeoutPropose` | 8500 ms | 3000 ms | Maximum time to wait for a block proposal before prevoting nil | No |
| `DelayedPrecommitTimeout` | 5850 ms | 2100 ms | Time delay before sending a precommit vote | No |
| `TimeoutPrevote` | 3000 ms | 2000 ms | Timeout for the prevote step before prevoting nil | No |
| `TimeoutCommit` | 1 ms | 500 ms | Time to wait after committing a block before starting the next height | No |
| `consensus.evidence.MaxAgeNumBlocks` | 242,640 blocks | 559,940 blocks | Maximum number of blocks for which evidence can be submitted for slashing | No |
| `ArabicaUpgradeHeightDelay` | 14,400 blocks | 33,231 blocks | Number of blocks Arabica waits after a MsgTryUpgrade to activate the next version (~1 day) | No |
| `MochaUpgradeHeightDelay` | 28,800 blocks | 66,462 blocks | Number of blocks Mocha waits after a MsgTryUpgrade to activate the next version (~2 days) | No |
| `MainnetUpgradeHeightDelay` | 100,800 blocks | 232,616 blocks | Number of blocks Mainnet waits after a MsgTryUpgrade to activate the next version (~7 days) | No |
| `ibc.ConnectionGenesis.Params.MaxExpectedTimePerBlock` | 75 seconds | 13 seconds | Maximum expected time per block used by IBC connection verification (should be 3-5x block time) | Yes |
| `GoalBlockTime` | 15 seconds | Removed | Deprecated constant that no longer reflects the actual target block time | No |

## Rationale

**Why 3 seconds?** The selection of a 3-second block time represents a practical halving of the current 6-second block time. This is the same approach taken in CIP-26 when block time was halved from 12 to 6 seconds. A 3-second block time is consistent with block times used by other modern L1 networks and provides a meaningful improvement in transaction latency without placing excessive demands on validator infrastructure.
**Why ~3 seconds?** The nominal target of a 3-second block time represents a practical halving of the current 6-second block time. This is the same approach taken in CIP-26 when block time was halved from 12 to 6 seconds. The actual effective block time from the proposed consensus parameters is ~2.6 seconds (`DelayedPrecommitTimeout` of 2100 ms + `TimeoutCommit` of 500 ms). A ~3-second block time is consistent with block times used by other modern L1 networks and provides a meaningful improvement in transaction latency without placing excessive demands on validator infrastructure.

**Why double block-count-based parameters?** Parameters defined in terms of block counts (such as `MaxAgeNumBlocks` and the upgrade height delays) represent wall-clock durations implicitly. When the block time is halved, these parameters must be doubled to preserve the same real-time durations. For example, `MainnetUpgradeHeightDelay` represents a 7-day waiting period: at 6 seconds per block this requires 100,800 blocks, and at 3 seconds per block this requires 201,600 blocks.
**Why scale block-count-based parameters?** Parameters defined in terms of block counts (such as `MaxAgeNumBlocks` and the upgrade height delays) represent wall-clock durations implicitly. When the effective block time changes, these parameters must be scaled by the ratio of old to new block time (6 / 2.6) to preserve the same real-time durations. For example, `MainnetUpgradeHeightDelay` represents a 7-day waiting period: at 6 seconds per block this requires 100,800 blocks, and at ~2.6 seconds per block this requires 232,616 blocks.

**Why remove `GoalBlockTime`?** The `GoalBlockTime` constant is set to 15 seconds, which has been inaccurate since CIP-26 reduced the block time to 6 seconds. Rather than updating it to 3 seconds, it is cleaner to remove it entirely. The actual block time is governed by the consensus timeout parameters (`TimeoutPropose`, `DelayedPrecommitTimeout`, etc.), making `GoalBlockTime` redundant and potentially misleading.

**Why reduce `MaxExpectedTimePerBlock` from 75 seconds to 15 seconds?** The IBC `MaxExpectedTimePerBlock` parameter should be 3-5x the expected block time per IBC documentation. The previous value of 75 seconds was calculated as 5x the `GoalBlockTime` of 15 seconds, which was already stale. With a ~3-second block time, 15 seconds (5x) is the correct value. An incorrect `MaxExpectedTimePerBlock` can cause IBC connection verification to behave suboptimally, as it affects how IBC calculates the expected time elapsed between block heights during connection handshakes and packet verification.
**Why reduce `MaxExpectedTimePerBlock` from 75 seconds to 13 seconds?** The IBC `MaxExpectedTimePerBlock` parameter should be 3-5x the expected block time per IBC documentation. The previous value of 75 seconds was calculated as 5x the `GoalBlockTime` of 15 seconds, which was already stale. With a ~2.6-second effective block time, 13 seconds (5x) is the correct value. An incorrect `MaxExpectedTimePerBlock` can cause IBC connection verification to behave suboptimally, as it affects how IBC calculates the expected time elapsed between block heights during connection handshakes and packet verification.

**Why halve `TimeoutPrevote` and `TimeoutPrecommit`?** These round-based timeout parameters (both currently 3000 ms) determine how long the network waits during the prevote and precommit steps before voting nil. Halving them to 1500 ms ensures that when the network fails to reach consensus in the first round, subsequent rounds progress proportionally faster. Without this adjustment, a failed round would take disproportionately long relative to the new 3-second block time, delaying recovery.
**Why reduce `TimeoutPrevote` and increase `TimeoutCommit`?** `TimeoutPrevote` is reduced from 3000 ms to 2000 ms to ensure that when the network fails to reach consensus in the first round, subsequent rounds progress proportionally faster relative to the new block time. `TimeoutPrecommit` remains unchanged at 3000 ms to preserve sufficient time for precommit aggregation. `TimeoutCommit` is increased from 1 ms to 500 ms to allow a delay for transactions to be included in the next block, benefiting clients that wait for a transaction to be included before submitting a new one. Combined with `DelayedPrecommitTimeout` of 2100 ms, this produces an effective block time of ~2.6 seconds in the happy path.

## Backwards Compatibility

This change is not backwards compatible. All consensus nodes must upgrade to the new software version before the activation height. Nodes running older software will be unable to keep up with the faster block production rate and will fall out of consensus.

Client applications and tooling that assume a 6-second block time (for example, when estimating confirmation times or computing block heights from timestamps) SHOULD be updated to reflect the new 3-second block time.
Client applications and tooling that assume a 6-second block time (for example, when estimating confirmation times or computing block heights from timestamps) SHOULD be updated to reflect the new ~2.6-second effective block time.

## Test Cases

Expand All @@ -96,7 +96,7 @@ These parameter changes will be tested on the Arabica devnet and Mocha testnet b

1. **Validator infrastructure requirements**: Faster block times place higher demands on validator hardware and network connectivity. Validators must ensure their systems can reliably propose and vote on blocks within the tighter time constraints. Validators with high-latency network connections may experience increased missed proposals or votes.

1. **Evidence validity window**: Doubling `MaxAgeNumBlocks` to 485,280 ensures the evidence validity window remains approximately 16.8 days at the new block rate, preserving the security guarantee that misbehavior can be detected and punished within the unbonding period. This maintains consistency with the unbonding time of 337 hours (14 days + 1 hour) established in CIP-37.
1. **Evidence validity window**: Increasing `MaxAgeNumBlocks` to 559,940 ensures the evidence validity window remains approximately 16.8 days at the ~2.6-second effective block time, preserving the security guarantee that misbehavior can be detected and punished within the unbonding period. This maintains consistency with the unbonding time of 337 hours (14 days + 1 hour) established in CIP-37.

1. **Upgrade coordination**: The simultaneous change of multiple consensus-critical parameters requires careful coordination. All parameters must be activated atomically as part of the same network upgrade to avoid inconsistent behavior.

Expand Down
Loading