atupa-core 0.1.1

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

cargo install atupa

🏮 One-Click Initialization

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

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

Capturing a Unified Trace

# 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.

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

Run the Demo

atupa profile --demo

🏮 Atupa Studio

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

# 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:

🤝 Contributing

We welcome contributions! Please see our Contributing Guidelines for more details.

📄 License

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