From dfa252718f31c0286043cbd94e7d164ab39c9afd Mon Sep 17 00:00:00 2001
From: init4samwise <samwise@init4.technology>
Date: Sat, 28 Feb 2026 15:03:32 +0000
Subject: [PATCH] docs: Document intentional RPC endpoint block parameter
 defaults

- eth_call uses 'latest' for current state inspection
- eth_estimateGas uses 'pending' for new transaction estimation
- eth_createAccessList would use 'pending' when implemented

Resolves ENG-1904
---
 crates/rpc/src/eth/endpoints.rs | 9 +++++++++
 crates/rpc/src/eth/mod.rs       | 1 +
 2 files changed, 10 insertions(+)

diff --git a/crates/rpc/src/eth/endpoints.rs b/crates/rpc/src/eth/endpoints.rs
index 23f099f..74e23f1 100644
--- a/crates/rpc/src/eth/endpoints.rs
+++ b/crates/rpc/src/eth/endpoints.rs
@@ -33,6 +33,11 @@ use tracing::{Instrument, debug, trace_span};
 use trevm::{EstimationResult, MIN_TRANSACTION_GAS, revm::context::result::ExecutionResult};
 
 /// Args for `eth_estimateGas` and `eth_call`.
+/// 
+/// **Note on default block parameters:**
+/// - `eth_call` defaults to `latest` - used for inspecting current chain state
+/// - `eth_estimateGas` defaults to `pending` - used for estimating new transactions with newest header info
+/// - `eth_createAccessList` (when implemented) would default to `pending` - same rationale as estimateGas
 #[derive(Debug, Deserialize)]
 pub(super) struct TxParams(
     TransactionRequest,
@@ -424,6 +429,8 @@ where
     Host: FullNodeComponents,
     Signet: Pnt,
 {
+    // eth_call defaults to `latest` for current state inspection
+    // (differs from eth_estimateGas which uses `pending` for new transactions)
     let id = block.unwrap_or(BlockId::latest());
 
     // this span is verbose yo.
@@ -526,6 +533,8 @@ where
     Host: FullNodeComponents,
     Signet: Pnt,
 {
+    // eth_estimateGas defaults to `pending` for new transaction estimation
+    // (differs from eth_call which uses `latest` for current state inspection)
     let id = block.unwrap_or(BlockId::pending());
 
     // this span is verbose yo.
diff --git a/crates/rpc/src/eth/mod.rs b/crates/rpc/src/eth/mod.rs
index 0d8c131..33c2241 100644
--- a/crates/rpc/src/eth/mod.rs
+++ b/crates/rpc/src/eth/mod.rs
@@ -85,6 +85,7 @@ where
         .route("signTransaction", not_supported)
         .route("signTypedData", not_supported)
         .route("getProof", not_supported)
+        // eth_createAccessList would use `pending` when implemented (like estimateGas)
         .route("createAccessList", not_supported)
         .route("newPendingTransactionFilter", not_supported)
 }