viem 2.17.10 → 2.18.0

package/account-abstraction/actions/bundler/sendUserOperation.ts

@@ -0,0 +1,149 @@
+import type { Address, Narrow } from 'abitype'
+import { parseAccount } from '../../../accounts/utils/parseAccount.js'
+import type { Client } from '../../../clients/createClient.js'
+import type { Transport } from '../../../clients/transports/createTransport.js'
+import { AccountNotFoundError } from '../../../errors/account.js'
+import type { BaseError } from '../../../errors/base.js'
+import type { ErrorType } from '../../../errors/utils.js'
+import type { Chain } from '../../../types/chain.js'
+import type { Hex } from '../../../types/misc.js'
+import type { Assign, OneOf } from '../../../types/utils.js'
+import type { RequestErrorType } from '../../../utils/buildRequest.js'
+import { getAction } from '../../../utils/getAction.js'
+import type { SmartAccount } from '../../accounts/types.js'
+import type { PaymasterActions } from '../../clients/decorators/paymaster.js'
+import type {
+  DeriveSmartAccount,
+  GetSmartAccountParameter,
+} from '../../types/account.js'
+import type {
+  DeriveEntryPointVersion,
+  EntryPointVersion,
+} from '../../types/entryPointVersion.js'
+import type {
+  UserOperation,
+  UserOperationCalls,
+  UserOperationRequest,
+} from '../../types/userOperation.js'
+import { getUserOperationError } from '../../utils/errors/getUserOperationError.js'
+import {
+  type FormatUserOperationRequestErrorType,
+  formatUserOperationRequest,
+} from '../../utils/formatters/userOperationRequest.js'
+import {
+  type PrepareUserOperationErrorType,
+  type PrepareUserOperationParameters,
+  prepareUserOperation,
+} from './prepareUserOperation.js'
+
+export type SendUserOperationParameters<
+  account extends SmartAccount | undefined = SmartAccount | undefined,
+  accountOverride extends SmartAccount | undefined = SmartAccount | undefined,
+  calls extends readonly unknown[] = readonly unknown[],
+  //
+  _derivedAccount extends SmartAccount | undefined = DeriveSmartAccount<
+    account,
+    accountOverride
+  >,
+  _derivedVersion extends
+    EntryPointVersion = DeriveEntryPointVersion<_derivedAccount>,
+> = Assign<
+  UserOperationRequest<_derivedVersion>,
+  OneOf<{ calls: UserOperationCalls<Narrow<calls>> } | { callData: Hex }> & {
+    paymaster?:
+      | Address
+      | true
+      | {
+          /** Retrieves paymaster-related User Operation properties to be used for sending the User Operation. */
+          getPaymasterData?: PaymasterActions['getPaymasterData'] | undefined
+          /** Retrieves paymaster-related User Operation properties to be used for gas estimation. */
+          getPaymasterStubData?:
+            | PaymasterActions['getPaymasterStubData']
+            | undefined
+        }
+      | undefined
+    /** Paymaster context to pass to `getPaymasterData` and `getPaymasterStubData` calls. */
+    paymasterContext?: unknown
+  }
+> &
+  GetSmartAccountParameter<account, accountOverride>
+
+export type SendUserOperationReturnType = Hex
+
+export type SendUserOperationErrorType =
+  | FormatUserOperationRequestErrorType
+  | PrepareUserOperationErrorType
+  | RequestErrorType
+  | ErrorType
+
+/**
+ * Broadcasts a User Operation to the Bundler.
+ *
+ * - Docs: https://viem.sh/actions/bundler/sendUserOperation
+ *
+ * @param client - Client to use
+ * @param parameters - {@link SendUserOperationParameters}
+ * @returns The User Operation hash. {@link SendUserOperationReturnType}
+ *
+ * @example
+ * import { createBundlerClient, http, parseEther } from 'viem'
+ * import { mainnet } from 'viem/chains'
+ * import { toSmartAccount } from 'viem/accounts'
+ * import { sendUserOperation } from 'viem/actions'
+ *
+ * const account = await toSmartAccount({ ... })
+ *
+ * const bundlerClient = createBundlerClient({
+ *   chain: mainnet,
+ *   transport: http(),
+ * })
+ *
+ * const values = await sendUserOperation(bundlerClient, {
+ *   account,
+ *   calls: [{ to: '0x...', value: parseEther('1') }],
+ * })
+ */
+export async function sendUserOperation<
+  const calls extends readonly unknown[],
+  account extends SmartAccount | undefined,
+  accountOverride extends SmartAccount | undefined = undefined,
+>(
+  client: Client<Transport, Chain | undefined, account>,
+  parameters: SendUserOperationParameters<account, accountOverride, calls>,
+) {
+  const { account: account_ = client.account } = parameters
+
+  if (!account_) throw new AccountNotFoundError()
+  const account = parseAccount(account_)
+
+  const request = await getAction(
+    client,
+    prepareUserOperation,
+    'prepareUserOperation',
+  )(parameters as unknown as PrepareUserOperationParameters)
+
+  const signature =
+    parameters.signature ||
+    (await account.signUserOperation(request as UserOperation))
+
+  const rpcParameters = formatUserOperationRequest({
+    ...request,
+    signature,
+  } as UserOperation)
+
+  try {
+    return await client.request(
+      {
+        method: 'eth_sendUserOperation',
+        params: [rpcParameters, account.entryPoint.address],
+      },
+      { retryCount: 0 },
+    )
+  } catch (error) {
+    throw getUserOperationError(error as BaseError, {
+      ...(request as UserOperation),
+      calls: parameters.calls,
+      signature,
+    })
+  }
+}

