@aa-sdk/core 4.0.0-alpha.0

package/src/utils/index.ts

@@ -0,0 +1,173 @@
+import type { Chain } from "viem";
+import { toHex } from "viem";
+import * as chains from "viem/chains";
+import * as alchemyChains from "../chains/index.js";
+import type { PromiseOrValue } from "../types.js";
+import type { RecordableKeys } from "./types.js";
+
+export const AlchemyChainMap = new Map<number, Chain>(
+  Object.values(alchemyChains).map((c) => [c.id, c])
+);
+
+/**
+ * Utility method for converting a chainId to a {@link Chain} object
+ *
+ * @param chainId - the chainId to convert
+ * @returns a {@link Chain} object for the given chainId
+ * @throws if the chainId is not found
+ */
+export const getChain = (chainId: number): Chain => {
+  for (const chain of Object.values(chains)) {
+    if (chain.id === chainId) {
+      return AlchemyChainMap.get(chain.id) ?? chain;
+    }
+  }
+  throw new Error("could not find chain");
+};
+
+/**
+ * Utility function that allows for piping a series of async functions together
+ *
+ * @param fns - functions to pipe
+ * @returns result of the pipe
+ */
+export const asyncPipe =
+  <S, O, F>(...fns: ((s: S, o?: O, f?: F) => Promise<S>)[]) =>
+  async (s: S, o?: O, f?: F) => {
+    let result = s;
+    for (const fn of fns) {
+      result = await fn(result, o, f);
+    }
+    return result;
+  };
+
+// based on @ethersproject/properties, but pulled in here to minize the dependency on ethers
+export type Deferrable<T> = {
+  [K in keyof T]: PromiseOrValue<T[K]>;
+};
+
+/**
+ * Await all of the properties of a {@link Deferrable} object
+ *
+ * @param object - a {@link Deferrable} object
+ * @returns the object with its properties resolved
+ */
+export async function resolveProperties<T>(object: Deferrable<T>): Promise<T> {
+  const promises = Object.keys(object).map((key) => {
+    const value = object[key as keyof Deferrable<T>];
+    return Promise.resolve(value).then((v) => ({ key: key, value: v }));
+  });
+
+  const results = await Promise.all(promises);
+
+  return filterUndefined<T>(
+    results.reduce((accum, curr) => {
+      accum[curr.key as keyof T] = curr.value;
+      return accum;
+    }, {} as T)
+  );
+}
+
+/**
+ * Recursively converts all values in an object to hex strings
+ *
+ * @param obj - obj to deep hexlify
+ * @returns object with all of its values hexlified
+ */
+export function deepHexlify(obj: any): any {
+  if (typeof obj === "function") {
+    return undefined;
+  }
+  if (obj == null || typeof obj === "string" || typeof obj === "boolean") {
+    return obj;
+  } else if (typeof obj === "bigint") {
+    return toHex(obj);
+  } else if (obj._isBigNumber != null || typeof obj !== "object") {
+    return toHex(obj).replace(/^0x0/, "0x");
+  }
+  if (Array.isArray(obj)) {
+    return obj.map((member) => deepHexlify(member));
+  }
+  return Object.keys(obj).reduce(
+    (set, key) => ({
+      ...set,
+      [key]: deepHexlify(obj[key]),
+    }),
+    {}
+  );
+}
+
+// borrowed from ethers.js
+export function defineReadOnly<T, K extends keyof T>(
+  object: T,
+  key: K,
+  value: T[K]
+): void {
+  Object.defineProperty(object, key, {
+    enumerable: true,
+    value: value,
+    writable: false,
+  });
+}
+
+export function filterUndefined<T>(obj: T): T {
+  for (const key in obj) {
+    if (obj[key] == null) {
+      delete obj[key];
+    }
+  }
+  return obj as T;
+}
+
+export function pick(obj: Record<string, unknown>, keys: string | string[]) {
+  return Object.keys(obj)
+    .filter((k) => keys.includes(k))
+    .reduce((res, k) => Object.assign(res, { [k]: obj[k] }), {});
+}
+
+/**
+ * Utility method for checking if the passed in values are all equal (strictly)
+ *
+ * @param params - values to check
+ * @returns a boolean indicating if all values are the same
+ * @throws if no values are passed in
+ */
+export const allEqual = (...params: any[]): boolean => {
+  if (params.length === 0) {
+    throw new Error("no values passed in");
+  }
+  return params.every((v) => v === params[0]);
+};
+
+/**
+ * Utility method for checking the condition and return the value if condition holds true, undefined if not.
+ *
+ * @param condition - condition to check
+ * @param value - value to return when condition holds true
+ * @returns the value if condition holds true, undefined if not
+ */
+export const conditionalReturn = <T>(
+  condition: Promise<boolean>,
+  value: () => Promise<T>
+): Promise<T | undefined> => condition.then((t) => (t ? value() : undefined));
+
+export const toRecord = <
+  T extends { [K in RecordableKeys<T>]: string | number | symbol },
+  K extends RecordableKeys<T>,
+  V
+>(
+  array: T[],
+  selector: K,
+  fn: (item: T) => V
+): Record<T[K], V> =>
+  array.reduce((acc, item) => {
+    acc[item[selector]] = fn(item);
+    return acc;
+  }, {} as Record<T[K], V>);
+
+export * from "./bigint.js";
+export * from "./bytes.js";
+export * from "./defaults.js";
+export * from "./schema.js";
+export type * from "./types.js";
+export * from "./userop.js";

