improve readme, add github ci workflow

Author: matthiaszimmermann

.github/workflows/ci.yml

@@ -0,0 +1,42 @@
+name: CI
+
+on:
+  push:
+    branches: [ main ]
+  pull_request:
+    branches: [ main ]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: [3.12, 3.14]
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v4
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Cache pip
+        uses: actions/cache@v4
+        with:
+          path: ~/.cache/pip
+          key: ${{ runner.os }}-pip-${{ hashFiles('**/pyproject.toml') }}
+          restore-keys: |
+            ${{ runner.os }}-pip-
+
+      - name: Upgrade pip
+        run: python -m pip install --upgrade pip
+
+      - name: Install project (editable) and test deps
+        run: |
+          python -m pip install -e .
+          python -m pip install pytest pytest-xdist
+
+      - name: Run tests (parallel if xdist available)
+        run: python -m pytest -n auto -q

README.md

@@ -1,6 +1,6 @@
-# Arkiv Python Starter
+# Arkiv - The Web3 Database - Python Starter
 
-**Get started with Arkiv in under 2 minutes!** 🚀
+**Get started with Arkiv in under 5 minutes!** 🚀
 
 This starter template provides everything you need to build applications with the Arkiv SDK for Python. No complex setup required—just clone, open, and run.
 
@@ -32,14 +32,14 @@ Store, query, and manage data on-chain with the simplicity of a traditional data
 - ⚡ **Real-time Events** - Subscribe to data changes as they happen
 - 🔗 **Web3 Compatible** - Just a simple extension of the web3.py library
 
-**Prerequisites:**
-- ✅ Git
-- ✅ Docker
-- ✅ VS Code
-- ✅ GitHub Copilot (optional but recommended)
-
 ## Quick Start
 
+**Before you begin, make sure you have:**
+- Git
+- Docker (running)
+- VS Code with Dev Containers extension
+- GitHub Copilot (optional, but recommended for learning)
+
 ### 1. Clone and Open
 
 ```bash
@@ -93,7 +93,6 @@ Every entity has three core components:
 The actual data you want to store on-chain.
 
 - **Type:** Raw bytes (`bytes` in Python)
-- **Size:** Up to approx 100KB per entity
 - **Format:** Can be anything—text, JSON, binary data, serialized objects
 - **Example:**
   ```python
@@ -190,11 +189,58 @@ How long the entity should persist on-chain before automatic expiration.
 
 This design gives you the flexibility of a document database with the immutability and transparency of blockchain storage.
 
+### Transaction Size Limits
+
+Arkiv operations are blockchain transactions, and the **maximum transaction size** is determined by the underlying blockchain network (currently around **120KB** for the entire transaction).
+
+This limit applies to the **complete transaction data**, which includes:
+- Entity payload(s)
+- All entity attributes (both system and custom)
+- Transaction metadata (signatures, gas data, etc.)
+- Multiple entities if you're creating/updating several in one transaction
+
+**Practical guidelines:**
+- Single entity with large payload: ~90KB payload is safe (leaves room for attributes and metadata)
+- Multiple entities in one transaction: Total size of all payloads + attributes must fit within limit
+- Rich attributes: Many custom attributes reduce available space for payload
+- Batch operations: Consider transaction size when batching multiple entity modifications
+
+**Example:**
+```python
+# This is fine - single entity with reasonable payload
+entity_key, receipt = client.arkiv.create_entity(
+    payload=json.dumps({"data": "..." * 1000}).encode(),  # ~80KB
+    attributes={"type": "large_document"}
+)
+
+# This may fail - total size exceeds transaction limit
+# (payload + attributes + metadata > 100KB)
+large_payload = b"x" * 95000  # 95KB payload
+many_attributes = {f"attr_{i}": f"value_{i}" for i in range(1000)}
+entity_key, receipt = client.arkiv.create_entity(
+    payload=large_payload,
+    attributes=many_attributes  # Too much data!
+)
+```
+
 ## Examples
 
 The template includes 4 progressive tutorials, each building on the previous:
 
-### Example 1: Basic CRUD Operations (5 min)
+1. Basic Arkiv CRUD operations
+2. Querying entities
+3. Real-time entity events
+4. Web3 integration
+
+Each example:
+- Starts a local Arkiv node, running in a container without external dependencies
+- Creates and funds a test account
+- Demonstrates specific features
+- Cleans up automatically and stops the local node when done
+
+All examples are self-contained and can run independently as modules: `uv run python -m arkiv_starter.01_basic_crud`
+
+### Example 1: Arkiv CRUD Operations (5 min)
 **File:** `01_basic_crud.py`
 
 Learn the fundamentals:
