docs: add explanation of LMD-GHOST and 3SF-mini

[MegaRedHand]

This PR adds documentation about LMD-GHOST and 3SF-mini to the repo.

TODOs:

• Review LMD-GHOST doc
• Explain how 3SF-mini differs from Casper FFG
• Further refine 3SF-mini doc

[github-actions]

🤖 Kimi Code Review

Documentation Review – PR #128

Overall: Excellent, comprehensive documentation that clearly explains 3SF-mini and LMD-GHOST. No critical issues, only minor suggestions.

3sf_mini.md

• Line 42: The formula 3 × vote_count ≥ 2 × validator_count is correct but could be simplified to vote_count ≥ 2/3 * validator_count for clarity.
• Line 46-50: The attestation validity checks list is missing the requirement that the attestation's slot must be ≤ current slot (anti-future-slot protection).
• Line 74: The table shows delta=36 as "2+3" but it's actually just Rule 2 (6²) since 36 isn't a pronic number (n(n+1)=36 has no integer solution).

ghost-fork-choice.md

• Line 45: "finalized a slot" → should be "finalize a slot".
• Line 183: The tiebreaker description says "lexicographically highest block root" but the actual implementation in compute_lmd_ghost_head uses the lower hash (see min_by_key(|root| *root)). The docs should match the code.
• Line 234: The attestation pipeline diagram shows promotion happening at intervals 0 and 3, but the text says "once per slot, twice" - this is slightly confusing since it's twice per slot (intervals 0 and 3).
• Line 486: The performance table lists O(A × D) for weight accumulation but doesn't mention that this could be optimized to O(A + D) with proper indexing (though this is noted as future work with proto-array).

3sf-mini-infographic.html

• Line 768: The JavaScript isJustifiable function correctly implements the rules, but the tooltip for delta=36 shows "n² (6²)" which is accurate - the table in 3sf_mini.md is the one that's slightly misleading.

Security Considerations

No security issues identified in the documentation itself. The clear explanation of the justifiability schedule and finalization conditions is crucial for consensus correctness and appears accurate.

Suggestions

1. Consider adding a brief note about how the justifiability rules ensure the schedule is infinite (no maximum delta) while maintaining the backoff property.
2. The infographic could benefit from a mobile-friendly view of the LMD-GHOST SVG diagram - it's currently quite wide.

Conclusion: The documentation is high-quality and accurate. The minor issues noted above don't affect consensus correctness.

---

Automated review by Kimi (Moonshot AI) · custom prompt

[github-actions]

🤖 Claude Code Review

Now I have enough context. This is a documentation-only PR that adds comprehensive explanations of LMD-GHOST and 3SF-mini. Let me provide my review:

---

PR Review: Documentation of LMD-GHOST and 3SF-mini

Summary

This PR adds extensive documentation explaining ethlambda's fork choice (LMD-GHOST) and finality (3SF-mini) mechanisms. The changes are documentation-only — no code modifications. The additions include:

1. Expanded docs/3sf_mini.md (22 → 218 lines)
2. New docs/ghost-fork-choice.md (841 lines)
3. New interactive HTML infographic docs/infographics/3sf-mini-infographic.html (768 lines)

Overall Assessment

✅ Approved — This is high-quality documentation that will significantly help developers understand the consensus layer. The explanations are clear, well-structured, and include helpful visualizations.

Detailed Review

1. docs/3sf_mini.md - Structure and Content

Strengths:

• Clear progression from concepts → justification → justifiability schedule → finalization
• Excellent ASCII diagrams showing vote thresholds and finalization checks
• Worked examples with concrete validator counts (4 validators, slot 100)
• Proper explanation of the justifiability backoff mechanism

Minor observations:

Line 52: The threshold formula 3 × vote_count ≥ 2 × validator_count is correct but could clarify this is checking for ≥2/3 supermajority (not >2/3). The implementation uses >= correctly.

Lines 100-111: The "Justifiable Slot Backoff" section is well-placed as a subsection now (was previously the entire document). Good improvement in organization.

Lines 113-145: The backoff example is clearer than the original, with better formatting and explicit bullet structure. One small inconsistency:

• Line 119 says "At slots 16–19" votes accumulate
• Line 133 in the old version said "At slots 16, 17, 18, and 19"

