Grant Proposal: Semaphore Paymaster

Thanks to John Guilding, Jake C-T, Yanis Meziane and Giacomo Corrias for review this proposal.

Project Overview

This project provides a toolkit for web3 developers looking to create dapps that offer a seamless, gasless experience for their users by leveraging their Semaphore group membership—without the hassle of spending excessive time integrating Semaphore and ERC-4337 themselves.

Problem Statement

The decentralized nature of Ethereum is powerful, but it also presents well-known fundamental challenges: onchain activities are not privacy-preserving, and every transaction incurs a gas fee. Various efforts have been made to address these issues. Semaphore is a widely used tool that allows group members to send anonymous signals, while ERC-4337 enables gasless transactions for users.

Although both tools are powerful, integrating them together into a single dapp is particularly challenging. Developers must navigate the complexities of combining these two technologies, which can be time-consuming and require deep technical expertise. This often leads to delays in development and increased costs.

Proposed Solution

To address these challenges, our project aims to provide open-source tools and modular components, including a Semaphore paymaster and frontend elements, specifically designed for building Account Abstraction applications. Our goal is to simplify the integration process, enabling developers to focus on building innovative features rather than getting bogged down by technical hurdles. This toolkit offers a robust and easily integrable base template for developers.

Key Features and Innovation
Paymaster is an extension of the ERC-4337 entry point logic. This feature allows application developers to subsidize fees for their users, enable users to pay fees with ERC-20 tokens, and support various other use cases. Consolidated with Paymaster, ERC-4337 significantly improves the user experience by freeing users from the need to understand and manage gas fees. If the QF Round in Ethcon Korea 2023 had utilized this approach, it likely would not have suffered from the low participation rate. However, it doesn't come without a trade-off: a lack of privacy.

With this proposal, we introduce a paymaster leveraging Semaphore (aka. Semaphore Paymaster). The Semaphore paymaster subsidizes transactions for users who can prove their membership in a Semaphore group. This combination allows for privacy-preserving, gasless transactions, addressing both of the major challenges developers face today.

Use Case and Demonstration
We will demonstrate the use of these tools through a concrete use case that combines the Semaphore paymaster and MACI. This application enables users to prove their identity and vote anonymously, with their gas fees sponsored by the Semaphore paymaster. Our commitment to this goal is reflected in the prototype we delivered at the PSE Hackerhouse during EthCC 2024.

Looking ahead, our timeline includes running an anonymous and gasless voting process for hackathon projects at Ethereum Costa Rica in October. This event will showcase the practical implementation and benefits of our tools in a real-world scenario

Project Details

Core Modules

Semaphore Paymaster

  • Gatekeeper: Allows a user to join a Semaphore group once their identity has been verified.
  • Paymaster: Sponsors gas fees anonymously for Semaphore group members.
  • Documentation: Comprehensive guides and tutorials.
  • Boilerplate: Frontend components for easy integration.

Future Work

  • Integration Support: Request ZeroDev, Biconomy, and Pimlico to add support for the Semaphore paymaster.
  • Gatekeeper Extensions
    Integrate the gatekeeper with other identity verification applications such as Hats Protocol, Gitcoin Passport, or Zupass. These extensions are expected to require minimal effort for off-chain components, owing to the unified interface provided by Excubiae.

Team

Team Members

Team's Experience

Our team consists of experienced blockchain developers with a strong background in Ethereum smart contracts and privacy protocols. We have previously developed and contributed to several open-source projects, including the Semaphore protocol, ZkEmail and various Account Abstraction applications. Our expertise aligns well with the project's objectives, ensuring we have the necessary skills to successfully implement and deliver the Semaphore + Paymaster integration.

Development Roadmap

Milestone 1: Simple Semaphore Paymaster Smart Contract + An Optimization for Executing Batch User Operations.

Estimated Duration: 2 weeks
Full-time equivalent (FTE): 2
Costs:
jihoonsong: $2,400
brolag: $4,800
Total amount: $7,200

We aim to deliver two Semaphore Paymasters:

  1. SimpleSemaphorePaymaster: This paymaster will sponsor gas for semaphore group members without imposing any limitations on how much gas members can consume.
  2. GasLimitedSemaphorePaymaster: This version will impose a periodic gas limit on how much gas members can consume.

In this milestone, we will be designing and implementing the SimpleSemaphorePaymaster.

Specification and High-Level Design:

At its core, the SimpleSemaphorePaymaster has two main components:

  • Semaphore Group Membership verification and validation
  • ERC-4337 Compatible Paymaster contract

