# Limenka Difficulty Adjustment Algorithm

The fork replaces Bitcoin's 2016-block retarget with a continuous
single-lane PI difficulty controller that activates at the fork gate and
runs for every fork-era block.  Everything below is per-block, no
windows.

## Activation

- The DAA takes over from the parent chain's retarget at the fork gate:
  `MTP(pindexPrev) + nForkActivationBias >= nForkActivationMTP`.
- `nForkActivationMTP = 1792328400` (2026-10-18 09:00 EDT).
- `nForkActivationBias = 30000` seconds: the MTP-101 median sits ~50
  blocks back, so the bias compensates the lag and activation lands near
  the intended wall time (handoff sim: ~1.7h lag vs 6-8h unbiased).
- `nForkMTPWindow = 101`: the median window used by the gate.
- The powLimit is NOT reset at activation - the fork continues the
  parent chain's difficulty without a jump.

## Measurement

- `e = block.nTime - prev_block.nTime`, floored at 1 second (the direct
  stamp delta, not a window average).
- Fork block stamps are capped ahead of wall time:
  `nTime <= now + 60s` (`nForkFutureLimit`).

## PI controller (asymmetric)

- Setpoint: `nForkIntervalTarget = 617` seconds.  It is calibrated above
  600 because the asymmetric integral rectifies: fast blocks get a small
  correction (slow to raise), slow blocks get a large one (fast to
  lower), so the naive 600 setpoint would land long-term above 600.
  With 617 the steady-state mean measures 601.1s over 10 seeds.
- Error: `error = 617 - e` (positive = blocks too fast).
- P term (proportional) acts on the instantaneous error:
  `kp = 10,000,000`.
- I term (integral) acts on an EMA accumulator of the error:
  `avg = 0.95 * avg + 0.05 * error` (`alpha = 0.05`).
  Asymmetric gains: `ki_up = 5,000,000` when the chain is fast (raise
  slowly, flood-proof), `ki_down = 50,000,000` when slow (lower fast,
  quick restore) - a 10x asymmetry.
- No D term: measured dead on a single-sample exponential measurement -
  SNR 1, and the derivative carries 3-5x more noise than signal.
- Correction and new target (scale = 1e6):

      correction = (ki * avg + kp * error) / 1e6
      denom      = clamp(1e6 + correction, 1e5, 1e7)
      target     = prev_target * 1e6 / denom

  The denominator clamp bounds any single block's difficulty change to a
  factor of 10 up or down.

## State and persistence

- Per-block state: `nForkTarget` (the running target),
  `nForkAvgError` (the EMA accumulator), `nForkLastBlockTime` (the
  previous fork block's stamp), and `nForkAggregateSeconds` (the halving
  counter, below).
- First fork block: the state seeds from the parent chain's difficulty
  (no reset), the first interval is assumed to be the 617s setpoint, and
  the EMA starts at zero.
- The state is persisted in `CDiskBlockIndex` (format v259901).  When it
  is missing (headers-first sync, restart with an older index, freshly
  loaded blocks) it is recomputed deterministically from the activation
  point and memoized on the entries - the validity function is identical
  for an uptime node, a restarted node, and a fresh sync.

## Time-proportional block weight

- Fork blocks carry a time-proportional payload limit instead of the
  fixed 4 MW cap:

      payload_limit = S_max * e / 600

  where S_max is the 4 MW block budget, and the header plus coinbase are
  subtracted by the caller.  A late block clears the backlog accumulated
  during a stall; a fast block carries less.
- The segwit witness discount is removed on the fork: weight is the raw
  serialized size, so the cap and the fee market price bytes honestly.

## Time-proportional subsidy

- The coinbase subsidy is also time-proportional:

      halvings = nForkAggregateSeconds / (600 * 210000)
      subsidy  = (50 COIN >> halvings) * e / 600

  The shift is capped at 63 (past that the subsidy is zero) so the shift
  is never undefined behavior.
- `nForkAggregateSeconds` advances by the actual elapsed `e` per block
  (time-anchored halving tracks wall clock).  At the activation boundary
  it seeds from `height * 600` so the fork continues the parent chain's
  halving schedule instead of restarting at 50 COIN.
- Same expression on both sides: the miner assembles its reward with the
  identical `e` the consensus checks, including the floor at 1.

## Sim-validated behavior

- 1000x/2h hashpower flood: target damage 2.5-2.7x, restore 7-12h.
- Miner collapse (hashpower vanishes): recovery 8.6-10.1h.
- 3% asymmetric-integral rectification dilation is canceled by the 617s
  setpoint.
- Steady-state cadence across 10 seeds: 601.1s mean.

## Related fork machinery (not part of the DAA)

- The sequential delay (division-free Barrett long division, 2^33 steps,
  ~60s on reference hardware, committed in the coinbase) is a separate
  per-block consensus feature.  It cannot be precomputed, so it
  indirectly disciplines cadence by making every fork block cost its
  miner a fixed sequential 60 seconds.
- `-forkmineondemand` (test mode) sets `fPowNoRetargeting`: fixed
  powLimit, no DAA - used by the functional tests and testnet bootstrap.