package/account-abstraction/actions/bundler/waitForUserOperationReceipt.ts

@@ -0,0 +1,139 @@
+import type { Client } from '../../../clients/createClient.js'
+import type { Transport } from '../../../clients/transports/createTransport.js'
+import type { ErrorType } from '../../../errors/utils.js'
+import type { Hash } from '../../../types/misc.js'
+import type { Prettify } from '../../../types/utils.js'
+import { getAction } from '../../../utils/getAction.js'
+import { type ObserveErrorType, observe } from '../../../utils/observe.js'
+import { type PollErrorType, poll } from '../../../utils/poll.js'
+import { stringify } from '../../../utils/stringify.js'
+import {
+  WaitForUserOperationReceiptTimeoutError,
+  type WaitForUserOperationReceiptTimeoutErrorType,
+} from '../../errors/userOperation.js'
+import type { UserOperationReceipt } from '../../types/userOperation.js'
+import {
+  type GetUserOperationReceiptErrorType,
+  getUserOperationReceipt,
+} from './getUserOperationReceipt.js'
+
+export type WaitForUserOperationReceiptParameters = {
+  /** The hash of the User Operation. */
+  hash: Hash
+  /**
+   * Polling frequency (in ms). Defaults to the client's pollingInterval config.
+   * @default client.pollingInterval
+   */
+  pollingInterval?: number | undefined
+  /**
+   * The number of times to retry.
+   * @default 6
+   */
+  retryCount?: number | undefined
+  /** Optional timeout (in ms) to wait before stopping polling. */
+  timeout?: number | undefined
+}
+
+export type WaitForUserOperationReceiptReturnType =
+  Prettify<UserOperationReceipt>
+
+export type WaitForUserOperationReceiptErrorType =
+  | WaitForUserOperationReceiptTimeoutErrorType
+  | PollErrorType
+  | ObserveErrorType
+  | ErrorType
+
+/**
+ * Waits for the User Operation to be included on a [Block](https://viem.sh/docs/glossary/terms#block) (one confirmation), and then returns the User Operation receipt.
+ *
+ * - Docs: https://viem.sh/docs/actions/bundler/waitForUserOperationReceipt
+ *
+ * @param client - Client to use
+ * @param parameters - {@link WaitForUserOperationReceiptParameters}
+ * @returns The receipt. {@link WaitForUserOperationReceiptReturnType}
+ *
+ * @example
+ * import { createBundlerClient, http } from 'viem'
+ * import { mainnet } from 'viem/chains'
+ * import { waitForUserOperationReceipt } from 'viem/actions'
+ *
+ * const client = createBundlerClient({
+ *   chain: mainnet,
+ *   transport: http(),
+ * })
+ *
+ * const receipt = await waitForUserOperationReceipt(client, {
+ *   hash: '0x4ca7ee652d57678f26e887c149ab0735f41de37bcad58c9f6d3ed5824f15b74d',
+ * })
+ */
+export function waitForUserOperationReceipt(
+  client: Client<Transport>,
+  parameters: WaitForUserOperationReceiptParameters,
+): Promise<WaitForUserOperationReceiptReturnType> {
+  const {
+    hash,
+    pollingInterval = client.pollingInterval,
+    retryCount,
+    timeout = 120_000,
+  } = parameters
+
+  let count = 0
+  const observerId = stringify([
+    'waitForUserOperationReceipt',
+    client.uid,
+    hash,
+  ])
+
+  return new Promise((resolve, reject) => {
+    const unobserve = observe(observerId, { resolve, reject }, (emit) => {
+      const done = (fn: () => void) => {
+        unpoll()
+        fn()
+        unobserve()
+      }
+
+      const unpoll = poll(
+        async () => {
+          if (retryCount && count >= retryCount)
+            done(() =>
+              emit.reject(
+                new WaitForUserOperationReceiptTimeoutError({ hash }),
+              ),
+            )
+
+          try {
+            const receipt = await getAction(
+              client,
+              getUserOperationReceipt,
+              'getUserOperationReceipt',
+            )({ hash })
+            done(() => emit.resolve(receipt))
+          } catch (err) {
+            const error = err as GetUserOperationReceiptErrorType
+            if (error.name !== 'UserOperationReceiptNotFoundError')
+              done(() => emit.reject(error))
+          }
+
+          count++
+        },
+        {
+          emitOnBegin: true,
+          interval: pollingInterval,
+        },
+      )
+
+      if (timeout)
+        setTimeout(
+          () =>
+            done(() =>
+              emit.reject(
+                new WaitForUserOperationReceiptTimeoutError({ hash }),
+              ),
+            ),
+          timeout,
+        )
+
+      return unpoll
+    })
+  })
+}

