@aa-sdk/core 4.0.0-alpha.0

package/src/actions/smartAccount/buildUserOperation.ts

@@ -0,0 +1,52 @@
+import type { Chain, Client, Transport } from "viem";
+import {
+  type GetEntryPointFromAccount,
+  type SmartContractAccount,
+} from "../../account/smartContractAccount.js";
+import { isBaseSmartAccountClient } from "../../client/isSmartAccountClient.js";
+import { AccountNotFoundError } from "../../errors/account.js";
+import { IncompatibleClientError } from "../../errors/client.js";
+import type { UserOperationStruct } from "../../types.js";
+import { _initUserOperation } from "./internal/initUserOperation.js";
+import { _runMiddlewareStack } from "./internal/runMiddlewareStack.js";
+import type {
+  BuildUserOperationParameters,
+  UserOperationContext,
+} from "./types";
+
+export async function buildUserOperation<
+  TTransport extends Transport = Transport,
+  TChain extends Chain | undefined = Chain | undefined,
+  TAccount extends SmartContractAccount | undefined =
+    | SmartContractAccount
+    | undefined,
+  TContext extends UserOperationContext | undefined =
+    | UserOperationContext
+    | undefined,
+  TEntryPointVersion extends GetEntryPointFromAccount<TAccount> = GetEntryPointFromAccount<TAccount>
+>(
+  client: Client<TTransport, TChain, TAccount>,
+  args: BuildUserOperationParameters<TAccount, TContext, TEntryPointVersion>
+): Promise<UserOperationStruct<TEntryPointVersion>> {
+  const { account = client.account, overrides, context } = args;
+  if (!account) {
+    throw new AccountNotFoundError();
+  }
+
+  if (!isBaseSmartAccountClient(client)) {
+    throw new IncompatibleClientError(
+      "BaseSmartAccountClient",
+      "buildUserOperation",
+      client
+    );
+  }
+
+  return _initUserOperation(client, args).then((_uo) =>
+    _runMiddlewareStack(client, {
+      uo: _uo,
+      overrides,
+      account,
+      context,
+    })
+  );
+}

package/src/actions/smartAccount/buildUserOperationFromTx.ts

