Install Paymaster Kit dependencies
Set up the development environment with the correct Paymaster Kit libraries to ensure compatibility with ERC-4337 bundlers. This step installs the foundational packages needed to interact with the Entry Point contract and manage user operations.
Initialize your project directory if you haven't already, then install the core Paymaster Kit package. This library provides the necessary abstractions for gas sponsorship logic and integrates directly with the ERC-4337 standard.
After installation, verify the package integrity by checking your node_modules directory. The presence of the @account-abstraction folders confirms that the necessary contracts and utilities are ready for configuration. Proceed to the next section to configure the paymaster logic.
Configure gas sponsorship logic
Setting up the paymaster contract requires defining how user operations are validated and which assets cover the gas costs. The core logic resides in the validatePaymasterUserOp function, which acts as the gatekeeper for sponsorship. You must explicitly choose between paying gas in native ETH or in an ERC-20 token like USDC, as this decision dictates your funding requirements and security model.
Implement validation rules
The paymaster contract must verify that the user operation is eligible for sponsorship before signing. This typically involves checking the aggregator field to ensure the user's signature is valid, and then applying your own business logic. For example, you might restrict sponsorship to specific user addresses, limit the total gas spent per day, or require a minimum deposit in the contract.
The validation function should return a context string. This context is passed to the postOp function later, allowing you to track how much gas was actually consumed. If the operation fails validation, the user pays for the gas; if it passes, the paymaster assumes liability.
Set fee payment methods
You need to decide whether your dApp will subsidize gas using ETH or an ERC-20 token. Paying in ETH is simpler but requires maintaining a balance of native currency on the contract. Paying in ERC-20 tokens, such as USDC, allows users to pay with their existing holdings, which can improve user experience by removing the need to buy ETH first.
If you choose ERC-20 sponsorship, the contract must handle token approvals and transfers. The paymaster will need to pre-fund the contract with the chosen token. When a user operation is executed, the bundler pays the gas in ETH, and your contract reimburses the bundler or settles the debt using the ERC-20 tokens. This approach requires careful handling of token allowances to prevent unauthorized drains.
Finalize funding and deployment
Before deploying, ensure the contract has sufficient balance for the chosen payment method. If using ERC-20, transfer the tokens to the paymaster address. If using ETH, send native currency to the contract address. Deploy the contract to your target network and update your dApp configuration to point to the new paymaster address.
Deploy to testnet and verify
Before moving to production, you must deploy your Paymaster contract to a public testnet and verify it against the bundler and smart account implementation. This step confirms that the contract is correctly deployed, the bytecode matches your source code, and the ERC-4337 flow functions as expected.
1. Deploy the contract
Use your deployment script to push the Paymaster contract to a testnet such as Sepolia or Holesky. Ensure you have sufficient test ETH in your deployer wallet to cover gas costs. For ERC-4337, the bundler must recognize the Paymaster’s address, so note the deployed address carefully.
2. Verify the source code
Once deployed, verify the contract on a block explorer like Etherscan or Sepolia Etherscan. This step is critical for transparency and allows the bundler to read the contract’s ABI. Use the etherscan plugin in Hardhat or the verify command in Foundry. Provide the constructor arguments used during deployment to ensure the verification matches exactly.
3. Test with a smart account and bundler
Run a test transaction using a smart account (like Safe or SimpleAccount) and your Paymaster. Send a small test transaction through the bundler. If the bundler includes your transaction in a UserOperation, the Paymaster is functioning correctly. If the transaction reverts, check the Paymaster’s validatePaymasterUserOp logic for errors.
4. Confirm sponsorship
Verify that the gas fees for the test transaction are paid by your Paymaster, not the user. Check the transaction receipt on the block explorer to confirm that the paymaster field is populated and the gas costs were deducted from your Paymaster’s balance or sponsor wallet. This confirms the gas sponsorship mechanism is active and legitimate.
Test gas sponsorship flows
Validating your ERC-4337 paymaster integration requires confirming that user operations (UserOps) are correctly sponsored and that the paymaster covers gas fees without reverting transactions. This section walks through the essential verification steps to ensure your paymaster contract interacts properly with the bundler and the entry point.
Before sending a transaction, inspect the UserOperation struct. Ensure the paymasterAndData field is correctly formatted, containing the paymaster address and any required signature or data payload. An incorrectly formatted field will cause immediate rejection by the entry point contract.
Use a local bundler (such as the Alchemy bundler or a local Halmi instance) to simulate the transaction. This step allows you to validate the paymaster’s pre- and post-op logic without spending real gas. Check the bundler’s response for any UserOperation validation errors or paymaster-specific reverts.
Once local simulation passes, submit the signed UserOperation to a public testnet bundler (e.g., Sepolia or Holesky). Monitor the mempool to ensure the bundler includes your operation in a batch. Verify that the transaction is included in a block and that the gas fees are deducted from your paymaster’s balance, not the user’s.
After inclusion, query the entry point contract to confirm the operation was executed successfully. Check the UserOperation receipt for any events emitted by your paymaster, such as PaymasterDeposit or PaymasterStake updates. Ensure the user’s balance or state changes as expected, confirming the sponsorship was applied correctly.
For more details on how paymasters function within the ERC-4337 ecosystem, refer to the Alchemy Paymaster overview.
Common integration errors and fixes
When deploying a Paymaster Kit for ERC-4337, the most frequent roadblocks involve signature validation and bundler rejections. These errors usually stem from mismatched data structures or incorrect gas parameters rather than fundamental protocol flaws. Follow this sequence to diagnose and resolve the most common integration failures.
Signature validation failures
The paymaster must validate the user’s signature against the expected hash. If validation fails, check that the paymasterAndData field is correctly formatted. The paymaster address and its specific data must be concatenated without errors. Ensure the signature scheme (e.g., EIP-712 or ECDSA) matches the one registered in your paymaster contract.
Verify that the userOpHash used in the signature matches the hash calculated by the bundler. Mismatches here are common when the paymaster uses a different hash function than the entry point. Align your paymaster’s signature verification logic with the EntryPoint’s expectations.
Bundler rejection errors
Bundlers reject operations that violate the EntryPoint’s rules. The most common reason is insufficient stake or unbonding issues if you are testing on a testnet with strict requirements. Ensure your paymaster is properly staked according to the network’s minimum requirements.
Another frequent cause is the preVerificationGas calculation. If this value is too low, the bundler cannot include your operation in a block. Increase the preVerificationGas buffer to account for signature overhead and data encoding. Use the official Safe Protocol Kit documentation for specific gas estimation guidelines when integrating with Safe accounts.
Mismatched entry point versions
Ensure your paymaster contract is compatible with the EntryPoint version you are targeting. ERC-4337 has evolved, and contracts built for v0.6 may not work with v0.7 without updates. Check the EntryPoint interface in your deployment configuration. If you are migrating, update the paymaster’s inheritance and function signatures accordingly.
Frequently asked questions about paymasters
Helpful gear
Use these product recommendations as a starting point, then choose the size, material, and price point that fit how you actually use the gear.
As an Amazon Associate, we may earn from qualifying purchases.
No comments yet. Be the first to share your thoughts!