InstaGas Policy Rules Overview

InstaGas provides customizable rules for gas policies. These rules are organized into four categories:

• General Rules
• Account Rules
• Access Rules
• Transaction Rules

General Rules

• Effective Date Range: Specify when the gas policy should be active. This setting is ignored if the policy is inactive.
• Active State: Toggle to activate or deactivate the policy at any time.
• Private or Public: Choose between public and private gas policies:
  • Public Gas Policies: Set up by dApps for wallet consumption without requiring a sponsorship policy ID.
  • Private Gas Policies: Set up by wallets, requiring a sponsorship policy ID. Used when no public gas policy matches.

Account Rules

• Total Max per Account: Set an account spending limit.
  • Example: "Each account has a total sponsorship gas limit of 0.5 ETH."
• Max per UserOperation: Limit transaction sponsorship.
  • Example: "Each UserOperation can be sponsored up to 0.0001 ETH."
• Rate Limit Per Account: Define rate and period constraints.
  • Example: "Each account is allowed x sponsorships per y days."

Access Rules

• Account Whitelist: Create an allowlist of accounts eligible for the gas policy. If empty, all accounts are allowed.
  • Example: "Only sponsor transactions from sender 0xabcd...."
• Domains Whitelist: Create an allowlist of origins eligible for the gas policy. If empty, all origins are allowed.
  • Example: "Only sponsor transactions originating from https://app.uniswap.com."
  • Partial wildcards are supported for subdomains, but the protocol scheme is required. https://*.candide.dev is accepted; *.candide.dev is not.
• IP Whitelists: Create an allowlist of IPs eligible for the gas policy. If empty, all IPs are allowed.
  • Example: "Only sponsor transactions originating from IP 148.156.123.63."

Transaction Rules

Transaction rules limit gas sponsorship to specific smart contract interactions, callable methods, input parameters, and constraints.

• Contract Address: Limit gas sponsorship to a specific smart contract address.
  • Example: "Only sponsor transactions interacting with smart contract 0x123."
• Method: Limit gas sponsorship to a specific callable method on the smart contract.
  • Example: "Only sponsor when the transaction calls the swap method."
• Parameters Constraints: Limit gas sponsorship based on method parameters and constraints.
  • Example: "Only sponsor when tokenIn amount is greater than or equal to 1 ETH."
• Batch Transaction: Design rules to sponsor transaction batches, such as an ERC-20 token approval followed by a contract deposit.
  • Example: "Only sponsor if the transaction includes both ERC-20 token approval and deposit calls."

Example: Uniswap Swap Transaction

When you want to make a swap on Uniswap, you can make a call to the swap function with specific parameters. For instance:

swap(400, usdt, weth)

In this example:

• swap is the function being called, which initiates the swap transaction.
• (400, usdt, weth) are the parameters being passed to the swap function, which specify the details of the swap:
  • 400 is the amount of tokens to be swapped.
  • usdt is the token being swapped (in this case, USDT).
  • weth is the token being swapped for (in this case, WETH).

For each function, you can specify a list of parameters, and each parameter can have a constraint. For example, you can assign constraints to the parameters in the swap function as follows:

• amount: greater than 350 (e.g., amount > 350)
• tokenIn: equal to USDT (e.g., tokenIn == usdt)
• tokenOut: equal to WETH (e.g., tokenOut == weth)

By specifying these constraints, you can control the behavior of the swap transaction and ensure that it is executed according to your requirements. For instance, you can ensure that the swap transaction only occurs if the amount being swapped is greater than 350, and if the tokens being swapped are USDT and WETH.

Policy configuration example

Policies can be created and edited in the Dashboard or through the Platform API. The example below is a policy creation body using the public API field names.

For request validation, update semantics, and response fields, use the Gas Policy API reference as the canonical source.

