arc-devkit 0.2.0__py3-none-any.whl → 0.4.0__py3-none-any.whl

arc_devkit/__init__.py

@@ -1,3 +1,3 @@
-"""Arc DevKit — Ferramentas para desenvolvedores da Arc blockchain (Circle)."""
+"""Arc DevKit — Developer tools for the Arc blockchain by Circle."""
 
-__version__ = "0.1.0"
+__version__ = "0.4.0"

arc_devkit/agents/__init__.py

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

arc_devkit/agents/async_base.py

@@ -0,0 +1,29 @@
+"""Async abstract base class for Arc economic agents."""
+
+import asyncio
+import logging
+from abc import abstractmethod
+
+from arc_devkit.agents.base_agent import BaseAgent
+
+logger = logging.getLogger(__name__)
+
+
+class AsyncBaseAgent(BaseAgent):
+    """
+    Async variant of BaseAgent — get_balance() and execute() are coroutines.
+
+    Inherits wallet resolution and RPC connection from BaseAgent.
+    Blocking web3 calls are dispatched to a thread pool via asyncio.to_thread()
+    so the event loop is never blocked.
+    """
+
+    @abstractmethod  # type: ignore[override]
+    async def get_balance(self) -> dict: ...
+
+    @abstractmethod  # type: ignore[override]
+    async def execute(self, **kwargs) -> dict: ...
+
+    async def _acall_rpc(self, fn, *args, **kwargs):
+        """Run a blocking RPC call in a thread without blocking the event loop."""
+        return await asyncio.to_thread(fn, *args, **kwargs)

arc_devkit/agents/async_monitor.py

