# Executors

> For the complete documentation index, see [llms.txt](https://ensforge.com/llms.txt).

Look up the HCA route, the executors that send hosted contract account calls, and their options in the experimental @ensforge/hca package.

Source: https://ensforge.com/docs/reference/hca/executors

Exports of `@ensforge/hca` besides its actions and `HcaError`. `@ensforge/hca` is experimental.

## Route and executors [#route-and-executors]

### `bundler` [#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.

```ts
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.

```ts title="A bundler URL"
import { bundler, hca } from "@ensforge/hca"

const via = hca({ executors: [bundler({ url: bundlerUrl, paymaster: bundlerUrl })] })
```

```ts title="Renewing gaslessly"
await ens.registration.renewSync({ names: ["alice.eth"], duration, via })
```

```ts title="With a sponsorship policy"
import { bundler } from "@ensforge/hca"

bundler({ url, paymaster: url, paymasterContext: { sponsorshipPolicyId: "sp_…" } })
```

### `defineExecutor` [#defineexecutor]

**Experimental**

Builds an executor from your own functions, e.g. for another bundler SDK or a relayer.

```ts
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.

```ts title="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),
})
```

```ts title="Used for the write"
import { hca } from "@ensforge/hca"

const via = hca({ executors: [relayer] })
```

```ts title="A test double"
import { defineExecutor } from "@ensforge/hca"

const fake = defineExecutor({ id: "fake", capabilities, send: async () => "1", status: async () => ({ status: "success", hashes: [hash] }) })
```

### `hca` [#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.

```ts
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.

```ts title="Migrating through the HCA"
import { hca } from "@ensforge/hca"

await ens.migration.migrateSync({ names: ["alice.eth", "bob.eth"], via: hca() })
```

```ts title="Gasless through a bundler"
import { hca, pimlico } from "@ensforge/hca"

await ens.hca.executeSync({ calls, via: hca({ executors: [pimlico({ apiKey, sponsor: true })] }) })
```

```ts title="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` [#hcaactions]

**Experimental**

Adds the `hca` actions to a client.

```ts
function hcaActions()
```

### `hcaAdminActions` [#hcaadminactions]

**Experimental**

Adds the `hcaAdmin` actions to a client.

```ts
function hcaAdminActions()
```

### `owner` [#owner]

**Experimental**

The owner's wallet sends each HCA execution as an `executeByOwner` transaction. The default
executor; needs no service.

```ts
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.

```ts title="Explicitly"
import { hca, owner } from "@ensforge/hca"

await ens.hca.executeSync({ calls, via: hca({ executors: [owner()] }) })
```

```ts title="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()] })
```

```ts title="Sponsored by the wallet"
import { hca } from "@ensforge/hca"

await ens.migration.migrate({ names, via: hca(), paymaster: { url: paymasterUrl } })
```

### `pimlico` [#pimlico]

**Experimental**

[`bundler`](/docs/reference/hca/executors#bundler) preset for Pimlico's hosted bundler and paymaster. Experimental, as `bundler`.

```ts
function pimlico(options: PimlicoOptions): Executor
```

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

```ts title="Sponsored"
import { hca, pimlico } from "@ensforge/hca"

const via = hca({ executors: [pimlico({ apiKey, sponsor: true })] })
```

```ts title="With a policy"
import { pimlico } from "@ensforge/hca"

pimlico({ apiKey, sponsor: true, sponsorshipPolicyId: "sp_…" })
```

```ts title="Unsponsored: the HCA pays gas"
import { pimlico } from "@ensforge/hca"

pimlico({ apiKey })
```

### `rhinestone` [#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.

```ts
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`](/docs/reference/errors/HCA_SDK_UNSUPPORTED) (stock SDK releases without the standalone HCA derive another).
- Status follows the intent until its fill transaction is mined.

```ts title="With a session"
import { hca, rhinestone } from "@ensforge/hca"

const via = hca({ executors: [rhinestone({ sdk, sessionSigner })], session })
```

```ts title="Owner-signed, sponsored"
import { hca, rhinestone } from "@ensforge/hca"

const via = hca({ executors: [rhinestone({ sdk })] })
```

```ts title="Paying fees in the refund token"
import { rhinestone } from "@ensforge/hca"

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

## Types [#types]

### `BundlerOptions` [#bundleroptions]

**Experimental**

Options of [`bundler`](/docs/reference/hca/executors#bundler).

```ts
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`](/docs/reference/errors/HCA_EXECUTION_TIMEOUT). Bundlers can keep an operation they cannot land forever. |

### `ExecutionRequest` [#executionrequest]

**Experimental**

What an executor is asked to run: owner-authorized (or session-authorized) calls from the HCA.

```ts
type ExecutionRequest
```

| Field | Type | Description |
| --- | --- | --- |
| `chainId` | `number` |  |
| `hca` | `Address` |  |
| `owner` | `Address` |  |
| `deployed` | `boolean` |  |
| `calls` | `readonly Plan.Call[]` |  |
| `session` (optional) | `HcaSession` |  |
| `description` | `string` |  |

### `Executor` [#executor]

**Experimental**

Runs HCA executions: the owner's wallet (`owner()`), an ERC-4337 bundler (`bundler()`,
`pimlico()`), Rhinestone intents (`rhinestone()`), or your own (`defineExecutor`).

```ts
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` [#hcaaccount]

**Experimental**

An ENS Hosted Contract Account, deployed or predicted.

```ts
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` [#hcaactions-1]

**Experimental**

`hca` actions bound to a client.

```ts
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` [#hcaadminactions-1]

**Experimental**

`hcaAdmin` actions bound to a client.

```ts
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` [#hcaoptions]

**Experimental**

Options of [`hca`](/docs/reference/hca/executors#hca).

```ts
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` [#hcaproblem]

**Experimental**

A reason an address is not a usable HCA of its owner (HCA.md's checks).

```ts
type HcaProblem = | "address-mismatch" | "owner-unavailable" | "owner-mismatch" | "unknown-account" | "untrusted-implementation" | "not-certified";
```

### `HcaSession` [#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.

```ts
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` [#pimlicooptions]

**Experimental**

Options of [`pimlico`](/docs/reference/hca/executors#pimlico).

```ts
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` [#rhinestoneaccount]

**Experimental**

A Rhinestone SDK account, as `createAccount` returns it.

```ts
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` [#rhinestoneoptions]

**Experimental**

Options of [`rhinestone`](/docs/reference/hca/executors#rhinestone).

```ts
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` [#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.

```ts
type RhinestoneSdk
```

| Field | Type | Description |
| --- | --- | --- |
| `createAccount` | `(config: unknown) => Promise<RhinestoneAccount>` |  |
| `getIntentStatus` | `(id: bigint) => Promise<{ readonly status: string; readonly fill?: { readonly hash?: Hex \| undefined } \| undefined; }>` |  |