ERC-4337 Bundle Optimizer

Deterministic gas & reputation optimization strategies for ERC-4337 bundlers, with mempool simulation rules.

---

Overview

Bundlers are the unsung bottleneck of Account Abstraction. Most bundlers today use naive fee-ordering or basic priority scoring. This repo implements and documents production-ready bundle optimization strategies that reduce reverts, maximize bundle profitability, and respect reputation constraints — without violating ERC-4337 rules.

It includes:

• A deterministic scoring engine for UserOperation prioritization
• Reputation-aware bundling (staking, ban duration, opsSeen/opsIncluded)
• Gas-price discontinuity detection across Flashbots + public mempool
• Simulated bundle dry-runs before on-chain submission

---

Why It Matters

Alchemy, Stackup, Pimlico, and Biconomy compete on bundler reliability and inclusion rate. A poorly optimized bundler spams the mempool, wastes gas on reverts, and gets entities jailed. This repo provides auditable, testable heuristics that bundler teams can copy directly or adapt.

A bundler that doesn't optimize is just a relayer with extra steps.

---

Table of Contents

• Architecture
• Scoring Engine
• Reputation Integration
• Mempool Simulation Rules
• Installation
• Usage
• Docs
• Contributing
• License

---

Architecture

[UserOp Pool] → [Pre-filter] → [Scoring Engine] → [Bundle Assembly] → [Dry Run] → [Submission]
                     │                │                   │               │
                     ↓                ↓                   ↓               ↓
              (gas limit)      (fee + rep)        (size + time)    (revert check)

The optimizer runs every block window. It:

1. Filters out ops with verificationGasLimit > block gas limit - 21000
2. Scores each op using score = (maxPriorityFeePerGas × prestake) / (gasPriceDeviation + 1)
3. Sorts bundles by cumulative score, then simulates top 3 candidates
4. Selects the bundle with the highest executionRatio (successful ops / total ops)

---

Scoring Engine

interface OptimizedUserOperation {
  userOp: UserOperation;
  score: number;
  prestake: bigint; // from reputation store
}

function scoreOperation(
  op: UserOperation,
  reputation: ReputationEntry
): number {
  const fee = Number(op.maxPriorityFeePerGas);
  const stake = Number(reputation.stake ?? 0n);
  const seen = reputation.opsSeen + 1;
  const deviation =
    Math.abs(Number(op.maxFeePerGas) - medianGasPrice()) / 1e9;

  // Reward high fee and stake; punish deviation and excessive submissions
  return (fee * stake) / (deviation + 1) / seen;
}

function selectBundle(
  ops: OptimizedUserOperation[],
  maxSize: number
): OptimizedUserOperation[] {
  return ops
    .sort((a, b) => b.score - a.score)
    .reduce((bundle, op) => {
      const size = estimateBundleSize([...bundle, op]);
      return size <= maxSize ? [...bundle, op] : bundle;
    }, [] as OptimizedUserOperation[]);
}

Two scoring strategies are available under src/optimizer/scoring/:

Strategy	Best for
linear.ts	Stable mempool, low volatility
dynamic.ts	High-volatility periods, MEV competition

---

Reputation Integration

ERC-4337 defines reputation rules but not their implementation. This repo provides a SQLite-backed reputation store with full throttling, banning, and recovery logic.

Field	Type	Description
address	string	Entity: paymaster, factory, or aggregator
opsSeen	number	Total UserOps seen from this entity
opsIncluded	number	Ops successfully included on-chain
status	ok | throttled | banned	Current entity status
banUntil	number	Unix timestamp of ban expiry

Core rule: If opsSeen > 100 and opsIncluded / opsSeen < 0.1 → entity is throttled for 10 minutes.

See docs/reputation-algorithms.md for full throttling, banning, and unstaking delay logic.

---

Mempool Simulation Rules

Before a UserOperation enters the bundle pool, it passes through simulateValidation():

UserOperation → simulateValidation()
                       ↓
            EntryPoint.simulateValidation()
                       ↓
       [Verification gas limit] → reject if >30% of block gas
       [Factory/Paymaster stake] → reject if stake < 1 ETH
       [Signature replay check] → reject if nonce gap > 64
                       ↓
                  ✓ Pass → enter bundle pool
                  ✗ Fail → drop + update reputation

Note: simulateValidation() passing does not guarantee handleOps() success. See docs/bundle-simulation-edge-cases.md.

---

Installation

git clone https://github.com/enochTe8/erc4337-bundle-optimizer.git
cd erc4337-bundle-optimizer
npm install
cp .env.example .env
# Add: RPC_URL, ENTRYPOINT_ADDRESS, BUNDLER_PRIVATE_KEY

Requirements: Node.js 18+, TypeScript 5.x

---

Usage

import { BundleOptimizer } from './src/optimizer';
import { MempoolMonitor } from './src/mempool';

const optimizer = new BundleOptimizer({
  entryPoint: '0x5FF137D4b0FDCD49DcA30c7CF57E578a026d2789',
  reputationStore: './reputation.db', // or 'sqlite::memory:'
  maxBundleSize: 3_000_000, // 3M gas
  scoringStrategy: 'dynamic',
});

const monitor = new MempoolMonitor(optimizer);
monitor.startPolling(2000); // poll every 2 seconds

monitor.on('bundle:submitted', ({ txHash, ops, profit }) => {
  console.log(`Bundle submitted: ${txHash} | ops: ${ops} | profit: ${profit} gwei`);
});

Run the CLI directly:

npm run optimize -- --rpc https://mainnet.infura.io/v3/YOUR_KEY --dry-run

---

Docs

Document	Description
docs/reputation-algorithms.md	Throttling, banning, and unstaking delay logic
docs/bundle-simulation-edge-cases.md	Why validation can pass but handleOps() reverts
docs/gas-price-discontinuity.md	Detecting gas spikes across Flashbots + public mempool

---

Contributing

See CONTRIBUTING.md. High-value contributions:

• ERC-4337 v0.7 EntityType support
• Time-based bundle expiry for long-pending ops
• Prometheus metrics endpoint for bundler ROI tracking
• Flashbots bundle submission integration

---

License

MIT — free to use for bundler operators and infrastructure teams. Attribution appreciated.

---

Written and maintained by Enoch Agboola — Account Abstraction technical writer.