Both are saying the same thing, but the new version is more concise. Good change.

Lines 148-193: The finalization section with ASCII diagrams is excellent. The "unjustifiable gap at slot 17" example clearly illustrates why gaps matter for security.

Lines 195-218: The worked example is pedagogically sound. The step-by-step justification and finalization flow is easy to follow.

2. docs/ghost-fork-choice.md - Technical Depth

Strengths:

• Comprehensive treatment starting from historical GHOST paper context
• Clear separation of LMD-GHOST vs original GHOST
• Excellent explanation of subtree weight accumulation (lines 375-396)
• Detailed three-phase algorithm breakdown (lines 220-249)
• Worked example with 5 validators showing weight propagation (lines 330-448)

Technical accuracy:

Lines 55-66: The two key extensions (attestation-based + latest-message driven) correctly distinguish LMD-GHOST from original GHOST. Accurate.

Lines 210-217: The four inputs to compute_lmd_ghost_head() match the implementation in crates/blockchain/fork_choice/src/lib.rs. Verified against codebase structure mentioned in CLAUDE.md.

Lines 456-460: States min_score = ⌈2V/3⌉ for safe target. This is correct per the codebase patterns (2/3 supermajority threshold).

Lines 505-530: The attestation pipeline explanation (new → known → fork choice) matches the CLAUDE.md description of the two-stage pipeline with promotion at intervals 0 and 3. Accurate.

Lines 560-614: The tick-based scheduling diagram matches the CLAUDE.md specification:

• Interval 0: Proposer accepts new attestations, runs fork choice, proposes block
• Interval 1: Non-proposers produce attestations
• Interval 2: Safe target update (2/3 threshold)
• Interval 3: Accept attestations, update head

This is correct.

Lines 721-753: The comparison table with Ethereum Beacon Chain is valuable. Notable accurate points:

• ethlambda has equal weight per validator (no balance weighting)
• No proposer boost
• 4-second slots vs 12-second
• Slot-level justification vs epoch boundaries

Lines 761-780: LMD-GHOST variants comparison (IMD, LMD, FMD, RLMD) is accurate and provides good context for why LMD was chosen.

Lines 788-797: Implementation file references are accurate per CLAUDE.md structure.

3. docs/infographics/3sf-mini-infographic.html - Interactive Visualization

Strengths:

• Clean, modern dark theme matching typical developer preferences
• Interactive justifiability grid with hover tooltips (lines 742-764)
• SVG diagram of LMD-GHOST descent (lines 596-651)
• Five-section structure mirrors the markdown docs well

Code quality:

Lines 742-754: The JavaScript implementation of isJustifiable() correctly implements the three rules:

