From e784d59c3d8bc5fc3c0c699097dff53eb309705a Mon Sep 17 00:00:00 2001 From: Marcus Pang Yu Yang Date: Sun, 14 Jul 2024 07:02:33 +0200 Subject: [PATCH] docs: update readme with basic information --- README.md | 77 ++++++++++----------------- packages/ethccUI/README.md | 2 + packages/foundry/README.md | 99 +++++------------------------------ packages/module-kit/README.md | 12 +++-- 4 files changed, 52 insertions(+), 138 deletions(-) diff --git a/README.md b/README.md index 6ff5330..54bc3ca 100644 --- a/README.md +++ b/README.md @@ -1,21 +1,28 @@ -# ๐Ÿ— Scaffold-ETH 2 +# ๐Ÿ— Piggy Wallet -

- Documentation | - Website -

+Piggy Wallet is a Smart Wallet that enables several functionality, similar to a form of no-code Smart Wallet. For instance, we support the following features: -๐Ÿงช An open-source, up-to-date toolkit for building decentralized applications (dapps) on the Ethereum blockchain. It's designed to make it easier for developers to create and deploy smart contracts and build user interfaces that interact with those contracts. +- Auto-conversion of incoming ERC20s to USDC +- Task system to reward users / wallet owners for completing tasks +- Timelock system to give non-owners access after a certain time -โš™๏ธ Built using NextJS, RainbowKit, Foundry, Wagmi, Viem, and Typescript. +## How it works -- โœ… **Contract Hot Reload**: Your frontend auto-adapts to your smart contract as you edit it. -- ๐Ÿช **[Custom hooks](https://docs.scaffoldeth.io/hooks/)**: Collection of React hooks wrapper around [wagmi](https://wagmi.sh/) to simplify interactions with smart contracts with typescript autocompletion. -- ๐Ÿงฑ [**Components**](https://docs.scaffoldeth.io/components/): Collection of common web3 components to quickly build your frontend. -- ๐Ÿ”ฅ **Burner Wallet & Local Faucet**: Quickly test your application with a burner wallet and local faucet. -- ๐Ÿ” **Integration with Wallet Providers**: Connect to different wallet providers and interact with the Ethereum network. +For the auto-conversion of ERC20 tokens to USDC, we allow any user to initiate a UserOp which simply converts some ERC20 that is currently in the Safe Smart Wallet. This is to enable non-wallet owners to initiate this transaction for these users, and thereby have the "automatic" conversion feature. -![Debug Contracts tab](https://github.com/scaffold-eth/scaffold-eth-2/assets/55535804/b237af0c-5027-4849-a5c1-2e31495cccb1) +- This will be enhanced with 1inch Fusion API, leveraging the Resolver network to fulfil this swap + +For the task system, it is a simple mapping of task IDs to task details, which include the reward amount, token address, and deadline. There is no strict enforcement of whether the task has been completed satisfactorily, as the main use case is to reward individuals known to the sponsor, who can mediate this off-chain (e.g. parents and their children). + +Timelock is implemented by defining a timestamp for when the user can access the Safe Smart Wallet again. This is meant to be used in conjunction with plugins that support multiple owners. + +## Implementation Details + +Smart Wallet is implemented initially with Coinbase Smart Wallet, which we unfortunately were unable to deploy due to issues with the bundler. Read more in [foundry](./packages/foundry/README.md). + +We have since switched to using [Module Kit](https://github.com/rhinestonewtf/module-template) to create plugins for the Safe ERC7579 smart wallet. Read more in [module-kit](./packages/module-kit/README.md). + +Swapping of tokens is done through Uniswap V4, which is implemented in [module-kit](./packages/module-kit/README.md) as well. See this [test](./packages/module-kit/test/USDCSwapperExecute.t.sol) for more information. ## Requirements @@ -27,54 +34,28 @@ Before you begin, you need to install the following tools: ## Quickstart -To get started with Scaffold-ETH 2, follow the steps below: +To get started, follow the steps below: 1. Install dependencies if it was skipped in CLI: ``` -cd my-dapp-example yarn install ``` -2. Run a local network in the first terminal: - -``` -yarn chain -``` - -This command starts a local Ethereum network using Foundry. The network runs on your local machine and can be used for testing and development. You can customize the network configuration in `packages/foundry/foundry.toml`. - -3. On a second terminal, deploy the test contract: +2. Start NextJS app: ``` -yarn deploy +cd packages/nextjs +yarn start ``` -This command deploys a test smart contract to the local network. The contract is located in `packages/foundry/contracts` and can be modified to suit your needs. The `yarn deploy` command uses the deploy script located in `packages/foundry/script` to deploy the contract to the network. You can also customize the deploy script. - -4. On a third terminal, start your NextJS app: +3. Run foundry tests: ``` -yarn start +cd packages/module-kit +forge test -vvv --evm-version=cancun ``` -Visit your app on: `http://localhost:3000`. You can interact with your smart contract using the `Debug Contracts` page. You can tweak the app config in `packages/nextjs/scaffold.config.ts`. - -Run smart contract test with `yarn foundry:test` - -- Edit your smart contract `YourContract.sol` in `packages/foundry/contracts` -- Edit your frontend homepage at `packages/nextjs/app/page.tsx`. For guidance on [routing](https://nextjs.org/docs/app/building-your-application/routing/defining-routes) and configuring [pages/layouts](https://nextjs.org/docs/app/building-your-application/routing/pages-and-layouts) checkout the Next.js documentation. -- Edit your deployment scripts in `packages/foundry/script` - - -## Documentation - -Visit our [docs](https://docs.scaffoldeth.io) to learn how to start building with Scaffold-ETH 2. - -To know more about its features, check out our [website](https://scaffoldeth.io). - -## Contributing to Scaffold-ETH 2 - -We welcome contributions to Scaffold-ETH 2! +## Acknowledgements -Please see [CONTRIBUTING.MD](https://github.com/scaffold-eth/scaffold-eth-2/blob/main/CONTRIBUTING.md) for more information and guidelines for contributing to Scaffold-ETH 2. \ No newline at end of file +This is a fork of [Scaffold-ETH 2](https://github.com/scaffold-eth/scaffold-eth-2). diff --git a/packages/ethccUI/README.md b/packages/ethccUI/README.md index e57cb52..4c6b3b9 100644 --- a/packages/ethccUI/README.md +++ b/packages/ethccUI/README.md @@ -1,5 +1,7 @@ # Test +Generated with the help of AI tools. + Note: Please ensure you have installed nodejs To preview and run the project on your device: diff --git a/packages/foundry/README.md b/packages/foundry/README.md index 86c34d2..946d235 100644 --- a/packages/foundry/README.md +++ b/packages/foundry/README.md @@ -1,98 +1,24 @@ # Smart Wallet -This repository contains code for a new, [ERC-4337](https://eips.ethereum.org/EIPS/eip-4337) compliant smart contract wallet from Coinbase. +This repository contains code for a modified [ERC-4337](https://eips.ethereum.org/EIPS/eip-4337) compliant smart contract wallet from Coinbase. -It supports -- Multiple owners -- Passkey owners and Ethereum address owners -- Cross-chain replayability for owner updates and other actions: sign once, update everywhere. +There are 2 main types: -## Multiple Owners -Our smart wallet supports a practically unlimited number of concurrent owners (max 2^256). Each owner can transact independently, without sign off from any other owner. +- `TimelockBountySmartWallet`: a Coinbase smart wallet with timelock and bounty features +- `TimelockSmartWallet`: a Coinbase smart wallet with timelock features only -Owners are identified as `bytes` to allow both Ethereum address owners and passkey (Secp256r1) public key owners. +## Developing -## Passkey owners and Ethereum address owners -Ethereum address owners can call directly to the smart contract wallet to transact and also transact via user operations. - -In the ERC-4337 context, we expect `UserOperation.signature` to be the ABI encoding of a `SignatureWrapper` struct -```solidity -struct SignatureWrapper { - uint8 ownerIndex; - bytes signatureData; -} -``` - -Owner index identifies the owner who signed the user operation. This must be passed because secp256r1 verifiers require the public key as an input. This differs from `ecrecover`, which returns the signer address. - -We pass an `ownerIndex` rather than the public key itself to optimize for calldata, which is currently the main cost driver on Ethereum layer 2 rollups, like Base. - -If the signer is an Ethereum address, `signatureData` should be the packed ABI encoding of the `r`, `s`, and `v` signature values. - -If the signer is a secp256r1 public key, `signatureData` should be the the ABI encoding of a [`WebAuthnAuth`](https://github.com/base-org/webauthn-sol/blob/main/src/WebAuthn.sol#L15-L34) struct. See [webauthn-sol](https://github.com/base-org/webauthn-sol) for more details. - -## Cross-chain replayability -If a user changes an owner or upgrade their smart wallet, they likely want this change applied to all instances of your smart wallet, across various chains. Our smart wallet allows users to sign a single user operation which can be permissionlessly replayed on other chains. - -There is a special function, `executeWithoutChainIdValidation`, which can only be called by the `EntryPoint` contract (v0.6). - -In `validateUserOp` we check if this function is being called. If it is, we recompute the userOpHash (which will be used for signature validation) to exclude the chain ID. - -Code excerpt from validateUserOp -```solidity -// 0xbf6ba1fc = bytes4(keccak256("executeWithoutChainIdValidation(bytes)")) -if (userOp.callData.length >= 4 && bytes4(userOp.callData[0:4]) == 0xbf6ba1fc) { - userOpHash = getUserOpHashWithoutChainId(userOp); - if (key != REPLAYABLE_NONCE_KEY) { - revert InvalidNonceKey(key); - } -} else { - if (key == REPLAYABLE_NONCE_KEY) { - revert InvalidNonceKey(key); - } -} -``` - -To help keep these cross-chain replayable user operations organized and sequential, we reserve a specific nonce key for only these user operations. - -`executeWithoutChainIdValidation` can only be used for calls to self and can only call a whitelisted set of functions. - -```solidity -function executeWithoutChainIdValidation(bytes calldata data) public payable virtual onlyEntryPoint { - bytes4 selector = bytes4(data[0:4]); - if (!canSkipChainIdValidation(selector)) { - revert SelectorNotAllowed(selector); - } - - _call(address(this), 0, data); -} -``` - -`canSkipChainIdValidation` can be used to check which functions can be called. - -Today, allowed are -- MultiOwnable.addOwnerPublicKey -- MultiOwnable.addOwnerAddress -- MultiOwnable.addOwnerAddressAtIndex -- MultiOwnable.addOwnerPublicKeyAtIndex -- MultiOwnable.removeOwnerAtIndex -- UUPSUpgradeable.upgradeToAndCall - -## Deployments -Factory and implementation are deployed via [Safe Singleton Factory](https://github.com/safe-global/safe-singleton-factory), which today will give the same address across 248 chains. See "Deploying" below for instructions on how to deploy to new chains. -| Version | Factory Address | -|-----------|-----------------------------------------| -| 1 | [0x0BA5ED0c6AA8c49038F819E587E2633c4A9F428a](https://basescan.org/address/0x0BA5ED0c6AA8c49038F819E587E2633c4A9F428a) | - - -## Developing After cloning the repo, run the tests using Forge, from [Foundry](https://github.com/foundry-rs/foundry?tab=readme-ov-file) + ```bash forge test ``` ## Deploying + To deploy on a new chain, in your `.env` set + ```bash #`cast wallet` name ACCOUNT= @@ -101,12 +27,15 @@ RPC_URL= # Optional Etherscan API key for contract verification ETHERSCAN_API_KEY= ``` + See [here](https://book.getfoundry.sh/reference/cast/cast-wallet-import) for more details on `cast wallet`. -Then run +Then run + ``` make deploy ``` -## Influences -Much of the code in this repository started from Solady's [ERC4337](https://github.com/Vectorized/solady/blob/main/src/accounts/ERC4337.sol) implementation. We were also influenced by [DaimoAccount](https://github.com/daimo-eth/daimo/blob/master/packages/contract/src/DaimoAccount.sol), which pioneered using passkey signers on ERC-4337 accounts, and [LightAccount](https://github.com/alchemyplatform/light-account). +## Acknowledgements + +This is a fork of [Coinbase's ERC-4337 Smart Wallet](https://github.com/coinbase/smart-wallet). diff --git a/packages/module-kit/README.md b/packages/module-kit/README.md index 51d8be5..bee4f7a 100644 --- a/packages/module-kit/README.md +++ b/packages/module-kit/README.md @@ -1,8 +1,10 @@ -## Module Template +## Piggy Wallet Modules -**A template for building smart account modules using the [ModuleKit](https://github.com/rhinestonewtf/modulekit)** +Existing modules: -## Using the template +- BountyExecute: maintains bounty data structure +- USDCSwapperExecute: swaps ERC20 tokens to USDC in Uniswap V4 pools +- TimelockValidator: validates a userOp of a specific owner to ensure it has passed the timelock ### Install dependencies @@ -76,6 +78,6 @@ To run the tests, run: forge test ``` -## Contributing +## Acknowledgements -For feature or change requests, feel free to open a PR, start a discussion or get in touch with us. +This is a fork of [https://github.com/rhinestonewtf/modulekit](https://github.com/rhinestonewtf/modulekit).