Forem: Nikhil

Developer’s Guide to ERC-4337 #2 | Testing Simple Account

Nikhil — Wed, 09 Oct 2024 11:45:33 +0000

This is part 2 of the “Developer’s Guide to ERC-4337” series. If you haven’t read the last article, check it out here: Developer's Guide to ERC-4337: Developing a Simple Account.

Many tutorials focus on how to use or work with new technologies, but often skip the important part—testing. Figuring out how to test on your own can be a valuable learning opportunity, solidifying your knowledge and clearing up any confusion you might have had before.

In the last article of this series, we developed a simple ERC-4337-compliant account contract. Now, in this article, we’re going to write unit tests for it. I'll first outline the test cases, and then you can either write the tests yourself or follow along with this guide.

What Should We Test For?

The approach I recommend is to start with basic checks, like verifying state variables and simple functions, then move on to more complex functions with multiple components. Here are the test cases:

Check Initialization of i_entryPoint and i_owner: Verify that the contract initializes and stores i_entryPoint and i_owner correctly after deployment.
Access control check for the execute function: Ensure the execute function only works when called by the correct i_entryPoint and reverts otherwise.
Check successful execution of the execute function: Ensure the execute function successfully forwards a call to the destination when invoked by the correct entry point.
Check failure handling in the execute function: Verify that the execute function reverts with SimpleAccount__CallFailed when the destination call fails.
Signature validation with correct owner signature: Confirm that the _validateSignature function returns SIG_VALIDATION_SUCCESS for a valid owner signature.
Signature validation with incorrect owner signature: Ensure the _validateSignature function returns SIG_VALIDATION_FAILED for an invalid owner signature.

Are all of these important? Yes and no. Our contract isn’t very complex, so there aren’t many ways things can go wrong. However, writing tests for as much as possible will build good habits. By the time you start working on more complex contracts, the habit of thorough testing will stick with you, and you'll be less likely to overlook mistakes.

We’ll aim for 100% test coverage for this contract, which is feasible in our case. In general, achieving 90% coverage is a good goal to have.

Unit Testing

Let’s start writing our tests. First, we need to set up our testing environment. If you’re unfamiliar with testing in Foundry, I recommend reading the relevant section of the Foundry documentation. We’ll write our tests in a file called SimpleAccountTest.t.sol, so go ahead and create that file in your test folder.

All tests will be placed in a contract, which we’ll call SimpleAccountTest.

// SPDX-License-Identifier: MIT
pragma solidity 0.8.24;

contract SimpleAccountTest {}

This contract will inherit the Test contract from the forge-std library, which includes helpful functions for testing. Let’s import the Test contract and extend it in our SimpleAccountTest contract.

import {Test} from "forge-std/Test.sol";

contract SimpleAccountTest is Test {}

Testing Internal Functions

Before we dive into the tests, let’s briefly discuss testing internal functions. Testing external and public functions is straightforward because they’re designed for external interaction. However, testing internal or private functions can be tricky.

For private functions, testing isn’t possible unless you copy-paste the code into the test, which isn’t ideal. But internal functions are inheritable, meaning we can create a contract that inherits the original contract and exposes the internal functions as public for testing purposes. These are called "harness" contracts.

Let’s create a harness contract for SimpleAccount that exposes the _validateSignature function. We’ll call this contract SimpleAccountHarness, and it will be the contract we use for testing since it includes all the functions from SimpleAccount, plus some additional ones. Add the following contract to the same file:

import {SimpleAccount} from "src/SimpleAccount.sol";
import {PackedUserOperation} from "account-abstraction/interfaces/PackedUserOperation.sol";

contract SimpleAccountHarness is SimpleAccount {
    constructor(address entryPoint, address owner) SimpleAccount(entryPoint, owner) {}

    // exposes `_validateSignature` for testing
    function validateSignature(PackedUserOperation calldata userOp, bytes32 userOpHash)
        external
        view
        returns (uint256)
    {
        return _validateSignature(userOp, userOpHash);
    }
}

To use SimpleAccount and expose its methods, we need to import both SimpleAccount and PackedUserOperation. We inherit from SimpleAccount, meaning we need to satisfy its constructor. Just like SimpleAccount, we pass the entry point contract’s address and the account owner’s address to the constructor.

Next, we create the validateSignature function, which has almost the same definition as _validateSignature but with external visibility. This allows us to expose the internal function for testing. We then pass the function’s arguments to _validateSignature and return its result.

`setUp` Function

To start writing tests, we first need a setUp function. This is a function that Forge automatically runs before each test to set up the necessary conditions, like deploying contracts or creating dummy users. In our setUp function, we will:

Create an instance of the EntryPoint contract.
Create two accounts: one for the owner and one for random users.
Create an instance of SimpleAccountHarness.

To deploy EntryPoint, we first need to import it from account-abstraction:

import {EntryPoint} from "account-abstraction/core/EntryPoint.sol";

We'll store these contract instances and accounts in state variables so they can be accessed by the test functions:

contract SimpleAccountTest is Test {
    SimpleAccountHarness private simpleAccountHarness;
    EntryPoint private entryPoint;

    Account owner;
    Account randomUser;
}

Next, we'll create instances of the contracts and two accounts using Foundry’s cheat code makeAccount. This cheat code generates an address and private key for each account, which we’ll use in our tests:

function setUp() external {
    owner = makeAccount("owner");
    randomUser = makeAccount("randomUser");

    entryPoint = new EntryPoint();
    simpleAccountHarness = new SimpleAccountHarness(address(entryPoint), owner.addr);
    vm.deal(address(simpleAccountHarness), 10 ether);
}