package/src/utils/schema.ts

@@ -0,0 +1,52 @@
+import { isHex, type Chain } from "viem";
+import { z } from "zod";
+import type { BigNumberish, Multiplier } from "../types";
+
+export const ChainSchema = z.custom<Chain>(
+  (chain) =>
+    chain != null &&
+    typeof chain === "object" &&
+    "id" in chain &&
+    typeof chain.id === "number"
+);
+
+export const HexSchema = z.custom<`0x${string}` | "0x">((val) => {
+  return isHex(val, { strict: true });
+});
+
+// [!region BigNumberish]
+export const BigNumberishSchema = z.union([HexSchema, z.number(), z.bigint()]);
+// [!endregion BigNumberish]
+
+// [!region BigNumberishRange]
+export const BigNumberishRangeSchema = z
+  .object({
+    min: BigNumberishSchema.optional(),
+    max: BigNumberishSchema.optional(),
+  })
+  .strict();
+// [!endregion BigNumberishRange]
+
+// [!region Multiplier]
+export const MultiplierSchema = z
+  .object({
+    /**
+     * Multiplier value with max precision of 4 decimal places
+     */
+    multiplier: z.number().refine(
+      (n) => {
+        return (n.toString().split(".")[1]?.length ?? 0) <= 4;
+      },
+      { message: "Max precision is 4 decimal places" }
+    ),
+  })
+  .strict();
+// [!endregion Multiplier]
+
+export function isBigNumberish(x: any): x is BigNumberish {
+  return x != null && BigNumberishSchema.safeParse(x).success;
+}
+
+export function isMultiplier(x: any): x is Multiplier {
+  return x != null && MultiplierSchema.safeParse(x).success;
+}

package/src/utils/stateOverride.ts

