Merge branch 'aa/erc7913-signer' into feature/zk-email-7913

Author: Amxx

CHANGELOG.md

@@ -4,6 +4,11 @@
 - `SignerERC7913`: Abstract signer that verifies signatures using the ERC-7913 workflow.
 - `ERC7913SignatureVerifierP256` and `ERC7913SignatureVerifierRSA`: Ready to use ERC-7913 verifiers that implement key verification for P256 (secp256r1) and RSA keys.
 
+## 03-04-2025
+
+- `PaymasterNFT`: Extension of `PaymasterCore` that approves sponsoring of user operation based on ownership of an ERC-721 NFT.
+- `PaymasterERC20`: Extension of `PaymasterCore` that sponsors user operations against payment in ERC-20 tokens.
+
 ## 28-03-2025
 
 - Deprecate `Account` and rename `AccountCore` to `Account`.

contracts/account/extensions/AccountERC7579.sol

@@ -1,6 +1,6 @@
 // SPDX-License-Identifier: MIT
 
-pragma solidity ^0.8.24;
+pragma solidity ^0.8.27;
 
 import {PackedUserOperation} from "@openzeppelin/contracts/interfaces/draft-IERC4337.sol";
 import {IERC1271} from "@openzeppelin/contracts/interfaces/IERC1271.sol";
@@ -19,7 +19,7 @@ import {Account} from "../Account.sol";
  * To comply with the ERC-1271 support requirement, this contract defers signature validation to
  * installed validator modules by calling {IERC7579Validator-isValidSignatureWithSender}.
  *
- * This contract does not implement validation logic for user operations since these functionality
+ * This contract does not implement validation logic for user operations since this functionality
  * is often delegated to self-contained validation modules. Developers must install a validator module
  * upon initialization (or any other mechanism to enable execution from the account):
  *
@@ -40,7 +40,12 @@ import {Account} from "../Account.sol";
  *   internal virtual functions {_extractUserOpValidator} and {_extractSignatureValidator}. Both are implemented
  *   following common practices. However, this part is not standardized in ERC-7579 (or in any follow-up ERC). Some
  *   accounts may want to override these internal functions.
+ * * When combined with {ERC7739}, resolution ordering of {isValidSignature} may have an impact ({ERC7739} does not
+ *   call super). Manual resolution might be necessary.
+ * * Static calls (using callType `0xfe`) are currently NOT supported.
  * ====