Essentially, the Paymaster contract will depend on a Semaphore contract to verify Semaphore membership proofs.

Paymaster

Each Paymaster will depend on one Semaphore group. To this end, the Paymaster contract will be passed the Semaphore contract address and a GroupId. It will sponsor transactions that have a valid membership proof of the predefined GroupId.

Membership Proof

A typical Semaphore membership proof is like this:

struct SemaphoreProof {
    uint256 merkleTreeDepth;
    uint256 merkleTreeRoot;
    uint256 nullifier;
    uint256 message;
    uint256 scope;
    uint256[8] points;
}

And we need to have access to the above proof from within the paymaster to be able to verify the membership. For this we ABI encode the SemaphoreProof struct and embed it in the PaymasterData field of the UserOperation.

In the validatePaymasterUserOp we decode the attached proof, send it to the Semaphore contract to make sure the proof is valid. Once the verification passes, the Paymaster will pay for the UserOperation. Since the SimpleSemaphorePaymaster does not impose any sort of limitation, this is the only check that happens.

Optimization

In case one wants to use the same AA wallet to execute multiple UserOperations, we can verify the membership proof once and store the result to avoid verifying expensive zk proofs each time the user wants to execute a UserOperation. This can be implemented in various ways:

  • An external method on the paymaster contract that stores a mapping between the account address and isMember and will be used in the validatePaymasterUserOp method:
mapping(address => bool) isMember; // stores the membership status

function setIsMember(SemaphoreProof proof, address accountAddress); // sets the membership status
  • It can be set after verifying the first UserOperation of the user. In the postOp phase of the paymaster, we can call setIsMember automatically, so the user won't need to provide membership proof again.

The downside of these methods is that once the user is no longer part of the Semaphore group, there needs to be a mechanism to invalidate the isMember flag. This can be implemented by having a fixed expiry date for the flag.

Considerations
  • Preventing proof front run: In order to prevent malicious actors to front-run the membership proof, the user MUST include the wallet address that is sending the UserOperation in the message field of the SemaphoreProof.
  • Proof reuse: This is a less severe issue since the wallet address is already embeded in the message, however to prevent any other issues with reusing a proof more than once, we will return the proof nullifier in the context field of validatePaymasterUserOp so that we can mark it as used in the PostOp phase of the Paymaster.*

In summery we will deliver the following:

Name Deliverable Specification
SimpleSemaphorePaymaster smart contract ERC-4337 compatible paymaster with described functionality that pays for Semaphore group members without any limitations
BatchOptimizedSemaphorePaymaster smart contract Allows users to use the SimpleSemaphorePaymaster without proving proofs for each UesrOperation
Unit Tests forge unit tests comprehensvie unit test for the SimpleSemaphorePaymaster
Integration test forge + hardhat tests end to end tests that cover the flow of gas sponsorship in a local environment

Milestone 2: Gas Limited Semaphore Paymaster

Estimated Duration: 2 weeks
Full-time equivalent (FTE): 2
Costs:
jihoonsong: $2,400
brolag: $4,800
Total amount: $7,200

Overview

In this milestone, we aim to implement the gas-limited Paymaster that imposes a predefined periodic gas limitation on requests. For example, the period could be one week, and the gas limit could be one million. This means that each member can execute UserOperations that consume at most one million gas each week. This limit will reset back to one million each week.

This implementation will be a continuation of the SimpleSemaphorePaymaster, and therefore it will have all the mentioned properties of the SimpleSemaphorePaymaster. Additionally, it receives the following extra parameters when instantiating the GasLimitedSemaphorePaymaster:

  • periodDuration: Defines the gas limit reset period in seconds.
  • startTimestamp: Timestamp of the start of the first period.
  • gasLimit: Maximum cumulative gas that can be consumed by each member during each period.

Note: All the above parameters are set once during the construction of the contract and will remain immutable.

Proof Scope

In order to enable and enforce periodic gas limits, we need to make use of the scope field in SemaphoreProof.

As a reminder, the nullifier is the hash of the user's private key and scope. This means that if the user uses the same scope to generate proofs, it will result in the same nullifier each time.

The nullifier is usually marked as used or invalid after the first time the proof is used to prevent double signaling.

In our use case, the scope that the user must use to generate the proof is determined by the GasLimitedSemaphorePaymaster contract, which will be the active period:

function getScope() public returns(uint256) { return (block.timestamp - startTimestamp) / periodDuration; }

This way, all the proofs that a user generates during each period will have the same nullifier. We can use this to track the gas consumption of the user and only mark the nullifier as used once the gas limit is reached.

PRIVACY NOTICE: This means that all the transactions of a user are linked together during each period through the nullifier. However, it is still disconnected from the original identity of the user.

Putting it all together

The client reads (or calculates) the correct scope and generates a proof as before, attaching it to the PaymasterData. On the Paymaster side, not only is the proof verified, but the scope is also checked to ensure it corresponds to the active period. Moreover, the Paymaster checks if the already consumed gas by the user, plus the gas that the current userOperation is going to use, is still below the period gas limit. If the check passes, the userOperation will be sponsored; otherwise, it will be rejected.

In the PostOp phase of the Paymaster, the actual gas consumed by the userOperation is added to the total gas consumed in the active period for the user (identified by the nullifier). If the total consumed gas goes above the limit, the nullifier will be marked as used and cannot be used anymore until the next period.

In summary this milestone delivers the following:

Name Deliverable Specification
GasLimitedSemaphorePaymaster smart contract ERC-4337 compatible paymaster with described functionality that enforces a periodic gas limit
Unit Tests forge unit tests comprehensvie unit test for the GasLimitedSemaphorePaymaster
Integration test forge + hardhat tests end to end tests that cover the flow of gas sponsorship in a local environment

Milestone 3: Gatekeeper Inheriting Excubiae and End-to-end test

Estimated Duration: 2 weeks
Full-time equivalent (FTE): 2
Costs:
jihoonsong: $2,400
brolag: $4,800
Total amount: $7,200

Overview

We need a gatekeeper that permits a user with a verified identity to join a Semaphore group. The gatekeeper will be inheriting Excubiae, with the aim of facilitating seamless extension to incorporate other identity verification applications such as Hats Protocol, Gitcoin Passport, or Zupass.

Having end-to-end testing with the gatekeeper and Semaphore paymaster will help us build a more robust system. Furthermore, the end-to-end testing environment can serve as a valuable example for other projects looking to construct their own end-to-end testing environments.

Name Deliverable Specification
Gatekeeper with Excubiae smart contract Add a gatekeeper inheriting Excubiae that allows all entry into a Semaphore group and incorporate it into the end-to-end test
End-to-end test script hardhat test Add an end-to-end test script that is entering a semaphore group via the Gatekeeper, constructing an UserOp that transfer some ETH with gas sponsored by SimpleSemaphorePaymaster

Milestone 4: Gasless Voting Process and Frontend Optimization

Estimated Duration: 3 weeks
Full-time equivalent (FTE): 2.5
Costs:
jihoonsong: $2,800
brolag: $5,600
Total amount: $8,400

Overview

This milestone encompasses the implementation of a gasless voting process for hackathon projects at Ethereum Costa Rica and the optimization of the frontend codebase. Our goal is to provide a seamless, user-friendly voting experience while ensuring the frontend code is maintainable, modular, and scalable. This preparation is crucial for delivering a polished application at the event.

Gasless Voting Process

To support a gasless voting process, all hackathon participants will be whitelisted and can use their verified identities to sign up for a Semaphore group. Additionally, we will implement a frontend-based mechanism to verify if an address is part of the whitelist through a signed message. The process is as follows:

  1. The user loads the application and the frontend fetches the whitelist JSON file stored in a GitHub repository.
  2. The user signs a predefined message using their wallet (e.g., MetaMask).
  3. The frontend recovers the user's address from the signed message and checks if the address is part of the fetched whitelist.
  4. If the address is on the whitelist, the user is allowed to submit their signed request to the bundler to join the Semaphore group.
Name Deliverable Specification
Frontend and smart contracts integration open source Put gatekeeper, Semaphore, Semaphore Paymaster, and frontend all together
Frontend Whitelist Verification frontend code Implement the capability in the frontend to verify if an address is part of the whitelist through a signed message
Voting Dashboard open source Develop a dashboard for users to view and participate in the voting process, with real-time updates and results

Frontend Optimization

In parallel, we will focus on cleaning up and optimizing the frontend code to ensure it aligns with best practices and is ready for scale.

Name Deliverable Specification
Code Refactoring code refactor Review and refactor existing frontend code to ensure clarity, reduce complexity, and remove redundancy
Modularization code modularization Break down large components into smaller, reusable modules to promote code reuse and simplify development
UI/UX Enhancements design update Address UI/UX issues to ensure an intuitive and standardized interface
Testing and Bug Fixes automated tests Conduct testing to identify and fix bugs, and implement automated tests for critical paths
Documentation documentation update Update documentation to reflect changes and provide clear instructions for future developers
Select a repo