permissionless 0.0.1 → 0.0.3

package/actions/pimlico.ts

@@ -0,0 +1,258 @@
+import type { Address, Client, Hash, Hex } from "viem"
+import type { PartialBy } from "viem/types/utils"
+import type { PimlicoBundlerClient, PimlicoPaymasterClient } from "../clients/pimlico"
+import type { PimlicoUserOperationStatus } from "../types/pimlico"
+import type { UserOperation, UserOperationWithBigIntAsHex } from "../types/userOperation"
+import { deepHexlify } from "./utils"
+
+export type SponsorUserOperationParameters = {
+    userOperation: PartialBy<
+        UserOperation,
+        "callGasLimit" | "preVerificationGas" | "verificationGasLimit" | "paymasterAndData"
+    >
+    entryPoint: Address
+}
+
+export type SponsorUserOperationReturnType = {
+    paymasterAndData: Hex
+    preVerificationGas: bigint
+    verificationGasLimit: bigint
+    callGasLimit: bigint
+}
+
+export type GetUserOperationGasPriceReturnType = {
+    slow: {
+        maxFeePerGas: bigint
+        maxPriorityFeePerGas: bigint
+    }
+    standard: {
+        maxFeePerGas: bigint
+        maxPriorityFeePerGas: bigint
+    }
+    fast: {
+        maxFeePerGas: bigint
+        maxPriorityFeePerGas: bigint
+    }
+}
+
+export type GetUserOperationStatusParameters = {
+    hash: Hash
+}
+
+export type GetUserOperationStatusReturnType = PimlicoUserOperationStatus
+
+/**
+ * Returns the live gas prices that you can use to send a user operation.
+ *
+ * - Docs: [TODO://add link]
+ * - Example: [TODO://add link]
+ *
+ * @param client {@link PimlicoBundlerClient} that you created using viem's createClient whose transport url is pointing to the Pimlico's bundler.
+ * @returns slow, standard & fast values for maxFeePerGas & maxPriorityFeePerGas
+ *
+ *
+ * @example
+ * import { createClient } from "viem"
+ * import { getUserOperationGasPrice } from "permissionless/actions"
+ *
+ * const bundlerClient = createClient({
+ *      chain: goerli,
+ *      transport: http("https://api.pimlico.io/v1/goerli/rpc?apikey=YOUR_API_KEY_HERE")
+ * })
+ *
+ * await getUserOperationGasPrice(bundlerClient)
+ *
+ */
+export const getUserOperationGasPrice = async (
+    client: PimlicoBundlerClient
+): Promise<GetUserOperationGasPriceReturnType> => {
+    const gasPrices = await client.request({
+        method: "pimlico_getUserOperationGasPrice",
+        params: []
+    })
+
+    return {
+        slow: {
+            maxFeePerGas: BigInt(gasPrices.slow.maxFeePerGas),
+            maxPriorityFeePerGas: BigInt(gasPrices.slow.maxPriorityFeePerGas)
+        },
+        standard: {
+            maxFeePerGas: BigInt(gasPrices.standard.maxFeePerGas),
+            maxPriorityFeePerGas: BigInt(gasPrices.standard.maxPriorityFeePerGas)
+        },
+        fast: {
+            maxFeePerGas: BigInt(gasPrices.fast.maxFeePerGas),
+            maxPriorityFeePerGas: BigInt(gasPrices.fast.maxPriorityFeePerGas)
+        }
+    }
+}
+
+/**
+ * Returns the status of the userOperation that is pending in the mempool.
+ *
+ * - Docs: [TODO://add link]
+ * - Example: [TODO://add link]
+ *
+ * @param client {@link PimlicoBundlerClient} that you created using viem's createClient whose transport url is pointing to the Pimlico's bundler.
+ * @param hash {@link Hash} UserOpHash that you must have received from sendUserOperation.
+ * @returns status & transaction hash if included {@link GetUserOperationStatusReturnType}
+ *
+ *
+ * @example
+ * import { createClient } from "viem"
+ * import { getUserOperationStatus } from "permissionless/actions"
+ *
+ * const bundlerClient = createClient({
+ *      chain: goerli,
+ *      transport: http("https://api.pimlico.io/v1/goerli/rpc?apikey=YOUR_API_KEY_HERE")
+ * })
+ *
+ * await getUserOperationStatus(bundlerClient, { hash: userOpHash })
+ *
+ */
+export const getUserOperationStatus = async (
+    client: PimlicoBundlerClient,
+    { hash }: GetUserOperationStatusParameters
+): Promise<GetUserOperationStatusReturnType> => {
+    return client.request({
+        method: "pimlico_getUserOperationStatus",
+        params: [hash]
+    })
+}
+
+export type PimlicoBundlerActions = {
+    /**
+     * Returns the live gas prices that you can use to send a user operation.
+     *
+     * - Docs: [TODO://add link]
+     * - Example: [TODO://add link]
+     *
+     * @returns slow, standard & fast values for maxFeePerGas & maxPriorityFeePerGas {@link GetUserOperationGasPriceReturnType}
+     *
+     * @example
+     *
+     * import { createClient } from "viem"
+     * import { pimlicoBundlerActions } from "permissionless/actions"
+     *
+     * const bundlerClient = createClient({
+     *      chain: goerli,
+     *      transport: http("https://api.pimlico.io/v1/goerli/rpc?apikey=YOUR_API_KEY_HERE")
+     * }).extend(pimlicoBundlerActions)
+     *
+     * await bundlerClient.getUserOperationGasPrice()
+     */
+    getUserOperationGasPrice: () => Promise<GetUserOperationGasPriceReturnType>
+    /**
+     * Returns the status of the userOperation that is pending in the mempool.
+     *
+     * - Docs: [TODO://add link]
+     * - Example: [TODO://add link]
+     *
+     * @param hash {@link Hash} UserOpHash that you must have received from sendUserOperation.
+     * @returns status & transaction hash if included {@link GetUserOperationStatusReturnType}
+     *
+     * @example
+     * import { createClient } from "viem"
+     * import { pimlicoBundlerActions } from "permissionless/actions"
+     *
+     * const bundlerClient = createClient({
+     *      chain: goerli,
+     *      transport: http("https://api.pimlico.io/v1/goerli/rpc?apikey=YOUR_API_KEY_HERE")
+     * }).extend(pimlicoBundlerActions)
+     *
+     * await bundlerClient.getUserOperationStatus({ hash: userOpHash })
+     */
+    getUserOperationStatus: (args: GetUserOperationStatusParameters) => Promise<GetUserOperationStatusReturnType>
+}
+
+export const pimlicoBundlerActions = (client: Client): PimlicoBundlerActions => ({
+    getUserOperationGasPrice: async () => getUserOperationGasPrice(client as PimlicoBundlerClient),
+    getUserOperationStatus: async (args: GetUserOperationStatusParameters) =>
+        getUserOperationStatus(client as PimlicoBundlerClient, args)
+})
+
+/**
+ * Returns paymasterAndData & updated gas parameters required to sponsor a userOperation.
+ *
+ * - Docs: [TODO://add link]
+ * - Example: [TODO://add link]
+ *
+ * @param client {@link PimlicoBundlerClient} that you created using viem's createClient whose transport url is pointing to the Pimlico's bundler.
+ * @param args {@link sponsorUserOperationParameters} UserOperation you want to sponsor & entryPoint.
+ * @returns paymasterAndData & updated gas parameters, see {@link SponsorUserOperationReturnType}
+ *
+ *
+ * @example
+ * import { createClient } from "viem"
+ * import { sponsorUserOperation } from "permissionless/actions"
+ *
+ * const bundlerClient = createClient({
+ *      chain: goerli,
+ *      transport: http("https://api.pimlico.io/v2/goerli/rpc?apikey=YOUR_API_KEY_HERE")
+ * })
+ *
+ * await sponsorUserOperation(bundlerClient, {
+ *      userOperation: userOperationWithDummySignature,
+ *      entryPoint: entryPoint
+ * }})
+ *
+ */
+export const sponsorUserOperation = async (
+    client: PimlicoPaymasterClient,
+    args: SponsorUserOperationParameters
+): Promise<SponsorUserOperationReturnType> => {
+    const response = await client.request({
+        method: "pm_sponsorUserOperation",
+        params: [deepHexlify(args.userOperation) as UserOperationWithBigIntAsHex, args.entryPoint]
+    })
+
+    return {
+        paymasterAndData: response.paymasterAndData,
+        preVerificationGas: BigInt(response.preVerificationGas),
+        verificationGasLimit: BigInt(response.verificationGasLimit),
+        callGasLimit: BigInt(response.callGasLimit)
+    }
+}
+
+export type PimlicoPaymasterClientActions = {
+    /**
+     * Returns paymasterAndData & updated gas parameters required to sponsor a userOperation.
+     *
+     * - Docs: [TODO://add link]
+     * - Example: [TODO://add link]
+     *
+     * @param args {@link SponsorUserOperationParameters} UserOperation you want to sponsor & entryPoint.
+     * @returns paymasterAndData & updated gas parameters, see {@link SponsorUserOperationReturnType}
+     *
+     * @example
+     * import { createClient } from "viem"
+     * import { sponsorUserOperation } from "permissionless/actions"
+     *
+     * const bundlerClient = createClient({
+     *      chain: goerli,
+     *      transport: http("https://api.pimlico.io/v2/goerli/rpc?apikey=YOUR_API_KEY_HERE")
+     * }).extend(pimlicoPaymasterActions)
+     *
+     * await bundlerClient.sponsorUserOperation(bundlerClient, {
+     *      userOperation: userOperationWithDummySignature,
+     *      entryPoint: entryPoint
+     * }})
+     *
+     */
+    sponsorUserOperation: (args: SponsorUserOperationParameters) => Promise<SponsorUserOperationReturnType>
+}
+
+export const pimlicoPaymasterActions = (client: Client): PimlicoPaymasterClientActions => ({
+    sponsorUserOperation: async (args: SponsorUserOperationParameters) =>
+        sponsorUserOperation(client as PimlicoPaymasterClient, args)
+})
+
+/**
+ * TODO: Add support for pimlicoActions after we support all the actions of v1 in v2 of the Pimlico API.
+ */
+// export const pimlicoActions = (client: Client) => {
+//     return {
+//         ...pimlicoBundlerActions(client),
+//         ...pimlicoPaymasterActions(client)
+//     }
+// }

