simplify Arkiv client creation for prototyping

Author: Matthias Zimmermann

README.md

@@ -1,6 +1,15 @@
 # Arkiv SDK
 
-Arkiv is a permissioned storage system for decentralized apps, supporting flexible entities with binary data, annotations, and metadata.
+Arkiv is ## Hello World
+Here's a "Hello World!" example showing how to use the Python Arkiv SDK:
+
+```python
+from arkiv import Arkiv
+
+# Create an Arkiv client for prototyping.
+# The default setup creates a funded default account and starts a containerized Arkiv node.
+client = Arkiv()
+print(f"Connected: {client.is_connected()}")ned storage system for decentralized apps, supporting flexible entities with binary data, annotations, and metadata.
 
 The Arkiv SDK is the official Python library for interacting with Arkiv networks. It offers a type-safe, developer-friendly API for managing entities, querying data, subscribing to events, and offchain verification—ideal for both rapid prototyping and production use.
 
@@ -25,12 +34,14 @@ Here's a "Hello World!" example showing how to use the Python Arkiv SDK:
 
 ```python
 from arkiv import Arkiv
-from arkiv.account import NamedAccount
 
-# Create account and client that implicitly starts a local Arkiv node
-alice = NamedAccount.create('Alice')
-client = Arkiv(account=alice)
-print(f"Connected: {client.is_connected()}")
+# Create Arkiv client with default settings:
+# - starting and connecting to a containerized Arkiv node
+# - creating a funded default account
+client = Arkiv()
+print(f"Client: {client}, connected: {client.is_connected()}")
+print(f"Account: {client.eth.default_account}")
+print(f"Balance: {client.from_wei(client.eth.get_balance(client.eth.default_account), 'ether')} ETH")
 
 # Create entity with data and annotations
 entity_key, tx_hash = client.arkiv.create_entity(
@@ -66,10 +77,14 @@ tx = client.eth.get_transaction(tx_hash)
 ### Arkiv Module Extension
 ```python
 from arkiv import Arkiv
-from arkiv.account import NamedAccount
 
+# Simple local setup
+client = Arkiv()
+
+# Or with custom provider and account
+from arkiv.account import NamedAccount
 account = NamedAccount.from_wallet('Alice', wallet, 's3cret')
-client = Arkiv(provider, account = account)
+client = Arkiv(provider, account=account)
 
 entity_key, tx_hash = client.arkiv.create_entity(
     payload=b"Hello World!",

USE_CASES.md

@@ -453,11 +453,10 @@ arkiv.create_entity(metadata, annotations={"token_id": token_id})
 
 ```python
 from arkiv import Arkiv
-from arkiv.account import NamedAccount
 
-# Connect to Arkiv
-alice = NamedAccount.create('Alice')
-client = Arkiv(account=alice)
+# Create an Arkiv client for prototyping.
+# The default setup creates a funded default account and starts a containerized Arkiv node.
+client = Arkiv()
 
 # Start building
 entity_key, tx_hash = client.arkiv.create_entity(

src/arkiv/client.py

@@ -38,27 +38,32 @@ def __init__(
     ) -> None:
         """Initialize Arkiv client with Web3 provider.
 
-        If no Web3 provider is provided, a local development node is automatically created and started.
+        If no Web3 provider is provided, a local development node is automatically created and started
+        with a funded default account for rapid prototyping.
         Remember to call arkiv.node.stop() for cleanup, or use context manager:
 
         Examples:
-            Auto-managed local node:
+            Simplest setup (auto-managed node + default account):
                 >>> with Arkiv() as arkiv:
+                ...     # Default account created, funded with test ETH
+                ...     print(arkiv.eth.default_account)
                 ...     print(arkiv.eth.chain_id)
 
-            With account (auto-funded on local node):
+            With custom 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:
+            Custom provider (no auto-node or account):
                 >>> provider = ProviderBuilder().kaolin().build()
-                >>> arkiv = Arkiv(provider)  # No auto-node
+                >>> account = NamedAccount.from_wallet("alice", wallet_json, password)
+                >>> arkiv = Arkiv(provider, account=account)
 
         Args:
             provider: Web3 provider instance (e.g., HTTPProvider).
-                If None, creates local ArkivNode (requires Docker and testcontainers).
+                If None, creates local ArkivNode with default account (requires Docker and testcontainers).
             account: Optional NamedAccount to use as the default signer.
+                If None and provider is None, creates 'default' account.
                 Auto-funded with test ETH if using local node and balance is zero.
             **kwargs: Additional arguments passed to Web3 constructor
 
@@ -77,6 +82,13 @@ def __init__(
 
             provider = ProviderBuilder().node(self.node).build()
 
+            # Create default account if none provided (for local node prototyping)
+            if account is None:
+                logger.info(
+                    f"Creating default account '{self.ACCOUNT_NAME_DEFAULT}' for local node..."
+                )
+                account = NamedAccount.create(self.ACCOUNT_NAME_DEFAULT)
+
         super().__init__(provider, **kwargs)
 
         # Initialize entity management module

tests/test_arkiv_create.py

@@ -20,10 +20,22 @@ class TestArkivClientCreation:
     """Test various Arkiv client creation scenarios."""
 
     def test_create_arkiv_without_provider(self) -> None:
-        """Test creating Arkiv client without provider."""
+        """Test creating Arkiv client without provider (creates local node + default account)."""
         with Arkiv() as client:
-            _assert_arkiv_client_properties(client, None, "Without Provider")
-            logger.info("Created Arkiv client without provider")
+            # When no provider given, Arkiv creates a local node AND a default account
+            assert client.node is not None, "Should create managed node"
+            assert len(client.accounts) == 1, "Should create default account"
+            assert "default" in client.accounts, "Should have 'default' account"
+            assert client.current_signer == "default", (
+                "Should set default as current signer"
+            )
+            assert client.eth.default_account is not None, (
+                "Should have default account set"
+            )
+            assert client.is_connected(), "Should be connected to managed node"
+            logger.info(
+                "Created Arkiv client without provider - auto-created node and default account"
+            )
 
     def test_create_arkiv_with_http_provider(self, arkiv_node) -> None:
         """Test creating Arkiv client with HTTP provider."""