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

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

@@ -1,16 +1,15 @@
 Metadata-Version: 2.4
 Name: arc-devkit
-Version: 0.4.7
+Version: 0.8.0
 Summary: Plataforma open source de ferramentas para desenvolvedores da Arc blockchain (Circle)
-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
+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
 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
@@ -39,8 +38,13 @@ 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"
+Requires-Dist: vcrpy>=6.0; extra == "dev"
+Requires-Dist: mcp>=1.2; extra == "dev"
+Requires-Dist: locust>=2.29; extra == "dev"
 Provides-Extra: security
 Requires-Dist: keyring>=24; extra == "security"
+Provides-Extra: mcp
+Requires-Dist: mcp>=1.2; extra == "mcp"
 
 # Arc DevKit
 
@@ -53,6 +57,8 @@ Requires-Dist: keyring>=24; extra == "security"
 
 **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-0.8.0}/README.md

@@ -9,6 +9,8 @@
 
 **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-0.8.0}/arc_devkit/agents/base_agent.py

@@ -74,6 +74,14 @@ class BaseAgent(ABC):
             account = Account.from_key(_key)
             self._address: str | None = account.address
             self._private_key: str | None = _key
+
+            from arc_devkit.core.signer import LocalKeySigner
+
+            # Prepares the pluggable Signer interface (core/signer.py) for
+            # future hardware-wallet/post-quantum backends — subclasses still
+            # sign via self._private_key today; this is additive, not a
+            # behavior change.
+            self._signer: LocalKeySigner | None = LocalKeySigner(_key)
             logger.info(
                 "[%s] Initialized with wallet %s",
                 self.__class__.__name__,
@@ -82,6 +90,7 @@ class BaseAgent(ABC):
         else:
             self._address = None
             self._private_key = None
+            self._signer = None
             logger.warning(
                 "[%s] No private key — read-only mode.",
                 self.__class__.__name__,

{arc_devkit-0.4.7 → arc_devkit-0.8.0}/arc_devkit/agents/coordinator.py

@@ -10,6 +10,7 @@ import logging
 
 from arc_devkit.agents.event_bus import EventBus
 from arc_devkit.agents.guardrails import Guardrails
+from arc_devkit.agents.jobs import Job, JobRegistry
 from arc_devkit.agents.monitor_agent import MonitorAgent
 from arc_devkit.agents.payment_agent import PaymentAgent
 
@@ -93,6 +94,44 @@ class CoordinatorAgent:
         self.bus.publish_sync("coordinator.transfer", {"to": to, "result": result})
         return result
 
+    def hire_agent(
+        self,
+        job_registry: JobRegistry,
+        agent_address: str,
+        amount_usdc: float,
+        spec: str,
+    ) -> Job:
+        """
+        Create a job (with USDC escrow) hiring another agent — planning a
+        workflow that contracts other agents via ERC-8183 jobs.
+
+        Requires a PaymentAgent registered with a private key (its wallet
+        signs the job-creation tx and funds the escrow). The caller must have
+        already approved `job_registry`'s contract to spend `amount_usdc` USDC.
+        """
+        from decimal import Decimal
+
+        if self._payment_agent is None or self._payment_agent._private_key is None:
+            return Job(
+                job_id=0,
+                requester="",
+                agent=agent_address,
+                amount_usdc=Decimal(str(amount_usdc)),
+                spec=spec,
+                error="No PaymentAgent with a private key registered.",
+            )
+
+        job = job_registry.create_job(
+            agent_address,
+            Decimal(str(amount_usdc)),
+            spec,
+            self._payment_agent._private_key,
+        )
+        self.bus.publish_sync(
+            "coordinator.hire", {"agent": agent_address, "job_id": job.job_id, "spec": spec}
+        )
+        return job
+
     def maintain_balance(
         self,
         address: str,

arc_devkit-0.8.0/arc_devkit/agents/identity.py

@@ -0,0 +1,205 @@
+"""ERC-8004 (Trustless Agents) identity + reputation registry client.
+
+ERC-8004 is a very recent EIP (2025) for on-chain agent identity and
+reputation, still evolving — no canonical registry deployment address is
+published for Arc (or confirmed cross-chain) yet, so `AgentRegistry` always
+requires an explicit `identity_registry_address` (and, for reputation,
+`reputation_registry_address`). The default ABIs below are this SDK's
+best-effort reconstruction of the registries described in the spec
+(`registerAgent`/`resolveAgent`, `giveFeedback`/`getReputation`) — pass
+`abi=`/`reputation_abi=` to override once a reference ABI is published.
+"""
+
+import logging
+from dataclasses import dataclass
+from decimal import Decimal
+
+from web3 import Web3
+
+logger = logging.getLogger(__name__)
+
+# Best-effort default ABIs — see module docstring.
+_DEFAULT_IDENTITY_ABI = [
+    {
+        "inputs": [
+            {"name": "domain", "type": "string"},
+            {"name": "agentAddress", "type": "address"},
+        ],
+        "name": "registerAgent",
+        "outputs": [{"name": "agentId", "type": "uint256"}],
+        "stateMutability": "nonpayable",
+        "type": "function",
+    },
+    {
+        "inputs": [{"name": "agentId", "type": "uint256"}],
+        "name": "resolveAgent",
+        "outputs": [
+            {"name": "domain", "type": "string"},
+            {"name": "agentAddress", "type": "address"},
+        ],
+        "stateMutability": "view",
+        "type": "function",
+    },
+    {
+        "anonymous": False,
+        "inputs": [
+            {"indexed": True, "name": "agentId", "type": "uint256"},
+            {"indexed": False, "name": "domain", "type": "string"},
+            {"indexed": True, "name": "agentAddress", "type": "address"},
+        ],
+        "name": "AgentRegistered",
+        "type": "event",
+    },
+]
+
+_DEFAULT_REPUTATION_ABI = [
+    {
+        "inputs": [
+            {"name": "agentId", "type": "uint256"},
+            {"name": "score", "type": "uint8"},
+            {"name": "tag", "type": "string"},
+        ],
+        "name": "giveFeedback",
+        "outputs": [],
+        "stateMutability": "nonpayable",
+        "type": "function",
+    },
+    {
+        "inputs": [{"name": "agentId", "type": "uint256"}],
+        "name": "getReputation",
+        "outputs": [
+            {"name": "totalScore", "type": "uint256"},
+            {"name": "feedbackCount", "type": "uint256"},
+        ],
+        "stateMutability": "view",
+        "type": "function",
+    },
+]
+
+
+@dataclass
+class AgentIdentity:
+    """An agent's on-chain identity (ERC-8004 Identity Registry)."""
+
+    agent_id: int
+    domain: str
+    agent_address: str
+    tx_hash: str | None = None
+
+
+@dataclass
+class ReputationScore:
+    """Aggregated feedback for an agent (ERC-8004 Reputation Registry)."""
+
+    agent_id: int
+    total_score: int
+    feedback_count: int
+
+    @property
+    def average(self) -> Decimal:
+        if self.feedback_count == 0:
+            return Decimal("0")
+        return Decimal(self.total_score) / Decimal(self.feedback_count)
+
+
+class AgentRegistry:
+    """Client for the ERC-8004 Identity + Reputation registries."""
+
+    def __init__(
+        self,
+        w3: Web3,
+        identity_registry_address: str,
+        reputation_registry_address: str | None = None,
+        abi: list[dict] | None = None,
+        reputation_abi: list[dict] | None = None,
+    ) -> None:
+        from arc_devkit.core.validation import validate_address
+
+        self._w3 = w3
+        self._identity_abi = abi or _DEFAULT_IDENTITY_ABI
+        self._identity = w3.eth.contract(
+            address=validate_address(identity_registry_address),
+            abi=self._identity_abi,
+        )
+        self._reputation_abi = reputation_abi or _DEFAULT_REPUTATION_ABI
+        self._reputation = None
+        if reputation_registry_address:
+            self._reputation = w3.eth.contract(
+                address=validate_address(reputation_registry_address),
+                abi=self._reputation_abi,
+            )
+
+    def register(self, domain: str, private_key: str) -> AgentIdentity:
+        """Register the caller's wallet as an agent under `domain`."""
+        from eth_account import Account
+
+        sender = Account.from_key(private_key).address
+        tx = self._identity.functions.registerAgent(domain, sender).build_transaction(
+            {
+                "from": sender,
+                "nonce": self._w3.eth.get_transaction_count(sender),
+                "gas": 200_000,
+                "gasPrice": self._w3.eth.gas_price,
+                "chainId": self._w3.eth.chain_id,
+            }
+        )
+        signed = self._w3.eth.account.sign_transaction(tx, private_key)
+        tx_hash = self._w3.eth.send_raw_transaction(signed.raw_transaction)
+        tx_hash_hex = tx_hash.hex()
+
+        receipt = self._w3.eth.wait_for_transaction_receipt(tx_hash)
+        agent_id = 0
+        logs = self._identity.events.AgentRegistered().process_receipt(receipt)
+        if logs:
+            agent_id = logs[0]["args"]["agentId"]
+
+        logger.info("Agent registered: domain=%s address=%s id=%s", domain, sender, agent_id)
+        return AgentIdentity(
+            agent_id=agent_id, domain=domain, agent_address=sender, tx_hash=tx_hash_hex
+        )
+
+    def resolve(self, agent_id: int) -> AgentIdentity | None:
+        """Look up an agent's domain and address by id."""
+        try:
+            domain, agent_address = self._identity.functions.resolveAgent(agent_id).call()
+        except Exception as exc:
+            logger.warning("resolveAgent(%d) failed: %s", agent_id, exc)
+            return None
+        return AgentIdentity(agent_id=agent_id, domain=domain, agent_address=agent_address)
+
+    def get_reputation(self, agent_id: int) -> ReputationScore | None:
+        """Return aggregated feedback for an agent. None if unavailable."""
+        if self._reputation is None:
+            logger.warning("No reputation_registry_address configured.")
+            return None
+        try:
+            total_score, feedback_count = self._reputation.functions.getReputation(agent_id).call()
+        except Exception as exc:
+            logger.warning("getReputation(%d) failed: %s", agent_id, exc)
+            return None
+        return ReputationScore(
+            agent_id=agent_id, total_score=total_score, feedback_count=feedback_count
+        )
+
+    def give_feedback(self, agent_id: int, score: int, private_key: str, tag: str = "") -> str:
+        """Submit feedback (0-100) for an agent. Returns the tx hash."""
+        if not 0 <= score <= 100:
+            raise ValueError("score must be between 0 and 100.")
+        if self._reputation is None:
+            raise ValueError("No reputation_registry_address configured.")
+
+        from eth_account import Account
+
+        sender = Account.from_key(private_key).address
+        tx = self._reputation.functions.giveFeedback(agent_id, score, tag).build_transaction(
+            {
+                "from": sender,
+                "nonce": self._w3.eth.get_transaction_count(sender),
+                "gas": 150_000,
+                "gasPrice": self._w3.eth.gas_price,
+                "chainId": self._w3.eth.chain_id,
+            }
+        )
+        signed = self._w3.eth.account.sign_transaction(tx, private_key)
+        tx_hash = self._w3.eth.send_raw_transaction(signed.raw_transaction)
+        return tx_hash.hex()

arc_devkit-0.8.0/arc_devkit/agents/job_agent.py

@@ -0,0 +1,88 @@
+"""JobAgent — accepts and executes ERC-8183 jobs autonomously, within guardrails."""
+
+import logging
+from collections.abc import Callable
+
+from arc_devkit.agents.base_agent import BaseAgent
+from arc_devkit.agents.guardrails import Guardrails, GuardrailViolation
+from arc_devkit.agents.jobs import Job, JobRegistry
+
+logger = logging.getLogger(__name__)
+
+
+class JobAgent(BaseAgent):
+    """
+    Autonomously accepts an ERC-8183 job, runs a handler to produce the
+    deliverable, and submits it — every step gated by the kill switch.
+
+    Example:
+        agent = JobAgent(registry_address="0x...", private_key=key, guardrails=guardrails)
+        result = agent.execute(job_id=42, handler=lambda job: "ipfs://Qm...")
+    """
+
+    def __init__(
+        self,
+        registry_address: str,
+        job_abi: list[dict] | None = None,
+        guardrails: Guardrails | None = None,
+        **kwargs: object,
+    ) -> None:
+        super().__init__(**kwargs)
+        self._guardrails = guardrails
+        self._registry = JobRegistry(self._w3, registry_address, abi=job_abi, guardrails=guardrails)
+
+    def get_balance(self) -> dict:
+        if not self._address:
+            return {"error": "No private key configured — read-only mode."}
+        wei = self._w3.eth.get_balance(self._address)
+        return {"address": self._address, "balance_wei": str(wei)}
+
+    def execute(self, job_id: int, handler: Callable[[Job], str]) -> dict:  # type: ignore[override]
+        """
+        Accept `job_id`, run `handler(job)` to produce a deliverable URI/string,
+        and deliver it.
+
+        Args:
+            job_id: The job to accept.
+            handler: Called with the accepted Job; must return the deliverable
+                     (e.g. an IPFS URI or a result string) to submit on-chain.
+
+        Returns:
+            Dict with status ("delivered"/"blocked"/"error") and the Job state.
+        """
+        if not self._private_key:
+            return {"status": "error", "error": "Private key required."}
+
+        if self._guardrails:
+            try:
+                self._guardrails.check_kill_switch()
+            except GuardrailViolation as exc:
+                return {"status": "blocked", "error": str(exc)}
+
+        job = self._registry.accept_job(job_id, self._private_key)
+        if job.error:
+            self.log(f"Failed to accept job {job_id}: {job.error}")
+            return {"status": "error", "error": job.error, "job": job}
+
+        self.log(f"Accepted job {job_id} — running handler...")
+        try:
+            deliverable = handler(job)
+        except Exception as exc:
+            self.log(f"Handler failed for job {job_id}: {exc}")
+            return {"status": "error", "error": str(exc), "job": job}
+
+        delivered = self._registry.deliver_job(job_id, deliverable, self._private_key)
+        if delivered.error:
+            return {"status": "error", "error": delivered.error, "job": delivered}
+
+        if self._guardrails:
+            self._guardrails.audit(
+                agent="JobAgent",
+                trigger="manual",
+                action="job_deliver",
+                job_id=job_id,
+                deliverable_uri=deliverable,
+            )
+
+        self.log(f"Delivered job {job_id}.")
+        return {"status": "delivered", "job": delivered}