|
1 | | -# Atupa Suit: System Architecture |
| 1 | +# 🏮 Atupa System Architecture |
2 | 2 |
|
3 | | -The Atupa Suite is designed as a modular, high-performance infrastructure stack that provides transparency for the "Multi-VM" future of Ethereum. It separates the heavy lifting of raw trace parsing from the high-level business logic of protocol-specific auditing. |
| 3 | +Atupa is a high-performance, modular infrastructure stack designed as a **Universal Multi-VM Execution Profiler**. This document details the technical design, data normalization strategies, and crate-level relationships that power the suite across diverse execution environments. |
| 4 | + |
| 5 | +--- |
| 6 | + |
| 7 | +## 🏛 Core Philosophy: The Unified Trace Model |
| 8 | + |
| 9 | +The central challenge Atupa solves is the fragmentation of execution data across different Virtual Machines (EVM, WASM, Cairo, SVM, Soroban). Each VM has its own "gas" units, log formats, and call-stack representations. |
| 10 | + |
| 11 | +Atupa addresses this by normalizing all execution data into a **Unified Trace Step** (`TraceStep`): |
| 12 | + |
| 13 | +```rust |
| 14 | +pub struct TraceStep { |
| 15 | + pub pc: u64, // Program counter or instruction index |
| 16 | + pub op: String, // Opcode, HostFn name, or Program Label |
| 17 | + pub gas_cost: u64, // Normalized execution weight |
| 18 | + pub depth: u16, // Call-stack depth |
| 19 | + pub vm_kind: VmKind, // The source VM (Evm, Stylus, Solana, etc.) |
| 20 | + pub stack: Option<Vec<String>>, |
| 21 | + // ... metadata |
| 22 | +} |
| 23 | +``` |
| 24 | + |
| 25 | +By mapping heterogeneous units (Solana Compute Units, Soroban HostFn weights, Cairo steps) into this model, Atupa enables **cross-chain execution diffing** and **unified flamegraph visualization**. |
| 26 | + |
| 27 | +--- |
4 | 28 |
|
5 | 29 | ## 🏗 System Components |
6 | 30 |
|
7 | | -### 1. Network Layer (The Sources) |
8 | | -Atupa connects to diverse execution environments: |
9 | | -- **Ethereum (L1)**: Standard EVM via `structLogs`. |
10 | | -- **Arbitrum (L2)**: Dual-VM (EVM + Stylus) via the Nitro `stylusTracer`. |
11 | | -- **Unichain (L2)**: Real-time "Flashblocks" (200ms pending state). |
12 | | - |
13 | | -### 2. Intelligence Layer (The Engine) |
14 | | -This is where raw hex data becomes human insight: |
15 | | -- **MixedTraceStitcher**: Correlates different trace formats (EVM, Stylus, Geth) into a unified timeline. |
16 | | -- **Protocol Adapters**: Specialized crates (`atupa-aave`, `atupa-lido`) that implement the `ProtocolAdapter` trait to extract domain-specific insights. |
17 | | -- **Symbol Resolver**: Uses DWARF symbols and Sourcify to map opcodes to source lines. |
18 | | - |
19 | | -### 3. Interface Layer (The UX) |
20 | | -How developers and auditors interact with the data: |
21 | | -- **`atupa`**: The primary Rust binary that orchestrates parsing, auditing, and visualization. |
22 | | -- **`atupa-sdk`**: A high-level library that bundles the core engine and all protocol adapters for third-party integrations. |
23 | | -- **Atupa Report**: Automated, professional audit summaries generated directly from the terminal. |
24 | | - |
25 | | -## 🏮 Data Formats |
26 | | -We use a unified **Atupa Profile JSON** that includes: |
27 | | -- `execution_steps`: Contiguous list of all VM instructions. |
28 | | -- `memory_deltas`: Mapping of memory growth and spikes. |
29 | | -- `protocol_context`: High-level labels and risk flags injected by Protocol Adapters (e.g., "Liquid Staking Share Rebase Detected"). |
| 31 | +### 1. Network Adapters (The Sources) |
| 32 | +Atupa connects to diverse execution environments via specialized clients: |
| 33 | +- **`atupa-nitro`**: Handles Arbitrum's dual-VM state. It stitches standard Geth-style EVM traces with `stylusTracer` WASM logs. |
| 34 | +- **`atupa-starknet`**: Interacts with the Starknet gateway to fetch `traceTransaction` data and flattens recursive Cairo call frames. |
| 35 | +- **`atupa-solana`**: Implements a complex **Log Stitcher** state machine. Since Solana RPCs only provide sequential logs, Atupa reconstructs the nested call stack by tracking `Program...invoke` and `Program...success` markers. |
| 36 | +- **`atupa-stellar`**: Parses Soroban `diagnostic_events` to reconstruct Host Function call trees. |
| 37 | + |
| 38 | +### 2. The Aggregation Engine (`atupa-parser`) |
| 39 | +Raw traces are often thousands of lines long. The parser performs: |
| 40 | +- **Depth-Aware Folding**: Groups sequential opcodes into logical blocks while preserving call-stack integrity. |
| 41 | +- **Instruction Normalization**: Maps VM-specific costs to a relative "unified cost" for cross-environment comparison. |
| 42 | +- **Category Tagging**: Tags steps as `StorageRead`, `Memory`, `Crypto`, etc., to power the Studio's metric cards. |
| 43 | + |
| 44 | +### 3. Visualization Engine (`atupa-output`) |
| 45 | +Atupa generates high-fidelity visual artifacts without relying on external SaaS platforms: |
| 46 | +- **SVG Flamegraphs**: Hand-crafted SVG templates with dynamic gradients that visually differentiate between VMs (e.g., Green for Solana, Purple for Starknet). |
| 47 | +- **Interactive Diffing**: A specialized visual mode that overlays two traces, using color intensities to highlight gas regressions or optimizations. |
| 48 | + |
| 49 | +### 4. Atupa Studio (`studio/`) |
| 50 | +A local-first, high-performance web dashboard built with Vite + React + TypeScript. It features: |
| 51 | +- **Zero-Dependency Flamegraphs**: Custom React components that render recursive trees directly into SVGs for maximum performance. |
| 52 | +- **Trace Inspector**: A paginated, filterable view of the normalized execution timeline. |
| 53 | + |
| 54 | +--- |
| 55 | + |
| 56 | +## 📦 Crate Hierarchy |
| 57 | + |
| 58 | +```mermaid |
| 59 | +graph TD |
| 60 | + CLI[bin/atupa] --> SDK[crates/atupa-sdk] |
| 61 | + SDK --> Core[crates/atupa-core] |
| 62 | + SDK --> Nitro[crates/atupa-nitro] |
| 63 | + SDK --> Solana[crates/atupa-solana] |
| 64 | + SDK --> Starknet[crates/atupa-starknet] |
| 65 | + SDK --> Stellar[crates/atupa-stellar] |
| 66 | + |
| 67 | + Nitro --> Parser[crates/atupa-parser] |
| 68 | + Solana --> Parser |
| 69 | + Starknet --> Parser |
| 70 | + Stellar --> Parser |
| 71 | + |
| 72 | + Parser --> Output[crates/atupa-output] |
| 73 | + Output --> Core |
| 74 | +``` |
| 75 | + |
| 76 | +--- |
| 77 | + |
| 78 | +## 🏮 Data Lifecycle |
| 79 | + |
| 80 | +1. **Capture**: CLI fetches raw RPC data based on the transaction hash and endpoint signature. |
| 81 | +2. **Normalize**: The chain-specific adapter converts raw logs/traces into `Vec<TraceStep>`. |
| 82 | +3. **Stitch**: If the transaction crosses VM boundaries (e.g., Arbitrum), the Nitro adapter synchronizes the EVM and WASM clocks. |
| 83 | +4. **Aggregate**: The parser collapses steps into a searchable tree. |
| 84 | +5. **Render**: The Output engine generates either a terminal summary, a JSON report, or an interactive SVG. |
30 | 85 |
|
31 | 86 | --- |
32 | | -🏮 *One Block: The Transparency Layer for the Hybrid Future.* |
| 87 | +🏮 *Atupa: Illuminating the path toward multi-VM transparency.* |
0 commit comments