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
ensforgeHCA

Bundlers

Run HCA writes as owner-signed ERC-4337 UserOperations through any bundler or through Pimlico, with or without a gas paymaster.

Experimental

@ensforge/hca is experimental for 1.0. The bundler path has no production proof upstream yet. ensforge tests it against a local bundler (alto) without ERC-7562 safe mode, and the live Pimlico check is still open. Test on Sepolia first.

A bundler collects ERC-4337 UserOperations and lands them on chain. The bundler() and pimlico() executors send each HCA execution as a UserOperation that the owner signs, so the owner needs no ETH when a paymaster sponsors it. By the end of this page you will run a write gaslessly.

What a bundler executor does

  • It sends owner operations only. HCA sessions run through Rhinestone, not ERC-4337, and hca() with a session and only bundler executors fails with HCA_EXECUTOR_UNSUPPORTED.
  • It targets EntryPoint v0.7.
  • The first operation deploys the HCA through its factory, so no setup transaction is needed.
  • The owner signs with personal_sign over the UserOperation hash. The wallet shows one signature prompt instead of a transaction.

Use Pimlico

pimlico() is a preset for Pimlico's hosted bundler and paymaster on mainnet or Sepolia. It builds the endpoint for the client's chain from your API key.

OptionTypeDefaultDescription
apiKeystringnoneYour Pimlico API key.
sponsorbooleanfalseSponsor operations with Pimlico's paymaster.
sponsorshipPolicyIdstringnonePimlico sponsorship policy id.

Example (Gasless Renewal With Pimlico)

pimlico.ts
import { hca, hcaActions, pimlico } from "@ensforge/hca";
import { Ensforge, ensActions } from "@ensforge/sdk";
import { createPublicClient, createWalletClient, http } from "viem";
import { privateKeyToAccount } from "viem/accounts";
import { sepolia } from "viem/chains";

const account = privateKeyToAccount(
  "0x0123456789012345678901234567890123456789012345678901234567890123",
);
const ens = Ensforge.create({
  publicClient: createPublicClient({ chain: sepolia, transport: http() }),
  walletClient: createWalletClient({ account, chain: sepolia, transport: http() }),
})
  .extend(ensActions())
  .extend(hcaActions());
const via = hca({
  executors: [pimlico({ apiKey: "pim_…", sponsor: true })],
});

await ens.hca.executeSync({
  calls: [{ to: "0x000000000000000000000000000000000000dEaD", value: 0n }],
  via,
});
  • sponsor: true lets Pimlico's paymaster pay. Without it, the HCA pays its own gas.
  • The owner signs the UserOperation. The wallet sends no transaction.
  • Replace pim_… with your Pimlico API key.

Use any bundler

bundler() takes any ERC-4337 bundler RPC URL that supports EntryPoint v0.7.

OptionTypeDefaultDescription
urlstringnoneBundler RPC URL.
paymasterstringnoneERC-7677 paymaster RPC URL that sponsors operations, often the bundler's own.
paymasterContextRecord<string, unknown>noneContext for the paymaster, such as a sponsorship policy id.
idstring"bundler"Name shown on plans and errors.
timeoutnumber180000Milliseconds an operation may stay pending before HCA_EXECUTION_TIMEOUT.

Example (A Sponsored Operation With a Policy)

bundler.ts
import { bundler, hca } from "@ensforge/hca";

const url = "https://bundler.example.com/rpc"; // your bundler

const via = hca({
  executors: [bundler({ url, paymaster: url, paymasterContext: { sponsorshipPolicyId: "sp_…" } })],
});

Pass via to any write, for example ens.registration.renewSync({ names, duration, via }). Migration, registration, renewal and hca.execute work through the HCA. Other writes need the HCA to hold the roles they use. See How it works.

Who pays gas

SetupWho pays
No paymaster (or sponsor: false)The HCA, from its own funds. Keep it funded: see Deposits and gas.
paymaster or sponsor: trueThe paymaster. The HCA's balance does not change.

Troubleshooting

HCA_BUNDLER_REJECTED

The bundler refused the operation. The usual cause is that neither the HCA nor a paymaster can pay. Fund the HCA, add a paymaster, and check that the bundler supports EntryPoint v0.7. ensforge marks this error as retryable. See HCA_BUNDLER_REJECTED.

HCA_PAYMASTER_REJECTED

The paymaster refused to sponsor the operation. Check the sponsorship policy and context. See HCA_PAYMASTER_REJECTED.

HCA_EXECUTION_TIMEOUT

The operation stayed pending longer than timeout. It may still land: plan.resume checks it again. Raise timeout to wait longer. See Continue after a failure and HCA_EXECUTION_TIMEOUT.

Was this page helpful?