You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
PimlicoERC20Paymaster is an ERC-4337 Paymaster contract by Pimlico which is able to sponsor gas fees in exchange for ERC20 tokens. The contract 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 contract uses an Oracle to fetch the latest token prices.
4
+
5
+
This 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.
4
6
5
7
## Features
6
-
- ERC20 token payments for transaction fees
7
-
- Refunding excess tokens based on actual gas cost
8
-
- Updating price configuration
9
-
- Withdrawing tokens by contract owner
10
-
- Fetching latest token prices using an Oracle
11
-
12
-
## Contract
13
-
The PimlicoERC20Paymaster contract inherits from BasePaymaster.
14
-
15
-
### Functions
16
-
- constructor: Initializes the PimlicoERC20Paymaster contract with the given parameters.
17
-
- updateConfig: Updates the price markup and price update threshold configurations.
18
-
- withdrawToken: Allows the contract owner to withdraw a specified amount of tokens from the contract.
19
-
- updatePrice: Updates the token price by fetching the latest price from the Oracle.
20
-
-_validatePaymasterUserOp: Validates a paymaster user operation and calculates the required token amount for the transaction.
21
-
-_postOp: Performs post-operation tasks, such as updating the token price and refunding excess tokens.
22
-
23
-
### Events
24
-
- ConfigUpdated: Emitted when the price markup and price update threshold configurations are updated.
8
+
9
+
- Users paying with ERC-20 tokens for transaction fees
10
+
- Using guarantors to front gas fees to allow for token approvals during execution
11
+
- Compatible with EntryPoint v0.7
12
+
- Refunding excess tokens based on the actual user operation cost
13
+
- Using oracles to fetch latest gas prices
14
+
- Withdrawing accrued tokens by the contract owner
25
15
26
16
## Usage
27
-
Deploy the PimlicoERC20Paymaster contract, providing the required parameters such as the ERC20 token, EntryPoint contract, and Oracle contract addresses.
28
-
Update the price markup and price update threshold configurations if needed, using the updateConfig function.
29
-
If necessary, the contract owner can withdraw tokens using the withdrawToken function.
30
-
To update the token price, call the updatePrice function.
31
-
For more information, please refer to the comments within the contract source code.
32
17
33
-
## SDK
34
-
You can use permissionless.js to interact with an ERC20 Paymaster. Follow [this link](https://docs.pimlico.io/permissionless/tutorial/tutorial-3) to check out tutorial on how to submit user operation using with an ERC-20 Paymaster.
18
+
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.
35
19
36
-
Check out [these docs](https://docs.pimlico.io/permissionless/how-to/paymasters/use-custom-paymaster) if you're going to use a custom paymaster implementation.
20
+
Mode 1:
21
+
- The user (sender) pays for gas fees with the ERC-20 token.
22
+
-`paymasterData` is empty
37
23
38
-
## Development setup
24
+
Mode 2:
25
+
- The user (sender) pays for gas fees with the ERC-20 token,
26
+
- There is a limit to the amount of ERC-20 tokens that can be taken from the user for the user opertion.
This repository uses both hardhat and foundry for development, and assumes you have already installed hardhat/foundry
29
+
Mode 3:
30
+
- A guarantor fronts the ERC-20 token gas fees during validation, and expects the user to be able to pay the actual cost during the postOp phase and get refunded. Otherwise the guarantor is liable.
- A guarantor fronts the ERC-20 token gas fees during validation, and expects the user to be able to pay the actual cost during the postOp phase and get refunded. Otherwise the guarantor is liable.
35
+
- There is a limit to the amount of ERC-20 tokens that can be taken from the user/guarantor for the user opertion.
Hardhat is used for gas metering and developing sdk.
38
+
## Development
45
39
46
-
1. install dependencies
47
-
```shell
48
-
npm install
49
-
```
50
-
2. run test
51
-
```
52
-
Npx hardhat test
53
-
```
54
-
This will show results for the gas metering on different modes based on 1) refund 2) token payment limit 3) price update
40
+
This repository uses Foundry and Halmos for development.
55
41
56
-
*note* : first transaction is expensive because nonce increases 0 -> 1
42
+
### Foundry
57
43
58
-
### foundry
44
+
Run `foundryup` to make sure you have the latest foundry version.
59
45
60
-
Foundry is used for unit tests
46
+
Foundry is used for unit tests.
61
47
62
48
1. install dependencies
63
49
```shell
@@ -71,9 +57,24 @@ forge test
71
57
72
58
3. run coverage
73
59
```shell
74
-
forge coverage
60
+
forge coverage --ir-minimum
75
61
```
76
62
63
+
### Halmos
64
+
65
+
To install Halmos, run `pip install halmos` or follow [their detailed installation guide](https://github.com/a16z/halmos?tab=readme-ov-file#installation).
66
+
67
+
Halmos is used for symbolic tests.
68
+
69
+
1. install dependencies
70
+
```shell
71
+
forge install
72
+
```
73
+
74
+
2. run tests
75
+
```shell
76
+
halmos
77
+
```
77
78
78
79
## License
79
-
This project is licensed under the GNU General Public License v3.0.
0 commit comments