Permissionless.js Detailed Guide

Contracts

In this guide, we will use some specific versions for the following contracts deployed on Gnosis Chain.

• v0.6.0 EntryPoint
• v1.4.1 Safe Smart Account
• v0.2.0 Safe4337Module
• v0.2.0 AddModuleLib

Check the commented links in the code snippet to get the correct addresses if you use a different network.

Imports

These are all the imports required in the script we are building for this guide, which includes permissionless and viem packages.

Create a signer

First, we need a signer instance that will be the owner of the Safe account once it is deployed.

Initialize the clients

We need to create a few client instances to query the blockchain network and operate with Pimlico infrastructure.

Firstly, we instantiate a standard publicClient instance for regular Ethereum RPC calls. To do this, we must first define the corresponding RPC URL depending on our network.

Secondly, we instantiate the bundlerClient using the Pimlico API v1, which is dedicated to the Bundler methods. This API requires a PIMLICO_API_KEY that we can get from their dashboard (opens in a new tab).

Lastly, we instantiate the pimlicoPaymasterClient using the Pimlico API v2, which is dedicated to the Paymaster methods and responsible for interacting with Pimlico's Verifying Paymaster endpoint and requesting sponsorship.

Create a UserOperation

We now define the user operation object we want to execute following the structure of the UserOperation type.

We are currently missing the values for the sender, nonce, initCode, and callData properties, so we need to calculate them. The gas-related properties will be calculated later in the next step, and the signature in the following one.

After getting these properties, we can instantiate the sponsoredUserOperation object.

Get the initCode

The initCode encodes the instructions for deploying the ERC-4337 smart account. For this reason, it's not needed when the account has already been deployed.

If we are deploying a new account, we can calculate it with the getAccountInitCode utility function defined in the second tab, which returns the concatenation of the SafeProxyFactory contract address and the initCodeCallData.

The initCodeCallData encodes the call to the createProxyWithNonce function in the SafeProxyFactory contract with the initializer and a saltNonce.

The initializer is calculated using the getInitializerCode function from its corresponding tab. This function returns the encoding of the call to the setup function in the Safe contract to initialize the account with its owners, threshold, fallbackHandler, etc.

In this case, we are creating a Safe account with one owner (our signer), threshold one, and the Safe4337Module as the fallbackHandler.

This initialization also includes the option to execute a call by using the to and data parameters, which we will use to enable the Safe4337Module contract in the Safe and give an allowance to the EntryPoint contract to pay the gas fees in an ERC-20 token like USDC. As we are performing multiple calls, we need to encode a call to the MultiSend contract using the encodeMultiSend function, setting the SAFE_MULTISEND_ADDRESS as the to and its encoding as the data.

To enable the module in the enableModuleCallData function, we will encode a call to the AddModuleLib contract by passing the address of the Safe4337Module.

In case of doing the token approval to the EntryPoint contract, check the list of ERC-20 Pimlico paymasters and USDC tokens addresses (opens in a new tab) to select the correct addresses for these contracts depending on the network.

Get the Safe address

We implemented the getAccountAddress utility function to calculate the' sender'. This function calls the viem getContractAddress function to get the address based on:

• The SAFE_PROXY_FACTORY_ADDRESS
• The bytecode of the deployed contract (the Safe Proxy)
• The saltNonce

Notice that the sender address will depend on the value of the Safe configuration properties and the saltNonce.

After calculating the predicted address of the counterfactual ERC-4337 Safe account, the sender, we can check on the Gnosis Chain block explorer (opens in a new tab) that the account is not deployed yet.

Get the nonce

To get the nonce, we can use the getAccountNonce function.

Get the callData

The callData encodes a call to the executeUserOp function and represents the action(s) that will be executed from the Safe account. In this example we are sending a transaction to the Safe account with no value and no data, resulting in an increase of the nonce of the account. However, this can be any action like a transfer of the native or an ERC-20 token, a call to another contract, etc.

Check the encodeCallData tab to see how the encoding is implemented.

Estimate the UserOperation gas

To estimate the gas limits for a user operation, we call the estimateUserOperationGas method from the bundler API, which receives the userOperation object and entryPoint as parameters.

After that, we call the getUserOperationGasPrice method to get the maximum gas price and add all the returned values to the sponsoredUserOperation.

To use the Paymaster to pay for the fees, we need to provide a SPONSORSHIP_POLICY_ID that can be provided by a third party willing to sponsor our user operations, or it can be generated in the Pimlico dashboard (opens in a new tab). Sponsorship policies allow the definition of custom rules for sponsorships with various options to limit the total sponsored amount, per user, and per user operation.

On top of that, we need to overwrite some gas values from the Paymaster and add the paymasterAndData to the sponsoredUserOperation.

If we don't want to use a Paymaster to pay the gas fees, we need to ensure the Safe account holds at least a few USDC tokens because the fees would be extracted from the Safe itself. Be cautious with the amount as it will depend on the callData, and the network gasPrice.

Sign the UserOperation

To sign the sponsoredUserOperation, we have created the signUserOperation utility function that returns the signature from the signer and accepts the following parameters. Check the second tab to see its implementation.

Submit the UserOperation

Call the sendUserOperation method from the bundler to submit the sponsoredUserOperation to the EntryPoint contract.

To get more details about the submitted UserOperation object copy the value of the userOperationHash returned, visit the UserOp Explorer (opens in a new tab), and paste it into the search bar.

Lastly, to get more details about the transaction, we can get the receipt of the sponsoredUserOperation, get the transactionHash, and check the transaction details in the Gnosis Chain block explorer (opens in a new tab).