+ *
+ * WARNING: Removing all validator modules will render the account inoperable, as no user operations can be validated thereafter.
  */
 abstract contract AccountERC7579 is Account, IERC1271, IERC7579Execution, IERC7579AccountConfig, IERC7579ModuleConfig {
     using Bytes for *;
@@ -163,8 +168,8 @@ abstract contract AccountERC7579 is Account, IERC1271, IERC7579Execution, IERC75
      * @dev Implement ERC-1271 through IERC7579Validator modules. If module based validation fails, fallback to
      * "native" validation by the abstract signer.
      *
-     * NOTE: when combined with {ERC7739} (for example through {Account}), resolution ordering may have an impact
-     * ({ERC7739} does not call super). Manual resolution might be necessary.
+     * NOTE: when combined with {ERC7739}, resolution ordering may have an impact ({ERC7739} does not call super).
+     * Manual resolution might be necessary.
      */
     function isValidSignature(bytes32 hash, bytes calldata signature) public view virtual returns (bytes4) {
         // check signature length is enough for extraction
@@ -173,10 +178,10 @@ abstract contract AccountERC7579 is Account, IERC1271, IERC7579Execution, IERC75
             // if module is not installed, skip
             if (isModuleInstalled(MODULE_TYPE_VALIDATOR, module, Calldata.emptyBytes())) {
                 // try validation, skip any revert
-                try IERC7579Validator(module).isValidSignatureWithSender(address(this), hash, innerSignature) returns (
+                try IERC7579Validator(module).isValidSignatureWithSender(msg.sender, hash, innerSignature) returns (
                     bytes4 magic
                 ) {
-                    if (magic == IERC1271.isValidSignature.selector) return magic;
+                    return magic;
                 } catch {}
             }
         }
@@ -220,8 +225,8 @@ abstract contract AccountERC7579 is Account, IERC1271, IERC7579Execution, IERC75
     /**
      * @dev Installs a module of the given type with the given initialization data.
      *
-     * For the fallback module type, the `initData` is expected to be a tuple of a 4-byte selector and the
-     * rest of the data to be sent to the handler when calling {IERC7579Module-onInstall}.
+     * For the fallback module type, the `initData` is expected to be the (packed) concatenation of a 4-byte
+     * selector and the rest of the data to be sent to the handler when calling {IERC7579Module-onInstall}.
      *
      * Requirements:
      *
@@ -259,14 +264,16 @@ abstract contract AccountERC7579 is Account, IERC1271, IERC7579Execution, IERC75
     /**
      * @dev Uninstalls a module of the given type with the given de-initialization data.
      *
-     * For the fallback module type, the `deInitData` is expected to be a tuple of a 4-byte selector and the
-     * rest of the data to be sent to the handler when calling {IERC7579Module-onUninstall}.
+     * For the fallback module type, the `deInitData` is expected to be the (packed) concatenation of a 4-byte
+     * selector and the rest of the data to be sent to the handler when calling {IERC7579Module-onUninstall}.
      *
      * Requirements:
      *
      * * Module must be already installed. Reverts with {ERC7579UninstalledModule} otherwise.
      */
     function _uninstallModule(uint256 moduleTypeId, address module, bytes memory deInitData) internal virtual {
+        require(supportsModule(moduleTypeId), ERC7579Utils.ERC7579UnsupportedModuleType(moduleTypeId));
+
         if (moduleTypeId == MODULE_TYPE_VALIDATOR) {
             require(_validators.remove(module), ERC7579Utils.ERC7579UninstalledModule(moduleTypeId, module));
         } else if (moduleTypeId == MODULE_TYPE_EXECUTOR) {
@@ -336,9 +343,10 @@ abstract contract AccountERC7579 is Account, IERC1271, IERC7579Execution, IERC75
      * ```
      * <module address (20 bytes)> | <key (4 bytes)> | <nonce (8 bytes)>
      * ```
-     * NOTE: The default behavior of this function replicated the behavior of
-     * https://github.com/rhinestonewtf/safe7579/blob/bb29e8b1a66658790c4169e72608e27d220f79be/src/Safe7579.sol#L266[Safe adapter] and
-     * https://github.com/etherspot/etherspot-prime-contracts/blob/cfcdb48c4172cea0d66038324c0bae3288aa8caa/src/modular-etherspot-wallet/wallet/ModularEtherspotWallet.sol#L227[Etherspot's Prime Account].
+     * NOTE: The default behavior of this function replicates the behavior of
+     * https://github.com/rhinestonewtf/safe7579/blob/bb29e8b1a66658790c4169e72608e27d220f79be/src/Safe7579.sol#L266[Safe adapter],
+     * https://github.com/etherspot/etherspot-prime-contracts/blob/cfcdb48c4172cea0d66038324c0bae3288aa8caa/src/modular-etherspot-wallet/wallet/ModularEtherspotWallet.sol#L227[Etherspot's Prime Account], and
+     * https://github.com/erc7579/erc7579-implementation/blob/16138d1afd4e9711f6c1425133538837bd7787b5/src/MSAAdvanced.sol#L247[ERC7579 reference implementation].
      *
      * This is not standardized in ERC-7579 (or in any follow-up ERC). Some accounts may want to override these internal functions.
      *
@@ -359,10 +367,11 @@ abstract contract AccountERC7579 is Account, IERC1271, IERC7579Execution, IERC75
      * <module address (20 bytes)> | <signature data>
      * ```
      *
-     * NOTE: The default behavior of this function replicated the behavior of
+     * NOTE: The default behavior of this function replicates the behavior of
      * https://github.com/rhinestonewtf/safe7579/blob/bb29e8b1a66658790c4169e72608e27d220f79be/src/Safe7579.sol#L350[Safe adapter],
-     * https://github.com/bcnmy/nexus/blob/54f4e19baaff96081a8843672977caf712ef19f4/contracts/Nexus.sol#L239[Biconomy's Nexus] and
-     * https://github.com/etherspot/etherspot-prime-contracts/blob/cfcdb48c4172cea0d66038324c0bae3288aa8caa/src/modular-etherspot-wallet/wallet/ModularEtherspotWallet.sol#L252[Etherspot's Prime Account]
+     * https://github.com/bcnmy/nexus/blob/54f4e19baaff96081a8843672977caf712ef19f4/contracts/Nexus.sol#L239[Biconomy's Nexus],
+     * https://github.com/etherspot/etherspot-prime-contracts/blob/cfcdb48c4172cea0d66038324c0bae3288aa8caa/src/modular-etherspot-wallet/wallet/ModularEtherspotWallet.sol#L252[Etherspot's Prime Account], and
+     * https://github.com/erc7579/erc7579-implementation/blob/16138d1afd4e9711f6c1425133538837bd7787b5/src/MSAAdvanced.sol#L296[ERC7579 reference implementation].
      *
      * This is not standardized in ERC-7579 (or in any follow-up ERC). Some accounts may want to override these internal functions.
      */
@@ -375,10 +384,10 @@ abstract contract AccountERC7579 is Account, IERC1271, IERC7579Execution, IERC75
     /**
      * @dev Extract the function selector from initData/deInitData for MODULE_TYPE_FALLBACK
      *
-     * NOTE: If we had calldata here, we would could use calldata slice which are cheaper to manipulate and don't
-     * require actual copy. However, this would require `_installModule` to get a calldata bytes object instead of a
-     * memory bytes object. This would prevent calling `_installModule` from a contract constructor and would force
-     * the use of external initializers. That may change in the future, as most accounts will probably be deployed as
+     * NOTE: If we had calldata here, we could use calldata slice which are cheaper to manipulate and don't require
+     * actual copy. However, this would require `_installModule` to get a calldata bytes object instead of a memory
+     * bytes object. This would prevent calling `_installModule` from a contract constructor and would force the use
+     * of external initializers. That may change in the future, as most accounts will probably be deployed as
      * clones/proxy/ERC-7702 delegates and therefore rely on initializers anyway.
      */
     function _decodeFallbackData(

contracts/account/extensions/AccountERC7579Hooked.sol

@@ -1,6 +1,6 @@
 // SPDX-License-Identifier: MIT
 
-pragma solidity ^0.8.24;
+pragma solidity ^0.8.27;
 
 import {IERC7579Hook, MODULE_TYPE_HOOK} from "@openzeppelin/contracts/interfaces/draft-IERC7579.sol";
 import {ERC7579Utils, Mode} from "@openzeppelin/contracts/account/utils/draft-ERC7579Utils.sol";
@@ -21,6 +21,9 @@ import {AccountERC7579} from "./AccountERC7579.sol";
 abstract contract AccountERC7579Hooked is AccountERC7579 {
     address private _hook;
 
+    /// @dev A hook module is already present. This contract only supports one hook module.
+    error ERC7579HookModuleAlreadyPresent(address hook);
+
     /**
      * @dev Calls {IERC7579Hook-preCheck} before executing the modified function and {IERC7579Hook-postCheck}
      * thereafter.
@@ -35,6 +38,12 @@ abstract contract AccountERC7579Hooked is AccountERC7579 {
         if (hook_ != address(0)) IERC7579Hook(hook_).postCheck(hookData);
     }
 
+    /// @inheritdoc AccountERC7579
+    function accountId() public view virtual override returns (string memory) {
+        // vendorname.accountname.semver
+        return "@openzeppelin/community-contracts.AccountERC7579Hooked.v0.0.0";
+    }
+
     /// @dev Returns the hook module address if installed, or `address(0)` otherwise.
     function hook() public view virtual returns (address) {
         return _hook;
@@ -63,7 +72,7 @@ abstract contract AccountERC7579Hooked is AccountERC7579 {
         bytes memory initData
     ) internal virtual override withHook {
         if (moduleTypeId == MODULE_TYPE_HOOK) {
-            require(_hook == address(0), ERC7579Utils.ERC7579AlreadyInstalledModule(moduleTypeId, module));
+            require(_hook == address(0), ERC7579HookModuleAlreadyPresent(_hook));
             _hook = module;
         }
         super._installModule(moduleTypeId, module, initData);

contracts/account/extensions/ERC7821.sol

@@ -7,7 +7,9 @@ import {IERC7821} from "../../interfaces/IERC7821.sol";
 import {Account} from "../Account.sol";
 
 /**
- * @dev Minimal batch executor following ERC-7821. Only supports basic mode (no optional "opData").
+ * @dev Minimal batch executor following ERC-7821.
+ *
+ * Only supports supports single batch mode (`0x01000000000000000000`). Does not support optional "opData".
  */
 abstract contract ERC7821 is IERC7821 {
     using ERC7579Utils for *;
@@ -18,7 +20,7 @@ abstract contract ERC7821 is IERC7821 {
      * @dev Executes the calls in `executionData` with no optional `opData` support.
      *
      * NOTE: Access to this function is controlled by {_erc7821AuthorizedExecutor}. Changing access permissions, for
-     * example to approve calls by the ERC-4337 entrypoint, should be implement by overriding it.
+     * example to approve calls by the ERC-4337 entrypoint, should be implemented by overriding it.
      *
      * Reverts and bubbles up error if any call fails.
      */

contracts/account/paymaster/PaymasterERC20.sol

@@ -0,0 +1,145 @@
+// SPDX-License-Identifier: MIT
+
+pragma solidity ^0.8.20;
+
+import {ERC4337Utils, PackedUserOperation} from "@openzeppelin/contracts/account/utils/draft-ERC4337Utils.sol";
+import {IERC20, SafeERC20} from "@openzeppelin/contracts/token/ERC20/utils/SafeERC20.sol";
+import {EIP712} from "@openzeppelin/contracts/utils/cryptography/EIP712.sol";
+import {Math} from "@openzeppelin/contracts/utils/math/Math.sol";
+import {PaymasterCore} from "./PaymasterCore.sol";
+
+/**
+ * @dev Extension of {PaymasterCore} that enables users to pay gas with ERC-20 tokens.
+ *
+ * To enable this feature, developers must implement the {fetchDetails} function:
+ *
+ * ```solidity
+ * function _fetchDetails(
+ *     PackedUserOperation calldata userOp,
+ *     bytes32 userOpHash
+ * ) internal view override returns (uint256 validationData, IERC20 token, uint256 tokenPrice, address guarantor) {
+ *     // Implement logic to fetch the token, token price, and guarantor address from the userOp
+ * }
+ * ```
+ */
+abstract contract PaymasterERC20 is PaymasterCore {
+    using ERC4337Utils for *;
+    using Math for *;
+    using SafeERC20 for IERC20;
+
+    event UserOperationSponsored(
+        bytes32 indexed userOpHash,
+        address indexed user,
+        address indexed guarantor,
+        uint256 tokenAmount,
+        uint256 tokenPrice,
+        bool paidByGuarantor
+    );
+
+    // Over-estimations: ERC-20 balances/allowances may be cold and contracts may not be optimized
+    uint256 private constant POST_OP_COST = 30_000;
+    uint256 private constant POST_OP_COST_WITH_GUARANTOR = 45_000;
+
+    /// @inheritdoc PaymasterCore
+    function _validatePaymasterUserOp(
+        PackedUserOperation calldata userOp,
+        bytes32 userOpHash,
+        uint256 maxCost
+    ) internal virtual override returns (bytes memory context, uint256 validationData) {
+        (uint256 validationData_, IERC20 token, uint256 tokenPrice, address guarantor) = _fetchDetails(
+            userOp,
+            userOpHash
+        );
+
+        uint256 prefundAmount = (maxCost +
+            (guarantor == address(0)).ternary(POST_OP_COST, POST_OP_COST_WITH_GUARANTOR) *
+            userOp.maxFeePerGas()).mulDiv(tokenPrice, _tokenPriceDenominator());
+
+        // if validation is obviously failed, don't even try to do the ERC-20 transfer
+        return
+            (validationData_ != ERC4337Utils.SIG_VALIDATION_FAILED &&
+                token.trySafeTransferFrom(
+                    guarantor == address(0) ? userOp.sender : guarantor,
+                    address(this),
+                    prefundAmount
+                ))
+                ? (
+                    abi.encodePacked(userOpHash, token, prefundAmount, tokenPrice, userOp.sender, guarantor),
+                    validationData_
+                )
+                : (bytes(""), ERC4337Utils.SIG_VALIDATION_FAILED);
+    }
+
+    /// @inheritdoc PaymasterCore
+    function _postOp(
+        PostOpMode /* mode */,
+        bytes calldata context,
+        uint256 actualGasCost,
+        uint256 actualUserOpFeePerGas
+    ) internal virtual override {
+        bytes32 userOpHash = bytes32(context[0x00:0x20]);
+        IERC20 token = IERC20(address(bytes20(context[0x20:0x34])));
+        uint256 prefundAmount = uint256(bytes32(context[0x34:0x54]));
+        uint256 tokenPrice = uint256(bytes32(context[0x54:0x74]));
+        address user = address(bytes20(context[0x74:0x88]));
+        address guarantor = address(bytes20(context[0x88:0x9C]));
+
+        uint256 actualAmount = (actualGasCost +
+            (guarantor == address(0)).ternary(POST_OP_COST, POST_OP_COST_WITH_GUARANTOR) *
+            actualUserOpFeePerGas).mulDiv(tokenPrice, _tokenPriceDenominator());
+
+        if (guarantor == address(0)) {
+            token.safeTransfer(user, prefundAmount - actualAmount);
+            emit UserOperationSponsored(userOpHash, user, address(0), actualAmount, tokenPrice, false);
+        } else if (token.trySafeTransferFrom(user, address(this), actualAmount)) {
+            token.safeTransfer(guarantor, prefundAmount);
+            emit UserOperationSponsored(userOpHash, user, guarantor, actualAmount, tokenPrice, false);
+        } else {
+            token.safeTransfer(guarantor, prefundAmount - actualAmount);
+            emit UserOperationSponsored(userOpHash, user, guarantor, actualAmount, tokenPrice, true);
+        }
+    }
+
+    /**
+     * @dev Retrieves payment details for a user operation
+     *
+     * The values returned by this internal function are:
+     * * `validationData`: ERC-4337 validation data, indicating success/failure and optional time validity (`validAfter`, `validUntil`).
+     * * `token`: Address of the ERC-20 token used for payment to the paymaster.
+     * * `tokenPrice`: Price of the token in native currency, scaled by `_tokenPriceDenominator()`.
+     * * `guarantor`: Address of an entity advancing funds if the user lacks them; receives tokens during execution or pays if the user can't.
+     *
+     * ==== Calculating the token price
+     *
+     * Given gas fees are paid in native currency, developers can use the `ERC20 price unit / native price unit` ratio to
+     * calculate the price of an ERC20 token price in native currency. However, the token may have a different number of decimals
+     * than the native currency. For a a generalized formula considering prices in USD and decimals, consider using:
+     *
+     * `(<ERC-20 token price in $> / 10**<ERC-20 decimals>) / (<Native token price in $> / 1e18) * _tokenPriceDenominator()`
+     *
+     * For example, suppose token is USDC ($1 with 6 decimals) and native currency is ETH (assuming $2524.86 with 18 decimals),
+     * then each unit (1e-6) of USDC is worth `(1 / 1e6) / ((252486 / 1e2) / 1e18) = 396061563.8094785` wei. The `_tokenPriceDenominator()`
+     * ensures precision by avoiding fractional value loss. (i.e. the 0.8094785 part).
+     *
+     * ==== Guarantor
+     *
+     * To support a guarantor, developers can use the `paymasterData` field to store the guarantor's address. Developers can disable
+     * support for a guarantor by returning `address(0)`. If supported, ensure explicit consent (e.g., signature verification) to prevent
+     * unauthorized use.
+     */
+    function _fetchDetails(
+        PackedUserOperation calldata userOp,
+        bytes32 userOpHash
+    ) internal view virtual returns (uint256 validationData, IERC20 token, uint256 tokenPrice, address guarantor);
+
+    /// @dev Denominator used for interpreting the `tokenPrice` returned by {_fetchDetails} as "fixed point".
+    function _tokenPriceDenominator() internal view virtual returns (uint256) {
+        return 1e18;
+    }
+
+    /// @dev Public function that allows the withdrawer to extract ERC-20 tokens resulting from gas payments.
+    function withdrawTokens(IERC20 token, address recipient, uint256 amount) public virtual onlyWithdrawer {
+        if (amount == type(uint256).max) amount = token.balanceOf(address(this));
+        token.safeTransfer(recipient, amount);
+    }
+}