arc-devkit 0.4.6__tar.gz → 0.4.7__tar.gz

{arc_devkit-0.4.6 → arc_devkit-0.4.7}/PKG-INFO

@@ -1,15 +1,16 @@
 Metadata-Version: 2.4
 Name: arc-devkit
-Version: 0.4.6
+Version: 0.4.7
 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
+Author: Arc DevKit Contributors
+License: MIT
+Project-URL: Homepage, https://github.com/Jeielsantosdev/arc_dev_kit
+Project-URL: Repository, https://github.com/Jeielsantosdev/arc_dev_kit
+Project-URL: Issues, https://github.com/Jeielsantosdev/arc_dev_kit/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
@@ -35,7 +36,11 @@ Requires-Dist: pytest-asyncio>=0.23; extra == "dev"
 Requires-Dist: pytest-cov>=4.0; extra == "dev"
 Requires-Dist: ruff>=0.6; extra == "dev"
 Requires-Dist: mypy>=1.8; extra == "dev"
+Requires-Dist: bandit>=1.7; extra == "dev"
+Requires-Dist: pip-audit>=2.7; extra == "dev"
 Requires-Dist: httpx>=0.27; extra == "dev"
+Provides-Extra: security
+Requires-Dist: keyring>=24; extra == "security"
 
 # Arc DevKit
 
@@ -48,8 +53,6 @@ Requires-Dist: httpx>=0.27; extra == "dev"
 
 **Arc DevKit** is a complete Python SDK for developers building on the **Arc blockchain** — Circle's EVM-compatible Layer 1 with USDC as the gas token and sub-second finality.
 
-**link to project**  https://arc-dev-kit-uxun.vercel.app/
-
 It solves the practical friction of building on Arc: USDC gas accounting, PoA middleware, ERC-20 monitoring, async agents, WebSocket streaming, and AI-assisted debugging — all packaged and ready to use.
 
 ---

{arc_devkit-0.4.6 → arc_devkit-0.4.7}/README.md

@@ -9,8 +9,6 @@
 
 **Arc DevKit** is a complete Python SDK for developers building on the **Arc blockchain** — Circle's EVM-compatible Layer 1 with USDC as the gas token and sub-second finality.
 
-**link to project**  https://arc-dev-kit-uxun.vercel.app/
-
 It solves the practical friction of building on Arc: USDC gas accounting, PoA middleware, ERC-20 monitoring, async agents, WebSocket streaming, and AI-assisted debugging — all packaged and ready to use.
 
 ---

arc_devkit-0.4.7/arc_devkit/agents/autonomous.py

