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

How it works

Learn what a hosted contract account is, how ensforge runs a write from it, how it checks the account, and who controls it.

Experimental

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

A hosted contract account (HCA) is a smart contract wallet that ENS hosts for your wallet. Your wallet owns it, ENS's factory deploys it, and it calls ENS contracts on your behalf. Because it is a contract, it can run many calls as one atomic execution, and it can act without a wallet prompt when you approve a session.

One account per owner

ensforge uses one HCA for each wallet on a chain. Its address derives from the owner and the deployment's initial implementation, so ensforge can compute it before it exists (hca.predictAddress). The address never changes, even after upgrades.

  • The owner is fixed when the account is deployed. Nobody can change it.
  • ensforge deploys the account on first use, through the ENS factory. You can also deploy it ahead of time with hca.deploy. Deploying twice returns the existing account.
  • The account is not a place to keep names. It refuses name tokens, so a transfer of a name to an HCA fails with TRANSFER_DISALLOWED.

How a write runs from the account

A normal write sends transactions from your wallet. A write with via: hca() sends a different plan: ensforge wraps the calls in one executeByOwner call on your HCA, and the HCA calls the ENS contracts. hca() is a route.

flowchart LR
  A[Your app] -->|via hca| B[ensforge]
  B -->|plan with one execution| C[Executor]
  C -->|executeByOwner| D[Your HCA]
  D -->|calls as msg.sender| E[ENS contracts]

The executor is the part that delivers the execution: your wallet (owner(), the default), an ERC-4337 bundler, Rhinestone or your own. hca() picks one executor when you call it: the first in executors, or with a session the first that runs sessions. It never switches to another executor if a send fails. See Your wallet and Custom executors.

ensforge adds two things around your calls:

  • A setup step, sent by your wallet, that deploys the HCA when the executor cannot and approves the HCA to move the name tokens the write touches.
  • Batches. Consecutive steps without a wait run as one atomic execution, up to 32 calls. A step is never split. Every call succeeds or the whole execution reverts.

When a wrapped name is involved, the HCA becomes an operator of all your names in the Name Wrapper. The plan warns with HCA_WRAPPER_APPROVAL. Revoke it with approval.setOperator once the write is done.

What the HCA can do

The HCA is msg.sender of the calls it runs, so it needs authority over what they touch. Migration and registration plan for it, and renewals work because anyone may renew. Other writes need the HCA to hold the roles they use, and fail at simulation otherwise. See Who can change a name.

ensforge never routes a write through an HCA unless you pass via.

How ensforge trusts an account

Before it uses a deployed HCA, ensforge checks it. hca.get returns the failed checks in problems. hca.verify throws HCA_NOT_VERIFIED instead.

ProblemMeaning
address-mismatchThe address is not the one derived from the owner.
owner-unavailableThe owner cannot be read from the account.
owner-mismatchThe account's owner is not the expected owner.
unknown-accountThe account does not report the id ens-standalone-hca.1.1.0.
untrusted-implementationThe implementation is neither the factory's first one nor in the DAO's upgrade set.
not-certifiedThe factory did not certify this owner for this account.

A predicted account, not yet deployed, passes: its first execution deploys it. A write through via: hca() fails with HCA_NOT_VERIFIED when the deployed account has any problem.

Every HCA error code has an end-user message: Errors.describe returns a title, message and action you can show as they are.

Read the account

The HCA reads (hca.get, hca.predictAddress, hca.verify, hca.getSession, hca.getDeposit, hca.getUpgrade, hca.checkSessionCalls and hcaAdmin.getGovernance) have a .request, like the SDK's reads. Pass them to batch next to other reads, or to useReads in React. A failed read fails only its own result unless you set allowFailure: false.

Who governs it

The factory has an owner, and the DAO keeps a set of implementations that accounts may upgrade to. An upgrade keeps the address and the sessions. See Upgrades and governance.

When it is not available

  • Only chains with an HCA deployment work: mainnet and Sepolia. Layer 2 plans do not route through an HCA, because the HCA lives on Ethereum.
  • Sessions run only through Rhinestone. Bundlers run owner operations only. See Sessions.

Was this page helpful?