@@ -222,7 +268,7 @@ Master data retrieval:
 uv run python -m arkiv_starter.02_queries
 ```
 
-### Example 3: Blockchain Events (10 min)
+### Example 3: Real-Time Events (10 min)
 **File:** `03_events.py`
 
 Real-time data monitoring:
@@ -249,18 +295,6 @@ Advanced usage:
 uv run python -m arkiv_starter.04_web3_integration
 ```
 
-
-
-## How It Works
-
-Each example:
-1. **Starts a local Arkiv node** - Runs in Docker, no external dependencies
-2. **Creates and funds a test account** - Ready to transact immediately
-3. **Demonstrates specific features** - Focused, runnable code
-4. **Cleans up automatically** - Stops the node when done
-
-All examples are self-contained and can run independently as modules: `uv run python -m arkiv_starter.01_basic_crud`
-
 ---
 
 ## Working with AI Assistants
@@ -463,6 +497,12 @@ The starter includes automated tests:
 uv run pytest
 ```
 
+For faster parallel execution:
+
+```bash
+uv run pytest -n auto
+```
+
 This verifies:
 - ✅ Basic CRUD operations work correctly
 - ✅ Query functionality performs as expected

pyproject.toml

@@ -18,6 +18,7 @@ packages = ["src/arkiv_starter"]
 [dependency-groups]
 dev = [
     "pytest>=8.0.0",
+    "pytest-xdist>=3.0.0",
 ]
 
 [tool.pytest.ini_options]

src/arkiv_starter/04_web3_integration.py

@@ -5,29 +5,33 @@
 - Using Arkiv with existing web3.py code
 - Accessing raw Web3 functionality
 - Mixing Arkiv operations with standard Web3 calls
+- Full CRUD lifecycle (create, read, update, delete)
 
-Run this example: python examples/04_web3_integration.py
+Run this example: uv run python -m arkiv_starter.04_web3_integration
 """
 
 from arkiv.provider import ProviderBuilder
-from eth_account import Account
-from web3 import Web3
-
-from arkiv import Arkiv
+from arkiv import Arkiv, NamedAccount
 from arkiv.node import ArkivNode
+from web3 import Web3
+from typing import cast
+from web3.providers.base import BaseProvider
 
 # Setup: Start node and create client
 print("🚀 Starting local Arkiv node...")
 node = ArkivNode()
 node.start()
 
+# Create and fund account
 provider = ProviderBuilder().node(node).build()
-client = Arkiv(provider)
+provider = cast(BaseProvider, provider) # cast for static type checkers
 
 # Create and fund account
-account = Account.create()
+account = NamedAccount.create("web3-integration")
 node.fund_account(account)
-client.eth.default_account = account
+
+# Initialize client with account
+client = Arkiv(provider, account=account)
 print(f"✅ Account ready: {account.address}\n")
 
 # ============================================================================
@@ -61,19 +65,15 @@
 
 # Create entity
 print("📝 Creating entity with Arkiv...")
-tx_hash = client.arkiv.create_entity(
-    payload=b"Web3 integration example", expires_in=3600, content_type="text/plain"
+entity_key, receipt = client.arkiv.create_entity(
+    payload=b"Web3 integration example", 
+    expires_in=3600, 
+    content_type="text/plain"
 )
-print(f"   Transaction Hash: {tx_hash.hex()}")
-
-# Wait and get receipt (standard Web3 call)
-receipt = client.eth.wait_for_transaction_receipt(tx_hash)
-print(f"   Block Number: {receipt['blockNumber']}")
-print(f"   Gas Used: {receipt['gasUsed']}\n")
+print(f"   Transaction Hash: {receipt.tx_hash}")
+print(f"   Block Number: {receipt.block_number}\n")
 
-# Extract entity ID from logs
-entity_id = int(receipt["logs"][0]["topics"][1].hex(), 16)
-print(f"✅ Entity Created: ID {entity_id}\n")
+print(f"✅ Entity Created: Key {entity_key}\n")
 
 # ============================================================================
 # Part 3: Direct Contract Interaction (Advanced)
@@ -85,70 +85,67 @@
 arkiv_contract = client.arkiv.contract
 print(f"📜 Contract Address: {arkiv_contract.address}")
 
-# Call contract methods directly
-entity_count = arkiv_contract.functions.getEntityCount().call()
-print(f"📊 Total Entity Count: {entity_count}")
-
-# Get entity using direct contract call
-entity_data = arkiv_contract.functions.getEntity(entity_id).call()
-print(f"\n📖 Entity {entity_id} (via direct contract call):")
-print(f"   Owner: {entity_data[0]}")
-print(f"   Content Type: {entity_data[1]}")
-print(f"   Expires At: {entity_data[2]}")
-print(f"   Content Length: {len(entity_data[3])} bytes")
-print(f"   Content: {entity_data[3].decode('utf-8')}\n")
+# Get entity using Arkiv's high-level API
+entity = client.arkiv.get_entity(entity_key)
+print(f"\n📖 Entity {entity_key} (via Arkiv SDK):")
+print(f"   Owner: {entity.owner}")
+print(f"   Content Type: {entity.content_type}")
+print(f"   Expires At Block: {entity.expires_at_block}")
+if entity.payload:
+    print(f"   Content Length: {len(entity.payload)} bytes")
+    print(f"   Content: {entity.payload.decode('utf-8')}\n")
+else:
+    print(f"   No payload content\n")
 
 # ============================================================================
-# Part 4: Transaction Signing (Manual)
+# Part 4: Updating and Deleting Entities
 # ============================================================================
-print("✍️  Part 4: Manual Transaction Signing")
+print("✍️  Part 4: Updating and Deleting Entities")
 print("=" * 60)
 
-# Build transaction manually
-print("🔨 Building transaction manually...")
-nonce = client.eth.get_transaction_count(account.address)
-
-# Prepare update transaction
-update_txn = arkiv_contract.functions.updateEntity(
-    entity_id,
-    b"Manually signed update",
-    int(client.eth.get_block("latest")["number"]) + 1800,  # expires_at in blocks
-    "text/plain",
-).build_transaction(
-    {
-        "from": account.address,
-        "nonce": nonce,
-        "gas": 200000,
-        "gasPrice": client.eth.gas_price,
-    }
+# Update entity
+print("🔄 Updating entity...")
+update_receipt = client.arkiv.update_entity(
+    entity_key,
+    payload=b"Updated via Web3 example",
+    expires_in=7200,
+    content_type="text/plain"
 )
-
-# Sign transaction
-print("✍️  Signing transaction...")
-signed_txn = client.eth.account.sign_transaction(update_txn, account.key)
-
-# Send signed transaction
-print("📤 Sending signed transaction...")
-tx_hash = client.eth.send_raw_transaction(signed_txn.raw_transaction)
-print(f"   Transaction Hash: {tx_hash.hex()}")
-
-# Wait for confirmation
-receipt = client.eth.wait_for_transaction_receipt(tx_hash)
-print(f"✅ Transaction mined in block {receipt['blockNumber']}\n")
+print(f"   Transaction Hash: {update_receipt.tx_hash}")
+print(f"   Block Number: {update_receipt.block_number}\n")
 
 # Verify update
-updated_entity = client.arkiv.get_entity(entity_id)
-print(f"📖 Updated content: {updated_entity.content.decode('utf-8')}")
+updated_entity = client.arkiv.get_entity(entity_key)
+if updated_entity.payload:
+    print(f"📖 Updated content: {updated_entity.payload.decode('utf-8')}\n")
+else:
+    print(f"📖 No payload content\n")
+
+# Delete entity
+print("🗑️  Deleting entity...")
+delete_receipt = client.arkiv.delete_entity(entity_key)
+print(f"   Transaction Hash: {delete_receipt.tx_hash}")
+print(f"   Block Number: {delete_receipt.block_number}\n")
+
+# Verify deletion (should return None or raise exception)
+try:
+    deleted_entity = client.arkiv.get_entity(entity_key)
+    if deleted_entity:
+        print(f"⚠️  Entity still exists")
+    else:
+        print(f"✅ Entity successfully deleted\n")
+except Exception as e:
+    print(f"✅ Entity successfully deleted (not found)\n")
 
 # ============================================================================
 # Summary
 # ============================================================================
-print("\n" + "=" * 60)
+print("=" * 60)
 print("📋 Summary:")
 print("   ✅ Standard Web3 operations work seamlessly")
 print("   ✅ Arkiv adds convenient entity management methods")
-print("   ✅ Direct contract access available when needed")
-print("   ✅ Full control over transaction signing")
+print("   ✅ Full CRUD operations on blockchain entities")
+print("   ✅ Access to contract details and chain information")
 print("=" * 60)
 
 # Cleanup