Skip to content

9 Proof of Work and Difficulty

Every Decred block header carries two difficulty values. The difficulty bits (header field Bits) encode the proof-of-work target: the hash of the header, computed with the network’s proof-of-work hash function and read as a number, must not exceed it. The stake difficulty (header field SBits), also called the ticket price, is the minimum amount, in atoms, that a ticket purchased in the block must pay. Neither value is chosen by the miner. Each is a deterministic function of the chain that the block extends, and a block whose header states any other value is invalid.

This chapter specifies how the proof of work is checked, how targets are encoded, how the work of a chain is measured, and how both difficulty values are computed. Each of the three mechanisms has changed once by stakeholder vote, and both forms of each are normative because a node validates the whole chain from the genesis block:

  • The proof-of-work hash was BLAKE-256 until the blake3pow agenda (DCP-0011 [34]) and is BLAKE3 afterwards.
  • The proof-of-work target was retargeted every 144 blocks by an exponentially weighted moving average (here called the EMA algorithm) until the same agenda, and is computed for every block by ASERT afterwards.
  • The stake difficulty was computed by a windowed moving average (stake difficulty version 1) until the sdiffalgorithm agenda (DCP-0001 [35]), and by the pool-size-based algorithm of that DCP (version 2) afterwards.

9.1 Overview and Selection of Algorithms

Table 9.1 lists the mechanisms and the condition that selects between them. “Active for the block” refers to the state of an agenda for the block being validated, computed from its ancestors as described in Chapter 13. Throughout this chapter, the block is the block being validated and the parent is the block it builds on; the parent always exists, because the genesis block is not validated (it is valid by definition, see Section 9.2.3).

Table 9.1. Difficulty mechanisms and their selection
QuantityOriginal ruleReplacementSelected by
Proof-of-work hashBLAKE-256 of the header (identical to the block hash)BLAKE3 of the headerblake3pow active for the block
BitsEMA algorithm (Section 9.6)ASERT (Section 9.7)blake3pow active for the block
SBitsVersion 1 (Section 9.9.1)Version 2 (Section 9.9.2)sdiffalgorithm active for the block

Table 9.2 summarizes how the two agendas resolved on each network defined by dcrd. An agenda that is forced active is active for every block, including block 1, without a vote. The activation heights restate the historical anchors of Table 13.8, which are part of the activity predicate (Rule 13.6): dcrd consults them before any tally of votes.

Table 9.2. Status of the difficulty-related agendas per network (informative)
Networkblake3pow (DCP-0011)sdiffalgorithm (DCP-0001)
mainnetVoted; active from block 794368Voted; active from block 149248
testnet3Voted; active from block 1170048Forced active
simnetForced activeForced active
regnetDecided by vote on each regnet chainDecided by vote on each regnet chain

The parameters used in this chapter are collected in Table 9.3. They are fields of the network parameters (Chapter 14); values are given for all four networks because the special cases below differ between them.

Table 9.3. Difficulty parameters
Parametermainnettestnet3simnetregnet
PowLimit2224−12232−12255−12255−1
PowLimitBits0x1d00ffff0x1e00ffff0x207fffff0x207fffff
TargetTimePerBlock300 s120 s1 s1 s
WorkDiffWindowSize14414488
WorkDiffWindows202044
WorkDiffAlpha1111
TargetTimespan43200 s17280 s8 s8 s
RetargetAdjustmentFactor4444
ReduceMinDifficultyfalsetruefalsefalse
MinDiffReductionTime(unused)600 s(unused)(unused)
WorkDiffV2Blake3StartBits0x1b00a5a60x1e00ffff0x207fffff0x207fffff
WorkDiffV2HalfLifeSecs4320072066
MinimumStakeDiff200000000200000002000020000
StakeDiffWindowSize14414488
StakeDiffWindows202088
StakeDiffAlpha1111
TicketPoolSizeWeight4444
TicketPoolSize819210246464
TicketsPerBlock5555
TicketMaturity256161616
CoinbaseMaturity256161616
BaseSubsidy311958266425000000005000000000050000000000
MulSubsidy / DivSubsidy100 / 101100 / 101100 / 101100 / 101
SubsidyReductionInterval61442048128128
Block-one subsidy (sum of BlockOneLedger)168000000000000100000000000003000000000000030000000000000
Genesis Bits0x1b01ffff0x1e00ffff0x207fffff0x207fffff
Genesis SBits2000000002000000000

Note

TargetTimespan equals WorkDiffWindowSize × TargetTimePerBlock on every network, but the EMA algorithm uses the parameter as given and an implementation should not derive it. RetargetAdjustmentFactor is shared by the EMA algorithm and stake difficulty version 1. Time durations are used as whole seconds.

9.1.1 Notation

The pseudocode follows the conventions of Section 2.7 in Chapter 2. In addition:

  • A block is represented by an object with the fields height, timestamp, bits, sbits, pool_size and fresh_stake, which are the header fields Height, Timestamp, Bits, SBits, PoolSize and FreshStake (Chapter 4), and parent, which is None for the genesis block. Timestamps are used as signed integers.
  • ancestor(b, h) is the block at height h on the chain ending at b (b itself if h = b.height), or None if h < 0.
  • back(b, d) is ancestor(b, max(b.height - d, 0)): the block d blocks before b, or the genesis block if b has fewer than d ancestors.
  • fdiv(a, b) is floor division for b > 0. It is used where dcrd applies the Euclidean division of Go’s big.Int.Div to a dividend that may be negative; for a positive divisor Euclidean division and floor division coincide. Where both operands are known to be non-negative, // is used.
  • >> on a negative integer is an arithmetic shift, rounding toward negative infinity; dcrd’s big.Int.Rsh behaves this way.
  • blake3pow_active_for(b) is true if the blake3pow agenda is active for block b, and blake3pow_active_for_child_of(p) if it is active for a block whose parent is p (similarly for sdiffalgorithm). blake3pow_forced_active is true on a network where the agenda is forced active, and is_testnet3 on testnet3.

9.2 The Proof-of-Work Check

9.2.1 Targets and the range rule

The target 𝑇 of a block is obtained by decoding its Bits field with the compact decoding of Section 9.3. A valid target is a positive integer no greater than the network’s PowLimit. The larger the target, the easier the block is to mine, so PowLimit defines the minimum difficulty.

Rule 9.1 · Target range

Let 𝑇=compact_to_big(Bits) (Algorithm 9.1), evaluated with unbounded signed integers. The block MUST be rejected (ErrUnexpectedDifficulty) if 𝑇≤0 or 𝑇> PowLimit. This check is context free and applies to every block other than the genesis block, independently of the proof-of-work hash check.

dcrd: internal/blockchain/validate.go · checkProofOfWorkSanity | blockchain/standalone/pow.go · checkProofOfWorkRange