@@ -0,0 +1,80 @@
+import type { Address } from "abitype";
+import {
+  AccountStateConflictError,
+  InvalidAddressError,
+  StateAssignmentConflictError,
+  isAddress,
+  numberToHex,
+  type RpcAccountStateOverride,
+  type RpcStateMapping,
+  type RpcStateOverride,
+  type StateMapping,
+  type StateOverride,
+} from "viem";
+
+// Copied from Viem's utils/stateOverride.ts, which does not expose these
+// functions.
+
+type SerializeStateMappingParameters = StateMapping | undefined;
+
+function serializeStateMapping(
+  stateMapping: SerializeStateMappingParameters
+): RpcStateMapping | undefined {
+  if (!stateMapping || stateMapping.length === 0) return undefined;
+  return stateMapping.reduce((acc, { slot, value }) => {
+    validateBytes32HexLength(slot);
+    validateBytes32HexLength(value);
+    acc[slot] = value;
+    return acc;
+  }, {} as RpcStateMapping);
+}
+
+function validateBytes32HexLength(value: Address): void {
+  if (value.length !== 66) {
+    // This is the error message from Viem's non-exported InvalidBytesLengthError.
+    throw new Error(
+      `Hex is expected to be 66 hex long, but is ${value.length} hex long.`
+    );
+  }
+}
+
+type SerializeAccountStateOverrideParameters = Omit<
+  StateOverride[number],
+  "address"
+>;
+
+function serializeAccountStateOverride(
+  parameters: SerializeAccountStateOverrideParameters
+): RpcAccountStateOverride {
+  const { balance, nonce, state, stateDiff, code } = parameters;
+  const rpcAccountStateOverride: RpcAccountStateOverride = {};
+  if (code !== undefined) rpcAccountStateOverride.code = code;
+  if (balance !== undefined)
+    rpcAccountStateOverride.balance = numberToHex(balance);
+  if (nonce !== undefined) rpcAccountStateOverride.nonce = numberToHex(nonce);
+  if (state !== undefined)
+    rpcAccountStateOverride.state = serializeStateMapping(state);
+  if (stateDiff !== undefined) {
+    if (rpcAccountStateOverride.state) throw new StateAssignmentConflictError();
+    rpcAccountStateOverride.stateDiff = serializeStateMapping(stateDiff);
+  }
+  return rpcAccountStateOverride;
+}
+
+type SerializeStateOverrideParameters = StateOverride | undefined;
+
+// eslint-disable-next-line jsdoc/require-jsdoc
+export function serializeStateOverride(
+  parameters?: SerializeStateOverrideParameters
+): RpcStateOverride | undefined {
+  if (!parameters) return undefined;
+  const rpcStateOverride: RpcStateOverride = {};
+  for (const { address, ...accountState } of parameters) {
+    if (!isAddress(address, { strict: false }))
+      throw new InvalidAddressError({ address });
+    if (rpcStateOverride[address])
+      throw new AccountStateConflictError({ address: address });
+    rpcStateOverride[address] = serializeAccountStateOverride(accountState);
+  }
+  return rpcStateOverride;
+}

package/src/utils/testUtils.ts

@@ -0,0 +1,42 @@
+import { createPublicClient, custom, type Chain, type Hex } from "viem";
+import {
+  toSmartContractAccount,
+  type SmartContractAccount,
+} from "../account/smartContractAccount.js";
+import {
+  createBundlerClientFromExisting,
+  type BundlerClient,
+} from "../client/bundlerClient.js";
+import { getEntryPoint } from "../entrypoint/index.js";
+import type { DefaultEntryPointVersion } from "../entrypoint/types.js";
+
+export const createDummySmartContractAccount = async <C extends BundlerClient>(
+  client: C
+): Promise<SmartContractAccount<"dummy", DefaultEntryPointVersion>> => {
+  return toSmartContractAccount({
+    source: "dummy",
+    accountAddress: "0x1234567890123456789012345678901234567890",
+    entryPoint: getEntryPoint(client.chain),
+    chain: client.chain,
+    transport: custom(client),
+    signMessage: async () => "0xdeadbeef",
+    signTypedData: async () => "0xdeadbeef",
+    getAccountInitCode: async () =>
+      "0x1234567890123456789012345678901234567890deadbeef",
+    encodeBatchExecute: async () => "0x",
+    encodeExecute: async () => "0x",
+    getDummySignature: (): Hex =>
+      "0xfffffffffffffffffffffffffffffff0000000000000000000000000000000007aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa1c",
+  });
+};
+
+export const createTestClient = (chain: Chain) => {
+  return createBundlerClientFromExisting(
+    createPublicClient({
+      chain,
+      transport: custom({
+        request: async () => {},
+      }),
+    })
+  );
+};

package/src/utils/types.ts

