🤖 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

🤖 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

🤖 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

🤖 Kimi Code Review

Review Summary

This PR adds comprehensive documentation for ethlambda's fork choice and finalization mechanisms. The documentation is well-structured and technically accurate. Here are my observations:

Strengths

• Excellent technical depth: The 3SF-mini explanation is particularly thorough, covering edge cases and providing clear worked examples
• Good cross-references: Links between 3SF-mini.md and ghost-fork-choice.md are helpful
• Implementation details: Specific references to ethlambda source files and functions add practical value

Minor Issues

1. Typo in 3sf_mini.md line 108: "to finalized a slot" → "to finalize a slot"

2. Inconsistent terminology:

   • Line 26 in 3sf_mini.md uses "checkpoint" but the rest of the document uses "slot" - should clarify that in 3SF-mini, slots themselves act as checkpoints
   • Line 140 mentions "original_finalized_slot" but this variable name isn't used in the referenced source files

3. Missing edge case: The 3SF-mini documentation doesn't explicitly mention what happens when slot <= finalized_slot in slot_is_justifiable_after. While the implementation likely returns false, documenting this would be helpful.

4. Code reference accuracy:

   • Line 144 references try_finalize() but this function appears to be named process_justification_and_finalization in the actual source
   • The shift_window() function mentioned on line 190 is actually named shift_justified_slots_window

Suggestions

1. Add visual diagram: A state transition diagram showing how justification/finalization interact with fork choice would complement the text descriptions

2. Clify validator count: In the worked examples, explicitly state that validator count is fixed at genesis for 3SF-mini (unlike Ethereum's dynamic validator set)

3. Document tiebreaker: While the ghost-fork-choice.md mentions lexicographic tiebreaking, 3sf_mini.md should mention what happens when two competing justifications occur at the same slot

These are minor documentation issues that don't affect correctness. The technical content is solid and will be valuable for understanding ethlambda's consensus mechanisms.

Automated review by Kimi (Moonshot AI) · custom prompt

🤖 Codex Code Review

Summary
Docs-only change. No code, consensus, or security logic is modified, so no correctness/perf risks from this PR. The new docs are thorough and align with the current implementation I spot-checked.

Findings

1. Minor doc accuracy: the attestation validity checklist omits the zero-hash guard for source/target roots. Consider adding a bullet so the doc matches is_valid_vote behavior. docs/3sf_mini.md:46

Notes
No tests needed for a documentation-only PR.

Automated review by OpenAI Codex · custom prompt

Greptile Summary

Adds comprehensive documentation for two core consensus mechanisms. The 3sf_mini.md file transforms from a minimal placeholder into a 308-line detailed explanation of justification and finalization, including the justifiability schedule, supermajority voting, and worked examples. The ghost-fork-choice.md is an entirely new 759-line document providing in-depth coverage of the LMD-GHOST fork choice algorithm, including historical context, algorithm walkthrough, attestation pipeline, and ethlambda-specific implementation details.

Key additions:

• Detailed explanation of 3SF-mini's slot-level justification (vs Casper FFG's epoch-based approach)
• Clear visualization of justifiability rules (delta ≤ 5, perfect squares, pronic numbers)
• Complete LMD-GHOST algorithm description with weight accumulation and greedy descent
• Accurate cross-references between documents and to actual codebase functions
• Well-formatted ASCII diagrams throughout for visual clarity

Note: The PR description lists TODOs including reviewing the LMD-GHOST doc and explaining differences from Casper FFG - the author acknowledges this is work in progress.

Confidence Score: 5/5

• This documentation-only PR is safe to merge with no risk to production code
• Documentation-only changes with accurate technical content, verified code references, proper formatting, and no impact on executable code. All referenced functions and file paths exist in the codebase.
• No files require special attention

_{Last reviewed commit: 79d959d}

🤖 Claude Code Review

PR #128 Review — docs: add explanation of LMD-GHOST and 3SF-mini

This PR replaces the stub docs/3sf_mini.md with a comprehensive 308-line document and adds a new 758-line docs/ghost-fork-choice.md. Overall the documentation is well-written, the ASCII diagrams are clear, and the ethlambda-specific callouts using blockquotes are a good structural choice.

Factual Error (must fix)

docs/3sf_mini.md — Justifiability table, row for delta=36

The rule column shows 2+3, claiming delta=36 satisfies both the perfect-square rule and the pronic rule. This is incorrect.

• Rule 2 (perfect square): 6² = 36 ✓
• Rule 3 (pronic, n(n+1)): Solving n(n+1) = 36 gives n ≈ 5.52, not an integer ✗

The next pronic after 5×6 = 30 is 6×7 = 42, not 36. The table entry should read:

The formula column makes this worse: 6²=6×6 visually pattern-matches the pronic format used above (2×3, 3×4, 4×5, 5×6), reinforcing the false impression that 36 is a pronic. Changing it to simply 6² removes the ambiguity.

Note: the visualization directly above the table (the two rows of ✓ / · marks) is actually correct — there is only one ✓ at delta=36, consistent with it being a perfect square only. The inconsistency is between the visualization and the table.

Minor Issues

docs/ghost-fork-choice.md — Tiebreaker direction

The document states "lexicographically higher block root hash wins." This is a concrete protocol detail that affects consensus correctness if two nodes apply opposite tiebreakers. It would be worth adding an inline reference to the relevant line in compute_lmd_ghost_head() so readers can verify the actual comparison direction without having to dig into the code.

Acknowledged gap

The PR description lists "Explain how 3SF-mini differs from Casper FFG" as a TODO. The current LMD-GHOST doc briefly mentions Casper FFG in the two-layer diagram but doesn't do a detailed comparison. Since this is already tracked in the PR, just noting it for completeness.

What Looks Good

• The worked examples in both documents are correct. The 4-validator justification/finalization example in 3sf_mini.md, the 5-validator LMD-GHOST head-selection example, and the 4-phase backoff scenario (with the math checked: 30²=900, 31²=961, 31×32=992, 32²=1024) are all accurate.
• The finalization check logic is described correctly: try_finalize() uses original_finalized_slot (not the current one) to avoid artifacts from mid-processing finalization advancement. This matches CLAUDE.md.
• The two-layer consensus framing (LMD-GHOST for fork choice, 3SF-mini for finality) clearly explains why the fork choice descent starts from the justified checkpoint, not genesis.
• The attestation pipeline section correctly identifies the asymmetry between gossip attestations (pending) and on-chain attestations (active), and the reasoning for the proposer's own attestation entering as pending is well-explained.
• The differences-from-Ethereum-Beacon-Chain table (no proposer boost, no balance weighting, no equivocation discounting) is accurate and useful context.
• Performance characteristics and the proto-array TODO reference are appropriate callouts for implementers.

Automated review by Claude (Anthropic) · custom prompt