diff --git a/.gitignore b/.gitignore index 79807b2..140ce61 100644 --- a/.gitignore +++ b/.gitignore @@ -20,3 +20,5 @@ artifacts-filtered account-abstraction scw-contracts +.DS_Store +yarn-error.log diff --git a/.husky/pre-commit b/.husky/pre-commit index 1525982..af50890 100755 --- a/.husky/pre-commit +++ b/.husky/pre-commit @@ -1,2 +1,4 @@ #!/usr/bin/env sh . "$(dirname -- "$0")/_/husky.sh" + +yarn lint:sol \ No newline at end of file diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..9e61241 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,67 @@ +# Contributing to Biconomy Projects πŸš€ + +First off, thank you for considering contributing to Biconomy! We truly appreciate your effort. +Contributions from the community are what make Biconomy awesome. πŸ™Œ + +Your contributions are valued and will help in driving the decentralized web forward. + +> If you're passionate about our mission but can't contribute directly, there are other ways to support: +> +> - ⭐ Star our projects on GitHub +> - 🐦 [Tweet about Biconomy](https://twitter.com/biconomy/) +> - πŸ“Œ Reference Biconomy in your project's readme +> - πŸ—£οΈ Share about Biconomy at meetups or with peers + +## Table of Contents + +- [Contributing to Biconomy Projects πŸš€](#contributing-to-biconomy-projects-) + - [Table of Contents](#table-of-contents) + - [Have a Question?](#have-a-question) + - [Ready to Contribute?](#ready-to-contribute) + - [Legal Notice πŸ“œ](#legal-notice-) + - [Reporting Bugs πŸ›](#reporting-bugs-) + - [Suggesting Enhancements πŸ’‘](#suggesting-enhancements-) + - [First Time Contributing? 🌱](#first-time-contributing-) + - [Improving Documentation πŸ“š](#improving-documentation-) + - [Commit Messages πŸ“](#commit-messages-) + - [Join Biconomy's Team! πŸš€](#join-biconomys-team-) + +## Have a Question? + +Before reaching out, please ensure you've gone through our [Documentation](https://docs.biconomy.io/). If you still have questions: + +1. Search for existing [Issues](https://github.com/bcnmy/biconomy-paymasters/issues) that might answer your question. +2. Check out our [Forum](https://forum.biconomy.io/). +3. Join our [Discord](https://discord.com/invite/biconomy) or [Telegram](https://t.me/biconomy) communities. + +If you still need assistance, feel free to open an [Issue](https://github.com/bcnmy/biconomy-paymasters/issues/new) with your question. + +## Ready to Contribute? + +### Legal Notice πŸ“œ + +By contributing, you agree that you've authored your contribution and that it can be provided under the project's license. + +### Reporting Bugs πŸ› + +Before submitting a bug report, ensure you're using the latest version and that you've read our [documentation](https://docs.biconomy.io/). If you've identified a bug that hasn't been reported, open a new [Issue](https://github.com/bcnmy/biconomy-paymasters/issues/new) detailing the bug. + +### Suggesting Enhancements πŸ’‘ + +Have a feature in mind? First, ensure it aligns with Biconomy's mission and hasn't been suggested before. Then, open an [Issue](https://github.com/bcnmy/biconomy-paymasters/issues/new) to discuss your enhancement. + +### First Time Contributing? 🌱 + +Welcome! We're thrilled to have you. If you're unsure where to start, look for issues labeled `good first issue`. + +### Improving Documentation πŸ“š + +Good documentation is key! If you spot areas for improvement or errors in our documentation, we'd love your input. If you wish to suggest changes, feel free to raise a PR on our [documentation repository](https://github.com/bcnmy/docs). + +### Commit Messages πŸ“ + +Ensure your commit messages are clear and descriptive. + +## Join Biconomy's Team! πŸš€ + +Interested in joining our mission full-time? Check out our [current job openings](https://jobs.lever.co/biconomy). diff --git a/LICENSE.md b/LICENSE.md new file mode 100644 index 0000000..cf907e9 --- /dev/null +++ b/LICENSE.md @@ -0,0 +1,21 @@ +MIT License + +Copyright (c) 2023 Biconomy + +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the "Software"), to deal +in the Software without restriction, including without limitation the rights +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in all +copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE +SOFTWARE. diff --git a/README.md b/README.md index f186692..6294834 100644 --- a/README.md +++ b/README.md @@ -1,87 +1,93 @@ -# biconomy-paymasters +# Biconomy Paymasters 🌐 -### Playground for ERC4337 Paymasters built with :heart_eyes: by Biconomy -#### Some examples +Welcome to the `biconomy-paymasters`` repository! Paymaster contracts enable seamless userOp fee handling in decentralized applications, offering innovative solutions similar to traditional web2 payment processing models. πŸ› οΈ -1. Singleton Verifying Paymaster: Acts as a sponsorship paymaster and lets Dapps manage deposit without deploying a new one for each Dapp. +## What are Biconomy Paymasters? πŸ€” -2. Token Paymaster: Extended version of Verifying Paymaster which can accept fees from user by withdrawing ERC20 tokens +Biconomy Paymasters, structured as smart contracts, streamline the management of gas fees, offering end-users the convenience of executing user operations without gas costs or the flexibility to pay fees with ERC20 tokens. πŸš€ -#### Other WIP +- **Sponsorship Paymaster**: Allows transactions without end-users needing to pay for gas, enhancing UX. +- **Token Paymaster**: Provides the ability to pay for transactions with ERC20 tokens. -Fiat Paymaster +## Features 🌟 -Deposit Paymaster +- Simplified transaction fee handling. +- ERC 4337 Account Abstraction compliant. +- Multi-token support for gas payments. +- Hybrid Paymaster approach, combining gas sponsorship and token-based payments into a single, streamlined solution. -Custom versions of above Verifying (allow Dapp deposit sponsorship in different tokens) and Token Paymaster (acts as deposit paymaster also) +## Upcoming Features (Work in Progress) +- Fiat Paymaster (WIP): Planned feature to allow users to pay gas fees using fiat currency. +- Deposit Paymaster (WIP): Intended to enable Dapp deposit sponsorship in various tokens. +### ERC20 Token Paymaster -# How to run the project +![ERC20 Token Paymaster](./assets/readme/erc20-token-gas-payment-flow.png) -#### You're going to need to place a private key in a .env file in the root. #### +- ERC20 Token Paymaster helps users pay for their transactions using ERC20 tokens. +- Users initiate a transaction using an ERC20 token. +- Paymaster validates the transaction and covers the userOp fees.This flow ensures ease of use and convenience for users. -#### In order to add/udpate git submodule account-abstraction: #### -.gitmodules file is already added. two submodules are being used in this project +### Sponsorship Paymaster -git submodule update --init (This command will initialize and fetch the submodules listed in the .gitmodules file.) +![Sponsorship Paymaster](./assets/readme/conditional-gas-sponsorship-paymaster.png) -git submodule update --remote (This will update the submodules to the latest commit in their respective repositories.) +- Users initiate the process with their userOps. +- The operation is checked against the requirements set by the Sponsorship Paymaster. +- Once verified and approved, the Paymaster sponsors the gas fees. +- This process ensures userOps are confirmed on the network without users incurring gas costs. -you can also alternatively run forge install (or forge install ) +Note: The Paymaster's approval process is crucial, requiring a verifying party's signature to confirm sponsorship eligibility for each userOp​​. -If you encounter any issues during the submodule update process, you can try deleting the submodules directory and then running the git submodule update --init command again. +## Getting Started 🏁 -#### If you face below error, make sure typechain artifacts are generated in account-abstraction folder. #### -Error: Cannot find module '../typechain' +To set up and use the Biconomy Paymasters, you'll need to have Node.js, Yarn, Hardhat, and Foundry installed. -cd lib/account-abstraction -yarn -npx hardhat compile +### Prerequisites πŸ“‹ +Make sure you have Node.js and Yarn installed. You will also need to install Foundry for smart contract development with Solidity. -This project demonstrates an advanced Hardhat use case, integrating other tools commonly used alongside Hardhat in the ecosystem. Foundry support is also added. +### Installation πŸ“¦ -Try running some of the following tasks: +Clone the repository and install the dependencies with `yarn`: -```shell -forge build --via-ir - -npx hardhat accounts -npx hardhat compile -npx hardhat clean -npx hardhat test -npx hardhat node -npx hardhat help -REPORT_GAS=true npx hardhat test -npx hardhat coverage -npx hardhat run scripts/deploy.ts -TS_NODE_FILES=true npx ts-node scripts/deploy.ts -npx eslint '**/*.{js,ts}' -npx eslint '**/*.{js,ts}' --fix -npx prettier '**/*.{json,sol,md}' --check -npx prettier '**/*.{json,sol,md}' --write -npx solhint 'contracts/**/*.sol' -npx solhint 'contracts/**/*.sol' --fix +```bash +git clone https://github.com/bcnmy/biconomy-paymasters.git +cd biconomy-paymasters +yarn install ``` -# Etherscan verification - -To try out Etherscan verification, you first need to deploy a contract to an Ethereum network that's supported by Etherscan, such as Ropsten. +### Building the Project πŸ—οΈ -In this project, copy the .env.example file to a file named .env, and then edit it to fill in the details. Enter your Etherscan API key, your Ropsten node URL (eg from Alchemy), and the private key of the account which will send the deployment transaction. With a valid .env file in place, first deploy your contract: +Compile your smart contracts and generate typechain artifacts: -```shell -hardhat run --network polygon_mumbai scripts/deploy.ts +```bash +yarn build ``` -Then, copy the deployment address and paste it in to replace `DEPLOYED_CONTRACT_ADDRESS` in this command: +### Running Tests πŸ§ͺ + +After building, run your tests to ensure everything is working correctly: -```shell -npx hardhat verify --network polygon_mumbai DEPLOYED_CONTRACT_ADDRESS "Hello, Hardhat!" +```bash +yarn test ``` -# Performance optimizations +This will run both Hardhat and Foundry tests as specified in your `package.json` scripts. + +## Documentation πŸ“š + +For more detailed information about Paymasters and how to integrate them into your project, visit the [Biconomy Paymaster Documentation](https://docs.biconomy.io/category/paymaster). + +## Foundry Installation + +For instructions on how to set up Foundryfollow the instructions provided in the [Foundry Book](https://book.getfoundry.sh/getting-started/installation.html). + +## Contributing 🀝 + +We welcome contributions from the community. Please take a look at the [guidelines for contributions](./CONTRIBUTING.md). -For faster runs of your tests and scripts, consider skipping ts-node's type checking by setting the environment variable `TS_NODE_TRANSPILE_ONLY` to `1` in hardhat's environment. For more details see [the documentation](https://hardhat.org/guides/typescript.html#performance-optimizations). +## License πŸ“œ +This project is licensed under the MIT License. See the [`LICENSE`](./LICENSE.md) file for more information. diff --git a/assets/readme/conditional-gas-sponsorship-paymaster.png b/assets/readme/conditional-gas-sponsorship-paymaster.png new file mode 100644 index 0000000..fb847ac Binary files /dev/null and b/assets/readme/conditional-gas-sponsorship-paymaster.png differ diff --git a/assets/readme/erc20-token-gas-payment-flow.png b/assets/readme/erc20-token-gas-payment-flow.png new file mode 100644 index 0000000..709cb8b Binary files /dev/null and b/assets/readme/erc20-token-gas-payment-flow.png differ diff --git a/assets/readme/paymaster-off-chain-request-processing-flow.png b/assets/readme/paymaster-off-chain-request-processing-flow.png new file mode 100644 index 0000000..043f649 Binary files /dev/null and b/assets/readme/paymaster-off-chain-request-processing-flow.png differ diff --git a/audits/Final Biconomy Security Assessment Report.pdf b/audits/Final Biconomy Security Assessment Report.pdf new file mode 100644 index 0000000..e7d4239 Binary files /dev/null and b/audits/Final Biconomy Security Assessment Report.pdf differ diff --git a/audits/Token Paymaster - Zellic Audit Report.pdf b/audits/Token Paymaster - Zellic Audit Report.pdf new file mode 100644 index 0000000..881e17d Binary files /dev/null and b/audits/Token Paymaster - Zellic Audit Report.pdf differ