The makeAccount function takes a string to generate a wallet and returns an Account struct. This struct has two fields: addr (the account address) and key (the private key). Both Account and makeAccount are available via StdCheats.sol, which Foundry automatically imports.

For contract instances, we use the new keyword, passing the required constructor arguments. The EntryPoint contract doesn’t require any arguments, but SimpleAccountHarness requires both the entryPoint address and the owner's address, which we get from the addr field of the owner account.

Finally, we add some balance to SimpleAccountHarness using the deal function, which is part of the Forge standard library. This function takes an address and an amount, adding the specified balance to that address. We give SimpleAccountHarness 10 ether, so it can execute actions like sending ether or paying back the entry point for user operations.

Here's what the test contract looks like at this point:

// SPDX-License-Identifier: MIT
pragma solidity 0.8.24;

import {Test} from "forge-std/Test.sol";
import {SimpleAccount} from "src/SimpleAccount.sol";
import {PackedUserOperation} from "account-abstraction/interfaces/PackedUserOperation.sol";
import {EntryPoint} from "account-abstraction/core/EntryPoint.sol";

contract SimpleAccountHarness is SimpleAccount {
    constructor(address entryPoint, address owner) SimpleAccount(entryPoint, owner) {}

    // exposes `_validateSignature` for testing
    function validateSignature(PackedUserOperation calldata userOp, bytes32 userOpHash)
        external
        view
        returns (uint256)
    {
        return _validateSignature(userOp, userOpHash);
    }
}

contract SimpleAccountTest is Test {
    SimpleAccountHarness private simpleAccountHarness;
    EntryPoint private entryPoint;

    Account owner;
    Account randomUser;

    function setUp() external {
        owner = makeAccount("owner");
        randomUser = makeAccount("randomUser");

        entryPoint = new EntryPoint();
        simpleAccountHarness = new SimpleAccountHarness(address(entryPoint), owner.addr);
    }
}

State Variable Check

Let's write our first test to verify if the state variables initialized by the SimpleAccount constructor are set correctly. In the SimpleAccount constructor, we are simply setting the values for entryPoint and owner. Both of these variables have getter functions, so in our test, we'll retrieve their values and compare them to the expected values.

function testStateVariables() public view {
    // Arrange
    // Act
    address contractOwner = simpleAccountHarness.getOwner();
    address contractEntryPoint = address(simpleAccountHarness.entryPoint());
    // Assert
    vm.assertEq(owner.addr, contractOwner);
    vm.assertEq(address(entryPoint), contractEntryPoint);
}

We've written our first test case. To run this test, use the following command:

forge test --mt testStateVariables

`execute` Function & Access Control Checks

In SimpleAccount, the execute function which interact with other accounts and contract. The entryPoint contract directly executes calldata on the account contract, with the calldata being sent through a PackedUserOperation. The dapp will construct calldata with execute function selector and required function arguments. The execute function can only be called by the entryPoint; if anyone else tries to call it, the call should revert.

Let’s test the execute function by sending 1 ether to randomUser and checking if randomUser's balance increases and the account contract's balance decreases. To do this, we need the initial balance for both accounts.

Since only the entryPoint can call the execute function, we will use the cheat code prank to make the call in the test originate from the entryPoint address.

 function testExecuteFunction() public {
    // Arrange
    uint256 initalBalanceOfRandomUser = randomUser.addr.balance;
    uint256 initalBalanceOfAccountContract = address(simpleAccountHarness).balance;

    uint256 valueToSend = 1 ether;
    // Act
    vm.prank(address(entryPoint));
    simpleAccountHarness.execute(randomUser.addr, valueToSend, "");
    // Assert
    vm.assertEq(randomUser.addr.balance, initalBalanceOfRandomUser + valueToSend);
    vm.assertEq(address(simpleAccountHarness).balance, initalBalanceOfAccountContract - valueToSend);
}

Now, let's ensure the function reverts if someone other than the entryPoint calls it. The access control is handled by _requireFromEntryPoint, which reverts with the message "account: not from EntryPoint" if an unauthorized address tries to call it. We'll also check if the correct revert message is returned.

function testExecuteRevertsWithCorrectError() public {
    // Arrange
    uint256 valueToSend = 1 ether;

    // Act + Assert
    vm.prank(randomUser.addr);
    vm.expectRevert(bytes("account: not from EntryPoint")); 
    simpleAccountHarness.execute(randomUser.addr, valueToSend, "");
}

Testing `execute` When Call Fails

Finally, we need to test what happens if the call made by the execute function fails. How do we simulate this?

We’ll create a contract with a fallback function that reverts on every call. You can add this contract below the SimpleAccountHarness contract.

contract RevertsOnEthTransfer {
    fallback() external {
        revert("");
    }
}

To test this, we’ll create an instance of RevertsOnEthTransfer in our test and try to send ether to it, which will cause the call to revert and return the custom error SimpleAccount__CallFailed.

function testCallFromExecuteFails() public {
    // Arrange
    RevertsOnEthTransfer revertsOnEthTransfer = new RevertsOnEthTransfer();

    uint256 valueToSend = 1 ether;

    // Act + Assert
    vm.prank(address(entryPoint)); // execute function needs to be executes from EntryPoint
    vm.expectRevert(SimpleAccount.SimpleAccount__CallFailed.selector);
    simpleAccountHarness.execute(address(revertsOnEthTransfer), valueToSend, "");
}

