diff --git a/README.md b/README.md index ef1a4c5c..3d0504b9 100644 --- a/README.md +++ b/README.md @@ -75,7 +75,7 @@ A deployment script can be found in the `scripts/` folder forge script script/Deploy.s.sol --rpc-url $RPC_URL --broadcast ``` -## Features Overview +## Features overview ### Features Modular Account v2 can: @@ -86,7 +86,7 @@ Modular Account v2 can: 5. Be upgradeable to or from most other smart contract account implementations. 6. Be customized in many ways. All customization options can be found [here](./2-customizing-your-modular-account.md). -#### ERC1271 Contract Signatures Support +#### ERC1271 contract signatures support Certain applications such as Permit2 or Cowswap use the ERC1271 contract signatures standard to determine if a smart contract has approved a certain action. Modular Account implements to allow smart accounts to use these applications. @@ -97,19 +97,19 @@ When modular accounts are created from the factory, an `ERC1967` proxy contract ### Customizing your Modular Account The Modular Account v2 can be customized by: -1. Installing executions to add custom execution logic to run, or uninstalling to remove them -2. Installing validations to apply custom validation logic for one or all executions, or uninstalling to remove them -3. Adding pre validation hooks that are attached to validations, or removing them -4. Adding execution hooks that are attached to executions, or removing them -5. Adding execution hooks that are attached to entities, or removing them +1. Installing execution functions to add custom execution logic to run, or uninstalling to remove them +2. Installing validations to apply custom validation logic for one or all execution functions, or uninstalling to remove them +3. Installing pre validation hooks that are attached to module entities, or removing them +4. Installing execution hooks that are attached to execution functions, or removing them +5. Installing execution hooks that are attached to module entities, or removing them -### Lifecycle of a User Operation +### Lifecycle of a user operation ![](./img/userop-flow.png) -### Lifecycle of a Runtime Call +### Lifecycle of a runtime call ![](./img/runtime-flow.png) -#### Pre-validation Hooks +#### Pre-validation hooks Pre validation hooks are run before validations. Pre-validation hooks are necessary to perform gas related checks for User Operations (session key gas limits, or gas metering taking into account paymaster usage). These checks must happen in the validation phase since a validation success would allow the entrypoint to charge gas for the user operation to the account. @@ -117,15 +117,15 @@ Pre validation hooks are run before validations. Pre-validation hooks are necess Validations are usually signature validation functions (secp256k1, BLS, WebAuthn, etc). While it’s feasible to implement signature validation as a pre-validation hook, it’s more efficient and ergonomic to do these in validations since it allows us to apply permissions per entity using execution hooks. In ERC-4337, accounts can return validation data that’s not 0 or 1 to signal the usage of a signature aggregator. -#### Execution Hooks +#### Execution hooks Execution hooks are useful for applying permissions on execution functions to limit the set of possible actions that can be taken. Post-execution hooks are useful for checking the final state after an execution. Pre and post-execution hook pairs are useful for measuring differences in state due to an execution. For example, you could use a pre and post execution hook pair to enforce that swap outputs from a DCA swap performed by a session key fall within a some tolerance price determined by a price oracle. Execution hooks can be associated either with an (validation module + entity ID) pair to apply permissions on that specific entity, or with an execution selector on the account to apply global restrictions on the account across all entities. A example of a useful global restriction would be to block NFT transfers for NFTs in cold storage, or to apply resource locks. -#### Executions +#### Execution functions -Execution hooks are applied across executions. Modular account comes with native executions such as `installValidation`, `installExecution`, or `upgradeToAndCall`. However, you could customize the account by installing additional executions. After a new execution is installed, when the account is called with that function selector, the account would forward the call to the module associated with that installed execution. An example for executions would be to implement callbacks to be able to take flash loans. +Execution hooks are applied across execution functions. Modular account comes with native execution functions such as `installValidation`, `installExecution`, or `upgradeToAndCall`. However, you could customize the account by installing additional execution functions. After a new execution is installed, when the account is called with that function selector, the account would forward the call to the module associated with that installed execution. An example of a useful execution functions would be to implement callbacks for the account to be able to take flash loans. ## Security, Audits, and Bug Bounty @@ -133,32 +133,32 @@ Our audit reports can be found in [audits](/audits). The filenames for the repor Details of our bug bounty program can be found at https://hackerone.com/alchemyplatform. -### Other Security Considerations +### Other security considerations This section contains other security considerations that developers should be aware of when using a Modular Account besides informational issues highlighted in the security audits. -#### Off-chain Safety Checks +#### Off-chain safety checks A client should perform the following off-chain checks when interacting with a modular account: 1. When installing a validation, clients should check that the entity ID has not been used for that validator for that account yet, as certain validation modules implement `onInstall` as another way to do `rotateKey`. 2. When upgrading to a Modular Account, clients should check if the proxy used to be a Modular Account by checking the value of the `initialized` variable at the Modular Account namespaced storage slot within the proxy. If so, any `initializer` functions called would not work, and the configuration of that past Modular Account might be different from the current ownership configuration. 3. When upgrading to a Modular Account, clients should check that the account is an ERC-1967 proxy by checking the ERC-1822 `proxiableUUID` ****slot. -4. When installing executions, clients should check that it does not collide with any native function selectors. +4. When installing execution function, clients should check that it does not collide with any native function selectors. 5. Clients should ensure that deferred action nonces are unique without dependencies. One possible scheme is to use unix timestamps as part of the nonce. -#### Proxy Pattern and Initializer Functions +#### Proxy pattern and initializer functions Initializer functions are not guarded by any access control modifier. If accounts are not used in a proxy pattern, during the account’s constructor, as per Openzeppelin’s implementation of `Initializable`, initializer functions are able to be reentered. This design choice can be used by an attacker to install additional validations to take over a user’s account. -#### EIP-7702 Accounts and Initializer Functions +#### Initializer functions with EIP-7702 When using EIP-7702, the delegate destination should only be the `SemiModularAccount7702` implementation, and not any of the other account variants. Otherwise, if the delegate destination is set to an account with an unprotected initializer function, an attacker will be able to take over the account. -### Semi Modular Account Considerations +### Semi modular account considerations `SemiModularAccountBytecode` (`SMABytecode`) is the cheapest account to deploy. It can only be used for new account deployment, and **should NOT** be used for account upgrades due to requiring specific proxy bytecode. -#### Deferred Actions +#### Deferred actions 1. In order for a deferred action to be run at validation, in addition to special encoding (which includes the validation to validate the deferred action itself), it must not break ERC-4337 validation-time rules. For instance, this means that any execution hooks on `installValidation` must comply with RIP-7562. 2. Deferred actions should only be used to perform actions necessary for user op validation to pass. Otherwise, as deferred actions are not signed over, a malicious bundler could remove the deferred action from the user op and cause an unexpected outcome. -#### Signature Validation Flag Enablement +#### Signature validation flag enablement The `isSignatureValidation` flag meant to allow a validation function to validate ERC-1271 signatures. Developer should note that for Modular Account this is a very powerful capability to grant as it allows validation functions to approve deferred actions on the account. ### Acknowledgements