From 42a40441ab6487584009aa87121243c0808c44dd Mon Sep 17 00:00:00 2001 From: Soheima M Date: Wed, 13 May 2026 17:27:47 +0000 Subject: [PATCH] docs(flashblocks): document simulate_v1 block-envelope fields + error object shape MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Expand the simulate_v1 trait doc to describe two response-schema details that are observable to callers but currently undocumented: * The hydrated block envelope on each SimulatedBlock entry (number, hash, gasUsed, baseFeePerGas at the block level). The flashblock executor populates these so callers can size cumulative gas budgets and dereference state by hash without an extra RPC round-trip. * The error object shape returned inside calls[*].error when a simulated call reverts. Two required fields: - message: String — human-readable revert reason - code: i64 — numeric revert classification Plus a note that calls[*].logs includes ETH transfer logs when the caller passes traceTransfers: true, matching the standard eth_simulateV1 contract. This is a doc-comment-only change. No signatures or behavior touched. Purpose: blind test of the sync-from-base agent vs base/docs#1405 (which surfaced the same fields in the corresponding docs page on the upstream side). Comparing the resulting docs PR against PR #1405 page-by-page is how we grade the agent's output against a human reference. See scripts/sync-from-base/NOTES.md. --- crates/execution/flashblocks/src/rpc/eth.rs | 30 +++++++++++++++++++++ 1 file changed, 30 insertions(+) diff --git a/crates/execution/flashblocks/src/rpc/eth.rs b/crates/execution/flashblocks/src/rpc/eth.rs index 7eb9d16a1..1c63efcdd 100644 --- a/crates/execution/flashblocks/src/rpc/eth.rs +++ b/crates/execution/flashblocks/src/rpc/eth.rs @@ -192,6 +192,36 @@ pub trait EthApiOverride { /// Only available on the Flashblocks-aware RPC endpoints /// (`mainnet-preconf.base.org`, `sepolia-preconf.base.org`). Standard /// public endpoints return a `Method not found` error. + /// + /// # Returns + /// + /// Array of simulated block results, one per entry in `blockStateCalls`. + /// Each `SimulatedBlock` carries the standard hydrated block envelope + /// (`number`, `hash`, `gasUsed`, `baseFeePerGas`) populated by the + /// flashblock executor so consumers can size cumulative gas budgets, + /// dereference state by hash, and rebuild call-execution context without + /// a second RPC round-trip. + /// + /// The wrapping `calls` array in each block uses the standard simulate + /// call-result shape: `status`, `gasUsed`, `returnData`, `logs`, and an + /// optional `error` object. When a call reverts, `error` is an object + /// with two fields: + /// + /// - `message: String` — a short human-readable revert reason. Mirrors + /// what RPC clients render today. + /// - `code: i64` — a numeric revert classification. Useful for callers + /// that want to programmatically distinguish revert types (e.g. + /// out-of-gas vs explicit revert) without parsing the prose. + /// + /// Both fields are always present together; consumers should not see + /// a partially-populated error object. + /// + /// # Logs in `calls[*].logs` + /// + /// The logs returned for each simulated call include ETH transfer logs + /// when `traceTransfers: true` was passed in the request; otherwise only + /// emitted contract logs appear. This matches the standard + /// `eth_simulateV1` contract. #[method(name = "simulateV1")] async fn simulate_v1( &self,