A Bits value whose sign bit is set and whose mantissa decodes to a nonzero magnitude yields 𝑇<0; one whose decoded magnitude is zero (for example 0x00000000, 0x01003456, or 0x01800000) yields 𝑇=0. Both are rejected by this rule.

9.2.2 The proof-of-work hash

The proof-of-work hash is computed over the serialized 180-byte block header (Chapter 4): the same byte string from which the block hash is computed. Two hash functions are used:

  • Version 1 is BLAKE-256 with 14 rounds [9], as specified in Chapter 3. Its output is exactly the block hash.
  • Version 2 is BLAKE3 [10] with a 32-byte output and no key (Chapter 3). It is used only for the proof of work. The block hash remains the BLAKE-256 hash in every role (identifying the block, linking it to its parent, merkle and commitment structures) after the change.

The 32-byte digest is interpreted as an unsigned 256-bit integer in little-endian byte order: byte 0 of the digest is the least significant byte. Read this way, the human-readable display form of a hash (Chapter 2) is the big-endian hexadecimal representation of the integer, which is why solved hashes are displayed with leading zeros.

Rule 9.2 · Proof-of-work hash

Let 𝐻 be the BLAKE3 hash of the serialized header if the blake3pow agenda is active for the block, and the BLAKE-256 hash of the serialized header otherwise. Let ℎ be 𝐻 read as a little-endian unsigned 256-bit integer and 𝑇 the target of Rule 9.1. The block MUST be rejected (ErrHighHash) if ℎ>𝑇. A hash equal to the target is valid.

dcrd: internal/blockchain/validate.go · checkProofOfWorkSanity, checkProofOfWorkContext | blockchain/standalone/pow.go · checkProofOfWorkHash | wire/blockheader.go · PowHashV1, PowHashV2

Note

dcrd applies this rule in two stages. The context-free header check, which cannot evaluate the agenda, accepts a header whose BLAKE-256 hash or whose BLAKE3 hash satisfies the target (and rejects one for which neither does). The contextual check later requires the hash selected by the agenda, as stated in the rule. The combined effect is exactly Rule 9.2. A block that satisfies the target only with the other hash function is invalid, even though it passes the first stage.

Note

dcrd has a processing flag that skips the hash comparison (but not the range check) when it validates a block template that it built itself for mining. It has no effect on which blocks are valid.

9.2.3 The genesis block

The genesis block of each network is hard-coded and is not subjected to any of the rules in this chapter. Its Bits, SBits and Timestamp serve only as inputs to the difficulty calculations for its descendants. In particular the main-network genesis header does not satisfy its own target: its hash 298e5cc3d985bfe7f81dc135f360abe089edd4396b86d2de66b0cef42b21d980 (display form) is far above the target 0x1b01ffff encodes.

Test vector: BLAKE3 proof of work (testnet3 block 1170048)

This is the first BLAKE3 block of testnet3, from the reference vectors of DCP-0011, recomputed with dcrd. Hashes are in display form except where marked.

ItemValue
Serialized header (180 bytes)0b00000027d7ae5c9872a879b9a9da0b63915121d741e4cee3a96faea6eabf96b30000003271fd283c087219f14c7b26389fa1b22a639632d59e02e4f8e0456f36cbf740e9bba84160577d03ca9d858f07d6c78426421887cd6dc518d13fa06cfa000b5a01000b4e00a52a7705000400d4130000ffff001e9d7152e80000000080da1100e7100000085fb464f9a00f009cb73ed0429619d10000000000000000000000000000000000000000000000000b000000
Bits0x1e00ffff (PowLimitBits of testnet3)
Target 𝑇000000ffff000000000000000000000000000000000000000000000000000000
Block hash = BLAKE-256 PoW hashc7da7b548a2a9463dc97adb48433c4ffff18c3873f7e2ae99338a990dae039f0
BLAKE3 PoW hash, digest bytes in order331e3590bd3988f55d1e69cc0163ff98e23824686ff19853e9db0530ce000000
BLAKE3 PoW hash as integer ℎ (= display form)000000ce3005dbe95398f16f682438e298ff6301cc691e5df58839bd90351e33
Resultℎ≤𝑇 with BLAKE3: valid. The BLAKE-256 value exceeds 𝑇, so the header would fail Rule 9.2 before activation.

9.3 The Compact Target Encoding

Targets are 256-bit quantities but are carried in headers as a 32-bit compact value, a base-256 floating-point format inherited from Bitcoin. Bits 31 to 24 hold an unsigned exponent 𝑒, bit 23 a sign flag, and bits 22 to 0 an unsigned mantissa 𝑚. The encoded number is

𝑁=(−1)sign·⌊𝑚·256𝑒−3⌋

(9.1)

so that the exponent is the length in bytes of the magnitude and the mantissa holds its three most significant bytes. The floor matters only for 𝑒<3, where low-order mantissa bytes are discarded.

Algorithm 9.1 · Compact decoding (CompactToBig)

def compact_to_big(c: uint32) -> int:
    m = c & 0x007fffff
    negative = (c & 0x00800000) != 0
    e = c >> 24
    if e <= 3:
        n = m >> (8 * (3 - e))
    else:
        n = m << (8 * (e - 3))         # may exceed 256 bits; no overflow
    return -n if negative else n

dcrd: blockchain/standalone/pow.go · CompactToBig

Decoding is defined for every 32-bit value; the result can be negative, zero, or far larger than 2256 (up to (223−1)·22016). An implementation that decodes into a fixed-width unsigned 256-bit type MUST still reject exactly the values Rule 9.1 rejects: those with the sign bit set and a nonzero decoded magnitude, those whose decoded magnitude is zero, and those whose value exceeds PowLimit (which includes every value that overflows 256 bits: a nonzero mantissa with exponent ≥35, exponent 34 with 𝑚> 0xff, or exponent 33 with 𝑚> 0xffff).

Encoding produces the canonical compact form of a non-negative integer by truncating it to its three most significant bytes. It is used by consensus code only on non-negative values (every computed target is positive).

Algorithm 9.2 · Compact encoding (BigToCompact) of a non-negative integer

def big_to_compact(n: int) -> uint32:      # n >= 0
    if n == 0:
        return 0
    e = (n.bit_length() + 7) // 8          # length of n in bytes
    if e <= 3:
        m = n << (8 * (3 - e))
    else:
        m = n >> (8 * (e - 3))             # truncates: discards low bytes
    if m & 0x00800000:                     # would collide with the sign bit
        m = m >> 8
        e = e + 1
    return uint32((e << 24) | m)

dcrd: blockchain/standalone/pow.go · BigToCompact

The final normalization means a canonical mantissa never has bit 23 set; for 𝑒>3 it lies in the range 0x008000 to 0x7fffff. As a consequence, for canonical encodings of positive values the order of the 32-bit compact values as unsigned integers is the same as the order of the targets they encode, which some testnet rules rely on (Section 9.8).

