Skip to content
Draft
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
7 changes: 6 additions & 1 deletion bin/mega-evme/AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -22,9 +22,14 @@ Two engines: the in-tree sources run Satin; a spec from `Equivalence` to `Rex6`
- Command handlers follow staged flow: parse inputs → build state/env → execute → print summary/receipt/trace.
- Replay uses block executor flow, including pre-execution system calls and preceding transactions.
- Logging is structured via tracing macros, with explicit progress milestones.
- RPC diagnostics use `display_rpc_url`, which hides userinfo, path, query and fragment; cache identity uses `redact_rpc_url` and keeps the path and query.
Keep the two separate, and remove reqwest's URL before an HTTP error reaches a diagnostic.
`RedactedTransport` wraps the retry layer: the dependency classifies the original errors and consumes backoff hints before final diagnostics replace every JSON-RPC error message and `data` with a fixed local diagnostic (`server error message omitted`) while preserving the numeric error code.
- Output paths keep both human-readable summaries and optional machine artifacts (trace/state dump).

- The engine is decided where a command needs it (`cmd.rs` for `run`/`tx`, `replay::Cmd::engine` for a transaction replay, `block/cmd.rs` per block), always through `Engine` (`of_spec`, `of_block`, `of_chain`), and a Satin run's schedule through `common::satin_schedule`; both read the chain's activation table, so they agree. A transaction replay's engine is decided at the timestamp of the block the replay runs it in (its own, or the latest for a pending one), the one whose schedule it runs under: keep a new site to the same pair.
- The engine is decided where a command needs it (`cmd.rs` for `run`/`tx`, `replay::Cmd::engine` for a transaction replay, `block/cmd.rs` per block), always through `Engine` (`of_spec`, `of_block`, `of_chain`), and a Satin run's schedule through `common::satin_schedule`; both read the chain's activation table, so they agree.
A transaction replay's engine is decided at the timestamp of its mined block, the one whose schedule it runs under: keep a new site to the same pair.
Satin transaction replay refuses pending and genesis transactions, checks the fetched parent's number and hash, forks pre-state at that verified parent hash via EIP-1898 (`requireCanonical: true`), and resolves `BLOCKHASH` ancestors on demand by walking `parentHash` via `eth_getBlockByHash` (verifying each ancestor's hash and number).
- Output on Satin is additive to the legacy output: every legacy field keeps its name and meaning, and what only Satin counts goes in the `satin` object (`tests/integration.rs` checks it on every fixture pair).

## ANTI-PATTERNS
Expand Down
11 changes: 10 additions & 1 deletion bin/mega-evme/src/common/logging.rs
Original file line number Diff line number Diff line change
Expand Up @@ -12,6 +12,8 @@ use clap::Parser;
use tracing::Level;
use tracing_subscriber::{fmt, EnvFilter};

use super::sanitize_terminal_text;

