arc-devkit 0.2.0__py3-none-any.whl

arc_devkit/core/wallet.py

@@ -0,0 +1,72 @@
+"""Operações de carteira na Arc blockchain."""
+
+import logging
+from decimal import Decimal
+
+from eth_account import Account
+from web3 import Web3
+
+from arc_devkit.core.connection import get_web3
+
+logger = logging.getLogger(__name__)
+
+# USDC usa 6 casas decimais (padrão Circle)
+USDC_DECIMALS = 6
+USDC_MULTIPLIER = 10**USDC_DECIMALS
+
+
+def create_wallet() -> dict[str, str]:
+    """
+    Cria uma nova carteira EVM aleatória.
+
+    Returns:
+        Dict com 'address' (checksummed) e 'private_key' (hex com prefixo 0x).
+
+    Warning:
+        A chave privada gerada nunca é armazenada — guarde-a imediatamente
+        em local seguro. Perder a chave significa perder acesso à carteira.
+    """
+    account = Account.create()
+    logger.info("Nova carteira criada: %s", account.address)
+    key_hex = account.key.hex()
+    return {
+        "address": account.address,
+        "private_key": key_hex if key_hex.startswith("0x") else f"0x{key_hex}",
+    }
+
+
+def get_balance(address: str) -> dict[str, str | Decimal]:
+    """
+    Retorna o saldo nativo de um endereço Arc.
+
+    Na Arc, USDC é o token de gás. Este método retorna o saldo nativo
+    da rede. Para saldo do contrato USDC ERC-20, será necessário o
+    endereço do contrato USDC na Arc (a confirmar com a documentação oficial).
+
+    Args:
+        address: Endereço EVM (com ou sem checksum).
+
+    Returns:
+        Dict com address, balance_wei e balance_usdc (Decimal).
+    """
+    w3 = get_web3()
+    checksum_addr = Web3.to_checksum_address(address)
+
+    wei = w3.eth.get_balance(checksum_addr)
+    # Converte para valor legível (18 casas decimais para saldo nativo)
+    balance_human = Decimal(str(w3.from_wei(wei, "ether")))
+
+    logger.debug("Saldo de %s: %s (%d wei)", checksum_addr, balance_human, wei)
+
+    return {
+        "address": checksum_addr,
+        "balance_wei": str(wei),
+        "balance_usdc": balance_human,
+    }
+
+
+def get_block_number() -> int:
+    """Retorna o número do bloco mais recente na Arc."""
+    bloco = get_web3().eth.block_number
+    logger.debug("Bloco atual: #%d", bloco)
+    return bloco

arc_devkit/debugger/__init__.py

@@ -0,0 +1,5 @@
+"""Módulo Tx Debugger — análise de transações Arc."""
+
+from arc_devkit.debugger.tx_analyzer import TxAnalyzer
+
+__all__ = ["TxAnalyzer"]

arc_devkit/debugger/tx_analyzer.py

