Executors
Look up the HCA route, the executors that send hosted contract account calls, and their options in the experimental @ensforge/hca package.
Exports of @ensforge/hca besides its actions and HcaError. @ensforge/hca is experimental.
Route and executors
bundler
Experimental
Runs HCA executions as owner-signed ERC-4337 UserOperations through any bundler, optionally sponsored by a paymaster. Experimental: the HCA's bundler path has no production proof upstream yet.
function bundler(options: BundlerOptions): ExecutorUse for gasless owner actions (renewals, registration, migration) when the owner holds no ETH; the owner signs each operation instead of sending a transaction.
- Writes other than registration, migration and
hca.executesucceed only where the HCA holds the roles they need, so transfers and record edits through it usually fail. - Owner operations only: HCA sessions run through Rhinestone's intent executor, not ERC-4337.
- EntryPoint v0.7; the first operation deploys the HCA through its factory.
- The owner signs with
personal_signover the UserOperation hash.
import { bundler, hca } from "@ensforge/hca"
const via = hca({ executors: [bundler({ url: bundlerUrl, paymaster: bundlerUrl })] })await ens.registration.renewSync({ names: ["alice.eth"], duration, via })import { bundler } from "@ensforge/hca"
bundler({ url, paymaster: url, paymasterContext: { sponsorshipPolicyId: "sp_…" } })defineExecutor
Experimental
Builds an executor from your own functions, e.g. for another bundler SDK or a relayer.
function defineExecutor(executor: Executor): ExecutorUse when none of the built-in executors fits: send runs one HCA execution and returns a
reference, status reports it.
- Requests carry the HCA, its owner, whether it is deployed, the calls and the session if any.
- Return
{ status: "failed" }without hashes for executions that never landed: the write can send them again.
import { defineExecutor } from "@ensforge/hca"
const relayer = defineExecutor({
id: "relayer",
capabilities: { sessions: false, sponsorship: true, deploys: false },
send: async (request) => api.relay(request),
status: async (id) => api.status(id),
})import { hca } from "@ensforge/hca"
const via = hca({ executors: [relayer] })import { defineExecutor } from "@ensforge/hca"
const fake = defineExecutor({ id: "fake", capabilities, send: async () => "1", status: async () => ({ status: "success", hashes: [hash] }) })hca
Experimental
Sends writes through the signer's ENS Hosted Contract Account (HCA): pass it as via to any
write. Steps run as one atomic executeByOwner each, the HCA is deployed on first use, and the
approvals it needs to move the owner's names are added as owner transactions.
function hca(options: HcaOptions = {}): Write.ViaUse to migrate several names in one or two transactions instead of one per step, to run writes gaslessly through a bundler, or prompt-free through a Rhinestone session.
- The HCA runs the calls (
msg.sender), so it needs authority over what they touch: migration and registration plan for it; other writes need the HCA to hold the roles they use. - With an EIP-5792 wallet the owner's steps (approvals, deployment, executions) share one bundle.
- Never selected implicitly: the user should agree to use their HCA.
import { hca } from "@ensforge/hca"
await ens.migration.migrateSync({ names: ["alice.eth", "bob.eth"], via: hca() })import { hca, pimlico } from "@ensforge/hca"
await ens.hca.executeSync({ calls, via: hca({ executors: [pimlico({ apiKey, sponsor: true })] }) })import { hca, rhinestone } from "@ensforge/hca"
const via = hca({ executors: [rhinestone({ sdk })], session })
await ens.record.set({ name: "alice.eth", texts: { url }, via })hcaActions
Experimental
Adds the hca actions to a client.
function hcaActions()hcaAdminActions
Experimental
Adds the hcaAdmin actions to a client.
function hcaAdminActions()owner
Experimental
The owner's wallet sends each HCA execution as an executeByOwner transaction. The default
executor; needs no service.
function owner(): ExecutorUse when the owner pays gas: one transaction per execution, or one EIP-5792 bundle for the whole write with a wallet that supports it.
- Deploys the HCA with a factory call in the first step when needed.
- With
paymasteron the write, an EIP-5792 wallet can sponsor the transactions.
import { hca, owner } from "@ensforge/hca"
await ens.hca.executeSync({ calls, via: hca({ executors: [owner()] }) })import { hca, owner, pimlico } from "@ensforge/hca"
// `hca()` uses the first executor only, so choose one per request.
const gasless = true
const via = gasless ? hca({ executors: [pimlico({ apiKey })] }) : hca({ executors: [owner()] })import { hca } from "@ensforge/hca"
await ens.migration.migrate({ names, via: hca(), paymaster: { url: paymasterUrl } })pimlico
Experimental
bundler preset for Pimlico's hosted bundler and paymaster. Experimental, as bundler.
function pimlico(options: PimlicoOptions): ExecutorUse with a Pimlico API key for gasless owner actions on mainnet or Sepolia.
import { hca, pimlico } from "@ensforge/hca"
const via = hca({ executors: [pimlico({ apiKey, sponsor: true })] })import { pimlico } from "@ensforge/hca"
pimlico({ apiKey, sponsor: true, sponsorshipPolicyId: "sp_…" })import { pimlico } from "@ensforge/hca"
pimlico({ apiKey })rhinestone
Experimental
Runs HCA executions as Rhinestone intents: owner-signed, or prompt-free with an HCA session. Experimental; bring a Rhinestone SDK with standalone HCA support.
function rhinestone(options: RhinestoneOptions): ExecutorUse for prompt-free registration and record updates with a session (hca.authorizeSession),
and for sponsored or stablecoin-paid executions.
- ensforge checks session calls against the HCA policy before anything is signed.
- The SDK account must derive the same HCA address, or the executor fails with
HCA_SDK_UNSUPPORTED(stock SDK releases without the standalone HCA derive another). - Status follows the intent until its fill transaction is mined.
import { hca, rhinestone } from "@ensforge/hca"
const via = hca({ executors: [rhinestone({ sdk, sessionSigner })], session })import { hca, rhinestone } from "@ensforge/hca"
const via = hca({ executors: [rhinestone({ sdk })] })import { rhinestone } from "@ensforge/hca"
rhinestone({ sdk, sessionSigner, sponsored: false })Types
BundlerOptions
Experimental
Options of bundler.
type BundlerOptions| Option | Type | Default | Description |
|---|---|---|---|
url (required) | string | ERC-4337 bundler RPC URL (EntryPoint v0.7). | |
paymaster | string | Paymaster RPC URL (ERC-7677) that sponsors the UserOperations, often the bundler's own. | |
paymasterContext | Readonly<Record<string, unknown>> | Paymaster context, e.g. a sponsorship policy id. | |
id | string | Id reported on plans and errors. @default "bundler" | |
timeout | number | 180_000 | Milliseconds a UserOperation may stay pending before the write fails with HCA_EXECUTION_TIMEOUT. Bundlers can keep an operation they cannot land forever. |
ExecutionRequest
Experimental
What an executor is asked to run: owner-authorized (or session-authorized) calls from the HCA.
type ExecutionRequest| Field | Type | Description |
|---|---|---|
chainId | number | |
hca | Address | |
owner | Address | |
deployed | boolean | |
calls | readonly Plan.Call[] | |
session (optional) | HcaSession | |
description | string |
Executor
Experimental
Runs HCA executions: the owner's wallet (owner()), an ERC-4337 bundler (bundler(),
pimlico()), Rhinestone intents (rhinestone()), or your own (defineExecutor).
type Executor| Field | Type | Description |
|---|---|---|
id | string | |
capabilities | { /** Runs session-authorized executions (no owner prompt). */ readonly sessions: boolean; /** Can run without the owner holding native gas. */ readonly sponsorship: boolean; /** Deploys the HCA on first use, without a separate transaction. */ readonly deploys: boolean; } | |
send (optional) | ((request: ExecutionRequest, context: Write.Via.Context) => Promise<string>) | Sends one execution and returns a reference to follow it. Omitted for owner(), whose executions are ordinary wallet transactions. |
status (optional) | ((reference: string, context: Write.Via.Context) => Promise<Write.Via.Status>) | Where a sent execution is. |
quote (optional) | ((request: ExecutionRequest, context: Write.Via.Context) => Promise<readonly Plan.Fee[]>) | Fees the executor will charge for a request, shown on the plan before sending. |
HcaAccount
Experimental
An ENS Hosted Contract Account, deployed or predicted.
type HcaAccount| Field | Type | Description |
|---|---|---|
address | Address | |
owner | Address | null | The immutable owner (the wallet); null when it cannot be read. |
deployed | boolean | |
authorizedOwner | Address | null | Owner the factory certified for this account. |
accountId | string | null | accountId(), e.g. ens-standalone-hca.1.1.0. |
implementation | Address | null | Current implementation; null before deployment. |
initialImplementation | Address | Implementation the address derives from; it never changes. |
sessionNonce | bigint | Increments with revokeSessions, invalidating every session approval. |
upgradeSet | Address | DAO set of implementations this account may upgrade to. |
problems | readonly HcaProblem[] | Failed checks; empty for a usable (or not yet deployed) HCA. |
HcaActions
Experimental
hca actions bound to a client.
type HcaActions| Field | Type | Description |
|---|---|---|
hca | { /** Adds ETH to an HCA's ERC-4337 EntryPoint deposit. Resolves once the transaction is submitted. */ readonly addDeposit: BoundWrite<typeof hca.addDeposit>; /** Adds ETH to an HCA's ERC-4337 EntryPoint deposit. Resolves once the receipt is in. */ readonly addDepositSync: Bound<typeof hca.addDepositSync>; /** Asks the owner to approve a session key for their HCA, with one signature and no transaction. */ readonly authorizeSession: Bound<typeof hca.authorizeSession>; /** Checks calls against the HCA session policy before anything is signed. */ readonly checkSessionCalls: Bound<typeof hca.checkSessionCalls>; /** Deploys the signer's HCA through the ENS factory. Resolves once the transaction is submitted. */ readonly deploy: BoundWrite<typeof hca.deploy>; /** Deploys the signer's HCA through the ENS factory. Resolves once the receipt is in. */ readonly deploySync: Bound<typeof hca.deploySync>; /** Runs calls from the signer's HCA as one atomic execution. Resolves once the transaction is submitted. */ readonly execute: BoundWrite<typeof hca.execute>; /** Runs calls from the signer's HCA as one atomic execution. Resolves once the receipt is in. */ readonly executeSync: Bound<typeof hca.executeSync>; /** Reads an ENS HCA (Hosted Contract Account): its address, owner, implementation, session nonce and verification problems. */ readonly get: Bound<typeof hca.get>; /** Reads an HCA's ERC-4337 EntryPoint deposit, which pays for its UserOperations without a paymaster. */ readonly getDeposit: Bound<typeof hca.getDeposit>; /** Checks whether a stored HCA session can still be used. */ readonly getSession: Bound<typeof hca.getSession>; /** Checks whether an HCA may upgrade to an implementation: it must be in the DAO's upgrade set and accept the current implementation. */ readonly getUpgrade: Bound<typeof hca.getUpgrade>; /** Computes the address of an owner's ENS HCA, deployed or not. */ readonly predictAddress: Bound<typeof hca.predictAddress>; /** Invalidates every session approval of the signer's HCA. Resolves once the transaction is submitted. */ readonly revokeSessions: BoundWrite<typeof hca.revokeSessions>; /** Invalidates every session approval of the signer's HCA. Resolves once the receipt is in. */ readonly revokeSessionsSync: Bound<typeof hca.revokeSessionsSync>; /** Upgrades the signer's HCA to an implementation the DAO's upgrade set and its own `canUpgradeFrom` check allow. Resolves once the transaction is submitted. */ readonly upgrade: BoundWrite<typeof hca.upgrade>; /** Upgrades the signer's HCA to an implementation the DAO's upgrade set and its own `canUpgradeFrom` check allow. Resolves once the receipt is in. */ readonly upgradeSync: Bound<typeof hca.upgradeSync>; /** Checks that an address is a usable ENS HCA of its owner, and returns it. */ readonly verify: Bound<typeof hca.verify>; /** Withdraws ETH from the signer's HCA EntryPoint deposit. Resolves once the transaction is submitted. */ readonly withdrawDeposit: BoundWrite<typeof hca.withdrawDeposit>; /** Withdraws ETH from the signer's HCA EntryPoint deposit. Resolves once the receipt is in. */ readonly withdrawDepositSync: Bound<typeof hca.withdrawDepositSync>; } |
HcaAdminActions
Experimental
hcaAdmin actions bound to a client.
type HcaAdminActions| Field | Type | Description |
|---|---|---|
hcaAdmin | { /** Reads who governs ENS HCAs: the factory owner and whether implementations are approved. */ readonly getGovernance: Bound<typeof hcaAdmin.getGovernance>; /** Grants root roles on the HCA upgrade set (role admins only). Resolves once the transaction is submitted. */ readonly grantUpgradeSetRoles: BoundWrite<typeof hcaAdmin.grantUpgradeSetRoles>; /** Grants root roles on the HCA upgrade set (role admins only). Resolves once the receipt is in. */ readonly grantUpgradeSetRolesSync: Bound<typeof hcaAdmin.grantUpgradeSetRolesSync>; /** Renounces ownership of the HCA factory, freezing its implementation approvals (factory owner only). Resolves once the transaction is submitted. */ readonly renounceGovernance: BoundWrite<typeof hcaAdmin.renounceGovernance>; /** Renounces ownership of the HCA factory, freezing its implementation approvals (factory owner only). Resolves once the receipt is in. */ readonly renounceGovernanceSync: Bound<typeof hcaAdmin.renounceGovernanceSync>; /** Revokes root roles on the HCA upgrade set (role admins only). Resolves once the transaction is submitted. */ readonly revokeUpgradeSetRoles: BoundWrite<typeof hcaAdmin.revokeUpgradeSetRoles>; /** Revokes root roles on the HCA upgrade set (role admins only). Resolves once the receipt is in. */ readonly revokeUpgradeSetRolesSync: Bound<typeof hcaAdmin.revokeUpgradeSetRolesSync>; /** Approves or revokes an implementation for new HCA deployments (factory owner only). Resolves once the transaction is submitted. */ readonly setDeploymentApproval: BoundWrite<typeof hcaAdmin.setDeploymentApproval>; /** Approves or revokes an implementation for new HCA deployments (factory owner only). Resolves once the receipt is in. */ readonly setDeploymentApprovalSync: Bound<typeof hcaAdmin.setDeploymentApprovalSync>; /** Approves or revokes an implementation in the HCA upgrade set (role holders only). Resolves once the transaction is submitted. */ readonly setUpgradeApproval: BoundWrite<typeof hcaAdmin.setUpgradeApproval>; /** Approves or revokes an implementation in the HCA upgrade set (role holders only). Resolves once the receipt is in. */ readonly setUpgradeApprovalSync: Bound<typeof hcaAdmin.setUpgradeApprovalSync>; /** Transfers ownership of the HCA factory (factory owner only). Resolves once the transaction is submitted. */ readonly transferGovernance: BoundWrite<typeof hcaAdmin.transferGovernance>; /** Transfers ownership of the HCA factory (factory owner only). Resolves once the receipt is in. */ readonly transferGovernanceSync: Bound<typeof hcaAdmin.transferGovernanceSync>; } |
HcaOptions
Experimental
Options of hca.
type HcaOptions| Option | Type | Default | Description |
|---|---|---|---|
executors | readonly Executor[] | [owner()] | How executions run. hca() picks the first executor that can run the request (one with sessions when session is set) once, and never falls back to another when a send fails. |
session | HcaSession | Run as this session (no owner prompts); needs an executor with sessions (rhinestone()). |
HcaProblem
Experimental
A reason an address is not a usable HCA of its owner (HCA.md's checks).
type HcaProblem = | "address-mismatch" | "owner-unavailable" | "owner-mismatch" | "unknown-account" | "untrusted-implementation" | "not-certified";HcaSession
Experimental
A session the HCA owner approved: a key that may register names and edit one resolver's records through Rhinestone without further prompts. Store it; it holds no secret.
type HcaSession| Field | Type | Description |
|---|---|---|
chainId | number | |
hca | Address | |
owner | Address | |
sessionKey | Address | Public address of the session key; the key itself stays with the app. |
terms | HcaSessionTerms | |
permissionId | Hex | |
sessionDigest | Hex | This chain's session digest. |
chains | readonly { readonly chainId: number; readonly sessionDigest: Hex }[] | Every chain and digest the owner signed, this chain first. |
ownerSignature | Hex | The owner's signature over the multi-chain approval. |
signingDomain | "smart-session" | "hca" | EIP-712 domain the approval was signed under. |
PimlicoOptions
Experimental
Options of pimlico.
type PimlicoOptions| Option | Type | Default | Description |
|---|---|---|---|
apiKey (required) | string | Pimlico API key. | |
sponsor | boolean | Sponsor UserOperations with Pimlico's paymaster. @default false | |
sponsorshipPolicyId | string | Pimlico sponsorship policy id. |
RhinestoneAccount
Experimental
A Rhinestone SDK account, as createAccount returns it.
type RhinestoneAccount| Field | Type | Description |
|---|---|---|
getAddress | () => Address | |
prepareTransaction | (transaction: unknown) => Promise<unknown> | |
signTransaction | (prepared: unknown) => Promise<unknown> | |
submitTransaction | (signed: unknown) => Promise<{ readonly id: bigint | string }> |
RhinestoneOptions
Experimental
Options of rhinestone.
type RhinestoneOptions| Option | Type | Default | Description |
|---|---|---|---|
sdk (required) | RhinestoneSdk | A Rhinestone SDK instance with standalone HCA support, created by the app. | |
sessionSigner | Account | The session key's signer, for session executions. | |
sponsored | boolean | Sponsor executions; otherwise fees are paid in the session's refund token. @default true |
RhinestoneSdk
Experimental
The parts of a Rhinestone SDK instance the executor uses; any SDK release with standalone
HCA support (type: "hca", version: "ens-standalone-1.1.0") fits.
type RhinestoneSdk| Field | Type | Description |
|---|---|---|
createAccount | (config: unknown) => Promise<RhinestoneAccount> | |
getIntentStatus | (id: bigint) => Promise<{ readonly status: string; readonly fill?: { readonly hash?: Hex | undefined } | undefined; }> |
Was this page helpful?