@@ -0,0 +1,94 @@
+// borrowed from viem
+
+/**
+ * @description Constructs a type by excluding `undefined` from `T`.
+ *
+ * @example
+ * NoUndefined<string | undefined>
+ * => string
+ */
+export type NoUndefined<T> = T extends undefined ? never : T;
+// borrowed from viem
+/**
+ * @description Checks if {@link T} is `undefined`
+ * @param T - Type to check
+ * @example
+ * type Result = IsUndefined<undefined>
+ * //   ^? type Result = true
+ */
+
+export type IsUndefined<T> = [undefined] extends [T] ? true : false;
+
+export type RequiredBy<TType, TKeys extends keyof TType> = Required<
+  Pick<TType, TKeys>
+> &
+  Omit<TType, TKeys>;
+
+/**
+ * @description Combines members of an intersection into a readable type.
+ *
+ * @see {@link https://twitter.com/mattpocockuk/status/1622730173446557697?s=20&t=NdpAcmEFXY01xkqU3KO0Mg}
+ * @example
+ * Prettify<{ a: string } & { b: string } & { c: number, d: bigint }>
+ * => { a: string, b: string, c: number, d: bigint }
+ */
+export type Prettify<T> = {
+  [K in keyof T]: T[K];
+} & {};
+
+export type WithRequired<T, K extends keyof T> = Required<Pick<T, K>>;
+export type WithOptional<T, K extends keyof T> = Pick<Partial<T>, K>;
+
+// Checks for type equivalence, evaluates always to either `true` or `false`.
+// Semantics: (EQ<A, B> = true) <==> (A <==> B)
+export type EQ<A, B> = [A] extends [B]
+  ? [B] extends [A]
+    ? true
+    : false
+  : false;
+
+// Auxiliary type for `IsMemberOrSubtypeOfAComponent`
+// Evaluates to `true` or `boolean` if one of the explicit components (according to the TypeScript distribution
+// mechanism for union types) of the union type equals the other given type.
+// Examples:
+//    EqualsOneOfTheComponents<string, string | boolean> ⟶ boolean
+//    EqualsOneOfTheComponents<string, string> ⟶ true
+//    EqualsOneOfTheComponents<number, string | boolean> ⟶ false
+export type EqualsOneOfTheComponents<T, Union> = Union extends infer Component // enforce distribution
+  ? EQ<T, Component>
+  : never;
+
+// Auxiliary type for `IsOneOf`
+export type IsMemberOrSubtypeOfAComponent<
+  T,
+  Union,
+  ConjunctionOfExplicitComponentChecks extends boolean
+> = [T] extends [Union]
+  ? true extends ConjunctionOfExplicitComponentChecks
+    ? true
+    : false
+  : false;
+
+// Checks whether the given type equals one of the explicit components of the union type. Note that in this respect we
+// consider the members of the infinite types number and string as implicit since the inbuilt distribution mechanism of
+// TypeScript does not (cannot) distribute over the infinite number of strings or numbers. However, `boolean` is treated
+// by TypeScript (and accordingly here) as the explicit union `true | false`.
+//
+// In particular, the evaluation result is `false` if the type is a proper union of components of the union type. It also
+// evaluates to false if the given type is a proper subtype of one of its explicit components.
+// It always evaluates to either `true` or `false`.
+// Examples:
+//    IsOneOf<number, string | number | boolean> ⟶ true
+//    IsOneOf<2 | 4, 0 | 1 | 2 | 3 | 4 | 5 | 6> ⟶ false
+//    IsOneOf<'text', string> ⟶ false  // only implicit but not explicit component
+export type IsOneOf<T, Union> = IsMemberOrSubtypeOfAComponent<
+  T,
+  Union,
+  EqualsOneOfTheComponents<T, Union>
+>;
+
+export type OneOf<T1, T2> = IsOneOf<T1, T2> extends true ? T1 : never;
+
+export type RecordableKeys<T> = {
+  [K in keyof T]: T[K] extends string | number | symbol ? K : never;
+}[keyof T];

package/src/utils/userop.ts

