feat: Mendel HF (#105)

* feat(txpool): add EIP-7594 blob sidecar toggle

* feat: align eth_getFinalizedHeader/block with BSC validator-based finalization

---------

Co-authored-by: Matus Kysel <matus.kysel@bnbchain.org>
Co-authored-by: cbh876 <3930922419@qq.com>
Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>

Author: 4 people

CLAUDE.md

@@ -1,6 +1,79 @@
-# Reth Development Guide for AI Agents
+# BNB Chain Reth (bnb-chain/reth) — Development Guide
 
-This guide provides comprehensive instructions for AI agents working on the Reth codebase. It covers the architecture, development workflows, and critical guidelines for effective contributions.
+This guide provides comprehensive instructions for AI agents working on the **BNB Chain fork** of the Reth codebase. This is a production-grade execution layer client specifically adapted for **BNB Smart Chain (BSC)**.
+
+**Repository**: `bnb-chain/reth` (https://github.com/bnb-chain/reth)
+**Upstream**: Fork of `paradigmxyz/reth` (v1.7.0 baseline)
+**Main branch**: `main`
+
+---
+
+## Relationship: reth-bsc and reth
+
+`bnb-chain/reth` (this repo) is the **core library layer** — a fork of upstream `paradigmxyz/reth` with BSC-specific modifications (Parlia consensus, TrieDB, system transactions, custom RPC, etc.).
+
+`bnb-chain/reth-bsc` is the **application layer** that depends on this repo. It is the actual BSC node binary that imports crates from `bnb-chain/reth` as git dependencies. Issues reported in `reth-bsc` (e.g., RPC returning wrong data during staged sync) often have root causes in this repo's provider/storage layer.
+
+When fixing issues from `reth-bsc`:
+1. Trace the call path from RPC through the provider layer in this repo
+2. Apply fixes here in `bnb-chain/reth`
+3. The `reth-bsc` project will pick up fixes via git dependency updates
+
+---
+
+## BSC Fork Summary
+
+This fork adapts the Ethereum-focused Reth client for BNB Smart Chain. Key differences from upstream:
+
+| Aspect | Upstream Reth | BSC Fork |
+|--------|--------------|----------|
+| Consensus | PoS (Beacon Chain) | **Parlia** (Validator-based PoSA) |
+| Finalized Block | Beacon Chain determined | Validator snapshot based |
+| State Backend | MDBX only | **MDBX + TrieDB** (dual backend) |
+| System Txs | Not supported | Supported (`gas_limit == u64::MAX/2`) |
+| P2P Peers | Standard | **Proxied peer** support |
+| Custom RPC | Standard Ethereum | `eth_getFinalizedBlock`, `eth_getFinalizedHeader` |
+| Hardforks | Ethereum only | Ethereum + BSC-specific (Ramanujan → Pascal) |
+
+### BSC-Specific Features
+
+1. **Parlia Consensus Engine**: BSC's Proof-of-Staked-Authority (PoSA) consensus replacing Ethereum's PoS. Implementation in `examples/bsc-p2p/src/block_import/parlia.rs`. Canonical head: highest block number wins; for equal heights, lower hash wins.
+
+2. **TrieDB State Storage Backend**: Alternative state database alongside MDBX. Configured via `StateDbConfig` in `crates/config/src/config.rs`. Supports genesis init, staged sync, live sync, and io-uring. Dependencies from `bnb-chain/reth-bsc-triedb`.
+
+3. **BSC System Transactions**: Special transactions identified by `gas_limit == u64::MAX/2 && caller == beneficiary`. Exempted from block gas limit validation. Handled across all RPC tracers via `handle_bsc_system_transaction()` in `crates/rpc/rpc/src/debug.rs`.
+
+4. **Custom RPC Methods**: `eth_getFinalizedBlock(verified_validator_num)` and `eth_getFinalizedHeader(verified_validator_num)` in `crates/rpc/rpc-eth-api/src/core.rs` and `helpers/block.rs`.
+
+5. **Proxied Peer Support**: Enhanced P2P networking with proxy peer definitions in `crates/net/network/` and `crates/net/eth-wire-types/`.
+
+6. **Validator Block Snapshot Table**: BSC validator support integrated into the engine with a dedicated database table.
+
+7. **Blob Fee Validation**: Enhanced blob storage with extended time support and fee checks for EIP-4844 compatibility on BSC.
+
+8. **BSC Hardforks**: Ramanujan, Niels, MirrorSync, Bruno, Euler, Nano, Moran, Gibbs, Planck, Luban, Plato, Hertz, HertzFix, Kepler, Feynman, FeynmanFix, Haber, HaberFix, Bohr, Pascal, Prague — defined in `examples/bsc-p2p/src/chainspec.rs`.
+
+### Key BSC Code Locations
+
+- `examples/bsc-p2p/` — Complete BSC P2P node example (Parlia consensus, chainspec, genesis)
+- `crates/config/src/config.rs` — `StateDbConfig` for TrieDB/MDBX selection
+- `crates/rpc/rpc/src/debug.rs` — BSC system transaction handling in tracers
+- `crates/rpc/rpc-eth-api/src/core.rs` — Custom `eth_getFinalizedBlock` / `eth_getFinalizedHeader`
+- `crates/rpc/rpc-eth-api/src/helpers/block.rs` — Finalized block logic with validator count
+- `crates/transaction-pool/src/validate/eth.rs` — Blob fee and EIP-1559 validation for BSC
+- `crates/net/network/` — Proxied peer support
+- `crates/storage/provider/` — TrieDB integration in state provider
+
+### Custom Dependencies
+
+```toml
+# In Cargo.toml — BSC TrieDB support
+rust-eth-triedb = { git = "https://github.com/bnb-chain/reth-bsc-triedb.git", tag = "v0.0.1" }
+rust-eth-triedb-common = { ... }
+rust-eth-triedb-state-trie = { ... }
+```
+
+---
 
 ## Project Overview
 
@@ -10,21 +83,22 @@ Reth is a high-performance Ethereum execution client written in Rust, focusing o
 
 ### Core Components
 
-1. **Consensus (`crates/consensus/`)**: Validates blocks according to Ethereum consensus rules
-2. **Storage (`crates/storage/`)**: Hybrid database using MDBX + static files for optimal performance
-3. **Networking (`crates/net/`)**: P2P networking stack with discovery, sync, and transaction propagation
-4. **RPC (`crates/rpc/`)**: JSON-RPC server supporting all standard Ethereum APIs
+1. **Consensus (`crates/consensus/`)**: Validates blocks according to consensus rules (Parlia for BSC)
+2. **Storage (`crates/storage/`)**: Hybrid database using MDBX + static files + TrieDB (BSC) for optimal performance
+3. **Networking (`crates/net/`)**: P2P networking stack with discovery, sync, transaction propagation, and proxied peer support
+4. **RPC (`crates/rpc/`)**: JSON-RPC server supporting standard Ethereum APIs + BSC custom methods
 5. **Execution (`crates/evm/`, `crates/ethereum/`)**: Transaction execution and state transitions
 6. **Pipeline (`crates/stages/`)**: Staged sync architecture for blockchain synchronization
 7. **Trie (`crates/trie/`)**: Merkle Patricia Trie implementation with parallel state root computation
 8. **Node Builder (`crates/node/`)**: High-level node orchestration and configuration
 9. **The Consensus Engine (`crates/engine/`)**: Handles processing blocks received from the consensus layer with the Engine API (newPayload, forkchoiceUpdated)
+10. **Configuration (`crates/config/`)**: Node configuration including StateDbConfig for TrieDB/MDBX backend selection
 
 ### Key Design Principles
 
 - **Modularity**: Each crate can be used as a standalone library
 - **Performance**: Extensive use of parallelism, memory-mapped I/O, and optimized data structures
-- **Extensibility**: Traits and generic types allow for different implementations (Ethereum, Optimism, etc.)
+- **Extensibility**: Traits and generic types allow for different implementations (Ethereum, BSC, Optimism, etc.)
 - **Type Safety**: Strong typing throughout with minimal use of dynamic dispatch
 
 ## Development Workflow
@@ -175,7 +249,7 @@ Before submitting changes, ensure:
 5. **Commit Messages**: Follow conventional format (feat:, fix:, chore:, etc.)
 
 
-### Opening PRs against <https://github.com/paradigmxyz/reth>
+### Opening PRs against <https://github.com/bnb-chain/reth>
 
 Label PRs appropriately, first check the available labels and then apply the relevant ones:
 * when changes are RPC related, add A-rpc label
@@ -258,7 +332,7 @@ const TRACER_TIMEOUT: Duration = Duration::from_secs(5);
 **Document constraints and assumptions:**
 ```rust
 /// Returns heap size estimate.
-/// 
+///
 /// Note: May undercount shared references (Rc/Arc). For precise
 /// accounting, combine with an allocator-based approach.
 fn deep_size_of(&self) -> usize
@@ -314,7 +388,6 @@ GLOBAL_COUNTER.fetch_add(1, Ordering::SeqCst);
 
 Before adding a comment, ask: Would someone reading just the current code (no PR, no history) find this helpful?
 
-
 ### Example Contribution Workflow
 
 Let's say you want to fix a bug where external IP resolution fails on startup:

crates/engine/tree/src/persistence.rs

@@ -100,7 +100,6 @@ where
                             .send(MetricEvent::SyncHeight { height: block_number });
 
                         if self.pruner.is_pruning_needed(block_number) {
-                            // We log `PrunerOutput` inside the `Pruner`
                             let _ = self.prune_before(block_number)?;
                         }
                     }

crates/node/builder/src/launch/common.rs

@@ -557,6 +557,8 @@ impl<R, ChainSpec: EthChainSpec> LaunchContextWith<Attached<WithConfigs<ChainSpe
         ChainSpec: reth_chainspec::EthereumHardforks,
     {
         PrunerBuilder::new(self.prune_config())
+            .delete_limit(self.chain_spec().prune_delete_limit())
+            .timeout(PrunerBuilder::DEFAULT_TIMEOUT)
     }
 
     /// Loads the JWT secret for the engine API

crates/prune/prune/src/builder.rs

@@ -29,6 +29,9 @@ pub struct PrunerBuilder {
 }
 
 impl PrunerBuilder {
+    /// Default timeout for a prune run.
+    pub const DEFAULT_TIMEOUT: Duration = Duration::from_millis(100);
+
     /// Creates a new [`PrunerBuilder`] from the given [`PruneConfig`].
     pub fn new(pruner_config: PruneConfig) -> Self {
         Self::default()

crates/rpc/rpc-eth-api/src/core.rs

@@ -245,22 +245,26 @@ pub trait EthApi<
 
     /// Returns the finalized block header.
     ///
-    /// The `verified_validator_num` parameter is provided for BSC compatibility but is not used
-    /// in standard Ethereum. The finalized block is determined by the Beacon Chain consensus
-    /// (Casper FFG) and requires 2/3+ validator attestations.
+    /// BSC compatibility:
+    /// - `-1` uses ceil(validators/2)
+    /// - `-2` uses ceil(validators*2/3)
+    /// - `-3` uses all validators
+    /// - positive values override the threshold directly.
     #[method(name = "getFinalizedHeader")]
-    async fn finalized_header(&self, verified_validator_num: u64) -> RpcResult<Option<H>>;
+    async fn finalized_header(&self, verified_validator_num: i64) -> RpcResult<Option<H>>;
 
     /// Returns the finalized block.
     ///
-    /// The `verified_validator_num` parameter is provided for BSC compatibility but is not used
-    /// in standard Ethereum. The finalized block is determined by the Beacon Chain consensus
-    /// (Casper FFG) and requires 2/3+ validator attestations.
+    /// BSC compatibility:
+    /// - `-1` uses ceil(validators/2)
+    /// - `-2` uses ceil(validators*2/3)
+    /// - `-3` uses all validators
+    /// - positive values override the threshold directly.
     ///
     /// If `full` is true, the block object will contain all transaction objects,
     /// otherwise it will only contain the transaction hashes.
     #[method(name = "getFinalizedBlock")]
-    async fn finalized_block(&self, verified_validator_num: u64, full: bool) -> RpcResult<Option<B>>;
+    async fn finalized_block(&self, verified_validator_num: i64, full: bool) -> RpcResult<Option<B>>;
 
     /// `eth_simulateV1` executes an arbitrary number of transactions on top of the requested state.
     /// The transactions are packed into individual blocks. Overrides can be provided.
@@ -752,13 +756,13 @@ where
     }
 
     /// Handler for: `eth_getFinalizedHeader`
-    async fn finalized_header(&self, verified_validator_num: u64) -> RpcResult<Option<RpcHeader<T::NetworkTypes>>> {
+    async fn finalized_header(&self, verified_validator_num: i64) -> RpcResult<Option<RpcHeader<T::NetworkTypes>>> {
         trace!(target: "rpc::eth", verified_validator_num, "Serving eth_getFinalizedHeader");
         Ok(EthBlocks::rpc_finalized_header(self, verified_validator_num).await?)
     }
 
     /// Handler for: `eth_getFinalizedBlock`
-    async fn finalized_block(&self, verified_validator_num: u64, full: bool) -> RpcResult<Option<RpcBlock<T::NetworkTypes>>> {
+    async fn finalized_block(&self, verified_validator_num: i64, full: bool) -> RpcResult<Option<RpcBlock<T::NetworkTypes>>> {
         trace!(target: "rpc::eth", verified_validator_num, ?full, "Serving eth_getFinalizedBlock");
         Ok(EthBlocks::rpc_finalized_block(self, verified_validator_num, full).await?)
     }
@@ -974,4 +978,3 @@ where
         Ok(EthState::get_account_info(self, address, block).await?)
     }
 }
-