LEZ wallet integration: containerized sequencer + wallet CLI

[shayanb]

Summary

Wrap the Logos Execution Zone (LEZ) wallet — a separate layer-2 wallet — as a logos-node lez-wallet ... (or similar, name TBD) subcommand surface. Distinct from the base-layer wallet that ships in 0.3.0 (logos-node wallet).

Reference upstream guide: https://github.com/logos-co/logos-docs/blob/main/docs/apps/wallet/journeys/quickstart-for-the-logos-execution-zone-wallet.md

Why this is separate from the base-layer wallet

	Base-layer wallet (shipped in 0.3.0)	LEZ wallet (this issue)
Where	Built into the node binary	Separate logos-execution-zone repo, separate binary
API surface	GET /wallet/{pk}/balance, POST /wallet/transactions/transfer-funds (port 8080 on the node)	Local sequencer process on :3040
Cryptography	Server-side: node signs internally	Client-side: wallet binary generates ZK proofs locally
Account model	wallet.known_keys in user_config.yaml, auto-created at init	Account creation via wallet account new public/private
Build deps	None (pure HTTP client in CLI)	Rust + RISC Zero + circuits
Operator weight	Zero — runs on whatever the node already has	~30 min first build on Pi, two extra long-running containers

Approach

Mirror the existing monitor containerized stack pattern:

• logos-sequencer container — long-running, serves :3040. Built from logos-blockchain/logos-execution-zone sequencer_service with --features standalone and a shipped config.
• logos-lez-wallet container (or logos-wallet if base-layer is renamed in a follow-up) — long-running idle (sleep infinity); CLI commands run via docker exec logos-lez-wallet wallet <args>.
• One shared Docker image with both binaries; two services from the same image with different entrypoints.
• State directory mounted from host: ~/.logos-node/lez-wallet/ → /wallet-home inside container, NSSA_WALLET_HOME_DIR=/wallet-home.
• Joined to existing logos-net so the wallet container can reach logos-sequencer over the docker network.

CLI subcommand surface (proposed)

Subcommand	Wraps upstream	Notes
install	n/a	wallet_build + wallet_up; prompts for password via interactive check-health
start / stop / status	n/a	Container lifecycle
health	wallet check-health	Pass-through
account new <public|private>	wallet account new <type>	Captures the new account_id
account list [-l]	wallet account ls
account show <id>	wallet account get --account-id <id>
account init <id>	wallet auth-transfer init --account-id <id>
faucet <id>	wallet pinata claim --to <id>
send <from> <to> <amount>	wallet auth-transfer send
sync	wallet account sync-private

Files needed (rough)

• docker/lez-wallet/Dockerfile — multi-stage: rust:1-bookworm builder + RISC Zero install + clone-and-build + slim runtime stage
• lib/lez_wallet.sh — compose generation, lez_wallet_exec docker-exec wrapper, lifecycle helpers
• lib/cmd_lez_wallet.sh — dispatcher with all subcommands
• monitoring/lez-wallet/sequencer_config.json — snapshot of upstream debug config (with 0.0.0.0 bind)
• lib/cmd_install.sh — opt-in prompt at install time
• lib/cmd_update.sh — auto-rebuild on LOGOS_LEZ_VERSION bump
• lib/config.sh — new settings: LOGOS_LEZ_VERSION, LOGOS_LEZ_WALLET_DIR, LOGOS_SEQUENCER_PORT
• lib/releases.sh — LOGOS_LEZ_VERSION_DEFAULT constant
• README.md — section explaining LEZ vs base-layer

Build complexity (the main risk)

• RISC Zero on ARM: Pi build will take 20–40 minutes the first time. Subsequent builds use Docker layer cache. Workable, but documented.
• Cross-compilation: --platform=$BUILDPLATFORM in the Dockerfile to support docker buildx from x86 hosts targeting Pi.
• Image size: builder stage is heavy (multi-GB Rust + circuits), but the final runtime stage should be slim (just the binaries + runtime libs).
• Pin upstream: pinned by tag/commit via LOGOS_LEZ_VERSION. Need to track upstream releases so we know when to bump.

Open questions to resolve before designing in detail

• Is there or will there be a hosted sequencer endpoint for testnet? If yes, the sequencer container becomes optional — the operator can point at the hosted URL via LOGOS_SEQUENCER_URL and skip the local container entirely. Right now the upstream docs only describe local dev mode.
• Password recovery — wallet password is the seed for all derived keys; losing it means losing the accounts. UX needs to make this very clear at install time.
• Naming collision with the 0.3.0 base-layer wallet command. Three options: (a) ship LEZ as lez-wallet, (b) rename base-layer to node-wallet later, (c) use wallet --layer=lez flag. Pick at design time.
• Sequencer config drift — the shipped sequencer_config.json snapshot will go stale as upstream evolves. Add to release checklist: regenerate on every LOGOS_LEZ_VERSION bump.

Deferred — not blocking

• Prebuilt image distribution (publish to ghcr.io to skip the build entirely)
• Backup/restore of wallet state directory
• Integration with the Grafana monitoring stack (LEZ-specific dashboards)

Existing patterns to reuse

Pattern	File	What we copy
Containerized service stack	lib/monitoring.sh:8-142	Compose generation with logging caps, external network
Subcommand dispatcher	lib/cmd_monitor.sh:4-35	Case-statement style
docker exec for CLI calls	lib/cmd_monitor.sh:253	$DOCKER_CMD exec ... one-liner
Update auto-rebuild hook	lib/cmd_update.sh:188-208	Mirror for LEZ schema changes
Network pre-creation	lib/monitoring.sh:160-164	Pre-create logos-net if missing

Success criteria (when this issue can close)

• logos-node lez-wallet install works on a fresh machine (x86 + Pi tested)
• Full quickstart flow works: account new → init → faucet claim → send → balance reflects transfer
• Containers survive restart; state persists
• README explains LEZ vs base-layer clearly