permissionless 0.0.5 → 0.0.7

package/clients/decorators/bundler.ts

@@ -0,0 +1,178 @@
+import type { Address } from "abitype"
+import type { Client, Hash } from "viem"
+import { chainId } from "../../actions/bundler/chainId.js"
+import {
+    type EstimateUserOperationGasParameters,
+    type EstimateUserOperationGasReturnType,
+    estimateUserOperationGas
+} from "../../actions/bundler/estimateUserOperationGas.js"
+import {
+    type GetUserOperationByHashParameters,
+    type GetUserOperationByHashReturnType,
+    getUserOperationByHash
+} from "../../actions/bundler/getUserOperationByHash.js"
+import {
+    type GetUserOperationReceiptParameters,
+    type GetUserOperationReceiptReturnType,
+    getUserOperationReceipt
+} from "../../actions/bundler/getUserOperationReceipt.js"
+import { type SendUserOperationParameters, sendUserOperation } from "../../actions/bundler/sendUserOperation.js"
+import { supportedEntryPoints } from "../../actions/bundler/supportedEntryPoints.js"
+import type { BundlerClient } from "../bundler.js"
+
+export type BundlerActions = {
+    /**
+     *
+     * Sends user operation to the bundler
+     *
+     * - Docs: https://docs.pimlico.io/permissionless/reference/bundler-actions/sendUserOperation
+     *
+     * @param args {@link SendUserOperationParameters}.
+     * @returns UserOpHash that you can use to track user operation as {@link Hash}.
+     *
+     * @example
+     * import { createClient } from "viem"
+     * import { bundlerActions } from "permissionless"
+     *
+     * const bundlerClient = createClient({
+     *      chain: goerli,
+     *      transport: http("https://api.pimlico.io/v1/goerli/rpc?apikey=YOUR_API_KEY_HERE")
+     * }).extend(bundlerActions)
+     *
+     * const userOpHash = await bundlerClient.sendUserOperation({
+     *      userOperation: signedUserOperation,
+     *      entryPoint: entryPoint
+     * })
+     *
+     * // Return '0xe9fad2cd67f9ca1d0b7a6513b2a42066784c8df938518da2b51bb8cc9a89ea34'
+     */
+    sendUserOperation: (args: SendUserOperationParameters) => Promise<Hash>
+    /**
+     *
+     * Estimates preVerificationGas, verificationGasLimit and callGasLimit for user operation
+     *
+     * - Docs: https://docs.pimlico.io/permissionless/reference/bundler-actions/estimateUserOperationGas
+     *
+     * @param args {@link EstimateUserOperationGasParameters}
+     * @returns preVerificationGas, verificationGasLimit and callGasLimit as {@link EstimateUserOperationGasReturnType}
+     *
+     * @example
+     * import { createClient } from "viem"
+     * import { bundlerActions } from "permissionless"
+     *
+     * const bundlerClient = createClient({
+     *      chain: goerli,
+     *      transport: http(BUNDLER_URL)
+     * }).extend(bundlerActions)
+     *
+     * const gasParameters = await bundlerClient.estimateUserOperationGas({
+     *     userOperation: signedUserOperation,
+     *    entryPoint: entryPoint
+     * })
+     *
+     * // Return {preVerificationGas: 43492n, verificationGasLimit: 59436n, callGasLimit: 9000n}
+     */
+    estimateUserOperationGas: (args: EstimateUserOperationGasParameters) => Promise<EstimateUserOperationGasReturnType>
+    /**
+     *
+     * Returns the supported entrypoints by the bundler service
+     *
+     * - Docs: https://docs.pimlico.io/permissionless/reference/bundler-actions/supportedEntryPoints
+     *
+     * @returns Supported entryPoints
+     *
+     * @example
+     * import { createClient } from "viem"
+     * import { bundlerActions } from "permissionless"
+     *
+     * const bundlerClient = createClient({
+     *      chain: goerli,
+     *      transport: http(BUNDLER_URL)
+     * }).extend(bundlerActions)
+     *
+     * const supportedEntryPoints = await bundlerClient.supportedEntryPoints()
+     *
+     * // Return ['0x5FF137D4b0FDCD49DcA30c7CF57E578a026d2789']
+     */
+    supportedEntryPoints: () => Promise<Address[]>
+    /**
+     *
+     * Returns the supported chain id by the bundler service
+     *
+     * - Docs: https://docs.pimlico.io/permissionless/reference/bundler-actions/chainId
+     *
+     * @returns Supported chain id
+     *
+     * @example
+     * import { createClient } from "viem"
+     * import { bundlerActions } from "permissionless"
+     *
+     * const bundlerClient = createClient({
+     *      chain: goerli,
+     *      transport: http(BUNDLER_URL)
+     * }).extend(bundlerActions)
+     *
+     * const chainId = await bundlerClient.chainId()
+     * // Return 5n for Goerli
+     */
+    chainId: () => Promise<number>
+    /**
+     *
+     * Returns the user operation from userOpHash
+     *
+     * - Docs: https://docs.pimlico.io/permissionless/reference/bundler-actions/getUserOperationByHash
+     *
+     * @param args {@link GetUserOperationByHash} UserOpHash that was returned by {@link sendUserOperation}
+     * @returns userOperation along with entryPoint, transactionHash, blockHash, blockNumber if found or null
+     *
+     * @example
+     * import { createClient } from "viem"
+     * import { bundlerActions } from "permissionless"
+     *
+     * const bundlerClient = createClient({
+     *      chain: goerli,
+     *      transport: http(BUNDLER_URL)
+     * }).extend(bundlerActions)
+     *
+     * await bundlerClient.getUserOperationByHash(userOpHash)
+     *
+     */
+    getUserOperationByHash: (args: GetUserOperationByHashParameters) => Promise<GetUserOperationByHashReturnType>
+    /**
+     *
+     * Returns the user operation receipt from userOpHash
+     *
+     * - Docs: https://docs.pimlico.io/permissionless/reference/bundler-actions/getUserOperationReceipt
+     *
+     * @param args {@link GetUserOperationReceiptParameters} UserOpHash that was returned by {@link sendUserOperation}
+     * @returns user operation receipt {@link GetUserOperationReceiptReturnType} if found or null
+     *
+     * @example
+     * import { createClient } from "viem"
+     * import { bundlerActions } from "permissionless"
+     *
+     * const bundlerClient = createClient({
+     *      chain: goerli,
+     *      transport: http(BUNDLER_URL)
+     * }).extend(bundlerActions)
+     *
+     * await bundlerClient.getUserOperationReceipt({hash: userOpHash})
+     *
+     */
+    getUserOperationReceipt: (args: GetUserOperationReceiptParameters) => Promise<GetUserOperationReceiptReturnType>
+}
+
+const bundlerActions = (client: Client): BundlerActions => ({
+    sendUserOperation: async (args: SendUserOperationParameters): Promise<Hash> =>
+        sendUserOperation(client as BundlerClient, args),
+    estimateUserOperationGas: (args: EstimateUserOperationGasParameters) =>
+        estimateUserOperationGas(client as BundlerClient, args),
+    supportedEntryPoints: (): Promise<Address[]> => supportedEntryPoints(client as BundlerClient),
+    chainId: () => chainId(client as BundlerClient),
+    getUserOperationByHash: (args: GetUserOperationByHashParameters) =>
+        getUserOperationByHash(client as BundlerClient, args),
+    getUserOperationReceipt: (args: GetUserOperationReceiptParameters) =>
+        getUserOperationReceipt(client as BundlerClient, args)
+})
+
+export { bundlerActions }

