Thanks to John Guilding, Jake C-T, Yanis Meziane and Giacomo Corrias for review this proposal.
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.
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.
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
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.
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:
SimpleSemaphorePaymaster
: This paymaster will sponsor gas for semaphore group members without imposing any limitations on how much gas members can consume.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
.
At its core, the SimpleSemaphorePaymaster
has two main components:
ERC-4337
Compatible Paymaster contractEssentially, the Paymaster
contract will depend on a Semaphore
contract to verify Semaphore
membership proofs.
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
.
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.
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:
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
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.
UserOperation
in the message
field of the SemaphoreProof
.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 |
Estimated Duration: 2 weeks
Full-time equivalent (FTE): 2
Costs:
jihoonsong: $2,400
brolag: $4,800
Total amount: $7,200
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.
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.
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 |
Estimated Duration: 2 weeks
Full-time equivalent (FTE): 2
Costs:
jihoonsong: $2,400
brolag: $4,800
Total amount: $7,200
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 |
Estimated Duration: 3 weeks
Full-time equivalent (FTE): 2.5
Costs:
jihoonsong: $2,800
brolag: $5,600
Total amount: $8,400
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.
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:
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 |
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 |