PaymasterERC20 simplification via a PaymasterERC20Guarantor Extension (#107)

Co-authored-by: ernestognw <[email protected]>

Author: gonzaotc

contracts/account/README.adoc

@@ -12,6 +12,7 @@ This directory includes contracts to build accounts for ERC-4337. These include:
  * {ERC7579SignatureValidator}: Implementation of ERC7579Validator using ERC-7913 signature verification for address-less cryptographic keys.
  * {PaymasterCore}: An ERC-4337 paymaster implementation that includes the core logic to validate and pay for user operations.
  * {PaymasterERC20}: A paymaster that allows users to pay for user operations using ERC-20 tokens.
+ * {PaymasterERC20Guarantor}: A paymaster that enables third parties to guarantee user operations by pre-funding gas costs, with the option for users to repay or for guarantors to absorb the cost.
  * {PaymasterERC721Owner}: A paymaster that allows users to pay for user operations based on ERC-721 ownership.
  * {PaymasterSigner}: A paymaster that allows users to pay for user operations using an authorized signature.
 
@@ -41,6 +42,8 @@ This directory includes contracts to build accounts for ERC-4337. These include:
 
 {{PaymasterERC20}}
 
+{{PaymasterERC20Guarantor}}
+
 {{PaymasterERC721Owner}}
 
 {{PaymasterSigner}}

contracts/account/paymaster/PaymasterERC20.sol

@@ -4,7 +4,6 @@ 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";
 
@@ -17,60 +16,105 @@ import {PaymasterCore} from "./PaymasterCore.sol";
  * 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
+ * ) internal view override returns (uint256 validationData, IERC20 token, uint256 tokenPrice) {
+ *     // Implement logic to fetch the token, and token price from the userOp
  * }
  * ```
+ *
+ * The contract follows a pre-charge and refund model:
+ * 1. During validation, it pre-charges the maximum possible gas cost
+ * 2. After execution, it refunds any unused gas back to the user
  */
 abstract contract PaymasterERC20 is PaymasterCore {
     using ERC4337Utils for *;
     using Math for *;
     using SafeERC20 for IERC20;
 
+    /**
+     * @dev Emitted when a user operation identified by `userOpHash` is sponsored by this paymaster
+     * using the specified ERC-20 `token`. The `tokenAmount` is the amount charged for the operation,
+     * and `tokenPrice` is the price of the token in native currency (e.g., ETH).
+     */
     event UserOperationSponsored(
         bytes32 indexed userOpHash,
-        address indexed user,
-        address indexed guarantor,
+        address indexed token,
         uint256 tokenAmount,
-        uint256 tokenPrice,
-        bool paidByGuarantor
+        uint256 tokenPrice
     );
 
-    // 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;
+    /**
+     * @dev Throws when the paymaster fails to refund the difference between the `prefundAmount`
+     * and the `actualAmount` of `token`.
+     */
+    error PaymasterERC20FailedRefund(IERC20 token, uint256 prefundAmount, uint256 actualAmount, bytes prefundContext);
 
-    /// @inheritdoc PaymasterCore
+    /**
+     * @dev See {PaymasterCore-_validatePaymasterUserOp}.
+     *
+     * Attempts to retrieve the `token` and `tokenPrice` from the user operation (see {_fetchDetails})
+     * and prefund the user operation using these values and the `maxCost` argument (see {_prefund}).
+     *
+     * Returns `abi.encodePacked(userOpHash, token, tokenPrice, prefundAmount, prefunder, prefundContext)` in
+     * `context` if the prefund is successful. Otherwise, it returns empty bytes.
+     */
     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(
+        IERC20 token;
+        uint256 tokenPrice;
+        (validationData, token, tokenPrice) = _fetchDetails(userOp, userOpHash);
+        context = abi.encodePacked(userOpHash, token, tokenPrice);
+        (bool prefunded, uint256 prefundAmount, address prefunder, bytes memory prefundContext) = _prefund(
             userOp,
-            userOpHash
+            userOpHash,
+            token,
+            tokenPrice,
+            userOp.sender,
+            maxCost
         );
 
-        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);
+        if (validationData == ERC4337Utils.SIG_VALIDATION_FAILED || !prefunded)
+            return (bytes(""), ERC4337Utils.SIG_VALIDATION_FAILED);
+
+        return (abi.encodePacked(context, prefundAmount, prefunder, prefundContext), validationData);
+    }
+
+    /**
+     * @dev Prefunds the `userOp` by charging the maximum possible gas cost (`maxCost`) in ERC-20 `token`.
+     *
+     * The `token` and `tokenPrice` is obtained from the {_fetchDetails} function and are funded by the `prefunder_`,
+     * which is the user operation sender by default. The `prefundAmount` is calculated using {_erc20Cost}.
+     *
+     * Returns a `prefundContext` that's passed to the {_postOp} function through its `context` return value.
+     *
+     * NOTE: Consider not reverting if the prefund fails when overriding this function. This is to avoid reverting
+     * during the validation phase of the user operation, which may penalize the paymaster's reputation according
+     * to ERC-7562 validation rules.
+     */
+    function _prefund(
+        PackedUserOperation calldata userOp,
+        bytes32 /* userOpHash */,
+        IERC20 token,
+        uint256 tokenPrice,
+        address prefunder_,
+        uint256 maxCost
+    ) internal virtual returns (bool prefunded, uint256 prefundAmount, address prefunder, bytes memory prefundContext) {
+        uint256 feePerGas = userOp.maxFeePerGas();
+        uint256 _prefundAmount = _erc20Cost(maxCost, feePerGas, tokenPrice);
+        return (token.trySafeTransferFrom(prefunder_, address(this), _prefundAmount), _prefundAmount, prefunder_, "");
     }
 
-    /// @inheritdoc PaymasterCore
+    /**
+     * @dev Attempts to refund the user operation after execution. See {_refund}.
+     *
+     * Reverts with {PaymasterERC20FailedRefund} if the refund fails.
+     *
+     * IMPORTANT: This function may revert after the user operation has been executed without
+     * reverting the user operation itself. Consider implementing a mechanism to handle
+     * this case gracefully.
+     */
     function _postOp(
         PostOpMode /* mode */,
         bytes calldata context,
@@ -79,36 +123,54 @@ abstract contract PaymasterERC20 is PaymasterCore {
     ) 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);
+        uint256 tokenPrice = uint256(bytes32(context[0x34:0x54]));
+        uint256 prefundAmount = uint256(bytes32(context[0x54:0x74]));
+        address prefunder = address(bytes20(context[0x74:0x88]));
+        bytes calldata prefundContext = context[0x88:];
+
+        (bool refunded, uint256 actualAmount) = _refund(
+            token,
+            tokenPrice,
+            actualGasCost,
+            actualUserOpFeePerGas,
+            prefunder,
+            prefundAmount,
+            prefundContext
+        );
+        if (!refunded) {
+            revert PaymasterERC20FailedRefund(token, prefundAmount, actualAmount, prefundContext);
         }
+
+        emit UserOperationSponsored(userOpHash, address(token), actualAmount, tokenPrice);
+    }
+
+    /**
+     * @dev Refunds any unused gas back to the user (i.e. `prefundAmount - actualAmount`) in `token`.
+     *
+     * The `actualAmount` is calculated using {_erc20Cost} and the `actualGasCost`, `actualUserOpFeePerGas`, `prefundContext`
+     * and the `tokenPrice` from the {_postOp}'s context.
+     */
+    function _refund(
+        IERC20 token,
+        uint256 tokenPrice,
+        uint256 actualGasCost,
+        uint256 actualUserOpFeePerGas,
+        address prefunder,
+        uint256 prefundAmount,
+        bytes calldata /* prefundContext */
+    ) internal virtual returns (bool refunded, uint256 actualAmount) {
+        uint256 actualAmount_ = _erc20Cost(actualGasCost, actualUserOpFeePerGas, tokenPrice);
+        return (token.trySafeTransfer(prefunder, prefundAmount - actualAmount_), actualAmount_);
     }
 
     /**
-     * @dev Retrieves payment details for a user operation
+     * @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
      *
@@ -121,23 +183,27 @@ abstract contract PaymasterERC20 is PaymasterCore {
      * 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);
+    ) internal view virtual returns (uint256 validationData, IERC20 token, uint256 tokenPrice);
+
+    /// @dev Over-estimates the cost of the post-operation logic.
+    function _postOpCost() internal view virtual returns (uint256) {
+        return 30_000;
+    }
 
-    /// @dev Denominator used for interpreting the `tokenPrice` returned by {_fetchDetails} as "fixed point".
+    /// @dev Denominator used for interpreting the `tokenPrice` returned by {_fetchDetails} as "fixed point" in {_erc20Cost}.
     function _tokenPriceDenominator() internal view virtual returns (uint256) {
         return 1e18;
     }
 
+    /// @dev Calculates the cost of the user operation in ERC-20 tokens.
+    function _erc20Cost(uint256 cost, uint256 feePerGas, uint256 tokenPrice) internal view virtual returns (uint256) {
+        return (cost + _postOpCost() * feePerGas).mulDiv(tokenPrice, _tokenPriceDenominator());
+    }
+
     /// @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));

contracts/account/paymaster/PaymasterERC20Guarantor.sol

@@ -0,0 +1,121 @@
+// 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 {PaymasterERC20} from "./PaymasterERC20.sol";
+
+/**
+ * @dev Extension of {PaymasterERC20} that enables third parties to guarantee user operations.
+ *
+ * This contract allows a guarantor to pre-fund user operations on behalf of users. The guarantor
+ * pays the maximum possible gas cost upfront, and after execution:
+ * 1. If the user repays the guarantor, the guarantor gets their funds back
+ * 2. If the user fails to repay, the guarantor absorbs the cost
+ *
+ * A common use case is for guarantors to pay for the operations of users claiming airdrops. In this scenario:
+ *
+ * * The guarantor pays the gas fees upfront
+ * * The user claims their airdrop tokens
+ * * The user repays the guarantor from the claimed tokens
+ * * If the user fails to repay, the guarantor absorbs the cost
+ *
+ * The guarantor is identified through the {_fetchGuarantor} function, which must be implemented
+ * by developers to determine who can guarantee operations. This allows for flexible guarantor selection
+ * logic based on the specific requirements of the application.
+ */
+abstract contract PaymasterERC20Guarantor is PaymasterERC20 {
+    using SafeERC20 for IERC20;
+
+    /// @dev Emitted when a user operation identified by `userOpHash` is guaranteed by a `guarantor` for `prefundAmount`.
+    event UserOperationGuaranteed(bytes32 indexed userOpHash, address indexed guarantor, uint256 prefundAmount);
+
+    /**
+     * @dev Prefunds the user operation using either the guarantor or the default prefunder.
+     * See {PaymasterERC20-_prefund}.
+     *
+     * Returns `abi.encodePacked(..., userOp.sender)` in `prefundContext` to allow
+     * the refund process to identify the user operation sender.
+     */
+    function _prefund(
+        PackedUserOperation calldata userOp,
+        bytes32 userOpHash,
+        IERC20 token,
+        uint256 tokenPrice,
+        address prefunder_,
+        uint256 maxCost
+    )
+        internal
+        virtual
+        override
+        returns (bool prefunded, uint256 prefundAmount, address prefunder, bytes memory prefundContext)
+    {
+        address guarantor = _fetchGuarantor(userOp);
+        bool isGuaranteed = guarantor != address(0);
+        (prefunded, prefundAmount, prefunder, prefundContext) = super._prefund(
+            userOp,
+            userOpHash,
+            token,
+            tokenPrice,
+            isGuaranteed ? guarantor : prefunder_,
+            maxCost + (isGuaranteed ? 0 : _guaranteedPostOpCost())
+        );
+        if (prefunder == guarantor) {
+            emit UserOperationGuaranteed(userOpHash, prefunder, prefundAmount);
+        }
+        return (prefunded, prefundAmount, prefunder, abi.encodePacked(prefundContext, userOp.sender));
+    }
+
+    /**
+     * @dev Handles the refund process for guaranteed operations.
+     *
+     * If the operation was guaranteed, it attempts to get repayment from the user first and then refunds the guarantor.
+     * Otherwise, fallback to {PaymasterERC20-refund}. See {_refundGuaranteed}.
+     *
+     * NOTE: For guaranteed user operations where the user paid the `actualGasCost` back, this function
+     * doesn't call `super._refund`. Consider whether there are side effects in the parent contract that need to be executed.
+     */
+    function _refund(
+        IERC20 token,
+        uint256 tokenPrice,
+        uint256 actualGasCost,
+        uint256 actualUserOpFeePerGas,
+        address prefunder,
+        uint256 prefundAmount,
+        bytes calldata prefundContext
+    ) internal virtual override returns (bool refunded, uint256 actualAmount) {
+        address userOpSender = address(bytes20(prefundContext[0x00:0x14]));
+
+        if (prefunder != userOpSender) {
+            actualAmount = _erc20Cost(actualGasCost, actualUserOpFeePerGas, tokenPrice);
+            if (token.trySafeTransferFrom(userOpSender, address(this), actualAmount)) {
+                // The paymaster gets the funds first, so in case of a failure, the guarantor absorbs the cost.
+                return (token.trySafeTransfer(prefunder, prefundAmount), actualAmount);
+            }
+        }
+        return
+            super._refund(
+                token,
+                tokenPrice,
+                actualGasCost,
+                actualUserOpFeePerGas,
+                prefunder,
+                prefundAmount,
+                prefundContext
+            );
+    }
+
+    /**
+     * @dev Fetches the guarantor address and validation data from the user operation.
+     *
+     * NOTE: Return `address(0)` to disable the guarantor feature. If supported, ensure
+     * explicit consent (e.g., signature verification) to prevent unauthorized use.
+     */
+    function _fetchGuarantor(PackedUserOperation calldata userOp) internal view virtual returns (address guarantor);
+
+    /// @dev Over-estimates the cost of the post-operation logic. Added on top of guaranteed userOps post-operation cost.
+    function _guaranteedPostOpCost() internal view virtual returns (uint256) {
+        return 15_000;
+    }
+}