@@ -0,0 +1,316 @@
+"""Async monitor agent — detects balance changes in Arc wallets (async variant)."""
+
+import asyncio
+import json
+import logging
+from collections.abc import AsyncIterator, Callable, Coroutine
+from pathlib import Path
+from typing import Any, cast
+
+import httpx
+from eth_typing import ChecksumAddress
+from web3 import Web3
+
+from arc_devkit.agents.async_base import AsyncBaseAgent
+
+logger = logging.getLogger(__name__)
+
+_TRANSFER_ABI = [
+    {
+        "anonymous": False,
+        "inputs": [
+            {"indexed": True, "name": "from", "type": "address"},
+            {"indexed": True, "name": "to", "type": "address"},
+            {"indexed": False, "name": "value", "type": "uint256"},
+        ],
+        "name": "Transfer",
+        "type": "event",
+    }
+]
+
+_WEBHOOK_TIMEOUT = 10
+
+# Callback type: may be a plain function OR an async coroutine function
+_Callback = Callable[[dict], Any]
+
+
+class AsyncMonitorAgent(AsyncBaseAgent):
+    """
+    Async version of MonitorAgent.
+
+    Uses asyncio.sleep() instead of time.sleep() so it integrates cleanly with
+    FastAPI WebSocket handlers and other async applications.
+    All balance reads are dispatched via _acall_rpc() to avoid blocking the loop.
+    """
+
+    def __init__(
+        self,
+        watched_address: str | None = None,
+        watched_addresses: list[str] | None = None,
+        interval_seconds: int = 15,
+        min_change_wei: int = 0,
+        state_file: str | Path | None = None,
+        usdc_contract_address: str | None = None,
+        webhook_url: str | None = None,
+        **kwargs: Any,
+    ) -> None:
+        super().__init__(**kwargs)
+
+        addrs: list[str] = []
+        if watched_addresses:
+            addrs = [Web3.to_checksum_address(a) for a in watched_addresses]
+        elif watched_address:
+            addrs = [Web3.to_checksum_address(watched_address)]
+        self._watched: list[str] = addrs
+        self._watched_lower: set[str] = {a.lower() for a in addrs}
+
+        self._interval = interval_seconds
+        self._min_change_wei = min_change_wei
+        self._last_balances: dict[str, int] = {}
+        self._last_erc20_block: int = 0
+        self._running = False
+        self._state_file = Path(state_file) if state_file else None
+        self._webhook_url = webhook_url
+
+        self._usdc_contract = None
+        if usdc_contract_address:
+            self._usdc_contract = self._w3.eth.contract(
+                address=Web3.to_checksum_address(usdc_contract_address),
+                abi=_TRANSFER_ABI,
+            )
+
+        if self._state_file and self._state_file.exists():
+            try:
+                saved = json.loads(self._state_file.read_text())
+                if "balances" in saved:
+                    self._last_balances = {k: int(v) for k, v in saved["balances"].items()}
+                    self._last_erc20_block = int(saved.get("last_erc20_block", 0))
+                else:
+                    self._last_balances = {k: int(v) for k, v in saved.items()}
+                logger.info("State restored from %s", self._state_file)
+            except Exception as exc:
+                logger.warning("Failed to restore state: %s", exc)
+
+    @property
+    def watched_addresses(self) -> list[str]:
+        return list(self._watched)
+
+    def _save_state(self) -> None:
+        if self._state_file:
+            try:
+                self._state_file.write_text(
+                    json.dumps({
+                        "balances": {k: str(v) for k, v in self._last_balances.items()},
+                        "last_erc20_block": self._last_erc20_block,
+                    })
+                )
+            except Exception as exc:
+                logger.warning("Failed to save state: %s", exc)
+
+    async def _fire_webhook(self, event: dict) -> None:
+        if not self._webhook_url:
+            return
+        try:
+            async with httpx.AsyncClient(timeout=_WEBHOOK_TIMEOUT) as client:
+                resp = await client.post(
+                    self._webhook_url,
+                    json=event,
+                    headers={"Content-Type": "application/json"},
+                )
+                resp.raise_for_status()
+                logger.debug("Webhook delivered: %s", resp.status_code)
+        except Exception as exc:
+            logger.warning("Webhook delivery failed (%s): %s", self._webhook_url, exc)
+
+    async def _emit(self, event: dict, callback: _Callback | None) -> None:
+        """Fire callback (sync or async) and webhook."""
+        if callback:
+            result = callback(event)
+            if asyncio.iscoroutine(result):
+                await result
+        await self._fire_webhook(event)
+
+    async def _scan_erc20_events(
+        self,
+        from_block: int,
+        to_block: int,
+        callback: _Callback | None,
+    ) -> None:
+        if not self._usdc_contract or not self._watched:
+            return
+        try:
+            logs = await self._acall_rpc(
+                self._usdc_contract.events.Transfer.get_logs,  # type: ignore[attr-defined]
+                from_block=from_block,
+                to_block=to_block,
+            )
+        except Exception as exc:
+            logger.debug("ERC-20 log query failed: %s", exc)
+            return
+
+        for log in logs:
+            args = log.get("args", {})
+            sender = (args.get("from") or "").lower()
+            recipient = (args.get("to") or "").lower()
+            value = args.get("value", 0)
+
+            if sender not in self._watched_lower and recipient not in self._watched_lower:
+                continue
+
+            direction = "credit" if recipient in self._watched_lower else "debit"
+            address = next(
+                (a for a in self._watched if a.lower() == (recipient if direction == "credit" else sender)),
+                "",
+            )
+
+            event = {
+                "address": address,
+                "event_type": "erc20_transfer",
+                "token": "USDC",
+                "from": args.get("from"),
+                "to": args.get("to"),
+                "value_atomic": str(value),
+                "tx_hash": log.get("transactionHash", b"").hex()
+                if hasattr(log.get("transactionHash", b""), "hex")
+                else str(log.get("transactionHash", "")),
+                "block": log.get("blockNumber"),
+                "type": direction,
+            }
+            self.log(f"[ERC-20] {direction} {value} atomic USDC → {address[:10]}")
+            await self._emit(event, callback)
+
+    async def get_balance(self) -> dict:  # type: ignore[override]
+        resultado = {}
+        for addr in self._watched:
+            wei = await self._acall_rpc(
+                self._w3.eth.get_balance, cast(ChecksumAddress, addr)
+            )
+            resultado[addr] = {
+                "address": addr,
+                "balance_wei": str(wei),
+                "balance_eth": str(self._w3.from_wei(wei, "ether")),
+            }
+        return resultado
+
+    async def execute(  # type: ignore[override]
+        self,
+        callback: _Callback | None = None,
+        max_iterations: int = 0,
+    ) -> dict:
+        """
+        Start the async wallet monitoring loop.
+
+        Args:
+            callback: Called with an event dict on each detected change.
+                      May be a plain function or an async coroutine function.
+            max_iterations: Maximum iterations (0 = infinite until stop()).
+        """
+        self._running = True
+
+        for addr in self._watched:
+            if addr not in self._last_balances:
+                self._last_balances[addr] = await self._acall_rpc(
+                    self._w3.eth.get_balance, cast(ChecksumAddress, addr)
+                )
+
+        if self._usdc_contract and self._last_erc20_block == 0:
+            try:
+                self._last_erc20_block = await self._acall_rpc(
+                    lambda: self._w3.eth.block_number
+                )
+            except Exception:
+                pass
+
+        iterations = 0
+        self.log(f"[Async] Monitoring {len(self._watched)} wallet(s) every {self._interval}s")
+
+        while self._running:
+            for addr in self._watched:
+                current_balance = await self._acall_rpc(
+                    self._w3.eth.get_balance, cast(ChecksumAddress, addr)
+                )
+                prev_balance = self._last_balances.get(addr, current_balance)
+                delta = current_balance - prev_balance
+
+                if delta != 0 and abs(delta) >= self._min_change_wei:
+                    event = {
+                        "address": addr,
+                        "prev_balance_wei": str(prev_balance),
+                        "balance_wei": str(current_balance),
+                        "change_wei": str(delta),
+                        "type": "credit" if delta > 0 else "debit",
+                        "event_type": "native",
+                    }
+                    self.log(f"[{addr[:10]}] Change: {delta:+d} wei ({event['type']})")
+                    await self._emit(event, callback)
+                    self._last_balances[addr] = current_balance
+
+            if self._usdc_contract:
+                try:
+                    current_block = await self._acall_rpc(lambda: self._w3.eth.block_number)
+                    if current_block > self._last_erc20_block:
+                        await self._scan_erc20_events(
+                            from_block=self._last_erc20_block + 1,
+                            to_block=current_block,
+                            callback=callback,
+                        )
+                        self._last_erc20_block = current_block
+                except Exception as exc:
+                    logger.debug("ERC-20 scan skipped: %s", exc)
+
+            await asyncio.to_thread(self._save_state)
+            iterations += 1
+            if max_iterations and iterations >= max_iterations:
+                break
+
+            await asyncio.sleep(self._interval)
+
+        return {"status": "done", "iterations": iterations}
+
+    async def event_stream(
+        self,
+        max_events: int = 0,
+    ) -> AsyncIterator[dict]:
+        """
+        Async generator that yields events as they occur.
+
+        Starts execute() as a background task and forwards events via an
+        internal asyncio.Queue. Safe to use inside WebSocket handlers.
+
+        Usage:
+            async for event in monitor.event_stream():
+                await ws.send_json(event)
+        """
+        queue: asyncio.Queue[dict] = asyncio.Queue()
+        count = 0
+
+        async def _enqueue(event: dict) -> None:
+            await queue.put(event)
+
+        task = asyncio.create_task(self.execute(callback=_enqueue))
+        try:
+            while True:
+                # Drain remaining events after the task finishes
+                if task.done() and queue.empty():
+                    break
+                try:
+                    event = await asyncio.wait_for(queue.get(), timeout=1.0)
+                except asyncio.TimeoutError:
+                    continue  # re-check task.done() on next iteration
+                yield event
+                count += 1
+                if max_events and count >= max_events:
+                    break
+        finally:
+            self.stop()
+            task.cancel()
+            try:
+                await task
+            except asyncio.CancelledError:
+                pass
+
+    def stop(self) -> None:
+        """Stop the monitoring loop on the next iteration."""
+        self._running = False
+        self._save_state()
+        self.log("Async monitoring stopped.")

