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.
| Problem | Meaning |
|---|---|
address-mismatch | The address is not the one derived from the owner. |
owner-unavailable | The owner cannot be read from the account. |
owner-mismatch | The account's owner is not the expected owner. |
unknown-account | The account does not report the id ens-standalone-hca.1.1.0. |
untrusted-implementation | The implementation is neither the factory's first one nor in the DAO's upgrade set. |
not-certified | The 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?