Paymaster

The CandidePaymaster class interacts with Candide's ERC-4337 Paymaster API.

Supports:

• Gas sponsorship through Gas Policies
• ERC-20 Token Sponsorship
• Multi-EntryPoint

Usage

Import

import { CandidePaymaster } from "abstractionkit";

How to Use

Initialize a Paymaster with your RPC URL. Get an API key from the dashboard.

paymaster.ts

import { CandidePaymaster } from "abstractionkit";

const paymasterRPC = "https://api.candide.dev/public/v3/sepolia";
const paymaster: CandidePaymaster = new CandidePaymaster(paymasterRPC);

Then consume Paymaster methods:

const supportedEntryPoints = await paymaster.getSupportedEntrypoints();

Methods

createSponsorPaymasterUserOperation

Returns the paymaster data if the the userOperation has a Gas Policy. Otherwise it returns an error message. Supports two types of Gas Policies:

• Public Gas Policies: These are gas policies provided by third parties, which do not require a sponsorship policy ID.
• Private Gas Policies: These require a sponsorship policy ID and can be used if no public gas policy matches the user operation.

Usage

example.ts

example.ts

import { CandidePaymaster } from "abstractionkit";

const paymasterRPC = "https://api.candide.dev/public/v3/sepolia";
const paymaster: CandidePaymaster = new CandidePaymaster(paymasterRPC);
const sponsorshipPolicyId = '1234';

// Use createUserOperation() to help you construct a userOp
const userOperation = smartAccount.createUserOperation(..)

const [sponsoredUserOperation, sponsorMetadata] =
  await paymaster.createSponsorPaymasterUserOperation(
    userOperation,
    bundlerUrl,
    sponsorshipPolicyId, // optional
  );

Param Type

key	type	description
userOperation	UserOperationV6 | UserOperationV7 | UserOperationV8 | UserOperationV9	UserOperation to Sponsor. Supports EntryPoint v0.6, v0.7, v0.8, and v0.9
bundlerUrl	string	Bundler URL to estimate the gas
sponsorshipPolicyId	string?	Optional sponsorship policy id if using a Private Gas Policy

Return Type

key	type	description
userOperation	UserOperationV6 | UserOperationV7 | UserOperationV8 | UserOperationV9	UserOperation with paymaster data included
sponsorMetadata	key type description name string Name of Sponsor who is sponsoring the Gas Policy description string A short description of the sponsor url string Website of the Sponsor icons string[] Logos or Icons that the Sponsor is using to promote their Gas Policy	Information about the Gas Policy Sponsor

Source code

createSponsorPaymasterUserOperation

fetchSupportedERC20TokensAndPaymasterMetadata

Returns a promise with the supported erc20 tokens and their exchange rate, along with the paymaster metadata

Usage

example.ts

example.ts

import { CandidePaymaster, SafeAccountV0_3_0 as SafeAccount } from "abstractionkit";

const paymasterRPC="https://api.candide.dev/public/v3/sepolia";
const paymaster = new CandidePaymaster(paymasterRPC);

const supportedERC20Tokens = await paymaster.fetchSupportedERC20TokensAndPaymasterMetadata(SafeAccount.DEFAULT_ENTRYPOINT_ADDRESS);

Param Types

key	type	description
entrypoint	string?	EntryPoint Address. Defaults to V0.7

Response Type

key	type	description
SupportedERC20TokensAndMetadataWithExchangeRate	Promise<SupportedERC20TokensAndMetadataV7WithExchangeRate | SupportedERC20TokensAndMetadataV6WithExchangeRate>	A promise with the list of supported erc20 tokens and their exchange rate

SupportedERC20TokensAndMetadataV7WithExchangeRate