@@ -0,0 +1,108 @@
+"""Autonomous agent behaviors — actions that run without a human in the loop.
+
+Every autonomous behavior REQUIRES Guardrails: kill switch, recipient whitelist,
+and daily spend limit are enforced on each action, and every execution is
+recorded in the audit log.
+"""
+
+import logging
+from decimal import Decimal
+
+from arc_devkit.agents.guardrails import Guardrails
+from arc_devkit.agents.monitor_agent import MonitorAgent
+from arc_devkit.agents.payment_agent import PaymentAgent
+from arc_devkit.core.validation import validate_address, validate_amount
+
+logger = logging.getLogger(__name__)
+
+
+class AutoRefueler:
+    """
+    Keeps a target address funded: when its native balance drops below a
+    threshold, a PaymentAgent automatically tops it up.
+
+    The refuel transfer goes through all guardrails (kill switch, whitelist,
+    daily spend limit) and mandatory simulation before broadcast.
+
+    Example:
+        guardrails = Guardrails.from_settings()
+        refueler = AutoRefueler(
+            target_address="0xServiceWallet...",
+            threshold_usdc=Decimal("0.5"),
+            top_up_amount_usdc=Decimal("1.0"),
+            payment_agent=PaymentAgent(guardrails=guardrails),
+            guardrails=guardrails,
+        )
+        monitor = MonitorAgent(watched_address="0xServiceWallet...", interval_seconds=30)
+        refueler.attach(monitor)
+        monitor.execute()
+    """
+
+    def __init__(
+        self,
+        target_address: str,
+        threshold_usdc: Decimal,
+        top_up_amount_usdc: Decimal,
+        payment_agent: PaymentAgent,
+        guardrails: Guardrails,
+    ) -> None:
+        """
+        Args:
+            target_address: Address to keep funded.
+            threshold_usdc: Refuel when balance drops below this value.
+            top_up_amount_usdc: Amount transferred on each refuel.
+            payment_agent: Funded PaymentAgent used to send the top-up.
+            guardrails: Required autonomy guardrails.
+        """
+        self._target = validate_address(target_address)
+        self._threshold = validate_amount(threshold_usdc)
+        self._top_up = validate_amount(top_up_amount_usdc)
+        self._payment_agent = payment_agent
+        self._guardrails = guardrails
+        # Ensure the payment agent enforces the same guardrails
+        if self._payment_agent._guardrails is None:
+            self._payment_agent._guardrails = guardrails
+
+    def attach(self, monitor: MonitorAgent) -> None:
+        """Register the refuel action on a monitor's low-balance trigger."""
+        threshold_wei = int(self._threshold * Decimal(10**18))
+        monitor.on_low_balance(threshold_wei, self._refuel)
+        logger.info(
+            "AutoRefueler attached: %s below %s USDC → top up %s USDC",
+            self._target[:10],
+            self._threshold,
+            self._top_up,
+        )
+
+    def _refuel(self, event: dict) -> None:
+        """Trigger action: execute the guarded top-up transfer."""
+        address = event.get("address", self._target)
+        logger.info(
+            "AutoRefueler firing for %s (balance %s wei)", address, event.get("balance_wei")
+        )
+
+        result = self._payment_agent.execute(
+            to=self._target,
+            amount_usdc=float(self._top_up),
+            enviar=True,
+            wait_receipt=False,
+            trigger="on_low_balance",
+        )
+
+        status = result.get("status")
+        if status in {"blocked", "error", "simulation_failed"}:
+            logger.warning("AutoRefueler blocked/failed: %s", result.get("error"))
+            self._guardrails.audit(
+                agent="AutoRefueler",
+                trigger="on_low_balance",
+                action="refuel_denied",
+                target=self._target,
+                reason=result.get("error", status),
+            )
+        else:
+            logger.info(
+                "AutoRefueler sent %s USDC → %s (%s)",
+                self._top_up,
+                self._target,
+                result.get("tx_hash"),
+            )

arc_devkit-0.4.7/arc_devkit/agents/coordinator.py

