Getting started

A collection of example scripts for working with ERC-4337. For an overview on the EIP and account abstraction, see our docs here.

The implementation for all commands are located in the scripts directory. All scripts are built with the following libraries:

• Sample contracts: eth-infinitism/account-abstraction
• JS SDK: userop.js

🚀 Looking for access to hosted infrastructure to build your Smart Accounts? Check out stackup.sh!

Table of contents

• Setup
  • Init config
    • rpcUrl
    • signingKey
    • entryPoint
    • simpleAccountFactory
    • paymaster
• Commands
  • Simple Account
    • Get account address
    • Transfer ETH
    • Transfer ERC-20 token
    • Approve ERC-20 token
    • Batch transfer ERC-20 token
• License
• Contact

Setup

Clone this repo into your local environment:

git clone [email protected]:stackup-wallet/erc-4337-examples.git

Install dependencies:

yarn install

Init config

These config values will be used for all documented commands.

yarn run init

rpcUrl

Default value is set to https://api.stackup.sh/v1/node/API_KEY.

This is a standard RPC URL for an ethereum node that also supports all ERC-4337 bundler methods. By default it uses the stackup endpoint. You will need to fill in your API key from the Stackup dashboard. Alternatively you can also use any RPC url that is also enabled as a bundler.

signingKey

Default value is randomly generated with ethers.js.

All UserOperations have a signature field which smart contract accounts will use to validate transactions. This key will be used to sign all UserOperations and set as the owner for the smart contract account.

entryPoint

Default value is set to 0x5FF137D4b0FDCD49DcA30c7CF57E578a026d2789.

This is address of the singleton EntryPoint contract. It is the same on all networks.

simpleAccountFactory

Default value is set to 0x9406Cc6185a346906296840746125a0E44976454.

This is the factory address for deploying SimpleAccount.sol. It is the same on all networks and allows us to generate deterministic addresses.

paymaster

This is an object with fields related to a paymaster entity.

rpcUrl

Default value is set to https://api.stackup.sh/v1/paymaster/API_KEY

This field specifies the URL to request paymaster approval when using the --withPaymaster flag. The examples assume that any paymaster service follows the interface specified here.

context

Default value is an empty object.

This arbitrary object is passed as the last parameter when calling pm_sponsorUserOperation. It's content will depend on the the specific paymaster you're interacting with.

Commands

Once you have an environment setup, these commands can be used for running the example scripts.

The location of each script mimics the command structure. For example yarn run simpleAccount address will be located in scripts/simpleAccount/address.ts

Optional flags

All commands below can be augmented with the following flags.

Dry run

Appending --dryRun will go through the whole process of making a UserOperation, but will not call eth_sendUserOperation. This is useful for debugging purposes to see what the final UserOperation looks like.

With Paymaster

Appending --withPaymaster will call pm_sponsorUserOperation on paymaster.rpcUrl with the UserOperation, EntryPoint, and paymaster.context. If successful, gas for this transaction will be paid for by the paymaster.

Example:

yarn run simpleAccount:erc20Transfer --withPaymaster ...

In this example, the contract account does not need to hold any ETH for gas fees.

---

Simple Account

Scripts for managing accounts based on SimpleAccount.sol.

For CLI details:

yarn run simpleAccount -h

Get account address

Smart contract account addresses can be deterministically generated. Use this command to get your account address based on the signingKey set in your config.json.

The account will be automatically deployed on the first transaction.

yarn run simpleAccount address

Transfer ETH

Before executing a transfer, make sure to deposit some ETH to the address generated by the simpleAccount address command.

yarn run simpleAccount transfer --to <address> --amount <eth>

Transfer ERC-20 token

Make sure the address generated by simpleAccount:address has enough specified tokens to execute the transfer.

If not using a paymaster, make sure to also have enough ETH to pay gas fees.

yarn run simpleAccount erc20Transfer --token <address> --to <address> --amount <decimal>

Approve ERC-20 token

If not using a paymaster, make sure to also have enough ETH to pay gas fees.

yarn run simpleAccount erc20Approve --token <address> --spender <address> --amount <decimal>

Batch transfer ERC-20 token

This command allows you to do multiple atomic contract interactions in a single transaction. The example shows us how with an ERC-20 token.

# recipient addresses is comma separated.
# e.g. 0x123..abc,0x456...def
yarn run simpleAccount batchErc20Transfer --token <address> --to <addresses> --amount <decimal>

---

License

Distributed under the MIT License. See LICENSE for more information.

Contact

Feel free to direct any technical related questions to the dev-hub channel in the Stackup Discord.