/consensus-safety-invariants

name: "consensus-safety-invariants"
description: "L1 trigger - detects non-determinism, state transition completeness violations, and safety/liveness invariant breaks in consensus code. Inject into depth-consensus-invariant or depth-state-trace."

Injectable Skill: Consensus Safety Invariants

> **L1 trigger**: `L1_PATTERN=true` AND (`consensus/` OR `state_transition/` OR `fork_choice/` OR `beacon_chain/` detected in recon subsystem map) > **Inject Into**: `depth-consensus-invariant` (primary) or `depth-state-trace` (fallback) > **Language**: Go and Rust (language-specific examples embedded) > **Finding prefix**: `[CS-N]` (consensus-safety) > **Status**: v0.1 draft, Round 4 exemplars pending

Orchestrator Decomposition Guide

Map sections to the assigned depth agent:

• Sections 1, 2: depth-consensus-invariant (determinism + invariants)
• Sections 3, 4: depth-state-trace (state transition completeness)
• Section 5: depth-edge-case (boundary conditions)
• Section 6: depth-external (cross-client consistency)

When This Skill Activates

Recon sets `L1_PATTERN=true` and identifies a consensus subsystem in the target. This skill attaches to agents auditing that subsystem. It is the single most load-bearing L1 skill — consensus bugs are Critical tier by default.

1. Non-Determinism Sources

A consensus implementation is non-deterministic if two honest nodes processing the same input can reach different output states. Each of the following is a production-bug class:

1a. Map iteration order

In Go, `for k, v := range m` visits keys in an **unspecified order**. In Rust, `HashMap` iteration order varies between runs (non-deterministic by default; `BTreeMap` is ordered).

**Check**: For every consensus-critical function, enumerate every map iteration. For each:

• Is the iteration result used to compute state that other nodes must agree on? If yes → non-determinism bug.
• Is there a deterministic sort (`sort.Strings(keys)` in Go; `BTreeMap` or explicit `.sort()` in Rust) before iteration?

**Known exemplar class**: Cosmos SDK Dragonberry/Elderflower (2022) involved IAVL tree iteration that became load-bearing for proof generation.

Tag: `[NON-DET:map-iter:{file}:{line} → {consumer}]`

1b. Node-local timestamps

`time.Now()`, `std::time::SystemTime::now()`, system clocks, file mtimes — any value that differs across nodes at the same block height.

**Check**: Grep/ast-grep for time sources. For each hit, trace forward: does the value enter consensus state?

• Block proposer timestamps are intentional (part of the block) — OK.
• Validator vote timestamps that affect scoring — check if rounded to epoch boundary.
• Timeouts for P2P operations — OK if used locally only.

Tag: `[NON-DET:wall-clock:{source} → {consumer}]`

1c. Floating-point math

**Rule**: floating-point arithmetic in consensus-reachable code paths is a CRITICAL-default finding. There are no portable, toolchain-stable, and SIMD-safe FP operations in production node-client code. "But we compiled with strict FP" is not a defense — the risk surface is compiler version, LLVM backend, target triple, feature flags, and the standard library implementation of transcendental functions, any of which can change across releases.

**Known exemplars**:

1. **Polkadot 2021-05-24 toolchain-driven divergence** — a consensus path used a Rust stdlib routine whose implementation differed between stable Rust 1.51 and nightly (same source, different generated code after an stdlib change). Two honest validators, both running the same source, produced different state because one had upgraded toolchain. Fix was twofold: ban FP in consensus code AND migrate affected logic to deterministic fixed-point. This is the canonical evidence that "identical source compiles identically" is false on FP paths.

2. **Cosmos SDK #7773 / #15381** — FP in fee / reward math produced validator-to-validator divergence in testnet replays; the fix ([#15381](https://github.com/cosmos/cosmos-sdk/issues/15381)) explicitly removed FP from the state machine and added lints to prevent regressions. SDK `defensive_programming` guidance now forbids FP in state-machine code, not just "discourages."

3. **Parity Ethereum #6511** — early Parity discussion documenting why the Yellow Paper has no FP opcodes: structural ban, not stylistic. Any FP introduced by a precompile or host function wrapping a native FP op recreates the same risk.

4. **EVM Yellow Paper** — the bytecode has ZERO FP opcodes by design. Protocols that introduce FP via precompiles, host functions, or a custom VM extend the risk surface of their client beyond the spec.

**Check**:

1. Grep for `float64`, `f64`, `f32`, `FloatingPointValue`, and native transcendentals (`.sin()`, `.exp()`, `.ln()`, `.pow()`) in every consensus-reachable module. 2. Grep for `#![allow(clippy::float_arithmetic)]` or the absence of `#![forbid(clippy::float_arithmetic)]` at the crate root for Rust consensus crates. The absence of `forbid` is itself a finding for any crate that participates in state transitions. 3. For each hit, trace forward: does the value enter the state root, a hash input, a signed-over payload, vote weight, gas accounting, or a cross-validator comparison? If yes → CRITICAL-default. 4. "Only used for metrics / local logging / display" is an acceptable defense ONLY if the value never leaves the process. Prometheus metrics are OK; anything written to disk that gets hashed or compared across nodes is NOT.

**Severity**: Consensus-reachable FP is CRITICAL-default. Non-consensus FP (telemetry, RPC display) is Informational. Absent `forbid` lint on a consensus crate is Low (defense-in-depth).

Tag: `[NON-DET:float:{op}:{file}:{line}]` — upgrade to `[NON-DET:float:CRITICAL:{op}:{file}:{line}]` when the value reaches state root / hash input / signed payload.

1d. Iteration over Go goroutine-produced data

Channels, select statements wi