@brninpay/sdk 0.1.0

package/src/bundler/client.ts

@@ -0,0 +1,306 @@
+import { ExecutionError, GasEstimationError, NetworkError, ValidationError } from '@brninpay/core'
+import type {
+  BundlerClientConfig,
+  BundlerProviderConfig,
+  GasEstimate,
+  JsonRpcErrorShape,
+  JsonRpcFailure,
+  JsonRpcSuccess,
+  SdkLogger,
+  UserOperation,
+  UserOperationByHash,
+  UserOperationReceipt,
+} from '../types.js'
+
+const defaultLogger: SdkLogger = {
+  debug: () => undefined,
+  info: () => undefined,
+  warn: () => undefined,
+  error: () => undefined,
+}
+
+function sleep(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms))
+}
+
+function bigintToHex(value: bigint): `0x${string}` {
+  return `0x${value.toString(16)}`
+}
+
+function numberToHex(value: number): `0x${string}` {
+  return bigintToHex(BigInt(value))
+}
+
+function hexToBigInt(value: string | bigint | undefined): bigint {
+  if (value === undefined) {
+    return 0n
+  }
+
+  if (typeof value === 'bigint') {
+    return value
+  }
+
+  return BigInt(value)
+}
+
+function serializeUserOperation(userOperation: UserOperation): Record<string, string> {
+  if (userOperation.version === 'v0.6') {
+    return {
+      sender: userOperation.sender,
+      nonce: bigintToHex(userOperation.nonce),
+      initCode: userOperation.initCode,
+      callData: userOperation.callData,
+      callGasLimit: bigintToHex(userOperation.callGasLimit),
+      verificationGasLimit: bigintToHex(userOperation.verificationGasLimit),
+      preVerificationGas: bigintToHex(userOperation.preVerificationGas),
+      maxFeePerGas: bigintToHex(userOperation.maxFeePerGas),
+      maxPriorityFeePerGas: bigintToHex(userOperation.maxPriorityFeePerGas),
+      paymasterAndData: userOperation.paymasterAndData,
+      signature: userOperation.signature,
+    }
+  }
+
+  return {
+    sender: userOperation.sender,
+    nonce: bigintToHex(userOperation.nonce),
+    factory: userOperation.factory,
+    factoryData: userOperation.factoryData,
+    callData: userOperation.callData,
+    callGasLimit: bigintToHex(userOperation.callGasLimit),
+    verificationGasLimit: bigintToHex(userOperation.verificationGasLimit),
+    preVerificationGas: bigintToHex(userOperation.preVerificationGas),
+    maxFeePerGas: bigintToHex(userOperation.maxFeePerGas),
+    maxPriorityFeePerGas: bigintToHex(userOperation.maxPriorityFeePerGas),
+    paymaster: userOperation.paymaster,
+    paymasterVerificationGasLimit: bigintToHex(userOperation.paymasterVerificationGasLimit),
+    paymasterPostOpGasLimit: bigintToHex(userOperation.paymasterPostOpGasLimit),
+    paymasterData: userOperation.paymasterData,
+    signature: userOperation.signature,
+  }
+}
+
+function mapJsonRpcError(error: JsonRpcErrorShape, method: string): Error {
+  if (method === 'eth_estimateUserOperationGas') {
+    return new GasEstimationError(error.message, error.data)
+  }
+
+  return new ExecutionError('bundler_rpc_error', error.message, {
+    method,
+    code: error.code,
+    data: error.data,
+  })
+}
+
+export class BundlerClient {
+  private readonly timeoutMs: number
+  private readonly pollingIntervalMs: number
+  private readonly maxRetries: number
+  private readonly logger: SdkLogger
+  private readonly fetchImplementation: typeof fetch
+
+  constructor(private readonly config: BundlerClientConfig) {
+    this.timeoutMs = config.timeoutMs ?? 15_000
+    this.pollingIntervalMs = config.pollingIntervalMs ?? 2_000
+    this.maxRetries = config.maxRetries ?? 1
+    this.logger = config.logger ?? defaultLogger
+    this.fetchImplementation = config.fetchImplementation ?? fetch.bind(globalThis)
+  }
+
+  async estimateUserOperationGas(userOperation: UserOperation): Promise<GasEstimate> {
+    const result = await this.requestWithFallback<Record<string, string>>(
+      'eth_estimateUserOperationGas',
+      [serializeUserOperation(userOperation), this.config.entryPointAddress]
+    )
+
+    return {
+      callGasLimit: hexToBigInt(result.callGasLimit),
+      verificationGasLimit: hexToBigInt(result.verificationGasLimit),
+      preVerificationGas: hexToBigInt(result.preVerificationGas),
+      maxFeePerGas: userOperation.maxFeePerGas,
+      maxPriorityFeePerGas: userOperation.maxPriorityFeePerGas,
+      paymasterVerificationGasLimit: result.paymasterVerificationGasLimit
+        ? hexToBigInt(result.paymasterVerificationGasLimit)
+        : undefined,
+      paymasterPostOpGasLimit: result.paymasterPostOpGasLimit
+        ? hexToBigInt(result.paymasterPostOpGasLimit)
+        : undefined,
+    }
+  }
+
+  async sendUserOperation(userOperation: UserOperation): Promise<`0x${string}`> {
+    return this.requestWithFallback<`0x${string}`>('eth_sendUserOperation', [
+      serializeUserOperation(userOperation),
+      this.config.entryPointAddress,
+    ])
+  }
+
+  async getUserOperationReceipt(
+    hash: `0x${string}`,
+    options: { pollingIntervalMs?: number; timeoutMs?: number } = {}
+  ): Promise<UserOperationReceipt> {
+    const startedAt = Date.now()
+    const pollingIntervalMs = options.pollingIntervalMs ?? this.pollingIntervalMs
+    const timeoutMs = options.timeoutMs ?? 60_000
+
+    while (true) {
+      const receipt = await this.requestWithFallback<{
+        userOpHash: `0x${string}`
+        sender: `0x${string}`
+        nonce: string
+        actualGasCost: string
+        actualGasUsed: string
+        success: boolean
+        entryPoint: `0x${string}`
+        receipt: {
+          transactionHash: `0x${string}`
+          blockHash: `0x${string}`
+          blockNumber: string
+        }
+        logs: readonly unknown[]
+      } | null>('eth_getUserOperationReceipt', [hash], {
+        allowNotFound: true,
+      })
+
+      if (receipt) {
+        return {
+          userOpHash: receipt.userOpHash,
+          sender: receipt.sender,
+          nonce: BigInt(receipt.nonce),
+          actualGasCost: BigInt(receipt.actualGasCost),
+          actualGasUsed: BigInt(receipt.actualGasUsed),
+          success: receipt.success,
+          entryPoint: receipt.entryPoint,
+          receipt: {
+            transactionHash: receipt.receipt.transactionHash,
+            blockHash: receipt.receipt.blockHash,
+            blockNumber: BigInt(receipt.receipt.blockNumber),
+          },
+          logs: receipt.logs,
+        }
+      }
+
+      if (Date.now() - startedAt >= timeoutMs) {
+        throw new ValidationError('Timed out while waiting for user operation receipt', {
+          hash,
+          timeoutMs,
+        })
+      }
+
+      await sleep(pollingIntervalMs)
+    }
+  }
+
+  async getUserOperationByHash(hash: `0x${string}`): Promise<UserOperationByHash> {
+    const result = await this.requestWithFallback<{
+      blockHash: `0x${string}`
+      blockNumber: string
+      entryPoint: `0x${string}`
+      transactionHash: `0x${string}`
+      userOperation: UserOperation
+    }>('eth_getUserOperationByHash', [hash])
+
+    return {
+      blockHash: result.blockHash,
+      blockNumber: BigInt(result.blockNumber),
+      entryPoint: result.entryPoint,
+      transactionHash: result.transactionHash,
+      userOperation: result.userOperation,
+    }
+  }
+
+  private async requestWithFallback<T>(
+    method: string,
+    params: unknown[],
+    options: { allowNotFound?: boolean } = {}
+  ): Promise<T> {
+    const providers = [this.config.primary, this.config.secondary].filter(
+      (provider): provider is BundlerProviderConfig => Boolean(provider)
+    )
+
+    let lastError: Error | undefined
+    for (const provider of providers) {
+      try {
+        return await this.requestWithProvider<T>(provider, method, params, options)
+      } catch (error) {
+        lastError = error instanceof Error ? error : new Error(String(error))
+        this.logger.warn('Bundler provider failed', {
+          provider: provider.name,
+          method,
+          error: lastError.message,
+        })
+      }
+    }
+
+    throw lastError ?? new ExecutionError('bundler_failure', `Bundler request ${method} failed`)
+  }
+
+  private async requestWithProvider<T>(
+    provider: BundlerProviderConfig,
+    method: string,
+    params: unknown[],
+    options: { allowNotFound?: boolean }
+  ): Promise<T> {
+    const body = JSON.stringify({
+      jsonrpc: '2.0',
+      id: Date.now(),
+      method,
+      params,
+    })
+
+    let attempt = 0
+    while (true) {
+      attempt += 1
+      const controller = new AbortController()
+      const timeoutId = setTimeout(() => controller.abort('Bundler request timed out'), this.timeoutMs)
+
+      try {
+        const response = await this.fetchImplementation(provider.url, {
+          method: 'POST',
+          headers: {
+            'Content-Type': 'application/json',
+            ...(provider.headers ?? {}),
+          },
+          body,
+          signal: controller.signal,
+        })
+
+        if (!response.ok) {
+          throw new NetworkError(`Bundler HTTP ${response.status}: ${response.statusText}`, {
+            provider: provider.name,
+            method,
+          })
+        }
+
+        const payload = (await response.json()) as JsonRpcSuccess<T> | JsonRpcFailure
+        if ('error' in payload) {
+          if (options.allowNotFound && payload.error.code === -32001) {
+            return null as T
+          }
+          throw mapJsonRpcError(payload.error, method)
+        }
+
+        return payload.result
+      } catch (error) {
+        if (attempt > this.maxRetries + 1) {
+          throw error
+        }
+
+        if (error instanceof Error && error.name === 'AbortError') {
+          throw new NetworkError('Bundler request timed out', {
+            provider: provider.name,
+            method,
+          })
+        }
+
+        if (error instanceof NetworkError) {
+          await sleep(250 * attempt)
+          continue
+        }
+
+        throw error
+      } finally {
+        clearTimeout(timeoutId)
+      }
+    }
+  }
+}

