feat: [Preconf Phase 2] Bundler Abstraction for Preconfirmation Support

[hadv]

Parent Issue

Part of #164 - Leverage EIP-7917 Based Preconfirmations for Sub-Second Transaction UX

Overview

Create an abstraction layer in the bundler client to prepare for preconfirmation-enabled bundlers. This allows seamless integration when preconf protocols become available.

Tasks

• Define preconfirmation types/interfaces

  // Preconfirmation receipt structure
  const PreconfReceipt = {
    preconfirmed: boolean,
    preconfHash: string,           // Hash of preconf commitment
    proposerSignature: string,     // Proposer's signed commitment
    proposerAddress: string,       // Proposer who made commitment
    targetBlock: number,           // Block where tx will be included
    targetSlot: number,            // Beacon chain slot
    expiresAt: number,             // Timestamp when preconf expires
    userOpHash: string,            // Original UserOp hash
  }

• Create PreconfBundlerClient class extending BundlerClient

  class PreconfBundlerClient extends BundlerClient {
    async getNextProposer() { /* beacon chain query */ }
    async requestPreconfirmation(userOp, options) { /* preconf request */ }
    async sendUserOperationWithPreconf(userOp, options) { /* main method */ }
    async verifyPreconfirmation(preconfReceipt) { /* verify proposer sig */ }
  }

• Add sendUserOperationWithPreconf() method

  async sendUserOperationWithPreconf(userOp, preconfOptions = {}) {
    // 1. Get next proposer from beacon chain (EIP-7917 lookahead)
    const nextProposer = await this.getNextProposer()
    
    // 2. Request preconfirmation commitment
    const preconfReceipt = await this.requestPreconfirmation(userOp, nextProposer)
    
    // 3. Return immediately with preconf + async final receipt
    return {
      ...preconfReceipt,
      finalReceipt: this.waitForUserOperation(preconfReceipt.userOpHash)
    }
  }

• Add beacon chain proposer lookahead query

  • Query consensus layer for proposer_lookahead (EIP-7917)
  • Cache lookahead data (valid for epoch duration)
  • Handle epoch boundaries gracefully

• Create factory function for bundler selection

  function createBundlerClient(config) {
    if (config.preconfEnabled && config.preconfGateway) {
      return new PreconfBundlerClient(config)
    }
    return new BundlerClient(config)
  }

• Add preconf configuration to network config

  const networkConfig = {
    // ... existing config
    preconf: {
      enabled: false,  // Feature flag
      gateway: null,    // Preconf gateway URL
      beaconRpc: null,  // Beacon chain RPC for lookahead
    }
  }

• Add stub implementations (no-op for now)

  • Methods should be callable but return standard bundler flow
  • Easy to swap in real implementation later

API Design

Return Type

{
  // Preconfirmation data (available immediately)
  preconfirmed: true,
  preconfHash: '0x...',
  proposerSignature: '0x...',
  proposerAddress: '0x...',
  targetBlock: 12345678,
  
  // Final receipt (Promise, resolves after block inclusion)
  finalReceipt: Promise<UserOpReceipt>
}

Usage in TransactionSender

const result = await bundler.sendUserOperationWithPreconf(signedUserOp)

// Immediately show preconfirmed state
setStatus('preconfirmed')
setPreconfData(result)

// Wait for final inclusion async
result.finalReceipt.then(receipt => {
  setStatus('included')
  setReceipt(receipt)
})

Files to Create/Modify

• frontend/src/lib/bundlerClient.js - Add PreconfBundlerClient
• frontend/src/lib/preconfTypes.js - Type definitions (new file)
• frontend/src/lib/beaconClient.js - Beacon chain queries (new file)
• frontend/src/config/networks.js - Add preconf config

Acceptance Criteria

• PreconfBundlerClient class implemented with stub methods
• Backward compatible - existing flow works unchanged
• Feature flag to enable/disable preconf path
• Clean abstraction that's easy to extend
• Unit tests for new bundler methods

Dependencies

• Phase 1 UI components (for integration testing)

Labels

enhancement bundler preconfirmations