feat: add bundler for passkey transactions (#2493)

* feat: add bundler for passkey transactions

* feat: continue bundler

Author: matthiasmatt

evm-e2e/README.md

@@ -92,7 +92,11 @@ npm run bundler
 The `bun test` suite now exercises the passkey ERC-4337 flow end-to-end. During the run it:
 
 - Builds the `passkey-sdk`, deploys a fresh `EntryPointV06` + `PasskeyAccountFactory`, and funds the dev bundler key.
-- Starts the local bundler from `passkey-sdk/dist/local-bundler.js` on port `14437`.
+- Starts a bundler on port `14437`: by default the lightweight `passkey-sdk/dist/local-bundler.js`; set
+  `PASSKEY_BUNDLER_MODE=official` to instead build and start `passkey-bundler/dist/index.js` (ensure `npm install` in
+  `passkey-bundler/` first).
 - Executes the CLI passkey script against that bundler to prove a full user operation.
 
-Ensure `node`, `npm`, and `tsup` dependencies are installed (`npm install` in both `evm-e2e/` and `evm-e2e/passkey-sdk/`) and that port `14437` is free before running `bun test` or `just test-e2e`.
+Ensure `node`, `npm`, and `tsup` dependencies are installed (`npm install` in `evm-e2e/`, `evm-e2e/passkey-sdk/`, and
+`passkey-bundler/` if using `PASSKEY_BUNDLER_MODE=official`) and that port `14437` is free before running `bun test` or
+`just test-e2e`.

evm-e2e/test/passkey_account.test.ts

@@ -8,14 +8,19 @@ import { account, provider } from "./setup"
 import { EntryPointV06__factory, PasskeyAccountFactory__factory } from "../types"
 
 const PASSKEY_SDK_DIR = path.resolve(__dirname, "..", "passkey-sdk")
+const PASSKEY_BUNDLER_DIR = path.resolve(__dirname, "..", "..", "passkey-bundler")
 const NPM_BIN = process.platform === "win32" ? "npm.cmd" : "npm"
 const NODE_BIN = "node"
 const JSON_RPC_ENDPOINT = process.env.JSON_RPC_ENDPOINT ?? "http://127.0.0.1:8545"
 const MNEMONIC = process.env.MNEMONIC
 const BUNDLER_DEV_ADDRESS = "0x70997970C51812dc3A010C7d01b50e0d17dc79C8"
+const BUNDLER_DEV_PRIVATE_KEY =
+  process.env.BUNDLER_DEV_PRIVATE_KEY ??
+  "0x59c6995e998f97a5a0044966f0945389dc9e86dae88c7a8412f4603b6b78690d"
 const BUNDLER_PORT = 14437
 const PASSKEY_SEED = "0x0102030405060708090a0b0c0d0e0f101112131415161718191a1b1c1d1e1f20"
 const PASSKEY_TEST_TIMEOUT = Number(process.env.PASSKEY_TEST_TIMEOUT ?? 240000)
+const PASSKEY_BUNDLER_MODE = process.env.PASSKEY_BUNDLER_MODE ?? "local"
 
 if (!MNEMONIC) {
   throw new Error("MNEMONIC must be set for passkey e2e test")
@@ -25,14 +30,15 @@ describe(
   "passkey ERC-4337 flow",
   () => {
     it(
-      "executes a passkey user operation via local bundler",
+      "executes a passkey user operation via bundler",
       async () => {
         await buildPasskeySdk()
+        await buildPasskeyBundlerIfNeeded()
         const { entryPointAddr, factoryAddr } = await deployPasskeyContracts()
         const chainId = BigInt((await provider.getNetwork()).chainId)
         await fundBundlerSigner()
 
-        const bundler = startBundler(entryPointAddr, chainId)
+        const bundler = await startBundler(entryPointAddr, chainId)
         try {
           await waitForBundlerReady(bundler)
           await runPasskeyScript({ entryPointAddr, factoryAddr })
@@ -52,6 +58,18 @@ async function buildPasskeySdk() {
   })
 }
 
+async function buildPasskeyBundlerIfNeeded() {
+  if (PASSKEY_BUNDLER_MODE !== "official") return
+  await runCommand(NPM_BIN, ["install"], {
+    cwd: PASSKEY_BUNDLER_DIR,
+    env: process.env,
+  })
+  await runCommand(NPM_BIN, ["run", "build"], {
+    cwd: PASSKEY_BUNDLER_DIR,
+    env: process.env,
+  })
+}
+
 async function deployPasskeyContracts() {
   const entryPoint = await new EntryPointV06__factory(account).deploy()
   await entryPoint.waitForDeployment()
@@ -72,7 +90,14 @@ async function fundBundlerSigner() {
   await tx.wait()
 }
 
-function startBundler(entryPointAddr: string, chainId: bigint) {
+async function startBundler(entryPointAddr: string, chainId: bigint) {
+  if (PASSKEY_BUNDLER_MODE === "official") {
+    return startOfficialBundler(entryPointAddr, chainId)
+  }
+  return startLocalBundler(entryPointAddr, chainId)
+}
+
+function startLocalBundler(entryPointAddr: string, chainId: bigint) {
   const env = {
     ...process.env,
     ENTRY_POINT: entryPointAddr,
@@ -89,8 +114,26 @@ function startBundler(entryPointAddr: string, chainId: bigint) {
   return proc
 }
 
+function startOfficialBundler(entryPointAddr: string, chainId: bigint) {
+  const env = {
+    ...process.env,
+    ENTRY_POINT: entryPointAddr,
+    JSON_RPC_ENDPOINT,
+    CHAIN_ID: chainId.toString(),
+    BUNDLER_PORT: BUNDLER_PORT.toString(),
+    BUNDLER_PRIVATE_KEY: BUNDLER_DEV_PRIVATE_KEY,
+  }
+  const proc = spawn(NODE_BIN, ["dist/index.js"], {
+    cwd: PASSKEY_BUNDLER_DIR,
+    env,
+    stdio: ["ignore", "pipe", "pipe"],
+  })
+  pipeOutput(proc, "bundler")
+  return proc
+}
+
 async function waitForBundlerReady(proc: ChildProcessWithoutNullStreams) {
-  await waitForOutput(proc, "Bundler JSON-RPC listening")
+  await waitForOutput(proc, ["Bundler JSON-RPC listening", "Bundler listening"])
 }
 
 async function runPasskeyScript(opts: { entryPointAddr: string; factoryAddr: string }) {
@@ -141,21 +184,23 @@ function pipeOutput(proc: ChildProcessWithoutNullStreams, label: string) {
   proc.stderr.on("data", (data) => process.stderr.write(`[${label}] ${data}`))
 }
 
-function waitForOutput(proc: ChildProcessWithoutNullStreams, marker: string, timeoutMs = 20000) {
+function waitForOutput(proc: ChildProcessWithoutNullStreams, markers: string | string[], timeoutMs = 20000) {
+  const markerList = Array.isArray(markers) ? markers : [markers]
   return new Promise<void>((resolve, reject) => {
     const onData = (data: Buffer) => {
-      if (data.toString().includes(marker)) {
+      const str = data.toString()
+      if (markerList.some((m) => str.includes(m))) {
         cleanup()
         resolve()
       }
     }
     const onExit = (code: number | null) => {
       cleanup()
-      reject(new Error(`process exited before emitting "${marker}" (code=${code})`))
+      reject(new Error(`process exited before emitting "${markerList.join(",")}" (code=${code})`))
     }
     const timer = setTimeout(() => {
       cleanup()
-      reject(new Error(`timed out waiting for "${marker}"`))
+      reject(new Error(`timed out waiting for "${markerList.join(",")}"`))
     }, timeoutMs)
 
     const cleanup = () => {

passkey-bundler/Dockerfile

@@ -0,0 +1,17 @@
+# syntax=docker/dockerfile:1
+
+FROM node:20-alpine AS build
+WORKDIR /app
+COPY package*.json ./
+RUN npm ci
+COPY . .
+RUN npm run build
+
+FROM node:20-alpine
+WORKDIR /app
+ENV NODE_ENV=production
+COPY --from=build /app/package*.json ./
+RUN npm ci --omit=dev
+COPY --from=build /app/dist ./dist
+EXPOSE 4337
+CMD ["node", "dist/index.js"]

passkey-bundler/README.md

@@ -0,0 +1,67 @@
+# Passkey Bundler
+
+Lightweight ERC-4337 bundler focused on passkey-backed accounts on Nibiru, aligned with `bundler-prd.md`. It exposes
+JSON-RPC on port `4337` by default, performs validation, prefunding, and queue-based submission to the configured
+EntryPoint, and ships with health and metrics endpoints for operations.
+
+## Features
+- JSON-RPC: `eth_chainId`, `eth_supportedEntryPoints`, `eth_sendUserOperation`, `eth_getUserOperationReceipt`.
+- Passkey helpers: `passkey_createAccount(qx,qy,factory?)`, `passkey_fundAccount(address,amountWei)`,
+  `passkey_getLogs(limit)`.
+- Validation: entry point and chain ID enforcement, userOp schema checks, rate limiting, optional API key auth
+  (`x-api-key` or `Authorization: Bearer <key>`).
+- Queue + retries: in-memory FIFO queue (tie-breaker `maxPriorityFeePerGas`), configurable concurrency, retries with
+  gas bumping and nonce management.
+- Prefunding: optional EntryPoint `depositTo` top-ups with configurable ceiling.
+- Observability: `/healthz`, `/readyz`, `/metrics` (Prometheus), structured logs kept in a rolling buffer.
+- Storage: in-memory receipt/log store with configurable retention (intended to be swapped for SQLite/Postgres later).
+
+## Quickstart
+
+```bash
+cd passkey-bundler
+npm install               # already run in repo; keeps package-lock.json
+
+# run in dev mode (ts)
+RPC_URL=http://127.0.0.1:8545 \
+ENTRY_POINT=0x... \
+BUNDLER_PRIVATE_KEY=0x... \
+BUNDLER_PORT=4337 \
+CHAIN_ID=9000 \
+npm run dev
+
+# or build then run
+npm run build
+node dist/index.js
+```
+
+## Configuration (env)
+
+- `BUNDLER_MODE`: `dev` (default) or `testnet` (enforces safer defaults + requires `DB_URL`).
+- `RPC_URL` / `JSON_RPC_ENDPOINT`: upstream RPC endpoint.
+- `ENTRY_POINT`: EntryPoint address (required).
+- `CHAIN_ID`: chain ID (falls back to RPC if unset).
+- `BUNDLER_PRIVATE_KEY`: bundler signer (required). Optional `BENEFICIARY` overrides the handleOps beneficiary.
+- `BUNDLER_PORT`: JSON-RPC/health/metrics port (default `4337`).
+- `METRICS_PORT`: optional separate port for metrics.
+- `DB_URL`: SQLite database location (e.g. `sqlite:./data/bundler.sqlite` or `./data/bundler.sqlite`).
+- `MAX_BODY_BYTES`: request body size limit (default `1000000`).
+- `BUNDLER_REQUIRE_AUTH`: require API key auth even if `BUNDLER_API_KEYS` is empty (defaults to `true` in testnet mode).
+- `MAX_QUEUE` (default `1000`), `QUEUE_CONCURRENCY` (default `4`).
+- `RATE_LIMIT`: requests/minute per IP or API key (default `120`); `BUNDLER_API_KEYS` as comma-separated list enables
+  auth.
+- `GAS_BUMP` (percent, default `15`), `GAS_BUMP_WEI` (absolute bump), `SUBMISSION_TIMEOUT_MS` (default `45000`),
+  `FINALITY_BLOCKS` (default `2`).
+- `VALIDATION_ENABLED`: run `simulateValidation` before enqueue (defaults to `true` in testnet mode).
+- `ENABLE_PASSKEY_HELPERS`: enable `passkey_*` helper RPC methods (defaults to `false` in testnet mode).
+- `PREFUND_ENABLED` (default `true` in dev, `false` in testnet), `MAX_PREFUND_WEI` (default `5e18`),
+  `PREFUND_ALLOWLIST` (comma-separated sender addresses; required if `PREFUND_ENABLED=true` in testnet mode).
+- `RECEIPT_LIMIT` (default `1000`), `RECEIPT_POLL_INTERVAL_MS` (default `5000`).
+
+Health: `GET /healthz` (process + RPC reachability), `GET /readyz` (RPC synced, signer nonce). Metrics: `GET /metrics`
+Prometheus text.
+
+## Notes
+- Queue and receipt storage are in-memory for now; the `BundlerStore` interface is intentionally pluggable for
+  SQLite/Postgres backends in a follow-up.
+- Rate limiting and API keys are best-effort protections; front a TLS terminator/reverse proxy in production.