package/actions/utils.ts

@@ -0,0 +1,30 @@
+import { toHex } from "viem"
+
+export const transactionReceiptStatus = {
+    "0x0": "reverted",
+    "0x1": "success"
+} as const
+
+// biome-ignore lint/suspicious/noExplicitAny: it's a recursive function, so it's hard to type
+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])
+        }),
+        {}
+    )
+}

package/clients/bundler.ts

@@ -0,0 +1,39 @@
+import type { Account, Chain, Client, PublicClientConfig, Transport } from "viem"
+import { createClient } from "viem"
+import { bundlerActions } from "../actions"
+import type { BundlerActions } from "../actions/bundler"
+import type { BundlerRpcSchema } from "../types/bundler"
+
+export type BundlerClient = Client<Transport, Chain | undefined, Account | undefined, BundlerRpcSchema, BundlerActions>
+/**
+ * Creates a EIP-4337 compliant Bundler Client with a given [Transport](https://viem.sh/docs/clients/intro.html) configured for a [Chain](https://viem.sh/docs/clients/chains.html).
+ *
+ * - Docs: [TODO://add link]
+ * - Example: [TODO://add link]
+ *
+ * A Bundler Client is an interface to "erc 4337" [JSON-RPC API](https://eips.ethereum.org/EIPS/eip-4337#rpc-methods-eth-namespace) methods such as sending user operation, estimating gas for a user operation, get user operation receipt, etc through [Bundler Actions](TODO://Add bundler action documentation link).
+ *
+ * @param config - {@link PublicClientConfig}
+ * @returns A Bundler Client. {@link BundlerClient}
+ *
+ * @example
+ * import { createPublicClient, http } from 'viem'
+ * import { mainnet } from 'viem/chains'
+ *
+ * const bundlerClient = createBundlerClient({
+ *   chain: mainnet,
+ *   transport: http(BUNDLER_URL),
+ * })
+ */
+export const createBundlerClient = <transport extends Transport, chain extends Chain | undefined = undefined>(
+    parameters: PublicClientConfig<transport, chain>
+): BundlerClient => {
+    const { key = "public", name = "Bundler Client" } = parameters
+    const client = createClient({
+        ...parameters,
+        key,
+        name,
+        type: "bundlerClient"
+    })
+    return client.extend(bundlerActions)
+}

