test(evm-wallet-experiment): Add local docker e2e test (#912)

Add a Docker Compose stack for isolated E2E testing with four services:

- `evm`: Anvil chain with EIP-7702 support + contract deployment
- `bundler`: Pimlico Alto ERC-4337 bundler
- `home`: home kernel node (EOA + DeleGator smart account)
- `away`: away kernel node (delegation recipient)

Supports three delegation modes, narrowed via DELEGATION_MODE env var:
7702 (interactive default), 4337, and relay. `yarn test:e2e:docker`
covers all three.

Home and away containers are constructed as pairs, parametrized by
delegation mode.

A little language model `qwen3.5:4B-UD-Q4_K_XL` is provided by Docker
Model Runner.

## Test Plan
### Interactive
<img width="693" height="287" alt="image"
src="https://github.com/user-attachments/assets/d8c93f2b-b80f-4178-afd1-3518a6ef625d"
/>

### `yarn test:e2e:docker`
<img width="680" height="835" alt="image"
src="https://github.com/user-attachments/assets/bb1833e3-bfb6-4a28-a731-06a79f8aa34e"
/>

<!-- CURSOR_SUMMARY -->
---

> [!NOTE]
> **Medium Risk**
> Adds a new Docker-based E2E harness and also changes wallet
initialization/environment resolution (SRP `addressIndex` support and
SDK environment overrides), which could affect key derivation and
contract address selection if misused.
> 
> **Overview**
> Adds a **Docker Compose-based local E2E stack** (Anvil + contract
deploy, Alto bundler, and 3 home/away kernel pairs behind profiles) plus
scripts to run *interactive simulation* and a **new `vitest` Docker E2E
suite** that exercises delegation creation/transfer and delegated
`sendTransaction` across `bundler-7702`, `bundler-hybrid`, and
`peer-relay` modes.
> 
> Updates wallet code to better support Docker/local chains: SRP keyring
initialization can now start at a configurable BIP-44 `addressIndex`
(persisted through encryption/unlock flows), and the SDK adapter gains
`registerEnvironment` overrides + logging wired from `coordinator-vat`,
enabling custom contract environments (e.g. chain `31337`).
Documentation and package scripts are updated accordingly (`docker:*`,
`test:e2e:docker`, new `docs/docker.md` and `docs/simulation.md`).
> 
> <sup>Reviewed by [Cursor Bugbot](https://cursor.com/bugbot) for commit
8235ad9. Bugbot is set up for automated
code reviews on this repo. Configure
[here](https://www.cursor.com/dashboard/bugbot).</sup>
<!-- /CURSOR_SUMMARY -->

Author: grypez

packages/evm-wallet-experiment/README.md

@@ -712,6 +712,8 @@ yarn workspace @ocap/evm-wallet-experiment build
 yarn workspace @ocap/evm-wallet-experiment lint:fix
 ```
 
+For Docker Compose setup (interactive simulation and E2E tests), see [docs/docker.md](./docs/docker.md). Docker Model Runner with `ai/qwen3.5:4B-UD-Q4_K_XL` is required for the interactive simulation's OpenClaw AI agent.
+
 ## Testing
 
 The package has four tiers of tests, each exercising a progressively larger slice of the stack.
@@ -784,6 +786,25 @@ yarn workspace @ocap/evm-wallet-experiment test:integration
 
 Vitest-based peer wallet tests in `test/integration/peer-wallet.test.ts`. Requires building bundles first (`yarn build`). Tests OCAP URL connection, remote message/transaction signing via CapTP, no-authority errors, and capabilities reporting across two kernels.
 
+### Docker E2E (3 delegation modes × home/away pair)
+
+```bash
+# Start the full stack (Anvil + bundler + 6 kernel containers)
+yarn workspace @ocap/evm-wallet-experiment docker:up
+
+# Run all three delegation modes in parallel
+yarn workspace @ocap/evm-wallet-experiment test:e2e:docker
+
+# Run a single mode
+DELEGATION_MODE=bundler-7702 yarn workspace @ocap/evm-wallet-experiment test:e2e:docker
+# or: bundler-hybrid, peer-relay
+
+# Tear down
+yarn workspace @ocap/evm-wallet-experiment docker:down
+```
+
+Full home/away delegation flow across three delegation modes (`bundler-7702`, `bundler-hybrid`, `peer-relay`) running in parallel. The stack requires Docker Model Runner. See [docs/docker.md](./docs/docker.md) for prerequisites, stack details, and troubleshooting. For manual interactive simulation, see [docs/simulation.md](./docs/simulation.md).
+
 ## Supported Chains
 
 The wallet supports all chains where the MetaMask Delegation Framework is deployed:

packages/evm-wallet-experiment/docker/.dockerignore

@@ -0,0 +1,6 @@
+**/node_modules
+**/.git
+**/dist
+**/coverage
+**/.turbo
+**/logs

packages/evm-wallet-experiment/docker/.env.interactive

@@ -0,0 +1,3 @@
+# Used by `yarn docker:compose:interactive` (--env-file). Switches
+# `kernel-away-bundler-7702` to the `interactive` Dockerfile target (OpenClaw).
+KERNEL_AWAY_7702_TARGET=interactive

packages/evm-wallet-experiment/docker/Dockerfile.evm

@@ -0,0 +1,24 @@
+FROM ghcr.io/foundry-rs/foundry:latest AS foundry
+
+FROM node:22-slim
+
+WORKDIR /app
+
+# Copy anvil + cast from the foundry image
+COPY --from=foundry /usr/local/bin/anvil /usr/local/bin/anvil
+COPY --from=foundry /usr/local/bin/cast /usr/local/bin/cast
+
+# Pinned to match yarn.lock in the monorepo (@ocap/evm-wallet-experiment).
+RUN npm init -y > /dev/null 2>&1 && \
+    npm install viem@2.46.2 @metamask/smart-accounts-kit@0.3.0
+
+COPY packages/evm-wallet-experiment/docker/deploy-contracts.mjs /app/deploy-contracts.mjs
+COPY packages/evm-wallet-experiment/docker/entrypoint-evm.sh /app/entrypoint-evm.sh
+
+RUN mkdir -p /logs /run/ocap
+
+EXPOSE 8545
+
+# Health is defined in docker-compose.yml (contracts.json after deploy).
+
+ENTRYPOINT ["/bin/sh", "/app/entrypoint-evm.sh"]

packages/evm-wallet-experiment/docker/Dockerfile.kernel-base

@@ -0,0 +1,72 @@
+FROM node:22 AS builder
+
+WORKDIR /build
+
+RUN corepack enable && apt-get update && apt-get install -y python3 make g++ && rm -rf /var/lib/apt/lists/*
+
+# Copy root workspace config first for layer caching
+COPY package.json yarn.lock .yarnrc.yml tsconfig*.json ./
+
+# Copy all packages (needed for workspace resolution)
+COPY packages/ packages/
+
+# Strip ALL postinstall scripts from root and every workspace package.
+# These (playwright, git-hooks, native rebuilds) fail in Docker and aren't needed.
+RUN node -e " \
+  const fs = require('fs'); \
+  const path = require('path'); \
+  function stripScripts(p) { \
+    const pkg = JSON.parse(fs.readFileSync(p, 'utf8')); \
+    let changed = false; \
+    if (pkg.scripts?.postinstall) { delete pkg.scripts.postinstall; changed = true; } \
+    if (pkg.scripts?.install) { delete pkg.scripts.install; changed = true; } \
+    if (pkg.scripts?.['rebuild:native']) { delete pkg.scripts['rebuild:native']; changed = true; } \
+    if (pkg.lavamoat?.allowScripts) { \
+      for (const k of Object.keys(pkg.lavamoat.allowScripts)) pkg.lavamoat.allowScripts[k] = false; \
+      changed = true; \
+    } \
+    if (changed) fs.writeFileSync(p, JSON.stringify(pkg, null, 2) + '\n'); \
+  } \
+  stripScripts('package.json'); \
+  for (const dir of fs.readdirSync('packages')) { \
+    const p = path.join('packages', dir, 'package.json'); \
+    if (fs.existsSync(p)) stripScripts(p); \
+  }"
+
+RUN yarn install --immutable
+
+# Rebuild native addons required at runtime (QUIC / SQLite / WebRTC). Fail the image
+# build if compilation does not succeed — do not mask errors with || true.
+RUN (cd node_modules/@ipshipyard/node-datachannel && npm run install --ignore-scripts=false) || \
+    npm rebuild @ipshipyard/node-datachannel
+
+# libp2p/webrtc pulls `node-datachannel` (distinct from @ipshipyard); install
+# scripts were stripped above, so compile the N-API addon before kernel-cli build.
+RUN npm rebuild node-datachannel
+
+RUN npm rebuild better-sqlite3
+
+# Build the kernel CLI and wallet bundles
+RUN yarn workspace @metamask/kernel-cli build && \
+    yarn workspace @ocap/evm-wallet-experiment build
+
+# ---------------------------------------------------------------------------
+# Target: kernel — minimal kernel runtime (used by tests)
+# ---------------------------------------------------------------------------
+FROM node:22-slim AS kernel
+
+WORKDIR /app
+
+COPY --from=builder /build /app
+
+RUN mkdir -p /logs /run/ocap
+
+# ---------------------------------------------------------------------------
+# Target: interactive — kernel + OpenClaw + wallet plugin (used interactively)
+# ---------------------------------------------------------------------------
+FROM kernel AS interactive
+
+# OpenClaw loads local plugins as TypeScript via jiti (no extra TS runner in the image).
+# `package.json` docker:interactive:setup starts the gateway via
+# `node /usr/local/lib/node_modules/openclaw/openclaw.mjs` (global bin PATH is unreliable under `docker exec`).
+RUN npm install -g openclaw@2026.4.1

packages/evm-wallet-experiment/docker/MAINTAINERS.md

@@ -0,0 +1,82 @@
+# Docker stack — maintainer notes
+
+Local E2E stack for `@ocap/evm-wallet-experiment`: Anvil + deployed contracts, Pimlico Alto, and six kernel containers (three `kernel-home-*` / `kernel-away-*` pairs). See `package.json` scripts (`docker:compose`, `test:e2e:docker`, etc.). Each pair is gated by a Compose **profile** (**`7702`**, **`4337`**, **`relay`**); **`yarn docker:up`** / **`docker:compose`** pass **all three** so Vitest Docker E2E and full-stack dev see every kernel. **`yarn docker:interactive:up`** enables **one** profile (default **`bundler-7702`** delegation mode → profile **`7702`**). Shared kernel **build / volumes / entrypoint / depends_on** live in root **`x-kernel-standard`**; **`x-kernel-build-core`** holds **`context`** / **`dockerfile`** so **`kernel-away-bundler-7702`** can set **`build.target`** from **`${KERNEL_AWAY_7702_TARGET:-kernel}`**. Per-pair **ports**, **`environment`**, and **`healthcheck.test`** stay explicit.
+
+## Startup order
+
+Compose encodes this dependency chain:
+
+1. **`evm`** becomes healthy when `/run/ocap/contracts.json` exists (written only after `deploy-contracts.mjs` finishes). **`entrypoint-evm.sh`** removes a previous **`contracts.json`** on the shared volume first so a stale file does not satisfy the healthcheck while Anvil is redeploying (bundler would otherwise start with dead EntryPoint addresses and exit).
+2. **`bundler`** waits on that file, reads `EntryPoint`, then starts Alto.
+3. **Kernel services** wait on **both** `evm` and **`bundler` healthy** so wallet setup does not race Alto boot.
+
+If you add a service that kernels need before they are ready, extend `depends_on` and healthchecks accordingly.
+
+## Pinned images and versions
+
+### Alto (bundler)
+
+The bundler image uses a **multi-arch OCI index digest**, not `:latest`, so CI and local builds stay aligned.
+
+To **upgrade Alto**:
+
+```sh
+docker buildx imagetools inspect ghcr.io/pimlicolabs/alto:latest
+```
+
+Copy the top-level **Digest** (index), then set in `docker-compose.yml`:
+
+`image: ghcr.io/pimlicolabs/alto@sha256:<digest>`
+
+Keep the comment above that line in sync with the command you used.
+
+### OpenClaw (interactive image only)
+
+`Dockerfile.kernel-base` installs a **fixed** global CLI version (`openclaw@…`). The gateway loads **`openclaw-plugin/index.ts`** via **jiti**; nothing in the image invokes `tsx`. Bump OpenClaw deliberately when you want new gateway behavior; avoid `@latest` here.
+
+Host-side scripts (e.g. `yarn docker:setup:wallets`) use the workspace **`tsx`** devDependency on your machine, not the container.
+
+### EVM deploy image (`Dockerfile.evm`)
+
+`viem` and `@metamask/smart-accounts-kit` are installed with **exact versions** that should match **`yarn.lock`** for `@ocap/evm-wallet-experiment`. When you bump those dependencies in the workspace, update the `npm install …@version` line in `Dockerfile.evm` in the same change (or CI/docker builds may diverge from monorepo behavior). Do not pipe **`npm install`** through **`tail`** (or other pipeline tails): **`sh`** uses the last command’s exit status, which would hide install failures.
+
+### Foundry base (`Dockerfile.evm`)
+
+`foundry:latest` is still a floating tag. If Anvil/cast behavior breaks the stack, consider pinning that image by digest the same way as Alto.
+
+## Healthchecks
+
+- **`evm`**: File-based (`contracts.json`). The image itself does not define `HEALTHCHECK`; Compose is the source of truth.
+- **`bundler`**: JSON-RPC `eth_supportedEntryPoints` must return a **non-empty** array. If Alto changes RPC surface, adjust the probe in `docker-compose.yml`.
+
+## Kernel image build (`Dockerfile.kernel-base`)
+
+- Postinstall scripts are stripped workspace-wide so `yarn install` succeeds in Docker; **native addons are rebuilt explicitly** afterward.
+- **`node-datachannel`** and **`better-sqlite3`** rebuilds **must succeed**; the Dockerfile does not swallow failures. If the image fails to build, fix the toolchain (compilers, libc) rather than reintroducing `|| true`.
+
+## Security (local dev only)
+
+`docker-compose.yml` embeds **well-known Anvil private keys** for Alto. That is intentional for an isolated local chain. **Do not reuse this pattern** for any network that is exposed or shared.
+
+## Docker Model Runner + Compose `models` (base `docker-compose.yml`)
+
+- **`yarn docker:up`** and **`yarn test:e2e:docker`** expect the full stack, including [**Compose `models`**](https://docs.docker.com/ai/compose/models-and-compose/) on each **`kernel-away-*`** service. That requires **Docker Compose v2.38+** and [**Docker Model Runner**](https://docs.docker.com/ai/model-runner/) enabled.
+- Top-level **`models.llm`** pins **`ai/qwen3.5:4B-UD-Q4_K_XL`** with **`context_size: 32768`** and **`runtime_flags: ['--ctx-size','32768']`** so llama.cpp does not stay at DMR’s 4096 default (OpenClaw + tools need more). Pull if needed: **`docker model pull ai/qwen3.5:4B-UD-Q4_K_XL`**. If requests still hit 4096, run **`docker model configure --context-size 32768 ai/qwen3.5:4B-UD-Q4_K_XL`** on the host and recreate containers.
+- Vitest Docker E2E does **not** call the LLM today, but away containers still receive **`LLM_URL`** / **`LLM_MODEL`** for consistency with interactive OpenClaw and future tests.
+
+## Interactive stack (`docker/.env.interactive` + one pair profile)
+
+- **`yarn docker:compose:interactive`** runs **`node docker/run-interactive-compose.mjs`**, which passes **`--env-file docker/.env.interactive`** ( **`KERNEL_AWAY_7702_TARGET=interactive`** for the 7702 away image) and **one** **`--profile`** (**`7702`**, **`4337`**, or **`relay`**). Default delegation mode is **`bundler-7702`** → profile **`7702`** (same mode strings as Docker E2E **`DELEGATION_MODE`**).
+- **Choose the pair**: set **`OCAP_INTERACTIVE_PAIR`** to **`bundler-7702`**, **`bundler-hybrid`**, or **`peer-relay`**, or pass **`--pair <value>`** before compose subcommands (after **`yarn … --`** if needed), e.g. **`yarn docker:interactive:up -- --pair bundler-hybrid`**.
+- **`yarn docker:interactive:setup`** runs wallet setup; OpenClaw **`setup-openclaw.mjs`** + gateway run **only** when the pair is **`bundler-7702`** (the image with OpenClaw). Other pairs skip those steps with a short log line.
+- OpenClaw UI history for 7702 lives under **`$HOME/.openclaw`** on the **`ocap-run`** volume; use **`yarn docker:interactive:reset-openclaw`** then **`yarn docker:interactive:setup`**, or **`docker compose … down -v`** for a full volume wipe. LLM wiring is **only** in **`docker-compose.yml`** (**`models:`**).
+
+**Raw `docker compose -f docker/docker-compose.yml up`** without **`--profile`** starts **evm** and **bundler** only (no kernels). Prefer **`yarn docker:up`** or the interactive scripts above.
+
+## `yarn docker:delegate`
+
+Runs **`create-delegation.mjs`** inside **`kernel-home-bundler-7702`**. It reads **`/run/ocap/docker-delegation-home.json`** and **`docker-delegation-away.json`** (coordinator **`kref`**, daemon **`socketPath`**, delegate addresses) written by **`yarn docker:setup:wallets`** on the shared **`ocap-run`** volume. Run wallet setup first for the delegation mode / pair you use.
+
+## Ports and conflicts
+
+Published TCP ports include **8545** (Anvil), **4337** (bundler). Kernels publish **UDP 4011–4032** (QUIC, three pairs). Use alternate mappings if these clash with other stacks.

packages/evm-wallet-experiment/docker/create-delegation.mjs

@@ -0,0 +1,111 @@
+/* eslint-disable */
+/**
+ * Create a delegation on the home kernel and push it to the away node over CapTP.
+ *
+ * Connects to the home daemon socket only — the delegation flows to the
+ * away node through the existing peer (OCAP) connection, exercising the real
+ * cross-kernel path.
+ *
+ * Usage:
+ *   node --conditions development /app/packages/evm-wallet-experiment/docker/create-delegation.mjs
+ *
+ * Options (env vars):
+ *   CAVEAT_ETH_LIMIT  — total native-token transfer limit in ETH (default: unlimited)
+ *
+ * Expects `/run/ocap/docker-delegation-{home,away}.json` on the shared volume
+ * (written by `yarn docker:setup:wallets`). Kernel `*-ready.json` files only
+ * expose `socketPath`, not coordinator krefs or wallet addresses.
+ */
+
+import '@metamask/kernel-shims/endoify-node';
+
+import { existsSync, readFileSync } from 'node:fs';
+
+import { makeDaemonClient } from '../test/e2e/docker/helpers/daemon-client.mjs';
+import {
+  buildCaveatsFromEnv,
+  createDelegationForDockerStack,
+  pushDelegationOverPeer,
+  resolveOnChainDelegateForDockerMode,
+} from '../test/e2e/docker/helpers/delegation-transfer.mjs';
+
+const HOME_CTX = '/run/ocap/docker-delegation-home.json';
+const AWAY_CTX = '/run/ocap/docker-delegation-away.json';
+
+async function main() {
+  if (!existsSync(HOME_CTX) || !existsSync(AWAY_CTX)) {
+    console.error(
+      '[delegation] Missing docker-delegation context files. Run on the host first:',
+    );
+    console.error('  yarn docker:setup:wallets');
+    process.exit(1);
+  }
+  const homeInfo = JSON.parse(readFileSync(HOME_CTX, 'utf8'));
+  const awayInfo = JSON.parse(readFileSync(AWAY_CTX, 'utf8'));
+  const delegationMode = process.env.DELEGATION_MODE ?? 'bundler-7702';
+
+  const coordinatorKref = homeInfo.coordinatorKref ?? homeInfo.kref;
+  if (typeof coordinatorKref !== 'string' || !coordinatorKref) {
+    throw new Error(
+      `${HOME_CTX} must include coordinatorKref or kref (run docker:setup:wallets).`,
+    );
+  }
+  const socketPath = homeInfo.socketPath;
+  if (typeof socketPath !== 'string' || !socketPath) {
+    throw new Error(
+      `${HOME_CTX} must include socketPath (run docker:setup:wallets).`,
+    );
+  }
+
+  const home = makeDaemonClient(socketPath);
+
+  const callHome = (method, args) =>
+    home.callVat(coordinatorKref, method, args);
+
+  const delegate = resolveOnChainDelegateForDockerMode({
+    delegationMode,
+    homeInfo,
+    awayInfo,
+  });
+  console.log(`[delegation] home coordinator: ${coordinatorKref}`);
+  console.log(`[delegation] mode: ${delegationMode}`);
+  console.log(
+    `[delegation] on-chain delegate: ${delegate}${
+      delegationMode === 'peer-relay'
+        ? ' (home; peer-relay redeem)'
+        : awayInfo.smartAccountAddress
+          ? ' (away smart account)'
+          : ' (away EOA)'
+    }`,
+  );
+
+  const caveats = buildCaveatsFromEnv();
+  const ethLimit = process.env.CAVEAT_ETH_LIMIT;
+  if (ethLimit) {
+    console.log(
+      `[delegation] caveat: nativeTokenTransferAmount <= ${ethLimit} ETH`,
+    );
+  }
+
+  console.log('[delegation] creating on home...');
+  const delegation = await createDelegationForDockerStack({
+    callHome,
+    awayInfo,
+    homeInfo,
+    delegationMode,
+    caveats,
+  });
+  console.log(`[delegation] id: ${delegation.id}`);
+  console.log(`[delegation] status: ${delegation.status}`);
+
+  console.log('[delegation] pushing to away over CapTP...');
+  await pushDelegationOverPeer(callHome, delegation);
+  console.log(
+    '[delegation] done — away received the delegation over the peer connection.',
+  );
+}
+
+main().catch((err) => {
+  console.error('[delegation] FATAL:', err);
+  process.exit(1);
+});