@@ -0,0 +1,112 @@
+import {
+  type Chain,
+  type Client,
+  type SendTransactionParameters,
+  type Transport,
+} from "viem";
+import type {
+  GetEntryPointFromAccount,
+  SmartContractAccount,
+} from "../../account/smartContractAccount.js";
+import { isBaseSmartAccountClient } from "../../client/isSmartAccountClient.js";
+import { AccountNotFoundError } from "../../errors/account.js";
+import { IncompatibleClientError } from "../../errors/client.js";
+import { TransactionMissingToParamError } from "../../errors/transaction.js";
+import type {
+  UserOperationOverrides,
+  UserOperationStruct,
+} from "../../types.js";
+import { buildUserOperation } from "./buildUserOperation.js";
+import type { UserOperationContext } from "./types.js";
+
+/**
+ * Performs [`buildUserOperationFromTx`](./buildUserOperationFromTx.md) in batch and builds into a single, yet to be signed `UserOperation` (UO) struct. The output user operation struct will be filled with all gas fields (and paymaster data if a paymaster is used) based on the transactions data (`to`, `data`, `value`, `maxFeePerGas`, `maxPriorityFeePerGas`) computed using the configured [`ClientMiddlewares`](/packages/aa-core/smart-account-client/middleware/index) on the `SmartAccountClient`
+ * 
+ * @example
+ * ```ts
+import type { RpcTransactionRequest } from "viem";
+import { smartAccountClient } from "./smartAccountClient";
+// [!code focus:99]
+// buildUserOperationFromTx converts a traditional Ethereum transaction and returns
+// the unsigned user operation struct after constructing the user operation struct
+// through the middleware pipeline
+const tx: RpcTransactionRequest = {
+  from, // ignored
+  to,
+  data: encodeFunctionData({
+    abi: ContractABI.abi,
+    functionName: "func",
+    args: [arg1, arg2, ...],
+  }),
+};
+const uoStruct = await smartAccountClient.buildUserOperationFromTx(tx);
+ 
+// signUserOperation signs the above unsigned user operation struct built
+// using the account connected to the smart account client
+const request = await smartAccountClient.signUserOperation({ uoStruct });
+ 
+// You can use the BundlerAction `sendRawUserOperation` (packages/core/src/actions/bundler/sendRawUserOperation.ts)
+// to send the signed user operation request to the bundler, requesting the bundler to send the signed uo to the
+// EntryPoint contract pointed at by the entryPoint address parameter
+const entryPointAddress = client.account.getEntryPoint().address;
+const uoHash = await smartAccountClient.sendRawUserOperation({ request, entryPoint: entryPointAddress });
+```
+ * 
+ * @param client the smart account client to use for RPC requests
+ * @param args {@link SendTransactionParameters}
+ * @param overrides optional {@link UserOperationOverrides} to use for any of the fields
+ * @param context if the smart account client requires additinoal context for building UOs
+ * @returns a Promise containing the built user operation
+ */
+export async function buildUserOperationFromTx<
+  TChain extends Chain | undefined = Chain | undefined,
+  TAccount extends SmartContractAccount | undefined =
+    | SmartContractAccount
+    | undefined,
+  TChainOverride extends Chain | undefined = Chain | undefined,
+  TContext extends UserOperationContext | undefined =
+    | UserOperationContext
+    | undefined,
+  TEntryPointVersion extends GetEntryPointFromAccount<TAccount> = GetEntryPointFromAccount<TAccount>
+>(
+  client: Client<Transport, TChain, TAccount>,
+  args: SendTransactionParameters<TChain, TAccount, TChainOverride>,
+  overrides?: UserOperationOverrides<TEntryPointVersion>,
+  context?: TContext
+): Promise<UserOperationStruct<TEntryPointVersion>> {
+  const { account = client.account, ...request } = args;
+  if (!account || typeof account === "string") {
+    throw new AccountNotFoundError();
+  }
+
+  if (!request.to) {
+    throw new TransactionMissingToParamError();
+  }
+
+  if (!isBaseSmartAccountClient(client)) {
+    throw new IncompatibleClientError(
+      "BaseSmartAccountClient",
+      "buildUserOperationFromTx",
+      client
+    );
+  }
+
+  const _overrides = {
+    ...overrides,
+    maxFeePerGas: request.maxFeePerGas ? request.maxFeePerGas : undefined,
+    maxPriorityFeePerGas: request.maxPriorityFeePerGas
+      ? request.maxPriorityFeePerGas
+      : undefined,
+  } as UserOperationOverrides<TEntryPointVersion>;
+
+  return buildUserOperation(client, {
+    uo: {
+      target: request.to,
+      data: request.data ?? "0x",
+      value: request.value ? request.value : 0n,
+    },
+    account: account as SmartContractAccount,
+    context,
+    overrides: _overrides,
+  });
+}

package/src/actions/smartAccount/buildUserOperationFromTxs.ts