package/src/bundler/providers/alchemy.ts

@@ -0,0 +1,21 @@
+import { ValidationError } from '@brninpay/core'
+import type { AlchemyBundlerProviderParams, BundlerProviderConfig } from '../../types.js'
+
+export function createAlchemyBundlerProvider(
+  params: AlchemyBundlerProviderParams
+): BundlerProviderConfig {
+  if (!params.apiKey.trim()) {
+    throw new ValidationError('Alchemy bundler provider requires a non-empty apiKey')
+  }
+
+  if (!params.url && !params.network?.trim()) {
+    throw new ValidationError('Alchemy bundler provider requires either a url or network')
+  }
+
+  return {
+    name: 'alchemy',
+    url:
+      params.url ??
+      `https://${params.network}.g.alchemy.com/v2/${encodeURIComponent(params.apiKey)}`,
+  }
+}

package/src/bundler/providers/pimlico.ts

@@ -0,0 +1,17 @@
+import { ValidationError } from '@brninpay/core'
+import type { BundlerProviderConfig, PimlicoBundlerProviderParams } from '../../types.js'
+
+export function createPimlicoBundlerProvider(
+  params: PimlicoBundlerProviderParams
+): BundlerProviderConfig {
+  if (!params.apiKey.trim()) {
+    throw new ValidationError('Pimlico bundler provider requires a non-empty apiKey')
+  }
+
+  return {
+    name: 'pimlico',
+    url:
+      params.url ??
+      `https://api.pimlico.io/v2/${params.chainId}/rpc?apikey=${encodeURIComponent(params.apiKey)}`,
+  }
+}