@@ -0,0 +1,128 @@
+"""Coordinator agent — plans multi-agent workflows from natural-language goals.
+
+The coordinator uses the DevCopilot in agentic mode (read-only tools) to inspect
+on-chain state and produce an execution plan. Steps that move funds are only
+executed when a PaymentAgent with Guardrails is registered — and every action
+passes the kill switch, whitelist, and spend-limit checks.
+"""
+
+import logging
+
+from arc_devkit.agents.event_bus import EventBus
+from arc_devkit.agents.guardrails import Guardrails
+from arc_devkit.agents.monitor_agent import MonitorAgent
+from arc_devkit.agents.payment_agent import PaymentAgent
+
+logger = logging.getLogger(__name__)
+
+_PLAN_PROMPT = """\
+You are coordinating economic agents on the Arc blockchain. Analyze the goal
+below using your read-only tools (balances, gas, block info) and produce a plan.
+
+Goal: {goal}
+
+Respond with:
+1. **Current state** — relevant on-chain data you gathered
+2. **Plan** — numbered steps; mark each step as [read-only] or [requires-funds]
+3. **Risks** — what could go wrong and which guardrails apply
+"""
+
+
+class CoordinatorAgent:
+    """
+    Orchestrates DevCopilot, PaymentAgent, and MonitorAgent around a goal.
+
+    Example:
+        coordinator = CoordinatorAgent(guardrails=Guardrails.from_settings())
+        coordinator.register_payment_agent(PaymentAgent(guardrails=guardrails))
+        result = coordinator.plan("keep 0xAbc... above 0.5 USDC")
+    """
+
+    def __init__(self, guardrails: Guardrails | None = None, bus: EventBus | None = None) -> None:
+        self._guardrails = guardrails or Guardrails.from_settings()
+        self.bus = bus or EventBus()
+        self._payment_agent: PaymentAgent | None = None
+        self._monitors: list[MonitorAgent] = []
+
+    def register_payment_agent(self, agent: PaymentAgent) -> None:
+        """Register the payment agent used for fund-moving steps (guardrails enforced)."""
+        if agent._guardrails is None:
+            agent._guardrails = self._guardrails
+        self._payment_agent = agent
+
+    def register_monitor(self, monitor: MonitorAgent) -> None:
+        """Register a monitor whose events feed the coordinator's bus."""
+        self._monitors.append(monitor)
+
+    def plan(self, goal: str, max_iterations: int = 10) -> dict:
+        """
+        Produce an execution plan for a natural-language goal.
+
+        Uses DevCopilot agentic mode with read-only tools; no funds are moved.
+
+        Returns:
+            Dict with 'response' (the plan), 'tool_calls', and 'iterations'.
+        """
+        from arc_devkit.copilot.agent import DevCopilot
+
+        self._guardrails.check_kill_switch()
+        copilot = DevCopilot()
+        result = copilot.run_agent(_PLAN_PROMPT.format(goal=goal), max_iterations=max_iterations)
+        self.bus.publish_sync("coordinator.plan", {"goal": goal, "plan": result["response"]})
+        self._guardrails.audit(
+            agent="CoordinatorAgent",
+            trigger="plan",
+            action="generate_plan",
+            goal=goal,
+            tool_calls=len(result["tool_calls"]),
+        )
+        return result
+
+    def execute_transfer(self, to: str, amount_usdc: float, trigger: str = "coordinator") -> dict:
+        """
+        Execute a fund-moving step through the registered (guarded) PaymentAgent.
+
+        Returns:
+            The PaymentAgent result dict; status "blocked" when a guardrail denies it.
+        """
+        if self._payment_agent is None:
+            return {"status": "error", "error": "No PaymentAgent registered."}
+        result = self._payment_agent.execute(
+            to=to, amount_usdc=amount_usdc, enviar=True, trigger=trigger
+        )
+        self.bus.publish_sync("coordinator.transfer", {"to": to, "result": result})
+        return result
+
+    def maintain_balance(
+        self,
+        address: str,
+        min_usdc: float,
+        top_up_usdc: float,
+        interval_seconds: int = 30,
+        max_iterations: int = 0,
+    ) -> dict:
+        """
+        Declarative workflow: keep an address above a minimum balance.
+
+        Wires an AutoRefueler to a MonitorAgent and runs the monitoring loop
+        (blocking). Requires a registered PaymentAgent with funds.
+        """
+        from decimal import Decimal
+
+        from arc_devkit.agents.autonomous import AutoRefueler
+
+        if self._payment_agent is None:
+            return {"status": "error", "error": "No PaymentAgent registered."}
+
+        monitor = MonitorAgent(watched_address=address, interval_seconds=interval_seconds)
+        refueler = AutoRefueler(
+            target_address=address,
+            threshold_usdc=Decimal(str(min_usdc)),
+            top_up_amount_usdc=Decimal(str(top_up_usdc)),
+            payment_agent=self._payment_agent,
+            guardrails=self._guardrails,
+        )
+        refueler.attach(monitor)
+        self.register_monitor(monitor)
+        logger.info("maintain_balance workflow started for %s", address)
+        return monitor.execute(max_iterations=max_iterations)

