feat(benchmarks): add GasTrace qualitative gas profiler

README.md

@@ -9,7 +9,6 @@ Awesome Sails is a comprehensive collection of production-ready services and uti
 The workspace is organized into the following components:
 
 - **[Utils](utils/README.md):** Foundational utilities, math helpers, and common patterns.
-- **[Storage](crates/awesome-sails/storage/README.md):** Storage abstractions and traits for different backends.
 - **[Access Control](crates/awesome-sails/access-control/README.md):** A flexible Role-Based Access Control (RBAC) system.
 - **[VFT](crates/awesome-sails/vft/README.md):** Implementation of the Vara Fungible Token (VFT) standard (ERC-20 analogous).
 - **[VFT Admin](crates/awesome-sails/vft-admin/README.md):** Administrative extensions for VFT (minting, burning, pausing).

benchmarks/Cargo.toml

@@ -17,6 +17,11 @@ serde_json = "1.0"
 gtest = { workspace = true, optional = true }
 gprimitives = { workspace = true }
 
+# Gas trace tree (gtest only)
+sails-rs = { workspace = true, features = ["gtest"], optional = true }
+gear-core = { version = "=1.10.0", optional = true }
+gear-core-errors = { version = "=1.10.0", optional = true }
+
 # Optional reporting
 cli-table = { version = "0.5", optional = true }
 clap = { version = "4.0", features = ["derive"], optional = true }
@@ -27,8 +32,8 @@ default = ["gtest"]
 "ascii-table" = ["dep:cli-table"]
 # Enables the bench-analyzer CLI binary
 cli = ["ascii-table", "dep:clap"]
-# Enables gtest-based benchmarking
-gtest = ["dep:gtest"]
+# Enables gtest-based benchmarking (includes GasTrace profiler)
+gtest = ["dep:gtest", "dep:sails-rs", "dep:gear-core", "dep:gear-core-errors"]
 
 [[bin]]
 name = "bench-analyzer"

benchmarks/README.md

@@ -71,7 +71,52 @@ async fn bench_my_service() {
 }
 ```
 
-### 2. Analysis
+### 2. Gas Trace Tree (Qualitative Profiling)
+
+While `MeasureGas` answers "how much gas?", `GasTrace` answers "**where** did the
+gas go?" — it reconstructs a reply-linked message tree from one or more
+`BlockRunResult`s, decorates each node with its gas cost, and resolves
+`(interface_id, entry_id)` pairs back to `Service::method` names via a
+`MethodRegistry`. Output is a human-readable ASCII tree.
+
+```rust
+use awesome_sails_benchmarks::{GasTrace, MethodRegistry};
+
+let block = system.run_next_block();
+
+let registry = MethodRegistry::new()
+    .register_service::<MyServiceMeta>("MyService");
+
+let tree = GasTrace::new(&block)
+    .with_registry(&registry)
+    .with_actor_name(user_id, "alice")
+    .build();
+
+println!("{}", tree);
+```
+
+Example output:
+
+```
+[0x1001..abcd] alice -> MyProgram::MyService::increment  12,400 gas
+  `-- [0x1002..9876] [reply] Ok  - gas
+[event] MyProgram
+Total: 12,400 gas | 3 messages | depth 1
+```
+
+**Limitations (gtest runtime constraints, not tool design):**
+
+- The tree is built from `reply_to` linkage. Cross-program sub-calls (A → B → C)
+  appear as separate roots because `gtest::CoreLog` doesn't expose
+  parent-message causality.
+- `block.log()` surfaces replies and events but not the originating request.
+  `GasTrace` synthesizes a root for any `gas_burned` entry whose id isn't
+  represented elsewhere in the tree and nests its reply under it — this
+  recovers gas attribution but the synthesized root has no payload, so its
+  method is shown as `[raw]` unless a future gtest revision exposes the full
+  request.
+
+### 3. Analysis
 
 The `bench-analyzer` utility compares generated results with a baseline.
 

benchmarks/src/lib.rs

@@ -29,6 +29,11 @@ use gprimitives::MessageId;
 #[cfg(feature = "gtest")]
 use gtest::System;
 
+#[cfg(feature = "gtest")]
+mod trace;
+#[cfg(feature = "gtest")]
+pub use trace::{GasTrace, GasTraceNode, GasTraceTree, MethodInfo, MethodRegistry};
+
 #[cfg(feature = "gtest")]
 const RELEASE_MODE_ERROR: &str =
     "Benchmarks MUST be run in --release mode to get accurate gas measurements.";