Implementation pitfall

The encoding is lossy and not unique. Many 32-bit values decode to the same target (0x04001234 and 0x03123400 both decode to 0x123400), and encoding then decoding a target generally yields a smaller number (0x12345678 encodes to 0x04123456, which decodes to 0x12345600). Consensus compares compact values, never decoded targets: the Bits field must equal, as a 32-bit integer, the canonical encoding of the required target (Rule 9.3). An implementation that compares decoded targets instead would wrongly accept a header carrying a non-canonical encoding of the required target. Likewise, a computed target is always passed through big_to_compact before it is compared or reused; for example the decoded value of PowLimitBits is smaller than PowLimit on every network.

Note

dcrd’s encoder also accepts negative inputs, setting the sign bit. For a negative input with more than three bytes it rounds the magnitude of the mantissa up rather than down (it shifts the signed value arithmetically), so -0x1234567 encodes as 0x04812346. No consensus computation encodes a negative value, so this has no effect on validity.
Test vector: Compact decoding
BitsDecoded value (hexadecimal)Note
0x1d00ffffffff followed by 52 zero digits (=ffff·2208)mainnet PowLimitBits
0x1b01ffff1ffff000000000000000000000000000000000000000000000000mainnet genesis
0x1b00a5a6a5a6000000000000000000000000000000000000000000000000mainnet BLAKE3 start
0x1e00ffffffff followed by 54 zero digitstestnet3 limit
0x207fffff7fffff followed by 58 zero digitssimnet/regnet limit
0x00000000, 0x00123456, 0x010034560rejected
0x011234560x12low bytes dropped
0x021234560x1234
0x031234560x123456
0x041234560x12345600
0x050092340x92340000
0x04923456-0x12345600sign bit; rejected
0x01810000-1sign bit; rejected
0x010100001hardest valid target
0x20123456123456 followed by 58 zero digitsabove every PowLimit
Test vector: Compact encoding
Input (hexadecimal)EncodingDecodes back to
00x000000000
10x010100001
7f0x017f00007f
800x0200800080
ff0x0200ff00ff
12340x021234001234
1234560x03123456123456
8000000x04008000800000
123456780x0412345612345600
ffffffff0x0500ffffffff0000
2224−10x1d00ffffffff·2208
2232−10x1e00ffffffff·2216
2255−10x207fffff7fffff·2232
2256−10x2100ffffffff·2240
2226−10x1d03ffff3ffff·2208

9.4 Work and Chain Work

The work of a block measures the expected number of hash evaluations needed to find a header that meets its target. It is computed from the Bits field alone:

Algorithm 9.3 · Work of a block (CalcWork)

def calc_work(bits: uint32) -> int:
    t = compact_to_big(bits)
    if t <= 0:
        return 0
    return (1 << 256) // (t + 1)

dcrd: internal/staging/primitives/pow.go · CalcWork | blockchain/standalone/pow.go · CalcWork

For any target that overflows 256 bits the quotient is zero, so the result is zero for every Bits value outside the valid range except targets between PowLimit and 2256−1, which Rule 9.1 excludes anyway. (dcrd’s block index uses a fixed-width 256-bit implementation that returns zero for negative, zero, and overflowing values and is otherwise equal to this formula.)

The cumulative work (chain work) of a block is the sum of calc_work over the block and all of its ancestors, including the genesis block. It is the quantity by which competing chains are compared; chain selection is specified in Chapter 10.

Test vector: Work
Bitscalc_work (hexadecimal)
0x1d00ffff100010001
0x1b01ffff800040002000
0x1b00a5a618ba210ed6b21
0x1e00ffff1000100
0x207fffff2
0x010100008000000000000000000000000000000000000000000000000000000000000000
0x04923456, 0x000000000

9.5 Required Difficulty Bits

Rule 9.3 · Difficulty bits

The Bits field of the block MUST equal, as a 32-bit unsigned integer, the value returned by next_required_bits(parent, timestamp) (Algorithm 9.4), where parent is the parent block and timestamp is the block’s own Timestamp field. Otherwise the block MUST be rejected (ErrUnexpectedDifficulty).

dcrd: internal/blockchain/validate.go · checkBlockHeaderContext, checkDifficultyPositional | internal/blockchain/difficulty.go · calcNextRequiredDifficulty

Algorithm 9.4 · Required difficulty bits

def next_required_bits(parent, timestamp: int64) -> uint32:
    if blake3pow_active_for_child_of(parent):
        return next_bits_asert(parent)              # Algorithm "ASERT required bits"
    return next_bits_ema(parent, timestamp)         # Algorithm "EMA required bits"

dcrd: internal/blockchain/difficulty.go · calcNextRequiredDifficulty

The block’s own timestamp is an input only in the EMA algorithm, and only through the testnet minimum-difficulty rule (Section 9.8). In all other cases the required bits are a function of the parent chain alone.

Note

Before the full contextual checks, dcrd checks Bits while accepting every new header, with only the ancestor headers available, where the agenda state is not yet known in general. On a network where blake3pow is forced active that earlier check computes the ASERT result directly. Otherwise, if an anchor that dcrd has already determined from full block data is an ancestor of the header, it requires the ASERT result for that anchor. Failing that, it requires the EMA result, except that a header that is solved under BLAKE3, has a version of at least 10 (mainnet) or 11 (other networks), and is at a height of at least StakeValidationHeight +2× RuleChangeActivationInterval is also accepted if its Bits matches the ASERT result for a candidate anchor: the final block of an earlier rule change interval, tried from the most recent backwards while the candidate’s version is at least that same minimum and its height is at least StakeValidationHeight +2× RuleChangeActivationInterval −1. This check never rejects a block that satisfies Rule 9.3, Rule 9.2 and the block version rule of Chapter 10: the blake3pow deployment has version 10 on mainnet and 11 on the other networks, it can leave the defined state only once a majority of recent blocks has at least that version (Chapter 13), and from then on the block version rule rejects every block with a lower version. A conforming implementation needs only Rule 9.3.

When dcrd connects the full data of a block that is an ancestor of its assumed-valid block (Chapter 10), or runs in bulk-import mode, it skips this comparison together with the stake difficulty comparison of Rule 9.6 (the header-acceptance check of the note above still applies to Bits); this is an optimization that presumes those blocks satisfy the rules, not a relaxation of them.

9.6 The EMA Difficulty Algorithm

The EMA algorithm is the original proof-of-work retargeting rule. It applies to every block for which blake3pow is not active: on mainnet, blocks 1 to 794367.

