Paymaster

Introducing LocalPaymaster

• Whitelist-Based Sponsorship: Instead of requiring per-operation signatures, LocalPaymaster uses a whitelist of trusted bundlers (transaction originators) who are authorized to include sponsored UserOps.
• Efficient Gas Usage: By eliminating the need for extra signatures, the paymaster reduces the gas overhead for each sponsored transaction.
• Fallback Mechanism: If a transaction cannot be sponsored (e.g., due to rate limits), users have the option to submit their operations through alternative means, ensuring strong censorship resistance.

How LocalPaymaster Works

Contract Overview

contract LocalPaymaster is BasePaymaster {
  mapping(address => bool) public bundlerWhitelist;
  IMetaPaymaster public metaPaymaster;
  uint256 private constant POST_OP_OVERHEAD = 34982;
 
  // Constructor and functions...
}

• Bundler Whitelist: A mapping that keeps track of whitelisted bundler addresses (tx.origin). Only transactions originating from these addresses are eligible for sponsorship.
• MetaPaymaster Integration: The contract can interact with a metaPaymaster for additional funding mechanisms.
• Post-Operation Overhead: A constant used to estimate gas costs in the _postOp function.

Key Functions

1. Setting the Bundler Whitelist

   function setBundlerWhitelist(
     address[] calldata addresses,
     bool isWhitelisted
   ) public onlyOwner {
     for (uint256 i = 0; i < addresses.length; i++) {
       bundlerWhitelist[addresses[i]] = isWhitelisted;
     }
   }

   • Allows the contract owner to add or remove bundlers from the whitelist.
   • Ensures that only trusted bundlers can include sponsored UserOps.

2. Validating User Operations

   function _validatePaymasterUserOp(
     UserOperation calldata userOp,
     bytes32 userOpHash,
     uint256 requiredPreFund
   ) internal override returns (bytes memory context, uint256 validationData) {
     bool isWhitelisted = bundlerWhitelist[tx.origin];
     require(isWhitelisted, "LocalPaymaster: non-whitelisted tx.origin");
    
     emit UserOperationSponsored(userOpHash, requiredPreFund);
     return (abi.encode(userOp.maxFeePerGas, userOp.maxPriorityFeePerGas), 0);
   }

   • Checks if the transaction originator (tx.origin) is whitelisted.
   • Emits an event UserOperationSponsored upon successful validation.
   • Returns encoded gas fee parameters for use in the post-operation phase.

3. Post-Operation Handling

   function _postOp(
     PostOpMode mode,
     bytes calldata context,
     uint256 actualGasCost
   ) internal override {
     if (metaPaymaster == IMetaPaymaster(address(0))) {
       return;
     }
     if (mode == PostOpMode.postOpReverted) {
       return;
     }
     (uint256 maxFeePerGas, uint256 maxPriorityFeePerGas) = abi.decode(
       context,
       (uint256, uint256)
     );
     uint256 gasPrice = min(maxFeePerGas, maxPriorityFeePerGas + block.basefee);
     metaPaymaster.fund(
       address(this),
       actualGasCost + POST_OP_OVERHEAD * gasPrice
     );
   }

   • Handles post-operation funding by interacting with the metaPaymaster.
   • Calculates the gas price and requests reimbursement for the gas used.
   • Skips funding if the metaPaymaster is not set or if the operation reverted.

Security Considerations

• Trust in Bundlers: By relying on a whitelist, the contract assumes that whitelisted bundlers will validate and rate-limit UserOps appropriately.
• EIP-4337 Mempool Compatibility: Since the contract uses tx.origin, it is not compatible with the standard 4337 mempool, where ORIGIN is banned. This is an intentional trade-off for efficiency.

Integration with Local Protocol

By integrating LocalPaymaster into Local Protocol:

• Efficient Transactions: Users can submit transactions without worrying about gas fees, improving accessibility.
• Cost Reduction: Eliminates the need for per-operation signatures, reducing gas costs and making microtransactions feasible.
• Enhanced User Experience: Simplifies the onboarding process for new users unfamiliar with gas mechanics.

Usage Flow

1. User Operation Submission

   • The user submits a UserOp intended for sponsorship.
   • The UserOp does not include any paymaster-specific signatures or extra data.

2. Bundler Inclusion

   • A whitelisted bundler includes the UserOp in a batch to be sent to the EntryPoint contract.
   • The bundler is responsible for initial validation and rate-limiting.

3. Paymaster Validation

   • The LocalPaymaster contract validates the UserOp by checking the tx.origin against the whitelist.
   • If the bundler is whitelisted, the operation proceeds; otherwise, it is rejected.

4. Execution and Post-Operation

   • The EntryPoint contract executes the UserOp.
   • After execution, the _postOp function handles any necessary funding via the metaPaymaster.

Handling Unsuccessful Sponsorship

If the UserOp cannot be sponsored (e.g., the bundler is not whitelisted or rate limits are exceeded):

• Fallback Mechanism: Users can choose to submit their transaction using an alternative paymaster that may require a small fee.
• Censorship Resistance: By allowing transactions to be sent through the public mempool with standard gas fees, the system ensures that users are not entirely dependent on sponsored transactions.