@zerodev/sdk 4.0.0

package/src/kernel-zerodev/provider.ts

@@ -0,0 +1,341 @@
+import {
+  fromHex,
+  type Address,
+  type Chain,
+  type Hash,
+  type Hex,
+  type HttpTransport,
+  type RpcTransactionRequest,
+} from "viem";
+import {
+  deepHexlify,
+  resolveProperties,
+  type SmartAccountProviderOpts,
+  getChain,
+  type UserOperationCallData,
+  type BatchUserOperationCallData,
+  type SendUserOperationResult,
+  asyncPipe,
+  noOpMiddleware,
+  type UserOperationStruct,
+  type BytesLike,
+  SmartAccountProvider,
+  type AccountMiddlewareFn,
+  type UserOperationOverrides,
+} from "@alchemy/aa-core";
+import {
+  BUNDLER_URL,
+  DEFAULT_SEND_TX_MAX_RETRIES,
+  DEFAULT_SEND_TX_RETRY_INTERVAL_MS,
+  ENTRYPOINT_ADDRESS,
+  minPriorityFeePerBidDefaults,
+} from "./constants.js";
+import { KernelSmartContractAccount, isKernelAccount } from "./account.js";
+import { withZeroDevGasEstimator } from "./middleware/gas-estimator.js";
+import { isValidRequest } from "./utils/ERC4337-utils.js";
+import { InvalidOperation } from "./errors.js";
+import { withZeroDevPaymasterAndData } from "./middleware/paymaster.js";
+import { createZeroDevPublicErc4337Client } from "./client/create-client.js";
+import type {
+  PaymasterAndBundlerProviders,
+  PaymasterConfig,
+  PaymasterPolicy,
+} from "./paymaster/types.js";
+
+export type ZeroDevProviderConfig = {
+  projectId: string;
+  chain: Chain | number;
+  entryPointAddress?: Address;
+  rpcUrl?: string;
+  account?: KernelSmartContractAccount;
+  bundlerProvider?: PaymasterAndBundlerProviders;
+  opts?: SmartAccountProviderOpts & {
+    sendTxMaxRetries?: number;
+    sendTxRetryIntervalMs?: number;
+  };
+};
+
+export enum Operation {
+  Call,
+  DelegateCall,
+}
+
+type UserOpDataOperationTypes<T> = T extends UserOperationCallData
+  ? Operation.Call | Operation.DelegateCall
+  : T extends BatchUserOperationCallData
+  ? Operation.Call
+  : never;
+
+export class ZeroDevProvider extends SmartAccountProvider<HttpTransport> {
+  protected projectId: string;
+  protected sendTxMaxRetries: number;
+  protected sendTxRetryIntervalMs: number;
+
+  constructor({
+    projectId,
+    chain,
+    entryPointAddress = ENTRYPOINT_ADDRESS,
+    rpcUrl = BUNDLER_URL,
+    account,
+    bundlerProvider,
+    opts,
+  }: ZeroDevProviderConfig) {
+    const _chain = typeof chain === "number" ? getChain(chain) : chain;
+    const rpcClient = createZeroDevPublicErc4337Client({
+      chain: _chain,
+      rpcUrl,
+      projectId,
+      bundlerProvider,
+    });
+
+    super(rpcClient, entryPointAddress, _chain, account, {
+      ...opts,
+      txMaxRetries: opts?.txMaxRetries ?? 10,
+      txRetryIntervalMs: opts?.txRetryIntervalMs ?? 10000,
+      minPriorityFeePerBid:
+        opts?.minPriorityFeePerBid ??
+        minPriorityFeePerBidDefaults.get(_chain.id),
+    });
+
+    this.projectId = projectId;
+    this.sendTxMaxRetries =
+      opts?.sendTxMaxRetries ?? DEFAULT_SEND_TX_MAX_RETRIES;
+    this.sendTxRetryIntervalMs =
+      opts?.sendTxRetryIntervalMs ?? DEFAULT_SEND_TX_RETRY_INTERVAL_MS;
+
+    withZeroDevGasEstimator(this);
+  }
+
+  getProjectId = (): string => this.projectId;
+
+  sendTransaction = async (
+    request: RpcTransactionRequest,
+    operation: UserOpDataOperationTypes<UserOperationCallData> = Operation.Call
+  ): Promise<Hash> => {
+    if (!request.to) {
+      throw new Error("transaction is missing to address");
+    }
+
+    const overrides: UserOperationOverrides = {};
+    if (request.maxFeePerGas) {
+      overrides.maxFeePerGas = request.maxFeePerGas;
+    }
+    if (request.maxPriorityFeePerGas) {
+      overrides.maxPriorityFeePerGas = request.maxPriorityFeePerGas;
+    }
+
+    const { hash } = await this.sendUserOperation(
+      {
+        target: request.to,
+        data: request.data ?? "0x",
+        value: request.value ? fromHex(request.value, "bigint") : 0n,
+      },
+      overrides,
+      operation
+    );
+
+    return await this.waitForUserOperationTransaction(hash as Hash);
+  };
+
+  sendUserOperation = async <
+    T extends UserOperationCallData | BatchUserOperationCallData
+  >(
+    data: T,
+    overrides?: UserOperationOverrides,
+    operation: UserOpDataOperationTypes<T> = Operation.Call as UserOpDataOperationTypes<T>
+  ): Promise<SendUserOperationResult> => {
+    if (!isKernelAccount(this.account)) {
+      throw new Error("account not connected!");
+    }
+    if (!this.account.validator) {
+      throw new Error("validator not connected!");
+    }
+
+    let callData: BytesLike = "0x";
+
+    if (Array.isArray(data)) {
+      if (operation === Operation.Call) {
+        callData = await this.account.encodeBatchExecute(data);
+      } else {
+        throw InvalidOperation;
+      }
+    } else if (isKernelAccount(this.account)) {
+      if (operation === Operation.DelegateCall) {
+        callData = await this.account.encodeExecuteDelegate(
+          data.target,
+          data.value ?? 0n,
+          data.data
+        );
+      } else if (operation === Operation.Call) {
+        callData = await this.account.encodeExecute(
+          data.target,
+          data.value ?? 0n,
+          data.data
+        );
+      } else {
+        throw InvalidOperation;
+      }
+    } else {
+      throw InvalidOperation;
+    }
+
+    const initCode = await this.account.getInitCode();
+    let hash: string = "";
+    let i = 0;
+    let maxFeePerGas = 0n;
+    let maxPriorityFeePerGas = 0n;
+    let request: UserOperationStruct;
+
+    const nonce = await this.account.getNonce();
+    do {
+      const uoStruct = await asyncPipe(
+        this.dummyPaymasterDataMiddleware,
+        this.feeDataGetter,
+        this.paymasterDataMiddleware,
+        this.gasEstimator,
+        this.customMiddleware ?? noOpMiddleware,
+        async (struct) => ({ ...struct, ...overrides })
+      )({
+        initCode,
+        sender: this.getAddress(),
+        nonce,
+        callData,
+        signature: await this.account
+          .getValidator()
+          .getDynamicDummySignature(await this.getAddress(), callData as Hex),
+        maxFeePerGas,
+        maxPriorityFeePerGas,
+      } as UserOperationStruct);
+      request = deepHexlify(await resolveProperties(uoStruct));
+
+      if (!isValidRequest(request)) {
+        // this pretty prints the uo
+        throw new Error(
+          `Request is missing parameters. All properties on UserOperationStruct must be set. uo: ${JSON.stringify(
+            request,
+            null,
+            2
+          )}`
+        );
+      }
+
+      request.signature = await this.account.validator.getSignature(request);
+      try {
+        hash = await this.rpcClient.sendUserOperation(
+          request,
+          this.entryPointAddress
+        );
+      } catch (error: any) {
+        if (this.isReplacementOpError(error) && i++ < this.sendTxMaxRetries) {
+          maxFeePerGas = (BigInt(request.maxFeePerGas) * 113n) / 100n;
+          maxPriorityFeePerGas =
+            (BigInt(request.maxPriorityFeePerGas) * 113n) / 100n;
+          console.log(
+            `After ${
+              this.sendTxRetryIntervalMs / 60000
+            } minutes, resending tx with Increased Gas fees: maxFeePerGas: ${maxFeePerGas}, maxPriorityFeePerGas: ${maxPriorityFeePerGas}`
+          );
+          await new Promise((resolve) =>
+            setTimeout(resolve, this.sendTxRetryIntervalMs)
+          );
+          continue;
+        }
+        throw this.unwrapError(error);
+      }
+    } while (hash === "");
+
+    return {
+      hash,
+      request,
+    };
+  };
+
+  isReplacementOpError(errorIn: any): boolean {
+    if (errorIn.cause != null) {
+      const failedOpMessage: string | undefined = errorIn?.cause?.message;
+      return (
+        (failedOpMessage?.includes(
+          "replacement op must increase maxFeePerGas and MaxPriorityFeePerGas"
+        ) ||
+          failedOpMessage?.match(/.*replacement.*underpriced.*/) !== null) ??
+        false
+      );
+    }
+    return false;
+  }
+
+  unwrapError(errorIn: any): Error {
+    if (errorIn?.cause != null) {
+      let paymasterInfo: string = "";
+      let failedOpMessage: string | undefined = errorIn?.cause?.message;
+      if (failedOpMessage?.includes("FailedOp") === true) {
+        // TODO: better error extraction methods will be needed
+        const matched = failedOpMessage.match(/FailedOp\((.*)\)/);
+        if (matched != null) {
+          const split = matched[1].split(",");
+          paymasterInfo = `(paymaster address: ${split[1]})`;
+          failedOpMessage = split[2];
+        }
+      }
+      const error = new Error(
+        `The bundler has failed to include UserOperation in a batch: ${failedOpMessage} ${paymasterInfo}`
+      );
+      error.stack = errorIn.stack;
+      return error;
+    }
+    return errorIn;
+  }
+
+  getAccount: () => KernelSmartContractAccount = () => {
+    if (!isKernelAccount(this.account)) {
+      throw new Error("account not connected!");
+    }
+    return this.account;
+  };
+
+  dummyPaymasterDataMiddleware: AccountMiddlewareFn = async (
+    struct: UserOperationStruct
+  ): Promise<UserOperationStruct> => {
+    struct.paymasterAndData =
+      "0xfe7dbcab8aaee4eb67943c1e6be95b1d065985c6000000000000000000000000000000000000000000000000000001869aa31cf400000000000000000000000000000000000000000000000000000000000000007dfe2190f34af27b265bae608717cdc9368b471fc0c097ab7b4088f255b4961e57b039e7e571b15221081c5dce7bcb93459b27a3ab65d2f8a889f4a40b4022801b";
+    return struct;
+  };
+
+  withZeroDevPaymasterAndData(config: PaymasterConfig<PaymasterPolicy>) {
+    if (!this.isConnected()) {
+      throw new Error(
+        "ZeroDevProvider: account is not set, did you call `connect` first?"
+      );
+    }
+
+    return withZeroDevPaymasterAndData(this, config);
+  }
+
+  request: (args: { method: string; params?: any[] }) => Promise<any> = async (
+    args
+  ) => {
+    const { method, params } = args;
+    switch (method) {
+      case "eth_chainId":
+        return this.chain.id;
+      case "eth_sendTransaction":
+        const [tx] = params as [RpcTransactionRequest];
+        return this.sendTransaction(tx);
+      case "personal_sign":
+        if (!this.account) {
+          throw new Error("account not connected!");
+        }
+        const [data, address] = params!;
+        if (address !== (await this.getAddress())) {
+          throw new Error(
+            "cannot sign for address that is not the current account"
+          );
+        }
+        // @ts-ignore
+        return this.account.signWithEip6492(data);
+      default:
+        // @ts-ignore
+        return this.rpcClient.request(args);
+    }
+  };
+}