key	type	description
paymasterMetadata	key type description name string The name of the Paymaster. description string A brief description of the Paymaster. icons string[] An array of icon URLs representing the Paymaster's brand or logo. address string The contract address of the Paymaster. sponsoredEventTopic string The event topic that will be emitted when a UserOperation is sponsored by the Paymaster. dummyPaymasterAndData key type description paymaster string The address of the Paymaster. paymasterVerificationGasLimit bigint The amount of gas allocated for the Paymaster verification step. paymasterPostOpGasLimit bigint The amount of gas allocated for the Paymaster post-operation step. paymasterData string Encoded data for the Paymaster. Dummy Paymaster data used for gas estimation.	The Paymaster metadata
tokens	key type description name string The name of the ERC20 token. symbol string The symbol representing the ERC20 token. address string The contract address of the ERC20 token. decimals number The number of decimal places for the token. exchangeRate bigint The exchange rate of the token.	Supported erc20 tokens with Exchange Rate

SupportedERC20TokensAndMetadataV6WithExchangeRate

key	type	description
paymasterMetadata	key type description name string The name of the Paymaster. description string A brief description of the Paymaster. icons string[] An array of icon URLs representing the Paymaster's brand or logo. address string The contract address of the Paymaster. sponsoredEventTopic string The event topic that will be emitted when a UserOperation is sponsored by the Paymaster. dummyPaymasterAndData string Dummy Paymaster data used for gas estimation.	The Paymaster metadata
tokens	key type description name string The name of the ERC20 token. symbol string The symbol representing the ERC20 token. address string The contract address of the ERC20 token. decimals number The number of decimal places for the token. exchangeRate bigint The exchange rate of the token.	Supported erc20 tokens with Exchange Rate

Example Response

{
  tokens: [
    {
      name: 'USD Coin',
      symbol: 'USDC',
      address: '0xaf88d065e77c8cC2239327C5EDb3A432268e5831',
      decimals: 6,
      exchangeRate: 123n
    },
    {
      name: 'Tether USDT',
      symbol: 'USDT',
      address: '0xFd086bC7CD5C481DCC9C85ebE478A1C0b69FCbb9',
      decimals: 6,
      exchangeRate: 123n
    },
    {
      name: 'Dai Stablecoin',
      symbol: 'DAI',
      address: '0xDA10009cBd5D07dd0CeCc66161FC93D7c9000da1',
      decimals: 18,
      exchangeRate: 123n
    }
  ],
  paymasterMetadata: {
    name: 'CANDIDE Paymaster',
    description: 'CANDIDE Paymaster a fast, secure and feature-rich 4337 Paymaster',
    icons: [],
    address: '0x8b1f6cb5d062aa2ce8d581942bbb960420d875ba',
    sponsoredEventTopic: '0xa050a122b4c0e369e3385eb6b7cccd8019638b2764de67bec0af99130ddf8471',
    dummyPaymasterAndData: {
      paymaster: '0x8b1f6cb5d062aa2ce8d581942bbb960420d875ba',
      paymasterVerificationGasLimit: '0xffff',
      paymasterPostOpGasLimit: '0xffff',
      paymasterData: '0x00010000000000ffff000000000000000000000000000000000000000000000000000000000000ffff010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101011c'
    }
  }
}

createTokenPaymasterUserOperation

Estimates gas limits and returns the user operation with the paymaster data for ERC-20 Token sponsorship.

Token Approval Reset

Some tokens like USDT do not allow changing a non-zero allowance directly. For known tokens (e.g. USDT on Ethereum mainnet), the SDK automatically prepends an approve(0) call before the actual approval. You can also manually trigger this behavior for other tokens by setting resetApproval: true in the overrides.

The overrides parameter also accepts an entrypoint field, which allows you to manually specify the EntryPoint address instead of relying on auto-detection from the UserOperation structure.

Usage

example.ts

import { SafeAccountV0_3_0 as SafeAccount, CandidePaymaster } from "abstractionkit";

const paymasterRPC="https://api.candide.dev/public/v3/sepolia";
const erc20TokenAddress = "0xFa5854FBf9964330d761961F46565AB7326e5a3b"; // CTT test token
const bundlerRPC = "https://api.candide.dev/public/v3/sepolia";

const ownerPublicAddress = "0x2Ef844456580b6e1E22e1D584EBbC2467D9298B2"
const smartAccount = SafeAccount.initializeNewAccount([ownerPublicAddress])

// Use createUserOperation() to help you construct a userOp
let userOperation = smartAccount.createUserOperation(..);

const paymaster: CandidePaymaster = new CandidePaymaster(paymasterRPC);

