feat: block Pruning

[pthmas]

Overview

• Adds a height-based pruning mechanism to the ev-node store:
  • Prunes /h/{height}, /d/{height}, /c/{height}, /i/{hash} up to a target height.
  • Also prunes per-height DA metadata (height → DA height mapping) for pruned heights.
  • Leaves /s/{height} (state), /t (current height), and global metadata keys untouched.
  • Tracks progress via a last-pruned-block-height metadata key so pruning is monotonic and idempotent.
• Integrates pruning into the DA inclusion loop:
  • As DA inclusion advances, at configurable intervals, the submitter computes a prune target and calls store.PruneBlocks.
  • The prune target is capped by both:
    • the DA-included height (DAIncludedHeightKey), so only DA-included blocks are ever pruned, and
    • the current store height, to avoid pruning beyond what we actually have locally.
  • If there are not enough fully DA-included blocks beyond PruningKeepRecent, pruning is skipped.
• Adds pruning for execution metadata:
  • Execution stores (EVM, ev-abci, etc.) expose PruneExecMeta to delete per-height ExecMeta entries up to the same target height.
  • The executor implements an optional ExecMetaPruner interface, and the submitter calls it from the DA inclusion pruning hook.
  • EV-ABCI PR: feat: pruning ev-abci#332
• Optimizes header/data tail lookups:
  • The StoreAdapter’s Tail() now uses the last-pruned-block-height metadata to skip fully pruned ranges instead of linearly scanning from genesis.
  • This keeps tail lookups efficient even after long-term pruning.

Config

New node config fields / flags:

• --evnode.node.pruning_enabled
• --evnode.node.pruning_keep_recent
• --evnode.node.pruning_interval

Pruning actually runs only when all three are set to non-trivial values (enabled, keep_recent > 0, interval > 0).

Design trade-offs

• Best-effort pruning:
  If pruning fails (either store or exec metadata), we log the error but do not halt DA inclusion. This avoids stopping the node but means disk usage can grow silently if pruning keeps failing; operators will need to watch logs/metrics.

• Scope:
  This PR prunes:

  • ev-node’s own block store (headers, data, signatures, hash index, and per-height DA metadata),
  • execution metadata via the ExecMetaPruner hook when available.

[github-actions]

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

Build	Format	Lint	Breaking	Updated (UTC)
✅ passed	⏩ skipped	✅ passed	✅ passed	Feb 10, 2026, 10:50 AM

[claude]

Claude finished @pthmas's task in 1m 58s —— View job

---

Comprehensive Code Review: Block Pruning Implementation

I've completed a thorough review of the block pruning implementation. Overall, this is a well-designed feature with good architectural decisions. Below is my detailed feedback organized by category.

---

1. Code Quality & Architecture

Strengths

✅ Clean separation of concerns: Pruning is correctly isolated in three layers:

• Core store pruning (pkg/store/store.go:PruneBlocks)
• Execution metadata pruning (execution/evm/store.go:PruneExec)
• Orchestration in DA inclusion loop (block/internal/submitting/submitter.go:pruneBlocks)

✅ Idempotent design: The use of last-pruned-block-height metadata ensures pruning can be safely resumed after crashes or restarted multiple times.

✅ Monotonic progress tracking: LastPrunedBlockHeightKey prevents redundant work and maintains correctness across restarts.

✅ Optional interface pattern: The ExecPruner interface is well-designed for optional execution-layer pruning.

✅ Tail optimization: Using last-pruned-block-height to skip pruned ranges in Tail() lookups (pkg/store/store_adapter.go:408-414) is excellent for performance.

Issues to Address

🔴 Critical: Data race in pruneBlocks (block/internal/submitting/submitter.go:374-413)
The pruneBlocks() function accesses s.ctx and s.store without any synchronization, but it's called from the processDAInclusionLoop goroutine which could race with the Stop() method that cancels s.ctx. While the current implementation may work due to atomic operations on the context, this is fragile.

Recommendation: Add a check at the beginning of pruneBlocks:

func (s *Submitter) pruneBlocks() {
    select {
    case <-s.ctx.Done():
        return  // Already stopped
    default:
    }
    
    if !s.config.Node.PruningEnabled || ...

🟡 Missing bounds validation in PruneBlocks (pkg/store/store.go:341-426)
While the function correctly handles the case where height <= lastPruned, it doesn't validate that height is reasonable relative to the current store height. Pruning beyond the store height won't cause corruption (due to ErrNotFound handling) but wastes resources.

Recommendation: Add validation:

func (s *DefaultStore) PruneBlocks(ctx context.Context, height uint64) error {
    currentHeight, err := s.Height(ctx)
    if err != nil {
        return fmt.Errorf("failed to get current height: %w", err)
    }
    if height > currentHeight {
        return fmt.Errorf("cannot prune beyond current height %d: requested %d", currentHeight, height)
    }
    // ... rest of function
}

🟡 Inconsistent error handling style (pkg/store/store.go:378-413)
The pruning loop treats ErrNotFound differently for different key types:

• For headers: continue (L372-374)
• For other keys: explicit error checking with !errors.Is(err, ds.ErrNotFound) (L379, L385, L391, L398, L403, L410)

Recommendation: Use consistent pattern throughout for better maintainability.

---

2. Error Handling & Resilience

Strengths

✅ Best-effort approach: Logging errors without halting is appropriate for pruning (submitter.go:405, 410).

✅ Idempotency: The implementation correctly handles partial failures and allows retry.

✅ Graceful degradation: If pruning fails, the system continues to function (disk usage grows but data integrity is maintained).

Issues to Address

🔴 Silent failure mode (block/internal/submitting/submitter.go:405-411)
The best-effort approach is good, but there's no way for operators to detect persistent pruning failures except by watching logs. Over time, this could lead to unexpected disk usage growth.

Recommendation: Add metrics for pruning failures:

if err := s.store.PruneBlocks(s.ctx, targetHeight); err != nil {
    s.logger.Error().Err(err).Uint64("target_height", targetHeight).Msg("failed to prune old block data")
    s.metrics.PruningFailures.Inc()  // Add this metric
}

🟡 No validation of pruning configuration (pkg/config/config.go:388-395)
The validation ensures PruningInterval >= 1 and PruningKeepRecent > 0, but doesn't validate the relationship between them. If PruningKeepRecent < PruningInterval, pruning will never run.

Recommendation: Add cross-field validation:

if c.Node.PruningEnabled {
    if c.Node.PruningInterval == 0 {
        return fmt.Errorf("pruning_interval must be >= 1 when pruning is enabled")
    }
    if c.Node.PruningKeepRecent == 0 {
        return fmt.Errorf("pruning_keep_recent must be > 0 when pruning is enabled")
    }
    if c.Node.PruningKeepRecent < c.Node.PruningInterval {
        return fmt.Errorf("pruning_keep_recent (%d) should be >= pruning_interval (%d) for effective pruning",
            c.Node.PruningKeepRecent, c.Node.PruningInterval)
    }
}

🟡 Missing context cancellation check in PruneBlocks (pkg/store/store.go:367-414)
The pruning loop can iterate over many heights without checking if the context has been cancelled.

Recommendation: Add periodic cancellation checks:

for h := lastPruned + 1; h <= height; h++ {
    // Check cancellation every 100 heights or so
    if h%100 == 0 {
        select {
        case <-ctx.Done():
            return ctx.Err()
        default:
        }
    }
    // ... rest of loop
}

---

3. Security

Assessment

✅ No security issues identified

• Pruning only affects local storage, not consensus
• Only DA-included blocks are pruned (safety check at submitter.go:396)
• State snapshots (/s/{height}) are preserved
• No authentication/authorization concerns (local operation)

---

4. Performance & Resource Efficiency

Strengths

✅ Batched deletion: Using ds.Batch for pruning operations is efficient (store.go:342-345).

✅ Interval-based pruning: Only pruning every N blocks prevents excessive overhead (submitter.go:391-393).

✅ Cache invalidation: CachedStore.PruneBlocks correctly invalidates cache entries (cached_store.go:162-170).

✅ Tail optimization: Skipping fully-pruned ranges dramatically improves tail lookups after long-running pruning.

Issues to Address

🟡 Linear scan for missing headers (pkg/store/store.go:370-376)
During pruning, if a header is already missing (from previous partial pruning), the code calls s.db.Get() which may hit the disk. This is acceptable but could be optimized.

Minor optimization suggestion: Track which heights were successfully pruned to avoid repeated lookups, though current approach is simple and correct.

🟡 Cache invalidation is overly broad (pkg/store/cached_store.go:168)
InvalidateRange(1, height) clears the cache from height 1, but we could be more surgical and only invalidate lastPruned+1 to height.

Recommendation:

func (cs *CachedStore) PruneBlocks(ctx context.Context, height uint64) error {
    lastPruned := uint64(0)
    if meta, err := cs.GetMetadata(ctx, LastPrunedBlockHeightKey); err == nil && len(meta) == heightLength {
        lastPruned, _ = decodeHeight(meta)
    }
    
    if err := cs.Store.PruneBlocks(ctx, height); err != nil {
        return err
    }
    
    // Only invalidate newly pruned range
    cs.InvalidateRange(lastPruned+1, height)
    return nil
}

---

5. Testing & Reliability

Test Coverage Analysis

Based on codecov report (23.58% patch coverage with 81 lines missing):

✅ Good coverage for:

• execution/evm/store_test.go: Excellent tests for ExecMeta pruning
• Basic store tests exist in pkg/store/store_test.go

🔴 Critical gaps (from codecov):

• pkg/store/store.go: Only 20% coverage with 24 missing + 12 partials
• block/internal/submitting/submitter.go: 17.39% with 19 missing lines
• pkg/store/tracing.go: 0% coverage (11 missing) - tracing wrapper not tested
• pkg/store/cached_store.go: 0% coverage (5 missing) - cache invalidation not tested

Recommendations for Test Coverage

🔴 High Priority - Add integration tests:

// Test the full pruning flow
func TestPruningIntegration(t *testing.T) {
    // 1. Create store, executor, submitter
    // 2. Produce blocks 1-100
    // 3. Mark blocks 1-50 as DA included
    // 4. Trigger pruning with KeepRecent=20
    // 5. Verify blocks 1-30 are pruned
    // 6. Verify blocks 31-50 remain (within KeepRecent)
    // 7. Verify blocks 51-100 remain (not yet DA included)
}

func TestPruningWithCacheInvalidation(t *testing.T) {
    // Test that cache correctly invalidates pruned entries
}

func TestPruningFailureRecovery(t *testing.T) {
    // Test that pruning can resume after partial failure
}

🔴 Add unit tests for edge cases:

func TestPruneBlocks_ContextCancellation(t *testing.T) {}
func TestPruneBlocks_DiskFailureMidway(t *testing.T) {}
func TestPruneBlocks_PruneTargetExceedsStoreHeight(t *testing.T) {}

---

6. Documentation & Developer Experience

Strengths

✅ Good inline documentation: Function comments explain the pruning behavior clearly.

✅ Configuration documentation: docs/learn/config.md has comprehensive pruning settings documentation.

✅ Clear PR description: The overview explains the design trade-offs well.

Minor Improvements

🟡 Add metrics documentation: List the observable metrics for pruning in docs or code comments.

🟡 Clarify best-effort semantics: Add a note in the config docs that pruning failures don't halt the node but should be monitored.

---

Summary & Recommendations

Priority Actions

P0 - Must Fix Before Merge:

1. Fix potential data race in pruneBlocks() goroutine access
2. Add metrics for pruning failures (operator visibility)
3. Add integration tests for the full pruning flow

P1 - Should Fix:

1. Validate pruning configuration (KeepRecent >= Interval)
2. Add context cancellation checks in long-running pruning loops
3. Add bounds validation in PruneBlocks (don't prune beyond store height)
4. Improve test coverage to at least 60% for pruning code paths

P2 - Nice to Have:

1. Optimize cache invalidation to be more surgical
2. Add edge case tests (context cancellation, disk failures)
3. Consistent error handling pattern in pruning loop

Overall Assessment

This is a well-architected feature with clean separation of concerns and good safety guarantees. The main concerns are:

• Test coverage is too low for a feature that deletes data
• Lack of operator visibility into pruning failures
• Minor concurrency and validation issues

The core algorithm is sound, idempotent, and handles partial failures well. With the recommended fixes, this will be production-ready.

View more recent changes

---

[codecov]

Codecov Report

❌ Patch coverage is 23.58491% with 81 lines in your changes missing coverage. Please review.
✅ Project coverage is 61.32%. Comparing base (a64c35b) to head (fec4fb4).
⚠️ Report is 1 commits behind head on main.

Files with missing lines	Patch %	Lines
pkg/store/store.go	20.00%	24 Missing and 12 partials ⚠️
block/internal/submitting/submitter.go	17.39%	19 Missing ⚠️
pkg/store/tracing.go	0.00%	11 Missing ⚠️
pkg/config/config.go	37.50%	4 Missing and 1 partial ⚠️
pkg/store/cached_store.go	0.00%	5 Missing ⚠️
pkg/store/store_adapter.go	54.54%	4 Missing and 1 partial ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #2984      +/-   ##
==========================================
- Coverage   61.64%   61.32%   -0.33%     
==========================================
  Files         111      111              
  Lines       11120    11221     +101     
==========================================
+ Hits         6855     6881      +26     
- Misses       3526     3584      +58     
- Partials      739      756      +17     

Flag	Coverage Δ
combined	61.32% <23.58%> (-0.33%)	⬇️

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.

[julienrbrt]

nice work 👏🏾

[tac0turtle]

this seems blocking? since we are pruning data that will not be modified we should be able to handle it async. Can we get some benchmarks on what the potential slow down to a node operating at 100ms is going to experience with different settings

[julienrbrt]

If we want to extract it, then i suppose we should create a pruning package under internal and have it be a new component. It was to put it in submitting so it would be called by both syncer and executor.
Having it its own component will make it async.

[tac0turtle]

the performance change here is unknown, please provide numbers on how this affects a chain with different amounts of blocks to prune.