In the previous test, we passed a string to expectRevert, but here we pass the error selector since SimpleAccount reverts with a custom error when the call fails.

With this, we've covered testing the execute function. Now, we can move on to the final part: testing the validateSignature function, which exposes _validateSignature from SimpleAccount. This part is a bit more complicated but essential to complete the test coverage.

Signature Validation Checks

Before we dive into writing the tests, we first need to create a function that generates a dummy UserOperation and signs it using the private key of the account. Let’s call this function generateAndSignUserOperation.

To get started, import MessageHashUtils from OpenZeppelin, which we'll use to generate the message the user will sign.

import {MessageHashUtils} from "@openzeppelin/contracts/utils/cryptography/MessageHashUtils.sol";

This function will take an argument of type Account, which we need to sign the UserOperation, and return two values: the signed UserOperation of type PackedUserOperation and the UserOperation hash of type bytes32.

function generateSigAndSignedUserOp(Account memory user)
    public
    view
    returns (PackedUserOperation memory, bytes32)
{}

Inside this function, we’ll create a dummy UserOperation with random values. Since we are unit testing _validateSignature, we only care about working with the signature field.

function generateSigAndSignedUserOp(Account memory user)
    public
    view
    returns (PackedUserOperation memory, bytes32)
{

    PackedUserOperation memory userOp = PackedUserOperation({
        sender: address(simpleAccountHarness),
        nonce: 1,
        initCode: hex"",
        callData: hex"",
        accountGasLimits: hex"",
        preVerificationGas: type(uint64).max,
        gasFees: hex"",
        paymasterAndData: hex"",
        signature: hex""
    });

    // Next part
}

The signature field will contain the signature generated by signing the UserOperation hash. This hash is generated using the getUserOpHash function from the EntryPoint contract, which takes a PackedUserOperation as an argument. We’ll pass the UserOperation with an empty signature field. Once the UserOpHash is signed, the signature is added and then sent to the EntryPoint contract for validation and execution.

function generateSigAndSignedUserOp(Account memory user)
    public
    view
    returns (PackedUserOperation memory, bytes32)
{

    PackedUserOperation memory userOp = PackedUserOperation({
        sender: address(simpleAccountHarness),
        nonce: 1,
        initCode: hex"",
        callData: hex"",
        accountGasLimits: hex"",
        preVerificationGas: type(uint64).max,
        gasFees: hex"",
        paymasterAndData: hex"",
        signature: hex""
    });

    bytes32 userOpHash = entryPoint.getUserOpHash(userOp);
    bytes32 formattedUserOpHash = MessageHashUtils.toEthSignedMessageHash(userOpHash);

        // Next Part

}

Next, we need to sign the formattedUserOpHash using the sign function from the Forge standard library. This function takes the message and private key used to sign the message. It returns the v, r, and s components of the signature, which we then encode in r, s, and v order using encodePacked. The signature is finally added to the signature field of userOp. The function will then return the modified userOp and the userOpHash.

function generateSigAndSignedUserOp(Account memory user)
    public
    view
    returns (PackedUserOperation memory, bytes32)
{

    PackedUserOperation memory userOp = PackedUserOperation({
        sender: address(simpleAccountHarness),
        nonce: 1,
        initCode: hex"",
        callData: hex"",
        accountGasLimits: hex"",
        preVerificationGas: type(uint64).max,
        gasFees: hex"",
        paymasterAndData: hex"",
        signature: hex""
    });

    bytes32 userOpHash = entryPoint.getUserOpHash(userOp);
    bytes32 formattedUserOpHash = MessageHashUtils.toEthSignedMessageHash(userOpHash);

    (uint8 v, bytes32 r, bytes32 s) = vm.sign(user.key, formattedUserOpHash);

    userOp.signature = abi.encodePacked(r, s, v);

    return (userOp, userOpHash);
}

Now that we have the generateSigAndSignedUserOp function, let’s write our test cases for _validateSignature. The first test will check if the owner has signed the UserOperation and that the function returns the correct value. The expected success value is SIG_VALIDATION_SUCCESS, which we first need to import.

import { SIG_VALIDATION_SUCCESS} from "account-abstraction/core/Helpers.sol";

In this test, we will use the generateSigAndSignedUserOp function to create a UserOperation, passing in the owner. We’ll then pass the returned userOp and userOpHash to the validateSignature function (which exposes _validateSignature via SimpleAccountHarness). Finally, we’ll check if the return value matches the expected value. Since no state modification happens here, we can make this a view function.

function testValidateSignature() public view {
    // Arrange
    (PackedUserOperation memory userOp, bytes32 userOpHash) = generateSigAndSignedUserOp(owner);
    // Act
    uint256 result = simpleAccountHarness.validateSignature(userOp, userOpHash);
    // Assert
    vm.assertEq(result, SIG_VALIDATION_SUCCESS);
}

The last test case will verify the failure scenario, ensuring that the function returns SIG_VALIDATION_FAILED when the UserOperation is signed with an incorrect user. We need to import the SIG_VALIDATION_FAILED constant from account-abstraction.

import {SIG_VALIDATION_SUCCESS, SIG_VALIDATION_FAILED} from "account-abstraction/core/Helpers.sol";

To test this, we’ll pass randomUser to the generateSigAndSignedUserOp function, and the rest will be similar to the previous test.