arc_devkit-0.4.7/arc_devkit/agents/dashboard.py

@@ -0,0 +1,64 @@
+"""Live terminal dashboard for agent state — built on rich.Live."""
+
+from datetime import datetime
+from decimal import Decimal
+
+from rich.live import Live
+from rich.table import Table
+
+from arc_devkit.agents.monitor_agent import MonitorAgent
+
+
+class AgentDashboard:
+    """
+    Renders watched-wallet balances and recent events in a live terminal panel.
+
+    Example:
+        monitor = MonitorAgent(watched_addresses=[...], interval_seconds=10)
+        AgentDashboard(monitor).run(max_iterations=0)
+    """
+
+    MAX_EVENTS = 8
+
+    def __init__(self, monitor: MonitorAgent) -> None:
+        self._monitor = monitor
+        self._events: list[dict] = []
+
+    def _on_event(self, event: dict) -> None:
+        self._events.append({**event, "_at": datetime.now().strftime("%H:%M:%S")})
+        self._events = self._events[-self.MAX_EVENTS :]
+
+    def _render(self) -> Table:
+        table = Table(title="Arc Agents — Live", header_style="bold cyan")
+        table.add_column("Wallet", style="cyan")
+        table.add_column("Balance (USDC)", justify="right")
+
+        balances = self._monitor.get_balance()
+        for addr, info in balances.items():
+            wei = Decimal(info["balance_wei"])
+            table.add_row(f"{addr[:10]}…{addr[-6:]}", str(wei / Decimal(10**18)))
+
+        if self._events:
+            table.add_section()
+            table.add_row("[bold]Recent events[/bold]", "")
+            for ev in reversed(self._events):
+                kind = ev.get("event_type", "native")
+                sign = "+" if ev.get("type") == "credit" else "-"
+                amount = ev.get("change_wei") or ev.get("value_atomic") or "?"
+                table.add_row(
+                    f"[dim]{ev['_at']}[/dim] {kind}",
+                    f"{sign}{amount}",
+                )
+        return table
+
+    def run(self, max_iterations: int = 0, refresh_per_second: int = 2) -> dict:
+        """Run the monitor loop while rendering the live panel (blocking)."""
+        with Live(self._render(), refresh_per_second=refresh_per_second) as live:
+
+            def _callback(event: dict) -> None:
+                self._on_event(event)
+                live.update(self._render())
+
+            result = self._monitor.execute(callback=_callback, max_iterations=max_iterations)
+            live.update(self._render())
+        return result

arc_devkit-0.4.7/arc_devkit/agents/event_bus.py

