Paymaster

The PaymasterClient enables gas sponsorship for your users through the ERC-4337 paymaster protocol. Users can send transactions without holding native tokens for gas, or pay gas fees using ERC-20 tokens.

PaymasterClient Features

Methods

getPaymasterData

Requests paymasterAndData and updated gas limits from the paymaster service. This is the primary method for obtaining gas sponsorship for a UserOperation.

getTokenPaymasterData

Convenience method for paying gas in specific ERC-20 tokens. Wraps the sponsorship request with token-specific parameters.

validatePaymasterUserOp

Checks if the paymaster will accept a specific UserOperation before submission. Use this as a pre-flight validation step to avoid failed transactions.

How Sponsorship Works

1. The SDK constructs a UserOperation with gas estimates from the bundler
2. The UserOperation is sent to the paymaster via pm_sponsorUserOperation
3. The paymaster returns paymasterAndData containing its sponsorship commitment and optionally adjusted gas limits
4. The complete UserOperation (with paymaster data) is signed by MPC
5. The bundler submits the sponsored UserOperation to the EntryPoint
6. The EntryPoint executes the transaction, with gas paid by the paymaster

Configuration

The paymaster is configured through the chain configuration. NERO chains include built-in paymaster endpoints:

For custom chains, specify the paymasterUrl field in your ChainConfig:

const customChain: ChainConfig = {
  chainId: 689,
  chainName: "nero-testnet",
  displayName: "NERO Testnet",
  nativeCurrency: { name: "NERO", symbol: "NERO", decimals: 18 },
  rpcUrls: ["https://rpc-testnet.nerochain.io"],
  isTestnet: true,
  paymasterUrl: "https://paymaster-testnet.nerochain.io",
  bundlerUrl: "https://bundler-testnet.nerochain.io",
  entryPointAddress: "0x5FF137D4b0FDCD49DcA30c7CF57E578a026d2789",
  simpleAccountFactoryAddress: "0x9406Cc6185a346906296840746125a0E44976454",
};

Integration with UserOperation Flow

The paymaster integrates at step 4 of the UserOperation lifecycle:

1. Fetch current account nonce
2. Encode target contract call data
3. Estimate gas via bundler (estimateUserOperationGas)
4. Fetch paymaster data if sponsorship is enabled
5. Assemble complete UserOperation
6. Sign UserOperation hash with MPC
7. Submit via sendUserOperation
8. Poll for receipt via waitForUserOperationReceipt

When a paymaster is configured, the SDK automatically requests sponsorship data and includes it in the UserOperation before signing. The paymaster can also override gas estimates returned by the bundler if needed.