@@ -0,0 +1,168 @@
+import { fromHex, type Chain, type Client, type Transport } from "viem";
+import type {
+  GetEntryPointFromAccount,
+  SmartContractAccount,
+} from "../../account/smartContractAccount";
+import { isBaseSmartAccountClient } from "../../client/isSmartAccountClient.js";
+import { AccountNotFoundError } from "../../errors/account.js";
+import { IncompatibleClientError } from "../../errors/client.js";
+import { TransactionMissingToParamError } from "../../errors/transaction.js";
+import type { UserOperationOverrides } from "../../types";
+import { bigIntMax } from "../../utils/index.js";
+import { buildUserOperation } from "./buildUserOperation.js";
+import type {
+  BuildTransactionParameters,
+  BuildUserOperationFromTransactionsResult,
+  UserOperationContext,
+} from "./types";
+
+/**
+ * Performs {@link buildUserOperationFromTx} in batch and builds into a single,
+ * yet to be signed `UserOperation` (UO) struct. The output user operation struct
+ * will be filled with all gas fields (and paymaster data if a paymaster is used)
+ * based on the transactions data (`to`, `data`, `value`, `maxFeePerGas`,
+ * `maxPriorityFeePerGas`) computed using the configured
+ * [`ClientMiddlewares`](/packages/aa-core/smart-account-client/middleware/index) on the `SmartAccountClient`
+ * 
+ * @example
+ * ```ts
+ * import type { RpcTransactionRequest } from "viem";
+import { smartAccountClient } from "./smartAccountClient";
+// [!code focus:99]
+// buildUserOperationFromTxs converts traditional Ethereum transactions in batch and returns
+// the unsigned user operation struct after constructing the user operation struct
+// through the middleware pipeline
+const requests: RpcTransactionRequest[] = [
+  {
+    from, // ignored
+    to,
+    data: encodeFunctionData({
+      abi: ContractABI.abi,
+      functionName: "func",
+      args: [arg1, arg2, ...],
+    }),
+  },
+  {
+    from, // ignored
+    to,
+    data: encodeFunctionData({
+      abi: ContractABI.abi,
+      functionName: "func",
+      args: [arg1, arg2, ...],
+    }),
+  },
+  ...
+  {
+    from, // ignored
+    to,
+    data: encodeFunctionData({
+      abi: ContractABI.abi,
+      functionName: "func",
+      args: [arg1, arg2, ...],
+    }),
+  },
+];
+const uoStruct = await smartAccountClient.buildUserOperationFromTxs({
+  requests,
+});
+ 
+// signUserOperation signs the above unsigned user operation struct built
+// using the account connected to the smart account client
+const request = await smartAccountClient.signUserOperation({ uoStruct });
+ 
+// You can use the BundlerAction `sendRawUserOperation` (packages/core/src/actions/bundler/sendRawUserOperation.ts)
+// to send the signed user operation request to the bundler, requesting the bundler to send the signed uo to the
+// EntryPoint contract pointed at by the entryPoint address parameter
+const entryPointAddress = client.account.getEntryPoint().address;
+const uoHash = await smartAccountClient.sendRawUserOperation({
+  request,
+  entryPoint: entryPointAddress,
+});
+ * ```
+ *
+ * @param client the smart account client to use to make RPC calls
+ * @param args {@link BuildTransactionParameters} an object containing the requests
+ * to build as well as, the account if not hoisted, the context, the overrides, and
+ * optionally a flag to enable signing of the UO via the underlying middleware
+ * @returns a Promise containing the built user operation
+ */
+export async function buildUserOperationFromTxs<
+  TTransport extends Transport = Transport,
+  TChain extends Chain | undefined = Chain | undefined,
+  TAccount extends SmartContractAccount | undefined =
+    | SmartContractAccount
+    | undefined,
+  TEntryPointVersion extends GetEntryPointFromAccount<TAccount> = GetEntryPointFromAccount<TAccount>,
+  TContext extends UserOperationContext | undefined =
+    | UserOperationContext
+    | undefined
+>(
+  client: Client<TTransport, TChain, TAccount>,
+  args: BuildTransactionParameters<TAccount, TContext, TEntryPointVersion>
+): Promise<BuildUserOperationFromTransactionsResult<TEntryPointVersion>> {
+  const { account = client.account, requests, overrides, context } = args;
+  if (!account) {
+    throw new AccountNotFoundError();
+  }
+
+  if (!isBaseSmartAccountClient(client)) {
+    throw new IncompatibleClientError(
+      "BaseSmartAccountClient",
+      "buildUserOperationFromTxs",
+      client
+    );
+  }
+
+  const batch = requests.map((request) => {
+    if (!request.to) {
+      throw new TransactionMissingToParamError();
+    }
+
+    return {
+      target: request.to,
+      data: request.data ?? "0x",
+      value: request.value ? fromHex(request.value, "bigint") : 0n,
+    };
+  });
+
+  const mfpgOverridesInTx = () =>
+    requests
+      .filter((x) => x.maxFeePerGas != null)
+      .map((x) => fromHex(x.maxFeePerGas!, "bigint"));
+  const maxFeePerGas =
+    overrides?.maxFeePerGas != null
+      ? overrides?.maxFeePerGas
+      : mfpgOverridesInTx().length > 0
+      ? bigIntMax(...mfpgOverridesInTx())
+      : undefined;
+
+  const mpfpgOverridesInTx = () =>
+    requests
+      .filter((x) => x.maxPriorityFeePerGas != null)
+      .map((x) => fromHex(x.maxPriorityFeePerGas!, "bigint"));
+  const maxPriorityFeePerGas =
+    overrides?.maxPriorityFeePerGas != null
+      ? overrides?.maxPriorityFeePerGas
+      : mpfpgOverridesInTx().length > 0
+      ? bigIntMax(...mpfpgOverridesInTx())
+      : undefined;
+
+  const _overrides = {
+    maxFeePerGas,
+    maxPriorityFeePerGas,
+  } as UserOperationOverrides<TEntryPointVersion>;
+
+  const uoStruct = await buildUserOperation(client, {
+    uo: batch,
+    account,
+    context,
+    overrides: _overrides,
+  });
+
+  return {
+    uoStruct,
+    // TODO: in v4 major version update, remove these as below parameters are not needed
+    batch,
+    overrides: _overrides,
+  };
+}

