From bedb845270fd340bf30d1875cd0b99a39286907e Mon Sep 17 00:00:00 2001 From: juvdiaz Date: Mon, 29 Jun 2026 19:13:23 -0600 Subject: [PATCH] Add local blockchain devnet --- README.md | 5 ++ README.md.tmpl | 5 ++ docs/jeannie.1.md | 5 ++ infra/blockchain-devnet/README.md | 48 ++++++++++++++ infra/blockchain-devnet/docker-compose.yml | 17 +++++ jeannie | 10 +++ scripts/blockchain-devnet | 73 ++++++++++++++++++++++ 7 files changed, 163 insertions(+) create mode 100644 infra/blockchain-devnet/README.md create mode 100644 infra/blockchain-devnet/docker-compose.yml create mode 100755 scripts/blockchain-devnet diff --git a/README.md b/README.md index 3cb4c88..a68e171 100644 --- a/README.md +++ b/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. diff --git a/README.md.tmpl b/README.md.tmpl index 372b10d..b38602b 100644 --- a/README.md.tmpl +++ b/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. diff --git a/docs/jeannie.1.md b/docs/jeannie.1.md index 40cd397..1fdc86e 100644 --- a/docs/jeannie.1.md +++ b/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. diff --git a/infra/blockchain-devnet/README.md b/infra/blockchain-devnet/README.md new file mode 100644 index 0000000..20f8bea --- /dev/null +++ b/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 +``` diff --git a/infra/blockchain-devnet/docker-compose.yml b/infra/blockchain-devnet/docker-compose.yml new file mode 100644 index 0000000..662d779 --- /dev/null +++ b/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 diff --git a/jeannie b/jeannie index 5d89c76..2629612 100755 --- a/jeannie +++ b/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 "$@" ;; diff --git a/scripts/blockchain-devnet b/scripts/blockchain-devnet new file mode 100755 index 0000000..8fc83a3 --- /dev/null +++ b/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