feat(docs): severity-axis figures + security checklist & unit/e2e test plan

- fig11 (subsystem×severity and root_cause×severity heatmaps) and fig10 (3D
  subsystem×severity bars) answer "by severity, which areas/causes are heavy vs
  light"; wired into analysis.md §7.
- docs/checklist.md: a prioritized security checklist built from the inline
  fixes — per-subsystem review items (each citing a real fix) plus a unit/e2e
  test matrix, ordered by impact (consensus/value core first, then availability),
  closing with cross-client differential/adversarial-devnet tests.
- Linked from the audit guide's playbook and the README docs index.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

Author: grandchildrice

README.md

@@ -219,6 +219,7 @@ docs/            BUILD_REPORT · IMPROVEMENT_LOG · silent_fix_detection · mode
 ## Documentation
 
 - [`docs/security_report.md`](docs/security_report.md) — 🔎 **Auditing Ethereum clients: where the bugs actually live** — a field guide for client devs, audit firms, and white-hats: where to look, the six recurring bug patterns, the attack surface, and the cross-implementation variant hunting that turns one client's fix into a lead on another's live bug
+- [`docs/checklist.md`](docs/checklist.md) — ✅ **Security checklist & test plan** — per-subsystem review items and unit/e2e tests derived from the actual fixes, ordered by impact
 - [`docs/analysis.md`](docs/analysis.md) — **what the data says** (silent-fix majority, availability-first vuln profile, cross-language diversity), read through the dataset-research literature
 - [`docs/limitations.md`](docs/limitations.md) — **honest inventory of coverage gaps & caveats** (read before relying on the data)
 - [`docs/severity_labeling.md`](docs/severity_labeling.md) — **methodology**: LLM severity estimation against the bug-bounty model (decompose → map → calibrate)

docs/analysis.md

@@ -137,6 +137,19 @@ publish advisories more than which clients are safer, and fix size does not trac
 severity (median 51 vs 45 LOC), so neither is a shortcut to finding the severe
 bugs.
 
+Adding the severity axis to the breakdowns answers the practical question — *by
+severity, which areas and causes are heavy, and which are light.*
+
+![Fixes by subsystem and root cause, split by severity](figures/fig11_severity_heatmap.png)
+
+High-severity fixes cluster where the impact model predicts: the state trie, p2p,
+sync, and fork-choice by subsystem; `missing_input_validation`,
+`resource_exhaustion`, `integer_overflow`, and `consensus_divergence` by cause.
+The state trie is dominated by Medium, p2p carries a relatively high share of High.
+(The same data as a 3D bar chart is `figures/fig10_severity_3d.png` — striking,
+but the heatmap reads exact counts better.) This view drives the prioritized
+[security checklist & test plan](./checklist.md).
+
 ## 8. Data quality and coverage
 
 ![Figure 6](figures/fig6_coverage.png)

docs/checklist.md