package/clients/index.ts

@@ -0,0 +1,3 @@
+import { type BundlerClient, createBundlerClient } from "./bundler"
+
+export { createBundlerClient, type BundlerClient }

package/clients/pimlico.ts

@@ -0,0 +1,93 @@
+import type { Account, Chain, Client, PublicClientConfig, Transport } from "viem"
+import { createClient } from "viem"
+import { bundlerActions } from "../actions"
+import type { BundlerActions } from "../actions/bundler"
+import {
+    type PimlicoBundlerActions,
+    type PimlicoPaymasterClientActions,
+    pimlicoBundlerActions,
+    pimlicoPaymasterActions
+} from "../actions/pimlico"
+import type { PimlicoBundlerRpcSchema, PimlicoPaymasterRpcSchema } from "../types/pimlico"
+
+export type PimlicoBundlerClient = Client<
+    Transport,
+    Chain | undefined,
+    Account | undefined,
+    PimlicoBundlerRpcSchema,
+    PimlicoBundlerActions & BundlerActions
+>
+
+export type PimlicoPaymasterClient = Client<
+    Transport,
+    Chain | undefined,
+    Account | undefined,
+    PimlicoPaymasterRpcSchema,
+    PimlicoPaymasterClientActions
+>
+
+/**
+ * Creates a pimlico specific Bundler Client with a given [Transport](https://viem.sh/docs/clients/intro.html) configured for a [Chain](https://viem.sh/docs/clients/chains.html).
+ *
+ * - Docs: [TODO://add link]
+ * - Example: [TODO://add link]
+ *
+ * A Pimlico Client is an interface to "pimlico endpoints" [JSON-RPC API](https://docs.pimlico.io/reference/bundler/endpoints) methods such as getting current blockchain gas prices, getting user operation status, etc through [Pimlico Bundler Actions](TODO://Add bundler action documentation link).
+ *
+ * @param config - {@link PublicClientConfig}
+ * @returns A Pimlico Bundler Client. {@link PimlicoBundlerClient}
+ *
+ * @example
+ * import { createPublicClient, http } from 'viem'
+ * import { mainnet } from 'viem/chains'
+ *
+ * const pimlicoBundlerClient = createPimlicoBundlerClient({
+ *   chain: mainnet,
+ *   transport: http("https://api.pimlico.io/v1/goerli/rpc?apikey=YOUR_API_KEY_HERE"),
+ * })
+ */
+export const createPimlicoBundlerClient = <transport extends Transport, chain extends Chain | undefined = undefined>(
+    parameters: PublicClientConfig<transport, chain>
+): PimlicoBundlerClient => {
+    const { key = "public", name = "Pimlico Bundler Client" } = parameters
+    const client = createClient({
+        ...parameters,
+        key,
+        name,
+        type: "pimlicoBundlerClient"
+    })
+    return client.extend(bundlerActions).extend(pimlicoBundlerActions)
+}
+
+/**
+ * Creates a pimlico specific Paymaster Client with a given [Transport](https://viem.sh/docs/clients/intro.html) configured for a [Chain](https://viem.sh/docs/clients/chains.html).
+ *
+ * - Docs: [TODO://add link]
+ * - Example: [TODO://add link]
+ *
+ * A Pimlico Paymaster Client is an interface to "pimlico paymaster endpoints" [JSON-RPC API](https://docs.pimlico.io/reference/verifying-paymaster/endpoints) methods such as sponsoring user operation, etc through [Pimlico Paymaster Actions](TODO://Add bundler action documentation link).
+ *
+ * @param config - {@link PublicClientConfig}
+ * @returns A Pimlico Paymaster Client. {@link PimlicoPaymasterClient}
+ *
+ * @example
+ * import { createPublicClient, http } from 'viem'
+ * import { mainnet } from 'viem/chains'
+ *
+ * const pimlicoPaymasterClient = createPimlicoPaymasterClient({
+ *   chain: mainnet,
+ *   transport: http("https://api.pimlico.io/v2/goerli/rpc?apikey=YOUR_API_KEY_HERE"),
+ * })
+ */
+export const createPimlicoPaymasterClient = <transport extends Transport, chain extends Chain | undefined = undefined>(
+    parameters: PublicClientConfig<transport, chain>
+): PimlicoPaymasterClient => {
+    const { key = "public", name = "Pimlico Paymaster Client" } = parameters
+    const client = createClient({
+        ...parameters,
+        key,
+        name,
+        type: "pimlicoPaymasterClient"
+    })
+    return client.extend(pimlicoPaymasterActions)
+}

