add ArkivNode, auto node creation for Arkiv

Author: Matthias Zimmermann

pyproject.toml

@@ -6,7 +6,13 @@ readme = "README.md"
 requires-python = ">=3.12"
 dependencies = [
     "web3>=7.13.0,<7.14.0",
-    "pytest>=8.4.2",
+]
+
+[project.optional-dependencies]
+# Optional: Local development node support (ArkivNode)
+dev = [
+    "testcontainers>=4.13.1",
+    "websockets>=13.0",
 ]
 
 [build-system]
@@ -17,21 +23,20 @@ build-backend = "setuptools.build_meta"
 where = ["src"]
 
 [dependency-groups]
-# Testing infrastructure
+# SDK development - testing
 test = [
-    "testcontainers==4.13.1",
+    "pytest>=8.4.2",
+    "pytest-cov>=7.0.0",
+    "testcontainers>=4.13.1",
     "websockets>=13.0",
+    "python-dotenv>=1.0.0",
 ]
 
-# Code quality and linting
+# SDK development - linting and type checking
 lint = [
     "mypy>=1.13.0",
     "ruff==0.13.2",
     "pre-commit>=4.0.0",
-]# Development utilities
-dev = [
-    "pytest-cov>=7.0.0",
-    "python-dotenv>=1.0.0",
 ]
 
 [tool.pytest.ini_options]

src/arkiv/__init__.py

@@ -1,6 +1,7 @@
 """Python SDK for Arkiv networks."""
 
 from .client import Arkiv
+from .node import ArkivNode
 
 __version__ = "0.1.0"
-__all__ = ["Arkiv"]
+__all__ = ["Arkiv", "ArkivNode"]

src/arkiv/client.py

@@ -1,7 +1,9 @@
 """Arkiv client - extends Web3 with entity management."""
 
+from __future__ import annotations
+
 import logging
-from typing import Any
+from typing import TYPE_CHECKING, Any
 
 from web3 import Web3
 from web3.middleware import SignAndSendRawMiddlewareBuilder
@@ -12,6 +14,9 @@
 from .account import NamedAccount
 from .module import ArkivModule
 
+if TYPE_CHECKING:
+    pass
+
 # Set up logger for Arkiv client
 logger = logging.getLogger(__name__)
 
@@ -20,7 +25,7 @@ class Arkiv(Web3):
     """
     Arkiv client that extends Web3 with entity management capabilities.
 
-    Provides the familiar Web3.py interface plus arkiv.* methods for entity operations.
+    Provides the familiar client Web3.py interface plus client.arkiv.* methods for entity operations.
     """
 
     ACCOUNT_NAME_DEFAULT = "default"
@@ -32,11 +37,46 @@ def __init__(
         **kwargs: Any,
     ) -> None:
         """Initialize Arkiv client with Web3 provider.
+
+        If no Web3 provider is provided, a local development node is automatically created and started.
+        Remember to call arkiv.node.stop() for cleanup, or use context manager:
+
+        Examples:
+            Auto-managed local node:
+                >>> with Arkiv() as arkiv:
+                ...     print(arkiv.eth.chain_id)
+
+            With account (auto-funded on local node):
+                >>> account = NamedAccount.create("alice")
+                >>> with Arkiv(account=account) as arkiv:
+                ...     balance = arkiv.eth.get_balance(account.address)
+
+            Custom provider:
+                >>> provider = ProviderBuilder().kaolin().build()
+                >>> arkiv = Arkiv(provider)  # No auto-node
+
         Args:
-            provider: Web3 provider instance (e.g., HTTPProvider)
-            account: Optional NamedAccount to use as the default signer
+            provider: Web3 provider instance (e.g., HTTPProvider).
+                If None, creates local ArkivNode (requires Docker and testcontainers).
+            account: Optional NamedAccount to use as the default signer.
+                Auto-funded with test ETH if using local node and balance is zero.
             **kwargs: Additional arguments passed to Web3 constructor
+
+        Note:
+            Auto-node creation requires testcontainers: pip install arkiv-sdk[dev]
         """
+        # Self managed node instance (only created/used if no provider is provided)
+        self.node: ArkivNode | None = None
+        if provider is None:
+            from .node import ArkivNode
+
+            logger.info("No provider given, creating managed ArkivNode...")
+            self.node = ArkivNode()
+
+            from .provider import ProviderBuilder
+
+            provider = ProviderBuilder().node(self.node).build()
+
         super().__init__(provider, **kwargs)
 
         # Initialize entity management module
@@ -51,9 +91,42 @@ def __init__(
             logger.debug(f"Initializing Arkiv client with account: {account.name}")
             self.accounts[account.name] = account
             self.switch_to(account.name)
+
+            # If client has node and account a zero balance, also fund the account with test ETH
+            if self.node is not None and self.eth.get_balance(account.address) == 0:
+                logger.info(
+                    f"Funding account {account.name} ({account.address}) with test ETH..."
+                )
+                self.node.fund_account(account)
+
+            balance = self.eth.get_balance(account.address)
+            balance_eth = self.from_wei(balance, "ether")
+            logger.info(
+                f"Account balance for {account.name} ({account.address}): {balance_eth} ETH"
+            )
         else:
             logger.debug("Initializing Arkiv client without default account")
 
+    def __enter__(self) -> Arkiv:
+        return self
+
+    def __exit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc_val: BaseException | None,
+        exc_tb: Any,
+    ) -> None:
+        if self.node:
+            logger.debug("Stopping managed ArkivNode...")
+            self.node.stop()
+
+    def __del__(self) -> None:
+        if self.node and self.node.is_running():
+            logger.warning(
+                "Arkiv client with managed node is being destroyed but node is still running. "
+                "Call arkiv.node.stop() or use context manager: 'with Arkiv() as arkiv:'"
+            )
+
     def __repr__(self) -> str:
         """String representation of Arkiv client."""
         return f"<Arkiv connected={self.is_connected()}>"

src/arkiv/module.py

@@ -174,6 +174,27 @@ def entity_exists(self, entity_key: EntityKey) -> bool:
         except Exception:
             return False
 
+    def transfer_eth(self, to: ChecksumAddress, amount_wei: int) -> TxHash:
+        """
+        Transfer ETH to the given address.
+
+        Args:
+            to: The recipient address or a named account
+            amount_wei: The amount of ETH to transfer in wei
+
+        Returns:
+            Transaction hash of the transfer
+        """
+        tx_hash_bytes = self.client.eth.send_transaction(
+            {
+                "to": to,
+                "value": Web3.to_wei(amount_wei, "wei"),
+                "gas": 21000,  # Standard gas for ETH transfer
+            }
+        )
+        tx_hash = TxHash(HexStr(tx_hash_bytes.to_0x_hex()))
+        return tx_hash
+
     def get_entity(self, entity_key: EntityKey, fields: int = ALL) -> Entity:
         """
         Get an entity by its entity key.