package/clients/decorators/pimlico.ts

@@ -0,0 +1,107 @@
+import type { Client, Hash } from "viem"
+import {
+    type GetUserOperationGasPriceReturnType,
+    getUserOperationGasPrice
+} from "../../actions/pimlico/getUserOperationGasPrice.js"
+import {
+    type GetUserOperationStatusParameters,
+    type GetUserOperationStatusReturnType,
+    getUserOperationStatus
+} from "../../actions/pimlico/getUserOperationStatus.js"
+import {
+    type SponsorUserOperationParameters,
+    type SponsorUserOperationReturnType,
+    sponsorUserOperation
+} from "../../actions/pimlico/sponsorUserOperation.js"
+import type { PimlicoBundlerClient, PimlicoPaymasterClient } from "../pimlico.js"
+
+export type PimlicoBundlerActions = {
+    /**
+     * Returns the live gas prices that you can use to send a user operation.
+     *
+     * - Docs: https://docs.pimlico.io/permissionless/reference/pimlico-bundler-actions/getUserOperationGasPrice
+     *
+     * @returns slow, standard & fast values for maxFeePerGas & maxPriorityFeePerGas {@link GetUserOperationGasPriceReturnType}
+     *
+     * @example
+     *
+     * import { createClient } from "viem"
+     * import { pimlicoBundlerActions } from "permissionless/actions/pimlico"
+     *
+     * 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: https://docs.pimlico.io/permissionless/reference/pimlico-bundler-actions/getUserOperationStatus
+     *
+     * @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/pimlico"
+     *
+     * 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)
+})
+
+export type PimlicoPaymasterClientActions = {
+    /**
+     * Returns paymasterAndData & updated gas parameters required to sponsor a userOperation.
+     *
+     * https://docs.pimlico.io/permissionless/reference/pimlico-paymaster-actions/sponsorUserOperation
+     *
+     * @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/pimlico"
+     *
+     * 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/clients/decorators/stackup.ts

@@ -0,0 +1,65 @@
+import type { Address, Client } from "viem"
+import { type AccountsParameters, accounts } from "../../actions/stackup/accounts.js"
+import {
+    type SponsorUserOperationParameters,
+    type SponsorUserOperationReturnType,
+    sponsorUserOperation
+} from "../../actions/stackup/sponsorUserOperation.js"
+import { type StackupPaymasterClient } from "../stackup.js"
+
+export type StackupPaymasterClientActions = {
+    /**
+     * Returns paymasterAndData & updated gas parameters required to sponsor a userOperation.
+     *
+     * https://docs.stackup.sh/docs/paymaster-api-rpc-methods#pm_sponsoruseroperation
+     *
+     * @param args {@link SponsorUserOperationParameters} UserOperation you want to sponsor & entryPoint.
+     * @returns paymasterAndData & updated gas parameters, see {@link SponsorUserOperationReturnType}
+     *
+     * @example
+     * import { createClient } from "viem"
+     * import { stackupPaymasterActions } from "permissionless/actions/stackup"
+     *
+     * const bundlerClient = createClient({
+     *      chain: goerli,
+     *      transport: http("https://api.stackup.sh/v1/paymaster/YOUR_API_KEY_HERE")
+     * }).extend(stackupPaymasterActions)
+     *
+     * await bundlerClient.sponsorUserOperation(bundlerClient, {
+     *      userOperation: userOperationWithDummySignature,
+     *      entryPoint: entryPoint
+     * }})
+     *
+     */
+    sponsorUserOperation: (args: SponsorUserOperationParameters) => Promise<SponsorUserOperationReturnType>
+
+    /**
+     * Returns all the Paymaster addresses associated with an EntryPoint that’s owned by this service.
+     *
+     * https://docs.stackup.sh/docs/paymaster-api-rpc-methods#pm_accounts
+     *
+     * @param args {@link AccountsParameters} entryPoint for which you want to get list of supported paymasters.
+     * @returns paymaster addresses
+     *
+     * @example
+     * import { createClient } from "viem"
+     * import { stackupPaymasterActions } from "permissionless/actions/stackup"
+     *
+     * const bundlerClient = createClient({
+     *      chain: goerli,
+     *      transport: http("https://api.stackup.sh/v1/paymaster/YOUR_API_KEY_HERE")
+     * }).extend(stackupPaymasterActions)
+     *
+     * await bundlerClient.accounts(bundlerClient, {
+     *      entryPoint: entryPoint
+     * }})
+     *
+     */
+    accounts: (args: AccountsParameters) => Promise<Address[]>
+}
+
+export const stackupPaymasterActions = (client: Client): StackupPaymasterClientActions => ({
+    sponsorUserOperation: async (args: SponsorUserOperationParameters) =>
+        sponsorUserOperation(client as StackupPaymasterClient, args),
+    accounts: async (args: AccountsParameters) => accounts(client as StackupPaymasterClient, args)
+})

package/clients/pimlico.ts

@@ -1,14 +1,13 @@
 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 { PimlicoBundlerRpcSchema, PimlicoPaymasterRpcSchema } from "../types/pimlico.js"
+import { type BundlerActions, bundlerActions } from "./decorators/bundler.js"
 import {
     type PimlicoBundlerActions,
     type PimlicoPaymasterClientActions,
     pimlicoBundlerActions,
     pimlicoPaymasterActions
-} from "../actions/pimlico"
-import type { PimlicoBundlerRpcSchema, PimlicoPaymasterRpcSchema } from "../types/pimlico"
+} from "./decorators/pimlico.js"
 
 export type PimlicoBundlerClient = Client<
     Transport,

package/clients/stackup.ts

@@ -0,0 +1,44 @@
+import { type Account, type Chain, type Client, type PublicClientConfig, type Transport, createClient } from "viem"
+import type { StackupPaymasterRpcSchema } from "../types/stackup.js"
+import { type BundlerActions, bundlerActions } from "./decorators/bundler.js"
+import { type StackupPaymasterClientActions, stackupPaymasterActions } from "./decorators/stackup.js"
+
+export type StackupPaymasterClient = Client<
+    Transport,
+    Chain | undefined,
+    Account | undefined,
+    StackupPaymasterRpcSchema,
+    StackupPaymasterClientActions & BundlerActions
+>
+
+/**
+ * Creates a Stackup 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: https://docs.pimlico.io/permissionless/reference/clients/stackupPaymasterClient
+ *
+ * A Stackup Paymaster Client is an interface to "stackup paymaster endpoints" [JSON-RPC API](https://docs.stackup.sh/docs/paymaster-api-rpc-methods) methods such as sponsoring user operation, etc through Stackup Paymaster Actions.
+ *
+ * @param config - {@link PublicClientConfig}
+ * @returns A Stackup Paymaster Client. {@link StackupPaymasterClient}
+ *
+ * @example
+ * import { createPublicClient, http } from 'viem'
+ * import { mainnet } from 'viem/chains'
+ *
+ * const stackupPaymasterClient = createStackupPaymasterClient({
+ *   chain: mainnet,
+ *   transport: http("https://api.stackup.sh/v1/paymaster/YOUR_API_KEY_HERE"),
+ * })
+ */
+export const createStackupPaymasterClient = <transport extends Transport, chain extends Chain | undefined = undefined>(
+    parameters: PublicClientConfig<transport, chain>
+): StackupPaymasterClient => {
+    const { key = "public", name = "Stackup Paymaster Client" } = parameters
+    const client = createClient({
+        ...parameters,
+        key,
+        name,
+        type: "stackupPaymasterClient"
+    })
+    return client.extend(bundlerActions).extend(stackupPaymasterActions)
+}

package/index.ts

@@ -1,4 +1,62 @@
-export * from "./actions"
-export * from "./clients"
-export * from "./types"
-export * from "./utils"
+import type {
+    EstimateUserOperationGasParameters,
+    EstimateUserOperationGasReturnType
+} from "./actions/bundler/estimateUserOperationGas.js"
+import type { GetUserOperationByHashParameters } from "./actions/bundler/getUserOperationByHash.js"
+import type { GetUserOperationByHashReturnType } from "./actions/bundler/getUserOperationByHash.js"
+import type {
+    GetUserOperationReceiptParameters,
+    GetUserOperationReceiptReturnType
+} from "./actions/bundler/getUserOperationReceipt.js"
+import type { SendUserOperationParameters } from "./actions/bundler/sendUserOperation.js"
+
+import type { GetSenderAddressParams } from "./actions/public/getSenderAddress.js"
+import { getSenderAddress } from "./actions/public/getSenderAddress.js"
+
+import { chainId } from "./actions/bundler/chainId.js"
+import { estimateUserOperationGas } from "./actions/bundler/estimateUserOperationGas.js"
+import { getUserOperationByHash } from "./actions/bundler/getUserOperationByHash.js"
+import { getUserOperationReceipt } from "./actions/bundler/getUserOperationReceipt.js"
+import { sendUserOperation } from "./actions/bundler/sendUserOperation.js"
+import { supportedEntryPoints } from "./actions/bundler/supportedEntryPoints.js"
+import type { GetAccountNonceParams } from "./actions/public/getAccountNonce.js"
+import { getAccountNonce } from "./actions/public/getAccountNonce.js"
+import { type BundlerClient, createBundlerClient } from "./clients/bundler.js"
+import type { BundlerActions } from "./clients/decorators/bundler.js"
+import { bundlerActions } from "./clients/decorators/bundler.js"
+
+export type {
+    SendUserOperationParameters,
+    EstimateUserOperationGasParameters,
+    EstimateUserOperationGasReturnType,
+    GetUserOperationByHashParameters,
+    GetUserOperationByHashReturnType,
+    GetUserOperationReceiptParameters,
+    GetUserOperationReceiptReturnType,
+    GetSenderAddressParams,
+    GetAccountNonceParams,
+    BundlerClient,
+    BundlerActions
+}
+
+export {
+    sendUserOperation,
+    estimateUserOperationGas,
+    supportedEntryPoints,
+    chainId,
+    getUserOperationByHash,
+    getUserOperationReceipt,
+    getSenderAddress,
+    getAccountNonce,
+    createBundlerClient,
+    bundlerActions
+}
+import type { UserOperation } from "./types/userOperation.js"
+
+export { type UserOperation }
+
+import type { GetUserOperationHashParams } from "./utils/getUserOperationHash.js"
+import { getUserOperationHash } from "./utils/getUserOperationHash.js"
+
+export { getUserOperationHash, type GetUserOperationHashParams }
+export * from "./utils/index.js"

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "permissionless",
-    "version": "0.0.5",
+    "version": "0.0.7",
     "author": "Pimlico",
     "main": "./_cjs/index.js",
     "module": "./_esm/index.js",
@@ -33,6 +33,11 @@
             "import": "./_esm/actions/pimlico.js",
             "default": "./_cjs/actions/pimlico.js"
         },
+        "./actions/stackup": {
+            "types": "./_types/actions/stackup.d.ts",
+            "import": "./_esm/actions/stackup.js",
+            "default": "./_cjs/actions/stackup.js"
+        },
         "./clients": {
             "types": "./_types/clients/index.d.ts",
             "import": "./_esm/clients/index.js",
@@ -43,6 +48,11 @@
             "import": "./_esm/clients/pimlico.js",
             "default": "./_cjs/clients/pimlico.js"
         },
+        "./clients/stackup": {
+            "types": "./_types/clients/stackup.d.ts",
+            "import": "./_esm/clients/stackup.js",
+            "default": "./_cjs/clients/stackup.js"
+        },
         "./utils": {
             "types": "./_types/utils/index.d.ts",
             "import": "./_esm/utils/index.js",