Your wallet
Run HCA executions as ordinary wallet transactions with the owner executor, the default, and combine it with other executors.
Experimental
@ensforge/hca is experimental for 1.0. Its API can change in a minor release.
The owner() executor sends each HCA execution as an executeByOwner transaction from the owner's wallet. It is the default, needs no service, and the owner pays gas. By the end of this page you will know when it runs, how to combine it with other executors, and how to run arbitrary calls from the HCA.
Use it by default
hca() with no options is the same as hca({ executors: [owner()] }).
Example (Running Calls From the HCA)
import { hca, hcaActions, owner } 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 { receipt } = await ens.hca.executeSync({
calls: [{ to: "0x000000000000000000000000000000000000dEaD", value: parseEther("0.001") }],
via: hca({ executors: [owner()] }),
});hca.execute runs the calls in order, from the HCA, as one atomic execution. Every call succeeds or the whole execution reverts. With the owner executor, your wallet sends the ETH the calls spend along with the transaction, so this example pays 0.001 ETH from your wallet. Tokens the calls spend come from the HCA's balance.
What the owner executor sends
- With a wallet that supports atomic batches (EIP-5792), the owner's steps share one bundle: the setup and the executions.
- Otherwise the wallet sends one transaction per step.
- The setup step,
hca-setup, deploys the HCA with a factory call when it does not exist yet. - Use
modeandmaxBundleCallson the write to control bundling, as for any write.
Let the wallet sponsor gas
With a wallet that supports the EIP-5792 paymasterService capability, pass paymaster on the write. The wallet's paymaster service then pays for its transactions.
import { hca, hcaActions } 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());
await ens.migration.migrate({
names: ["alice.eth"],
via: hca(),
paymaster: { url: "https://paymaster.example.com" }, // your EIP-5792 paymaster service
});See Pay gas for users for the wallet side.
Combine it with other executors
executors lists executors in order of preference. Without a session, ensforge uses the first one in the list. With a session, it uses the first one that runs sessions. ensforge picks the executor when you call hca(), and does not switch to another one when a send fails.
One list can serve both kinds of write: owner writes go through your wallet, and session writes through Rhinestone.
import { hca, owner, rhinestone, type HcaSession, type RhinestoneSdk } from "@ensforge/hca";
import type { Account } from "viem";
declare const sdk: RhinestoneSdk; // created by your app from Rhinestone's SDK
declare const sessionSigner: Account;
declare const session: HcaSession; // from ens.hca.authorizeSession
const executors = [owner(), rhinestone({ sdk, sessionSigner })];
const asOwner = hca({ executors }); // uses owner()
const withSession = hca({ executors, session }); // uses rhinestone()The owner executor does not run sessions. See Sessions.
Troubleshooting
HCA_EXECUTOR_UNSUPPORTED
hca() throws it when you pass a session and no executor in the list runs sessions. Add rhinestone(). See HCA_EXECUTOR_UNSUPPORTED.
HCA_NOT_VERIFIED
The write has no signer, or the deployed HCA failed its checks. Pass an account or a wallet client, and read details for the failed checks. See HCA_NOT_VERIFIED.
Was this page helpful?