userOperation = await paymaster.createTokenPaymasterUserOperation(
  smartAccount,
  userOperation,
  erc20TokenAddress,
  bundlerRPC,
);

Param Types

key	type	description
smartAccount	(callData: string, tokenAddress: string, paymasterAddress: string, approveAmount: bigint) => string	The SmartAccount object that created the target userOperation
userOperation	UserOperationV6 | UserOperationV7 | UserOperationV8 | UserOperationV9	The userOperation to sponsor gas with erc-20 paymaster
tokenAddress	string	The address of the token to approve.
bundlerRpc	string	The Bundler RPC to estimate the gas
overrides	key type description entrypoint string? Set the EntryPoint address instead of auto-detecting it from the UserOperation structure. resetApproval boolean? When true, prepend an approve(0) call before the actual token approval. Required for tokens like USDT that do not allow changing a non-zero allowance directly. Automatically applied for known tokens (e.g. USDT on Ethereum mainnet). callGasLimit bigint Set the callGasLimit instead of estimating gas using the bundler. verificationGasLimit bigint Set the verificationGasLimit instead of estimating gas using the bundler. preVerificationGas bigint Set the preVerificationGas instead of estimating gas using the bundler. callGasLimitPercentageMultiplier number Set the callGasLimitPercentageMultiplier instead of estimating gas using the bundler. verificationGasLimitPercentageMultiplier number Set the verificationGasLimitPercentageMultiplier instead of estimating gas using the bundler. preVerificationGasPercentageMultiplier number Set the preVerificationGasPercentageMultiplier instead of estimating gas using the bundler. stateOverrideSetType key type description [address: string] key type description balance bigint Override the balance of the address nonce bigint Override the nonce of the address code string Override the code of the address state Dictionary<string> Override the storage slots of the address stateDiff Dictionary<string> Apply state differences to the storage slots of the address Overrides for a specific address Pass state overrides for gas estimation, including balance, nonce, code, and state or stateDiff for the account at each address.	Overrides for the default values

Response Type

key	type	description
userOperation	Promise<UserOperationV6 | UserOperationV7 | UserOperationV8 | UserOperationV9>	The userOperation to sponsor gas with erc-20 paymaster

Example Response

{
  sender: '0xb8741a449d50ed0dcfe395287f85be152884c8d9',
  nonce: 10n,
  initCode: '0x',
  callData: '0x541d63c800000000000000000000000038869bf66a61cf6bdb996a6ae40d5853fd43b52600000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000080000000000000000000000000000000000000000000000000000000000000000100000000000000000000000000000000000000000000000000000000000001e48d80ff0a0000000000000000000000000000000000000000000000000000000000000020000000000000000000000000000000000000000000000000000000000000018b009a7af758ae5d7b6aae84fe4c5ba67c041dfe5336000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000246a627842000000000000000000000000b8741a449d50ed0dcfe395287f85be152884c8d9009a7af758ae5d7b6aae84fe4c5ba67c041dfe5336000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000246a627842000000000000000000000000b8741a449d50ed0dcfe395287f85be152884c8d900fa5854fbf9964330d761961f46565ab7326e5a3b00000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000044095ea7b30000000000000000000000003fe285dcd76bcce4ac92d38a6f2f8e964041e02000000000000000000000000000000000000000000000000000a1d1b51fe47c5c00000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000',
  callGasLimit: 116807n,
  verificationGasLimit: 75441n,
  preVerificationGas: 50444n,
  maxFeePerGas: 66195658616n,
  maxPriorityFeePerGas: 120000n,
  paymasterAndData: '0x3fE285DcD76BCcE4Ac92d38A6F2F8E964041e020Fa5854FBf9964330d761961F46565AB7326e5a3b00000065bcd7fc00000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000de84cb0d94beb10a4658077bd4ad19f4fdf94425ec730f342b8115d9907f6072f40bcea6a95bce74c29b84a7d4ee9fa67f4efb39e25a2e39a2ecb110b9a0af6b6a9589bfef7ec431b',
  signature: '0xffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff'
}

Source code

createTokenPaymasterUserOperation

calculateUserOperationErc20TokenMaxGasCost