package/index.ts

@@ -0,0 +1,3 @@
+export * from "./actions"
+export * from "./clients"
+export * from "./types"

package/package.json

@@ -1,12 +1,50 @@
 {
-  "name": "permissionless",
-  "version": "0.0.1",
-  "description": "",
-  "main": "index.js",
-  "keywords": [],
-  "author": "Pimlico",
-  "license": "MIT",
-  "scripts": {
-    "test": "echo \"Error: no test specified\" && exit 1"
-  }
-}
+    "name": "permissionless",
+    "version": "0.0.3",
+    "author": "Pimlico",
+    "main": "./_cjs/index.js",
+    "module": "./_esm/index.js",
+    "types": "./_types/index.d.ts",
+    "typings": "./_types/index.d.ts",
+    "type": "module",
+    "sideEffects": false,
+    "description": "A utility library for working with ERC-4337",
+    "keywords": [
+        "ethereum",
+        "erc-4337",
+        "eip-4337",
+        "paymaster",
+        "bundler"
+    ],
+    "license": "MIT",
+    "exports": {
+        ".": {
+            "types": "./_types/index.d.ts",
+            "import": "./_esm/index.js",
+            "default": "./_cjs/index.js"
+        },
+        "./actions": {
+            "types": "./_types/actions/index.d.ts",
+            "import": "./_esm/actions/index.js",
+            "default": "./_cjs/actions/index.js"
+        },
+        "./actions/pimlico": {
+            "types": "./_types/actions/pimlico.d.ts",
+            "import": "./_esm/actions/pimlico.js",
+            "default": "./_cjs/actions/pimlico.js"
+        },
+        "./clients": {
+            "types": "./_types/clients/index.d.ts",
+            "import": "./_esm/clients/index.js",
+            "default": "./_cjs/clients/index.js"
+        },
+        "./clients/pimlico": {
+            "types": "./_types/clients/pimlico.d.ts",
+            "import": "./_esm/clients/pimlico.js",
+            "default": "./_cjs/clients/pimlico.js"
+        }
+    },
+    "peerDependencies": {
+        "viem": "^1.10.10"
+    }
+}