if (delta <= 5) return { justifiable: true, rule: 'proximity' };  // Rule 1
const sqrtD = Math.floor(Math.sqrt(delta));
if (sqrtD * sqrtD === delta) return { justifiable: true, rule: 'n²...' };  // Rule 2
const check = 4 * delta + 1;  // Solving n(n+1) = delta
const sqrtC = Math.floor(Math.sqrt(check));
if (sqrtC * sqrtC === check && sqrtC % 2 === 1) {  // Rule 3

The pronic number check using 4*delta + 1 is the standard formula: if delta = n(n+1), then 4*delta + 1 = (2n+1)². Checking if this is an odd perfect square correctly detects pronic numbers. ✓

Lines 597-605: SVG markers for arrows use proper stroke colors (#10B981 for chosen path, #64748B for unchosen). Visually clear.

Lines 620-647: The SVG tree structure shows:

• Justified Root (weight 10) → A (weight 7, chosen) vs B (weight 3, unchosen)
• A → D (weight 5, HEAD) vs C (weight 2)
• B → E (weight 3)

This correctly illustrates greedy descent selecting the heaviest subtree at each level.

Security note: The HTML uses external CDN fonts from fonts.googleapis.com (line 8). This is a documentation file, not a runtime component, so the external dependency is acceptable.

4. Consistency Between Documents

Cross-referencing the three files:

• 3sf_mini.md line 19: References justifiability schedule → explained in detail starting line 48
• ghost-fork-choice.md line 19: References [3sf_mini.md](3sf_mini.md) → correct relative link
• HTML infographic mirrors the five-section structure from markdown docs → consistent

All three documents use the same terminology (justified, finalized, justifiable, source, target, delta) consistently. ✓

5. Potential Improvements (Optional)

These are not blockers, just suggestions for future iterations:

1. Cross-references to implementation: The docs could add more line-number references to the actual Rust implementation (e.g., "process_attestations in state_transition/src/lib.rs:450") to help code readers.

2. 3SF-mini comparison: The docs explain 3SF-mini vs Casper FFG (epoch-based) but could briefly mention why slot-level finality was chosen (faster finalization in good conditions).

3. Reorg depth: The reorg section (lines 683-718 in ghost doc) could mention typical expected reorg depths under normal operation vs adversarial conditions.

4. Performance metrics: The "Performance Characteristics" section (lines 828-841) mentions "sub-millisecond" — citing actual benchmarks if available would strengthen this claim.

5. Interactive HTML accessibility: The infographic uses hover tooltips, which may not work on touch devices. Consider adding click-based tooltips as a fallback.

6. Formatting and Style

Strengths:

• Consistent use of ASCII diagrams for concepts
• Code blocks properly fenced with triple backticks
• Tables formatted consistently
• Proper markdown heading hierarchy

Minor nitpicks:

• ghost-fork-choice.md line 829: "O(A × D)" uses × (multiplication symbol). Consistent with line 832-834. Good.
• Some ASCII diagrams use box-drawing characters (─, │, ┌, etc.) which may not render in all terminals. This is acceptable for documentation files.

Security Considerations

Since this is documentation-only:

✅ No code changes — No risk of introducing consensus bugs, state transition errors, or cryptographic vulnerabilities.

✅ Accurate algorithm descriptions — The documented LMD-GHOST and 3SF-mini logic matches the consensus-critical implementation per CLAUDE.md specifications. No misleading information that could cause implementer errors.

✅ HTML infographic safety — Pure HTML/CSS/JavaScript with no external scripts beyond Google Fonts CDN. No XSS vectors or malicious code.

Consensus-Layer Verification

Verified against CLAUDE.md specifications:

• ✅ Tick-based scheduling (4 intervals per 4-second slot)
• ✅ Attestation pipeline (new → known promotion at intervals 0/3)
• ✅ Justifiability rules (≤5, n², n(n+1))
• ✅ Finalization via unjustifiable gap checking
• ✅ LMD-GHOST greedy descent from justified checkpoint
• ✅ Safe target using ⌈2V/3⌉ threshold

All descriptions accurately reflect the implementation architecture.

Conclusion

This PR significantly improves the project's documentation quality. The explanations are technically accurate, well-structured, and pedagogically sound. The addition of visual aids (ASCII diagrams, interactive HTML) makes complex consensus mechanisms more accessible.

Recommendation: Merge without changes.

No code correctness, security, or consensus issues found. The documentation will be valuable for onboarding new developers and understanding the protocol design.

---

Automated review by Claude (Anthropic) · custom prompt

[github-actions]

🤖 Codex Code Review

Summary
Docs-only PR. No Rust code changes, so no direct correctness, security, performance, or memory-safety impact. The main review point is a consensus-critical doc inconsistency around finalization rules.

Findings

1. Finalization rule is internally inconsistent and contradicts implementation. In docs/3sf_mini.md the example says finalization happens when consecutive justifiable slots are justified (lines 108-124), but the formal definition says finalization requires no unjustifiable gaps between source and target (lines 130-133), which is a stronger condition and would not allow finalization in the “16 → 20” example (lines 122-124). The implementation actually finalizes when there are no justifiable slots between source and target (i.e., consecutive justifiable slots). Please align the definition and example with the implemented rule to avoid spec drift.

   • docs/3sf_mini.md:108-133

2. Infographic repeats the same inconsistency. The infographic states “two consecutive justifiable slots are both justified with no justifiable gaps between them” (line 662), then later uses “No justifiable slots between 16 and 20 → slot 16 finalized” (line 718). This should be made consistent with the actual finalization condition and the main doc.

   • docs/infographics/3sf-mini-infographic.html:662-718

Notes

• No tests were run (docs-only change).

If you want, I can suggest exact wording for the finalization rule that matches the implementation.

---

Automated review by OpenAI Codex · custom prompt