feat(rpc): refactor event provider to use structured error types (#1266)

Co-authored-by: Claude Sonnet 4.5 <noreply@anthropic.com>

Author: dancoombs

.claude/hooks/pre-commit-checks.sh

@@ -0,0 +1,30 @@
+#!/bin/bash
+# Pre-commit checks hook for rundler
+# Runs cargo fmt and clippy before allowing git commit
+
+set -e
+
+INPUT=$(cat)
+COMMAND=$(echo "$INPUT" | jq -r '.tool_input.command // empty')
+
+# Only run checks if this is a git commit command
+if ! echo "$COMMAND" | grep -q "git commit"; then
+  exit 0
+fi
+
+PROJECT_DIR=$(echo "$INPUT" | jq -r '.cwd // empty')
+cd "$PROJECT_DIR"
+
+echo "Running cargo +nightly fmt --all..." >&2
+if ! cargo +nightly fmt --all; then
+  echo "BLOCKED: formatting failed" >&2
+  exit 2
+fi
+
+echo "Running cargo clippy..." >&2
+if ! cargo clippy --all --all-features --tests -- -D warnings; then
+  echo "BLOCKED: clippy check failed" >&2
+  exit 2
+fi
+
+exit 0

.claude/settings.json

@@ -0,0 +1,15 @@
+{
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "Bash",
+        "hooks": [
+          {
+            "type": "command",
+            "command": ".claude/hooks/pre-commit-checks.sh"
+          }
+        ]
+      }
+    ]
+  }
+}

AGENTS.md

@@ -23,6 +23,9 @@ Rundler is a Rust workspace.
 - Lint must be clean: `cargo clippy --all --all-features --tests -- -D warnings`.
 - Follow Rust naming defaults: modules/files `snake_case`, types/traits `UpperCamelCase`, constants `SCREAMING_SNAKE_CASE`.
 - Keep crate names in the established `rundler-*` pattern.
+- Use the `{variable}` shorthand syntax in format strings, logs, and error messages (e.g. `format!("transaction {tx_hash} missing")` instead of `format!("transaction {} missing", tx_hash)`).
+- Always import types rather than using inline paths (e.g. `use crate::eth::events::EventProviderError;` then `EventProviderError`, not `crate::eth::events::EventProviderError` inline). Use `as` renames to resolve conflicts.
+- Always qualify function calls with their module or type (e.g. `EthRpcError::from(...)`, `Vec::new()`), but do not qualify types/structs/enums unless needed to resolve ambiguity.
 
 ## Testing Guidelines
 - Add or update tests for every behavior change (`#[test]` / `#[tokio::test]` near the changed module is common here).

crates/rpc/src/eth/api.rs

@@ -27,7 +27,10 @@ use super::{
     error::{EthResult, EthRpcError},
     router::EntryPointRouter,
 };
-use crate::types::{RpcGasEstimate, RpcUserOperationByHash, RpcUserOperationReceipt};
+use crate::{
+    eth::events::EventProviderError,
+    types::{RpcGasEstimate, RpcUserOperationByHash, RpcUserOperationReceipt},
+};
 
 pub(crate) struct EthApi<P> {
     pub(crate) chain_spec: ChainSpec,
@@ -143,7 +146,12 @@ where
         > = vec![];
 
         for ep in self.router.entry_points() {
-            futs.push(Box::pin(self.router.get_mined_by_hash(ep, hash)));
+            futs.push(Box::pin(async move {
+                self.router
+                    .get_mined_by_hash(ep, hash)
+                    .await
+                    .map_err(EthRpcError::from)
+            }));
         }
         futs.push(Box::pin(self.get_pending_user_operation_by_hash(hash)));
 
@@ -164,30 +172,52 @@ where
         }
         let tag = tag.unwrap_or(BlockTag::Latest);
 