arc_devkit/agents/base_agent.py

@@ -1,21 +1,41 @@
-"""Classe base abstrata para todos os agentes econômicos Arc."""
+"""Abstract base class for all Arc economic agents."""
 
 import logging
 from abc import ABC, abstractmethod
 
 from eth_account import Account
+from tenacity import retry, retry_if_exception_type, stop_after_attempt, wait_exponential
 from web3 import Web3
 
 logger = logging.getLogger(__name__)
 
 
+def _make_web3(rpc_url: str) -> Web3:
+    from web3.middleware import ExtraDataToPOAMiddleware
+
+    w3 = Web3(Web3.HTTPProvider(rpc_url, request_kwargs={"timeout": 10}))
+    w3.middleware_onion.inject(ExtraDataToPOAMiddleware, layer=0)
+    return w3
+
+
+def _get_web3_with_fallback(rpc_urls: tuple[str, ...]) -> Web3:
+    """Try each URL in order; raise ConnectionError if all fail."""
+    for url in rpc_urls:
+        try:
+            w3 = _make_web3(url)
+            if w3.is_connected():
+                return w3
+        except Exception as exc:
+            logger.warning("RPC %s unavailable: %s", url, exc)
+    raise ConnectionError(f"No RPC available: {rpc_urls}")
+
+
 class BaseAgent(ABC):
     """
-    Fundação para todos os agentes econômicos Arc.
+    Foundation for all Arc economic agents.
 
-    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.
+    Manages blockchain connection, wallet identity, and logging helpers.
+    Subclasses implement get_balance() and execute() with agent-specific logic.
     """
 
     def __init__(
@@ -24,28 +44,38 @@ class BaseAgent(ABC):
         rpc_url: str | None = None,
     ) -> None:
         """
-        Inicializa o agente com carteira e conexão RPC.
+        Initialize the agent with wallet and RPC connection.
 
         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.
+            private_key: Hex private key (optional). Falls back to ARC_PRIVATE_KEY
+                         env var. Without a key the agent runs in read-only mode.
+            rpc_url: RPC node URL (optional). Falls back to ARC_RPC_URL.
+                     Comma-separated list enables automatic failover.
         """
         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()