@@ -0,0 +1,107 @@
+"""Analisador de transações Arc — combina dados RPC com análise via Claude."""
+
+import logging
+from decimal import Decimal
+
+from arc_devkit.core.connection import get_web3
+
+logger = logging.getLogger(__name__)
+
+# Prompt enviado ao Claude com os dados brutos da transação
+_PROMPT_ANALISE = """\
+Analise os dados desta transação da Arc blockchain e responda em português brasileiro.
+
+Dados da transação:
+{dados}
+
+Responda de forma estruturada:
+1. **O que a transação fez** — descreva em linguagem simples
+2. **Status** — sucesso ou falha, com motivo se houver erro
+3. **Custo em USDC** — gás consumido convertido para USDC
+4. **Sugestão** — se houve erro, como corrigir; se sucesso, alguma otimização possível
+"""
+
+
+class TxAnalyzer:
+    """
+    Analisa transações Arc: busca dados via RPC e gera diagnóstico com IA.
+
+    O analisador combina eth_getTransaction + eth_getTransactionReceipt
+    com o Dev Copilot para produzir uma análise em linguagem natural.
+    """
+
+    def __init__(self) -> None:
+        self._w3 = get_web3()
+
+    def analyze(self, tx_hash: str) -> dict:
+        """
+        Analisa uma transação e retorna diagnóstico completo.
+
+        Args:
+            tx_hash: Hash da transação (formato 0x...).
+
+        Returns:
+            Dict com: status, resumo, custo_usdc, erro, sugestao,
+            e dados brutos da transação.
+        """
+        logger.info("Analisando transação: %s", tx_hash)
+
+        # --- 1. Buscar dados brutos via RPC ---
+        try:
+            tx = self._w3.eth.get_transaction(tx_hash)
+            receipt = self._w3.eth.get_transaction_receipt(tx_hash)
+        except Exception as exc:
+            logger.error("Erro ao buscar transação %s: %s", tx_hash, exc)
+            return {
+                "hash": tx_hash,
+                "status": "erro",
+                "resumo": f"Não foi possível buscar a transação: {exc}",
+                "custo_usdc": "0",
+                "erro": str(exc),
+                "sugestao": "Verifique se o hash está correto e se a RPC está acessível.",
+            }
+
+        # --- 2. Calcular custo em USDC ---
+        gas_usado = receipt.get("gasUsed", 0)
+        gas_price = tx.get("gasPrice", 0)
+        custo_wei = gas_usado * gas_price
+        # Converte para unidade legível (18 decimais para o token nativo)
+        custo_decimal = Decimal(str(self._w3.from_wei(custo_wei, "ether")))
+
+        # --- 3. Montar resumo dos dados para o prompt ---
+        status_str = "sucesso" if receipt.get("status") == 1 else "revertida"
+        dados_resumo = {
+            "hash": tx_hash,
+            "de": tx.get("from"),
+            "para": tx.get("to"),
+            "valor_wei": str(tx.get("value", 0)),
+            "gas_limite": tx.get("gas"),
+            "gas_usado": gas_usado,
+            "status": status_str,
+            "custo_estimado_usdc": str(custo_decimal),
+            "bloco": receipt.get("blockNumber"),
+            "logs_count": len(receipt.get("logs", [])),
+        }
+
+        logger.debug("Dados coletados: %s", dados_resumo)
+
+        # --- 4. Solicitar análise ao Dev Copilot ---
+        try:
+            from arc_devkit.copilot.agent import DevCopilot
+
+            copilot = DevCopilot()
+            prompt = _PROMPT_ANALISE.format(dados=dados_resumo)
+            resumo = copilot.ask(prompt)
+        except Exception as exc:
+            logger.warning("Análise de IA indisponível: %s", exc)
+            resumo = f"Status: {status_str} | Gas usado: {gas_usado} | Custo: {custo_decimal} USDC"
+
+        return {
+            "hash": tx_hash,
+            "status": status_str,
+            "resumo": resumo,
+            "custo_usdc": str(custo_decimal),
+            "erro": None if status_str == "sucesso" else "Transação revertida",
+            "sugestao": "",  # incluído no resumo gerado pelo Claude
+            "dados_brutos": dados_resumo,
+        }

