Metadata-Version: 2.4
Name: pybitrum
Version: 1.0.0
Summary: Python SDK and CLI for building AI agents with onchain actions.
Home-page: https://github.com/Srizdebnath/PyBitrum
Author: Sriz Debnath
Description-Content-Type: text/markdown
Requires-Dist: vyper>=0.4.3
Requires-Dist: requests
Requires-Dist: web3
Dynamic: author
Dynamic: description
Dynamic: description-content-type
Dynamic: home-page
Dynamic: requires-dist
Dynamic: summary

# PyBitrum v1.0.0

PyBitrum is a state-of-the-art, high-fidelity Web3 IDE designed for the Arbitrum ecosystem. It enables developers to write smart contracts using a Pythonic syntax, which is automatically transformed into **both Solidity and Vyper**, compiled, and verified via a massive industrial-grade test suite.


## 🚀 Key Features

- **Dual-Compiler Pipeline**: Write once in Python, compile simultaneously to Solidity and Vyper.
- **100% Validation**: Verified against 100 industrial-grade smart contracts (DeFi, Governance, NFTs).
- **Cloud-Synced Workspace**: Persistent file storage and user profiles powered by Supabase.
- **Pitch Black UI**: A premium, industrial-grade interface designed for maximum focus and aesthetics.
- **Integrated Terminal**: Live logs, deployment feedback, and real-time compilation details.

---

## 📚 Documentation

For detailed technical information, please refer to the following:

- **[System Architecture](./docs/ARCHITECTURE.md)**: High-level overview of the IDE components.
- **[Compiler Engine](./docs/COMPILER.md)**: Deep dive into the Python-to-Solidity/Vyper transformation logic.
- **[Backend Services](./docs/BACKEND.md)**: Documentation for the Express API and Supabase integration.
- **[Frontend IDE](./docs/FRONTEND.md)**: Details on the "Pitch Black" UI and Monaco Editor configuration.
- **[Testing & Validation](./docs/TESTING.md)**: Information on the 100-contract test suite and runner.

---

## 🏗 Project Architecture

```mermaid
graph TD
    User((Developer)) -->|Writes Code| Frontend[Next.js Frontend]
    Frontend -->|Auth / Sync| Supabase[(Supabase Cloud)]
    Frontend -->|Compile Request| Backend[Node.js / Express Backend]
    Backend -->|Transform Logic| Compiler[Python / Flask Service]
    Compiler -->|Solidity Code| Backend
    Compiler -->|Vyper Code| Backend
    Backend -->|Compiled Artifacts| Frontend
    Frontend -->|Transaction| Arbitrum[Arbitrum Sepolia Testnet]
```

### System Components

1.  **Frontend (Next.js 15)**: The user interface, built with React and Tailwind CSS. Handles file management, authentication via GitHub, and wallet interactions.
2.  **Backend (Node.js/Express)**: The orchestration layer. Manages API routes, user-scoped Supabase clients, and coordinates with the compiler service.
3.  **Compiler Service (Python/Flask)**: The dual-engine that translates Pythonic syntax into valid Solidity and Vyper code using an AST-based transformer.
4.  **Testing Suite (Python)**: A comprehensive suite of 100 contracts used to validate the compiler's output parity.

---

## 📂 Directory Structure

- `/frontend`: Next.js web application.
- `/backend`: Express.js API server.
- `/compiler`: Python transformation and compilation service.
- `/deployment`: Smart contract deployment scripts and configurations.
- `/docs`: Detailed documentation and architecture guides.
- `/tests`: The 100-contract industrial test suite.

---

## 🛠 Setup & Installation

### 1. Prerequisites
- Node.js (v18+)
- Python (v3.9+)
- Solidity Compiler (`solc`)
- Vyper Compiler (`vyper` 0.4.0+)

### 2. Quick Start
From the root directory:
```bash
# Install dependencies
npm install

# Start all services (Frontend, Backend, Compiler)
npm run dev
```

### 3. Running the Test Suite
```bash
# Activate compiler environment
cd compiler
source venv/bin/activate

# Run the 100-contract validation
python ../tests/runner.py
```

---

## 📜 License
MIT License - PyBitrum 1.0.0