@@ -0,0 +1,66 @@
+"""Async event bus for inter-agent communication.
+
+Lightweight publish/subscribe over asyncio: agents publish events to topics
+("balance.low", "payment.sent", ...) and other agents subscribe with async or
+sync handlers. Handler failures are isolated and logged.
+"""
+
+import asyncio
+import inspect
+import logging
+from collections.abc import Callable
+from typing import Any
+
+logger = logging.getLogger(__name__)
+
+
+class EventBus:
+    """In-process pub/sub bus for agent coordination."""
+
+    def __init__(self) -> None:
+        self._subscribers: dict[str, list[Callable[[dict], Any]]] = {}
+        self._history: list[tuple[str, dict]] = []
+
+    def subscribe(self, topic: str, handler: Callable[[dict], Any]) -> None:
+        """Register a sync or async handler for a topic."""
+        self._subscribers.setdefault(topic, []).append(handler)
+        logger.debug("Subscribed %s to topic %r", getattr(handler, "__name__", handler), topic)
+
+    def unsubscribe(self, topic: str, handler: Callable[[dict], Any]) -> None:
+        """Remove a handler from a topic (no-op if absent)."""
+        handlers = self._subscribers.get(topic, [])
+        if handler in handlers:
+            handlers.remove(handler)
+
+    async def publish(self, topic: str, event: dict) -> int:
+        """
+        Deliver an event to all subscribers of a topic.
+
+        Returns:
+            Number of handlers that received the event.
+        """
+        self._history.append((topic, event))
+        handlers = list(self._subscribers.get(topic, []))
+        for handler in handlers:
+            try:
+                result = handler(event)
+                if inspect.isawaitable(result):
+                    await result
+            except Exception as exc:
+                logger.error("Event handler failed on topic %r: %s", topic, exc)
+        return len(handlers)
+
+    def publish_sync(self, topic: str, event: dict) -> int:
+        """Publish from synchronous code (runs its own event loop tick)."""
+        try:
+            loop = asyncio.get_running_loop()
+        except RuntimeError:
+            return asyncio.run(self.publish(topic, event))
+        task = loop.create_task(self.publish(topic, event))
+        del task  # fire-and-forget inside a running loop
+        return len(self._subscribers.get(topic, []))
+
+    @property
+    def history(self) -> list[tuple[str, dict]]:
+        """Copy of all published (topic, event) pairs."""
+        return list(self._history)

arc_devkit-0.4.7/arc_devkit/agents/guardrails.py

