arc-devkit 0.2.0__tar.gz

arc_devkit-0.2.0/PKG-INFO

@@ -0,0 +1,238 @@
+Metadata-Version: 2.4
+Name: arc-devkit
+Version: 0.2.0
+Summary: Plataforma open source de ferramentas para desenvolvedores da Arc blockchain (Circle)
+Author-email: Jeiel Santos <jeielsantos.ti@gmail.com>
+License: 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: License :: OSI Approved :: MIT License
+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/)
+[![Licença MIT](https://img.shields.io/badge/licença-MIT-green.svg)](LICENSE)
+[![Testnet](https://img.shields.io/badge/arc-testnet-orange.svg)](https://arc.io)
+[![Status](https://img.shields.io/badge/status-em%20desenvolvimento-yellow.svg)]()
+
+Uma plataforma open source de ferramentas para desenvolvedores que constroem na **Arc blockchain** — a Layer 1 da Circle com USDC como token de gás e finalidade em menos de 1 segundo.
+
+---
+
+## O que é a Arc?
+
+A **Arc** é uma blockchain Layer 1 desenvolvida pela Circle (criadores do USDC), com foco em pagamentos programáveis e agentes econômicos autônomos. Características principais:
+
+- **EVM-compatível** — contratos Solidity funcionam sem modificação
+- **USDC como gás** — sem necessidade de ETH ou token nativo separado
+- **Consenso Malachite** — finalidade em menos de 1 segundo
+- **Circle Agent Stack** — infraestrutura nativa para agentes de IA econômicos
+- **Testnet ativa** desde outubro de 2025; mainnet prevista para o verão de 2026
+
+---
+
+## Módulos
+
+### Dev Copilot
+Assistente de IA para geração de código Arc. Responde a perguntas, gera contratos Solidity, scripts de deploy e interações com o ecossistema Circle.
+
+### Agent Starter Kit
+Templates prontos para agentes econômicos autônomos: pagamento recorrente, monitoramento de carteira, arbitragem de câmbio e marketplace descentralizado.
+
+### Tx Debugger
+Ferramenta de análise de transações Arc. Decodifica traces, identifica erros, calcula custos em USDC e sugere correções.
+
+---
+
+## Instalação
+
+**Pré-requisitos:** Python 3.11 ou superior, pip.
+
+```bash
+# Instalação padrão
+pip install arc-devkit
+
+# Instalação para desenvolvimento (inclui ferramentas de teste e lint)
+git clone https://github.com/seu-usuario/arc-devkit.git
+cd arc-devkit
+pip install -e ".[dev]"
+```
+
+### Configurar variáveis de ambiente
+
+```bash
+# Chave da API Anthropic (obrigatória para o Dev Copilot)
+export ANTHROPIC_API_KEY="sua-chave-aqui"
+
+# URL RPC da Arc (padrão: testnet)
+export ARC_RPC_URL="https://rpc.arc.io/testnet"
+
+# Chave privada da carteira (opcional — necessária apenas para enviar transações)
+export ARC_PRIVATE_KEY="sua-chave-privada"
+```
+
+---
+
+## Uso Rápido
+
+### Dev Copilot — Gerar código com IA
+
+```python
+from arc_devkit.copilot import DevCopilot
+
+copilot = DevCopilot()
+
+# Gerar um contrato de pagamento recorrente
+resposta = copilot.perguntar(
+    "Como implemento pagamento recorrente em USDC na Arc usando Solidity?"
+)
+print(resposta)
+```
+
+Via linha de comando:
+
+```bash
+arc-copilot perguntar "Como fazer deploy de um contrato ERC-20 na Arc testnet?"
+```
+
+---
+
+### Agent Starter Kit — Criar agente econômico
+
+```python
+from arc_devkit.agents import AgenteMonitoramento
+from decimal import Decimal
+
+# Monitorar uma carteira e agir ao receber USDC
+agente = AgenteMonitoramento(
+    carteira="0xSuaCarteiraAqui",
+    limiar_usdc=Decimal("100.00"),   # agir ao receber 100 USDC ou mais
+    intervalo_segundos=30,
+)
+
+agente.ao_receber(lambda evento: print(f"Recebido: {evento.valor} USDC"))
+agente.iniciar()
+```
+
+Via linha de comando:
+
+```bash
+arc-agents iniciar monitoramento \
+  --carteira 0xSuaCarteiraAqui \
+  --limiar 100 \
+  --intervalo 30
+```
+
+---
+
+### Tx Debugger — Analisar transação
+
+```python
+from arc_devkit.debugger import TxDebugger
+
+debugger = TxDebugger()
+
+# Analisar uma transação que falhou
+analise = debugger.analisar("0xhash_da_transacao_aqui")
+
+print(analise.status)          # "revertida"
+print(analise.motivo)          # "ERC20: transferência excede saldo"
+print(analise.custo_usdc)      # "0.0012 USDC"
+print(analise.sugestao)        # "Verifique o saldo antes de transferir"
+```
+
+Via linha de comando:
+
+```bash
+arc-debug analisar 0xhash_da_transacao_aqui --formato json
+```
+
+---
+
+## Estrutura do Projeto
+
+```
+arc_devkit/
+├── core/               # Fundação: cliente RPC, utilitários de gás em USDC
+│   ├── client.py       # Cliente Arc (web3.py com defaults Arc)
+│   ├── gas.py          # Estimativa e conversão de gás em USDC
+│   └── config.py       # Carregamento de configuração e variáveis de ambiente
+│
+├── copilot/            # Módulo Dev Copilot
+│   ├── ai.py           # Wrapper do SDK Anthropic com streaming
+│   ├── cli.py          # Interface de linha de comando (Click)
+│   └── prompts/        # Templates de prompt por tipo de tarefa
+│
+├── agents/             # Módulo Agent Starter Kit
+│   ├── base.py         # Classe base para todos os agentes
+│   ├── pagamento.py    # Agente de pagamento recorrente
+│   ├── monitoramento.py # Agente de monitoramento de carteira
+│   ├── cambio.py       # Agente de arbitragem de câmbio
+│   └── marketplace.py  # Agente de marketplace descentralizado
+│
+└── debugger/           # Módulo Tx Debugger
+    ├── debugger.py     # Orquestrador principal
+    ├── trace.py        # Decodificador de traces de transação
+    ├── abi.py          # Resolução de ABI (cache local + Sourcify)
+    └── cli.py          # Interface de linha de comando (Click)
+```
+
+---
+
+## Documentação
+
+- [Começando](docs/getting-started.md) — instalação, configuração e primeiro exemplo
+- [Dev Copilot](docs/modules/dev-copilot.md) — uso completo do assistente de IA
+- [Agent Starter Kit](docs/modules/agent-starter-kit.md) — templates de agentes econômicos
+- [Tx Debugger](docs/modules/tx-debugger.md) — análise e debugging de transações
+
+---
+
+## Contribuição
+
+Contribuições são bem-vindas! Leia [CONTRIBUTING.md](CONTRIBUTING.md) para entender o processo.
+
+```bash
+# Rodar os testes
+pytest
+
+# Verificar formatação e tipos
+ruff check . && mypy arc_devkit/
+```
+
+---
+
+## Licença
+
+MIT — veja [LICENSE](LICENSE) para detalhes.
+
+---
+
+## Sobre a Arc
+
+A Arc é desenvolvida pela Circle, a empresa por trás do USDC. Para mais informações sobre a blockchain e o ecossistema de agentes econômicos, consulte a documentação oficial da Circle.

arc_devkit-0.2.0/README.md

@@ -0,0 +1,203 @@
+# Arc DevKit
+
+[![Python 3.11+](https://img.shields.io/badge/python-3.11+-blue.svg)](https://www.python.org/downloads/)
+[![Licença MIT](https://img.shields.io/badge/licença-MIT-green.svg)](LICENSE)
+[![Testnet](https://img.shields.io/badge/arc-testnet-orange.svg)](https://arc.io)
+[![Status](https://img.shields.io/badge/status-em%20desenvolvimento-yellow.svg)]()
+
+Uma plataforma open source de ferramentas para desenvolvedores que constroem na **Arc blockchain** — a Layer 1 da Circle com USDC como token de gás e finalidade em menos de 1 segundo.
+
+---
+
+## O que é a Arc?
+
+A **Arc** é uma blockchain Layer 1 desenvolvida pela Circle (criadores do USDC), com foco em pagamentos programáveis e agentes econômicos autônomos. Características principais:
+
+- **EVM-compatível** — contratos Solidity funcionam sem modificação
+- **USDC como gás** — sem necessidade de ETH ou token nativo separado
+- **Consenso Malachite** — finalidade em menos de 1 segundo
+- **Circle Agent Stack** — infraestrutura nativa para agentes de IA econômicos
+- **Testnet ativa** desde outubro de 2025; mainnet prevista para o verão de 2026
+
+---
+
+## Módulos
+
+### Dev Copilot
+Assistente de IA para geração de código Arc. Responde a perguntas, gera contratos Solidity, scripts de deploy e interações com o ecossistema Circle.
+
+### Agent Starter Kit
+Templates prontos para agentes econômicos autônomos: pagamento recorrente, monitoramento de carteira, arbitragem de câmbio e marketplace descentralizado.
+
+### Tx Debugger
+Ferramenta de análise de transações Arc. Decodifica traces, identifica erros, calcula custos em USDC e sugere correções.
+
+---
+
+## Instalação
+
+**Pré-requisitos:** Python 3.11 ou superior, pip.
+
+```bash
+# Instalação padrão
+pip install arc-devkit
+
+# Instalação para desenvolvimento (inclui ferramentas de teste e lint)
+git clone https://github.com/seu-usuario/arc-devkit.git
+cd arc-devkit
+pip install -e ".[dev]"
+```
+
+### Configurar variáveis de ambiente
+
+```bash
+# Chave da API Anthropic (obrigatória para o Dev Copilot)
+export ANTHROPIC_API_KEY="sua-chave-aqui"
+
+# URL RPC da Arc (padrão: testnet)
+export ARC_RPC_URL="https://rpc.arc.io/testnet"
+
+# Chave privada da carteira (opcional — necessária apenas para enviar transações)
+export ARC_PRIVATE_KEY="sua-chave-privada"
+```
+
+---
+
+## Uso Rápido
+
+### Dev Copilot — Gerar código com IA
+
+```python
+from arc_devkit.copilot import DevCopilot
+
+copilot = DevCopilot()
+
+# Gerar um contrato de pagamento recorrente
+resposta = copilot.perguntar(
+    "Como implemento pagamento recorrente em USDC na Arc usando Solidity?"
+)
+print(resposta)
+```
+
+Via linha de comando:
+
+```bash
+arc-copilot perguntar "Como fazer deploy de um contrato ERC-20 na Arc testnet?"
+```
+
+---
+
+### Agent Starter Kit — Criar agente econômico
+
+```python
+from arc_devkit.agents import AgenteMonitoramento
+from decimal import Decimal
+
+# Monitorar uma carteira e agir ao receber USDC
+agente = AgenteMonitoramento(
+    carteira="0xSuaCarteiraAqui",
+    limiar_usdc=Decimal("100.00"),   # agir ao receber 100 USDC ou mais
+    intervalo_segundos=30,
+)
+
+agente.ao_receber(lambda evento: print(f"Recebido: {evento.valor} USDC"))
+agente.iniciar()
+```
+
+Via linha de comando:
+
+```bash
+arc-agents iniciar monitoramento \
+  --carteira 0xSuaCarteiraAqui \
+  --limiar 100 \
+  --intervalo 30
+```
+
+---
+
+### Tx Debugger — Analisar transação
+
+```python
+from arc_devkit.debugger import TxDebugger
+
+debugger = TxDebugger()
+
+# Analisar uma transação que falhou
+analise = debugger.analisar("0xhash_da_transacao_aqui")
+
+print(analise.status)          # "revertida"
+print(analise.motivo)          # "ERC20: transferência excede saldo"
+print(analise.custo_usdc)      # "0.0012 USDC"
+print(analise.sugestao)        # "Verifique o saldo antes de transferir"
+```
+
+Via linha de comando:
+
+```bash
+arc-debug analisar 0xhash_da_transacao_aqui --formato json
+```
+
+---
+
+## Estrutura do Projeto
+
+```
+arc_devkit/
+├── core/               # Fundação: cliente RPC, utilitários de gás em USDC
+│   ├── client.py       # Cliente Arc (web3.py com defaults Arc)
+│   ├── gas.py          # Estimativa e conversão de gás em USDC
+│   └── config.py       # Carregamento de configuração e variáveis de ambiente
+│
+├── copilot/            # Módulo Dev Copilot
+│   ├── ai.py           # Wrapper do SDK Anthropic com streaming
+│   ├── cli.py          # Interface de linha de comando (Click)
+│   └── prompts/        # Templates de prompt por tipo de tarefa
+│
+├── agents/             # Módulo Agent Starter Kit
+│   ├── base.py         # Classe base para todos os agentes
+│   ├── pagamento.py    # Agente de pagamento recorrente
+│   ├── monitoramento.py # Agente de monitoramento de carteira
+│   ├── cambio.py       # Agente de arbitragem de câmbio
+│   └── marketplace.py  # Agente de marketplace descentralizado
+│
+└── debugger/           # Módulo Tx Debugger
+    ├── debugger.py     # Orquestrador principal
+    ├── trace.py        # Decodificador de traces de transação
+    ├── abi.py          # Resolução de ABI (cache local + Sourcify)
+    └── cli.py          # Interface de linha de comando (Click)
+```
+
+---
+
+## Documentação
+
+- [Começando](docs/getting-started.md) — instalação, configuração e primeiro exemplo
+- [Dev Copilot](docs/modules/dev-copilot.md) — uso completo do assistente de IA
+- [Agent Starter Kit](docs/modules/agent-starter-kit.md) — templates de agentes econômicos
+- [Tx Debugger](docs/modules/tx-debugger.md) — análise e debugging de transações
+
+---
+
+## Contribuição
+
+Contribuições são bem-vindas! Leia [CONTRIBUTING.md](CONTRIBUTING.md) para entender o processo.
+
+```bash
+# Rodar os testes
+pytest
+
+# Verificar formatação e tipos
+ruff check . && mypy arc_devkit/
+```
+
+---
+
+## Licença
+
+MIT — veja [LICENSE](LICENSE) para detalhes.
+
+---
+
+## Sobre a Arc
+
+A Arc é desenvolvida pela Circle, a empresa por trás do USDC. Para mais informações sobre a blockchain e o ecossistema de agentes econômicos, consulte a documentação oficial da Circle.

arc_devkit-0.2.0/arc_devkit/__init__.py

@@ -0,0 +1,3 @@
+"""Arc DevKit — Ferramentas para desenvolvedores da Arc blockchain (Circle)."""
+
+__version__ = "0.1.0"

arc_devkit-0.2.0/arc_devkit/agents/__init__.py

@@ -0,0 +1,7 @@
+"""Módulo Agent Starter Kit — templates de agentes econômicos Arc."""
+
+from arc_devkit.agents.base_agent import BaseAgent
+from arc_devkit.agents.payment_agent import PaymentAgent
+from arc_devkit.agents.monitor_agent import MonitorAgent
+
+__all__ = ["BaseAgent", "PaymentAgent", "MonitorAgent"]

arc_devkit-0.2.0/arc_devkit/agents/base_agent.py

@@ -0,0 +1,87 @@
+"""Classe base abstrata para todos os agentes econômicos Arc."""
+
+import logging
+from abc import ABC, abstractmethod
+
+from eth_account import Account
+from web3 import Web3
+
+logger = logging.getLogger(__name__)
+
+
+class BaseAgent(ABC):
+    """
+    Fundação para todos os agentes econômicos Arc.
+
+    Gerencia a conexão com a blockchain, a identidade da carteira
+    e fornece helpers de logging. Subclasses implementam get_balance()
+    e execute() com a lógica específica de cada tipo de agente.
+    """
+
+    def __init__(
+        self,
+        private_key: str | None = None,
+        rpc_url: str | None = None,
+    ) -> None:
+        """
+        Inicializa o agente com carteira e conexão RPC.
+
+        Args:
+            private_key: Chave privada hex (opcional). Se omitida, usa
+                         ARC_PRIVATE_KEY do ambiente. Sem chave = modo leitura.
+            rpc_url: URL do nó RPC (opcional). Se omitida, usa ARC_RPC_URL.
+        """
+        from arc_devkit.config import settings
+        from arc_devkit.core.connection import get_web3
+
+        # Configurar conexão com a Arc
+        self._w3: Web3 = get_web3()
+
+        # Resolver chave privada: argumento > variável de ambiente > None
+        _chave = private_key or settings.arc_private_key
+
+        if _chave:
+            account = Account.from_key(_chave)
+            self._address: str | None = account.address
+            self._private_key: str | None = _chave
+            logger.info(
+                "[%s] Inicializado com carteira %s",
+                self.__class__.__name__,
+                self._address,
+            )
+        else:
+            self._address = None
+            self._private_key = None
+            logger.warning(
+                "[%s] Sem chave privada — modo somente leitura.",
+                self.__class__.__name__,
+            )
+
+    @property
+    def wallet_address(self) -> str | None:
+        """Endereço checksummed da carteira do agente."""
+        return self._address
+
+    @abstractmethod
+    def get_balance(self) -> dict:
+        """
+        Retorna o saldo atual da carteira do agente.
+
+        Returns:
+            Dict com pelo menos 'address' e 'balance_usdc'.
+        """
+        ...
+
+    @abstractmethod
+    def execute(self, **kwargs) -> dict:
+        """
+        Executa a ação principal do agente.
+
+        Returns:
+            Dict com o resultado da execução, incluindo 'status'.
+        """
+        ...
+
+    def log(self, msg: str) -> None:
+        """Helper de log padronizado: prefixo com nome da classe."""
+        logger.info("[%s] %s", self.__class__.__name__, msg)

arc_devkit-0.2.0/arc_devkit/agents/monitor_agent.py

@@ -0,0 +1,104 @@
+"""Agente de monitoramento — detecta mudanças de saldo em carteiras Arc."""
+
+import logging
+import time
+from collections.abc import Callable
+from typing import Any
+
+from web3 import Web3
+
+from arc_devkit.agents.base_agent import BaseAgent
+
+logger = logging.getLogger(__name__)
+
+
+class MonitorAgent(BaseAgent):
+    """
+    Monitora uma carteira Arc e chama callbacks ao detectar mudanças de saldo.
+
+    Executa em loop de polling — adequado para MVP. Versões futuras
+    utilizarão eth_subscribe para eventos em tempo real via WebSocket.
+    """
+
+    def __init__(
+        self,
+        watched_address: str,
+        interval_seconds: int = 15,
+        **kwargs: Any,
+    ) -> None:
+        """
+        Inicializa o agente de monitoramento.
+
+        Args:
+            watched_address: Endereço EVM a monitorar.
+            interval_seconds: Intervalo de polling em segundos (padrão: 15).
+            **kwargs: Repassado ao BaseAgent (private_key, rpc_url).
+        """
+        super().__init__(**kwargs)
+        self._watched = Web3.to_checksum_address(watched_address)
+        self._interval = interval_seconds
+        self._last_balance: int | None = None
+        self._running = False
+
+    def get_balance(self) -> dict:
+        """Retorna o saldo atual da carteira monitorada."""
+        wei = self._w3.eth.get_balance(self._watched)
+        return {
+            "address": self._watched,
+            "balance_wei": str(wei),
+            "balance_eth": str(self._w3.from_wei(wei, "ether")),
+        }
+
+    def execute(
+        self,
+        callback: Callable[[dict], None] | None = None,
+        max_iterations: int = 0,
+    ) -> dict:
+        """
+        Inicia o loop de monitoramento da carteira.
+
+        Args:
+            callback: Função chamada com um dict de evento ao detectar mudança.
+                      O dict contém: address, saldo_anterior, saldo_atual, diferenca_wei.
+            max_iterations: Número máximo de iterações (0 = loop infinito).
+
+        Returns:
+            Dict com status e total de iterações executadas.
+        """
+        self._running = True
+        self._last_balance = self._w3.eth.get_balance(self._watched)
+        iteracoes = 0
+
+        self.log(f"Monitorando {self._watched} a cada {self._interval}s")
+
+        while self._running:
+            saldo_atual = self._w3.eth.get_balance(self._watched)
+
+            if saldo_atual != self._last_balance:
+                diferenca = saldo_atual - self._last_balance
+                evento = {
+                    "address": self._watched,
+                    "saldo_anterior_wei": str(self._last_balance),
+                    "saldo_atual_wei": str(saldo_atual),
+                    "diferenca_wei": str(diferenca),
+                    "tipo": "credito" if diferenca > 0 else "debito",
+                }
+                self.log(f"Mudança detectada: {diferenca:+d} wei ({evento['tipo']})")
+
+                if callback:
+                    callback(evento)
+
+                self._last_balance = saldo_atual
+
+            iteracoes += 1
+            if max_iterations and iteracoes >= max_iterations:
+                break
+
+            time.sleep(self._interval)
+
+        return {"status": "finalizado", "iteracoes": iteracoes}
+
+    def stop(self) -> None:
+        """Interrompe o loop de monitoramento na próxima iteração."""
+        self._running = False
+        self.log("Monitoramento encerrado.")