arc-devkit 0.2.0__py3-none-any.whl

arc_devkit/__init__.py

@@ -0,0 +1,3 @@
+"""Arc DevKit — Ferramentas para desenvolvedores da Arc blockchain (Circle)."""
+
+__version__ = "0.1.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/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/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.")

arc_devkit/agents/payment_agent.py

@@ -0,0 +1,97 @@
+"""Agente de pagamento Arc — monta e assina transações de transferência."""
+
+import logging
+from decimal import Decimal
+
+from web3 import Web3
+
+from arc_devkit.agents.base_agent import BaseAgent
+
+logger = logging.getLogger(__name__)
+
+
+class PaymentAgent(BaseAgent):
+    """
+    Agente responsável por executar pagamentos na rede Arc.
+
+    Monta, assina e (opcionalmente) envia transações de transferência.
+    Projetado para ser reutilizado em fluxos de pagamento recorrente.
+    """
+
+    def get_balance(self) -> dict:
+        """
+        Retorna o saldo nativo da carteira do agente.
+
+        Returns:
+            Dict com address, balance_wei e balance_usdc (Decimal).
+        """
+        if not self._address:
+            return {"error": "Nenhuma chave privada configurada — modo somente leitura."}
+
+        wei = self._w3.eth.get_balance(self._address)
+        balance = Decimal(str(self._w3.from_wei(wei, "ether")))
+
+        return {
+            "address": self._address,
+            "balance_wei": str(wei),
+            "balance_usdc": balance,
+        }
+
+    def execute(self, to: str, amount_usdc: float, enviar: bool = False) -> dict:
+        """
+        Monta e assina uma transação de pagamento.
+
+        Args:
+            to: Endereço EVM do destinatário.
+            amount_usdc: Valor a transferir (em USDC).
+            enviar: Se True, envia a transação para a rede (requer chave privada).
+                    Se False (padrão), retorna a transação assinada sem enviar.
+
+        Returns:
+            Dict com status, dados da transação e hash (se enviada).
+        """
+        if not self._private_key:
+            return {"status": "erro", "error": "Chave privada necessária para assinar transações."}
+
+        destinatario = Web3.to_checksum_address(to)
+        self.log(f"Preparando pagamento de {amount_usdc} USDC → {destinatario}")
+
+        # Montar transação
+        nonce = self._w3.eth.get_transaction_count(self._address)
+        tx = {
+            "from": self._address,
+            "to": destinatario,
+            "value": self._w3.to_wei(amount_usdc, "ether"),  # placeholder: USDC nativo
+            "gas": 21_000,
+            "gasPrice": self._w3.eth.gas_price,
+            "nonce": nonce,
+            "chainId": self._w3.eth.chain_id,
+        }
+
+        # Assinar a transação com a chave privada
+        signed = self._w3.eth.account.sign_transaction(tx, self._private_key)
+        self.log("Transação assinada com sucesso.")
+
+        if enviar:
+            # Enviar para a rede Arc
+            tx_hash = self._w3.eth.send_raw_transaction(signed.raw_transaction)
+            tx_hash_hex = tx_hash.hex()
+            self.log(f"Transação enviada: {tx_hash_hex}")
+            return {
+                "status": "enviada",
+                "from": self._address,
+                "to": destinatario,
+                "amount_usdc": amount_usdc,
+                "tx_hash": tx_hash_hex,
+            }
+
+        # Modo padrão: retornar transação assinada sem enviar
+        # TODO: remova enviar=False e passe enviar=True para envio real
+        return {
+            "status": "assinada",
+            "from": self._address,
+            "to": destinatario,
+            "amount_usdc": amount_usdc,
+            "raw_transaction": signed.raw_transaction.hex(),
+            "nota": "Transação assinada. Passe enviar=True para enviar à rede.",
+        }

arc_devkit/api/__init__.py

@@ -0,0 +1 @@
+"""Módulo API — interface REST FastAPI do Arc DevKit."""

arc_devkit/api/main.py