@@ -0,0 +1,220 @@
+import { concat, type Address, type Hex } from "viem";
+import type { EntryPointVersion } from "../entrypoint/types";
+import type {
+  BigNumberish,
+  Multiplier,
+  UserOperationFeeOptionsField,
+  UserOperationOverrides,
+  UserOperationRequest,
+  UserOperationStruct,
+  UserOperationStruct_v6,
+  UserOperationStruct_v7,
+} from "../types";
+import { bigIntClamp, bigIntMultiply } from "./bigint.js";
+import { allEqual, isBigNumberish } from "./index.js";
+
+/**
+ * Utility method for asserting a {@link UserOperationStruct} has valid fields for the given entry point version
+ *
+ * @param request a {@link UserOperationStruct} to validate
+ * @returns a type guard that asserts the {@link UserOperationRequest} is valid
+ */
+export function isValidRequest<
+  TEntryPointVersion extends EntryPointVersion = EntryPointVersion
+>(
+  request: UserOperationStruct<TEntryPointVersion>
+): request is UserOperationRequest<TEntryPointVersion> {
+  // These are the only ones marked as optional in the interface above
+  return (
+    BigInt(request.callGasLimit || 0n) > 0n &&
+    BigInt(request.maxFeePerGas || 0n) > 0n &&
+    BigInt(request.preVerificationGas || 0n) > 0n &&
+    BigInt(request.verificationGasLimit || 0n) > 0n &&
+    request.maxPriorityFeePerGas != null &&
+    isValidPaymasterAndData(request) &&
+    isValidFactoryAndData(request)
+  );
+}
+
+/**
+ * Utility method for asserting a {@link UserOperationRequest} has valid fields for the paymaster data
+ *
+ * @param request a {@link UserOperationRequest} to validate
+ * @returns a type guard that asserts the {@link UserOperationRequest} is a {@link UserOperationRequest}
+ */
+export function isValidPaymasterAndData<
+  TEntryPointVersion extends EntryPointVersion = EntryPointVersion
+>(request: UserOperationStruct<TEntryPointVersion>): boolean {
+  if ("paymasterAndData" in request) {
+    return (request as UserOperationStruct_v6).paymasterAndData != null;
+  }
+
+  // either all exist, or none.
+  return allEqual(
+    (request as UserOperationStruct_v7).paymaster == null,
+    (request as UserOperationStruct_v7).paymasterData == null,
+    (request as UserOperationStruct_v7).paymasterPostOpGasLimit == null,
+    (request as UserOperationStruct_v7).paymasterVerificationGasLimit == null
+  );
+}
+
+/**
+ * Utility method for asserting a {@link UserOperationStruct} has valid fields for the paymaster data
+ *
+ * @param request a {@link UserOperationRequest} to validate
+ * @returns a type guard that asserts the {@link UserOperationStruct} is a {@link UserOperationRequest}
+ */
+export function isValidFactoryAndData<
+  TEntryPointVersion extends EntryPointVersion = EntryPointVersion
+>(request: UserOperationStruct<TEntryPointVersion>): boolean {
+  if ("initCode" in request) {
+    const { initCode } = request as UserOperationStruct_v6;
+    return initCode != null;
+  }
+
+  // either all exist, or none.
+  return allEqual(
+    (request as UserOperationStruct_v7).factory == null,
+    (request as UserOperationStruct_v7).factoryData == null
+  );
+}
+
+/**
+ * Utility method for applying a {@link UserOperationOverrides} field value
+ * over the current value set for the field
+ *
+ * @param value the current value of the field
+ * @param override the override value to apply
+ * @returns the new value of the field after applying the override
+ */
+export function applyUserOpOverride<TValue extends BigNumberish | undefined>(
+  value: TValue,
+  override?: BigNumberish | Multiplier
+): TValue | BigNumberish {
+  if (override == null) {
+    return value;
+  }
+
+  if (isBigNumberish(override)) {
+    return override;
+  }
+
+  // multiplier override
+  else {
+    return value != null ? bigIntMultiply(value, override.multiplier) : value;
+  }
+}
+
+/**
+ * Utility method for applying a {@link UserOperationFeeOptionsField} value
+ * over the current value set for the field
+ *
+ * @param value the current value of the field
+ * @param feeOption the fee option field value to apply
+ * @returns the new value of the field after applying the fee option
+ */
+export function applyUserOpFeeOption<TValue extends BigNumberish | undefined>(
+  value: TValue,
+  feeOption?: UserOperationFeeOptionsField
+): TValue | BigNumberish {
+  if (feeOption == null) {
+    return value;
+  }
+
+  return value != null
+    ? bigIntClamp(
+        feeOption.multiplier
+          ? bigIntMultiply(value, feeOption.multiplier)
+          : value,
+        feeOption.min,
+        feeOption.max
+      )
+    : feeOption.min ?? 0n;
+}
+
+/**
+ * Utility method for applying a {@link UserOperationOverrides} field value and
+ * a {@link UserOperationFeeOptionsField} value over the current value set for the field,
+ * with the override taking precedence over the fee option
+ *
+ * @param value the current value of the field
+ * @param [override] the override value to apply
+ * @param [feeOption] the fee option field value to apply
+ * @returns the new value of the field after applying the override or fee option
+ */
+export function applyUserOpOverrideOrFeeOption<
+  TValue extends BigNumberish | undefined
+>(
+  value: TValue,
+  override?: BigNumberish | Multiplier,
+  feeOption?: UserOperationFeeOptionsField
+): TValue | BigNumberish {
+  return value != null && override != null
+    ? applyUserOpOverride(value, override)!
+    : applyUserOpFeeOption(value, feeOption);
+}
+
+/**
+ * Utility method for checking whether the middleware pipeline should
+ * bypass the paymaster middleware for the user operation with the given overrides,
+ * either because the UserOp is paying for its own gas, or passing a specific paymaster
+ *
+ * @template EntryPointVersion TEntryPointVersion
+ * @param overrides the user operation overrides to check
+ * @returns whether the paymaster middleware should be bypassed
+ */
+export const bypassPaymasterAndData = <
+  TEntryPointVersion extends EntryPointVersion = EntryPointVersion
+>(
+  overrides: UserOperationOverrides<TEntryPointVersion> | undefined
+): boolean =>
+  !!overrides &&
+  ("paymasterAndData" in overrides || "paymasterData" in overrides);
+
+/**
+ * An alternative to `bypassPaymasterAndData` which only returns true if the data parameter
+ * is "0x," this is useful for cases when middleware should be bypassed ONLY IF the UserOp will
+ * pay for its own gas
+ *
+ * @template EntryPointVersion TEntryPointVersion
+ * @param overrides the user operation overrides to check
+ * @returns whether the paymaster middleware should be bypassed
+ */
+export const bypassPaymasterAndDataEmptyHex = <
+  TEntryPointVersion extends EntryPointVersion = EntryPointVersion
+>(
+  overrides: UserOperationOverrides<TEntryPointVersion> | undefined
+): boolean =>
+  overrides !== undefined &&
+  (("paymasterAndData" in overrides && overrides.paymasterAndData === "0x") ||
+    ("paymasterData" in overrides && overrides.paymasterData === "0x"));
+
+/**
+ * Utility method for parsing the paymaster address and paymasterData from the paymasterAndData hex string
+ *
+ * @param paymasterAndData the paymaster and data hex string to parse.
+ *                         The hex string refers to the paymasterAndData field of entrypoint v0.6 user operation request
+ * @returns the parsed paymaster and paymasterData fields of entrypoint v0.7 user operation request paymaster and paymasterData field
+ */
+export const parsePaymasterAndData = (
+  paymasterAndData: Hex
+): Pick<UserOperationRequest<"0.7.0">, "paymaster" | "paymasterData"> => ({
+  paymaster: paymasterAndData.substring(0, 42) as Address,
+  paymasterData: `0x${paymasterAndData.substring(42)}` as Hex,
+});
+
+/**
+ * Utility method for converting the object containing the paymaster address and paymaster data
+ * to the paymaster and data concatenated hex string
+ *
+ * @param paymasterAndData the object containing the picked paymaster and paymasterData fields of
+ *                         entrypoint v0.7 user operation request
+ * @param paymasterAndData.paymaster the paymaster address
+ * @param paymasterAndData.paymasterData the paymaster data
+ * @returns the paymasterAndData hex value of entrypoint v0.6 user operation request paymasterAndData field
+ */
+export const concatPaymasterAndData = ({
+  paymaster = "0x",
+  paymasterData = "0x",
+}: Pick<UserOperationRequest<"0.7.0">, "paymaster" | "paymasterData">): Hex =>
+  concat([paymaster, paymasterData]);

package/src/version.ts

@@ -0,0 +1,3 @@
+// This file is autogenerated by inject-version.ts. Any changes will be
+// overwritten on commit!
+export const VERSION = "4.0.0-alpha.0";