@zerodev/sdk 4.0.2-alpha.23

package/src/kernel-zerodev/provider.ts

@@ -0,0 +1,307 @@
+import {
+  type Address,
+  type Chain,
+  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,
+} 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;
+
+  sendUserOperation = async <
+    T extends UserOperationCallData | BatchUserOperationCallData
+  >(
+    data: T,
+    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
+      )({
+        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/signer/zd-local-account.ts

@@ -0,0 +1,63 @@
+import { type SmartAccountSigner } from "@alchemy/aa-core";
+import {
+  isHex,
+  type HDAccount,
+  type Hash,
+  type PrivateKeyAccount,
+  type TypedData,
+  type TypedDataDefinition,
+  type Hex,
+} from "viem";
+import { mnemonicToAccount, privateKeyToAccount } from "viem/accounts";
+
+export class ZeroDevLocalAccountSigner<T extends HDAccount | PrivateKeyAccount>
+  implements SmartAccountSigner
+{
+  private owner: T;
+  constructor(owner: T) {
+    this.owner = owner;
+  }
+
+  readonly signMessage: (msg: string | Uint8Array) => Promise<`0x${string}`> = (
+    msg
+  ) => {
+    if (typeof msg === "string" && !isHex(msg)) {
+      return this.owner.signMessage({
+        message: msg,
+      });
+    } else {
+      return this.owner.signMessage({
+        message: {
+          raw: msg,
+        },
+      });
+    }
+  };
+
+  readonly signTypedData: <
+    TTypedData extends TypedData | { [key: string]: unknown },
+    TPrimaryType extends string = string
+  >(
+    typedData: TypedDataDefinition<TTypedData, TPrimaryType>
+  ) => Promise<Hash> = async (typedData) => {
+    return await this.owner.signTypedData(typedData);
+  };
+
+  readonly getAddress: () => Promise<`0x${string}`> = async () => {
+    return this.owner.address;
+  };
+
+  static mnemonicToAccountSigner(
+    key: string
+  ): ZeroDevLocalAccountSigner<HDAccount> {
+    const owner = mnemonicToAccount(key);
+    return new ZeroDevLocalAccountSigner(owner);
+  }
+
+  static privateKeyToAccountSigner(
+    key: Hex
+  ): ZeroDevLocalAccountSigner<PrivateKeyAccount> {
+    const owner = privateKeyToAccount(key);
+    return new ZeroDevLocalAccountSigner(owner);
+  }
+}

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;
+}