@@ -0,0 +1,42 @@
+"""API REST do Arc DevKit — FastAPI."""
+
+from fastapi import FastAPI
+from fastapi.middleware.cors import CORSMiddleware
+
+from arc_devkit import __version__
+from arc_devkit.api.routes import agents, copilot, debugger
+
+app = FastAPI(
+    title="Arc DevKit API",
+    description=(
+        "API REST para ferramentas de desenvolvimento na Arc blockchain. "
+        "Expõe os módulos Dev Copilot, Agent Kit e Tx Debugger via HTTP."
+    ),
+    version=__version__,
+    docs_url="/docs",
+    redoc_url="/redoc",
+)
+
+# CORS para desenvolvimento local (ajuste allow_origins em produção)
+app.add_middleware(
+    CORSMiddleware,
+    allow_origins=[
+        "http://localhost:3000",   # React CRA
+        "http://localhost:5173",   # Vite
+        "http://localhost:8080",
+    ],
+    allow_credentials=True,
+    allow_methods=["*"],
+    allow_headers=["*"],
+)
+
+# Registrar routers
+app.include_router(copilot.router, prefix="/copilot", tags=["Dev Copilot"])
+app.include_router(agents.router, prefix="/agents", tags=["Agents"])
+app.include_router(debugger.router, prefix="/debug", tags=["Tx Debugger"])
+
+
+@app.get("/health", tags=["Infra"])
+def health() -> dict:
+    """Verifica se a API está respondendo."""
+    return {"status": "ok", "version": __version__}

arc_devkit/api/routes/__init__.py

@@ -0,0 +1 @@
+"""Rotas da API Arc DevKit."""

arc_devkit/api/routes/agents.py

@@ -0,0 +1,126 @@
+"""Rotas API para operações de carteira e agentes Arc."""
+
+from fastapi import APIRouter, HTTPException
+from pydantic import BaseModel, Field
+
+router = APIRouter()
+
+
+class WalletResponse(BaseModel):
+    """Dados de uma carteira criada ou consultada."""
+
+    address: str
+    balance_wei: str | None = None
+    balance_usdc: str | None = None
+    private_key: str | None = None  # presente apenas na criação
+
+
+class PaymentRequest(BaseModel):
+    """Corpo da requisição de pagamento."""
+
+    to: str = Field(..., description="Endereço EVM de destino.")
+    amount_usdc: float = Field(..., gt=0, description="Valor a transferir (em USDC).")
+    private_key: str = Field(..., description="Chave privada do remetente (hex).")
+    enviar: bool = Field(False, description="Se True, envia à rede; caso contrário retorna tx assinada.")
+
+
+class PaymentResponse(BaseModel):
+    """Resultado de um pagamento."""
+
+    status: str
+    from_address: str | None = Field(None, alias="from")
+    to: str | None = None
+    amount_usdc: float | None = None
+    tx_hash: str | None = None
+    raw_transaction: str | None = None
+    nota: str | None = None
+
+    model_config = {"populate_by_name": True}
+
+
+class BlockResponse(BaseModel):
+    """Número do bloco atual na Arc."""
+
+    block_number: int
+    chain_id: int
+
+
+@router.post("/wallet", response_model=WalletResponse, summary="Criar nova carteira")
+async def create_wallet() -> WalletResponse:
+    """
+    Cria uma nova carteira EVM para uso na Arc.
+
+    A chave privada retornada é gerada localmente — armazene com segurança.
+    Este endpoint não armazena a chave privada.
+    """
+    from arc_devkit.core.wallet import create_wallet
+
+    try:
+        carteira = create_wallet()
+        return WalletResponse(**carteira)
+    except Exception as exc:
+        raise HTTPException(status_code=500, detail=str(exc)) from exc
+
+
+@router.get(
+    "/balance/{address}",
+    response_model=WalletResponse,
+    summary="Consultar saldo de carteira",
+)
+async def get_balance(address: str) -> WalletResponse:
+    """Retorna o saldo nativo de um endereço Arc."""
+    from arc_devkit.core.wallet import get_balance
+
+    try:
+        resultado = get_balance(address)
+        return WalletResponse(
+            address=resultado["address"],
+            balance_wei=resultado["balance_wei"],
+            balance_usdc=str(resultado["balance_usdc"]),
+        )
+    except Exception as exc:
+        raise HTTPException(status_code=400, detail=str(exc)) from exc
+
+
+@router.post("/payment", response_model=PaymentResponse, summary="Executar pagamento")
+async def payment(body: PaymentRequest) -> PaymentResponse:
+    """
+    Prepara e (opcionalmente) envia um pagamento na Arc.
+
+    Com `enviar=false` (padrão), retorna a transação assinada sem enviá-la.
+    Com `enviar=true`, transmite à rede e retorna o tx_hash.
+    """
+    from arc_devkit.agents.payment_agent import PaymentAgent
+
+    try:
+        agente = PaymentAgent(private_key=body.private_key)
+        resultado = agente.execute(to=body.to, amount_usdc=body.amount_usdc, enviar=body.enviar)
+
+        if resultado.get("status") == "erro":
+            raise HTTPException(status_code=400, detail=resultado.get("error"))
+
+        return PaymentResponse(
+            status=resultado["status"],
+            **{"from": resultado.get("from")},
+            to=resultado.get("to"),
+            amount_usdc=resultado.get("amount_usdc"),
+            tx_hash=resultado.get("tx_hash"),
+            raw_transaction=resultado.get("raw_transaction"),
+            nota=resultado.get("nota"),
+        )
+    except HTTPException:
+        raise
+    except Exception as exc:
+        raise HTTPException(status_code=500, detail=str(exc)) from exc
+
+
+@router.get("/block", response_model=BlockResponse, summary="Bloco atual da Arc")
+async def get_block() -> BlockResponse:
+    """Retorna o número do bloco mais recente e o chain ID da Arc."""
+    from arc_devkit.core.connection import get_web3
+
+    try:
+        w3 = get_web3()
+        return BlockResponse(block_number=w3.eth.block_number, chain_id=w3.eth.chain_id)
+    except Exception as exc:
+        raise HTTPException(status_code=503, detail=str(exc)) from exc