package/account-abstraction/actions/paymaster/getPaymasterData.ts

@@ -0,0 +1,135 @@
+import type { Address } from 'abitype'
+import type { Client } from '../../../clients/createClient.js'
+import type { Transport } from '../../../clients/transports/createTransport.js'
+import type { ErrorType } from '../../../errors/utils.js'
+import type { Hex } from '../../../types/misc.js'
+import type { OneOf, PartialBy, Prettify } from '../../../types/utils.js'
+import { hexToBigInt } from '../../../utils/encoding/fromHex.js'
+import { numberToHex } from '../../../utils/encoding/toHex.js'
+import type { UserOperation } from '../../types/userOperation.js'
+import {
+  type FormatUserOperationRequestErrorType,
+  formatUserOperationRequest,
+} from '../../utils/formatters/userOperationRequest.js'
+
+export type GetPaymasterDataParameters = OneOf<
+  | PartialBy<
+      Pick<
+        UserOperation<'0.6'>,
+        | 'callData'
+        | 'callGasLimit'
+        | 'initCode'
+        | 'maxFeePerGas'
+        | 'maxPriorityFeePerGas'
+        | 'nonce'
+        | 'sender'
+        | 'preVerificationGas'
+        | 'verificationGasLimit'
+      >,
+      | 'callGasLimit'
+      | 'initCode'
+      | 'maxFeePerGas'
+      | 'maxPriorityFeePerGas'
+      | 'preVerificationGas'
+      | 'verificationGasLimit'
+    >
+  | PartialBy<
+      Pick<
+        UserOperation<'0.7'>,
+        | 'callData'
+        | 'callGasLimit'
+        | 'factory'
+        | 'factoryData'
+        | 'maxFeePerGas'
+        | 'maxPriorityFeePerGas'
+        | 'nonce'
+        | 'sender'
+        | 'preVerificationGas'
+        | 'verificationGasLimit'
+      >,
+      | 'callGasLimit'
+      | 'factory'
+      | 'factoryData'
+      | 'maxFeePerGas'
+      | 'maxPriorityFeePerGas'
+      | 'preVerificationGas'
+      | 'verificationGasLimit'
+    >
+> & {
+  context?: unknown | undefined
+  chainId: number
+  entryPointAddress: Address
+}
+
+export type GetPaymasterDataReturnType = Prettify<
+  OneOf<
+    | { paymasterAndData: Hex }
+    | {
+        paymaster: Address
+        paymasterData: Hex
+        paymasterVerificationGasLimit: bigint
+        paymasterPostOpGasLimit: bigint
+      }
+  >
+>
+
+export type GetPaymasterDataErrorType =
+  | FormatUserOperationRequestErrorType
+  | ErrorType
+
+/**
+ * Retrieves paymaster-related User Operation properties to be used for sending the User Operation.
+ *
+ * - Docs: https://viem.sh/account-abstraction/actions/paymaster/getPaymasterData
+ *
+ * @param client - Client to use
+ * @param parameters - {@link GetPaymasterDataParameters}
+ * @returns Paymaster-related User Operation properties. {@link GetPaymasterDataReturnType}
+ *
+ * @example
+ * import { http } from 'viem'
+ * import { createPaymasterClient, getPaymasterData } from 'viem/account-abstraction'
+ *
+ * const paymasterClient = createPaymasterClient({
+ *   transport: http('https://...'),
+ * })
+ *
+ * const userOperation = { ... }
+ *
+ * const values = await getPaymasterData(paymasterClient, {
+ *   chainId: 1,
+ *   entryPointAddress: '0x...',
+ *   ...userOperation,
+ * })
+ */
+export async function getPaymasterData(
+  client: Client<Transport>,
+  parameters: GetPaymasterDataParameters,
+): Promise<GetPaymasterDataReturnType> {
+  const { chainId, entryPointAddress, context, ...userOperation } = parameters
+  const request = formatUserOperationRequest(userOperation)
+  const { paymasterPostOpGasLimit, paymasterVerificationGasLimit, ...rest } =
+    await client.request({
+      method: 'pm_getPaymasterData',
+      params: [
+        {
+          ...request,
+          callGasLimit: request.callGasLimit ?? '0x0',
+          verificationGasLimit: request.verificationGasLimit ?? '0x0',
+          preVerificationGas: request.preVerificationGas ?? '0x0',
+        },
+        entryPointAddress,
+        numberToHex(chainId),
+        context,
+      ],
+    })
+  return {
+    ...rest,
+    ...(paymasterPostOpGasLimit && {
+      paymasterPostOpGasLimit: hexToBigInt(paymasterPostOpGasLimit),
+    }),
+    ...(paymasterVerificationGasLimit && {
+      paymasterVerificationGasLimit: hexToBigInt(paymasterVerificationGasLimit),
+    }),
+  } as unknown as GetPaymasterDataReturnType
+}

