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

Deposits and gas

Fund an HCA, read and top up its EntryPoint deposit, and learn who pays gas for each executor, with or without a paymaster.

Experimental

@ensforge/hca is experimental for 1.0. Its API can change in a minor release.

An HCA is its own account, so it can hold funds and pay for things. By the end of this guide you will know who pays gas for each executor, how to fund an HCA before it exists, and how to manage its ERC-4337 deposit.

Who pays what

Two costs exist. The gas pays for running the execution. The spend is what the calls themselves pay, such as ETH sent with a call or a registration fee in tokens.

ExecutorPays the gasPays ETH the calls sendPays tokens the calls spend
owner()The owner's wallet.The owner's wallet, sent with the transaction.The HCA.
bundler() or pimlico() without a paymasterThe HCA.The HCA.The HCA.
bundler() or pimlico() with a paymasterThe paymaster.The HCA.The HCA.
rhinestone()Sponsored by default. With sponsored: false, a session's refund token.The HCA.The HCA.

The HCA is msg.sender of the calls it runs, so tokens a call spends come from the HCA's balance, not the wallet's. A registration through via: hca() fails with INSUFFICIENT_TOKEN_BALANCE before it is sent when the HCA cannot pay. Fund the HCA first.

Fund an HCA before it exists

The address of an HCA is known before deployment. Predict it and send funds there.

Example (Reading the Address to Fund)

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

const account = privateKeyToAccount(
  "0x0123456789012345678901234567890123456789012345678901234567890123",
);
const publicClient = createPublicClient({ chain: sepolia, transport: http() });
const walletClient = createWalletClient({ account, chain: sepolia, transport: http() });
const ens = Ensforge.create({ publicClient, walletClient })
  .extend(ensActions())
  .extend(hcaActions());
const address = await ens.hca.predictAddress({});

await walletClient.sendTransaction({ to: address, value: parseEther("0.01") });

hca.predictAddress takes an optional owner, which defaults to the client's account. The address never changes, even after upgrades.

Read and top up the EntryPoint deposit

With a bundler and no paymaster, the HCA pays for its UserOperations. The ERC-4337 EntryPoint keeps a deposit for each account and charges that gas to it. Read the deposit, and add to it ahead of time, with these actions.

ActionWhat it does
hca.getDepositReads the deposit in wei. Takes an optional address or owner.
hca.addDepositAdds amount wei from your wallet to the deposit.
hca.withdrawDepositWithdraws amount wei to to.

Example (Topping Up and Withdrawing)

deposit.ts
import { hcaActions } from "@ensforge/hca";
import { Ensforge, ensActions } from "@ensforge/sdk";
import { createPublicClient, createWalletClient, http, parseEther } 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 before = await ens.hca.getDeposit({});

await ens.hca.addDepositSync({ amount: parseEther("0.01") });

const after = await ens.hca.getDeposit({});

await ens.hca.withdrawDepositSync({ to: account.address, amount: after - before });

withdrawDeposit runs from the HCA through executeByOwner, because only the account may withdraw its deposit. Each action has a …Sync form that waits for the receipt and a form that resolves once the transaction is submitted. See Ways to call actions.

Check the cost before you send

Every write has prepare, simulate and estimateGas. With an executor that quotes fees, the plan shows them in plan.fees before anything is sent. See Preview before sending.

Troubleshooting

INSUFFICIENT_TOKEN_BALANCE

The HCA does not hold enough of the payment token for the registration. Send the token to the HCA's address and run the write again. See INSUFFICIENT_TOKEN_BALANCE.

HCA_BUNDLER_REJECTED

With a bundler and no paymaster, neither the HCA nor a paymaster could pay. Fund the HCA or its deposit, or add a paymaster. See Bundlers.

Was this page helpful?