The raw next target of a retarget period and the target after a sequence of periods
DefinitionBitcoinDifficultyTwo names over the proof-of-work mission's BitcoinPow; nothing is re-transcribed.
rawNextTarget t lastTime firstTime — the value CalculateNextWorkRequired encodes: the last target times the clamped actual timespan (clampTimespan (lastTime − firstTime), between targetTimespan/4 and 4·targetTimespan), taken modulo , divided by targetTimespan (1,209,600 s), and capped at powLimit. calculateNextWork bits lastTime firstTime is by definition getCompact (rawNextTarget (setCompact bits) lastTime firstTime).
targetAfter bits periods — the encoded target after applying calculateNextWork once per element of periods, a list of (last time, first time) pairs, starting from bits.
Formalization Note. setCompact, getCompact, clampTimespan, calculateNextWork, nextWorkRequired, powLimit, width are the proof-of-work mission's; ChainState.requiredBits is the block mission's GetNextWorkRequired on a chain. Only Std is imported.
import Definitions.Def_BitcoinPow import Definitions.Def_BitcoinBlockV2 /-! # How fast the difficulty can move `CalculateNextWorkRequired` multiplies the last target by the clamped actual timespan of the period and divides by two weeks, caps at `powLimit`, and re-encodes. The clamp bounds the ratio by a factor of four in either direction; this file names the raw (unencoded) next target so the theorems can state that bound exactly, before the compact rounding, and then transfer it to the encoded value and along a chain of periods. These are the limits on what an adversary who controls timestamps can do to the difficulty: a "timewarp" moves the target by at most this much per period. -/ namespace BitcoinDifficulty open BitcoinPow /-- The raw next target of a period: the last target times the clamped timespan, divided by the target timespan, capped at `powLimit` — the value `CalculateNextWorkRequired` encodes. -/ def rawNextTarget (lastTarget : Nat) (lastTime firstTime : Int) : Nat := let ts := (clampTimespan (lastTime - firstTime)).toNat let bn := (lastTarget * ts) % width / targetTimespan if powLimit < bn then powLimit else bn /-- The encoded target after `m` retargets starting from `bits`, with the given sequence of (last time, first time) pairs, one per period. -/ def targetAfter : BitVec 32 → List (Int × Int) → BitVec 32 | bits, [] => bits | bits, (lastTime, firstTime) :: rest => targetAfter (calculateNextWork bits lastTime firstTime) rest end BitcoinDifficulty
Read-back
What the Lean code literally says, in plain math · claude-fable-5-1 (independent sub-agent, blind: Lean code + auditor instructions only)
Read-back: Def_BitcoinDifficulty.lean
This file introduces two definitions, rawNextTarget and targetAfter, in terms of the imported proof-of-work definitions. The imported notions they use are expanded first; then one paragraph per declaration, in file order.
Imported notions used
Constants (from the imported proof-of-work definitions).
- (the modulus called
width). - (the value called
powLimit). - (the value called
targetTimespan); hence and .
Decoding a compact word, (the function called setCompact). A compact word is a 32-bit word, i.e. an integer with . Put
- , the top byte of , an integer in ;
- , the low 23 bits of (bit 23, worth , and the top byte are discarded).
Then is the natural number
Consequences of this definition that the quantifiers below silently include: always; whenever , whenever , and whenever (the shift then exceeds 256 bits and the reduction modulo leaves ); for or only the low 16 or low 8 bits of survive the reduction; a word whose bit 23 ("sign" bit) is set decodes to the same value as the word with that bit cleared. never consults the overflow or sign conditions of the original code; it is a total function on all words.
Encoding a natural number, (the function called getCompact). For a natural number let be its bit length (, and for ) and let (the number of bytes of ). Put
If bit 23 of is set (i.e. , bitwise and), let and ; otherwise and . Then is the 32-bit word (bitwise or, then reduction modulo ).
Consequences: for every one has and , so the reductions modulo and change nothing and the bitwise or is a plain sum ; the word then has top byte and low 23 bits (bit 23 of is clear). Composing with : for , equals with its lowest bits set to zero (lowest bits when the bit-23 adjustment fired; nothing zeroed when and no adjustment), so in particular , and .
Clamping a timespan, (the function called clampTimespan). For an integer (positive, zero or negative),
always lies in , so it is positive and its conversion to a natural number (written below as well) is lossless.
The next encoded target, (the function called calculateNextWork). For a compact word and integers ("last time") and ("first time"), put and
i.e. . Then , a compact word. The product is reduced modulo before the floor division by ; the cap at is applied before re-encoding, and nothing caps or checks the decoded value of the encoded result afterwards.
Declaration 1: rawNextTarget
Binders. A natural number (named lastTarget; any natural number, with no upper bound — in particular not required to be below or ), and two integers (lastTime) and (firstTime), each positive, zero or negative, with no ordering between them.
Value. A natural number, defined as follows. Let , the clamped difference, a natural number in . Let
where the product is first reduced modulo and the result is then divided by with the remainder discarded (the source writes the two operations left to right, so the reduction precedes the division). Then
that is, with .
Edge cases built into the definition. If (including every case with , i.e. zero or negative differences), ; if , . If then . If (possible for , which is above ), the reduction modulo discards the high part before dividing. The result is always , and no encoding step is applied: is the value that calculateNextWork would pass to , so that for every compact word .
Declaration 2: targetAfter
Binders. A compact word (a 32-bit word, named bits) and a finite list of pairs of integers , where by the definition's naming the first component of each pair is the "last time" and the second the "first time" of that period.
Value. A compact word, defined by recursion on the list:
Hence for ,
where each application of decodes the current word with , multiplies by the clamped timespan modulo , floor-divides by , caps at , and re-encodes with (so each step rounds the value to a compact word before the next step decodes it).
Edge cases built into the definition. For the empty list, unchanged, whatever is (no decoding or validity check). The pairs are independent integers: nothing requires , nothing relates to , and no height or interval condition is consulted (unlike nextWorkRequired, every list element triggers a retarget). The initial word is unconstrained: it may have its bit 23 set, decode to , or have a top byte .
Confirmed by the mission captain (proposal self-audit).
Confirmed by the moderator at approval.