arc-devkit 0.2.0__tar.gz → 0.2.1__tar.gz

arc_devkit-0.2.1/PKG-INFO

@@ -0,0 +1,322 @@
+Metadata-Version: 2.4
+Name: arc-devkit
+Version: 0.2.1
+Summary: Plataforma open source de ferramentas para desenvolvedores da Arc blockchain (Circle)
+Author-email: Jeielsantosdev <jeielsantos.ti@gmail.com>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/Jeielsantosdev/arc-devkit
+Project-URL: Repository, https://github.com/Jeielsantosdev/arc-devkit
+Project-URL: Bug Tracker, https://github.com/Jeielsantosdev/arc-devkit/issues
+Keywords: arc,blockchain,circle,usdc,web3,ai,anthropic
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries
+Classifier: Topic :: Internet :: WWW/HTTP :: HTTP Servers
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+Requires-Dist: typer[all]>=0.12
+Requires-Dist: rich>=13.7
+Requires-Dist: fastapi>=0.115
+Requires-Dist: uvicorn[standard]>=0.30
+Requires-Dist: web3>=7.0
+Requires-Dist: anthropic>=0.40
+Requires-Dist: python-dotenv>=1.0
+Requires-Dist: httpx>=0.27
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.23; extra == "dev"
+Requires-Dist: ruff>=0.6; extra == "dev"
+Requires-Dist: httpx>=0.27; extra == "dev"
+
+# Arc DevKit
+
+[![Python 3.11+](https://img.shields.io/badge/python-3.11+-blue.svg)](https://www.python.org/downloads/)
+[![MIT License](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
+[![Testnet](https://img.shields.io/badge/arc-testnet-orange.svg)](https://arc.io)
+[![Status](https://img.shields.io/badge/status-in%20development-yellow.svg)]()
+
+**Arc DevKit** is a Python toolkit for developers building applications on the **Arc blockchain** — Circle's Layer 1 with USDC as the gas token and sub-second finality.
+
+It solves a practical problem: Arc has unique characteristics (USDC gas, Malachite consensus, Circle Agent Stack) that don't exist on Ethereum or other EVMs. Without a dedicated kit, developers must dig through scattered documentation, configure Arc-specific middleware, and manually figure out how to estimate costs in USDC, debug reverted transactions, or structure an economic agent. Arc DevKit packages all of that.
+
+---
+
+## What is Arc?
+
+**Arc** is a Layer 1 blockchain developed by Circle (creators of USDC), designed for programmable payments and autonomous economic agents.
+
+| Feature | Detail |
+|---|---|
+| **EVM-compatible** | Solidity contracts work without modification |
+| **USDC as gas** | No need for ETH or a separate native token |
+| **Malachite consensus** | Sub-second finality |
+| **Circle Agent Stack** | Native infrastructure for AI economic agents |
+| **Testnet** | Live since October 2025; mainnet expected summer 2026 |
+
+---
+
+## What you can build with Arc DevKit
+
+### On-chain contracts and scripts
+Use the **Dev Copilot** to ask questions, generate Solidity boilerplate, deploy scripts, and Circle ecosystem integrations — all with Arc-specific context built in.
+
+**Examples of what to generate:**
+- Recurring USDC payment contract
+- ERC-20 token deployed to Arc testnet
+- USDC approval and transfer script
+- Circle CCTP (Cross-Chain Transfer Protocol) integration
+
+### Autonomous economic agents
+Use the **Agent Starter Kit** to build agents that interact with Arc programmatically — monitor wallets, execute conditional payments, react to on-chain events.
+
+**Examples of what to build:**
+- Agent that monitors a wallet and triggers actions when USDC is received
+- Recurring payment bot (e.g. monthly subscription in USDC)
+- Balance control agent with threshold alerts
+- Automated payment processing pipeline
+
+### Transaction debugging
+Use the **Tx Debugger** to understand why a transaction failed — without manually decoding raw EVM traces. It fetches the transaction data, decodes the error, and produces a plain-language explanation with a suggested fix.
+
+**Useful for:**
+- Reverted transactions with generic error messages
+- Gas estimation failures in USDC
+- Diagnosing interactions with external contracts
+- Analyzing the real cost of an operation
+
+---
+
+## Modules
+
+### Dev Copilot
+AI assistant (Claude Sonnet) with built-in Arc context. Answers technical questions, generates code, and explains Circle ecosystem concepts — without you needing to paste documentation into a chat window.
+
+### Agent Starter Kit
+Base classes and templates for economic agents. Includes `PaymentAgent` (USDC payments) and `MonitorAgent` (wallet monitoring). Supports read-only mode (no private key) and write mode (with private key).
+
+### Tx Debugger
+Fetches the transaction via RPC (`eth_getTransaction` + `eth_getTransactionReceipt`), decodes the result, and calls the Dev Copilot to generate a natural-language analysis with diagnosis and suggestion.
+
+---
+
+## Installation
+
+**Requirements:** Python 3.11 or higher.
+
+```bash
+# Standard install via PyPI
+pip install arc-devkit
+
+# Development install (clone + editable mode)
+git clone https://github.com/Jeielsantosdev/arc-devkit.git
+cd arc-devkit
+pip install -e ".[dev]"
+```
+
+### Environment variables
+
+```bash
+# Required — Anthropic API key (used by Dev Copilot and Tx Debugger)
+export ANTHROPIC_API_KEY="your-key-here"
+
+# Arc RPC URL (default: public testnet)
+export ARC_RPC_URL="https://rpc.arc.io/testnet"
+
+# Optional — required only to send transactions (agents in write mode)
+export ARC_PRIVATE_KEY="your-private-key"
+```
+
+Create a `.env` file at the project root so you don't need to export these on every session.
+
+---
+
+## Usage
+
+### Check testnet connection
+
+```bash
+arcdevkit status
+```
+
+```
+Arc testnet: connected
+Chain ID:    7777777
+Latest block: 4821903
+Gas (USDC):  0.000021 USDC/tx
+```
+
+---
+
+### Dev Copilot — ask questions and generate code
+
+Via CLI:
+
+```bash
+arcdevkit copilot ask "How do I deploy an ERC-20 contract on Arc testnet?"
+arcdevkit copilot ask "What is the difference between ETH gas and USDC gas on Arc?"
+arcdevkit copilot ask "How do I integrate Circle CCTP into my Solidity contract?"
+```
+
+Via Python:
+
+```python
+from arc_devkit.copilot.agent import DevCopilot
+
+copilot = DevCopilot()
+
+response = copilot.ask(
+    "How do I implement recurring USDC payments on Arc using Solidity?"
+)
+print(response)
+```
+
+---
+
+### Agent Starter Kit — create and manage agent wallets
+
+```bash
+# Create a new wallet for an agent
+arcdevkit agent wallet create
+
+# Check balance (USDC and gas)
+arcdevkit agent wallet balance --address 0xYourWalletHere
+```
+
+Via Python — monitor agent:
+
+```python
+from arc_devkit.agents.monitor_agent import MonitorAgent
+
+agent = MonitorAgent(private_key=None)  # read-only mode, no private key
+
+balance = agent.get_balance("0xYourWalletHere")
+print(f"Balance: {balance} USDC")
+```
+
+Via Python — payment agent:
+
+```python
+from arc_devkit.agents.payment_agent import PaymentAgent
+import os
+
+agent = PaymentAgent(private_key=os.environ["ARC_PRIVATE_KEY"])
+
+result = agent.execute({
+    "to": "0xDestinationHere",
+    "amount_usdc": "10.00",
+})
+print(result)
+```
+
+---
+
+### Tx Debugger — analyze transactions
+
+Via CLI:
+
+```bash
+arcdevkit debug tx 0xyour_transaction_hash_here
+```
+
+Via Python:
+
+```python
+from arc_devkit.debugger.tx_analyzer import TxAnalyzer
+
+analyzer = TxAnalyzer()
+analysis = analyzer.analyze("0xyour_transaction_hash_here")
+print(analysis)
+```
+
+Example output for a reverted transaction:
+
+```
+Status:     reverted
+Error:      ERC20: transfer amount exceeds balance
+Cost:       0.0008 USDC
+Diagnosis:  The sender wallet did not have enough USDC balance at execution
+            time. Check the balance before calling transfer().
+```
+
+---
+
+### REST API
+
+Arc DevKit also exposes a REST API for integrating with other systems or frontends:
+
+```bash
+uvicorn arc_devkit.api.main:app --reload
+```
+
+Available endpoints:
+
+| Method | Route | Description |
+|--------|-------|-------------|
+| `POST` | `/copilot/ask` | Send a question to the Dev Copilot |
+| `GET` | `/agents/balance/{address}` | Query wallet balance |
+| `POST` | `/agents/payment` | Execute a USDC payment |
+| `GET` | `/debugger/tx/{hash}` | Analyze a transaction |
+| `GET` | `/debugger/block` | Current block information |
+
+CORS pre-configured for `localhost:3000`, `localhost:5173`, and `localhost:8080`.
+
+---
+
+## Project Structure
+
+```
+arc_devkit/
+├── config.py           # Global config; reads .env and validates required vars
+├── core/
+│   ├── connection.py   # web3.py client with PoA middleware for Arc
+│   └── wallet.py       # Wallet utilities
+├── copilot/
+│   └── agent.py        # DevCopilot — Anthropic SDK wrapper with Arc system prompt
+├── agents/
+│   ├── base_agent.py   # ABC with get_balance() and execute()
+│   ├── payment_agent.py
+│   └── monitor_agent.py
+├── debugger/
+│   └── tx_analyzer.py  # Fetches tx via RPC + analysis with DevCopilot
+├── api/
+│   ├── main.py         # FastAPI app
+│   └── routes/         # copilot.py, agents.py, debugger.py
+└── cli/
+    ├── main.py         # Typer entry point (arcdevkit)
+    └── commands/       # copilot.py, agent.py, debug.py
+```
+
+---
+
+## Tests
+
+```bash
+# Unit tests (no testnet connection required)
+pytest
+
+# Single test
+pytest -k "test_copilot"
+
+# Integration tests (require ARC_RPC_URL and ANTHROPIC_API_KEY)
+pytest -m integration
+```
+
+---
+
+## License
+
+MIT — see [LICENSE](LICENSE) for details.
+
+---
+
+## About Arc
+
+Arc is developed by Circle, the company behind USDC. For more information about the blockchain and the economic agents ecosystem, see Circle's official documentation.
+
+---
+
+> **Actively in development.** Arc DevKit is in early stage — the Arc testnet is still running and mainnet is expected in summer 2026. APIs and interfaces may change between versions. Keep this in mind for production use.

arc_devkit-0.2.1/README.md

@@ -0,0 +1,288 @@
+# Arc DevKit
+
+[![Python 3.11+](https://img.shields.io/badge/python-3.11+-blue.svg)](https://www.python.org/downloads/)
+[![MIT License](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
+[![Testnet](https://img.shields.io/badge/arc-testnet-orange.svg)](https://arc.io)
+[![Status](https://img.shields.io/badge/status-in%20development-yellow.svg)]()
+
+**Arc DevKit** is a Python toolkit for developers building applications on the **Arc blockchain** — Circle's Layer 1 with USDC as the gas token and sub-second finality.
+
+It solves a practical problem: Arc has unique characteristics (USDC gas, Malachite consensus, Circle Agent Stack) that don't exist on Ethereum or other EVMs. Without a dedicated kit, developers must dig through scattered documentation, configure Arc-specific middleware, and manually figure out how to estimate costs in USDC, debug reverted transactions, or structure an economic agent. Arc DevKit packages all of that.
+
+---
+
+## What is Arc?
+
+**Arc** is a Layer 1 blockchain developed by Circle (creators of USDC), designed for programmable payments and autonomous economic agents.
+
+| Feature | Detail |
+|---|---|
+| **EVM-compatible** | Solidity contracts work without modification |
+| **USDC as gas** | No need for ETH or a separate native token |
+| **Malachite consensus** | Sub-second finality |
+| **Circle Agent Stack** | Native infrastructure for AI economic agents |
+| **Testnet** | Live since October 2025; mainnet expected summer 2026 |
+
+---
+
+## What you can build with Arc DevKit
+
+### On-chain contracts and scripts
+Use the **Dev Copilot** to ask questions, generate Solidity boilerplate, deploy scripts, and Circle ecosystem integrations — all with Arc-specific context built in.
+
+**Examples of what to generate:**
+- Recurring USDC payment contract
+- ERC-20 token deployed to Arc testnet
+- USDC approval and transfer script
+- Circle CCTP (Cross-Chain Transfer Protocol) integration
+
+### Autonomous economic agents
+Use the **Agent Starter Kit** to build agents that interact with Arc programmatically — monitor wallets, execute conditional payments, react to on-chain events.
+
+**Examples of what to build:**
+- Agent that monitors a wallet and triggers actions when USDC is received
+- Recurring payment bot (e.g. monthly subscription in USDC)
+- Balance control agent with threshold alerts
+- Automated payment processing pipeline
+
+### Transaction debugging
+Use the **Tx Debugger** to understand why a transaction failed — without manually decoding raw EVM traces. It fetches the transaction data, decodes the error, and produces a plain-language explanation with a suggested fix.
+
+**Useful for:**
+- Reverted transactions with generic error messages
+- Gas estimation failures in USDC
+- Diagnosing interactions with external contracts
+- Analyzing the real cost of an operation
+
+---
+
+## Modules
+
+### Dev Copilot
+AI assistant (Claude Sonnet) with built-in Arc context. Answers technical questions, generates code, and explains Circle ecosystem concepts — without you needing to paste documentation into a chat window.
+
+### Agent Starter Kit
+Base classes and templates for economic agents. Includes `PaymentAgent` (USDC payments) and `MonitorAgent` (wallet monitoring). Supports read-only mode (no private key) and write mode (with private key).
+
+### Tx Debugger
+Fetches the transaction via RPC (`eth_getTransaction` + `eth_getTransactionReceipt`), decodes the result, and calls the Dev Copilot to generate a natural-language analysis with diagnosis and suggestion.
+
+---
+
+## Installation
+
+**Requirements:** Python 3.11 or higher.
+
+```bash
+# Standard install via PyPI
+pip install arc-devkit
+
+# Development install (clone + editable mode)
+git clone https://github.com/Jeielsantosdev/arc-devkit.git
+cd arc-devkit
+pip install -e ".[dev]"
+```
+
+### Environment variables
+
+```bash
+# Required — Anthropic API key (used by Dev Copilot and Tx Debugger)
+export ANTHROPIC_API_KEY="your-key-here"
+
+# Arc RPC URL (default: public testnet)
+export ARC_RPC_URL="https://rpc.arc.io/testnet"
+
+# Optional — required only to send transactions (agents in write mode)
+export ARC_PRIVATE_KEY="your-private-key"
+```
+
+Create a `.env` file at the project root so you don't need to export these on every session.
+
+---
+
+## Usage
+
+### Check testnet connection
+
+```bash
+arcdevkit status
+```
+
+```
+Arc testnet: connected
+Chain ID:    7777777
+Latest block: 4821903
+Gas (USDC):  0.000021 USDC/tx
+```
+
+---
+
+### Dev Copilot — ask questions and generate code
+
+Via CLI:
+
+```bash
+arcdevkit copilot ask "How do I deploy an ERC-20 contract on Arc testnet?"
+arcdevkit copilot ask "What is the difference between ETH gas and USDC gas on Arc?"
+arcdevkit copilot ask "How do I integrate Circle CCTP into my Solidity contract?"
+```
+
+Via Python:
+
+```python
+from arc_devkit.copilot.agent import DevCopilot
+
+copilot = DevCopilot()
+
+response = copilot.ask(
+    "How do I implement recurring USDC payments on Arc using Solidity?"
+)
+print(response)
+```
+
+---
+
+### Agent Starter Kit — create and manage agent wallets
+
+```bash
+# Create a new wallet for an agent
+arcdevkit agent wallet create
+
+# Check balance (USDC and gas)
+arcdevkit agent wallet balance --address 0xYourWalletHere
+```
+
+Via Python — monitor agent:
+
+```python
+from arc_devkit.agents.monitor_agent import MonitorAgent
+
+agent = MonitorAgent(private_key=None)  # read-only mode, no private key
+
+balance = agent.get_balance("0xYourWalletHere")
+print(f"Balance: {balance} USDC")
+```
+
+Via Python — payment agent:
+
+```python
+from arc_devkit.agents.payment_agent import PaymentAgent
+import os
+
+agent = PaymentAgent(private_key=os.environ["ARC_PRIVATE_KEY"])
+
+result = agent.execute({
+    "to": "0xDestinationHere",
+    "amount_usdc": "10.00",
+})
+print(result)
+```
+
+---
+
+### Tx Debugger — analyze transactions
+
+Via CLI:
+
+```bash
+arcdevkit debug tx 0xyour_transaction_hash_here
+```
+
+Via Python:
+
+```python
+from arc_devkit.debugger.tx_analyzer import TxAnalyzer
+
+analyzer = TxAnalyzer()
+analysis = analyzer.analyze("0xyour_transaction_hash_here")
+print(analysis)
+```
+
+Example output for a reverted transaction:
+
+```
+Status:     reverted
+Error:      ERC20: transfer amount exceeds balance
+Cost:       0.0008 USDC
+Diagnosis:  The sender wallet did not have enough USDC balance at execution
+            time. Check the balance before calling transfer().
+```
+
+---
+
+### REST API
+
+Arc DevKit also exposes a REST API for integrating with other systems or frontends:
+
+```bash
+uvicorn arc_devkit.api.main:app --reload
+```
+
+Available endpoints:
+
+| Method | Route | Description |
+|--------|-------|-------------|
+| `POST` | `/copilot/ask` | Send a question to the Dev Copilot |
+| `GET` | `/agents/balance/{address}` | Query wallet balance |
+| `POST` | `/agents/payment` | Execute a USDC payment |
+| `GET` | `/debugger/tx/{hash}` | Analyze a transaction |
+| `GET` | `/debugger/block` | Current block information |
+
+CORS pre-configured for `localhost:3000`, `localhost:5173`, and `localhost:8080`.
+
+---
+
+## Project Structure
+
+```
+arc_devkit/
+├── config.py           # Global config; reads .env and validates required vars
+├── core/
+│   ├── connection.py   # web3.py client with PoA middleware for Arc
+│   └── wallet.py       # Wallet utilities
+├── copilot/
+│   └── agent.py        # DevCopilot — Anthropic SDK wrapper with Arc system prompt
+├── agents/
+│   ├── base_agent.py   # ABC with get_balance() and execute()
+│   ├── payment_agent.py
+│   └── monitor_agent.py
+├── debugger/
+│   └── tx_analyzer.py  # Fetches tx via RPC + analysis with DevCopilot
+├── api/
+│   ├── main.py         # FastAPI app
+│   └── routes/         # copilot.py, agents.py, debugger.py
+└── cli/
+    ├── main.py         # Typer entry point (arcdevkit)
+    └── commands/       # copilot.py, agent.py, debug.py
+```
+
+---
+
+## Tests
+
+```bash
+# Unit tests (no testnet connection required)
+pytest
+
+# Single test
+pytest -k "test_copilot"
+
+# Integration tests (require ARC_RPC_URL and ANTHROPIC_API_KEY)
+pytest -m integration
+```
+
+---
+
+## License
+
+MIT — see [LICENSE](LICENSE) for details.
+
+---
+
+## About Arc
+
+Arc is developed by Circle, the company behind USDC. For more information about the blockchain and the economic agents ecosystem, see Circle's official documentation.
+
+---
+
+> **Actively in development.** Arc DevKit is in early stage — the Arc testnet is still running and mainnet is expected in summer 2026. APIs and interfaces may change between versions. Keep this in mind for production use.