chore!: cleanup header unused types

[tac0turtle]

Overview

remove unused fields in header

[claude]

Claude finished @tac0turtle's task —— View job

---

Code Review Complete

I've performed a comprehensive review of this PR that removes unused header fields. Here's my detailed analysis:

---

Summary

This PR removes four unused fields from the Header type and one field from State:

• From Header: LastCommitHash, ConsensusHash, LastResultsHash (all previously at positions 5, 7, 9)
• From State: LastResultsHash (position 7)

The fields are properly marked as reserved in the protobuf schema to prevent field number reuse, which is the correct approach for proto evolution.

---

1. Code Quality & Architecture ✅

Strengths:

• Proper proto evolution: Field numbers are correctly reserved (5, 7, 9 in Header; 7 in State) to prevent accidental reuse
• Clean removal: All references to removed fields have been systematically eliminated across the codebase
• Consistent updates: Generated code (protobuf, Rust bindings) has been properly regenerated
• Documentation updated: ADRs and specification docs reflect the changes

Observations:

• The removal aligns with the goal of maintaining a minimal header design (per ADR-004)
• Field removal is clean with no orphaned references detected
• The codebase search confirms no lingering references to LastCommitHash, ConsensusHash, or LastResultsHash

---

2. Error Handling & Resilience ✅

• Backward compatibility: Using reserved fields ensures old messages can still be parsed
• Serialization safety: The protobuf conversions in types/serialization.go handle nil values correctly
• Validation intact: ValidateBasic() methods remain functional and appropriate for the reduced field set

---

3. Security ⚠️

Concerns:

1. Reduced commitment surface: Removing LastCommitHash means the header no longer commits to previous block's commit information. This changes the trust model.

   • Impact: Light clients or validators that relied on this field for verification will need updates
   • Question: Is there documentation on why these fields are safe to remove from a security perspective?

2. ConsensusHash removal: This field was meant for consensus parameter changes

   • Per ADR-004, ConsensusParams are treated as constants, which justifies removal
   • Good: The code comments in ADR-004 already noted this assumption

3. LastResultsHash removal: Transaction receipts/results are no longer committed to in the header

   • Impact: Applications that need to prove transaction execution results will need alternative mechanisms
   • Question: How will this affect IBC or other cross-chain verification scenarios?

Recommendations:

• Consider documenting the security implications in a migration guide
• Ensure ev-abci (mentioned by @julienrbrt) handles these changes correctly

---

4. Performance & Resource Efficiency ✅

Improvements:

• Reduced header size: Removing 3 x 32-byte hash fields = 96 bytes saved per header
• State size reduction: One additional hash removed from state = 32 bytes
• Network efficiency: Smaller headers mean less gossip overhead
• Storage savings: Cumulative savings across blockchain history

Metrics:

• Proto message size reduction visible in generated code
• tools/blob-decoder/main.go simplified by removing unused field displays

---

5. Testing & Reliability ⚠️

Issues Found:

Critical: Test Coverage Gap

File: tools/blob-decoder/main.go:202-229

• Issue: Codecov reports 0% coverage for 4 new/modified lines
• Lines: The tryDecodeHeader function has uncovered code paths
• Impact: The blob decoder's header parsing might have untested edge cases
• Recommendation: Add unit tests for tryDecodeHeader with various header formats

Tests Updated Appropriately:

• ✅ types/serialization_test.go: Removed LastResultsHash from test cases
• ✅ Test cases properly updated to reflect new header structure
• ✅ Roundtrip tests ensure serialization correctness

---

6. Documentation & Developer Experience ✅

Well-Documented:

• ADR-004 (docs/adr/adr-004-core-types.md): Removed evidence hash references
• ADR-015 (docs/adr/adr-015-rollkit-minimal-header.md): Updated for minimal header
• Block validity spec (docs/learn/specs/block-validity.md): Updated
• OpenAPI schema (docs/src/openapi-rpc.json): Removed deprecated fields

Observations:

• The UI template (tools/blob-decoder/templates/index.html) correctly removes field displays
• Proto comments remain clear and informative
• Type documentation in types/header.go is accurate

---

7. Breaking Changes Assessment 🔴

Buf Breaking Change Detection:

The CI shows buf-check failed with 4 breaking changes. This is expected and acceptable because:

1. Wire-compatible: Proto reserved fields maintain wire compatibility
2. API breaking: Field removal is an API break, correctly detected by buf
3. Semantic versioning: The ! in "chore!: cleanup header unused types" correctly signals a breaking change

Migration Impact:

Affected Components:

• ✅ Block executor: block/internal/executing/executor.go - imports removed
• ✅ Block syncer: block/internal/syncing/syncer.go - imports removed
• ✅ RPC server: pkg/rpc/server/server.go - imports removed
• ✅ Tools: blob-decoder and da-debug updated
• ⚠️ External: ev-abci needs updates (acknowledged by maintainer)
• ⚠️ Clients: Any external clients using these fields will break

Downstream Considerations:

• Light clients trusting these fields need updates
• Block explorers displaying these fields need UI changes
• Archive nodes may need to handle both old and new header formats

---

Specific Issues & Recommendations

Issue 1: Blob Decoder Test Coverage

File: tools/blob-decoder/main.go:202-229

// This function needs test coverage
func tryDecodeHeader(data []byte) interface{} {
    // Lines 202-229 are not covered by tests
}

Recommendation: Add unit tests:

func TestTryDecodeHeader(t *testing.T) {
    // Test valid header
    // Test invalid protobuf
    // Test header that fails validation
    // Test nil/empty input
}

Issue 2: Reserved Field Documentation

File: proto/evnode/v1/evnode.proto:42

reserved 5, 7, 9;

Recommendation: Add a comment explaining what was reserved:

// Reserved field numbers from removed fields:
// 5 = last_commit_hash (removed in v2.x)
// 7 = consensus_hash (removed in v2.x)  
// 9 = last_results_hash (removed in v2.x)
reserved 5, 7, 9;

Issue 3: Migration Documentation

Missing: No migration guide for users

Recommendation: Create a migration document covering:

• Why these fields were removed
• Impact on light clients and validators
• How to update ev-abci integrations
• Backward compatibility guarantees

---

Positive Highlights 🎉

1. Thorough cleanup: All 32 files updated consistently
2. No orphaned code: Zero remaining references to removed fields
3. Rust bindings: Automatically updated via proto generation
4. Test consistency: Tests updated to match new structure
5. Documentation diligence: Multiple doc files updated

---

Summary & Verdict

Overall Assessment: Approve with Minor Recommendations ✅

This is a well-executed breaking change that achieves its goal of simplifying the header structure. The implementation is clean, consistent, and follows protobuf best practices.

Required Actions:

1. ✅ Breaking change acknowledged: Correctly marked with !
2. ⚠️ Add tests: Cover the blob decoder's new code paths
3. 📝 Document reserved fields: Add comments to proto file
4. 📝 Migration guide: Document for downstream consumers

Optional Improvements:

• Consider a dedicated ADR for this breaking change
• Document security implications of removed commitments
• Add integration tests for backward compatibility

Risk Level: Medium

• Technical risk: Low (clean implementation)
• Ecosystem risk: Medium (breaking change affecting downstream)

---

Recommendation: Approve after addressing test coverage. The buf-check failures are expected and acceptable for this breaking change.

---

[github-actions]

The latest Buf updates on your PR. Results from workflow CI and Release / buf-check (pull_request).

Build	Format	Lint	Breaking	Updated (UTC)
✅ passed	⏩ skipped	✅ passed	❌ failed (4)	Oct 17, 2025, 12:47 PM

[codecov]

Codecov Report

❌ Patch coverage is 0% with 4 lines in your changes missing coverage. Please review.
✅ Project coverage is 61.34%. Comparing base (1890a37) to head (f5b6907).
⚠️ Report is 1 commits behind head on main.

Files with missing lines	Patch %	Lines
tools/blob-decoder/main.go	0.00%	4 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #2766      +/-   ##
==========================================
- Coverage   61.42%   61.34%   -0.09%     
==========================================
  Files          81       81              
  Lines        8622     8583      -39     
==========================================
- Hits         5296     5265      -31     
+ Misses       2828     2820       -8     
  Partials      498      498              

Flag	Coverage Δ
combined	61.34% <0.00%> (-0.09%)	⬇️

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[github-actions]

PR Preview Action v1.6.2
Preview removed because the pull request was closed.
2025-10-17 13:02 UTC

[julienrbrt]

ACK. I can update ev-abci to reflect this afterwards.