From 594e660f4a861bdbcbe268f0d0a31d86d2fe1ebb Mon Sep 17 00:00:00 2001
From: Wataxi <wataxiwajojo@protonmail.com>
Date: Fri, 24 Apr 2026 02:09:23 +0800
Subject: [PATCH] fix(rpc): include block numbers in `BlockRangeExceedsHead`
 error

`FilterBlockRangeError::BlockRangeExceedsHead` and `EthFilterError::BlockRangeExceedsHead` now carry `requested` and `head`, matching the existing `EthApiError::RequestBeyondHead` pattern. Callers can't know the current head, so surfacing it makes the error actionable.

Before:
```
block range extends beyond current head block
```

After:
```
block range extends beyond current head block: requested 21000100, head 21000000
```
---
 crates/rpc/rpc-eth-types/src/logs_utils.rs | 24 +++++++++++++++++-----
 crates/rpc/rpc/src/eth/filter.rs           | 20 +++++++++++++-----
 2 files changed, 34 insertions(+), 10 deletions(-)

diff --git a/crates/rpc/rpc-eth-types/src/logs_utils.rs b/crates/rpc/rpc-eth-types/src/logs_utils.rs
index 4eb2ee7c001..3abf4aea759 100644
--- a/crates/rpc/rpc-eth-types/src/logs_utils.rs
+++ b/crates/rpc/rpc-eth-types/src/logs_utils.rs
@@ -169,7 +169,10 @@ pub fn get_filter_block_range(
 
     // we cannot query blocks that don't exist yet
     if to_block_number > info.best_number {
-        return Err(FilterBlockRangeError::BlockRangeExceedsHead);
+        return Err(FilterBlockRangeError::BlockRangeExceedsHead {
+            requested: to_block_number,
+            head: info.best_number,
+        });
     }
 
     Ok((from_block_number, to_block_number))
@@ -184,8 +187,13 @@ pub enum FilterBlockRangeError {
     #[error("invalid block range params")]
     InvalidBlockRange,
     /// Block range extends beyond current head
-    #[error("block range extends beyond current head block")]
-    BlockRangeExceedsHead,
+    #[error("block range extends beyond current head block: requested {requested}, head {head}")]
+    BlockRangeExceedsHead {
+        /// The requested `toBlock` number
+        requested: u64,
+        /// The current head block number
+        head: u64,
+    },
 }
 
 #[cfg(test)]
@@ -227,7 +235,10 @@ mod tests {
         let to = 15000002u64;
         let info = ChainInfo { best_number: 15000000, ..Default::default() };
         let err = get_filter_block_range(Some(from), Some(to), info.best_number, info).unwrap_err();
-        assert_eq!(err, FilterBlockRangeError::BlockRangeExceedsHead);
+        assert_eq!(
+            err,
+            FilterBlockRangeError::BlockRangeExceedsHead { requested: to, head: info.best_number }
+        );
     }
 
     #[test]
@@ -263,7 +274,10 @@ mod tests {
         let to = 200;
         let info = ChainInfo { best_number: 150, ..Default::default() };
         let err = get_filter_block_range(Some(from), Some(to), 0, info).unwrap_err();
-        assert_eq!(err, FilterBlockRangeError::BlockRangeExceedsHead);
+        assert_eq!(
+            err,
+            FilterBlockRangeError::BlockRangeExceedsHead { requested: to, head: info.best_number }
+        );
     }
 
     #[test]
diff --git a/crates/rpc/rpc/src/eth/filter.rs b/crates/rpc/rpc/src/eth/filter.rs
index d3f72159ba8..591fd95af2e 100644
--- a/crates/rpc/rpc/src/eth/filter.rs
+++ b/crates/rpc/rpc/src/eth/filter.rs
@@ -564,7 +564,10 @@ where
                 if let Some(t) = to &&
                     t > info.best_number
                 {
-                    return Err(EthFilterError::BlockRangeExceedsHead);
+                    return Err(EthFilterError::BlockRangeExceedsHead {
+                        requested: t,
+                        head: info.best_number,
+                    });
                 }
 
                 if let Some(f) = from &&
@@ -942,8 +945,13 @@ pub enum EthFilterError {
     #[error("invalid block range params")]
     InvalidBlockRangeParams,
     /// Block range extends beyond current head.
-    #[error("block range extends beyond current head block")]
-    BlockRangeExceedsHead,
+    #[error("block range extends beyond current head block: requested {requested}, head {head}")]
+    BlockRangeExceedsHead {
+        /// The requested `toBlock` number
+        requested: u64,
+        /// The current head block number
+        head: u64,
+    },
     /// Query scope is too broad.
     #[error("query exceeds max block range {0}")]
     QueryExceedsMaxBlocks(u64),
@@ -979,7 +987,7 @@ impl From<EthFilterError> for jsonrpsee::types::error::ErrorObject<'static> {
             err @ (EthFilterError::InvalidBlockRangeParams |
             EthFilterError::QueryExceedsMaxBlocks(_) |
             EthFilterError::QueryExceedsMaxResults { .. } |
-            EthFilterError::BlockRangeExceedsHead) => {
+            EthFilterError::BlockRangeExceedsHead { .. }) => {
                 rpc_error_with_code(jsonrpsee::types::error::INVALID_PARAMS_CODE, err.to_string())
             }
         }
@@ -996,7 +1004,9 @@ impl From<logs_utils::FilterBlockRangeError> for EthFilterError {
     fn from(err: logs_utils::FilterBlockRangeError) -> Self {
         match err {
             logs_utils::FilterBlockRangeError::InvalidBlockRange => Self::InvalidBlockRangeParams,
-            logs_utils::FilterBlockRangeError::BlockRangeExceedsHead => Self::BlockRangeExceedsHead,
+            logs_utils::FilterBlockRangeError::BlockRangeExceedsHead { requested, head } => {
+                Self::BlockRangeExceedsHead { requested, head }
+            }
         }
     }
 }