Calculates the maximum gas cost in ERC-20 tokens for a given userOperation

Usage

example.ts

import { CandidePaymaster } from "abstractionkit";

const erc20TokenAddress = "0xFa5854FBf9964330d761961F46565AB7326e5a3b"; // CTT test token
// Use createUserOperation() to help you construct a userOp
const userOperation = smartAccount.createUserOperation(..)

const paymasterRPC="https://api.candide.dev/public/v3/sepolia";
const paymaster: CandidePaymaster = new CandidePaymaster(paymasterRPC);

const cost = await paymaster.calculateUserOperationErc20TokenMaxGasCost(
  userOperation,
  erc20TokenAddress,
);

Param Types

key	type	description
userOperation	UserOperationV6 | UserOperationV7 | UserOperationV8 | UserOperationV9	UserOperation to calculate cost for. Supports EntryPoint v0.6, v0.7, v0.8, and v0.9
erc20TokenAddress	string	ERC-20 Token Address

Return Types

key	type	description
cost	Promise<bigint>	Returns maximum amount that the operation will cost in the erc-20 token

Example Response

3391931975665260

Source code

calculateUserOperationErc20TokenMaxGasCost

Advanced Methods

getPaymasterMetaData

Returns the metadata associated with the Paymaster, along with dummyPaymasterAndData useful for gas estimates

Usage

example.ts

example.ts

import { CandidePaymaster, SafeAccountV0_3_0 as SafeAccount } from "abstractionkit";

const paymasterRPC="https://api.candide.dev/public/v3/sepolia";
const paymaster: CandidePaymaster = new CandidePaymaster(paymasterRPC);

const paymasterResult = await paymaster.getPaymasterMetaData(SafeAccount.DEFAULT_ENTRYPOINT_ADDRESS);

Param Type

key	type	description
entrypoint	string	Target EntryPoint Contract Address

Return Type

key	type	description
paymastermetadata	Promise<PaymasterMetadataV7 | PaymasterMetadataV6 | null>	Returns a promise with the paymaster metadata associated with the target entrypoint

PaymasterMetadataV7

key	type	description
name	string	The name of the Paymaster.
description	string	A brief description of the Paymaster.
icons	string[]	An array of icon URLs representing the Paymaster's brand or logo.
address	string	The contract address of the Paymaster.
sponsoredEventTopic	string	The event topic that will be emitted when a UserOperation is sponsored by the Paymaster.
dummyPaymasterAndData	key type description paymaster string The address of the Paymaster. paymasterVerificationGasLimit bigint The amount of gas allocated for the Paymaster verification step. paymasterPostOpGasLimit bigint The amount of gas allocated for the Paymaster post-operation step. paymasterData string Encoded data for the Paymaster.	Dummy Paymaster data used for gas estimation.

PaymasterMetadataV6

key	type	description
name	string	The name of the Paymaster.
description	string	A brief description of the Paymaster.
icons	string[]	An array of icon URLs representing the Paymaster's brand or logo.
address	string	The contract address of the Paymaster.
sponsoredEventTopic	string	The event topic that will be emitted when a UserOperation is sponsored by the Paymaster.
dummyPaymasterAndData	string	Dummy Paymaster data used for gas estimation.

Example Response

{
  name: 'CANDIDE Paymaster',
  description: 'CANDIDE Paymaster a fast, secure and feature-rich 4337 Paymaster',
  icons: [],
  address: '0x8b1f6cb5d062aa2ce8d581942bbb960420d875ba',
  sponsoredEventTopic: '0xa050a122b4c0e369e3385eb6b7cccd8019638b2764de67bec0af99130ddf8471',
  dummyPaymasterAndData: {
    paymaster: '0x8b1f6cb5d062aa2ce8d581942bbb960420d875ba',
    paymasterVerificationGasLimit: '0xffff',
    paymasterPostOpGasLimit: '0xffff',
    paymasterData: '0x00010000000000ffff000000000000000000000000000000000000000000000000000000000000ffff010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101011c'
  }
}

source code

getPaymasterMetaData

getSupportedEntrypoints

Returns the supported Entrypoints by the paymaster

Usage

example.ts

example.ts

import { CandidePaymaster } from "abstractionkit";