package/src/actions/smartAccount/checkGasSponsorshipEligibility.ts

@@ -0,0 +1,86 @@
+import type { Chain, Client, Transport } from "viem";
+import type { SmartContractAccount } from "../../account/smartContractAccount.js";
+import { isBaseSmartAccountClient } from "../../client/isSmartAccountClient.js";
+import { AccountNotFoundError } from "../../errors/account.js";
+import { IncompatibleClientError } from "../../errors/client.js";
+import type { UserOperationStruct } from "../../types.js";
+import { buildUserOperation } from "./buildUserOperation.js";
+import type {
+  SendUserOperationParameters,
+  UserOperationContext,
+} from "./types";
+
+/**
+ * This function verifies the eligibility of the connected account for gas sponsorship concerning the upcoming `UserOperation` (UO) that is intended to be sent.
+ * Internally, this method invokes [`buildUserOperation`](./buildUserOperation.md), which navigates through the middleware pipeline, including the `PaymasterMiddleware`. Its purpose is to construct the UO struct meant for transmission to the bundler. Following the construction of the UO struct, this function verifies if the resulting structure contains a non-empty `paymasterAndData` field.
+ * You can utilize this method before sending the user operation to confirm its eligibility for gas sponsorship. Depending on the outcome, it allows you to tailor the user experience accordingly, based on eligibility.
+ *
+ * @example
+ * ```ts
+ * import { smartAccountClient } from "./smartAccountClient";
+// [!code focus:99]
+const eligible = await smartAccountClient.checkGasSponsorshipEligibility({
+  uo: {
+    data: "0xCalldata",
+    target: "0xTarget",
+    value: 0n,
+  },
+});
+ 
+console.log(
+  `User Operation is ${
+    eligible ? "eligible" : "ineligible"
+  } for gas sponsorship.`
+);
+ * ```
+ * 
+ * @param client the smart account client to use for making RPC calls
+ * @param args {@link SendUserOperationParameters} containing the user operation, account, context, and overrides
+ * @returns a Promise containing a boolean indicating if the account is elgibile for sponsorship
+ */
+export function checkGasSponsorshipEligibility<
+  TTransport extends Transport = Transport,
+  TChain extends Chain | undefined = Chain | undefined,
+  TAccount extends SmartContractAccount | undefined =
+    | SmartContractAccount
+    | undefined,
+  TContext extends UserOperationContext | undefined =
+    | UserOperationContext
+    | undefined
+>(
+  client: Client<TTransport, TChain, TAccount>,
+  args: SendUserOperationParameters<TAccount, TContext>
+): Promise<boolean> {
+  const { account = client.account, overrides, context } = args;
+
+  if (!account) {
+    throw new AccountNotFoundError();
+  }
+
+  if (!isBaseSmartAccountClient(client)) {
+    throw new IncompatibleClientError(
+      "BaseSmartAccountClient",
+      "checkGasSponsorshipEligibility",
+      client
+    );
+  }
+
+  return buildUserOperation(client, {
+    uo: args.uo,
+    account,
+    overrides,
+    context,
+  })
+    .then((userOperationStruct) =>
+      account.getEntryPoint().version === "0.6.0"
+        ? (userOperationStruct as UserOperationStruct<"0.6.0">)
+            .paymasterAndData !== "0x" &&
+          (userOperationStruct as UserOperationStruct<"0.6.0">)
+            .paymasterAndData !== null
+        : (userOperationStruct as UserOperationStruct<"0.7.0">)
+            .paymasterData !== "0x" &&
+          (userOperationStruct as UserOperationStruct<"0.7.0">)
+            .paymasterData !== null
+    )
+    .catch(() => false);
+}