The target changes only at retarget blocks, those whose height is a multiple of WorkDiffWindowSize (144 on mainnet); every other block must repeat its parent’s Bits (except under the testnet rule of Section 9.8). At a retarget block, the algorithm looks back over WorkDiffWindows (20) consecutive windows of WorkDiffWindowSize blocks each, ending at the parent. For each window it measures the time the window took relative to TargetTimespan, as a 32.32 fixed-point ratio. The ratios are averaged with weights that double from each window to the next more recent one, and the old target is multiplied by the average. The result is clamped to between one quarter and four times the old target (RetargetAdjustmentFactor =4) and to at most PowLimit.

9.6.1 Windows

Let the block be at height 𝐻, a multiple of 𝑊= WorkDiffWindowSize, so the parent 𝑃 is at height 𝐻−1. Window 𝑘 (for 𝑘=0,…,𝑁−1, 𝑁= WorkDiffWindows) is delimited by the two blocks back(P, k W) (its newer end) and back(P, (k+1) W) (its older end). Its time difference is the difference of their timestamps, except that if the older end is the genesis block the window is taken to have lasted exactly TargetTimespan. With back clamping at the genesis block, this covers every window that reaches back to or beyond the genesis block, including a window whose newer end is itself the genesis block. Window 𝑘 has weight 2(𝑁−𝑘)𝛼 with 𝛼= WorkDiffAlpha, so with mainnet parameters window 0 (the most recent) has weight 220 and window 19 has weight 21; the weights sum to 221−2.

Table 9.4. EMA windows for the mainnet retarget block at height 𝐻=144𝑚
Window 𝑘Newer end (height)Older end (height)Weight
0144𝑚−1144(𝑚−1)−1220
1144(𝑚−1)−1144(𝑚−2)−1219
…………
19144(𝑚−19)−1144(𝑚−20)−121

Heights below 0 in Table 9.4 mean the genesis block. A window’s time difference may be negative if timestamps decrease; the arithmetic below is defined for that case and uses floor division.

9.6.2 Algorithm

Algorithm 9.5 · EMA required bits

TESTNET3_MAX_DIFF_HEIGHT = 962928

def next_bits_ema(parent, timestamp: int64) -> uint32:
    W, N, ALPHA = WorkDiffWindowSize, WorkDiffWindows, WorkDiffAlpha
    SPAN = TargetTimespan                      # in seconds
    RAF = RetargetAdjustmentFactor
    next_height = parent.height + 1

    if next_height % W != 0:                   # not a retarget block
        if ReduceMinDifficulty and (not is_testnet3 or
                                    next_height < TESTNET3_MAX_DIFF_HEIGHT):
            if timestamp > parent.timestamp + MinDiffReductionTime:
                return PowLimitBits
            return last_non_min_diff_bits(parent)
        return parent.bits

    old = compact_to_big(parent.bits)
    lower = fdiv(old, RAF)
    upper = old * RAF

    weighted_sum = 0
    weights = 0
    for k in range(N):                         # k = 0 is the most recent window
        newer = back(parent, k * W)
        older = back(parent, (k + 1) * W)
        elapsed = newer.timestamp - older.timestamp
        if older.height == 0:
            elapsed = SPAN
        ratio = fdiv(elapsed << 32, SPAN)      # 32.32 fixed point, may be < 0
        weighted_sum += ratio << ((N - k) * ALPHA)
        weights += 1 << ((N - k) * ALPHA)

    target = (fdiv(weighted_sum, weights) * old) >> 32

    if old == 0:
        pass                                   # unreachable for valid chains
    elif target == 0:
        target = PowLimit
    elif target > upper:
        target = upper
    elif target < lower:
        target = lower
    if target > PowLimit:
        target = PowLimit
    if is_testnet3 and target < MIN_TESTNET_TARGET and \
            next_height >= TESTNET3_MAX_DIFF_HEIGHT:
        target = MIN_TESTNET_TARGET            # 2**226 - 1, see testnet rules
    return big_to_compact(target)

def last_non_min_diff_bits(b) -> uint32:
    period = WorkDiffWindowSize * WorkDiffWindows
    while b is not None and b.height % period != 0 and b.bits == PowLimitBits:
        b = b.parent
    return b.bits if b is not None else PowLimitBits

dcrd: internal/blockchain/difficulty.go · calcNextBlake256Diff, findPrevTestNetDifficulty

The order of operations is significant and must be reproduced exactly: each window ratio is floored before it is weighted; the weighted sum is floor-divided by the sum of weights before multiplication by the old target; and the product is shifted right by 32 (flooring) only at the end. The clamping is a chain of alternatives evaluated in the order shown, of which at most one applies, followed by the PowLimit clamp. A computed target of exactly zero (when the floored average ratio times the old target is below 232) becomes PowLimit, whereas a negative computed target (possible only with decreasing timestamps) falls into the lower branch.

Implementation pitfall

Every intermediate quantity is unbounded: elapsed << 32 exceeds 64 bits for elapsed times above 231 seconds, and the weighted terms grow with the window weights. An implementation using 64-bit integers for the ratio sum overflows on realistic inputs. Division of a negative weighted sum must floor (not truncate).

Implementation pitfall

The retarget condition uses WorkDiffWindowSize alone (retargets every 144 blocks), while last_non_min_diff_bits stops at multiples of WorkDiffWindowSize × WorkDiffWindows (2880 blocks). This asymmetry is part of the testnet rule as implemented.

Rationale

Each window ratio is the factor by which the target would need to change to make that window last exactly TargetTimespan at the same hash rate. Weighting recent windows more heavily makes the estimate an exponentially weighted moving average over roughly the last 2880 blocks (10 days on mainnet), smoothing short-term hash-rate fluctuations while still tracking trends. Treating windows that extend before the genesis block as on-target lets the algorithm run unchanged from block 144.
Test vector: EMA retargets with mainnet parameters

Chains of n blocks after the mainnet genesis block (timestamp 1454954400), with the stated block spacing and every block carrying the stated Bits. The result is next_bits_ema for the block at height n + 1, which is a retarget block in every case. For each case the block at height n (not a retarget block) required the parent’s Bits unchanged.

nBlock spacingParent BitsRequired Bits
2879300 s0x1b01ffff0x1b01ffff
2879600 s0x1b01ffff0x1b03fffd
5759600 s0x1b01ffff0x1b03fffe
5759150 s0x1b01ffff0x1b00ffff
575960 s0x1b01ffff0x1a7fffc0 (clamped to old/4)
57593000 s0x1b01ffff0x1b07fffc (clamped to old × 4)
143150 s0x1b01ffff0x1b01ffff (all windows reach genesis)
287150 s0x1b01ffff0x1b017fff
5759300 s; 600 s for the last 144 blocks0x1b01ffff0x1b02fffe
5759600 s for blocks 1 to 3023; 300 s after0x1b01ffff0x1b01ffff
5759200+50·(ℎmod7) s before block ℎ0x1a0f00ff0x1a1184d6