package/src/kernel-zerodev/types.ts

@@ -0,0 +1,8 @@
+export type WithOptional<T, K extends keyof T> = Pick<Partial<T>, K>;
+export type WithRequired<T, K extends keyof T> = Required<Pick<T, K>>;
+export type MakeOptional<T, K extends keyof T> = Omit<T, K> &
+  Partial<Pick<T, K>>;
+export type RequiredKeys<T> = {
+  [K in keyof T]-?: {} extends Pick<T, K> ? never : K;
+}[keyof T];
+export type RequiredProps<T> = Pick<T, RequiredKeys<T>>;

package/src/kernel-zerodev/utils/ERC4337-utils.ts

@@ -0,0 +1,161 @@
+import {
+  EntryPointAbi,
+  type UserOperationRequest,
+  type UserOperationStruct,
+} from "@alchemy/aa-core";
+import type { NotPromise } from "./calc-pre-verification-gas.js";
+import {
+  encodeAbiParameters,
+  parseAbiParameters,
+  type Hex,
+  keccak256,
+  toHex,
+} from "viem";
+
+// UserOperation is the first parameter of validateUseOp
+const validateUserOpMethod = "simulateValidation";
+
+const UserOpType = EntryPointAbi.find(
+  // @ts-ignore
+  (entry) => entry.name === validateUserOpMethod
+  // @ts-ignore
+)?.inputs[0];
+
+function encode(
+  typevalues: Array<{ type: string; val: any }>,
+  forSignature: boolean
+): string {
+  const types = typevalues
+    .map((typevalue) =>
+      typevalue.type === "bytes" && forSignature ? "bytes32" : typevalue.type
+    )
+    .join(", ");
+  const values = typevalues.map((typevalue) =>
+    typevalue.type === "bytes" && forSignature
+      ? keccak256(typevalue.val)
+      : typevalue.val
+  );
+  return encodeAbiParameters(parseAbiParameters(types), values);
+}
+
+/**
+ * pack the userOperation
+ * @param op
+ * @param forSignature "true" if the hash is needed to calculate the getUserOpHash()
+ *  "false" to pack entire UserOp, for calculating the calldata cost of putting it on-chain.
+ */
+export function packUserOp(
+  op: NotPromise<UserOperationStruct>,
+  forSignature = true
+): string {
+  if (forSignature) {
+    // lighter signature scheme (must match UserOperation#pack): do encode a zero-length signature, but strip afterwards the appended zero-length value
+    const userOpType = {
+      components: [
+        {
+          type: "address",
+          name: "sender",
+        },
+        {
+          type: "uint256",
+          name: "nonce",
+        },
+        {
+          type: "bytes",
+          name: "initCode",
+        },
+        {
+          type: "bytes",
+          name: "callData",
+        },
+        {
+          type: "uint256",
+          name: "callGasLimit",
+        },
+        {
+          type: "uint256",
+          name: "verificationGasLimit",
+        },
+        {
+          type: "uint256",
+          name: "preVerificationGas",
+        },
+        {
+          type: "uint256",
+          name: "maxFeePerGas",
+        },
+        {
+          type: "uint256",
+          name: "maxPriorityFeePerGas",
+        },
+        {
+          type: "bytes",
+          name: "paymasterAndData",
+        },
+        {
+          type: "bytes",
+          name: "signature",
+        },
+      ],
+      name: "userOp",
+      type: "tuple",
+    };
+    // console.log('hard-coded userOpType', userOpType)
+    // console.log('from ABI userOpType', UserOpType)
+    let encoded = encodeAbiParameters(
+      userOpType.components,
+      Object.values({
+        ...op,
+        signature: "0x",
+      })
+    );
+    // remove leading word (total length) and trailing word (zero-length signature)
+    encoded = ("0x" + encoded.slice(66, encoded.length - 64)) as Hex;
+    return encoded;
+  }
+
+  const typevalues = (UserOpType as any).components.map(
+    (c: { name: keyof typeof op; type: string }) => ({
+      type: c.type,
+      val: op[c.name],
+    })
+  );
+  return encode(typevalues, forSignature);
+}
+
+/**
+ * Utility method for asserting a {@link UserOperationStruct} is a {@link UserOperationRequest}
+ *
+ * @param request a {@link UserOperationStruct} to validate
+ * @returns a type guard that asserts the {@link UserOperationStruct} is a {@link UserOperationRequest}
+ */
+export function isValidRequest(
+  request: UserOperationStruct
+): request is UserOperationRequest {
+  // These are the only ones marked as optional in the interface above
+  return (
+    !!request.callGasLimit &&
+    !!request.maxFeePerGas &&
+    request.maxPriorityFeePerGas != null &&
+    !!request.preVerificationGas &&
+    !!request.verificationGasLimit
+  );
+}
+
+export const hexifyUserOp = (resolvedUserOp: any) => {
+  return Object.keys(resolvedUserOp)
+    .map((key) => {
+      let val = resolvedUserOp[key];
+      if (typeof val !== "string" || !val.startsWith("0x")) {
+        val = toHex(val);
+      }
+      return [key, val];
+    })
+    .reduce(
+      (set, [k, v]) => ({
+        ...set,
+        [k]: v,
+      }),
+      {}
+    );
+};