/// Logging configuration arguments.
#[derive(Debug, Clone, Default, Parser)]
pub struct LogArgs {
Expand Down Expand Up @@ -73,7 +75,14 @@ impl LogArgs {
.init();
}
Err(e) => {
eprintln!("Failed to create log file '{}': {}", log_file.display(), e);
eprintln!(
"{}",
sanitize_terminal_text(&format!(
"Failed to create log file '{}': {}",
log_file.display(),
e
))
);
fmt()
.with_env_filter(filter)
.with_target(show_target)
Expand Down
64 changes: 51 additions & 13 deletions bin/mega-evme/src/common/provider/mod.rs
Original file line number Diff line number Diff line change
Expand Up @@ -35,7 +35,7 @@ use tracing::{debug, info, warn};
pub use self::cache_store::{ExternalEnvSnapshot, RpcCacheStore};
use self::{
cache_store::CacheFileEnvelope,
transport::{CachingTransport, ReplayTransport, TransportCache},
transport::{CachingTransport, RedactedTransport, ReplayTransport, TransportCache},
};
use super::{EvmeError, Result};

Expand Down Expand Up @@ -166,7 +166,7 @@ impl RpcArgs {
}
let provider = build_bare_op_provider(self.build_retry_client(url));
info!(
rpc_url = %redact_rpc_url(rpc_url_str),
rpc_url = %display_rpc_url(rpc_url_str),
max_retries = self.max_retries,
backoff_ms = self.backoff_ms,
"Built RPC provider (cache disabled)",
Expand Down Expand Up @@ -226,7 +226,7 @@ impl RpcArgs {
.connect_client(client);

info!(
rpc_url = %redact_rpc_url(rpc_url_str),
rpc_url = %display_rpc_url(rpc_url_str),
cache_size = self.cache_size,
max_retries = self.max_retries,
backoff_ms = self.backoff_ms,
Expand Down Expand Up @@ -350,7 +350,7 @@ impl RpcArgs {
let chain_id = provider.get_chain_id().await.map_err(|e| {
EvmeError::RpcError(format!(
"Failed to fetch chain ID from '{}': {e}",
redact_rpc_url(rpc_url_str)
display_rpc_url(rpc_url_str)
))
})?;

Expand All @@ -372,7 +372,7 @@ impl RpcArgs {
}

info!(
rpc_url = %redact_rpc_url(rpc_url_str),
rpc_url = %display_rpc_url(rpc_url_str),
path = %path.display(),
chain_id,
"Built RPC provider (capture to cache file)",
Expand All @@ -394,15 +394,17 @@ impl RpcArgs {
}

/// Build an `RpcClient` over an arbitrary transport, wired with the configured
/// retry layer (or bare when `max_retries == 0`). `url` is used only to detect
/// whether the endpoint is local.
/// retry layer (or bare when `max_retries == 0`). `url` is used to detect whether
/// the endpoint is local; [`RedactedTransport`] wraps the outermost layer so the
/// retry policy sees original server errors before final diagnostics replace them.
fn build_client<T: alloy_transport::IntoBoxTransport>(
&self,
transport: T,
url: &alloy_transport_http::reqwest::Url,
) -> RpcClient {
let is_local =
url.host_str().is_some_and(|h| h == "localhost" || h == "127.0.0.1" || h == "::1");
let max_retries = self.max_retries;
if self.max_retries > 0 {
let policy = RateLimitRetryPolicy::default().or(|err: &TransportError| {
matches!(err, RpcError::Transport(TransportErrorKind::Custom(_)))
Expand All @@ -413,16 +415,22 @@ impl RpcArgs {
self.compute_units_per_sec,
policy,
);
ClientBuilder::default().layer(retry).transport(transport, is_local)
ClientBuilder::default()
.layer(tower::layer::layer_fn(move |inner| {
RedactedTransport::new(inner, max_retries)
}))
.layer(retry)
.transport(transport, is_local)
} else {
ClientBuilder::default().transport(transport, is_local)
ClientBuilder::default()
.transport(RedactedTransport::new(transport, max_retries), is_local)
}
}

/// Resolve the chain ID by issuing `eth_chainId` against a throwaway
/// cache-less provider using the configured retry policy.
async fn resolve_chain_id(&self, url: alloy_transport_http::reqwest::Url) -> Result<u64> {
let url_str = redact_rpc_url(url.as_str());
let url_str = display_rpc_url(url.as_str());
let bare = build_bare_op_provider(self.build_retry_client(url));
bare.get_chain_id().await.map_err(|e| {
EvmeError::RpcError(format!("Failed to fetch chain ID from '{}': {e}", url_str))
Expand Down Expand Up @@ -461,7 +469,7 @@ fn build_bare_op_provider(client: RpcClient) -> OpProvider {
)
}

/// The URL with any userinfo removed, for a log line, an error, or a cache file name.
/// The normalized endpoint identity used for cache file names, with any userinfo removed.
///
/// Userinfo is the part of the authority before its last `@`, as the URL standard reads it, so a
/// password holding an `@` goes whole. It is removed from the text itself, so it holds for a URL
Expand All @@ -484,16 +492,27 @@ fn normalized(raw: &str) -> String {
.map_or_else(|_| raw.to_string(), |u| u.to_string())
}

/// The public origin of an RPC URL, without userinfo, path, query or fragment.
///
/// This is for logs and errors only: cache keys keep the whole endpoint identity through
/// `redact_rpc_url`. An unparseable URL is hidden whole rather than guessed at.
pub(crate) fn display_rpc_url(raw: &str) -> String {
raw.parse::<alloy_transport_http::reqwest::Url>()
.ok()
.filter(|url| url.host_str().is_some())
.map_or_else(|| "<redacted RPC URL>".to_string(), |url| url.origin().ascii_serialization())
}

/// Parses `--rpc`. The transport speaks HTTP, so any other scheme is refused here, before the URL
/// reaches a library whose error text would repeat it whole.
fn parse_rpc_url(raw: &str) -> Result<alloy_transport_http::reqwest::Url> {
let url: alloy_transport_http::reqwest::Url = raw.parse().map_err(|e| {
EvmeError::RpcError(format!("Invalid RPC URL '{}': {e}", redact_rpc_url(raw)))
EvmeError::RpcError(format!("Invalid RPC URL '{}': {e}", display_rpc_url(raw)))
})?;
if !matches!(url.scheme(), "http" | "https") {
return Err(EvmeError::InvalidInput(format!(
"Invalid RPC URL '{}': it has to start with http:// or https://",
redact_rpc_url(raw)
display_rpc_url(raw)
)));
}
Ok(url)
Expand Down Expand Up @@ -555,6 +574,19 @@ mod tests {

use super::*;

#[test]
fn test_display_rpc_url_hides_every_credential_location() {
for url in [
"https://alice:secret@rpc.example:8443/v2/path-secret?key=query-secret#fragment-secret",
"https://rpc.example:8443/another-secret",
] {
assert_eq!(display_rpc_url(url), "https://rpc.example:8443");
}
for url in ["alice:secret@rpc.example/path-secret", "http://bad host/path-secret"] {
assert_eq!(display_rpc_url(url), "<redacted RPC URL>");
}
}

/// Explicit `--rpc.cache-dir` is used verbatim. The file names the chain and a hash of the
/// endpoint, and the hash does not change when only the userinfo does.
#[test]
Expand All @@ -568,6 +600,12 @@ mod tests {
assert!(!name.contains("secret") && !name.contains("alice") && !name.contains("example"));
assert_eq!(name, rpc_cache_file_name(4326, "http://example.com/rpc"));
assert_ne!(name, rpc_cache_file_name(4326, "http://other.example/rpc"));
assert_ne!(name, rpc_cache_file_name(4326, "http://example.com/another-path"));
assert_ne!(name, rpc_cache_file_name(4326, "http://example.com/rpc?key=one"));
assert_ne!(
rpc_cache_file_name(4326, "http://example.com/rpc?key=one"),
rpc_cache_file_name(4326, "http://example.com/rpc?key=two"),
);
}

#[test]
Expand Down
98 changes: 98 additions & 0 deletions bin/mega-evme/src/common/provider/transport.rs
Original file line number Diff line number Diff line change
Expand Up @@ -20,6 +20,104 @@ use serde::{Deserialize, Serialize};

use crate::common::{EvmeError, Result};

/// Fixed local diagnostic replacing every server-supplied JSON-RPC error message so server error
/// payloads can never disclose endpoint credentials or other server-echoed text.
const LOCAL_RPC_ERROR_MESSAGE: &str = "server error message omitted";

/// Hides transport diagnostics only after the dependency has applied its retry policy.
/// The inner future runs without tracing because dependency spans can contain the endpoint URL.
#[derive(Clone)]
pub(super) struct RedactedTransport<T> {
inner: T,
max_retries: u32,
}

impl<T> RedactedTransport<T> {
pub(super) fn new(inner: T, max_retries: u32) -> Self {
Self { inner, max_retries }
}
}

impl<T: alloy_transport::IntoBoxTransport> tower::Service<RequestPacket> for RedactedTransport<T> {
type Response = ResponsePacket;
type Error = TransportError;
type Future = TransportFut<'static>;

fn poll_ready(
&mut self,
cx: &mut std::task::Context<'_>,
) -> std::task::Poll<std::result::Result<(), Self::Error>> {
self.inner.poll_ready(cx).map_err(|error| redact_transport_error(error, self.max_retries))
}

fn call(&mut self, req: RequestPacket) -> Self::Future {
use tracing::{instrument::WithSubscriber, subscriber::NoSubscriber};

let future =
tracing::subscriber::with_default(NoSubscriber::default(), || self.inner.call(req));
let max_retries = self.max_retries;
Box::pin(async move {
let mut response = future
.with_subscriber(NoSubscriber::default())
.await
.map_err(|error| redact_transport_error(error, max_retries))?;
match &mut response {
ResponsePacket::Single(response) => redact_error_response(response),
ResponsePacket::Batch(responses) => {
responses.iter_mut().for_each(redact_error_response)
}
}
Ok(response)
})
}
}

fn redact_error_payload(error: &mut alloy_json_rpc::ErrorPayload) {
error.message = LOCAL_RPC_ERROR_MESSAGE.into();
// Arbitrary error data need not be interpreted or re-serialized for a diagnostic.
// Backoff hints have already been consumed by the inner retry layer.
error.data = None;
}

fn redact_error_response(response: &mut alloy_json_rpc::Response) {
if let alloy_json_rpc::ResponsePayload::Failure(error) = &mut response.payload {
redact_error_payload(error);
}
}

fn redact_transport_error(error: TransportError, max_retries: u32) -> TransportError {
use alloy_provider::transport::RpcError;
match error {
RpcError::ErrorResp(mut error) => {
redact_error_payload(&mut error);
RpcError::ErrorResp(error)
}
RpcError::Transport(TransportErrorKind::Custom(error)) => {
match error.downcast::<alloy_transport_http::reqwest::Error>() {
Ok(error) => TransportErrorKind::custom((*error).without_url()),
Err(error) if error.to_string().starts_with("Max retries exceeded ") => {
TransportErrorKind::custom_str(&format!(
"Max retries exceeded ({max_retries} retries; details redacted)"
))
}
Err(_) => TransportErrorKind::custom_str("RPC transport error (details redacted)"),
}
}
RpcError::Transport(TransportErrorKind::HttpError(mut error)) => {
error.body = "<redacted HTTP response body>".to_string();
RpcError::Transport(TransportErrorKind::HttpError(error))
}
RpcError::DeserError { err, .. } => RpcError::DeserError {
err: serde_json::Error::io(std::io::Error::new(
std::io::ErrorKind::InvalidData,
format!("invalid RPC response at line {}, column {}", err.line(), err.column()),
)),
text: "<redacted HTTP response body>".to_string(),
},
error => error,
}
}

/// A single entry in the transport-level cache.
#[derive(Debug, Serialize, Deserialize)]
struct TransportCacheEntry {
Expand Down
16 changes: 14 additions & 2 deletions bin/mega-evme/src/common/state.rs
Original file line number Diff line number Diff line change
Expand Up @@ -2,6 +2,7 @@

use std::{collections::BTreeMap, path::PathBuf, str::FromStr};

use alloy_eips::BlockId;
use alloy_network::Network;
use alloy_primitives::{Address, BlockNumber, Bytes, B256, U256};
use alloy_provider::Provider;
Expand Down Expand Up @@ -820,8 +821,19 @@ where
BlockNumber::from(latest_block)
};

// Create AlloyDB with the provider and block number
let alloy_db = AlloyDB::new(provider, block_num.into());
Self::new_forked_at(provider, block_num.into(), prestate, block_hashes)
}

/// Create a new forked state bound to an explicit EIP-1898 [`BlockId`] (number or hash),
/// with optional prestate overrides and block hash overrides.
pub fn new_forked_at(
provider: P,
block_id: BlockId,
prestate: EvmState,
block_hashes: HashMap<u64, B256>,
) -> Result<Self> {
// Create AlloyDB with the provider and block selector
let alloy_db = AlloyDB::new(provider, block_id);

// Wrap the AlloyDB for synchronous access with the runtime
let wrapped_db =
Expand Down
Loading
Loading