stylus_trace_core/parser/
schema.rs

1//! Output JSON schema definitions for profile data.
2//!
3//! This module defines the structure of JSON files we write to disk.
4//! Schema is versioned to allow future evolution.
5
6use crate::aggregator::stack_builder::CollapsedStack;
7use serde::{Deserialize, Serialize};
8use std::collections::HashMap;
9
10/// A category describing what type of operation a hot path primarily performs.
11///
12/// This is computed server-side from `HostIoType` knowledge so the frontend
13/// does not need brittle substring-matching heuristics.
14#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize, Default)]
15#[serde(rename_all = "PascalCase")]
16pub enum GasCategory {
17    /// Expensive storage writes (flush/store)
18    StorageExpensive,
19    /// Cheaper storage reads (load/cache)
20    StorageNormal,
21    /// Cryptographic operations (keccak)
22    Crypto,
23    /// Memory / ABI operations (read_args, write_result)
24    Memory,
25    /// External calls (call, delegatecall, staticcall, create)
26    Call,
27    /// System / context queries (msg_sender, msg_value, block_hash, etc.)
28    System,
29    /// Root / entry-point frame
30    Root,
31    /// User-defined contract code not matching any known host op
32    #[default]
33    UserCode,
34    /// Aggregated remainder
35    Other,
36}
37
38/// Top-level profile structure written to JSON
39#[derive(Debug, Clone, Serialize, Deserialize)]
40pub struct Profile {
41    /// Schema version for compatibility checking
42    pub version: String,
43
44    /// Transaction hash that was profiled
45    pub transaction_hash: String,
46
47    /// Total gas used by the transaction
48    pub total_gas: u64,
49
50    /// Summary of HostIO events by category
51    pub hostio_summary: HostIoSummary,
52
53    /// Top hot paths (ranked by gas usage)
54    pub hot_paths: Vec<HotPath>,
55
56    /// Complete execution stacks (optional, for full diff visualization)
57    #[serde(skip_serializing_if = "Option::is_none")]
58    pub all_stacks: Option<Vec<CollapsedStack>>,
59
60    /// Timestamp when profile was generated
61    pub generated_at: String,
62}
63
64/// Summary statistics for HostIO events
65#[derive(Debug, Clone, Serialize, Deserialize)]
66pub struct HostIoSummary {
67    /// Total number of HostIO calls
68    pub total_calls: u64,
69
70    /// Breakdown by HostIO type
71    pub by_type: HashMap<String, u64>,
72
73    /// Total gas consumed by HostIO operations
74    pub total_hostio_gas: u64,
75}
76
77/// A hot path in the execution (stack trace with gas)
78#[derive(Debug, Clone, Serialize, Deserialize)]
79pub struct HotPath {
80    /// Collapsed stack representation (e.g., "main;execute;storage_read")
81    pub stack: String,
82
83    /// Gas consumed by this path
84    pub gas: u64,
85
86    /// Percentage of total gas
87    pub percentage: f64,
88
89    /// Gas category derived from the leaf node of the stack.
90    /// Computed server-side so the frontend doesn't need heuristics.
91    #[serde(default)]
92    pub category: GasCategory,
93
94    /// Source hint (if debug symbols available)
95    #[serde(skip_serializing_if = "Option::is_none")]
96    pub source_hint: Option<SourceHint>,
97}
98
99/// Source code location hint
100///
101/// NOTE: This is currently a placeholder/reserved feature. It is non-functional
102/// because `stylusTracer` does not provide PC offsets.
103#[derive(Debug, Clone, Serialize, Deserialize)]
104pub struct SourceHint {
105    pub file: String,
106    pub line: Option<u32>,
107    pub column: Option<u32>,
108    pub function: Option<String>,
109}
stylus_trace_core/parser/schema.rs

stylus_trace_core/parser/
schema.rs
