atupa-core 0.1.1

Atupa: High-Fidelity Ethereum Tracing & Visual Profiling Suite
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120

<p align="center">
  <img src="assets/logo.png" width="350" alt="Atupa Logo">
</p>

<h1 align="center">Atupa</h1>

<p align="center">
  <strong>High-Fidelity Ethereum Tracing, Profiling &amp; Visual Analysis Suite</strong>
</p>

<p align="center">
  <a href="https://github.com/One-Block-Org/Atupa/actions"><img src="https://github.com/One-Block-Org/Atupa/actions/workflows/rust.yml/badge.svg" alt="CI Status"></a>
  <a href="https://crates.io/crates/atupa-core"><img src="https://img.shields.io/crates/v/atupa-core.svg" alt="Crates.io"></a>
  <a href="https://docs.rs/atupa-core"><img src="https://docs.rs/atupa-core/badge.svg" alt="Documentation"></a>
  <a href="https://opensource.org/licenses/MIT"><img src="https://img.shields.io/badge/License-MIT%20OR%20Apache--2.0-blue.svg" alt="License"></a>
</p>

---

**Atupa** (meaning *Lantern/Lamp*) is a professional-grade EVM + Arbitrum Stylus execution profiler. It turns raw JSON-RPC `debug_traceTransaction` and `stylusTracer` logs into actionable visual insights — from gas flamegraphs to unified EVM/WASM execution dashboards.

## ✨ Key Features

- **🔥 Unified EVM + Stylus Tracing**: Stitches data from both the EVM and Stylus WASM runtime into a single coherent execution timeline.
- **🏮 Atupa Studio**: A local-first web visualizer — drop a `report.json` to instantly render metric cards, HostIO hot paths, and a step-by-step trace inspector.
- **📊 HostIO Flamegraph**: Surfaces the most expensive Stylus Host I/O calls (`storage_flush_cache`, `native_keccak256`, etc.) ranked by gas-equivalent cost.
- **🚨 Crisp Revert Identification**: Instantly identifies failing sub-calls with high-contrast highlights.
- **🔍 Smart Contract Resolution**: Automatically resolves hex addresses to verified contract names via Etherscan V2.
- **🚀 Automated CI/CD Pipeline**: Built-in `atupa init` for zero-config gas regression gating in GitHub Actions.
- **💉 Protocol-Specific Deep Auditing**: Built-in deep traces for **Lido stETH** and **Aave v3**.
- **🛠 Modular Library Architecture**: Pure Rust workspace with specialized crates for adapters, RPC, parsing, and output.

## 🚀 Quick Start

### Installation

```bash
cargo install atupa
```

### 🏮 One-Click Initialization

Bootstrap your project with Atupa profiling and automated CI regression in one command.

```bash
# Detects Foundry/Hardhat and sets up atupa.toml + GitHub Action
atupa init
```

### Capturing a Unified Trace

```bash
# Capture an Arbitrum Stylus transaction (summary to terminal)
atupa capture --tx 0x... --rpc https://arb-mainnet.g.alchemy.com/v2/KEY

# Export as JSON for Atupa Studio
atupa capture --tx 0x... --rpc https://... --output json --file report.json

# Deep protocol audit (Lido or Aave)
atupa audit --protocol lido --tx 0x...

# Compare execution cost of two transactions
atupa diff --base 0x... --target 0x...
```

## 🛡 Automated Gas Regression (CI)

Atupa is designed to sit inside your CI/CD pipeline. Use `atupa init` to generate a `.github/workflows/atupa.yml` file that:
1. Runs your profile scripts on the base branch (baseline).
2. Runs your profile scripts on the pull request branch (target).
3. Compares results and fails the CI if gas regressions exceed your `atupa.toml` thresholds.

```bash
atupa diff --base 0xBASE_TX --target 0xPR_TX --protocol lido
```

### Run the Demo
```bash
atupa profile --demo
```

## 🏮 Atupa Studio

Atupa Studio is a local-first web visualizer for your execution traces.

```bash
# Start the Studio dev server
cd studio && npm install && npm run dev
```

Then open **http://localhost:5173**, generate a trace with `--output json --file report.json`, and drop the file into the Studio. The dashboard instantly renders:

- **Execution Metrics** — EVM Gas, Stylus Ink, HostIO call counts, VM boundary crossings
- **HostIO Hot Paths** — Ranked table with inline distribution bars
- **Trace Inspector** — Paginated, filterable, searchable step-by-step execution viewer

## 📦 Project Structure

Atupa is built as a highly modular monorepo:

| Crate / Directory | Description |
|---|---|
| [`bin/atupa`](bin/atupa) | The primary command-line interface. |
| [`studio/`](studio) | Atupa Studio — Vite + React web visualizer. |
| [`crates/atupa-sdk`](crates/atupa-sdk) | Public-facing SDK for programmatic tracing. |
| [`crates/atupa-core`](crates/atupa-core) | Shared types and core configuration logic. |
| [`crates/atupa-parser`](crates/atupa-parser) | Aggregation engine that collapses EVM traces. |
| [`crates/atupa-nitro`](crates/atupa-nitro) | Arbitrum Nitro dual-VM stitcher (EVM + Stylus). |
| [`crates/atupa-rpc`](crates/atupa-rpc) | Async Ethereum JSON-RPC client & Etherscan resolver. |
| [`crates/atupa-lido`](crates/atupa-lido) | Specialized adapter for Lido stETH. |
| [`crates/atupa-aave`](crates/atupa-aave) | Specialized adapter for Aave v3 & GHO. |

## 🤝 Contributing

We welcome contributions! Please see our [Contributing Guidelines](CONTRIBUTING.md) for more details.

## 📄 License

Atupa is dual-licensed under the [MIT License](LICENSE-MIT) and the [Apache License, Version 2.0](LICENSE-APACHE).
You may use this software under either license, at your option.