Sponsorship rules

You can easily define rules around which transactions (User Ops) the paymaster should sponsor. This can be used to prevent abuse, progressively onboard users, and incentivize specific in-app actions.

You can set the following sponsorship rules

• Global spend limits: Maximum gas cost (in USD) that you want to sponsor. This applies for the duration of the billing period (monthly).
• Server verifier: This is a general-purpose check that can be used to define custom rules. Before a transaction is sent, it checks with an endpoint that you specify whether it should be sponsored or not.
• Contract address restrictions: Use this if you want to sponsor transactions sent only to a specific set of contracts. Transactions sent to contracts outside this allowlist will remain unsponsored.
• Chain restrictions: Use this if you want to sponsor transactions only on certain chains. If this is not set, transactions on all supported chains will be sponsored.
• User lists: You can use this define allowlists or blocklists. Allowlists let you restrict sponsored transactions to transactions sent by a specific set of known accounts. Blocklists let you block bad actors from abusing your paymaster.
• Admin accounts: These accounts are not subject to any sponsorship rule, all their transactions will be sponsored. Use this only with accounts that you control (eg. for testing purposes).

We highly recommend that you set sponsorship rules before your app goes live to prevent malicious actors from abusing your paymaster, which could lead to unexpectedly large bills.

You can easily set sponsorship rules by going to the configuration tab in the Account abstraction dashboard..To use them in your app all you need to do is pass your API key, and sponsorship rules will automatically be applied.

You can set up a server verifier by providing a URL that the paymaster will call before sponsoring a transaction. This allows for fine grained control over which transactions are sponsored.

The thirdweb infrastructure will send a POST request to the URL you specify with the following JSON payload:

// thirdweb will call your server with the following JSON body as a POST request
{
	clientId: string; // the clientId that is making the request
	chainId: number; // the chainId of the transaction
	userOp: {
		sender: string; // the address of the sender
  		targets: string[]; // the addresses of the target contracts or wallets
  		gasLimit: string; // the gas limit of the transaction
  		gasPrice: string; // the gas price of the transaction in wei
                data: {
		  targets: string[], // the targets contracts or wallets called in this operation
		  callDatas: string[], // the call data of each transaction
		  values: string[], // the values (in wei) of each transaction
                }
	};
}

Your server should respond with a 200 and the following JSON payload:

// You should respond with the following JSON payload
{
	isAllowed: boolean; // whether the transaction should be sponsored or not
	reason: string?; // optional reason for why the transaction is not allowed
}

Note: for performance reasons, your server should respond within 5 seconds. If it takes longer, the transaction will be unsponsored.

What happens if a limit is hit? Does the transaction fail or does it go unsponsored?

If a limit is hit the transaction will go unsponsored. If you are spinning up fresh accounts for users in your app, it is unlikely that the user accounts will hold any funds. You can catch the following out of funds error to gracefully handle this within your app AA21 didn't pay prefund.

What networks are sponsorship rules available in?

Sponsorship rules apply across all the networks that we support account abstraction in. You don't need to specify different rules for each network or each account factory as long as they use the same client ID. However, you can restrict sponsored transactions to specific networks if you choose to.

Will sponsorship rules work with third-party paymasters?

No, sponsorship rules will apply if you are using thirdweb's paymaster.

Setting a server verifier requires your account to be on the growth plan. The other policies are free to use. There is no usage based pricing for policies.