From c29fcf3b162e737c5f20cf52dc672a8d30678ff3 Mon Sep 17 00:00:00 2001 From: Matthias Seitz Date: Thu, 30 Nov 2023 16:10:02 +0100 Subject: [PATCH] docs: more tracing type docs (#5638) --- .../rpc/rpc-types/src/eth/trace/geth/call.rs | 13 ++++++ .../rpc/rpc-types/src/eth/trace/geth/mod.rs | 8 +++- crates/rpc/rpc-types/src/eth/trace/parity.rs | 46 ++++++++++++++++++- 3 files changed, 65 insertions(+), 2 deletions(-) diff --git a/crates/rpc/rpc-types/src/eth/trace/geth/call.rs b/crates/rpc/rpc-types/src/eth/trace/geth/call.rs index 1d2d754194..bf6910cf19 100644 --- a/crates/rpc/rpc-types/src/eth/trace/geth/call.rs +++ b/crates/rpc/rpc-types/src/eth/trace/geth/call.rs @@ -7,30 +7,43 @@ use serde::{Deserialize, Serialize}; /// #[derive(Debug, Clone, Default, PartialEq, Eq, Serialize, Deserialize)] pub struct CallFrame { + /// The address of that initiated the call. pub from: Address, + /// How much gas was left before the call #[serde(default, deserialize_with = "from_int_or_hex")] pub gas: U256, + /// How much gas was used by the call #[serde(default, deserialize_with = "from_int_or_hex", rename = "gasUsed")] pub gas_used: U256, + /// The address of the contract that was called. #[serde(default, skip_serializing_if = "Option::is_none")] pub to: Option
, + /// Calldata input pub input: Bytes, + /// Output of the call, if any. #[serde(default, skip_serializing_if = "Option::is_none")] pub output: Option, + /// Error message, if any. #[serde(default, skip_serializing_if = "Option::is_none")] pub error: Option, + /// Why this call reverted, if it reverted. #[serde(default, rename = "revertReason", skip_serializing_if = "Option::is_none")] pub revert_reason: Option, + /// Recorded child calls. #[serde(default, skip_serializing_if = "Vec::is_empty")] pub calls: Vec, + /// Logs emitted by this call #[serde(default, skip_serializing_if = "Vec::is_empty")] pub logs: Vec, + /// Value transferred #[serde(default, skip_serializing_if = "Option::is_none")] pub value: Option, + /// The type of the call #[serde(rename = "type")] pub typ: String, } +/// Represents a recorded call #[derive(Debug, Clone, Default, PartialEq, Eq, Serialize, Deserialize)] pub struct CallLogFrame { #[serde(default, skip_serializing_if = "Option::is_none")] diff --git a/crates/rpc/rpc-types/src/eth/trace/geth/mod.rs b/crates/rpc/rpc-types/src/eth/trace/geth/mod.rs index adc2f7a8e3..a95a3dc2da 100644 --- a/crates/rpc/rpc-types/src/eth/trace/geth/mod.rs +++ b/crates/rpc/rpc-types/src/eth/trace/geth/mod.rs @@ -1,5 +1,5 @@ -//! Geth tracing types #![allow(missing_docs)] +//! Geth tracing types use crate::{state::StateOverride, BlockOverrides}; use alloy_primitives::{Bytes, B256, U256}; @@ -43,10 +43,14 @@ pub struct BlockTraceResult { #[derive(Debug, Clone, Default, PartialEq, Eq, Serialize, Deserialize)] #[serde(rename_all = "camelCase")] pub struct DefaultFrame { + /// Whether the transaction failed pub failed: bool, + /// How much gas was used. pub gas: u64, + /// Output of the transaction #[serde(serialize_with = "crate::serde_helpers::serialize_hex_string_no_prefix")] pub return_value: Bytes, + /// Recorded traces of the transaction pub struct_logs: Vec, } @@ -250,6 +254,7 @@ impl From for GethDebugTracerConfig { #[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize, Default)] #[serde(rename_all = "camelCase")] pub struct GethDebugTracingOptions { + /// The common tracing options #[serde(default, flatten)] pub config: GethDefaultTracingOptions, /// The custom tracer to use. @@ -460,6 +465,7 @@ impl GethDefaultTracingOptions { #[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize, Default)] #[serde(rename_all = "camelCase")] pub struct GethDebugTracingCallOptions { + /// All the options #[serde(flatten)] pub tracing_options: GethDebugTracingOptions, /// The state overrides to apply diff --git a/crates/rpc/rpc-types/src/eth/trace/parity.rs b/crates/rpc/rpc-types/src/eth/trace/parity.rs index 5a24a151d8..2fbc36137a 100644 --- a/crates/rpc/rpc-types/src/eth/trace/parity.rs +++ b/crates/rpc/rpc-types/src/eth/trace/parity.rs @@ -1,4 +1,3 @@ -#![allow(missing_docs)] //! Types for trace module. //! //! See @@ -58,26 +57,38 @@ impl TraceResults { #[derive(Clone, Debug, Eq, PartialEq, Serialize, Deserialize)] #[serde(rename_all = "camelCase")] pub struct TraceResultsWithTransactionHash { + /// The recorded trace. #[serde(flatten)] pub full_trace: TraceResults, + /// Hash of the traced transaction. pub transaction_hash: B256, } +/// A changed value #[derive(Clone, Debug, Eq, PartialEq, Serialize, Deserialize)] pub struct ChangedType { + /// Original value pub from: T, + /// New value pub to: T, } +/// Represents how a value changed. +/// +/// This is used for statediff. #[derive(Clone, Debug, Default, Eq, PartialEq, Serialize, Deserialize)] pub enum Delta { + /// Existing value didn't change. #[default] #[serde(rename = "=")] Unchanged, + /// New storage value added. #[serde(rename = "+")] Added(T), + /// Existing storage value removed. #[serde(rename = "-")] Removed(T), + /// Existing storage value changed. #[serde(rename = "*")] Changed(ChangedType), } @@ -111,12 +122,17 @@ impl Delta { } } +/// The diff of an account after a transaction #[derive(Clone, Debug, Default, Eq, PartialEq, Serialize, Deserialize)] #[serde(rename_all = "camelCase")] pub struct AccountDiff { + /// How the balance changed, if at all pub balance: Delta, + /// How the code changed, if at all pub code: Delta, + /// How the nonce changed, if at all pub nonce: Delta, + /// All touched/changed storage values pub storage: BTreeMap>, } @@ -139,16 +155,20 @@ impl DerefMut for StateDiff { } } +/// Represents the various types of actions recorded during tracing #[derive(Clone, Debug, Eq, PartialEq, Serialize, Deserialize)] #[serde(rename_all = "camelCase", tag = "type", content = "action")] pub enum Action { + /// Regular call Call(CallAction), + /// A CREATE call Create(CreateAction), /// Parity style traces never renamed suicide to selfdestruct: /// /// For compatibility reasons, this is serialized as `suicide`: #[serde(rename = "suicide", alias = "selfdestruct")] Selfdestruct(SelfdestructAction), + /// Rewards if any (pre POS) Reward(RewardAction), } @@ -249,13 +269,17 @@ pub struct CreateAction { pub value: U256, } +/// What kind of reward. #[derive(Clone, Debug, Eq, PartialEq, Serialize, Deserialize)] #[serde(rename_all = "camelCase")] pub enum RewardType { + /// Block rewards Block, + /// Reward for uncle block Uncle, } +/// Recorded reward of a block. #[derive(Clone, Debug, Eq, PartialEq, Serialize, Deserialize)] #[serde(rename_all = "camelCase")] pub struct RewardAction { @@ -279,18 +303,25 @@ pub struct SelfdestructAction { pub refund_address: Address, } +/// Outcome of a CALL. #[derive(Clone, Debug, Eq, PartialEq, Serialize, Deserialize)] #[serde(rename_all = "camelCase")] pub struct CallOutput { + /// Gas used by the call. pub gas_used: U64, + /// The output data of the call. pub output: Bytes, } +/// Outcome of a CREATE. #[derive(Clone, Debug, Eq, PartialEq, Serialize, Deserialize)] #[serde(rename_all = "camelCase")] pub struct CreateOutput { + /// Address of the created contract. pub address: Address, + /// Contract code. pub code: Bytes, + /// Gas used by the call. pub gas_used: U64, } @@ -328,15 +359,24 @@ impl TraceOutput { #[derive(Clone, Debug, Eq, PartialEq, Serialize, Deserialize)] #[serde(rename_all = "camelCase")] pub struct TransactionTrace { + /// Represents what kind of trace this is #[serde(flatten)] pub action: Action, + /// The error message if the transaction failed. #[serde(skip_serializing_if = "Option::is_none")] pub error: Option, + /// Output of the trace, can be CALL or CREATE pub result: Option, + /// How many subtraces this trace has. pub subtraces: usize, + /// The identifier of this transaction trace in the set. + /// + /// This gives the exact location in the call trace + /// [index in root CALL, index in first CALL, index in second CALL, …]. pub trace_address: Vec, } +/// A wrapper for [TransactionTrace] that includes additional information about the transaction. #[derive(Clone, Debug, Eq, PartialEq, Deserialize)] #[serde(rename_all = "camelCase")] pub struct LocalizedTransactionTrace { @@ -429,6 +469,7 @@ pub struct VmTrace { pub ops: Vec, } +/// A record of a single VM instruction, opcode level. #[derive(Clone, Debug, Eq, PartialEq, Serialize, Deserialize)] #[serde(rename_all = "camelCase")] pub struct VmInstruction { @@ -443,6 +484,7 @@ pub struct VmInstruction { /// Stringified opcode. #[serde(skip_serializing_if = "Option::is_none")] pub op: Option, + /// Index of the instruction in the set. #[serde(skip_serializing_if = "Option::is_none")] pub idx: Option, } @@ -475,7 +517,9 @@ pub struct MemoryDelta { #[derive(Clone, Debug, Eq, PartialEq, Serialize, Deserialize)] #[serde(rename_all = "camelCase")] pub struct StorageDelta { + /// Storage key. pub key: U256, + /// Storage value belonging to the key. pub val: U256, }