package/src/actions/smartAccount/dropAndReplaceUserOperation.ts

@@ -0,0 +1,111 @@
+import type { Chain, Client, Transport } from "viem";
+import type {
+  GetEntryPointFromAccount,
+  SmartContractAccount,
+} from "../../account/smartContractAccount";
+import { isBaseSmartAccountClient } from "../../client/isSmartAccountClient.js";
+import type { SendUserOperationResult } from "../../client/types";
+import { AccountNotFoundError } from "../../errors/account.js";
+import { IncompatibleClientError } from "../../errors/client.js";
+import type {
+  UserOperationOverrides,
+  UserOperationRequest,
+  UserOperationStruct,
+} from "../../types";
+import { bigIntMax, bigIntMultiply } from "../../utils/index.js";
+import { _runMiddlewareStack } from "./internal/runMiddlewareStack.js";
+import { _sendUserOperation } from "./internal/sendUserOperation.js";
+import type {
+  DropAndReplaceUserOperationParameters,
+  UserOperationContext,
+} from "./types";
+
+export async function dropAndReplaceUserOperation<
+  TTransport extends Transport = Transport,
+  TChain extends Chain | undefined = Chain | undefined,
+  TAccount extends SmartContractAccount | undefined =
+    | SmartContractAccount
+    | undefined,
+  TContext extends UserOperationContext | undefined =
+    | UserOperationContext
+    | undefined,
+  TEntryPointVersion extends GetEntryPointFromAccount<TAccount> = GetEntryPointFromAccount<TAccount>
+>(
+  client: Client<TTransport, TChain, TAccount>,
+  args: DropAndReplaceUserOperationParameters<TAccount, TContext>
+): Promise<SendUserOperationResult<TEntryPointVersion>> {
+  const { account = client.account, uoToDrop, overrides, context } = args;
+  if (!account) {
+    throw new AccountNotFoundError();
+  }
+  if (!isBaseSmartAccountClient(client)) {
+    throw new IncompatibleClientError(
+      "BaseSmartAccountClient",
+      "dropAndReplaceUserOperation",
+      client
+    );
+  }
+
+  const entryPoint = account.getEntryPoint();
+
+  const uoToSubmit = (
+    entryPoint.version === "0.6.0"
+      ? {
+          initCode: (uoToDrop as UserOperationRequest<"0.6.0">).initCode,
+          sender: (uoToDrop as UserOperationRequest<"0.6.0">).sender,
+          nonce: (uoToDrop as UserOperationRequest<"0.6.0">).nonce,
+          callData: (uoToDrop as UserOperationRequest<"0.6.0">).callData,
+          signature: await account.getDummySignature(),
+        }
+      : {
+          ...((uoToDrop as UserOperationRequest<"0.7.0">).factory &&
+          (uoToDrop as UserOperationRequest<"0.7.0">).factoryData
+            ? {
+                factory: (uoToDrop as UserOperationRequest<"0.7.0">).factory,
+                factoryData: (uoToDrop as UserOperationRequest<"0.7.0">)
+                  .factoryData,
+              }
+            : {}),
+          sender: (uoToDrop as UserOperationRequest<"0.7.0">).sender,
+          nonce: (uoToDrop as UserOperationRequest<"0.7.0">).nonce,
+          callData: (uoToDrop as UserOperationRequest<"0.7.0">).callData,
+          signature: await account.getDummySignature(),
+        }
+  ) as UserOperationStruct<TEntryPointVersion>;
+
+  // Run once to get the fee estimates
+  // This can happen at any part of the middleware stack, so we want to run it all
+  const { maxFeePerGas, maxPriorityFeePerGas } = await _runMiddlewareStack(
+    client,
+    {
+      uo: uoToSubmit,
+      overrides,
+      account,
+    }
+  );
+
+  const _overrides = {
+    ...overrides,
+    maxFeePerGas: bigIntMax(
+      BigInt(maxFeePerGas ?? 0n),
+      bigIntMultiply(uoToDrop.maxFeePerGas, 1.1)
+    ),
+    maxPriorityFeePerGas: bigIntMax(
+      BigInt(maxPriorityFeePerGas ?? 0n),
+      bigIntMultiply(uoToDrop.maxPriorityFeePerGas, 1.1)
+    ),
+  } as UserOperationOverrides<TEntryPointVersion>;
+
+  const uoToSend = await _runMiddlewareStack(client, {
+    uo: uoToSubmit,
+    overrides: _overrides,
+    account,
+  });
+
+  return _sendUserOperation(client, {
+    uoStruct: uoToSend,
+    account,
+    context,
+    overrides: _overrides,
+  });
+}

