docs: document log availability requirement and reth receipt pruning config

[joanestebanr]

🔄 Changes Summary

• Added a new section "Requirements: log availability from genesis" to the full node usage guide
• Documents that aggkit requires event logs (receipts) to be available from genesis block
• Explains that receipt pruning on clients like reth will break aggkit's historical log sync
• Provides both CLI flag and reth.toml config options to retain all receipts

⚠️ Breaking Changes

• None

📋 Config Updates

• reth users must run with --full --prune.receipts.before=0 or set receipts = { before = 0 } in [prune.segments] of reth.toml

✅ Testing

• 🖱️ Manual: Documentation-only change

🐞 Issues

• N/A

📝 Notes

• The receipt pruning requirement applies to both L1 and L2 full nodes
• Historical state pruning (account/storage tries) is still acceptable — aggkit only needs logs

🤖 Generated with Claude Code

[claude]

Claude finished @joanestebanr's task in 58s —— View job

---

📋 Review Progress

• Read the modified documentation file
• Review documentation changes for accuracy and clarity
• Provide comprehensive feedback
• Fill in review template

---

🚀 What's New

Documentation now clearly explains that aggkit requires event logs (receipts) to be available from genesis block for proper operation. Added specific configuration guidance for reth users to disable receipt pruning using either CLI flags or configuration file settings.

🐛 Bug Fixes

None.

📋 Config Updates

• reth users: Must disable receipt pruning to use aggkit
  • CLI: reth node --full --prune.receipts.before=0
  • Config file (reth.toml): [prune.segments] → receipts = { before = 0 }

⚠️ Breaking Changes

None - this is a documentation clarification of existing requirements.

---

Review Summary

This is an excellent documentation addition that addresses a critical operational requirement. The new section fills an important gap by explicitly documenting receipt/log availability requirements.

🟢 Strengths

1. Well-positioned: The new section is logically placed after explaining the background but before component compatibility details
2. Clear and actionable: Provides both the "why" (aggkit needs logs from genesis) and the "how" (specific reth configuration)
3. Complete examples: Shows both CLI and config file approaches for reth
4. Good cross-references: Links to official reth pruning documentation
5. Helpful clarification: The note about state pruning being acceptable is important to avoid confusion

🟡 Suggestions for Improvement

1. Other client coverage (docs/usage_ethereum_full_node.md:44-72)

   • The section only covers reth explicitly. Consider adding a brief mention of other common clients:
     • Geth: Mention that geth full nodes retain receipts by default (no special config needed)
     • Erigon: Similar to geth, retains receipts in full mode
     • Nethermind: Also retains receipts by default
   • This would help users running other clients understand whether they need to take action
   • Suggested addition after the reth section:

     ### Other clients (geth, erigon, nethermind)
     
     Most other Ethereum clients (geth, erigon, nethermind) retain receipts by default in full-node mode. No special configuration is required for these clients.

2. Scope clarification (docs/usage_ethereum_full_node.md:44-48)

   • Consider explicitly stating whether this applies to L1, L2, or both
   • The PR description mentions "both L1 and L2 full nodes" but the documentation doesn't make this explicit
   • Suggested rewording for line 44-48:

     ## Requirements: log availability from genesis
     
     aggkit relies on Ethereum event logs (`eth_getLogs`) to synchronize contract state from the
     beginning of the chain. **This applies to both L1 and L2 RPC endpoints.** Logs (receipts) must 
     be available from genesis, not just for a recent window of blocks.

3. Warning visibility (docs/usage_ethereum_full_node.md:50-51)

   • The warning about receipt pruning causing failures could be more prominent
   • Consider using a warning callout instead of regular text:

     > **⚠️ Warning:** Clients that perform **receipt pruning** will drop this data and cause 
     > aggkit to fail when it tries to backfill historical events.

🟢 Technical Accuracy

• ✅ reth CLI flags are correct (--full --prune.receipts.before=0)
• ✅ TOML configuration syntax is valid
• ✅ The pruning configuration link points to correct reth documentation
• ✅ The distinction between receipt pruning and state pruning is accurate
• ✅ The reference to eth_call vs logs is technically correct

🟢 Documentation Quality

• ✅ Clear section structure with proper markdown headers
• ✅ Code blocks are properly formatted with syntax highlighting
• ✅ Good use of bold for emphasis on critical points
• ✅ Proper use of blockquote notes for additional context
• ✅ Consistent with existing documentation style in the file

---

Overall Assessment

Approve with minor suggestions. This documentation change is important, accurate, and well-written. The suggestions above would make it even more comprehensive, but the current version is already valuable and can be merged as-is. The most impactful improvement would be adding brief coverage of other common clients to avoid user confusion.

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud