Skip to content

Conversation

@ncitron
Copy link
Collaborator

@ncitron ncitron commented Jun 9, 2025

Summary

This PR implements a flexible historical block provider architecture that enables chain-specific historical block retrieval mechanisms while maintaining security through verified execution provider access.

🚨 Breaking Changes

  • EIP-2935 provider moved from block cache to historical providers module
  • Block cache no longer handles historical EIP-2935 lookups directly

✨ Key Features

  • Pluggable architecture: HistoricalBlockProvider trait allows chain-specific implementations
  • Enhanced security: All storage operations use verified account proofs instead of untrusted RPC calls
  • Network-specific providers: Type-safe implementations prevent cross-chain misuse
  • Block hash support: Historical blocks can be retrieved by both number and hash
  • DRY compliance: Linea provider reuses existing consensus verification logic

🏗️ Architecture Changes

Core Module (core/src/execution/providers/historical/)

  • HistoricalBlockProvider trait: Defines interface for historical block sources
  • Eip2935Provider: Retrieves blocks using EIP-2935 ring buffer contract verification
  • Integration with RpcExecutionProvider and VerifiableApiExecutionProvider

Network-Specific Implementations

  • Ethereum/OpStack: Use Eip2935Provider for standardized historical block access
  • Linea: Custom LineaHistoricalProvider in linea crate with signature validation

🔒 Security Improvements

  1. Verified storage access: Replace untrusted RPC calls with account proof verification
  2. Shared verification logic: Linea provider reuses consensus layer signature validation
  3. Consistent validation: All blocks validated using network-specific rules
  4. Cache isolation: Historical blocks don't interfere with block cache consistency

🛠️ Technical Implementation

EIP-2935 Provider

// Secure storage verification using execution provider
let account = execution_provider
    .get_account(contract_address, &[slot], false, latest_hash.into())
    .await?;
    
// Verify block hash matches stored value
if target_block.header().hash() == stored_hash {
    Ok(Some(target_block))
}

Linea Provider Integration

// Reuse existing consensus verification
match verify_block(self.unsafe_signer, &block) {
    Ok(()) => Ok(Some(block)),
    Err(e) => Err(eyre\!("Linea block validation failed: {}", e)),
}

Block Retrieval Flow

  1. Block cache check: First try cached blocks
  2. Historical provider: If not cached and not latest, try historical provider
  3. Verification: All historical blocks validated before return
  4. No caching: Historical blocks bypass cache to maintain consistency

📦 Module Organization

  • core/execution/providers/historical/: Core trait and EIP-2935 implementation
  • linea/src/historical.rs: Linea-specific historical provider
  • Updated builders: All network builders use appropriate historical providers

🧪 Testing & Quality

  • ✅ All existing tests pass
  • ✅ Clippy warnings resolved
  • ✅ Code formatted with cargo fmt
  • ✅ Type safety maintained across all providers
  • ✅ Backward compatibility for non-historical block operations

📋 Migration Guide

For applications using EIP-2935 functionality:

  • No API changes: Historical block retrieval works transparently
  • Enhanced security: Storage verification now uses account proofs
  • Better performance: Historical lookups no longer interfere with block caching

🔍 Files Changed

  • Core providers: Moved and enhanced EIP-2935 implementation
  • Network builders: Updated to use historical providers
  • Linea module: Added dedicated historical provider
  • Type annotations: Fixed compilation issues in verifiable API server

This implementation provides a secure, extensible foundation for historical block access while maintaining the existing API surface and improving overall system security.

ncitron added 3 commits June 9, 2025 16:52
Implement a flexible historical block provider architecture that enables
chain-specific historical block retrieval mechanisms while maintaining
security through verified execution provider access.

BREAKING CHANGE: Move EIP-2935 provider from block cache to historical providers

Key improvements:
- Add HistoricalBlockProvider trait for pluggable historical block sources
- Implement EIP-2935 provider for Ethereum/OpStack using verified storage access
- Move Linea historical provider to linea crate with shared verification logic
- Remove dependency on untrusted RPC calls for storage verification
- Support block retrieval by both number and hash through block prefetching
- Integrate with existing execution providers without breaking block caching

Technical details:
- Historical blocks bypass block cache to avoid consistency detection interference
- EIP-2935 provider validates blocks against ring buffer at address 0x0000...2935
- Linea provider reuses existing consensus signature verification for DRY compliance
- All storage operations use execution provider's verified account access
- Network-specific providers ensure type safety and prevent misuse

Security enhancements:
- Replace untrusted RPC storage reads with verified account proofs
- Maintain same verification standards as consensus layers
- Prevent historical block caching that could interfere with consistency
- Ensure all block validation uses network-specific rules
Use conditional async_trait annotations for wasm32 target compatibility.
All historical providers now compile successfully for wasm32-unknown-unknown target.
Add comprehensive validation to ensure requested blocks are within the
EIP-2935 ring buffer range before attempting storage lookups.

- Check if target block is outside ring buffer (too old)
- Check if target block is in the future (beyond latest)
- Provide clear error messages with block numbers and buffer size
- Prevent unnecessary storage operations for out-of-range blocks
@ncitron ncitron merged commit c9a1fd7 into master Jun 9, 2025
6 checks passed
@ncitron ncitron deleted the historical-block-provider branch June 9, 2025 21:07
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants