permissionless 0.0.13 → 0.0.15

package/accounts/kernel/signerToEcdsaKernelSmartAccount.ts

@@ -0,0 +1,363 @@
+import {
+    type Account,
+    type Address,
+    type Chain,
+    type Client,
+    type Hex,
+    type Transport,
+    concatHex,
+    encodeFunctionData,
+    isAddressEqual
+} from "viem"
+import { toAccount } from "viem/accounts"
+import {
+    getBytecode,
+    getChainId,
+    readContract,
+    signMessage,
+    signTypedData
+} from "viem/actions"
+import { getAccountNonce } from "../../actions/public/getAccountNonce.js"
+import { getSenderAddress } from "../../actions/public/getSenderAddress.js"
+import { getUserOperationHash } from "../../utils/getUserOperationHash.js"
+import type { SmartAccount } from "../types.js"
+import {
+    SignTransactionNotSupportedBySmartAccount,
+    type SmartAccountSigner
+} from "../types.js"
+import { KernelExecuteAbi, KernelInitAbi } from "./abi/KernelAccountAbi.js"
+
+export type KernelEcdsaSmartAccount<
+    transport extends Transport = Transport,
+    chain extends Chain | undefined = Chain | undefined
+> = SmartAccount<"kernelEcdsaSmartAccount", transport, chain>
+
+/**
+ * The account creation ABI for a kernel smart account (from the KernelFactory)
+ */
+const createAccountAbi = [
+    {
+        inputs: [
+            {
+                internalType: "address",
+                name: "_implementation",
+                type: "address"
+            },
+            {
+                internalType: "bytes",
+                name: "_data",
+                type: "bytes"
+            },
+            {
+                internalType: "uint256",
+                name: "_index",
+                type: "uint256"
+            }
+        ],
+        name: "createAccount",
+        outputs: [
+            {
+                internalType: "address",
+                name: "proxy",
+                type: "address"
+            }
+        ],
+        stateMutability: "payable",
+        type: "function"
+    }
+] as const
+
+/**
+ * Default addresses for kernel smart account
+ */
+const KERNEL_ADDRESSES: {
+    ECDSA_VALIDATOR: Address
+    ACCOUNT_V2_2_LOGIC: Address
+    FACTORY_ADDRESS: Address
+} = {
+    ECDSA_VALIDATOR: "0xd9AB5096a832b9ce79914329DAEE236f8Eea0390",
+    ACCOUNT_V2_2_LOGIC: "0x0DA6a956B9488eD4dd761E59f52FDc6c8068E6B5",
+    FACTORY_ADDRESS: "0x5de4839a76cf55d0c90e2061ef4386d962E15ae3"
+}
+
+/**
+ * Get the account initialization code for a kernel smart account
+ * @param owner
+ * @param index
+ * @param factoryAddress
+ * @param accountLogicAddress
+ * @param ecdsaValidatorAddress
+ */
+const getAccountInitCode = async ({
+    owner,
+    index,
+    factoryAddress,
+    accountLogicAddress,
+    ecdsaValidatorAddress
+}: {
+    owner: Address
+    index: bigint
+    factoryAddress: Address
+    accountLogicAddress: Address
+    ecdsaValidatorAddress: Address
+}): Promise<Hex> => {
+    if (!owner) throw new Error("Owner account not found")
+
+    // Build the account initialization data
+    const initialisationData = encodeFunctionData({
+        abi: KernelInitAbi,
+        functionName: "initialize",
+        args: [ecdsaValidatorAddress, owner]
+    })
+
+    // Build the account init code
+    return concatHex([
+        factoryAddress,
+        encodeFunctionData({
+            abi: createAccountAbi,
+            functionName: "createAccount",
+            args: [accountLogicAddress, initialisationData, index]
+        }) as Hex
+    ])
+}
+
+/**
+ * Check the validity of an existing account address, or fetch the pre-deterministic account address for a kernel smart wallet
+ * @param client
+ * @param owner
+ * @param entryPoint
+ * @param ecdsaValidatorAddress
+ * @param initCodeProvider
+ * @param deployedAccountAddress
+ */
+const getAccountAddress = async <
+    TTransport extends Transport = Transport,
+    TChain extends Chain | undefined = Chain | undefined
+>({
+    client,
+    owner,
+    entryPoint,
+    initCodeProvider,
+    ecdsaValidatorAddress,
+    deployedAccountAddress
+}: {
+    client: Client<TTransport, TChain>
+    owner: Address
+    initCodeProvider: () => Promise<Hex>
+    entryPoint: Address
+    ecdsaValidatorAddress: Address
+    deployedAccountAddress?: Address
+}): Promise<Address> => {
+    // If we got an already deployed account, ensure it's well deployed, and the validator & signer are correct
+    if (deployedAccountAddress !== undefined) {
+        // Get the owner of the deployed account, ensure it's the same as the owner given in params
+        const deployedAccountOwner = await readContract(client, {
+            address: ecdsaValidatorAddress,
+            abi: [
+                {
+                    inputs: [
+                        {
+                            internalType: "address",
+                            name: "",
+                            type: "address"
+                        }
+                    ],
+                    name: "ecdsaValidatorStorage",
+                    outputs: [
+                        {
+                            internalType: "address",
+                            name: "owner",
+                            type: "address"
+                        }
+                    ],
+                    stateMutability: "view",
+                    type: "function"
+                }
+            ],
+            functionName: "ecdsaValidatorStorage",
+            args: [deployedAccountAddress]
+        })
+
+        // Ensure the address match
+        if (!isAddressEqual(deployedAccountOwner, owner)) {
+            throw new Error("Invalid owner for the already deployed account")
+        }
+
+        // If ok, return the address
+        return deployedAccountAddress
+    }
+
+    // Find the init code for this account
+    const initCode = await initCodeProvider()
+
+    // Get the sender address based on the init code
+    return getSenderAddress(client, {
+        initCode,
+        entryPoint
+    })
+}
+
+/**
+ * Build a kernel smart account from a private key, that use the ECDSA signer behind the scene
+ * @param client
+ * @param privateKey
+ * @param entryPoint
+ * @param index
+ * @param factoryAddress
+ * @param accountLogicAddress
+ * @param ecdsaValidatorAddress
+ * @param deployedAccountAddress
+ */
+export async function signerToEcdsaKernelSmartAccount<
+    TTransport extends Transport = Transport,
+    TChain extends Chain | undefined = Chain | undefined
+>(
+    client: Client<TTransport, TChain>,
+    {
+        signer,
+        entryPoint,
+        index = 0n,
+        factoryAddress = KERNEL_ADDRESSES.FACTORY_ADDRESS,
+        accountLogicAddress = KERNEL_ADDRESSES.ACCOUNT_V2_2_LOGIC,
+        ecdsaValidatorAddress = KERNEL_ADDRESSES.ECDSA_VALIDATOR,
+        deployedAccountAddress
+    }: {
+        signer: SmartAccountSigner
+        entryPoint: Address
+        index?: bigint
+        factoryAddress?: Address
+        accountLogicAddress?: Address
+        ecdsaValidatorAddress?: Address
+        deployedAccountAddress?: Address
+    }
+): Promise<KernelEcdsaSmartAccount<TTransport, TChain>> {
+    // Get the private key related account
+    const viemSigner: Account =
+        signer.type === "local"
+            ? ({
+                  ...signer,
+                  signTransaction: (_, __) => {
+                      throw new SignTransactionNotSupportedBySmartAccount()
+                  }
+              } as Account)
+            : (signer as Account)
+
+    // Helper to generate the init code for the smart account
+    const generateInitCode = () =>
+        getAccountInitCode({
+            owner: viemSigner.address,
+            index,
+            factoryAddress,
+            accountLogicAddress,
+            ecdsaValidatorAddress
+        })
+
+    // Fetch account address and chain id
+    const [accountAddress, chainId] = await Promise.all([
+        getAccountAddress<TTransport, TChain>({
+            client,
+            entryPoint,
+            owner: viemSigner.address,
+            ecdsaValidatorAddress,
+            initCodeProvider: generateInitCode,
+            deployedAccountAddress
+        }),
+        getChainId(client)
+    ])
+
+    if (!accountAddress) throw new Error("Account address not found")
+
+    // Build the EOA Signer
+    const account = toAccount({
+        address: accountAddress,
+        async signMessage({ message }) {
+            return signMessage(client, { account: viemSigner, message })
+        },
+        async signTransaction(_, __) {
+            throw new SignTransactionNotSupportedBySmartAccount()
+        },
+        async signTypedData(typedData) {
+            return signTypedData(client, { account: viemSigner, ...typedData })
+        }
+    })
+
+    return {
+        ...account,
+        client: client,
+        publicKey: accountAddress,
+        entryPoint: entryPoint,
+        source: "kernelEcdsaSmartAccount",
+
+        // Get the nonce of the smart account
+        async getNonce() {
+            return getAccountNonce(client, {
+                sender: accountAddress,
+                entryPoint: entryPoint
+            })
+        },
+
+        // Sign a user operation
+        async signUserOperation(userOperation) {
+            const hash = getUserOperationHash({
+                userOperation: {
+                    ...userOperation,
+                    signature: "0x"
+                },
+                entryPoint: entryPoint,
+                chainId: chainId
+            })
+            const signature = await signMessage(client, {
+                account: viemSigner,
+                message: { raw: hash }
+            })
+            // Always use the sudo mode, since we will use external paymaster
+            return concatHex(["0x00000000", signature])
+        },
+
+        // Encode the init code
+        async getInitCode() {
+            const contractCode = await getBytecode(client, {
+                address: accountAddress
+            })
+
+            if ((contractCode?.length ?? 0) > 2) return "0x"
+
+            return generateInitCode()
+        },
+
+        // Encode the deploy call data
+        async encodeDeployCallData(_) {
+            throw new Error("Simple account doesn't support account deployment")
+        },
+
+        // Encode a call
+        async encodeCallData(_tx) {
+            if (Array.isArray(_tx)) {
+                // Encode a batched call
+                return encodeFunctionData({
+                    abi: KernelExecuteAbi,
+                    functionName: "executeBatch",
+                    args: [
+                        _tx.map((tx) => ({
+                            to: tx.to,
+                            value: tx.value,
+                            data: tx.data
+                        }))
+                    ]
+                })
+            } else {
+                // Encode a simple call
+                return encodeFunctionData({
+                    abi: KernelExecuteAbi,
+                    functionName: "execute",
+                    args: [_tx.to, _tx.value, _tx.data, 0]
+                })
+            }
+        },
+
+        // Get simple dummy signature
+        async getDummySignature() {
+            return "0x00000000fffffffffffffffffffffffffffffff0000000000000000000000000000000007aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa1c"
+        }
+    }
+}