In the 600 s case with n = 2879, windows 0 to 18 each lasted 86400 s (ratio 2·232) and window 19 reaches the genesis block and counts as on target (ratio 232). The weighted sum is 18014372739678208; divided by the weight sum 221−2 it gives 8589930495 (0x1ffffefff), slightly below 2·232; multiplying by the old target 0x1ffff ·2192 and shifting right by 32 gives 3fffddffe10010000000000000000000000000000000000000000, which encodes to 0x1b03fffd.

9.7 ASERT

Once blake3pow is active, the required target is computed for every block by ASERT (“absolutely scheduled exponentially rising targets”, [36], DCP-0011). ASERT fixes an anchor block and an ideal schedule from it: one block every TargetTimePerBlock seconds. If the parent is Δ𝑡 seconds after the anchor and Δℎ blocks above it, it is Δ𝑡−Δℎ· TargetTimePerBlock seconds behind schedule, and the target is set to the starting target WorkDiffV2Blake3StartBits multiplied by 2 raised to that delay divided by the half-life WorkDiffV2HalfLifeSecs:

𝑇=min(max(𝑇𝑠·2(Δ𝑡−Δℎ·𝐼𝑏)/𝜏,1),PowLimit)

(9.2)

with 𝑇𝑠 the decoded starting target, 𝐼𝑏= TargetTimePerBlock and 𝜏= WorkDiffV2HalfLifeSecs. The target doubles (difficulty halves) for every half-life the chain is behind schedule and halves for every half-life it is ahead. Eq. (9.2) is the design goal; the normative computation is the integer approximation of Algorithm 9.6, which uses a 16-bit fixed-point exponent and a cubic polynomial for the fractional power of two.

9.7.1 The anchor block and the difficulty reset

The anchor is determined as follows:

  • If blake3pow was activated by a vote (mainnet, testnet3, and regnet once voted): the anchor is the last block, on the chain of the block being validated, for which blake3pow is not active; equivalently, the parent of the first block for which it is active. Because an agenda’s state changes only at the start of a rule change interval (Chapter 13), the anchor is the final block of a rule change interval. The first BLAKE3 block is the block immediately after the anchor; its parent is the anchor itself, so Δ𝑡=Δℎ=0 and its required bits are exactly WorkDiffV2Blake3StartBits (see the vectors). The proof-of-work hash switches to BLAKE3 at the same block (Rule 9.2).
  • If blake3pow is forced active (simnet): block 1 must carry WorkDiffV2Blake3StartBits, and block 1 is the anchor for every later block. The genesis block is never the anchor, because its hard-coded timestamp is typically far in the past when mining starts.
Table 9.5. ASERT anchors of the networks where the agenda was voted (informative)
NetworkAnchor heightAnchor block hash (display form)
mainnet7943670000000000000000c293d8c67409d05e960447ea25cdaf770e864d995c764ef0
testnet31170047000000b396bfeaa6ae6fa9e3cee441d7215191630bdaa9b979a872985caed727

Note that the anchor’s own Bits are not used: the difficulty is reset to WorkDiffV2Blake3StartBits at activation, because a target appropriate for specialized BLAKE-256 hardware would be unattainable with BLAKE3. Only the anchor’s height and timestamp enter the calculation.

9.7.2 Algorithm

Algorithm 9.6 · ASERT target calculation (CalcASERTDiff)

POLY_C1 = 195766423245049     # ceil(0.695502049712533 * 2**48)
POLY_C2 = 971821376           # ceil(0.2262697964 * 2**32)
POLY_C3 = 5127                # ceil(0.0782318 * 2**16)

def asert(start_bits: uint32, pow_limit: int, block_secs: int,
          dt: int, dh: int, half_life: int) -> uint32:
    start = compact_to_big(start_bits)
    assert 0 < start <= pow_limit and dh >= 0       # guaranteed by callers

    # Exponent in 16.16 fixed point, truncated toward zero.
    x = tdiv((dt - dh * block_secs) << 16, half_life)
    n = x >> 16                  # integer part: arithmetic shift (floor)
    f = x & 0xffff               # fractional part, 0 <= f < 2**16

    # 2**16 * 2**(f / 2**16), cubic approximation, 16.48 fixed point inside.
    factor = (1 << 16) + ((POLY_C1 * f + POLY_C2 * f * f +
                           POLY_C3 * f * f * f + (1 << 47)) >> 48)

    target = start * factor
    s = n - 16
    if s >= 0:
        target = target << s
    else:
        target = target >> -s    # floor
    if target == 0:
        target = 1
    elif target > pow_limit:
        target = pow_limit
    return big_to_compact(target)

dcrd: blockchain/standalone/pow.go · CalcASERTDiff

Algorithm 9.7 · ASERT required bits

MIN_TESTNET_BITS = 0x1d03ffff             # big_to_compact(MIN_TESTNET_TARGET)

def next_bits_asert(parent) -> uint32:
    if blake3pow_forced_active:
        if parent.height == 0:
            return WorkDiffV2Blake3StartBits
        anchor = ancestor(parent, 1)
    else:
        # Last block on this chain for which blake3pow is not active.
        anchor = parent
        while blake3pow_active_for(anchor):
            anchor = anchor.parent
    dt = parent.timestamp - anchor.timestamp      # may be negative
    dh = parent.height - anchor.height            # >= 0
    bits = asert(WorkDiffV2Blake3StartBits, PowLimit, TargetTimePerBlock,
                 dt, dh, WorkDiffV2HalfLifeSecs)
    if is_testnet3 and bits < MIN_TESTNET_BITS:   # unsigned 32-bit comparison
        bits = MIN_TESTNET_BITS
    return bits

dcrd: internal/blockchain/difficulty.go · calcNextBlake3Diff, calcNextBlake3DiffFromAnchor, blake3WorkDiffAnchor

dcrd locates the anchor by stepping back one rule change interval at a time from the final block of the interval preceding the block, testing only those interval-final blocks, and caches the result; because the agenda state can change only at interval boundaries, the block-by-block loop in Algorithm 9.7 finds the same block. If blake3pow is active for the block but not for its parent, the anchor is the parent. The loop always terminates before the genesis block, since an agenda activated by vote is never active for block 1.

Implementation pitfall

The exponent uses truncating division (toward zero), but its integer part uses flooring (an arithmetic shift) and its fractional part is the non-negative remainder modulo 216, so that 𝑥=216𝑛+𝑓 exactly. For example Δ𝑡=299, Δℎ=1 on mainnet gives 𝑥=tdiv(−65536,43200)=−1, hence 𝑛=−1 and 𝑓=65535; floor division would give 𝑥=−2 and a different result. A logical (unsigned) shift for 𝑛 is also wrong.

Implementation pitfall