function testValidateSignatureWithWrongSignature() public view {
    // Arrange
    (PackedUserOperation memory userOp, bytes32 userOpHash) = generateSigAndSignedUserOp(randomUser);
    // Act
    uint256 result = simpleAccountHarness.validateSignature(userOp, userOpHash);
    // Assert
    vm.assertEq(result, SIG_VALIDATION_FAILED);
}

With these test cases, we have covered the _validateSignature function. Here’s how the final test file should look:

// SPDX-License-Identifier: MIT
pragma solidity 0.8.24;

import {Test} from "forge-std/Test.sol";
import {SimpleAccount} from "src/SimpleAccount.sol";
import {PackedUserOperation} from "account-abstraction/interfaces/PackedUserOperation.sol";
import {EntryPoint} from "account-abstraction/core/EntryPoint.sol";
import {MessageHashUtils} from "@openzeppelin/contracts/utils/cryptography/MessageHashUtils.sol";
import {SIG_VALIDATION_SUCCESS, SIG_VALIDATION_FAILED} from "account-abstraction/core/Helpers.sol";

contract SimpleAccountHarness is SimpleAccount {
    constructor(address entryPoint, address owner) SimpleAccount(entryPoint, owner) {}

    // exposes `_validateSignature` for testing
    function validateSignature(PackedUserOperation calldata userOp, bytes32 userOpHash)
        external
        view
        returns (uint256)
    {
        return _validateSignature(userOp, userOpHash);
    }
}

contract RevertsOnEthTransfer {
    fallback() external {
        revert("");
    }
}

contract SimpleAccountTest is Test {
    SimpleAccountHarness private simpleAccountHarness;
    EntryPoint private entryPoint;

    Account owner;
    Account randomUser;

    function setUp() external {
        owner = makeAccount("owner");
        randomUser = makeAccount("randomUser");

        entryPoint = new EntryPoint();
        simpleAccountHarness = new SimpleAccountHarness(address(entryPoint), owner.addr);
        vm.deal(address(simpleAccountHarness), 10 ether);
    }

    function testStateVariables() public view {
        // Arrange

        // Act
        address contractOwner = simpleAccountHarness.getOwner();
        address contractEntryPoint = address(simpleAccountHarness.entryPoint());

        // Assert
        vm.assertEq(owner.addr, contractOwner);
        vm.assertEq(address(entryPoint), contractEntryPoint);
    }

    function testExecuteFunction() public {
        // Arrange
        uint256 initalBalanceOfRandomUser = randomUser.addr.balance;
        uint256 initalBalanceOfAccountContract = address(simpleAccountHarness).balance;

        uint256 valueToSend = 1 ether;

        // Act
        vm.prank(address(entryPoint));
        simpleAccountHarness.execute(randomUser.addr, valueToSend, "");

        // Assert
        vm.assertEq(randomUser.addr.balance, initalBalanceOfRandomUser + valueToSend);
        vm.assertEq(address(simpleAccountHarness).balance, initalBalanceOfAccountContract - valueToSend);
    }

    function testExecuteRevertsWithCorrectError() public {
        // Arrange
        uint256 valueToSend = 1 ether;

        // Act + Assert
        vm.prank(randomUser.addr);
        vm.expectRevert(bytes("account: not from EntryPoint"));
        simpleAccountHarness.execute(randomUser.addr, valueToSend, "");
    }

    function testCallFromExecuteFails() public {
        // Arrange
        RevertsOnEthTransfer revertsOnEthTransfer = new RevertsOnEthTransfer();

        uint256 valueToSend = 1 ether;

        // Act + Assert
        vm.prank(address(entryPoint)); // execute function needs to be executes from EntryPoint
        vm.expectRevert(SimpleAccount.SimpleAccount__CallFailed.selector);
        simpleAccountHarness.execute(address(revertsOnEthTransfer), valueToSend, "");
    }

    function generateSigAndSignedUserOp(Account memory user)
        public
        view
        returns (PackedUserOperation memory, bytes32)
    {
        PackedUserOperation memory userOp = PackedUserOperation({
            sender: address(simpleAccountHarness),
            nonce: 1,
            initCode: hex"",
            callData: hex"",
            accountGasLimits: hex"",
            preVerificationGas: type(uint64).max,
            gasFees: hex"",
            paymasterAndData: hex"",
            signature: hex""
        });

        bytes32 userOpHash = entryPoint.getUserOpHash(userOp);
        bytes32 formattedUserOpHash = MessageHashUtils.toEthSignedMessageHash(userOpHash);

        (uint8 v, bytes32 r, bytes32 s) = vm.sign(user.key, formattedUserOpHash);

        userOp.signature = abi.encodePacked(r, s, v);

        return (userOp, userOpHash);
    }

    function testValidateSignature() public view {
        // Arrange
        (PackedUserOperation memory userOp, bytes32 userOpHash) = generateSigAndSignedUserOp(owner);
        // Act
        uint256 result = simpleAccountHarness.validateSignature(userOp, userOpHash);
        // Assert
        vm.assertEq(result, SIG_VALIDATION_SUCCESS);
    }

    function testValidateSignatureWithWrongSignature() public view {
        // Arrange
        (PackedUserOperation memory userOp, bytes32 userOpHash) = generateSigAndSignedUserOp(randomUser);
        // Act
        uint256 result = simpleAccountHarness.validateSignature(userOp, userOpHash);
        // Assert
        vm.assertEq(result, SIG_VALIDATION_FAILED);
    }
}

As we’ve finished writing our unit tests, let’s check the test coverage. You can do this by running the following command in the terminal:

forge coverage

