permissionless 0.0.31 → 0.0.32

package/actions/bundler/sendUserOperation.ts

@@ -1,4 +1,12 @@
-import type { Account, Address, Chain, Client, Hash, Transport } from "viem"
+import type {
+    Account,
+    Address,
+    BaseError,
+    Chain,
+    Client,
+    Hash,
+    Transport
+} from "viem"
 import type { BundlerClient } from "../../clients/createBundlerClient.js"
 import type { BundlerRpcSchema } from "../../types/bundler.js"
 import type { Prettify } from "../../types/index.js"
@@ -7,6 +15,7 @@ import type {
     UserOperationWithBigIntAsHex
 } from "../../types/userOperation.js"
 import { deepHexlify } from "../../utils/deepHexlify.js"
+import { getSendUserOperationError } from "../../utils/errors/getSendUserOperationError.js"
 
 export type SendUserOperationParameters = {
     userOperation: UserOperation
@@ -48,11 +57,20 @@ export const sendUserOperation = async <
 ): Promise<Hash> => {
     const { userOperation, entryPoint } = args
 
-    return client.request({
-        method: "eth_sendUserOperation",
-        params: [
-            deepHexlify(userOperation) as UserOperationWithBigIntAsHex,
-            entryPoint as Address
-        ]
-    })
+    try {
+        const userOperationHash = await client.request({
+            method: "eth_sendUserOperation",
+            params: [
+                deepHexlify(userOperation) as UserOperationWithBigIntAsHex,
+                entryPoint as Address
+            ]
+        })
+
+        return userOperationHash
+    } catch (err) {
+        throw getSendUserOperationError(
+            err as BaseError,
+            args as SendUserOperationParameters
+        )
+    }
 }

package/actions/index.ts

@@ -1,4 +1,5 @@
 import type {
+    EstimateUserOperationErrorType,
     EstimateUserOperationGasParameters,
     EstimateUserOperationGasReturnType
 } from "./bundler/estimateUserOperationGas.js"