The polynomial numerator needs the full unsigned 64-bit range: at 𝑓=65535 it equals 18446563080438344768, just below 264. It is always positive and the resulting factor is at most 17 bits (216≤factor<217). In the final step the shift amount 𝑛−16 is unbounded in principle; for consensus inputs (Δℎ<232, timestamps 32-bit) the exponent stays far inside the 64-bit range, but the target before clamping can exceed 256 bits (on testnet3, whose half-life is 720 seconds, by more than a thousand bits for a chain stalled for two weeks). An implementation may clamp early, provided the result is identical: any left shift by at least the bit length of PowLimit yields PowLimit, and any right shift by at least the bit length of start * factor yields 1.

Implementation pitfall

The testnet3 lower bound in Algorithm 9.7 compares the 32-bit compact values, not targets. Because asert returns a canonical encoding of a positive target, this ordering agrees with the ordering of the targets (Section 9.3).

Rationale

An absolutely scheduled algorithm measures the cumulative deviation from the ideal schedule since a fixed point, so errors do not accumulate and there are no windows whose boundaries a miner could exploit. Using a fixed anchor makes each target an exact function of two numbers, which is cheaper to compute and to verify than a windowed average. The polynomial approximates 2𝑥 on [0,1) with a relative error below 0.013%, and integer arithmetic keeps the result identical across implementations.
Test vector: ASERT with mainnet parameters

Start bits 0x1b00a5a6, PowLimit =2224−1, block time 300, half-life 43200. dt and dh are the deltas of the parent from the anchor.

dtdhResultComment
000x1b00a5a6first BLAKE3 block
30010x1b00a5a6on schedule
29910x1b00a5a5𝑥=−1, 𝑛=−1, 𝑓=65535, factor 131071
30110x1b00a5a6𝑥=1, 𝑛=0, 𝑓=1, factor 65537
100x1b00a5a6
−100x1b00a5a5
4320000x1b014b4cone half-life behind: target doubles
−4320000x1a52d300one half-life ahead: target halves
2160000x1b00ea3e𝑥=32768, factor 92674
−2160000x1a751f03𝑥=−32768, 𝑛=−1, 𝑓=32768
864001440x1b014b4c
8640000x1b029698
01440x1a52d300
02880x1a296980
1728002880x1b029698
86400000x1d00ffffclamped to PowLimit
−172800000x1600a5a640 half-lives ahead
−432000000x0e0a5a60100 half-lives ahead
−894240000x01010000207 half-lives ahead: the shift leaves exactly 1
−898560000x01010000208 half-lives ahead: the shift leaves 0, clamped to 1
Test vector: ASERT reference vectors of DCP-0011 (excerpt)

From the test vector file shipped with dcrd and DCP-0011; mainnet parameters, anchor height 0 and anchor time as stated. dcrd reproduces all of them.

Start bitsAnchor timeHeightTimestampResult
0x1d00ffff016912000x1d00ffff
0x1d00ffff06117936000x1d00ffff
0x1b00a5a60411990x1b00a5a5
0x1b00a5a630012990x1b00a4da
0x1b00a5a630062940x1b00a0ed
0x0101000001435000x01020000
0x01010000073045000x02008000
Test vector: ASERT with testnet3 parameters and the testnet3 bound

Start bits 0x1e00ffff, PowLimit =2232−1, block time 120, half-life 720.

dtdhasert resultRequired bits
000x1e00ffff0x1e00ffff
1200100x1e00ffff0x1e00ffff
600100x1e008faf0x1e008faf
−72000x1d7fff800x1d7fff80
−720000x1c3fffc00x1d03ffff (testnet3 bound)

9.8 Test Network Rules

Version 3 of the test network (testnet3) has rules that keep it usable with ordinary hardware. They are selected by the network identity (the TestNet3 network magic), not by a parameter, except for the minimum-difficulty rule, which is selected by ReduceMinDifficulty and limited on testnet3 by height. On testnet3, MIN_TESTNET_TARGET is PowLimit shifted right by 6 bits, 2226−1 (a maximum difficulty of 26=64 relative to the limit), and MIN_TESTNET_BITS = big_to_compact(MIN_TESTNET_TARGET) = 0x1d03ffff. The threshold height is 962928.

Minimum-difficulty blocks
On a network with ReduceMinDifficulty set (only testnet3 among dcrd’s networks), for a block that is not an EMA retarget block and, on testnet3, whose height is below 962928: if its timestamp is more than MinDiffReductionTime (600 s) after its parent’s timestamp, the required bits are PowLimitBits; otherwise they are the bits of the most recent ancestor (starting with the parent) that does not carry PowLimitBits, stopping at the first block whose height is a multiple of WorkDiffWindowSize × WorkDiffWindows (Algorithm 9.5). Retarget blocks are never minimum-difficulty blocks, and the retarget calculation uses the parent’s Bits as the old target even if it is PowLimitBits. The rule never applies to ASERT.
Maximum difficulty
On testnet3, from height 962928 on, an EMA retarget result below MIN_TESTNET_TARGET is replaced by MIN_TESTNET_TARGET before encoding, and an ASERT result whose compact value is below MIN_TESTNET_BITS is replaced by MIN_TESTNET_BITS (at all heights; ASERT begins above 962928 on testnet3). Both forms produce the same compact result for every target, because every target between the decoded value of 0x1d03ffff and 2226−1 encodes to 0x1d03ffff.
Block spacing and checkpoint
Rule 9.4 and Rule 9.5 below.

Rule 9.4 · Testnet3 maximum-difficulty checkpoint

On testnet3, a block at height 962928 whose block hash is not the hash below (display form) MUST be rejected (ErrBadMaxDiffCheckpoint): 0000004fd1b267fd39111d456ff557137824538e6f6776168600e56002e23b93

dcrd: internal/blockchain/validate.go · checkBlockHeaderPositional

Rule 9.5 · Testnet3 minimum block spacing at maximum difficulty

On testnet3, a block at height 962928 or above whose Bits, compared as an unsigned 32-bit integer, is less than or equal to 0x1d03ffff MUST have a timestamp at least 60 seconds after its parent’s timestamp (equality allowed); otherwise it MUST be rejected (ErrTimeTooOld).

dcrd: internal/blockchain/validate.go · checkBlockHeaderPositional

History

The testnet3 maximum-difficulty rules were introduced at height 962928. dcrd invalidates, at startup, any stored testnet3 chain whose block at that height is not the checkpoint block, which has the same effect as Rule 9.4 for chains received before the rule existed.

9.9 Stake Difficulty

The stake difficulty is the ticket price: the minimum value, in atoms, of the stake submission output (output 0) of every ticket purchase in a block. It is carried in the header field SBits, an int64. Like the proof-of-work target it is recomputed only at stake retarget blocks, those whose height is a multiple of StakeDiffWindowSize (144 blocks on mainnet), and every other block repeats its parent’s value. The ticket structure, the ticket pool and the header fields PoolSize (the number of live tickets) and FreshStake (the number of ticket purchases in the block) are specified in Chapter 8.