package/src/kernel-zerodev/utils/calc-pre-verification-gas.ts

@@ -0,0 +1,88 @@
+import type { UserOperationStruct } from "@alchemy/aa-core";
+import { toBytes, toHex } from "viem";
+import { packUserOp } from "./ERC4337-utils.js";
+
+export interface GasOverheads {
+  /**
+   * fixed overhead for entire handleOp bundle.
+   */
+  fixed: number;
+
+  /**
+   * per userOp overhead, added on top of the above fixed per-bundle.
+   */
+  perUserOp: number;
+
+  /**
+   * overhead for userOp word (32 bytes) block
+   */
+  perUserOpWord: number;
+
+  // perCallDataWord: number
+
+  /**
+   * zero byte cost, for calldata gas cost calculations
+   */
+  zeroByte: number;
+
+  /**
+   * non-zero byte cost, for calldata gas cost calculations
+   */
+  nonZeroByte: number;
+
+  /**
+   * expected bundle size, to split per-bundle overhead between all ops.
+   */
+  bundleSize: number;
+
+  /**
+   * expected length of the userOp signature.
+   */
+  sigSize: number;
+}
+
+export const DefaultGasOverheads: GasOverheads = {
+  fixed: 21000,
+  perUserOp: 18300,
+  perUserOpWord: 4,
+  zeroByte: 4,
+  nonZeroByte: 16,
+  bundleSize: 1,
+  sigSize: 65,
+};
+
+export type NotPromise<T> = {
+  [P in keyof T]: Exclude<T[P], Promise<any>>;
+};
+
+/**
+ * calculate the preVerificationGas of the given UserOperation
+ * preVerificationGas (by definition) is the cost overhead that can't be calculated on-chain.
+ * it is based on parameters that are defined by the Ethereum protocol for external transactions.
+ * @param userOp filled userOp to calculate. The only possible missing fields can be the signature and preVerificationGas itself
+ * @param overheads gas overheads to use, to override the default values
+ */
+export function calcPreVerificationGas(
+  userOp: Partial<NotPromise<UserOperationStruct>>,
+  overheads?: Partial<GasOverheads>
+): number {
+  const ov = { ...DefaultGasOverheads, ...(overheads ?? {}) };
+  const p: NotPromise<UserOperationStruct> = {
+    // dummy values, in case the UserOp is incomplete.
+    preVerificationGas: 21000, // dummy value, just for calldata cost
+    signature: toHex(Buffer.alloc(ov.sigSize, 1)), // dummy signature
+    ...userOp,
+  } as any;
+
+  const packed = toBytes(packUserOp(p, false));
+  const callDataCost = packed
+    .map((x) => (x === 0 ? ov.zeroByte : ov.nonZeroByte))
+    .reduce((sum, x) => sum + x);
+  const ret = Math.round(
+    callDataCost +
+      ov.fixed / ov.bundleSize +
+      ov.perUserOp +
+      ov.perUserOpWord * packed.length
+  );
+  return ret;
+}

