Add local blockchain devnet

README.md

@@ -283,6 +283,7 @@ Run a read-only health snapshot from the Debian server with:
 ./jeannie synthetic-checks
 ./jeannie resource-budget
 ./jeannie artifact-cache status
+./jeannie blockchain-devnet status
 ./jeannie golden-ledger check
 ./jeannie route-inventory
 ./jeannie workers list
@@ -369,6 +370,10 @@ it before adding heavier workloads so the HP laptop remains usable.
 `infra/artifact-cache` with apt-cacher-ng and a Docker Hub registry pull-through
 cache. Use `artifact-cache instructions` for client configuration snippets.
 
+`blockchain-devnet` manages an optional local Ethereum Anvil devnet under
+`infra/blockchain-devnet`. It is for contract, wallet, RPC, and observability
+learning only; never use real seed phrases or mainnet keys.
+
 `golden-ledger` shows or validates `infra/pimox/golden-image-ledger.yml`, the
 reviewable record of template VMID, storage, OS release, Kubernetes pins,
 runtime versions, and build metadata for Pimox worker golden images.

README.md.tmpl

@@ -283,6 +283,7 @@ Run a read-only health snapshot from the Debian server with:
 ./{{ main_script }} synthetic-checks
 ./{{ main_script }} resource-budget
 ./{{ main_script }} artifact-cache status
+./{{ main_script }} blockchain-devnet status
 ./{{ main_script }} golden-ledger check
 ./{{ main_script }} route-inventory
 ./{{ main_script }} workers list
@@ -369,6 +370,10 @@ it before adding heavier workloads so the HP laptop remains usable.
 `infra/artifact-cache` with apt-cacher-ng and a Docker Hub registry pull-through
 cache. Use `artifact-cache instructions` for client configuration snippets.
 
+`blockchain-devnet` manages an optional local Ethereum Anvil devnet under
+`infra/blockchain-devnet`. It is for contract, wallet, RPC, and observability
+learning only; never use real seed phrases or mainnet keys.
+
 `golden-ledger` shows or validates `infra/pimox/golden-image-ledger.yml`, the
 reviewable record of template VMID, storage, OS release, Kubernetes pins,
 runtime versions, and build metadata for Pimox worker golden images.

docs/jeannie.1.md

@@ -122,6 +122,11 @@ Kubernetes pod requests/limits and Debian disk/memory signals.
 : Manage the optional Debian-host artifact cache stack for apt packages and
 Docker Hub pull-through image caching.
 
+`blockchain-devnet {status|up|down|logs|rpc}`
+: Manage the optional local Ethereum Anvil devnet stack under
+`infra/blockchain-devnet`. This is for local learning only; never use real seed
+phrases or mainnet keys.
+
 `golden-ledger {show|check}`
 : Show or validate the Pimox golden image version ledger.
 

infra/blockchain-devnet/README.md

@@ -0,0 +1,48 @@
+# Blockchain Devnet
+
+This stack runs a local Ethereum-compatible devnet for learning smart contracts,
+wallets, JSON-RPC, block production, and defensive RPC operations.
+
+It is intentionally local/dev-only. Do not use real wallets, seed phrases, or
+mainnet private keys here.
+
+## Commands
+
+```bash
+./jeannie blockchain-devnet status
+./jeannie blockchain-devnet up
+./jeannie blockchain-devnet logs
+./jeannie blockchain-devnet down
+```
+
+The default RPC endpoint is:
+
+```text
+http://127.0.0.1:8545
+```
+
+From another LAN host, use the Debian host IP:
+
+```text
+http://192.168.100.73:8545
+```
+
+## Useful RPC Checks
+
+```bash
+curl -sS -X POST http://127.0.0.1:8545 \
+  -H 'content-type: application/json' \
+  --data '{"jsonrpc":"2.0","method":"eth_chainId","params":[],"id":1}'
+
+curl -sS -X POST http://127.0.0.1:8545 \
+  -H 'content-type: application/json' \
+  --data '{"jsonrpc":"2.0","method":"eth_blockNumber","params":[],"id":1}'
+```
+
+## Environment
+
+```bash
+BLOCKCHAIN_RPC_PORT=8545
+BLOCKCHAIN_CHAIN_ID=31337
+BLOCKCHAIN_BLOCK_TIME=2
+```

