plamentsv / consensus-math-correctness

Injectable Skill: Consensus Math Correctness

L1 trigger: CONSENSUS flag AND (adjust_difficulty OR difficulty_adjust OR ema OR moving_average OR reward_curve OR target_time detected)
Inject Into: depth-consensus-invariant or depth-edge-case
Language: Go and Rust
Finding prefix: [CM-N]

Consensus math bugs are small, deterministic, and load-bearing. They rarely need
fancy exploit chains: one wrong operator, one dead bound, or one flipped EMA
direction can permanently skew the chain.

1. Division-before-multiplication

For every expression of the form (A / B) * C, test whether A < B is
possible. If so, the intermediate division truncates to zero before the
multiplication and the protocol silently loses precision.

Questions:

1. Can A < B happen at runtime?
2. Is the intended formula mathematically (A * C) / B?

3. If multiplication moves first, is there an overflow guard on the wider
   intermediate?

Tag: [CONSENSUS-MATH:DIV-FIRST]

2. Declared-but-unapplied bounds

Consensus configs often declare bounds that never influence runtime math.

Questions:

1. Which config fields look like bounds or caps? Example names:
   max_difficulty_adjustment_factor, min_reward, max_step_count.

2. Is each field used only during config parsing, or also in the live
   computation?

3. If a field is declared but never applied at runtime, what unbounded state
   transition does that permit?

Tag: [CONSENSUS-MATH:UNUSED-BOUND]

3. EMA / moving-average direction

For each moving-average implementation, identify the prior sample, current
sample, and smoothing factor.

Questions:

1. Does the code use the same sample ordering as the design doc or comments?

2. Is the "previous" state actually previous, or has the implementation swapped
   current and prior inputs?

3. If the direction is flipped, does the chain overreact instead of smoothing?

Tag: [CONSENSUS-MATH:EMA-DIRECTION]

4. Threshold operators

Consensus edge cases often live at threshold-1, threshold, and
threshold+1.

Questions:

1. For every > / >= / < / <= gate in consensus math, what does the
   protocol text say should happen exactly at the threshold?

2. Does the implementation match that boundary?
3. What happens at threshold-1, threshold, and threshold+1?

Tag: [CONSENSUS-MATH:BOUNDARY-OP]

5. Ratio / fixed-point edge vectors

Difficulty and reward math often expresses "increase/decrease by X%" using
integer ratios or fixed-point factors. Enumerate the exact vectors:

Mandatory checks:

1. If a config field is named max_*_adjustment_factor, prove it clamps both
   upward and downward movement at runtime.

2. Test the exact human-readable boundary from docs/comments, not only random
   samples. If docs say "up to 50% decrease," test exactly 50%.

3. Check whether integer truncation prevents the boundary from ever being
   reached.

4. Check > vs >= at every clamp boundary.

Tag: [CONSENSUS-MATH:RATIO-EDGE]

6. Consensus floating point / platform dependence

If consensus math uses f32, f64, log, log10, pow, platform C math,
SIMD, CUDA, or FFI:

1. Determine whether the result affects any value that other nodes must agree
   on.

2. Check cross-platform determinism: Linux vs Windows, CPU vs GPU, feature
   flags, and architecture word size.

3. If a floating-point result is cast back into integer consensus state, emit a
   finding unless the implementation proves deterministic rounding.

Tag: [CONSENSUS-MATH:NONDET-FP]

Output guidance

• Preferred evidence tags: [CONFORMANCE-PASS] > [NON-DET-PASS] >
  [LSP-TRACE] > [CODE-TRACE]

• Severity baseline: Medium, upgrade when the math directly affects consensus
  safety, liveness, or issuance economics

Known class references

1. Consensus clients and SDKs have repeatedly removed floating-point or
   precision-sensitive arithmetic from state-machine code after divergence
   incidents.

2. Difficulty-adjustment and reward-curve bugs are historically dominated by
   truncation, unused bounds, and edge-threshold mistakes rather than complex
   exploit logic.