ERC20Paymaster
contractThis repository contains an ERC-4337 paymaster implementation allowing users to pay for gas fees with ERC-20 tokens, leveraging an oracle to fetch latest prices. The contract takes the max fee during the paymaster validation step, and refunds excess tokens if the actual gas cost is lower than the initially provided amount. It also allows updating price configuration and withdrawing tokens by the contract owner.
The ERC-20 paymaster supports:
This paymaster has four modes. It allows the user to be simply made to pay themselves, but also allows the selection of a guarnator who can front the ERC-20 token fees during validation, allowing the user to approve tokens to the paymaster or fetch / claim tokens if they do not already have any. For each mode, it is possible to set a ERC-20 token spend limit to protect against sudden price fluctuations or oracle manipulation.
Mode 0:
paymasterData
is emptyMode 1:
paymasterData
: "0x01" + token spend limit (32 bytes)Mode 2:
paymasterData
: "0x02" + guarantor address (20 bytes) + validUntil (6 bytes) + validAfter (6 bytes) + guarantor signature (dynamic bytes)Mode 3:
paymasterData
: "0x03" + token spend limit (32 bytes) + guarantor address (20 bytes) + validUntil (6 bytes) + validAfter (6 bytes) + guarantor signature (dynamic bytes)This repository uses Foundry and Halmos for development.
Run foundryup
to make sure you have the latest foundry version.
Foundry is used for unit tests.
install dependencies
forge install
set up local environment
cp .env.sample .env
# Fill the envs
run tests
forge test
run coverage
forge coverage --ir-minimum
The ERC20 paymaster relies on Chainlink oracles. However, they may be not presented in some networks or may miss some tokens. To face this issue, we have implemented three additional oracles, which are all compliant with Chainlink's oracle interface
TWAP oracle relies on the TWAP, received from the existing Uniswap V3 pool. The TWAP is fetched for the uint32 twapAge
seconds, this parameter can't be changed after deployment. The oracle is built around official Uniswap's OracleLibrary implementation.
Manual oracle returns a fixed price, specified by the owner. The price can be changed an infinite amount of times.
Fixed oracle returns the fixed price, specified at the time of deploy.
To install Halmos, run pip install halmos
or follow their detailed installation guide.
Halmos is used for symbolic tests.
install dependencies
forge install
run tests
halmos
The audits of the ERC-20 Paymaster can be found in the audits folder:
This project is licensed under the MIT license.