@@ -0,0 +1,181 @@
+# Ethereum client security checklist & test plan
+
+A working checklist for auditing or hardening an Ethereum client, built by reading
+the actual fixes in this corpus and keeping the ones that recur. Items are ordered
+by impact: the consensus and value core first (a bug there splits the chain or
+moves ETH), then the availability surface (a bug there drops the node). Each item
+names a real fix that motivates it and how to test it.
+
+Use it two ways: as a review checklist against an implementation, and as a test
+matrix — the *unit* column is what to fuzz or property-test in isolation, the
+*e2e* column is what to exercise on a multi-client devnet.
+
+![Where the severe bugs cluster](figures/fig11_severity_heatmap.png)
+
+The heatmap is the quick orientation: `missing_input_validation`,
+`resource_exhaustion`, `integer_overflow`, and `consensus_divergence` carry the
+most High-severity fixes, and they land hardest in the state trie, p2p, sync,
+fork-choice, and the beacon-chain state transition.
+
+---
+
+## Tier 1 — Consensus & value core
+
+A wrong result here is a chain split or forged value. Read this code line by line.
+
+### EVM, opcodes & precompiles
+
+- [ ] **Every opcode handles boundary operands** (zero, max, oversized shift) with
+  the spec's result and no native exception. *(besu: SHL/SHR/SAR native exception
+  at key values; geth: RETURNDATA corruption via `datacopy`)*
+- [ ] **Gas accounting matches the spec exactly**, with no signed/unsigned or
+  overflow slip. *(besu: Gas allocation error in CALL — Critical; geth: DoS via
+  `MulMod`)*
+- [ ] **Return-data and memory buffers are bounds-checked before any copy.**
+  *(geth: RETURNDATA corruption via `datacopy`)*
+- [ ] **Precompiles copy, not alias, their inputs/outputs.** *(geth: shallow copy
+  in the 0x4 precompile)*
+
+  | | test |
+  |---|---|
+  | **unit** | differential opcode/precompile tests vs the reference spec (EELS) over boundary operands; property-test gas math for overflow; fuzz each opcode's stack inputs |
+  | **e2e** | official state tests + blockchain tests; execute a block of adversarial opcodes across all clients on a devnet and compare state roots |
+
+### State-transition arithmetic (gas, balance, stake, slots)
+
+- [ ] **All balance / gas / stake / slot arithmetic is overflow- and
+  underflow-checked**, including empty-collection edge cases. *(lighthouse: Eth1
+  data underflow; underflow in `verify_transfer`; underflow in shuffle with an
+  empty list)*
+
+  | | test |
+  |---|---|
+  | **unit** | property/fuzz tests asserting no under/overflow on extreme and empty inputs |
+  | **e2e** | process adversarial blocks and states on a devnet; assert no panic and cross-client agreement |
+
+### Fork-choice
+
+- [ ] **Graph traversals are bounded** — no O(n²) `find_head`, no unbounded
+  recursion or stack growth. *(lighthouse: O(n²) `find_head` and stack overflow in
+  `filter_block_tree`)*
+- [ ] **Zero/null block hashes and missing parents are handled, not assumed.**
+  *(lighthouse: avoid 0x00 block hashes in `forkchoiceUpdated`)*
+- [ ] **Message timing cannot bias the head** (proposer boost, late/early
+  attestations). *(lighthouse: fork-choice timing attack)*
+
+  | | test |
+  |---|---|
+  | **unit** | fork-choice tests with crafted block trees, equivocations, zero hashes, deep chains |
+  | **e2e** | devnet reorg scenarios; proposer-boost edge cases; delayed and duplicated messages |
+
+### State trie & snapshots
+
+- [ ] **Trie/snapshot code returns errors instead of panicking** on malformed or
+  short nodes. *(geth: stacktrie explicit errors instead of panic; snapshot unlock
+  before return/panic)*
+- [ ] **Concurrent access to layers/snapshots is race-free.** *(geth: race
+  condition on `diffLayer`)*
+
+  | | test |
+  |---|---|
+  | **unit** | feed malformed/truncated trie nodes; run the race detector over concurrent layer ops |
+  | **e2e** | snap-sync from an adversarial peer serving crafted state |
+
+### Crypto & KZG
+
+- [ ] **Curve points, signatures, and proofs are validated** (on-curve, subgroup,
+  length) before use, and parsing never panics. *(geth: invalid-curve DoS in
+  secp256k1)*
+- [ ] **No `expect`/`unwrap`/assert on attacker-supplied crypto input.**
+  *(lighthouse: remove `expect` in `kzg_utils`)*
+
+  | | test |
+  |---|---|
+  | **unit** | fuzz signature/point/proof parsers with invalid and boundary inputs |
+  | **e2e** | gossip invalid BLS signatures and KZG proofs on a devnet; the node must reject them, not crash |
+
+---
+
+## Tier 2 — Availability surface
+
+A bug here is a remote denial of service. Audit for bounds on anything a peer can
+control.
+
+### p2p & discovery
+
+- [ ] **Every length/count field from a peer is bounded** before allocation or
+  iteration. *(pattern P1: LES `GetProofsV2` DoS; malicious snap/1 request)*
+- [ ] **Decode paths never panic** on malformed messages. *(geth: p2p/discover
+  crash in `Resolve`; les panic)*
+
+  | | test |
+  |---|---|
+  | **unit** | fuzz every wire-message decoder; assert allocation stays bounded relative to declared sizes |
+  | **e2e** | flood a node with malformed and oversized gossip/request messages; memory and CPU must stay bounded |
+
+### Sync
+
+- [ ] **Downloader concurrency is correct** — no nil, mutex, or timeout-
+  resurrection panics under failure. *(geth: timeout resurrection panic; mutex
+  regression panics; nil panic from wrong variable)*
+
+  | | test |
+  |---|---|
+  | **unit** | race detector plus fault injection on the downloader queue |
+  | **e2e** | sync against a peer that stalls, reorders, or withholds responses |
+
+### RPC
+
+- [ ] **Request parameters are validated and result sizes are bounded** — no
+  unbounded proof or range queries. *(reth: trie-proof edge cases; LES
+  `GetProofsV2` DoS)*
+
+  | | test |
+  |---|---|
+  | **unit** | fuzz RPC param decoding; assert response-size limits |
+  | **e2e** | hammer the RPC with expensive/oversized queries; rate and size limits must hold |
+
+### Transaction pool
+
+- [ ] **Malformed and edge-case transactions are rejected without panic** (bad
+  signature length, bad sender). *(geth: panic on invalid signature length; panic
+  on bad tx sender; nil statedb panic in `applyTransaction`)*
+
+  | | test |
+  |---|---|
+  | **unit** | fuzz tx decoding and validation |
+  | **e2e** | submit adversarial transaction streams; the pool must stay healthy |
+
+### Beacon-chain queues (attestation / block / slasher)
+
+- [ ] **Per-peer queues are memory-bounded** and cannot be grown without limit.
+  *(lighthouse: reprocess-queue memory leak; slasher OOM)*
+
+  | | test |
+  |---|---|
+  | **unit** | queue-bound tests under flood |
+  | **e2e** | gossip flood of attestations and blocks; memory must stay bounded |
+
+---
+
+## The highest-value tests: cross-client conformance
+
+The bugs unique to this ecosystem live *between* implementations, so the tests
+that find them run more than one client at once.
+
+- [ ] **Differential testing.** Feed identical EVM, SSZ, and epoch-processing
+  inputs to every client and diff the output. Any disagreement is a candidate
+  chain split.
+- [ ] **Adversarial devnet.** Run a mixed-client network with one malicious peer
+  driving the P1–P6 patterns: malformed gossip, oversized requests, equivocations,
+  crafted reorgs, boundary-value transactions. Assert liveness, bounded resources,
+  and a single canonical head.
+- [ ] **Spec-divergence fuzzing.** Mutate consensus-critical inputs (opcode
+  operands, precompile inputs, SSZ containers) and cross-check every client against
+  the reference spec.
+
+---
+
+*Sources: every checklist item traces to one or more fixes in
+`data/ethereum_vulns.parquet` (filter by `label` and `root_cause`); the patterns
+P1–P6 and the priority map are in [`security_report.md`](./security_report.md).*

