Skip to content

CLAUDE.md

Latest commit

 

History

History
171 lines (127 loc) · 5.29 KB

CLAUDE.md

File metadata and controls

171 lines (127 loc) · 5.29 KB

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Repository Overview

This is the EIP-4337 reference bundler implementation. The bundler implements the full EIP-4337 RPC calls (both production and debug calls), required to pass the bundler-spec-tests test suite.

Architecture

This is a monorepo managed with Lerna and Yarn workspaces. The main packages are:

  1. bundler - The core bundler server that processes UserOperations
  2. sdk - SDK to create and send UserOperations, provides both low-level and high-level APIs
  3. utils - Shared utilities for the account abstraction ecosystem
  4. validation-manager - SDK to check if UserOperation validation violates any rules

Key architectural components in the bundler:

  • BundlerServer - Express server handling RPC endpoints
  • UserOpMethodHandler - Handles production UserOperation RPC methods
  • DebugMethodHandler - Handles debug RPC methods
  • Module system: BundleManager, EventsManager, ExecutionManager, MempoolManager, ReputationManager

Essential Commands

Development Setup

# Install dependencies and compile contracts
yarn && yarn preprocess

# Deploy contracts locally
yarn hardhat-deploy --network localhost

# Start local bundler
yarn run bundler

# For unsafe mode (when using hardhat node or ganache)
yarn run bundler --unsafe

Running Tests

# Run all tests
yarn lerna-test

# Run bundler tests
yarn --cwd packages/bundler hardhat-test

# Run specific test
yarn --cwd packages/bundler hardhat test test/BundlerManager.test.ts

Linting and Type Checking

# Lint all packages
yarn lerna-lint

# Fix lint issues
yarn lint-fix

# Type check
yarn lerna-tsc

# Watch mode for TypeScript
yarn lerna-watch-tsc

Building

# Build all packages
yarn preprocess

# Clean build artifacts
yarn lerna-clear

Running Tools

# Run a UserOperation
yarn run runop --deployFactory --network http://localhost:8545/ --entryPoint 0x0000000071727De22E5E9d8BAf0edAc6f37da032

# Start bundler with specific config
yarn --cwd packages/bundler bundler --config ./localconfig/bundler.config.json

Configuration

The bundler uses a JSON configuration file. Key configuration options:

  • gasFactor: Gas multiplier for estimations
  • port: Server port (default 3000)
  • beneficiary: Address to receive bundle fees
  • minBalance: Minimum balance for bundler wallet
  • mnemonic: Path to mnemonic file
  • maxBundleGas: Maximum gas for a bundle
  • autoBundleInterval: Auto-bundling interval in seconds
  • autoBundleMempoolSize: Mempool size to trigger auto-bundling

Network Requirements

The bundler requires a GETH node supporting debug_traceCall with JavaScript tracer to implement full spec storage access rules and opcode banning. Hardhat node and Ganache do NOT support this API - use --unsafe flag with these nodes.

Local Development with Docker

To run a local GETH node:

docker run --rm -ti --name geth -p 8545:8545 ethereum/client-go:v1.10.26 \
  --miner.gaslimit 12000000 \
  --http --http.api personal,eth,net,web3,debug \
  --http.vhosts '*,localhost,host.docker.internal' --http.addr "0.0.0.0" \
  --ignore-legacy-receipts --allow-insecure-unlock --rpc.allow-unprotected-txs \
  --dev \
  --verbosity 2 \
  --nodiscover --maxpeers 0 --mine --miner.threads 1 \
  --networkid 1337

Smart Contracts

The bundler interacts with the EIP-4337 contracts located in submodules/account-abstraction. Key contracts:

  • EntryPoint - Core contract that processes UserOperations
  • SimpleAccount - Sample account implementation
  • SimpleAccountFactory - Factory for creating SimpleAccounts

Testing Structure

Tests are organized by module in packages/bundler/test/:

  • Unit tests for individual components
  • Integration tests for RPC methods
  • Validation tests for rules checking

Docker Build and Deployment

The bundler uses Docker for containerized deployment. Images are versioned using the ERC-4337 version followed by the git commit SHA.

Building Docker Images

Use the dbuild.sh script located in dockers/bundler/:

# Build locally (without pushing)
VERSION=0.7.0-$(git rev-parse --short HEAD) IMAGE=0xbigboss/bundler ./dockers/bundler/dbuild.sh

# Build and push to Docker Hub
VERSION=0.7.0-$(git rev-parse --short HEAD) PUSH=1 IMAGE=0xbigboss/bundler ./dockers/bundler/dbuild.sh

Version Format

  • Images are tagged as: 0.7.0-<short-commit-sha>
  • Example: 0.7.0-66737fb
  • The ERC-4337 version (0.7.0) indicates the EntryPoint contract version
  • The commit SHA ensures traceability to specific code versions

Build Process

  1. The script preprocesses the code with yarn preprocess
  2. Webpack bundles the application if source files have changed
  3. Docker buildx creates multi-platform images (linux/amd64, linux/arm64)
  4. Images are tagged with both the specific version and latest

Required Environment Variables

  • VERSION: The version tag (e.g., 0.7.0-66737fb)
  • IMAGE: The Docker image name (e.g., 0xbigboss/bundler)
  • PUSH=1: Set to push the image to the registry (omit for local build only)

Example Workflow

# Get the current commit SHA
COMMIT=$(git rev-parse --short HEAD)

# Build and push the image
VERSION=0.7.0-$COMMIT PUSH=1 IMAGE=0xbigboss/bundler ./dockers/bundler/dbuild.sh