Final Thoughts

Throughout the unit tests, we learned a lot, like creating PackedUserOperation and working with EntryPoint to generate the user hash. We also explored many other concepts related to testing with Forge. While this isn't a Foundry basics guide, working through it will help improve our skills and understanding.

In our unit tests, we created a dummy PackedUserOperation, but it was quite basic—there was no gas or calldata involved. Obviously, this won’t be enough for production use. In the next part, which will focus on integration testing, we’ll attempt to execute a real user operation through the entry point.

I hope you’re as excited as I am for the next part. If you’ve enjoyed the series so far, stay tuned for the upcoming content.

If you think there’s room for improvement in the code or explanation, please feel free to let me know in the comments!

Who Am I?

My name is Nikhil. I’m a full-time technical writer focused on Web3 tech, especially Ethereum and Solidity. If you’re looking for a technical writer, either freelance or full-time, feel free to reach out—I’d love to explore any opportunities.

Developer’s Guide to ERC-4337 #1 | Developing Simple Account

Nikhil — Fri, 04 Oct 2024 06:11:37 +0000

Lately, I’ve been exploring ERC-4337, which introduces account abstraction with an alternative mempool. It’s a really exciting topic because it lets developers hide much of the complexity with wallet management and dapp interaction, making the user experience more seamless.

I’m creating this series for developers who want to get hands-on with ERC-4337. This isn’t a series to learn about pros and cons of account abstraction. Instead, this series will focus on the ERC-4337 specification and walk through building account contracts using it.

Since we’ll be working with ERC-4337, I originally planned to explain concepts as we need them. But I realized it’s more helpful to start with an overview so you can understand the bigger picture upfront. So, let’s dive in and get familiar with ERC-4337!

Understanding ERC-4337: What It Is and How It Works

ERC-4337 defines how account abstraction should work on Ethereum or any EVM-compatible chain without changing the consensus layer. It introduces two key ideas: the UserOperation and the Alt Mempool, which are higher-layer components that rely on existing blockchain infrastructure.

A UserOperation is a high-level, pseudo-transaction object that holds both intent and verification data. Unlike regular transactions that are sent to validators, UserOperations are sent to bundlers through public or private alt mempools. These bundlers collect multiple UserOperations, bundle them together into a single transaction, and submit them to get included on the blockchain.

When bundlers send these UserOperations, they interact with a special contract called EntryPoint. The EntryPoint contract is responsible for validating and executing UserOperations. However, it doesn’t handle verification itself. Instead, the verification logic is stored in the Account Contract, which is the user’s smart contract wallet.

The Account Contract contains both the validation and execution logic for UserOperations. The ERC-4337 specification defines a standard interface for these contracts, ensuring they follow a consistent structure. Here's the IAccount interface from the spec:

interface IAccount {
  function validateUserOp
      (PackedUserOperation calldata userOp, bytes32 userOpHash, uint256 missingAccountFunds)
      external returns (uint256 validationData);
}

When a bundler submits a UserOperation to the EntryPoint contract, the EntryPoint first calls the validateUserOp function on the user’s account contract. If the UserOperation is valid, the function returns SIG_VALIDATION_SUCCESS. If validation is successful, the EntryPoint proceeds to execute the UserOperation's calldata on the account contract.

That’s a high-level overview of account abstraction with ERC-4337. Next, we’ll dive into the code and break down the key components of ERC-4337 starting with account contract in more detail. Let’s get started!

Setting Up the Project

We'll be using Foundry to write and test our smart contracts. If you’re not familiar with Foundry, I recommend checking out the Foundry documentation to get up to speed.

To create a new Foundry project, run the following commands in your terminal:

# Creates a new directory named 'simple-account'
mkdir simple-account

# Navigates into the 'simple-account' directory
cd simple-account

# Initializes a new Foundry project
forge init

Next, we need to install some dependencies that will help us develop our account contract. The eth-infinitism team has created an implementation of ERC-4337, which we’ll use as a base. To add it to our project, run the following command:

# Installs the ERC-4337 implementation from eth-infinitism
forge install eth-infinitism/account-abstraction@v0.7.0 --no-commit

Lastly, clean up the default files by removing everything inside the src, script, and test folders. Then, create a new file named SimpleAccount.sol inside the src folder.

With this, your project setup is complete, and you’re ready to start developing the smart contract!

BaseAccount.sol

Much like with ERC-20 tokens, we don’t need to build everything from scratch. We can use BaseAccount.sol from the eth-infinitism/account-abstraction package as a foundation. Here's the BaseAccount.sol implementation:

// SPDX-License-Identifier: GPL-3.0
pragma solidity ^0.8.23;

/* solhint-disable avoid-low-level-calls */
/* solhint-disable no-empty-blocks */

import "../interfaces/IAccount.sol";
import "../interfaces/IEntryPoint.sol";
import "./UserOperationLib.sol";

