pyrevm-trace 0.1.0__tar.gz

pyrevm_trace-0.1.0/.cargo/config.toml.example

@@ -0,0 +1,15 @@
+# Copy this file to .cargo/config.toml and set PYO3_PYTHON to your Python interpreter.
+# Required for `cargo test` to link against Python when using pyo3 extension-module feature.
+#
+# Find your Python path: which python3  (or: pyenv which python3)
+
+[env]
+PYO3_PYTHON = "/path/to/your/python3"
+
+[target.aarch64-apple-darwin]
+rustflags = [
+    "-L/path/to/your/python/lib",
+    "-lpython3.12",
+]
+
+# For x86_64-apple-darwin or Linux, add a matching [target.*] section.

pyrevm_trace-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,45 @@
+name: CI
+
+on:
+  push:
+    branches: [master]
+  pull_request:
+    branches: [master]
+
+jobs:
+  test:
+    name: Test (${{ matrix.os }}, Python ${{ matrix.python-version }})
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, macos-latest, windows-latest]
+        python-version: ["3.10", "3.11", "3.12"]
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Set up Rust
+        uses: dtolnay/rust-toolchain@stable
+
+      - name: Cache Rust
+        uses: Swatinem/rust-cache@v2
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+
+      - name: Install dependencies
+        run: |
+          uv venv
+          uv pip install maturin pydantic pytest pytest-asyncio
+
+      - name: Build extension
+        run: uv run maturin develop --skip-install
+
+      - name: Run Python tests
+        run: uv run pytest tests/ -v

pyrevm_trace-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,83 @@
+name: Publish
+
+on:
+  push:
+    tags:
+      - "v*"
+
+jobs:
+  build:
+    name: Build wheels (${{ matrix.target }})
+    runs-on: ${{ matrix.os }}
+    strategy:
+      matrix:
+        include:
+          - os: ubuntu-latest
+            target: x86_64
+          - os: ubuntu-latest
+            target: aarch64
+          - os: macos-latest
+            target: universal2-apple-darwin
+          - os: windows-latest
+            target: x86_64
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Build wheels
+        uses: PyO3/maturin-action@v1
+        with:
+          target: ${{ matrix.target }}
+          args: --release --out dist --interpreter 3.10 3.11 3.12
+          sccache: true
+          manylinux: auto
+
+      - name: Upload wheels
+        uses: actions/upload-artifact@v4
+        with:
+          name: wheels-${{ matrix.target }}
+          path: dist
+
+  build-sdist:
+    name: Build source distribution
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Build sdist
+        uses: PyO3/maturin-action@v1
+        with:
+          command: sdist
+          args: --out dist
+
+      - name: Upload sdist
+        uses: actions/upload-artifact@v4
+        with:
+          name: wheels-sdist
+          path: dist
+
+  publish:
+    name: Publish to PyPI
+    runs-on: ubuntu-latest
+    needs: [build, build-sdist]
+    environment:
+      name: pypi
+      url: https://pypi.org/p/pyrevm-trace
+    permissions:
+      id-token: write  # trusted publishing — no token needed
+
+    steps:
+      - name: Download all wheels
+        uses: actions/download-artifact@v4
+        with:
+          pattern: wheels-*
+          merge-multiple: true
+          path: dist
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

pyrevm_trace-0.1.0/.gitignore

@@ -0,0 +1,19 @@
+# Python-generated files
+__pycache__/
+*.py[oc]
+build/
+dist/
+wheels/
+*.egg-info
+
+# Virtual environments
+.venv
+
+# Rust build artifacts
+target/
+
+# Compiled Python extensions
+*.so
+
+# Machine-specific Cargo config (PYO3_PYTHON path — copy from .cargo/config.toml.example)
+.cargo/config.toml

pyrevm_trace-0.1.0/.python-version

@@ -0,0 +1 @@
+3.12.3

pyrevm_trace-0.1.0/CLAUDE.md

@@ -0,0 +1,66 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Behavior & Tool Guidelines
+- use "rtk" before bash commands
+- Always use the Bash tool for file operations (e.g., cat, ls, grep, find) instead of internal Read or Search tools. If you need to see a file, run cat or head via Bash.
+
+## Build & Test Commands
+
+This is a hybrid Rust/Python project. **Always use `uv run` for Python commands** — the project was created with `uv`.
+
+```bash
+# Build the Rust extension (required after any change to src/)
+# --skip-install avoids maturin's pip path, which doesn't support PEP 735 dependency-groups
+uv run maturin develop --skip-install
+
+# Run Python tests
+uv run pytest
+
+# Run a single test
+uv run pytest tests/test_simulation.py::test_set_balance -v
+
+# Run Rust unit tests (no Python involved)
+cargo test
+
+# Run Rust tests for a specific module
+cargo test types
+```
+
+## Architecture
+
+The project has two distinct layers that must be kept in sync.
+
+### Rust layer (`src/`)
+
+PyO3 extension compiled to `python/pyrevm_trace/_pyrevm_trace.cpython-*.so` by maturin.
+
+- **`src/lib.rs`** — PyO3 module entry point. Registers all Python-visible classes. Only touch this to add new `#[pyclass]` types.
+- **`src/executor.rs`** — `EVMSimulator` `#[pyclass]`. Owns the `CacheDB<EmptyDB>` (in-memory EVM state) and all `#[pymethods]`. This is where Python ↔ REVM conversion happens: extract Python types → call REVM → convert result to Python dicts.
+- **`src/types.rs`** — Stateless conversion helpers (`parse_address`, `address_to_hex`, `py_int_to_u256`). All Rust modules that touch Python-provided addresses or amounts use these.
+- **`src/tracer.rs`** — `CallTracer` implementing REVM's `Inspector` trait for recursive call tree capture.
+- **`src/gas_profiler.rs`** — `GasProfiler` implementing `Inspector` for opcode-level gas steps.
+
+Data flows one way: Python dict → Rust extraction → REVM execution → result as Python dict. No Pydantic or serde on the Rust side.
+
+### Python layer (`python/pyrevm_trace/`)
+
+Pure Python, depends on the compiled `.so`.
+- `models.py` — Pydantic v2 models wrapping the raw dicts from Rust (`SimulationResult`, `CallFrame`, `GasStep`, `Log`)
+- `simulator.py` — `Simulator` class: typed sync wrapper
+- `async_simulator.py` — `AsyncSimulator`: offloads simulation to `asyncio.to_thread` for non-blocking async use
+
+### Key invariants
+
+- The Rust layer returns **raw Python dicts** from `simulate()`. The Python layer wraps them in Pydantic models. Never add serde/JSON serialization on the Rust side.
+- Each `EVMSimulator` instance owns independent state — safe for concurrent use across threads/tasks when each caller has its own instance.
+- `with_trace=True` runs a `CallTracer` inspector; `with_gas_profile=True` runs `GasProfiler`. Both flags together: only trace is active (combined inspector is future work).
+
+## Development Setup
+
+`.cargo/config.toml` is gitignored (machine-specific Python paths for `cargo test`). Copy `.cargo/config.toml.example` and set `PYO3_PYTHON` to your Python 3.12 interpreter path, or export it as an env var before running `cargo test`.
+
+## Commit Style
+
+Plain commit messages only — no `Co-Authored-By` trailers.