infra/blockchain-devnet/docker-compose.yml

@@ -0,0 +1,17 @@
+services:
+  anvil:
+    image: ghcr.io/foundry-rs/foundry:latest
+    container_name: homelab-blockchain-anvil
+    command:
+      - anvil
+      - --host
+      - 0.0.0.0
+      - --port
+      - "8545"
+      - --chain-id
+      - "${BLOCKCHAIN_CHAIN_ID:-31337}"
+      - --block-time
+      - "${BLOCKCHAIN_BLOCK_TIME:-2}"
+    ports:
+      - "${BLOCKCHAIN_RPC_PORT:-8545}:8545"
+    restart: unless-stopped

jeannie

@@ -6007,6 +6007,11 @@ artifact_cache() {
     "${REPO_ROOT}/scripts/artifact-cache" "${@:2}"
 }
 
+blockchain_devnet() {
+    require_debian_server "blockchain-devnet"
+    "${REPO_ROOT}/scripts/blockchain-devnet" "${@:2}"
+}
+
 golden_ledger() {
     "${REPO_ROOT}/scripts/golden-ledger" "${@:2}"
 }
@@ -6073,6 +6078,8 @@ Build And Bootstrap
   ollama-setup                               Install/configure Ollama on the Debian host.
   artifact-cache {status|up|down|instructions}
                                              Manage optional Debian artifact caches.
+  blockchain-devnet {status|up|down|logs|rpc}
+                                             Manage the local Ethereum Anvil devnet.
   golden-ledger {show|check}                 Show or validate Pimox golden image versions.
 
 Cluster Lifecycle
@@ -6208,6 +6215,9 @@ case "${1:-}" in
     artifact-cache)
         artifact_cache "$@"
         ;;
+    blockchain-devnet)
+        blockchain_devnet "$@"
+        ;;
     golden-ledger)
         golden_ledger "$@"
         ;;

scripts/blockchain-devnet

@@ -0,0 +1,73 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+REPO_ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+STACK_DIR="${REPO_ROOT}/infra/blockchain-devnet"
+RPC_URL="${BLOCKCHAIN_RPC_URL:-http://127.0.0.1:${BLOCKCHAIN_RPC_PORT:-8545}}"
+
+usage() {
+    cat <<'EOF'
+Usage: ./jeannie blockchain-devnet {status|up|down|logs|rpc}
+
+status  Show local devnet containers and RPC health.
+up      Start the local Anvil devnet.
+down    Stop the local Anvil devnet.
+logs    Follow devnet logs.
+rpc     Print the configured JSON-RPC endpoint.
+EOF
+}
+
+rpc_call() {
+    local method="$1"
+
+    curl -fsS -X POST "$RPC_URL" \
+        -H 'content-type: application/json' \
+        --data "{\"jsonrpc\":\"2.0\",\"method\":\"${method}\",\"params\":[],\"id\":1}"
+}
+
+case "${1:-status}" in
+    status)
+        echo "Blockchain devnet stack: ${STACK_DIR}"
+        if command -v docker >/dev/null 2>&1; then
+            (cd "$STACK_DIR" && docker compose ps) || true
+        else
+            echo "docker compose unavailable; cannot inspect local devnet stack"
+        fi
+
+        echo
+        echo "RPC endpoint: ${RPC_URL}"
+        if rpc_call eth_chainId >/tmp/homelab-blockchain-chainid.json 2>/tmp/homelab-blockchain-rpc.err; then
+            printf 'chainId: '
+            cat /tmp/homelab-blockchain-chainid.json
+            echo
+            printf 'blockNumber: '
+            rpc_call eth_blockNumber || true
+            echo
+        else
+            echo "RPC unavailable"
+            sed 's/^/  /' /tmp/homelab-blockchain-rpc.err >&2 || true
+        fi
+        ;;
+    up)
+        cd "$STACK_DIR"
+        docker compose up -d
+        ;;
+    down)
+        cd "$STACK_DIR"
+        docker compose down
+        ;;
+    logs)
+        cd "$STACK_DIR"
+        docker compose logs -f --tail=100
+        ;;
+    rpc)
+        echo "$RPC_URL"
+        ;;
+    -h|--help|help)
+        usage
+        ;;
+    *)
+        usage >&2
+        exit 1
+        ;;
+esac