arc_devkit-0.2.0.dist-info/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,31 @@
+arc_devkit/__init__.py,sha256=_U6nBRL-8xVY_OTVrWnhiP6uXQJVOqav-5HmuWzNRx4,105
+arc_devkit/config.py,sha256=v1Qbvt92i2grTnpfW29kpxyQL18Cd-KlMDbBs5Ov09c,2174
+arc_devkit/agents/__init__.py,sha256=IMZVCD5QyeOCVc69SA-mAhJcvl5NtUf_H8NFfi9SU1A,297
+arc_devkit/agents/base_agent.py,sha256=sqjJNZ4koGSAvj85YMRePUnKxI7ddo3KA_VpgmKirSk,2612
+arc_devkit/agents/monitor_agent.py,sha256=orOJ5Bc5vaRpGE76hljsexNAFy8A6Qn5C9N9nIxAkT0,3416
+arc_devkit/agents/payment_agent.py,sha256=gdHoecngKZX0bzrEjQCEvnH0oETXaFXcF53KnyctjGw,3411
+arc_devkit/api/__init__.py,sha256=Z25C5ONPiCIoviRZYcvcAGIfkaRkI2kMiWBEuo1Lw6k,60
+arc_devkit/api/main.py,sha256=zUDbJTuN6W2Uez8FpqO-5dhCZsj0VfhjbnMNOTVDxhI,1252
+arc_devkit/api/routes/__init__.py,sha256=j3UP1a0EGfALvvpq-otJccTXiUT7UFLyveOw66cPDoA,31
+arc_devkit/api/routes/agents.py,sha256=BAl83BgVJcZFE6Xl4-7YJld7gLYxDCB3fQOKUdXNdMI,4195
+arc_devkit/api/routes/copilot.py,sha256=gCTzTlkKocCea4iPsogsN5L6xwyK66f5gygiYKCMA2I,1199
+arc_devkit/api/routes/debugger.py,sha256=GEdYEefCm0ETzBbtFbtqBGARi1jYTGmLn9M2zk0zf8k,1758
+arc_devkit/cli/__init__.py,sha256=HxXvqwve8YcVgcPMtyh1Eh_pEP7OhNG1xV1s4XWyIsQ,67
+arc_devkit/cli/main.py,sha256=lnG6fNynMemkXglUGydPIEYOFqB7TBAm3EbRVtvvq2Q,2574
+arc_devkit/cli/commands/__init__.py,sha256=9mV6f6CarhEi8Q0qIiw-JB2TU4UqVqTuvEX9ICyQ13o,34
+arc_devkit/cli/commands/agent.py,sha256=Mwh99CSywr3eRFuyTHDsk6J4PAPl7OiBtWISVNfIJm8,6243
+arc_devkit/cli/commands/copilot.py,sha256=bqxw6rYSeYPjUVAgsDZjVxwfI9M-gABX0UUviSxzNS4,1051
+arc_devkit/cli/commands/debug.py,sha256=h9zqordjnPnZNrA1La5Cq9HACcMTMEEZY9vlgtPFJjc,3453
+arc_devkit/copilot/__init__.py,sha256=ux9txnF1N7tSNaLVuGuk-7Uqkfe1LSnPwzHcFi5-HRc,151
+arc_devkit/copilot/agent.py,sha256=SQ6VAj4dRF48HZLrdHvNEDqhis-XSTMMNS_bjn_PpLA,2698
+arc_devkit/core/__init__.py,sha256=cyP5-3A-bOahtvgpce-NkwOD0PaP2Zx423B3iSzLpPo,67
+arc_devkit/core/connection.py,sha256=h045FcmvkSVSIZoK9LTxU6IgblcXfiZuvkEhC1lS2xY,1348
+arc_devkit/core/gas.py,sha256=eww3ANeFDi4vWBaTvC9yV66ZtjyQZOlMWig8G-YuLn0,1961
+arc_devkit/core/wallet.py,sha256=eRkQiC9-gDIXqQ7MFwsvC7n0-_GXBJkL53aU-Pa87ZE,2100
+arc_devkit/debugger/__init__.py,sha256=p9--cHKoWMjuemxzfb--PUJ7EIMyLXR8cIKb3w6rweQ,142
+arc_devkit/debugger/tx_analyzer.py,sha256=PYB62AjxczK_EMWmojZK_ffEXimfL71vtdXKmxJaHuo,3899
+arc_devkit-0.2.0.dist-info/METADATA,sha256=4ByhBfDaS_9oG_1sK3IW_EAGw_iJaY6dBLokYbC7jdM,7608
+arc_devkit-0.2.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+arc_devkit-0.2.0.dist-info/entry_points.txt,sha256=wKF8LAEu1vWKfiujTrp7h_df1kVCsbuGl96Ql75QjfU,54
+arc_devkit-0.2.0.dist-info/top_level.txt,sha256=_8As_e0w6FWAQptRM9vVTpBaTQmGKjajyiscnqRps-8,11
+arc_devkit-0.2.0.dist-info/RECORD,,

arc_devkit-0.2.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

arc_devkit-0.2.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+arcdevkit = arc_devkit.cli.main:app

arc_devkit-0.2.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+arc_devkit