abstract contract BaseAccount is IAccount {
    using UserOperationLib for PackedUserOperation;

    function getNonce() public view virtual returns (uint256) {
        return entryPoint().getNonce(address(this), 0);
    }

    function entryPoint() public view virtual returns (IEntryPoint);

    function validateUserOp(
        PackedUserOperation calldata userOp,
        bytes32 userOpHash,
        uint256 missingAccountFunds
    ) external virtual override returns (uint256 validationData) {
        _requireFromEntryPoint();
        validationData = _validateSignature(userOp, userOpHash);
        _validateNonce(userOp.nonce);
        _payPrefund(missingAccountFunds);
    }

    function _requireFromEntryPoint() internal view virtual {
        require(
            msg.sender == address(entryPoint()),
            "account: not from EntryPoint"
        );
    }

    function _validateSignature(
        PackedUserOperation calldata userOp,
        bytes32 userOpHash
    ) internal virtual returns (uint256 validationData);

    function _validateNonce(uint256 nonce) internal view virtual {
    }

    function _payPrefund(uint256 missingAccountFunds) internal virtual {
        if (missingAccountFunds != 0) {
            (bool success, ) = payable(msg.sender).call{
                value: missingAccountFunds,
                gas: type(uint256).max
            }("");
            (success);
            //ignore failure (its EntryPoint's job to verify, not account.)
        }
    }
}

Before diving into the code, let’s first understand some key specifications that ERC-4337 defines for account contracts. These are important to understand before moving forward:

Trusted EntryPoint: The contract MUST verify that the caller is a trusted EntryPoint.
Signature Validation: If the account doesn't support signature aggregation, the contract MUST ensure that the signature is valid for the userOpHash. On a signature mismatch, it SHOULD return SIG_VALIDATION_FAILED (instead of reverting). Any other errors MUST cause a revert.
Paying EntryPoint: The contract MUST ensure the EntryPoint (the caller) is paid at least the missingAccountFunds, which may be zero if the account’s deposit is already sufficient.

The provided BaseAccount.sol implementation satisfies all these requirements in the validateUserOp function.

function validateUserOp(
    PackedUserOperation calldata userOp,
    bytes32 userOpHash,
    uint256 missingAccountFunds
) external virtual override returns (uint256 validationData) {
    _requireFromEntryPoint();
    validationData = _validateSignature(userOp, userOpHash);
    _validateNonce(userOp.nonce);
    _payPrefund(missingAccountFunds);
}

Let’s break down what happens in this function:

_requireFromEntryPoint: This checks that the caller is the trusted EntryPoint contract.
_validateSignature: This function handles the signature validation logic, which we will implement in our contract.
_payPrefund: This ensures that the EntryPoint is paid the missingAccountFunds, fulfilling the requirement of paying at least the minimum amount.
_validateNonce: This checks the transaction nonce, preventing replay attacks.

Why Do We Have a Nonce?

EOAs (Externally Owned Accounts) have a nonce to prevent replay attacks, ensuring that each transaction is unique. Now that we are building a smart contract wallet, we need a nonce for the same purpose. While we could define our own nonce validation logic, EntryPoint already handles this in a similar way, so we don’t need to focus too much on it for now.

In summary, the validateUserOp function satisfies all the key requirements from the ERC-4337 specification.

SimpleAccount.sol

Now that we've met the core requirements, what’s left? From the BaseAccount contract, we see that when inheriting it, we need to implement two key functions: _validateSignature and entryPoint. These two functions are essential to fulfill the basic requirements.

In addition to these, we also need a function to allow interaction with other accounts and contracts. ERC-4337 doesn’t specify what this function should be named, and it’s not important since the EntryPoint contract will execute the calldata directly on the account contract.

Let’s begin by implementing the entryPoint function, which is the simplest. Our goal is to define the trusted entryPoint and return its address when the function is called.

EntryPoint Function

We’ll start by developing SimpleAccount.sol. Begin by creating the SimpleAccount contract and importing BaseAccount from the BaseAccount.sol file. This contract will inherit from BaseAccount.

// SPDX-License-Identifier: MIT
pragma solidity 0.8.24;

import {BaseAccount} from "account-abstraction/core/BaseAccount.sol";

contract SimpleAccount is BaseAccount {
    constructor() {}
}

Next, we need to define the trusted EntryPoint in the constructor. The EntryPoint address will be passed in as a parameter and stored in an immutable variable called i_entryPoint, which is of type IEntryPoint.

contract SimpleAccount is BaseAccount {
    IEntryPoint private immutable i_entryPoint;

    constructor(address entryPointAddress) {
        i_entryPoint = IEntryPoint(entryPointAddress);
    }
}

We'll also need to import the IEntryPoint interface from the account-abstraction module.

import {IEntryPoint} from "account-abstraction/interfaces/IEntryPoint.sol";

Finally, we implement the entryPoint function, which will return the trusted i_entryPoint. This function will be a view function and will override the inherited function from BaseAccount, so we’ll add the override keyword.

function entryPoint() public view override returns (IEntryPoint) {
    return i_entryPoint;
}

At this point, your contract should look like this:

// SPDX-License-Identifier: MIT
pragma solidity 0.8.24;

import {BaseAccount} from "account-abstraction/core/BaseAccount.sol";
import {IEntryPoint} from "account-abstraction/interfaces/IEntryPoint.sol";

contract SimpleAccount is BaseAccount {
    IEntryPoint private immutable i_entryPoint;

    constructor(address entryPointAddress) {
        i_entryPoint = IEntryPoint(entryPointAddress);
    }

    function entryPoint() public view override returns (IEntryPoint) {
        return i_entryPoint;
    }
}

With this, you’ve successfully set up the basic structure of the SimpleAccount contract, defining the trusted EntryPoint. The next step would be to implement the _validateSignature and the function that allows interaction with other contracts/accounts.

Account Contract Owner

Developers can implement any method they prefer to validate a UserOperation, but for this series, we will use an ECDSA signature for validation. To perform this validation, we need to have the owner of the account contract. The owner's address will be provided in the constructor and stored in an immutable variable, i_owner.

