Documentation for agents: an index at /llms.txt, every docs page in one file at /llms-full.txt, and Markdown for any docs page by adding .md to its URL.

Skip to Content
ensforgeSDK

Pay gas for users

Sponsor the gas of a write with an EIP-5792 paymaster service, or through an HCA bundler, so users do not need ETH for fees.

A paymaster pays the gas of a transaction on the user's behalf. ensforge supports two ways to sponsor a write: a paymaster service your wallet understands, and the sponsorship of an HCA bundler.

Prerequisites

  • A client with a wallet. See Send a transaction.
  • For the first way, a wallet that supports the EIP-5792 paymasterService capability, and the URL of a paymaster service (ERC-7677) that accepts your users.

Pass paymaster to any write. ensforge sends the write through wallet_sendCalls with the paymasterService capability, so the wallet asks the service to sponsor it.

Example (Sponsoring a record update)

paymaster.ts
import type { EIP1193Provider } from "viem";

declare global {
  interface Window {
    ethereum?: EIP1193Provider;
  }
}

import { Ensforge, ensActions } from "@ensforge/sdk";
import { createPublicClient, createWalletClient, custom, http } from "viem";
import { sepolia } from "viem/chains";

const publicClient = createPublicClient({ chain: sepolia, transport: http() });
const walletClient = createWalletClient({ chain: sepolia, transport: custom(window.ethereum!) });
const [account] = await walletClient.requestAddresses();
const ens = Ensforge.create({ publicClient, walletClient, account }).extend(ensActions());

const { id } = await ens.record.set({
  name: "ensforge-docs-demo.eth",
  texts: { url: "https://example.com" },
  paymaster: {
    url: "https://paymaster.example.com/rpc",
    context: { policyId: "ens-profile-updates" },
  },
});
  • url is the paymaster service the wallet calls.
  • context is passed to the service as it is, for example a sponsorship policy. It is optional.
  • The write goes out as a bundle even when it has one call, and the bundle is atomic. id is the bundle id. See Bundle transactions.

paymaster is a write option, so …Sync forms, plan.send and plan.resume take it too.

An HCA can run a write as a UserOperation through a bundler, and the bundler's paymaster can pay for it. The executors take their own sponsorship settings: bundler({ paymaster }), pimlico({ sponsor, sponsorshipPolicyId }) and rhinestone({ sponsored }). This path is experimental. See Bundlers, Rhinestone and Deposits and gas, and Use smart accounts for via.

With the default owner() executor, the HCA's transactions come from your wallet, so pass paymaster on the write as above.

A route's plan.fees shows each fee with sponsored: true when the sponsor pays it.

Check the result

Use a …Sync write, then compare the account's ETH balance before and after. A sponsored write leaves it unchanged except for any value the calls send.

Troubleshooting

WALLET_BATCH_UNSUPPORTED

The wallet does not support the paymasterService capability, or does not send atomic bundles. Remove paymaster, or let the user pay. See WALLET_BATCH_UNSUPPORTED.

INSUFFICIENT_ETH

The wallet could not cover the gas, for example because the sponsor did not pay for the bundle. Check the paymaster service's policy. See INSUFFICIENT_ETH.

HCA_PAYMASTER_REJECTED

An HCA bundler's paymaster refused the operation. See HCA_PAYMASTER_REJECTED.

Was this page helpful?