BIP-0094: reformat specification section for clarity and readability

Roasbeef commented at 11:12 pm on March 6, 2025: contributor

In this commit, we restructure the specification section to make the consensus rules clearer and more scannable. The previous section interleaved commentary and historical tidbits with the motivation and new rules, making it difficult to quickly identify the exact rule changes.

A high level over view the intended changes is as follows:

Numbers each rule for easier reference
Adds explicit “Rule Specification” sections
Uses structured lists with MUST statements following RFC/IETF conventions
Provides a clear problem statement before each solution
Separates explanatory text from the actual rules

I was reviewing a PR to btcd to implement testnet4, and found it hard to scan the BIP to find the actual new rules, which inspired this PR.

BIP-0094: reformat specification section for clarity and readability

Restructured the specification section to make the consensus rules
clearer and more scannable. The previous section interleaved commentary
and historical tidbits with the motivation and new rules, making it
difficult to quickly identify the exact rule changes.

The updated format:
- Numbers each rule for easier reference
- Adds explicit "Rule Specification" sections
- Uses structured lists with MUST statements following RFC/IETF
  conventions
- Provides a clear problem statement before each solution
- Separates explanatory text from the actual rules

These changes make it much easier for implementers to understand what
changes are required without having to parse through multiple paragraphs
of text.

0dd4d3ec61

jonatack added the label Proposed BIP modification on Mar 7, 2025

jonatack added the label Pending acceptance on Mar 7, 2025

jonatack commented at 2:07 am on March 7, 2025: member

cc @fjahr

in bip-0094.mediawiki:81 in 0dd4d3ec61

90+
91+This rule prevents time warp attacks that could otherwise be used to amplify block storms<ref>A perpetual block storm attack with entire difficulty periods being authored in less than 3.5 days that resets the difficulty to the minimum in the last block of every difficulty period would adjust to a new actual difficulty of 4 every period. An attacker that additionally leverages a time warp attack would start their attack by holding back timestamps until the latest block's timestamp is at least two weeks in the past, and then limiting their block rate to six blocks per second, incrementing the timestamp on every sixth block. Only on the last block they would use the current time, which both resets the difficulty to one per the 20-minute exception and would result in a difficulty adjustment keeping the difficulty at the minimum due to the elapsed time exceeding the target. This would allow lower the difficulty for all blocks to difficulty 1 instead of difficulty 4</ref>.
92+
93+==== Rule Specification ====
94+
95+1. For any block whose height modulo 2016 equals 0 (i.e., the first block of each difficulty period):

murchandamus commented at 3:25 pm on March 12, 2025:

I like the “block height modulo 2016 equals 0” definition of “first block”. Perhaps this definition could be introduced in advance of Rule 1 as all three rules make reference to the “first block” per this definition.

in bip-0094.mediawiki:55 in 0dd4d3ec61

60+This rule enables CPU mining on testnet but has led to block storms<ref>https://blog.lopp.net/the-block-storms-of-bitcoins-testnet/</ref> which rule #2 below addresses.
61 
62-Block storms happen organically whenever the 20-minute exception is applied to a difficulty period’s last block, causing the block to be mined at a difficulty of 1. The difficulty adjustment rules then limit the subsequent period’s difficulty to a value between 1 (the minimum) and 4. Blocks will be generated rapidly in the subsequent low-difficulty periods while the difficulty climbs back to an adequate range. An arbitrarily large number of blocks can be generated quickly by repeatedly using the 20-minute exception on every last block of difficulty periods. The block storm is then bounded only by miner hash rate, the need for last blocks to have a timestamp 20 minutes after the second to last block, the Median-Time-Past nTime rule, and the requirement that blocks can't be more than 2 hours in the future. Overall a sustained attack would eventually be limited to a maximum cadence of six blocks per second.
63+=== 2. Block Storm Fix ===
64 
65-A block storm does not require a time warp attack, but one can be used to amplify<ref>A perpetual block storm attack with entire difficulty periods being authored in less than 3.5 days that resets the difficulty to the minimum in the last block of every difficulty period would adjust to a new actual difficulty of 4 every period. An attacker that additionally leverages a time warp attack would start their attack by holding back timestamps until the latest block’s timestamp is at least two weeks in the past, and then limiting their block rate to six blocks per second, incrementing the timestamp on every sixth block. Only on the last block they would use the current time, which both resets the difficulty to one per the 20-minute exception and would result in a difficulty adjustment keeping the difficulty at the minimum due to the elapsed time exceeding the target. This would allow lower the difficulty for all blocks to difficulty 1 instead of difficulty 4</ref> it.

murchandamus commented at 3:26 pm on March 12, 2025:

It seems to me that some of the description of block storms was dropped in the rewrite. Perhaps it could be moved to a footnote or rationale, for readers that are not already familiar with the concept of block storms rather than requiring them to read Lopp’s article.

fjahr commented at 4:43 pm on March 15, 2025:

Yeah, that would be good. As far as I can remember this was requested by reviewers of the original bip.

murchandamus commented at 3:31 pm on March 12, 2025: contributor

I have read the proposed changes, and have the impression that this refactor preserves the content of the Specification, I have however not gone to the level of comparing point-by-point with a checklist. The rewrite makes the rules more obvious which seems like an improvement to me.

Needs a sign-off from @fjahr for merge.

fjahr commented at 4:43 pm on March 15, 2025: contributor

ACK 0dd4d3ec61305610454e976cd5e92a7fb23c34e1

Changes look good to me, I can re-ack quickly if you want to address @murchandamus ’s comments.

jonatack removed the label Pending acceptance on Mar 17, 2025

in bip-0094.mediawiki:141 in 0dd4d3ec61

137@@ -117,4 +138,4 @@ Pull request at https://github.com/bitcoin/bitcoin/pull/29775
138 
139 == Copyright ==
140 
141-This document is licensed under the  Creative Commons CC0 1.0 Universal license.
142+This document is licensed under the  Creative Commons CC0 1.0 Universal license.

jonatack commented at 11:18 pm on March 17, 2025:

nit for any follow-up

0This document is licensed under the Creative Commons CC0 1.0 Universal license.

in bip-0094.mediawiki:67 in 0dd4d3ec61

75+==== Rule Specification ====
76 
77-In addition to a time warp attack potentially exacerbating the perpetual block storm attack, a time warp attack provides an alternative way to increase the block production rate even if the unintended reset of the actual difficulty due to the 20-minute exception was mitigated.
78+1. For difficulty adjustment calculations between periods:
79+   a. The base difficulty value MUST be taken from the first block of the previous difficulty period
80+   b. NOT from the last block as in previous implementations

jonatack commented at 0:39 am on March 18, 2025:

Here and in similar additions formatted this way, unsure if these render well on GitHub (in the GitHub preview, the a. and b. sections render as code, and the code tags within them don’t function).

Edit: yes, GitHub doesn’t render those sections well.

jonatack commented at 0:49 am on March 18, 2025: member

Agree with @murchandamus’s feedback and suggest they be done in a follow-up.

jonatack merged this on Mar 18, 2025

jonatack closed this on Mar 18, 2025

BIP-0094: reformat specification section for clarity and readability #1782