docs: document log availability requirement and reth receipt pruning

[joanestebanr]

🔄 Changes Summary

• 📄 Extends docs/usage_ethereum_full_node.md with a new "Requirements: log availability from genesis" section.
• Documents that aggkit relies on eth_getLogs to sync contract state from the start of the chain, so logs (receipts) must be available from genesis — not just for a recent window of blocks.
• Adds reth-specific guidance: receipts are pruned by default in full-node mode, so run with --full --prune.receipts.before=0 (or the equivalent [prune.segments] reth.toml snippet) to ensure no receipts are ever discarded.
• Clarifies that historical state pruning is still acceptable, since aggkit only needs logs (aside from the initial LER query already covered in the doc).

⚠️ Breaking Changes

• None — documentation only.

📋 Config Updates

• No aggkit config changes. The doc references external reth node configuration:

  reth node --full --prune.receipts.before=0

  [prune.segments]
  receipts = { before = 0 }

✅ Testing

• 🤖 Automatic: N/A — documentation-only change, no code paths affected.
• 🖱️ Manual: Rendered the Markdown to verify formatting, links, and code blocks.

📝 Notes

• Captures an operational requirement that previously caused full-node sync failures when receipt pruning silently dropped historical logs.

[claude]

Claude finished @joanestebanr's task in 1m 2s —— View job

---

PR Review Complete ✅

---

🚀 What's New

This PR adds critical documentation about log availability requirements and reth receipt pruning configuration when using full nodes instead of archive nodes. It clarifies that aggkit requires logs (receipts) to be available from genesis, and provides specific configuration guidance for reth users to disable receipt pruning.

🐛 Bug Fixes

None.

📋 Config Updates

None - this is purely documentation.

⚠️ Breaking Changes

None.

---

Review Feedback

🟢 Overall Assessment

This is an excellent documentation addition that addresses a critical operational requirement. The new section fits naturally into the existing document flow and provides clear, actionable guidance.

✅ Strengths

1. Clear Problem Statement: The section effectively explains why log availability from genesis is required
2. Concrete Solutions: Provides both CLI and config file approaches for reth configuration
3. Good Context: The note explaining that state pruning is acceptable helps users understand they don't need a full archive node
4. Proper Placement: The new section is logically positioned right after the "Background" section and before "Component compatibility"

🟡 Suggested Improvements

1. Consider Adding Coverage for Other Clients (docs/usage_ethereum_full_node.md:53-67)
The section currently only covers reth. Consider mentioning other popular Ethereum clients:

• Geth: By default keeps receipts, but users should verify with --gcmode=full
• Erigon: Similar considerations may apply
• Nethermind: Receipt retention behavior

This would make the documentation more comprehensive for operators using different client implementations.

2. Add Verification Steps (docs/usage_ethereum_full_node.md:44-52)
Consider adding guidance on how operators can verify their full node has receipts available from genesis. For example:

# Test if receipts are available from an early block
cast receipt <early-tx-hash> --rpc-url <your-rpc>

3. Link to Node Client Documentation (docs/usage_ethereum_full_node.md:62)
While the reth pruning configuration reference link is good, consider also linking to reth's main documentation about receipt storage for additional context.

🟢 Minor Observations

Technical Accuracy: ✅ All technical content is accurate

• Correctly identifies that eth_getLogs requires receipt data
• Accurately describes reth's default pruning behavior
• Proper TOML syntax in examples

Writing Quality: ✅ Clear and well-structured

• Good use of formatting (bold, code blocks, notes)
• Consistent terminology
• No grammatical issues detected

Formatting: ✅ Consistent with existing document style

• Proper markdown heading hierarchy
• Horizontal rules used consistently
• Code blocks properly formatted with language identifiers

---

PR Template Feedback

⚠️ The PR description template is not filled out. While this is a documentation-only change, completing the template helps reviewers and provides better historical context. Specifically:

Suggested PR Description:

## 🔄 Changes Summary
- Added "Requirements: log availability from genesis" section documenting that aggkit requires receipts from genesis
- Documented reth-specific configuration to disable receipt pruning (`--prune.receipts.before=0`)
- Clarified that state pruning is acceptable but receipt pruning is not

## 📋 Config Updates
- None - provides guidance on reth node configuration but no changes to aggkit config

## ✅ Testing
- 🖱️ **Manual**: Verified documentation renders correctly and examples are syntactically valid

## 🐞 Issues
- Improves documentation for full node usage (related to archive node requirements)

---

Summary

This is a valuable documentation enhancement that fills an important gap. The content is technically accurate, well-written, and properly positioned within the document. The suggested improvements are minor and optional - the PR is ready to merge as-is, though addressing the suggestions would make it even more comprehensive.

Recommendation: ✅ Approve (with optional improvements)

[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