package/accounts/signerToSafeSmartAccount.ts

@@ -61,8 +61,8 @@ const SAFE_VERSION_TO_ADDRESSES_MAP: {
     }
 } = {
     "1.4.1": {
-        ADD_MODULES_LIB_ADDRESS: "0x191EFDC03615B575922289DC339F4c70aC5C30Af",
-        SAFE_4337_MODULE_ADDRESS: "0x39E54Bb2b3Aa444b4B39DEe15De3b7809c36Fc38",
+        ADD_MODULES_LIB_ADDRESS: "0x8EcD4ec46D4D2a6B64fE960B3D64e8B94B2234eb",
+        SAFE_4337_MODULE_ADDRESS: "0xa581c4A4DB7175302464fF3C06380BC3270b4037",
         SAFE_PROXY_FACTORY_ADDRESS:
             "0x4e1DCf7AD4e460CfD30791CCC4F9c8a4f820ec67",
         SAFE_SINGLETON_ADDRESS: "0x41675C099F32341bf84BFc5382aF534df5C7461a",

package/actions/pimlico/sponsorUserOperation.ts

@@ -7,7 +7,7 @@ import type {
 } from "../../types/userOperation.js"
 import { deepHexlify } from "../../utils/deepHexlify.js"
 
-export type SponsorUserOperationParameters = {
+export type PimlocoSponsorUserOperationParameters = {
     userOperation: PartialBy<
         UserOperation,
         | "callGasLimit"
@@ -16,6 +16,7 @@ export type SponsorUserOperationParameters = {
         | "paymasterAndData"
     >
     entryPoint: Address
+    sponsorshipPolicyId?: string
 }
 
 export type SponsorUserOperationReturnType = {
@@ -31,7 +32,7 @@ export type SponsorUserOperationReturnType = {
  * - Docs: https://docs.pimlico.io/permissionless/reference/pimlico-paymaster-actions/sponsorUserOperation
  *
  * @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.
+ * @param args {@link PimlocoSponsorUserOperationParameters} UserOperation you want to sponsor & entryPoint.
  * @returns paymasterAndData & updated gas parameters, see {@link SponsorUserOperationReturnType}
  *
  *
@@ -56,14 +57,26 @@ export const sponsorUserOperation = async <
     TAccount extends Account | undefined = Account | undefined
 >(
     client: Client<TTransport, TChain, TAccount, PimlicoPaymasterRpcSchema>,
-    args: SponsorUserOperationParameters
+    args: PimlocoSponsorUserOperationParameters
 ): Promise<SponsorUserOperationReturnType> => {
     const response = await client.request({
         method: "pm_sponsorUserOperation",
-        params: [
-            deepHexlify(args.userOperation) as UserOperationWithBigIntAsHex,
-            args.entryPoint
-        ]
+        params: args.sponsorshipPolicyId
+            ? [
+                  deepHexlify(
+                      args.userOperation
+                  ) as UserOperationWithBigIntAsHex,
+                  args.entryPoint,
+                  {
+                      sponsorshipPolicyId: args.sponsorshipPolicyId
+                  }
+              ]
+            : [
+                  deepHexlify(
+                      args.userOperation
+                  ) as UserOperationWithBigIntAsHex,
+                  args.entryPoint
+              ]
     })
 
     return {

package/actions/pimlico/validateSponsorshipPolicies.ts

@@ -0,0 +1,76 @@
+import type { Account, Address, Chain, Client, Transport } from "viem"
+import type { PimlicoPaymasterRpcSchema } from "../../types/pimlico.js"
+import type {
+    UserOperation,
+    UserOperationWithBigIntAsHex
+} from "../../types/userOperation.js"
+import { deepHexlify } from "../../utils/deepHexlify.js"
+
+export type ValidateSponsorshipPoliciesParameters = {
+    userOperation: UserOperation
+    entryPoint: Address
+    sponsorshipPolicyIds: string[]
+}
+
+export type ValidateSponsorshipPoliciesReturnType = {
+    sponsorshipPolicyId: string
+    data: {
+        name: string | null
+        author: string | null
+        icon: string | null
+        description: string | null
+    }
+}[]
+
+/**
+ * Returns valid sponsorship policies for a userOperation from the list of ids passed
+ * - Docs: https://docs.pimlico.io/permissionless/reference/pimlico-paymaster-actions/ValidateSponsorshipPolicies
+ *
+ * @param client {@link PimlicoBundlerClient} that you created using viem's createClient whose transport url is pointing to the Pimlico's bundler.
+ * @param args {@link ValidateSponsorshipPoliciesParameters} UserOperation you want to sponsor & entryPoint.
+ * @returns valid sponsorship policies, see {@link ValidateSponsorshipPoliciesReturnType}
+ *
+ * @example
+ * import { createClient } from "viem"
+ * import { validateSponsorshipPolicies } from "permissionless/actions/pimlico"
+ *
+ * const bundlerClient = createClient({
+ *   chain: goerli,
+ *   transport: http("https://api.pimlico.io/v2/goerli/rpc?apikey=YOUR_API_KEY_HERE")
+ * })
+ *
+ * await validateSponsorshipPolicies(bundlerClient, {
+ *   userOperation: userOperationWithDummySignature,
+ *   entryPoint: entryPoint,
+ *   sponsorshipPolicyIds: ["sp_shiny_puma"]
+ * })
+ * Returns
+ * [
+ *   {
+ *     sponsorshipPolicyId: "sp_shiny_puma",
+ *     data: {
+ *       name: "Shiny Puma",
+ *       author: "Pimlico",
+ *       icon: "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAUAAAAFCAYAAACNbyblAAAAHElEQVQI12P4...",
+ *       description: "This policy is for testing purposes only"
+ *    }
+ *   }
+ * ]
+ */
+export const validateSponsorshipPolicies = async <
+    TTransport extends Transport = Transport,
+    TChain extends Chain | undefined = Chain | undefined,
+    TAccount extends Account | undefined = Account | undefined
+>(
+    client: Client<TTransport, TChain, TAccount, PimlicoPaymasterRpcSchema>,
+    args: ValidateSponsorshipPoliciesParameters
+): Promise<ValidateSponsorshipPoliciesReturnType> => {
+    return await client.request({
+        method: "pm_validateSponsorshipPolicies",
+        params: [
+            deepHexlify(args.userOperation) as UserOperationWithBigIntAsHex,
+            args.entryPoint,
+            args.sponsorshipPolicyIds
+        ]
+    })
+}

package/actions/pimlico.ts

@@ -8,7 +8,7 @@ import {
     getUserOperationStatus
 } from "./pimlico/getUserOperationStatus.js"
 import {
-    type SponsorUserOperationParameters,
+    type PimlocoSponsorUserOperationParameters,
     type SponsorUserOperationReturnType,
     sponsorUserOperation
 } from "./pimlico/sponsorUserOperation.js"
@@ -22,14 +22,22 @@ import {
     pimlicoPaymasterActions
 } from "../clients/decorators/pimlico.js"
 
+import {
+    type ValidateSponsorshipPoliciesParameters,
+    type ValidateSponsorshipPoliciesReturnType,
+    validateSponsorshipPolicies
+} from "./pimlico/validateSponsorshipPolicies.js"
+
 export type {
     GetUserOperationGasPriceReturnType,
     GetUserOperationStatusParameters,
     GetUserOperationStatusReturnType,
-    SponsorUserOperationParameters,
+    PimlocoSponsorUserOperationParameters,
     SponsorUserOperationReturnType,
     PimlicoBundlerActions,
-    PimlicoPaymasterClientActions
+    PimlicoPaymasterClientActions,
+    ValidateSponsorshipPoliciesParameters,
+    ValidateSponsorshipPoliciesReturnType
 }
 
 export {
@@ -37,5 +45,6 @@ export {
     getUserOperationStatus,
     sponsorUserOperation,
     pimlicoBundlerActions,
-    pimlicoPaymasterActions
+    pimlicoPaymasterActions,
+    validateSponsorshipPolicies
 }

package/clients/createSmartAccountClient.ts

@@ -16,6 +16,11 @@ import {
     smartAccountActions
 } from "./decorators/smartAccount.js"
 
+/**
+ * TODO:
+ *  - Add docs
+ *  - Fix typing, 'accounts' is required to signMessage, signTypedData, signTransaction, but not needed here, since account is embedded in the client
+ */
 export type SmartAccountClient<
     transport extends Transport = Transport,
     chain extends Chain | undefined = Chain | undefined,
@@ -54,7 +59,7 @@ export type SmartAccountClientConfig<
  *
  * 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.
  *
- * @param config - {@link WalletClientConfig}
+ * @param parameters - {@link WalletClientConfig}
  * @returns A Bundler Client. {@link SmartAccountClient}
  *
  * @example

package/clients/decorators/pimlico.ts

@@ -1,4 +1,9 @@
 import type { Client, Hash } from "viem"
+import {
+    type ValidateSponsorshipPoliciesParameters,
+    type ValidateSponsorshipPoliciesReturnType,
+    validateSponsorshipPolicies
+} from "../../actions/pimlico.js"
 import {
     type GetUserOperationGasPriceReturnType,
     getUserOperationGasPrice
@@ -9,7 +14,7 @@ import {
     getUserOperationStatus
 } from "../../actions/pimlico/getUserOperationStatus.js"
 import {
-    type SponsorUserOperationParameters,
+    type PimlocoSponsorUserOperationParameters,
     type SponsorUserOperationReturnType,
     sponsorUserOperation
 } from "../../actions/pimlico/sponsorUserOperation.js"
@@ -78,7 +83,7 @@ export type PimlicoPaymasterClientActions = {
      *
      * https://docs.pimlico.io/permissionless/reference/pimlico-paymaster-actions/sponsorUserOperation
      *
-     * @param args {@link SponsorUserOperationParameters} UserOperation you want to sponsor & entryPoint.
+     * @param args {@link PimlocoSponsorUserOperationParameters} UserOperation you want to sponsor & entryPoint.
      * @returns paymasterAndData & updated gas parameters, see {@link SponsorUserOperationReturnType}
      *
      * @example
@@ -97,15 +102,57 @@ export type PimlicoPaymasterClientActions = {
      *
      */
     sponsorUserOperation: (
-        args: SponsorUserOperationParameters
+        args: PimlocoSponsorUserOperationParameters
     ) => Promise<SponsorUserOperationReturnType>
+
+    validateSponsorshipPolicies: (
+        args: ValidateSponsorshipPoliciesParameters
+    ) => Promise<ValidateSponsorshipPoliciesReturnType>
 }
 
+/**
+ * Returns valid sponsorship policies for a userOperation from the list of ids passed
+ * - Docs: https://docs.pimlico.io/permissionless/reference/pimlico-paymaster-actions/ValidateSponsorshipPolicies
+ *
+ * @param args {@link ValidateSponsorshipPoliciesParameters} UserOperation you want to sponsor & entryPoint.
+ * @returns valid sponsorship policies, see {@link ValidateSponsorshipPoliciesReturnType}
+ *
+ * @example
+ * import { createClient } from "viem"
+ * import { validateSponsorshipPolicies } 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.validateSponsorshipPolicies({
+ *   userOperation: userOperationWithDummySignature,
+ *   entryPoint: entryPoint,
+ *   sponsorshipPolicyIds: ["sp_shiny_puma"]
+ * })
+ * Returns
+ * [
+ *   {
+ *     sponsorshipPolicyId: "sp_shiny_puma",
+ *     data: {
+ *       name: "Shiny Puma",
+ *       author: "Pimlico",
+ *       icon: "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAUAAAAFCAYAAACNbyblAAAAHElEQVQI12P4...",
+ *       description: "This policy is for testing purposes only"
+ *    }
+ *   }
+ * ]
+ */
 export const pimlicoPaymasterActions = (
     client: Client
 ): PimlicoPaymasterClientActions => ({
-    sponsorUserOperation: async (args: SponsorUserOperationParameters) =>
-        sponsorUserOperation(client as PimlicoPaymasterClient, args)
+    sponsorUserOperation: async (args: PimlocoSponsorUserOperationParameters) =>
+        sponsorUserOperation(client as PimlicoPaymasterClient, args),
+    validateSponsorshipPolicies: async (
+        args: ValidateSponsorshipPoliciesParameters
+    ) => validateSponsorshipPolicies(client as PimlicoPaymasterClient, args)
 })
 
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "permissionless",
-    "version": "0.0.13",
+    "version": "0.0.15",
     "author": "Pimlico",
     "main": "./_cjs/index.js",
     "module": "./_esm/index.js",