Paymasters

Paymasters are smart contracts that pay for the gas fees of transactions on behalf of other accounts.

All paymasters must implement the IPaymaster interface. As outlined in the transaction flow, after the smart contract wallet validates and executes the transaction, it can optionally call prepareForPaymaster to delegate the payment of the gas fees to a paymaster set in the transaction, at which point the paymaster will validate and pay for the transaction.

​

Get Started with Paymasters

Use our example repositories to quickly get started building paymasters.

Or follow our video tutorial for a step-by-step guide to building a smart contract wallet.

​

IPaymaster Interface

The IPaymaster interface defines the mandatory functions that a paymaster must implement to be compatible with Abstract. View source code ↗.

First, install the system contracts library:

Then, import and implement the IPaymaster interface in your smart contract:

import {IPaymaster} from "@matterlabs/zksync-contracts/l2/system-contracts/interfaces/IPaymaster.sol";

contract MyPaymaster is IPaymaster {
  // Implement the interface (see docs below)
    // validateAndPayForPaymasterTransaction
    // postTransaction
}

​

validateAndPayForPaymasterTransaction

This function is called to perform 2 actions:

1. Validate (determine whether or not to sponsor the gas fees for) the transaction.
2. Pay the gas fee to the bootloader for the transaction. This method must send at least tx.gasprice * tx.gasLimit to the bootloader. Learn more about gas fees and gas refunds.

To validate (i.e. agree to sponsor the gas fee for) a transaction, this function should return magic = PAYMASTER_VALIDATION_SUCCESS_MAGIC. Optionally, you can also provide context that is provided to the postTransaction function called after the transaction is executed.

function validateAndPayForPaymasterTransaction(
    bytes32 _txHash,
    bytes32 _suggestedSignedHash,
    Transaction calldata _transaction
) external payable returns (bytes4 magic, bytes memory context);

​

postTransaction

This function is optional and is called after the transaction is executed. There is no guarantee this method will be called if the transaction fails with out of gas error.

function postTransaction(
    bytes calldata _context,
    Transaction calldata _transaction,
    bytes32 _txHash,
    bytes32 _suggestedSignedHash,
    ExecutionResult _txResult,
    uint256 _maxRefundedGas
) external payable;

​

Sending Transactions with a Paymaster

Use EIP-712 formatted transactions to submit transactions with a paymaster set. You must specify a customData object containing a valid paymasterParams object.

import { Provider, Wallet } from "zksync-ethers";
import { getApprovalBasedPaymasterInput, getGeneralPaymasterInput, getPaymasterParams } from "zksync-ethers/build/paymaster-utils";

// Address of the deployed paymaster contract
const CONTRACT_ADDRESS = "YOUR-PAYMASTER-CONTRACT-ADDRESS";

// An example of a script to interact with the contract
export default async function () {
  const provider = new Provider("https://explorer.testnet.abs.xyz");
  const wallet = new Wallet(privateKey ?? process.env.WALLET_PRIVATE_KEY!, provider);
  const type = "General"; // We're using a general flow in this example

  // Create the object: You can use the helper functions that are imported!
  const paymasterParams = getPaymasterParams(
    CONTRACT_ADDRESS,
    {
      type,
      innerInput: getGeneralPaymasterInput({
        type,
        innerInput: "0x", // Any additional info to send to the paymaster. We leave it empty here.
      })
    }
  );

  // Submit tx, as an example, send a message to another wallet.
  const tx = await wallet.sendTransaction({
    to: "0x8e729E23CDc8bC21c37a73DA4bA9ebdddA3C8B6d" // Example, send message to some other wallet
    data: "0x1337" // Example, some arbitrary data
    customData: {
      paymasterParams, // Provide the paymaster params object here!
    }
  })

  const res = await tx.wait();
}

​

Paymaster Flows

Below are two example flows for paymasters you can use as a reference to build your own paymaster:

1. General Paymaster Flow: Showcases a minimal paymaster that sponsors all transactions.
2. Approval-Based Paymaster Flow: Showcases how users can pay for gas fees with an ERC-20 token.

​

Smart Contract References