arc_devkit/api/routes/copilot.py

@@ -0,0 +1,37 @@
+"""Rotas API para o Dev Copilot."""
+
+from fastapi import APIRouter, HTTPException
+from pydantic import BaseModel, Field
+
+router = APIRouter()
+
+
+class AskRequest(BaseModel):
+    """Corpo da requisição para o endpoint /copilot/ask."""
+
+    prompt: str = Field(..., min_length=3, description="Pergunta ou instrução.")
+
+
+class AskResponse(BaseModel):
+    """Resposta do Dev Copilot."""
+
+    response: str = Field(..., description="Resposta gerada pelo modelo.")
+    model: str = Field(..., description="Identificador do modelo usado.")
+
+
+@router.post("/ask", response_model=AskResponse, summary="Perguntar ao Dev Copilot")
+async def ask(body: AskRequest) -> AskResponse:
+    """
+    Envia uma pergunta ao Dev Copilot e retorna a resposta.
+
+    O Dev Copilot é especializado em desenvolvimento na Arc blockchain:
+    Solidity, web3.py, USDC, Circle Agent Stack e agentes econômicos.
+    """
+    from arc_devkit.copilot.agent import DevCopilot
+
+    try:
+        copilot = DevCopilot()
+        resposta = copilot.ask(body.prompt)
+        return AskResponse(response=resposta, model=DevCopilot.MODEL)
+    except Exception as exc:
+        raise HTTPException(status_code=500, detail=str(exc)) from exc

arc_devkit/api/routes/debugger.py

@@ -0,0 +1,55 @@
+"""Rotas API para o Tx Debugger."""
+
+from fastapi import APIRouter, HTTPException, Query
+from pydantic import BaseModel
+
+router = APIRouter()
+
+
+class GasEstimateResponse(BaseModel):
+    """Estimativa de custo de gás para uma transferência."""
+
+    gas_limit: int
+    gas_price_gwei: str
+    gas_price_wei: str
+    custo_usdc: str
+    custo_wei: str
+    amount_usdc: float
+    to: str
+
+
+@router.get("/estimate", response_model=GasEstimateResponse, summary="Estimar custo de gás")
+async def estimate_gas(
+    to: str = Query(..., description="Endereço EVM de destino."),
+    amount: float = Query(..., gt=0, description="Valor a transferir (em USDC)."),
+    from_address: str = Query("", description="Endereço remetente (opcional)."),
+) -> GasEstimateResponse:
+    """
+    Estima o custo de gás para uma transferência nativa na Arc.
+
+    Útil para exibir o custo ao usuário antes de confirmar uma transação.
+    """
+    from arc_devkit.core.gas import estimate_transfer
+
+    try:
+        est = estimate_transfer(to, amount, from_address or None)
+        return GasEstimateResponse(**est)
+    except Exception as exc:
+        raise HTTPException(status_code=400, detail=str(exc)) from exc
+
+
+@router.get("/{tx_hash}", summary="Analisar transação")
+async def analyze(tx_hash: str) -> dict:
+    """
+    Analisa uma transação Arc e retorna diagnóstico completo.
+
+    Combina dados do RPC (receipt + trace) com análise do Dev Copilot
+    para gerar um relatório em linguagem natural em português.
+    """
+    from arc_devkit.debugger.tx_analyzer import TxAnalyzer
+
+    try:
+        analyzer = TxAnalyzer()
+        return analyzer.analyze(tx_hash)
+    except Exception as exc:
+        raise HTTPException(status_code=500, detail=str(exc)) from exc

arc_devkit/cli/__init__.py

@@ -0,0 +1 @@
+"""Módulo CLI — interface de linha de comando do Arc DevKit."""

arc_devkit/cli/commands/__init__.py

@@ -0,0 +1 @@
+"""Comandos da CLI Arc DevKit."""