# 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](https://eips.ethereum.org/EIPS/eip-4337#extension-paymasters). 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](https://qf.pse.dev/case-studies/ethcon-23) 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](https://www.loom.com/share/67aa3d4d284c4e6294f00d6d852b4ad1?sid=43952cb2-c6fe-4a66-9502-9d1ae854715b) 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](https://x.com/ethereumcr) 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
- [zkfriendly](https://github.com/zkfriendly)
- [jihoonsong](https://github.com/jihoonsong)
- [baumstern](https://github.com/baumstern)
- [brolag](https://github.com/brolag)

#### 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](https://github.com/jihoonsong): $2,400
[brolag](https://github.com/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`](https://eips.ethereum.org/EIPS/eip-4337#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](https://github.com/jihoonsong): $2,400
[brolag](https://github.com/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`](https://docs.semaphore.pse.dev/glossary#nullifier). 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](https://github.com/privacy-scaling-explorations/zk-kit.solidity/tree/main/packages/excubiae) and End-to-end test
**Estimated Duration**: 2 weeks
**Full-time equivalent (FTE)**: 2
**Costs**:
[jihoonsong](https://github.com/jihoonsong): $2,400
[brolag](https://github.com/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](https://github.com/privacy-scaling-explorations/zk-kit.solidity/tree/main/packages/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](https://github.com/jihoonsong): $2,800
[brolag](https://github.com/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 |