+        # Multi-RPC support
+        if rpc_url:
+            # Explicit rpc_url — may be a comma-separated list
+            rpc_urls = tuple(u.strip() for u in rpc_url.split(",") if u.strip())
+            self._w3: Web3 = _get_web3_with_fallback(rpc_urls)
+        elif len(settings.arc_rpc_urls) > 1:
+            # Multiple RPCs configured — activate automatic fallback
+            self._w3 = _get_web3_with_fallback(settings.arc_rpc_urls)
+        else:
+            # Single RPC — use default get_web3() (mockable in tests)
+            self._w3 = get_web3()
 
-        # Resolver chave privada: argumento > variável de ambiente > None
-        _chave = private_key or settings.arc_private_key
+        # Resolve private key: argument > env var > None
+        _key = private_key or settings.arc_private_key
 
-        if _chave:
-            account = Account.from_key(_chave)
+        if _key:
+            account = Account.from_key(_key)
             self._address: str | None = account.address
-            self._private_key: str | None = _chave
+            self._private_key: str | None = _key
             logger.info(
-                "[%s] Inicializado com carteira %s",
+                "[%s] Initialized with wallet %s",
                 self.__class__.__name__,
                 self._address,
             )
@@ -53,35 +83,31 @@ class BaseAgent(ABC):
             self._address = None
             self._private_key = None
             logger.warning(
-                "[%s] Sem chave privada — modo somente leitura.",
+                "[%s] No private key — read-only mode.",
                 self.__class__.__name__,
             )
 
     @property
     def wallet_address(self) -> str | None:
-        """Endereço checksummed da carteira do agente."""
+        """Checksummed wallet address."""
         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'.
-        """
-        ...
+    @retry(
+        retry=retry_if_exception_type((ConnectionError, TimeoutError, OSError)),
+        wait=wait_exponential(multiplier=1, min=1, max=10),
+        stop=stop_after_attempt(3),
+        reraise=True,
+    )
+    def _call_rpc(self, fn, *args, **kwargs):
+        """Execute an RPC call with automatic retry on network failures."""
+        return fn(*args, **kwargs)
 
     @abstractmethod
-    def execute(self, **kwargs) -> dict:
-        """
-        Executa a ação principal do agente.
+    def get_balance(self) -> dict: ...
 
-        Returns:
-            Dict com o resultado da execução, incluindo 'status'.
-        """
-        ...
+    @abstractmethod
+    def execute(self, **kwargs) -> dict: ...
 
     def log(self, msg: str) -> None:
-        """Helper de log padronizado: prefixo com nome da classe."""
+        """Standardized log helper: prefixes with class name."""
         logger.info("[%s] %s", self.__class__.__name__, msg)