Rule 9.6 · Stake difficulty

The SBits field of the block MUST equal next_required_sbits(parent) (Algorithm 9.8), where parent is the parent block. Otherwise the block MUST be rejected (ErrUnexpectedDifficulty).

dcrd: internal/blockchain/validate.go · checkBlockHeaderContext | internal/blockchain/difficulty.go · calcNextRequiredStakeDifficulty

The SBits field is in turn the minimum price of every ticket in the block: Rule 8.6 requires output 0 of each ticket purchase in the stake tree to be worth at least the block’s SBits and at least MinimumStakeDiff.

Algorithm 9.8 · Required stake difficulty

def next_required_sbits(parent) -> int64:
    if sdiffalgorithm_active_for_child_of(parent):
        return next_sbits_v2(parent)
    return next_sbits_v1(parent)

dcrd: internal/blockchain/difficulty.go · calcNextRequiredStakeDifficulty

Both versions share the retarget schedule and carry the parent’s value forward between retargets. They differ by one block in their start-up rule: version 1 returns MinimumStakeDiff whenever the parent’s height is at most CoinbaseMaturity, version 2 whenever the block’s height is at most CoinbaseMaturity. Before CoinbaseMaturity +1 no output exists that could fund a ticket.

Note

On mainnet the sdiffalgorithm agenda became active at block 149248, which is not a stake retarget block (149248=1036×144+64). Blocks 149248 to 149327 therefore carry forward the value computed by version 1 for block 149184, and block 149328 is the first to be computed by version 2, from that carried-forward value. No other transition step exists.

9.9.1 Version 1

Version 1 computes two independent estimates of the new price, each a weighted moving average over StakeDiffWindows windows of StakeDiffWindowSize blocks in the style of the EMA algorithm, and combines them:

  • The pool-size estimate compares the live ticket pool size, sampled once per window, with the target pool size TicketsPerBlock×TicketPoolSize (40960 on mainnet). Deviations are amplified by TicketPoolSizeWeight.
  • The fresh-stake estimate compares the number of tickets bought in each window with StakeDiffWindowSize×TicketsPerBlock (720 on mainnet).

Each estimate is clamped to a factor of RetargetAdjustmentFactor around the old price, the two are combined multiplicatively, the result is clamped again, and finally raised to at least MinimumStakeDiff.

For a stake retarget block at height 𝐻=144𝑚 with mainnet parameters, the pool-size estimate uses the PoolSize of the blocks at heights 144(𝑚−1−𝑘) for 𝑘=0,…,19 (the first block of each of the last 20 intervals), and the fresh-stake estimate sums FreshStake over the complete intervals [144(𝑚−1−𝑘),144(𝑚−𝑘)−1]. Window 𝑘 has weight 2(20−𝑘)𝛼 with 𝛼= StakeDiffAlpha =1. Blocks before the genesis block are replaced by the genesis block (whose PoolSize and FreshStake are 0 on every network); in the fresh-stake sum, a window extending before the genesis block therefore counts the genesis block repeatedly.

Algorithm 9.9 · Stake difficulty version 1