@@ -40,7 +41,8 @@ export type {
     GetUserOperationReceiptReturnType,
     GetSenderAddressParams,
     GetAccountNonceParams,
-    WaitForUserOperationReceiptParameters
+    WaitForUserOperationReceiptParameters,
+    EstimateUserOperationErrorType
 }
 
 export {

package/errors/account.ts

@@ -0,0 +1,345 @@
+import { type Address, BaseError } from "viem"
+
+export type SenderAlreadyDeployedErrorType = SenderAlreadyDeployedError & {
+    name: "SenderAlreadyDeployedError"
+}
+export class SenderAlreadyDeployedError extends BaseError {
+    static message = /aa10/
+    override name = "SenderAlreadyDeployedError" as const
+    constructor({
+        cause,
+        sender,
+        docsPath
+    }: { cause?: BaseError; sender?: Address; docsPath?: string } = {}) {
+        super(
+            [
+                `Smart account ${sender} is already deployed.`,
+                "",
+                "Possible solutions:",
+                `• Remove the initCode from the user operation and set it to "0x"`,
+                "",
+                docsPath ? `Docs: ${docsPath}` : ""
+            ].join("\n"),
+            {
+                cause
+            }
+        )
+    }
+}
+
+export type InitCodeRevertedErrorType = InitCodeRevertedError & {
+    name: "InitCodeRevertedError"
+}
+export class InitCodeRevertedError extends BaseError {
+    static message = /aa13/
+    override name = "InitCodeRevertedError" as const
+    constructor({
+        cause,
+        docsPath
+    }: { cause?: BaseError; docsPath?: string } = {}) {
+        super(
+            [
+                "EntryPoint failed to create the smart account with the initCode provided.",
+                "",
+                "Possible reasons:",
+                "• The initCode ran out of gas",
+                "• The initCode reverted during the account deployment process",
+                "",
+                "Possible solutions:",
+                "• Verify that the factory address in the initCode is correct (the factory address is the first 20 bytes of the initCode).",
+                "• Verify that the initCode is correct.",
+                "• Check whether the verificationGasLimit is sufficient for the initCode to complete without running out of gas.",
+                "",
+                docsPath ? `Docs: ${docsPath}` : ""
+            ].join("\n"),
+            {
+                cause
+            }
+        )
+    }
+}
+
+export type SenderAddressMismatchErrorType = SenderAddressMismatchError & {
+    name: "SenderAddressMismatchError"
+}
+export class SenderAddressMismatchError extends BaseError {
+    static message = /aa14/
+    override name = "SenderAddressMismatchError" as const
+    constructor({
+        cause,
+        sender,
+        docsPath
+    }: {
+        cause?: BaseError
+        sender: Address
+        docsPath?: string
+    }) {
+        super(
+            [
+                "The initCode returned a different smart account address than expected.",
+                `Expected: ${sender}`,
+                "",
+                "Possible reasons:",
+                "• Account deployed with the initCode provided does not match match the sender address provided",
+                "",
+                "Possible solutions:",
+                "• Verify that the sender address was generated deterministically from the initCode. (consider leveraging functions like getSenderAddress)",
+                "• Verify that the factory address in the initCode is correct (the factory address is the first 20 bytes of the initCode)",
+                "• Verify that the initCode is correct.",
+                "",
+                docsPath ? `Docs: ${docsPath}` : ""
+            ].join("\n"),
+            {
+                cause
+            }
+        )
+    }
+}
+
+export type InitCodeDidNotDeploySenderErrorType =
+    InitCodeDidNotDeploySenderError & {
+        name: "InitCodeDidNotDeploySenderError"
+    }
+export class InitCodeDidNotDeploySenderError extends BaseError {
+    static message = /aa15/
+    override name = "InitCodeDidNotDeploySenderError" as const
+    constructor({
+        cause,
+        sender,
+        docsPath
+    }: {
+        cause?: BaseError
+        sender: Address
+        docsPath?: string
+    }) {
+        super(
+            [
+                `The initCode did not deploy the sender at the address ${sender}.`,
+                "",
+                "Possible reasons:",
+                "• The initCode factory is not creating an account.",
+                "• The initCode factory is creating an account, but is not implemented correctly as it is not deploying at the sender address",
+                "",
+                "Possible solutions:",
+                "• Verify that the factory address in the initCode is correct (the factory address is the first 20 bytes of the initCode).",
+                "• Verify that the initCode factory is implemented correctly. The factory must deploy the smart account at the sender address.",
+                "",
+                docsPath ? `Docs: ${docsPath}` : ""
+            ].join("\n"),
+            {
+                cause
+            }
+        )
+    }
+}
+
+export type SenderNotDeployedErrorType = SenderNotDeployedError & {
+    name: "SenderNotDeployedError"
+}
+export class SenderNotDeployedError extends BaseError {
+    static message = /aa20/
+    override name = "SenderNotDeployedError" as const
+    constructor({
+        cause,
+        sender,
+        docsPath
+    }: {
+        cause?: BaseError
+        sender: Address
+        docsPath?: string
+    }) {
+        super(
+            [
+                `Smart account ${sender} is not deployed.`,
+                "",
+                "Possible reasons:",
+                "• An initCode was not specified, but the sender address (i.e. the smart account) is not deployed.",
+                "",
+                "Possible solutions:",
+                "• If this is the first transaction by this account, make sure the initCode is included in the user operation.",
+                "• If the smart account is already supposed to be deployed, verify that you have selected the correct sender address for the user operation.",
+                "",
+                docsPath ? `Docs: ${docsPath}` : ""
+            ].join("\n"),
+            {
+                cause
+            }
+        )
+    }
+}
+
+export type SmartAccountInsufficientFundsErrorType =
+    SmartAccountInsufficientFundsError & {
+        name: "SmartAccountInsufficientFundsError"
+    }
+export class SmartAccountInsufficientFundsError extends BaseError {
+    static message = /aa21/
+    override name = "SmartAccountInsufficientFundsError" as const
+    constructor({
+        cause,
+        sender,
+        docsPath
+    }: {
+        cause?: BaseError
+        sender: Address
+        docsPath?: string
+    }) {
+        super(
+            [
+                `You are not using a paymaster, and the ${sender} address did not have enough native tokens to cover the gas costs associated with the user operation.`,
+                "",
+                "Possible solutions:",
+                "• If you are not using a paymaster, verify that the sender address has enough native tokens to cover the required prefund. Consider leveraging functions like getRequiredPrefund.",
+                "• If you are looking to use a paymaster to cover the gas fees, verify that the paymasterAndData field is set.",
+                "",
+                docsPath ? `Docs: ${docsPath}` : ""
+            ].join("\n"),
+            {
+                cause
+            }
+        )
+    }
+}
+
+export type SmartAccountSignatureValidityPeriodErrorType =
+    SmartAccountSignatureValidityPeriodError & {
+        name: "SmartAccountSignatureValidityPeriodError"
+    }
+export class SmartAccountSignatureValidityPeriodError extends BaseError {
+    static message = /aa22/
+    override name = "SmartAccountSignatureValidityPeriodError" as const
+    constructor({
+        cause,
+        docsPath
+    }: {
+        cause?: BaseError
+        docsPath?: string
+    }) {
+        super(
+            [
+                "The signature used in the user operation is not valid, because it is outside of the time range it specified.",
+                "",
+                "Possible reasons:",
+                "• This error occurs when the block.timestamp falls after the validUntil timestamp, or before the validAfter timestamp.",
+                "",
+                "Possible solutions:",
+                "• If you are looking to use time-based signatures, verify that the validAfter and validUntil fields are set correctly and that the user operation is sent within the specified range.",
+                "• If you are not looking to use time-based signatures, verify that the validAfter and validUntil fields are set to 0.",
+                "",
+                docsPath ? `Docs: ${docsPath}` : ""
+            ].join("\n"),
+            {
+                cause
+            }
+        )
+    }
+}
+
+export type SmartAccountValidationRevertedErrorType =
+    SmartAccountValidationRevertedError & {
+        name: "SmartAccountValidationRevertedError"
+    }
+export class SmartAccountValidationRevertedError extends BaseError {
+    static message = /aa23/
+    override name = "SmartAccountValidationRevertedError" as const
+    constructor({
+        cause,
+        sender,
+        docsPath
+    }: {
+        cause?: BaseError
+        sender: Address
+        docsPath?: string
+    }) {
+        super(
+            [
+                `The smart account ${sender} reverted or ran out of gas during the validation of the user operation.`,
+                "",
+                "Possible solutions:",
+                "• Verify that the verificationGasLimit is high enough to cover the validateUserOp function's gas costs.",
+                "• Make sure validateUserOp returns uint(1) for invalid signatures, and MUST NOT REVERT when the signature is invalid",
+                "• If you are not using a paymaster, verify that the sender address has enough native tokens to cover the required pre fund. Consider leveraging functions like getRequiredPrefund.",
+                "• Verify that the validateUserOp function is implemented with the correct logic, and that the user operation is supposed to be valid.",
+                "",
+                docsPath ? `Docs: ${docsPath}` : ""
+            ].join("\n"),
+            {
+                cause
+            }
+        )
+    }
+}
+
+export type InvalidSmartAccountSignatureErrorType =
+    InvalidSmartAccountSignatureError & {
+        name: "InvalidSmartAccountSignatureError"
+    }
+export class InvalidSmartAccountSignatureError extends BaseError {
+    static message = /aa24/
+    override name = "InvalidSmartAccountSignatureError" as const
+    constructor({
+        cause,
+        sender,
+        docsPath
+    }: {
+        cause?: BaseError
+        sender: Address
+        docsPath?: string
+    }) {
+        super(
+            [
+                `The smart account ${sender} signature is invalid.`,
+                "",
+                "Possible solutions:",
+                "• Verify that the user operation was correctly signed, and that the signature was correctly encoded in the signature field of the user operation.",
+                "• Most smart account implementations sign over the userOpHash. Make sure that the userOpHash is correctly computed. Consider leveraging functions like getUserOperationHash.",
+                "• Make sure you have selected the correct chainId and entryPointAddress when computing the userOpHash.",
+                "• Make sure the smart account signature verification function is correctly implemented.",
+                "",
+                docsPath ? `Docs: ${docsPath}` : ""
+            ].join("\n"),
+            {
+                cause
+            }
+        )
+    }
+}
+
+export type InvalidSmartAccountNonceErrorType =
+    InvalidSmartAccountNonceError & {
+        name: "InvalidSmartAccountNonceError"
+    }
+export class InvalidSmartAccountNonceError extends BaseError {
+    static message = /aa25/
+    override name = "InvalidSmartAccountNonceError" as const
+    constructor({
+        cause,
+        sender,
+        nonce,
+        docsPath
+    }: {
+        cause?: BaseError
+        sender: Address
+        docsPath?: string
+        nonce: bigint
+    }) {
+        const nonceKey = nonce >> 64n // first 192 bits of nonce
+        const nonceSequence = nonce & 0xffffffffffffffffn // last 64 bits of nonce
+
+        super(
+            [
+                `The smart account ${sender} nonce is invalid.`,
+                `Nonce sent: ${nonce} (key: ${nonceKey}, sequence: ${nonceSequence})`,
+                "",
+                "Possible solutions:",
+                "• Verify that you are using the correct nonce for the user operation. The nonce should be the current nonce of the smart account for the selected key. Consider leveraging functions like getAccountNonce.",
+                "• Verify that the nonce is formatted correctly.",
+                "",
+                docsPath ? `Docs: ${docsPath}` : ""
+            ].join("\n"),
+            {
+                cause
+            }
+        )
+    }
+}

package/errors/bundler.ts

@@ -0,0 +1,62 @@
+import { BaseError } from "viem"
+
+export type InvalidBeneficiaryAddressErrorType =
+    InvalidBeneficiaryAddressError & {
+        name: "InvalidBeneficiaryAddressError"
+    }
+export class InvalidBeneficiaryAddressError extends BaseError {
+    static message = /aa9[01]/
+    override name = "InvalidBeneficiaryAddressError"
+    constructor({
+        cause,
+        docsPath
+    }: {
+        cause?: BaseError
+        docsPath?: string
+    }) {
+        super(
+            [
+                "The bundler did not set a beneficiary address when bundling the user operation.",
+                "",
+                "Possible solutions:",
+                "• If you encounter this error when running self-hosted bundler, make sure you have configured the bundler correctly.",
+                "• If you are using a bundler provider, reach out to them.",
+                "",
+                docsPath ? `Docs: ${docsPath}` : ""
+            ].join("\n"),
+            {
+                cause
+            }
+        )
+    }
+}
+
+export type InvalidAggregatorErrorType = InvalidAggregatorError & {
+    name: "InvalidAggregatorError"
+}
+export class InvalidAggregatorError extends BaseError {
+    static message = /aa96/
+    override name = "InvalidAggregatorError"
+    constructor({
+        cause,
+        docsPath
+    }: {
+        cause?: BaseError
+        docsPath?: string
+    }) {
+        super(
+            [
+                "The bundler tried to bundle the user operation with an invalid aggregator.",
+                "",
+                "Possible solutions:",
+                "• If you are using your own bundler, configure it to use a valid aggregator.",
+                "• If you are using a bundler provider, reach out to them.",
+                "",
+                docsPath ? `Docs: ${docsPath}` : ""
+            ].join("\n"),
+            {
+                cause
+            }
+        )
+    }
+}

package/errors/estimateUserOperationGas.ts

@@ -0,0 +1,50 @@
+import { BaseError } from "viem"
+import type { EstimateUserOperationGasParameters } from "../actions/bundler/estimateUserOperationGas.js"
+import { prettyPrint } from "./utils.js"
+
+export type EstimateUserOperationGasErrorType =
+    EstimateUserOperationGasError & {
+        name: "EstimateUserOperationGasError"
+    }
+export class EstimateUserOperationGasError extends BaseError {
+    override cause: BaseError
+
+    override name = "EstimateUserOperationGasError"
+
+    constructor(
+        cause: BaseError,
+        {
+            userOperation,
+            entryPoint,
+            docsPath
+        }: EstimateUserOperationGasParameters & {
+            docsPath?: string
+        }
+    ) {
+        const prettyArgs = prettyPrint({
+            sender: userOperation.sender,
+            nonce: userOperation.nonce,
+            initCode: userOperation.initCode,
+            callData: userOperation.callData,
+            callGasLimit: userOperation.callGasLimit,
+            verificationGasLimit: userOperation.verificationGasLimit,
+            preVerificationGas: userOperation.preVerificationGas,
+            maxFeePerGas: userOperation.maxFeePerGas,
+            maxPriorityFeePerGas: userOperation.maxPriorityFeePerGas,
+            paymasterAndData: userOperation.paymasterAndData,
+            signature: userOperation.signature,
+            entryPoint
+        })
+
+        super(cause.shortMessage, {
+            cause,
+            docsPath,
+            metaMessages: [
+                ...(cause.metaMessages ? [...cause.metaMessages, " "] : []),
+                "Estimate Gas Arguments:",
+                prettyArgs
+            ].filter(Boolean) as string[]
+        })
+        this.cause = cause
+    }
+}

package/errors/gas.ts

@@ -0,0 +1,120 @@
+import { BaseError } from "viem"
+
+export type VerificationGasLimitTooLowErrorType =
+    VerificationGasLimitTooLowError & {
+        name: "VerificationGasLimitTooLowError"
+    }
+export class VerificationGasLimitTooLowError extends BaseError {
+    static message = /aa4[01]/
+    override name = "VerificationGasLimitTooLowError"
+    constructor({
+        cause,
+        verificationGasLimit,
+        docsPath
+    }: {
+        cause?: BaseError
+        verificationGasLimit?: bigint
+        docsPath?: string
+    }) {
+        super(
+            [
+                `The smart account and paymaster verification exceeded the verificationGasLimit ${verificationGasLimit} set for the user operation.`,
+                "",
+                "Possible solutions:",
+                "• Verify that the verificationGasLimit set for the user operation is high enough to cover the gas used during smart account and paymaster verification.",
+                "• If you are using the eth_estimateUserOperationGas or pm_sponsorUserOperation method from bundler provider to set user operation gas limits and the EntryPoint throws this error during submission, reach out to them.",
+                "",
+                docsPath ? `Docs: ${docsPath}` : ""
+            ].join("\n"),
+            {
+                cause
+            }
+        )
+    }
+}
+
+export type ActualGasCostTooHighErrorType = ActualGasCostTooHighError & {
+    name: "ActualGasCostTooHighError"
+}
+export class ActualGasCostTooHighError extends BaseError {
+    static message = /aa51/
+    override name = "ActualGasCostTooHighError"
+    constructor({
+        cause,
+        docsPath
+    }: {
+        cause?: BaseError
+        docsPath?: string
+    }) {
+        super(
+            [
+                "The actual gas cost of the user operation ended up being higher than the funds paid by the smart account or the paymaster.",
+                "",
+                "Possible solutions:",
+                "• If you encounter this error, try increasing the verificationGasLimit set for the user operation.",
+                "• If you are using the eth_estimateUserOperationGas or pm_sponsorUserOperation method from bundler provider to set user operation gas limits and the EntryPoint throws this error during submission, reach out to them.",
+                "",
+                docsPath ? `Docs: ${docsPath}` : ""
+            ].join("\n"),
+            {
+                cause
+            }
+        )
+    }
+}
+
+export type GasValuesOverflowErrorType = GasValuesOverflowError & {
+    name: "GasValuesOverflowError"
+}
+export class GasValuesOverflowError extends BaseError {
+    static message = /aa94/
+    override name = "GasValuesOverflowError"
+    constructor({
+        cause,
+        docsPath
+    }: {
+        cause?: BaseError
+        docsPath?: string
+    }) {
+        super(
+            [
+                "The gas limit values of the user operation overflowed, they must fit in uint160.",
+                "",
+                docsPath ? `Docs: ${docsPath}` : ""
+            ].join("\n"),
+            {
+                cause
+            }
+        )
+    }
+}
+
+export type BundlerOutOfGasErrorType = BundlerOutOfGasError & {
+    name: "BundlerOutOfGasError"
+}
+export class BundlerOutOfGasError extends BaseError {
+    static message = /aa95/
+    override name = "BundlerOutOfGasError"
+    constructor({
+        cause,
+        docsPath
+    }: {
+        cause?: BaseError
+        docsPath?: string
+    }) {
+        super(
+            [
+                "The bundler tried to bundle the user operation with the gas limit set too low.",
+                "",
+                "Possible solutions:",
+                "• If you are using your own bundler, configure it send gas limits properly.",
+                "• If you are using a bundler provider, reach out to them.",
+                "",
+                docsPath ? `Docs: ${docsPath}` : ""
+            ].join("\n"),
+            {
+                cause
+            }
+        )
+    }
+}