Here’s how we define the owner in the constructor:

// Variable to store the owner's address
address private immutable i_owner;

constructor(address entryPointAddress, address owner) {
    i_entryPoint = IEntryPoint(entryPointAddress);
    // Set the owner
    i_owner = owner;
}

We also want to add a getter function, getOwner, which returns the owner's address:

function getOwner() public view returns (address) {
    return i_owner;
}

Next, we’ll work on the validateUserOp function, but before diving into that, let's first understand the UserOperation object and the data it contains.

UserOperation

We've mentioned the UserOperation object several times, but what exactly does it contain?

The UserOperation consists of common fields like the sender, nonce, gas details, calldata, and more—similar to what you’d find in a typical transaction. In addition to these standard fields, it includes extra ones, like accountFactory, paymaster, and signature. Don’t worry about the extra fields just yet; we’ll explore them later in this series.

Once the UserOperation is created by the user, it is sent to a bundler, which consolidates the fields and compresses the operation into a more compact format called PackedUserOperation. This PackedUserOperation will be sent to EntryPoint. Here's what that looks like:

struct PackedUserOperation {
    address sender;
    uint256 nonce;
    bytes initCode;
    bytes callData;
    bytes32 accountGasLimits;
    uint256 preVerificationGas;
    bytes32 gasFees;
    bytes paymasterAndData;
    bytes signature;
}

At this point, we only need to focus on two fields: calldata, which is used for execution, and signature, which is used to validate the UserOperation.

`validateUserOp` Function

The validateUserOp function checks the validity of a UserOperation. As we’ve seen in the BaseAccount contract part of this article, this function is already implemented. However, the portion that handles signature validation—via the _validateSignature function—needs to be implemented by the developer (in this case, us).

We’ll use an ECDSA signature to verify that the signature in the UserOperation is signed by the account contract’s owner. If the signer matches the owner, we return SIG_VALIDATION_SUCCESS. If not, we return SIG_VALIDATION_FAILED.

To verify the ECDSA signature, we can use the ecrecover precompile, but it’s more efficient to use the OpenZeppelin ECDSA library, which simplifies the process and eliminates a lot of manual steps. Let’s install OpenZeppelin:

forge install OpenZeppelin/openzeppelin-contracts@v5.0.2 --no-commit

If installed correctly, you should see a message like this:

Installed openzeppelin-contracts v5.0.2

Now that OpenZeppelin is installed, we can begin writing the _validateSignature function. The function signature is already defined in BaseAccount, so we will override it:

function _validateSignature(PackedUserOperation calldata userOp, bytes32 userOpHash)
    internal
    view
    override
    returns (uint256) {}

As this function uses the PackedUserOperation struct, we need to import it from the account-abstraction package. Additionally, we'll import the constants used for signature validation (SIG_VALIDATION_SUCCESS and SIG_VALIDATION_FAILED) from the same package.

import {PackedUserOperation} from "account-abstraction/interfaces/PackedUserOperation.sol";
import {SIG_VALIDATION_FAILED, SIG_VALIDATION_SUCCESS} from "account-abstraction/core/Helpers.sol";

Next, we need to convert the userOpHash into a structured message. We will use OpenZeppelin’s MessageHashUtils.toEthSignedMessageHash function to convert userOpHash into the appropriate Ethereum Signed Message format. To recover the signer's address from this structured message and the provided signature, we’ll use OpenZeppelin’s ECDSA.recover function. Let’s import these libraries before writing the function.

import {MessageHashUtils} from "@openzeppelin/contracts/utils/cryptography/MessageHashUtils.sol";
import {ECDSA} from "@openzeppelin/contracts/utils/cryptography/ECDSA.sol";

Now, let’s use these libraries to retrieve the address of the signer and store it in the messageSigner variable.

function _validateSignature(PackedUserOperation calldata userOp, bytes32 userOpHash)
    internal
    view
    override
    returns (uint256)
{
    bytes32 digest = MessageHashUtils.toEthSignedMessageHash(userOpHash);
    address messageSigner = ECDSA.recover(digest, userOp.signature);
}

Now that we have the messageSigner, we can compare it with the i_owner. If they match, we return SIG_VALIDATION_SUCCESS; otherwise, we return SIG_VALIDATION_FAILED:

if (messageSigner == i_owner) {
    return SIG_VALIDATION_SUCCESS;
} else {
    return SIG_VALIDATION_FAILED;
}

Here’s the complete _validateSignature function:

function _validateSignature(PackedUserOperation calldata userOp, bytes32 userOpHash)
    internal
    view
    override
    returns (uint256)
{
    bytes32 digest = MessageHashUtils.toEthSignedMessageHash(userOpHash);
    address messageSigner = ECDSA.recover(digest, userOp.signature);

    if (messageSigner == i_owner) {
        return SIG_VALIDATION_SUCCESS;
    } else {
        return SIG_VALIDATION_FAILED;
    }
}

This completes the signature validation logic, ensuring the UserOperation is signed by the account owner. The next step is to implement functionality for interacting with external accounts or contracts.

`execute` Function

This function allows the account contract to interact with external contracts or accounts. While the function's name is arbitrary (since the EntryPoint contract directly executes the calldata), in this contract, we'll call it execute. The user or dapp constructing the UserOperation will need to construct calldata for execution.

The execute function will take three arguments:

dest: The address of the contract or account to be called.
value: The amount of ETH to be sent with the call.
funcCallData: The calldata to be executed on the target address.

Here’s the basic function structure:

function execute(address dest, uint256 value, bytes calldata funcCallData) external {}

Since this function allows transferring assets and executing actions on behalf of the user (i.e., the owner of the account contract), it must be protected to prevent unauthorized access. To enforce access control, we'll use the _requireFromEntryPoint function provided by the BaseAccount contract, making sure that only entry points can call this function.

Next, the contract will perform the external call, and we’ll check if it was successful. If the call fails, we'll revert the transaction with a custom error, SimpleAccount__CallFailed, which we define at the top of the contract.

Here’s how the error is defined, and it should be added at the top of the contract:

error SimpleAccount__CallFailed();

The complete execute function is as follows:

function execute(address dest, uint256 value, bytes calldata funcCallData) external {
    _requireFromEntryPoint(); // Restrict access to valid entry points
    (bool success, bytes memory result) = dest.call{value: value}(funcCallData);

    if (!success) {
        revert SimpleAccount__CallFailed(result); // Revert if the call fails
    }
}

With this function in place, we now have a simple account contract that can interact with other contracts and accounts, complying with ERC-4337 and compatible with the EntryPoint contract and bundlers.

Here is the completed code for SimpleAccount:

// SPDX-License-Identifier: MIT
pragma solidity 0.8.24;

import {BaseAccount} from "account-abstraction/core/BaseAccount.sol";
import {IEntryPoint} from "account-abstraction/interfaces/IEntryPoint.sol";
import {PackedUserOperation} from "account-abstraction/interfaces/PackedUserOperation.sol";
import {SIG_VALIDATION_FAILED, SIG_VALIDATION_SUCCESS} from "account-abstraction/core/Helpers.sol";

import {MessageHashUtils} from "@openzeppelin/contracts/utils/cryptography/MessageHashUtils.sol";
import {ECDSA} from "@openzeppelin/contracts/utils/cryptography/ECDSA.sol";

contract SimpleAccount is BaseAccount {
    error SimpleAccount__CallFailed();

    IEntryPoint private immutable i_entryPoint;
    address private immutable i_owner;

    constructor(address entryPointAddress, address owner) {
        i_entryPoint = IEntryPoint(entryPointAddress);
        i_owner = owner;
    }

    function _validateSignature(PackedUserOperation calldata userOp, bytes32 userOpHash)
        internal
        view
        override
        returns (uint256)
    {
        bytes32 digest = MessageHashUtils.toEthSignedMessageHash(userOpHash);
        address messageSigner = ECDSA.recover(digest, userOp.signature);

        if (messageSigner == i_owner) {
            return SIG_VALIDATION_SUCCESS;
        } else {
            return SIG_VALIDATION_FAILED;
        }
    }

    function execute(address dest, uint256 value, bytes calldata funcCallData) external {
        _requireFromEntryPoint();
        (bool success,) = dest.call{value: value}(funcCallData);
        if (!success) {
            revert SimpleAccount__CallFailed();
        }
    }

    function entryPoint() public view override returns (IEntryPoint) {
        return i_entryPoint;
    }

    function getOwner() public view returns (address) {
        return i_owner;
    }
}

Final Thoughts

In this article, we walked through the process of developing a simple account contract that meets the basic requirements of ERC-4337. We explored each function, along with the libraries we used, such as the account-abstraction package from eth-infinitism and OpenZeppelin’s ECDSA library.

We also touched on important ERC-4337 concepts like bundlers and the entry point, though we haven't fully explored them yet. We’ll cover them in more detail as we progress through this series.

Next Steps

In the next article, we’ll shift focus to testing this contract and to gain better grasp of UserOperation, including how to generate the UserOperation hash via the entry point. If you’re excited to dive in, you can start writing tests now, which will help improve your understanding and ensure that the contract works as expected.

I hope you enjoyed this article, and I hope you’ll follow along with the rest of the series!

How to Track liquidity for token pairs on Uniswap

Nikhil — Tue, 05 Sep 2023 09:30:00 +0000

Introduction

Today we will explore different aspects of the liquidity pools of any token pair on Uniswap. Uniswap is the most popular dapp in the crypto ecosystem; it is a decentralized exchange (DEX) that allows you to trade tokens on a blockchain. Out of the different types of DEX, Uniswap is called AMM (Automated money market), which relies on the concept of liquidity pools. Let’s refresh on liquidity pools and then explore data using Bitquery V2 APIs.

Our V2 APIs allow us to access blockchain data in real-time using GraphQL subscriptions. You can try out V2 APIs here

Understanding Token-Pair Liquidity

There are different types of DEX, which you can divide mainly into AMM DEX and Order Book DEX. An AMM DEX like Uniswap, Sushiswap, etc. relies on algorithmic pricing and liquidity pools, while an order book DEX matches buyers and sellers directly based on their submitted orders.

Liquidity, in the context of Uniswap and similar AMM DEXs, refers to the availability of tokens in liquidity pools that facilitate trades. The pools are created by liquidity providers, who provide tokens to liquidity pools in exchange for earning part of trading fees. The depth of liquidity pools plays an important role in determining how easily traders can execute trades without causing significant fluctuations in market prices.

Now that we have clarified what liquidity pools are and how they affect DEX working, let’s see how to fetch data using the DEX API.

Get All Liquidity Pools For a Token

As anyone can create a liquidity pool for any token, there will be many pools for a single token, so let’s try to fetch a list of all the pools.

In this query, we will be fetching a list of liquidity pools created for USDT, for which we need to set buy currency to the address of USDT token.