docs: add documentation about checkpoint-sync

[MegaRedHand]

This PR adds high-level documentation about checkpoint-sync

[github-actions]

🤖 Kimi Code Review

Review of docs/checkpoint_sync.md

The documentation is clear and technically accurate. A few minor suggestions:

1. Line 36: The endpoint path /lean/v0/states/finalized appears to be a typo - should likely be /ethlambda/v0/states/finalized or similar, given the project name is "ethlambda" not "lean".

2. Line 40: The timeout description could be clearer. "15 seconds of inactivity that resets on each successful read" might be better phrased as "15-second read timeout that resets on each successful data chunk received".

3. Line 55: The phrase "writes the new anchor state on top without clearing existing data" could be misinterpreted. Consider clarifying: "overwrites the anchor state while preserving other historical data".

4. Security Considerations section: While the weak subjectivity explanation is excellent, it might be worth explicitly mentioning that checkpoint sync should only be used from trusted sources, and that long-range attacks are still possible if the checkpoint source is malicious and serves a state from a fork that diverged more than ~2 epochs ago.

5. Missing: Consider adding a note about how this interacts with slashing protection - users should ensure their validator keys haven't signed conflicting messages before the checkpoint slot.

Overall, this is well-written documentation that accurately explains the checkpoint sync mechanism and its security implications.

---

Automated review by Kimi (Moonshot AI) · custom prompt

[github-actions]

🤖 Codex Code Review

I reviewed /tmp/pr_diff.txt. The PR only adds documentation (docs/checkpoint_sync.md) and no Rust code changes.

Findings:

• No code-level issues to assess for correctness, security, performance, or consensus logic.

Docs look clear and accurate. If you want, I can review the underlying implementation in the repo, but it is not part of this diff.

Next steps:

1. If you want a code review, point me to the relevant files or PR diff with code changes.

---

Automated review by OpenAI Codex · custom prompt

[greptile-apps]

Greptile Overview

Greptile Summary

Adds comprehensive documentation for the checkpoint-sync feature that was implemented in PR #93. The documentation accurately describes:

• How to use the --checkpoint-sync-url flag with proper examples
• Two checkpoint source options (direct peer and Leanpoint)
• Internal mechanics including fetch/verify/initialize flow and timeout behavior
• Complete verification checks table matching the implementation in checkpoint_sync.rs
• Security considerations around weak subjectivity and trust models

The documentation is well-structured, technically accurate when cross-referenced with the implementation code, and provides clear guidance for both quick-start usage and deeper understanding of the security implications.

Confidence Score: 5/5

• This PR is safe to merge with no risk - it only adds documentation
• Documentation-only PR that accurately reflects the existing implementation. All technical details verified against source code in checkpoint_sync.rs and main.rs. No code changes, no functional impact.
• No files require special attention

Important Files Changed

Filename	Overview
docs/checkpoint_sync.md	Comprehensive documentation added for checkpoint-sync feature with accurate technical details, clear usage examples, and security considerations

[github-actions]

🤖 Claude Code Review

Perfect! Now I have enough context to provide a comprehensive review. Let me create the review:

---

PR Review: Documentation for Checkpoint Sync

Summary

This PR adds comprehensive documentation for ethlambda's checkpoint sync feature. The documentation is well-structured, accurate, and aligns with the implementation in bin/ethlambda/src/checkpoint_sync.rs. Overall, this is excellent technical documentation.

Strengths

1. Accuracy: All technical details match the implementation:

   • Timeout values (15s connect, 15s read) match constants at checkpoint_sync.rs:9-13
   • Verification checks table accurately reflects all checks in verify_checkpoint_state() at checkpoint_sync.rs:100-192
   • CLI flag --checkpoint-sync-url matches main.rs:53
   • Endpoint /lean/v0/states/finalized matches checkpoint_sync.rs:71

2. Clear structure: The document flows logically from usage → sources → implementation → security considerations

3. Security focus: The "Security Considerations" section properly explains the weak subjectivity model and trust assumptions, which is critical for consensus client documentation

4. Comprehensive coverage: Includes both success and failure paths, timeout strategy explanation, and data directory behavior

Suggestions

1. Minor technical clarification (line 47)

Current:

No block body is stored since it isn't available from the checkpoint.

Suggested clarification:

No block body is stored since it isn't available from the checkpoint (only the state and header are fetched from /lean/v0/states/finalized).

This makes it clearer that it's a limitation of the endpoint, not a design choice.

2. Add note about data directory location (line 55)

Current:

If the data directory (./data) already contains state from a previous run...

Consider adding:
This could reference that the data directory is currently hardcoded to ./data (as seen in main.rs:106), and perhaps note if this is configurable in the future or recommend users be aware of this path.

3. Verification table enhancement (line 61-74)

The verification checks table is excellent and matches the code perfectly. However, consider adding one more column for "Error variant" to help developers debug failed syncs:

| Check | What it catches | Error variant |
| ------- | ----------------- | ------------- |
| Slot > 0 | Checkpoint state cannot be genesis (slot 0) | `SlotIsZero` |
| ... | ... | ... |

This would help users map error messages to specific validation failures.

4. Minor wording improvement (line 82)

Current:

Checkpoint sync operates under a weak subjectivity assumption.

Suggested:

Checkpoint sync operates under the weak subjectivity assumption.

Change "a" to "the" since weak subjectivity is a specific, well-defined concept in PoS consensus.

5. Consider adding a troubleshooting section

Given that the implementation exits on failure (checkpoint_sync.rs:51), users might benefit from a brief troubleshooting section covering:

• Common error messages and their meanings
• How to verify the checkpoint source is reachable
• What "clean slate" means (removing ./data directory)
• How to verify the genesis config matches the network

Technical Correctness

All verification checks documented match the implementation exactly:

• ✅ Slot > 0 check (checkpoint_sync.rs:106-108)
• ✅ Validators non-empty (checkpoint_sync.rs:111-113)
• ✅ Genesis time match (checkpoint_sync.rs:116-121)
• ✅ Validator count match (checkpoint_sync.rs:124-129)
• ✅ Sequential validator indices (checkpoint_sync.rs:132-140)
• ✅ Validator pubkeys match (checkpoint_sync.rs:143-152)
• ✅ Finalized slot consistency (checkpoint_sync.rs:155-157)
• ✅ Justified slot consistency (checkpoint_sync.rs:160-162)
• ✅ Same-slot checkpoint root match (checkpoint_sync.rs:165-169)
• ✅ Block header slot consistency (checkpoint_sync.rs:172-174)
• ✅ Block header finalized root match (checkpoint_sync.rs:179-183)
• ✅ Block header justified root match (checkpoint_sync.rs:185-189)

Security Assessment

The security considerations section is well-written and appropriately emphasizes:

• The trust assumptions when using checkpoint sync
• What verification protects against vs. what it doesn't
• The importance of choosing a trustworthy checkpoint source

This is crucial for a consensus client where users need to understand the trust model.

Verdict

Approve with minor suggestions. The documentation is accurate, comprehensive, and well-structured. The suggestions above are minor improvements that would enhance usability but are not blocking issues. This is high-quality technical documentation that will serve users well.

---

Automated review by Claude (Anthropic) · custom prompt