@@ -0,0 +1,162 @@
+"""Guardrails for autonomous agent actions — spend limits, whitelists, audit log, kill switch.
+
+Any action executed without a human in the loop must pass through these checks:
+
+    guardrails = Guardrails.from_settings()
+    guardrails.check_recipient(to)
+    guardrails.check_spend(amount)
+    ... broadcast ...
+    guardrails.record_spend(amount)
+    guardrails.audit(agent="PaymentAgent", trigger="on_low_balance", action="transfer", ...)
+"""
+
+import json
+import logging
+from datetime import UTC, datetime
+from decimal import Decimal
+from pathlib import Path
+
+from arc_devkit.core.validation import validate_address
+
+logger = logging.getLogger(__name__)
+
+_STATE_DIR = Path.home() / ".arc_devkit"
+_KILL_SWITCH_FILE = _STATE_DIR / "agents.stop"
+_SPEND_FILE = _STATE_DIR / "spend_tracker.json"
+_AUDIT_FILE = _STATE_DIR / "audit.log"
+
+
+class GuardrailViolation(Exception):
+    """Raised when an autonomous action violates a configured guardrail."""
+
+
+def kill_switch_active(state_dir: Path | None = None) -> bool:
+    """True when the kill switch file exists — all autonomous agents must halt."""
+    path = (state_dir / "agents.stop") if state_dir else _KILL_SWITCH_FILE
+    return path.exists()
+
+
+def activate_kill_switch(state_dir: Path | None = None) -> Path:
+    """Create the kill switch file, halting all autonomous agents."""
+    path = (state_dir / "agents.stop") if state_dir else _KILL_SWITCH_FILE
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(datetime.now(UTC).isoformat())
+    logger.warning("Kill switch ACTIVATED: %s", path)
+    return path
+
+
+def clear_kill_switch(state_dir: Path | None = None) -> bool:
+    """Remove the kill switch file; returns True if it existed."""
+    path = (state_dir / "agents.stop") if state_dir else _KILL_SWITCH_FILE
+    if path.exists():
+        path.unlink()
+        logger.info("Kill switch cleared: %s", path)
+        return True
+    return False
+
+
+class Guardrails:
+    """
+    Enforces autonomy limits for agents that act without human confirmation.
+
+    Args:
+        max_spend_per_day_usdc: Daily spend ceiling; None disables the check.
+        allowed_recipients: Whitelist of recipient addresses; empty allows any
+                            (a warning is logged — configure a whitelist in production).
+        state_dir: Directory for the spend tracker, audit log, and kill switch.
+    """
+
+    def __init__(
+        self,
+        max_spend_per_day_usdc: Decimal | None = None,
+        allowed_recipients: tuple[str, ...] | list[str] = (),
+        state_dir: str | Path | None = None,
+    ) -> None:
+        self._max_spend = max_spend_per_day_usdc
+        self._whitelist = {validate_address(a).lower() for a in allowed_recipients}
+        self._state_dir = Path(state_dir) if state_dir else _STATE_DIR
+        self._state_dir.mkdir(parents=True, exist_ok=True)
+
+    @classmethod
+    def from_settings(cls) -> "Guardrails":
+        """Build guardrails from MAX_SPEND_PER_DAY_USDC and AGENT_ALLOWED_RECIPIENTS."""
+        from arc_devkit.config import settings
+
+        return cls(
+            max_spend_per_day_usdc=settings.max_spend_per_day_usdc,
+            allowed_recipients=settings.agent_allowed_recipients,
+        )
+
+    # ------------------------------------------------------------------
+    # Checks
+    # ------------------------------------------------------------------
+
+    def check_kill_switch(self) -> None:
+        """Raise if the kill switch is active."""
+        if kill_switch_active(self._state_dir):
+            raise GuardrailViolation(
+                "Kill switch is active — autonomous actions are halted. "
+                "Run 'arcdevkit agent resume' to re-enable."
+            )
+
+    def check_recipient(self, to: str) -> None:
+        """Raise if the recipient is not on the configured whitelist."""
+        if not self._whitelist:
+            logger.warning(
+                "No recipient whitelist configured (AGENT_ALLOWED_RECIPIENTS) — "
+                "autonomous transfers are unrestricted by destination."
+            )
+            return
+        if validate_address(to).lower() not in self._whitelist:
+            raise GuardrailViolation(f"Recipient {to} is not on the autonomous-agent whitelist.")
+
+    def _spent_today(self) -> Decimal:
+        spend_file = self._state_dir / "spend_tracker.json"
+        today = datetime.now(UTC).date().isoformat()
+        if spend_file.exists():
+            try:
+                data = json.loads(spend_file.read_text())
+                if data.get("date") == today:
+                    return Decimal(data.get("spent", "0"))
+            except Exception as exc:
+                logger.warning("Failed to read spend tracker: %s", exc)
+        return Decimal("0")
+
+    def check_spend(self, amount: Decimal) -> None:
+        """Raise if amount would exceed the daily spend ceiling."""
+        if self._max_spend is None:
+            return
+        spent = self._spent_today()
+        if spent + amount > self._max_spend:
+            raise GuardrailViolation(
+                f"Daily spend limit exceeded: {spent} + {amount} > "
+                f"{self._max_spend} USDC (MAX_SPEND_PER_DAY_USDC)."
+            )
+
+    def record_spend(self, amount: Decimal) -> None:
+        """Persist a completed spend against today's counter."""
+        spend_file = self._state_dir / "spend_tracker.json"
+        today = datetime.now(UTC).date().isoformat()
+        total = self._spent_today() + amount
+        spend_file.write_text(json.dumps({"date": today, "spent": str(total)}))
+
+    # ------------------------------------------------------------------
+    # Audit
+    # ------------------------------------------------------------------
+
+    def audit(self, agent: str, trigger: str, action: str, **details: object) -> None:
+        """Append an autonomous-action record to the audit log (JSON lines)."""
+        record = {
+            "timestamp": datetime.now(UTC).isoformat(),
+            "agent": agent,
+            "trigger": trigger,
+            "action": action,
+            **{k: str(v) for k, v in details.items()},
+        }
+        audit_file = self._state_dir / "audit.log"
+        try:
+            with audit_file.open("a") as fh:
+                fh.write(json.dumps(record, ensure_ascii=False) + "\n")
+        except Exception as exc:
+            logger.error("Failed to write audit log: %s", exc)
+        logger.info("AUDIT %s", record)