Merge pull request #507 from pimlicolabs/claude/adoring-nash

perf(test): share test infrastructure per worker and use unique keys

Author: plusminushalf

.gitignore

@@ -21,4 +21,5 @@ temp.ts
 .env.test.local
 .env.production.local
 .envrc
-.vscode
+.vscode
+.claude

.size-limit.json

@@ -2,7 +2,7 @@
     {
         "name": "permissionless (esm)",
         "path": "./packages/permissionless/_esm/index.js",
-        "limit": "60 kB",
+        "limit": "250 kB",
         "import": "*"
     },
     {

bun.lock

@@ -46,11 +46,15 @@ bun run test
           │     describe.each(getCoreSmartAccounts())(...)  ← matrix over accounts
           │         testWithRpc("...", async ({ rpc }) => { ... })
           │
-          └─ per test() invocation:
-                1. testWithRpc fixture allocates 3 ports
-                2. spawns anvil → setupContracts → alto → mock-paymaster
-                3. awaits the test body with { rpc: { anvilRpc, altoRpc, paymasterRpc } }
-                4. stops all 3 instances, releases ports
+          └─ per worker (shared across all tests in that worker):
+                1. first testWithRpc fixture call triggers getSharedRig()
+                2. spawns anvil → setupContracts → alto → mock-paymaster (once)
+                3. tops up paymaster deposits (1000 ETH per EntryPoint)
+                per test:
+                4. clears alto mempool + resets base fee
+                5. awaits the test body with { rpc: { anvilRpc, altoRpc, paymasterRpc } }
+                worker exit:
+                6. stops all 3 instances (Promise.all)
 ```
 
 Fixture mechanics are detailed in [02-lifecycle.md](./02-lifecycle.md); process details in [03-infrastructure.md](./03-infrastructure.md).
@@ -99,31 +103,32 @@ Field-by-field:
 | `coverage.reporter`         | `CI ? ["lcov"] : ["text","json","html"]`         | Local dev gets HTML + text output; CI produces only lcov (Codecov-friendly).                                           |
 | `coverage.include`          | `["**/permissionless/**"]`                       | Measures coverage of the published package only.                                                                       |
 | `coverage.exclude`          | test files, generated `_cjs`/`_esm`/`_types`, test infra | Keeps coverage numbers honest.                                                                                         |
-| `sequence.concurrent`       | `false`                                          | Tests inside one file run **sequentially**. Multiple parallel Anvil stacks from one file would risk port exhaustion and noisy logs. |
-| `fileParallelism`           | `true`                                           | Separate `.test.ts` files DO run in parallel (in separate workers).                                                    |
+| `sequence.concurrent`       | `false`                                          | Tests inside one file run **sequentially**. This is essential for the shared-rig model: tests in a worker share the same anvil/alto/paymaster trio and clear state between runs. |
+| `fileParallelism`           | `true`                                           | Separate `.test.ts` files DO run in parallel (in separate workers). Each worker gets its own shared rig.               |
 | `environment`               | `"node"`                                         | No jsdom; tests run in raw Node.                                                                                       |
 | `testTimeout`               | `60_000` (60s)                                   | User operations + bundling + receipts are slow; 60s is the per-test cap.                                               |
-| `hookTimeout`               | `45_000` (45s)                                   | The `testWithRpc` fixture setup (anvil + contracts + alto + paymaster) can take tens of seconds cold.                  |
+| `hookTimeout`               | `45_000` (45s)                                   | The `testWithRpc` fixture setup (on first test: anvil + contracts + alto + paymaster) can take tens of seconds cold.   |
 | `include`                   | `join(__dirname, "./**/*.test.ts")`              | Discovery is rooted at `packages/permissionless/` — not the repo root. Tests elsewhere (e.g. `packages/mock-paymaster/`) are **not** picked up. |
 | `env`                       | `loadEnv("test", process.cwd())`                 | Reads `.env.test`, `.env.test.local`, `.env`, `.env.local` from the CWD and exposes `VITE_*` vars to tests.            |
 
 ### Parallelism model
 
-- **File-level:** parallel. Each `.test.ts` file runs in its own worker, which means each has its own module-level state (including the `ports: number[]` tracker in `testWithRpc.ts:80`). Workers do not share a port list, but `get-port` asks the OS for a free port, so real collisions are rare.
-- **Test-level (inside a file):** serial. Each `testWithRpc(...)` inside a file waits for the previous one to tear down before the next starts. That means **within one file, there is never more than one Anvil/Alto/paymaster trio alive at once**.
+- **File-level:** parallel. Each `.test.ts` file runs in its own worker, which means each has its own shared rig (anvil + alto + paymaster trio). Workers do not share processes or ports.
+- **Test-level (inside a file):** serial. Each `testWithRpc(...)` inside a file waits for the previous one to complete before the next starts. This is critical because tests share the same anvil/alto/paymaster trio within a worker.
 
 Combined: at any instant, concurrency ≈ number of `.test.ts` files currently in flight. With Vitest's default worker count (≈ CPU cores), you typically have 4–8 parallel stacks.
 
 ### Why `hookTimeout` is 45s
 
-`testWithRpc` setup does, in order:
+The first `testWithRpc` call in a worker triggers `getSharedRig()`, which does:
 1. Allocate 3 free ports (ms).
 2. Start Anvil (~1–3s cold).
 3. Call `setupContracts(anvilRpc)` which issues **~80+ transactions** to the deterministic deployer and a few impersonation + `setCode` calls. With all txns batched via `Promise.all`, this typically lands in 2–8s but can spike.
-4. Start Alto (subprocess, waits for `"Server listening at"` message; ~2–5s).
+4. Start Alto with debug endpoints enabled (subprocess, waits for `"Server listening at"` message; ~2–5s).
 5. Start the paymaster (Fastify boot; ~1s).
+6. Top up paymaster deposits (~1s).
 
-On a slow machine or noisy CI runner, cumulative setup > 30s is possible; 45s is the margin.
+On a slow machine or noisy CI runner, cumulative setup > 30s is possible; 45s is the margin. Subsequent tests in the same worker skip this setup entirely (the rig is already running), so only the first test pays the cold-start cost.
 
 ## File layout
 
@@ -152,7 +157,7 @@ Non-exhaustive — see `packages/permissionless/**/*.test.ts` for the full set.
 
 | Directory / file                          | Purpose                                                                 |
 | ----------------------------------------- | ----------------------------------------------------------------------- |
-| `src/testWithRpc.ts`                      | The `testWithRpc` fixture — starts/stops anvil + alto + paymaster.      |
+| `src/testWithRpc.ts`                      | The `testWithRpc` fixture — shared per-worker rig, per-test reset, `createAutoBundleTransport`. |
 | `src/utils.ts`                            | All viem/Pimlico/smart-account helpers. Re-read this often.             |
 | `src/types.ts`                            | `AAParamType<entryPointVersion>`.                                       |
 | `mock-aa-infra/alto/instance.ts`          | `alto(...)` prool instance factory.                                     |
@@ -171,7 +176,7 @@ It is imported from test files by **relative path** (e.g. `"../../../permissionl
 | You want to…                             | Open                                                                      |
 | ---------------------------------------- | ------------------------------------------------------------------------- |
 | Change how tests are discovered / timed out | `packages/permissionless/vitest.config.ts`                                |
-| Change the per-test setup/teardown       | `packages/permissionless-test/src/testWithRpc.ts`                         |
+| Change the per-worker setup or per-test reset | `packages/permissionless-test/src/testWithRpc.ts`                         |
 | Add a new viem client helper             | `packages/permissionless-test/src/utils.ts`                               |
 | Add a new smart account type             | `packages/permissionless-test/src/utils.ts` + `mock-aa-infra/alto/constants/accounts/` + `mock-aa-infra/alto/index.ts` |
 | Change how the bundler is started        | `packages/permissionless-test/mock-aa-infra/alto/instance.ts`             |