def next_sbits_v1(parent) -> int64:
    SW, SN, ALPHA = StakeDiffWindowSize, StakeDiffWindows, StakeDiffAlpha
    RAF = RetargetAdjustmentFactor
    if parent.height < CoinbaseMaturity + 1:
        return MinimumStakeDiff
    old = parent.sbits
    if (parent.height + 1) % SW != 0:
        return old
    if old == 0:
        return 0                                # unreachable for valid chains

    # Pool-size estimate.
    target_pool = TicketsPerBlock * TicketPoolSize
    weighted_sum, weights = 0, 0
    for k in range(SN):
        b = back(parent, (k + 1) * SW - 1)
        skew = (b.pool_size - target_pool) * TicketPoolSizeWeight + target_pool
        if skew <= 0:
            skew = 1
        ratio = (skew << 32) // target_pool
        weighted_sum += ratio << ((SN - k) * ALPHA)
        weights += 1 << ((SN - k) * ALPHA)
    by_pool = int64(((weighted_sum // weights) * old) >> 32)
    by_pool = clamp_v1(old, by_pool)

    # Fresh-stake estimate.
    target_fresh = SW * TicketsPerBlock
    weighted_sum, weights = 0, 0
    for k in range(SN):
        fresh = 0
        for d in range(k * SW, (k + 1) * SW):
            fresh += back(parent, d).fresh_stake
        if fresh <= 0:
            fresh = 1
        ratio = (fresh << 32) // target_fresh
        weighted_sum += ratio << ((SN - k) * ALPHA)
        weights += 1 << ((SN - k) * ALPHA)
    by_fresh = int64(((weighted_sum // weights) * old) >> 32)
    by_fresh = clamp_v1(old, by_fresh)

    nxt = clamp_v1(old, merge(old, by_pool, by_fresh))
    if nxt < MinimumStakeDiff:
        return MinimumStakeDiff
    return nxt

def clamp_v1(old: int64, x: int64) -> int64:   # old > 0, x >= 0
    if x == 0:
        return old // RetargetAdjustmentFactor
    if x // old > RetargetAdjustmentFactor - 1:
        return old * RetargetAdjustmentFactor
    if old // x > RetargetAdjustmentFactor - 1:
        return old // RetargetAdjustmentFactor
    return x

def merge(old: int64, d1: int64, d2: int64) -> int64:   # all > 0
    a = (old << 32) // d1
    b = (d2 << 32) // old
    return int64((((b << 32) // a) * old) >> 32)

dcrd: internal/blockchain/difficulty.go · calcNextRequiredStakeDifficultyV1, mergeDifficulty

merge computes approximately 𝑑1𝑑2/old: the product of the two estimated change factors applied to the old price. All divisions in version 1 are of non-negative operands. The int64 conversions take the value modulo 264 as two’s complement; for every reachable input the values fit, so the conversion has no effect. (Wrapping requires a price far above the total supply. dcrd also evaluates clamp_v1 in 64-bit arithmetic, and the pseudocode above does not describe its results in that unreachable range, where the estimates can wrap to negative values.) The clamp conditions are integer comparisons of truncated quotients: x // old > RAF - 1 holds exactly when 𝑥≥RAF·old, and old // x > RAF - 1 exactly when old≥RAF·𝑥.

Implementation pitfall

The early return for old == 0 reproduces dcrd, which returns the (necessarily zero) pool-size estimate when the old price is zero. merge divides by d1, old and a; these are nonzero because a valid chain’s price is at least MinimumStakeDiff, which exceeds RetargetAdjustmentFactor on every network. dcrd would fail on a zero divisor rather than reject the block.
Test vector: Stake difficulty version 1, mainnet parameters

Chains of 5759 blocks in which every block has the stated PoolSize and FreshStake and SBits 5000000000; the result is the required SBits of block 5760.

PoolSizeFreshStakeResultComment
4096055000000000both estimates on target
4505656999999999skew =4096×4+40960: factor 1.4
3686452999999998factor 0.6
409602020000000000fresh estimate clamped to ×4
4096001250000000fresh estimate clamped to ÷4
001250000000
417791010799804684

merge(5000000000, 6000000000, 4000000000) =4799999998;
merge(200000000, 800000000, 800000000) =3200000000.

9.9.2 Version 2 (DCP-0001)

Version 2 adjusts the price in proportion to two ratios: the relative change of the pool size (including immature tickets) since the previous retarget, and the ratio of the current pool size to its target. With 𝑆 the current price, 𝑃𝑁 and 𝑃𝑁−1 the current and previous pool sizes including immature tickets, and 𝑇𝑃=TicketsPerBlock×(TicketPoolSize+TicketMaturity) (42240 on mainnet):

𝑆′=max(min(⌊𝑆·𝑃𝑁2𝑃𝑁−1·𝑇𝑃⌋,𝑆ub),𝑆lb)

(9.3)

where 𝑆lb= MinimumStakeDiff and 𝑆ub is an estimate of the total supply divided by TicketPoolSize. The normative computation, including the order in which the bounds are applied, is Algorithm 9.10.

The pool size including immature tickets “as of” a block 𝑏 is 𝑏.pool_size plus the FreshStake of 𝑏 and of its TicketMaturity −1 nearest ancestors (TicketMaturity blocks in total, fewer if the genesis block is reached). For a retarget block at height 𝐻, the current value is taken as of the parent (height 𝐻−1) and the previous value as of the block at height 𝐻−StakeDiffWindowSize−1, the parent of the previous retarget block. The PoolSize header field counts live tickets only and does not yet include tickets that mature in that very block (Chapter 8); the formula uses the header values as they are.

Algorithm 9.10 · Stake difficulty version 2

def next_sbits_v2(parent) -> int64:
    next_height = parent.height + 1
    if next_height < CoinbaseMaturity + 1:
        return MinimumStakeDiff
    cur = parent.sbits
    if next_height % StakeDiffWindowSize != 0:
        return cur

    prev_node = ancestor(parent, next_height - StakeDiffWindowSize - 1)
    prev_all = 0
    if prev_node is not None:
        prev_all = prev_node.pool_size + sum_fresh(prev_node, TicketMaturity)
    if prev_all == 0:
        return cur                     # avoids division by zero at start-up
    cur_all = parent.pool_size + sum_fresh(parent, TicketMaturity)

    target_all = TicketsPerBlock * (TicketPoolSize + TicketMaturity)
    nxt = int64((cur * cur_all * cur_all) // prev_all // target_all)
    maximum = estimate_supply(next_height) // TicketPoolSize
    if nxt > maximum:
        nxt = maximum
    if nxt < MinimumStakeDiff:
        nxt = MinimumStakeDiff
    return nxt

def sum_fresh(b, count: int) -> int:
    total = 0
    while b is not None and count > 0:
        total += b.fresh_stake
        b = b.parent
        count -= 1
    return total

def estimate_supply(height: int64) -> int64:
    if height <= 0:
        return 0
    I = SubsidyReductionInterval
    supply = BLOCK_ONE_SUBSIDY        # sum of the BlockOneLedger amounts
    subsidy = BaseSubsidy
    for _ in range(height // I):
        supply += I * subsidy
        subsidy = subsidy * MulSubsidy // DivSubsidy
    supply += (1 + height % I) * subsidy
    supply -= BaseSubsidy * 2         # blocks 0 and 1 were counted at full subsidy
    return supply

dcrd: internal/blockchain/difficulty.go · calcNextRequiredStakeDifficultyV2, calcNextStakeDiffV2, sumPurchasedTickets, estimateSupply

The numerator is formed first and divided by prev_all and then by target_all, each time with flooring; since all operands are non-negative this equals a single floored division by their product. The maximum is applied before the minimum, so when the supply-based maximum is below MinimumStakeDiff the minimum prevails. (DCP-0001 writes the bounds in the opposite nesting; the difference is unobservable on dcrd’s networks, where the maximum exceeds the minimum at every height at which a retarget can occur, and dcrd’s order is normative.) estimate_supply is evaluated at the height of the block being validated. It is a deliberately simplified model of issuance that assumes every block paid its full subsidy; it does not account for missing votes, disapproved blocks, or changes in the subsidy split, which do not alter the total block subsidy.

Implementation pitfall

The product cur * cur_all * cur_all can exceed 64 bits on realistic inputs (for example 2×1010×728452≈1020) and MUST be computed with wider arithmetic. The quotient is then converted to int64 modulo 264, as with version 1; it fits for every reachable input.
Test vector: Supply estimate, mainnet parameters
Heightestimate_supplyMaximum price (// 8192)
0 (and negative)00
116800000000000020507812500
216800311958266420508193308
409618077469100908022067223023
614318716047672228822846737881
614418716356541799422847114919
14924858363656941047571244698414
7943681569076628758532191537674409
Test vector: Stake difficulty version 2, mainnet parameters

A chain from dcrd’s tests: no purchases in blocks 1 to 256, then 20 ticket purchases in every block, with no votes before block 4096 and 5 per block from 4096. Each row is a retarget block; “prev” and “cur” are pool sizes and immature counts as defined above.

HeightParent SBitsPrev poolPrev imm.Cur poolCur imm.Result
2304200000000329205120358005120208418769
2448208418769358005120386805120231326567
2592231326567386805120415605120272451490
345613549896695596051205884051202148473276
40321094754737967480512070360512020338554623
41762033855462370360512072845512022097687698

For example, at height 2304: prev_all=32920+5120=38040 and cur_all=35800+5120=40920; 200000000·409202=334889280000000000; divided by 38040 this gives 8803608832807, and divided by 42240 it gives 208418769, which is within the bounds. The last row (height 4176) is the only one that is clamped to the maximum: the unclamped value 38776057578 exceeds the estimated supply divided by the target pool size, 22097687698.

Note

dcrd also provides an estimate of the next stake difficulty for wallets, which simulates the remaining blocks of the interval under assumed purchase counts. It is not part of consensus.

9.10 Summary of Header Rules

For every block other than the genesis block:

  1. Bits decodes to a target in [1,PowLimit] (Rule 9.1).
  2. The proof-of-work hash selected by blake3pow does not exceed the target (Rule 9.2).
  3. Bits equals the required bits computed from the parent chain and the block’s timestamp by the EMA algorithm or ASERT (Rule 9.3).
  4. SBits equals the required stake difficulty computed from the parent chain by version 1 or version 2 (Rule 9.6).
  5. Every ticket purchase pays at least SBits and at least MinimumStakeDiff (Rule 8.6).
  6. On testnet3 only: Rule 9.4 and Rule 9.5.