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

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): Executor

Use 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.execute succeed 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_sign over the UserOperation hash.
A bundler URL
import { bundler, hca } from "@ensforge/hca"

const via = hca({ executors: [bundler({ url: bundlerUrl, paymaster: bundlerUrl })] })
Renewing gaslessly
await ens.registration.renewSync({ names: ["alice.eth"], duration, via })
With a sponsorship policy
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): Executor

Use 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.
A relayer
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),
})
Used for the write
import { hca } from "@ensforge/hca"

const via = hca({ executors: [relayer] })
A test double
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.Via

Use 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.
Migrating through the HCA
import { hca } from "@ensforge/hca"

await ens.migration.migrateSync({ names: ["alice.eth", "bob.eth"], via: hca() })
Gasless through a bundler
import { hca, pimlico } from "@ensforge/hca"

await ens.hca.executeSync({ calls, via: hca({ executors: [pimlico({ apiKey, sponsor: true })] }) })
Prompt-free with a session
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(): Executor

Use 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 paymaster on the write, an EIP-5792 wallet can sponsor the transactions.
Explicitly
import { hca, owner } from "@ensforge/hca"

await ens.hca.executeSync({ calls, via: hca({ executors: [owner()] }) })
Choosing the executor
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()] })
Sponsored by the wallet
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): Executor

Use with a Pimlico API key for gasless owner actions on mainnet or Sepolia.

Sponsored
import { hca, pimlico } from "@ensforge/hca"

const via = hca({ executors: [pimlico({ apiKey, sponsor: true })] })
With a policy
import { pimlico } from "@ensforge/hca"

pimlico({ apiKey, sponsor: true, sponsorshipPolicyId: "sp_…" })
Unsponsored: the HCA pays gas
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): Executor

Use 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.
With a session
import { hca, rhinestone } from "@ensforge/hca"

const via = hca({ executors: [rhinestone({ sdk, sessionSigner })], session })
Owner-signed, sponsored
import { hca, rhinestone } from "@ensforge/hca"

const via = hca({ executors: [rhinestone({ sdk })] })
Paying fees in the refund token
import { rhinestone } from "@ensforge/hca"

rhinestone({ sdk, sessionSigner, sponsored: false })

Types

BundlerOptions

Experimental

Options of bundler.

type BundlerOptions
OptionTypeDefaultDescription
url (required)stringERC-4337 bundler RPC URL (EntryPoint v0.7).
paymasterstringPaymaster RPC URL (ERC-7677) that sponsors the UserOperations, often the bundler's own.
paymasterContextReadonly<Record<string, unknown>>Paymaster context, e.g. a sponsorship policy id.
idstringId reported on plans and errors. @default "bundler"
timeoutnumber180_000Milliseconds 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
FieldTypeDescription
chainIdnumber
hcaAddress
ownerAddress
deployedboolean
callsreadonly Plan.Call[]
session (optional)HcaSession
descriptionstring

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
FieldTypeDescription
idstring
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
FieldTypeDescription
addressAddress
ownerAddress | nullThe immutable owner (the wallet); null when it cannot be read.
deployedboolean
authorizedOwnerAddress | nullOwner the factory certified for this account.
accountIdstring | nullaccountId(), e.g. ens-standalone-hca.1.1.0.
implementationAddress | nullCurrent implementation; null before deployment.
initialImplementationAddressImplementation the address derives from; it never changes.
sessionNoncebigintIncrements with revokeSessions, invalidating every session approval.
upgradeSetAddressDAO set of implementations this account may upgrade to.
problemsreadonly HcaProblem[]Failed checks; empty for a usable (or not yet deployed) HCA.

HcaActions

Experimental

hca actions bound to a client.

type HcaActions
FieldTypeDescription
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
FieldTypeDescription
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
OptionTypeDefaultDescription
executorsreadonly 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.
sessionHcaSessionRun 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
FieldTypeDescription
chainIdnumber
hcaAddress
ownerAddress
sessionKeyAddressPublic address of the session key; the key itself stays with the app.
termsHcaSessionTerms
permissionIdHex
sessionDigestHexThis chain's session digest.
chainsreadonly { readonly chainId: number; readonly sessionDigest: Hex }[]Every chain and digest the owner signed, this chain first.
ownerSignatureHexThe 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
OptionTypeDefaultDescription
apiKey (required)stringPimlico API key.
sponsorbooleanSponsor UserOperations with Pimlico's paymaster. @default false
sponsorshipPolicyIdstringPimlico sponsorship policy id.

RhinestoneAccount

Experimental

A Rhinestone SDK account, as createAccount returns it.

type RhinestoneAccount
FieldTypeDescription
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
OptionTypeDefaultDescription
sdk (required)RhinestoneSdkA Rhinestone SDK instance with standalone HCA support, created by the app.
sessionSignerAccountThe session key's signer, for session executions.
sponsoredbooleanSponsor 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
FieldTypeDescription
createAccount(config: unknown) => Promise<RhinestoneAccount>
getIntentStatus(id: bigint) => Promise<{ readonly status: string; readonly fill?: { readonly hash?: Hex | undefined } | undefined; }>

Was this page helpful?