package/src/kernel-zerodev/utils.ts

@@ -0,0 +1,106 @@
+import {
+  encodePacked,
+  fromBytes,
+  toBytes,
+  type Hex,
+  type WalletClient,
+  toHex,
+} from "viem";
+import type {
+  SignTypedDataParams,
+  SmartAccountSigner,
+  UserOperationCallData,
+} from "@alchemy/aa-core";
+import { Signer, type TypedDataField } from "@ethersproject/abstract-signer";
+import { Wallet } from "@ethersproject/wallet";
+import type { SupportedGasToken } from "./paymaster/types.js";
+import { gasTokenChainAddresses } from "./constants.js";
+
+export type UserOperationCallDataWithDelegate = UserOperationCallData & {
+  delegateCall?: boolean;
+};
+
+export type BatchUserOperationCallDataWithDelegate =
+  UserOperationCallDataWithDelegate[];
+
+const encodeCall = (_tx: UserOperationCallDataWithDelegate): string => {
+  const data = toBytes(_tx.data);
+  const encoded = encodePacked(
+    ["uint8", "address", "uint256", "uint256", "bytes"],
+    [
+      _tx.delegateCall ? 1 : 0,
+      _tx.target,
+      _tx.value || BigInt(0),
+      BigInt(data.length),
+      fromBytes(data, "hex"),
+    ]
+  );
+  return encoded.slice(2);
+};
+export const encodeMultiSend = (
+  _txs: BatchUserOperationCallDataWithDelegate
+): Hex => {
+  return ("0x" + _txs.map((tx) => encodeCall(tx)).join("")) as Hex;
+};
+
+export function getGasTokenAddress(
+  gasToken: SupportedGasToken,
+  chainId: number
+): Hex | undefined {
+  if (gasToken === "TEST_ERC20") {
+    return "0x3870419Ba2BBf0127060bCB37f69A1b1C090992B";
+  }
+  return gasTokenChainAddresses[gasToken][chainId] || undefined;
+}
+
+export const convertWalletClientToAccountSigner = (
+  client: WalletClient
+): SmartAccountSigner => {
+  return {
+    getAddress: async () =>
+      Promise.resolve((await client.getAddresses())[0] as `0x${string}`),
+    signMessage: async (message: Uint8Array | string) =>
+      (await client.signMessage({
+        account: client.account!,
+        message:
+          typeof message === "string"
+            ? message
+            : {
+                raw: message,
+              },
+      })) as `0x${string}`,
+    signTypedData: async (params: SignTypedDataParams) =>
+      await client.signTypedData({ ...params, account: client.account! }),
+  };
+};
+
+export const isWallet = (signer: any): signer is Wallet =>
+  signer && signer._signTypedData !== undefined;
+
+export const convertEthersSignerToAccountSigner = (
+  signer: Signer | Wallet
+): SmartAccountSigner => {
+  return {
+    getAddress: async () =>
+      Promise.resolve((await signer.getAddress()) as `0x${string}`),
+    signMessage: async (msg: Uint8Array | string) =>
+      (await signer.signMessage(msg)) as `0x${string}`,
+    signTypedData: async (params: SignTypedDataParams) => {
+      if (!isWallet(signer)) {
+        throw Error("signTypedData method not implemented in signer");
+      }
+      return (await signer._signTypedData(
+        params.domain!,
+        params.types as unknown as Record<string, TypedDataField[]>,
+        params.message
+      )) as Hex;
+    },
+  };
+};
+
+export const randomHexString = (length: number): Hex =>
+  toHex(
+    Array.from({ length }, () =>
+      Math.floor(Math.random() * 16).toString(16)
+    ).join("")
+  );