-        let bundle_transaction: Option<B256> = match tag {
-            BlockTag::Pending => {
-                if !self.chain_spec.flashblocks_enabled {
-                    return Err(EthRpcError::InvalidParams(
-                        "Unsupported feature: preconfirmation".to_string(),
-                    ));
-                }
-                let op_status = self
-                    .pool
-                    .get_op_status(hash)
-                    .await
-                    .map_err(EthRpcError::from)?;
+        if tag == BlockTag::Pending {
+            if !self.chain_spec.flashblocks_enabled {
+                return Err(EthRpcError::InvalidParams(
+                    "Pending block tag is not supported on this network".to_string(),
+                ));
+            }
 
-                op_status
-                    .and_then(|s| s.preconf_info)
-                    .map(|info| info.tx_hash)
+            // Preconfirmed check. If not found fallthrough to pending check.
+            let op_status = self
+                .pool
+                .get_op_status(hash)
+                .await
+                .map_err(EthRpcError::from)?;
+
+            if let Some(op_status) = op_status
+                && let Some(preconf_info) = op_status.preconf_info
+            {
+                let ret = self
+                    .router
+                    .get_receipt(&op_status.entry_point, hash, Some(preconf_info.tx_hash))
+                    .await;
+                match ret {
+                    Ok(Some(receipt)) => return Ok(Some(receipt)),
+                    Ok(None) => {
+                        // fallthrough to pending if not found
+                        tracing::warn!(
+                            "no receipt found for preconfirmed user operation {hash}. Treating as pending."
+                        );
+                    }
+                    Err(EventProviderError::Provider(e)) => {
+                        return Err(EthRpcError::from(EventProviderError::Provider(e)));
+                    }
+                    _ => {
+                        // fallthrough to pending on unexpected errors related to consistency issues or invalid receipts
+                        tracing::warn!(
+                            "unexpected error fetching receipt for preconfirmed user operation {hash}. Treating as pending: {ret:?}"
+                        );
+                    }
+                };
             }
-            BlockTag::Latest => None,
         };
 
         let futs = self
             .router
             .entry_points()
-            .map(|ep| self.router.get_receipt(ep, hash, bundle_transaction));
+            .map(|ep| self.router.get_receipt(ep, hash, None));
         let results = future::try_join_all(futs).await?;
         Ok(results.into_iter().find_map(|x| x))
     }

crates/rpc/src/eth/error.rs

@@ -27,7 +27,10 @@ use rundler_types::{
 };
 use serde::Serialize;
 
-use crate::error::{rpc_err, rpc_err_with_data};
+use crate::{
+    error::{rpc_err, rpc_err_with_data},
+    eth::events::EventProviderError,
+};
 
 // Error codes borrowed from jsonrpsee
 // INVALID_REQUEST_CODE = -32600
@@ -472,6 +475,7 @@ struct ProviderErrorWithContext {
 
 impl From<ProviderErrorWithContext> for EthRpcError {
     fn from(e: ProviderErrorWithContext) -> Self {
+        // Log the full error details at ERROR level for debugging
         let inner_msg = match &e.error {
             ProviderError::RPC(rpc_error) => match rpc_error {
                 RpcError::ErrorResp(error_payload) => {
@@ -498,15 +502,16 @@ impl From<ProviderErrorWithContext> for EthRpcError {
                 format!("other error: {}", error)
             }
         };
-        if let Some(context_msg) = e.context {
-            Self::Internal(anyhow::anyhow!(
-                "{}: provider error: {}",
-                context_msg,
-                inner_msg
-            ))
+
+        // Log full error details for debugging
+        if let Some(context_msg) = &e.context {
+            tracing::error!("{}: provider error: {}", context_msg, inner_msg);
         } else {
-            Self::Internal(anyhow::anyhow!("provider error: {}", inner_msg))
+            tracing::error!("provider error: {}", inner_msg);
         }
+
+        // Return generic error message to user
+        Self::Internal(anyhow::anyhow!("internal error: rpc provider error"))
     }
 }
 
@@ -518,6 +523,24 @@ impl From<ProviderError> for ProviderErrorWithContext {
         }
     }
 }
+
+impl From<EventProviderError> for EthRpcError {
+    fn from(e: EventProviderError) -> Self {
+        match e {
+            // Reuse existing ProviderError conversion for all provider errors
+            EventProviderError::Provider(provider_err) => Self::from(ProviderErrorWithContext {
+                error: provider_err,
+                context: None,
+            }),
+            // Log full details server-side, return generic message to user
+            other => {
+                tracing::error!("event provider error: {}", other);
+                Self::Internal(anyhow::anyhow!("internal error: event provider error"))
+            }
+        }
+    }
+}
+
 impl From<GasEstimationError> for EthRpcError {
     fn from(e: GasEstimationError) -> Self {
         match e {