Difficulty adjustment
Protocol and consensus12.4.15+

Difficulty adjustment

How Lotus sets the target of every block with ASERT: the formula, the constants of each network, and the integer algorithm.

Lotus adjusts the difficulty at every block with ASERT, an exponential rule that compares the chain with an ideal schedule of one block every 2 minutes. The rule has been in force since the first block: there is no older algorithm to implement.

The rule #

Text
next_target = anchor_target x 2^( (time_delta - 120 x (height_delta + 1)) / half_life )

For the block that follows a parent block P:

TermValue
anchor_targetThe target of block 1. Block 1 always gets the easiest target allowed (the proof-of-work limit).
time_deltaTimestamp of P minus the timestamp of the genesis block (the anchor's parent), in seconds.
height_deltaHeight of P minus 1 (the anchor's height).
120Target block spacing in seconds.
half_life172,800 seconds (2 days) on mainnet.

When the chain is exactly on schedule the exponent is 0 and the target equals the anchor target. For every half_life seconds the chain is behind schedule the target doubles (difficulty halves); for every half_life seconds ahead it halves.

The target only depends on the parent's height and timestamp and on the fixed anchor, so no error accumulates from block to block.

Constants per network #

MainnetTestnetRegtest
Target spacing120 s120 s120 s
Half-life172,800 s172,800 sno retargeting
Proof-of-work limit (nBits)0x1c1000000x1d00ffff0x207fffff
Minimum-difficulty blocksnoyesyes

On regtest every block keeps its parent's nBits.

On networks that allow minimum-difficulty blocks, a block whose timestamp is more than 240 seconds (two target spacings) after its parent's may use the proof-of-work limit.

Integer algorithm #

The node computes 2^x with 16-bit fixed-point arithmetic and a cubic approximation, so that every implementation gets the same nBits. In pseudocode, with integer arithmetic throughout:

Text
exponent = ((time_delta - 120 * (height_delta + 1)) * 65536) / half_life
shifts   = exponent >> 16                  # arithmetic shift, rounds down
frac     = exponent & 0xffff               # 0 .. 65535

factor = 65536 + ((195766423245049 * frac
                 + 971821376 * frac^2
                 + 5127 * frac^3
                 + 2^47) >> 48)

next_target = anchor_target * factor
shifts = shifts - 16
if shifts <= 0:  next_target = next_target >> -shifts
else:            next_target = next_target << shifts   # on overflow: pow_limit

if next_target == 0:        next_target = 1
if next_target > pow_limit: next_target = pow_limit
next_bits = compact(next_target)

Notes for implementers:

  • The division by half_life is the C++ integer division of two signed 64-bit values.
  • shifts uses an arithmetic right shift, so it rounds toward minus infinity, and frac is the low 16 bits of exponent: exponent == shifts * 65536 + frac always holds.
  • factor approximates 65536 x 2^(frac / 65536).
  • next_target is a 256-bit unsigned integer. The proof-of-work limit is below 2^224, which leaves room for the multiplication by factor.
  • The header must carry exactly the compact value this gives. Any other nBits is rejected with bad-diffbits.

Proof of work #

A block is valid when its block hash, read as a 256-bit number, is not above the target encoded in nBits, and the target is not above the proof-of-work limit. A block may instead carry a merged-mining proof where the rules allow it; see Merged mining.

The target also sets the reward of the block. See Block subsidy.

Napoleon upgrade

Napoleon does not change the difficulty adjustment on mainnet: the same rule, anchored at block 1 with a 2-day half-life, governs every block before and after the activation. Blocks found by merged mining and by GPUs share this one difficulty.

Test networks after merged mining v2 #

On testnet, regtest and the Napoleon testnet, blocks use a second ASERT track once merged mining v2 is active: the same formula with a half-life of 7,200 seconds (2 hours), anchored at the first block whose median time past reached the activation time, so the difficulty does not jump at the switch. Mainnet does not use this track.

Read the difficulty #

Shell
curl -s http://127.0.0.1:10604/api/v1/chain
Source share/www/docs/difficulty.md in the lotusd repository
Checked against src/pow/pow.cpp src/pow/aserti32d.cpp src/chainparams.cpp