package/src/actions/smartAccount/estimateUserOperationGas.ts

@@ -0,0 +1,65 @@
+import type { Chain, Client, Transport } from "viem";
+import {
+  type GetEntryPointFromAccount,
+  type SmartContractAccount,
+} from "../../account/smartContractAccount.js";
+import { isBaseSmartAccountClient } from "../../client/isSmartAccountClient.js";
+import { AccountNotFoundError } from "../../errors/account.js";
+import { IncompatibleClientError } from "../../errors/client.js";
+import type { UserOperationEstimateGasResponse } from "../../types.js";
+import { deepHexlify, resolveProperties } from "../../utils/index.js";
+import { _initUserOperation } from "./internal/initUserOperation.js";
+import type {
+  SendUserOperationParameters,
+  UserOperationContext,
+} from "./types.js";
+
+/**
+ * Description SmartAccountClientAction for estimating the gas cost of a user operation
+ *
+ * @async
+ * @template {Transport} TTransport
+ * @template {Chain | undefined} TChain
+ * @template {SmartContractAccount | undefined} TAccount
+ * @template {UserOperationContext | undefined} TContext
+ * @template {GetEntryPointFromAccount<TAccount>} TEntryPointVersion
+ * @param client smart account client
+ * @param args send user operation parameters
+ * @returns user operation gas estimate response
+ */
+export async function estimateUserOperationGas<
+  TTransport extends Transport = Transport,
+  TChain extends Chain | undefined = Chain | undefined,
+  TAccount extends SmartContractAccount | undefined =
+    | SmartContractAccount
+    | undefined,
+  TContext extends UserOperationContext | undefined =
+    | UserOperationContext
+    | undefined,
+  TEntryPointVersion extends GetEntryPointFromAccount<TAccount> = GetEntryPointFromAccount<TAccount>
+>(
+  client: Client<TTransport, TChain, TAccount>,
+  args: SendUserOperationParameters<TAccount, TContext>
+): Promise<UserOperationEstimateGasResponse<TEntryPointVersion>> {
+  const { account = client.account, overrides } = args;
+  if (!account) {
+    throw new AccountNotFoundError();
+  }
+
+  if (!isBaseSmartAccountClient(client)) {
+    throw new IncompatibleClientError(
+      "BaseSmartAccountClient",
+      "estimateUserOperationGas",
+      client
+    );
+  }
+
+  return _initUserOperation(client, args).then(async (struct) => {
+    const request = deepHexlify(await resolveProperties(struct));
+    return client.estimateUserOperationGas(
+      request,
+      account.getEntryPoint().address,
+      overrides?.stateOverride
+    );
+  });
+}

package/src/actions/smartAccount/getAddress.ts

@@ -0,0 +1,25 @@
+import type { Address } from "abitype";
+import type { Chain, Client, Transport } from "viem";
+import type {
+  GetAccountParameter,
+  SmartContractAccount,
+} from "../../account/smartContractAccount";
+import { AccountNotFoundError } from "../../errors/account.js";
+
+export const getAddress: <
+  TTransport extends Transport = Transport,
+  TChain extends Chain | undefined = Chain | undefined,
+  TAccount extends SmartContractAccount | undefined =
+    | SmartContractAccount
+    | undefined
+>(
+  client: Client<TTransport, TChain, TAccount>,
+  args: GetAccountParameter<TAccount>
+) => Address = (client, args) => {
+  const { account } = args ?? { account: client.account };
+  if (!account) {
+    throw new AccountNotFoundError();
+  }
+
+  return account.address;
+};