package/account-abstraction/actions/paymaster/getPaymasterStubData.ts

@@ -0,0 +1,138 @@
+import type { Address } from 'abitype'
+import type { Client } from '../../../clients/createClient.js'
+import type { Transport } from '../../../clients/transports/createTransport.js'
+import type { ErrorType } from '../../../errors/utils.js'
+import type { Hex } from '../../../types/misc.js'
+import type { OneOf, PartialBy, Prettify } from '../../../types/utils.js'
+import { hexToBigInt } from '../../../utils/encoding/fromHex.js'
+import { numberToHex } from '../../../utils/encoding/toHex.js'
+import type { UserOperation } from '../../types/userOperation.js'
+import {
+  type FormatUserOperationRequestErrorType,
+  formatUserOperationRequest,
+} from '../../utils/formatters/userOperationRequest.js'
+
+export type GetPaymasterStubDataParameters = OneOf<
+  | PartialBy<
+      Pick<
+        UserOperation<'0.6'>,
+        | 'callData'
+        | 'callGasLimit'
+        | 'initCode'
+        | 'maxFeePerGas'
+        | 'maxPriorityFeePerGas'
+        | 'nonce'
+        | 'sender'
+        | 'preVerificationGas'
+        | 'verificationGasLimit'
+      >,
+      | 'callGasLimit'
+      | 'initCode'
+      | 'maxFeePerGas'
+      | 'maxPriorityFeePerGas'
+      | 'preVerificationGas'
+      | 'verificationGasLimit'
+    >
+  | PartialBy<
+      Pick<
+        UserOperation<'0.7'>,
+        | 'callData'
+        | 'callGasLimit'
+        | 'factory'
+        | 'factoryData'
+        | 'maxFeePerGas'
+        | 'maxPriorityFeePerGas'
+        | 'nonce'
+        | 'sender'
+        | 'preVerificationGas'
+        | 'verificationGasLimit'
+      >,
+      | 'callGasLimit'
+      | 'factory'
+      | 'factoryData'
+      | 'maxFeePerGas'
+      | 'maxPriorityFeePerGas'
+      | 'preVerificationGas'
+      | 'verificationGasLimit'
+    >
+> & {
+  context?: unknown | undefined
+  chainId: number
+  entryPointAddress: Address
+}
+
+export type GetPaymasterStubDataReturnType = Prettify<
+  OneOf<
+    | { paymasterAndData: Hex }
+    | {
+        paymaster: Address
+        paymasterData: Hex
+        paymasterVerificationGasLimit: bigint
+        paymasterPostOpGasLimit: bigint
+      }
+  > & {
+    sponsor?: { name: string; icon?: string | undefined } | undefined
+    isFinal?: boolean | undefined
+  }
+>
+
+export type GetPaymasterStubDataErrorType =
+  | FormatUserOperationRequestErrorType
+  | ErrorType
+
+/**
+ * Retrieves paymaster-related User Operation properties to be used for gas estimation.
+ *
+ * - Docs: https://viem.sh/account-abstraction/actions/paymaster/getPaymasterStubData
+ *
+ * @param client - Client to use
+ * @param parameters - {@link GetPaymasterStubDataParameters}
+ * @returns Paymaster-related User Operation properties. {@link GetPaymasterStubDataReturnType}
+ *
+ * @example
+ * import { http } from 'viem'
+ * import { createPaymasterClient, getPaymasterStubData } from 'viem/account-abstraction'
+ *
+ * const paymasterClient = createPaymasterClient({
+ *   transport: http('https://...'),
+ * })
+ *
+ * const userOperation = { ... }
+ *
+ * const values = await getPaymasterStubData(paymasterClient, {
+ *   chainId: 1,
+ *   entryPointAddress: '0x...',
+ *   ...userOperation,
+ * })
+ */
+export async function getPaymasterStubData(
+  client: Client<Transport>,
+  parameters: GetPaymasterStubDataParameters,
+): Promise<GetPaymasterStubDataReturnType> {
+  const { chainId, entryPointAddress, context, ...userOperation } = parameters
+  const request = formatUserOperationRequest(userOperation)
+  const { paymasterPostOpGasLimit, paymasterVerificationGasLimit, ...rest } =
+    await client.request({
+      method: 'pm_getPaymasterStubData',
+      params: [
+        {
+          ...request,
+          callGasLimit: request.callGasLimit ?? '0x0',
+          verificationGasLimit: request.verificationGasLimit ?? '0x0',
+          preVerificationGas: request.preVerificationGas ?? '0x0',
+        },
+        entryPointAddress,
+        numberToHex(chainId),
+        context,
+      ],
+    })
+  return {
+    ...rest,
+    ...(paymasterPostOpGasLimit && {
+      paymasterPostOpGasLimit: hexToBigInt(paymasterPostOpGasLimit),
+    }),
+    ...(paymasterVerificationGasLimit && {
+      paymasterVerificationGasLimit: hexToBigInt(paymasterVerificationGasLimit),
+    }),
+  } as unknown as GetPaymasterStubDataReturnType
+}