{
  "name": "Onboarding sponsorship",
  "chainId": 10,
  "general": {
    "enabled": true,
    "private": false,
    "startDate": 1751500800000,
    "endDate": 1754179200000
  },
  "accountRules": {
    "totalMax": "0x6f05b59d3b20000",
    "maxPerOp": "0x5af3107a4000",
    "rate": 3,
    "ratePeriod": 86400
  },
  "accessRules": {
    "accounts": [
      { "value": "0xA1b2C3d4E5f6A7b8C9d0E1f2A3b4C5d6E7f8A9b0", "label": "Beta tester" }
    ],
    "origins": [
      { "value": "https://*.example.com", "label": "Our app" }
    ],
    "ips": []
  },
  "transactions": [
    {
      "to": "0xE592427A0AEce92De3Edee1F18E0157C05861564",
      "selector": "0x414bf389",
      "abi": "[{\"type\":\"function\",\"name\":\"exactInputSingle\",\"constant\":false,\"payable\":true,\"inputs\":[{\"type\":\"tuple\",\"name\":\"params\",\"components\":[{\"type\":\"address\",\"name\":\"tokenIn\"},{\"type\":\"address\",\"name\":\"tokenOut\"},{\"type\":\"uint24\",\"name\":\"fee\"},{\"type\":\"address\",\"name\":\"recipient\"},{\"type\":\"uint256\",\"name\":\"deadline\"},{\"type\":\"uint256\",\"name\":\"amountIn\"},{\"type\":\"uint256\",\"name\":\"amountOutMinimum\"},{\"type\":\"uint160\",\"name\":\"sqrtPriceLimitX96\"}]}],\"outputs\":[{\"type\":\"uint256\",\"name\":\"amountOut\"}]}]",
      "parameters": [
        { "index": "0;5", "operator": "$gte", "value": "0x0f4240" }
      ]
    }
  ]
}

General

field	type	description
enabled	boolean	Whether the policy is active. Disabled policies never sponsor, regardless of dates.
private	boolean	Private policies require the wallet to pass the policy ID when requesting sponsorship. Public policies apply without one.
sponsorshipPolicyId	string	Assigned by InstaGas at creation. Wallets reference it as the sponsorship policy ID for private policies.
startDate	number	Unix timestamp in milliseconds. Sponsorship starts at this time.
endDate	number	Unix timestamp in milliseconds. Sponsorship stops at this time.

Account

field	type	description
totalMax	string (hex wei)	Lifetime sponsorship limit per account. 0x6f05b59d3b20000 is 0.5 ETH.
maxPerOp	string (hex wei)	Maximum sponsored gas cost for a single UserOperation. 0x5af3107a4000 is 0.0001 ETH.
rate	number	Number of sponsored UserOperations allowed per ratePeriod, per account.
ratePeriod	number	Rate limit window in seconds. 86400 with rate: 3 means 3 sponsorships per account per day.

Amounts are entered in ETH in the dashboard and stored as hex-encoded wei.

Access

field	type	description
accounts	{value, label}[]	Sender addresses eligible for sponsorship. Empty allows all senders.
origins	{value, label}[]	Web origins eligible for sponsorship. Empty allows all origins. Subdomain wildcards are supported, and the scheme is required: https://*.example.com is valid, *.example.com is not.
ips	{value, label}[]	IP addresses eligible for sponsorship. Empty allows all IPs.

Transactions

Each entry describes one allowed contract call. Constraints within an entry must all pass for the call to qualify.

field	type	description
to	string (address)	The contract the call must target.
selector	string (4-byte hex)	The function selector the call must invoke.
abi	string	A JSON-stringified ABI array containing the complete function fragment, used to decode call parameters for constraint checks.
parameters	constraint[]	Constraints on the decoded call parameters. Empty sponsors any call to this function.

Each parameter constraint:

field	type	description
index	string	Argument index. Use semicolons for nested tuples: 0;5 targets the sixth field of the first argument.
operator	string	One of the operators below.
value	string	The value the decoded argument is compared against. Encode uint and bytes values as 0x-prefixed hexadecimal strings. Token amounts are in the token's smallest unit.

Supported operators:

operator	meaning
$eq	Equals
$gt	Greater than
$gte	Greater than or equal
$lt	Less than
$lte	Less than or equal
$startsWith	Value prefix match

The comparison operators apply to numeric parameters. Use $eq for addresses and exact matches.