docs/figures/fig10_severity_3d.png

@@ -183,6 +183,9 @@ in the consensus path, which is what turned an off-by-something into a Critical.
    present in one and missing in another is a candidate.
 5. Rank what you find by the damage one packet or transaction could do.
 
+Working from these patterns as concrete, per-subsystem review items and tests?
+See the [security checklist & test plan](./checklist.md).
+
 ## Caveats and disclosure
 
 Labels are model- and heuristic-derived (about 0.90 precision), not hand-verified.

docs/figures/fig11_severity_heatmap.png

@@ -186,3 +186,47 @@ def impact_class(a):
           loc="lower right",frameon=False,fontsize=8.5)
 plt.tight_layout(); plt.savefig(f"{FG}/fig9_priority_map.png",bbox_inches="tight"); plt.close()
 print("fig9 written")
+
+# ---- FIG 10: 3D — subsystem × severity × count -----------------------------
+from mpl_toolkits.mplot3d import Axes3D  # noqa
+se=d.severity_estimated.fillna("")
+d['_tier']=se.where(se.isin(['Critical','High','Medium','Low']),'—')
+TIERS=['Low','Medium','High','Critical']
+TCOL={'Low':TEAL,'Medium':ORANGE,'High':RED,'Critical':'#7b1fa2'}
+skip={'other','build-ci','test','cli','metrics-observability','docs'}
+subs=[a for a in d.label.value_counts().index if a not in skip][:12][::-1]
+fig=plt.figure(figsize=(11,6.6)); ax=fig.add_subplot(111,projection='3d')
+for yi,t in enumerate(TIERS):
+    zs=[int(((d.label==s)&(d._tier==t)).sum()) for s in subs]
+    xs=np.arange(len(subs))
+    ax.bar3d(xs, np.full(len(subs),yi), np.zeros(len(subs)), 0.7, 0.55, zs,
+             color=TCOL[t], shade=True, alpha=0.92)
+ax.set_xticks(np.arange(len(subs))+0.35); ax.set_xticklabels(subs,rotation=40,ha='right',fontsize=7.5)
+ax.set_yticks(np.arange(len(TIERS))+0.25); ax.set_yticklabels(TIERS,fontsize=8.5)
+ax.set_zlabel("fixes",fontsize=9)
+ax.set_title("Fixes by subsystem × severity  (severity incl. estimated)",fontsize=12.5,color=INK,fontweight="bold")
+ax.view_init(elev=22,azim=-58); ax.set_box_aspect((2.0,1.0,0.8))
+plt.tight_layout(); plt.savefig(f"{FG}/fig10_severity_3d.png",bbox_inches="tight"); plt.close()
+
+# ---- FIG 11: heatmaps — subsystem×severity and root_cause×severity ---------
+def heat(ax,rows,rowlab,title):
+    M=np.array([[int(((idx==r)&(d._tier==t)).sum()) for t in TIERS] for r in rows])
+    im=ax.imshow(M,cmap="YlOrRd",aspect="auto")
+    ax.set_xticks(range(len(TIERS))); ax.set_xticklabels(TIERS,fontsize=9)
+    ax.set_yticks(range(len(rows))); ax.set_yticklabels(rowlab,fontsize=9)
+    for i in range(len(rows)):
+        for j in range(len(TIERS)):
+            v=M[i,j]
+            if v: ax.text(j,i,v,ha="center",va="center",fontsize=8,
+                          color="white" if v>M.max()*0.55 else "#333")
+    ax.set_title(title,loc="left",fontsize=12,color=INK,fontweight="bold")
+    ax.grid(False)
+    return im
+subs2=[a for a in d.label.value_counts().index if a not in skip][:12]
+rcs=[c for c in d.root_cause.value_counts().head(9).index if c!='other'][:8]
+fig,(a1,a2)=plt.subplots(1,2,figsize=(12,5.2))
+idx=d.label; heat(a1,subs2,subs2,"(a) subsystem × severity")
+idx=d.root_cause; im=heat(a2,rcs,[r.replace('_',' ') for r in rcs],"(b) root cause × severity")
+fig.colorbar(im,ax=a2,fraction=0.046,pad=0.04,label="fixes")
+plt.tight_layout(); plt.savefig(f"{FG}/fig11_severity_heatmap.png",bbox_inches="tight"); plt.close()
+print("fig10, fig11 written")