const paymasterRPC="https://api.candide.dev/public/v3/sepolia";
const paymaster: CandidePaymaster = new CandidePaymaster(paymasterRPC);

const paymasterResult = await paymaster.getSupportedEntrypoints();

Return Type

key	type	description
entrypoint addresses	Promise<string[]>	A promise of a list of entrypoints addresses

Example Response

[
  '0x0000000071727De22E5E9d8BAf0edAc6f37da032',
  '0x5FF137D4b0FDCD49DcA30c7CF57E578a026d2789'
] 

source code

getSupportedEntrypoints

isSupportedERC20Token

Checks if a particular ERC-20 token is accepted as gas payment by the paymaster. Returns a boolean

Usage

example.ts

example.ts

import { CandidePaymaster } from "abstractionkit";

const paymasterRPC="https://api.candide.dev/public/v3/sepolia";
const paymaster: CandidePaymaster = new CandidePaymaster(paymasterRPC);

const erc20TokenAddress = "0xFa5854FBf9964330d761961F46565AB7326e5a3b"; // CTT on sepolia testnet

const isSupported = await paymaster.isSupportedERC20Token(erc20TokenAddress);

Param Types

key	type	description
erc20TokenAddress	string	ERC-20 Token Address
entrypoint?	string	Target EntryPoint Address. Defaults to ENTRYPOINT_V7

Response Type

key	type	description
isSupported	boolean	Returns true if the erc20 token is supported

Example Response

true

Source

isSupportedERC20Token

getSupportedERC20TokenData

Returns the token data given an erc20 address

Usage

example.ts

example.ts

import { CandidePaymaster } from "abstractionkit";

const paymasterRPC = "https://api.candide.dev/public/v3/sepolia";

const erc20TokenAddress = "0xFa5854FBf9964330d761961F46565AB7326e5a3b";
const paymaster: CandidePaymaster = new CandidePaymaster(paymasterRPC);
const erc20TokenData = await paymaster.getSupportedERC20TokenData(erc20TokenAddress);

Param Types

key	type	description
erc20TokenAddress	string	ERC-20 Token Address
entrypoint?	string	Target EntryPoint Address. Defaults to ENTRYPOINT_V7

Return Type

key	type	description
ERC20Token	Promise<ERC20Token | null>	ERC-20 Token

key	type	description
name	string	The name of the ERC20 token.
symbol	string	The symbol representing the ERC20 token.
address	string	The contract address of the ERC20 token.
decimals	number	The number of decimal places for the token.

Example Response

{
  name: 'Candide Test Token',
  symbol: 'CTT',
  address: '0xFa5854FBf9964330d761961F46565AB7326e5a3b',
  decimals: 18,
  fee: 0n,
  exchangeRate: 1001219705870085130n
}

Source code

getSupportedERC20TokenData

fetchTokenPaymasterExchangeRate

Fetches the current exchange rate for an ERC-20 token from the paymaster. The exchange rate represents the token cost per unit of native currency, used to calculate how much of the token is needed to cover gas fees.

Usage

example.ts

example.ts

import { CandidePaymaster } from "abstractionkit";

const paymasterRPC = "https://api.candide.dev/public/v3/sepolia";
const paymaster: CandidePaymaster = new CandidePaymaster(paymasterRPC);

const erc20TokenAddress = "0xFa5854FBf9964330d761961F46565AB7326e5a3b"; // CTT on sepolia testnet

const exchangeRate = await paymaster.fetchTokenPaymasterExchangeRate(erc20TokenAddress);

Param Types

key	type	description
erc20TokenAddress	string	ERC-20 Token Address
entrypoint	string?	EntryPoint Address that the paymaster is supporting. Defaults to ENTRYPOINT_V7

Return Type

key	type	description
exchangeRate	bigInt	Returns the exchange rate to the native token

Example Response

1001219705870085130n

Source code

fetchTokenPaymasterExchangeRate

createPaymasterUserOperation

Internal Method

createPaymasterUserOperation is an internal method. Use createSponsorPaymasterUserOperation for gas sponsorship or createTokenPaymasterUserOperation for ERC-20 token payment instead.

Source code

createPaymasterUserOperation