# Addresses and chains
> For the complete documentation index, see [llms.txt](https://ensforge.com/llms.txt).
Look up ENS contract addresses, behaviour flags and provenance for mainnet and Sepolia, or for any supported chain by its ID.
Source: https://ensforge.com/docs/contracts/addresses-and-chains
`Deployments` holds one **profile** per supported chain. A profile has the addresses of every ENS contract on that chain, flags for behaviour that differs between chains, and where the addresses come from. By the end of this guide you will find any address by chain and know which flags to check.
## Look up a profile [#look-up-a-profile]
`Deployments.mainnet` and `Deployments.sepolia` are the built-in profiles. `Deployments.get({ chainId })` returns the profile of a chain, or `undefined` when ensforge ships none. `Deployments.list()` returns both.
**Example** (Reading Addresses From a Profile)
```ts title="profiles.ts"
import { Deployments } from "@ensforge/contracts";
const registry = Deployments.mainnet.v2.contracts.ethRegistry;
const sepoliaResolver = Deployments.get({ chainId: 11155111 })?.v2?.contracts.publicResolver;
const chainIds = Deployments.list().map((profile) => profile.chainId);
```
A profile is `{ name, chainId, v1?, v2? }`. `v1` and `v2` are the [ENSv1](/docs/reference/glossary#ensv1) and [ENSv2](/docs/reference/glossary#ensv2) deployments on that chain. Both exist on mainnet and Sepolia. Use `get` with optional chaining for chains that may have no profile.
## What a deployment holds [#what-a-deployment-holds]
Both `v1` and `v2` carry an `id` such as `mainnet-v2`, the `chainId`, a `protocol`, a `status` and a `provenance`. `status` is `"active"` for the current protocol on that chain, `"legacy"` for a deployment kept for compatibility and migration, and `"beta"` for one not yet recommended for production names. On mainnet and Sepolia, ENSv2 is `active` and ENSv1 is `legacy`.
### ENSv2 address groups [#ensv2-address-groups]
| Group | What it holds |
| ----------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `contracts` | Entry points apps call directly, such as the Universal Resolver proxy, the root and `.eth` [registries](/docs/reference/glossary#registry), the `.eth` [registrar](/docs/reference/glossary#registrar), the rent price oracle, the public [resolver](/docs/reference/glossary#resolver), the verifiable factory and the reverse registrar adapters. |
| `implementations` | Implementation contracts that proxies and the factory point to, such as `permissionedResolver` and `userRegistry`. |
| `migration` | ENSv1 to ENSv2 [migration](/docs/reference/glossary#migration) contracts, such as `unlockedMigrationController` and `migrationHelper`. |
| `infrastructure` | Supporting contracts: batch registrars, token URI renderers and the ENS-managed Universal Resolver proxy. |
| `dns` | DNS integration contracts. Present when the deployment has them. |
| `hca` | [HCA](/docs/reference/glossary#hca) (Hosted Contract Account) contracts, experimental. Present when the deployment has them. |
| `paymentTokens` | The ERC-20 tokens the `.eth` registrar accepts: `dai` and `usdc`. The rent price oracle stays the source of truth. |
### ENSv1 contracts [#ensv1-contracts]
`v1.contracts` holds the registry, the `.eth` registrar, its controller, price oracle and bulk renewal helper, the [Name Wrapper](/docs/reference/glossary#name-wrapper), the public resolver, the Universal Resolver, the reverse registrars and the DNS contracts. `legacyPublicResolvers` and `frozenPublicResolvers` list earlier public resolver generations: legacy ones still authorise writes, frozen ones can be read but no longer changed.
Since the ENSv2 cutover, ENSv1 controllers no longer register or renew `.eth` names on mainnet: the ENSv1 `.eth` registrar now belongs to ENSv2's `migration.ethRenewerV1`. The controller addresses remain so that you can read past registrations.
## Check behaviour flags before you branch on a chain [#check-behaviour-flags-before-you-branch-on-a-chain]
The same ENSv2 release can behave differently on two chains, because ENS deployed some contracts individually. `v2.capabilities` records those differences, so code can branch on a flag instead of on the chain ID.
| Flag | Values | Meaning |
| ----------------------------- | ------------------------------ | ------------------------------------------------------------------------------- |
| `resolutionErrorWrapping` | `boolean` | Resolution contracts wrap registry reverts in `ResolutionError(address,bytes)`. |
| `wrapperRegistryInitializer` | `"explicit"`, `"fuse-derived"` | How a WrapperRegistry receives its label and roles. |
| `wrapperRegistryEmancipation` | `"static"`, `"role-derived"` | How `isEmancipated` is computed. |
| `lockedMigrationRenewal` | `"renew-role"`, `"max-expiry"` | How locked migration treats names that can extend their expiry. |
| `userRegistryUpgradeGate` | `boolean` | User registries upgrade only to approved implementations. |
| `userRegistryRootRenewal` | `boolean` | New user registries check the `renew` role at their root only. |
| `hcaSameChainSourceRejected` | `boolean` | The HCA validator rejects permits whose source chain is the current chain. |
| `hcaSessionDomain` | `"smart-session"`, `"hca"` | The EIP-712 domain HCA session approvals use. |
| `hcaContractOwners` | `boolean` | HCA owners can be contracts that sign with ERC-1271. |
**Example** (Branching on a Flag)
```ts title="capabilities.ts"
import { Deployments } from "@ensforge/contracts";
const { wrapperRegistryInitializer } = Deployments.mainnet.v2.capabilities;
```
`wrapperRegistryInitializer` is `"fuse-derived"` on mainnet and `"explicit"` on Sepolia.
## Find where an address comes from [#find-where-an-address-comes-from]
`provenance` names the repository, the release tag, the commit and, for ENSv2, the compiler build of each contract. ENSv2 networks mix builds because contracts were redeployed one by one. Mainnet and Sepolia ENSv2 come from contracts-v2 `v1.0.1`, ENSv1 from ens-contracts `v1.7.0`.
**Example** (Reading Provenance)
```ts title="provenance.ts"
import { Deployments } from "@ensforge/contracts";
const { repository, release, commit } = Deployments.sepolia.v2.provenance;
```
## Find a reverse registrar on a layer 2 [#find-a-reverse-registrar-on-a-layer-2]
`Deployments.l2ReverseRegistrars` maps a chain ID to the ENSv1 `L2ReverseRegistrar` on that chain, where an address sets its [primary name](/docs/reference/glossary#primary-name) for that chain. All mainnet layer 2s share one address and all testnets share another.
**Example** (Finding the Base Reverse Registrar)
```ts title="l2-reverse.ts"
import { Deployments } from "@ensforge/contracts";
const base = Deployments.l2ReverseRegistrars[8453];
```
It covers OP Mainnet, Base, Arbitrum One, Linea and Scroll, and their Sepolia testnets. The ABI is `Abis.v1.l2ReverseRegistrar`.
## Troubleshooting [#troubleshooting]
### `get` returns `undefined` [#get-returns-undefined]
ensforge ships profiles for mainnet and Sepolia only. For a devnet, a fork or any other chain, [define a custom deployment](/docs/contracts/custom-deployments). See also [`UNKNOWN_CHAIN`](/docs/reference/errors/UNKNOWN_CHAIN), which the SDK client throws for a chain without a profile.
See the [deployments reference](/docs/reference/contracts/deployments) for every address.
# Custom deployments
> For the complete documentation index, see [llms.txt](https://ensforge.com/llms.txt).
Validate the ENS profile of a devnet, fork or custom chain with Deployments.define, then pass it to the ensforge SDK to use it.
Source: https://ensforge.com/docs/contracts/custom-deployments
ensforge ships profiles for mainnet and Sepolia. For a local devnet, a fork or any other chain, you write the profile yourself. `Deployments.define` checks it and returns it unchanged. By the end of this guide you will have a validated profile and an SDK client that uses it.
## Prerequisites [#prerequisites]
- The addresses of the ENS contracts on your chain.
- `@ensforge/contracts` installed. See [Installation](/docs/contracts/installation).
## 1. Write the profile [#1-write-the-profile]
A profile is `{ name, chainId, v1?, v2? }`, and at least one of `v1` and `v2` is required. Each deployment needs an `id`, the same `chainId` as the profile, a `protocol`, a `status` and its address groups. See [Addresses and chains](/docs/contracts/addresses-and-chains) for the groups.
The simplest start is to copy a built-in deployment and change the addresses you deploy yourself.
**Example** (A Devnet Profile Based on Mainnet)
```ts title="devnet.ts"
import { Deployments } from "@ensforge/contracts";
export const devnet = Deployments.define({
name: "devnet",
chainId: 31337,
v2: {
...Deployments.mainnet.v2,
id: "devnet-v2",
chainId: 31337,
contracts: {
...Deployments.mainnet.v2.contracts,
ethRegistry: "0x5FbDB2315678afecb367f032d93F642f64180aa3", // your devnet address
},
},
});
```
- Every address must be a `0x`-prefixed 20-byte address.
- `capabilities` is required on a `v2` deployment. Copy it from the release your contracts match, then adjust flags that differ. See [Addresses and chains](/docs/contracts/addresses-and-chains#check-behaviour-flags-before-you-branch-on-a-chain).
## 2. Handle validation errors [#2-handle-validation-errors]
`define` throws `Deployments.InvalidProfileError` with every problem it finds, not only the first. It checks that the chain IDs agree, that every required group and address is present and well-formed, that no unknown contract name appears, and that every capability flag has a known value. It does not read the chain.
**Example** (Catching an Invalid Profile)
```ts title="invalid.ts"
import { Deployments } from "@ensforge/contracts";
try {
Deployments.define({ name: "broken", chainId: 31337 });
} catch (error) {
if (error instanceof Deployments.InvalidProfileError) {
console.log(error.issues); // ["at least one of v1 and v2 is required"]
}
}
```
## 3. Use the profile with the SDK [#3-use-the-profile-with-the-sdk]
Pass the profile as `deployment` when you create the client. The client's chain must match the profile's `chainId`, or creation fails with [`INVALID_DEPLOYMENT`](/docs/reference/errors/INVALID_DEPLOYMENT).
**Example** (Creating a Client for the Devnet)
```ts title="client.ts"
import { Deployments } from "@ensforge/contracts";
import { Ensforge, ensActions } from "@ensforge/sdk";
import { createPublicClient, http } from "viem";
import { foundry } from "viem/chains";
declare const devnet: Deployments.Profile;
const ens = Ensforge.create({
publicClient: createPublicClient({ chain: foundry, transport: http() }),
deployment: devnet,
}).extend(ensActions());
```
See [Create a client](/docs/sdk/create-a-client).
## Troubleshooting [#troubleshooting]
### `Deployments.InvalidProfileError` [#deploymentsinvalidprofileerror]
Read `error.issues`. Each entry names the path, such as `v2.contracts.ethRegistry is required` or `v2.capabilities.hcaSessionDomain must be one of "smart-session", "hca"`. Fix each and call `define` again.
### `INVALID_DEPLOYMENT` [#invalid_deployment]
`Deployments.define` rejected the profile, or the profile is for another chain than the client's. Read the error's `cause` for the profile's issues, and match `chainId` to the viem client's chain. See [`INVALID_DEPLOYMENT`](/docs/reference/errors/INVALID_DEPLOYMENT).
# Interface IDs and roles
> For the complete documentation index, see [llms.txt](https://ensforge.com/llms.txt).
Detect ENS contract types with ERC-165 interface IDs, and check the ENSv2 roles an account holds on a registry or resolver.
Source: https://ensforge.com/docs/contracts/interface-ids-and-roles
This guide covers two sets of constants. **Interface IDs** tell you what a contract is. **Role bitmaps** tell you what an account may do on an [ENSv2](/docs/reference/glossary#ensv2) [registry](/docs/reference/glossary#registry) or [resolver](/docs/reference/glossary#resolver). By the end you will have detected a resolver type and checked a role.
## Prerequisites [#prerequisites]
- `@ensforge/contracts` and `viem` installed. See [Installation](/docs/contracts/installation).
- A public client. See [Use ABIs with viem](/docs/contracts/use-abis-with-viem).
## Detect a contract with an interface ID [#detect-a-contract-with-an-interface-id]
An **ERC-165 interface ID** is a four-byte value a contract reports through `supportsInterface`. `InterfaceIds` groups them:
| Group | Holds |
| ------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------- |
| `InterfaceIds.registry` | ENSv2 registry interfaces, such as `permissionedRegistry` and `wrapperRegistry`. |
| `InterfaceIds.wrapperRegistryInitializable` | The two `IWrapperRegistryInitializable` IDs, `explicit` and `fuseDerived`, one per `wrapperRegistryInitializer` flag value. |
| `InterfaceIds.resolver` | ENSv2 resolver interfaces, such as `permissionedResolver`. |
| `InterfaceIds.resolverProfiles` | Resolver profile interfaces: `addr`, `text`, `contenthash`, `abi`, `pubkey`, `extended` and others. |
| `InterfaceIds.erc165` | The ERC-165 interface ID itself. |
**Example** (Detecting a PermissionedResolver)
```ts title="detect-resolver.ts"
import { Abis, InterfaceIds } from "@ensforge/contracts";
import { createPublicClient, http } from "viem";
import { mainnet } from "viem/chains";
const publicClient = createPublicClient({ chain: mainnet, transport: http() });
const resolver = "0x0000000000000000000000000000000000000001"; // placeholder: the resolver to inspect
const isPermissioned = await publicClient.readContract({
address: resolver,
abi: Abis.shared.erc165,
functionName: "supportsInterface",
args: [InterfaceIds.resolver.permissionedResolver],
});
```
A resolver that does not support the ID returns `false`. Use `InterfaceIds.resolverProfiles.text` the same way to ask whether a resolver can store text [records](/docs/reference/glossary#record).
## Read how roles are encoded [#read-how-roles-are-encoded]
In ENSv2, a registry or resolver grants [roles](/docs/reference/glossary#role) to accounts through EnhancedAccessControl. A role is one bit of a 256-bit number, and a set of roles is a bitmap you combine with `|`. Each role sits in its own nybble, and its **admin role**, which may grant that role, sits 128 bits higher.
| Constant | Holds |
| ----------------------------- | -------------------------------------------------------------------------------------------------------------------------- |
| `Roles.registry` | Registry roles, such as `renew`, `setResolver` and `setSubregistry`. Every role except `wasReserved` has an `…Admin` twin. |
| `Roles.resolver` | PermissionedResolver roles, such as `setAddr`, `setText` and `setContenthash`, each with an `…Admin` twin. |
| `Roles.registryBitmaps` | Role sets: `unemancipated`, `regeneration` and `registration`. |
| `Roles.enhancedAccessControl` | Masks for `allRoles` and `adminRoles`. |
`Roles.registryBitmaps.registration` is the set the `.eth` [registrar](/docs/reference/glossary#registrar) grants a new [owner](/docs/reference/glossary#owner): changing the resolver and subregistry, their admin roles, and the admin role of transfers. Use it as a default for any new name an owner should control.
## Check a role [#check-a-role]
Ask the registry for the account's roles on a name, then test the bit with `&`.
**Example** (Checking the Renew Role)
```ts title="check-role.ts"
import { Abis, Deployments, Roles } from "@ensforge/contracts";
import { createPublicClient, hexToBigInt, http } from "viem";
import { labelhash } from "viem/ens";
import { mainnet } from "viem/chains";
const publicClient = createPublicClient({ chain: mainnet, transport: http() });
const account = "0x0000000000000000000000000000000000000001"; // placeholder: the account to check
const bitmap = await publicClient.readContract({
address: Deployments.mainnet.v2.contracts.ethRegistry,
abi: Abis.v2.permissionedRegistry,
functionName: "roles",
args: [hexToBigInt(labelhash("vitalik")), account],
});
const canRenew = (bitmap & Roles.registry.renew) !== 0n;
```
- `roles` takes the label hash as a number and the account.
- To grant several roles, combine them: `Roles.registry.setResolver | Roles.registry.renew`.
For a resolver, `Roles.resolver.setText` and its siblings apply to a **resource**: one record key, or the root. `permissionedResolverResource({ text: "url" })` from `@ensforge/contracts/v2` computes the resource for a record.
## Which role bitmaps change a name's token [#which-role-bitmaps-change-a-names-token]
`Roles.registryBitmaps.regeneration` lists the roles whose change regenerates a name's token ID. `Roles.registryBitmaps.unemancipated` lists the roles that, held by anyone but the sole owner, mean the name is not [emancipated](/docs/reference/glossary#emancipated). It leaves out the `renew` and `upgrade` roles. Mainnet WrapperRegistry follows these sets; the Sepolia WrapperRegistry build predates them.
Role bitmaps apply to ENSv2 registries and resolvers. ENSv1 names use owners, managers and Name
Wrapper fuses instead. See [Roles and permissions](/docs/sdk/roles-and-permissions).
## Troubleshooting [#troubleshooting]
### `supportsInterface` reverts [#supportsinterface-reverts]
The address may not implement ERC-165. Check that it is a contract and that you pass the interface ID as a four-byte hex value.
See the [roles reference](/docs/reference/contracts/roles) and the [interface IDs reference](/docs/reference/contracts/interface-ids).
# Use ABIs with viem
> For the complete documentation index, see [llms.txt](https://ensforge.com/llms.txt).
Read contracts, simulate and send writes, and decode events with viem, using the typed ENS ABIs from @ensforge/contracts.
Source: https://ensforge.com/docs/contracts/use-abis-with-viem
Every ABI in `@ensforge/contracts` is an `as const` array. viem uses that to type `functionName`, `args` and the result, and to catch a misspelled function at compile time. By the end of this guide you will have read a contract, sent a write and decoded events with these ABIs.
## Prerequisites [#prerequisites]
- `@ensforge/contracts` and `viem` installed. See [Installation](/docs/contracts/installation).
- A viem public client, and a wallet client for writes.
## Find the ABI you need [#find-the-abi-you-need]
`Abis` groups ABIs by protocol, and each key is a contract name in camel case.
| Group | What it holds | Example |
| ------------------------------------------ | -------------------------------------------------------------------------------------------------------- | ------------------------------ |
| `Abis.v2` | ENSv2 contracts at contracts-v2 v1.0.1. Each ABI is the superset of the mainnet and Sepolia deployments. | `Abis.v2.permissionedRegistry` |
| `Abis.v1` | ENSv1 contracts at ens-contracts v1.7.0. | `Abis.v1.ensRegistry` |
| `Abis.shared` | Token standards, ERC-165, resolver profiles, errors and events that both versions share. | `Abis.shared.erc165` |
| `Abis.v2.interfaces`, `Abis.v1.interfaces` | The ABIs of interfaces, for code that targets an interface instead of one contract. | `Abis.v2.interfaces.registry` |
The addresses come from [`Deployments`](/docs/contracts/addresses-and-chains). Browse every key in the [ABI reference](/docs/reference/contracts/abis).
## Read a contract [#read-a-contract]
Pass the address, the ABI, the function name and the arguments to `readContract`. This example asks a registry whether it implements an interface, using the ERC-165 ABI from `Abis.shared`.
**Example** (Checking an Interface With ERC-165)
```ts title="supports-interface.ts"
import { Abis, Deployments, InterfaceIds } from "@ensforge/contracts";
import { createPublicClient, http } from "viem";
import { mainnet } from "viem/chains";
const publicClient = createPublicClient({ chain: mainnet, transport: http() });
const supported = await publicClient.readContract({
address: Deployments.mainnet.v2.contracts.ethRegistry,
abi: Abis.shared.erc165,
functionName: "supportsInterface",
args: [InterfaceIds.registry.permissionedRegistry],
});
supported;
```
`InterfaceIds.registry.permissionedRegistry` is the ERC-165 ID of the `IPermissionedRegistry` interface. See [Interface IDs and roles](/docs/contracts/interface-ids-and-roles).
## Send a write [#send-a-write]
Simulate first, then send. `simulateContract` returns a typed request that `writeContract` accepts, so a revert shows up before the wallet prompt. This example sets a text [record](/docs/reference/glossary#record) on Sepolia with the [ENSv2](/docs/reference/glossary#ensv2) public [resolver](/docs/reference/glossary#resolver).
**Example** (Setting a Text Record on Sepolia)
```ts title="set-text.ts"
import { Abis, Deployments } from "@ensforge/contracts";
import { createPublicClient, createWalletClient, http } from "viem";
import { privateKeyToAccount } from "viem/accounts";
import { namehash, normalize } from "viem/ens";
import { sepolia } from "viem/chains";
const account = privateKeyToAccount(
"0x0123456789012345678901234567890123456789012345678901234567890123",
);
const publicClient = createPublicClient({ chain: sepolia, transport: http() });
const walletClient = createWalletClient({ account, chain: sepolia, transport: http() });
const { request } = await publicClient.simulateContract({
account,
address: Deployments.sepolia.v2.contracts.publicResolver,
abi: Abis.v2.publicResolver,
functionName: "setText",
args: [namehash(normalize("my-name.eth")), "url", "https://example.com"], // placeholder name
});
const hash = await walletClient.writeContract(request);
```
- `namehash(normalize(name))` is the [namehash](/docs/reference/glossary#namehash), the node the resolver stores records under. Always [normalise](/docs/reference/glossary#normalisation) a name before you hash it, or the hash points to another node.
- The call succeeds only when the name uses this resolver and the account may set its records.
Many ENS writes take several dependent calls, waits and approvals. `@ensforge/sdk` plans them for
you. See [Set records](/docs/sdk/set-records). Use raw ABIs when you need a single call that the
SDK does not wrap.
## Decode events [#decode-events]
`Abis.shared.events` holds the events that ENS indexers consume, from registries, registrars, the Name Wrapper, resolvers, reverse registrars and the DNS registrar, across both versions. Pass it to `getContractEvents` or `parseEventLogs` to get typed logs. This example reads the `TextChanged` events of the last 1,000 blocks.
**Example** (Reading Recent TextChanged Events)
```ts title="events.ts"
import { Abis, Deployments } from "@ensforge/contracts";
import { createPublicClient, http } from "viem";
import { sepolia } from "viem/chains";
const publicClient = createPublicClient({ chain: sepolia, transport: http() });
const latest = await publicClient.getBlockNumber();
const logs = await publicClient.getContractEvents({
address: Deployments.sepolia.v2.contracts.publicResolver,
abi: Abis.shared.events,
eventName: "TextChanged",
fromBlock: latest - 1000n,
toBlock: latest,
});
```
## Import ABIs one by one [#import-abis-one-by-one]
Each ABI is also a flat named export, so a bundler can drop every ABI you do not use. The export name is the contract name plus the protocol: `permissionedRegistryV2Abi` from `@ensforge/contracts/v2`, `baseRegistrarV1Abi` from `@ensforge/contracts/v1`. Shared ABIs keep their plain name, such as `erc165Abi`.
**Example** (Importing Flat ABIs)
```ts title="flat-import.ts"
import { permissionedRegistryV2Abi } from "@ensforge/contracts/v2";
import { baseRegistrarV1Abi } from "@ensforge/contracts/v1";
import { erc165Abi } from "@ensforge/contracts/shared";
```
## Troubleshooting [#troubleshooting]
### A function is missing from an ABI [#a-function-is-missing-from-an-abi]
Each ABI belongs to one contract. A registry's ABI has no resolver functions. Check the contract in [Addresses and chains](/docs/contracts/addresses-and-chains) and pick the matching key in `Abis`.
# Quick start
> For the complete documentation index, see [llms.txt](https://ensforge.com/llms.txt).
Read an ENS contract with viem in a few minutes, using a typed ABI and the deployed address for your chain from @ensforge/contracts.
Source: https://ensforge.com/docs/contracts
By the end of this page you will have read a name's state from the [ENSv2](/docs/reference/glossary#ensv2) `.eth` [registry](/docs/reference/glossary#registry) with viem, using an ABI and an address from `@ensforge/contracts`. Install the package first: [Installation](/docs/contracts/installation).
## 1. Pick an address and an ABI [#1-pick-an-address-and-an-abi]
`Deployments.mainnet.v2.contracts.ethRegistry` is the address of the registry that holds [`.eth` names](/docs/reference/glossary#eth-name). `Abis.v2.permissionedRegistry` is the ABI to read it with. The ABI is an `as const` array, so viem infers the function names, arguments and return types.
## 2. Read the contract [#2-read-the-contract]
`getState` takes a [label](/docs/reference/glossary#label)'s hash as a number and returns the name's status, [expiry](/docs/reference/glossary#expiry), latest [owner](/docs/reference/glossary#owner), token ID and role resource.
**Example** (Reading a Name's State)
```ts title="get-state.ts"
import { Abis, Deployments } from "@ensforge/contracts";
import { createPublicClient, hexToBigInt, http } from "viem";
import { labelhash } from "viem/ens";
import { mainnet } from "viem/chains";
const publicClient = createPublicClient({ chain: mainnet, transport: http() });
const state = await publicClient.readContract({
address: Deployments.mainnet.v2.contracts.ethRegistry,
abi: Abis.v2.permissionedRegistry,
functionName: "getState",
args: [hexToBigInt(labelhash("vitalik"))],
});
state;
```
- `labelhash("vitalik")` hashes the label (the part before `.eth`), giving its [labelhash](/docs/reference/glossary#labelhash). [Normalise](/docs/reference/glossary#normalisation) a label before you hash it.
- `status` is the contract's `Status` enum, returned as a number: `0` (`AVAILABLE`), `1` (`RESERVED`) or `2` (`REGISTERED`).
- A `.eth` name that has not moved from [ENSv1](/docs/reference/glossary#ensv1) yet reads as `1` (`RESERVED`) with a zero `latestOwner`, because its owner is still in the ENSv1 registry. `vitalik.eth` reads this way while it stays on ENSv1. The SDK reads both registries for you: see [Get a name's owner, expiry and status](/docs/sdk/get-name-details).
## 3. Read another chain [#3-read-another-chain]
`Deployments.sepolia` has the same shape. Use `Deployments.get({ chainId })` when the chain comes from a variable.
**Example** (Looking Up a Chain by ID)
```ts title="by-chain.ts"
import { Deployments } from "@ensforge/contracts";
const profile = Deployments.get({ chainId: 11155111 });
const ethRegistry = profile?.v2?.contracts.ethRegistry;
```
`get` returns `undefined` for a chain ensforge does not ship. See [Addresses and chains](/docs/contracts/addresses-and-chains).
## Learn more [#learn-more]
Reads, writes, events and the flat exports.
Every address group and behaviour flag.
Detect contracts and check ENSv2 roles.
# Installation
> For the complete documentation index, see [llms.txt](https://ensforge.com/llms.txt).
Install @ensforge/contracts, the ENS ABIs, addresses and constants for viem, and pick the entry point that fits what you need.
Source: https://ensforge.com/docs/contracts/installation
`@ensforge/contracts` holds the ENS contract ABIs, deployment addresses and protocol constants such as interface IDs and [role](/docs/reference/glossary#role) bitmaps. It has no runtime dependencies beyond the `viem` peer, and it does not depend on Effect or on `@ensforge/sdk`, so you can use it alone.
## Requirements [#requirements]
- Node.js 20.19 or later.
- `viem` version 2.57 or later.
## 1. Install the package [#1-install-the-package]
```package-install
@ensforge/contracts viem
```
## 2. Import what you need [#2-import-what-you-need]
The root entry point has four namespaces:
| Namespace | What it holds |
| -------------- | --------------------------------------------------------------------- |
| `Abis` | ABIs as `as const` arrays, in `Abis.v1`, `Abis.v2` and `Abis.shared`. |
| `Deployments` | Addresses, behaviour flags and provenance for mainnet and Sepolia. |
| `InterfaceIds` | ERC-165 interface IDs of registries, resolvers and resolver profiles. |
| `Roles` | ENSv2 role bitmaps for registries and resolvers. |
**Example** (Importing the Namespaces)
```ts title="imports.ts"
import { Abis, Deployments, InterfaceIds, Roles } from "@ensforge/contracts";
const registryAbi = Abis.v2.permissionedRegistry;
const ethRegistry = Deployments.mainnet.v2.contracts.ethRegistry;
const permissionedResolverId = InterfaceIds.resolver.permissionedResolver;
const renewRole = Roles.registry.renew;
```
## Subpath entry points [#subpath-entry-points]
The same ABIs and constants are also available as flat named exports, which suit bundlers that tree-shake by file.
| Import | What it holds |
| ----------------------------------------- | --------------------------------------------------------------------------------------------------------- |
| `@ensforge/contracts/v1` | ENSv1 ABIs and constants, such as `baseRegistrarV1Abi`. |
| `@ensforge/contracts/v2` | ENSv2 ABIs, interfaces, role and interface-ID constants and helpers, such as `permissionedRegistryV2Abi`. |
| `@ensforge/contracts/shared` | ABIs both protocol versions share: token standards, ERC-165, resolver profiles, errors, events. |
| `@ensforge/contracts/v2/experimental/hca` | The experimental [HCA](/docs/reference/glossary#hca) (Hosted Contract Account) ABIs and session helpers. |
See the [entry points reference](/docs/reference/contracts/entry-points) for every export.
## Use it with the SDK [#use-it-with-the-sdk]
`@ensforge/sdk` depends on this package. Use `@ensforge/contracts` directly when you read or write contracts with viem yourself. See [Use ABIs with viem](/docs/contracts/use-abis-with-viem).
# Bundlers
> For the complete documentation index, see [llms.txt](https://ensforge.com/llms.txt).
Run HCA writes as owner-signed ERC-4337 UserOperations through any bundler or through Pimlico, with or without a gas paymaster.
Source: https://ensforge.com/docs/hca/bundlers
`@ensforge/hca` is experimental for 1.0. The bundler path has no production proof upstream yet.
ensforge tests it against a local bundler (alto) without ERC-7562 safe mode, and the live Pimlico
check is still open. Test on Sepolia first.
A **bundler** collects ERC-4337 UserOperations and lands them on chain. The `bundler()` and `pimlico()` [executors](/docs/reference/glossary#executor) send each [HCA](/docs/reference/glossary#hca) execution as a UserOperation that the owner signs, so the owner needs no ETH when a [paymaster](/docs/reference/glossary#paymaster) sponsors it. By the end of this page you will run a write gaslessly.
## What a bundler executor does [#what-a-bundler-executor-does]
- It sends owner operations only. HCA sessions run through [Rhinestone](/docs/hca/rhinestone), not ERC-4337, and `hca()` with a session and only bundler executors fails with [`HCA_EXECUTOR_UNSUPPORTED`](/docs/reference/errors/HCA_EXECUTOR_UNSUPPORTED).
- It targets EntryPoint v0.7.
- The first operation deploys the HCA through its factory, so no setup transaction is needed.
- The owner signs with `personal_sign` over the UserOperation hash. The wallet shows one signature prompt instead of a transaction.
## Use Pimlico [#use-pimlico]
`pimlico()` is a preset for Pimlico's hosted bundler and paymaster on mainnet or Sepolia. It builds the endpoint for the client's chain from your API key.
| Option | Type | Default | Description |
| --------------------- | --------- | ------- | -------------------------------------------- |
| `apiKey` | `string` | none | Your Pimlico API key. |
| `sponsor` | `boolean` | `false` | Sponsor operations with Pimlico's paymaster. |
| `sponsorshipPolicyId` | `string` | none | Pimlico sponsorship policy id. |
**Example** (Gasless Renewal With Pimlico)
```ts title="pimlico.ts"
import { hca, hcaActions, pimlico } from "@ensforge/hca";
import { Ensforge, ensActions } from "@ensforge/sdk";
import { createPublicClient, createWalletClient, http } from "viem";
import { privateKeyToAccount } from "viem/accounts";
import { sepolia } from "viem/chains";
const account = privateKeyToAccount(
"0x0123456789012345678901234567890123456789012345678901234567890123",
);
const ens = Ensforge.create({
publicClient: createPublicClient({ chain: sepolia, transport: http() }),
walletClient: createWalletClient({ account, chain: sepolia, transport: http() }),
})
.extend(ensActions())
.extend(hcaActions());
const via = hca({
executors: [pimlico({ apiKey: "pim_…", sponsor: true })],
});
await ens.hca.executeSync({
calls: [{ to: "0x000000000000000000000000000000000000dEaD", value: 0n }],
via,
});
```
- `sponsor: true` lets Pimlico's paymaster pay. Without it, the HCA pays its own gas.
- The owner signs the UserOperation. The wallet sends no transaction.
- Replace `pim_…` with your Pimlico API key.
## Use any bundler [#use-any-bundler]
`bundler()` takes any ERC-4337 bundler RPC URL that supports EntryPoint v0.7.
| Option | Type | Default | Description |
| ------------------ | ------------------------- | ----------- | ----------------------------------------------------------------------------- |
| `url` | `string` | none | Bundler RPC URL. |
| `paymaster` | `string` | none | ERC-7677 paymaster RPC URL that sponsors operations, often the bundler's own. |
| `paymasterContext` | `Record` | none | Context for the paymaster, such as a sponsorship policy id. |
| `id` | `string` | `"bundler"` | Name shown on plans and errors. |
| `timeout` | `number` | `180000` | Milliseconds an operation may stay pending before `HCA_EXECUTION_TIMEOUT`. |
**Example** (A Sponsored Operation With a Policy)
```ts title="bundler.ts"
import { bundler, hca } from "@ensforge/hca";
const url = "https://bundler.example.com/rpc"; // your bundler
const via = hca({
executors: [bundler({ url, paymaster: url, paymasterContext: { sponsorshipPolicyId: "sp_…" } })],
});
```
Pass `via` to any write, for example `ens.registration.renewSync({ names, duration, via })`. Migration, registration, renewal and `hca.execute` work through the HCA. Other writes need the HCA to hold the roles they use. See [How it works](/docs/hca/how-it-works#what-the-hca-can-do).
## Who pays gas [#who-pays-gas]
| Setup | Who pays |
| ------------------------------------ | ------------------------------------------------------------------------------------------------ |
| No `paymaster` (or `sponsor: false`) | The HCA, from its own funds. Keep it funded: see [Deposits and gas](/docs/hca/deposits-and-gas). |
| `paymaster` or `sponsor: true` | The paymaster. The HCA's balance does not change. |
## Troubleshooting [#troubleshooting]
### `HCA_BUNDLER_REJECTED` [#hca_bundler_rejected]
The bundler refused the operation. The usual cause is that neither the HCA nor a paymaster can pay. Fund the HCA, add a paymaster, and check that the bundler supports EntryPoint v0.7. ensforge marks this error as retryable. See [`HCA_BUNDLER_REJECTED`](/docs/reference/errors/HCA_BUNDLER_REJECTED).
### `HCA_PAYMASTER_REJECTED` [#hca_paymaster_rejected]
The paymaster refused to sponsor the operation. Check the sponsorship policy and context. See [`HCA_PAYMASTER_REJECTED`](/docs/reference/errors/HCA_PAYMASTER_REJECTED).
### `HCA_EXECUTION_TIMEOUT` [#hca_execution_timeout]
The operation stayed pending longer than `timeout`. It may still land: `plan.resume` checks it again. Raise `timeout` to wait longer. See [Continue after a failure](/docs/sdk/continue-after-a-failure) and [`HCA_EXECUTION_TIMEOUT`](/docs/reference/errors/HCA_EXECUTION_TIMEOUT).
# Custom executors
> For the complete documentation index, see [llms.txt](https://ensforge.com/llms.txt).
Build your own HCA executor with defineExecutor, for a relayer, another bundler SDK or a test double, and use it with hca().
Source: https://ensforge.com/docs/hca/custom-executors
`@ensforge/hca` is experimental for 1.0. The `Executor` type can change in a minor release.
An [executor](/docs/reference/glossary#executor) delivers one [HCA](/docs/reference/glossary#hca) execution and reports what happened to it. `defineExecutor` builds one from your own functions. Use it when none of the built-in executors ([your wallet](/docs/hca/your-wallet), [bundlers](/docs/hca/bundlers), [Rhinestone](/docs/hca/rhinestone)) fits, for example a relayer your company runs. By the end of this page you will have an executor that `hca()` can use.
## The shape of an executor [#the-shape-of-an-executor]
An executor is a plain object with a few members. `defineExecutor` freezes a copy of it.
| Member | Type | Description |
| -------------------------- | ----------------------------------------- | -------------------------------------------------------------------------- |
| `id` | `string` | Name shown on plans and errors. |
| `capabilities.sessions` | `boolean` | The executor can run session-authorized executions (no owner prompt). |
| `capabilities.sponsorship` | `boolean` | The executor can run without the owner holding native gas. |
| `capabilities.deploys` | `boolean` | The executor deploys the HCA on first use, without a separate transaction. |
| `send` | `(request, context) => Promise` | Sends one execution and returns a reference to follow it. |
| `status` | `(reference, context) => Promise` | Reports where a sent execution is. |
| `quote` | `(request, context) => Promise` | Optional. Returns the fees to show on the plan before sending. |
Leave `send` out and the owner's wallet sends the executions, as `owner()` does. The two cases fund calls differently: without `send`, the owner's transaction carries the ETH the calls spend; with `send`, that ETH comes from the HCA's balance.
The `request` that `send` and `quote` receive carries the chain, the HCA address, the owner, whether the HCA is deployed, the calls to run in order, the session if there is one, and a description. `status` returns `{ status: "pending" }`, `{ status: "success", hashes }` or `{ status: "failed", reason, hashes? }`.
## Build a relayer executor [#build-a-relayer-executor]
**Example** (An Executor for Your Relayer)
```ts title="relayer.ts"
import { defineExecutor, hca } from "@ensforge/hca";
// Your relayer client: it takes a request and returns an id you can poll.
declare const api: {
relay(request: { hca: string; calls: readonly { to: string }[] }): Promise;
status(id: string): Promise<{ done: boolean; hash?: `0x${string}` }>;
};
const relayer = defineExecutor({
id: "relayer",
capabilities: { sessions: false, sponsorship: true, deploys: false },
send: async (request) => api.relay(request),
status: async (id) => {
const result = await api.status(id);
return result.done && result.hash !== undefined
? { status: "success", hashes: [result.hash] }
: { status: "pending" };
},
});
const via = hca({ executors: [relayer] });
```
- `capabilities.deploys: false` makes ensforge add a deployment call to the owner's setup step when the HCA does not exist yet.
- `send` returns the relayer's id, and `status` polls it until a transaction hash is known.
## Report failures that never landed [#report-failures-that-never-landed]
Return `{ status: "failed" }` without `hashes` for an execution that never reached the chain. The write can then send it again. Include `hashes` when a transaction was mined and reverted.
## Test with a double [#test-with-a-double]
A fake executor makes route tests fast and needs no service.
```ts title="fake-executor.ts"
import { defineExecutor } from "@ensforge/hca";
const fake = defineExecutor({
id: "fake",
capabilities: { sessions: false, sponsorship: false, deploys: true },
send: async () => "1",
status: async () => ({
status: "success",
hashes: ["0x0000000000000000000000000000000000000000000000000000000000000001"],
}),
});
```
## Executor rules ensforge follows [#executor-rules-ensforge-follows]
- `hca()` picks its executor when you call it: the first in the list, or with a `session` the first with `capabilities.sessions`. It throws [`HCA_EXECUTOR_UNSUPPORTED`](/docs/reference/errors/HCA_EXECUTOR_UNSUPPORTED) when none qualifies.
- When `quote` throws an `HcaError`, it passes through unchanged. Any other error from `quote` becomes [`HCA_EXECUTION_FAILED`](/docs/reference/errors/HCA_EXECUTION_FAILED).
- Every executor is a Promise interface, so you can wrap Promise SDKs without Effect.
See the [executor reference](/docs/reference/hca/executors) for the exact types.
# Rhinestone
> For the complete documentation index, see [llms.txt](https://ensforge.com/llms.txt).
Run HCA executions as Rhinestone intents, signed by the owner or run without a prompt with a session, and set a refund token.
Source: https://ensforge.com/docs/hca/rhinestone
`@ensforge/hca` is experimental for 1.0. The Rhinestone executor needs a Rhinestone SDK with
standalone HCA support, and ensforge only tests its wiring, not Rhinestone's orchestrator.
**Rhinestone** is an intent network. The `rhinestone()` [executor](/docs/reference/glossary#executor) sends [HCA](/docs/reference/glossary#hca) executions as Rhinestone intents, either signed by the owner or, with a [session](/docs/hca/sessions), signed by a session key without a wallet prompt. By the end of this page you will have an executor ready for both.
## Prerequisites [#prerequisites]
- A Rhinestone SDK instance that supports the standalone ENS HCA (account type `hca`, version `ens-standalone-1.1.0`). Stock `@rhinestone/sdk` 3.2.0 knows only an older HCA account type, so it needs a build with standalone HCA support, as the ENS app uses. Create the instance in your app. ensforge does not depend on the SDK.
- For sessions, the session key's signer (a viem account) and an authorized session. See [Sessions](/docs/hca/sessions).
## Create the executor [#create-the-executor]
| Option | Type | Default | Description |
| --------------- | --------------- | ------- | ------------------------------------------------------------------------------ |
| `sdk` | `RhinestoneSdk` | none | A Rhinestone SDK instance with standalone HCA support. |
| `sessionSigner` | `Account` | none | The session key's signer. Required for session executions. |
| `sponsored` | `boolean` | `true` | Sponsor executions. When `false`, fees are paid in the session's refund token. |
**Example** (A Prompt-Free Route)
```ts title="rhinestone.ts"
import { hca, rhinestone, type HcaSession, type RhinestoneSdk } from "@ensforge/hca";
import { generatePrivateKey, privateKeyToAccount } from "viem/accounts";
declare const sdk: RhinestoneSdk; // created by your app from Rhinestone's SDK
declare const session: HcaSession; // from ens.hca.authorizeSession
const sessionSigner = privateKeyToAccount(generatePrivateKey());
const via = hca({ executors: [rhinestone({ sdk, sessionSigner })], session });
```
Pass `via` to a write the session allows. See [Sessions](/docs/hca/sessions) for what that includes.
## Owner-signed executions [#owner-signed-executions]
Without a `session`, `rhinestone({ sdk })` sends owner-signed, sponsored intents.
```ts title="owner-signed.ts"
import { hca, rhinestone, type RhinestoneSdk } from "@ensforge/hca";
declare const sdk: RhinestoneSdk;
const via = hca({ executors: [rhinestone({ sdk })] });
```
## Pay fees in the refund token [#pay-fees-in-the-refund-token]
With `sponsored: false`, a session execution pays its fees in the session's refund token. The session sets the token and its ceilings when you authorize it.
```ts title="refund-token.ts"
import { rhinestone, type RhinestoneSdk } from "@ensforge/hca";
import type { Account } from "viem";
declare const sdk: RhinestoneSdk;
declare const sessionSigner: Account;
const executor = rhinestone({ sdk, sessionSigner, sponsored: false });
```
## What ensforge checks [#what-ensforge-checks]
- Before signing, ensforge checks every session call against the HCA policy. A call outside it fails with [`HCA_ACTION_NOT_ALLOWED`](/docs/reference/errors/HCA_ACTION_NOT_ALLOWED) and nothing is signed.
- The SDK account must derive the same HCA address as ensforge. Otherwise the executor fails with `HCA_SDK_UNSUPPORTED` before it signs anything.
- Status follows the intent until it has a fill transaction. An intent that is `FAILED` or `EXPIRED` reports as failed.
## Troubleshooting [#troubleshooting]
### `HCA_SDK_UNSUPPORTED` [#hca_sdk_unsupported]
The Rhinestone SDK derives a different address than the owner's HCA. Use an SDK release with standalone HCA support (`ens-standalone-1.1.0`). See [`HCA_SDK_UNSUPPORTED`](/docs/reference/errors/HCA_SDK_UNSUPPORTED).
### `HCA_EXECUTOR_UNSUPPORTED` [#hca_executor_unsupported]
The write has no wallet account, the chain has no HCA deployment, or a session execution has no `sessionSigner`. `hca()` also throws it when you pass a `session` and no executor in the list runs sessions. See [`HCA_EXECUTOR_UNSUPPORTED`](/docs/reference/errors/HCA_EXECUTOR_UNSUPPORTED).
# Your wallet
> For the complete documentation index, see [llms.txt](https://ensforge.com/llms.txt).
Run HCA executions as ordinary wallet transactions with the owner executor, the default, and combine it with other executors.
Source: https://ensforge.com/docs/hca/your-wallet
`@ensforge/hca` is experimental for 1.0. Its API can change in a minor release.
The `owner()` [executor](/docs/reference/glossary#executor) sends each [HCA](/docs/reference/glossary#hca) execution as an `executeByOwner` transaction from the owner's wallet. It is the default, needs no service, and the owner pays gas. By the end of this page you will know when it runs, how to combine it with other executors, and how to run arbitrary calls from the HCA.
## Use it by default [#use-it-by-default]
`hca()` with no options is the same as `hca({ executors: [owner()] })`.
**Example** (Running Calls From the HCA)
```ts title="execute.ts"
import { hca, hcaActions, owner } from "@ensforge/hca";
import { Ensforge, ensActions } from "@ensforge/sdk";
import { createPublicClient, createWalletClient, http, parseEther } from "viem";
import { privateKeyToAccount } from "viem/accounts";
import { sepolia } from "viem/chains";
const account = privateKeyToAccount(
"0x0123456789012345678901234567890123456789012345678901234567890123",
);
const ens = Ensforge.create({
publicClient: createPublicClient({ chain: sepolia, transport: http() }),
walletClient: createWalletClient({ account, chain: sepolia, transport: http() }),
})
.extend(ensActions())
.extend(hcaActions());
const { receipt } = await ens.hca.executeSync({
calls: [{ to: "0x000000000000000000000000000000000000dEaD", value: parseEther("0.001") }],
via: hca({ executors: [owner()] }),
});
```
[`hca.execute`](/docs/reference/hca/hca/execute) runs the calls in order, from the HCA, as one atomic execution. Every call succeeds or the whole execution reverts. With the owner executor, your wallet sends the ETH the calls spend along with the transaction, so this example pays 0.001 ETH from your wallet. Tokens the calls spend come from the HCA's balance.
## What the owner executor sends [#what-the-owner-executor-sends]
- With a wallet that supports atomic batches (EIP-5792), the owner's [steps](/docs/reference/glossary#step) share one [bundle](/docs/reference/glossary#bundle): the setup and the executions.
- Otherwise the wallet sends one transaction per step.
- The setup step, `hca-setup`, deploys the HCA with a factory call when it does not exist yet.
- Use `mode` and `maxBundleCalls` on the write to control bundling, as for any [write](/docs/sdk/send-a-transaction).
## Let the wallet sponsor gas [#let-the-wallet-sponsor-gas]
With a wallet that supports the EIP-5792 `paymasterService` capability, pass `paymaster` on the write. The wallet's [paymaster](/docs/reference/glossary#paymaster) service then pays for its transactions.
```ts title="sponsored-by-wallet.ts"
import { hca, hcaActions } from "@ensforge/hca";
import { Ensforge, ensActions } from "@ensforge/sdk";
import { createPublicClient, createWalletClient, http } from "viem";
import { privateKeyToAccount } from "viem/accounts";
import { sepolia } from "viem/chains";
const account = privateKeyToAccount(
"0x0123456789012345678901234567890123456789012345678901234567890123",
);
const ens = Ensforge.create({
publicClient: createPublicClient({ chain: sepolia, transport: http() }),
walletClient: createWalletClient({ account, chain: sepolia, transport: http() }),
})
.extend(ensActions())
.extend(hcaActions());
await ens.migration.migrate({
names: ["alice.eth"],
via: hca(),
paymaster: { url: "https://paymaster.example.com" }, // your EIP-5792 paymaster service
});
```
See [Pay gas for users](/docs/sdk/pay-gas-for-users) for the wallet side.
## Combine it with other executors [#combine-it-with-other-executors]
`executors` lists executors in order of preference. Without a session, ensforge uses the first one in the list. With a session, it uses the first one that runs sessions. ensforge picks the executor when you call `hca()`, and does not switch to another one when a send fails.
One list can serve both kinds of write: owner writes go through your wallet, and session writes through Rhinestone.
```ts title="executors.ts"
import { hca, owner, rhinestone, type HcaSession, type RhinestoneSdk } from "@ensforge/hca";
import type { Account } from "viem";
declare const sdk: RhinestoneSdk; // created by your app from Rhinestone's SDK
declare const sessionSigner: Account;
declare const session: HcaSession; // from ens.hca.authorizeSession
const executors = [owner(), rhinestone({ sdk, sessionSigner })];
const asOwner = hca({ executors }); // uses owner()
const withSession = hca({ executors, session }); // uses rhinestone()
```
The owner executor does not run sessions. See [Sessions](/docs/hca/sessions).
## Troubleshooting [#troubleshooting]
### `HCA_EXECUTOR_UNSUPPORTED` [#hca_executor_unsupported]
`hca()` throws it when you pass a `session` and no executor in the list runs sessions. Add `rhinestone()`. See [`HCA_EXECUTOR_UNSUPPORTED`](/docs/reference/errors/HCA_EXECUTOR_UNSUPPORTED).
### `HCA_NOT_VERIFIED` [#hca_not_verified]
The write has no signer, or the deployed HCA failed its checks. Pass an `account` or a wallet client, and read `details` for the failed checks. See [`HCA_NOT_VERIFIED`](/docs/reference/errors/HCA_NOT_VERIFIED).
# Deposits and gas
> For the complete documentation index, see [llms.txt](https://ensforge.com/llms.txt).
Fund an HCA, read and top up its EntryPoint deposit, and learn who pays gas for each executor, with or without a paymaster.
Source: https://ensforge.com/docs/hca/deposits-and-gas
`@ensforge/hca` is experimental for 1.0. Its API can change in a minor release.
An [HCA](/docs/reference/glossary#hca) is its own account, so it can hold funds and pay for things. By the end of this guide you will know who pays gas for each [executor](/docs/reference/glossary#executor), how to fund an HCA before it exists, and how to manage its ERC-4337 deposit.
## Who pays what [#who-pays-what]
Two costs exist. The **gas** pays for running the execution. The **spend** is what the calls themselves pay, such as ETH sent with a call or a registration fee in tokens.
| Executor | Pays the gas | Pays ETH the calls send | Pays tokens the calls spend |
| ---------------------------------------------- | ------------------------------------------------------------------------ | ---------------------------------------------- | --------------------------- |
| `owner()` | The owner's wallet. | The owner's wallet, sent with the transaction. | The HCA. |
| `bundler()` or `pimlico()` without a paymaster | The HCA. | The HCA. | The HCA. |
| `bundler()` or `pimlico()` with a paymaster | The [paymaster](/docs/reference/glossary#paymaster). | The HCA. | The HCA. |
| `rhinestone()` | Sponsored by default. With `sponsored: false`, a session's refund token. | The HCA. | The HCA. |
The HCA is `msg.sender` of the calls it runs, so tokens a call spends come from the HCA's balance, not the wallet's. A registration through `via: hca()` fails with [`INSUFFICIENT_TOKEN_BALANCE`](/docs/reference/errors/INSUFFICIENT_TOKEN_BALANCE) before it is sent when the HCA cannot pay. Fund the HCA first.
## Fund an HCA before it exists [#fund-an-hca-before-it-exists]
The address of an HCA is known before deployment. Predict it and send funds there.
**Example** (Reading the Address to Fund)
```ts title="fund.ts"
import { hcaActions } from "@ensforge/hca";
import { Ensforge, ensActions } from "@ensforge/sdk";
import { createPublicClient, createWalletClient, http, parseEther } from "viem";
import { privateKeyToAccount } from "viem/accounts";
import { sepolia } from "viem/chains";
const account = privateKeyToAccount(
"0x0123456789012345678901234567890123456789012345678901234567890123",
);
const publicClient = createPublicClient({ chain: sepolia, transport: http() });
const walletClient = createWalletClient({ account, chain: sepolia, transport: http() });
const ens = Ensforge.create({ publicClient, walletClient })
.extend(ensActions())
.extend(hcaActions());
const address = await ens.hca.predictAddress({});
await walletClient.sendTransaction({ to: address, value: parseEther("0.01") });
```
[`hca.predictAddress`](/docs/reference/hca/hca/predict-address) takes an optional `owner`, which defaults to the client's account. The address never changes, even after upgrades.
## Read and top up the EntryPoint deposit [#read-and-top-up-the-entrypoint-deposit]
With a bundler and no paymaster, the HCA pays for its UserOperations. The ERC-4337 **EntryPoint** keeps a deposit for each account and charges that gas to it. Read the deposit, and add to it ahead of time, with these actions.
| Action | What it does |
| ----------------------------------------------------------------- | ----------------------------------------------------------------- |
| [`hca.getDeposit`](/docs/reference/hca/hca/get-deposit) | Reads the deposit in wei. Takes an optional `address` or `owner`. |
| [`hca.addDeposit`](/docs/reference/hca/hca/add-deposit) | Adds `amount` wei from your wallet to the deposit. |
| [`hca.withdrawDeposit`](/docs/reference/hca/hca/withdraw-deposit) | Withdraws `amount` wei to `to`. |
**Example** (Topping Up and Withdrawing)
```ts title="deposit.ts"
import { hcaActions } from "@ensforge/hca";
import { Ensforge, ensActions } from "@ensforge/sdk";
import { createPublicClient, createWalletClient, http, parseEther } from "viem";
import { privateKeyToAccount } from "viem/accounts";
import { sepolia } from "viem/chains";
const account = privateKeyToAccount(
"0x0123456789012345678901234567890123456789012345678901234567890123",
);
const ens = Ensforge.create({
publicClient: createPublicClient({ chain: sepolia, transport: http() }),
walletClient: createWalletClient({ account, chain: sepolia, transport: http() }),
})
.extend(ensActions())
.extend(hcaActions());
const before = await ens.hca.getDeposit({});
await ens.hca.addDepositSync({ amount: parseEther("0.01") });
const after = await ens.hca.getDeposit({});
await ens.hca.withdrawDepositSync({ to: account.address, amount: after - before });
```
`withdrawDeposit` runs from the HCA through `executeByOwner`, because only the account may withdraw its deposit. Each action has a `…Sync` form that waits for the receipt and a form that resolves once the transaction is submitted. See [Ways to call actions](/docs/sdk/ways-to-call-actions).
## Check the cost before you send [#check-the-cost-before-you-send]
Every write has `prepare`, `simulate` and `estimateGas`. With an executor that quotes fees, the [plan](/docs/reference/glossary#plan) shows them in `plan.fees` before anything is sent. See [Preview before sending](/docs/sdk/preview-before-sending).
## Troubleshooting [#troubleshooting]
### `INSUFFICIENT_TOKEN_BALANCE` [#insufficient_token_balance]
The HCA does not hold enough of the payment token for the registration. Send the token to the HCA's address and run the write again. See [`INSUFFICIENT_TOKEN_BALANCE`](/docs/reference/errors/INSUFFICIENT_TOKEN_BALANCE).
### `HCA_BUNDLER_REJECTED` [#hca_bundler_rejected]
With a bundler and no paymaster, neither the HCA nor a paymaster could pay. Fund the HCA or its deposit, or add a paymaster. See [Bundlers](/docs/hca/bundlers).
# Sessions
> For the complete documentation index, see [llms.txt](https://ensforge.com/llms.txt).
Let an app register names and edit records from a user's HCA without a wallet prompt for each step, then check and revoke access.
Source: https://ensforge.com/docs/hca/sessions
`@ensforge/hca` is experimental for 1.0. Sessions run only through Rhinestone, and the signing
domain of session approvals can change when ENS deploys a dedicated one.
A **session** is an approval the [HCA](/docs/reference/glossary#hca)'s owner signs once so that a session key can act for the HCA within fixed limits. After it, an app registers names and edits records without a wallet prompt for each step. By the end of this guide you will have authorized a session, used it, checked it and revoked it.
## What a session may do [#what-a-session-may-do]
A session may do only these things:
- Register `.eth` names to the owner, with the session's [resolver](/docs/reference/glossary#resolver) and no subregistry.
- Deploy the session's resolver and set its [records](/docs/reference/glossary#record).
- Set the owner's [primary name](/docs/reference/glossary#primary-name).
- Approve token payments to the [registrar](/docs/reference/glossary#registrar) for a registration.
Nothing else is allowed. Renewals, transfers, [subnames](/docs/reference/glossary#subname), registry approvals, calls that send ETH and calls to other contracts all fail with [`HCA_ACTION_NOT_ALLOWED`](/docs/reference/errors/HCA_ACTION_NOT_ALLOWED). A session binds one resolver, the one it may deploy and edit.
## Prerequisites [#prerequisites]
- A client with a wallet and the HCA actions. See [Installation](/docs/hca/installation).
- A Rhinestone SDK with standalone HCA support and a session key. See [Rhinestone](/docs/hca/rhinestone).
- A resolver address for the session: the one resolver whose records the session may set. Any resolver that the session policy approves works: an existing resolver, or a PermissionedResolver proxy that the HCA deploys at that address through ENS's VerifiableFactory. There is no separate API for either. The HCA calls the resolver, so the HCA must be allowed to write records there.
## 1. Authorize the session [#1-authorize-the-session]
`authorizeSession` asks the owner for one EIP-712 signature, made for the HCA's predicted address. It sends no transaction and needs no deployed HCA, so you can authorize a session before the account exists. Whether the account accepts the session on its first use before it is deployed is not confirmed, so deploy the HCA with [`hca.deploy`](/docs/reference/hca/hca/deploy) before the session runs.
| Option | Type | Description |
| ------------ | --------- | ----------------------------------------------------------------------------------------------------- |
| `sessionKey` | `string` | Public address of the session key your app keeps. |
| `resolver` | `string` | The one resolver whose records the session may set. |
| `validUntil` | `number` | Unix seconds after which the session stops working. |
| `refund` | object | Refund ceilings for Rhinestone executions: `token`, `maxExchangeRate`, `maxGasOverhead`, `maxAmount`. |
| `account` | `Address` | The HCA's owner. Defaults to the client's account. |
Without `refund`, the token is the deployment's USDC and the ceilings are the ENS app's: $20k per ETH, 500k gas of overhead and 100 USDC per intent.
**Example** (Authorizing a Session for One Day)
```ts title="authorize.ts"
import { hcaActions } from "@ensforge/hca";
import { Ensforge, ensActions } from "@ensforge/sdk";
import { createPublicClient, createWalletClient, http } from "viem";
import { generatePrivateKey, privateKeyToAccount } from "viem/accounts";
import { sepolia } from "viem/chains";
const account = privateKeyToAccount(
"0x0123456789012345678901234567890123456789012345678901234567890123",
);
const ens = Ensforge.create({
publicClient: createPublicClient({ chain: sepolia, transport: http() }),
walletClient: createWalletClient({ account, chain: sepolia, transport: http() }),
})
.extend(ensActions())
.extend(hcaActions());
const sessionAccount = privateKeyToAccount(generatePrivateKey());
const resolver = "0x0000000000000000000000000000000000000001"; // placeholder: your session resolver
const session = await ens.hca.authorizeSession({
sessionKey: sessionAccount.address,
resolver,
validUntil: Math.floor(Date.now() / 1000) + 24 * 60 * 60,
});
```
The returned `HcaSession` holds no secret: it has the owner's signature and the session terms, but the key stays with your app. Store it where the app can find it. It contains `bigint` values, so use a serializer that supports them. If the owner declines, the action fails with [`USER_REJECTED`](/docs/reference/errors/USER_REJECTED).
## 2. Check what a session can do [#2-check-what-a-session-can-do]
[`hca.checkSessionCalls`](/docs/reference/hca/hca/check-session-calls) tests calls against the policy before anything is signed. It returns `true`, or throws `HCA_ACTION_NOT_ALLOWED` for the first call outside the policy. Use it to tell users up front what runs without prompts. `hca({ session })` runs the same check on its own.
```ts title="check.ts"
import { hcaActions, type HcaSession } from "@ensforge/hca";
import { Duration, Ensforge, ensActions } from "@ensforge/sdk";
import { createPublicClient, createWalletClient, http } from "viem";
import { privateKeyToAccount } from "viem/accounts";
import { sepolia } from "viem/chains";
const account = privateKeyToAccount(
"0x0123456789012345678901234567890123456789012345678901234567890123",
);
const ens = Ensforge.create({
publicClient: createPublicClient({ chain: sepolia, transport: http() }),
walletClient: createWalletClient({ account, chain: sepolia, transport: http() }),
})
.extend(ensActions())
.extend(hcaActions());
declare const session: HcaSession;
const plan = await ens.registration.register.prepare({
names: "my-new-name.eth", // placeholder
duration: Duration.years(1),
resolver: session.terms.resolver,
});
const allowed = await ens.hca.checkSessionCalls({ session, calls: plan.calls });
```
A registration that sets a `subregistry`, for example, is outside every session.
## 3. Run a write with the session [#3-run-a-write-with-the-session]
Pass the session to `hca()` with an executor that runs sessions. The write is signed by the session key and delivered through Rhinestone, with no wallet prompt.
**Example** (Registering a Name Without a Prompt)
```ts title="register-with-session.ts"
import { hca, hcaActions, rhinestone, type HcaSession, type RhinestoneSdk } from "@ensforge/hca";
import { Duration, Ensforge, ensActions } from "@ensforge/sdk";
import { createPublicClient, createWalletClient, http } from "viem";
import { privateKeyToAccount } from "viem/accounts";
import { sepolia } from "viem/chains";
const account = privateKeyToAccount(
"0x0123456789012345678901234567890123456789012345678901234567890123",
);
const ens = Ensforge.create({
publicClient: createPublicClient({ chain: sepolia, transport: http() }),
walletClient: createWalletClient({ account, chain: sepolia, transport: http() }),
})
.extend(ensActions())
.extend(hcaActions());
declare const sdk: RhinestoneSdk;
declare const session: HcaSession;
const sessionSigner = privateKeyToAccount(
"0x1123456789012345678901234567890123456789012345678901234567890123",
);
const via = hca({ executors: [rhinestone({ sdk, sessionSigner })], session });
await ens.registration.registerSync({
names: "my-new-name.eth", // placeholder
duration: Duration.years(1),
resolver: session.terms.resolver,
via,
});
```
A registration through a session must use the session's resolver, `session.terms.resolver`. The HCA pays for the registration, so it must hold the payment token. Without it, the registration fails with `INSUFFICIENT_TOKEN_BALANCE` before anything is sent. See [Deposits and gas](/docs/hca/deposits-and-gas).
To edit records, route `ens.record.set` the same way: `ens.record.set({ name, texts: { url }, via })`. The name's resolver must be the session's resolver.
## 4. Check that a session still works [#4-check-that-a-session-still-works]
[`hca.getSession`](/docs/reference/hca/hca/get-session) tells you whether a stored session can still be used, and why not.
```ts title="get-session.ts"
import { hcaActions, type HcaSession } from "@ensforge/hca";
import { Ensforge, ensActions } from "@ensforge/sdk";
import { createPublicClient, createWalletClient, http } from "viem";
import { privateKeyToAccount } from "viem/accounts";
import { sepolia } from "viem/chains";
const account = privateKeyToAccount(
"0x0123456789012345678901234567890123456789012345678901234567890123",
);
const ens = Ensforge.create({
publicClient: createPublicClient({ chain: sepolia, transport: http() }),
walletClient: createWalletClient({ account, chain: sepolia, transport: http() }),
})
.extend(ensActions())
.extend(hcaActions());
declare const session: HcaSession;
const { valid, problem } = await ens.hca.getSession({ session });
```
| `problem` | Meaning |
| ------------------ | ----------------------------------------------------------------------- |
| `"chain"` | The session was authorized for another chain. |
| `"expired"` | `validUntil` has passed, by the block's timestamp. |
| `"revoked"` | The owner called `revokeSessions`. |
| `"signing-domain"` | The deployment's session signing domain changed since the owner signed. |
When `problem` is not `null`, authorize a new session.
## 5. Revoke every session [#5-revoke-every-session]
`revokeSessions` bumps the HCA's session nonce, which invalidates every session approval at once. Use it when a session key may be lost or when you want to end all prompt-free access. It is the owner's own transaction and is never routed through the HCA. It fails with `HCA_NOT_VERIFIED` when the HCA is not deployed, because an undeployed HCA has no sessions.
```ts title="revoke.ts"
import { hcaActions } from "@ensforge/hca";
import { Ensforge, ensActions } from "@ensforge/sdk";
import { createPublicClient, createWalletClient, http } from "viem";
import { privateKeyToAccount } from "viem/accounts";
import { sepolia } from "viem/chains";
const account = privateKeyToAccount(
"0x0123456789012345678901234567890123456789012345678901234567890123",
);
const ens = Ensforge.create({
publicClient: createPublicClient({ chain: sepolia, transport: http() }),
walletClient: createWalletClient({ account, chain: sepolia, transport: http() }),
})
.extend(ensActions())
.extend(hcaActions());
await ens.hca.revokeSessionsSync({});
```
Afterwards `getSession` reports `"revoked"` for every stored session.
## Troubleshooting [#troubleshooting]
### `HCA_ACTION_NOT_ALLOWED` [#hca_action_not_allowed]
A call is outside the session policy. Send that call as the owner, without the session. See [`HCA_ACTION_NOT_ALLOWED`](/docs/reference/errors/HCA_ACTION_NOT_ALLOWED).
### `HCA_SESSION_INVALID` [#hca_session_invalid]
The session is expired, revoked, for another chain or signing domain, or for another owner. `authorizeSession` also throws it when the deployment has no default refund token and you pass no `refund.token`. Authorize a new session. See [`HCA_SESSION_INVALID`](/docs/reference/errors/HCA_SESSION_INVALID).
### `HCA_EXECUTOR_UNSUPPORTED` [#hca_executor_unsupported]
No executor in the list runs sessions. Add `rhinestone()`. See [`HCA_EXECUTOR_UNSUPPORTED`](/docs/reference/errors/HCA_EXECUTOR_UNSUPPORTED).
# Upgrades and governance
> For the complete documentation index, see [llms.txt](https://ensforge.com/llms.txt).
Check and run an HCA upgrade as its owner, and approve or revoke implementations and upgrade paths as a governance account.
Source: https://ensforge.com/docs/hca/upgrades-and-governance
`@ensforge/hca` is experimental for 1.0. The `hcaAdmin` actions are for governance accounts only,
and their API can change in a minor release.
An [HCA](/docs/reference/glossary#hca) runs an **implementation**: the contract code behind the account. Governance accounts decide which implementations new accounts may use and which ones existing accounts may upgrade to. By the end of this guide you will have checked an upgrade, run it, and, as a governance account, approved a new implementation.
## Upgrade your HCA (owners) [#upgrade-your-hca-owners]
An upgrade keeps the HCA's address and its sessions. Only the owner can run it, only on a deployed HCA, and only to an implementation that passes two checks:
1. The implementation is in the DAO's **upgrade set**, a list of allowed upgrade targets.
2. The new implementation accepts the account's current implementation as its predecessor. The new implementation's own code decides this.
### 1. Check the upgrade [#1-check-the-upgrade]
[`hca.getUpgrade`](/docs/reference/hca/hca/get-upgrade) reports each check, so you can tell the user which approval is missing.
```ts title="check-upgrade.ts"
import { hcaActions } from "@ensforge/hca";
import { Ensforge, ensActions } from "@ensforge/sdk";
import { createPublicClient, createWalletClient, http } from "viem";
import { privateKeyToAccount } from "viem/accounts";
import { sepolia } from "viem/chains";
const account = privateKeyToAccount(
"0x0123456789012345678901234567890123456789012345678901234567890123",
);
const ens = Ensforge.create({
publicClient: createPublicClient({ chain: sepolia, transport: http() }),
walletClient: createWalletClient({ account, chain: sepolia, transport: http() }),
})
.extend(ensActions())
.extend(hcaActions());
const implementation = "0x0000000000000000000000000000000000000001"; // placeholder: the new implementation
const { allowed, inUpgradeSet, predecessorAllowed } = await ens.hca.getUpgrade({
implementation,
});
```
| Field | Meaning |
| -------------------- | ----------------------------------------------------------------------------------- |
| `allowed` | `true` when both checks pass. |
| `current` | The account's current implementation, or `null` before deployment. |
| `inUpgradeSet` | The upgrade set includes the implementation. |
| `predecessorAllowed` | The implementation accepts `current` as its predecessor. `false` before deployment. |
### 2. Run the upgrade [#2-run-the-upgrade]
[`hca.upgrade`](/docs/reference/hca/hca/upgrade) is the owner's own transaction. It fails with [`HCA_UPGRADE_NOT_ALLOWED`](/docs/reference/errors/HCA_UPGRADE_NOT_ALLOWED) before sending when the HCA is not deployed or a check fails.
```ts title="upgrade.ts"
import { hcaActions } from "@ensforge/hca";
import { Ensforge, ensActions } from "@ensforge/sdk";
import { createPublicClient, createWalletClient, http } from "viem";
import { privateKeyToAccount } from "viem/accounts";
import { sepolia } from "viem/chains";
const account = privateKeyToAccount(
"0x0123456789012345678901234567890123456789012345678901234567890123",
);
const ens = Ensforge.create({
publicClient: createPublicClient({ chain: sepolia, transport: http() }),
walletClient: createWalletClient({ account, chain: sepolia, transport: http() }),
})
.extend(ensActions())
.extend(hcaActions());
const implementation = "0x0000000000000000000000000000000000000001"; // placeholder
await ens.hca.upgradeSync({ implementation });
```
After an upgrade, `ens.hca.get` returns the new `implementation`. The account's `initialImplementation`, which its address derives from, does not change.
## Inspect governance [#inspect-governance]
[`hcaAdmin.getGovernance`](/docs/reference/hca/hca-admin/get-governance) is a read anyone can run. Add `hcaAdminActions()` to the client first. See [Installation](/docs/hca/installation).
| Field | Meaning |
| -------------------- | ------------------------------------------------------------------------------------------------ |
| `factoryOwner` | The account that owns the HCA factory. |
| `upgradeSet` | The address of the upgrade set. |
| `deploymentApproved` | Whether the implementation may be used for new accounts. `null` when you pass no implementation. |
| `upgradeApproved` | Whether the upgrade set includes the implementation. `null` when you pass no implementation. |
## Approve implementations (governance accounts) [#approve-implementations-governance-accounts]
Each action is limited to the accounts in the table's second column. Each has a `…Sync` form that waits for the receipt.
| Action | Who | What it does |
| --------------------------------------------------------------------------------- | ------------------------ | ----------------------------------------------------------------------------- |
| [`setDeploymentApproval`](/docs/reference/hca/hca-admin/set-deployment-approval) | Factory owner | Approves or revokes an implementation for new HCA deployments. |
| [`setUpgradeApproval`](/docs/reference/hca/hca-admin/set-upgrade-approval) | Upgrade-set role holders | Approves or revokes an implementation in the upgrade set. |
| [`grantUpgradeSetRoles`](/docs/reference/hca/hca-admin/grant-upgrade-set-roles) | Role admins | Grants root roles on the upgrade set to `grantee` (`roles` is a bitmap). |
| [`revokeUpgradeSetRoles`](/docs/reference/hca/hca-admin/revoke-upgrade-set-roles) | Role admins | Revokes root roles on the upgrade set from `grantee`. |
| [`transferGovernance`](/docs/reference/hca/hca-admin/transfer-governance) | Factory owner | Transfers ownership of the factory to `newOwner`, for example a DAO timelock. |
| [`renounceGovernance`](/docs/reference/hca/hca-admin/renounce-governance) | Factory owner | Gives up factory ownership. |
**Example** (Allowing an Upgrade Target)
```ts title="approve-upgrade.ts"
import { hcaAdminActions } from "@ensforge/hca";
import { Ensforge, ensActions } from "@ensforge/sdk";
import { createPublicClient, createWalletClient, http } from "viem";
import { privateKeyToAccount } from "viem/accounts";
import { sepolia } from "viem/chains";
const account = privateKeyToAccount(
"0x0123456789012345678901234567890123456789012345678901234567890123",
);
const ens = Ensforge.create({
publicClient: createPublicClient({ chain: sepolia, transport: http() }),
walletClient: createWalletClient({ account, chain: sepolia, transport: http() }),
})
.extend(ensActions())
.extend(hcaAdminActions());
const implementation = "0x0000000000000000000000000000000000000001"; // placeholder
await ens.hcaAdmin.setUpgradeApprovalSync({ implementation, approved: true });
const governance = await ens.hcaAdmin.getGovernance({ implementation });
```
`renounceGovernance` freezes the factory's implementation approvals. After it, nobody can add or
retire an implementation for new HCAs. Use it only to make the set of deployable implementations
permanent.
## Troubleshooting [#troubleshooting]
### `HCA_UPGRADE_NOT_ALLOWED` [#hca_upgrade_not_allowed]
The HCA is not deployed, the upgrade set does not include the implementation, or the implementation does not accept the current one as predecessor. Run `getUpgrade` to see which. See [`HCA_UPGRADE_NOT_ALLOWED`](/docs/reference/errors/HCA_UPGRADE_NOT_ALLOWED).
### `untrusted-implementation` in `problems` [#untrusted-implementation-in-problems]
The account runs an implementation that is neither the factory's first one nor in the upgrade set. ensforge refuses to route writes through such an account. See [How it works](/docs/hca/how-it-works#how-ensforge-trusts-an-account).
# How it works
> For the complete documentation index, see [llms.txt](https://ensforge.com/llms.txt).
Learn what a hosted contract account is, how ensforge runs a write from it, how it checks the account, and who controls it.
Source: https://ensforge.com/docs/hca/how-it-works
`@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 [#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`](/docs/reference/hca/hca/predict-address)). 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`](/docs/reference/hca/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`](/docs/reference/errors/TRANSFER_DISALLOWED).
## How a write runs from the account [#how-a-write-runs-from-the-account]
A normal write sends transactions from your wallet. A write with `via: hca()` sends a different [plan](/docs/reference/glossary#plan): ensforge wraps the calls in one `executeByOwner` call on your HCA, and the HCA calls the ENS contracts. `hca()` is a [route](/docs/reference/glossary#route).
```mermaid
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](/docs/hca/your-wallet) and [Custom executors](/docs/hca/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](/docs/reference/glossary#step) 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](/docs/reference/glossary#name-wrapper). The plan warns with `HCA_WRAPPER_APPROVAL`. Revoke it with [`approval.setOperator`](/docs/reference/sdk/approval/set-operator) once the write is done.
## What the HCA can do [#what-the-hca-can-do]
The HCA is `msg.sender` of the calls it runs, so it needs authority over what they touch. [Migration](/docs/reference/glossary#migration) and registration plan for it, and renewals work because anyone may renew. Other writes need the HCA to hold the [roles](/docs/reference/glossary#role) they use, and fail at simulation otherwise. See [Who can change a name](/docs/sdk/who-can-change-a-name).
ensforge never routes a write through an HCA unless you pass `via`.
## How ensforge trusts an account [#how-ensforge-trusts-an-account]
Before it uses a deployed HCA, ensforge checks it. [`hca.get`](/docs/reference/hca/hca/get) returns the failed checks in `problems`. [`hca.verify`](/docs/reference/hca/hca/verify) throws [`HCA_NOT_VERIFIED`](/docs/reference/errors/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`](/docs/sdk/errors-explained) returns a title, message and action you can show as they are.
## Read the account [#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`](/docs/sdk/look-up-many-at-once) 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 [#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](/docs/hca/upgrades-and-governance).
## When it is not available [#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](/docs/hca/sessions).
# Quick start
> For the complete documentation index, see [llms.txt](https://ensforge.com/llms.txt).
Send a write through your hosted contract account with the hca() route, then read the account back, in a few minutes on Sepolia.
Source: https://ensforge.com/docs/hca
`@ensforge/hca` is experimental for 1.0. Its API can change in a minor release.
By the end of this page you will have moved two names to ENSv2 ([migration](/docs/reference/glossary#migration)) in one execution of your [HCA](/docs/reference/glossary#hca), and read the account that ran it. Install the package first: [Installation](/docs/hca/installation).
## 1. Create the client [#1-create-the-client]
Add `hcaActions()` to a client that has a wallet. The example uses Sepolia.
```ts title="client.ts"
import { hcaActions } from "@ensforge/hca";
import { Ensforge, ensActions } from "@ensforge/sdk";
import { createPublicClient, createWalletClient, http } from "viem";
import { privateKeyToAccount } from "viem/accounts";
import { sepolia } from "viem/chains";
const account = privateKeyToAccount(
"0x0123456789012345678901234567890123456789012345678901234567890123",
);
export const ens = Ensforge.create({
publicClient: createPublicClient({ chain: sepolia, transport: http() }),
walletClient: createWalletClient({ account, chain: sepolia, transport: http() }),
})
.extend(ensActions())
.extend(hcaActions());
```
- Replace the placeholder key with your signer. Never commit a real key.
- `hcaActions()` adds the `ens.hca` actions, such as `ens.hca.get`.
## 2. Send a write through the HCA [#2-send-a-write-through-the-hca]
Pass `via: hca()` to any write. `hca()` is a [route](/docs/reference/glossary#route): it rewrites the write's [plan](/docs/reference/glossary#plan) so that the HCA runs the calls. ensforge never selects it on its own, so the user agrees to it through the code you write.
**Example** (Migrating Two Names Through the HCA)
```ts title="migrate.ts"
import { hca, hcaActions } from "@ensforge/hca";
import { Ensforge, ensActions } from "@ensforge/sdk";
import { createPublicClient, createWalletClient, http } from "viem";
import { privateKeyToAccount } from "viem/accounts";
import { sepolia } from "viem/chains";
const account = privateKeyToAccount(
"0x0123456789012345678901234567890123456789012345678901234567890123",
);
const ens = Ensforge.create({
publicClient: createPublicClient({ chain: sepolia, transport: http() }),
walletClient: createWalletClient({ account, chain: sepolia, transport: http() }),
})
.extend(ensActions())
.extend(hcaActions());
const result = await ens.migration.migrateSync({
names: ["alice.eth", "bob.eth"], // placeholders: ENSv1 .eth names your wallet owns
via: hca(),
});
console.log(result.plan.steps.map((step) => step.id));
```
Replace the two names with names your wallet owns that are not on ENSv2 yet. With the default [executor](/docs/reference/glossary#executor), your wallet sends every transaction:
1. A first [step](/docs/reference/glossary#step) named `hca-setup` deploys the HCA, when it does not exist yet, and approves it to move your names.
2. Both migrations run as one atomic `executeByOwner` call, so either every name moves or none does.
With an EIP-5792 wallet, the owner's steps share one [bundle](/docs/reference/glossary#bundle). See [Your wallet](/docs/hca/your-wallet).
## 3. Read the account [#3-read-the-account]
`ens.hca.get` reads the HCA's address, owner, implementation and any problems. It works before deployment, using the predicted address.
```ts title="get-account.ts"
import { hcaActions } from "@ensforge/hca";
import { Ensforge, ensActions } from "@ensforge/sdk";
import { createPublicClient, createWalletClient, http } from "viem";
import { privateKeyToAccount } from "viem/accounts";
import { sepolia } from "viem/chains";
const account = privateKeyToAccount(
"0x0123456789012345678901234567890123456789012345678901234567890123",
);
const ens = Ensforge.create({
publicClient: createPublicClient({ chain: sepolia, transport: http() }),
walletClient: createWalletClient({ account, chain: sepolia, transport: http() }),
})
.extend(ensActions())
.extend(hcaActions());
const hcaAccount = await ens.hca.get({});
```
`problems` is empty for an account that is safe to use. See [`hca.get`](/docs/reference/hca/hca/get).
Through `via: hca()` the HCA, not your wallet, calls the contracts. Migration, registration and
renewal work through it. Other writes, such as records or transfers, work only where the HCA holds
the [roles](/docs/reference/glossary#role) they need, and fail at simulation otherwise.
## Learn more [#learn-more]
What an HCA is and why a write runs from it.
Run writes gaslessly with Pimlico or any ERC-4337 bundler.
Register names and edit records without wallet prompts.
# Installation
> For the complete documentation index, see [llms.txt](https://ensforge.com/llms.txt).
Install @ensforge/hca next to the SDK, then add the HCA actions to your client so that ens.hca and the hca() route are available.
Source: https://ensforge.com/docs/hca/installation
`@ensforge/hca` is experimental for 1.0. Its API can change in a minor release, and the bundler
and Rhinestone paths have no production proof yet. Pin the version you test.
`@ensforge/hca` adds hosted contract accounts ([HCA](/docs/reference/glossary#hca)) to the ensforge client. An HCA is a smart account that ENS hosts for a wallet. See [How it works](/docs/hca/how-it-works).
## Requirements [#requirements]
- Node.js 20.19 or later.
- `@ensforge/sdk`, `effect` (version 4.1.4 or later) and `viem` (version 2.57 or later). The package lists `effect` and `viem` as peer dependencies.
- A chain with an HCA deployment: Ethereum mainnet or Sepolia. Other chains fail with [`HCA_UNAVAILABLE`](/docs/reference/errors/HCA_UNAVAILABLE) unless you [define a deployment](/docs/contracts/custom-deployments) that has an `hca` group.
## 1. Install the packages [#1-install-the-packages]
```package-install
@ensforge/hca @ensforge/sdk effect viem
```
## 2. Add the actions to the client [#2-add-the-actions-to-the-client]
`hcaActions()` adds the `ens.hca` actions. `hcaAdminActions()` adds `ens.hcaAdmin`, which only governance accounts need. See [Upgrades and governance](/docs/hca/upgrades-and-governance).
**Example** (A Client With HCA Actions)
```ts title="client.ts"
import { hcaActions, hcaAdminActions } from "@ensforge/hca";
import { Ensforge, ensActions } from "@ensforge/sdk";
import { createPublicClient, createWalletClient, http } from "viem";
import { privateKeyToAccount } from "viem/accounts";
import { sepolia } from "viem/chains";
const account = privateKeyToAccount(
"0x0123456789012345678901234567890123456789012345678901234567890123",
);
const ens = Ensforge.create({
publicClient: createPublicClient({ chain: sepolia, transport: http() }),
walletClient: createWalletClient({ account, chain: sepolia, transport: http() }),
})
.extend(ensActions())
.extend(hcaActions())
.extend(hcaAdminActions());
```
- Replace the placeholder key with your signer. Never commit a real key.
- Writes through an HCA need a wallet client, because the HCA's owner signs or sends them.
## Use the Effect API [#use-the-effect-api]
The same actions run in Effect programs: import `Actions` from `@ensforge/hca/effect`. See [The Effect API](/docs/sdk/effect-api).
## Troubleshooting [#troubleshooting]
### `HCA_UNAVAILABLE` [#hca_unavailable]
The client's chain has no HCA deployment. Use mainnet or Sepolia, or pass a deployment that has an `hca` group. See [`HCA_UNAVAILABLE`](/docs/reference/errors/HCA_UNAVAILABLE).
# Atoms
> For the complete documentation index, see [llms.txt](https://ensforge.com/llms.txt).
Compose ENS reads and writes with your own Effect Atom state outside the hooks, and invalidate cached reads when a name changes.
Source: https://ensforge.com/docs/react/atoms
Every hook reads atoms. The atom layer lets you build your own derived state from the same reads, read ENS outside components, or send writes from a store.
Everything in `@ensforge/react/atoms` is marked `unstable`, except the `Action`, `ActionOptions`,
`ActionValue`, `ActionError`, `Freshness` and `PageAction` types. It is built on Effect's
`effect/reactivity` Atom module, which is unstable upstream. Names and shapes can change in a
minor release. The hooks are stable.
## Prerequisites [#prerequisites]
- [`@ensforge/react` installed](/docs/react/installation).
- Some familiarity with Effect Atom: an atom holds a value, and `Atom.make((get) => ...)` derives one from others.
## Read ENS in an atom [#read-ens-in-an-atom]
`ensAtom(client, action, options, freshness?)` returns the atom of one read. It holds an `AsyncResult`. It is cached per client (chain, account and indexer), action and options, so it shares its request and result with `useRead` for that read.
**Example** (Composing Reads)
```ts title="profile-atom.ts"
import { Actions, Ensforge } from "@ensforge/sdk";
import { ensAtom } from "@ensforge/react/atoms";
import { Atom } from "effect/reactivity";
import { createPublicClient, http } from "viem";
import { mainnet } from "viem/chains";
const ens = Ensforge.create({
publicClient: createPublicClient({ chain: mainnet, transport: http() }),
});
export const profile = Atom.make((get) => ({
address: get(ensAtom(ens, Actions.record.getAddress, { name: "nick.eth" })),
avatar: get(ensAtom(ens, Actions.record.getAvatar, { name: "nick.eth" })),
}));
```
Each field is an `AsyncResult`: initial, success or failure, with a `waiting` flag. Use `AsyncResult.match` to read it. The atom refreshes when a write touches `nick.eth`, like the hooks.
## Read atoms outside components [#read-atoms-outside-components]
An atom registry runs atoms anywhere. Mount an atom to keep it alive, then read its result.
**Example** (Reading With A Registry)
```ts title="registry.ts"
import { Actions, Ensforge } from "@ensforge/sdk";
import { ensAtom } from "@ensforge/react/atoms";
import { AtomRegistry } from "effect/reactivity";
import { createPublicClient, http } from "viem";
import { mainnet } from "viem/chains";
const ens = Ensforge.create({
publicClient: createPublicClient({ chain: mainnet, transport: http() }),
});
const registry = AtomRegistry.make();
const owner = ensAtom(ens, Actions.name.get, { name: "nick.eth" });
registry.mount(owner);
registry.subscribe(owner, (result) => console.log(result._tag));
```
## Send a write from an atom [#send-a-write-from-an-atom]
`ensWriteAtom(client, action)` returns three parts: `run`, `steps` and `send`. Each call makes new atoms, so every form or button has its own state. The `useWrite` hook keeps one per component.
| Part | What it is |
| --------------- | ----------------------------------------------------------------------------------------------------- |
| `run` | The latest write's `AsyncResult`. Set it to the write's options to send, or to `Atom.Reset` to clear. |
| `steps` | The latest write's plan events: `waiting`, `submitted`, `confirmed`, `failed`. |
| `send(options)` | An Effect that sends a write and ends with its own result, even when later writes start. |
**Example** (Sending A Write)
```ts title="write-atom.ts"
import { Actions, Ensforge } from "@ensforge/sdk";
import { ensWriteAtom } from "@ensforge/react/atoms";
import { AtomRegistry } from "effect/reactivity";
import { createPublicClient, http } from "viem";
import { sepolia } from "viem/chains";
const ens = Ensforge.create({
publicClient: createPublicClient({ chain: sepolia, transport: http() }),
});
const registry = AtomRegistry.make();
const setRecords = ensWriteAtom(ens, Actions.record.set);
registry.mount(setRecords.run);
registry.set(setRecords.run, { name: "alice.eth", texts: { url: "https://alice.xyz" } });
```
Mount `run` while you write through it. Writes never interrupt each other, and resetting interrupts none, because a sent transaction cannot be taken back. After a write, the reads it touched refresh, as with the hooks. See [Caching and refreshing](/docs/react/caching-and-refreshing#refresh-after-a-write).
## Page through a list [#page-through-a-list]
`ensPagesAtom(client, pageAction, options)` returns the atom of an [indexer](/docs/reference/glossary#indexer) list. Its value holds every page loaded so far, and setting it loads the next page.
**Example** (Loading Subnames Page By Page)
```ts title="pages-atom.ts"
import { Actions, Ensforge } from "@ensforge/sdk";
import { goldsky } from "@ensforge/sdk/indexer";
import { ensPagesAtom } from "@ensforge/react/atoms";
import { AtomRegistry } from "effect/reactivity";
import { createPublicClient, http } from "viem";
import { mainnet } from "viem/chains";
const ens = Ensforge.create({
publicClient: createPublicClient({ chain: mainnet, transport: http() }),
indexer: goldsky(),
});
const registry = AtomRegistry.make();
const subnames = ensPagesAtom(ens, Actions.indexer.getSubnames, { name: "ens.eth" });
registry.mount(subnames);
registry.set(subnames, undefined); // load the next page
```
## Refresh and key helpers [#refresh-and-key-helpers]
| Export | Use |
| ---------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `invalidate(registry, client, { names, addresses })` | Refetches every cached read of those names and addresses, chain and indexer reads alike. Use it after a change ensforge did not make. |
| `readKey(client, action, options)` | The key a read is cached, hydrated and invalidated under: `ensforge:::::`. |
| `optionsKey(options)` | A stable string for an action's options: keys sorted, `undefined`, callbacks and `signal` dropped, `name`, `names` and `parent` normalised, addresses lowercased, bigints written as `123n`. |
The key names the client by what changes its answer, not by object, so it is the same on the server and in the browser. That is how a prefetched value finds its hook.
For hooks, see [Read data](/docs/react/read-data). For adding your own actions, see [Use your own actions](/docs/react/custom-actions).
# Use your own actions
> For the complete documentation index, see [llms.txt](https://ensforge.com/llms.txt).
Run your own action, or an Effect action, through useRead and useWrite so it is cached, shared and refreshed like built-in ones.
Source: https://ensforge.com/docs/react/custom-actions
`useRead` and `useWrite` accept any action: a function of a client and options with a unique `path`. Build one to combine several reads into one, or use an action from `@ensforge/sdk/effect` as it is.
## What an action is [#what-an-action-is]
An action is `(client, options) => Promise | Effect`, with a `path` string property. ensforge uses `path` in the cache key, so give each action its own. The built-in ones use `record.getAddress` and similar. Pick a prefix that is yours, such as `app.getProfile`.
The hook adds an `AbortSignal` as `options.signal`. Pass it on, so a refresh or an unmount cancels the requests.
## Combine reads into one action [#combine-reads-into-one-action]
**Example** (A Profile Read)
```tsx title="profile-action.tsx"
import { useRead } from "@ensforge/react";
import { Actions, type Ensforge } from "@ensforge/sdk";
const getProfile = Object.assign(
async (client: Ensforge.Client, options: { name: string; signal?: AbortSignal }) => {
const [address, url] = await Promise.all([
Actions.record.getAddress(client, options),
Actions.record.getText(client, { ...options, key: "url" }),
]);
return { address, url };
},
{ path: "app.getProfile" },
);
export function Profile({ name }: { name: string }) {
const { data } = useRead(getProfile, { name });
return (
{data?.address} {data?.url}
);
}
```
Value and error types come from the action. A Promise action fails with whatever it throws; ensforge's own actions throw typed errors. See [Handle errors](/docs/sdk/handle-errors).
## Refresh after writes [#refresh-after-writes]
Writes refresh the reads whose options name something the write touched. ensforge looks for these option fields:
| Kind | Fields |
| -------- | ----------------------------------------------------------------------------------------------- |
| Names | `name`, `names`, `parent` |
| Accounts | `address`, `account`, `owner`, `newOwner`, `to`, `recipient`, `operator`, `delegate`, `grantee` |
Name your options with those fields, as `getProfile` does with `name`, and your read refetches after a write to that name. A read whose options use other field names is not refreshed by writes. Call `refresh()` or `invalidate` for it. See [Caching and refreshing](/docs/react/caching-and-refreshing).
A read is refreshed too when its returned value mentions a touched name or account, such as a [primary name](/docs/reference/glossary#primary-name).
## Use an Effect action [#use-an-effect-action]
An action from `@ensforge/sdk/effect` works as it is. Its error type is the Effect error channel instead of the general ensforge error.
**Example** (Reading With An Effect Action)
```tsx title="Role.tsx"
import type { Address } from "viem";
import { useRead } from "@ensforge/react";
import { Actions } from "@ensforge/sdk/effect";
export function Role({ name, account }: { name: string; account: Address }) {
const { data } = useRead(Actions.role.get, { name, account, target: "registry" });
return {data?.toString()};
}
```
For how the Effect API relates to the Promise one, see [The Effect API](/docs/sdk/effect-api).
## Write with a custom action [#write-with-a-custom-action]
`useWrite(action)` takes your own write the same way. The write refreshes reads only when its result is a [plan](/docs/reference/glossary#plan) result, which carries `hashes`. A custom write that returns something else never triggers a refresh, so call `invalidate` after it.
For the atoms behind both hooks, see [Atoms](/docs/react/atoms).
# Next.js App Router
> For the complete documentation index, see [llms.txt](https://ensforge.com/llms.txt).
Prefetch ENS reads in a Next.js server component and hand them to the browser with HydrationBoundary, with streaming for slow reads.
Source: https://ensforge.com/docs/react/nextjs-app-router
In the App Router, a server component prefetches the reads a page shows first. The browser then renders them immediately and revalidates them.
`prefetch`, `dehydrate` and `HydrationBoundary` are marked `unstable`. Their names and shapes can
change in a minor release.
## How it works [#how-it-works]
Reads that you did not prefetch render as loading on the server and run in the browser, so a server render never fans out RPC calls. Prefetched reads travel as plain JSON (bigints and bytes are tagged).
```mermaid
flowchart LR
S[Server component] -->|prefetch| R[Request registry]
R -->|dehydrate| H[HydrationBoundary]
H -->|state in the page| B[Browser registry]
B -->|hooks read it| C[Client components]
```
## 1. Share one client [#1-share-one-client]
Put the client in a module both the server component and the provider import.
**Example** (A Shared Client)
```ts title="lib/ens.ts"
import { createPublicClient, http } from "viem";
import { mainnet } from "viem/chains";
import { Ensforge } from "@ensforge/sdk";
export const ens = Ensforge.create({
publicClient: createPublicClient({ chain: mainnet, transport: http() }),
});
```
## 2. Provide the client in a client component [#2-provide-the-client-in-a-client-component]
`EnsforgeProvider` and the hooks are client components. A server component cannot pass the client object to them as a prop, so render the provider in a `"use client"` file that imports the client.
**Example** (The Providers File)
```tsx no-check title="app/providers.tsx"
"use client";
import type { ReactNode } from "react";
import { EnsforgeProvider } from "@ensforge/react";
import { ens } from "../lib/ens";
export function Providers({ children }: { children: ReactNode }) {
return {children};
}
```
```tsx no-check title="app/layout.tsx"
import type { ReactNode } from "react";
import { Providers } from "./providers";
export default function RootLayout({ children }: { children: ReactNode }) {
return (
{children}
);
}
```
## 3. Prefetch in the page [#3-prefetch-in-the-page]
Create a new registry for each request, `prefetch` the reads, and pass `dehydrate(registry)` to `HydrationBoundary`. Prefetch with the same action and options the component reads with.
**Example** (A Name Page)
```tsx no-check title="app/[name]/page.tsx"
import { AtomRegistry } from "effect/reactivity";
import { HydrationBoundary } from "@ensforge/react";
import { dehydrate, prefetch } from "@ensforge/react/server";
import { Actions } from "@ensforge/sdk";
import { ens } from "../../lib/ens";
import { Profile } from "./profile";
export default async function Page({ params }: { params: Promise<{ name: string }> }) {
const { name } = await params;
const registry = AtomRegistry.make();
await prefetch(registry, ens, Actions.name.get, { name });
return (
);
}
```
```tsx title="app/[name]/profile.tsx"
"use client";
import { useName } from "@ensforge/react";
export function Profile({ name }: { name: string }) {
const { data } = useName({ name });
return
{data?.owner}
;
}
```
- `prefetch` resolves once the read settles. A failed read is not sent, so the browser retries it.
- `useName` reads the same action and options, so it finds the prefetched value and does not fetch again.
- Without `staleTime`, a hydrated value revalidates once it is 30 seconds old.
## Stream slow reads [#stream-slow-reads]
Do not await `prefetch` to stream. Call `dehydrate(registry, { streaming: true })`: reads that are still loading reach the browser as promises that resolve there, so the fast parts of the page appear first.
Streaming puts real Promises in the state, so the state must cross to the browser through a serializer that streams promises. React Server Components do this when a server component passes the state to `HydrationBoundary`. A serializer that writes plain JSON drops the promise without an error, and the browser then fetches the read itself.
**Example** (Streaming A Subname List)
```tsx no-check title="app/[name]/page.tsx"
import { Suspense } from "react";
import { AtomRegistry } from "effect/reactivity";
import { HydrationBoundary } from "@ensforge/react";
import { dehydrate, prefetch } from "@ensforge/react/server";
import { Actions } from "@ensforge/sdk";
import { ens } from "../../lib/ens";
import { Subnames } from "./subnames";
export default async function Page({ params }: { params: Promise<{ name: string }> }) {
const { name } = await params;
const registry = AtomRegistry.make();
void prefetch(registry, ens, Actions.indexer.getSubnames, { name });
return (
Loading subnames...
}>
);
}
```
```tsx title="app/[name]/subnames.tsx"
"use client";
import { useSuspenseRead } from "@ensforge/react";
import { Actions } from "@ensforge/sdk";
export function Subnames({ name }: { name: string }) {
const { data } = useSuspenseRead(Actions.indexer.getSubnames, { name });
return (
{data.items.map((item) => (
{item.name}
))}
);
}
```
Read a streamed value with [`useSuspenseRead`](/docs/react/suspense) inside ``: the fallback shows until the promise resolves. Paged hooks such as `useSubnames` fetch in the browser and do not read a prefetched value.
## Troubleshooting [#troubleshooting]
### The browser fetches again after prefetching [#the-browser-fetches-again-after-prefetching]
The read in the component differs from the prefetched one. The action and the options must match. Names are compared [normalised](/docs/reference/glossary#normalisation), so `Nick.eth` and `nick.eth` match.
### Next.js says a function cannot be passed to a client component [#nextjs-says-a-function-cannot-be-passed-to-a-client-component]
You passed the client from a server component. Import it in the `"use client"` providers file instead.
See [Caching and refreshing](/docs/react/caching-and-refreshing) for how hydrated reads revalidate, and the [reference for `prefetch`](/docs/reference/react/server) for every option.
# Next.js Pages Router
> For the complete documentation index, see [llms.txt](https://ensforge.com/llms.txt).
Prefetch ENS reads in getServerSideProps or getStaticProps and hydrate them in the page, so names render without a loading state.
Source: https://ensforge.com/docs/react/nextjs-pages-router
In the Pages Router, prefetch the reads in `getServerSideProps` or `getStaticProps`, return the state as a prop, and render `HydrationBoundary` in the page. `getStaticProps` also works for a static export.
`prefetch`, `dehydrate` and `HydrationBoundary` are marked `unstable`. Their names and shapes can
change in a minor release.
## 1. Provide the client in `_app` [#1-provide-the-client-in-_app]
Create the client once in a shared module and render the provider in `_app`. Pages Router components are all client-capable, so no `"use client"` is needed.
**Example** (A Shared Client And The App Component)
```ts title="lib/ens.ts"
import { createPublicClient, http } from "viem";
import { mainnet } from "viem/chains";
import { Ensforge } from "@ensforge/sdk";
export const ens = Ensforge.create({
publicClient: createPublicClient({ chain: mainnet, transport: http() }),
});
```
```tsx no-check title="pages/_app.tsx"
import type { AppProps } from "next/app";
import { EnsforgeProvider } from "@ensforge/react";
import { ens } from "../lib/ens";
export default function App({ Component, pageProps }: AppProps) {
return (
);
}
```
## 2. Prefetch on the server [#2-prefetch-on-the-server]
Create a new registry for each request. The values are plain JSON (bigints and bytes are tagged). Pass `dehydrate(registry)` straight into the page props.
**Example** (A Name Page)
```tsx no-check title="pages/[name].tsx"
import type { GetServerSideProps } from "next";
import { AtomRegistry } from "effect/reactivity";
import { HydrationBoundary, useName } from "@ensforge/react";
import { dehydrate, prefetch } from "@ensforge/react/server";
import { Actions } from "@ensforge/sdk";
import { ens } from "../lib/ens";
type Props = { name: string; state: ReturnType };
export const getServerSideProps: GetServerSideProps = async ({ params }) => {
const name = String(params?.name);
const registry = AtomRegistry.make();
await prefetch(registry, ens, Actions.name.get, { name });
return { props: { name, state: dehydrate(registry) } };
};
function Profile({ name }: { name: string }) {
const { data } = useName({ name });
return
{data?.owner}
;
}
export default function Page({ name, state }: Props) {
return (
);
}
```
- `useName` reads the same action and options as `prefetch`, so it uses the prefetched value.
- `dehydrate` returns plain JSON, so Next.js can serialize it as props without a conversion.
- A failed read is not sent, so the browser retries it.
## Static pages [#static-pages]
Use the same `prefetch` and `dehydrate`, in `getStaticProps`. The state is baked into the page at build time. Set `staleTime` on the hooks for data that changes. Without it, a hydrated value revalidates once it is 30 seconds old.
For the App Router version with streaming, see [Next.js App Router](/docs/react/nextjs-app-router).
# React Router
> For the complete documentation index, see [llms.txt](https://ensforge.com/llms.txt).
Prefetch ENS reads in a React Router or Remix loader and hydrate them in the route component, so names render without a loading state.
Source: https://ensforge.com/docs/react/react-router
In React Router (framework mode) and Remix, prefetch the reads in a route `loader`, return the state, and render `HydrationBoundary` in the route component.
`prefetch`, `dehydrate` and `HydrationBoundary` are marked `unstable`. Their names and shapes can
change in a minor release.
## 1. Provide the client in the root [#1-provide-the-client-in-the-root]
Create the client in a shared module and render the provider in `root.tsx`, around the ``.
**Example** (The Root Route)
```tsx no-check title="app/root.tsx"
import { Outlet } from "react-router";
import { EnsforgeProvider } from "@ensforge/react";
import { ens } from "./lib/ens";
export default function Root() {
return (
);
}
```
```ts title="app/lib/ens.ts"
import { createPublicClient, http } from "viem";
import { mainnet } from "viem/chains";
import { Ensforge } from "@ensforge/sdk";
export const ens = Ensforge.create({
publicClient: createPublicClient({ chain: mainnet, transport: http() }),
});
```
## 2. Prefetch in the loader [#2-prefetch-in-the-loader]
Create a new registry in each loader call. The loader returns plain JSON, so the state serializes to the browser.
**Example** (A Name Route)
```tsx no-check title="app/routes/name.tsx"
import { AtomRegistry } from "effect/reactivity";
import { useLoaderData, type LoaderFunctionArgs } from "react-router";
import { HydrationBoundary, useName } from "@ensforge/react";
import { dehydrate, prefetch } from "@ensforge/react/server";
import { Actions } from "@ensforge/sdk";
import { ens } from "../lib/ens";
export async function loader({ params }: LoaderFunctionArgs) {
const name = String(params.name);
const registry = AtomRegistry.make();
await prefetch(registry, ens, Actions.name.get, { name });
return { name, state: dehydrate(registry) };
}
function Profile({ name }: { name: string }) {
const { data } = useName({ name });
return
{data?.owner}
;
}
export default function Route() {
const { name, state } = useLoaderData();
return (
);
}
```
- `useName` reads the same action and options as `prefetch`, so it uses the prefetched value.
- A failed read is not sent, so the route retries it in the browser.
For streaming, call `dehydrate(registry, { streaming: true })` and do not await `prefetch`, as in [Next.js App Router](/docs/react/nextjs-app-router#stream-slow-reads). Reads still loading then stream to the browser as they resolve.
Streaming puts real Promises in the state, so a loader must return it through a serializer that streams promises. React Router's turbo-stream encoding should do this by its documented behaviour, but this page has not verified it. A plain JSON response drops the promise without an error, and the browser then fetches the read itself.
# TanStack Start
> For the complete documentation index, see [llms.txt](https://ensforge.com/llms.txt).
Prefetch ENS reads in a TanStack Start route loader, stream the slow ones as promises, and hydrate them with HydrationBoundary.
Source: https://ensforge.com/docs/react/tanstack-start
In TanStack Start, prefetch the reads in a route `loader`, return the dehydrated state, and render `HydrationBoundary` in the route component. Reads that are still loading can stream to the browser.
`prefetch`, `dehydrate` and `HydrationBoundary` are marked `unstable`. Their names and shapes can
change in a minor release.
## 1. Provide the client in the root route [#1-provide-the-client-in-the-root-route]
Render `EnsforgeProvider` in the root route, around the outlet. Create the client in a shared module.
**Example** (The Root Route)
```tsx title="routes/__root.tsx"
import { createRootRoute, Outlet } from "@tanstack/react-router";
import { EnsforgeProvider } from "@ensforge/react";
import { Ensforge } from "@ensforge/sdk";
import { createPublicClient, http } from "viem";
import { mainnet } from "viem/chains";
const ens = Ensforge.create({
publicClient: createPublicClient({ chain: mainnet, transport: http() }),
});
export const Route = createRootRoute({
component: () => (
),
});
```
## 2. Prefetch in the loader [#2-prefetch-in-the-loader]
Create a new registry in each loader call, `prefetch` the reads, and return `dehydrate(registry)`. The state is plain JSON, so TanStack Start serializes it to the browser.
**Example** (A Name Route)
```tsx no-check title="routes/$name.tsx"
import { createFileRoute } from "@tanstack/react-router";
import { AtomRegistry } from "effect/reactivity";
import { HydrationBoundary, useName } from "@ensforge/react";
import { dehydrate, prefetch } from "@ensforge/react/server";
import { Actions, Ensforge } from "@ensforge/sdk";
import { createPublicClient, http } from "viem";
import { mainnet } from "viem/chains";
const ens = Ensforge.create({
publicClient: createPublicClient({ chain: mainnet, transport: http() }),
});
export const Route = createFileRoute("/$name")({
loader: async ({ params }) => {
const registry = AtomRegistry.make();
await prefetch(registry, ens, Actions.name.get, { name: params.name });
return { state: dehydrate(registry) };
},
component: NamePage,
});
function Profile({ name }: { name: string }) {
const { data } = useName({ name });
return
{data?.owner}
;
}
function NamePage() {
const { name } = Route.useParams();
const { state } = Route.useLoaderData();
return (
);
}
```
- `useName` reads the same action and options as `prefetch`, so it uses the prefetched value.
- `prefetch` resolves once the read settles. A failed read is not sent, so the browser retries it.
- Without `staleTime`, a hydrated value revalidates once it is 30 seconds old.
## Stream slow reads [#stream-slow-reads]
Do not await a slow `prefetch`. Start it, and call `dehydrate(registry, { streaming: true })`. Reads that are still loading reach the browser as promises that resolve there. The loader returns at once with the fast data.
Streaming puts real Promises in the state, so the loader result must go through a serializer that streams promises. TanStack Start's serializer (seroval) does, so the promise reaches the browser and resolves there. A serializer that writes plain JSON drops the promise without an error, and the browser then fetches the read itself.
**Example** (Streaming A Subname List)
```tsx no-check title="routes/$name.tsx"
import { createFileRoute } from "@tanstack/react-router";
import { AtomRegistry } from "effect/reactivity";
import { Suspense } from "react";
import { HydrationBoundary, useSuspenseRead } from "@ensforge/react";
import { dehydrate, prefetch } from "@ensforge/react/server";
import { Actions, Ensforge } from "@ensforge/sdk";
import { goldsky } from "@ensforge/sdk/indexer";
import { createPublicClient, http } from "viem";
import { mainnet } from "viem/chains";
const ens = Ensforge.create({
publicClient: createPublicClient({ chain: mainnet, transport: http() }),
indexer: goldsky(),
});
export const Route = createFileRoute("/$name")({
loader: ({ params }) => {
const registry = AtomRegistry.make();
void prefetch(registry, ens, Actions.indexer.getSubnames, { name: params.name });
return { state: dehydrate(registry, { streaming: true }) };
},
component: Subnames,
});
function List({ name }: { name: string }) {
const { data } = useSuspenseRead(Actions.indexer.getSubnames, { name });
return (
{data.items.map((item) => (
{item.name}
))}
);
}
function Subnames() {
const { name } = Route.useParams();
const { state } = Route.useLoaderData();
return (
Loading subnames...}>
);
}
```
Read a streamed value with [`useSuspenseRead`](/docs/react/suspense) inside ``: the fallback shows until the promise resolves. Prefetch the first page of a list this way. Paged hooks such as `useSubnames` fetch in the browser and do not read a prefetched value.
See [Caching and refreshing](/docs/react/caching-and-refreshing) for how hydrated reads revalidate.
# Use with wagmi
> For the complete documentation index, see [llms.txt](https://ensforge.com/llms.txt).
Build the ensforge client from your wagmi config, so hooks read through wagmi's clients and write with the wallet the user connected.
Source: https://ensforge.com/docs/react/with-wagmi
If your app already uses wagmi, create the ensforge client from the wagmi config. Reads go through wagmi's client, and writes use whichever wallet is connected when they run. It works the same with RainbowKit, ConnectKit, Dynamic, Privy and Reown AppKit, because they all sit on a wagmi config.
## Prerequisites [#prerequisites]
- A wagmi 2 or 3 config, with a transport for the ENS chain.
- [`@ensforge/react` installed](/docs/react/installation).
## Create the client and render the provider [#create-the-client-and-render-the-provider]
`Ensforge.fromWagmi(config)` lives on the `Ensforge` from `@ensforge/sdk/wagmi`, so apps without wagmi never load it. Render `EnsforgeProvider` inside the wagmi providers.
**Example** (Ensforge Inside The Wagmi Providers)
```tsx no-check title="providers.tsx"
import type { ReactNode } from "react";
import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
import { createConfig, http, WagmiProvider } from "wagmi";
import { mainnet } from "wagmi/chains";
import { EnsforgeProvider } from "@ensforge/react";
import { Ensforge } from "@ensforge/sdk/wagmi";
const wagmiConfig = createConfig({
chains: [mainnet],
transports: { [mainnet.id]: http() },
});
const queryClient = new QueryClient();
const ens = Ensforge.fromWagmi(wagmiConfig);
export function Providers({ children }: { children: ReactNode }) {
return (
{children}
);
}
```
With RainbowKit or another wallet kit, put its provider around `EnsforgeProvider` in the same place.
## What `fromWagmi` does for you [#what-fromwagmi-does-for-you]
- The ENS chain is the `chainId` option, else mainnet when the config has it, else the first configured chain ensforge has a deployment for. Its transport must be in the wagmi config. Otherwise it throws [`UNKNOWN_CHAIN`](/docs/reference/errors/UNKNOWN_CHAIN).
- The wallet is looked up on every write, so account and connector changes are followed. With no wallet connected, a write fails with [`WALLET_NOT_CONFIGURED`](/docs/reference/errors/WALLET_NOT_CONFIGURED).
- A wallet on another chain is asked to switch first, as wagmi's own `writeContract` does. Pass `switchChain: false` to turn that off. A wallet on another chain then fails with [`CHAIN_MISMATCH`](/docs/reference/errors/CHAIN_MISMATCH).
- Every other chain of the wagmi config becomes one of the client's `chains`, so writes ENS makes there (an L2 [primary name](/docs/reference/glossary#primary-name)) use wagmi's clients and wallet.
**Example** (A Sepolia Client Without Chain Switching)
```ts no-check title="ens.ts"
import { Ensforge } from "@ensforge/sdk/wagmi";
import { wagmiConfig } from "./wagmi";
export const ens = Ensforge.fromWagmi(wagmiConfig, { chainId: 11155111, switchChain: false });
```
## Troubleshooting [#troubleshooting]
### A write fails with `WALLET_NOT_CONFIGURED` [#a-write-fails-with-wallet_not_configured]
No wallet is connected. Connect one first, then send the write.
### `fromWagmi` throws `UNKNOWN_CHAIN` [#fromwagmi-throws-unknown_chain]
The wagmi config has no chain ensforge can use, or no transport for it. Add mainnet, or another chain ensforge has a deployment for, with a transport. For any other chain, pass `chainId` with a `deployment`.
See [Create a client](/docs/sdk/create-a-client) for every client option, and [Set up the provider](/docs/react/set-up-the-provider) for the provider's props.
# Caching and refreshing
> For the complete documentation index, see [llms.txt](https://ensforge.com/llms.txt).
Learn how hooks share one read, how long results stay cached, and when they refetch after a write, on window focus or on a timer.
Source: https://ensforge.com/docs/react/caching-and-refreshing
Hooks never fetch on their own schedule per component. They share one cached read per question, keep it for a while after the last component leaves, and refetch it when a write changes what it answers.
## How hooks share a read [#how-hooks-share-a-read]
A read is identified by the client's chain, account and indexer, the action and its options. Names are [normalised](/docs/reference/glossary#normalisation) (`Nick.eth` and `nick.eth` share one read) and addresses are compared in lowercase. Two components with the same identity share one request and one result, whatever their freshness settings.
```mermaid
flowchart LR
A[useAddress in Header] -->|asks| R[One shared read]
B[useAddress in Card] -->|asks| R
R -->|one request| N[ENS]
W[useSetRecords] -->|write is mined| R
R -->|refetches| A
R -->|refetches| B
```
After a write is mined, the read refetches and every component that uses it updates.
## Choose how fresh a read is [#choose-how-fresh-a-read-is]
Four settings control freshness. Set them on a hook, or on the provider's `defaults` for every hook. A hook's own value wins.
| Setting | Default | Effect |
| ---------------------- | ------------ | --------------------------------------------------------------------------------------------------------------------------------------------------- |
| `staleTime` | none | After this long, the next mount or window focus refetches in the background while the cached value stays on screen. `Duration.infinity` never does. |
| `idleTTL` | `"1 minute"` | How long an unused read stays cached after its last component unmounts. `"forever"` keeps it. |
| `refetchInterval` | none | Refetches on this interval while the read is in use. Browser only: servers never poll. |
| `refreshOnWindowFocus` | `false` | Refetches when the window regains focus, respecting `staleTime` when set. |
Hooks with different settings still share the read's value and requests. When hooks disagree on `idleTTL`, the longest applies.
**Example** (Refetching A Name's State In The Background)
```tsx title="Expiry.tsx"
import { useName } from "@ensforge/react";
export function Expiry({ name }: { name: string }) {
const { data, isRefreshing } = useName(
{ name },
{ staleTime: "30 seconds", refreshOnWindowFocus: true, idleTTL: "5 minutes" },
);
return (
{String(data?.expiry)} {isRefreshing && "(updating)"}
);
}
```
`data` stays on screen while `isRefreshing` is `true`. This pattern is called stale-while-revalidate.
## What unmounting does [#what-unmounting-does]
An unmounted read keeps its result, and any request still in flight, for `idleTTL`. A remount within that time reuses both. A failed read is always stale, so a remount retries it.
## Refresh after a write [#refresh-after-a-write]
Writes made through ensforge refresh the reads they touched. You do not call anything.
- A write touches the names and accounts in its options, the parents of those names (for [subname](/docs/reference/glossary#subname) lists) and the signer (for primary names, approvals and "my names" lists).
- **Chain reads** refetch once the write's last transaction is mined. They refetch even if waiting for the receipt fails, because the transaction may have landed.
- **[Indexer](/docs/reference/glossary#indexer) reads**, such as [infinite lists](/docs/react/infinite-lists), refetch once the indexer reports the write's block. ensforge polls for up to a minute, and gives an indexer with no status a few seconds instead.
- A write that fails after one step was confirmed refreshes too.
- A signature (`primaryName.signClaim`) sends no transaction and refreshes nothing.
- A read also follows the names its value mentions, such as a [primary name](/docs/reference/glossary#primary-name), so changing that name's address refreshes it.
The write's result never waits for these refreshes. See [Write data](/docs/react/write-data).
## Refresh by hand [#refresh-by-hand]
Every read hook returns `refresh()`. Call it to refetch one read now.
**Example** (A Refresh Button)
```tsx title="Refresh.tsx"
import { useAddress } from "@ensforge/react";
export function Refresh({ name }: { name: string }) {
const { data, isRefreshing, refresh } = useAddress({ name });
return (
);
}
```
## Refresh after a change ensforge did not make [#refresh-after-a-change-ensforge-did-not-make]
When another app, or a transaction sent outside ensforge, changes a name, call `invalidate` from `@ensforge/react/atoms`. It refetches every cached read of the given names and addresses, chain and indexer reads alike. It is unstable. The example imports `RegistryContext` from `@effect/atom-react`, so add that package at the version `@ensforge/react` depends on.
**Example** (Invalidating After An External Transaction)
```tsx no-check title="Invalidate.tsx"
import { RegistryContext } from "@effect/atom-react";
import { useContext } from "react";
import { useEnsforge } from "@ensforge/react";
import { invalidate } from "@ensforge/react/atoms";
export function Invalidate({ name }: { name: string }) {
const ens = useEnsforge();
const registry = useContext(RegistryContext);
return (
);
}
```
## Hydrated reads [#hydrated-reads]
A value that came from the server renders first, then revalidates. With no `staleTime` set, a hydrated value counts as stale after 30 seconds. See [Next.js App Router](/docs/react/nextjs-app-router) and the other framework guides.
# Infinite lists
> For the complete documentation index, see [llms.txt](https://ensforge.com/llms.txt).
Page through an account's names, a name's subnames or a name's history with load-more hooks that read from an ENS indexer.
Source: https://ensforge.com/docs/react/infinite-lists
List hooks load an indexer list one page at a time, for "load more" buttons and infinite scroll. They need an [indexer](/docs/reference/glossary#indexer) on the client. Without one, the read fails with [`INDEXER_NOT_CONFIGURED`](/docs/reference/errors/INDEXER_NOT_CONFIGURED).
## Add an indexer to the client [#add-an-indexer-to-the-client]
Pass `indexer` to `Ensforge.create`: `bigname()`, `goldsky()`, `fallback([...])` or `defineIndexer({...})` from `@ensforge/sdk/indexer`. See [Connect an indexer](/docs/sdk/connect-an-indexer).
**Example** (A Client With An Indexer)
```tsx title="providers.tsx"
import type { ReactNode } from "react";
import { EnsforgeProvider } from "@ensforge/react";
import { Ensforge } from "@ensforge/sdk";
import { goldsky } from "@ensforge/sdk/indexer";
import { createPublicClient, http } from "viem";
import { mainnet } from "viem/chains";
const ens = Ensforge.create({
publicClient: createPublicClient({ chain: mainnet, transport: http() }),
indexer: goldsky(),
});
export function Providers({ children }: { children: ReactNode }) {
return {children};
}
```
## Show a list with "Load more" [#show-a-list-with-load-more]
`useSubnames` lists a name's [subnames](/docs/reference/glossary#subname). It returns every item loaded so far in `items`, and `loadMore` fetches the next page.
**Example** (Subnames With A Load More Button)
```tsx title="Subnames.tsx"
import { useSubnames } from "@ensforge/react";
export function Subnames({ name }: { name: string }) {
const { items, hasMore, loadMore, isLoading, isLoadingMore, error } = useSubnames({ name });
if (isLoading) return
Loading...
;
if (error) return
{error.message}
;
return (
<>
{items.map((item) => (
{item.name}
))}
{hasMore && (
)}
>
);
}
```
| Field | Meaning |
| --------------- | ---------------------------------- |
| `pages` | Every page loaded so far. |
| `items` | The items of every page, in order. |
| `hasMore` | More pages remain. |
| `loadMore` | Loads the next page. |
| `isLoading` | The first page is loading. |
| `isLoadingMore` | A further page is loading. |
| `error` | The action's error when it failed. |
## Pick a list hook [#pick-a-list-hook]
| Hook | Lists |
| ------------------------------------------------------------------- | ------------------------------------------------------------- |
| [`useSubnames`](/docs/reference/react/use-subnames) | A name's subnames. |
| [`useNamesForAddress`](/docs/reference/react/use-names-for-address) | Names an address owns, manages or is the primary name of. |
| [`useNameHistory`](/docs/reference/react/use-name-history) | A name's events: registrations, transfers and record changes. |
For any other paginated indexer action, use `useInfiniteRead(action, options, config)`. The action must return `{ items, cursor }` and take a `cursor`, as `Actions.indexer.getSubnames` does. Leave `cursor` out of the options: the hook manages it.
**Example** (Any Paginated Action)
```tsx title="SearchSubnames.tsx"
import { useInfiniteRead } from "@ensforge/react";
import { Actions } from "@ensforge/sdk";
export function SearchSubnames({ name, search }: { name: string; search: string }) {
const { items, hasMore, loadMore } = useInfiniteRead(Actions.indexer.getSubnames, {
name,
search,
});
return (
<>
{items.map((item) => (
{item.name}
))}
{hasMore && }
>
);
}
```
## Wait for input and keep lists fresh [#wait-for-input-and-keep-lists-fresh]
Pass `undefined` options, or `enabled: false` in the config, to hold the list back, as with [read hooks](/docs/react/read-data#wait-for-input). The config takes `enabled` and `client` only.
A write that touches the list's name or account starts the list over once the indexer has caught up, so a new subname appears without a manual refresh. See [Caching and refreshing](/docs/react/caching-and-refreshing#refresh-after-a-write).
For the same lists outside React, see [Load more results](/docs/sdk/load-more-results).
# Read data
> For the complete documentation index, see [llms.txt](https://ensforge.com/llms.txt).
Read names, records and lists in components with hooks that share and cache every request, and handle loading and errors.
Source: https://ensforge.com/docs/react/read-data
Use a read hook in a component to get a value for a [name](/docs/reference/glossary#name) or an address. Every hook returns the same result object, and components that ask for the same thing share one request.
## Read with a named hook [#read-with-a-named-hook]
Named hooks cover the common reads. Pass the same options as the matching [SDK action](/docs/reference/sdk/record/get-address).
**Example** (Reading An Address And A Profile)
```tsx title="Profile.tsx"
import { useAddress, useRecords } from "@ensforge/react";
export function Profile({ name }: { name: string }) {
const { data: address } = useAddress({ name });
const { data: profile, isLoading } = useRecords({ name, texts: ["url", "avatar"] });
if (isLoading) return
Loading...
;
return (
Address
{address}
Website
{profile?.texts.url}
);
}
```
`useRecords` reads several [records](/docs/reference/glossary#record) in one call and returns them under `texts` and `addresses`.
| Hook | Reads |
| ---------------------------------------------------------------------- | ----------------------------------------------------------------------- |
| [`useAddress`](/docs/reference/react/use-address) | The address a name points to, for ETH or another coin. |
| [`useText`](/docs/reference/react/use-text) | One text record, such as `url` or `com.twitter`. |
| [`useRecords`](/docs/reference/react/use-records) | Several records at once. |
| [`useAvatar`](/docs/reference/react/use-avatar) | An avatar as an image URL, with NFT avatars resolved. |
| [`usePrimaryName`](/docs/reference/react/use-primary-name) | The primary name of an address, verified against its forward address. |
| [`useName`](/docs/reference/react/use-name) | A name's owner, manager, expiry, resolver, registry and wrapper status. |
| [`useAvailability`](/docs/reference/react/use-availability) | Whether a name can be registered now. |
| [`useRegistrationPrice`](/docs/reference/react/use-registration-price) | What registering names for a duration costs. |
| [`usePermissions`](/docs/reference/react/use-permissions) | What an account may do with a name. |
| [`useMigrationStatus`](/docs/reference/react/use-migration-status) | Whether and how a name can move from ENSv1 to ENSv2. |
Lists from an [indexer](/docs/reference/glossary#indexer) have their own hooks. See [Infinite lists](/docs/react/infinite-lists).
## Read the result [#read-the-result]
Every read hook returns a `ReadResult`.
| Field | Type | Meaning |
| -------------- | --------------------------------------------- | -------------------------------------------------------- |
| `data` | `value \| undefined` | The latest value. It stays while the read refreshes. |
| `error` | `error \| undefined` | The action's error when it failed. |
| `status` | `"idle" \| "loading" \| "success" \| "error"` | `idle` while disabled, `loading` until the first result. |
| `isLoading` | `boolean` | No result yet, and loading. |
| `isRefreshing` | `boolean` | Loading again, with a previous result shown. |
| `refresh` | `() => void` | Refetches the read. |
| `result` | `AsyncResult` | The Effect Atom result, for `AsyncResult.match`. |
`error` is a typed ensforge error. Read its `code` to decide what to show. See [Handle errors](/docs/sdk/handle-errors).
## Read with any action [#read-with-any-action]
`useRead(action, options, config)` runs any SDK action. Pass the action itself, not a call to it.
**Example** (Reading An Account's Permissions)
```tsx title="CanEdit.tsx"
import type { Address } from "viem";
import { useRead } from "@ensforge/react";
import { Actions } from "@ensforge/sdk";
export function CanEdit({ name, account }: { name: string; account: Address }) {
const { data, isLoading } = useRead(Actions.permission.get, { name, account });
if (isLoading) return null;
return {String(data?.can.setRecords)};
}
```
`useRead` accepts actions from `@ensforge/sdk` and from `@ensforge/sdk/effect`. Named hooks are presets of it.
## Wait for input [#wait-for-input]
Pass `undefined` options, or `enabled: false`, to hold a read back until you have what it needs, such as a name the user is still typing. `status` is `"idle"` meanwhile.
**Example** (Reading After The User Types)
```tsx title="Lookup.tsx"
import { useState } from "react";
import { useAddress } from "@ensforge/react";
export function Lookup() {
const [name, setName] = useState("");
const { data, status } = useAddress(name === "" ? undefined : { name });
return (
<>
setName(event.target.value)} />
{status === "idle" ? "Type a name" : data}
>
);
}
```
## Settings for one hook [#settings-for-one-hook]
Every read hook takes a config as its last argument: `staleTime`, `idleTTL`, `refetchInterval`, `refreshOnWindowFocus`, `enabled` and `client`. See [Caching and refreshing](/docs/react/caching-and-refreshing).
**Example** (Polling A Name's State)
```tsx title="Expiry.tsx"
import { useName } from "@ensforge/react";
export function Expiry({ name }: { name: string }) {
const { data } = useName({ name }, { refetchInterval: "1 minute" });
return {String(data?.expiry)};
}
```
To read inside `` instead of checking `isLoading`, see [Use Suspense](/docs/react/suspense).
# Read many at once
> For the complete documentation index, see [llms.txt](https://ensforge.com/llms.txt).
Run a changing list of reads with useReads, such as an avatar for every row, and share multicall batches between components.
Source: https://ensforge.com/docs/react/read-many-at-once
Use `useReads` when the number of reads changes, such as one address or [avatar](/docs/reference/glossary#avatar) per row of a list. Their RPC calls share the client's multicall [batches](/docs/reference/glossary#batch), so a long list does not send a request per row.
## Pass a list of reads [#pass-a-list-of-reads]
Each read is a pair of an action and its options. Mark the array `as const` so each pair keeps its types. Results come back in the same order.
**Example** (Addresses Of Several Names)
```tsx title="Addresses.tsx"
import { useReads } from "@ensforge/react";
import { Actions } from "@ensforge/sdk";
export function Addresses({ names }: { names: readonly string[] }) {
const results = useReads(names.map((name) => [Actions.record.getAddress, { name }] as const));
return (
);
}
```
Each entry is a [`ReadResult`](/docs/react/read-data#read-the-result) with its own `data`, `error`, `status` and `refresh`. One failed read does not fail the others.
## Mix actions in a fixed set [#mix-actions-in-a-fixed-set]
For a fixed set, separate hooks work equally well. Use `useReads` with different actions when you want them in one tuple. Each result is typed by its own action.
**Example** (An Address And An Avatar Together)
```tsx title="Card.tsx"
import { useReads } from "@ensforge/react";
import { Actions } from "@ensforge/sdk";
export function Card({ name }: { name: string }) {
const [address, avatar] = useReads([
[Actions.record.getAddress, { name }],
[Actions.record.getAvatar, { name }],
] as const);
return (
{address.data}
);
}
```
## Read an HCA account [#read-an-hca-account]
The `@ensforge/hca` reads, such as `Actions.hca.get`, work in `useReads` like any other read. Pass the pair `[Actions.hca.get, {}]`.
## Settings [#settings]
`useReads` takes a config as its second argument: `staleTime`, `idleTTL`, `refetchInterval`, `refreshOnWindowFocus` and `client`. It applies to every read in the list. There is no `enabled`: leave a read out of the list instead.
## Reads are shared with other hooks [#reads-are-shared-with-other-hooks]
A read in `useReads` is the same read a `useAddress` elsewhere makes for that name. Both share one request and one cached result. See [Caching and refreshing](/docs/react/caching-and-refreshing).
Outside React, the SDK batches reads the same way. See [Look up many at once](/docs/sdk/look-up-many-at-once).
# Use Suspense
> For the complete documentation index, see [llms.txt](https://ensforge.com/llms.txt).
Read ENS data with useSuspenseRead inside Suspense and error boundaries, and retry failed reads with ReadErrorResetBoundary.
Source: https://ensforge.com/docs/react/suspense
`useSuspenseRead` suspends until its value is there, so `data` is never `undefined`. Loading shows the nearest `` fallback. A failure throws to the nearest error boundary.
## Read inside Suspense [#read-inside-suspense]
Call `useSuspenseRead(action, options, config)` in a component and wrap it in ``. Options are required: there is no `enabled` switch, because a suspending read always runs.
**Example** (A Website Link Behind Suspense)
```tsx title="Url.tsx"
import { Suspense } from "react";
import { useSuspenseRead } from "@ensforge/react";
import { Actions } from "@ensforge/sdk";
function Url({ name }: { name: string }) {
const { data } = useSuspenseRead(Actions.record.getText, { name, key: "url" });
return {data};
}
export function Website({ name }: { name: string }) {
return (
Loading...}>
);
}
```
It returns `{ data, isRefreshing, refresh }`. `isRefreshing` is `true` while a refetch runs and the current value stays on screen. The config takes the same freshness settings as `useRead`, without `enabled`. See [Caching and refreshing](/docs/react/caching-and-refreshing).
## Handle failures with an error boundary [#handle-failures-with-an-error-boundary]
A failed read throws the ensforge error to the nearest error boundary. The failure stays cached: until you reset, every render throws the same error again, so "try again" would show the old error instead of fetching.
Wrap the error boundary in `ReadErrorResetBoundary` and call `reset` when the boundary resets. After that, the reads below read again. It works like React Query's `QueryErrorResetBoundary`.
**Example** (Retrying A Failed Read)
```tsx title="Owner.tsx"
import { Component, Suspense, type ReactNode } from "react";
import { ReadErrorResetBoundary, useSuspenseRead } from "@ensforge/react";
import { Actions } from "@ensforge/sdk";
// Any error boundary with a reset callback works, such as react-error-boundary's `onReset`.
class Boundary extends Component<
{ children: ReactNode; onReset: () => void },
{ failed: boolean }
> {
override state = { failed: false };
static getDerivedStateFromError() {
return { failed: true };
}
override render() {
if (!this.state.failed) return this.props.children;
return (
);
}
}
function Owner({ name }: { name: string }) {
const { data } = useSuspenseRead(Actions.name.get, { name });
return {data.owner};
}
export const View = ({ name }: { name: string }) => (
{({ reset }) => (
)}
);
```
- `ReadErrorResetBoundary` takes children, or a function of `{ reset }`.
- Remounting the component alone does not retry a failure thrown to an error boundary. Only `reset` does.
- Without a `ReadErrorResetBoundary`, `reset` applies to every read in the app. Use one boundary per region to retry only that region.
## Reset from inside a component [#reset-from-inside-a-component]
`useReadErrorReset()` returns the same `{ reset }` handle for the nearest `ReadErrorResetBoundary`, or for the whole app without one. Use it in a fallback component that you wire to an error boundary.
**Example** (A Retry Button)
```tsx title="RetryButton.tsx"
import { useReadErrorReset } from "@ensforge/react";
export function RetryButton({ onRetry }: { onRetry: () => void }) {
const { reset } = useReadErrorReset();
return (
);
}
```
Call `reset` first, then reset your error boundary, so the re-render reads again.
## Suspense with server rendering [#suspense-with-server-rendering]
On the server, a suspending read that was not prefetched throws, so React renders the boundary's fallback there and the read runs in the browser. React reports that as a recoverable error. Prefetch the reads a page needs to render them on the server. See [Next.js App Router](/docs/react/nextjs-app-router).
# Preview before sending
> For the complete documentation index, see [llms.txt](https://ensforge.com/llms.txt).
Plan a write with usePrepare to show its steps and warnings before anything is sent, and disable the send button while the write cannot run.
Source: https://ensforge.com/docs/react/preview-before-sending
`usePrepare` plans a write without sending it. It never sends a transaction and never opens the wallet. Use it for a review screen: how many transactions, what warnings, and whether the account is allowed to send at all.
## Plan a write [#plan-a-write]
Pass a write action and its options. `usePrepare` runs the action's `.prepare` and returns a [`ReadResult`](/docs/react/read-data#read-the-result) whose `data` is the [plan](/docs/reference/glossary#plan). See [How writes work](/docs/sdk/writing-to-ens).
**Example** (Reviewing A Records Update)
```tsx title="Review.tsx"
import { usePrepare } from "@ensforge/react";
import { Actions } from "@ensforge/sdk";
export function Review({ name, url }: { name: string; url: string }) {
const { data: plan, error, isLoading } = usePrepare(Actions.record.set, { name, texts: { url } });
if (isLoading) return
Planning...
;
if (error) return
{error.message}
;
return (
<>
{plan?.steps.length} transaction step(s)
{plan?.warnings.map((warning) => (
{warning.message}
))}
>
);
}
```
A plan lists `steps` and `calls`, `requirements` (such as a balance or an approval) and `warnings` (non-blocking notes for the user).
## Disable the button while the plan fails [#disable-the-button-while-the-plan-fails]
Planning surfaces permission errors early, so the same hook can gate the submit button. Pair it with `useSetRecords` (or any write hook) with the same options.
**Example** (Review And Send)
```tsx title="ReviewAndSend.tsx"
import { usePrepare, useSetRecords } from "@ensforge/react";
import { Actions } from "@ensforge/sdk";
export function ReviewAndSend({ name, url }: { name: string; url: string }) {
const options = { name, texts: { url } };
const plan = usePrepare(Actions.record.set, options);
const { mutate, isPending } = useSetRecords();
return (
<>
{plan.error &&
{plan.error.message}
}
>
);
}
```
## Pass undefined to wait [#pass-undefined-to-wait]
Like read hooks, `usePrepare` waits when its options are `undefined`, and takes the same config (`enabled`, freshness, `client`). Plans are cached and shared like any read. See [Caching and refreshing](/docs/react/caching-and-refreshing).
For the full plan type, simulation and gas estimates outside React, see [Preview before sending](/docs/sdk/preview-before-sending).
# Write data
> For the complete documentation index, see [llms.txt](https://ensforge.com/llms.txt).
Send ENS writes from components with useWrite or a named hook, track their steps and errors, and await the final result.
Source: https://ensforge.com/docs/react/write-data
Use a write hook to send a transaction from an event handler. The hook tracks the write for you: its status, its steps, its result and its error. Use a testnet such as Sepolia and a name you own while you build.
## Send a write [#send-a-write]
`useSetRecords` writes records to a name. Call `mutate` with the action's options. Writes need a wallet on the client. See [Set up the provider](/docs/react/set-up-the-provider).
**Example** (A Save Button)
```tsx title="Save.tsx"
import { useSetRecords } from "@ensforge/react";
export function Save({ name }: { name: string }) {
const { mutate, isPending, status, error } = useSetRecords();
return (
<>
{status === "success" &&
Saved
}
{error &&
{error.message}
}
>
);
}
```
`mutate` returns nothing. The outcome lands in `status`, `data` and `error`. `useSetRecords` runs `record.set`, which resolves once the transaction is submitted. Use the `…Sync` action to wait for the receipt, shown below.
## Pick a write hook [#pick-a-write-hook]
| Hook | Sends |
| ----------------------------------------------------------------- | ------------------------------------------------------------- |
| [`useSetRecords`](/docs/reference/react/use-set-records) | Sets, changes or clears a name's records in one write. |
| [`useRegister`](/docs/reference/react/use-register) | Registers names: commit, wait the minimum age, then register. |
| [`useRenew`](/docs/reference/react/use-renew) | Renews names. |
| [`useSetResolver`](/docs/reference/react/use-set-resolver) | Points a name at a resolver. |
| [`useTransferName`](/docs/reference/react/use-transfer-name) | Transfers a name to another account. |
| [`useCreateSubname`](/docs/reference/react/use-create-subname) | Creates a subname, optionally with records. |
| [`useSetPrimaryName`](/docs/reference/react/use-set-primary-name) | Sets the signer's primary name. |
| [`useSignClaim`](/docs/reference/react/use-sign-claim) | Signs a primary-name claim once, to set it on other chains. |
| [`useMigrate`](/docs/reference/react/use-migrate) | Moves names from ENSv1 to ENSv2. |
For any other write, use `useWrite(action)` with an action from `@ensforge/sdk`. Named hooks are presets of it.
## What the hook returns [#what-the-hook-returns]
| Field | Meaning |
| ---------------------- | --------------------------------------------------------------------------------------------------- |
| `mutate(options)` | Sends the write. The outcome lands in `status`, `data` and `error`. Stable across renders. |
| `mutateAsync(options)` | Sends the write and resolves with its own result, or rejects with its error. Stable across renders. |
| `status` | `"idle"`, `"pending"`, `"success"` or `"error"`, for the latest write started. |
| `isPending` | A write is running. |
| `data` | The latest write's value, once it succeeded. |
| `error` | The latest write's typed error. |
| `steps` | Plan events of the latest write: `waiting`, `submitted`, `confirmed`, `failed`. |
| `reset()` | Clears the result and steps. |
Each component gets its own state, so two buttons never share a result. The state follows the latest write started, while each `mutateAsync` settles with its own write.
## Show progress [#show-progress]
Multi-step writes, such as a registration (commit, wait, register), push an event to `steps` as each [step](/docs/reference/glossary#step) changes. Each event names its `step` and its `status`. `submitted` events carry the transaction `hashes`, and `failed` events carry the `error`.
**Example** (Registering With Progress)
```tsx title="Register.tsx"
import { useRegister } from "@ensforge/react";
import { Duration } from "@ensforge/sdk";
export function Register({ name }: { name: string }) {
const { mutate, isPending, steps, error } = useRegister();
return (
<>
{steps.map((event, index) => (
{event.step.description}: {event.status}
))}
{error &&
{error.message}
}
>
);
}
```
## Await a write [#await-a-write]
Use `mutateAsync` to run code after the write, such as closing a dialog. It rejects with the action's error, so catch it.
**Example** (Waiting For The Receipt)
```tsx title="SaveAndClose.tsx"
import { useWrite } from "@ensforge/react";
import { Actions } from "@ensforge/sdk";
export function SaveAndClose({ name, onDone }: { name: string; onDone: () => void }) {
const { mutateAsync, isPending } = useWrite(Actions.record.setSync);
const save = async () => {
try {
await mutateAsync({ name, texts: { url: "https://alice.xyz" } });
onDone();
} catch (error) {
console.error(error);
}
};
return (
);
}
```
`Actions.record.setSync` resolves with receipts, once the transaction is mined. `Actions.record.set` resolves when it is submitted.
## Start over [#start-over]
`reset()` clears `status`, `data`, `error` and `steps`. It never cancels a write in flight, because a sent transaction cannot be taken back. Their `mutateAsync` promises still settle, but they no longer update the state.
## What refreshes afterwards [#what-refreshes-afterwards]
Once a write succeeds, every read of the names and accounts it touched refetches: chain reads once the transaction is mined, indexer reads once the indexer has caught up. Components that show the data update on their own. See [Caching and refreshing](/docs/react/caching-and-refreshing#refresh-after-a-write).
To show what a write will do before the wallet prompt, see [Preview before sending](/docs/react/preview-before-sending). For how [plans](/docs/reference/glossary#plan) work, see [How writes work](/docs/sdk/writing-to-ens).
# Quick start
> For the complete documentation index, see [llms.txt](https://ensforge.com/llms.txt).
Show a name's address in a React app with one hook, then send a write with another, in a few minutes with EnsforgeProvider.
Source: https://ensforge.com/docs/react
You will read the address of `nick.eth` in a component and then send one write. You need a React 19 app with [the package installed](/docs/react/installation).
## 1. Create a client and wrap your app [#1-create-a-client-and-wrap-your-app]
Create one ensforge client and pass it to `EnsforgeProvider` once, near the root. Every hook below it uses that client. See [Set up the provider](/docs/react/set-up-the-provider) for wagmi and for the options.
**Example** (Providing A Client)
```tsx title="providers.tsx"
import type { ReactNode } from "react";
import { EnsforgeProvider } from "@ensforge/react";
import { Ensforge } from "@ensforge/sdk";
import { createPublicClient, http } from "viem";
import { mainnet } from "viem/chains";
const ens = Ensforge.create({
publicClient: createPublicClient({ chain: mainnet, transport: http() }),
});
export function Providers({ children }: { children: ReactNode }) {
return {children};
}
```
- `Ensforge.create` builds the client from a viem public client. Add a `walletClient` to send writes.
- Create the client outside any component, so every render uses the same one.
## 2. Read an address [#2-read-an-address]
`useAddress` reads the address a [name](/docs/reference/glossary#name) points to. It returns `isLoading` until the first result, then `data`. It is a preset of [`useRead`](/docs/reference/react/use-read).
**Example** (Showing An Address)
```tsx title="Address.tsx"
import { useAddress } from "@ensforge/react";
export function Address() {
const { data: address, isLoading, error } = useAddress({ name: "nick.eth" });
if (isLoading) return
Loading...
;
if (error) return
{error.message}
;
return
{address}
;
}
```
```text title="Output"
Loading...
0xb8c2C29ee19D8307cb7255e1Cd9CbDE883A267d5
```
Every component that reads `nick.eth` shares this one request and result. See [Read data](/docs/react/read-data).
## 3. Send a write [#3-send-a-write]
`useSetRecords` writes [records](/docs/reference/glossary#record) to a name you manage. Call `mutate` from an event handler. `status` and `steps` follow the transaction. Use a testnet such as Sepolia and a name you own for writes.
**Example** (Saving A Website Record)
```tsx title="SaveUrl.tsx"
import { useSetRecords } from "@ensforge/react";
export function SaveUrl({ name }: { name: string }) {
const { mutate, status, steps, error } = useSetRecords();
return (
<>
{status}, {steps.length} step(s)
{error &&
{error.message}
}
>
);
}
```
Once the transaction is mined, every read of `name` on screen refetches, so a component that shows the record updates on its own. See [Write data](/docs/react/write-data).
The client in step 1 has no wallet, so a write fails with
[`WALLET_NOT_CONFIGURED`](/docs/reference/errors/WALLET_NOT_CONFIGURED). Pass a `walletClient` to
`Ensforge.create`, or use [wagmi](/docs/react/with-wagmi).
## Where to go next [#where-to-go-next]
# Installation
> For the complete documentation index, see [llms.txt](https://ensforge.com/llms.txt).
Install @ensforge/react with the ensforge SDK and its peer dependencies in a React 19 app, then check that the install works.
Source: https://ensforge.com/docs/react/installation
`@ensforge/react` needs React 19 and the ensforge SDK. It depends on `@effect/atom-react` and installs it for you. Add `@effect/atom-react` to your own dependencies only when your code imports from it, such as `RegistryContext` for the atom layer. Use the version `@ensforge/react` depends on, so both share one registry context.
## Install the packages [#install-the-packages]
```package-install
@ensforge/react @ensforge/sdk effect viem react
```
- `@ensforge/sdk` is the client the hooks run actions with. See [Create a client](/docs/sdk/create-a-client).
- `effect` and `viem` are peer dependencies, as they are for the SDK.
- `scheduler` (0.25 to 0.28) is a peer dependency too. React DOM depends on it. If your package manager reports it missing, add it.
- `react` must be version 19 or newer.
## Use wagmi? Add the adapter [#use-wagmi-add-the-adapter]
If your app already has a wagmi config, you do not need a separate wallet setup. `Ensforge.fromWagmi` from `@ensforge/sdk/wagmi` builds the client from it. wagmi 2 and 3 work. See [Use with wagmi](/docs/react/with-wagmi).
## What each entry point holds [#what-each-entry-point-holds]
| Import | Holds |
| ------------------------ | ------------------------------------------------------------------------------ |
| `@ensforge/react` | `EnsforgeProvider`, every hook, `ReadErrorResetBoundary`, `HydrationBoundary`. |
| `@ensforge/react/server` | `prefetch` and `dehydrate` for server rendering (unstable). |
| `@ensforge/react/atoms` | The atom layer the hooks are built on (unstable). |
The package is ESM only. Add `"use client"` to a component file that uses a hook when your framework has server components, as in the [Next.js App Router](/docs/react/nextjs-app-router).
## Check the install [#check-the-install]
Render `useAddress({ name: "nick.eth" })` under a provider. The [Quick start](/docs/react) walks through it.
# Set up the provider
> For the complete documentation index, see [llms.txt](https://ensforge.com/llms.txt).
Create one ensforge client and render EnsforgeProvider once near the root, so every hook below it can read and write ENS.
Source: https://ensforge.com/docs/react/set-up-the-provider
Every hook needs a client from `EnsforgeProvider`, or a `client` option. Render the provider once, near the root of your app.
## Pass a client [#pass-a-client]
`client` takes any ensforge client: `Ensforge.create(...)` or, with wagmi, `Ensforge.fromWagmi(config)`. Create it once, outside components, so renders share it.
**Example** (A Provider Without Wagmi)
```tsx title="providers.tsx"
import type { ReactNode } from "react";
import { EnsforgeProvider } from "@ensforge/react";
import { Ensforge } from "@ensforge/sdk";
import { createPublicClient, http } from "viem";
import { mainnet } from "viem/chains";
const ens = Ensforge.create({
publicClient: createPublicClient({ chain: mainnet, transport: http() }),
});
export function Providers({ children }: { children: ReactNode }) {
return {children};
}
```
Add a `walletClient` to `Ensforge.create` to send writes. See [Create a client](/docs/sdk/create-a-client) for every client option, including the [indexer](/docs/reference/glossary#indexer) that list hooks need. With wagmi, see [Use with wagmi](/docs/react/with-wagmi).
A hook that runs with no provider and no `client` option throws this error:
```text title="Error"
ensforge hooks need an above them, or a `client` option.
```
## Props [#props]
| Prop | Type | Default | Description |
| ---------- | ----------------- | -------- | ----------------------------------------------------------- |
| `client` | `Ensforge.Client` | required | The client every hook below uses. |
| `defaults` | `Freshness` | `{}` | Freshness for every read below, unless a hook sets its own. |
| `registry` | `boolean` | `true` | Render an atom registry for the subtree. |
| `children` | `ReactNode` | none | Your app. |
## Set freshness for every read [#set-freshness-for-every-read]
`defaults` takes `staleTime`, `idleTTL`, `refetchInterval` and `refreshOnWindowFocus`. A hook's own config wins over `defaults`. See [Caching and refreshing](/docs/react/caching-and-refreshing) for what each one does.
**Example** (Refetching On Window Focus)
```tsx title="providers.tsx"
import type { ReactNode } from "react";
import { EnsforgeProvider } from "@ensforge/react";
import { Ensforge } from "@ensforge/sdk";
import { createPublicClient, http } from "viem";
import { mainnet } from "viem/chains";
const ens = Ensforge.create({
publicClient: createPublicClient({ chain: mainnet, transport: http() }),
});
const defaults = { staleTime: "30 seconds", refreshOnWindowFocus: true } as const;
export function Providers({ children }: { children: ReactNode }) {
return (
{children}
);
}
```
Define `defaults` outside the component, as above, so the provider does not rebuild its context on every render.
## Share a registry [#share-a-registry]
The provider renders an atom registry, the cache every hook reads and writes. Each server request therefore gets its own cache. Pass `registry={false}` when your app already renders a `RegistryProvider` (to share atoms with it), or when you nest a second provider, for example for another chain.
**Example** (A Second Provider For Sepolia)
```tsx title="sepolia-provider.tsx"
import type { ReactNode } from "react";
import { EnsforgeProvider } from "@ensforge/react";
import { Ensforge } from "@ensforge/sdk";
import { createPublicClient, http } from "viem";
import { sepolia } from "viem/chains";
const sepoliaEns = Ensforge.create({
publicClient: createPublicClient({ chain: sepolia, transport: http() }),
});
export function SepoliaProvider({ children }: { children: ReactNode }) {
return (
{children}
);
}
```
Reads are cached per chain, account and indexer, so two clients never mix results.
## Get the client in your own code [#get-the-client-in-your-own-code]
`useEnsforge()` returns the nearest provider's client. Use it to call an action from an event handler, outside the hooks.
**Example** (Calling An Action From A Click)
```tsx title="Check.tsx"
import { useEnsforge } from "@ensforge/react";
import { Actions } from "@ensforge/sdk";
export function Check({ name }: { name: string }) {
const ens = useEnsforge();
return ;
}
```
## Override the client for one hook [#override-the-client-for-one-hook]
Every read and write hook takes a `client` in its config. It replaces the provider's client for that hook. The provider's `defaults` still apply to reads.
# ABIs
> For the complete documentation index, see [llms.txt](https://ensforge.com/llms.txt).
Look up every ENS contract ABI in @ensforge/contracts, by protocol version, as typed const arrays you can pass straight to viem.
Source: https://ensforge.com/docs/reference/contracts/abis
`Abis` holds every ENS contract ABI as a `const` array, so viem infers function names, arguments and results. ENSv1 ABIs are in `Abis.v1`, ENSv2 ABIs in `Abis.v2`, and resolver profiles, token standards, errors and events shared by both in `Abis.shared`. See [Use ABIs with viem](/docs/contracts/use-abis-with-viem).
## `Abis.shared` [#abisshared]
| ABI | Functions | Events | Errors | Description |
| --- | --- | --- | --- | --- |
| `Abis.shared.abiResolver` | 1 | 1 | 0 | ENSIP-4 contract ABI resolver profile. |
| `Abis.shared.addrResolver` | 1 | 1 | 0 | Legacy ETH-only address resolver profile. |
| `Abis.shared.addressResolver` | 1 | 1 | 0 | ENSIP-9 multicoin address resolver profile. |
| `Abis.shared.contenthashResolver` | 1 | 1 | 0 | ENSIP-7 content hash resolver profile. |
| `Abis.shared.dataResolver` | 1 | 1 | 0 | ENSIP-24 arbitrary data resolver profile. |
| `Abis.shared.dnsRecordResolver` | 2 | 2 | 0 | DNS record resolver profile for wire-format DNS records. |
| `Abis.shared.dnsZoneResolver` | 1 | 1 | 0 | DNS zone hash resolver profile. |
| `Abis.shared.dnssecGateway` | 1 | 0 | 0 | Off-chain DNSSEC gateway interface (`IDNSGateway`, ENSIP-17): returns the signed RRSets that prove a DNS record, in the shape `DNSRegistrar.proveAndClaim` and DNSSEC oracles accept. |
| `Abis.shared.erc1155` | 8 | 4 | 7 | [ERC-1155 Multi Token Standard](https://ethereum.org/en/developers/docs/standards/tokens/erc-1155) |
| `Abis.shared.erc165` | 1 | 0 | 0 | ERC-165 interface detection. |
| `Abis.shared.erc20` | 9 | 2 | 0 | [ERC-20 Token Standard](https://ethereum.org/en/developers/docs/standards/tokens/erc-20) |
| `Abis.shared.erc721` | 15 | 3 | 0 | [ERC-721 Non-Fungible Token Standard](https://ethereum.org/en/developers/docs/standards/tokens/erc-721) |
| `Abis.shared.errors` | 0 | 0 | 170 | Every custom error of the ENS contracts in this package (ENSv1 ens-contracts v1.7.0 and ENSv2 contracts-v2 v1.0.1, with mainnet's UserRegistry from `post-audit-2`), plus the OpenZeppelin `IERC20Errors` that ERC-20 payment tokens raise, the verifiable proxy's `InvalidUpgradeTarget`, the HCA's `NoNFTAllowed` (raised when a name token is sent to a Hosted Contract Account), the errors with which resolvers that keep their records elsewhere refuse on-chain writes (ERC-5559 `StorageHandledBy…`, ERC-7884 `OperationHandled…`) and the verifier and fetcher errors of unruggable gateways, which the L2 reverse resolvers raise for a proof that does not verify. |
| `Abis.shared.events` | 0 | 56 | 0 | The ENS events indexers consume, across ENSv1 and ENSv2: registry, registrar, NameWrapper, resolver, reverse and DNS registrar events, following the ENSv2 indexing guide. |
| `Abis.shared.extendedDnsResolver` | 1 | 0 | 0 | Extended DNS resolution profile with caller-provided context. |
| `Abis.shared.extendedResolver` | 1 | 0 | 0 | ENSIP-10 wildcard resolution profile. |
| `Abis.shared.hasAddressResolver` | 1 | 0 | 0 | Optional address-presence capability used by current ENS resolvers. |
| `Abis.shared.interfaceResolver` | 1 | 1 | 0 | ERC-165 interface implementer resolver profile. |
| `Abis.shared.multicallResolver` | 1 | 0 | 0 | Resolver-native batching used for resolving multiple records for one name. |
| `Abis.shared.nameResolver` | 1 | 1 | 0 | ENSIP-3 reverse name resolver profile. |
| `Abis.shared.pubkeyResolver` | 1 | 1 | 0 | SECP256k1 public key resolver profile. |
| `Abis.shared.textResolver` | 1 | 1 | 0 | ENSIP-5 text record resolver profile. |
| `Abis.shared.universalResolverFindResolver` | 1 | 0 | 0 | Resolver discovery shared by ENSv1 and ENSv2 Universal Resolvers. |
| `Abis.shared.versionableResolver` | 1 | 1 | 0 | Resolver profile that clears all records by bumping a version. |
## `Abis.v1` [#abisv1]
| ABI | Functions | Events | Errors | Description |
| --- | --- | --- | --- | --- |
| `Abis.v1.baseRegistrar` | 27 | 9 | 0 | Complete BaseRegistrarImplementation ABI from @ensdomains/ens-contracts v1.7.0. |
| `Abis.v1.bulkRenewal` | 4 | 0 | 0 | Complete BulkRenewal ABI from @ensdomains/ens-contracts v1.7.0. |
| `Abis.v1.defaultReverseRegistrar` | 10 | 3 | 3 | Complete DefaultReverseRegistrar ABI from @ensdomains/ens-contracts v1.7.0. |
| `Abis.v1.dnsRegistrar` | 11 | 2 | 6 | Complete DNSRegistrar ABI from @ensdomains/ens-contracts v1.7.0. |
| `Abis.v1.dnssecOracle` | 9 | 2 | 11 | Complete DNSSECImpl ABI from @ensdomains/ens-contracts v1.7.0. |
| `Abis.v1.ensRegistry` | 13 | 5 | 0 | Complete ENSRegistry ABI from @ensdomains/ens-contracts v1.7.0. |
| `Abis.v1.ethRegistrarController` | 21 | 3 | 11 | Complete ETHRegistrarController ABI from @ensdomains/ens-contracts v1.7.0. |
| `Abis.v1.exponentialPremiumPriceOracle` | 10 | 1 | 0 | Complete ExponentialPremiumPriceOracle ABI from @ensdomains/ens-contracts v1.7.0. |
| `Abis.v1.l2ReverseRegistrar` | 7 | 1 | 6 | Complete L2ReverseRegistrar ABI from @ensdomains/ens-contracts v1.7.0. |
| `Abis.v1.l2ReverseRegistrarWithMigration` | 11 | 2 | 8 | Complete L2ReverseRegistrarWithMigration ABI from @ensdomains/ens-contracts v1.7.0. |
| `Abis.v1.linearPremiumPriceOracle` | 12 | 1 | 0 | Complete LinearPremiumPriceOracle ABI from @ensdomains/ens-contracts v1.7.0. |
| `Abis.v1.nameWrapper` | 48 | 11 | 10 | Complete NameWrapper ABI from @ensdomains/ens-contracts v1.7.0. |
| `Abis.v1.nameWrapperUpgrade` | 1 | 0 | 0 | Migration receiver used when upgrading a wrapped V1 name. |
| `Abis.v1.offchainDnsResolver` | 6 | 0 | 4 | Complete OffchainDNSResolver ABI from @ensdomains/ens-contracts v1.7.0. |
| `Abis.v1.priceOracle` | 1 | 0 | 0 | Complete IPriceOracle ABI from @ensdomains/ens-contracts v1.7.0. |
| `Abis.v1.publicResolver` | 33 | 15 | 2 | Complete PublicResolver ABI from @ensdomains/ens-contracts v1.7.0. |
| `Abis.v1.reverseRegistrar` | 14 | 4 | 0 | Complete ReverseRegistrar ABI from @ensdomains/ens-contracts v1.7.0. |
| `Abis.v1.stablePriceOracle` | 9 | 1 | 0 | Complete StablePriceOracle ABI from @ensdomains/ens-contracts v1.7.0. |
| `Abis.v1.standaloneReverseRegistrar` | 2 | 1 | 0 | Complete StandaloneReverseRegistrar ABI from @ensdomains/ens-contracts v1.7.0. |
| `Abis.v1.staticBulkRenewal` | 3 | 0 | 0 | Complete StaticBulkRenewal ABI from @ensdomains/ens-contracts v1.7.0. |
| `Abis.v1.universalResolver` | 19 | 0 | 12 | Complete UniversalResolver ABI from @ensdomains/ens-contracts v1.7.0. |
| `Abis.v1.wrappedEthRegistrarController` | 20 | 3 | 9 | Complete WrappedETHRegistrarController ABI from @ensdomains/ens-contracts v1.7.0. |
## `Abis.v1.interfaces` [#abisv1interfaces]
| ABI | Functions | Events | Errors | Description |
| --- | --- | --- | --- | --- |
| `Abis.v1.interfaces.bulkRenewal` | 2 | 0 | 0 | Complete IBulkRenewal ABI from @ensdomains/ens-contracts v1.7.0. |
| `Abis.v1.interfaces.defaultReverseRegistrar` | 3 | 0 | 0 | Complete IDefaultReverseRegistrar ABI from @ensdomains/ens-contracts v1.7.0. |
| `Abis.v1.interfaces.dnsRegistrar` | 2 | 0 | 0 | Complete IDNSRegistrar ABI from @ensdomains/ens-contracts v1.7.0. |
| `Abis.v1.interfaces.dnssecOracle` | 3 | 2 | 0 | Complete DNSSEC ABI from @ensdomains/ens-contracts v1.7.0. |
| `Abis.v1.interfaces.ethRegistrarController` | 6 | 0 | 0 | Complete IETHRegistrarController ABI from @ensdomains/ens-contracts v1.7.0. |
| `Abis.v1.interfaces.l2ReverseRegistrar` | 4 | 0 | 0 | Complete IL2ReverseRegistrar ABI from @ensdomains/ens-contracts v1.7.0. |
| `Abis.v1.interfaces.linearPremiumPriceOracle` | 1 | 0 | 0 | Complete ILinearPremiumPriceOracle ABI from @ensdomains/ens-contracts v1.7.0. |
| `Abis.v1.interfaces.reverseRegistrar` | 7 | 0 | 0 | Complete IReverseRegistrar ABI from @ensdomains/ens-contracts v1.7.0. |
| `Abis.v1.interfaces.standaloneReverseRegistrar` | 1 | 1 | 0 | Complete IStandaloneReverseRegistrar ABI from @ensdomains/ens-contracts v1.7.0. |
## `Abis.v2` [#abisv2]
| ABI | Functions | Events | Errors | Description |
| --- | --- | --- | --- | --- |
| `Abis.v2.batchRegistrar` | 5 | 1 | 3 | Batch registration helper, deployed as `BatchRegistrar` (`.eth`) and `RootBatchRegistrar` (root). |
| `Abis.v2.boxedEnsUriRenderer` | 7 | 2 | 2 | Token URI renderer for names held in boxed (wrapped) registries. |
| `Abis.v2.contractNamer` | 9 | 5 | 10 | Upgradeable contract that sets reverse names for ENSv2 contracts (proxy plus implementation ABI). |
| `Abis.v2.defaultReverseRegistrarAdapter` | 7 | 0 | 3 | Adapter that sets the default (chain-independent) primary name for an account. |
| `Abis.v2.dnsAliasResolver` | 14 | 0 | 10 | Resolver that maps a DNS name onto an ENS name through a TXT alias record. |
| `Abis.v2.dnsTldResolver` | 24 | 1 | 10 | Resolver for DNS top-level domains that reads names imported via DNSSEC or TXT records. |
| `Abis.v2.dnsTxtResolver` | 5 | 0 | 4 | Resolver that answers ENS records from `ENS1` DNS TXT records. |
| `Abis.v2.dnssecGatewayProvider` | 5 | 1 | 2 | Gateway provider listing the CCIP-Read gateways that serve DNSSEC proofs. |
| `Abis.v2.ensUriRenderer` | 8 | 1 | 2 | Static token URI renderer for registry tokens. |
| `Abis.v2.ensV1Resolver` | 14 | 0 | 6 | Resolver that forwards resolution of unmigrated names to the ENSv1 registry. |
| `Abis.v2.ensV2Resolver` | 15 | 0 | 8 | Resolver that resolves names through the ENSv2 registry tree. |
| `Abis.v2.ethRegistrar` | 24 | 5 | 11 | Commit-reveal registrar for second-level `.eth` names. |
| `Abis.v2.ethRenewerV1` | 21 | 3 | 5 | Renewal controller that extends unmigrated ENSv1 `.eth` names. |
| `Abis.v2.graveyard` | 8 | 0 | 3 | Holder of ENSv1 tokens retired by migration. |
| `Abis.v2.labelStore` | 5 | 1 | 2 | Store mapping label hashes to their plaintext labels. |
| `Abis.v2.lockedMigrationController` | 19 | 2 | 6 | Migration controller for locked (fuse-burned) NameWrapper names. |
| `Abis.v2.migrationHelper` | 8 | 0 | 5 | Helper that batches ENSv1 to ENSv2 migrations. |
| `Abis.v2.permissionedAddressSet` | 16 | 2 | 8 | Role-managed address set, deployed as `PublicResolverSet`, `RegistryUpgradeSet` and `HCAUpgradeSet`. |
| `Abis.v2.permissionedRegistry` | 47 | 16 | 23 | Role-based registry, deployed as `RootRegistry` (top-level names) and `ETHRegistry` (`.eth` names). |
| `Abis.v2.permissionedResolver` | 36 | 14 | 21 | Implementation of the role-based ENSv2 resolver, deployed per user through the VerifiableFactory. |
| `Abis.v2.publicResolver` | 38 | 15 | 4 | Shared public resolver for ENSv2 names. |
| `Abis.v2.reverseRegistrarAdapter` | 7 | 0 | 3 | Adapter that sets the Ethereum primary name for an account. |
| `Abis.v2.standardRentPriceOracle` | 33 | 2 | 13 | Rent price oracle for `.eth` registrations and renewals. |
| `Abis.v2.temporaryDnsRegistrar` | 11 | 1 | 5 | Temporary registrar that claims DNS names into ENSv2 (mainnet only). |
| `Abis.v2.universalHelper` | 12 | 0 | 4 | Read helper for batched ENSv2 lookups (registries, resolvers, names). |
| `Abis.v2.universalResolver` | 28 | 0 | 19 | Universal Resolver implementation that resolves through ENSv2 with ENSv1 fallback. |
| `Abis.v2.universalResolverProxy` | 4 | 3 | 5 | Upgradeable Universal Resolver proxy, deployed as the public `0xeeee…eeee` proxy and the ENS-managed proxy behind it. |
| `Abis.v2.universalResolverV1` | 27 | 0 | 18 | Universal Resolver implementation that resolves through the ENSv1 registry only (mainnet only). |
| `Abis.v2.unlockedMigrationController` | 10 | 0 | 6 | Migration controller for unlocked ENSv1 names. |
| `Abis.v2.userRegistry` | 54 | 18 | 34 | Implementation of user-owned subname registries, deployed per name through the VerifiableFactory. |
| `Abis.v2.verifiableFactory` | 4 | 1 | 1 | Factory that deploys verifiable proxies for user registries and resolvers. |
| `Abis.v2.wrapperRegistry` | 67 | 18 | 40 | Implementation of registries for migrated NameWrapper names. |
## `Abis.v2.interfaces` [#abisv2interfaces]
| ABI | Functions | Events | Errors | Description |
| --- | --- | --- | --- | --- |
| `Abis.v2.interfaces.addressSet` | 1 | 0 | 0 | `IAddressSet` interface ABI at contracts-v2 v1.0.1. |
| `Abis.v2.interfaces.contractName` | 1 | 0 | 0 | `IContractName` interface ABI at contracts-v2 v1.0.1. |
| `Abis.v2.interfaces.contractNamer` | 1 | 0 | 0 | `IContractNamer` interface ABI at contracts-v2 v1.0.1. |
| `Abis.v2.interfaces.enhancedAccessControl` | 12 | 1 | 8 | `IEnhancedAccessControl` interface ABI at contracts-v2 v1.0.1. |
| `Abis.v2.interfaces.erc1155Singleton` | 8 | 4 | 0 | `IERC1155Singleton` interface ABI at contracts-v2 v1.0.1. |
| `Abis.v2.interfaces.ethRegistrar` | 12 | 3 | 6 | `IETHRegistrar` interface ABI at contracts-v2 v1.0.1. |
| `Abis.v2.interfaces.ethRenewer` | 6 | 1 | 2 | `IETHRenewer` interface ABI at contracts-v2 v1.0.1. |
| `Abis.v2.interfaces.l2ReverseRegistrar` | 6 | 0 | 0 | `IL2ReverseRegistrar` interface ABI at contracts-v2 v1.0.1. |
| `Abis.v2.interfaces.labelStore` | 2 | 1 | 0 | `ILabelStore` interface ABI at contracts-v2 v1.0.1. |
| `Abis.v2.interfaces.ownedRegistry` | 4 | 10 | 0 | `IOwnedRegistry` interface ABI at contracts-v2 v1.0.1. |
| `Abis.v2.interfaces.permissionedRegistry` | 45 | 16 | 16 | `IPermissionedRegistry` interface ABI at contracts-v2 v1.0.1. |
| `Abis.v2.interfaces.permissionedResolver` | 28 | 12 | 12 | `IPermissionedResolver` interface ABI at contracts-v2 v1.0.1. |
| `Abis.v2.interfaces.registry` | 3 | 10 | 0 | `IRegistry` interface ABI at contracts-v2 v1.0.1. |
| `Abis.v2.interfaces.registryEvents` | 0 | 10 | 0 | `IRegistryEvents` interface ABI at contracts-v2 v1.0.1. |
| `Abis.v2.interfaces.registryUriRenderer` | 1 | 0 | 0 | `IRegistryURIRenderer` interface ABI at contracts-v2 v1.0.1. |
| `Abis.v2.interfaces.rentPriceOracle` | 3 | 0 | 2 | `IRentPriceOracle` interface ABI at contracts-v2 v1.0.1. |
| `Abis.v2.interfaces.standardRegistry` | 21 | 14 | 4 | `IStandardRegistry` interface ABI at contracts-v2 v1.0.1. |
| `Abis.v2.interfaces.temporalRegistry` | 4 | 10 | 0 | `ITemporalRegistry` interface ABI at contracts-v2 v1.0.1. |
| `Abis.v2.interfaces.tokenizedRegistry` | 13 | 14 | 0 | `ITokenizedRegistry` interface ABI at contracts-v2 v1.0.1. |
| `Abis.v2.interfaces.universalResolver` | 7 | 0 | 6 | IUniversalResolverExtended ABI from the pinned ENSv2 snapshot. |
| `Abis.v2.interfaces.universalSignatureValidator` | 1 | 0 | 0 | `IUniversalSignatureValidator` interface ABI at contracts-v2 v1.0.1. |
| `Abis.v2.interfaces.wrapperRegistry` | 47 | 16 | 17 | `IWrapperRegistry` interface ABI at contracts-v2 v1.0.1. |
# Deployments
> For the complete documentation index, see [llms.txt](https://ensforge.com/llms.txt).
Look up ENS contract addresses per chain, the capability flags of each deployment and the Deployments helpers in @ensforge/contracts.
Source: https://ensforge.com/docs/reference/contracts/deployments
`Deployments` holds the address of every ENS contract per chain, for ENSv1 and ENSv2. ensforge picks the deployment from the client's chain. See [Addresses and chains](/docs/contracts/addresses-and-chains).
## mainnet (chain 1) [#mainnet-chain-1]
### ENSv2 (`mainnet-v2`, active) [#ensv2-mainnet-v2-active]
From https://github.com/ensdomains/contracts-v2 `v1.0.1`.
| Group | Contract | Address |
| --- | --- | --- |
| `contracts` | `universalResolver` | `0xeEeEEEeE14D718C2B47D9923Deab1335E144EeEe` |
| `contracts` | `universalHelper` | `0x46AE127D14683Ac74eF151e46ae2117A1A25C676` |
| `contracts` | `rootRegistry` | `0x2553c09bE6447BeFfdB86FA622ad41fB8f77A91e` |
| `contracts` | `ethRegistry` | `0xf60aba43E1f7F3DAB1186Ff03B561401C9Df85E2` |
| `contracts` | `ethRegistrar` | `0xD6D8369e55c94Ae8AFA714E6cF7AB5bE54D5CC81` |
| `contracts` | `rentPriceOracle` | `0x76F29609A363a8A1a2a6abe2e859C0F8916Af469` |
| `contracts` | `ensV2Resolver` | `0x3071AD643cE4Ed8b3D67b289845b45dB82b068A4` |
| `contracts` | `publicResolver` | `0x66f9F566fF2f26309C1Bd9134388478A801dA3e1` |
| `contracts` | `verifiableFactory` | `0x77510ba162dfeA3d8989E3f0928a691B345730D2` |
| `contracts` | `labelStore` | `0x31e5E081fe38d15B3E8214ba5Cb08dC4708B70Ba` |
| `contracts` | `contractNamer` | `0x5cDaF63d4C2a01218149DDe707E5bc239c68730c` |
| `contracts` | `reverseRegistrarAdapter` | `0x349151735790269a9C14668B58D7C83b5ecb9607` |
| `contracts` | `defaultReverseRegistrarAdapter` | `0xd86E32499eCAFe9c181dd7410f93A1a9bB61ef0d` |
| `implementations` | `universalResolver` | `0x06Fdd07F007ADaC667177b46aB2EB9A75132Cfd5` |
| `implementations` | `universalResolverV1` | `0x804bf0D289C8353a0BaFdAAF9069Ab14C92B2099` |
| `implementations` | `permissionedResolver` | `0x565b0F456a04Ac9b48758190e90030623Cff57C5` |
| `implementations` | `userRegistry` | `0x3269b830b61b3186Dc6d2f57Cab118E2FBC3E2df` |
| `implementations` | `wrapperRegistry` | `0xe86A4ef4d7A210aAA1d6A9594fC7Add7cD2Cf888` |
| `implementations` | `contractNamer` | `0x87d7CDffAfBe9826D978FBdBE3Ad45E7A4BF3D1C` |
| `migration` | `ensV1Resolver` | `0x394D8EB4a4fDF599384DeAb25F31d111d755c398` |
| `migration` | `ethRenewerV1` | `0x56c447F308F463A01121C41E72b0E7e7557fCb68` |
| `migration` | `unlockedMigrationController` | `0xaB821Ca676CF2e0790Fa273526a165CFa86aEB64` |
| `migration` | `lockedMigrationController` | `0x3ceA18620883a69ED349B23328A3B6302598e51A` |
| `migration` | `migrationHelper` | `0x6c8452AFc6043b5aF32eb345A8135108906F07ee` |
| `migration` | `graveyard` | `0xDa021A2C1C2F99574D861Ef8c6fA745851BEB7F6` |
| `migration` | `publicResolverSet` | `0xfFCedA021CBDF20f1a66ebbef32E49d208cAbf62` |
| `migration` | `registryUpgradeSet` | `0x573A73c0B3C0C90bB8BD728519434aF19Fb88935` |
| `infrastructure` | `ensUriRenderer` | `0x82CaC0d801b9A392a4fF217D5E68145801E90a41` |
| `infrastructure` | `boxedEnsUriRenderer` | `0x6f412Ff4144d525f791777d3384e9A1B170492Fb` |
| `infrastructure` | `managedUniversalResolverProxy` | `0xcFFd2Ae680CD110D28739a70922636B5937b022B` |
| `infrastructure` | `batchRegistrar` | `0xf0CcfBF6DbA1E01CCB833CED6d551A8F000E9721` |
| `infrastructure` | `rootBatchRegistrar` | `0xe467Ae049DDd65A21fb85B5f1dE5F7997a8Eb164` |
| `dns` | `tldResolver` | `0x6695327EE70F41151d2cBADC3ABBb6e4a58e739c` |
| `dns` | `legacyTldResolver` | `0xaB48304A2520CE420E636AaCD48A8bb3e7e485Ee` |
| `dns` | `aliasResolver` | `0x13285e928c65beFd90904F77A68FE4e7D9a43882` |
| `dns` | `txtResolver` | `0xbB76e2ae1a61Ef91D095eC044ABf563e4C464E3E` |
| `dns` | `gatewayProvider` | `0xA646BCEE466D77669A087f3379640CB03aCA7c3D` |
| `dns` | `temporaryRegistrar` | `0x9d6D535f08be25A9A2FdA1a1C21217D27d81cC61` |
| `hca` | `ownerAndSessionValidator` | `0xa818428ed2F3F949bdc71b8A15bDD7B5D27ce938` |
| `hca` | `upgradeSet` | `0x85E115F5b43c72e2BA4419a9A95e325dB18431c2` |
| `hca` | `standaloneFactory` | `0x742bf21897a78e2C98cC5f5C5473A370a081e561` |
| `hca` | `standaloneImplementation` | `0x116F462FA078ec0009e9b25DCd60309E70aaC4F4` |
| `hca` | `entryPoint` | `0x0000000071727De22E5E9d8BAf0edAc6f37da032` |
| `hca` | `intentExecutor` | `0x00000000005aD9ce1f5035FD62CA96CEf16AdAAF` |
| `hca` | `gasRefundPaymaster` | `0x1d7df6Ddc7328Ac827EB4D7f171C60AFB7f9A599` |
| `paymentTokens` | `dai` | `0x6B175474E89094C44Da98b954EedeAC495271d0F` |
| `paymentTokens` | `usdc` | `0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48` |
### ENSv1 (`mainnet-v1`, legacy) [#ensv1-mainnet-v1-legacy]
From https://github.com/ensdomains/ens-contracts `v1.7.0`.
| Group | Contract | Address |
| --- | --- | --- |
| `contracts` | `registry` | `0x00000000000C2E074eC69A0dFb2997BA6C7d2e1e` |
| `contracts` | `baseRegistrar` | `0x57f1887a8BF19b14fC0dF6Fd9B2acc9Af147eA85` |
| `contracts` | `ethRegistrarController` | `0x59E16fcCd424Cc24e280Be16E11Bcd56fb0CE547` |
| `contracts` | `wrappedEthRegistrarController` | `0x253553366Da8546fC250F225fe3d25d0C782303b` |
| `contracts` | `bulkRenewal` | `0xc649947a460B135e6B9a70Ee2FB429aDBB529290` |
| `contracts` | `priceOracle` | `0x7542565191d074cE84fBfA92cAE13AcB84788CA9` |
| `contracts` | `nameWrapper` | `0xD4416b13d2b3a9aBae7AcD5D6C2BbDBE25686401` |
| `contracts` | `publicResolver` | `0xF29100983E058B709F3D539b0c765937B804AC15` |
| `contracts` | `universalResolver` | `0xeEeEEEeE14D718C2B47D9923Deab1335E144EeEe` |
| `contracts` | `reverseRegistrar` | `0xa58E81fe9b61B5c3fE2AFD33CF304c454AbFc7Cb` |
| `contracts` | `defaultReverseRegistrar` | `0x283F227c4Bd38ecE252C4Ae7ECE650B0e913f1f9` |
| `contracts` | `dnsRegistrar` | `0xB32cB5677a7C971689228EC835800432B339bA2B` |
| `contracts` | `dnssecOracle` | `0x0fc3152971714E5ed7723FAFa650F86A4BaF30C5` |
| `contracts` | `offchainDnsResolver` | `0xF142B308cF687d4358410a4cB885513b30A42025` |
## sepolia (chain 11155111) [#sepolia-chain-11155111]
### ENSv2 (`sepolia-v2`, active) [#ensv2-sepolia-v2-active]
From https://github.com/ensdomains/contracts-v2 `v1.0.1`.
| Group | Contract | Address |
| --- | --- | --- |
| `contracts` | `universalResolver` | `0xeEeEEEeE14D718C2B47D9923Deab1335E144EeEe` |
| `contracts` | `universalHelper` | `0xd453e5Bdb62CC3beA84341B1e306319C8Ffd7DFe` |
| `contracts` | `rootRegistry` | `0xB458D6a3a77919449d03e7A6903C26827c1eC43f` |
| `contracts` | `ethRegistry` | `0xD4eBcbBdF463C9c45784603Db0dDD499BC44A8B4` |
| `contracts` | `ethRegistrar` | `0xf633e7FC17e2bbE0D0965D18ec1821dcB754a3d3` |
| `contracts` | `rentPriceOracle` | `0x8196665D4ca7488B6474a9EC8E7d2719FB42263A` |
| `contracts` | `ensV2Resolver` | `0x1cF3989ED3E5EC3cB1d731fC3777323813b61aCf` |
| `contracts` | `publicResolver` | `0xdC4a563d00F5c3012b699794eB9e13A561Be386F` |
| `contracts` | `verifiableFactory` | `0xDa70306C98E97eCe36F997a21368e53298572991` |
| `contracts` | `labelStore` | `0xed8246FF02203a4d4cb262bD78bEAA7408A57cAE` |
| `contracts` | `contractNamer` | `0x606f2453484f4Fa85b6E5FDB0E0bf777064bf9F3` |
| `contracts` | `reverseRegistrarAdapter` | `0x56Bce5E727FAa9D237341Bb5B9E8a03D5919779d` |
| `contracts` | `defaultReverseRegistrarAdapter` | `0x36f97328e843e37520cbF530e9402791c2754066` |
| `implementations` | `universalResolver` | `0x24E1D8e068620B647CA097f961A61055f4f42D72` |
| `implementations` | `permissionedResolver` | `0x115eb53F0c60696633855F90b138178Fb40b2b2C` |
| `implementations` | `userRegistry` | `0x0822d199699f0a9D378617817a1439663234a126` |
| `implementations` | `wrapperRegistry` | `0xBe768b63E5fBBFBB0Ae97E9064E0002dF8001880` |
| `implementations` | `contractNamer` | `0x4b8263BE7c522d8Fb3FBcA1F74B9C6e083B8D3e4` |
| `migration` | `ensV1Resolver` | `0x322B7581cA210a69c6D0e0D7c88a7688D2789Cb0` |
| `migration` | `ethRenewerV1` | `0xf2ece44980778966b8a0FccB3A9E339440f6e045` |
| `migration` | `unlockedMigrationController` | `0x2a35B94DF22cc7354570be2284655E2CDC0e64A2` |
| `migration` | `lockedMigrationController` | `0x6029a063d69b09D23c52a754a90E4FE43aDac3A8` |
| `migration` | `migrationHelper` | `0xA8F86EE5cdD28703bd876F3a8c10B1DE70f36899` |
| `migration` | `graveyard` | `0xB58A90a39D13CcE1D0E192B5da5c47640855B04D` |
| `migration` | `publicResolverSet` | `0x5B2bd5208dac31905106d8e5a4973Ae1Cd7414F2` |
| `migration` | `registryUpgradeSet` | `0xF0a6f68c28603bDF2881Ca17476Ee477C72cD2fE` |
| `infrastructure` | `ensUriRenderer` | `0x4D7f0349DfFB8e7BeD9fFBA1B9e45f7ECBD4f0f8` |
| `infrastructure` | `boxedEnsUriRenderer` | `0x0f5B101b6Fc626b9b210bB5E70f60F3dd9cA0d96` |
| `infrastructure` | `managedUniversalResolverProxy` | `0x6d80F2172CFdEc5730fE683860C33d26fC42e6F1` |
| `infrastructure` | `batchRegistrar` | `0x4A4c8B7CDAB6B19dc2CdB417cdB53a2ccBaf5322` |
| `infrastructure` | `rootBatchRegistrar` | `0x4CDEDc6B514A6bc9B64854DfE2D6849D5B1369a6` |
| `dns` | `tldResolver` | `0x0c9F5E9AE61165140b49919F0dF13C0a6642e80d` |
| `dns` | `aliasResolver` | `0xe30c9374929De41b71b6fb999B945553F2194c5F` |
| `dns` | `txtResolver` | `0x00263173B7De91594Eb4140Ad8dD3a723B8e4EB3` |
| `dns` | `gatewayProvider` | `0xd542a53982FDd0c456F02c5a54734c06073fA915` |
| `hca` | `ownerAndSessionValidator` | `0x4bF641590ab18E31B9F8789A3417A2620f860466` |
| `hca` | `upgradeSet` | `0xCde956D6E2949Bc25a4273F93E0db6f68A1a6f34` |
| `hca` | `standaloneFactory` | `0x6Bad0176236e97b346B5Dd13BCc8325B931EE8ab` |
| `hca` | `standaloneImplementation` | `0xC940e5C5bF263C0e097054AECf73826769A72CEE` |
| `hca` | `entryPoint` | `0x0000000071727De22E5E9d8BAf0edAc6f37da032` |
| `hca` | `intentExecutor` | `0x00000000005aD9ce1f5035FD62CA96CEf16AdAAF` |
| `hca` | `gasRefundPaymaster` | `0x1d7df6Ddc7328Ac827EB4D7f171C60AFB7f9A599` |
| `paymentTokens` | `dai` | `0xF6faC8A58a0BE13b9197f27C41B73162Fe32572b` |
| `paymentTokens` | `usdc` | `0x240b0316Df57887DBBE58b586508b19e633a14aa` |
### ENSv1 (`sepolia-v1`, legacy) [#ensv1-sepolia-v1-legacy]
From https://github.com/ensdomains/ens-contracts `v1.7.0`.
| Group | Contract | Address |
| --- | --- | --- |
| `contracts` | `registry` | `0x00000000000C2E074eC69A0dFb2997BA6C7d2e1e` |
| `contracts` | `baseRegistrar` | `0x57f1887a8BF19b14fC0dF6Fd9B2acc9Af147eA85` |
| `contracts` | `ethRegistrarController` | `0xfb3cE5D01e0f33f41DbB39035dB9745962F1f968` |
| `contracts` | `bulkRenewal` | `0x6394b694a8C0DC716e447802E568F0Fb2c4E0965` |
| `contracts` | `priceOracle` | `0x6810DbCE73C67506f785A225F818b30D8f209AAb` |
| `contracts` | `nameWrapper` | `0x0635513f179D50A207757E05759CbD106d7dFcE8` |
| `contracts` | `publicResolver` | `0xE99638b40E4Fff0129D56f03b55b6bbC4BBE49b5` |
| `contracts` | `universalResolver` | `0xeEeEEEeE14D718C2B47D9923Deab1335E144EeEe` |
| `contracts` | `reverseRegistrar` | `0xA0a1AbcDAe1a2a4A2EF8e9113Ff0e02DD81DC0C6` |
| `contracts` | `defaultReverseRegistrar` | `0x4F382928805ba0e23B30cFB75fC9E848e82DFD47` |
| `contracts` | `dnsRegistrar` | `0x5a07C75Ae469Bf3ee2657B588e8E6ABAC6741b4f` |
| `contracts` | `dnssecOracle` | `0xe62E4b6cE018Ad6e916fcC24545e20a33b9d8653` |
| `contracts` | `offchainDnsResolver` | `0x179Be112b24Ad4cFC392eF8924DfA08C20Ad8583` |
## Capabilities [#capabilities]
Deployments differ in some behaviours; ensforge reads these flags instead of the chain ID.
| Capability | mainnet | sepolia | Description |
| --- | --- | --- | --- |
| `resolutionErrorWrapping` | `true` | `false` | Resolution contracts wrap registry reverts in `ResolutionError(address,bytes)` and reject foreign `OffchainLookup` senders with `InvalidOffchainLookup()`. |
| `wrapperRegistryInitializer` | `fuse-derived` | `explicit` | How WrapperRegistry `initialize` receives its label and roles: passed `explicit`ly (`initialize(bytes32,address,string,uint256)`) or `fuse-derived` from NameWrapper fuses (`initialize(bytes32,address)`). |
| `wrapperRegistryEmancipation` | `role-derived` | `static` | How WrapperRegistry `isEmancipated` is computed: `static` (always `true`) or `role-derived` (from the unemancipated role bitmap). |
| `lockedMigrationRenewal` | `max-expiry` | `renew-role` | How locked migration treats names with `CAN_EXTEND_EXPIRY`: grant the `renew-role`, or set the expiry to `max-expiry` (`type(uint64).max`). |
| `userRegistryUpgradeGate` | `true` | `true` | User registries only upgrade to implementations approved by `UPGRADE_SET()`. |
| `userRegistryRootRenewal` | `true` | `false` | Registries running `implementations.userRegistry` check the `renew` role at their root only (contracts-v2 #505, mainnet since 2026-11-17). Every other registry, including those created on an earlier UserRegistry implementation, also accepts it on the name. |
| `hcaSameChainSourceRejected` | `true` | `false` | The HCA validator rejects permits whose source chain is the current chain. |
| `hcaSessionDomain` | `smart-session` | `smart-session` | EIP-712 domain HCA session approvals are signed under: Rhinestone's `smart-session` domain (contracts-v2 v1.0.1), or a dedicated `hca` domain (contracts-v2 #498, not deployed). |
| `hcaContractOwners` | `false` | `false` | HCA owners can be contracts that sign with ERC-1271 (contracts-v2 #499, not deployed). |
## L2 reverse registrars [#l2-reverse-registrars]
| Chain ID | Address |
| --- | --- |
| 10 | `0x0000000000D8e504002cC26E3Ec46D81971C1664` |
| 8453 | `0x0000000000D8e504002cC26E3Ec46D81971C1664` |
| 42161 | `0x0000000000D8e504002cC26E3Ec46D81971C1664` |
| 59141 | `0x00000BeEF055f7934784D6d81b6BC86665630dbA` |
| 59144 | `0x0000000000D8e504002cC26E3Ec46D81971C1664` |
| 84532 | `0x00000BeEF055f7934784D6d81b6BC86665630dbA` |
| 421614 | `0x00000BeEF055f7934784D6d81b6BC86665630dbA` |
| 534351 | `0x00000BeEF055f7934784D6d81b6BC86665630dbA` |
| 534352 | `0x0000000000D8e504002cC26E3Ec46D81971C1664` |
| 11155420 | `0x00000BeEF055f7934784D6d81b6BC86665630dbA` |
## API [#api]
### `Deployments.InvalidProfileError` [#deploymentsinvalidprofileerror]
Thrown by `define` with every problem found in a profile.
```ts
class InvalidProfileError
```
| Field | Type | Description |
| --- | --- | --- |
| `name` | `unknown` | |
| `_tag` | `unknown` | |
| `issues` | `readonly string[]` | |
### `Deployments.Profile` [#deploymentsprofile]
Every ENS deployment on one chain.
```ts
interface Profile
```
| Field | Type | Description |
| --- | --- | --- |
| `name` | `string` | Network name, e.g. `mainnet`. |
| `chainId` | `number` | |
| `v1` (optional) | `V1` | |
| `v2` (optional) | `V2` | |
### `Deployments.Provenance` [#deploymentsprovenance]
Where the addresses of a deployment come from.
```ts
interface Provenance
```
| Field | Type | Description |
| --- | --- | --- |
| `repository` | `string` | Source repository of the deployed contracts. |
| `release` | `string` | Release tag the addresses were taken from, e.g. `v1.0.1`. |
| `commit` | `string` | Commit of the release tag. |
| `builds` (optional) | `{ readonly default: string; readonly overrides: Readonly>; }` | Compiler builds of the live contracts. ENSv2 networks mix builds because contracts were redeployed individually; `overrides` maps contracts-v2 deployment names to their build. |
| `documentation` (optional) | `string` | Human-readable deployment documentation. |
### `Deployments.Status` [#deploymentsstatus]
Lifecycle of a deployment: `active` is the current protocol on that chain, `legacy` is kept for
compatibility and migration, `beta` is not yet recommended for production names.
```ts
type Status = "active" | "beta" | "legacy";
```
### `Deployments.V1` [#deploymentsv1]
An ENSv1 deployment.
```ts
interface V1
```
| Field | Type | Description |
| --- | --- | --- |
| `id` | `string` | Stable identifier, e.g. `mainnet-v1`. |
| `chainId` | `number` | |
| `protocol` | `"v1"` | |
| `status` | `Status` | |
| `contracts` | `V1Contracts` | |
| `legacyPublicResolvers` (optional) | `readonly Address[]` | Earlier ENS PublicResolver generations, still used by many names. They authorize writes the same way, through the current registry. Newest first; `contracts.publicResolver` is not listed. |
| `frozenPublicResolvers` (optional) | `readonly Address[]` | ENS PublicResolvers bound to the registry that ENS replaced in 2020. Their records can be read but no longer changed; the oldest store raw `content` instead of `contenthash`. |
| `provenance` (optional) | `Provenance` | |
### `Deployments.V1Contracts` [#deploymentsv1contracts]
ENSv1 contract addresses.
```ts
interface V1Contracts
```
| Field | Type | Description |
| --- | --- | --- |
| `registry` | `Address` | ENS registry. |
| `baseRegistrar` | `Address` | `.eth` ERC-721 registrar. |
| `ethRegistrarController` | `Address` | Current `.eth` registrar controller. |
| `wrappedEthRegistrarController` (optional) | `Address` | Previous `.eth` controller that registers names directly into the NameWrapper. |
| `bulkRenewal` | `Address` | Batch renewal helper. |
| `priceOracle` | `Address` | `.eth` rent price oracle. |
| `nameWrapper` | `Address` | NameWrapper (ERC-1155 wrapped names and fuses). |
| `publicResolver` | `Address` | Current public resolver. |
| `universalResolver` | `Address` | Universal Resolver proxy. |
| `reverseRegistrar` | `Address` | Reverse registrar for `addr.reverse`. |
| `defaultReverseRegistrar` | `Address` | Reverse registrar for `default.reverse`. |
| `dnsRegistrar` | `Address` | DNSSEC registrar for DNS names. |
| `dnssecOracle` | `Address` | DNSSEC oracle. |
| `offchainDnsResolver` | `Address` | Off-chain DNS resolver (gasless DNSSEC). |
### `Deployments.V2` [#deploymentsv2]
An ENSv2 deployment.
```ts
interface V2
```
| Field | Type | Description |
| --- | --- | --- |
| `id` | `string` | Stable identifier, e.g. `mainnet-v2`. |
| `chainId` | `number` | |
| `protocol` | `"v2"` | |
| `status` | `Status` | |
| `contracts` | `V2Contracts` | |
| `implementations` | `V2Implementations` | |
| `migration` | `V2Migration` | |
| `infrastructure` | `V2Infrastructure` | |
| `dns` (optional) | `V2Dns` | |
| `hca` (optional) | `V2Hca` | |
| `paymentTokens` (optional) | `V2PaymentTokens` | |
| `capabilities` | `Capabilities` | |
| `provenance` (optional) | `Provenance` | |
### `Deployments.V2Contracts` [#deploymentsv2contracts]
ENSv2 entry points that applications call directly.
```ts
interface V2Contracts
```
| Field | Type | Description |
| --- | --- | --- |
| `universalResolver` | `Address` | Public Universal Resolver proxy (`0xeeee…eeee` on mainnet and Sepolia). |
| `universalHelper` | `Address` | Batched read helper for registries, resolvers and names. |
| `rootRegistry` | `Address` | Root registry holding top-level names. |
| `ethRegistry` | `Address` | Registry holding second-level `.eth` names. |
| `ethRegistrar` | `Address` | Commit-reveal `.eth` registrar. |
| `rentPriceOracle` | `Address` | `.eth` rent price oracle. |
| `ensV2Resolver` | `Address` | Resolver that resolves through the ENSv2 registry tree. |
| `publicResolver` | `Address` | Shared public resolver. |
| `verifiableFactory` | `Address` | Factory for per-name user registries and per-user resolvers. |
| `labelStore` | `Address` | Label hash to label store. |
| `contractNamer` | `Address` | Reverse-name setter for ENSv2 contracts (proxy). |
| `reverseRegistrarAdapter` | `Address` | Ethereum primary name adapter. |
| `defaultReverseRegistrarAdapter` | `Address` | Default (chain-independent) primary name adapter. |
### `Deployments.V2Dns` [#deploymentsv2dns]
ENSv2 DNS integration contracts.
```ts
interface V2Dns
```
| Field | Type | Description |
| --- | --- | --- |
| `tldResolver` | `Address` | Resolver for DNS top-level domains. |
| `legacyTldResolver` (optional) | `Address` | An earlier DNSTLDResolver the root registry still points DNS TLDs at, when ENS has not switched over to `tldResolver` yet (mainnet, contracts-v2 v1.0.1). |
| `aliasResolver` | `Address` | Resolver mapping DNS names onto ENS names through TXT aliases. |
| `txtResolver` | `Address` | Resolver answering from `ENS1` TXT records. |
| `gatewayProvider` | `Address` | Gateway provider for DNSSEC proofs. |
| `temporaryRegistrar` (optional) | `Address` | Registrar that claims DNS names into ENSv2 (mainnet only). |
### `Deployments.V2Hca` [#deploymentsv2hca]
**Experimental**
Hosted contract account (HCA) contracts.
```ts
interface V2Hca
```
| Field | Type | Description |
| --- | --- | --- |
| `ownerAndSessionValidator` | `Address` | Owner signature and session key validator. |
| `upgradeSet` | `Address` | Set of approved HCA implementation upgrades. |
| `standaloneFactory` | `Address` | Standalone HCA factory. |
| `standaloneImplementation` | `Address` | Single-owner standalone HCA implementation. |
| `entryPoint` | `Address` | ERC-4337 EntryPoint (v0.7) the HCA accepts UserOperations from. |
| `intentExecutor` | `Address` | Rhinestone IntentExecutor, the only caller whose session signatures the validator accepts. |
| `gasRefundPaymaster` | `Address` | Paymaster that reimburses intent execution from the session's refund token. |
### `Deployments.V2Implementations` [#deploymentsv2implementations]
ENSv2 implementation contracts that proxies and factory deployments point to.
```ts
interface V2Implementations
```
| Field | Type | Description |
| --- | --- | --- |
| `universalResolver` | `Address` | Universal Resolver implementation behind the managed proxy. |
| `universalResolverV1` (optional) | `Address` | ENSv1-only Universal Resolver implementation kept as a fallback target. |
| `permissionedResolver` | `Address` | PermissionedResolver implementation for factory-deployed resolvers. |
| `userRegistry` | `Address` | UserRegistry implementation for factory-deployed subname registries. |
| `wrapperRegistry` | `Address` | WrapperRegistry implementation for migrated NameWrapper names. |
| `contractNamer` | `Address` | ContractNamer implementation. |
### `Deployments.V2Infrastructure` [#deploymentsv2infrastructure]
ENSv2 supporting infrastructure.
```ts
interface V2Infrastructure
```
| Field | Type | Description |
| --- | --- | --- |
| `ensUriRenderer` (optional) | `Address` | Static token URI renderer. |
| `boxedEnsUriRenderer` (optional) | `Address` | Token URI renderer for boxed registries. |
| `managedUniversalResolverProxy` (optional) | `Address` | ENS-managed Universal Resolver proxy behind the public proxy. |
| `batchRegistrar` | `Address` | Batch registration helper for `.eth`. |
| `rootBatchRegistrar` | `Address` | Batch registration helper for the root registry. |
### `Deployments.V2Migration` [#deploymentsv2migration]
ENSv1 to ENSv2 migration contracts.
```ts
interface V2Migration
```
| Field | Type | Description |
| --- | --- | --- |
| `ensV1Resolver` | `Address` | Resolver that forwards unmigrated names to ENSv1. |
| `ethRenewerV1` | `Address` | Renewal controller for unmigrated ENSv1 `.eth` names. |
| `unlockedMigrationController` | `Address` | Migration controller for unlocked names. |
| `lockedMigrationController` | `Address` | Migration controller for locked NameWrapper names (a proxy on mainnet). |
| `migrationHelper` | `Address` | Batched migration helper. |
| `graveyard` | `Address` | Holder of retired ENSv1 tokens. |
| `publicResolverSet` | `Address` | Set of resolvers treated as public resolvers during migration. |
| `registryUpgradeSet` | `Address` | Set of registry implementations user registries may upgrade to. |
### `Deployments.V2PaymentTokens` [#deploymentsv2paymenttokens]
ERC-20 tokens the `.eth` registrar accepts: real stablecoins on mainnet, mocks on testnets.
The rent price oracle (`isPaymentToken`) stays the source of truth.
```ts
interface V2PaymentTokens
```
| Field | Type | Description |
| --- | --- | --- |
| `dai` | `Address` | |
| `usdc` | `Address` | |
### `Deployments.define` [#deploymentsdefine]
Validates a custom profile (a devnet, a fork or a chain ensforge does not ship) and returns it
unchanged.
```ts
function define(profile: profile): profile
```
Checks that the chain IDs agree, that every required contract group and address is present and
well-formed, and that every capability flag has a known value. It does not read the chain.
```ts title="Defining a devnet profile"
import { Deployments } from "@ensforge/contracts"
const devnet = Deployments.define({
name: "devnet",
chainId: 31337,
v2: { ...devnetAddresses, capabilities: Deployments.mainnet.v2.capabilities },
})
```
Errors:
- `` `Deployments.InvalidProfileError` listing every problem found.
### `Deployments.get` [#deploymentsget]
Returns the built-in profile for a chain, or `undefined` when ensforge ships none.
```ts
function get(options: { readonly chainId: number }): Profile | undefined
```
```ts title="Looking up the connected chain"
import { Deployments } from "@ensforge/contracts"
const profile = Deployments.get({ chainId: await client.getChainId() })
const registry = profile?.v1?.contracts.registry
```
### `Deployments.l2ReverseRegistrars` [#deploymentsl2reverseregistrars]
The ENSv1 `L2ReverseRegistrar` (ens-contracts v1.7.0) of each chain it is deployed on, by chain
ID: where an address sets its primary name for that chain (`.reverse`). Its ABI is
`Abis.v1.l2ReverseRegistrar`. Every mainnet L2 shares one address, and every testnet another,
so one signed name claim covers all of them.
### `Deployments.list` [#deploymentslist]
Lists the built-in profiles.
```ts
function list(): readonly Profile[]
```
```ts title="Listing supported chains"
import { Deployments } from "@ensforge/contracts"
const chainIds = Deployments.list().map((profile) => profile.chainId)
```
### `Deployments.mainnet` [#deploymentsmainnet]
ENSv1 and ENSv2 on Ethereum mainnet.
### `Deployments.sepolia` [#deploymentssepolia]
ENSv1 (legacy) and ENSv2 on Sepolia.
# Entry points
> For the complete documentation index, see [llms.txt](https://ensforge.com/llms.txt).
Look up what each import path of @ensforge/contracts exports, so you can import single constants from a subpath and keep bundles small.
Source: https://ensforge.com/docs/reference/contracts/entry-points
Import the namespaces from `@ensforge/contracts`, or single constants from a subpath to keep bundles small.
## `@ensforge/contracts` [#ensforgecontracts]
`Abis`, `Deployments`, `InterfaceIds`, `Roles`
## `@ensforge/contracts/shared` [#ensforgecontractsshared]
`abiResolverAbi`, `abiResolverInterfaceId`, `addrResolverAbi`, `addrResolverInterfaceId`, `addressResolverAbi`, `addressResolverInterfaceId`, `contenthashResolverAbi`, `contenthashResolverInterfaceId`, `dataResolverAbi`, `dataResolverInterfaceId`, `dnsRecordResolverAbi`, `dnsRecordResolverInterfaceId`, `dnsZoneResolverAbi`, `dnsZoneResolverInterfaceId`, `dnssecGatewayAbi`, `ensErrorsAbi`, `ensEventsAbi`, `erc1155Abi`, `erc165Abi`, `erc165InterfaceId`, `erc20Abi`, `erc721Abi`, `extendedDnsResolverAbi`, `extendedDnsResolverInterfaceId`, `extendedResolverAbi`, `extendedResolverInterfaceId`, `hasAddressResolverAbi`, `hasAddressResolverInterfaceId`, `interfaceResolverAbi`, `interfaceResolverInterfaceId`, `multicallResolverAbi`, `nameResolverAbi`, `nameResolverInterfaceId`, `pubkeyResolverAbi`, `pubkeyResolverInterfaceId`, `textResolverAbi`, `textResolverInterfaceId`, `universalResolverFindResolverAbi`, `versionableResolverAbi`, `versionableResolverInterfaceId`
## `@ensforge/contracts/v1` [#ensforgecontractsv1]
`NameWrapperFuse`, `baseRegistrarV1Abi`, `bulkRenewalV1Abi`, `bulkRenewalV1InterfaceAbi`, `defaultReverseRegistrarV1Abi`, `defaultReverseRegistrarV1InterfaceAbi`, `dnsRegistrarV1Abi`, `dnsRegistrarV1InterfaceAbi`, `dnssecOracleV1Abi`, `dnssecOracleV1InterfaceAbi`, `ensRegistryV1Abi`, `ethRegistrarControllerV1Abi`, `ethRegistrarControllerV1InterfaceAbi`, `exponentialPremiumPriceOracleV1Abi`, `l2ReverseRegistrarV1Abi`, `l2ReverseRegistrarV1InterfaceAbi`, `l2ReverseRegistrarWithMigrationV1Abi`, `linearPremiumPriceOracleV1Abi`, `linearPremiumPriceOracleV1InterfaceAbi`, `nameWrapperFuses`, `nameWrapperUpgradeV1Abi`, `nameWrapperV1Abi`, `offchainDnsResolverV1Abi`, `priceOracleV1Abi`, `publicResolverV1Abi`, `reverseRegistrarV1Abi`, `reverseRegistrarV1InterfaceAbi`, `stablePriceOracleV1Abi`, `standaloneReverseRegistrarV1Abi`, `standaloneReverseRegistrarV1InterfaceAbi`, `staticBulkRenewalV1Abi`, `universalResolverV1Abi`, `wrappedEthRegistrarControllerV1Abi`
## `@ensforge/contracts/v2` [#ensforgecontractsv2]
`RegistryInterfaceId`, `RegistryRole`, `ResolverInterfaceId`, `ResolverRole`, `addressSetV2InterfaceAbi`, `batchRegistrarV2Abi`, `boxedEnsUriRendererV2Abi`, `contractNameV2InterfaceAbi`, `contractNamerV2Abi`, `contractNamerV2InterfaceAbi`, `defaultReverseRegistrarAdapterV2Abi`, `dnsAliasResolverV2Abi`, `dnsTldResolverV2Abi`, `dnsTxtResolverV2Abi`, `dnssecGatewayProviderV2Abi`, `enhancedAccessControlRoles`, `enhancedAccessControlV2InterfaceAbi`, `ensUriRendererV2Abi`, `ensV1ResolverV2Abi`, `ensV2ResolverV2Abi`, `erc1155SingletonV2InterfaceAbi`, `ethRegistrarV2Abi`, `ethRegistrarV2InterfaceAbi`, `ethRenewerV1Abi`, `ethRenewerV2InterfaceAbi`, `graveyardV2Abi`, `l2ReverseRegistrarV2InterfaceAbi`, `labelStoreV2Abi`, `labelStoreV2InterfaceAbi`, `lockedMigrationControllerV2Abi`, `migrationHelperV2Abi`, `migrationUserRegistrySalt`, `ownedRegistryV2InterfaceAbi`, `ownedResolverSalt`, `permissionedAddressSetV2Abi`, `permissionedRegistryV2Abi`, `permissionedRegistryV2InterfaceAbi`, `permissionedResolverResource`, `permissionedResolverV2Abi`, `permissionedResolverV2InterfaceAbi`, `predictVerifiableProxyAddress`, `publicResolverV2Abi`, `registryEventsV2InterfaceAbi`, `registryInterfaceIds`, `registryRoleBitmaps`, `registryRoles`, `registryUriRendererV2InterfaceAbi`, `registryV2InterfaceAbi`, `rentPriceOracleV2InterfaceAbi`, `resolverInterfaceIds`, `resolverRoles`, `reverseRegistrarAdapterV2Abi`, `standardRegistryV2InterfaceAbi`, `standardRentPriceOracleV2Abi`, `temporalRegistryV2InterfaceAbi`, `temporaryDnsRegistrarV2Abi`, `tokenizedRegistryV2InterfaceAbi`, `universalHelperV2Abi`, `universalResolverProxyV2Abi`, `universalResolverV1V2Abi`, `universalResolverV2Abi`, `universalResolverV2InterfaceAbi`, `universalSignatureValidatorV2InterfaceAbi`, `unlockedMigrationControllerV2Abi`, `userRegistryV2Abi`, `verifiableFactoryV2Abi`, `wrapperRegistryInitializableInterfaceIds`, `wrapperRegistryV2Abi`, `wrapperRegistryV2InterfaceAbi`
## `@ensforge/contracts/v2/experimental/hca` [#ensforgecontractsv2experimentalhca]
Experimental: can change in a minor release.
`HcaSessionTerms`, `hcaAccountId`, `hcaAuthorizerV2Abi`, `hcaDeploymentSalt`, `hcaFundingSessionValidatorV2Abi`, `hcaOwnableSessionValidator`, `hcaOwnerAndSessionValidatorV2Abi`, `hcaSessionApprovalDigest`, `hcaSessionDigest`, `hcaSessionDomain`, `hcaSessionPermissionId`, `hcaSessionSalt`, `hcaSessionTypedData`, `hcaSessionTypes`, `hcaSignedSession`, `hcaSmartSessionEmissary`, `standaloneHcaFactoryV2Abi`, `standaloneHcaFactoryV2InterfaceAbi`, `standaloneHcaOwnerV2InterfaceAbi`, `standaloneSingleOwnerHcaV2Abi`
# Contracts
> For the complete documentation index, see [llms.txt](https://ensforge.com/llms.txt).
Look up the ENS ABIs, contract addresses per chain, interface IDs and roles that @ensforge/contracts exports, with no dependency on the SDK.
Source: https://ensforge.com/docs/reference/contracts
Runtime-neutral ENS ABIs, addresses and constants, with no dependency on the SDK.
# Interface IDs
> For the complete documentation index, see [llms.txt](https://ensforge.com/llms.txt).
Look up the ERC-165 interface IDs of ENS registries, resolvers and resolver profiles that ensforge checks before it reads or writes.
Source: https://ensforge.com/docs/reference/contracts/interface-ids
`InterfaceIds` holds the ERC-165 interface IDs ensforge checks before it reads or writes. See [Interface IDs and roles](/docs/contracts/interface-ids-and-roles).
## `InterfaceIds.erc165` [#interfaceidserc165]
ERC-165 interface ID of `supportsInterface(bytes4)`.
| Constant | Value |
| --- | --- |
| `InterfaceIds.erc165` | `0x01ffc9a7` |
## `InterfaceIds.registry` [#interfaceidsregistry]
ERC-165 interface IDs of the ENSv2 registry interfaces, verified against contracts-v2 v1.0.1.
| Constant | Value |
| --- | --- |
| `InterfaceIds.registry.registry` | `0x51f67f40` |
| `InterfaceIds.registry.ownedRegistry` | `0x63560a8e` |
| `InterfaceIds.registry.permissionedRegistry` | `0xc18bd555` |
| `InterfaceIds.registry.standardRegistry` | `0xb844ab6c` |
| `InterfaceIds.registry.temporalRegistry` | `0x6f537c72` |
| `InterfaceIds.registry.tokenizedRegistry` | `0x91b3c037` |
| `InterfaceIds.registry.wrapperRegistry` | `0xf5586a0b` |
## `InterfaceIds.resolver` [#interfaceidsresolver]
ERC-165 interface IDs of the ENSv2 resolver interfaces, verified against contracts-v2 v1.0.1.
| Constant | Value |
| --- | --- |
| `InterfaceIds.resolver.permissionedResolver` | `0x8c2427cc` |
| `InterfaceIds.resolver.permissionedResolverInitializable` | `0x33cc44a0` |
## `InterfaceIds.resolverProfiles` [#interfaceidsresolverprofiles]
| Constant | Value |
| --- | --- |
| `InterfaceIds.resolverProfiles.abi` | `0x2203ab56` |
| `InterfaceIds.resolverProfiles.addr` | `0x3b3b57de` |
| `InterfaceIds.resolverProfiles.address` | `0xf1cb7e06` |
| `InterfaceIds.resolverProfiles.contenthash` | `0xbc1c58d1` |
| `InterfaceIds.resolverProfiles.data` | `0xecbfada3` |
| `InterfaceIds.resolverProfiles.dnsRecord` | `0xa8fa5682` |
| `InterfaceIds.resolverProfiles.dnsZone` | `0x5c98042b` |
| `InterfaceIds.resolverProfiles.extended` | `0x9061b923` |
| `InterfaceIds.resolverProfiles.extendedDns` | `0x8ef98a7e` |
| `InterfaceIds.resolverProfiles.hasAddress` | `0x32f111d7` |
| `InterfaceIds.resolverProfiles.interface` | `0x124a319c` |
| `InterfaceIds.resolverProfiles.name` | `0x691f3431` |
| `InterfaceIds.resolverProfiles.pubkey` | `0xc8690233` |
| `InterfaceIds.resolverProfiles.text` | `0x59d1d43c` |
| `InterfaceIds.resolverProfiles.versionable` | `0xd700ff33` |
## `InterfaceIds.wrapperRegistryInitializable` [#interfaceidswrapperregistryinitializable]
ERC-165 interface IDs of `IWrapperRegistryInitializable`, keyed like the `wrapperRegistryInitializer` capability: `explicit` for `initialize(bytes32,address,string,uint256)` (Sepolia) and `fuseDerived` for `initialize(bytes32,address)` (mainnet).
| Constant | Value |
| --- | --- |
| `InterfaceIds.wrapperRegistryInitializable.explicit` | `0x1542c01a` |
| `InterfaceIds.wrapperRegistryInitializable.fuseDerived` | `0x6910e334` |
# Roles
> For the complete documentation index, see [llms.txt](https://ensforge.com/llms.txt).
Look up the ENSv2 role bitmaps of registries and resolvers, with the admin role that may grant and revoke each one and how to combine them.
Source: https://ensforge.com/docs/reference/contracts/roles
`Roles` holds the ENSv2 role bitmaps. Each role has an admin role that may grant and revoke it. See [Interface IDs and roles](/docs/contracts/interface-ids-and-roles).
## `Roles.enhancedAccessControl` [#rolesenhancedaccesscontrol]
EnhancedAccessControl masks covering every role and every admin role.
| Constant | Value |
| --- | --- |
| `Roles.enhancedAccessControl.allRoles` | `0x1111111111111111111111111111111111111111111111111111111111111111` |
| `Roles.enhancedAccessControl.adminRoles` | `0x1111111111111111111111111111111100000000000000000000000000000000` |
## `Roles.registry` [#rolesregistry]
Registry roles from contracts-v2 v1.0.1 `RegistryRolesLib`.
| Constant | Value |
| --- | --- |
| `Roles.registry.registrar` | `0x1` |
| `Roles.registry.registrarAdmin` | `0x100000000000000000000000000000000` |
| `Roles.registry.registerReserved` | `0x10` |
| `Roles.registry.registerReservedAdmin` | `0x1000000000000000000000000000000000` |
| `Roles.registry.setParent` | `0x100` |
| `Roles.registry.setParentAdmin` | `0x10000000000000000000000000000000000` |
| `Roles.registry.unregister` | `0x1000` |
| `Roles.registry.unregisterAdmin` | `0x100000000000000000000000000000000000` |
| `Roles.registry.renew` | `0x10000` |
| `Roles.registry.renewAdmin` | `0x1000000000000000000000000000000000000` |
| `Roles.registry.setSubregistry` | `0x100000` |
| `Roles.registry.setSubregistryAdmin` | `0x10000000000000000000000000000000000000` |
| `Roles.registry.setResolver` | `0x1000000` |
| `Roles.registry.setResolverAdmin` | `0x100000000000000000000000000000000000000` |
| `Roles.registry.canTransfer` | `0x10000000` |
| `Roles.registry.canTransferAdmin` | `0x1000000000000000000000000000000000000000` |
| `Roles.registry.wasReserved` | `0x100000000` |
| `Roles.registry.setUri` | `0x1000000000` |
| `Roles.registry.setUriAdmin` | `0x100000000000000000000000000000000000000000` |
| `Roles.registry.canName` | `0x1000000000000000000000000000000` |
| `Roles.registry.canNameAdmin` | `0x100000000000000000000000000000000000000000000000000000000000000` |
| `Roles.registry.upgrade` | `0x10000000000000000000000000000000` |
| `Roles.registry.upgradeAdmin` | `0x1000000000000000000000000000000000000000000000000000000000000000` |
## `Roles.registryBitmaps` [#rolesregistrybitmaps]
Registry role sets from contracts-v2 v1.0.1 `RegistryRolesLib`.
| Constant | Value |
| --- | --- |
| `Roles.registryBitmaps.unemancipated` | `0x1110100000000000000000000000000001101000` |
| `Roles.registryBitmaps.regeneration` | `0x1110100000000000000000000000000011101000` |
| `Roles.registryBitmaps.registration` | `0x1110000000000000000000000000000001100000` |
## `Roles.resolver` [#rolesresolver]
PermissionedResolver roles from contracts-v2 v1.0.1 `PermissionedResolverLib`.
| Constant | Value |
| --- | --- |
| `Roles.resolver.setAddr` | `0x1` |
| `Roles.resolver.setAddrAdmin` | `0x100000000000000000000000000000000` |
| `Roles.resolver.setText` | `0x10` |
| `Roles.resolver.setTextAdmin` | `0x1000000000000000000000000000000000` |
| `Roles.resolver.setContenthash` | `0x100` |
| `Roles.resolver.setContenthashAdmin` | `0x10000000000000000000000000000000000` |
| `Roles.resolver.setAbi` | `0x1000` |
| `Roles.resolver.setAbiAdmin` | `0x100000000000000000000000000000000000` |
| `Roles.resolver.setInterface` | `0x10000` |
| `Roles.resolver.setInterfaceAdmin` | `0x1000000000000000000000000000000000000` |
| `Roles.resolver.setName` | `0x100000` |
| `Roles.resolver.setNameAdmin` | `0x10000000000000000000000000000000000000` |
| `Roles.resolver.link` | `0x10000000` |
| `Roles.resolver.linkAdmin` | `0x1000000000000000000000000000000000000000` |
| `Roles.resolver.setData` | `0x1000000` |
| `Roles.resolver.setDataAdmin` | `0x100000000000000000000000000000000000000` |
| `Roles.resolver.canName` | `0x1000000000000000000000000000000` |
| `Roles.resolver.canNameAdmin` | `0x100000000000000000000000000000000000000000000000000000000000000` |
| `Roles.resolver.upgrade` | `0x10000000000000000000000000000000` |
| `Roles.resolver.upgradeAdmin` | `0x1000000000000000000000000000000000000000000000000000000000000000` |
# Entry points
> For the complete documentation index, see [llms.txt](https://ensforge.com/llms.txt).
Find every import path of every ensforge package, what each one exports, and how stable it is, so you import only what you use.
Source: https://ensforge.com/docs/reference/entry-points
Each package exposes a few import paths (subpath exports). Import from these paths only; anything
else is private and can change in any release.
## Stability [#stability]
Every export carries one of three stability levels.
| Level | Promise |
| ------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Stable | Breaking changes only in a major release, after a deprecation in a minor one. |
| Experimental | A complete feature whose design may still change with the protocol or services it depends on. Breaking changes can land in a minor release, described in its changelog. |
| Unstable | Building blocks for adapters and extension packages. Can change or be removed in any minor release, described in its changelog. |
Patch releases never break any level.
## `@ensforge/sdk` [#ensforgesdk]
| Import path | Exports | Stability |
| ------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------- |
| `@ensforge/sdk` | `Ensforge` (`create`, `from`, `is`, client types), `Actions` (every action and `Actions.batch`), `ensActions()` and one decorator per action group (`recordActions()`, `nameActions()`, …, `batchActions()`, `indexerActions()`), `Errors`, `Plan`, the types `Read`, `Write` and `Request`, and the utilities `Name`, `CoinType`, `ContentHash`, `Duration`, `Fuse` and `Role`. | Stable |
| `@ensforge/sdk/actions` | The same actions as `Actions`, as one named export per group (`record`, `name`, `registration`, …) plus `batch`: `import { record } from "@ensforge/sdk/actions"`. | Stable |
| `@ensforge/sdk/effect` | The Effect API: `Actions` returning Effects, `Ensforge` with the `Ensforge.Ensforge` service and `Ensforge.layer`, `Errors`, `Plan`, the utilities, `Name.Normalized` (a schema) and `Indexer` (`Indexer.define`, `Indexer.paginate` as a `Stream`). No decorators. | Stable |
| `@ensforge/sdk/indexer` | `bigname()`, `goldsky()`, `fallback()`, `defineIndexer()`, `paginate()`, `indexerActions()`, and the indexer query and result types. | Stable |
| `@ensforge/sdk/wagmi` | `Ensforge`, with everything from the root `Ensforge` plus `Ensforge.fromWagmi(config, options)`. Needs `wagmi` 2.14 or later, or wagmi 3. | Stable |
| `@ensforge/sdk/extension` | Building blocks for packages that add action groups, such as `@ensforge/hca`: action builders, route helpers, plan helpers. | Unstable |
Every path except `@ensforge/sdk/effect` can be used without writing Effect code; their types never
mention Effect. See [Ways to call actions](/docs/sdk/ways-to-call-actions).
## `@ensforge/react` [#ensforgereact]
| Import path | Exports | Stability |
| ------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------- |
| `@ensforge/react` | `EnsforgeProvider`, `useEnsforge`, the generic hooks (`useRead`, `useReads`, `useSuspenseRead`, `useInfiniteRead`, `useWrite`, `usePrepare`), the named hooks (`useAddress`, `useName`, `useRegister`, …), `ReadErrorResetBoundary`, `useReadErrorReset`. Also re-exports the atom layer and `HydrationBoundary`. | Stable, except the atom layer and `HydrationBoundary` (unstable) |
| `@ensforge/react/atoms` | The atom layer: `ensAtom`, `ensWriteAtom`, `ensPagesAtom`, `invalidate`, `readKey`, `optionsKey`. | Unstable |
| `@ensforge/react/server` | `prefetch` and `dehydrate`, for server rendering. | Unstable |
See [React](/docs/react).
## `@ensforge/hca` [#ensforgehca]
| Import path | Exports | Stability |
| ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------ |
| `@ensforge/hca` | `hca()` (a route for `via`), the executors `owner()`, `bundler()`, `pimlico()`, `rhinestone()`, `defineExecutor()`, `Actions`, `hcaActions()`, `hcaAdminActions()`, `HcaError`. | Experimental |
| `@ensforge/hca/effect` | `Actions` returning Effects, and `HcaError`. | Experimental |
See [HCA](/docs/hca).
## `@ensforge/contracts` [#ensforgecontracts]
| Import path | Exports | Stability |
| ----------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------- |
| `@ensforge/contracts` | `Abis` (ENSv1, ENSv2 and shared ABIs), `Deployments` (`mainnet`, `sepolia`, `get`, `list`, `define`, …), `InterfaceIds`, `Roles`. | Stable, except `Deployments.V2Hca` (experimental) |
| `@ensforge/contracts/shared` | ABIs and interface IDs shared by both versions, as flat constants (`textResolverAbi`, …). | Stable |
| `@ensforge/contracts/v1` | ENSv1 ABIs as flat constants, and the Name Wrapper fuses. | Stable |
| `@ensforge/contracts/v2` | ENSv2 ABIs as flat constants, role bits, interface IDs and salts. | Stable |
| `@ensforge/contracts/v2/experimental/hca` | HCA ABIs and session helpers. | Experimental |
See [Contracts](/docs/contracts).
## Paths not to import [#paths-not-to-import]
Every package also has `internal/*` paths. They exist only inside the ensforge repository, for its
tests, and are not published. Import paths not listed on this page do not exist in the published
packages.
# COMMITMENT_EXISTS
> For the complete documentation index, see [llms.txt](https://ensforge.com/llms.txt).
What COMMITMENT_EXISTS means, why CommitmentError throws it, what to show users and how to fix it in ensforge. Also covers retry safety.
Source: https://ensforge.com/docs/reference/errors/COMMITMENT_EXISTS
## What happened [#what-happened]
An unexpired commitment with the same data already exists.
## What to show users [#what-to-show-users]
| Title | Message | Action |
| --- | --- | --- |
| Already started | A registration for this name is already in progress. | |
## Retry safety [#retry-safety]
Retrying the same call fails the same way until the cause is fixed (`retryable: false`).
## Actions that throw it [#actions-that-throw-it]
| Action | When |
| --- | --- |
| [`registration.commit`](/docs/reference/sdk/registration/commit) | for a resumed commitment outside its window. |
| [`registration.register`](/docs/reference/sdk/registration/register) | for a resumed commitment outside its window. |
## Catch it [#catch-it]
`Errors.hasCode("COMMITMENT_EXISTS")` narrows to this error. See [Handle errors](/docs/sdk/handle-errors).
# COMMITMENT_NOT_FOUND
> For the complete documentation index, see [llms.txt](https://ensforge.com/llms.txt).
What COMMITMENT_NOT_FOUND means, why CommitmentError throws it, what to show users and how to fix it in ensforge. Also covers retry safety.
Source: https://ensforge.com/docs/reference/errors/COMMITMENT_NOT_FOUND
## What happened [#what-happened]
No commitment was found for this registration.
## What to show users [#what-to-show-users]
| Title | Message | Action |
| --- | --- | --- |
| Registration not started | The first registration step was not found. | Start the registration again. |
## How to fix [#how-to-fix]
Commit first with registration.commit or registration.register.
## Retry safety [#retry-safety]
Retrying the same call fails the same way until the cause is fixed (`retryable: false`).
## Actions that throw it [#actions-that-throw-it]
No action names this code in its documented errors.
## Catch it [#catch-it]
`Errors.hasCode("COMMITMENT_NOT_FOUND")` narrows to this error. See [Handle errors](/docs/sdk/handle-errors).
# COMMITMENT_TOO_NEW
> For the complete documentation index, see [llms.txt](https://ensforge.com/llms.txt).
What COMMITMENT_TOO_NEW means, why CommitmentError throws it, what to show users and how to fix it in ensforge. Also covers retry safety.
Source: https://ensforge.com/docs/reference/errors/COMMITMENT_TOO_NEW
## What happened [#what-happened]
The registration commitment is not ready yet.
## What to show users [#what-to-show-users]
| Title | Message | Action |
| --- | --- | --- |
| Almost ready | Registration needs a short wait after the first step. | Wait a minute, then continue. |
## How to fix [#how-to-fix]
Wait for the minimum commitment age, then register.
## Retry safety [#retry-safety]
Retrying the same call can succeed (`retryable: true`).
## Actions that throw it [#actions-that-throw-it]
| Action | When |
| --- | --- |
| [`registration.commit`](/docs/reference/sdk/registration/commit) | for a resumed commitment outside its window. |
| [`registration.register`](/docs/reference/sdk/registration/register) | for a resumed commitment outside its window. |
## Catch it [#catch-it]
`Errors.hasCode("COMMITMENT_TOO_NEW")` narrows to this error. See [Handle errors](/docs/sdk/handle-errors).
# COMMITMENT_TOO_OLD
> For the complete documentation index, see [llms.txt](https://ensforge.com/llms.txt).
What COMMITMENT_TOO_OLD means, why CommitmentError throws it, what to show users and how to fix it in ensforge. Also covers retry safety.
Source: https://ensforge.com/docs/reference/errors/COMMITMENT_TOO_OLD
## What happened [#what-happened]
The registration commitment has expired.
## What to show users [#what-to-show-users]
| Title | Message | Action |
| --- | --- | --- |
| Registration expired | Too much time passed since the first step. | Start the registration again. |
## How to fix [#how-to-fix]
Commit again, then register.
## Retry safety [#retry-safety]
Retrying the same call fails the same way until the cause is fixed (`retryable: false`).
## Actions that throw it [#actions-that-throw-it]
| Action | When |
| --- | --- |
| [`registration.commit`](/docs/reference/sdk/registration/commit) | for a resumed commitment outside its window. |
| [`registration.register`](/docs/reference/sdk/registration/register) | for a resumed commitment outside its window. |
## Catch it [#catch-it]
`Errors.hasCode("COMMITMENT_TOO_OLD")` narrows to this error. See [Handle errors](/docs/sdk/handle-errors).
# CommitmentError
> For the complete documentation index, see [llms.txt](https://ensforge.com/llms.txt).
What CommitmentError means, which codes it carries and how to catch it in ensforge. A .eth commit-reveal registration step is out of order or out of time.
Source: https://ensforge.com/docs/reference/errors/commitment-error
A `.eth` commit-reveal registration step is out of order or out of time.
## Fields [#fields]
| Field | Type | Description |
| --- | --- | --- |
| `commitment` | `Hex` | Hash of the commitment the step concerns, when known. |
| `readyAt` | `bigint` | Unix time (seconds) from which `register` succeeds. |
| `expiresAt` | `bigint` | Unix time (seconds) after which the commitment is too old. |
## Codes [#codes]
| Code | Meaning | Retryable |
| --- | --- | --- |
| [`COMMITMENT_TOO_NEW`](/docs/reference/errors/COMMITMENT_TOO_NEW) | The registration commitment is not ready yet. | Yes |
| [`COMMITMENT_TOO_OLD`](/docs/reference/errors/COMMITMENT_TOO_OLD) | The registration commitment has expired. | No |
| [`COMMITMENT_EXISTS`](/docs/reference/errors/COMMITMENT_EXISTS) | An unexpired commitment with the same data already exists. | No |
| [`COMMITMENT_NOT_FOUND`](/docs/reference/errors/COMMITMENT_NOT_FOUND) | No commitment was found for this registration. | No |
## Catch it [#catch-it]
`Effect.catchTag("CommitmentError", …)` or `error instanceof Errors.CommitmentError`. See [Handle errors](/docs/sdk/handle-errors).
# CCIP_READ_DISABLED
> For the complete documentation index, see [llms.txt](https://ensforge.com/llms.txt).
What CCIP_READ_DISABLED means, why ConfigError throws it, what to show users and how to fix it in ensforge. Also covers retry safety.
Source: https://ensforge.com/docs/reference/errors/CCIP_READ_DISABLED
## What happened [#what-happened]
This name resolves off-chain, and CCIP-Read is disabled.
## What to show users [#what-to-show-users]
| Title | Message | Action |
| --- | --- | --- |
| Off-chain name | This name is stored off-chain, and off-chain lookups are turned off. | |
## How to fix [#how-to-fix]
Remove `ccipRead: false` from Ensforge.create.
## Retry safety [#retry-safety]
Retrying the same call fails the same way until the cause is fixed (`retryable: false`).
## Actions that throw it [#actions-that-throw-it]
| Action | When |
| --- | --- |
| [`resolver.resolve`](/docs/reference/sdk/resolver/resolve) | for off-chain names when CCIP-Read is disabled. |
Any action can fail with `ConfigError`: it is part of `Errors.CommonError`.
## Catch it [#catch-it]
`Errors.hasCode("CCIP_READ_DISABLED")` narrows to this error. See [Handle errors](/docs/sdk/handle-errors).
# CHAIN_NOT_CONFIGURED
> For the complete documentation index, see [llms.txt](https://ensforge.com/llms.txt).
What CHAIN_NOT_CONFIGURED means, why ConfigError throws it, what to show users and how to fix it in ensforge. Also covers retry safety.
Source: https://ensforge.com/docs/reference/errors/CHAIN_NOT_CONFIGURED
## What happened [#what-happened]
The client has no clients for chain ?.
## What to show users [#what-to-show-users]
| Title | Message | Action |
| --- | --- | --- |
| Network not set up | This app is not set up for that network. | |
## How to fix [#how-to-fix]
Add chain \ to `chains` in Ensforge.create, e.g. `chains: { : { publicClient, walletClient } }`.
## Retry safety [#retry-safety]
Retrying the same call fails the same way until the cause is fixed (`retryable: false`).
## Actions that throw it [#actions-that-throw-it]
| Action | When |
| --- | --- |
| [`primaryName.set`](/docs/reference/sdk/primary-name/set) | for an L2 that is not in the client's `chains`. |
Any action can fail with `ConfigError`: it is part of `Errors.CommonError`.
## Catch it [#catch-it]
`Errors.hasCode("CHAIN_NOT_CONFIGURED")` narrows to this error. See [Handle errors](/docs/sdk/handle-errors).
# CONTRACT_NOT_DEPLOYED
> For the complete documentation index, see [llms.txt](https://ensforge.com/llms.txt).
What CONTRACT_NOT_DEPLOYED means, why ConfigError throws it, what to show users and how to fix it in ensforge. Also covers retry safety.
Source: https://ensforge.com/docs/reference/errors/CONTRACT_NOT_DEPLOYED
## What happened [#what-happened]
No contract is deployed at the called address.
## What to show users [#what-to-show-users]
| Title | Message | Action |
| --- | --- | --- |
| Network mismatch | The ENS contracts were not found on this network. | Check that your wallet is on the right network. |
## How to fix [#how-to-fix]
Check that the client's chain matches the deployment profile.
## Retry safety [#retry-safety]
Retrying the same call fails the same way until the cause is fixed (`retryable: false`).
## Actions that throw it [#actions-that-throw-it]
No action names this code in its documented errors.
Any action can fail with `ConfigError`: it is part of `Errors.CommonError`.
## Catch it [#catch-it]
`Errors.hasCode("CONTRACT_NOT_DEPLOYED")` narrows to this error. See [Handle errors](/docs/sdk/handle-errors).
# INDEXER_NOT_CONFIGURED
> For the complete documentation index, see [llms.txt](https://ensforge.com/llms.txt).
What INDEXER_NOT_CONFIGURED means, why ConfigError throws it, what to show users and how to fix it in ensforge. Also covers retry safety.
Source: https://ensforge.com/docs/reference/errors/INDEXER_NOT_CONFIGURED
## What happened [#what-happened]
This action needs an indexer.
## What to show users [#what-to-show-users]
| Title | Message | Action |
| --- | --- | --- |
| Search unavailable | Name data is not available in this app. | |
## How to fix [#how-to-fix]
Pass an indexer to Ensforge.create, e.g. `indexer: bigname()` from @ensforge/sdk/indexer.
## Retry safety [#retry-safety]
Retrying the same call fails the same way until the cause is fixed (`retryable: false`).
## Actions that throw it [#actions-that-throw-it]
| Action | When |
| --- | --- |
| [`indexer.getEvents`](/docs/reference/sdk/indexer/get-events) | when the client has no indexer. |
| [`indexer.getHistory`](/docs/reference/sdk/indexer/get-history) | when the client has no indexer. |
| [`indexer.getName`](/docs/reference/sdk/indexer/get-name) | when the client has no indexer. |
| [`indexer.getNamesByExpiry`](/docs/reference/sdk/indexer/get-names-by-expiry) | when the client has no indexer. |
| [`indexer.getNamesForAddress`](/docs/reference/sdk/indexer/get-names-for-address) | when the client has no indexer. |
| [`indexer.getNamespace`](/docs/reference/sdk/indexer/get-namespace) | when the client has no indexer. |
| [`indexer.getPermissions`](/docs/reference/sdk/indexer/get-permissions) | when the client has no indexer. |
| [`indexer.getPrimaryName`](/docs/reference/sdk/indexer/get-primary-name) | when the client has no indexer. |
| [`indexer.getRecords`](/docs/reference/sdk/indexer/get-records) | when the client has no indexer. |
| [`indexer.getRegistry`](/docs/reference/sdk/indexer/get-registry) | when the client has no indexer. |
| [`indexer.getRegistryLabels`](/docs/reference/sdk/indexer/get-registry-labels) | when the client has no indexer. |
| [`indexer.getResolver`](/docs/reference/sdk/indexer/get-resolver) | when the client has no indexer. |
| [`indexer.getResolverLinks`](/docs/reference/sdk/indexer/get-resolver-links) | when the client has no indexer. |
| [`indexer.getResolverRoles`](/docs/reference/sdk/indexer/get-resolver-roles) | when the client has no indexer. |
| [`indexer.getResolvers`](/docs/reference/sdk/indexer/get-resolvers) | when the client has no indexer. |
| [`indexer.getStatus`](/docs/reference/sdk/indexer/get-status) | when the client has no indexer. |
| [`indexer.getSubnames`](/docs/reference/sdk/indexer/get-subnames) | when the client has no indexer. |
| [`indexer.lookup`](/docs/reference/sdk/indexer/lookup) | when the client has no indexer. |
| [`indexer.search`](/docs/reference/sdk/indexer/search) | when the client has no indexer. |
Any action can fail with `ConfigError`: it is part of `Errors.CommonError`.
## Catch it [#catch-it]
`Errors.hasCode("INDEXER_NOT_CONFIGURED")` narrows to this error. See [Handle errors](/docs/sdk/handle-errors).
# INVALID_ACTION_GROUP
> For the complete documentation index, see [llms.txt](https://ensforge.com/llms.txt).
What INVALID_ACTION_GROUP means, why ConfigError throws it, what to show users and how to fix it in ensforge. Also covers retry safety.
Source: https://ensforge.com/docs/reference/errors/INVALID_ACTION_GROUP
## What happened [#what-happened]
A decorator added an action group with a reserved name.
## What to show users [#what-to-show-users]
| Title | Message | Action |
| --- | --- | --- |
| Configuration problem | This app is misconfigured. | |
## How to fix [#how-to-fix]
Rename the group; chain, account, deployment, publicClient, config and extend are reserved.
## Retry safety [#retry-safety]
Retrying the same call fails the same way until the cause is fixed (`retryable: false`).
## Actions that throw it [#actions-that-throw-it]
No action names this code in its documented errors.
Any action can fail with `ConfigError`: it is part of `Errors.CommonError`.
## Catch it [#catch-it]
`Errors.hasCode("INVALID_ACTION_GROUP")` narrows to this error. See [Handle errors](/docs/sdk/handle-errors).
# INVALID_DEPLOYMENT
> For the complete documentation index, see [llms.txt](https://ensforge.com/llms.txt).
What INVALID_DEPLOYMENT means, why ConfigError throws it, what to show users and how to fix it in ensforge. Also covers retry safety.
Source: https://ensforge.com/docs/reference/errors/INVALID_DEPLOYMENT
## What happened [#what-happened]
The deployment profile is invalid.
## What to show users [#what-to-show-users]
| Title | Message | Action |
| --- | --- | --- |
| Configuration problem | This app is misconfigured for ENS. | |
## How to fix [#how-to-fix]
Check the issues listed in the cause; Deployments.define reports every problem.
## Retry safety [#retry-safety]
Retrying the same call fails the same way until the cause is fixed (`retryable: false`).
## Actions that throw it [#actions-that-throw-it]
No action names this code in its documented errors.
Any action can fail with `ConfigError`: it is part of `Errors.CommonError`.
## Catch it [#catch-it]
`Errors.hasCode("INVALID_DEPLOYMENT")` narrows to this error. See [Handle errors](/docs/sdk/handle-errors).
# UNKNOWN_CHAIN
> For the complete documentation index, see [llms.txt](https://ensforge.com/llms.txt).
What UNKNOWN_CHAIN means, why ConfigError throws it, what to show users and how to fix it in ensforge. Also covers retry safety and the actions that throw it.
Source: https://ensforge.com/docs/reference/errors/UNKNOWN_CHAIN
## What happened [#what-happened]
ensforge has no ENS deployment for this chain.
## What to show users [#what-to-show-users]
| Title | Message | Action |
| --- | --- | --- |
| Network not supported | ENS is not available on this network. | Switch to Ethereum mainnet or Sepolia. |
## How to fix [#how-to-fix]
Pass `deployment` to Ensforge.create, e.g. Deployments.define(\{ name, chainId, v2 \}).
## Retry safety [#retry-safety]
Retrying the same call fails the same way until the cause is fixed (`retryable: false`).
## Actions that throw it [#actions-that-throw-it]
No action names this code in its documented errors.
Any action can fail with `ConfigError`: it is part of `Errors.CommonError`.
## Catch it [#catch-it]
`Errors.hasCode("UNKNOWN_CHAIN")` narrows to this error. See [Handle errors](/docs/sdk/handle-errors).
# WALLET_NOT_CONFIGURED
> For the complete documentation index, see [llms.txt](https://ensforge.com/llms.txt).
What WALLET_NOT_CONFIGURED means, why ConfigError throws it, what to show users and how to fix it in ensforge. Also covers retry safety.
Source: https://ensforge.com/docs/reference/errors/WALLET_NOT_CONFIGURED
## What happened [#what-happened]
This action needs a wallet client with an account.
## What to show users [#what-to-show-users]
| Title | Message | Action |
| --- | --- | --- |
| Wallet not connected | Connect a wallet to continue. | Connect your wallet. |
## How to fix [#how-to-fix]
Pass `walletClient` to Ensforge.create, or `account` to the action.
## Retry safety [#retry-safety]
Retrying the same call fails the same way until the cause is fixed (`retryable: false`).
## Actions that throw it [#actions-that-throw-it]
| Action | When |
| --- | --- |
| [`permission.check`](/docs/reference/sdk/permission/check) | without `account` or a client account. |
| [`permission.get`](/docs/reference/sdk/permission/get) | without `account` or a client account. |
| [`primaryName.set`](/docs/reference/sdk/primary-name/set) | when no signing account is known. |
| [`primaryName.signClaim`](/docs/reference/sdk/primary-name/sign-claim) | when no signing account is known. |
| [`record.set`](/docs/reference/sdk/record/set) | when the client has no wallet. |
| [`registration.commit`](/docs/reference/sdk/registration/commit) | when no signing account is known. |
| [`registration.register`](/docs/reference/sdk/registration/register) | when no signing account is known. |
| [`registration.renew`](/docs/reference/sdk/registration/renew) | when no signing account is known. |
| [`registry.deploy`](/docs/reference/sdk/registry/deploy) | when no signing account is known. |
| [`registry.upgrade`](/docs/reference/sdk/registry/upgrade) | when no signing account is known. |
| [`resolver.create`](/docs/reference/sdk/resolver/create) | when no account is known to predict the address. |
| [`subname.create`](/docs/reference/sdk/subname/create) | when no signing account is known. |
| [`subname.remove`](/docs/reference/sdk/subname/remove) | when no signing account is known. |
Any action can fail with `ConfigError`: it is part of `Errors.CommonError`.
## Catch it [#catch-it]
`Errors.hasCode("WALLET_NOT_CONFIGURED")` narrows to this error. See [Handle errors](/docs/sdk/handle-errors).
# ConfigError
> For the complete documentation index, see [llms.txt](https://ensforge.com/llms.txt).
What ConfigError means, which codes it carries and how to catch it in ensforge. The ensforge client or a call is configured incorrectly.
Source: https://ensforge.com/docs/reference/errors/config-error
The ensforge client or a call is configured incorrectly. Fix the code; retrying does not help.
Any action can fail with `ConfigError`: it is part of `Errors.CommonError`.
## Codes [#codes]
| Code | Meaning | Retryable |
| --- | --- | --- |
| [`UNKNOWN_CHAIN`](/docs/reference/errors/UNKNOWN_CHAIN) | ensforge has no ENS deployment for this chain. | No |
| [`INVALID_DEPLOYMENT`](/docs/reference/errors/INVALID_DEPLOYMENT) | The deployment profile is invalid. | No |
| [`CONTRACT_NOT_DEPLOYED`](/docs/reference/errors/CONTRACT_NOT_DEPLOYED) | No contract is deployed at the called address. | No |
| [`WALLET_NOT_CONFIGURED`](/docs/reference/errors/WALLET_NOT_CONFIGURED) | This action needs a wallet client with an account. | No |
| [`INDEXER_NOT_CONFIGURED`](/docs/reference/errors/INDEXER_NOT_CONFIGURED) | This action needs an indexer. | No |
| [`CCIP_READ_DISABLED`](/docs/reference/errors/CCIP_READ_DISABLED) | This name resolves off-chain, and CCIP-Read is disabled. | No |
| [`INVALID_ACTION_GROUP`](/docs/reference/errors/INVALID_ACTION_GROUP) | A decorator added an action group with a reserved name. | No |
| [`CHAIN_NOT_CONFIGURED`](/docs/reference/errors/CHAIN_NOT_CONFIGURED) | The client has no clients for chain ?. | No |
## Catch it [#catch-it]
`Effect.catchTag("ConfigError", …)` or `error instanceof Errors.ConfigError`. See [Handle errors](/docs/sdk/handle-errors).
# CONTRACT_REVERTED
> For the complete documentation index, see [llms.txt](https://ensforge.com/llms.txt).
What CONTRACT_REVERTED means, why ContractRevertError throws it, what to show users and how to fix it in ensforge. Also covers retry safety.
Source: https://ensforge.com/docs/reference/errors/CONTRACT_REVERTED
## What happened [#what-happened]
The contract call reverted.
## What to show users [#what-to-show-users]
| Title | Message | Action |
| --- | --- | --- |
| Transaction would fail | The network rejected this action. | |
## Retry safety [#retry-safety]
Retrying the same call fails the same way until the cause is fixed (`retryable: false`).
## Actions that throw it [#actions-that-throw-it]
| Action | When |
| --- | --- |
| [`plan.resume`](/docs/reference/sdk/plan/resume) | , or the failing step's own error (`Errors.AnyError`: a plan can hold any step), with `context.planId` and `context.step`. |
| [`plan.send`](/docs/reference/sdk/plan/send) | , or the failing step's own error (`Errors.AnyError`: a plan can hold any step), with `context.planId` and `context.step`. |
Any action can fail with `ContractRevertError`: it is part of `Errors.CommonError`.
## Catch it [#catch-it]
`Errors.hasCode("CONTRACT_REVERTED")` narrows to this error. See [Handle errors](/docs/sdk/handle-errors).
# ContractRevertError
> For the complete documentation index, see [llms.txt](https://ensforge.com/llms.txt).
What ContractRevertError means, which codes it carries and how to catch it in ensforge. Lists its fields and every code.
Source: https://ensforge.com/docs/reference/errors/contract-revert-error
A contract reverted with an error ensforge does not map to a more specific class.
Any action can fail with `ContractRevertError`: it is part of `Errors.CommonError`.
## Fields [#fields]
| Field | Type | Description |
| --- | --- | --- |
| `errorName` | `string` | Decoded error name, e.g. `InvalidRecord`, when the ABI knows it. |
| `args` | `readonly unknown[]` | |
| `data` | `Hex` | Raw revert data. |
## Codes [#codes]
| Code | Meaning | Retryable |
| --- | --- | --- |
| [`CONTRACT_REVERTED`](/docs/reference/errors/CONTRACT_REVERTED) | The contract call reverted. | No |
## Catch it [#catch-it]
`Effect.catchTag("ContractRevertError", …)` or `error instanceof Errors.ContractRevertError`. See [Handle errors](/docs/sdk/handle-errors).
# DNSSEC_PROOF_FAILED
> For the complete documentation index, see [llms.txt](https://ensforge.com/llms.txt).
What DNSSEC_PROOF_FAILED means, why DnsError throws it, what to show users and how to fix it in ensforge. Also covers retry safety.
Source: https://ensforge.com/docs/reference/errors/DNSSEC_PROOF_FAILED
## What happened [#what-happened]
The DNSSEC proof could not be built or verified.
## What to show users [#what-to-show-users]
| Title | Message | Action |
| --- | --- | --- |
| DNSSEC problem | Your domain's DNSSEC setup could not be verified. | Check that DNSSEC is enabled at your DNS provider. |
## How to fix [#how-to-fix]
Check that DNSSEC is enabled for the domain.
## Retry safety [#retry-safety]
Retrying the same call fails the same way until the cause is fixed (`retryable: false`).
## Actions that throw it [#actions-that-throw-it]
| Action | When |
| --- | --- |
| [`dns.claim`](/docs/reference/sdk/dns/claim) | when the name cannot be proven. |
## Catch it [#catch-it]
`Errors.hasCode("DNSSEC_PROOF_FAILED")` narrows to this error. See [Handle errors](/docs/sdk/handle-errors).
# DNS_RECORD_MISSING
> For the complete documentation index, see [llms.txt](https://ensforge.com/llms.txt).
What DNS_RECORD_MISSING means, why DnsError throws it, what to show users and how to fix it in ensforge. Also covers retry safety and the actions that throw it.
Source: https://ensforge.com/docs/reference/errors/DNS_RECORD_MISSING
## What happened [#what-happened]
The `_ens` TXT record is missing.
## What to show users [#what-to-show-users]
| Title | Message | Action |
| --- | --- | --- |
| DNS record missing | The required DNS TXT record was not found. | Add the TXT record at your DNS provider, then retry. |
## How to fix [#how-to-fix]
Add a TXT record `_ens.` with the value "a=\".
## Retry safety [#retry-safety]
Retrying the same call fails the same way until the cause is fixed (`retryable: false`).
## Actions that throw it [#actions-that-throw-it]
| Action | When |
| --- | --- |
| [`dns.claim`](/docs/reference/sdk/dns/claim) | when the name cannot be proven. |
## Catch it [#catch-it]
`Errors.hasCode("DNS_RECORD_MISSING")` narrows to this error. See [Handle errors](/docs/sdk/handle-errors).
# PROOF_STALE
> For the complete documentation index, see [llms.txt](https://ensforge.com/llms.txt).
What PROOF_STALE means, why DnsError throws it, what to show users and how to fix it in ensforge. Also covers retry safety and the actions that throw it.
Source: https://ensforge.com/docs/reference/errors/PROOF_STALE
## What happened [#what-happened]
The DNSSEC proof is older than the one on-chain.
## What to show users [#what-to-show-users]
| Title | Message | Action |
| --- | --- | --- |
| Out of date | The DNS data changed. | Try again. |
## How to fix [#how-to-fix]
Fetch a fresh proof and retry.
## Retry safety [#retry-safety]
Retrying the same call fails the same way until the cause is fixed (`retryable: false`).
## Actions that throw it [#actions-that-throw-it]
| Action | When |
| --- | --- |
| [`dns.claim`](/docs/reference/sdk/dns/claim) | when the name cannot be proven. |
## Catch it [#catch-it]
`Errors.hasCode("PROOF_STALE")` narrows to this error. See [Handle errors](/docs/sdk/handle-errors).
# TLD_NOT_PUBLIC
> For the complete documentation index, see [llms.txt](https://ensforge.com/llms.txt).
What TLD_NOT_PUBLIC means, why DnsError throws it, what to show users and how to fix it in ensforge. Also covers retry safety and the actions that throw it.
Source: https://ensforge.com/docs/reference/errors/TLD_NOT_PUBLIC
## What happened [#what-happened]
The top-level domain is not a public suffix and cannot be imported.
## What to show users [#what-to-show-users]
| Title | Message | Action |
| --- | --- | --- |
| Domain not supported | This top-level domain cannot be imported into ENS. | |
## Retry safety [#retry-safety]
Retrying the same call fails the same way until the cause is fixed (`retryable: false`).
## Actions that throw it [#actions-that-throw-it]
| Action | When |
| --- | --- |
| [`dns.claim`](/docs/reference/sdk/dns/claim) | when the name cannot be proven. |
## Catch it [#catch-it]
`Errors.hasCode("TLD_NOT_PUBLIC")` narrows to this error. See [Handle errors](/docs/sdk/handle-errors).
# DnsError
> For the complete documentation index, see [llms.txt](https://ensforge.com/llms.txt).
What DnsError means, which codes it carries and how to catch it in ensforge. Importing or reading a DNS name failed. Lists its fields and every code.
Source: https://ensforge.com/docs/reference/errors/dns-error
Importing or reading a DNS name failed.
## Fields [#fields]
| Field | Type | Description |
| --- | --- | --- |
| `onchainOwner` | `Address` | |
| `dnsOwner` | `Address` | |
## Codes [#codes]
| Code | Meaning | Retryable |
| --- | --- | --- |
| [`DNS_RECORD_MISSING`](/docs/reference/errors/DNS_RECORD_MISSING) | The `_ens` TXT record is missing. | No |
| [`DNSSEC_PROOF_FAILED`](/docs/reference/errors/DNSSEC_PROOF_FAILED) | The DNSSEC proof could not be built or verified. | No |
| [`PROOF_STALE`](/docs/reference/errors/PROOF_STALE) | The DNSSEC proof is older than the one on-chain. | No |
| [`TLD_NOT_PUBLIC`](/docs/reference/errors/TLD_NOT_PUBLIC) | The top-level domain is not a public suffix and cannot be imported. | No |
## Catch it [#catch-it]
`Effect.catchTag("DnsError", …)` or `error instanceof Errors.DnsError`. See [Handle errors](/docs/sdk/handle-errors).
# GATEWAY_REQUEST_FAILED
> For the complete documentation index, see [llms.txt](https://ensforge.com/llms.txt).
What GATEWAY_REQUEST_FAILED means, why GatewayError throws it, what to show users and how to fix it in ensforge. Also covers retry safety.
Source: https://ensforge.com/docs/reference/errors/GATEWAY_REQUEST_FAILED
## What happened [#what-happened]
The off-chain gateway request failed.
## What to show users [#what-to-show-users]
| Title | Message | Action |
| --- | --- | --- |
| Lookup failed | The service that stores this name's data did not respond. | Try again. |
## Retry safety [#retry-safety]
Retrying the same call can succeed (`retryable: true`).
## Actions that throw it [#actions-that-throw-it]
| Action | When |
| --- | --- |
| [`dns.claim`](/docs/reference/sdk/dns/claim) | when the proof cannot be fetched. |
| [`dns.getOffchainResolver`](/docs/reference/sdk/dns/get-offchain-resolver) | when the DNSSEC gateway fails. |
| [`dns.getProof`](/docs/reference/sdk/dns/get-proof) | when the DNSSEC gateway fails. |
| [`dns.getStatus`](/docs/reference/sdk/dns/get-status) | when the DNSSEC gateway fails. |
| [`primaryName.get`](/docs/reference/sdk/primary-name/get) | when an off-chain gateway fails. |
| [`record.get`](/docs/reference/sdk/record/get) | when an off-chain gateway fails. |
| [`record.getAddress`](/docs/reference/sdk/record/get-address) | when an off-chain gateway fails. |
| [`record.getAvatar`](/docs/reference/sdk/record/get-avatar) | with `strict` when NFT metadata cannot be loaded. |
| [`record.getContentHash`](/docs/reference/sdk/record/get-content-hash) | when an off-chain gateway fails. |
| [`record.getText`](/docs/reference/sdk/record/get-text) | when an off-chain gateway fails. |
| [`resolver.resolve`](/docs/reference/sdk/resolver/resolve) | when an off-chain gateway fails. |
## Catch it [#catch-it]
`Errors.hasCode("GATEWAY_REQUEST_FAILED")` narrows to this error. See [Handle errors](/docs/sdk/handle-errors).
# GATEWAY_RESPONSE_INVALID
> For the complete documentation index, see [llms.txt](https://ensforge.com/llms.txt).
What GATEWAY_RESPONSE_INVALID means, why GatewayError throws it, what to show users and how to fix it in ensforge. Also covers retry safety.
Source: https://ensforge.com/docs/reference/errors/GATEWAY_RESPONSE_INVALID
## What happened [#what-happened]
The off-chain gateway returned an invalid response.
## What to show users [#what-to-show-users]
| Title | Message | Action |
| --- | --- | --- |
| Lookup failed | The service that stores this name's data returned invalid data. | |
## Retry safety [#retry-safety]
Retrying the same call fails the same way until the cause is fixed (`retryable: false`).
## Actions that throw it [#actions-that-throw-it]
| Action | When |
| --- | --- |
| [`dns.claim`](/docs/reference/sdk/dns/claim) | when the proof cannot be fetched. |
| [`dns.getOffchainResolver`](/docs/reference/sdk/dns/get-offchain-resolver) | when the DNSSEC gateway fails. |
| [`dns.getProof`](/docs/reference/sdk/dns/get-proof) | when the DNSSEC gateway fails. |
| [`dns.getStatus`](/docs/reference/sdk/dns/get-status) | when the DNSSEC gateway fails. |
| [`primaryName.get`](/docs/reference/sdk/primary-name/get) | when an off-chain gateway fails. |
| [`record.get`](/docs/reference/sdk/record/get) | when an off-chain gateway fails. |
| [`record.getAddress`](/docs/reference/sdk/record/get-address) | when an off-chain gateway fails. |
| [`record.getAvatar`](/docs/reference/sdk/record/get-avatar) | with `strict` when NFT metadata cannot be loaded. |
| [`record.getContentHash`](/docs/reference/sdk/record/get-content-hash) | when an off-chain gateway fails. |
| [`record.getText`](/docs/reference/sdk/record/get-text) | when an off-chain gateway fails. |
| [`resolver.resolve`](/docs/reference/sdk/resolver/resolve) | when an off-chain gateway fails. |
## Catch it [#catch-it]
`Errors.hasCode("GATEWAY_RESPONSE_INVALID")` narrows to this error. See [Handle errors](/docs/sdk/handle-errors).
# OFFCHAIN_LOOKUP_INVALID
> For the complete documentation index, see [llms.txt](https://ensforge.com/llms.txt).
What OFFCHAIN_LOOKUP_INVALID means, why GatewayError throws it, what to show users and how to fix it in ensforge. Also covers retry safety.
Source: https://ensforge.com/docs/reference/errors/OFFCHAIN_LOOKUP_INVALID
## What happened [#what-happened]
The resolver requested an off-chain lookup from an unexpected sender.
## What to show users [#what-to-show-users]
| Title | Message | Action |
| --- | --- | --- |
| Lookup failed | This name's resolver made an invalid off-chain request. | |
## Retry safety [#retry-safety]
Retrying the same call fails the same way until the cause is fixed (`retryable: false`).
## Actions that throw it [#actions-that-throw-it]
| Action | When |
| --- | --- |
| [`primaryName.get`](/docs/reference/sdk/primary-name/get) | when an off-chain gateway fails. |
| [`record.get`](/docs/reference/sdk/record/get) | when an off-chain gateway fails. |
| [`record.getAddress`](/docs/reference/sdk/record/get-address) | when an off-chain gateway fails. |
| [`record.getContentHash`](/docs/reference/sdk/record/get-content-hash) | when an off-chain gateway fails. |
| [`record.getText`](/docs/reference/sdk/record/get-text) | when an off-chain gateway fails. |
| [`resolver.resolve`](/docs/reference/sdk/resolver/resolve) | when an off-chain gateway fails. |
## Catch it [#catch-it]
`Errors.hasCode("OFFCHAIN_LOOKUP_INVALID")` narrows to this error. See [Handle errors](/docs/sdk/handle-errors).
# GatewayError
> For the complete documentation index, see [llms.txt](https://ensforge.com/llms.txt).
What GatewayError means, which codes it carries and how to catch it in ensforge. Off-chain resolution (CCIP-Read, ERC-3668) failed.
Source: https://ensforge.com/docs/reference/errors/gateway-error
Off-chain resolution (CCIP-Read, ERC-3668) failed.
## Fields [#fields]
| Field | Type | Description |
| --- | --- | --- |
| `status` | `number` | |
| `url` | `string` | |
## Codes [#codes]
| Code | Meaning | Retryable |
| --- | --- | --- |
| [`GATEWAY_REQUEST_FAILED`](/docs/reference/errors/GATEWAY_REQUEST_FAILED) | The off-chain gateway request failed. | Yes |
| [`GATEWAY_RESPONSE_INVALID`](/docs/reference/errors/GATEWAY_RESPONSE_INVALID) | The off-chain gateway returned an invalid response. | No |
| [`OFFCHAIN_LOOKUP_INVALID`](/docs/reference/errors/OFFCHAIN_LOOKUP_INVALID) | The resolver requested an off-chain lookup from an unexpected sender. | No |
## Catch it [#catch-it]
`Effect.catchTag("GatewayError", …)` or `error instanceof Errors.GatewayError`. See [Handle errors](/docs/sdk/handle-errors).
# HCA_ACTION_NOT_ALLOWED
> For the complete documentation index, see [llms.txt](https://ensforge.com/llms.txt).
What HCA_ACTION_NOT_ALLOWED means, why HcaError throws it, what to show users and how to fix it in ensforge. Also covers retry safety.
Source: https://ensforge.com/docs/reference/errors/HCA_ACTION_NOT_ALLOWED
## What happened [#what-happened]
The HCA session policy does not allow this call.
## What to show users [#what-to-show-users]
| Title | Message | Action |
| --- | --- | --- |
| Not allowed | Your session does not allow this action. | Approve it from your wallet instead. |
## How to fix [#how-to-fix]
Sessions may register names, deploy the session resolver and set its records; send other calls as the owner.
## Retry safety [#retry-safety]
Retrying the same call fails the same way until the cause is fixed (`retryable: false`).
## Actions that throw it [#actions-that-throw-it]
| Action | When |
| --- | --- |
| [`hca.checkSessionCalls`](/docs/reference/hca/hca/check-session-calls) | for the first call outside the policy. |
## Catch it [#catch-it]
Check `error instanceof HcaError && error.code === "HCA_ACTION_NOT_ALLOWED"`. See [Handle errors](/docs/sdk/handle-errors).
# HCA_BUNDLER_REJECTED
> For the complete documentation index, see [llms.txt](https://ensforge.com/llms.txt).
What HCA_BUNDLER_REJECTED means, why HcaError throws it, what to show users and how to fix it in ensforge. Also covers retry safety.
Source: https://ensforge.com/docs/reference/errors/HCA_BUNDLER_REJECTED
## What happened [#what-happened]
The bundler rejected the HCA UserOperation.
## What to show users [#what-to-show-users]
| Title | Message | Action |
| --- | --- | --- |
| Transaction not sent | The service that sends your transaction turned it down. | Try again. |
## How to fix [#how-to-fix]
Check the bundler URL and EntryPoint v0.7 support; HCA UserOperations must be signed by the owner.
## Retry safety [#retry-safety]
Retrying the same call can succeed (`retryable: true`).
## Actions that throw it [#actions-that-throw-it]
No action names this code in its documented errors.
## Catch it [#catch-it]
Check `error instanceof HcaError && error.code === "HCA_BUNDLER_REJECTED"`. See [Handle errors](/docs/sdk/handle-errors).
# HCA_EXECUTION_FAILED
> For the complete documentation index, see [llms.txt](https://ensforge.com/llms.txt).
What HCA_EXECUTION_FAILED means, why HcaError throws it, what to show users and how to fix it in ensforge. Also covers retry safety.
Source: https://ensforge.com/docs/reference/errors/HCA_EXECUTION_FAILED
## What happened [#what-happened]
The HCA execution failed.
## What to show users [#what-to-show-users]
| Title | Message | Action |
| --- | --- | --- |
| Transaction failed | The transaction from your ENS account failed. | |
## Retry safety [#retry-safety]
Retrying the same call fails the same way until the cause is fixed (`retryable: false`).
## Actions that throw it [#actions-that-throw-it]
No action names this code in its documented errors.
## Catch it [#catch-it]
Check `error instanceof HcaError && error.code === "HCA_EXECUTION_FAILED"`. See [Handle errors](/docs/sdk/handle-errors).
# HCA_EXECUTION_TIMEOUT
> For the complete documentation index, see [llms.txt](https://ensforge.com/llms.txt).
What HCA_EXECUTION_TIMEOUT means, why HcaError throws it, what to show users and how to fix it in ensforge. Also covers retry safety.
Source: https://ensforge.com/docs/reference/errors/HCA_EXECUTION_TIMEOUT
## What happened [#what-happened]
The HCA execution was not included in time.
## What to show users [#what-to-show-users]
| Title | Message | Action |
| --- | --- | --- |
| Still pending | The transaction is taking longer than expected to confirm. | Check its status before retrying. |
## How to fix [#how-to-fix]
It may still be included: `plan.resume` checks it again. Raise the executor's `timeout` to wait longer.
## Retry safety [#retry-safety]
Retrying the same call fails the same way until the cause is fixed (`retryable: false`).
## Actions that throw it [#actions-that-throw-it]
No action names this code in its documented errors.
## Catch it [#catch-it]
Check `error instanceof HcaError && error.code === "HCA_EXECUTION_TIMEOUT"`. See [Handle errors](/docs/sdk/handle-errors).
# HCA_EXECUTOR_UNSUPPORTED
> For the complete documentation index, see [llms.txt](https://ensforge.com/llms.txt).
What HCA_EXECUTOR_UNSUPPORTED means, why HcaError throws it, what to show users and how to fix it in ensforge. Also covers retry safety.
Source: https://ensforge.com/docs/reference/errors/HCA_EXECUTOR_UNSUPPORTED
## What happened [#what-happened]
No configured executor can run this HCA operation.
## What to show users [#what-to-show-users]
| Title | Message | Action |
| --- | --- | --- |
| Cannot continue | This app cannot send this action from your ENS account. | |
## How to fix [#how-to-fix]
Sessions need `rhinestone()`; owner operations work with `owner()`.
## Retry safety [#retry-safety]
Retrying the same call fails the same way until the cause is fixed (`retryable: false`).
## Actions that throw it [#actions-that-throw-it]
| Action | When |
| --- | --- |
| [`hca.execute`](/docs/reference/hca/hca/execute) | when the HCA or executor cannot run them. |
## Catch it [#catch-it]
Check `error instanceof HcaError && error.code === "HCA_EXECUTOR_UNSUPPORTED"`. See [Handle errors](/docs/sdk/handle-errors).
# HCA_NOT_VERIFIED
> For the complete documentation index, see [llms.txt](https://ensforge.com/llms.txt).
What HCA_NOT_VERIFIED means, why HcaError throws it, what to show users and how to fix it in ensforge. Also covers retry safety and the actions that throw it.
Source: https://ensforge.com/docs/reference/errors/HCA_NOT_VERIFIED
## What happened [#what-happened]
The account is not a verified ENS HCA of this owner.
## What to show users [#what-to-show-users]
| Title | Message | Action |
| --- | --- | --- |
| Account not recognized | This is not a verified ENS account for your wallet. | |
## How to fix [#how-to-fix]
Check the address, or let ensforge derive the owner's HCA.
## Retry safety [#retry-safety]
Retrying the same call fails the same way until the cause is fixed (`retryable: false`).
## Actions that throw it [#actions-that-throw-it]
| Action | When |
| --- | --- |
| [`hca.execute`](/docs/reference/hca/hca/execute) | when the HCA or executor cannot run them. |
| [`hca.revokeSessions`](/docs/reference/hca/hca/revoke-sessions) | when the HCA is not deployed. |
| [`hca.verify`](/docs/reference/hca/hca/verify) | when a check fails. |
## Catch it [#catch-it]
Check `error instanceof HcaError && error.code === "HCA_NOT_VERIFIED"`. See [Handle errors](/docs/sdk/handle-errors).
# HCA_PAYMASTER_REJECTED
> For the complete documentation index, see [llms.txt](https://ensforge.com/llms.txt).
What HCA_PAYMASTER_REJECTED means, why HcaError throws it, what to show users and how to fix it in ensforge. Also covers retry safety.
Source: https://ensforge.com/docs/reference/errors/HCA_PAYMASTER_REJECTED
## What happened [#what-happened]
The paymaster refused to sponsor the HCA UserOperation.
## What to show users [#what-to-show-users]
| Title | Message | Action |
| --- | --- | --- |
| Fees not covered | The service that pays the network fees declined this transaction. | |
## Retry safety [#retry-safety]
Retrying the same call fails the same way until the cause is fixed (`retryable: false`).
## Actions that throw it [#actions-that-throw-it]
No action names this code in its documented errors.
## Catch it [#catch-it]
Check `error instanceof HcaError && error.code === "HCA_PAYMASTER_REJECTED"`. See [Handle errors](/docs/sdk/handle-errors).
# HCA_SDK_UNSUPPORTED
> For the complete documentation index, see [llms.txt](https://ensforge.com/llms.txt).
What HCA_SDK_UNSUPPORTED means, why HcaError throws it, what to show users and how to fix it in ensforge. Also covers retry safety.
Source: https://ensforge.com/docs/reference/errors/HCA_SDK_UNSUPPORTED
## What happened [#what-happened]
The Rhinestone SDK does not support the standalone ENS HCA.
## What to show users [#what-to-show-users]
| Title | Message | Action |
| --- | --- | --- |
| Configuration problem | This app is misconfigured for ENS accounts. | |
## How to fix [#how-to-fix]
Use a Rhinestone SDK with standalone HCA support (`ens-standalone-1.1.0`).
## Retry safety [#retry-safety]
Retrying the same call fails the same way until the cause is fixed (`retryable: false`).
## Actions that throw it [#actions-that-throw-it]
No action names this code in its documented errors.
## Catch it [#catch-it]
Check `error instanceof HcaError && error.code === "HCA_SDK_UNSUPPORTED"`. See [Handle errors](/docs/sdk/handle-errors).
# HCA_SESSION_INVALID
> For the complete documentation index, see [llms.txt](https://ensforge.com/llms.txt).
What HCA_SESSION_INVALID means, why HcaError throws it, what to show users and how to fix it in ensforge. Also covers retry safety.
Source: https://ensforge.com/docs/reference/errors/HCA_SESSION_INVALID
## What happened [#what-happened]
The HCA session is expired, revoked or for another resolver.
## What to show users [#what-to-show-users]
| Title | Message | Action |
| --- | --- | --- |
| Session ended | Your session has expired or was revoked. | Start a new session. |
## How to fix [#how-to-fix]
Authorize a new session with hca.authorizeSession.
## Retry safety [#retry-safety]
Retrying the same call fails the same way until the cause is fixed (`retryable: false`).
## Actions that throw it [#actions-that-throw-it]
No action names this code in its documented errors.
## Catch it [#catch-it]
Check `error instanceof HcaError && error.code === "HCA_SESSION_INVALID"`. See [Handle errors](/docs/sdk/handle-errors).
# HCA_UNAVAILABLE
> For the complete documentation index, see [llms.txt](https://ensforge.com/llms.txt).
What HCA_UNAVAILABLE means, why HcaError throws it, what to show users and how to fix it in ensforge. Also covers retry safety and the actions that throw it.
Source: https://ensforge.com/docs/reference/errors/HCA_UNAVAILABLE
## What happened [#what-happened]
This chain has no ENS HCA deployment.
## What to show users [#what-to-show-users]
| Title | Message | Action |
| --- | --- | --- |
| Network not supported | ENS accounts are not available on this network. | Switch to Ethereum mainnet or Sepolia. |
## How to fix [#how-to-fix]
Use mainnet or Sepolia, or pass a deployment with an `hca` group.
## Retry safety [#retry-safety]
Retrying the same call fails the same way until the cause is fixed (`retryable: false`).
## Actions that throw it [#actions-that-throw-it]
| Action | When |
| --- | --- |
| [`hca.addDeposit`](/docs/reference/hca/hca/add-deposit) | on chains without an HCA deployment. |
| [`hca.authorizeSession`](/docs/reference/hca/hca/authorize-session) | on chains without an HCA deployment. |
| [`hca.checkSessionCalls`](/docs/reference/hca/hca/check-session-calls) | on chains without an HCA deployment. |
| [`hca.deploy`](/docs/reference/hca/hca/deploy) | on chains without an HCA deployment. |
| [`hca.execute`](/docs/reference/hca/hca/execute) | on chains without an HCA deployment. |
| [`hca.get`](/docs/reference/hca/hca/get) | on chains without an HCA deployment. |
| [`hca.getDeposit`](/docs/reference/hca/hca/get-deposit) | on chains without an HCA deployment. |
| [`hca.getSession`](/docs/reference/hca/hca/get-session) | on chains without an HCA deployment. |
| [`hca.getUpgrade`](/docs/reference/hca/hca/get-upgrade) | on chains without an HCA deployment. |
| [`hca.predictAddress`](/docs/reference/hca/hca/predict-address) | on chains without an HCA deployment. |
| [`hca.revokeSessions`](/docs/reference/hca/hca/revoke-sessions) | on chains without an HCA deployment. |
| [`hca.upgrade`](/docs/reference/hca/hca/upgrade) | on chains without an HCA deployment. |
| [`hca.verify`](/docs/reference/hca/hca/verify) | on chains without an HCA deployment. |
| [`hca.withdrawDeposit`](/docs/reference/hca/hca/withdraw-deposit) | on chains without an HCA deployment. |
| [`hcaAdmin.getGovernance`](/docs/reference/hca/hca-admin/get-governance) | on chains without an HCA deployment. |
| [`hcaAdmin.grantUpgradeSetRoles`](/docs/reference/hca/hca-admin/grant-upgrade-set-roles) | on chains without an HCA deployment. |
| [`hcaAdmin.renounceGovernance`](/docs/reference/hca/hca-admin/renounce-governance) | on chains without an HCA deployment. |
| [`hcaAdmin.revokeUpgradeSetRoles`](/docs/reference/hca/hca-admin/revoke-upgrade-set-roles) | on chains without an HCA deployment. |
| [`hcaAdmin.setDeploymentApproval`](/docs/reference/hca/hca-admin/set-deployment-approval) | on chains without an HCA deployment. |
| [`hcaAdmin.setUpgradeApproval`](/docs/reference/hca/hca-admin/set-upgrade-approval) | on chains without an HCA deployment. |
| [`hcaAdmin.transferGovernance`](/docs/reference/hca/hca-admin/transfer-governance) | on chains without an HCA deployment. |
## Catch it [#catch-it]
Check `error instanceof HcaError && error.code === "HCA_UNAVAILABLE"`. See [Handle errors](/docs/sdk/handle-errors).
# HCA_UPGRADE_NOT_ALLOWED
> For the complete documentation index, see [llms.txt](https://ensforge.com/llms.txt).
What HCA_UPGRADE_NOT_ALLOWED means, why HcaError throws it, what to show users and how to fix it in ensforge. Also covers retry safety.
Source: https://ensforge.com/docs/reference/errors/HCA_UPGRADE_NOT_ALLOWED
## What happened [#what-happened]
The upgrade set or the new implementation's `canUpgradeFrom` check does not allow this HCA upgrade.
## What to show users [#what-to-show-users]
| Title | Message | Action |
| --- | --- | --- |
| Upgrade unavailable | Your ENS account cannot be upgraded to this version. | |
## Retry safety [#retry-safety]
Retrying the same call fails the same way until the cause is fixed (`retryable: false`).
## Actions that throw it [#actions-that-throw-it]
| Action | When |
| --- | --- |
| [`hca.upgrade`](/docs/reference/hca/hca/upgrade) | when a DAO set does not allow it. |
## Catch it [#catch-it]
Check `error instanceof HcaError && error.code === "HCA_UPGRADE_NOT_ALLOWED"`. See [Handle errors](/docs/sdk/handle-errors).
# HcaError
> For the complete documentation index, see [llms.txt](https://ensforge.com/llms.txt).
What HcaError means, which codes it carries and how to catch it in ensforge. Lists its fields and every code. Includes how to catch it.
Source: https://ensforge.com/docs/reference/errors/hca-error
An HCA (Hosted Contract Account) operation failed: the account, its session, an executor
(bundler, Rhinestone) or the DAO's upgrade set.
## Fields [#fields]
| Field | Type | Description |
| --- | --- | --- |
| `executor` | `string` | Executor that failed, e.g. `pimlico`. |
## Codes [#codes]
| Code | Meaning | Retryable |
| --- | --- | --- |
| [`HCA_UNAVAILABLE`](/docs/reference/errors/HCA_UNAVAILABLE) | This chain has no ENS HCA deployment. | No |
| [`HCA_NOT_VERIFIED`](/docs/reference/errors/HCA_NOT_VERIFIED) | The account is not a verified ENS HCA of this owner. | No |
| [`HCA_EXECUTOR_UNSUPPORTED`](/docs/reference/errors/HCA_EXECUTOR_UNSUPPORTED) | No configured executor can run this HCA operation. | No |
| [`HCA_ACTION_NOT_ALLOWED`](/docs/reference/errors/HCA_ACTION_NOT_ALLOWED) | The HCA session policy does not allow this call. | No |
| [`HCA_SESSION_INVALID`](/docs/reference/errors/HCA_SESSION_INVALID) | The HCA session is expired, revoked or for another resolver. | No |
| [`HCA_BUNDLER_REJECTED`](/docs/reference/errors/HCA_BUNDLER_REJECTED) | The bundler rejected the HCA UserOperation. | Yes |
| [`HCA_PAYMASTER_REJECTED`](/docs/reference/errors/HCA_PAYMASTER_REJECTED) | The paymaster refused to sponsor the HCA UserOperation. | No |
| [`HCA_EXECUTION_FAILED`](/docs/reference/errors/HCA_EXECUTION_FAILED) | The HCA execution failed. | No |
| [`HCA_EXECUTION_TIMEOUT`](/docs/reference/errors/HCA_EXECUTION_TIMEOUT) | The HCA execution was not included in time. | No |
| [`HCA_UPGRADE_NOT_ALLOWED`](/docs/reference/errors/HCA_UPGRADE_NOT_ALLOWED) | The upgrade set or the new implementation's `canUpgradeFrom` check does not allow this HCA upgrade. | No |
| [`HCA_SDK_UNSUPPORTED`](/docs/reference/errors/HCA_SDK_UNSUPPORTED) | The Rhinestone SDK does not support the standalone ENS HCA. | No |
## Catch it [#catch-it]
`error instanceof HcaError`. See [Handle errors](/docs/sdk/handle-errors).
# INDEXER_BEHIND
> For the complete documentation index, see [llms.txt](https://ensforge.com/llms.txt).
What INDEXER_BEHIND means, why IndexerError throws it, what to show users and how to fix it in ensforge. Also covers retry safety and the actions that throw it.
Source: https://ensforge.com/docs/reference/errors/INDEXER_BEHIND
## What happened [#what-happened]
The indexer is behind the chain.
## What to show users [#what-to-show-users]
| Title | Message | Action |
| --- | --- | --- |
| Data updating | Recent changes may take a moment to appear. | Refresh shortly. |
## How to fix [#how-to-fix]
Retry shortly, or read on-chain instead.
## Retry safety [#retry-safety]
Retrying the same call can succeed (`retryable: true`).
## Actions that throw it [#actions-that-throw-it]
| Action | When |
| --- | --- |
| [`indexer.getEvents`](/docs/reference/sdk/indexer/get-events) | when the indexer is unavailable, rate limiting, behind, rejects the request or answers unexpectedly. |
| [`indexer.getHistory`](/docs/reference/sdk/indexer/get-history) | when the indexer is unavailable, rate limiting, behind, rejects the request or answers unexpectedly. |
| [`indexer.getName`](/docs/reference/sdk/indexer/get-name) | when the indexer is unavailable, rate limiting, behind, rejects the request or answers unexpectedly. |
| [`indexer.getNamesByExpiry`](/docs/reference/sdk/indexer/get-names-by-expiry) | when the indexer is unavailable, rate limiting, behind, rejects the request or answers unexpectedly. |
| [`indexer.getNamesForAddress`](/docs/reference/sdk/indexer/get-names-for-address) | when the indexer is unavailable, rate limiting, behind, rejects the request or answers unexpectedly. |
| [`indexer.getNamespace`](/docs/reference/sdk/indexer/get-namespace) | when the indexer is unavailable, rate limiting, behind, rejects the request or answers unexpectedly. |
| [`indexer.getPermissions`](/docs/reference/sdk/indexer/get-permissions) | when the indexer is unavailable, rate limiting, behind, rejects the request or answers unexpectedly. |
| [`indexer.getPrimaryName`](/docs/reference/sdk/indexer/get-primary-name) | when the indexer is unavailable, rate limiting, behind, rejects the request or answers unexpectedly. |
| [`indexer.getRecords`](/docs/reference/sdk/indexer/get-records) | when the indexer is unavailable, rate limiting, behind, rejects the request or answers unexpectedly. |
| [`indexer.getRegistry`](/docs/reference/sdk/indexer/get-registry) | when the indexer is unavailable, rate limiting, behind, rejects the request or answers unexpectedly. |
| [`indexer.getRegistryLabels`](/docs/reference/sdk/indexer/get-registry-labels) | when the indexer is unavailable, rate limiting, behind, rejects the request or answers unexpectedly. |
| [`indexer.getResolver`](/docs/reference/sdk/indexer/get-resolver) | when the indexer is unavailable, rate limiting, behind, rejects the request or answers unexpectedly. |
| [`indexer.getResolverLinks`](/docs/reference/sdk/indexer/get-resolver-links) | when the indexer is unavailable, rate limiting, behind, rejects the request or answers unexpectedly. |
| [`indexer.getResolverRoles`](/docs/reference/sdk/indexer/get-resolver-roles) | when the indexer is unavailable, rate limiting, behind, rejects the request or answers unexpectedly. |
| [`indexer.getResolvers`](/docs/reference/sdk/indexer/get-resolvers) | when the indexer is unavailable, rate limiting, behind, rejects the request or answers unexpectedly. |
| [`indexer.getStatus`](/docs/reference/sdk/indexer/get-status) | when the indexer is unavailable, rate limiting, behind, rejects the request or answers unexpectedly. |
| [`indexer.getSubnames`](/docs/reference/sdk/indexer/get-subnames) | when the indexer is unavailable, rate limiting, behind, rejects the request or answers unexpectedly. |
| [`indexer.lookup`](/docs/reference/sdk/indexer/lookup) | when the indexer is unavailable, rate limiting, behind, rejects the request or answers unexpectedly. |
| [`indexer.search`](/docs/reference/sdk/indexer/search) | when the indexer is unavailable, rate limiting, behind, rejects the request or answers unexpectedly. |
## Catch it [#catch-it]
`Errors.hasCode("INDEXER_BEHIND")` narrows to this error. See [Handle errors](/docs/sdk/handle-errors).
# INDEXER_RATE_LIMITED
> For the complete documentation index, see [llms.txt](https://ensforge.com/llms.txt).
What INDEXER_RATE_LIMITED means, why IndexerError throws it, what to show users and how to fix it in ensforge. Also covers retry safety.
Source: https://ensforge.com/docs/reference/errors/INDEXER_RATE_LIMITED
## What happened [#what-happened]
The indexer is rate limiting requests.
## What to show users [#what-to-show-users]
| Title | Message | Action |
| --- | --- | --- |
| Too many requests | Please wait a moment. | Try again shortly. |
## Retry safety [#retry-safety]
Retrying the same call can succeed (`retryable: true`).
## Actions that throw it [#actions-that-throw-it]
| Action | When |
| --- | --- |
| [`indexer.getEvents`](/docs/reference/sdk/indexer/get-events) | when the indexer is unavailable, rate limiting, behind, rejects the request or answers unexpectedly. |
| [`indexer.getHistory`](/docs/reference/sdk/indexer/get-history) | when the indexer is unavailable, rate limiting, behind, rejects the request or answers unexpectedly. |
| [`indexer.getName`](/docs/reference/sdk/indexer/get-name) | when the indexer is unavailable, rate limiting, behind, rejects the request or answers unexpectedly. |
| [`indexer.getNamesByExpiry`](/docs/reference/sdk/indexer/get-names-by-expiry) | when the indexer is unavailable, rate limiting, behind, rejects the request or answers unexpectedly. |
| [`indexer.getNamesForAddress`](/docs/reference/sdk/indexer/get-names-for-address) | when the indexer is unavailable, rate limiting, behind, rejects the request or answers unexpectedly. |
| [`indexer.getNamespace`](/docs/reference/sdk/indexer/get-namespace) | when the indexer is unavailable, rate limiting, behind, rejects the request or answers unexpectedly. |
| [`indexer.getPermissions`](/docs/reference/sdk/indexer/get-permissions) | when the indexer is unavailable, rate limiting, behind, rejects the request or answers unexpectedly. |
| [`indexer.getPrimaryName`](/docs/reference/sdk/indexer/get-primary-name) | when the indexer is unavailable, rate limiting, behind, rejects the request or answers unexpectedly. |
| [`indexer.getRecords`](/docs/reference/sdk/indexer/get-records) | when the indexer is unavailable, rate limiting, behind, rejects the request or answers unexpectedly. |
| [`indexer.getRegistry`](/docs/reference/sdk/indexer/get-registry) | when the indexer is unavailable, rate limiting, behind, rejects the request or answers unexpectedly. |
| [`indexer.getRegistryLabels`](/docs/reference/sdk/indexer/get-registry-labels) | when the indexer is unavailable, rate limiting, behind, rejects the request or answers unexpectedly. |
| [`indexer.getResolver`](/docs/reference/sdk/indexer/get-resolver) | when the indexer is unavailable, rate limiting, behind, rejects the request or answers unexpectedly. |
| [`indexer.getResolverLinks`](/docs/reference/sdk/indexer/get-resolver-links) | when the indexer is unavailable, rate limiting, behind, rejects the request or answers unexpectedly. |
| [`indexer.getResolverRoles`](/docs/reference/sdk/indexer/get-resolver-roles) | when the indexer is unavailable, rate limiting, behind, rejects the request or answers unexpectedly. |
| [`indexer.getResolvers`](/docs/reference/sdk/indexer/get-resolvers) | when the indexer is unavailable, rate limiting, behind, rejects the request or answers unexpectedly. |
| [`indexer.getStatus`](/docs/reference/sdk/indexer/get-status) | when the indexer is unavailable, rate limiting, behind, rejects the request or answers unexpectedly. |
| [`indexer.getSubnames`](/docs/reference/sdk/indexer/get-subnames) | when the indexer is unavailable, rate limiting, behind, rejects the request or answers unexpectedly. |
| [`indexer.lookup`](/docs/reference/sdk/indexer/lookup) | when the indexer is unavailable, rate limiting, behind, rejects the request or answers unexpectedly. |
| [`indexer.search`](/docs/reference/sdk/indexer/search) | when the indexer is unavailable, rate limiting, behind, rejects the request or answers unexpectedly. |
## Catch it [#catch-it]
`Errors.hasCode("INDEXER_RATE_LIMITED")` narrows to this error. See [Handle errors](/docs/sdk/handle-errors).
# INDEXER_REQUEST_REJECTED
> For the complete documentation index, see [llms.txt](https://ensforge.com/llms.txt).
What INDEXER_REQUEST_REJECTED means, why IndexerError throws it, what to show users and how to fix it in ensforge. Also covers retry safety.
Source: https://ensforge.com/docs/reference/errors/INDEXER_REQUEST_REJECTED
## What happened [#what-happened]
The indexer rejected the request.
## What to show users [#what-to-show-users]
| Title | Message | Action |
| --- | --- | --- |
| Search failed | This search could not be completed. | |
## Retry safety [#retry-safety]
Retrying the same call fails the same way until the cause is fixed (`retryable: false`).
## Actions that throw it [#actions-that-throw-it]
| Action | When |
| --- | --- |
| [`indexer.getEvents`](/docs/reference/sdk/indexer/get-events) | when the indexer is unavailable, rate limiting, behind, rejects the request or answers unexpectedly. |
| [`indexer.getHistory`](/docs/reference/sdk/indexer/get-history) | when the indexer is unavailable, rate limiting, behind, rejects the request or answers unexpectedly. |
| [`indexer.getName`](/docs/reference/sdk/indexer/get-name) | when the indexer is unavailable, rate limiting, behind, rejects the request or answers unexpectedly. |
| [`indexer.getNamesByExpiry`](/docs/reference/sdk/indexer/get-names-by-expiry) | when the indexer is unavailable, rate limiting, behind, rejects the request or answers unexpectedly. |
| [`indexer.getNamesForAddress`](/docs/reference/sdk/indexer/get-names-for-address) | when the indexer is unavailable, rate limiting, behind, rejects the request or answers unexpectedly. |
| [`indexer.getNamespace`](/docs/reference/sdk/indexer/get-namespace) | when the indexer is unavailable, rate limiting, behind, rejects the request or answers unexpectedly. |
| [`indexer.getPermissions`](/docs/reference/sdk/indexer/get-permissions) | when the indexer is unavailable, rate limiting, behind, rejects the request or answers unexpectedly. |
| [`indexer.getPrimaryName`](/docs/reference/sdk/indexer/get-primary-name) | when the indexer is unavailable, rate limiting, behind, rejects the request or answers unexpectedly. |
| [`indexer.getRecords`](/docs/reference/sdk/indexer/get-records) | when the indexer is unavailable, rate limiting, behind, rejects the request or answers unexpectedly. |
| [`indexer.getRegistry`](/docs/reference/sdk/indexer/get-registry) | when the indexer is unavailable, rate limiting, behind, rejects the request or answers unexpectedly. |
| [`indexer.getRegistryLabels`](/docs/reference/sdk/indexer/get-registry-labels) | when the indexer is unavailable, rate limiting, behind, rejects the request or answers unexpectedly. |
| [`indexer.getResolver`](/docs/reference/sdk/indexer/get-resolver) | when the indexer is unavailable, rate limiting, behind, rejects the request or answers unexpectedly. |
| [`indexer.getResolverLinks`](/docs/reference/sdk/indexer/get-resolver-links) | when the indexer is unavailable, rate limiting, behind, rejects the request or answers unexpectedly. |
| [`indexer.getResolverRoles`](/docs/reference/sdk/indexer/get-resolver-roles) | when the indexer is unavailable, rate limiting, behind, rejects the request or answers unexpectedly. |
| [`indexer.getResolvers`](/docs/reference/sdk/indexer/get-resolvers) | when the indexer is unavailable, rate limiting, behind, rejects the request or answers unexpectedly. |
| [`indexer.getStatus`](/docs/reference/sdk/indexer/get-status) | when the indexer is unavailable, rate limiting, behind, rejects the request or answers unexpectedly. |
| [`indexer.getSubnames`](/docs/reference/sdk/indexer/get-subnames) | when the indexer is unavailable, rate limiting, behind, rejects the request or answers unexpectedly. |
| [`indexer.lookup`](/docs/reference/sdk/indexer/lookup) | when the indexer is unavailable, rate limiting, behind, rejects the request or answers unexpectedly. |
| [`indexer.search`](/docs/reference/sdk/indexer/search) | when the indexer is unavailable, rate limiting, behind, rejects the request or answers unexpectedly. |
## Catch it [#catch-it]
`Errors.hasCode("INDEXER_REQUEST_REJECTED")` narrows to this error. See [Handle errors](/docs/sdk/handle-errors).
# INDEXER_RESPONSE_INVALID
> For the complete documentation index, see [llms.txt](https://ensforge.com/llms.txt).
What INDEXER_RESPONSE_INVALID means, why IndexerError throws it, what to show users and how to fix it in ensforge. Also covers retry safety.
Source: https://ensforge.com/docs/reference/errors/INDEXER_RESPONSE_INVALID
## What happened [#what-happened]
The indexer returned an unexpected response.
## What to show users [#what-to-show-users]
| Title | Message | Action |
| --- | --- | --- |
| Data unavailable | Name data could not be loaded. | |
## Retry safety [#retry-safety]
Retrying the same call fails the same way until the cause is fixed (`retryable: false`).
## Actions that throw it [#actions-that-throw-it]
| Action | When |
| --- | --- |
| [`indexer.getEvents`](/docs/reference/sdk/indexer/get-events) | when the indexer is unavailable, rate limiting, behind, rejects the request or answers unexpectedly. |
| [`indexer.getHistory`](/docs/reference/sdk/indexer/get-history) | when the indexer is unavailable, rate limiting, behind, rejects the request or answers unexpectedly. |
| [`indexer.getName`](/docs/reference/sdk/indexer/get-name) | when the indexer is unavailable, rate limiting, behind, rejects the request or answers unexpectedly. |
| [`indexer.getNamesByExpiry`](/docs/reference/sdk/indexer/get-names-by-expiry) | when the indexer is unavailable, rate limiting, behind, rejects the request or answers unexpectedly. |
| [`indexer.getNamesForAddress`](/docs/reference/sdk/indexer/get-names-for-address) | when the indexer is unavailable, rate limiting, behind, rejects the request or answers unexpectedly. |
| [`indexer.getNamespace`](/docs/reference/sdk/indexer/get-namespace) | when the indexer is unavailable, rate limiting, behind, rejects the request or answers unexpectedly. |
| [`indexer.getPermissions`](/docs/reference/sdk/indexer/get-permissions) | when the indexer is unavailable, rate limiting, behind, rejects the request or answers unexpectedly. |
| [`indexer.getPrimaryName`](/docs/reference/sdk/indexer/get-primary-name) | when the indexer is unavailable, rate limiting, behind, rejects the request or answers unexpectedly. |
| [`indexer.getRecords`](/docs/reference/sdk/indexer/get-records) | when the indexer is unavailable, rate limiting, behind, rejects the request or answers unexpectedly. |
| [`indexer.getRegistry`](/docs/reference/sdk/indexer/get-registry) | when the indexer is unavailable, rate limiting, behind, rejects the request or answers unexpectedly. |
| [`indexer.getRegistryLabels`](/docs/reference/sdk/indexer/get-registry-labels) | when the indexer is unavailable, rate limiting, behind, rejects the request or answers unexpectedly. |
| [`indexer.getResolver`](/docs/reference/sdk/indexer/get-resolver) | when the indexer is unavailable, rate limiting, behind, rejects the request or answers unexpectedly. |
| [`indexer.getResolverLinks`](/docs/reference/sdk/indexer/get-resolver-links) | when the indexer is unavailable, rate limiting, behind, rejects the request or answers unexpectedly. |
| [`indexer.getResolverRoles`](/docs/reference/sdk/indexer/get-resolver-roles) | when the indexer is unavailable, rate limiting, behind, rejects the request or answers unexpectedly. |
| [`indexer.getResolvers`](/docs/reference/sdk/indexer/get-resolvers) | when the indexer is unavailable, rate limiting, behind, rejects the request or answers unexpectedly. |
| [`indexer.getStatus`](/docs/reference/sdk/indexer/get-status) | when the indexer is unavailable, rate limiting, behind, rejects the request or answers unexpectedly. |
| [`indexer.getSubnames`](/docs/reference/sdk/indexer/get-subnames) | when the indexer is unavailable, rate limiting, behind, rejects the request or answers unexpectedly. |
| [`indexer.lookup`](/docs/reference/sdk/indexer/lookup) | when the indexer is unavailable, rate limiting, behind, rejects the request or answers unexpectedly. |
| [`indexer.search`](/docs/reference/sdk/indexer/search) | when the indexer is unavailable, rate limiting, behind, rejects the request or answers unexpectedly. |
## Catch it [#catch-it]
`Errors.hasCode("INDEXER_RESPONSE_INVALID")` narrows to this error. See [Handle errors](/docs/sdk/handle-errors).
# INDEXER_UNAVAILABLE
> For the complete documentation index, see [llms.txt](https://ensforge.com/llms.txt).
What INDEXER_UNAVAILABLE means, why IndexerError throws it, what to show users and how to fix it in ensforge. Also covers retry safety.
Source: https://ensforge.com/docs/reference/errors/INDEXER_UNAVAILABLE
## What happened [#what-happened]
The indexer is unavailable.
## What to show users [#what-to-show-users]
| Title | Message | Action |
| --- | --- | --- |
| Data unavailable | Name data is temporarily unavailable. | Try again. |
## Retry safety [#retry-safety]
Retrying the same call can succeed (`retryable: true`).
## Actions that throw it [#actions-that-throw-it]
| Action | When |
| --- | --- |
| [`indexer.getEvents`](/docs/reference/sdk/indexer/get-events) | when the indexer is unavailable, rate limiting, behind, rejects the request or answers unexpectedly. |
| [`indexer.getHistory`](/docs/reference/sdk/indexer/get-history) | when the indexer is unavailable, rate limiting, behind, rejects the request or answers unexpectedly. |
| [`indexer.getName`](/docs/reference/sdk/indexer/get-name) | when the indexer is unavailable, rate limiting, behind, rejects the request or answers unexpectedly. |
| [`indexer.getNamesByExpiry`](/docs/reference/sdk/indexer/get-names-by-expiry) | when the indexer is unavailable, rate limiting, behind, rejects the request or answers unexpectedly. |
| [`indexer.getNamesForAddress`](/docs/reference/sdk/indexer/get-names-for-address) | when the indexer is unavailable, rate limiting, behind, rejects the request or answers unexpectedly. |
| [`indexer.getNamespace`](/docs/reference/sdk/indexer/get-namespace) | when the indexer is unavailable, rate limiting, behind, rejects the request or answers unexpectedly. |
| [`indexer.getPermissions`](/docs/reference/sdk/indexer/get-permissions) | when the indexer is unavailable, rate limiting, behind, rejects the request or answers unexpectedly. |
| [`indexer.getPrimaryName`](/docs/reference/sdk/indexer/get-primary-name) | when the indexer is unavailable, rate limiting, behind, rejects the request or answers unexpectedly. |
| [`indexer.getRecords`](/docs/reference/sdk/indexer/get-records) | when the indexer is unavailable, rate limiting, behind, rejects the request or answers unexpectedly. |
| [`indexer.getRegistry`](/docs/reference/sdk/indexer/get-registry) | when the indexer is unavailable, rate limiting, behind, rejects the request or answers unexpectedly. |
| [`indexer.getRegistryLabels`](/docs/reference/sdk/indexer/get-registry-labels) | when the indexer is unavailable, rate limiting, behind, rejects the request or answers unexpectedly. |
| [`indexer.getResolver`](/docs/reference/sdk/indexer/get-resolver) | when the indexer is unavailable, rate limiting, behind, rejects the request or answers unexpectedly. |
| [`indexer.getResolverLinks`](/docs/reference/sdk/indexer/get-resolver-links) | when the indexer is unavailable, rate limiting, behind, rejects the request or answers unexpectedly. |
| [`indexer.getResolverRoles`](/docs/reference/sdk/indexer/get-resolver-roles) | when the indexer is unavailable, rate limiting, behind, rejects the request or answers unexpectedly. |
| [`indexer.getResolvers`](/docs/reference/sdk/indexer/get-resolvers) | when the indexer is unavailable, rate limiting, behind, rejects the request or answers unexpectedly. |
| [`indexer.getStatus`](/docs/reference/sdk/indexer/get-status) | when the indexer is unavailable, rate limiting, behind, rejects the request or answers unexpectedly. |
| [`indexer.getSubnames`](/docs/reference/sdk/indexer/get-subnames) | when the indexer is unavailable, rate limiting, behind, rejects the request or answers unexpectedly. |
| [`indexer.lookup`](/docs/reference/sdk/indexer/lookup) | when the indexer is unavailable, rate limiting, behind, rejects the request or answers unexpectedly. |
| [`indexer.search`](/docs/reference/sdk/indexer/search) | when the indexer is unavailable, rate limiting, behind, rejects the request or answers unexpectedly. |
## Catch it [#catch-it]
`Errors.hasCode("INDEXER_UNAVAILABLE")` narrows to this error. See [Handle errors](/docs/sdk/handle-errors).
# INDEXER_UNSUPPORTED
> For the complete documentation index, see [llms.txt](https://ensforge.com/llms.txt).
What INDEXER_UNSUPPORTED means, why IndexerError throws it, what to show users and how to fix it in ensforge. Also covers retry safety.
Source: https://ensforge.com/docs/reference/errors/INDEXER_UNSUPPORTED
## What happened [#what-happened]
The indexer does not support this query.
## What to show users [#what-to-show-users]
| Title | Message | Action |
| --- | --- | --- |
| Data unavailable | This information is not available here. | |
## How to fix [#how-to-fix]
Use an indexer that serves it, e.g. `fallback([bigname(), goldsky()])`.
## Retry safety [#retry-safety]
Retrying the same call fails the same way until the cause is fixed (`retryable: false`).
## Actions that throw it [#actions-that-throw-it]
| Action | When |
| --- | --- |
| [`indexer.getEvents`](/docs/reference/sdk/indexer/get-events) | when the indexer does not serve the query or its namespace. |
| [`indexer.getHistory`](/docs/reference/sdk/indexer/get-history) | when the indexer does not serve the query or its namespace. |
| [`indexer.getName`](/docs/reference/sdk/indexer/get-name) | when the indexer does not serve the query or its namespace. |
| [`indexer.getNamesByExpiry`](/docs/reference/sdk/indexer/get-names-by-expiry) | when the indexer does not serve the query or its namespace. |
| [`indexer.getNamesForAddress`](/docs/reference/sdk/indexer/get-names-for-address) | when the indexer does not serve the query or its namespace. |
| [`indexer.getNamespace`](/docs/reference/sdk/indexer/get-namespace) | when the indexer does not serve the query or its namespace. |
| [`indexer.getPermissions`](/docs/reference/sdk/indexer/get-permissions) | when the indexer does not serve the query or its namespace. |
| [`indexer.getPrimaryName`](/docs/reference/sdk/indexer/get-primary-name) | when the indexer does not serve the query or its namespace. |
| [`indexer.getRecords`](/docs/reference/sdk/indexer/get-records) | when the indexer does not serve the query or its namespace. |
| [`indexer.getRegistry`](/docs/reference/sdk/indexer/get-registry) | when the indexer does not serve the query or its namespace. |
| [`indexer.getRegistryLabels`](/docs/reference/sdk/indexer/get-registry-labels) | when the indexer does not serve the query or its namespace. |
| [`indexer.getResolver`](/docs/reference/sdk/indexer/get-resolver) | when the indexer does not serve the query or its namespace. |
| [`indexer.getResolverLinks`](/docs/reference/sdk/indexer/get-resolver-links) | when the indexer does not serve the query or its namespace. |
| [`indexer.getResolverRoles`](/docs/reference/sdk/indexer/get-resolver-roles) | when the indexer does not serve the query or its namespace. |
| [`indexer.getResolvers`](/docs/reference/sdk/indexer/get-resolvers) | when the indexer does not serve the query or its namespace. |
| [`indexer.getStatus`](/docs/reference/sdk/indexer/get-status) | when the indexer does not serve the query or its namespace. |
| [`indexer.getSubnames`](/docs/reference/sdk/indexer/get-subnames) | when the indexer does not serve the query or its namespace. |
| [`indexer.lookup`](/docs/reference/sdk/indexer/lookup) | when the indexer does not serve the query or its namespace. |
| [`indexer.search`](/docs/reference/sdk/indexer/search) | when the indexer does not serve the query or its namespace. |
## Catch it [#catch-it]
`Errors.hasCode("INDEXER_UNSUPPORTED")` narrows to this error. See [Handle errors](/docs/sdk/handle-errors).
# IndexerError
> For the complete documentation index, see [llms.txt](https://ensforge.com/llms.txt).
What IndexerError means, which codes it carries and how to catch it in ensforge. Lists its fields and every code. Includes how to catch it.
Source: https://ensforge.com/docs/reference/errors/indexer-error
An indexer request failed, or the indexer cannot serve the query ([`INDEXER_UNSUPPORTED`](/docs/reference/errors/INDEXER_UNSUPPORTED)).
## Fields [#fields]
| Field | Type | Description |
| --- | --- | --- |
| `indexerCode` | `string` | The indexer's own error code, e.g. bigname's `rate_limited`. |
| `status` | `number` | HTTP status of the failed request. |
| `route` | `string` | Route that failed, e.g. `/v1/names/{name}`. |
| `source` | `string` | Adapter that failed, e.g. `bigname`. |
## Codes [#codes]
| Code | Meaning | Retryable |
| --- | --- | --- |
| [`INDEXER_UNAVAILABLE`](/docs/reference/errors/INDEXER_UNAVAILABLE) | The indexer is unavailable. | Yes |
| [`INDEXER_RATE_LIMITED`](/docs/reference/errors/INDEXER_RATE_LIMITED) | The indexer is rate limiting requests. | Yes |
| [`INDEXER_RESPONSE_INVALID`](/docs/reference/errors/INDEXER_RESPONSE_INVALID) | The indexer returned an unexpected response. | No |
| [`INDEXER_REQUEST_REJECTED`](/docs/reference/errors/INDEXER_REQUEST_REJECTED) | The indexer rejected the request. | No |
| [`INDEXER_BEHIND`](/docs/reference/errors/INDEXER_BEHIND) | The indexer is behind the chain. | Yes |
| [`INDEXER_UNSUPPORTED`](/docs/reference/errors/INDEXER_UNSUPPORTED) | The indexer does not support this query. | No |
## Catch it [#catch-it]
`Effect.catchTag("IndexerError", …)` or `error instanceof Errors.IndexerError`. See [Handle errors](/docs/sdk/handle-errors).
# INSUFFICIENT_ETH
> For the complete documentation index, see [llms.txt](https://ensforge.com/llms.txt).
What INSUFFICIENT_ETH means, why InsufficientFundsError throws it, what to show users and how to fix it in ensforge. Also covers retry safety.
Source: https://ensforge.com/docs/reference/errors/INSUFFICIENT_ETH
## What happened [#what-happened]
The account does not have enough ETH.
## What to show users [#what-to-show-users]
| Title | Message | Action |
| --- | --- | --- |
| Not enough ETH | Your wallet does not have enough ETH to cover this transaction. | Add ETH to your wallet. |
## Retry safety [#retry-safety]
Retrying the same call fails the same way until the cause is fixed (`retryable: false`).
## Actions that throw it [#actions-that-throw-it]
No action names this code in its documented errors.
Any write can fail with `InsufficientFundsError`: it is part of `Errors.WriteError`.
## Catch it [#catch-it]
`Errors.hasCode("INSUFFICIENT_ETH")` narrows to this error. See [Handle errors](/docs/sdk/handle-errors).
# INSUFFICIENT_TOKEN_BALANCE
> For the complete documentation index, see [llms.txt](https://ensforge.com/llms.txt).
What INSUFFICIENT_TOKEN_BALANCE means, why InsufficientFundsError throws it, what to show users and how to fix it in ensforge.
Source: https://ensforge.com/docs/reference/errors/INSUFFICIENT_TOKEN_BALANCE
## What happened [#what-happened]
The account does not have enough of the payment token.
## What to show users [#what-to-show-users]
| Title | Message | Action |
| --- | --- | --- |
| Insufficient balance | Your wallet does not have enough tokens to pay. | |
## Retry safety [#retry-safety]
Retrying the same call fails the same way until the cause is fixed (`retryable: false`).
## Actions that throw it [#actions-that-throw-it]
| Action | When |
| --- | --- |
| [`registration.register`](/docs/reference/sdk/registration/register) | when the signer cannot pay in the payment token. |
| [`registration.renew`](/docs/reference/sdk/registration/renew) | when the signer cannot pay in the payment token. |
Any write can fail with `InsufficientFundsError`: it is part of `Errors.WriteError`.
## Catch it [#catch-it]
`Errors.hasCode("INSUFFICIENT_TOKEN_BALANCE")` narrows to this error. See [Handle errors](/docs/sdk/handle-errors).
# InsufficientFundsError
> For the complete documentation index, see [llms.txt](https://ensforge.com/llms.txt).
What InsufficientFundsError means, which codes it carries and how to catch it in ensforge. The account cannot pay for the operation.
Source: https://ensforge.com/docs/reference/errors/insufficient-funds-error
The account cannot pay for the operation.
Any write can fail with `InsufficientFundsError`: it is part of `Errors.WriteError`.
## Fields [#fields]
| Field | Type | Description |
| --- | --- | --- |
| `required` | `bigint` | |
| `available` | `bigint` | |
| `token` | `Address` | ERC-20 token, or `undefined` for ETH. |
## Codes [#codes]
| Code | Meaning | Retryable |
| --- | --- | --- |
| [`INSUFFICIENT_ETH`](/docs/reference/errors/INSUFFICIENT_ETH) | The account does not have enough ETH. | No |
| [`INSUFFICIENT_TOKEN_BALANCE`](/docs/reference/errors/INSUFFICIENT_TOKEN_BALANCE) | The account does not have enough of the payment token. | No |
## Catch it [#catch-it]
`Effect.catchTag("InsufficientFundsError", …)` or `error instanceof Errors.InsufficientFundsError`. See [Handle errors](/docs/sdk/handle-errors).
# UNEXPECTED
> For the complete documentation index, see [llms.txt](https://ensforge.com/llms.txt).
What UNEXPECTED means, why InternalError throws it, what to show users and how to fix it in ensforge. Also covers retry safety and the actions that throw it.
Source: https://ensforge.com/docs/reference/errors/UNEXPECTED
## What happened [#what-happened]
An unexpected error occurred.
## What to show users [#what-to-show-users]
| Title | Message | Action |
| --- | --- | --- |
| Something went wrong | An unexpected error occurred. | Try again. If it keeps happening, contact support. |
## How to fix [#how-to-fix]
If this persists, report it at https://github.com/thenamespace/ensforge/issues with the cause.
## Retry safety [#retry-safety]
Retrying the same call fails the same way until the cause is fixed (`retryable: false`).
## Actions that throw it [#actions-that-throw-it]
| Action | When |
| --- | --- |
| [`event.decode`](/docs/reference/sdk/event/decode) | for malformed logs. |
| [`plan.get`](/docs/reference/sdk/plan/get) | when the storage fails. |
Any action can fail with `InternalError`: it is part of `Errors.CommonError`.
## Catch it [#catch-it]
`Errors.hasCode("UNEXPECTED")` narrows to this error. See [Handle errors](/docs/sdk/handle-errors).
# InternalError
> For the complete documentation index, see [llms.txt](https://ensforge.com/llms.txt).
What InternalError means, which codes it carries and how to catch it in ensforge. Something failed that ensforge does not recognise.
Source: https://ensforge.com/docs/reference/errors/internal-error
Something failed that ensforge does not recognise. The original error is in `cause`.
Any action can fail with `InternalError`: it is part of `Errors.CommonError`.
## Codes [#codes]
| Code | Meaning | Retryable |
| --- | --- | --- |
| [`UNEXPECTED`](/docs/reference/errors/UNEXPECTED) | An unexpected error occurred. | No |
## Catch it [#catch-it]
`Effect.catchTag("InternalError", …)` or `error instanceof Errors.InternalError`. See [Handle errors](/docs/sdk/handle-errors).
# DURATION_TOO_SHORT
> For the complete documentation index, see [llms.txt](https://ensforge.com/llms.txt).
What DURATION_TOO_SHORT means, why InvalidInputError throws it, what to show users and how to fix it in ensforge. Also covers retry safety.
Source: https://ensforge.com/docs/reference/errors/DURATION_TOO_SHORT
## What happened [#what-happened]
The duration is shorter than the registrar's minimum.
## What to show users [#what-to-show-users]
| Title | Message | Action |
| --- | --- | --- |
| Duration too short | The registration period is shorter than the minimum. | Choose a longer duration. |
## Retry safety [#retry-safety]
Retrying the same call fails the same way until the cause is fixed (`retryable: false`).
## Actions that throw it [#actions-that-throw-it]
| Action | When |
| --- | --- |
| [`registration.commit`](/docs/reference/sdk/registration/commit) | for invalid input. |
| [`registration.getPrice`](/docs/reference/sdk/registration/get-price) | for invalid input. |
| [`registration.register`](/docs/reference/sdk/registration/register) | for invalid input. |
| [`registration.renew`](/docs/reference/sdk/registration/renew) | for invalid input. |
## Catch it [#catch-it]
`Errors.hasCode("DURATION_TOO_SHORT")` narrows to this error. See [Handle errors](/docs/sdk/handle-errors).
# INVALID_ADDRESS
> For the complete documentation index, see [llms.txt](https://ensforge.com/llms.txt).
What INVALID_ADDRESS means, why InvalidInputError throws it, what to show users and how to fix it in ensforge. Also covers retry safety.
Source: https://ensforge.com/docs/reference/errors/INVALID_ADDRESS
## What happened [#what-happened]
undefined is not a valid address.
## What to show users [#what-to-show-users]
| Title | Message | Action |
| --- | --- | --- |
| Invalid address | This address is not valid. | |
## Retry safety [#retry-safety]
Retrying the same call fails the same way until the cause is fixed (`retryable: false`).
## Actions that throw it [#actions-that-throw-it]
| Action | When |
| --- | --- |
| [`approval.getDelegate`](/docs/reference/sdk/approval/get-delegate) | for invalid input. |
| [`approval.getOperator`](/docs/reference/sdk/approval/get-operator) | for invalid addresses. |
| [`approval.setDelegate`](/docs/reference/sdk/approval/set-delegate) | for invalid input. |
| [`approval.setOperator`](/docs/reference/sdk/approval/set-operator) | for invalid addresses. |
| [`approval.setToken`](/docs/reference/sdk/approval/set-token) | for invalid input. |
| [`dns.claim`](/docs/reference/sdk/dns/claim) | for invalid input. |
| [`indexer.getEvents`](/docs/reference/sdk/indexer/get-events) | for invalid input. |
| [`indexer.getHistory`](/docs/reference/sdk/indexer/get-history) | for invalid input. |
| [`indexer.getNamesForAddress`](/docs/reference/sdk/indexer/get-names-for-address) | for invalid input. |
| [`indexer.getPermissions`](/docs/reference/sdk/indexer/get-permissions) | for invalid input. |
| [`indexer.getPrimaryName`](/docs/reference/sdk/indexer/get-primary-name) | for invalid input. |
| [`indexer.getRecords`](/docs/reference/sdk/indexer/get-records) | for invalid input. |
| [`indexer.getRegistry`](/docs/reference/sdk/indexer/get-registry) | for an invalid address. |
| [`indexer.getRegistryLabels`](/docs/reference/sdk/indexer/get-registry-labels) | for an invalid address. |
| [`indexer.getResolver`](/docs/reference/sdk/indexer/get-resolver) | for an invalid address. |
| [`indexer.getResolverLinks`](/docs/reference/sdk/indexer/get-resolver-links) | for an invalid address. |
| [`indexer.getResolverRoles`](/docs/reference/sdk/indexer/get-resolver-roles) | for an invalid address. |
| [`indexer.getResolvers`](/docs/reference/sdk/indexer/get-resolvers) | for an invalid address. |
| [`migration.get`](/docs/reference/sdk/migration/get) | for invalid input. |
| [`migration.migrate`](/docs/reference/sdk/migration/migrate) | for invalid input. |
| [`name.reclaim`](/docs/reference/sdk/name/reclaim) | for invalid input. |
| [`name.setManager`](/docs/reference/sdk/name/set-manager) | for invalid input. |
| [`name.transfer`](/docs/reference/sdk/name/transfer) | for invalid input. |
| [`permission.check`](/docs/reference/sdk/permission/check) | for invalid input. |
| [`permission.get`](/docs/reference/sdk/permission/get) | for invalid input. |
| [`permission.setRecordAccess`](/docs/reference/sdk/permission/set-record-access) | for invalid input or an unconfirmed widening. |
| [`plan.list`](/docs/reference/sdk/plan/list) | for an invalid account. |
| [`primaryName.get`](/docs/reference/sdk/primary-name/get) | for invalid input, or with `strict` an unnormalized name. |
| [`primaryName.set`](/docs/reference/sdk/primary-name/set) | for invalid input. |
| [`primaryName.signClaim`](/docs/reference/sdk/primary-name/sign-claim) | for invalid input. |
| [`record.set`](/docs/reference/sdk/record/set) | for invalid input. |
| [`registration.commit`](/docs/reference/sdk/registration/commit) | for invalid input. |
| [`registration.getPrice`](/docs/reference/sdk/registration/get-price) | for invalid input. |
| [`registration.getRenewalPrice`](/docs/reference/sdk/registration/get-renewal-price) | for invalid input. |
| [`registration.register`](/docs/reference/sdk/registration/register) | for invalid input. |
| [`registration.renew`](/docs/reference/sdk/registration/renew) | for invalid input. |
| [`registry.attach`](/docs/reference/sdk/registry/attach) | for invalid input. |
| [`registry.deploy`](/docs/reference/sdk/registry/deploy) | for invalid input. |
| [`registry.get`](/docs/reference/sdk/registry/get) | for invalid input. |
| [`registry.setUri`](/docs/reference/sdk/registry/set-uri) | for invalid input. |
| [`registry.upgrade`](/docs/reference/sdk/registry/upgrade) | for invalid input or an up-to-date registry. |
| [`resolver.create`](/docs/reference/sdk/resolver/create) | for invalid input, or a `salt` whose resolver already exists. |
| [`resolver.set`](/docs/reference/sdk/resolver/set) | for invalid input. |
| [`resolver.upgrade`](/docs/reference/sdk/resolver/upgrade) | for invalid input or an up-to-date resolver. |
| [`role.get`](/docs/reference/sdk/role/get) | for invalid input or targets. |
| [`role.grant`](/docs/reference/sdk/role/grant) | for invalid input or targets. |
| [`role.revoke`](/docs/reference/sdk/role/revoke) | for invalid input or targets. |
| [`subname.create`](/docs/reference/sdk/subname/create) | for invalid input. |
| [`subname.update`](/docs/reference/sdk/subname/update) | for invalid input. |
| [`wrapper.unwrap`](/docs/reference/sdk/wrapper/unwrap) | for invalid input. |
| [`wrapper.wrap`](/docs/reference/sdk/wrapper/wrap) | for invalid input or fuses. |
| [`hca.addDeposit`](/docs/reference/hca/hca/add-deposit) | for an invalid address. |
| [`hca.authorizeSession`](/docs/reference/hca/hca/authorize-session) | for invalid addresses. |
| [`hca.get`](/docs/reference/hca/hca/get) | for an invalid address. |
| [`hca.getDeposit`](/docs/reference/hca/hca/get-deposit) | for an invalid address. |
| [`hca.getUpgrade`](/docs/reference/hca/hca/get-upgrade) | for invalid addresses. |
| [`hca.predictAddress`](/docs/reference/hca/hca/predict-address) | for an invalid owner. |
| [`hca.upgrade`](/docs/reference/hca/hca/upgrade) | for an invalid address. |
| [`hca.verify`](/docs/reference/hca/hca/verify) | for an invalid address. |
| [`hca.withdrawDeposit`](/docs/reference/hca/hca/withdraw-deposit) | for an invalid recipient. |
| [`hcaAdmin.getGovernance`](/docs/reference/hca/hca-admin/get-governance) | for an invalid address. |
| [`hcaAdmin.grantUpgradeSetRoles`](/docs/reference/hca/hca-admin/grant-upgrade-set-roles) | for an invalid address. |
| [`hcaAdmin.revokeUpgradeSetRoles`](/docs/reference/hca/hca-admin/revoke-upgrade-set-roles) | for an invalid address. |
| [`hcaAdmin.setDeploymentApproval`](/docs/reference/hca/hca-admin/set-deployment-approval) | for an invalid address. |
| [`hcaAdmin.setUpgradeApproval`](/docs/reference/hca/hca-admin/set-upgrade-approval) | for an invalid address. |
| [`hcaAdmin.transferGovernance`](/docs/reference/hca/hca-admin/transfer-governance) | for an invalid address. |
## Catch it [#catch-it]
`Errors.hasCode("INVALID_ADDRESS")` narrows to this error. See [Handle errors](/docs/sdk/handle-errors).
# INVALID_COIN_TYPE
> For the complete documentation index, see [llms.txt](https://ensforge.com/llms.txt).
What INVALID_COIN_TYPE means, why InvalidInputError throws it, what to show users and how to fix it in ensforge. Also covers retry safety.
Source: https://ensforge.com/docs/reference/errors/INVALID_COIN_TYPE
## What happened [#what-happened]
undefined is not a known coin type.
## What to show users [#what-to-show-users]
| Title | Message | Action |
| --- | --- | --- |
| Unsupported network | This coin or network is not supported. | |
## How to fix [#how-to-fix]
Pass a symbol (`btc`), `{ chainId }` or a numeric coin type.
## Retry safety [#retry-safety]
Retrying the same call fails the same way until the cause is fixed (`retryable: false`).
## Actions that throw it [#actions-that-throw-it]
| Action | When |
| --- | --- |
| [`indexer.getNamesForAddress`](/docs/reference/sdk/indexer/get-names-for-address) | for invalid input. |
| [`indexer.getPrimaryName`](/docs/reference/sdk/indexer/get-primary-name) | for invalid input. |
| [`permission.check`](/docs/reference/sdk/permission/check) | for invalid input. |
| [`primaryName.get`](/docs/reference/sdk/primary-name/get) | for invalid input, or with `strict` an unnormalized name. |
| [`primaryName.set`](/docs/reference/sdk/primary-name/set) | for a coin that is not an EVM chain, or a chain the claim does not cover. |
| [`primaryName.signClaim`](/docs/reference/sdk/primary-name/sign-claim) | when `chainIds` is empty, includes the ENS chain, or mixes mainnet L2s and testnets. |
| [`record.get`](/docs/reference/sdk/record/get) | for invalid input. |
| [`record.getAddress`](/docs/reference/sdk/record/get-address) | for invalid input. |
| [`record.set`](/docs/reference/sdk/record/set) | for invalid input. |
## Catch it [#catch-it]
`Errors.hasCode("INVALID_COIN_TYPE")` narrows to this error. See [Handle errors](/docs/sdk/handle-errors).
# INVALID_CONTENT_HASH
> For the complete documentation index, see [llms.txt](https://ensforge.com/llms.txt).
What INVALID_CONTENT_HASH means, why InvalidInputError throws it, what to show users and how to fix it in ensforge. Also covers retry safety.
Source: https://ensforge.com/docs/reference/errors/INVALID_CONTENT_HASH
## What happened [#what-happened]
undefined is not a valid content hash.
## What to show users [#what-to-show-users]
| Title | Message | Action |
| --- | --- | --- |
| Invalid content link | This content link is not valid. | |
## How to fix [#how-to-fix]
Use a URI such as `ipfs://…`, `ipns://…`, `bzz://…` or `ar://…`.
## Retry safety [#retry-safety]
Retrying the same call fails the same way until the cause is fixed (`retryable: false`).
## Actions that throw it [#actions-that-throw-it]
| Action | When |
| --- | --- |
| [`record.set`](/docs/reference/sdk/record/set) | for invalid input. |
## Catch it [#catch-it]
`Errors.hasCode("INVALID_CONTENT_HASH")` narrows to this error. See [Handle errors](/docs/sdk/handle-errors).
# INVALID_DURATION
> For the complete documentation index, see [llms.txt](https://ensforge.com/llms.txt).
What INVALID_DURATION means, why InvalidInputError throws it, what to show users and how to fix it in ensforge. Also covers retry safety.
Source: https://ensforge.com/docs/reference/errors/INVALID_DURATION
## What happened [#what-happened]
undefined is not a valid duration.
## What to show users [#what-to-show-users]
| Title | Message | Action |
| --- | --- | --- |
| Invalid duration | The chosen duration is not valid. | |
## How to fix [#how-to-fix]
Durations are bigint seconds, e.g. Duration.years(1).
## Retry safety [#retry-safety]
Retrying the same call fails the same way until the cause is fixed (`retryable: false`).
## Actions that throw it [#actions-that-throw-it]
| Action | When |
| --- | --- |
| [`primaryName.signClaim`](/docs/reference/sdk/primary-name/sign-claim) | when `expiresIn` is not between 1 and 3600 seconds. |
## Catch it [#catch-it]
`Errors.hasCode("INVALID_DURATION")` narrows to this error. See [Handle errors](/docs/sdk/handle-errors).
# INVALID_EXPIRY
> For the complete documentation index, see [llms.txt](https://ensforge.com/llms.txt).
What INVALID_EXPIRY means, why InvalidInputError throws it, what to show users and how to fix it in ensforge. Also covers retry safety.
Source: https://ensforge.com/docs/reference/errors/INVALID_EXPIRY
## What happened [#what-happened]
The expiry cannot be in the past or earlier than the current expiry.
## What to show users [#what-to-show-users]
| Title | Message | Action |
| --- | --- | --- |
| Invalid expiry | The new expiry date is not valid. | |
## Retry safety [#retry-safety]
Retrying the same call fails the same way until the cause is fixed (`retryable: false`).
## Actions that throw it [#actions-that-throw-it]
| Action | When |
| --- | --- |
| [`subname.update`](/docs/reference/sdk/subname/update) | for invalid input. |
| [`wrapper.setChildFuses`](/docs/reference/sdk/wrapper/set-child-fuses) | for invalid input or fuses. |
## Catch it [#catch-it]
`Errors.hasCode("INVALID_EXPIRY")` narrows to this error. See [Handle errors](/docs/sdk/handle-errors).
# INVALID_NAME
> For the complete documentation index, see [llms.txt](https://ensforge.com/llms.txt).
What INVALID_NAME means, why InvalidInputError throws it, what to show users and how to fix it in ensforge. Also covers retry safety.
Source: https://ensforge.com/docs/reference/errors/INVALID_NAME
## What happened [#what-happened]
undefined is not a valid ENS name.
## What to show users [#what-to-show-users]
| Title | Message | Action |
| --- | --- | --- |
| Invalid name | This is not a valid ENS name. | Check the spelling and remove unsupported characters. |
## How to fix [#how-to-fix]
Names must normalize under ENSIP-15, e.g. `nick.eth`.
## Retry safety [#retry-safety]
Retrying the same call fails the same way until the cause is fixed (`retryable: false`).
## Actions that throw it [#actions-that-throw-it]
| Action | When |
| --- | --- |
| [`approval.getDelegate`](/docs/reference/sdk/approval/get-delegate) | for invalid input. |
| [`approval.getToken`](/docs/reference/sdk/approval/get-token) | when the name cannot be normalized. |
| [`approval.setDelegate`](/docs/reference/sdk/approval/set-delegate) | for invalid input. |
| [`approval.setToken`](/docs/reference/sdk/approval/set-token) | for invalid input. |
| [`dns.claim`](/docs/reference/sdk/dns/claim) | for invalid input. |
| [`dns.getOffchainResolver`](/docs/reference/sdk/dns/get-offchain-resolver) | for names that are not DNS names. |
| [`dns.getProof`](/docs/reference/sdk/dns/get-proof) | for names that are not DNS names. |
| [`dns.getRecords`](/docs/reference/sdk/dns/get-records) | for invalid names. |
| [`dns.getStatus`](/docs/reference/sdk/dns/get-status) | for names that are not DNS names. |
| [`dns.setRecords`](/docs/reference/sdk/dns/set-records) | for invalid input, such as records that are not DNS wire format. |
| [`event.get`](/docs/reference/sdk/event/get) | for invalid input. |
| [`event.watch`](/docs/reference/sdk/event/watch) | for invalid names. |
| [`indexer.getEvents`](/docs/reference/sdk/indexer/get-events) | for invalid input. |
| [`indexer.getHistory`](/docs/reference/sdk/indexer/get-history) | for invalid input. |
| [`indexer.getName`](/docs/reference/sdk/indexer/get-name) | when the name does not normalize. |
| [`indexer.getNamesByExpiry`](/docs/reference/sdk/indexer/get-names-by-expiry) | when `parent` does not normalize. |
| [`indexer.getNamesForAddress`](/docs/reference/sdk/indexer/get-names-for-address) | for invalid input. |
| [`indexer.getPermissions`](/docs/reference/sdk/indexer/get-permissions) | for invalid input. |
| [`indexer.getRecords`](/docs/reference/sdk/indexer/get-records) | for invalid input. |
| [`indexer.getSubnames`](/docs/reference/sdk/indexer/get-subnames) | when the name does not normalize. |
| [`migration.get`](/docs/reference/sdk/migration/get) | for invalid input. |
| [`migration.migrate`](/docs/reference/sdk/migration/migrate) | for invalid input. |
| [`name.get`](/docs/reference/sdk/name/get) | when the name is invalid or the root. |
| [`name.reclaim`](/docs/reference/sdk/name/reclaim) | for invalid input. |
| [`name.setManager`](/docs/reference/sdk/name/set-manager) | for invalid input. |
| [`name.setTtl`](/docs/reference/sdk/name/set-ttl) | for invalid input. |
| [`name.transfer`](/docs/reference/sdk/name/transfer) | for invalid input. |
| [`permission.check`](/docs/reference/sdk/permission/check) | for invalid input. |
| [`permission.get`](/docs/reference/sdk/permission/get) | for invalid input. |
| [`permission.setRecordAccess`](/docs/reference/sdk/permission/set-record-access) | for invalid input or an unconfirmed widening. |
| [`primaryName.get`](/docs/reference/sdk/primary-name/get) | for invalid input, or with `strict` an unnormalized name. |
| [`primaryName.set`](/docs/reference/sdk/primary-name/set) | for invalid input. |
| [`primaryName.signClaim`](/docs/reference/sdk/primary-name/sign-claim) | for invalid input. |
| [`record.get`](/docs/reference/sdk/record/get) | for invalid input. |
| [`record.getAddress`](/docs/reference/sdk/record/get-address) | for invalid input. |
| [`record.getAvatar`](/docs/reference/sdk/record/get-avatar) | when the name cannot be normalized. |
| [`record.getContentHash`](/docs/reference/sdk/record/get-content-hash) | when the name cannot be normalized. |
| [`record.getText`](/docs/reference/sdk/record/get-text) | when the name cannot be normalized. |
| [`record.set`](/docs/reference/sdk/record/set) | for invalid input. |
| [`registration.commit`](/docs/reference/sdk/registration/commit) | for invalid input. |
| [`registration.getPrice`](/docs/reference/sdk/registration/get-price) | for invalid input. |
| [`registration.getRenewalPrice`](/docs/reference/sdk/registration/get-renewal-price) | for invalid input. |
| [`registration.isAvailable`](/docs/reference/sdk/registration/is-available) | for names that are not `.eth` second-level names. |
| [`registration.register`](/docs/reference/sdk/registration/register) | for invalid input. |
| [`registration.renew`](/docs/reference/sdk/registration/renew) | for invalid input. |
| [`registry.attach`](/docs/reference/sdk/registry/attach) | for invalid input. |
| [`registry.deploy`](/docs/reference/sdk/registry/deploy) | for invalid input. |
| [`registry.get`](/docs/reference/sdk/registry/get) | for invalid input. |
| [`registry.setUri`](/docs/reference/sdk/registry/set-uri) | for invalid input. |
| [`registry.upgrade`](/docs/reference/sdk/registry/upgrade) | for invalid input or an up-to-date registry. |
| [`resolver.create`](/docs/reference/sdk/resolver/create) | for invalid input, or a `salt` whose resolver already exists. |
| [`resolver.get`](/docs/reference/sdk/resolver/get) | when the name cannot be normalized. |
| [`resolver.getLink`](/docs/reference/sdk/resolver/get-link) | when the name cannot be normalized. |
| [`resolver.link`](/docs/reference/sdk/resolver/link) | for invalid input or a target without records. |
| [`resolver.resolve`](/docs/reference/sdk/resolver/resolve) | for an invalid name or calldata. |
| [`resolver.set`](/docs/reference/sdk/resolver/set) | for invalid input. |
| [`resolver.upgrade`](/docs/reference/sdk/resolver/upgrade) | for invalid input or an up-to-date resolver. |
| [`role.get`](/docs/reference/sdk/role/get) | for invalid input or targets. |
| [`role.grant`](/docs/reference/sdk/role/grant) | for invalid input or targets. |
| [`role.revoke`](/docs/reference/sdk/role/revoke) | for invalid input or targets. |
| [`subname.create`](/docs/reference/sdk/subname/create) | for invalid input. |
| [`subname.remove`](/docs/reference/sdk/subname/remove) | for invalid input. |
| [`subname.update`](/docs/reference/sdk/subname/update) | for invalid input. |
| [`wrapper.getFuses`](/docs/reference/sdk/wrapper/get-fuses) | for invalid names. |
| [`wrapper.setChildFuses`](/docs/reference/sdk/wrapper/set-child-fuses) | for invalid input or fuses. |
| [`wrapper.setFuses`](/docs/reference/sdk/wrapper/set-fuses) | for invalid input or fuses. |
| [`wrapper.unwrap`](/docs/reference/sdk/wrapper/unwrap) | for invalid input. |
| [`wrapper.wrap`](/docs/reference/sdk/wrapper/wrap) | for invalid input or fuses. |
## Catch it [#catch-it]
`Errors.hasCode("INVALID_NAME")` narrows to this error. See [Handle errors](/docs/sdk/handle-errors).
# INVALID_RECORD_VALUE
> For the complete documentation index, see [llms.txt](https://ensforge.com/llms.txt).
What INVALID_RECORD_VALUE means, why InvalidInputError throws it, what to show users and how to fix it in ensforge. Also covers retry safety.
Source: https://ensforge.com/docs/reference/errors/INVALID_RECORD_VALUE
## What happened [#what-happened]
undefined is not a valid record value.
## What to show users [#what-to-show-users]
| Title | Message | Action |
| --- | --- | --- |
| Invalid value | One of the values is not valid. | |
## Retry safety [#retry-safety]
Retrying the same call fails the same way until the cause is fixed (`retryable: false`).
## Actions that throw it [#actions-that-throw-it]
| Action | When |
| --- | --- |
| [`dns.claim`](/docs/reference/sdk/dns/claim) | for invalid input. |
| [`dns.setRecords`](/docs/reference/sdk/dns/set-records) | for invalid input, such as records that are not DNS wire format. |
| [`event.get`](/docs/reference/sdk/event/get) | for invalid input. |
| [`indexer.getPermissions`](/docs/reference/sdk/indexer/get-permissions) | for invalid input. |
| [`indexer.lookup`](/docs/reference/sdk/indexer/lookup) | for more than 1,000 inputs or none. |
| [`indexer.search`](/docs/reference/sdk/indexer/search) | when `query` is empty. |
| [`migration.migrate`](/docs/reference/sdk/migration/migrate) | for invalid input. |
| [`name.getLabel`](/docs/reference/sdk/name/get-label) | when `labelhash` is not 32 bytes. |
| [`name.setTtl`](/docs/reference/sdk/name/set-ttl) | for invalid input. |
| [`permission.setRecordAccess`](/docs/reference/sdk/permission/set-record-access) | for invalid input or an unconfirmed widening. |
| [`plan.reconcile`](/docs/reference/sdk/plan/reconcile) | for an unknown step or an unrelated transaction. |
| [`record.set`](/docs/reference/sdk/record/set) | for invalid input. |
| [`registration.commit`](/docs/reference/sdk/registration/commit) | for invalid input. |
| [`registration.getCommitmentStatus`](/docs/reference/sdk/registration/get-commitment-status) | when the commitment is not 32 bytes. |
| [`registration.register`](/docs/reference/sdk/registration/register) | for invalid input. |
| [`registry.upgrade`](/docs/reference/sdk/registry/upgrade) | for invalid input or an up-to-date registry. |
| [`resolver.create`](/docs/reference/sdk/resolver/create) | for invalid input, or a `salt` whose resolver already exists. |
| [`resolver.link`](/docs/reference/sdk/resolver/link) | for invalid input or a target without records. |
| [`resolver.resolve`](/docs/reference/sdk/resolver/resolve) | for an invalid name or calldata. |
| [`resolver.upgrade`](/docs/reference/sdk/resolver/upgrade) | for invalid input or an up-to-date resolver. |
| [`role.get`](/docs/reference/sdk/role/get) | for invalid input or targets. |
| [`role.grant`](/docs/reference/sdk/role/grant) | for invalid input or targets. |
| [`role.revoke`](/docs/reference/sdk/role/revoke) | for invalid input or targets. |
| [`subname.create`](/docs/reference/sdk/subname/create) | for invalid input. |
| [`subname.update`](/docs/reference/sdk/subname/update) | for invalid input. |
| [`wrapper.setChildFuses`](/docs/reference/sdk/wrapper/set-child-fuses) | for invalid input or fuses. |
| [`wrapper.setFuses`](/docs/reference/sdk/wrapper/set-fuses) | for invalid input or fuses. |
| [`wrapper.wrap`](/docs/reference/sdk/wrapper/wrap) | for invalid input or fuses. |
| [`batch`](/docs/reference/sdk/batch) | for a request that cannot be batched. |
## Catch it [#catch-it]
`Errors.hasCode("INVALID_RECORD_VALUE")` narrows to this error. See [Handle errors](/docs/sdk/handle-errors).
# INVALID_ROLES
> For the complete documentation index, see [llms.txt](https://ensforge.com/llms.txt).
What INVALID_ROLES means, why InvalidInputError throws it, what to show users and how to fix it in ensforge. Also covers retry safety.
Source: https://ensforge.com/docs/reference/errors/INVALID_ROLES
## What happened [#what-happened]
undefined is not a valid role bitmap.
## What to show users [#what-to-show-users]
| Title | Message | Action |
| --- | --- | --- |
| Invalid permissions | The selected permissions are not valid. | |
## Retry safety [#retry-safety]
Retrying the same call fails the same way until the cause is fixed (`retryable: false`).
## Actions that throw it [#actions-that-throw-it]
| Action | When |
| --- | --- |
| [`registry.deploy`](/docs/reference/sdk/registry/deploy) | for invalid input. |
| [`resolver.create`](/docs/reference/sdk/resolver/create) | for invalid input, or a `salt` whose resolver already exists. |
| [`role.grant`](/docs/reference/sdk/role/grant) | for invalid input or targets. |
| [`role.revoke`](/docs/reference/sdk/role/revoke) | for invalid input or targets. |
| [`subname.create`](/docs/reference/sdk/subname/create) | for invalid input. |
## Catch it [#catch-it]
`Errors.hasCode("INVALID_ROLES")` narrows to this error. See [Handle errors](/docs/sdk/handle-errors).
# SALT_TAKEN
> For the complete documentation index, see [llms.txt](https://ensforge.com/llms.txt).
What SALT_TAKEN means, why InvalidInputError throws it, what to show users and how to fix it in ensforge. Also covers retry safety.
Source: https://ensforge.com/docs/reference/errors/SALT_TAKEN
## What happened [#what-happened]
A contract was already deployed with this salt.
## What to show users [#what-to-show-users]
| Title | Message | Action |
| --- | --- | --- |
| Already created | A resolver was already created with these settings. | Use the existing resolver, or create a new one. |
## How to fix [#how-to-fix]
Use the existing contract, or pass another `salt`.
## Retry safety [#retry-safety]
Retrying the same call fails the same way until the cause is fixed (`retryable: false`).
## Actions that throw it [#actions-that-throw-it]
| Action | When |
| --- | --- |
| [`resolver.create`](/docs/reference/sdk/resolver/create) | for invalid input, or a `salt` whose resolver already exists. |
## Catch it [#catch-it]
`Errors.hasCode("SALT_TAKEN")` narrows to this error. See [Handle errors](/docs/sdk/handle-errors).
# InvalidInputError
> For the complete documentation index, see [llms.txt](https://ensforge.com/llms.txt).
What InvalidInputError means, which codes it carries and how to catch it in ensforge. An argument is invalid. Lists its fields and every code.
Source: https://ensforge.com/docs/reference/errors/invalid-input-error
An argument is invalid. Detected before any network request.
## Fields [#fields]
| Field | Type | Description |
| --- | --- | --- |
| `input` | `unknown` | The rejected value. |
| `field` | `string` | The option it was passed as, when relevant. |
## Codes [#codes]
| Code | Meaning | Retryable |
| --- | --- | --- |
| [`INVALID_NAME`](/docs/reference/errors/INVALID_NAME) | undefined is not a valid ENS name. | No |
| [`INVALID_ADDRESS`](/docs/reference/errors/INVALID_ADDRESS) | undefined is not a valid address. | No |
| [`INVALID_COIN_TYPE`](/docs/reference/errors/INVALID_COIN_TYPE) | undefined is not a known coin type. | No |
| [`INVALID_CONTENT_HASH`](/docs/reference/errors/INVALID_CONTENT_HASH) | undefined is not a valid content hash. | No |
| [`INVALID_RECORD_VALUE`](/docs/reference/errors/INVALID_RECORD_VALUE) | undefined is not a valid record value. | No |
| [`INVALID_DURATION`](/docs/reference/errors/INVALID_DURATION) | undefined is not a valid duration. | No |
| [`DURATION_TOO_SHORT`](/docs/reference/errors/DURATION_TOO_SHORT) | The duration is shorter than the registrar's minimum. | No |
| [`INVALID_EXPIRY`](/docs/reference/errors/INVALID_EXPIRY) | The expiry cannot be in the past or earlier than the current expiry. | No |
| [`INVALID_ROLES`](/docs/reference/errors/INVALID_ROLES) | undefined is not a valid role bitmap. | No |
| [`SALT_TAKEN`](/docs/reference/errors/SALT_TAKEN) | A contract was already deployed with this salt. | No |
## Catch it [#catch-it]
`Effect.catchTag("InvalidInputError", …)` or `error instanceof Errors.InvalidInputError`. See [Handle errors](/docs/sdk/handle-errors).
# ALREADY_MIGRATED
> For the complete documentation index, see [llms.txt](https://ensforge.com/llms.txt).
What ALREADY_MIGRATED means, why MigrationError throws it, what to show users and how to fix it in ensforge. Also covers retry safety.
Source: https://ensforge.com/docs/reference/errors/ALREADY_MIGRATED
## What happened [#what-happened]
The name is already on ENSv2.
## What to show users [#what-to-show-users]
| Title | Message | Action |
| --- | --- | --- |
| Already upgraded | This name is already upgraded. | |
## Retry safety [#retry-safety]
Retrying the same call fails the same way until the cause is fixed (`retryable: false`).
## Actions that throw it [#actions-that-throw-it]
| Action | When |
| --- | --- |
| [`migration.migrate`](/docs/reference/sdk/migration/migrate) | when a name cannot migrate as asked. |
## Catch it [#catch-it]
`Errors.hasCode("ALREADY_MIGRATED")` narrows to this error. See [Handle errors](/docs/sdk/handle-errors).
# NAME_NOT_LOCKED
> For the complete documentation index, see [llms.txt](https://ensforge.com/llms.txt).
What NAME_NOT_LOCKED means, why MigrationError throws it, what to show users and how to fix it in ensforge. Also covers retry safety.
Source: https://ensforge.com/docs/reference/errors/NAME_NOT_LOCKED
## What happened [#what-happened]
The wrapped name is not locked, so it cannot use the locked migration route.
## What to show users [#what-to-show-users]
| Title | Message | Action |
| --- | --- | --- |
| Upgrade unavailable | This name cannot use this upgrade path. | |
## Retry safety [#retry-safety]
Retrying the same call fails the same way until the cause is fixed (`retryable: false`).
## Actions that throw it [#actions-that-throw-it]
| Action | When |
| --- | --- |
| [`migration.migrate`](/docs/reference/sdk/migration/migrate) | when a name cannot migrate as asked. |
## Catch it [#catch-it]
`Errors.hasCode("NAME_NOT_LOCKED")` narrows to this error. See [Handle errors](/docs/sdk/handle-errors).
# NOT_ELIGIBLE
> For the complete documentation index, see [llms.txt](https://ensforge.com/llms.txt).
What NOT_ELIGIBLE means, why MigrationError throws it, what to show users and how to fix it in ensforge. Also covers retry safety and the actions that throw it.
Source: https://ensforge.com/docs/reference/errors/NOT_ELIGIBLE
## What happened [#what-happened]
The name cannot be migrated to ENSv2 yet.
## What to show users [#what-to-show-users]
| Title | Message | Action |
| --- | --- | --- |
| Upgrade unavailable | This name cannot be upgraded to the new ENS yet. | |
## Retry safety [#retry-safety]
Retrying the same call fails the same way until the cause is fixed (`retryable: false`).
## Actions that throw it [#actions-that-throw-it]
| Action | When |
| --- | --- |
| [`migration.migrate`](/docs/reference/sdk/migration/migrate) | when a name cannot migrate as asked. |
## Catch it [#catch-it]
`Errors.hasCode("NOT_ELIGIBLE")` narrows to this error. See [Handle errors](/docs/sdk/handle-errors).
# RECORDS_UNKNOWN
> For the complete documentation index, see [llms.txt](https://ensforge.com/llms.txt).
What RECORDS_UNKNOWN means, why MigrationError throws it, what to show users and how to fix it in ensforge. Also covers retry safety.
Source: https://ensforge.com/docs/reference/errors/RECORDS_UNKNOWN
## What happened [#what-happened]
The name's records are not known, so they cannot be copied to its new resolver.
## What to show users [#what-to-show-users]
| Title | Message | Action |
| --- | --- | --- |
| Profile needed | The records of This name must be provided before it can be upgraded. | |
## Retry safety [#retry-safety]
Retrying the same call fails the same way until the cause is fixed (`retryable: false`).
## Actions that throw it [#actions-that-throw-it]
| Action | When |
| --- | --- |
| [`migration.migrate`](/docs/reference/sdk/migration/migrate) | when a name cannot migrate as asked. |
## Catch it [#catch-it]
`Errors.hasCode("RECORDS_UNKNOWN")` narrows to this error. See [Handle errors](/docs/sdk/handle-errors).
# VERIFICATION_FAILED
> For the complete documentation index, see [llms.txt](https://ensforge.com/llms.txt).
What VERIFICATION_FAILED means, why MigrationError throws it, what to show users and how to fix it in ensforge. Also covers retry safety.
Source: https://ensforge.com/docs/reference/errors/VERIFICATION_FAILED
## What happened [#what-happened]
The migration was sent, but the name's ENSv2 state differs from the plan.
## What to show users [#what-to-show-users]
| Title | Message | Action |
| --- | --- | --- |
| Upgrade incomplete | This name was upgraded, but its new state does not match the plan. | |
## Retry safety [#retry-safety]
Retrying the same call fails the same way until the cause is fixed (`retryable: false`).
## Actions that throw it [#actions-that-throw-it]
| Action | When |
| --- | --- |
| [`migration.migrate`](/docs/reference/sdk/migration/migrate) | when a migrated name's ENSv2 state differs from the plan. |
## Catch it [#catch-it]
`Errors.hasCode("VERIFICATION_FAILED")` narrows to this error. See [Handle errors](/docs/sdk/handle-errors).
# MigrationError
> For the complete documentation index, see [llms.txt](https://ensforge.com/llms.txt).
What MigrationError means, which codes it carries and how to catch it in ensforge. ENSv1 to ENSv2 migration is blocked for this name.
Source: https://ensforge.com/docs/reference/errors/migration-error
ENSv1 to ENSv2 migration is blocked for this name.
## Fields [#fields]
| Field | Type | Description |
| --- | --- | --- |
| `blockers` | `readonly string[]` | |
## Codes [#codes]
| Code | Meaning | Retryable |
| --- | --- | --- |
| [`NOT_ELIGIBLE`](/docs/reference/errors/NOT_ELIGIBLE) | The name cannot be migrated to ENSv2 yet. | No |
| [`ALREADY_MIGRATED`](/docs/reference/errors/ALREADY_MIGRATED) | The name is already on ENSv2. | No |
| [`NAME_NOT_LOCKED`](/docs/reference/errors/NAME_NOT_LOCKED) | The wrapped name is not locked, so it cannot use the locked migration route. | No |
| [`RECORDS_UNKNOWN`](/docs/reference/errors/RECORDS_UNKNOWN) | The name's records are not known, so they cannot be copied to its new resolver. | No |
| [`VERIFICATION_FAILED`](/docs/reference/errors/VERIFICATION_FAILED) | The migration was sent, but the name's ENSv2 state differs from the plan. | No |
## Catch it [#catch-it]
`Effect.catchTag("MigrationError", …)` or `error instanceof Errors.MigrationError`. See [Handle errors](/docs/sdk/handle-errors).
# NAME_EXPIRED
> For the complete documentation index, see [llms.txt](https://ensforge.com/llms.txt).
What NAME_EXPIRED means, why NameStateError throws it, what to show users and how to fix it in ensforge. Also covers retry safety and the actions that throw it.
Source: https://ensforge.com/docs/reference/errors/NAME_EXPIRED
## What happened [#what-happened]
The name has expired.
## What to show users [#what-to-show-users]
| Title | Message | Action |
| --- | --- | --- |
| Name expired | This name has expired. | Renew it to continue. |
## Retry safety [#retry-safety]
Retrying the same call fails the same way until the cause is fixed (`retryable: false`).
## Actions that throw it [#actions-that-throw-it]
| Action | When |
| --- | --- |
| [`approval.setToken`](/docs/reference/sdk/approval/set-token) | when the name is not registered. |
| [`dns.setRecords`](/docs/reference/sdk/dns/set-records) | when the name is not registered. |
| [`name.reclaim`](/docs/reference/sdk/name/reclaim) | when the name is not registered. |
| [`name.setManager`](/docs/reference/sdk/name/set-manager) | when the name is not registered. |
| [`name.setTtl`](/docs/reference/sdk/name/set-ttl) | when the name is not registered. |
| [`name.transfer`](/docs/reference/sdk/name/transfer) | when the name cannot be sent. |
| [`record.set`](/docs/reference/sdk/record/set) | when the name is not registered. |
| [`registry.attach`](/docs/reference/sdk/registry/attach) | when the name is not registered. |
| [`resolver.create`](/docs/reference/sdk/resolver/create) | when the name is not registered. |
| [`resolver.link`](/docs/reference/sdk/resolver/link) | when the name is not registered. |
| [`resolver.set`](/docs/reference/sdk/resolver/set) | when the name is not registered. |
| [`subname.create`](/docs/reference/sdk/subname/create) | when the child exists or the parent is not registered. |
| [`subname.remove`](/docs/reference/sdk/subname/remove) | when the child or parent does not exist. |
| [`subname.update`](/docs/reference/sdk/subname/update) | when the child or parent does not exist, or an emancipated child expired. |
| [`wrapper.setChildFuses`](/docs/reference/sdk/wrapper/set-child-fuses) | when the name is not wrapped. |
| [`wrapper.setFuses`](/docs/reference/sdk/wrapper/set-fuses) | when the name is not wrapped. |
| [`wrapper.unwrap`](/docs/reference/sdk/wrapper/unwrap) | when the name is not wrapped. |
| [`wrapper.wrap`](/docs/reference/sdk/wrapper/wrap) | when the name cannot be wrapped. |
## Catch it [#catch-it]
`Errors.hasCode("NAME_EXPIRED")` narrows to this error. See [Handle errors](/docs/sdk/handle-errors).
# NAME_LOCKED
> For the complete documentation index, see [llms.txt](https://ensforge.com/llms.txt).
What NAME_LOCKED means, why NameStateError throws it, what to show users and how to fix it in ensforge. Also covers retry safety and the actions that throw it.
Source: https://ensforge.com/docs/reference/errors/NAME_LOCKED
## What happened [#what-happened]
The name is locked.
## What to show users [#what-to-show-users]
| Title | Message | Action |
| --- | --- | --- |
| Name locked | This name is locked and cannot be changed. | |
## Retry safety [#retry-safety]
Retrying the same call fails the same way until the cause is fixed (`retryable: false`).
## Actions that throw it [#actions-that-throw-it]
| Action | When |
| --- | --- |
| [`migration.migrate`](/docs/reference/sdk/migration/migrate) | when the name is locked. |
## Catch it [#catch-it]
`Errors.hasCode("NAME_LOCKED")` narrows to this error. See [Handle errors](/docs/sdk/handle-errors).
# NAME_NOT_AVAILABLE
> For the complete documentation index, see [llms.txt](https://ensforge.com/llms.txt).
What NAME_NOT_AVAILABLE means, why NameStateError throws it, what to show users and how to fix it in ensforge. Also covers retry safety.
Source: https://ensforge.com/docs/reference/errors/NAME_NOT_AVAILABLE
## What happened [#what-happened]
The name is already registered.
## What to show users [#what-to-show-users]
| Title | Message | Action |
| --- | --- | --- |
| Name not available | This name is already registered. | Try a different name. |
## Retry safety [#retry-safety]
Retrying the same call fails the same way until the cause is fixed (`retryable: false`).
## Actions that throw it [#actions-that-throw-it]
| Action | When |
| --- | --- |
| [`registration.commit`](/docs/reference/sdk/registration/commit) | when a name is taken or in its grace period. |
| [`registration.register`](/docs/reference/sdk/registration/register) | when a name is taken or in its grace period. |
| [`subname.create`](/docs/reference/sdk/subname/create) | when the child exists or the parent is not registered. |
## Catch it [#catch-it]
`Errors.hasCode("NAME_NOT_AVAILABLE")` narrows to this error. See [Handle errors](/docs/sdk/handle-errors).
# NAME_NOT_REGISTERED
> For the complete documentation index, see [llms.txt](https://ensforge.com/llms.txt).
What NAME_NOT_REGISTERED means, why NameStateError throws it, what to show users and how to fix it in ensforge. Also covers retry safety.
Source: https://ensforge.com/docs/reference/errors/NAME_NOT_REGISTERED
## What happened [#what-happened]
The name is not registered.
## What to show users [#what-to-show-users]
| Title | Message | Action |
| --- | --- | --- |
| Name not registered | This name is not registered. | |
## Retry safety [#retry-safety]
Retrying the same call fails the same way until the cause is fixed (`retryable: false`).
## Actions that throw it [#actions-that-throw-it]
| Action | When |
| --- | --- |
| [`approval.setToken`](/docs/reference/sdk/approval/set-token) | when the name is not registered. |
| [`dns.setRecords`](/docs/reference/sdk/dns/set-records) | when the name is not registered. |
| [`name.reclaim`](/docs/reference/sdk/name/reclaim) | when the name is not registered. |
| [`name.setManager`](/docs/reference/sdk/name/set-manager) | when the name is not registered. |
| [`name.setTtl`](/docs/reference/sdk/name/set-ttl) | when the name is not registered. |
| [`name.transfer`](/docs/reference/sdk/name/transfer) | when the name cannot be sent. |
| [`record.set`](/docs/reference/sdk/record/set) | when the name is not registered. |
| [`registry.attach`](/docs/reference/sdk/registry/attach) | when the name is not registered. |
| [`resolver.create`](/docs/reference/sdk/resolver/create) | when the name is not registered. |
| [`resolver.link`](/docs/reference/sdk/resolver/link) | when the name is not registered. |
| [`resolver.set`](/docs/reference/sdk/resolver/set) | when the name is not registered. |
| [`subname.create`](/docs/reference/sdk/subname/create) | when the child exists or the parent is not registered. |
| [`subname.remove`](/docs/reference/sdk/subname/remove) | when the child or parent does not exist. |
| [`subname.update`](/docs/reference/sdk/subname/update) | when the child or parent does not exist, or an emancipated child expired. |
| [`wrapper.setChildFuses`](/docs/reference/sdk/wrapper/set-child-fuses) | when the name is not wrapped. |
| [`wrapper.setFuses`](/docs/reference/sdk/wrapper/set-fuses) | when the name is not wrapped. |
| [`wrapper.unwrap`](/docs/reference/sdk/wrapper/unwrap) | when the name is not wrapped. |
| [`wrapper.wrap`](/docs/reference/sdk/wrapper/wrap) | when the name cannot be wrapped. |
## Catch it [#catch-it]
`Errors.hasCode("NAME_NOT_REGISTERED")` narrows to this error. See [Handle errors](/docs/sdk/handle-errors).
# NAME_NOT_RENEWABLE
> For the complete documentation index, see [llms.txt](https://ensforge.com/llms.txt).
What NAME_NOT_RENEWABLE means, why NameStateError throws it, what to show users and how to fix it in ensforge. Also covers retry safety.
Source: https://ensforge.com/docs/reference/errors/NAME_NOT_RENEWABLE
## What happened [#what-happened]
The name cannot be renewed.
## What to show users [#what-to-show-users]
| Title | Message | Action |
| --- | --- | --- |
| Cannot renew | This name cannot be renewed. | |
## Retry safety [#retry-safety]
Retrying the same call fails the same way until the cause is fixed (`retryable: false`).
## Actions that throw it [#actions-that-throw-it]
| Action | When |
| --- | --- |
| [`registration.getRenewalPrice`](/docs/reference/sdk/registration/get-renewal-price) | when a name is neither registered nor in its grace period. |
| [`registration.renew`](/docs/reference/sdk/registration/renew) | when a name is neither registered nor in its grace period. |
## Catch it [#catch-it]
`Errors.hasCode("NAME_NOT_RENEWABLE")` narrows to this error. See [Handle errors](/docs/sdk/handle-errors).
# NAME_NOT_WRAPPED
> For the complete documentation index, see [llms.txt](https://ensforge.com/llms.txt).
What NAME_NOT_WRAPPED means, why NameStateError throws it, what to show users and how to fix it in ensforge. Also covers retry safety.
Source: https://ensforge.com/docs/reference/errors/NAME_NOT_WRAPPED
## What happened [#what-happened]
The name is not wrapped in the NameWrapper.
## What to show users [#what-to-show-users]
| Title | Message | Action |
| --- | --- | --- |
| Name not wrapped | This name is not wrapped. | |
## Retry safety [#retry-safety]
Retrying the same call fails the same way until the cause is fixed (`retryable: false`).
## Actions that throw it [#actions-that-throw-it]
| Action | When |
| --- | --- |
| [`wrapper.setChildFuses`](/docs/reference/sdk/wrapper/set-child-fuses) | when the name is not wrapped. |
| [`wrapper.setFuses`](/docs/reference/sdk/wrapper/set-fuses) | when the name is not wrapped. |
| [`wrapper.unwrap`](/docs/reference/sdk/wrapper/unwrap) | when the name is not wrapped. |
## Catch it [#catch-it]
`Errors.hasCode("NAME_NOT_WRAPPED")` narrows to this error. See [Handle errors](/docs/sdk/handle-errors).
# NAME_REQUIRES_MIGRATION
> For the complete documentation index, see [llms.txt](https://ensforge.com/llms.txt).
What NAME_REQUIRES_MIGRATION means, why NameStateError throws it, what to show users and how to fix it in ensforge. Also covers retry safety.
Source: https://ensforge.com/docs/reference/errors/NAME_REQUIRES_MIGRATION
## What happened [#what-happened]
The name must be migrated to ENSv2 first.
## What to show users [#what-to-show-users]
| Title | Message | Action |
| --- | --- | --- |
| Upgrade required | This name needs to be upgraded to the new ENS first. | Upgrade the name. |
## How to fix [#how-to-fix]
Use migration.migrate.
## Retry safety [#retry-safety]
Retrying the same call fails the same way until the cause is fixed (`retryable: false`).
## Actions that throw it [#actions-that-throw-it]
No action names this code in its documented errors.
## Catch it [#catch-it]
`Errors.hasCode("NAME_REQUIRES_MIGRATION")` narrows to this error. See [Handle errors](/docs/sdk/handle-errors).
# NAME_RESERVED
> For the complete documentation index, see [llms.txt](https://ensforge.com/llms.txt).
What NAME_RESERVED means, why NameStateError throws it, what to show users and how to fix it in ensforge. Also covers retry safety.
Source: https://ensforge.com/docs/reference/errors/NAME_RESERVED
## What happened [#what-happened]
The name is reserved.
## What to show users [#what-to-show-users]
| Title | Message | Action |
| --- | --- | --- |
| Name reserved | This name is reserved. | |
## Retry safety [#retry-safety]
Retrying the same call fails the same way until the cause is fixed (`retryable: false`).
## Actions that throw it [#actions-that-throw-it]
| Action | When |
| --- | --- |
| [`dns.setRecords`](/docs/reference/sdk/dns/set-records) | when the name is not registered. |
| [`name.reclaim`](/docs/reference/sdk/name/reclaim) | when the name is not registered. |
| [`name.setManager`](/docs/reference/sdk/name/set-manager) | when the name is not registered. |
| [`name.setTtl`](/docs/reference/sdk/name/set-ttl) | when the name is not registered. |
| [`name.transfer`](/docs/reference/sdk/name/transfer) | when the name cannot be sent. |
| [`record.set`](/docs/reference/sdk/record/set) | when the name is not registered. |
| [`resolver.create`](/docs/reference/sdk/resolver/create) | when the name is not registered. |
| [`resolver.link`](/docs/reference/sdk/resolver/link) | when the name is not registered. |
| [`resolver.set`](/docs/reference/sdk/resolver/set) | when the name is not registered. |
| [`subname.create`](/docs/reference/sdk/subname/create) | when the parent is reserved or ENSv2 resolution no longer reaches it. |
| [`subname.remove`](/docs/reference/sdk/subname/remove) | when the parent is reserved or ENSv2 resolution no longer reaches it. |
| [`subname.update`](/docs/reference/sdk/subname/update) | when the parent is reserved or ENSv2 resolution no longer reaches it. |
## Catch it [#catch-it]
`Errors.hasCode("NAME_RESERVED")` narrows to this error. See [Handle errors](/docs/sdk/handle-errors).
# NAME_UNREACHABLE
> For the complete documentation index, see [llms.txt](https://ensforge.com/llms.txt).
What NAME_UNREACHABLE means, why NameStateError throws it, what to show users and how to fix it in ensforge. Also covers retry safety.
Source: https://ensforge.com/docs/reference/errors/NAME_UNREACHABLE
## What happened [#what-happened]
ENSv2 resolution no longer reaches this ENSv1 name.
## What to show users [#what-to-show-users]
| Title | Message | Action |
| --- | --- | --- |
| Name unreachable | This name no longer resolves: ENSv2 resolution does not reach its ENSv1 records. | |
## How to fix [#how-to-fix]
ENSv2 resolves it elsewhere: an ancestor moved to ENSv2 without it, or ENSv2 holds no reservation for it. Ask the parent's owner to recreate it there.
## Retry safety [#retry-safety]
Retrying the same call fails the same way until the cause is fixed (`retryable: false`).
## Actions that throw it [#actions-that-throw-it]
| Action | When |
| --- | --- |
| [`approval.setToken`](/docs/reference/sdk/approval/set-token) | when ENSv2 resolution no longer reaches the name. |
| [`dns.setRecords`](/docs/reference/sdk/dns/set-records) | when ENSv2 resolution no longer reaches the name. |
| [`name.reclaim`](/docs/reference/sdk/name/reclaim) | when ENSv2 resolution no longer reaches the name. |
| [`name.setManager`](/docs/reference/sdk/name/set-manager) | when ENSv2 resolution no longer reaches the name. |
| [`name.setTtl`](/docs/reference/sdk/name/set-ttl) | when ENSv2 resolution no longer reaches the name. |
| [`name.transfer`](/docs/reference/sdk/name/transfer) | when ENSv2 resolution no longer reaches the name. |
| [`record.set`](/docs/reference/sdk/record/set) | when ENSv2 resolution no longer reaches the name. |
| [`registry.attach`](/docs/reference/sdk/registry/attach) | when ENSv2 resolution no longer reaches the name. |
| [`resolver.create`](/docs/reference/sdk/resolver/create) | when ENSv2 resolution no longer reaches the name. |
| [`resolver.link`](/docs/reference/sdk/resolver/link) | when ENSv2 resolution no longer reaches the name. |
| [`resolver.set`](/docs/reference/sdk/resolver/set) | when ENSv2 resolution no longer reaches the name. |
| [`subname.create`](/docs/reference/sdk/subname/create) | when the parent is reserved or ENSv2 resolution no longer reaches it. |
| [`subname.remove`](/docs/reference/sdk/subname/remove) | when the parent is reserved or ENSv2 resolution no longer reaches it. |
| [`subname.update`](/docs/reference/sdk/subname/update) | when the parent is reserved or ENSv2 resolution no longer reaches it. |
| [`wrapper.setChildFuses`](/docs/reference/sdk/wrapper/set-child-fuses) | when ENSv2 resolution no longer reaches the name. |
| [`wrapper.setFuses`](/docs/reference/sdk/wrapper/set-fuses) | when ENSv2 resolution no longer reaches the name. |
| [`wrapper.unwrap`](/docs/reference/sdk/wrapper/unwrap) | when ENSv2 resolution no longer reaches the name. |
| [`wrapper.wrap`](/docs/reference/sdk/wrapper/wrap) | when ENSv2 resolution no longer reaches the name. |
## Catch it [#catch-it]
`Errors.hasCode("NAME_UNREACHABLE")` narrows to this error. See [Handle errors](/docs/sdk/handle-errors).
# NAME_WRAPPED
> For the complete documentation index, see [llms.txt](https://ensforge.com/llms.txt).
What NAME_WRAPPED means, why NameStateError throws it, what to show users and how to fix it in ensforge. Also covers retry safety and the actions that throw it.
Source: https://ensforge.com/docs/reference/errors/NAME_WRAPPED
## What happened [#what-happened]
The name is already wrapped in the NameWrapper.
## What to show users [#what-to-show-users]
| Title | Message | Action |
| --- | --- | --- |
| Name already wrapped | This name is already wrapped. | |
## Retry safety [#retry-safety]
Retrying the same call fails the same way until the cause is fixed (`retryable: false`).
## Actions that throw it [#actions-that-throw-it]
| Action | When |
| --- | --- |
| [`wrapper.wrap`](/docs/reference/sdk/wrapper/wrap) | when the name cannot be wrapped. |
## Catch it [#catch-it]
`Errors.hasCode("NAME_WRAPPED")` narrows to this error. See [Handle errors](/docs/sdk/handle-errors).
# PARENT_NOT_MIGRATED
> For the complete documentation index, see [llms.txt](https://ensforge.com/llms.txt).
What PARENT_NOT_MIGRATED means, why NameStateError throws it, what to show users and how to fix it in ensforge. Also covers retry safety.
Source: https://ensforge.com/docs/reference/errors/PARENT_NOT_MIGRATED
## What happened [#what-happened]
The parent name has not been migrated to ENSv2.
## What to show users [#what-to-show-users]
| Title | Message | Action |
| --- | --- | --- |
| Upgrade required | The parent name has not been upgraded to the new ENS yet. | |
## Retry safety [#retry-safety]
Retrying the same call fails the same way until the cause is fixed (`retryable: false`).
## Actions that throw it [#actions-that-throw-it]
No action names this code in its documented errors.
## Catch it [#catch-it]
`Errors.hasCode("PARENT_NOT_MIGRATED")` narrows to this error. See [Handle errors](/docs/sdk/handle-errors).
# REGISTRY_NOT_EMANCIPATED
> For the complete documentation index, see [llms.txt](https://ensforge.com/llms.txt).
What REGISTRY_NOT_EMANCIPATED means, why NameStateError throws it, what to show users and how to fix it in ensforge. Also covers retry safety.
Source: https://ensforge.com/docs/reference/errors/REGISTRY_NOT_EMANCIPATED
## What happened [#what-happened]
The registry is not emancipated, so this transfer is unsafe.
## What to show users [#what-to-show-users]
| Title | Message | Action |
| --- | --- | --- |
| Transfer blocked | This name cannot be transferred safely yet. | |
## Retry safety [#retry-safety]
Retrying the same call fails the same way until the cause is fixed (`retryable: false`).
## Actions that throw it [#actions-that-throw-it]
| Action | When |
| --- | --- |
| [`name.transfer`](/docs/reference/sdk/name/transfer) | when the name's registry is not emancipated and `unsafe` is not set. |
## Catch it [#catch-it]
`Errors.hasCode("REGISTRY_NOT_EMANCIPATED")` narrows to this error. See [Handle errors](/docs/sdk/handle-errors).
# NameStateError
> For the complete documentation index, see [llms.txt](https://ensforge.com/llms.txt).
What NameStateError means, which codes it carries and how to catch it in ensforge. Lists its fields and every code. Includes how to catch it.
Source: https://ensforge.com/docs/reference/errors/name-state-error
The name is in the wrong state for this operation (registered, expired, locked, …).
## Codes [#codes]
| Code | Meaning | Retryable |
| --- | --- | --- |
| [`NAME_NOT_AVAILABLE`](/docs/reference/errors/NAME_NOT_AVAILABLE) | The name is already registered. | No |
| [`NAME_NOT_REGISTERED`](/docs/reference/errors/NAME_NOT_REGISTERED) | The name is not registered. | No |
| [`NAME_RESERVED`](/docs/reference/errors/NAME_RESERVED) | The name is reserved. | No |
| [`NAME_EXPIRED`](/docs/reference/errors/NAME_EXPIRED) | The name has expired. | No |
| [`NAME_NOT_RENEWABLE`](/docs/reference/errors/NAME_NOT_RENEWABLE) | The name cannot be renewed. | No |
| [`NAME_LOCKED`](/docs/reference/errors/NAME_LOCKED) | The name is locked. | No |
| [`NAME_NOT_WRAPPED`](/docs/reference/errors/NAME_NOT_WRAPPED) | The name is not wrapped in the NameWrapper. | No |
| [`NAME_WRAPPED`](/docs/reference/errors/NAME_WRAPPED) | The name is already wrapped in the NameWrapper. | No |
| [`NAME_UNREACHABLE`](/docs/reference/errors/NAME_UNREACHABLE) | ENSv2 resolution no longer reaches this ENSv1 name. | No |
| [`NAME_REQUIRES_MIGRATION`](/docs/reference/errors/NAME_REQUIRES_MIGRATION) | The name must be migrated to ENSv2 first. | No |
| [`PARENT_NOT_MIGRATED`](/docs/reference/errors/PARENT_NOT_MIGRATED) | The parent name has not been migrated to ENSv2. | No |
| [`REGISTRY_NOT_EMANCIPATED`](/docs/reference/errors/REGISTRY_NOT_EMANCIPATED) | The registry is not emancipated, so this transfer is unsafe. | No |
## Catch it [#catch-it]
`Effect.catchTag("NameStateError", …)` or `error instanceof Errors.NameStateError`. See [Handle errors](/docs/sdk/handle-errors).
# LOG_RANGE_TOO_LARGE
> For the complete documentation index, see [llms.txt](https://ensforge.com/llms.txt).
What LOG_RANGE_TOO_LARGE means, why NetworkError throws it, what to show users and how to fix it in ensforge. Also covers retry safety.
Source: https://ensforge.com/docs/reference/errors/LOG_RANGE_TOO_LARGE
## What happened [#what-happened]
The RPC provider's eth_getLogs limits make this block range too expensive.
## What to show users [#what-to-show-users]
| Title | Message | Action |
| --- | --- | --- |
| History unavailable | This RPC provider cannot return events for such a long period. | |
## How to fix [#how-to-fix]
Narrow the block range, use an RPC URL with wider log ranges, or use the indexer for history.
## Retry safety [#retry-safety]
Retrying the same call can succeed (`retryable: true`).
## Actions that throw it [#actions-that-throw-it]
| Action | When |
| --- | --- |
| [`event.get`](/docs/reference/sdk/event/get) | when the provider's log limits make the range too expensive. |
Any action can fail with `NetworkError`: it is part of `Errors.CommonError`.
## Catch it [#catch-it]
`Errors.hasCode("LOG_RANGE_TOO_LARGE")` narrows to this error. See [Handle errors](/docs/sdk/handle-errors).
# RATE_LIMITED
> For the complete documentation index, see [llms.txt](https://ensforge.com/llms.txt).
What RATE_LIMITED means, why NetworkError throws it, what to show users and how to fix it in ensforge. Also covers retry safety and the actions that throw it.
Source: https://ensforge.com/docs/reference/errors/RATE_LIMITED
## What happened [#what-happened]
The RPC provider is rate limiting requests.
## What to show users [#what-to-show-users]
| Title | Message | Action |
| --- | --- | --- |
| Too many requests | Please wait a moment. | Try again shortly. |
## How to fix [#how-to-fix]
Retry later, or use an RPC URL with a higher limit.
## Retry safety [#retry-safety]
Retrying the same call can succeed (`retryable: true`).
## Actions that throw it [#actions-that-throw-it]
| Action | When |
| --- | --- |
| [`approval.getDelegate`](/docs/reference/sdk/approval/get-delegate) | when the RPC request fails. |
| [`approval.getOperator`](/docs/reference/sdk/approval/get-operator) | when the RPC request fails. |
| [`approval.getToken`](/docs/reference/sdk/approval/get-token) | when the RPC request fails. |
| [`dns.getOffchainResolver`](/docs/reference/sdk/dns/get-offchain-resolver) | when the RPC request fails. |
| [`dns.getProof`](/docs/reference/sdk/dns/get-proof) | when the RPC request fails. |
| [`dns.getRecords`](/docs/reference/sdk/dns/get-records) | when the RPC request fails. |
| [`dns.getStatus`](/docs/reference/sdk/dns/get-status) | when the RPC request fails. |
| [`event.decode`](/docs/reference/sdk/event/decode) | when the RPC request fails. |
| [`event.get`](/docs/reference/sdk/event/get) | when the RPC request fails. |
| [`migration.get`](/docs/reference/sdk/migration/get) | when the RPC request fails. |
| [`name.get`](/docs/reference/sdk/name/get) | when the RPC request fails. |
| [`name.getLabel`](/docs/reference/sdk/name/get-label) | when the RPC request fails. |
| [`permission.check`](/docs/reference/sdk/permission/check) | when the RPC request fails. |
| [`permission.get`](/docs/reference/sdk/permission/get) | when the RPC request fails. |
| [`plan.get`](/docs/reference/sdk/plan/get) | when the RPC request fails. |
| [`plan.list`](/docs/reference/sdk/plan/list) | when the RPC request fails. |
| [`plan.reconcile`](/docs/reference/sdk/plan/reconcile) | when the RPC request fails. |
| [`primaryName.get`](/docs/reference/sdk/primary-name/get) | when the RPC request fails. |
| [`record.get`](/docs/reference/sdk/record/get) | when the RPC request fails. |
| [`record.getAddress`](/docs/reference/sdk/record/get-address) | when the RPC request fails. |
| [`record.getAvatar`](/docs/reference/sdk/record/get-avatar) | when the RPC request fails. |
| [`record.getContentHash`](/docs/reference/sdk/record/get-content-hash) | when the RPC request fails. |
| [`record.getText`](/docs/reference/sdk/record/get-text) | when the RPC request fails. |
| [`registration.getCommitmentStatus`](/docs/reference/sdk/registration/get-commitment-status) | when the RPC request fails. |
| [`registration.getParameters`](/docs/reference/sdk/registration/get-parameters) | when the RPC request fails. |
| [`registration.getPrice`](/docs/reference/sdk/registration/get-price) | when the RPC request fails. |
| [`registration.getRenewalPrice`](/docs/reference/sdk/registration/get-renewal-price) | when the RPC request fails. |
| [`registration.isAvailable`](/docs/reference/sdk/registration/is-available) | when the RPC request fails. |
| [`registry.get`](/docs/reference/sdk/registry/get) | when the RPC request fails. |
| [`resolver.get`](/docs/reference/sdk/resolver/get) | when the RPC request fails. |
| [`resolver.getLink`](/docs/reference/sdk/resolver/get-link) | when the RPC request fails. |
| [`role.get`](/docs/reference/sdk/role/get) | when the RPC request fails. |
| [`wrapper.getFuses`](/docs/reference/sdk/wrapper/get-fuses) | when the RPC request fails. |
Any action can fail with `NetworkError`: it is part of `Errors.CommonError`.
## Catch it [#catch-it]
`Errors.hasCode("RATE_LIMITED")` narrows to this error. See [Handle errors](/docs/sdk/handle-errors).
# RPC_REQUEST_FAILED
> For the complete documentation index, see [llms.txt](https://ensforge.com/llms.txt).
What RPC_REQUEST_FAILED means, why NetworkError throws it, what to show users and how to fix it in ensforge. Also covers retry safety.
Source: https://ensforge.com/docs/reference/errors/RPC_REQUEST_FAILED
## What happened [#what-happened]
The RPC request failed.
## What to show users [#what-to-show-users]
| Title | Message | Action |
| --- | --- | --- |
| Connection problem | Could not reach the network. | Check your connection and try again. |
## Retry safety [#retry-safety]
Retrying the same call can succeed (`retryable: true`).
## Actions that throw it [#actions-that-throw-it]
| Action | When |
| --- | --- |
| [`approval.getDelegate`](/docs/reference/sdk/approval/get-delegate) | when the RPC request fails. |
| [`approval.getOperator`](/docs/reference/sdk/approval/get-operator) | when the RPC request fails. |
| [`approval.getToken`](/docs/reference/sdk/approval/get-token) | when the RPC request fails. |
| [`dns.getOffchainResolver`](/docs/reference/sdk/dns/get-offchain-resolver) | when the RPC request fails. |
| [`dns.getProof`](/docs/reference/sdk/dns/get-proof) | when the RPC request fails. |
| [`dns.getRecords`](/docs/reference/sdk/dns/get-records) | when the RPC request fails. |
| [`dns.getStatus`](/docs/reference/sdk/dns/get-status) | when the RPC request fails. |
| [`event.decode`](/docs/reference/sdk/event/decode) | when the RPC request fails. |
| [`event.get`](/docs/reference/sdk/event/get) | when the RPC request fails. |
| [`migration.get`](/docs/reference/sdk/migration/get) | when the RPC request fails. |
| [`name.get`](/docs/reference/sdk/name/get) | when the RPC request fails. |
| [`name.getLabel`](/docs/reference/sdk/name/get-label) | when the RPC request fails. |
| [`permission.check`](/docs/reference/sdk/permission/check) | when the RPC request fails. |
| [`permission.get`](/docs/reference/sdk/permission/get) | when the RPC request fails. |
| [`plan.get`](/docs/reference/sdk/plan/get) | when the RPC request fails. |
| [`plan.list`](/docs/reference/sdk/plan/list) | when the RPC request fails. |
| [`plan.reconcile`](/docs/reference/sdk/plan/reconcile) | when the RPC request fails. |
| [`primaryName.get`](/docs/reference/sdk/primary-name/get) | when the RPC request fails. |
| [`record.get`](/docs/reference/sdk/record/get) | when the RPC request fails. |
| [`record.getAddress`](/docs/reference/sdk/record/get-address) | when the RPC request fails. |
| [`record.getAvatar`](/docs/reference/sdk/record/get-avatar) | when the RPC request fails. |
| [`record.getContentHash`](/docs/reference/sdk/record/get-content-hash) | when the RPC request fails. |
| [`record.getText`](/docs/reference/sdk/record/get-text) | when the RPC request fails. |
| [`registration.getCommitmentStatus`](/docs/reference/sdk/registration/get-commitment-status) | when the RPC request fails. |
| [`registration.getParameters`](/docs/reference/sdk/registration/get-parameters) | when the RPC request fails. |
| [`registration.getPrice`](/docs/reference/sdk/registration/get-price) | when the RPC request fails. |
| [`registration.getRenewalPrice`](/docs/reference/sdk/registration/get-renewal-price) | when the RPC request fails. |
| [`registration.isAvailable`](/docs/reference/sdk/registration/is-available) | when the RPC request fails. |
| [`registry.get`](/docs/reference/sdk/registry/get) | when the RPC request fails. |
| [`resolver.get`](/docs/reference/sdk/resolver/get) | when the RPC request fails. |
| [`resolver.getLink`](/docs/reference/sdk/resolver/get-link) | when the RPC request fails. |
| [`role.get`](/docs/reference/sdk/role/get) | when the RPC request fails. |
| [`wrapper.getFuses`](/docs/reference/sdk/wrapper/get-fuses) | when the RPC request fails. |
Any action can fail with `NetworkError`: it is part of `Errors.CommonError`.
## Catch it [#catch-it]
`Errors.hasCode("RPC_REQUEST_FAILED")` narrows to this error. See [Handle errors](/docs/sdk/handle-errors).
# RPC_TIMEOUT
> For the complete documentation index, see [llms.txt](https://ensforge.com/llms.txt).
What RPC_TIMEOUT means, why NetworkError throws it, what to show users and how to fix it in ensforge. Also covers retry safety and the actions that throw it.
Source: https://ensforge.com/docs/reference/errors/RPC_TIMEOUT
## What happened [#what-happened]
The RPC request timed out.
## What to show users [#what-to-show-users]
| Title | Message | Action |
| --- | --- | --- |
| Network slow | The network took too long to respond. | Try again. |
## Retry safety [#retry-safety]
Retrying the same call can succeed (`retryable: true`).
## Actions that throw it [#actions-that-throw-it]
| Action | When |
| --- | --- |
| [`approval.getDelegate`](/docs/reference/sdk/approval/get-delegate) | when the RPC request fails. |
| [`approval.getOperator`](/docs/reference/sdk/approval/get-operator) | when the RPC request fails. |
| [`approval.getToken`](/docs/reference/sdk/approval/get-token) | when the RPC request fails. |
| [`dns.getOffchainResolver`](/docs/reference/sdk/dns/get-offchain-resolver) | when the RPC request fails. |
| [`dns.getProof`](/docs/reference/sdk/dns/get-proof) | when the RPC request fails. |
| [`dns.getRecords`](/docs/reference/sdk/dns/get-records) | when the RPC request fails. |
| [`dns.getStatus`](/docs/reference/sdk/dns/get-status) | when the RPC request fails. |
| [`event.decode`](/docs/reference/sdk/event/decode) | when the RPC request fails. |
| [`event.get`](/docs/reference/sdk/event/get) | when the RPC request fails. |
| [`migration.get`](/docs/reference/sdk/migration/get) | when the RPC request fails. |
| [`name.get`](/docs/reference/sdk/name/get) | when the RPC request fails. |
| [`name.getLabel`](/docs/reference/sdk/name/get-label) | when the RPC request fails. |
| [`permission.check`](/docs/reference/sdk/permission/check) | when the RPC request fails. |
| [`permission.get`](/docs/reference/sdk/permission/get) | when the RPC request fails. |
| [`plan.get`](/docs/reference/sdk/plan/get) | when the RPC request fails. |
| [`plan.list`](/docs/reference/sdk/plan/list) | when the RPC request fails. |
| [`plan.reconcile`](/docs/reference/sdk/plan/reconcile) | when the RPC request fails. |
| [`primaryName.get`](/docs/reference/sdk/primary-name/get) | when the RPC request fails. |
| [`record.get`](/docs/reference/sdk/record/get) | when the RPC request fails. |
| [`record.getAddress`](/docs/reference/sdk/record/get-address) | when the RPC request fails. |
| [`record.getAvatar`](/docs/reference/sdk/record/get-avatar) | when the RPC request fails. |
| [`record.getContentHash`](/docs/reference/sdk/record/get-content-hash) | when the RPC request fails. |
| [`record.getText`](/docs/reference/sdk/record/get-text) | when the RPC request fails. |
| [`registration.getCommitmentStatus`](/docs/reference/sdk/registration/get-commitment-status) | when the RPC request fails. |
| [`registration.getParameters`](/docs/reference/sdk/registration/get-parameters) | when the RPC request fails. |
| [`registration.getPrice`](/docs/reference/sdk/registration/get-price) | when the RPC request fails. |
| [`registration.getRenewalPrice`](/docs/reference/sdk/registration/get-renewal-price) | when the RPC request fails. |
| [`registration.isAvailable`](/docs/reference/sdk/registration/is-available) | when the RPC request fails. |
| [`registry.get`](/docs/reference/sdk/registry/get) | when the RPC request fails. |
| [`resolver.get`](/docs/reference/sdk/resolver/get) | when the RPC request fails. |
| [`resolver.getLink`](/docs/reference/sdk/resolver/get-link) | when the RPC request fails. |
| [`role.get`](/docs/reference/sdk/role/get) | when the RPC request fails. |
| [`wrapper.getFuses`](/docs/reference/sdk/wrapper/get-fuses) | when the RPC request fails. |
Any action can fail with `NetworkError`: it is part of `Errors.CommonError`.
## Catch it [#catch-it]
`Errors.hasCode("RPC_TIMEOUT")` narrows to this error. See [Handle errors](/docs/sdk/handle-errors).
# NetworkError
> For the complete documentation index, see [llms.txt](https://ensforge.com/llms.txt).
What NetworkError means, which codes it carries and how to catch it in ensforge. The RPC provider could not be reached or rejected the request.
Source: https://ensforge.com/docs/reference/errors/network-error
The RPC provider could not be reached or rejected the request. Usually worth retrying.
Any action can fail with `NetworkError`: it is part of `Errors.CommonError`.
## Fields [#fields]
| Field | Type | Description |
| --- | --- | --- |
| `status` | `number` | HTTP status, when the transport is HTTP. |
## Codes [#codes]
| Code | Meaning | Retryable |
| --- | --- | --- |
| [`RPC_REQUEST_FAILED`](/docs/reference/errors/RPC_REQUEST_FAILED) | The RPC request failed. | Yes |
| [`RPC_TIMEOUT`](/docs/reference/errors/RPC_TIMEOUT) | The RPC request timed out. | Yes |
| [`RATE_LIMITED`](/docs/reference/errors/RATE_LIMITED) | The RPC provider is rate limiting requests. | Yes |
| [`LOG_RANGE_TOO_LARGE`](/docs/reference/errors/LOG_RANGE_TOO_LARGE) | The RPC provider's eth_getLogs limits make this block range too expensive. | Yes |
## Catch it [#catch-it]
`Effect.catchTag("NetworkError", …)` or `error instanceof Errors.NetworkError`. See [Handle errors](/docs/sdk/handle-errors).
# INDEXER_NOT_FOUND
> For the complete documentation index, see [llms.txt](https://ensforge.com/llms.txt).
What INDEXER_NOT_FOUND means, why NotFoundError throws it, what to show users and how to fix it in ensforge. Also covers retry safety.
Source: https://ensforge.com/docs/reference/errors/INDEXER_NOT_FOUND
## What happened [#what-happened]
The indexer has no record of this resource.
## What to show users [#what-to-show-users]
| Title | Message | Action |
| --- | --- | --- |
| Not found | Nothing was found. | |
## Retry safety [#retry-safety]
Retrying the same call fails the same way until the cause is fixed (`retryable: false`).
## Actions that throw it [#actions-that-throw-it]
| Action | When |
| --- | --- |
| [`indexer.getHistory`](/docs/reference/sdk/indexer/get-history) | when the indexer has no such name. |
| [`indexer.getName`](/docs/reference/sdk/indexer/get-name) | with `strict: true` when the indexer has no such name. |
| [`indexer.getNamespace`](/docs/reference/sdk/indexer/get-namespace) | with `strict: true` when the indexer does not know the namespace. |
| [`indexer.getRecords`](/docs/reference/sdk/indexer/get-records) | with `strict: true` when the indexer has no such name. |
| [`indexer.getRegistry`](/docs/reference/sdk/indexer/get-registry) | with `strict: true` when the indexer does not know the contract. |
| [`indexer.getResolver`](/docs/reference/sdk/indexer/get-resolver) | with `strict: true` when the indexer does not know the contract. |
| [`indexer.getSubnames`](/docs/reference/sdk/indexer/get-subnames) | when the indexer has no such name. |
## Catch it [#catch-it]
`Errors.hasCode("INDEXER_NOT_FOUND")` narrows to this error. See [Handle errors](/docs/sdk/handle-errors).
# PLAN_NOT_FOUND
> For the complete documentation index, see [llms.txt](https://ensforge.com/llms.txt).
What PLAN_NOT_FOUND means, why NotFoundError throws it, what to show users and how to fix it in ensforge. Also covers retry safety.
Source: https://ensforge.com/docs/reference/errors/PLAN_NOT_FOUND
## What happened [#what-happened]
No saved plan was found with this id.
## What to show users [#what-to-show-users]
| Title | Message | Action |
| --- | --- | --- |
| Nothing to resume | There is no saved progress to continue. | |
## Retry safety [#retry-safety]
Retrying the same call fails the same way until the cause is fixed (`retryable: false`).
## Actions that throw it [#actions-that-throw-it]
| Action | When |
| --- | --- |
| [`plan.reconcile`](/docs/reference/sdk/plan/reconcile) | for an unknown plan. |
| [`plan.resume`](/docs/reference/sdk/plan/resume) | for an unknown plan. |
## Catch it [#catch-it]
`Errors.hasCode("PLAN_NOT_FOUND")` narrows to this error. See [Handle errors](/docs/sdk/handle-errors).
# PRIMARY_NAME_MISMATCH
> For the complete documentation index, see [llms.txt](https://ensforge.com/llms.txt).
What PRIMARY_NAME_MISMATCH means, why NotFoundError throws it, what to show users and how to fix it in ensforge. Also covers retry safety.
Source: https://ensforge.com/docs/reference/errors/PRIMARY_NAME_MISMATCH
## What happened [#what-happened]
The primary name does not resolve back to this address.
## What to show users [#what-to-show-users]
| Title | Message | Action |
| --- | --- | --- |
| Primary name not verified | The primary name of this address does not point back to it. | |
## How to fix [#how-to-fix]
Set the name's address record to this address, or set another primary name.
## Retry safety [#retry-safety]
Retrying the same call fails the same way until the cause is fixed (`retryable: false`).
## Actions that throw it [#actions-that-throw-it]
| Action | When |
| --- | --- |
| [`primaryName.get`](/docs/reference/sdk/primary-name/get) | with `strict` when there is no valid primary name. |
| [`primaryName.set`](/docs/reference/sdk/primary-name/set) | when the name does not resolve to the address. |
| [`primaryName.signClaim`](/docs/reference/sdk/primary-name/sign-claim) | when the name does not resolve to the address on a chain. |
## Catch it [#catch-it]
`Errors.hasCode("PRIMARY_NAME_MISMATCH")` narrows to this error. See [Handle errors](/docs/sdk/handle-errors).
# PRIMARY_NAME_NOT_SET
> For the complete documentation index, see [llms.txt](https://ensforge.com/llms.txt).
What PRIMARY_NAME_NOT_SET means, why NotFoundError throws it, what to show users and how to fix it in ensforge. Also covers retry safety.
Source: https://ensforge.com/docs/reference/errors/PRIMARY_NAME_NOT_SET
## What happened [#what-happened]
The address has no primary name.
## What to show users [#what-to-show-users]
| Title | Message | Action |
| --- | --- | --- |
| No primary name | This address has no primary name. | |
## Retry safety [#retry-safety]
Retrying the same call fails the same way until the cause is fixed (`retryable: false`).
## Actions that throw it [#actions-that-throw-it]
| Action | When |
| --- | --- |
| [`primaryName.get`](/docs/reference/sdk/primary-name/get) | with `strict` when there is no valid primary name. |
## Catch it [#catch-it]
`Errors.hasCode("PRIMARY_NAME_NOT_SET")` narrows to this error. See [Handle errors](/docs/sdk/handle-errors).
# RECORD_NOT_FOUND
> For the complete documentation index, see [llms.txt](https://ensforge.com/llms.txt).
What RECORD_NOT_FOUND means, why NotFoundError throws it, what to show users and how to fix it in ensforge. Also covers retry safety.
Source: https://ensforge.com/docs/reference/errors/RECORD_NOT_FOUND
## What happened [#what-happened]
The record is not set.
## What to show users [#what-to-show-users]
| Title | Message | Action |
| --- | --- | --- |
| Not set | This record is not set. | |
## Retry safety [#retry-safety]
Retrying the same call fails the same way until the cause is fixed (`retryable: false`).
## Actions that throw it [#actions-that-throw-it]
| Action | When |
| --- | --- |
| [`record.getAddress`](/docs/reference/sdk/record/get-address) | with `strict`. |
| [`record.getAvatar`](/docs/reference/sdk/record/get-avatar) | with `strict`. |
| [`record.getContentHash`](/docs/reference/sdk/record/get-content-hash) | with `strict`. |
| [`record.getText`](/docs/reference/sdk/record/get-text) | with `strict`. |
| [`resolver.getLink`](/docs/reference/sdk/resolver/get-link) | without a resolver, or with `strict` and no records. |
## Catch it [#catch-it]
`Errors.hasCode("RECORD_NOT_FOUND")` narrows to this error. See [Handle errors](/docs/sdk/handle-errors).
# REGISTRY_NOT_FOUND
> For the complete documentation index, see [llms.txt](https://ensforge.com/llms.txt).
What REGISTRY_NOT_FOUND means, why NotFoundError throws it, what to show users and how to fix it in ensforge. Also covers retry safety.
Source: https://ensforge.com/docs/reference/errors/REGISTRY_NOT_FOUND
## What happened [#what-happened]
No registry was found for this name.
## What to show users [#what-to-show-users]
| Title | Message | Action |
| --- | --- | --- |
| Not found | This name could not be found. | |
## Retry safety [#retry-safety]
Retrying the same call fails the same way until the cause is fixed (`retryable: false`).
## Actions that throw it [#actions-that-throw-it]
| Action | When |
| --- | --- |
| [`registry.get`](/docs/reference/sdk/registry/get) | with `strict` when the name has no subregistry. |
| [`registry.setUri`](/docs/reference/sdk/registry/set-uri) | when the name has no subregistry. |
| [`registry.upgrade`](/docs/reference/sdk/registry/upgrade) | when the name has no subregistry. |
## Catch it [#catch-it]
`Errors.hasCode("REGISTRY_NOT_FOUND")` narrows to this error. See [Handle errors](/docs/sdk/handle-errors).
# RESOLVER_NOT_FOUND
> For the complete documentation index, see [llms.txt](https://ensforge.com/llms.txt).
What RESOLVER_NOT_FOUND means, why NotFoundError throws it, what to show users and how to fix it in ensforge. Also covers retry safety.
Source: https://ensforge.com/docs/reference/errors/RESOLVER_NOT_FOUND
## What happened [#what-happened]
The name has no resolver.
## What to show users [#what-to-show-users]
| Title | Message | Action |
| --- | --- | --- |
| No resolver | This name is not set up to hold records yet. | Set a resolver first. |
## How to fix [#how-to-fix]
Set one with resolver.set.
## Retry safety [#retry-safety]
Retrying the same call fails the same way until the cause is fixed (`retryable: false`).
## Actions that throw it [#actions-that-throw-it]
| Action | When |
| --- | --- |
| [`approval.getDelegate`](/docs/reference/sdk/approval/get-delegate) | when the name has no resolver. |
| [`approval.setDelegate`](/docs/reference/sdk/approval/set-delegate) | when the name has no resolver. |
| [`dns.setRecords`](/docs/reference/sdk/dns/set-records) | when the name has no resolver. |
| [`permission.setRecordAccess`](/docs/reference/sdk/permission/set-record-access) | when the name has no resolver. |
| [`record.get`](/docs/reference/sdk/record/get) | with `strict` when the name has no resolver. |
| [`record.getAddress`](/docs/reference/sdk/record/get-address) | with `strict`. |
| [`record.getAvatar`](/docs/reference/sdk/record/get-avatar) | with `strict`. |
| [`record.getContentHash`](/docs/reference/sdk/record/get-content-hash) | with `strict`. |
| [`record.getText`](/docs/reference/sdk/record/get-text) | with `strict`. |
| [`record.set`](/docs/reference/sdk/record/set) | when the name has no resolver of its own. |
| [`resolver.get`](/docs/reference/sdk/resolver/get) | with `strict` when nothing resolves the name. |
| [`resolver.getLink`](/docs/reference/sdk/resolver/get-link) | without a resolver, or with `strict` and no records. |
| [`resolver.link`](/docs/reference/sdk/resolver/link) | when the name has no resolver of its own. |
| [`resolver.resolve`](/docs/reference/sdk/resolver/resolve) | when nothing resolves the name. |
| [`resolver.upgrade`](/docs/reference/sdk/resolver/upgrade) | when the name has no resolver of its own. |
| [`role.get`](/docs/reference/sdk/role/get) | when the name has no resolver. |
## Catch it [#catch-it]
`Errors.hasCode("RESOLVER_NOT_FOUND")` narrows to this error. See [Handle errors](/docs/sdk/handle-errors).
# NotFoundError
> For the complete documentation index, see [llms.txt](https://ensforge.com/llms.txt).
What NotFoundError means, which codes it carries and how to catch it in ensforge. Something the call requires does not exist.
Source: https://ensforge.com/docs/reference/errors/not-found-error
Something the call requires does not exist. Reads only throw this with `strict: true`;
otherwise they return `null`.
## Fields [#fields]
| Field | Type | Description |
| --- | --- | --- |
| `resource` | `string` | What was missing, e.g. a record key. |
## Codes [#codes]
| Code | Meaning | Retryable |
| --- | --- | --- |
| [`RESOLVER_NOT_FOUND`](/docs/reference/errors/RESOLVER_NOT_FOUND) | The name has no resolver. | No |
| [`RECORD_NOT_FOUND`](/docs/reference/errors/RECORD_NOT_FOUND) | The record is not set. | No |
| [`PRIMARY_NAME_NOT_SET`](/docs/reference/errors/PRIMARY_NAME_NOT_SET) | The address has no primary name. | No |
| [`PRIMARY_NAME_MISMATCH`](/docs/reference/errors/PRIMARY_NAME_MISMATCH) | The primary name does not resolve back to this address. | No |
| [`REGISTRY_NOT_FOUND`](/docs/reference/errors/REGISTRY_NOT_FOUND) | No registry was found for this name. | No |
| [`PLAN_NOT_FOUND`](/docs/reference/errors/PLAN_NOT_FOUND) | No saved plan was found with this id. | No |
| [`INDEXER_NOT_FOUND`](/docs/reference/errors/INDEXER_NOT_FOUND) | The indexer has no record of this resource. | No |
## Catch it [#catch-it]
`Effect.catchTag("NotFoundError", …)` or `error instanceof Errors.NotFoundError`. See [Handle errors](/docs/sdk/handle-errors).
# PLAN_ACCOUNT_MISMATCH
> For the complete documentation index, see [llms.txt](https://ensforge.com/llms.txt).
What PLAN_ACCOUNT_MISMATCH means, why PlanError throws it, what to show users and how to fix it in ensforge. Also covers retry safety.
Source: https://ensforge.com/docs/reference/errors/PLAN_ACCOUNT_MISMATCH
## What happened [#what-happened]
The plan was prepared for another account.
## What to show users [#what-to-show-users]
| Title | Message | Action |
| --- | --- | --- |
| Wrong account | This was prepared for a different account. | |
## Retry safety [#retry-safety]
Retrying the same call fails the same way until the cause is fixed (`retryable: false`).
## Actions that throw it [#actions-that-throw-it]
| Action | When |
| --- | --- |
| [`plan.resume`](/docs/reference/sdk/plan/resume) | when the plan cannot continue here. |
| [`plan.send`](/docs/reference/sdk/plan/send) | for a plan prepared elsewhere. |
## Catch it [#catch-it]
`Errors.hasCode("PLAN_ACCOUNT_MISMATCH")` narrows to this error. See [Handle errors](/docs/sdk/handle-errors).
# PLAN_CHAIN_MISMATCH
> For the complete documentation index, see [llms.txt](https://ensforge.com/llms.txt).
What PLAN_CHAIN_MISMATCH means, why PlanError throws it, what to show users and how to fix it in ensforge. Also covers retry safety.
Source: https://ensforge.com/docs/reference/errors/PLAN_CHAIN_MISMATCH
## What happened [#what-happened]
The plan was prepared for another chain.
## What to show users [#what-to-show-users]
| Title | Message | Action |
| --- | --- | --- |
| Wrong network | This was prepared for a different network. | |
## Retry safety [#retry-safety]
Retrying the same call fails the same way until the cause is fixed (`retryable: false`).
## Actions that throw it [#actions-that-throw-it]
| Action | When |
| --- | --- |
| [`plan.resume`](/docs/reference/sdk/plan/resume) | when the plan cannot continue here. |
| [`plan.send`](/docs/reference/sdk/plan/send) | for a plan prepared elsewhere. |
## Catch it [#catch-it]
`Errors.hasCode("PLAN_CHAIN_MISMATCH")` narrows to this error. See [Handle errors](/docs/sdk/handle-errors).
# PLAN_INVALID
> For the complete documentation index, see [llms.txt](https://ensforge.com/llms.txt).
What PLAN_INVALID means, why PlanError throws it, what to show users and how to fix it in ensforge. Also covers retry safety and the actions that throw it.
Source: https://ensforge.com/docs/reference/errors/PLAN_INVALID
## What happened [#what-happened]
The text is not a serialized ensforge plan.
## What to show users [#what-to-show-users]
| Title | Message | Action |
| --- | --- | --- |
| Cannot resume | The saved progress is damaged. | Start again. |
## Retry safety [#retry-safety]
Retrying the same call fails the same way until the cause is fixed (`retryable: false`).
## Actions that throw it [#actions-that-throw-it]
| Action | When |
| --- | --- |
| [`plan.get`](/docs/reference/sdk/plan/get) | when a saved plan cannot be read. |
| [`plan.list`](/docs/reference/sdk/plan/list) | when a saved plan cannot be read. |
| [`plan.reconcile`](/docs/reference/sdk/plan/reconcile) | when a saved plan cannot be read. |
| [`plan.resume`](/docs/reference/sdk/plan/resume) | when a saved plan cannot be read. |
## Catch it [#catch-it]
`Errors.hasCode("PLAN_INVALID")` narrows to this error. See [Handle errors](/docs/sdk/handle-errors).
# PLAN_ROUTE_REQUIRED
> For the complete documentation index, see [llms.txt](https://ensforge.com/llms.txt).
What PLAN_ROUTE_REQUIRED means, why PlanError throws it, what to show users and how to fix it in ensforge. Also covers retry safety.
Source: https://ensforge.com/docs/reference/errors/PLAN_ROUTE_REQUIRED
## What happened [#what-happened]
Part of this plan was sent through a route (`via`), which resuming needs again.
## What to show users [#what-to-show-users]
| Title | Message | Action |
| --- | --- | --- |
| Cannot continue | This transaction must be continued the same way it was started. | |
## How to fix [#how-to-fix]
Pass the same `via` to plan.resume, e.g. `via: hca()`.
## Retry safety [#retry-safety]
Retrying the same call fails the same way until the cause is fixed (`retryable: false`).
## Actions that throw it [#actions-that-throw-it]
| Action | When |
| --- | --- |
| [`plan.resume`](/docs/reference/sdk/plan/resume) | when the plan cannot continue here. |
## Catch it [#catch-it]
`Errors.hasCode("PLAN_ROUTE_REQUIRED")` narrows to this error. See [Handle errors](/docs/sdk/handle-errors).
# PLAN_STALE
> For the complete documentation index, see [llms.txt](https://ensforge.com/llms.txt).
What PLAN_STALE means, why PlanError throws it, what to show users and how to fix it in ensforge. Also covers retry safety and the actions that throw it.
Source: https://ensforge.com/docs/reference/errors/PLAN_STALE
## What happened [#what-happened]
The plan no longer matches on-chain state.
## What to show users [#what-to-show-users]
| Title | Message | Action |
| --- | --- | --- |
| Out of date | Something changed since this was prepared. | Start again. |
## How to fix [#how-to-fix]
Prepare the plan again.
## Retry safety [#retry-safety]
Retrying the same call fails the same way until the cause is fixed (`retryable: false`).
## Actions that throw it [#actions-that-throw-it]
| Action | When |
| --- | --- |
| [`plan.send`](/docs/reference/sdk/plan/send) | when a token it transfers was reissued since it was prepared. |
## Catch it [#catch-it]
`Errors.hasCode("PLAN_STALE")` narrows to this error. See [Handle errors](/docs/sdk/handle-errors).
# PlanError
> For the complete documentation index, see [llms.txt](https://ensforge.com/llms.txt).
What PlanError means, which codes it carries and how to catch it in ensforge. A prepared or saved plan can no longer be sent as-is.
Source: https://ensforge.com/docs/reference/errors/plan-error
A prepared or saved plan can no longer be sent as-is.
## Codes [#codes]
| Code | Meaning | Retryable |
| --- | --- | --- |
| [`PLAN_STALE`](/docs/reference/errors/PLAN_STALE) | The plan no longer matches on-chain state. | No |
| [`PLAN_CHAIN_MISMATCH`](/docs/reference/errors/PLAN_CHAIN_MISMATCH) | The plan was prepared for another chain. | No |
| [`PLAN_ACCOUNT_MISMATCH`](/docs/reference/errors/PLAN_ACCOUNT_MISMATCH) | The plan was prepared for another account. | No |
| [`PLAN_INVALID`](/docs/reference/errors/PLAN_INVALID) | The text is not a serialized ensforge plan. | No |
| [`PLAN_ROUTE_REQUIRED`](/docs/reference/errors/PLAN_ROUTE_REQUIRED) | Part of this plan was sent through a route (`via`), which resuming needs again. | No |
## Catch it [#catch-it]
`Effect.catchTag("PlanError", …)` or `error instanceof Errors.PlanError`. See [Handle errors](/docs/sdk/handle-errors).
# NONCE_CONFLICT
> For the complete documentation index, see [llms.txt](https://ensforge.com/llms.txt).
What NONCE_CONFLICT means, why TransactionError throws it, what to show users and how to fix it in ensforge. Also covers retry safety.
Source: https://ensforge.com/docs/reference/errors/NONCE_CONFLICT
## What happened [#what-happened]
The transaction nonce conflicts with another transaction.
## What to show users [#what-to-show-users]
| Title | Message | Action |
| --- | --- | --- |
| Transaction conflict | Another transaction from your wallet is pending. | Wait for it to confirm, then try again. |
## How to fix [#how-to-fix]
Wait for pending transactions to confirm, then retry.
## Retry safety [#retry-safety]
Retrying the same call can succeed (`retryable: true`).
## Actions that throw it [#actions-that-throw-it]
| Action | When |
| --- | --- |
| [`approval.setDelegate`](/docs/reference/sdk/approval/set-delegate) | when confirmation fails or the wallet's nonce is already used. |
| [`approval.setOperator`](/docs/reference/sdk/approval/set-operator) | when confirmation fails or the wallet's nonce is already used. |
| [`approval.setToken`](/docs/reference/sdk/approval/set-token) | when confirmation fails or the wallet's nonce is already used. |
| [`dns.claim`](/docs/reference/sdk/dns/claim) | when confirmation fails or the wallet's nonce is already used. |
| [`dns.setRecords`](/docs/reference/sdk/dns/set-records) | when confirmation fails or the wallet's nonce is already used. |
| [`migration.migrate`](/docs/reference/sdk/migration/migrate) | when confirmation fails or the wallet's nonce is already used. |
| [`name.reclaim`](/docs/reference/sdk/name/reclaim) | when confirmation fails or the wallet's nonce is already used. |
| [`name.setManager`](/docs/reference/sdk/name/set-manager) | when confirmation fails or the wallet's nonce is already used. |
| [`name.setTtl`](/docs/reference/sdk/name/set-ttl) | when confirmation fails or the wallet's nonce is already used. |
| [`name.transfer`](/docs/reference/sdk/name/transfer) | when confirmation fails or the wallet's nonce is already used. |
| [`permission.setRecordAccess`](/docs/reference/sdk/permission/set-record-access) | when confirmation fails or the wallet's nonce is already used. |
| [`plan.resume`](/docs/reference/sdk/plan/resume) | when confirmation fails or the wallet's nonce is already used. |
| [`plan.send`](/docs/reference/sdk/plan/send) | when confirmation fails or the wallet's nonce is already used. |
| [`primaryName.set`](/docs/reference/sdk/primary-name/set) | when confirmation fails or the wallet's nonce is already used. |
| [`record.set`](/docs/reference/sdk/record/set) | when confirmation fails or the wallet's nonce is already used. |
| [`registration.commit`](/docs/reference/sdk/registration/commit) | when confirmation fails or the wallet's nonce is already used. |
| [`registration.register`](/docs/reference/sdk/registration/register) | when confirmation fails or the wallet's nonce is already used. |
| [`registration.renew`](/docs/reference/sdk/registration/renew) | when confirmation fails or the wallet's nonce is already used. |
| [`registry.attach`](/docs/reference/sdk/registry/attach) | when confirmation fails or the wallet's nonce is already used. |
| [`registry.deploy`](/docs/reference/sdk/registry/deploy) | when confirmation fails or the wallet's nonce is already used. |
| [`registry.setUri`](/docs/reference/sdk/registry/set-uri) | when confirmation fails or the wallet's nonce is already used. |
| [`registry.upgrade`](/docs/reference/sdk/registry/upgrade) | when confirmation fails or the wallet's nonce is already used. |
| [`resolver.create`](/docs/reference/sdk/resolver/create) | when confirmation fails or the wallet's nonce is already used. |
| [`resolver.link`](/docs/reference/sdk/resolver/link) | when confirmation fails or the wallet's nonce is already used. |
| [`resolver.set`](/docs/reference/sdk/resolver/set) | when confirmation fails or the wallet's nonce is already used. |
| [`resolver.upgrade`](/docs/reference/sdk/resolver/upgrade) | when confirmation fails or the wallet's nonce is already used. |
| [`role.grant`](/docs/reference/sdk/role/grant) | when confirmation fails or the wallet's nonce is already used. |
| [`role.revoke`](/docs/reference/sdk/role/revoke) | when confirmation fails or the wallet's nonce is already used. |
| [`subname.create`](/docs/reference/sdk/subname/create) | when confirmation fails or the wallet's nonce is already used. |
| [`subname.remove`](/docs/reference/sdk/subname/remove) | when confirmation fails or the wallet's nonce is already used. |
| [`subname.update`](/docs/reference/sdk/subname/update) | when confirmation fails or the wallet's nonce is already used. |
| [`wrapper.setChildFuses`](/docs/reference/sdk/wrapper/set-child-fuses) | when confirmation fails or the wallet's nonce is already used. |
| [`wrapper.setFuses`](/docs/reference/sdk/wrapper/set-fuses) | when confirmation fails or the wallet's nonce is already used. |
| [`wrapper.unwrap`](/docs/reference/sdk/wrapper/unwrap) | when confirmation fails or the wallet's nonce is already used. |
| [`wrapper.wrap`](/docs/reference/sdk/wrapper/wrap) | when confirmation fails or the wallet's nonce is already used. |
Any write can fail with `TransactionError`: it is part of `Errors.WriteError`.
## Catch it [#catch-it]
`Errors.hasCode("NONCE_CONFLICT")` narrows to this error. See [Handle errors](/docs/sdk/handle-errors).
# RECEIPT_TIMEOUT
> For the complete documentation index, see [llms.txt](https://ensforge.com/llms.txt).
What RECEIPT_TIMEOUT means, why TransactionError throws it, what to show users and how to fix it in ensforge. Also covers retry safety.
Source: https://ensforge.com/docs/reference/errors/RECEIPT_TIMEOUT
## What happened [#what-happened]
Timed out waiting for the transaction receipt.
## What to show users [#what-to-show-users]
| Title | Message | Action |
| --- | --- | --- |
| Still pending | The transaction is taking longer than expected to confirm. | Check your wallet for its status before retrying. |
## How to fix [#how-to-fix]
The transaction may still confirm; check it by hash before retrying.
## Retry safety [#retry-safety]
Retrying the same call fails the same way until the cause is fixed (`retryable: false`).
## Actions that throw it [#actions-that-throw-it]
| Action | When |
| --- | --- |
| [`approval.setDelegate`](/docs/reference/sdk/approval/set-delegate) | when confirmation fails or the wallet's nonce is already used. |
| [`approval.setOperator`](/docs/reference/sdk/approval/set-operator) | when confirmation fails or the wallet's nonce is already used. |
| [`approval.setToken`](/docs/reference/sdk/approval/set-token) | when confirmation fails or the wallet's nonce is already used. |
| [`dns.claim`](/docs/reference/sdk/dns/claim) | when confirmation fails or the wallet's nonce is already used. |
| [`dns.setRecords`](/docs/reference/sdk/dns/set-records) | when confirmation fails or the wallet's nonce is already used. |
| [`migration.migrate`](/docs/reference/sdk/migration/migrate) | when confirmation fails or the wallet's nonce is already used. |
| [`name.reclaim`](/docs/reference/sdk/name/reclaim) | when confirmation fails or the wallet's nonce is already used. |
| [`name.setManager`](/docs/reference/sdk/name/set-manager) | when confirmation fails or the wallet's nonce is already used. |
| [`name.setTtl`](/docs/reference/sdk/name/set-ttl) | when confirmation fails or the wallet's nonce is already used. |
| [`name.transfer`](/docs/reference/sdk/name/transfer) | when confirmation fails or the wallet's nonce is already used. |
| [`permission.setRecordAccess`](/docs/reference/sdk/permission/set-record-access) | when confirmation fails or the wallet's nonce is already used. |
| [`plan.resume`](/docs/reference/sdk/plan/resume) | when confirmation fails or the wallet's nonce is already used. |
| [`plan.send`](/docs/reference/sdk/plan/send) | when confirmation fails or the wallet's nonce is already used. |
| [`primaryName.set`](/docs/reference/sdk/primary-name/set) | when confirmation fails or the wallet's nonce is already used. |
| [`record.set`](/docs/reference/sdk/record/set) | when confirmation fails or the wallet's nonce is already used. |
| [`registration.commit`](/docs/reference/sdk/registration/commit) | when confirmation fails or the wallet's nonce is already used. |
| [`registration.register`](/docs/reference/sdk/registration/register) | when confirmation fails or the wallet's nonce is already used. |
| [`registration.renew`](/docs/reference/sdk/registration/renew) | when confirmation fails or the wallet's nonce is already used. |
| [`registry.attach`](/docs/reference/sdk/registry/attach) | when confirmation fails or the wallet's nonce is already used. |
| [`registry.deploy`](/docs/reference/sdk/registry/deploy) | when confirmation fails or the wallet's nonce is already used. |
| [`registry.setUri`](/docs/reference/sdk/registry/set-uri) | when confirmation fails or the wallet's nonce is already used. |
| [`registry.upgrade`](/docs/reference/sdk/registry/upgrade) | when confirmation fails or the wallet's nonce is already used. |
| [`resolver.create`](/docs/reference/sdk/resolver/create) | when confirmation fails or the wallet's nonce is already used. |
| [`resolver.link`](/docs/reference/sdk/resolver/link) | when confirmation fails or the wallet's nonce is already used. |
| [`resolver.set`](/docs/reference/sdk/resolver/set) | when confirmation fails or the wallet's nonce is already used. |
| [`resolver.upgrade`](/docs/reference/sdk/resolver/upgrade) | when confirmation fails or the wallet's nonce is already used. |
| [`role.grant`](/docs/reference/sdk/role/grant) | when confirmation fails or the wallet's nonce is already used. |
| [`role.revoke`](/docs/reference/sdk/role/revoke) | when confirmation fails or the wallet's nonce is already used. |
| [`subname.create`](/docs/reference/sdk/subname/create) | when confirmation fails or the wallet's nonce is already used. |
| [`subname.remove`](/docs/reference/sdk/subname/remove) | when confirmation fails or the wallet's nonce is already used. |
| [`subname.update`](/docs/reference/sdk/subname/update) | when confirmation fails or the wallet's nonce is already used. |
| [`wrapper.setChildFuses`](/docs/reference/sdk/wrapper/set-child-fuses) | when confirmation fails or the wallet's nonce is already used. |
| [`wrapper.setFuses`](/docs/reference/sdk/wrapper/set-fuses) | when confirmation fails or the wallet's nonce is already used. |
| [`wrapper.unwrap`](/docs/reference/sdk/wrapper/unwrap) | when confirmation fails or the wallet's nonce is already used. |
| [`wrapper.wrap`](/docs/reference/sdk/wrapper/wrap) | when confirmation fails or the wallet's nonce is already used. |
| [`hca.addDeposit`](/docs/reference/hca/hca/add-deposit) | when confirmation fails. |
| [`hca.deploy`](/docs/reference/hca/hca/deploy) | when confirmation fails. |
| [`hca.execute`](/docs/reference/hca/hca/execute) | when confirmation fails. |
| [`hca.revokeSessions`](/docs/reference/hca/hca/revoke-sessions) | when confirmation fails. |
| [`hca.upgrade`](/docs/reference/hca/hca/upgrade) | when confirmation fails. |
| [`hca.withdrawDeposit`](/docs/reference/hca/hca/withdraw-deposit) | when confirmation fails. |
| [`hcaAdmin.grantUpgradeSetRoles`](/docs/reference/hca/hca-admin/grant-upgrade-set-roles) | when confirmation fails. |
| [`hcaAdmin.renounceGovernance`](/docs/reference/hca/hca-admin/renounce-governance) | when confirmation fails. |
| [`hcaAdmin.revokeUpgradeSetRoles`](/docs/reference/hca/hca-admin/revoke-upgrade-set-roles) | when confirmation fails. |
| [`hcaAdmin.setDeploymentApproval`](/docs/reference/hca/hca-admin/set-deployment-approval) | when confirmation fails. |
| [`hcaAdmin.setUpgradeApproval`](/docs/reference/hca/hca-admin/set-upgrade-approval) | when confirmation fails. |
| [`hcaAdmin.transferGovernance`](/docs/reference/hca/hca-admin/transfer-governance) | when confirmation fails. |
Any write can fail with `TransactionError`: it is part of `Errors.WriteError`.
## Catch it [#catch-it]
`Errors.hasCode("RECEIPT_TIMEOUT")` narrows to this error. See [Handle errors](/docs/sdk/handle-errors).
# TRANSACTION_REVERTED
> For the complete documentation index, see [llms.txt](https://ensforge.com/llms.txt).
What TRANSACTION_REVERTED means, why TransactionError throws it, what to show users and how to fix it in ensforge. Also covers retry safety.
Source: https://ensforge.com/docs/reference/errors/TRANSACTION_REVERTED
## What happened [#what-happened]
The transaction reverted on-chain.
## What to show users [#what-to-show-users]
| Title | Message | Action |
| --- | --- | --- |
| Transaction failed | The transaction was rejected by the network. | |
## Retry safety [#retry-safety]
Retrying the same call fails the same way until the cause is fixed (`retryable: false`).
## Actions that throw it [#actions-that-throw-it]
| Action | When |
| --- | --- |
| [`approval.setDelegate`](/docs/reference/sdk/approval/set-delegate) | when confirmation fails or the wallet's nonce is already used. |
| [`approval.setOperator`](/docs/reference/sdk/approval/set-operator) | when confirmation fails or the wallet's nonce is already used. |
| [`approval.setToken`](/docs/reference/sdk/approval/set-token) | when confirmation fails or the wallet's nonce is already used. |
| [`dns.claim`](/docs/reference/sdk/dns/claim) | when confirmation fails or the wallet's nonce is already used. |
| [`dns.setRecords`](/docs/reference/sdk/dns/set-records) | when confirmation fails or the wallet's nonce is already used. |
| [`migration.migrate`](/docs/reference/sdk/migration/migrate) | when confirmation fails or the wallet's nonce is already used. |
| [`name.reclaim`](/docs/reference/sdk/name/reclaim) | when confirmation fails or the wallet's nonce is already used. |
| [`name.setManager`](/docs/reference/sdk/name/set-manager) | when confirmation fails or the wallet's nonce is already used. |
| [`name.setTtl`](/docs/reference/sdk/name/set-ttl) | when confirmation fails or the wallet's nonce is already used. |
| [`name.transfer`](/docs/reference/sdk/name/transfer) | when confirmation fails or the wallet's nonce is already used. |
| [`permission.setRecordAccess`](/docs/reference/sdk/permission/set-record-access) | when confirmation fails or the wallet's nonce is already used. |
| [`plan.resume`](/docs/reference/sdk/plan/resume) | when confirmation fails or the wallet's nonce is already used. |
| [`plan.send`](/docs/reference/sdk/plan/send) | when confirmation fails or the wallet's nonce is already used. |
| [`primaryName.set`](/docs/reference/sdk/primary-name/set) | when confirmation fails or the wallet's nonce is already used. |
| [`record.set`](/docs/reference/sdk/record/set) | when confirmation fails or the wallet's nonce is already used. |
| [`registration.commit`](/docs/reference/sdk/registration/commit) | when confirmation fails or the wallet's nonce is already used. |
| [`registration.register`](/docs/reference/sdk/registration/register) | when confirmation fails or the wallet's nonce is already used. |
| [`registration.renew`](/docs/reference/sdk/registration/renew) | when confirmation fails or the wallet's nonce is already used. |
| [`registry.attach`](/docs/reference/sdk/registry/attach) | when confirmation fails or the wallet's nonce is already used. |
| [`registry.deploy`](/docs/reference/sdk/registry/deploy) | when confirmation fails or the wallet's nonce is already used. |
| [`registry.setUri`](/docs/reference/sdk/registry/set-uri) | when confirmation fails or the wallet's nonce is already used. |
| [`registry.upgrade`](/docs/reference/sdk/registry/upgrade) | when confirmation fails or the wallet's nonce is already used. |
| [`resolver.create`](/docs/reference/sdk/resolver/create) | when confirmation fails or the wallet's nonce is already used. |
| [`resolver.link`](/docs/reference/sdk/resolver/link) | when confirmation fails or the wallet's nonce is already used. |
| [`resolver.set`](/docs/reference/sdk/resolver/set) | when confirmation fails or the wallet's nonce is already used. |
| [`resolver.upgrade`](/docs/reference/sdk/resolver/upgrade) | when confirmation fails or the wallet's nonce is already used. |
| [`role.grant`](/docs/reference/sdk/role/grant) | when confirmation fails or the wallet's nonce is already used. |
| [`role.revoke`](/docs/reference/sdk/role/revoke) | when confirmation fails or the wallet's nonce is already used. |
| [`subname.create`](/docs/reference/sdk/subname/create) | when confirmation fails or the wallet's nonce is already used. |
| [`subname.remove`](/docs/reference/sdk/subname/remove) | when confirmation fails or the wallet's nonce is already used. |
| [`subname.update`](/docs/reference/sdk/subname/update) | when confirmation fails or the wallet's nonce is already used. |
| [`wrapper.setChildFuses`](/docs/reference/sdk/wrapper/set-child-fuses) | when confirmation fails or the wallet's nonce is already used. |
| [`wrapper.setFuses`](/docs/reference/sdk/wrapper/set-fuses) | when confirmation fails or the wallet's nonce is already used. |
| [`wrapper.unwrap`](/docs/reference/sdk/wrapper/unwrap) | when confirmation fails or the wallet's nonce is already used. |
| [`wrapper.wrap`](/docs/reference/sdk/wrapper/wrap) | when confirmation fails or the wallet's nonce is already used. |
| [`hca.addDeposit`](/docs/reference/hca/hca/add-deposit) | when confirmation fails. |
| [`hca.deploy`](/docs/reference/hca/hca/deploy) | when confirmation fails. |
| [`hca.execute`](/docs/reference/hca/hca/execute) | when confirmation fails. |
| [`hca.revokeSessions`](/docs/reference/hca/hca/revoke-sessions) | when confirmation fails. |
| [`hca.upgrade`](/docs/reference/hca/hca/upgrade) | when confirmation fails. |
| [`hca.withdrawDeposit`](/docs/reference/hca/hca/withdraw-deposit) | when confirmation fails. |
| [`hcaAdmin.grantUpgradeSetRoles`](/docs/reference/hca/hca-admin/grant-upgrade-set-roles) | when confirmation fails. |
| [`hcaAdmin.renounceGovernance`](/docs/reference/hca/hca-admin/renounce-governance) | when confirmation fails. |
| [`hcaAdmin.revokeUpgradeSetRoles`](/docs/reference/hca/hca-admin/revoke-upgrade-set-roles) | when confirmation fails. |
| [`hcaAdmin.setDeploymentApproval`](/docs/reference/hca/hca-admin/set-deployment-approval) | when confirmation fails. |
| [`hcaAdmin.setUpgradeApproval`](/docs/reference/hca/hca-admin/set-upgrade-approval) | when confirmation fails. |
| [`hcaAdmin.transferGovernance`](/docs/reference/hca/hca-admin/transfer-governance) | when confirmation fails. |
Any write can fail with `TransactionError`: it is part of `Errors.WriteError`.
## Catch it [#catch-it]
`Errors.hasCode("TRANSACTION_REVERTED")` narrows to this error. See [Handle errors](/docs/sdk/handle-errors).
# TransactionError
> For the complete documentation index, see [llms.txt](https://ensforge.com/llms.txt).
What TransactionError means, which codes it carries and how to catch it in ensforge. Lists its fields and every code. Includes how to catch it.
Source: https://ensforge.com/docs/reference/errors/transaction-error
A submitted transaction failed, conflicted with another, or did not confirm in time.
Any write can fail with `TransactionError`: it is part of `Errors.WriteError`.
## Fields [#fields]
| Field | Type | Description |
| --- | --- | --- |
| `hash` | `Hex` | |
| `bundleId` | `string` | EIP-5792 bundle id, when the calls were sent as one batch; check it with `getCallsStatus`. |
## Codes [#codes]
| Code | Meaning | Retryable |
| --- | --- | --- |
| [`TRANSACTION_REVERTED`](/docs/reference/errors/TRANSACTION_REVERTED) | The transaction reverted on-chain. | No |
| [`RECEIPT_TIMEOUT`](/docs/reference/errors/RECEIPT_TIMEOUT) | Timed out waiting for the transaction receipt. | No |
| [`NONCE_CONFLICT`](/docs/reference/errors/NONCE_CONFLICT) | The transaction nonce conflicts with another transaction. | Yes |
## Catch it [#catch-it]
`Effect.catchTag("TransactionError", …)` or `error instanceof Errors.TransactionError`. See [Handle errors](/docs/sdk/handle-errors).
# CANNOT_GRANT_ROLES
> For the complete documentation index, see [llms.txt](https://ensforge.com/llms.txt).
What CANNOT_GRANT_ROLES means, why UnauthorizedError throws it, what to show users and how to fix it in ensforge. Also covers retry safety.
Source: https://ensforge.com/docs/reference/errors/CANNOT_GRANT_ROLES
## What happened [#what-happened]
The account cannot grant or revoke these roles.
## What to show users [#what-to-show-users]
| Title | Message | Action |
| --- | --- | --- |
| Permission needed | Your account cannot change these permissions. | |
## How to fix [#how-to-fix]
Granting a role needs its admin role.
## Retry safety [#retry-safety]
Retrying the same call fails the same way until the cause is fixed (`retryable: false`).
## Actions that throw it [#actions-that-throw-it]
| Action | When |
| --- | --- |
| [`permission.setRecordAccess`](/docs/reference/sdk/permission/set-record-access) | when the account may not grant access. |
| [`role.grant`](/docs/reference/sdk/role/grant) | without the admin roles. |
| [`role.revoke`](/docs/reference/sdk/role/revoke) | without the admin roles. |
## Catch it [#catch-it]
`Errors.hasCode("CANNOT_GRANT_ROLES")` narrows to this error. See [Handle errors](/docs/sdk/handle-errors).
# FUSE_BURNED
> For the complete documentation index, see [llms.txt](https://ensforge.com/llms.txt).
What FUSE_BURNED means, why UnauthorizedError throws it, what to show users and how to fix it in ensforge. Also covers retry safety.
Source: https://ensforge.com/docs/reference/errors/FUSE_BURNED
## What happened [#what-happened]
A burned NameWrapper fuse forbids this change.
## What to show users [#what-to-show-users]
| Title | Message | Action |
| --- | --- | --- |
| Change not allowed | This name has a permanent restriction that blocks this change. | |
## Retry safety [#retry-safety]
Retrying the same call fails the same way until the cause is fixed (`retryable: false`).
## Actions that throw it [#actions-that-throw-it]
| Action | When |
| --- | --- |
| [`approval.setToken`](/docs/reference/sdk/approval/set-token) | when the account may not approve it. |
| [`migration.migrate`](/docs/reference/sdk/migration/migrate) | when the account may not move a token. |
| [`name.setTtl`](/docs/reference/sdk/name/set-ttl) | when the account may not change it. |
| [`resolver.set`](/docs/reference/sdk/resolver/set) | when the account may not change it. |
| [`subname.create`](/docs/reference/sdk/subname/create) | when the account may not create children. |
| [`subname.remove`](/docs/reference/sdk/subname/remove) | when the account may not remove it. |
| [`subname.update`](/docs/reference/sdk/subname/update) | when the account may not change it. |
| [`wrapper.setChildFuses`](/docs/reference/sdk/wrapper/set-child-fuses) | when the account may not change it. |
| [`wrapper.setFuses`](/docs/reference/sdk/wrapper/set-fuses) | when the account may not burn them. |
| [`wrapper.unwrap`](/docs/reference/sdk/wrapper/unwrap) | when the account may not unwrap it. |
## Catch it [#catch-it]
`Errors.hasCode("FUSE_BURNED")` narrows to this error. See [Handle errors](/docs/sdk/handle-errors).
# MISSING_ROLES
> For the complete documentation index, see [llms.txt](https://ensforge.com/llms.txt).
What MISSING_ROLES means, why UnauthorizedError throws it, what to show users and how to fix it in ensforge. Also covers retry safety.
Source: https://ensforge.com/docs/reference/errors/MISSING_ROLES
## What happened [#what-happened]
The account is missing the roles this change needs.
## What to show users [#what-to-show-users]
| Title | Message | Action |
| --- | --- | --- |
| Permission needed | Your account is not allowed to make this change to this name. | Ask the owner for permission. |
## How to fix [#how-to-fix]
Ask the name's owner to grant the roles, or send from the owner's account.
## Retry safety [#retry-safety]
Retrying the same call fails the same way until the cause is fixed (`retryable: false`).
## Actions that throw it [#actions-that-throw-it]
| Action | When |
| --- | --- |
| [`record.set`](/docs/reference/sdk/record/set) | when the account may not edit records. |
| [`registry.attach`](/docs/reference/sdk/registry/attach) | when the account may not change it. |
| [`registry.deploy`](/docs/reference/sdk/registry/deploy) | when the account may not set the name's subregistry. |
| [`registry.setUri`](/docs/reference/sdk/registry/set-uri) | without the `setUri` root role. |
| [`registry.upgrade`](/docs/reference/sdk/registry/upgrade) | without the `upgrade` root role. |
| [`resolver.create`](/docs/reference/sdk/resolver/create) | when the account may not point the name at it. |
| [`resolver.link`](/docs/reference/sdk/resolver/link) | without the `link` role. |
| [`resolver.set`](/docs/reference/sdk/resolver/set) | when the account may not change it. |
| [`resolver.upgrade`](/docs/reference/sdk/resolver/upgrade) | without the `upgrade` role. |
| [`subname.create`](/docs/reference/sdk/subname/create) | when the account may not create children. |
| [`subname.remove`](/docs/reference/sdk/subname/remove) | when the account may not remove it. |
| [`subname.update`](/docs/reference/sdk/subname/update) | when the account may not change it. |
## Catch it [#catch-it]
`Errors.hasCode("MISSING_ROLES")` narrows to this error. See [Handle errors](/docs/sdk/handle-errors).
# NOT_APPROVED
> For the complete documentation index, see [llms.txt](https://ensforge.com/llms.txt).
What NOT_APPROVED means, why UnauthorizedError throws it, what to show users and how to fix it in ensforge. Also covers retry safety.
Source: https://ensforge.com/docs/reference/errors/NOT_APPROVED
## What happened [#what-happened]
The account is not approved to manage this name.
## What to show users [#what-to-show-users]
| Title | Message | Action |
| --- | --- | --- |
| Approval needed | Your account is not approved to manage this name. | |
## How to fix [#how-to-fix]
Approve the operator first, or send from the owner's account.
## Retry safety [#retry-safety]
Retrying the same call fails the same way until the cause is fixed (`retryable: false`).
## Actions that throw it [#actions-that-throw-it]
| Action | When |
| --- | --- |
| [`primaryName.set`](/docs/reference/sdk/primary-name/set) | when the signer may not name the address. |
| [`wrapper.wrap`](/docs/reference/sdk/wrapper/wrap) | when the account does not own the name, or the manager has not approved the NameWrapper. |
## Catch it [#catch-it]
`Errors.hasCode("NOT_APPROVED")` narrows to this error. See [Handle errors](/docs/sdk/handle-errors).
# NOT_OWNER
> For the complete documentation index, see [llms.txt](https://ensforge.com/llms.txt).
What NOT_OWNER means, why UnauthorizedError throws it, what to show users and how to fix it in ensforge. Also covers retry safety and the actions that throw it.
Source: https://ensforge.com/docs/reference/errors/NOT_OWNER
## What happened [#what-happened]
The account does not own this name.
## What to show users [#what-to-show-users]
| Title | Message | Action |
| --- | --- | --- |
| Not the owner | Your account does not own this name. | Switch to the owner's account. |
## How to fix [#how-to-fix]
Send from the owner's account.
## Retry safety [#retry-safety]
Retrying the same call fails the same way until the cause is fixed (`retryable: false`).
## Actions that throw it [#actions-that-throw-it]
| Action | When |
| --- | --- |
| [`approval.setDelegate`](/docs/reference/sdk/approval/set-delegate) | when the signer does not own the name. |
| [`approval.setToken`](/docs/reference/sdk/approval/set-token) | when the account may not approve it. |
| [`dns.claim`](/docs/reference/sdk/dns/claim) | when someone other than the DNS owner claims with a resolver. |
| [`dns.setRecords`](/docs/reference/sdk/dns/set-records) | when the account may not edit the records. |
| [`migration.migrate`](/docs/reference/sdk/migration/migrate) | when the account may not move a token. |
| [`name.reclaim`](/docs/reference/sdk/name/reclaim) | when the account is not the registrant. |
| [`name.setManager`](/docs/reference/sdk/name/set-manager) | when the account is neither registrant nor manager. |
| [`name.setTtl`](/docs/reference/sdk/name/set-ttl) | when the account may not change it. |
| [`name.transfer`](/docs/reference/sdk/name/transfer) | when the account may not send it, or the recipient (an HCA) refuses it. |
| [`permission.setRecordAccess`](/docs/reference/sdk/permission/set-record-access) | when the account may not grant access. |
| [`record.set`](/docs/reference/sdk/record/set) | when the account may not edit records. |
| [`resolver.create`](/docs/reference/sdk/resolver/create) | when the account may not point the name at it. |
| [`resolver.set`](/docs/reference/sdk/resolver/set) | when the account may not change it. |
| [`subname.create`](/docs/reference/sdk/subname/create) | when the account may not create children. |
| [`subname.remove`](/docs/reference/sdk/subname/remove) | when the account may not remove it. |
| [`subname.update`](/docs/reference/sdk/subname/update) | when the account may not change it. |
| [`wrapper.setChildFuses`](/docs/reference/sdk/wrapper/set-child-fuses) | when the account may not change it. |
| [`wrapper.setFuses`](/docs/reference/sdk/wrapper/set-fuses) | when the account may not burn them. |
| [`wrapper.unwrap`](/docs/reference/sdk/wrapper/unwrap) | when the account may not unwrap it. |
| [`wrapper.wrap`](/docs/reference/sdk/wrapper/wrap) | when the account does not own the name, or the manager has not approved the NameWrapper. |
## Catch it [#catch-it]
`Errors.hasCode("NOT_OWNER")` narrows to this error. See [Handle errors](/docs/sdk/handle-errors).
# SIGNATURE_EXPIRED
> For the complete documentation index, see [llms.txt](https://ensforge.com/llms.txt).
What SIGNATURE_EXPIRED means, why UnauthorizedError throws it, what to show users and how to fix it in ensforge. Also covers retry safety.
Source: https://ensforge.com/docs/reference/errors/SIGNATURE_EXPIRED
## What happened [#what-happened]
The signature has expired.
## What to show users [#what-to-show-users]
| Title | Message | Action |
| --- | --- | --- |
| Signature expired | The signature for this change has expired. | Sign the request again. |
## How to fix [#how-to-fix]
Sign again: reverse registrars accept a signature for at most one hour.
## Retry safety [#retry-safety]
Retrying the same call fails the same way until the cause is fixed (`retryable: false`).
## Actions that throw it [#actions-that-throw-it]
| Action | When |
| --- | --- |
| [`primaryName.set`](/docs/reference/sdk/primary-name/set) | when the claim's signature is invalid or expired. |
## Catch it [#catch-it]
`Errors.hasCode("SIGNATURE_EXPIRED")` narrows to this error. See [Handle errors](/docs/sdk/handle-errors).
# SIGNATURE_INVALID
> For the complete documentation index, see [llms.txt](https://ensforge.com/llms.txt).
What SIGNATURE_INVALID means, why UnauthorizedError throws it, what to show users and how to fix it in ensforge. Also covers retry safety.
Source: https://ensforge.com/docs/reference/errors/SIGNATURE_INVALID
## What happened [#what-happened]
The signature does not authorize this change.
## What to show users [#what-to-show-users]
| Title | Message | Action |
| --- | --- | --- |
| Signature not valid | The signature does not authorize this change. | Sign the request again with the right account. |
## How to fix [#how-to-fix]
Sign again with the account being named (or the contract's Ownable owner), for the same name, chains and expiry.
## Retry safety [#retry-safety]
Retrying the same call fails the same way until the cause is fixed (`retryable: false`).
## Actions that throw it [#actions-that-throw-it]
| Action | When |
| --- | --- |
| [`primaryName.set`](/docs/reference/sdk/primary-name/set) | when the claim's signature is invalid or expired. |
## Catch it [#catch-it]
`Errors.hasCode("SIGNATURE_INVALID")` narrows to this error. See [Handle errors](/docs/sdk/handle-errors).
# TRANSFER_DISALLOWED
> For the complete documentation index, see [llms.txt](https://ensforge.com/llms.txt).
What TRANSFER_DISALLOWED means, why UnauthorizedError throws it, what to show users and how to fix it in ensforge. Also covers retry safety.
Source: https://ensforge.com/docs/reference/errors/TRANSFER_DISALLOWED
## What happened [#what-happened]
This name cannot be transferred right now.
## What to show users [#what-to-show-users]
| Title | Message | Action |
| --- | --- | --- |
| Transfer blocked | This name cannot be transferred with the roles held on it. | |
## How to fix [#how-to-fix]
The owner lacks the role to transfer it, or other accounts hold roles on it (revoke them, or transfer with `unsafe: true`); `requirements` says which.
## Retry safety [#retry-safety]
Retrying the same call fails the same way until the cause is fixed (`retryable: false`).
## Actions that throw it [#actions-that-throw-it]
| Action | When |
| --- | --- |
| [`name.transfer`](/docs/reference/sdk/name/transfer) | when the account may not send it, or the recipient (an HCA) refuses it. |
## Catch it [#catch-it]
`Errors.hasCode("TRANSFER_DISALLOWED")` narrows to this error. See [Handle errors](/docs/sdk/handle-errors).
# UnauthorizedError
> For the complete documentation index, see [llms.txt](https://ensforge.com/llms.txt).
What UnauthorizedError means, which codes it carries and how to catch it in ensforge. Lists its fields and every code. Includes how to catch it.
Source: https://ensforge.com/docs/reference/errors/unauthorized-error
The account lacks ownership, approval or roles for this change, or the signature that should
authorize it is invalid or expired.
## Fields [#fields]
| Field | Type | Description |
| --- | --- | --- |
| `account` | `Address` | |
| `missingRoles` | `readonly string[]` | Role names the account lacks ([`MISSING_ROLES`](/docs/reference/errors/MISSING_ROLES)), decoded when the contract kind is known. |
| `roleBitmap` | `bigint` | Raw role bitmap from the revert. |
| `requirements` | `readonly UnauthorizedError.Requirement[]` | What the account lacks, or what blocks the change, from `permission.check`. |
## Codes [#codes]
| Code | Meaning | Retryable |
| --- | --- | --- |
| [`NOT_OWNER`](/docs/reference/errors/NOT_OWNER) | The account does not own this name. | No |
| [`MISSING_ROLES`](/docs/reference/errors/MISSING_ROLES) | The account is missing the roles this change needs. | No |
| [`CANNOT_GRANT_ROLES`](/docs/reference/errors/CANNOT_GRANT_ROLES) | The account cannot grant or revoke these roles. | No |
| [`NOT_APPROVED`](/docs/reference/errors/NOT_APPROVED) | The account is not approved to manage this name. | No |
| [`FUSE_BURNED`](/docs/reference/errors/FUSE_BURNED) | A burned NameWrapper fuse forbids this change. | No |
| [`TRANSFER_DISALLOWED`](/docs/reference/errors/TRANSFER_DISALLOWED) | This name cannot be transferred right now. | No |
| [`SIGNATURE_INVALID`](/docs/reference/errors/SIGNATURE_INVALID) | The signature does not authorize this change. | No |
| [`SIGNATURE_EXPIRED`](/docs/reference/errors/SIGNATURE_EXPIRED) | The signature has expired. | No |
## Catch it [#catch-it]
`Effect.catchTag("UnauthorizedError", …)` or `error instanceof Errors.UnauthorizedError`. See [Handle errors](/docs/sdk/handle-errors).
# PAYMENT_TOKEN_UNSUPPORTED
> For the complete documentation index, see [llms.txt](https://ensforge.com/llms.txt).
What PAYMENT_TOKEN_UNSUPPORTED means, why UnsupportedError throws it, what to show users and how to fix it in ensforge. Also covers retry safety.
Source: https://ensforge.com/docs/reference/errors/PAYMENT_TOKEN_UNSUPPORTED
## What happened [#what-happened]
The registrar does not accept this payment token.
## What to show users [#what-to-show-users]
| Title | Message | Action |
| --- | --- | --- |
| Payment not accepted | This token is not accepted for registration. | |
## Retry safety [#retry-safety]
Retrying the same call fails the same way until the cause is fixed (`retryable: false`).
## Actions that throw it [#actions-that-throw-it]
| Action | When |
| --- | --- |
| [`registration.commit`](/docs/reference/sdk/registration/commit) | for an unaccepted token or without ENSv2. |
| [`registration.getPrice`](/docs/reference/sdk/registration/get-price) | for an unaccepted token or without ENSv2. |
| [`registration.getRenewalPrice`](/docs/reference/sdk/registration/get-renewal-price) | for an unaccepted token or without ENSv2. |
| [`registration.register`](/docs/reference/sdk/registration/register) | for an unaccepted token or without ENSv2. |
| [`registration.renew`](/docs/reference/sdk/registration/renew) | for an unaccepted token or without ENSv2. |
Any write can fail with `UnsupportedError`: it is part of `Errors.WriteError`.
## Catch it [#catch-it]
`Errors.hasCode("PAYMENT_TOKEN_UNSUPPORTED")` narrows to this error. See [Handle errors](/docs/sdk/handle-errors).
# RESOLVER_PROFILE_UNSUPPORTED
> For the complete documentation index, see [llms.txt](https://ensforge.com/llms.txt).
What RESOLVER_PROFILE_UNSUPPORTED means, why UnsupportedError throws it, what to show users and how to fix it in ensforge.
Source: https://ensforge.com/docs/reference/errors/RESOLVER_PROFILE_UNSUPPORTED
## What happened [#what-happened]
The resolver does not support this record type.
## What to show users [#what-to-show-users]
| Title | Message | Action |
| --- | --- | --- |
| Not supported | This name's resolver does not support this record. | Switch to a resolver that supports it. |
## How to fix [#how-to-fix]
Point the name at a resolver that supports it, e.g. the public resolver.
## Retry safety [#retry-safety]
Retrying the same call fails the same way until the cause is fixed (`retryable: false`).
## Actions that throw it [#actions-that-throw-it]
| Action | When |
| --- | --- |
| [`approval.setDelegate`](/docs/reference/sdk/approval/set-delegate) | for PermissionedResolvers. |
| [`dns.setRecords`](/docs/reference/sdk/dns/set-records) | for resolvers without DNS records. |
| [`permission.setRecordAccess`](/docs/reference/sdk/permission/set-record-access) | for public keys on a PermissionedResolver. |
| [`record.get`](/docs/reference/sdk/record/get) | with `strict` when the resolver supports none of the records. |
| [`record.getAddress`](/docs/reference/sdk/record/get-address) | with `strict` when the resolver supports none of the records. |
| [`record.getAvatar`](/docs/reference/sdk/record/get-avatar) | with `strict` when the resolver supports none of the records. |
| [`record.getContentHash`](/docs/reference/sdk/record/get-content-hash) | with `strict` when the resolver supports none of the records. |
| [`record.getText`](/docs/reference/sdk/record/get-text) | with `strict` when the resolver supports none of the records. |
| [`record.set`](/docs/reference/sdk/record/set) | for records the resolver does not support (`feature` names them), a resolver that keeps its records off-chain or takes no writes, or `resolver: "default"` on an ENSv2 name. |
| [`resolver.create`](/docs/reference/sdk/resolver/create) | without ENSv2, or for records a PermissionedResolver cannot store. |
| [`resolver.getLink`](/docs/reference/sdk/resolver/get-link) | when the resolver is not a PermissionedResolver. |
| [`resolver.link`](/docs/reference/sdk/resolver/link) | when the resolver is not a PermissionedResolver. |
| [`resolver.resolve`](/docs/reference/sdk/resolver/resolve) | when the resolver does not answer the call. |
| [`resolver.upgrade`](/docs/reference/sdk/resolver/upgrade) | when the resolver or target cannot be upgraded. |
Any write can fail with `UnsupportedError`: it is part of `Errors.WriteError`.
## Catch it [#catch-it]
`Errors.hasCode("RESOLVER_PROFILE_UNSUPPORTED")` narrows to this error. See [Handle errors](/docs/sdk/handle-errors).
# UNSUPPORTED_ON_DEPLOYMENT
> For the complete documentation index, see [llms.txt](https://ensforge.com/llms.txt).
What UNSUPPORTED_ON_DEPLOYMENT means, why UnsupportedError throws it, what to show users and how to fix it in ensforge. Also covers retry safety.
Source: https://ensforge.com/docs/reference/errors/UNSUPPORTED_ON_DEPLOYMENT
## What happened [#what-happened]
This feature is not available on this deployment.
## What to show users [#what-to-show-users]
| Title | Message | Action |
| --- | --- | --- |
| Not supported | This action is not available on this network. | |
## Retry safety [#retry-safety]
Retrying the same call fails the same way until the cause is fixed (`retryable: false`).
## Actions that throw it [#actions-that-throw-it]
| Action | When |
| --- | --- |
| [`approval.getOperator`](/docs/reference/sdk/approval/get-operator) | for ENSv1 contracts without ENSv1. |
| [`approval.setOperator`](/docs/reference/sdk/approval/set-operator) | for ENSv1 contracts without ENSv1. |
| [`dns.getOffchainResolver`](/docs/reference/sdk/dns/get-offchain-resolver) | without a DNSSEC gateway or `gatewayUrls`. |
| [`dns.getProof`](/docs/reference/sdk/dns/get-proof) | without a DNSSEC gateway or `gatewayUrls`. |
| [`dns.getStatus`](/docs/reference/sdk/dns/get-status) | without a DNSSEC gateway or `gatewayUrls`. |
| [`migration.get`](/docs/reference/sdk/migration/get) | where ENSv2 is not deployed. |
| [`migration.migrate`](/docs/reference/sdk/migration/migrate) | where ENSv2 is not deployed. |
| [`name.getLabel`](/docs/reference/sdk/name/get-label) | without an ENSv2 deployment. |
| [`primaryName.set`](/docs/reference/sdk/primary-name/set) | for a chain without an L2 reverse registrar. |
| [`primaryName.signClaim`](/docs/reference/sdk/primary-name/sign-claim) | for a chain without an L2 reverse registrar. |
| [`registration.commit`](/docs/reference/sdk/registration/commit) | for an unaccepted token or without ENSv2. |
| [`registration.getCommitmentStatus`](/docs/reference/sdk/registration/get-commitment-status) | without ENSv2. |
| [`registration.getParameters`](/docs/reference/sdk/registration/get-parameters) | without ENSv2. |
| [`registration.getPrice`](/docs/reference/sdk/registration/get-price) | for an unaccepted token or without ENSv2. |
| [`registration.getRenewalPrice`](/docs/reference/sdk/registration/get-renewal-price) | for an unaccepted token or without ENSv2. |
| [`registration.isAvailable`](/docs/reference/sdk/registration/is-available) | without ENSv2. |
| [`registration.register`](/docs/reference/sdk/registration/register) | for an unaccepted token or without ENSv2. |
| [`registration.renew`](/docs/reference/sdk/registration/renew) | for an unaccepted token or without ENSv2. |
| [`registry.deploy`](/docs/reference/sdk/registry/deploy) | without ENSv2, or for an ENSv1 `attachTo`. |
| [`resolver.create`](/docs/reference/sdk/resolver/create) | without ENSv2, or for records a PermissionedResolver cannot store. |
| [`wrapper.getFuses`](/docs/reference/sdk/wrapper/get-fuses) | without ENSv1. |
Any write can fail with `UnsupportedError`: it is part of `Errors.WriteError`.
## Catch it [#catch-it]
`Errors.hasCode("UNSUPPORTED_ON_DEPLOYMENT")` narrows to this error. See [Handle errors](/docs/sdk/handle-errors).
# UNSUPPORTED_PROTOCOL
> For the complete documentation index, see [llms.txt](https://ensforge.com/llms.txt).
What UNSUPPORTED_PROTOCOL means, why UnsupportedError throws it, what to show users and how to fix it in ensforge. Also covers retry safety.
Source: https://ensforge.com/docs/reference/errors/UNSUPPORTED_PROTOCOL
## What happened [#what-happened]
This operation is not supported for this names.
## What to show users [#what-to-show-users]
| Title | Message | Action |
| --- | --- | --- |
| Not supported | This action is not available for this name. | |
## Retry safety [#retry-safety]
Retrying the same call fails the same way until the cause is fixed (`retryable: false`).
## Actions that throw it [#actions-that-throw-it]
| Action | When |
| --- | --- |
| [`approval.getToken`](/docs/reference/sdk/approval/get-token) | for ENSv2 names and unwrapped subnames. |
| [`approval.setToken`](/docs/reference/sdk/approval/set-token) | for ENSv2 names and unwrapped subnames. |
| [`name.reclaim`](/docs/reference/sdk/name/reclaim) | for wrapped, ENSv2 and non-`.eth` names. |
| [`name.setManager`](/docs/reference/sdk/name/set-manager) | for wrapped and ENSv2 names. |
| [`name.setTtl`](/docs/reference/sdk/name/set-ttl) | for ENSv2 names. |
| [`name.transfer`](/docs/reference/sdk/name/transfer) | for `role: "registrant"` on names without a registrant. |
| [`record.set`](/docs/reference/sdk/record/set) | for records the resolver does not support (`feature` names them), a resolver that keeps its records off-chain or takes no writes, or `resolver: "default"` on an ENSv2 name. |
| [`registry.attach`](/docs/reference/sdk/registry/attach) | for ENSv1 names. |
| [`registry.deploy`](/docs/reference/sdk/registry/deploy) | without ENSv2, or for an ENSv1 `attachTo`. |
| [`resolver.set`](/docs/reference/sdk/resolver/set) | for `"default"` on ENSv2 names. |
| [`role.get`](/docs/reference/sdk/role/get) | for ENSv1 names. |
| [`role.grant`](/docs/reference/sdk/role/grant) | for ENSv1 names. |
| [`role.revoke`](/docs/reference/sdk/role/revoke) | for ENSv1 names. |
| [`subname.create`](/docs/reference/sdk/subname/create) | for `roles` on ENSv1 or `fuses` on unwrapped parents. |
| [`subname.update`](/docs/reference/sdk/subname/update) | for an ENSv2 owner change or an unwrapped ENSv1 expiry. |
| [`wrapper.setChildFuses`](/docs/reference/sdk/wrapper/set-child-fuses) | for ENSv2 names; migrated names have no NameWrapper. |
| [`wrapper.setFuses`](/docs/reference/sdk/wrapper/set-fuses) | for ENSv2 names; migrated names have no NameWrapper. |
| [`wrapper.unwrap`](/docs/reference/sdk/wrapper/unwrap) | for ENSv2 names; migrated names have no NameWrapper. |
| [`wrapper.wrap`](/docs/reference/sdk/wrapper/wrap) | for ENSv2 names; migrated names have no NameWrapper. |
Any write can fail with `UnsupportedError`: it is part of `Errors.WriteError`.
## Catch it [#catch-it]
`Errors.hasCode("UNSUPPORTED_PROTOCOL")` narrows to this error. See [Handle errors](/docs/sdk/handle-errors).
# UPGRADE_NOT_APPROVED
> For the complete documentation index, see [llms.txt](https://ensforge.com/llms.txt).
What UPGRADE_NOT_APPROVED means, why UnsupportedError throws it, what to show users and how to fix it in ensforge. Also covers retry safety.
Source: https://ensforge.com/docs/reference/errors/UPGRADE_NOT_APPROVED
## What happened [#what-happened]
The upgrade target is not an approved implementation.
## What to show users [#what-to-show-users]
| Title | Message | Action |
| --- | --- | --- |
| Upgrade not allowed | This upgrade has not been approved by ENS. | |
## Retry safety [#retry-safety]
Retrying the same call fails the same way until the cause is fixed (`retryable: false`).
## Actions that throw it [#actions-that-throw-it]
| Action | When |
| --- | --- |
| [`registry.upgrade`](/docs/reference/sdk/registry/upgrade) | when the target is not approved. |
| [`resolver.upgrade`](/docs/reference/sdk/resolver/upgrade) | when the resolver or target cannot be upgraded. |
Any write can fail with `UnsupportedError`: it is part of `Errors.WriteError`.
## Catch it [#catch-it]
`Errors.hasCode("UPGRADE_NOT_APPROVED")` narrows to this error. See [Handle errors](/docs/sdk/handle-errors).
# WALLET_BATCH_UNSUPPORTED
> For the complete documentation index, see [llms.txt](https://ensforge.com/llms.txt).
What WALLET_BATCH_UNSUPPORTED means, why UnsupportedError throws it, what to show users and how to fix it in ensforge. Also covers retry safety.
Source: https://ensforge.com/docs/reference/errors/WALLET_BATCH_UNSUPPORTED
## What happened [#what-happened]
The wallet cannot send calls as one batch.
## What to show users [#what-to-show-users]
| Title | Message | Action |
| --- | --- | --- |
| Wallet not supported | Your wallet cannot send these transactions together. | |
## How to fix [#how-to-fix]
Use `mode: "auto"` or `mode: "sequential"`.
## Retry safety [#retry-safety]
Retrying the same call fails the same way until the cause is fixed (`retryable: false`).
## Actions that throw it [#actions-that-throw-it]
| Action | When |
| --- | --- |
| [`approval.setDelegate`](/docs/reference/sdk/approval/set-delegate) | with `mode: "batch"` or a paymaster when the wallet cannot send calls as one batch. |
| [`approval.setOperator`](/docs/reference/sdk/approval/set-operator) | with `mode: "batch"` or a paymaster when the wallet cannot send calls as one batch. |
| [`approval.setToken`](/docs/reference/sdk/approval/set-token) | with `mode: "batch"` or a paymaster when the wallet cannot send calls as one batch. |
| [`dns.claim`](/docs/reference/sdk/dns/claim) | with `mode: "batch"` or a paymaster when the wallet cannot send calls as one batch. |
| [`dns.setRecords`](/docs/reference/sdk/dns/set-records) | with `mode: "batch"` or a paymaster when the wallet cannot send calls as one batch. |
| [`migration.migrate`](/docs/reference/sdk/migration/migrate) | with `mode: "batch"` or a paymaster when the wallet cannot send calls as one batch. |
| [`name.reclaim`](/docs/reference/sdk/name/reclaim) | with `mode: "batch"` or a paymaster when the wallet cannot send calls as one batch. |
| [`name.setManager`](/docs/reference/sdk/name/set-manager) | with `mode: "batch"` or a paymaster when the wallet cannot send calls as one batch. |
| [`name.setTtl`](/docs/reference/sdk/name/set-ttl) | with `mode: "batch"` or a paymaster when the wallet cannot send calls as one batch. |
| [`name.transfer`](/docs/reference/sdk/name/transfer) | with `mode: "batch"` or a paymaster when the wallet cannot send calls as one batch. |
| [`permission.setRecordAccess`](/docs/reference/sdk/permission/set-record-access) | with `mode: "batch"` or a paymaster when the wallet cannot send calls as one batch. |
| [`plan.send`](/docs/reference/sdk/plan/send) | with `mode: "batch"` or a paymaster when the wallet cannot send calls as one batch. |
| [`primaryName.set`](/docs/reference/sdk/primary-name/set) | with `mode: "batch"` or a paymaster when the wallet cannot send calls as one batch. |
| [`primaryName.signClaim`](/docs/reference/sdk/primary-name/sign-claim) | with `mode: "batch"` or a paymaster when the wallet cannot send calls as one batch. |
| [`record.set`](/docs/reference/sdk/record/set) | with `mode: "batch"` or a paymaster when the wallet cannot send calls as one batch. |
| [`registration.commit`](/docs/reference/sdk/registration/commit) | with `mode: "batch"` or a paymaster when the wallet cannot send calls as one batch. |
| [`registration.register`](/docs/reference/sdk/registration/register) | with `mode: "batch"` or a paymaster when the wallet cannot send calls as one batch. |
| [`registration.renew`](/docs/reference/sdk/registration/renew) | with `mode: "batch"` or a paymaster when the wallet cannot send calls as one batch. |
| [`registry.attach`](/docs/reference/sdk/registry/attach) | with `mode: "batch"` or a paymaster when the wallet cannot send calls as one batch. |
| [`registry.deploy`](/docs/reference/sdk/registry/deploy) | with `mode: "batch"` or a paymaster when the wallet cannot send calls as one batch. |
| [`registry.setUri`](/docs/reference/sdk/registry/set-uri) | with `mode: "batch"` or a paymaster when the wallet cannot send calls as one batch. |
| [`registry.upgrade`](/docs/reference/sdk/registry/upgrade) | with `mode: "batch"` or a paymaster when the wallet cannot send calls as one batch. |
| [`resolver.create`](/docs/reference/sdk/resolver/create) | with `mode: "batch"` or a paymaster when the wallet cannot send calls as one batch. |
| [`resolver.link`](/docs/reference/sdk/resolver/link) | with `mode: "batch"` or a paymaster when the wallet cannot send calls as one batch. |
| [`resolver.set`](/docs/reference/sdk/resolver/set) | with `mode: "batch"` or a paymaster when the wallet cannot send calls as one batch. |
| [`resolver.upgrade`](/docs/reference/sdk/resolver/upgrade) | with `mode: "batch"` or a paymaster when the wallet cannot send calls as one batch. |
| [`role.grant`](/docs/reference/sdk/role/grant) | with `mode: "batch"` or a paymaster when the wallet cannot send calls as one batch. |
| [`role.revoke`](/docs/reference/sdk/role/revoke) | with `mode: "batch"` or a paymaster when the wallet cannot send calls as one batch. |
| [`subname.create`](/docs/reference/sdk/subname/create) | with `mode: "batch"` or a paymaster when the wallet cannot send calls as one batch. |
| [`subname.remove`](/docs/reference/sdk/subname/remove) | with `mode: "batch"` or a paymaster when the wallet cannot send calls as one batch. |
| [`subname.update`](/docs/reference/sdk/subname/update) | with `mode: "batch"` or a paymaster when the wallet cannot send calls as one batch. |
| [`wrapper.setChildFuses`](/docs/reference/sdk/wrapper/set-child-fuses) | with `mode: "batch"` or a paymaster when the wallet cannot send calls as one batch. |
| [`wrapper.setFuses`](/docs/reference/sdk/wrapper/set-fuses) | with `mode: "batch"` or a paymaster when the wallet cannot send calls as one batch. |
| [`wrapper.unwrap`](/docs/reference/sdk/wrapper/unwrap) | with `mode: "batch"` or a paymaster when the wallet cannot send calls as one batch. |
| [`wrapper.wrap`](/docs/reference/sdk/wrapper/wrap) | with `mode: "batch"` or a paymaster when the wallet cannot send calls as one batch. |
Any write can fail with `UnsupportedError`: it is part of `Errors.WriteError`.
## Catch it [#catch-it]
`Errors.hasCode("WALLET_BATCH_UNSUPPORTED")` narrows to this error. See [Handle errors](/docs/sdk/handle-errors).
# UnsupportedError
> For the complete documentation index, see [llms.txt](https://ensforge.com/llms.txt).
What UnsupportedError means, which codes it carries and how to catch it in ensforge. Lists its fields and every code. Includes how to catch it.
Source: https://ensforge.com/docs/reference/errors/unsupported-error
The operation is not available for this name, resolver, deployment or wallet.
Any write can fail with `UnsupportedError`: it is part of `Errors.WriteError`.
## Fields [#fields]
| Field | Type | Description |
| --- | --- | --- |
| `feature` | `string` | |
| `protocol` | `"v1" \| "v2"` | |
## Codes [#codes]
| Code | Meaning | Retryable |
| --- | --- | --- |
| [`UNSUPPORTED_PROTOCOL`](/docs/reference/errors/UNSUPPORTED_PROTOCOL) | This operation is not supported for this names. | No |
| [`UNSUPPORTED_ON_DEPLOYMENT`](/docs/reference/errors/UNSUPPORTED_ON_DEPLOYMENT) | This feature is not available on this deployment. | No |
| [`RESOLVER_PROFILE_UNSUPPORTED`](/docs/reference/errors/RESOLVER_PROFILE_UNSUPPORTED) | The resolver does not support this record type. | No |
| [`PAYMENT_TOKEN_UNSUPPORTED`](/docs/reference/errors/PAYMENT_TOKEN_UNSUPPORTED) | The registrar does not accept this payment token. | No |
| [`UPGRADE_NOT_APPROVED`](/docs/reference/errors/UPGRADE_NOT_APPROVED) | The upgrade target is not an approved implementation. | No |
| [`WALLET_BATCH_UNSUPPORTED`](/docs/reference/errors/WALLET_BATCH_UNSUPPORTED) | The wallet cannot send calls as one batch. | No |
## Catch it [#catch-it]
`Effect.catchTag("UnsupportedError", …)` or `error instanceof Errors.UnsupportedError`. See [Handle errors](/docs/sdk/handle-errors).
# USER_REJECTED
> For the complete documentation index, see [llms.txt](https://ensforge.com/llms.txt).
What USER_REJECTED means, why UserRejectedError throws it, what to show users and how to fix it in ensforge. Also covers retry safety.
Source: https://ensforge.com/docs/reference/errors/USER_REJECTED
## What happened [#what-happened]
The user rejected the request.
## What to show users [#what-to-show-users]
| Title | Message | Action |
| --- | --- | --- |
| Request cancelled | You cancelled the request in your wallet. | |
## Retry safety [#retry-safety]
Retrying the same call fails the same way until the cause is fixed (`retryable: false`).
## Actions that throw it [#actions-that-throw-it]
| Action | When |
| --- | --- |
| [`approval.setDelegate`](/docs/reference/sdk/approval/set-delegate) | when the user rejects the request. |
| [`approval.setOperator`](/docs/reference/sdk/approval/set-operator) | when the user rejects the request. |
| [`approval.setToken`](/docs/reference/sdk/approval/set-token) | when the user rejects the request. |
| [`dns.claim`](/docs/reference/sdk/dns/claim) | when the user rejects the request. |
| [`dns.setRecords`](/docs/reference/sdk/dns/set-records) | when the user rejects the request. |
| [`migration.migrate`](/docs/reference/sdk/migration/migrate) | when the user rejects the request. |
| [`name.reclaim`](/docs/reference/sdk/name/reclaim) | when the user rejects the request. |
| [`name.setManager`](/docs/reference/sdk/name/set-manager) | when the user rejects the request. |
| [`name.setTtl`](/docs/reference/sdk/name/set-ttl) | when the user rejects the request. |
| [`name.transfer`](/docs/reference/sdk/name/transfer) | when the user rejects the request. |
| [`permission.setRecordAccess`](/docs/reference/sdk/permission/set-record-access) | when the user rejects the request. |
| [`plan.send`](/docs/reference/sdk/plan/send) | when the user rejects the request. |
| [`primaryName.set`](/docs/reference/sdk/primary-name/set) | when the user rejects the request. |
| [`primaryName.signClaim`](/docs/reference/sdk/primary-name/sign-claim) | when the user rejects the request. |
| [`record.set`](/docs/reference/sdk/record/set) | when the user rejects the request. |
| [`registration.commit`](/docs/reference/sdk/registration/commit) | when the user rejects the request. |
| [`registration.register`](/docs/reference/sdk/registration/register) | when the user rejects the request. |
| [`registration.renew`](/docs/reference/sdk/registration/renew) | when the user rejects the request. |
| [`registry.attach`](/docs/reference/sdk/registry/attach) | when the user rejects the request. |
| [`registry.deploy`](/docs/reference/sdk/registry/deploy) | when the user rejects the request. |
| [`registry.setUri`](/docs/reference/sdk/registry/set-uri) | when the user rejects the request. |
| [`registry.upgrade`](/docs/reference/sdk/registry/upgrade) | when the user rejects the request. |
| [`resolver.create`](/docs/reference/sdk/resolver/create) | when the user rejects the request. |
| [`resolver.link`](/docs/reference/sdk/resolver/link) | when the user rejects the request. |
| [`resolver.set`](/docs/reference/sdk/resolver/set) | when the user rejects the request. |
| [`resolver.upgrade`](/docs/reference/sdk/resolver/upgrade) | when the user rejects the request. |
| [`role.grant`](/docs/reference/sdk/role/grant) | when the user rejects the request. |
| [`role.revoke`](/docs/reference/sdk/role/revoke) | when the user rejects the request. |
| [`subname.create`](/docs/reference/sdk/subname/create) | when the user rejects the request. |
| [`subname.remove`](/docs/reference/sdk/subname/remove) | when the user rejects the request. |
| [`subname.update`](/docs/reference/sdk/subname/update) | when the user rejects the request. |
| [`wrapper.setChildFuses`](/docs/reference/sdk/wrapper/set-child-fuses) | when the user rejects the request. |
| [`wrapper.setFuses`](/docs/reference/sdk/wrapper/set-fuses) | when the user rejects the request. |
| [`wrapper.unwrap`](/docs/reference/sdk/wrapper/unwrap) | when the user rejects the request. |
| [`wrapper.wrap`](/docs/reference/sdk/wrapper/wrap) | when the user rejects the request. |
| [`hca.authorizeSession`](/docs/reference/hca/hca/authorize-session) | when the owner declines. |
Any write can fail with `UserRejectedError`: it is part of `Errors.WriteError`.
## Catch it [#catch-it]
`Errors.hasCode("USER_REJECTED")` narrows to this error. See [Handle errors](/docs/sdk/handle-errors).
# UserRejectedError
> For the complete documentation index, see [llms.txt](https://ensforge.com/llms.txt).
What UserRejectedError means, which codes it carries and how to catch it in ensforge. The user declined the request in their wallet.
Source: https://ensforge.com/docs/reference/errors/user-rejected-error
The user declined the request in their wallet.
Any write can fail with `UserRejectedError`: it is part of `Errors.WriteError`.
## Codes [#codes]
| Code | Meaning | Retryable |
| --- | --- | --- |
| [`USER_REJECTED`](/docs/reference/errors/USER_REJECTED) | The user rejected the request. | No |
## Catch it [#catch-it]
`Effect.catchTag("UserRejectedError", …)` or `error instanceof Errors.UserRejectedError`. See [Handle errors](/docs/sdk/handle-errors).
# ACCOUNT_NOT_FOUND
> For the complete documentation index, see [llms.txt](https://ensforge.com/llms.txt).
What ACCOUNT_NOT_FOUND means, why WalletError throws it, what to show users and how to fix it in ensforge. Also covers retry safety.
Source: https://ensforge.com/docs/reference/errors/ACCOUNT_NOT_FOUND
## What happened [#what-happened]
The wallet has no account to sign with.
## What to show users [#what-to-show-users]
| Title | Message | Action |
| --- | --- | --- |
| No account | No wallet account is selected. | Select an account in your wallet. |
## How to fix [#how-to-fix]
Connect an account, or pass `account` to the action.
## Retry safety [#retry-safety]
Retrying the same call fails the same way until the cause is fixed (`retryable: false`).
## Actions that throw it [#actions-that-throw-it]
| Action | When |
| --- | --- |
| [`approval.setDelegate`](/docs/reference/sdk/approval/set-delegate) | when the wallet is on another chain or has no account to sign with. |
| [`approval.setOperator`](/docs/reference/sdk/approval/set-operator) | when the wallet is on another chain or has no account to sign with. |
| [`approval.setToken`](/docs/reference/sdk/approval/set-token) | when the wallet is on another chain or has no account to sign with. |
| [`dns.claim`](/docs/reference/sdk/dns/claim) | when the wallet is on another chain or has no account to sign with. |
| [`dns.setRecords`](/docs/reference/sdk/dns/set-records) | when the wallet is on another chain or has no account to sign with. |
| [`migration.migrate`](/docs/reference/sdk/migration/migrate) | when the wallet is on another chain or has no account to sign with. |
| [`name.reclaim`](/docs/reference/sdk/name/reclaim) | when the wallet is on another chain or has no account to sign with. |
| [`name.setManager`](/docs/reference/sdk/name/set-manager) | when the wallet is on another chain or has no account to sign with. |
| [`name.setTtl`](/docs/reference/sdk/name/set-ttl) | when the wallet is on another chain or has no account to sign with. |
| [`name.transfer`](/docs/reference/sdk/name/transfer) | when the wallet is on another chain or has no account to sign with. |
| [`permission.setRecordAccess`](/docs/reference/sdk/permission/set-record-access) | when the wallet is on another chain or has no account to sign with. |
| [`plan.send`](/docs/reference/sdk/plan/send) | when the wallet is on another chain or has no account to sign with. |
| [`primaryName.set`](/docs/reference/sdk/primary-name/set) | when the wallet is on another chain or has no account to sign with. |
| [`primaryName.signClaim`](/docs/reference/sdk/primary-name/sign-claim) | when the wallet is on another chain or has no account to sign with. |
| [`record.set`](/docs/reference/sdk/record/set) | when the wallet is on another chain or has no account to sign with. |
| [`registration.commit`](/docs/reference/sdk/registration/commit) | when the wallet is on another chain or has no account to sign with. |
| [`registration.register`](/docs/reference/sdk/registration/register) | when the wallet is on another chain or has no account to sign with. |
| [`registration.renew`](/docs/reference/sdk/registration/renew) | when the wallet is on another chain or has no account to sign with. |
| [`registry.attach`](/docs/reference/sdk/registry/attach) | when the wallet is on another chain or has no account to sign with. |
| [`registry.deploy`](/docs/reference/sdk/registry/deploy) | when the wallet is on another chain or has no account to sign with. |
| [`registry.setUri`](/docs/reference/sdk/registry/set-uri) | when the wallet is on another chain or has no account to sign with. |
| [`registry.upgrade`](/docs/reference/sdk/registry/upgrade) | when the wallet is on another chain or has no account to sign with. |
| [`resolver.create`](/docs/reference/sdk/resolver/create) | when the wallet is on another chain or has no account to sign with. |
| [`resolver.link`](/docs/reference/sdk/resolver/link) | when the wallet is on another chain or has no account to sign with. |
| [`resolver.set`](/docs/reference/sdk/resolver/set) | when the wallet is on another chain or has no account to sign with. |
| [`resolver.upgrade`](/docs/reference/sdk/resolver/upgrade) | when the wallet is on another chain or has no account to sign with. |
| [`role.grant`](/docs/reference/sdk/role/grant) | when the wallet is on another chain or has no account to sign with. |
| [`role.revoke`](/docs/reference/sdk/role/revoke) | when the wallet is on another chain or has no account to sign with. |
| [`subname.create`](/docs/reference/sdk/subname/create) | when the wallet is on another chain or has no account to sign with. |
| [`subname.remove`](/docs/reference/sdk/subname/remove) | when the wallet is on another chain or has no account to sign with. |
| [`subname.update`](/docs/reference/sdk/subname/update) | when the wallet is on another chain or has no account to sign with. |
| [`wrapper.setChildFuses`](/docs/reference/sdk/wrapper/set-child-fuses) | when the wallet is on another chain or has no account to sign with. |
| [`wrapper.setFuses`](/docs/reference/sdk/wrapper/set-fuses) | when the wallet is on another chain or has no account to sign with. |
| [`wrapper.unwrap`](/docs/reference/sdk/wrapper/unwrap) | when the wallet is on another chain or has no account to sign with. |
| [`wrapper.wrap`](/docs/reference/sdk/wrapper/wrap) | when the wallet is on another chain or has no account to sign with. |
Any write can fail with `WalletError`: it is part of `Errors.WriteError`.
## Catch it [#catch-it]
`Errors.hasCode("ACCOUNT_NOT_FOUND")` narrows to this error. See [Handle errors](/docs/sdk/handle-errors).
# CHAIN_MISMATCH
> For the complete documentation index, see [llms.txt](https://ensforge.com/llms.txt).
What CHAIN_MISMATCH means, why WalletError throws it, what to show users and how to fix it in ensforge. Also covers retry safety and the actions that throw it.
Source: https://ensforge.com/docs/reference/errors/CHAIN_MISMATCH
## What happened [#what-happened]
The wallet is on chain ?, expected ?.
## What to show users [#what-to-show-users]
| Title | Message | Action |
| --- | --- | --- |
| Wrong network | Your wallet is connected to a different network. | Switch networks in your wallet. |
## How to fix [#how-to-fix]
Switch the wallet's network, then retry.
## Retry safety [#retry-safety]
Retrying the same call fails the same way until the cause is fixed (`retryable: false`).
## Actions that throw it [#actions-that-throw-it]
| Action | When |
| --- | --- |
| [`approval.setDelegate`](/docs/reference/sdk/approval/set-delegate) | when the wallet is on another chain or has no account to sign with. |
| [`approval.setOperator`](/docs/reference/sdk/approval/set-operator) | when the wallet is on another chain or has no account to sign with. |
| [`approval.setToken`](/docs/reference/sdk/approval/set-token) | when the wallet is on another chain or has no account to sign with. |
| [`dns.claim`](/docs/reference/sdk/dns/claim) | when the wallet is on another chain or has no account to sign with. |
| [`dns.setRecords`](/docs/reference/sdk/dns/set-records) | when the wallet is on another chain or has no account to sign with. |
| [`migration.migrate`](/docs/reference/sdk/migration/migrate) | when the wallet is on another chain or has no account to sign with. |
| [`name.reclaim`](/docs/reference/sdk/name/reclaim) | when the wallet is on another chain or has no account to sign with. |
| [`name.setManager`](/docs/reference/sdk/name/set-manager) | when the wallet is on another chain or has no account to sign with. |
| [`name.setTtl`](/docs/reference/sdk/name/set-ttl) | when the wallet is on another chain or has no account to sign with. |
| [`name.transfer`](/docs/reference/sdk/name/transfer) | when the wallet is on another chain or has no account to sign with. |
| [`permission.setRecordAccess`](/docs/reference/sdk/permission/set-record-access) | when the wallet is on another chain or has no account to sign with. |
| [`plan.send`](/docs/reference/sdk/plan/send) | when the wallet is on another chain or has no account to sign with. |
| [`primaryName.set`](/docs/reference/sdk/primary-name/set) | when the wallet is on another chain or has no account to sign with. |
| [`primaryName.signClaim`](/docs/reference/sdk/primary-name/sign-claim) | when the wallet is on another chain or has no account to sign with. |
| [`record.set`](/docs/reference/sdk/record/set) | when the wallet is on another chain or has no account to sign with. |
| [`registration.commit`](/docs/reference/sdk/registration/commit) | when the wallet is on another chain or has no account to sign with. |
| [`registration.register`](/docs/reference/sdk/registration/register) | when the wallet is on another chain or has no account to sign with. |
| [`registration.renew`](/docs/reference/sdk/registration/renew) | when the wallet is on another chain or has no account to sign with. |
| [`registry.attach`](/docs/reference/sdk/registry/attach) | when the wallet is on another chain or has no account to sign with. |
| [`registry.deploy`](/docs/reference/sdk/registry/deploy) | when the wallet is on another chain or has no account to sign with. |
| [`registry.setUri`](/docs/reference/sdk/registry/set-uri) | when the wallet is on another chain or has no account to sign with. |
| [`registry.upgrade`](/docs/reference/sdk/registry/upgrade) | when the wallet is on another chain or has no account to sign with. |
| [`resolver.create`](/docs/reference/sdk/resolver/create) | when the wallet is on another chain or has no account to sign with. |
| [`resolver.link`](/docs/reference/sdk/resolver/link) | when the wallet is on another chain or has no account to sign with. |
| [`resolver.set`](/docs/reference/sdk/resolver/set) | when the wallet is on another chain or has no account to sign with. |
| [`resolver.upgrade`](/docs/reference/sdk/resolver/upgrade) | when the wallet is on another chain or has no account to sign with. |
| [`role.grant`](/docs/reference/sdk/role/grant) | when the wallet is on another chain or has no account to sign with. |
| [`role.revoke`](/docs/reference/sdk/role/revoke) | when the wallet is on another chain or has no account to sign with. |
| [`subname.create`](/docs/reference/sdk/subname/create) | when the wallet is on another chain or has no account to sign with. |
| [`subname.remove`](/docs/reference/sdk/subname/remove) | when the wallet is on another chain or has no account to sign with. |
| [`subname.update`](/docs/reference/sdk/subname/update) | when the wallet is on another chain or has no account to sign with. |
| [`wrapper.setChildFuses`](/docs/reference/sdk/wrapper/set-child-fuses) | when the wallet is on another chain or has no account to sign with. |
| [`wrapper.setFuses`](/docs/reference/sdk/wrapper/set-fuses) | when the wallet is on another chain or has no account to sign with. |
| [`wrapper.unwrap`](/docs/reference/sdk/wrapper/unwrap) | when the wallet is on another chain or has no account to sign with. |
| [`wrapper.wrap`](/docs/reference/sdk/wrapper/wrap) | when the wallet is on another chain or has no account to sign with. |
Any write can fail with `WalletError`: it is part of `Errors.WriteError`.
## Catch it [#catch-it]
`Errors.hasCode("CHAIN_MISMATCH")` narrows to this error. See [Handle errors](/docs/sdk/handle-errors).
# WalletError
> For the complete documentation index, see [llms.txt](https://ensforge.com/llms.txt).
What WalletError means, which codes it carries and how to catch it in ensforge. The wallet is not in a state to sign: wrong chain or no account.
Source: https://ensforge.com/docs/reference/errors/wallet-error
The wallet is not in a state to sign: wrong chain or no account.
Any write can fail with `WalletError`: it is part of `Errors.WriteError`.
## Fields [#fields]
| Field | Type | Description |
| --- | --- | --- |
| `expectedChainId` | `number` | |
| `actualChainId` | `number` | |
## Codes [#codes]
| Code | Meaning | Retryable |
| --- | --- | --- |
| [`CHAIN_MISMATCH`](/docs/reference/errors/CHAIN_MISMATCH) | The wallet is on chain ?, expected ?. | No |
| [`ACCOUNT_NOT_FOUND`](/docs/reference/errors/ACCOUNT_NOT_FOUND) | The wallet has no account to sign with. | No |
## Catch it [#catch-it]
`Effect.catchTag("WalletError", …)` or `error instanceof Errors.WalletError`. See [Handle errors](/docs/sdk/handle-errors).
# Errors
> For the complete documentation index, see [llms.txt](https://ensforge.com/llms.txt).
Look up all 103 error codes ensforge throws, grouped by 20 error classes, with what each means and how to fix it. Each code has its own page.
Source: https://ensforge.com/docs/reference/errors
Every error ensforge throws has a class (`_tag`) and a code. Each code has its own page, the one `error.docsUrl` points to. See [How errors work](/docs/sdk/errors-explained).
## Classes [#classes]
## Codes [#codes]
| Code | Class | Meaning |
| --- | --- | --- |
| [`COMMITMENT_TOO_NEW`](/docs/reference/errors/COMMITMENT_TOO_NEW) | [`CommitmentError`](/docs/reference/errors/commitment-error) | The registration commitment is not ready yet. |
| [`COMMITMENT_TOO_OLD`](/docs/reference/errors/COMMITMENT_TOO_OLD) | [`CommitmentError`](/docs/reference/errors/commitment-error) | The registration commitment has expired. |
| [`COMMITMENT_EXISTS`](/docs/reference/errors/COMMITMENT_EXISTS) | [`CommitmentError`](/docs/reference/errors/commitment-error) | An unexpired commitment with the same data already exists. |
| [`COMMITMENT_NOT_FOUND`](/docs/reference/errors/COMMITMENT_NOT_FOUND) | [`CommitmentError`](/docs/reference/errors/commitment-error) | No commitment was found for this registration. |
| [`UNKNOWN_CHAIN`](/docs/reference/errors/UNKNOWN_CHAIN) | [`ConfigError`](/docs/reference/errors/config-error) | ensforge has no ENS deployment for this chain. |
| [`INVALID_DEPLOYMENT`](/docs/reference/errors/INVALID_DEPLOYMENT) | [`ConfigError`](/docs/reference/errors/config-error) | The deployment profile is invalid. |
| [`CONTRACT_NOT_DEPLOYED`](/docs/reference/errors/CONTRACT_NOT_DEPLOYED) | [`ConfigError`](/docs/reference/errors/config-error) | No contract is deployed at the called address. |
| [`WALLET_NOT_CONFIGURED`](/docs/reference/errors/WALLET_NOT_CONFIGURED) | [`ConfigError`](/docs/reference/errors/config-error) | This action needs a wallet client with an account. |
| [`INDEXER_NOT_CONFIGURED`](/docs/reference/errors/INDEXER_NOT_CONFIGURED) | [`ConfigError`](/docs/reference/errors/config-error) | This action needs an indexer. |
| [`CCIP_READ_DISABLED`](/docs/reference/errors/CCIP_READ_DISABLED) | [`ConfigError`](/docs/reference/errors/config-error) | This name resolves off-chain, and CCIP-Read is disabled. |
| [`INVALID_ACTION_GROUP`](/docs/reference/errors/INVALID_ACTION_GROUP) | [`ConfigError`](/docs/reference/errors/config-error) | A decorator added an action group with a reserved name. |
| [`CHAIN_NOT_CONFIGURED`](/docs/reference/errors/CHAIN_NOT_CONFIGURED) | [`ConfigError`](/docs/reference/errors/config-error) | The client has no clients for chain ?. |
| [`CONTRACT_REVERTED`](/docs/reference/errors/CONTRACT_REVERTED) | [`ContractRevertError`](/docs/reference/errors/contract-revert-error) | The contract call reverted. |
| [`DNS_RECORD_MISSING`](/docs/reference/errors/DNS_RECORD_MISSING) | [`DnsError`](/docs/reference/errors/dns-error) | The `_ens` TXT record is missing. |
| [`DNSSEC_PROOF_FAILED`](/docs/reference/errors/DNSSEC_PROOF_FAILED) | [`DnsError`](/docs/reference/errors/dns-error) | The DNSSEC proof could not be built or verified. |
| [`PROOF_STALE`](/docs/reference/errors/PROOF_STALE) | [`DnsError`](/docs/reference/errors/dns-error) | The DNSSEC proof is older than the one on-chain. |
| [`TLD_NOT_PUBLIC`](/docs/reference/errors/TLD_NOT_PUBLIC) | [`DnsError`](/docs/reference/errors/dns-error) | The top-level domain is not a public suffix and cannot be imported. |
| [`GATEWAY_REQUEST_FAILED`](/docs/reference/errors/GATEWAY_REQUEST_FAILED) | [`GatewayError`](/docs/reference/errors/gateway-error) | The off-chain gateway request failed. |
| [`GATEWAY_RESPONSE_INVALID`](/docs/reference/errors/GATEWAY_RESPONSE_INVALID) | [`GatewayError`](/docs/reference/errors/gateway-error) | The off-chain gateway returned an invalid response. |
| [`OFFCHAIN_LOOKUP_INVALID`](/docs/reference/errors/OFFCHAIN_LOOKUP_INVALID) | [`GatewayError`](/docs/reference/errors/gateway-error) | The resolver requested an off-chain lookup from an unexpected sender. |
| [`INDEXER_UNAVAILABLE`](/docs/reference/errors/INDEXER_UNAVAILABLE) | [`IndexerError`](/docs/reference/errors/indexer-error) | The indexer is unavailable. |
| [`INDEXER_RATE_LIMITED`](/docs/reference/errors/INDEXER_RATE_LIMITED) | [`IndexerError`](/docs/reference/errors/indexer-error) | The indexer is rate limiting requests. |
| [`INDEXER_RESPONSE_INVALID`](/docs/reference/errors/INDEXER_RESPONSE_INVALID) | [`IndexerError`](/docs/reference/errors/indexer-error) | The indexer returned an unexpected response. |
| [`INDEXER_REQUEST_REJECTED`](/docs/reference/errors/INDEXER_REQUEST_REJECTED) | [`IndexerError`](/docs/reference/errors/indexer-error) | The indexer rejected the request. |
| [`INDEXER_BEHIND`](/docs/reference/errors/INDEXER_BEHIND) | [`IndexerError`](/docs/reference/errors/indexer-error) | The indexer is behind the chain. |
| [`INDEXER_UNSUPPORTED`](/docs/reference/errors/INDEXER_UNSUPPORTED) | [`IndexerError`](/docs/reference/errors/indexer-error) | The indexer does not support this query. |
| [`INSUFFICIENT_ETH`](/docs/reference/errors/INSUFFICIENT_ETH) | [`InsufficientFundsError`](/docs/reference/errors/insufficient-funds-error) | The account does not have enough ETH. |
| [`INSUFFICIENT_TOKEN_BALANCE`](/docs/reference/errors/INSUFFICIENT_TOKEN_BALANCE) | [`InsufficientFundsError`](/docs/reference/errors/insufficient-funds-error) | The account does not have enough of the payment token. |
| [`UNEXPECTED`](/docs/reference/errors/UNEXPECTED) | [`InternalError`](/docs/reference/errors/internal-error) | An unexpected error occurred. |
| [`INVALID_NAME`](/docs/reference/errors/INVALID_NAME) | [`InvalidInputError`](/docs/reference/errors/invalid-input-error) | undefined is not a valid ENS name. |
| [`INVALID_ADDRESS`](/docs/reference/errors/INVALID_ADDRESS) | [`InvalidInputError`](/docs/reference/errors/invalid-input-error) | undefined is not a valid address. |
| [`INVALID_COIN_TYPE`](/docs/reference/errors/INVALID_COIN_TYPE) | [`InvalidInputError`](/docs/reference/errors/invalid-input-error) | undefined is not a known coin type. |
| [`INVALID_CONTENT_HASH`](/docs/reference/errors/INVALID_CONTENT_HASH) | [`InvalidInputError`](/docs/reference/errors/invalid-input-error) | undefined is not a valid content hash. |
| [`INVALID_RECORD_VALUE`](/docs/reference/errors/INVALID_RECORD_VALUE) | [`InvalidInputError`](/docs/reference/errors/invalid-input-error) | undefined is not a valid record value. |
| [`INVALID_DURATION`](/docs/reference/errors/INVALID_DURATION) | [`InvalidInputError`](/docs/reference/errors/invalid-input-error) | undefined is not a valid duration. |
| [`DURATION_TOO_SHORT`](/docs/reference/errors/DURATION_TOO_SHORT) | [`InvalidInputError`](/docs/reference/errors/invalid-input-error) | The duration is shorter than the registrar's minimum. |
| [`INVALID_EXPIRY`](/docs/reference/errors/INVALID_EXPIRY) | [`InvalidInputError`](/docs/reference/errors/invalid-input-error) | The expiry cannot be in the past or earlier than the current expiry. |
| [`INVALID_ROLES`](/docs/reference/errors/INVALID_ROLES) | [`InvalidInputError`](/docs/reference/errors/invalid-input-error) | undefined is not a valid role bitmap. |
| [`SALT_TAKEN`](/docs/reference/errors/SALT_TAKEN) | [`InvalidInputError`](/docs/reference/errors/invalid-input-error) | A contract was already deployed with this salt. |
| [`NOT_ELIGIBLE`](/docs/reference/errors/NOT_ELIGIBLE) | [`MigrationError`](/docs/reference/errors/migration-error) | The name cannot be migrated to ENSv2 yet. |
| [`ALREADY_MIGRATED`](/docs/reference/errors/ALREADY_MIGRATED) | [`MigrationError`](/docs/reference/errors/migration-error) | The name is already on ENSv2. |
| [`NAME_NOT_LOCKED`](/docs/reference/errors/NAME_NOT_LOCKED) | [`MigrationError`](/docs/reference/errors/migration-error) | The wrapped name is not locked, so it cannot use the locked migration route. |
| [`RECORDS_UNKNOWN`](/docs/reference/errors/RECORDS_UNKNOWN) | [`MigrationError`](/docs/reference/errors/migration-error) | The name's records are not known, so they cannot be copied to its new resolver. |
| [`VERIFICATION_FAILED`](/docs/reference/errors/VERIFICATION_FAILED) | [`MigrationError`](/docs/reference/errors/migration-error) | The migration was sent, but the name's ENSv2 state differs from the plan. |
| [`NAME_NOT_AVAILABLE`](/docs/reference/errors/NAME_NOT_AVAILABLE) | [`NameStateError`](/docs/reference/errors/name-state-error) | The name is already registered. |
| [`NAME_NOT_REGISTERED`](/docs/reference/errors/NAME_NOT_REGISTERED) | [`NameStateError`](/docs/reference/errors/name-state-error) | The name is not registered. |
| [`NAME_RESERVED`](/docs/reference/errors/NAME_RESERVED) | [`NameStateError`](/docs/reference/errors/name-state-error) | The name is reserved. |
| [`NAME_EXPIRED`](/docs/reference/errors/NAME_EXPIRED) | [`NameStateError`](/docs/reference/errors/name-state-error) | The name has expired. |
| [`NAME_NOT_RENEWABLE`](/docs/reference/errors/NAME_NOT_RENEWABLE) | [`NameStateError`](/docs/reference/errors/name-state-error) | The name cannot be renewed. |
| [`NAME_LOCKED`](/docs/reference/errors/NAME_LOCKED) | [`NameStateError`](/docs/reference/errors/name-state-error) | The name is locked. |
| [`NAME_NOT_WRAPPED`](/docs/reference/errors/NAME_NOT_WRAPPED) | [`NameStateError`](/docs/reference/errors/name-state-error) | The name is not wrapped in the NameWrapper. |
| [`NAME_WRAPPED`](/docs/reference/errors/NAME_WRAPPED) | [`NameStateError`](/docs/reference/errors/name-state-error) | The name is already wrapped in the NameWrapper. |
| [`NAME_UNREACHABLE`](/docs/reference/errors/NAME_UNREACHABLE) | [`NameStateError`](/docs/reference/errors/name-state-error) | ENSv2 resolution no longer reaches this ENSv1 name. |
| [`NAME_REQUIRES_MIGRATION`](/docs/reference/errors/NAME_REQUIRES_MIGRATION) | [`NameStateError`](/docs/reference/errors/name-state-error) | The name must be migrated to ENSv2 first. |
| [`PARENT_NOT_MIGRATED`](/docs/reference/errors/PARENT_NOT_MIGRATED) | [`NameStateError`](/docs/reference/errors/name-state-error) | The parent name has not been migrated to ENSv2. |
| [`REGISTRY_NOT_EMANCIPATED`](/docs/reference/errors/REGISTRY_NOT_EMANCIPATED) | [`NameStateError`](/docs/reference/errors/name-state-error) | The registry is not emancipated, so this transfer is unsafe. |
| [`RPC_REQUEST_FAILED`](/docs/reference/errors/RPC_REQUEST_FAILED) | [`NetworkError`](/docs/reference/errors/network-error) | The RPC request failed. |
| [`RPC_TIMEOUT`](/docs/reference/errors/RPC_TIMEOUT) | [`NetworkError`](/docs/reference/errors/network-error) | The RPC request timed out. |
| [`RATE_LIMITED`](/docs/reference/errors/RATE_LIMITED) | [`NetworkError`](/docs/reference/errors/network-error) | The RPC provider is rate limiting requests. |
| [`LOG_RANGE_TOO_LARGE`](/docs/reference/errors/LOG_RANGE_TOO_LARGE) | [`NetworkError`](/docs/reference/errors/network-error) | The RPC provider's eth_getLogs limits make this block range too expensive. |
| [`RESOLVER_NOT_FOUND`](/docs/reference/errors/RESOLVER_NOT_FOUND) | [`NotFoundError`](/docs/reference/errors/not-found-error) | The name has no resolver. |
| [`RECORD_NOT_FOUND`](/docs/reference/errors/RECORD_NOT_FOUND) | [`NotFoundError`](/docs/reference/errors/not-found-error) | The record is not set. |
| [`PRIMARY_NAME_NOT_SET`](/docs/reference/errors/PRIMARY_NAME_NOT_SET) | [`NotFoundError`](/docs/reference/errors/not-found-error) | The address has no primary name. |
| [`PRIMARY_NAME_MISMATCH`](/docs/reference/errors/PRIMARY_NAME_MISMATCH) | [`NotFoundError`](/docs/reference/errors/not-found-error) | The primary name does not resolve back to this address. |
| [`REGISTRY_NOT_FOUND`](/docs/reference/errors/REGISTRY_NOT_FOUND) | [`NotFoundError`](/docs/reference/errors/not-found-error) | No registry was found for this name. |
| [`PLAN_NOT_FOUND`](/docs/reference/errors/PLAN_NOT_FOUND) | [`NotFoundError`](/docs/reference/errors/not-found-error) | No saved plan was found with this id. |
| [`INDEXER_NOT_FOUND`](/docs/reference/errors/INDEXER_NOT_FOUND) | [`NotFoundError`](/docs/reference/errors/not-found-error) | The indexer has no record of this resource. |
| [`PLAN_STALE`](/docs/reference/errors/PLAN_STALE) | [`PlanError`](/docs/reference/errors/plan-error) | The plan no longer matches on-chain state. |
| [`PLAN_CHAIN_MISMATCH`](/docs/reference/errors/PLAN_CHAIN_MISMATCH) | [`PlanError`](/docs/reference/errors/plan-error) | The plan was prepared for another chain. |
| [`PLAN_ACCOUNT_MISMATCH`](/docs/reference/errors/PLAN_ACCOUNT_MISMATCH) | [`PlanError`](/docs/reference/errors/plan-error) | The plan was prepared for another account. |
| [`PLAN_INVALID`](/docs/reference/errors/PLAN_INVALID) | [`PlanError`](/docs/reference/errors/plan-error) | The text is not a serialized ensforge plan. |
| [`PLAN_ROUTE_REQUIRED`](/docs/reference/errors/PLAN_ROUTE_REQUIRED) | [`PlanError`](/docs/reference/errors/plan-error) | Part of this plan was sent through a route (`via`), which resuming needs again. |
| [`TRANSACTION_REVERTED`](/docs/reference/errors/TRANSACTION_REVERTED) | [`TransactionError`](/docs/reference/errors/transaction-error) | The transaction reverted on-chain. |
| [`RECEIPT_TIMEOUT`](/docs/reference/errors/RECEIPT_TIMEOUT) | [`TransactionError`](/docs/reference/errors/transaction-error) | Timed out waiting for the transaction receipt. |
| [`NONCE_CONFLICT`](/docs/reference/errors/NONCE_CONFLICT) | [`TransactionError`](/docs/reference/errors/transaction-error) | The transaction nonce conflicts with another transaction. |
| [`NOT_OWNER`](/docs/reference/errors/NOT_OWNER) | [`UnauthorizedError`](/docs/reference/errors/unauthorized-error) | The account does not own this name. |
| [`MISSING_ROLES`](/docs/reference/errors/MISSING_ROLES) | [`UnauthorizedError`](/docs/reference/errors/unauthorized-error) | The account is missing the roles this change needs. |
| [`CANNOT_GRANT_ROLES`](/docs/reference/errors/CANNOT_GRANT_ROLES) | [`UnauthorizedError`](/docs/reference/errors/unauthorized-error) | The account cannot grant or revoke these roles. |
| [`NOT_APPROVED`](/docs/reference/errors/NOT_APPROVED) | [`UnauthorizedError`](/docs/reference/errors/unauthorized-error) | The account is not approved to manage this name. |
| [`FUSE_BURNED`](/docs/reference/errors/FUSE_BURNED) | [`UnauthorizedError`](/docs/reference/errors/unauthorized-error) | A burned NameWrapper fuse forbids this change. |
| [`TRANSFER_DISALLOWED`](/docs/reference/errors/TRANSFER_DISALLOWED) | [`UnauthorizedError`](/docs/reference/errors/unauthorized-error) | This name cannot be transferred right now. |
| [`SIGNATURE_INVALID`](/docs/reference/errors/SIGNATURE_INVALID) | [`UnauthorizedError`](/docs/reference/errors/unauthorized-error) | The signature does not authorize this change. |
| [`SIGNATURE_EXPIRED`](/docs/reference/errors/SIGNATURE_EXPIRED) | [`UnauthorizedError`](/docs/reference/errors/unauthorized-error) | The signature has expired. |
| [`UNSUPPORTED_PROTOCOL`](/docs/reference/errors/UNSUPPORTED_PROTOCOL) | [`UnsupportedError`](/docs/reference/errors/unsupported-error) | This operation is not supported for this names. |
| [`UNSUPPORTED_ON_DEPLOYMENT`](/docs/reference/errors/UNSUPPORTED_ON_DEPLOYMENT) | [`UnsupportedError`](/docs/reference/errors/unsupported-error) | This feature is not available on this deployment. |
| [`RESOLVER_PROFILE_UNSUPPORTED`](/docs/reference/errors/RESOLVER_PROFILE_UNSUPPORTED) | [`UnsupportedError`](/docs/reference/errors/unsupported-error) | The resolver does not support this record type. |
| [`PAYMENT_TOKEN_UNSUPPORTED`](/docs/reference/errors/PAYMENT_TOKEN_UNSUPPORTED) | [`UnsupportedError`](/docs/reference/errors/unsupported-error) | The registrar does not accept this payment token. |
| [`UPGRADE_NOT_APPROVED`](/docs/reference/errors/UPGRADE_NOT_APPROVED) | [`UnsupportedError`](/docs/reference/errors/unsupported-error) | The upgrade target is not an approved implementation. |
| [`WALLET_BATCH_UNSUPPORTED`](/docs/reference/errors/WALLET_BATCH_UNSUPPORTED) | [`UnsupportedError`](/docs/reference/errors/unsupported-error) | The wallet cannot send calls as one batch. |
| [`USER_REJECTED`](/docs/reference/errors/USER_REJECTED) | [`UserRejectedError`](/docs/reference/errors/user-rejected-error) | The user rejected the request. |
| [`CHAIN_MISMATCH`](/docs/reference/errors/CHAIN_MISMATCH) | [`WalletError`](/docs/reference/errors/wallet-error) | The wallet is on chain ?, expected ?. |
| [`ACCOUNT_NOT_FOUND`](/docs/reference/errors/ACCOUNT_NOT_FOUND) | [`WalletError`](/docs/reference/errors/wallet-error) | The wallet has no account to sign with. |
| [`HCA_UNAVAILABLE`](/docs/reference/errors/HCA_UNAVAILABLE) | [`HcaError`](/docs/reference/errors/hca-error) | This chain has no ENS HCA deployment. |
| [`HCA_NOT_VERIFIED`](/docs/reference/errors/HCA_NOT_VERIFIED) | [`HcaError`](/docs/reference/errors/hca-error) | The account is not a verified ENS HCA of this owner. |
| [`HCA_EXECUTOR_UNSUPPORTED`](/docs/reference/errors/HCA_EXECUTOR_UNSUPPORTED) | [`HcaError`](/docs/reference/errors/hca-error) | No configured executor can run this HCA operation. |
| [`HCA_ACTION_NOT_ALLOWED`](/docs/reference/errors/HCA_ACTION_NOT_ALLOWED) | [`HcaError`](/docs/reference/errors/hca-error) | The HCA session policy does not allow this call. |
| [`HCA_SESSION_INVALID`](/docs/reference/errors/HCA_SESSION_INVALID) | [`HcaError`](/docs/reference/errors/hca-error) | The HCA session is expired, revoked or for another resolver. |
| [`HCA_BUNDLER_REJECTED`](/docs/reference/errors/HCA_BUNDLER_REJECTED) | [`HcaError`](/docs/reference/errors/hca-error) | The bundler rejected the HCA UserOperation. |
| [`HCA_PAYMASTER_REJECTED`](/docs/reference/errors/HCA_PAYMASTER_REJECTED) | [`HcaError`](/docs/reference/errors/hca-error) | The paymaster refused to sponsor the HCA UserOperation. |
| [`HCA_EXECUTION_FAILED`](/docs/reference/errors/HCA_EXECUTION_FAILED) | [`HcaError`](/docs/reference/errors/hca-error) | The HCA execution failed. |
| [`HCA_EXECUTION_TIMEOUT`](/docs/reference/errors/HCA_EXECUTION_TIMEOUT) | [`HcaError`](/docs/reference/errors/hca-error) | The HCA execution was not included in time. |
| [`HCA_UPGRADE_NOT_ALLOWED`](/docs/reference/errors/HCA_UPGRADE_NOT_ALLOWED) | [`HcaError`](/docs/reference/errors/hca-error) | The upgrade set or the new implementation's `canUpgradeFrom` check does not allow this HCA upgrade. |
| [`HCA_SDK_UNSUPPORTED`](/docs/reference/errors/HCA_SDK_UNSUPPORTED) | [`HcaError`](/docs/reference/errors/hca-error) | The Rhinestone SDK does not support the standalone ENS HCA. |
# Glossary
> For the complete documentation index, see [llms.txt](https://ensforge.com/llms.txt).
Look up the ENS and ensforge terms used across these docs, from name and resolver to plan and role, each explained in plain words.
Source: https://ensforge.com/docs/reference/glossary
Every term used in these docs, in alphabetical order. Each has its own anchor, so pages link here
the first time they use it.
## Avatar [#avatar]
A profile picture for a name, stored as the `avatar` text record (ENSIP-12). The record holds a
link: HTTPS, IPFS, Arweave, or an NFT the name's address owns. `record.getAvatar` turns it into a
URL a browser can load.
## Batch [#batch]
Several reads run together in as few requests as possible. `ens.batch` runs the `.request(...)`
forms of read actions; reads made at the same time are also grouped into multicall requests
automatically. Not to be confused with a [bundle](#bundle), which groups writes.
## Bundle [#bundle]
Several contract calls a wallet sends as one atomic unit (EIP-5792 `wallet_sendCalls`). ensforge
bundles a [plan](#plan)'s calls when the wallet supports it.
## CCIP-Read [#ccip-read]
The protocol that lets a resolver answer from a server instead of the chain (EIP-3668). The resolver
replies with a pointer to a [gateway](#gateway); ensforge fetches the answer there and has the
resolver check it. Names served this way are [off-chain names](#off-chain-name).
## Commitment [#commitment]
The first half of registering a `.eth` name. The registrant first submits a hash of the
registration (the commitment), waits at least a minute, then registers. This stops others from
seeing the name in a pending transaction and registering it first.
## Emancipated [#emancipated]
A name its parent can no longer take back or change. On ENSv1, a wrapped name is emancipated when
its [PCC](#pcc) fuse is burned. On ENSv2, a registry is emancipated when the owners of its parent
can no longer take its names back.
## ENSv1 [#ensv1]
The original ENS contracts: one registry for every name, the `.eth` registrar,
public resolvers and the [Name Wrapper](#name-wrapper). See
[ENS versions under the hood](/docs/sdk/ens-versions).
## ENSv2 [#ensv2]
The successor to ENSv1: a tree of [registries](#registry), names held as ERC-1155 tokens, and
[roles](#role) for fine-grained permissions. Names move to it by [migration](#migration). ensforge
reads and writes both versions with the same actions.
## .eth name [#eth-name]
A second-level name under `eth`, such as `nick.eth`. It is bought from the [registrar](#registrar)
for a period of time and renewed before its [expiry](#expiry). Subnames of a `.eth` name, such as
`pay.nick.eth`, are not `.eth` names in this sense: their parent creates them.
## Executor [#executor]
How an [HCA](#hca) gets its calls on-chain: the owner's own wallet, an ERC-4337 bundler, or
Rhinestone. See [HCA](/docs/hca).
## Expiry [#expiry]
When a name's registration ends. After it, a `.eth` name enters its [grace period](#grace-period).
Subnames can have their own expiry, or never expire.
## Fuse [#fuse]
A permanent switch on a name wrapped in the [Name Wrapper](#name-wrapper). Burning a fuse removes a
permission, such as `cannotTransfer` or `cannotSetResolver`, until the name expires. See
[Lock permissions with fuses](/docs/sdk/fuses).
## Gateway [#gateway]
A server that holds records for an [off-chain name](#off-chain-name) and answers
[CCIP-Read](#ccip-read) requests. Separately, a storage gateway (such as `https://ipfs.io`) turns
IPFS or Arweave links into web URLs for avatars and websites.
## Grace period [#grace-period]
The time after a `.eth` name's [expiry](#expiry) during which it can still be renewed and nobody
else can register it. `registration.getParameters` returns its length.
## HCA [#hca]
An ENS smart account (Hosted Contract Account) that can send writes for its owner, in one atomic
execution, with sessions and sponsored gas. Provided by `@ensforge/hca`, which is experimental.
## Indexer [#indexer]
A service that reads every ENS event and keeps a database of names, so it can answer questions the
chain cannot: lists, search and history. See
[Name lists and indexers](/docs/sdk/name-lists-and-indexers).
## Label [#label]
One part of a name between dots. `pay.nick.eth` has the labels `pay`, `nick` and `eth`.
## Labelhash [#labelhash]
The keccak-256 hash of one [label](#label). Contracts store labels as hashes; a label whose text is
unknown is written as `[` plus its hash plus `]`. `Name.labelhash` computes it.
## Locked [#locked]
A wrapped ENSv1 name whose `cannotUnwrap` [fuse](#fuse) is burned: it can never leave the
[Name Wrapper](#name-wrapper) before it expires, so its other fuses hold. Locked and unlocked names
move to ENSv2 in different ways.
## Manager [#manager]
On ENSv1, the account that controls a name in the registry: its resolver, records and subnames. For
an unwrapped `.eth` name it can differ from the [registrant](#registrant), who can take management
back. ENSv2 names have no manager; they use [roles](#role).
## Migration [#migration]
Moving a name from [ENSv1](#ensv1) to [ENSv2](#ensv2), with its records and subnames.
`migration.get` says whether and how a name can move. See
[Move a name to ENSv2](/docs/sdk/move-a-name-to-ensv2).
## Name [#name]
A human-readable identifier made of [labels](#label) separated by dots, such as `nick.eth`. ENS
maps names to [records](#record). See [Names and records](/docs/sdk/names-and-records).
## Name Wrapper [#name-wrapper]
An ENSv1 contract that holds a name as an ERC-1155 token and adds [fuses](#fuse). Such names are
called wrapped. See [What wrapped names are](/docs/sdk/wrapped-names).
## Namehash [#namehash]
The hash that identifies a name in contracts, also called its **node** (EIP-137). It is computed
from the [labelhashes](#labelhash) of all labels, so it never reveals the name's text.
`Name.namehash` computes it from a [normalised](#normalisation) name.
## Normalisation [#normalisation]
Turning a name into its one canonical form before hashing it (ENSIP-15): lower case, standard
characters, and rejection of names that could be confused with others. `Nick.ETH` normalises to
`nick.eth`. ensforge normalises every name you pass; `Name.normalize` does it on its own.
## Off-chain name [#off-chain-name]
A name whose records are not stored on Ethereum but served by a [gateway](#gateway) through
[CCIP-Read](#ccip-read). Basenames and many subnames given out by apps are served this way.
ensforge reads them like any other name.
## Owner [#owner]
The account that holds a name and has final control over it: transfer, resolver, subnames and
records. `name.get` returns it as `owner`.
## Paymaster [#paymaster]
A service that pays gas for a user. ensforge passes one to EIP-5792 wallets with the `paymaster`
write option, and `@ensforge/hca` supports paymasters through its bundler executors.
## PCC [#pcc]
Short for the `parentCannotControl` [fuse](#fuse). Once burned, the parent of a wrapped name can no
longer change or take back that name: the name is [emancipated](#emancipated).
## Permission [#permission]
Whether an account may perform an operation on a name, whatever grants it: ownership, an approval,
a [role](#role) or a fuse. `permission.get` and `permission.check` answer it. See
[Who can change a name](/docs/sdk/who-can-change-a-name).
## Plan [#plan]
A write, fully worked out but not sent: its [steps](#step), the calls of each, and what the account
needs first. Every write action has `.prepare` to build one. See
[How writes work](/docs/sdk/writing-to-ens).
## Premium [#premium]
An extra price on a `.eth` name that has recently left its [grace period](#grace-period). It starts
high and falls over time, so a released name does not go to whoever sends a transaction first.
## Primary name [#primary-name]
The one name an address chooses to be known by, stored in its **reverse record** (ENSIP-19). A
primary name counts only when the name's address record points back to the same address. Each
chain can have its own. See [Get the name for an address](/docs/sdk/get-a-primary-name).
## Record [#record]
A piece of data a name points to, stored by its [resolver](#resolver):
- **Text**: a string under a key such as `url` or `com.github`.
- **Address**: an address for one chain or coin, chosen by its **coin type** (ENSIP-9, ENSIP-11).
Ethereum is coin type 60.
- **Content hash**: a website or file on IPFS, Swarm, Arweave and similar (ENSIP-7).
- **ABI**: a contract ABI (ENSIP-4).
- **Pubkey**: a SECP256k1 public key.
- **Data**: raw bytes under a key (ENSIP-24).
## Registrant [#registrant]
On ENSv1, the holder of a `.eth` registration token. The registrant can transfer the registration
and reset the [manager](#manager).
## Registrar [#registrar]
The contract that sells [.eth names](#eth-name): it quotes prices, takes [commitments](#commitment),
registers and renews. The contract you call to register is also called the registrar
**controller**.
## Registry [#registry]
The contract that records who holds each name and which [resolver](#resolver) serves it. ENSv1 has
one registry for every name. ENSv2 has a tree of registries: the root registry, the `.eth`
registry, and a **subregistry** for any name that has subnames.
## Resolver [#resolver]
The contract that stores a name's [records](#record) and answers for them. Kinds you will meet:
- **Public resolver**: shared by many names, run by ENS.
- **PermissionedResolver**: an ENSv2 resolver for one name or a few, with [roles](#role) per
record.
- **Wildcard or extended resolver** (ENSIP-10): answers for names below the one it is set on, and
can answer through [CCIP-Read](#ccip-read).
- **Inherited resolver**: the resolver that serves a name with none of its own, from a parent.
`name.get` returns it as `inheritedResolver`.
## Role [#role]
A named permission in [ENSv2](#ensv2), such as `setResolver`, `setText` or `renew`, granted to an
account on one name or on every name of a registry or resolver. Each role has an admin role that may
grant and revoke it. See [Roles and permissions](/docs/sdk/roles-and-permissions).
## Route [#route]
Another way to send a write than the signer's own transactions, passed as `via`. `hca()` from
`@ensforge/hca` routes writes through an [HCA](#hca).
## Step [#step]
One stage of a [plan](#plan): a group of calls sent together, sometimes after a wait on chain time.
Registration has several steps; most writes have one.
## Subname [#subname]
A name under another name, such as `pay.nick.eth` under `nick.eth`. The parent's owner creates it
and decides who holds it.
## TLD [#tld]
The top-level domain: the last label of a name, such as `eth` or `com`.
# 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>` | | 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)` | 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)` | Where a sent execution is. |
| `quote` (optional) | `((request: ExecutionRequest, context: Write.Via.Context) => Promise)` | 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; /** Adds ETH to an HCA's ERC-4337 EntryPoint deposit. Resolves once the receipt is in. */ readonly addDepositSync: Bound; /** Asks the owner to approve a session key for their HCA, with one signature and no transaction. */ readonly authorizeSession: Bound; /** Checks calls against the HCA session policy before anything is signed. */ readonly checkSessionCalls: Bound; /** Deploys the signer's HCA through the ENS factory. Resolves once the transaction is submitted. */ readonly deploy: BoundWrite; /** Deploys the signer's HCA through the ENS factory. Resolves once the receipt is in. */ readonly deploySync: Bound; /** Runs calls from the signer's HCA as one atomic execution. Resolves once the transaction is submitted. */ readonly execute: BoundWrite; /** Runs calls from the signer's HCA as one atomic execution. Resolves once the receipt is in. */ readonly executeSync: Bound; /** Reads an ENS HCA (Hosted Contract Account): its address, owner, implementation, session nonce and verification problems. */ readonly get: Bound; /** Reads an HCA's ERC-4337 EntryPoint deposit, which pays for its UserOperations without a paymaster. */ readonly getDeposit: Bound; /** Checks whether a stored HCA session can still be used. */ readonly getSession: Bound; /** 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; /** Computes the address of an owner's ENS HCA, deployed or not. */ readonly predictAddress: Bound; /** Invalidates every session approval of the signer's HCA. Resolves once the transaction is submitted. */ readonly revokeSessions: BoundWrite; /** Invalidates every session approval of the signer's HCA. Resolves once the receipt is in. */ readonly revokeSessionsSync: Bound; /** 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; /** 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; /** Checks that an address is a usable ENS HCA of its owner, and returns it. */ readonly verify: Bound; /** Withdraws ETH from the signer's HCA EntryPoint deposit. Resolves once the transaction is submitted. */ readonly withdrawDeposit: BoundWrite; /** Withdraws ETH from the signer's HCA EntryPoint deposit. Resolves once the receipt is in. */ readonly withdrawDepositSync: Bound; } `` | |
### `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; /** Grants root roles on the HCA upgrade set (role admins only). Resolves once the transaction is submitted. */ readonly grantUpgradeSetRoles: BoundWrite; /** Grants root roles on the HCA upgrade set (role admins only). Resolves once the receipt is in. */ readonly grantUpgradeSetRolesSync: Bound; /** Renounces ownership of the HCA factory, freezing its implementation approvals (factory owner only). Resolves once the transaction is submitted. */ readonly renounceGovernance: BoundWrite; /** Renounces ownership of the HCA factory, freezing its implementation approvals (factory owner only). Resolves once the receipt is in. */ readonly renounceGovernanceSync: Bound; /** Revokes root roles on the HCA upgrade set (role admins only). Resolves once the transaction is submitted. */ readonly revokeUpgradeSetRoles: BoundWrite; /** Revokes root roles on the HCA upgrade set (role admins only). Resolves once the receipt is in. */ readonly revokeUpgradeSetRolesSync: Bound; /** Approves or revokes an implementation for new HCA deployments (factory owner only). Resolves once the transaction is submitted. */ readonly setDeploymentApproval: BoundWrite; /** Approves or revokes an implementation for new HCA deployments (factory owner only). Resolves once the receipt is in. */ readonly setDeploymentApprovalSync: Bound; /** Approves or revokes an implementation in the HCA upgrade set (role holders only). Resolves once the transaction is submitted. */ readonly setUpgradeApproval: BoundWrite; /** Approves or revokes an implementation in the HCA upgrade set (role holders only). Resolves once the receipt is in. */ readonly setUpgradeApprovalSync: Bound; /** Transfers ownership of the HCA factory (factory owner only). Resolves once the transaction is submitted. */ readonly transferGovernance: BoundWrite; /** Transfers ownership of the HCA factory (factory owner only). Resolves once the receipt is in. */ readonly transferGovernanceSync: Bound; }` | |
### `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` | |
| `signTransaction` | `(prepared: unknown) => Promise` | |
| `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` | |
| `getIntentStatus` | `(id: bigint) => Promise<{ readonly status: string; readonly fill?: { readonly hash?: Hex \| undefined } \| undefined; }>` | |
# hca.addDeposit
> For the complete documentation index, see [llms.txt](https://ensforge.com/llms.txt).
Adds ETH to an HCA's ERC-4337 EntryPoint deposit. Parameters, return value, errors and examples for hca.addDeposit in @ensforge/hca.
Source: https://ensforge.com/docs/reference/hca/hca/add-deposit
`@ensforge/hca` is experimental: its API can change in a minor release.
Adds ETH to an HCA's ERC-4337 EntryPoint deposit. Resolves once the transaction is submitted.
## When to use [#when-to-use]
Use when `bundler()` executions are paid by the HCA itself rather than a paymaster.
## Signature [#signature]
```ts
function addDeposit(
client: Like,
options: addDeposit.Options & Write.Options,
): Promise
```
Call it as `ens.hca.addDeposit(options)` on a client, or `Actions.hca.addDeposit(client, options)`.
## Parameters [#parameters]
| Option | Type | Default | Description |
| --- | --- | --- | --- |
| `amount` (required) | `bigint` | | Wei to deposit. |
| `address` | `string` | | The HCA's address. @default the signer's HCA |
Also takes the [write options](/docs/reference/sdk/client#write-options).
## Returns [#returns]
Resolves to `Write.Result`. Submitted transaction hashes and the plan that produced them.
| Field | Type | Description |
| --- | --- | --- |
| `hash` | `Hex` | Hash of the last transaction. |
| `hashes` | `readonly Hex[]` | Every submitted transaction, in order. |
| `id` | `string` | EIP-5792 bundle id when the calls were sent as one batch. |
| `plan` | `Plan` | The plan the write executed: its steps, in order, as they were submitted. |
## Errors [#errors]
| Error | Codes | When |
| --- | --- | --- |
| [`InvalidInputError`](/docs/reference/errors/invalid-input-error) | [`INVALID_ADDRESS`](/docs/reference/errors/INVALID_ADDRESS) | an invalid address. |
| [`HcaError`](/docs/reference/errors/hca-error) | [`HCA_UNAVAILABLE`](/docs/reference/errors/HCA_UNAVAILABLE) | on chains without an HCA deployment. |
It can also fail with the errors every write can (`Errors.WriteError`: the common errors plus `InsufficientFundsError`, `TransactionError`, `UnsupportedError`, `UserRejectedError`, `WalletError`).
See [How errors work](/docs/sdk/errors-explained).
## Examples [#examples]
```ts title="Funding the deposit"
import { parseEther } from "viem"
const { hash } = await ens.hca.addDeposit({ amount: parseEther("0.01") })
```
```ts title="Funding the deposit with a standalone call"
import { parseEther } from "viem"
import { Actions } from "@ensforge/hca"
await Actions.hca.addDeposit(ens, { amount: parseEther("0.01") })
```
```ts title="Funding the deposit in an Effect program"
import { parseEther } from "viem"
import { Actions } from "@ensforge/hca/effect"
yield* Actions.hca.addDeposit(ens, { amount: parseEther("0.01") })
```
## Plan methods [#plan-methods]
Each method takes the same options as `hca.addDeposit` and sends nothing. See [Preview before sending](/docs/sdk/preview-before-sending).
| Method | Description |
| --- | --- |
| `hca.addDeposit.prepare(options)` | Builds the plan without sending anything. |
| `hca.addDeposit.simulate(options)` | Simulates the plan with `eth_call`, reporting each step. |
| `hca.addDeposit.estimateGas(options)` | Estimates the gas and ETH the plan needs. |
## Wait for the receipt with `addDepositSync` [#wait-for-the-receipt-with-adddepositsync]
Adds ETH to an HCA's ERC-4337 EntryPoint deposit. Resolves once the receipt is in.
Use when the next step depends on the change being on-chain.
`hca.addDepositSync` takes the same options plus [`confirmations` and `timeout`](/docs/reference/sdk/client#sync-options).
Resolves to `Write.SyncResult`. Receipts plus the submitted hashes and plan.
```ts title="Funding the deposit and waiting"
import { parseEther } from "viem"
const { receipt } = await ens.hca.addDepositSync({ amount: parseEther("0.01") })
```
```ts title="Funding the deposit with a standalone call and waiting"
import { parseEther } from "viem"
import { Actions } from "@ensforge/hca"
await Actions.hca.addDepositSync(ens, { amount: parseEther("0.01") })
```
```ts title="Funding the deposit in an Effect program and waiting"
import { parseEther } from "viem"
import { Actions } from "@ensforge/hca/effect"
yield* Actions.hca.addDepositSync(ens, { amount: parseEther("0.01") })
```
# hca.authorizeSession
> For the complete documentation index, see [llms.txt](https://ensforge.com/llms.txt).
Asks the owner to approve a session key for their HCA, with one signature and no transaction. Options, result, errors and examples for hca.authorizeSession.
Source: https://ensforge.com/docs/reference/hca/hca/authorize-session
`@ensforge/hca` is experimental: its API can change in a minor release.
Asks the owner to approve a session key for their HCA, with one signature and no transaction.
## When to use [#when-to-use]
Use to enable prompt-free registration and record updates through Rhinestone (`hca(\{ session
\})`).
## Details [#details]
- The session may register names to the owner, deploy and edit `resolver` (one resolver per
session), set the owner's primary name and approve registration payments.
- It stays valid until `validUntil` or until the owner calls `revokeSessions`. Store the
returned session; it holds no secret.
- Refund ceilings default to the ENS app's: $20k per ETH, 500k gas of overhead, 100 USDC per
intent.
## Signature [#signature]
```ts
function authorizeSession(
client: Like,
options: authorizeSession.Options,
): Promise
```
Call it as `ens.hca.authorizeSession(options)` on a client, or `Actions.hca.authorizeSession(client, options)`.
## Parameters [#parameters]
| Option | Type | Default | Description |
| --- | --- | --- | --- |
| `sessionKey` (required) | `string` | | Public address of the session key the app keeps. |
| `resolver` (required) | `string` | | The one resolver the session may deploy and edit (an existing resolver, or a PermissionedResolver proxy the session deploys from the HCA at that address). |
| `validUntil` (required) | `number` | | Unix seconds after which the session stops working. |
| `refund` | `{ readonly token?: Address \| undefined; readonly maxExchangeRate?: bigint \| undefined; readonly maxGasOverhead?: bigint \| undefined; readonly maxAmount?: bigint \| undefined; }` | | Refund ceilings for Rhinestone executions, in the refund token's units. |
| `account` | `Address` | | Signer (the HCA owner). @default the client's account |
## Returns [#returns]
Resolves to `HcaSession`. The approved session, to store.
| 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. |
## Errors [#errors]
| Error | Codes | When |
| --- | --- | --- |
| [`UserRejectedError`](/docs/reference/errors/user-rejected-error) | [`USER_REJECTED`](/docs/reference/errors/USER_REJECTED) | the owner declines. |
| [`InvalidInputError`](/docs/reference/errors/invalid-input-error) | [`INVALID_ADDRESS`](/docs/reference/errors/INVALID_ADDRESS) | invalid addresses. |
| [`HcaError`](/docs/reference/errors/hca-error) | [`HCA_UNAVAILABLE`](/docs/reference/errors/HCA_UNAVAILABLE) | on chains without an HCA deployment. |
It can also fail with the errors every read can (`Errors.CommonError`: `ConfigError`, `ContractRevertError`, `InternalError`, `NetworkError`).
See [How errors work](/docs/sdk/errors-explained).
## Examples [#examples]
```ts title="Authorizing a session"
const session = await ens.hca.authorizeSession({ sessionKey: sessionAccount.address, resolver, validUntil })
```
```ts title="Authorizing a session with a standalone call"
import { Actions } from "@ensforge/hca"
await Actions.hca.authorizeSession(ens, { sessionKey: sessionAccount.address, resolver, validUntil })
```
```ts title="Authorizing a session in an Effect program"
import { Actions } from "@ensforge/hca/effect"
yield* Actions.hca.authorizeSession(ens, { sessionKey: sessionAccount.address, resolver, validUntil })
```
# hca.checkSessionCalls
> For the complete documentation index, see [llms.txt](https://ensforge.com/llms.txt).
Checks calls against the HCA session policy before anything is signed. Parameters, return value, errors and examples for hca.checkSessionCalls in @ensforge/hca.
Source: https://ensforge.com/docs/reference/hca/hca/check-session-calls
`@ensforge/hca` is experimental: its API can change in a minor release.
Checks calls against the HCA session policy before anything is signed.
## When to use [#when-to-use]
Use to tell users up front which actions a session can do without prompts; `hca({ session })`
runs this check itself.
## Details [#details]
- Allowed: commit and register (to the owner, with the session resolver), the session
resolver's deployment and record setters, the owner's primary name, and payment approvals to
the registrar.
- Not allowed: renewals, transfers, subnames, registry approvals and other contracts.
## Signature [#signature]
```ts
function checkSessionCalls(
client: Like,
options: checkSessionCalls.Options,
): Promise
```
Call it as `ens.hca.checkSessionCalls(options)` on a client, or `Actions.hca.checkSessionCalls(client, options)`.
`hca.checkSessionCalls.request(options)` builds a deferred read for `Actions.batch`. See [Look up many at once](/docs/sdk/look-up-many-at-once).
## Parameters [#parameters]
| Option | Type | Default | Description |
| --- | --- | --- | --- |
| `session` (required) | `HcaSession` | | The session from `authorizeSession`. |
| `calls` (required) | `readonly Plan.Call[]` | | Calls the HCA would run. |
## Returns [#returns]
Resolves to `true`. `true` when every call is allowed.
## Errors [#errors]
| Error | Codes | When |
| --- | --- | --- |
| [`HcaError`](/docs/reference/errors/hca-error) | [`HCA_ACTION_NOT_ALLOWED`](/docs/reference/errors/HCA_ACTION_NOT_ALLOWED) | the first call outside the policy. |
| [`HcaError`](/docs/reference/errors/hca-error) | [`HCA_UNAVAILABLE`](/docs/reference/errors/HCA_UNAVAILABLE) | on chains without an HCA deployment. |
It can also fail with the errors every read can (`Errors.CommonError`: `ConfigError`, `ContractRevertError`, `InternalError`, `NetworkError`).
See [How errors work](/docs/sdk/errors-explained).
## Examples [#examples]
```ts title="Checking a record update"
await ens.hca.checkSessionCalls({ session, calls })
```
```ts title="Checking a record update with a standalone call"
import { Actions } from "@ensforge/hca"
await Actions.hca.checkSessionCalls(ens, { session, calls })
```
```ts title="Checking a record update in an Effect program"
import { Actions } from "@ensforge/hca/effect"
yield* Actions.hca.checkSessionCalls(ens, { session, calls })
```
# hca.deploy
> For the complete documentation index, see [llms.txt](https://ensforge.com/llms.txt).
Deploys the signer's HCA through the ENS factory. Parameters, return value, errors and examples for hca.deploy in @ensforge/hca.
Source: https://ensforge.com/docs/reference/hca/hca/deploy
`@ensforge/hca` is experimental: its API can change in a minor release.
Deploys the signer's HCA through the ENS factory. Resolves once the transaction is submitted.
## When to use [#when-to-use]
Use to deploy ahead of time; otherwise the first execution through the HCA deploys it.
## Details [#details]
- Idempotent: deploying an existing HCA returns it unchanged.
## Signature [#signature]
```ts
function deploy(
client: Like,
options: deploy.Options & Write.Options,
): Promise
```
Call it as `ens.hca.deploy(options)` on a client, or `Actions.hca.deploy(client, options)`.
## Parameters [#parameters]
Also takes the [write options](/docs/reference/sdk/client#write-options).
## Returns [#returns]
Resolves to `Write.Result`. Submitted transaction hashes and the plan that produced them.
| Field | Type | Description |
| --- | --- | --- |
| `hash` | `Hex` | Hash of the last transaction. |
| `hashes` | `readonly Hex[]` | Every submitted transaction, in order. |
| `id` | `string` | EIP-5792 bundle id when the calls were sent as one batch. |
| `plan` | `Plan` | The plan the write executed: its steps, in order, as they were submitted. |
## Errors [#errors]
| Error | Codes | When |
| --- | --- | --- |
| [`HcaError`](/docs/reference/errors/hca-error) | [`HCA_UNAVAILABLE`](/docs/reference/errors/HCA_UNAVAILABLE) | on chains without an HCA deployment. |
It can also fail with the errors every write can (`Errors.WriteError`: the common errors plus `InsufficientFundsError`, `TransactionError`, `UnsupportedError`, `UserRejectedError`, `WalletError`).
See [How errors work](/docs/sdk/errors-explained).
## Examples [#examples]
```ts title="Deploying the signer's HCA"
const { hash } = await ens.hca.deploy({})
```
```ts title="Deploying the signer's HCA with a standalone call"
import { Actions } from "@ensforge/hca"
await Actions.hca.deploy(ens, {})
```
```ts title="Deploying the signer's HCA in an Effect program"
import { Actions } from "@ensforge/hca/effect"
yield* Actions.hca.deploy(ens, {})
```
## Plan methods [#plan-methods]
Each method takes the same options as `hca.deploy` and sends nothing. See [Preview before sending](/docs/sdk/preview-before-sending).
| Method | Description |
| --- | --- |
| `hca.deploy.prepare(options)` | Builds the plan without sending anything. |
| `hca.deploy.simulate(options)` | Simulates the plan with `eth_call`, reporting each step. |
| `hca.deploy.estimateGas(options)` | Estimates the gas and ETH the plan needs. |
## Wait for the receipt with `deploySync` [#wait-for-the-receipt-with-deploysync]
Deploys the signer's HCA through the ENS factory. Resolves once the receipt is in.
Use when the next step depends on the change being on-chain.
`hca.deploySync` takes the same options plus [`confirmations` and `timeout`](/docs/reference/sdk/client#sync-options).
Resolves to `Write.SyncResult`. Receipts plus the submitted hashes and plan.
```ts title="Deploying the signer's HCA and waiting"
const { receipt } = await ens.hca.deploySync({})
```
```ts title="Deploying the signer's HCA with a standalone call and waiting"
import { Actions } from "@ensforge/hca"
await Actions.hca.deploySync(ens, {})
```
```ts title="Deploying the signer's HCA in an Effect program and waiting"
import { Actions } from "@ensforge/hca/effect"
yield* Actions.hca.deploySync(ens, {})
```
# hca.execute
> For the complete documentation index, see [llms.txt](https://ensforge.com/llms.txt).
Runs calls from the signer's HCA as one atomic execution. Parameters, return value, errors and examples for hca.execute in @ensforge/hca.
Source: https://ensforge.com/docs/reference/hca/hca/execute
`@ensforge/hca` is experimental: its API can change in a minor release.
Runs calls from the signer's HCA as one atomic execution. Resolves once the transaction is submitted.
## When to use [#when-to-use]
Use to batch arbitrary calls the HCA has authority for, or to recover funds the HCA holds.
## Details [#details]
- Runs through `via` (default `hca()`: the owner's wallet sends `executeByOwner`).
- Every call succeeds or the whole execution reverts.
## Signature [#signature]
```ts
function execute(
client: Like,
options: execute.Options & Write.Options,
): Promise
```
Call it as `ens.hca.execute(options)` on a client, or `Actions.hca.execute(client, options)`.
## Parameters [#parameters]
| Option | Type | Default | Description |
| --- | --- | --- | --- |
| `calls` (required) | `readonly { readonly to: Address; readonly data?: Hex \| undefined; readonly value?: bigint \| undefined; }[]` | | Calls to run, in order; `value` is paid from what the execution forwards. |
Also takes the [write options](/docs/reference/sdk/client#write-options).
## Returns [#returns]
Resolves to `Write.Result`. Submitted transaction hashes and the plan that produced them.
| Field | Type | Description |
| --- | --- | --- |
| `hash` | `Hex` | Hash of the last transaction. |
| `hashes` | `readonly Hex[]` | Every submitted transaction, in order. |
| `id` | `string` | EIP-5792 bundle id when the calls were sent as one batch. |
| `plan` | `Plan` | The plan the write executed: its steps, in order, as they were submitted. |
## Errors [#errors]
| Error | Codes | When |
| --- | --- | --- |
| [`HcaError`](/docs/reference/errors/hca-error) | [`HCA_NOT_VERIFIED`](/docs/reference/errors/HCA_NOT_VERIFIED), [`HCA_EXECUTOR_UNSUPPORTED`](/docs/reference/errors/HCA_EXECUTOR_UNSUPPORTED) | the HCA or executor cannot run them. |
| [`HcaError`](/docs/reference/errors/hca-error) | [`HCA_UNAVAILABLE`](/docs/reference/errors/HCA_UNAVAILABLE) | on chains without an HCA deployment. |
It can also fail with the errors every write can (`Errors.WriteError`: the common errors plus `InsufficientFundsError`, `TransactionError`, `UnsupportedError`, `UserRejectedError`, `WalletError`).
See [How errors work](/docs/sdk/errors-explained).
## Examples [#examples]
```ts title="Running calls from the HCA"
const { hash } = await ens.hca.execute({ calls })
```
```ts title="Running calls from the HCA with a standalone call"
import { Actions } from "@ensforge/hca"
await Actions.hca.execute(ens, { calls })
```
```ts title="Running calls from the HCA in an Effect program"
import { Actions } from "@ensforge/hca/effect"
yield* Actions.hca.execute(ens, { calls })
```
## Plan methods [#plan-methods]
Each method takes the same options as `hca.execute` and sends nothing. See [Preview before sending](/docs/sdk/preview-before-sending).
| Method | Description |
| --- | --- |
| `hca.execute.prepare(options)` | Builds the plan without sending anything. |
| `hca.execute.simulate(options)` | Simulates the plan with `eth_call`, reporting each step. |
| `hca.execute.estimateGas(options)` | Estimates the gas and ETH the plan needs. |
## Wait for the receipt with `executeSync` [#wait-for-the-receipt-with-executesync]
Runs calls from the signer's HCA as one atomic execution. Resolves once the receipt is in.
Use when the next step depends on the change being on-chain.
`hca.executeSync` takes the same options plus [`confirmations` and `timeout`](/docs/reference/sdk/client#sync-options).
Resolves to `Write.SyncResult`. Receipts plus the submitted hashes and plan.
```ts title="Running calls from the HCA and waiting"
const { receipt } = await ens.hca.executeSync({ calls })
```
```ts title="Running calls from the HCA with a standalone call and waiting"
import { Actions } from "@ensforge/hca"
await Actions.hca.executeSync(ens, { calls })
```
```ts title="Running calls from the HCA in an Effect program and waiting"
import { Actions } from "@ensforge/hca/effect"
yield* Actions.hca.executeSync(ens, { calls })
```
# hca.getDeposit
> For the complete documentation index, see [llms.txt](https://ensforge.com/llms.txt).
Reads an HCA's ERC-4337 EntryPoint deposit, which pays for its UserOperations without a paymaster. Options, result, errors and examples for hca.getDeposit.
Source: https://ensforge.com/docs/reference/hca/hca/get-deposit
`@ensforge/hca` is experimental: its API can change in a minor release.
Reads an HCA's ERC-4337 EntryPoint deposit, which pays for its UserOperations without a paymaster.
## When to use [#when-to-use]
Use with `bundler()` executions that the HCA pays for itself.
## Signature [#signature]
```ts
function getDeposit(
client: Like,
options?: getDeposit.Options,
): Promise
```
Call it as `ens.hca.getDeposit(options)` on a client, or `Actions.hca.getDeposit(client, options)`.
`hca.getDeposit.request(options)` builds a deferred read for `Actions.batch`. See [Look up many at once](/docs/sdk/look-up-many-at-once).
## Parameters [#parameters]
| Option | Type | Default | Description |
| --- | --- | --- | --- |
| `address` | `string` | | The HCA's address. |
| `owner` | `string` | the client's account | Owner whose HCA to use. |
## Returns [#returns]
Resolves to `bigint`. Deposit in wei.
## Errors [#errors]
| Error | Codes | When |
| --- | --- | --- |
| [`InvalidInputError`](/docs/reference/errors/invalid-input-error) | [`INVALID_ADDRESS`](/docs/reference/errors/INVALID_ADDRESS) | an invalid address. |
| [`HcaError`](/docs/reference/errors/hca-error) | [`HCA_UNAVAILABLE`](/docs/reference/errors/HCA_UNAVAILABLE) | on chains without an HCA deployment. |
It can also fail with the errors every read can (`Errors.CommonError`: `ConfigError`, `ContractRevertError`, `InternalError`, `NetworkError`).
See [How errors work](/docs/sdk/errors-explained).
## Examples [#examples]
```ts title="Reading the deposit"
const deposit = await ens.hca.getDeposit({})
```
```ts title="Reading the deposit with a standalone call"
import { Actions } from "@ensforge/hca"
await Actions.hca.getDeposit(ens, {})
```
```ts title="Reading the deposit in an Effect program"
import { Actions } from "@ensforge/hca/effect"
yield* Actions.hca.getDeposit(ens, {})
```
# hca.getSession
> For the complete documentation index, see [llms.txt](https://ensforge.com/llms.txt).
Checks whether a stored HCA session can still be used. Parameters, return value, errors and examples for hca.getSession in @ensforge/hca.
Source: https://ensforge.com/docs/reference/hca/hca/get-session
`@ensforge/hca` is experimental: its API can change in a minor release.
Checks whether a stored HCA session can still be used.
## When to use [#when-to-use]
Use when restoring a session the app stored, before offering prompt-free actions with it.
## Details [#details]
- A session stops working when it expires, when the owner calls `revokeSessions`, or when the
deployment's session signing domain changes.
## Signature [#signature]
```ts
function getSession(
client: Like,
options: getSession.Options,
): Promise
```
Call it as `ens.hca.getSession(options)` on a client, or `Actions.hca.getSession(client, options)`.
`hca.getSession.request(options)` builds a deferred read for `Actions.batch`. See [Look up many at once](/docs/sdk/look-up-many-at-once).
## Parameters [#parameters]
| Option | Type | Default | Description |
| --- | --- | --- | --- |
| `session` (required) | `HcaSession` | | The session from `authorizeSession`. |
## Returns [#returns]
Resolves to `getSession.ReturnType`. Whether the session works, and why not.
| Field | Type | Description |
| --- | --- | --- |
| `valid` | `boolean` | |
| `problem` | `"chain" \| "expired" \| "revoked" \| "signing-domain" \| null` | |
## Errors [#errors]
| Error | Codes | When |
| --- | --- | --- |
| [`HcaError`](/docs/reference/errors/hca-error) | [`HCA_UNAVAILABLE`](/docs/reference/errors/HCA_UNAVAILABLE) | on chains without an HCA deployment. |
It can also fail with the errors every read can (`Errors.CommonError`: `ConfigError`, `ContractRevertError`, `InternalError`, `NetworkError`).
See [How errors work](/docs/sdk/errors-explained).
## Examples [#examples]
```ts title="Checking a stored session"
const { valid } = await ens.hca.getSession({ session })
```
```ts title="Checking a stored session with a standalone call"
import { Actions } from "@ensforge/hca"
await Actions.hca.getSession(ens, { session })
```
```ts title="Checking a stored session in an Effect program"
import { Actions } from "@ensforge/hca/effect"
yield* Actions.hca.getSession(ens, { session })
```
# hca.getUpgrade
> For the complete documentation index, see [llms.txt](https://ensforge.com/llms.txt).
Checks whether an HCA may upgrade to an implementation: it must be in the DAO's upgrade set and accept the current implementation.
Source: https://ensforge.com/docs/reference/hca/hca/get-upgrade
`@ensforge/hca` is experimental: its API can change in a minor release.
Checks whether an HCA may upgrade to an implementation: it must be in the DAO's upgrade set and accept the current implementation.
## When to use [#when-to-use]
Use to check an upgrade before offering it: it reports which approval is missing.
## Signature [#signature]
```ts
function getUpgrade(
client: Like,
options: getUpgrade.Options,
): Promise
```
Call it as `ens.hca.getUpgrade(options)` on a client, or `Actions.hca.getUpgrade(client, options)`.
`hca.getUpgrade.request(options)` builds a deferred read for `Actions.batch`. See [Look up many at once](/docs/sdk/look-up-many-at-once).
## Parameters [#parameters]
| Option | Type | Default | Description |
| --- | --- | --- | --- |
| `implementation` (required) | `string` | | Implementation to upgrade to. |
| `address` | `string` | | The HCA's address. |
| `owner` | `string` | the client's account | Owner whose HCA to check. |
## Returns [#returns]
Resolves to `getUpgrade.ReturnType`. Whether the upgrade is allowed, and each approval.
| Field | Type | Description |
| --- | --- | --- |
| `allowed` | `boolean` | |
| `current` | `Address \| null` | |
| `inUpgradeSet` | `boolean` | |
| `predecessorAllowed` | `boolean` | |
## Errors [#errors]
| Error | Codes | When |
| --- | --- | --- |
| [`InvalidInputError`](/docs/reference/errors/invalid-input-error) | [`INVALID_ADDRESS`](/docs/reference/errors/INVALID_ADDRESS) | invalid addresses. |
| [`HcaError`](/docs/reference/errors/hca-error) | [`HCA_UNAVAILABLE`](/docs/reference/errors/HCA_UNAVAILABLE) | on chains without an HCA deployment. |
It can also fail with the errors every read can (`Errors.CommonError`: `ConfigError`, `ContractRevertError`, `InternalError`, `NetworkError`).
See [How errors work](/docs/sdk/errors-explained).
## Examples [#examples]
```ts title="Checking an upgrade"
const { allowed } = await ens.hca.getUpgrade({ implementation })
```
```ts title="Checking an upgrade with a standalone call"
import { Actions } from "@ensforge/hca"
await Actions.hca.getUpgrade(ens, { implementation })
```
```ts title="Checking an upgrade in an Effect program"
import { Actions } from "@ensforge/hca/effect"
yield* Actions.hca.getUpgrade(ens, { implementation })
```
# hca.get
> For the complete documentation index, see [llms.txt](https://ensforge.com/llms.txt).
Reads an ENS HCA (Hosted Contract Account): its address, owner, implementation, session nonce and verification problems.
Source: https://ensforge.com/docs/reference/hca/hca/get
`@ensforge/hca` is experimental: its API can change in a minor release.
Reads an ENS HCA (Hosted Contract Account): its address, owner, implementation, session nonce and verification problems.
## When to use [#when-to-use]
Use to show a user's HCA, or to check it before routing writes through it; works before
deployment (predicted address).
## Details [#details]
- Without `address`, reads the HCA of `owner` (default: the client's account).
- `problems` lists failed checks (HCA.md): an empty list means the account is safe to use.
## Signature [#signature]
```ts
function get(client: Like, options?: get.Options): Promise
```
Call it as `ens.hca.get(options)` on a client, or `Actions.hca.get(client, options)`.
`hca.get.request(options)` builds a deferred read for `Actions.batch`. See [Look up many at once](/docs/sdk/look-up-many-at-once).
## Parameters [#parameters]
| Option | Type | Default | Description |
| --- | --- | --- | --- |
| `address` | `string` | | The HCA's address. |
| `owner` | `string` | the client's account | Owner whose HCA to use. |
## Returns [#returns]
Resolves to `HcaAccount`. The account, deployed or predicted.
| 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. |
## Errors [#errors]
| Error | Codes | When |
| --- | --- | --- |
| [`InvalidInputError`](/docs/reference/errors/invalid-input-error) | [`INVALID_ADDRESS`](/docs/reference/errors/INVALID_ADDRESS) | an invalid address. |
| [`HcaError`](/docs/reference/errors/hca-error) | [`HCA_UNAVAILABLE`](/docs/reference/errors/HCA_UNAVAILABLE) | on chains without an HCA deployment. |
It can also fail with the errors every read can (`Errors.CommonError`: `ConfigError`, `ContractRevertError`, `InternalError`, `NetworkError`).
See [How errors work](/docs/sdk/errors-explained).
## Examples [#examples]
```ts title="Reading the signer's HCA"
const account = await ens.hca.get({})
```
```ts title="Reading the signer's HCA with a standalone call"
import { Actions } from "@ensforge/hca"
await Actions.hca.get(ens, {})
```
```ts title="Reading the signer's HCA in an Effect program"
import { Actions } from "@ensforge/hca/effect"
yield* Actions.hca.get(ens, {})
```
# hca
> For the complete documentation index, see [llms.txt](https://ensforge.com/llms.txt).
List the 14 hca actions of @ensforge/hca and whether each reads, writes or signs. Covers addDeposit, authorizeSession, checkSessionCalls, deploy, execute, get.
Source: https://ensforge.com/docs/reference/hca/hca
Call them as `ens.hca.(options)` on a client, or `Actions.hca.(client, options)`.
## Reads [#reads]
| Action | Description |
| --- | --- |
| [`authorizeSession`](/docs/reference/hca/hca/authorize-session) | Asks the owner to approve a session key for their HCA, with one signature and no transaction. |
| [`checkSessionCalls`](/docs/reference/hca/hca/check-session-calls) (batchable) | Checks calls against the HCA session policy before anything is signed. |
| [`get`](/docs/reference/hca/hca/get) (batchable) | Reads an ENS HCA (Hosted Contract Account): its address, owner, implementation, session nonce and verification problems. |
| [`getDeposit`](/docs/reference/hca/hca/get-deposit) (batchable) | Reads an HCA's ERC-4337 EntryPoint deposit, which pays for its UserOperations without a paymaster. |
| [`getSession`](/docs/reference/hca/hca/get-session) (batchable) | Checks whether a stored HCA session can still be used. |
| [`getUpgrade`](/docs/reference/hca/hca/get-upgrade) (batchable) | Checks whether an HCA may upgrade to an implementation: it must be in the DAO's upgrade set and accept the current implementation. |
| [`predictAddress`](/docs/reference/hca/hca/predict-address) (batchable) | Computes the address of an owner's ENS HCA, deployed or not. |
| [`verify`](/docs/reference/hca/hca/verify) (batchable) | Checks that an address is a usable ENS HCA of its owner, and returns it. |
## Writes [#writes]
| Action | Description |
| --- | --- |
| [`addDeposit`](/docs/reference/hca/hca/add-deposit) | Adds ETH to an HCA's ERC-4337 EntryPoint deposit. |
| [`deploy`](/docs/reference/hca/hca/deploy) | Deploys the signer's HCA through the ENS factory. |
| [`execute`](/docs/reference/hca/hca/execute) | Runs calls from the signer's HCA as one atomic execution. |
| [`revokeSessions`](/docs/reference/hca/hca/revoke-sessions) | Invalidates every session approval of the signer's HCA. |
| [`upgrade`](/docs/reference/hca/hca/upgrade) | Upgrades the signer's HCA to an implementation the DAO's upgrade set and its own `canUpgradeFrom` check allow. |
| [`withdrawDeposit`](/docs/reference/hca/hca/withdraw-deposit) | Withdraws ETH from the signer's HCA EntryPoint deposit. |
# hca.predictAddress
> For the complete documentation index, see [llms.txt](https://ensforge.com/llms.txt).
Computes the address of an owner's ENS HCA, deployed or not. Parameters, return value, errors and examples for hca.predictAddress in @ensforge/hca.
Source: https://ensforge.com/docs/reference/hca/hca/predict-address
`@ensforge/hca` is experimental: its API can change in a minor release.
Computes the address of an owner's ENS HCA, deployed or not.
## When to use [#when-to-use]
Use to show or fund an HCA before it exists; the address never changes, even after upgrades.
## Signature [#signature]
```ts
function predictAddress(
client: Like,
options?: predictAddress.Options,
): Promise
```
Call it as `ens.hca.predictAddress(options)` on a client, or `Actions.hca.predictAddress(client, options)`.
`hca.predictAddress.request(options)` builds a deferred read for `Actions.batch`. See [Look up many at once](/docs/sdk/look-up-many-at-once).
## Parameters [#parameters]
| Option | Type | Default | Description |
| --- | --- | --- | --- |
| `owner` | `string` | the client's account | The owner. |
## Returns [#returns]
Resolves to `Address`. The HCA address.
## Errors [#errors]
| Error | Codes | When |
| --- | --- | --- |
| [`InvalidInputError`](/docs/reference/errors/invalid-input-error) | [`INVALID_ADDRESS`](/docs/reference/errors/INVALID_ADDRESS) | an invalid owner. |
| [`HcaError`](/docs/reference/errors/hca-error) | [`HCA_UNAVAILABLE`](/docs/reference/errors/HCA_UNAVAILABLE) | on chains without an HCA deployment. |
It can also fail with the errors every read can (`Errors.CommonError`: `ConfigError`, `ContractRevertError`, `InternalError`, `NetworkError`).
See [How errors work](/docs/sdk/errors-explained).
## Examples [#examples]
```ts title="Predicting the signer's HCA"
const address = await ens.hca.predictAddress({})
```
```ts title="Predicting the signer's HCA with a standalone call"
import { Actions } from "@ensforge/hca"
await Actions.hca.predictAddress(ens, {})
```
```ts title="Predicting the signer's HCA in an Effect program"
import { Actions } from "@ensforge/hca/effect"
yield* Actions.hca.predictAddress(ens, {})
```
# hca.revokeSessions
> For the complete documentation index, see [llms.txt](https://ensforge.com/llms.txt).
Invalidates every session approval of the signer's HCA. Parameters, return value, errors and examples for hca.revokeSessions in @ensforge/hca.
Source: https://ensforge.com/docs/reference/hca/hca/revoke-sessions
`@ensforge/hca` is experimental: its API can change in a minor release.
Invalidates every session approval of the signer's HCA. Resolves once the transaction is submitted.
## When to use [#when-to-use]
Use when a session key may be lost or compromised, or to end all prompt-free access.
## Details [#details]
- Bumps the HCA's session nonce; must be the owner's own transaction (never routed through the
HCA).
## Signature [#signature]
```ts
function revokeSessions(
client: Like,
options: revokeSessions.Options & Write.Options,
): Promise
```
Call it as `ens.hca.revokeSessions(options)` on a client, or `Actions.hca.revokeSessions(client, options)`.
## Parameters [#parameters]
Also takes the [write options](/docs/reference/sdk/client#write-options).
## Returns [#returns]
Resolves to `Write.Result`. Submitted transaction hashes and the plan that produced them.
| Field | Type | Description |
| --- | --- | --- |
| `hash` | `Hex` | Hash of the last transaction. |
| `hashes` | `readonly Hex[]` | Every submitted transaction, in order. |
| `id` | `string` | EIP-5792 bundle id when the calls were sent as one batch. |
| `plan` | `Plan` | The plan the write executed: its steps, in order, as they were submitted. |
## Errors [#errors]
| Error | Codes | When |
| --- | --- | --- |
| [`HcaError`](/docs/reference/errors/hca-error) | [`HCA_NOT_VERIFIED`](/docs/reference/errors/HCA_NOT_VERIFIED) | the HCA is not deployed. |
| [`HcaError`](/docs/reference/errors/hca-error) | [`HCA_UNAVAILABLE`](/docs/reference/errors/HCA_UNAVAILABLE) | on chains without an HCA deployment. |
It can also fail with the errors every write can (`Errors.WriteError`: the common errors plus `InsufficientFundsError`, `TransactionError`, `UnsupportedError`, `UserRejectedError`, `WalletError`).
See [How errors work](/docs/sdk/errors-explained).
## Examples [#examples]
```ts title="Revoking every session"
const { hash } = await ens.hca.revokeSessions({})
```
```ts title="Revoking every session with a standalone call"
import { Actions } from "@ensforge/hca"
await Actions.hca.revokeSessions(ens, {})
```
```ts title="Revoking every session in an Effect program"
import { Actions } from "@ensforge/hca/effect"
yield* Actions.hca.revokeSessions(ens, {})
```
## Plan methods [#plan-methods]
Each method takes the same options as `hca.revokeSessions` and sends nothing. See [Preview before sending](/docs/sdk/preview-before-sending).
| Method | Description |
| --- | --- |
| `hca.revokeSessions.prepare(options)` | Builds the plan without sending anything. |
| `hca.revokeSessions.simulate(options)` | Simulates the plan with `eth_call`, reporting each step. |
| `hca.revokeSessions.estimateGas(options)` | Estimates the gas and ETH the plan needs. |
## Wait for the receipt with `revokeSessionsSync` [#wait-for-the-receipt-with-revokesessionssync]
Invalidates every session approval of the signer's HCA. Resolves once the receipt is in.
Use when the next step depends on the change being on-chain.
`hca.revokeSessionsSync` takes the same options plus [`confirmations` and `timeout`](/docs/reference/sdk/client#sync-options).
Resolves to `Write.SyncResult`. Receipts plus the submitted hashes and plan.
```ts title="Revoking every session and waiting"
const { receipt } = await ens.hca.revokeSessionsSync({})
```
```ts title="Revoking every session with a standalone call and waiting"
import { Actions } from "@ensforge/hca"
await Actions.hca.revokeSessionsSync(ens, {})
```
```ts title="Revoking every session in an Effect program and waiting"
import { Actions } from "@ensforge/hca/effect"
yield* Actions.hca.revokeSessionsSync(ens, {})
```
# hca.upgrade
> For the complete documentation index, see [llms.txt](https://ensforge.com/llms.txt).
Upgrades the signer's HCA to an implementation the DAO's upgrade set and its own canUpgradeFrom check allow. Options, errors and examples for hca.upgrade.
Source: https://ensforge.com/docs/reference/hca/hca/upgrade
`@ensforge/hca` is experimental: its API can change in a minor release.
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.
## When to use [#when-to-use]
Use when the DAO approves a new HCA implementation; the address and sessions stay.
## Signature [#signature]
```ts
function upgrade(
client: Like,
options: upgrade.Options & Write.Options,
): Promise
```
Call it as `ens.hca.upgrade(options)` on a client, or `Actions.hca.upgrade(client, options)`.
## Parameters [#parameters]
| Option | Type | Default | Description |
| --- | --- | --- | --- |
| `implementation` (required) | `string` | | Implementation to upgrade to. |
Also takes the [write options](/docs/reference/sdk/client#write-options).
## Returns [#returns]
Resolves to `Write.Result`. Submitted transaction hashes and the plan that produced them.
| Field | Type | Description |
| --- | --- | --- |
| `hash` | `Hex` | Hash of the last transaction. |
| `hashes` | `readonly Hex[]` | Every submitted transaction, in order. |
| `id` | `string` | EIP-5792 bundle id when the calls were sent as one batch. |
| `plan` | `Plan` | The plan the write executed: its steps, in order, as they were submitted. |
## Errors [#errors]
| Error | Codes | When |
| --- | --- | --- |
| [`HcaError`](/docs/reference/errors/hca-error) | [`HCA_UPGRADE_NOT_ALLOWED`](/docs/reference/errors/HCA_UPGRADE_NOT_ALLOWED) | a DAO set does not allow it. |
| [`InvalidInputError`](/docs/reference/errors/invalid-input-error) | [`INVALID_ADDRESS`](/docs/reference/errors/INVALID_ADDRESS) | an invalid address. |
| [`HcaError`](/docs/reference/errors/hca-error) | [`HCA_UNAVAILABLE`](/docs/reference/errors/HCA_UNAVAILABLE) | on chains without an HCA deployment. |
It can also fail with the errors every write can (`Errors.WriteError`: the common errors plus `InsufficientFundsError`, `TransactionError`, `UnsupportedError`, `UserRejectedError`, `WalletError`).
See [How errors work](/docs/sdk/errors-explained).
## Examples [#examples]
```ts title="Upgrading the HCA"
const { hash } = await ens.hca.upgrade({ implementation })
```
```ts title="Upgrading the HCA with a standalone call"
import { Actions } from "@ensforge/hca"
await Actions.hca.upgrade(ens, { implementation })
```
```ts title="Upgrading the HCA in an Effect program"
import { Actions } from "@ensforge/hca/effect"
yield* Actions.hca.upgrade(ens, { implementation })
```
## Plan methods [#plan-methods]
Each method takes the same options as `hca.upgrade` and sends nothing. See [Preview before sending](/docs/sdk/preview-before-sending).
| Method | Description |
| --- | --- |
| `hca.upgrade.prepare(options)` | Builds the plan without sending anything. |
| `hca.upgrade.simulate(options)` | Simulates the plan with `eth_call`, reporting each step. |
| `hca.upgrade.estimateGas(options)` | Estimates the gas and ETH the plan needs. |
## Wait for the receipt with `upgradeSync` [#wait-for-the-receipt-with-upgradesync]
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.
Use when the next step depends on the change being on-chain.
`hca.upgradeSync` takes the same options plus [`confirmations` and `timeout`](/docs/reference/sdk/client#sync-options).
Resolves to `Write.SyncResult`. Receipts plus the submitted hashes and plan.
```ts title="Upgrading the HCA and waiting"
const { receipt } = await ens.hca.upgradeSync({ implementation })
```
```ts title="Upgrading the HCA with a standalone call and waiting"
import { Actions } from "@ensforge/hca"
await Actions.hca.upgradeSync(ens, { implementation })
```
```ts title="Upgrading the HCA in an Effect program and waiting"
import { Actions } from "@ensforge/hca/effect"
yield* Actions.hca.upgradeSync(ens, { implementation })
```
# hca.verify
> For the complete documentation index, see [llms.txt](https://ensforge.com/llms.txt).
Checks that an address is a usable ENS HCA of its owner, and returns it. Parameters, return value, errors and examples for hca.verify in @ensforge/hca.
Source: https://ensforge.com/docs/reference/hca/hca/verify
`@ensforge/hca` is experimental: its API can change in a minor release.
Checks that an address is a usable ENS HCA of its owner, and returns it.
## When to use [#when-to-use]
Use to check an existing HCA before trusting it, e.g. one stored by the app: it fails instead of returning
problems.
## Details [#details]
- Runs HCA.md's checks: derived address, owner, `accountId`, trusted implementation, factory
certification.
- A predicted (not yet deployed) HCA passes; its first execution deploys it.
## Signature [#signature]
```ts
function verify(client: Like, options?: verify.Options): Promise
```
Call it as `ens.hca.verify(options)` on a client, or `Actions.hca.verify(client, options)`.
`hca.verify.request(options)` builds a deferred read for `Actions.batch`. See [Look up many at once](/docs/sdk/look-up-many-at-once).
## Parameters [#parameters]
| Option | Type | Default | Description |
| --- | --- | --- | --- |
| `address` | `string` | | The HCA's address. |
| `owner` | `string` | the client's account | Owner whose HCA to use. |
## Returns [#returns]
Resolves to `HcaAccount`. The verified account.
| 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. |
## Errors [#errors]
| Error | Codes | When |
| --- | --- | --- |
| [`HcaError`](/docs/reference/errors/hca-error) | [`HCA_NOT_VERIFIED`](/docs/reference/errors/HCA_NOT_VERIFIED) | a check fails. |
| [`InvalidInputError`](/docs/reference/errors/invalid-input-error) | [`INVALID_ADDRESS`](/docs/reference/errors/INVALID_ADDRESS) | an invalid address. |
| [`HcaError`](/docs/reference/errors/hca-error) | [`HCA_UNAVAILABLE`](/docs/reference/errors/HCA_UNAVAILABLE) | on chains without an HCA deployment. |
It can also fail with the errors every read can (`Errors.CommonError`: `ConfigError`, `ContractRevertError`, `InternalError`, `NetworkError`).
See [How errors work](/docs/sdk/errors-explained).
## Examples [#examples]
```ts title="Verifying the signer's HCA"
const account = await ens.hca.verify({})
```
```ts title="Verifying the signer's HCA with a standalone call"
import { Actions } from "@ensforge/hca"
await Actions.hca.verify(ens, {})
```
```ts title="Verifying the signer's HCA in an Effect program"
import { Actions } from "@ensforge/hca/effect"
yield* Actions.hca.verify(ens, {})
```
# hca.withdrawDeposit
> For the complete documentation index, see [llms.txt](https://ensforge.com/llms.txt).
Withdraws ETH from the signer's HCA EntryPoint deposit. Parameters, return value, errors and examples for hca.withdrawDeposit in @ensforge/hca.
Source: https://ensforge.com/docs/reference/hca/hca/withdraw-deposit
`@ensforge/hca` is experimental: its API can change in a minor release.
Withdraws ETH from the signer's HCA EntryPoint deposit. Resolves once the transaction is submitted.
## When to use [#when-to-use]
Use to recover a deposit the HCA no longer needs.
## Signature [#signature]
```ts
function withdrawDeposit(
client: Like,
options: withdrawDeposit.Options & Write.Options,
): Promise
```
Call it as `ens.hca.withdrawDeposit(options)` on a client, or `Actions.hca.withdrawDeposit(client, options)`.
## Parameters [#parameters]
| Option | Type | Default | Description |
| --- | --- | --- | --- |
| `to` (required) | `string` | | Recipient. |
| `amount` (required) | `bigint` | | Wei to withdraw. |
Also takes the [write options](/docs/reference/sdk/client#write-options).
## Returns [#returns]
Resolves to `Write.Result`. Submitted transaction hashes and the plan that produced them.
| Field | Type | Description |
| --- | --- | --- |
| `hash` | `Hex` | Hash of the last transaction. |
| `hashes` | `readonly Hex[]` | Every submitted transaction, in order. |
| `id` | `string` | EIP-5792 bundle id when the calls were sent as one batch. |
| `plan` | `Plan` | The plan the write executed: its steps, in order, as they were submitted. |
## Errors [#errors]
| Error | Codes | When |
| --- | --- | --- |
| [`InvalidInputError`](/docs/reference/errors/invalid-input-error) | [`INVALID_ADDRESS`](/docs/reference/errors/INVALID_ADDRESS) | an invalid recipient. |
| [`HcaError`](/docs/reference/errors/hca-error) | [`HCA_UNAVAILABLE`](/docs/reference/errors/HCA_UNAVAILABLE) | on chains without an HCA deployment. |
It can also fail with the errors every write can (`Errors.WriteError`: the common errors plus `InsufficientFundsError`, `TransactionError`, `UnsupportedError`, `UserRejectedError`, `WalletError`).
See [How errors work](/docs/sdk/errors-explained).
## Examples [#examples]
```ts title="Withdrawing the deposit"
const { hash } = await ens.hca.withdrawDeposit({ to: account, amount })
```
```ts title="Withdrawing the deposit with a standalone call"
import { Actions } from "@ensforge/hca"
await Actions.hca.withdrawDeposit(ens, { to: account, amount })
```
```ts title="Withdrawing the deposit in an Effect program"
import { Actions } from "@ensforge/hca/effect"
yield* Actions.hca.withdrawDeposit(ens, { to: account, amount })
```
## Plan methods [#plan-methods]
Each method takes the same options as `hca.withdrawDeposit` and sends nothing. See [Preview before sending](/docs/sdk/preview-before-sending).
| Method | Description |
| --- | --- |
| `hca.withdrawDeposit.prepare(options)` | Builds the plan without sending anything. |
| `hca.withdrawDeposit.simulate(options)` | Simulates the plan with `eth_call`, reporting each step. |
| `hca.withdrawDeposit.estimateGas(options)` | Estimates the gas and ETH the plan needs. |
## Wait for the receipt with `withdrawDepositSync` [#wait-for-the-receipt-with-withdrawdepositsync]
Withdraws ETH from the signer's HCA EntryPoint deposit. Resolves once the receipt is in.
Use when the next step depends on the change being on-chain.
`hca.withdrawDepositSync` takes the same options plus [`confirmations` and `timeout`](/docs/reference/sdk/client#sync-options).
Resolves to `Write.SyncResult`. Receipts plus the submitted hashes and plan.
```ts title="Withdrawing the deposit and waiting"
const { receipt } = await ens.hca.withdrawDepositSync({ to: account, amount })
```
```ts title="Withdrawing the deposit with a standalone call and waiting"
import { Actions } from "@ensforge/hca"
await Actions.hca.withdrawDepositSync(ens, { to: account, amount })
```
```ts title="Withdrawing the deposit in an Effect program and waiting"
import { Actions } from "@ensforge/hca/effect"
yield* Actions.hca.withdrawDepositSync(ens, { to: account, amount })
```
# hcaAdmin.getGovernance
> For the complete documentation index, see [llms.txt](https://ensforge.com/llms.txt).
Reads who governs ENS HCAs: the factory owner and whether implementations are approved. Options, result, errors and examples for hcaAdmin.getGovernance.
Source: https://ensforge.com/docs/reference/hca/hca-admin/get-governance
`@ensforge/hca` is experimental: its API can change in a minor release.
Reads who governs ENS HCAs: the factory owner and whether implementations are approved.
## When to use [#when-to-use]
Use to inspect HCA governance before approving or revoking implementations.
## Signature [#signature]
```ts
function getGovernance(
client: Like,
options?: getGovernance.Options,
): Promise
```
Call it as `ens.hcaAdmin.getGovernance(options)` on a client, or `Actions.hcaAdmin.getGovernance(client, options)`.
`hcaAdmin.getGovernance.request(options)` builds a deferred read for `Actions.batch`. See [Look up many at once](/docs/sdk/look-up-many-at-once).
## Parameters [#parameters]
| Option | Type | Default | Description |
| --- | --- | --- | --- |
| `implementation` | `string` | | Implementation to check. |
## Returns [#returns]
Resolves to `getGovernance.ReturnType`. Factory owner, upgrade set and the implementation's approvals.
| Field | Type | Description |
| --- | --- | --- |
| `factoryOwner` | `Address` | |
| `upgradeSet` | `Address` | |
| `deploymentApproved` | `boolean \| null` | |
| `upgradeApproved` | `boolean \| null` | |
## Errors [#errors]
| Error | Codes | When |
| --- | --- | --- |
| [`InvalidInputError`](/docs/reference/errors/invalid-input-error) | [`INVALID_ADDRESS`](/docs/reference/errors/INVALID_ADDRESS) | an invalid address. |
| [`HcaError`](/docs/reference/errors/hca-error) | [`HCA_UNAVAILABLE`](/docs/reference/errors/HCA_UNAVAILABLE) | on chains without an HCA deployment. |
It can also fail with the errors every read can (`Errors.CommonError`: `ConfigError`, `ContractRevertError`, `InternalError`, `NetworkError`).
See [How errors work](/docs/sdk/errors-explained).
## Examples [#examples]
```ts title="Reading HCA governance"
const governance = await ens.hcaAdmin.getGovernance({ implementation })
```
```ts title="Reading HCA governance with a standalone call"
import { Actions } from "@ensforge/hca"
await Actions.hcaAdmin.getGovernance(ens, { implementation })
```
```ts title="Reading HCA governance in an Effect program"
import { Actions } from "@ensforge/hca/effect"
yield* Actions.hcaAdmin.getGovernance(ens, { implementation })
```
# hcaAdmin.grantUpgradeSetRoles
> For the complete documentation index, see [llms.txt](https://ensforge.com/llms.txt).
Grants root roles on the HCA upgrade set (role admins only). Parameters, return value, errors and examples for hcaAdmin.grantUpgradeSetRoles in @ensforge/hca.
Source: https://ensforge.com/docs/reference/hca/hca-admin/grant-upgrade-set-roles
`@ensforge/hca` is experimental: its API can change in a minor release.
Grants root roles on the HCA upgrade set (role admins only). Resolves once the transaction is submitted.
## When to use [#when-to-use]
Use to let another account approve HCA upgrade targets.
## Signature [#signature]
```ts
function grantUpgradeSetRoles(
client: Like,
options: grantUpgradeSetRoles.Options & Write.Options,
): Promise
```
Call it as `ens.hcaAdmin.grantUpgradeSetRoles(options)` on a client, or `Actions.hcaAdmin.grantUpgradeSetRoles(client, options)`.
## Parameters [#parameters]
| Option | Type | Default | Description |
| --- | --- | --- | --- |
| `grantee` (required) | `string` | | Account to grant. |
| `roles` (required) | `bigint` | | Role bitmap. |
Also takes the [write options](/docs/reference/sdk/client#write-options).
## Returns [#returns]
Resolves to `Write.Result`. Submitted transaction hashes and the plan that produced them.
| Field | Type | Description |
| --- | --- | --- |
| `hash` | `Hex` | Hash of the last transaction. |
| `hashes` | `readonly Hex[]` | Every submitted transaction, in order. |
| `id` | `string` | EIP-5792 bundle id when the calls were sent as one batch. |
| `plan` | `Plan` | The plan the write executed: its steps, in order, as they were submitted. |
## Errors [#errors]
| Error | Codes | When |
| --- | --- | --- |
| [`InvalidInputError`](/docs/reference/errors/invalid-input-error) | [`INVALID_ADDRESS`](/docs/reference/errors/INVALID_ADDRESS) | an invalid address. |
| [`HcaError`](/docs/reference/errors/hca-error) | [`HCA_UNAVAILABLE`](/docs/reference/errors/HCA_UNAVAILABLE) | on chains without an HCA deployment. |
It can also fail with the errors every write can (`Errors.WriteError`: the common errors plus `InsufficientFundsError`, `TransactionError`, `UnsupportedError`, `UserRejectedError`, `WalletError`).
See [How errors work](/docs/sdk/errors-explained).
## Examples [#examples]
```ts title="Granting upgrade-set roles"
const { hash } = await ens.hcaAdmin.grantUpgradeSetRoles({ grantee, roles })
```
```ts title="Granting upgrade-set roles with a standalone call"
import { Actions } from "@ensforge/hca"
await Actions.hcaAdmin.grantUpgradeSetRoles(ens, { grantee, roles })
```
```ts title="Granting upgrade-set roles in an Effect program"
import { Actions } from "@ensforge/hca/effect"
yield* Actions.hcaAdmin.grantUpgradeSetRoles(ens, { grantee, roles })
```
## Plan methods [#plan-methods]
Each method takes the same options as `hcaAdmin.grantUpgradeSetRoles` and sends nothing. See [Preview before sending](/docs/sdk/preview-before-sending).
| Method | Description |
| --- | --- |
| `hcaAdmin.grantUpgradeSetRoles.prepare(options)` | Builds the plan without sending anything. |
| `hcaAdmin.grantUpgradeSetRoles.simulate(options)` | Simulates the plan with `eth_call`, reporting each step. |
| `hcaAdmin.grantUpgradeSetRoles.estimateGas(options)` | Estimates the gas and ETH the plan needs. |
## Wait for the receipt with `grantUpgradeSetRolesSync` [#wait-for-the-receipt-with-grantupgradesetrolessync]
Grants root roles on the HCA upgrade set (role admins only). Resolves once the receipt is in.
Use when the next step depends on the change being on-chain.
`hcaAdmin.grantUpgradeSetRolesSync` takes the same options plus [`confirmations` and `timeout`](/docs/reference/sdk/client#sync-options).
Resolves to `Write.SyncResult`. Receipts plus the submitted hashes and plan.
```ts title="Granting upgrade-set roles and waiting"
const { receipt } = await ens.hcaAdmin.grantUpgradeSetRolesSync({ grantee, roles })
```
```ts title="Granting upgrade-set roles with a standalone call and waiting"
import { Actions } from "@ensforge/hca"
await Actions.hcaAdmin.grantUpgradeSetRolesSync(ens, { grantee, roles })
```
```ts title="Granting upgrade-set roles in an Effect program and waiting"
import { Actions } from "@ensforge/hca/effect"
yield* Actions.hcaAdmin.grantUpgradeSetRolesSync(ens, { grantee, roles })
```
# hcaAdmin
> For the complete documentation index, see [llms.txt](https://ensforge.com/llms.txt).
List the 7 hcaAdmin actions of @ensforge/hca and whether each reads, writes or signs. Covers getGovernance, grantUpgradeSetRoles, renounceGovernance.
Source: https://ensforge.com/docs/reference/hca/hca-admin
Call them as `ens.hcaAdmin.(options)` on a client, or `Actions.hcaAdmin.(client, options)`.
## Reads [#reads]
| Action | Description |
| --- | --- |
| [`getGovernance`](/docs/reference/hca/hca-admin/get-governance) (batchable) | Reads who governs ENS HCAs: the factory owner and whether implementations are approved. |
## Writes [#writes]
| Action | Description |
| --- | --- |
| [`grantUpgradeSetRoles`](/docs/reference/hca/hca-admin/grant-upgrade-set-roles) | Grants root roles on the HCA upgrade set (role admins only). |
| [`renounceGovernance`](/docs/reference/hca/hca-admin/renounce-governance) | Renounces ownership of the HCA factory, freezing its implementation approvals (factory owner only). |
| [`revokeUpgradeSetRoles`](/docs/reference/hca/hca-admin/revoke-upgrade-set-roles) | Revokes root roles on the HCA upgrade set (role admins only). |
| [`setDeploymentApproval`](/docs/reference/hca/hca-admin/set-deployment-approval) | Approves or revokes an implementation for new HCA deployments (factory owner only). |
| [`setUpgradeApproval`](/docs/reference/hca/hca-admin/set-upgrade-approval) | Approves or revokes an implementation in the HCA upgrade set (role holders only). |
| [`transferGovernance`](/docs/reference/hca/hca-admin/transfer-governance) | Transfers ownership of the HCA factory (factory owner only). |
# hcaAdmin.renounceGovernance
> For the complete documentation index, see [llms.txt](https://ensforge.com/llms.txt).
Renounces ownership of the HCA factory, freezing its implementation approvals (factory owner only). Errors and examples for hcaAdmin.renounceGovernance.
Source: https://ensforge.com/docs/reference/hca/hca-admin/renounce-governance
`@ensforge/hca` is experimental: its API can change in a minor release.
Renounces ownership of the HCA factory, freezing its implementation approvals (factory owner only). Resolves once the transaction is submitted.
## When to use [#when-to-use]
Use to make the set of deployable HCA implementations permanent.
## Signature [#signature]
```ts
function renounceGovernance(
client: Like,
options: renounceGovernance.Options & Write.Options,
): Promise
```
Call it as `ens.hcaAdmin.renounceGovernance(options)` on a client, or `Actions.hcaAdmin.renounceGovernance(client, options)`.
## Parameters [#parameters]
Also takes the [write options](/docs/reference/sdk/client#write-options).
## Returns [#returns]
Resolves to `Write.Result`. Submitted transaction hashes and the plan that produced them.
| Field | Type | Description |
| --- | --- | --- |
| `hash` | `Hex` | Hash of the last transaction. |
| `hashes` | `readonly Hex[]` | Every submitted transaction, in order. |
| `id` | `string` | EIP-5792 bundle id when the calls were sent as one batch. |
| `plan` | `Plan` | The plan the write executed: its steps, in order, as they were submitted. |
## Errors [#errors]
| Error | Codes | When |
| --- | --- | --- |
| [`HcaError`](/docs/reference/errors/hca-error) | [`HCA_UNAVAILABLE`](/docs/reference/errors/HCA_UNAVAILABLE) | on chains without an HCA deployment. |
It can also fail with the errors every write can (`Errors.WriteError`: the common errors plus `InsufficientFundsError`, `TransactionError`, `UnsupportedError`, `UserRejectedError`, `WalletError`).
See [How errors work](/docs/sdk/errors-explained).
## Examples [#examples]
```ts title="Renouncing the factory"
const { hash } = await ens.hcaAdmin.renounceGovernance({})
```
```ts title="Renouncing the factory with a standalone call"
import { Actions } from "@ensforge/hca"
await Actions.hcaAdmin.renounceGovernance(ens, {})
```
```ts title="Renouncing the factory in an Effect program"
import { Actions } from "@ensforge/hca/effect"
yield* Actions.hcaAdmin.renounceGovernance(ens, {})
```
## Plan methods [#plan-methods]
Each method takes the same options as `hcaAdmin.renounceGovernance` and sends nothing. See [Preview before sending](/docs/sdk/preview-before-sending).
| Method | Description |
| --- | --- |
| `hcaAdmin.renounceGovernance.prepare(options)` | Builds the plan without sending anything. |
| `hcaAdmin.renounceGovernance.simulate(options)` | Simulates the plan with `eth_call`, reporting each step. |
| `hcaAdmin.renounceGovernance.estimateGas(options)` | Estimates the gas and ETH the plan needs. |
## Wait for the receipt with `renounceGovernanceSync` [#wait-for-the-receipt-with-renouncegovernancesync]
Renounces ownership of the HCA factory, freezing its implementation approvals (factory owner only). Resolves once the receipt is in.
Use when the next step depends on the change being on-chain.
`hcaAdmin.renounceGovernanceSync` takes the same options plus [`confirmations` and `timeout`](/docs/reference/sdk/client#sync-options).
Resolves to `Write.SyncResult`. Receipts plus the submitted hashes and plan.
```ts title="Renouncing the factory and waiting"
const { receipt } = await ens.hcaAdmin.renounceGovernanceSync({})
```
```ts title="Renouncing the factory with a standalone call and waiting"
import { Actions } from "@ensforge/hca"
await Actions.hcaAdmin.renounceGovernanceSync(ens, {})
```
```ts title="Renouncing the factory in an Effect program and waiting"
import { Actions } from "@ensforge/hca/effect"
yield* Actions.hcaAdmin.renounceGovernanceSync(ens, {})
```
# hcaAdmin.revokeUpgradeSetRoles
> For the complete documentation index, see [llms.txt](https://ensforge.com/llms.txt).
Revokes root roles on the HCA upgrade set (role admins only). Parameters, return value, errors and examples for hcaAdmin.revokeUpgradeSetRoles in @ensforge/hca.
Source: https://ensforge.com/docs/reference/hca/hca-admin/revoke-upgrade-set-roles
`@ensforge/hca` is experimental: its API can change in a minor release.
Revokes root roles on the HCA upgrade set (role admins only). Resolves once the transaction is submitted.
## When to use [#when-to-use]
Use to remove an account's ability to approve HCA upgrade targets.
## Signature [#signature]
```ts
function revokeUpgradeSetRoles(
client: Like,
options: revokeUpgradeSetRoles.Options & Write.Options,
): Promise
```
Call it as `ens.hcaAdmin.revokeUpgradeSetRoles(options)` on a client, or `Actions.hcaAdmin.revokeUpgradeSetRoles(client, options)`.
## Parameters [#parameters]
| Option | Type | Default | Description |
| --- | --- | --- | --- |
| `grantee` (required) | `string` | | Account to revoke. |
| `roles` (required) | `bigint` | | Role bitmap. |
Also takes the [write options](/docs/reference/sdk/client#write-options).
## Returns [#returns]
Resolves to `Write.Result`. Submitted transaction hashes and the plan that produced them.
| Field | Type | Description |
| --- | --- | --- |
| `hash` | `Hex` | Hash of the last transaction. |
| `hashes` | `readonly Hex[]` | Every submitted transaction, in order. |
| `id` | `string` | EIP-5792 bundle id when the calls were sent as one batch. |
| `plan` | `Plan` | The plan the write executed: its steps, in order, as they were submitted. |
## Errors [#errors]
| Error | Codes | When |
| --- | --- | --- |
| [`InvalidInputError`](/docs/reference/errors/invalid-input-error) | [`INVALID_ADDRESS`](/docs/reference/errors/INVALID_ADDRESS) | an invalid address. |
| [`HcaError`](/docs/reference/errors/hca-error) | [`HCA_UNAVAILABLE`](/docs/reference/errors/HCA_UNAVAILABLE) | on chains without an HCA deployment. |
It can also fail with the errors every write can (`Errors.WriteError`: the common errors plus `InsufficientFundsError`, `TransactionError`, `UnsupportedError`, `UserRejectedError`, `WalletError`).
See [How errors work](/docs/sdk/errors-explained).
## Examples [#examples]
```ts title="Revoking upgrade-set roles"
const { hash } = await ens.hcaAdmin.revokeUpgradeSetRoles({ grantee, roles })
```
```ts title="Revoking upgrade-set roles with a standalone call"
import { Actions } from "@ensforge/hca"
await Actions.hcaAdmin.revokeUpgradeSetRoles(ens, { grantee, roles })
```
```ts title="Revoking upgrade-set roles in an Effect program"
import { Actions } from "@ensforge/hca/effect"
yield* Actions.hcaAdmin.revokeUpgradeSetRoles(ens, { grantee, roles })
```
## Plan methods [#plan-methods]
Each method takes the same options as `hcaAdmin.revokeUpgradeSetRoles` and sends nothing. See [Preview before sending](/docs/sdk/preview-before-sending).
| Method | Description |
| --- | --- |
| `hcaAdmin.revokeUpgradeSetRoles.prepare(options)` | Builds the plan without sending anything. |
| `hcaAdmin.revokeUpgradeSetRoles.simulate(options)` | Simulates the plan with `eth_call`, reporting each step. |
| `hcaAdmin.revokeUpgradeSetRoles.estimateGas(options)` | Estimates the gas and ETH the plan needs. |
## Wait for the receipt with `revokeUpgradeSetRolesSync` [#wait-for-the-receipt-with-revokeupgradesetrolessync]
Revokes root roles on the HCA upgrade set (role admins only). Resolves once the receipt is in.
Use when the next step depends on the change being on-chain.
`hcaAdmin.revokeUpgradeSetRolesSync` takes the same options plus [`confirmations` and `timeout`](/docs/reference/sdk/client#sync-options).
Resolves to `Write.SyncResult`. Receipts plus the submitted hashes and plan.
```ts title="Revoking upgrade-set roles and waiting"
const { receipt } = await ens.hcaAdmin.revokeUpgradeSetRolesSync({ grantee, roles })
```
```ts title="Revoking upgrade-set roles with a standalone call and waiting"
import { Actions } from "@ensforge/hca"
await Actions.hcaAdmin.revokeUpgradeSetRolesSync(ens, { grantee, roles })
```
```ts title="Revoking upgrade-set roles in an Effect program and waiting"
import { Actions } from "@ensforge/hca/effect"
yield* Actions.hcaAdmin.revokeUpgradeSetRolesSync(ens, { grantee, roles })
```
# hcaAdmin.setDeploymentApproval
> For the complete documentation index, see [llms.txt](https://ensforge.com/llms.txt).
Approves or revokes an implementation for new HCA deployments (factory owner only). Options, result, errors and examples for hcaAdmin.setDeploymentApproval.
Source: https://ensforge.com/docs/reference/hca/hca-admin/set-deployment-approval
`@ensforge/hca` is experimental: its API can change in a minor release.
Approves or revokes an implementation for new HCA deployments (factory owner only). Resolves once the transaction is submitted.
## When to use [#when-to-use]
Use when the DAO adds or retires an HCA implementation for new accounts.
## Signature [#signature]
```ts
function setDeploymentApproval(
client: Like,
options: setDeploymentApproval.Options & Write.Options,
): Promise
```
Call it as `ens.hcaAdmin.setDeploymentApproval(options)` on a client, or `Actions.hcaAdmin.setDeploymentApproval(client, options)`.
## Parameters [#parameters]
| Option | Type | Default | Description |
| --- | --- | --- | --- |
| `implementation` (required) | `string` | | HCA implementation. |
| `approved` (required) | `boolean` | | `true` to approve, `false` to revoke. |
Also takes the [write options](/docs/reference/sdk/client#write-options).
## Returns [#returns]
Resolves to `Write.Result`. Submitted transaction hashes and the plan that produced them.
| Field | Type | Description |
| --- | --- | --- |
| `hash` | `Hex` | Hash of the last transaction. |
| `hashes` | `readonly Hex[]` | Every submitted transaction, in order. |
| `id` | `string` | EIP-5792 bundle id when the calls were sent as one batch. |
| `plan` | `Plan` | The plan the write executed: its steps, in order, as they were submitted. |
## Errors [#errors]
| Error | Codes | When |
| --- | --- | --- |
| [`InvalidInputError`](/docs/reference/errors/invalid-input-error) | [`INVALID_ADDRESS`](/docs/reference/errors/INVALID_ADDRESS) | an invalid address. |
| [`HcaError`](/docs/reference/errors/hca-error) | [`HCA_UNAVAILABLE`](/docs/reference/errors/HCA_UNAVAILABLE) | on chains without an HCA deployment. |
It can also fail with the errors every write can (`Errors.WriteError`: the common errors plus `InsufficientFundsError`, `TransactionError`, `UnsupportedError`, `UserRejectedError`, `WalletError`).
See [How errors work](/docs/sdk/errors-explained).
## Examples [#examples]
```ts title="Approving an implementation"
const { hash } = await ens.hcaAdmin.setDeploymentApproval({ implementation, approved: true })
```
```ts title="Approving an implementation with a standalone call"
import { Actions } from "@ensforge/hca"
await Actions.hcaAdmin.setDeploymentApproval(ens, { implementation, approved: true })
```
```ts title="Approving an implementation in an Effect program"
import { Actions } from "@ensforge/hca/effect"
yield* Actions.hcaAdmin.setDeploymentApproval(ens, { implementation, approved: true })
```
## Plan methods [#plan-methods]
Each method takes the same options as `hcaAdmin.setDeploymentApproval` and sends nothing. See [Preview before sending](/docs/sdk/preview-before-sending).
| Method | Description |
| --- | --- |
| `hcaAdmin.setDeploymentApproval.prepare(options)` | Builds the plan without sending anything. |
| `hcaAdmin.setDeploymentApproval.simulate(options)` | Simulates the plan with `eth_call`, reporting each step. |
| `hcaAdmin.setDeploymentApproval.estimateGas(options)` | Estimates the gas and ETH the plan needs. |
## Wait for the receipt with `setDeploymentApprovalSync` [#wait-for-the-receipt-with-setdeploymentapprovalsync]
Approves or revokes an implementation for new HCA deployments (factory owner only). Resolves once the receipt is in.
Use when the next step depends on the change being on-chain.
`hcaAdmin.setDeploymentApprovalSync` takes the same options plus [`confirmations` and `timeout`](/docs/reference/sdk/client#sync-options).
Resolves to `Write.SyncResult`. Receipts plus the submitted hashes and plan.
```ts title="Approving an implementation and waiting"
const { receipt } = await ens.hcaAdmin.setDeploymentApprovalSync({ implementation, approved: true })
```
```ts title="Approving an implementation with a standalone call and waiting"
import { Actions } from "@ensforge/hca"
await Actions.hcaAdmin.setDeploymentApprovalSync(ens, { implementation, approved: true })
```
```ts title="Approving an implementation in an Effect program and waiting"
import { Actions } from "@ensforge/hca/effect"
yield* Actions.hcaAdmin.setDeploymentApprovalSync(ens, { implementation, approved: true })
```
# hcaAdmin.setUpgradeApproval
> For the complete documentation index, see [llms.txt](https://ensforge.com/llms.txt).
Approves or revokes an implementation in the HCA upgrade set (role holders only). Options, result, errors and examples for hcaAdmin.setUpgradeApproval.
Source: https://ensforge.com/docs/reference/hca/hca-admin/set-upgrade-approval
`@ensforge/hca` is experimental: its API can change in a minor release.
Approves or revokes an implementation in the HCA upgrade set (role holders only). Resolves once the transaction is submitted.
## When to use [#when-to-use]
Use when the DAO allows existing HCAs to upgrade to an implementation, or withdraws that.
## Signature [#signature]
```ts
function setUpgradeApproval(
client: Like,
options: setUpgradeApproval.Options & Write.Options,
): Promise
```
Call it as `ens.hcaAdmin.setUpgradeApproval(options)` on a client, or `Actions.hcaAdmin.setUpgradeApproval(client, options)`.
## Parameters [#parameters]
| Option | Type | Default | Description |
| --- | --- | --- | --- |
| `implementation` (required) | `string` | | HCA implementation. |
| `approved` (required) | `boolean` | | `true` to approve, `false` to revoke. |
Also takes the [write options](/docs/reference/sdk/client#write-options).
## Returns [#returns]
Resolves to `Write.Result`. Submitted transaction hashes and the plan that produced them.
| Field | Type | Description |
| --- | --- | --- |
| `hash` | `Hex` | Hash of the last transaction. |
| `hashes` | `readonly Hex[]` | Every submitted transaction, in order. |
| `id` | `string` | EIP-5792 bundle id when the calls were sent as one batch. |
| `plan` | `Plan` | The plan the write executed: its steps, in order, as they were submitted. |
## Errors [#errors]
| Error | Codes | When |
| --- | --- | --- |
| [`InvalidInputError`](/docs/reference/errors/invalid-input-error) | [`INVALID_ADDRESS`](/docs/reference/errors/INVALID_ADDRESS) | an invalid address. |
| [`HcaError`](/docs/reference/errors/hca-error) | [`HCA_UNAVAILABLE`](/docs/reference/errors/HCA_UNAVAILABLE) | on chains without an HCA deployment. |
It can also fail with the errors every write can (`Errors.WriteError`: the common errors plus `InsufficientFundsError`, `TransactionError`, `UnsupportedError`, `UserRejectedError`, `WalletError`).
See [How errors work](/docs/sdk/errors-explained).
## Examples [#examples]
```ts title="Allowing an upgrade target"
const { hash } = await ens.hcaAdmin.setUpgradeApproval({ implementation, approved: true })
```
```ts title="Allowing an upgrade target with a standalone call"
import { Actions } from "@ensforge/hca"
await Actions.hcaAdmin.setUpgradeApproval(ens, { implementation, approved: true })
```
```ts title="Allowing an upgrade target in an Effect program"
import { Actions } from "@ensforge/hca/effect"
yield* Actions.hcaAdmin.setUpgradeApproval(ens, { implementation, approved: true })
```
## Plan methods [#plan-methods]
Each method takes the same options as `hcaAdmin.setUpgradeApproval` and sends nothing. See [Preview before sending](/docs/sdk/preview-before-sending).
| Method | Description |
| --- | --- |
| `hcaAdmin.setUpgradeApproval.prepare(options)` | Builds the plan without sending anything. |
| `hcaAdmin.setUpgradeApproval.simulate(options)` | Simulates the plan with `eth_call`, reporting each step. |
| `hcaAdmin.setUpgradeApproval.estimateGas(options)` | Estimates the gas and ETH the plan needs. |
## Wait for the receipt with `setUpgradeApprovalSync` [#wait-for-the-receipt-with-setupgradeapprovalsync]
Approves or revokes an implementation in the HCA upgrade set (role holders only). Resolves once the receipt is in.
Use when the next step depends on the change being on-chain.
`hcaAdmin.setUpgradeApprovalSync` takes the same options plus [`confirmations` and `timeout`](/docs/reference/sdk/client#sync-options).
Resolves to `Write.SyncResult`. Receipts plus the submitted hashes and plan.
```ts title="Allowing an upgrade target and waiting"
const { receipt } = await ens.hcaAdmin.setUpgradeApprovalSync({ implementation, approved: true })
```
```ts title="Allowing an upgrade target with a standalone call and waiting"
import { Actions } from "@ensforge/hca"
await Actions.hcaAdmin.setUpgradeApprovalSync(ens, { implementation, approved: true })
```
```ts title="Allowing an upgrade target in an Effect program and waiting"
import { Actions } from "@ensforge/hca/effect"
yield* Actions.hcaAdmin.setUpgradeApprovalSync(ens, { implementation, approved: true })
```
# hcaAdmin.transferGovernance
> For the complete documentation index, see [llms.txt](https://ensforge.com/llms.txt).
Transfers ownership of the HCA factory (factory owner only). Parameters, return value, errors and examples for hcaAdmin.transferGovernance in @ensforge/hca.
Source: https://ensforge.com/docs/reference/hca/hca-admin/transfer-governance
`@ensforge/hca` is experimental: its API can change in a minor release.
Transfers ownership of the HCA factory (factory owner only). Resolves once the transaction is submitted.
## When to use [#when-to-use]
Use when governance of HCA deployments moves to another account, e.g. the DAO timelock.
## Signature [#signature]
```ts
function transferGovernance(
client: Like,
options: transferGovernance.Options & Write.Options,
): Promise
```
Call it as `ens.hcaAdmin.transferGovernance(options)` on a client, or `Actions.hcaAdmin.transferGovernance(client, options)`.
## Parameters [#parameters]
| Option | Type | Default | Description |
| --- | --- | --- | --- |
| `newOwner` (required) | `string` | | New factory owner. |
Also takes the [write options](/docs/reference/sdk/client#write-options).
## Returns [#returns]
Resolves to `Write.Result`. Submitted transaction hashes and the plan that produced them.
| Field | Type | Description |
| --- | --- | --- |
| `hash` | `Hex` | Hash of the last transaction. |
| `hashes` | `readonly Hex[]` | Every submitted transaction, in order. |
| `id` | `string` | EIP-5792 bundle id when the calls were sent as one batch. |
| `plan` | `Plan` | The plan the write executed: its steps, in order, as they were submitted. |
## Errors [#errors]
| Error | Codes | When |
| --- | --- | --- |
| [`InvalidInputError`](/docs/reference/errors/invalid-input-error) | [`INVALID_ADDRESS`](/docs/reference/errors/INVALID_ADDRESS) | an invalid address. |
| [`HcaError`](/docs/reference/errors/hca-error) | [`HCA_UNAVAILABLE`](/docs/reference/errors/HCA_UNAVAILABLE) | on chains without an HCA deployment. |
It can also fail with the errors every write can (`Errors.WriteError`: the common errors plus `InsufficientFundsError`, `TransactionError`, `UnsupportedError`, `UserRejectedError`, `WalletError`).
See [How errors work](/docs/sdk/errors-explained).
## Examples [#examples]
```ts title="Transferring the factory"
const { hash } = await ens.hcaAdmin.transferGovernance({ newOwner })
```
```ts title="Transferring the factory with a standalone call"
import { Actions } from "@ensforge/hca"
await Actions.hcaAdmin.transferGovernance(ens, { newOwner })
```
```ts title="Transferring the factory in an Effect program"
import { Actions } from "@ensforge/hca/effect"
yield* Actions.hcaAdmin.transferGovernance(ens, { newOwner })
```
## Plan methods [#plan-methods]
Each method takes the same options as `hcaAdmin.transferGovernance` and sends nothing. See [Preview before sending](/docs/sdk/preview-before-sending).
| Method | Description |
| --- | --- |
| `hcaAdmin.transferGovernance.prepare(options)` | Builds the plan without sending anything. |
| `hcaAdmin.transferGovernance.simulate(options)` | Simulates the plan with `eth_call`, reporting each step. |
| `hcaAdmin.transferGovernance.estimateGas(options)` | Estimates the gas and ETH the plan needs. |
## Wait for the receipt with `transferGovernanceSync` [#wait-for-the-receipt-with-transfergovernancesync]
Transfers ownership of the HCA factory (factory owner only). Resolves once the receipt is in.
Use when the next step depends on the change being on-chain.
`hcaAdmin.transferGovernanceSync` takes the same options plus [`confirmations` and `timeout`](/docs/reference/sdk/client#sync-options).
Resolves to `Write.SyncResult`. Receipts plus the submitted hashes and plan.
```ts title="Transferring the factory and waiting"
const { receipt } = await ens.hcaAdmin.transferGovernanceSync({ newOwner })
```
```ts title="Transferring the factory with a standalone call and waiting"
import { Actions } from "@ensforge/hca"
await Actions.hcaAdmin.transferGovernanceSync(ens, { newOwner })
```
```ts title="Transferring the factory in an Effect program and waiting"
import { Actions } from "@ensforge/hca/effect"
yield* Actions.hcaAdmin.transferGovernanceSync(ens, { newOwner })
```
# HCA
> For the complete documentation index, see [llms.txt](https://ensforge.com/llms.txt).
Browse every action of the experimental @ensforge/hca package by domain, plus the route and executors that send hosted contract account calls.
Source: https://ensforge.com/docs/reference/hca
`@ensforge/hca` is experimental: its API can change in a minor release.
Every action of `@ensforge/hca`, by domain, and the executors that send them.
## [hca](/docs/reference/hca/hca) [#hca]
| Action | Description |
| --- | --- |
| [`addDeposit`](/docs/reference/hca/hca/add-deposit) | Adds ETH to an HCA's ERC-4337 EntryPoint deposit. |
| [`authorizeSession`](/docs/reference/hca/hca/authorize-session) | Asks the owner to approve a session key for their HCA, with one signature and no transaction. |
| [`checkSessionCalls`](/docs/reference/hca/hca/check-session-calls) (batchable) | Checks calls against the HCA session policy before anything is signed. |
| [`deploy`](/docs/reference/hca/hca/deploy) | Deploys the signer's HCA through the ENS factory. |
| [`execute`](/docs/reference/hca/hca/execute) | Runs calls from the signer's HCA as one atomic execution. |
| [`get`](/docs/reference/hca/hca/get) (batchable) | Reads an ENS HCA (Hosted Contract Account): its address, owner, implementation, session nonce and verification problems. |
| [`getDeposit`](/docs/reference/hca/hca/get-deposit) (batchable) | Reads an HCA's ERC-4337 EntryPoint deposit, which pays for its UserOperations without a paymaster. |
| [`getSession`](/docs/reference/hca/hca/get-session) (batchable) | Checks whether a stored HCA session can still be used. |
| [`getUpgrade`](/docs/reference/hca/hca/get-upgrade) (batchable) | Checks whether an HCA may upgrade to an implementation: it must be in the DAO's upgrade set and accept the current implementation. |
| [`predictAddress`](/docs/reference/hca/hca/predict-address) (batchable) | Computes the address of an owner's ENS HCA, deployed or not. |
| [`revokeSessions`](/docs/reference/hca/hca/revoke-sessions) | Invalidates every session approval of the signer's HCA. |
| [`upgrade`](/docs/reference/hca/hca/upgrade) | Upgrades the signer's HCA to an implementation the DAO's upgrade set and its own `canUpgradeFrom` check allow. |
| [`verify`](/docs/reference/hca/hca/verify) (batchable) | Checks that an address is a usable ENS HCA of its owner, and returns it. |
| [`withdrawDeposit`](/docs/reference/hca/hca/withdraw-deposit) | Withdraws ETH from the signer's HCA EntryPoint deposit. |
## [hcaAdmin](/docs/reference/hca/hca-admin) [#hcaadmin]
| Action | Description |
| --- | --- |
| [`getGovernance`](/docs/reference/hca/hca-admin/get-governance) (batchable) | Reads who governs ENS HCAs: the factory owner and whether implementations are approved. |
| [`grantUpgradeSetRoles`](/docs/reference/hca/hca-admin/grant-upgrade-set-roles) | Grants root roles on the HCA upgrade set (role admins only). |
| [`renounceGovernance`](/docs/reference/hca/hca-admin/renounce-governance) | Renounces ownership of the HCA factory, freezing its implementation approvals (factory owner only). |
| [`revokeUpgradeSetRoles`](/docs/reference/hca/hca-admin/revoke-upgrade-set-roles) | Revokes root roles on the HCA upgrade set (role admins only). |
| [`setDeploymentApproval`](/docs/reference/hca/hca-admin/set-deployment-approval) | Approves or revokes an implementation for new HCA deployments (factory owner only). |
| [`setUpgradeApproval`](/docs/reference/hca/hca-admin/set-upgrade-approval) | Approves or revokes an implementation in the HCA upgrade set (role holders only). |
| [`transferGovernance`](/docs/reference/hca/hca-admin/transfer-governance) | Transfers ownership of the HCA factory (factory owner only). |
# API reference
> For the complete documentation index, see [llms.txt](https://ensforge.com/llms.txt).
Look up every action, hook, contract constant and error code of the ensforge packages, generated from their source and checked on each release.
Source: https://ensforge.com/docs/reference
# Known limitations
> For the complete documentation index, see [llms.txt](https://ensforge.com/llms.txt).
Check the known limits of ensforge 1.0 and of ENS itself, grouped by topic, with what each one means and what to do about it.
Source: https://ensforge.com/docs/reference/known-limitations
These are the places where ensforge 1.0, or the ENS contracts and services it uses, behave in a way
you might not expect. Each entry says what happens and what to do. Most come from how the ENS
protocol works and are not bugs.
## Records and resolvers [#records-and-resolvers]
### Older public resolvers show as `custom` [#older-public-resolvers-show-as-custom]
`resolver.get` reports some older ENS public resolvers, such as the 2020 one, as
`kind: "custom"` with `authorization: "unknown"`. They are not in the deployment's list of known
resolvers, so ensforge cannot prove how they decide who may write.
**What to do:** reading and writing records still works, except kinds of record the resolver
lacks: the 2020 public resolver has no `data` records and cannot `clear`. To use a resolver
ensforge recognises, pass `resolver: "default"` to `record.set` with the records to keep. It writes
them to the current public resolver and points the name at it. Records you do not pass are not
copied.
### Frozen resolvers cannot change records [#frozen-resolvers-cannot-change-records]
Names on three old public resolvers, tied to the registry ENS replaced in 2020, cannot change their
records. `record.set` fails before sending and suggests a new resolver.
**What to do:** pass `resolver` to `record.set` to write the records to a new resolver and point the
name at it in one step.
### The ENSv2 public resolver only serves Name Wrapper names [#the-ensv2-public-resolver-only-serves-name-wrapper-names]
`resolver: "default"` works for ENSv1 names only. On ENSv2 names it fails with
[`UNSUPPORTED_PROTOCOL`](/docs/reference/errors/UNSUPPORTED_PROTOCOL), because the ENSv2 public resolver
only accepts names the Name Wrapper knows.
**What to do:** give the name its own resolver with `resolver.create`.
### Clearing records on a PermissionedResolver shows its default record [#clearing-records-on-a-permissionedresolver-shows-its-default-record]
`record.set({ clear: true })` on an ENSv2 PermissionedResolver links the name to the resolver's
default record. Until new records are written, the name reads that default record, which is empty
unless someone set it.
**What to do:** write the new records in the same `record.set` call as `clear`. ensforge clears
first and writes the new records in the same transaction.
### Shared resolvers share record access [#shared-resolvers-share-record-access]
On a PermissionedResolver used by several names, `permission.setRecordAccess` lets the grantee
edit those records on every name that uses the resolver.
**What to do:** keep one resolver per name, as ensforge does by default. Share a resolver only with
accounts you trust for every name on it.
### Predicted resolver addresses assume the signer sends [#predicted-resolver-addresses-assume-the-signer-sends]
`resolver.create` predicts the new resolver's address from the account that sends the deploy call.
If a relayer or a bundler sends it instead, the resolver lands at another address.
**What to do:** send `resolver.create` from the account itself, or read the address from the
receipt.
### Some coins are not supported [#some-coins-are-not-supported]
EOS (coin type 194) and other coins whose encoders were removed upstream fail with
[`INVALID_COIN_TYPE`](/docs/reference/errors/INVALID_COIN_TYPE) or
[`INVALID_ADDRESS`](/docs/reference/errors/INVALID_ADDRESS).
**What to do:** nothing in ensforge; these coins cannot be encoded.
### XRP addresses can be stored two ways [#xrp-addresses-can-be-stored-two-ways]
An XRP X-address and the r-address of the same account encode to different bytes, so the same
account can be stored in two forms.
**What to do:** pick one form for your app and store addresses in it.
### The default IPFS gateway is rate limited [#the-default-ipfs-gateway-is-rate-limited]
Avatars and website links on IPFS go through `https://ipfs.io` by default, which answers HTTP 429
under load.
**What to do:** set your own gateway with `Ensforge.create({ gateways: { ipfs: "…" } })`. See
[Configure RPC and gateways](/docs/sdk/rpc-and-gateways).
## Writes and plans [#writes-and-plans]
### RPCs without `eth_simulateV1` cannot simulate dependent calls [#rpcs-without-eth_simulatev1-cannot-simulate-dependent-calls]
ensforge simulates a step's calls in sequence with `eth_simulateV1`. On RPCs without it, each call
is simulated alone, so a call that depends on an earlier one in the same step can fail in
simulation although sending would succeed.
**What to do:** use an RPC that supports `eth_simulateV1`, or send that write with
`simulate: false`.
### Plans are kept in memory by default [#plans-are-kept-in-memory-by-default]
The default plan storage loses plans on a page reload, and an aborted write rejects with the abort
reason instead of an error carrying the plan id.
**What to do:** create the client with `storage: Plan.localStorage()` or your own `Plan.Storage`.
Find the id of an aborted plan with `plan.list`. See
[Continue after a failure](/docs/sdk/continue-after-a-failure).
### Wallets differ in bundle size and resuming [#wallets-differ-in-bundle-size-and-resuming]
`maxBundleCalls` defaults to 10, MetaMask's limit. Resuming a bundle sent through EIP-5792 asks the
wallet that sent it, since only that wallet knows the bundle.
**What to do:** lower `maxBundleCalls` for wallets with a smaller limit, and resume with the same
wallet.
## Registration [#registration]
### Registering takes at least a minute [#registering-takes-at-least-a-minute]
`registration.register` commits, waits the registrar's minimum commitment age on chain time (60
seconds on the networks tested), then registers. With a payment approval, a resolver and a primary
name, one name takes four to five transactions.
**What to do:** show progress with `onStep`. A wallet that supports atomic batches bundles each
step's calls. `commit` and a later `register` with the same `secret` split the flow across sessions.
### Contracts that reject ERC-1155 tokens cannot own ENSv2 names [#contracts-that-reject-erc-1155-tokens-cannot-own-ensv2-names]
ENSv2 sends the new name to its owner as an ERC-1155 token. If `owner` is a contract that does not
accept ERC-1155 tokens, the register step reverts after the commit was sent.
**What to do:** register to an account, or to a contract that implements `onERC1155Received`.
## Subnames and registries [#subnames-and-registries]
### An ENSv2 subname's owner cannot be changed from its parent [#an-ensv2-subnames-owner-cannot-be-changed-from-its-parent]
`subname.update({ owner })` on an ENSv2 subname fails with
[`UNSUPPORTED_PROTOCOL`](/docs/reference/errors/UNSUPPORTED_PROTOCOL): only the token holder can transfer
it.
**What to do:** the subname's owner calls `name.transfer`, or the parent removes the subname and
creates it again.
### Subnames created without an expiry cannot get one later [#subnames-created-without-an-expiry-cannot-get-one-later]
ENSv2 subnames never expire by default, and an expiry can only be extended, not added.
`subname.update({ expiry })` on such a subname fails with
[`INVALID_EXPIRY`](/docs/reference/errors/INVALID_EXPIRY).
**What to do:** pass `expiry` to `subname.create` when subnames should lapse.
### Some ENSv2 registries cannot be upgraded [#some-ensv2-registries-cannot-be-upgraded]
Registries created on mainnet before 17 November 2026 run an implementation that the latest one
does not accept. `registry.get` reports `blocker: "not-approved"`, and `registry.upgrade` fails
with [`UPGRADE_NOT_APPROVED`](/docs/reference/errors/UPGRADE_NOT_APPROVED).
**What to do:** nothing until ENS approves an upgrade path. These registries keep working.
## Permissions [#permissions]
### `.eth` owners cannot delegate renewal [#eth-owners-cannot-delegate-renewal]
`role.grant({ roles: ["renew"] })` on a `.eth` name fails with
[`CANNOT_GRANT_ROLES`](/docs/reference/errors/CANNOT_GRANT_ROLES): the `.eth` registrar gives owners no
right to grant it.
**What to do:** nothing is needed. Anyone can renew a `.eth` name with `registration.renew`.
## DNS names [#dns-names]
### DNSSEC proofs do not verify at the moment [#dnssec-proofs-do-not-verify-at-the-moment]
Since the DNS root changed its signing key in October 2026, the ENS DNSSEC oracle no longer accepts
any proof, on mainnet and Sepolia. `dns.getStatus` reports `proof-invalid`, and `dns.claim` fails
with [`DNSSEC_PROOF_FAILED`](/docs/reference/errors/DNSSEC_PROOF_FAILED). Lookups of DNS names that
resolve through a proof, because they have no resolver of their own in ENS (such as
`ens.domains`), fail the same way.
**What to do:** nothing on the client side. This needs ENS to add the new key to its oracle.
### `dns.claim` cannot set an address [#dnsclaim-cannot-set-an-address]
ENS public resolvers refuse the address the DNS registrar would set while claiming.
**What to do:** claim with `resolver` only, then set records with `record.set`.
### DNS names are imported into ENSv1 [#dns-names-are-imported-into-ensv1]
There is no ENSv2 way to claim a second-level DNS name yet. `dns.claim` imports it into ENSv1, and
ENSv2 resolves it from there.
**What to do:** nothing; lookups work as usual.
### DNS reads are not verified [#dns-reads-are-not-verified]
`dns.getProof` and `dns.getOffchainResolver` return what the gateway sends without verifying it,
and ignore `blockNumber` and `blockTag`. `dns.getStatus` does verify the proof.
**What to do:** use `dns.getStatus` when the answer must be trusted.
## Moving names to ENSv2 [#moving-names-to-ensv2]
### Migration needs records and subnames listed without an indexer [#migration-needs-records-and-subnames-listed-without-an-indexer]
Without an indexer, `migration.migrate` cannot discover every record and subname of a name. With
one, it finds them itself, up to 500 subnames across all levels.
**What to do:** create the client with an `indexer`, or pass the records and `subnames` yourself.
See [Move a name to ENSv2](/docs/sdk/move-a-name-to-ensv2).
### Subname records stay where they are [#subname-records-stay-where-they-are]
Migrated subnames keep their records on their ENSv1 resolvers, as in the ENS app. Lookups keep
working: the subnames still point at those resolvers.
**What to do:** nothing for lookups. To give a subname its own ENSv2 resolver, read its records
with `record.get`, then create a resolver with them with `resolver.create({ name, records })`.
### Public keys and DNS records are not copied [#public-keys-and-dns-records-are-not-copied]
ENSv2 PermissionedResolvers have no public key or DNS record types, so migration cannot copy them.
**What to do:** keep a copy before migrating if you need them.
### A name in its grace period migrates as the signer's [#a-name-in-its-grace-period-migrates-as-the-signers]
The registrar hides who held an expired name. With `renew`, ensforge assumes the signer is the
registrant, and checks the transfer again after renewing.
**What to do:** migrate names in grace from the account that held them.
## Events and history [#events-and-history]
### Event history over RPC is bounded [#event-history-over-rpc-is-bounded]
`event.get` needs a block range. Free RPC plans that limit `eth_getLogs` to a few blocks reach the
request budget quickly and fail with
[`LOG_RANGE_TOO_LARGE`](/docs/reference/errors/LOG_RANGE_TOO_LARGE). Some transfers are not scanned:
Name Wrapper token transfers, and `.eth` and root registry transfers beyond 5,000 blocks for
anyone but the current owner.
**What to do:** use `indexer.getHistory` or `indexer.getEvents` for full history. See
[Name history](/docs/sdk/name-history).
## Indexers [#indexers]
### Indexers disagree on some fields [#indexers-disagree-on-some-fields]
bigname and Goldsky answer some fields differently: a name's registration date, the format of
registration ids, and which fields and counts they fill.
**What to do:** compare answers from one indexer only. Every answer says which indexer gave it in
`indexer`.
### Snapshots and finality need bigname [#snapshots-and-finality-need-bigname]
`at` and `finality` exist only on name, records, registry and resolver reads, and only bigname
supports them. Goldsky fails with [`INDEXER_UNSUPPORTED`](/docs/reference/errors/INDEXER_UNSUPPORTED).
bigname answers [`INDEXER_BEHIND`](/docs/reference/errors/INDEXER_BEHIND) when it no longer keeps the
requested snapshot.
**What to do:** use bigname for snapshot reads, and retry without `at` when it is behind.
### Basenames come from Goldsky [#basenames-come-from-goldsky]
bigname does not index Basenames yet, so it reports `INDEXER_UNSUPPORTED` for them.
**What to do:** use `fallback([bigname(), goldsky()])`; Basenames are then served by Goldsky.
### A missing indexer route looks like a missing name [#a-missing-indexer-route-looks-like-a-missing-name]
A server that lacks a route answers like it does for an unknown name, so the call fails with
[`INDEXER_NOT_FOUND`](/docs/reference/errors/INDEXER_NOT_FOUND) instead of `INDEXER_UNSUPPORTED`.
**What to do:** check the indexer's version when a list you expect is not found.
### Custom indexer answers are checked shallowly [#custom-indexer-answers-are-checked-shallowly]
`defineIndexer` checks that answers are objects and that pages have an `items` array. Field types
are trusted to your adapter's TypeScript types.
**What to do:** validate your source's data in the adapter.
### bigname misses some names under new registries [#bigname-misses-some-names-under-new-registries]
Names under a subregistry set at registration on ENSv2 registries created since 17 November 2026
are missing from bigname. Reads from the chain are not affected.
**What to do:** read such names with chain actions until bigname handles them.
### Indexed expiry of ENSv1 names [#indexed-expiry-of-ensv1-names]
For ENSv1 names not yet moved to ENSv2, bigname reports the expiry of the ENSv2 reservation, not of
the `.eth` registration.
**What to do:** use `name.get` for the expiry of an ENSv1 name.
## Smart accounts (HCA) [#smart-accounts-hca]
`@ensforge/hca` is experimental. See [HCA](/docs/hca).
### Bundlers and Rhinestone are not proven in production [#bundlers-and-rhinestone-are-not-proven-in-production]
The bundler route has not been tested against a production bundler in safe mode. The `rhinestone`
executor needs a Rhinestone SDK that supports standalone ENS HCAs, and fails with
`HCA_SDK_UNSUPPORTED` with one that does not.
**What to do:** test these routes on Sepolia before relying on them.
### Writes through an HCA need the HCA's authority [#writes-through-an-hca-need-the-hcas-authority]
Through `via: hca()` the HCA sends the calls. Registration, migration and `hca.execute` work. Other
writes, such as records, roles and transfers, succeed only where the HCA holds the needed
permissions, and fail at simulation otherwise. L2 primary names cannot be sent through an HCA.
**What to do:** use `hca()` for registration and migration, and the owner's wallet for other writes.
### Migrating wrapped names leaves a Name Wrapper approval [#migrating-wrapped-names-leaves-a-name-wrapper-approval]
Wrapped names need the HCA approved as an operator on the Name Wrapper. The plan warns with
`HCA_WRAPPER_APPROVAL`, and the approval stays after migration.
**What to do:** revoke it afterwards with `approval.setOperator`.
### A session on a not-yet-deployed account is not confirmed to work before deployment [#a-session-on-a-not-yet-deployed-account-is-not-confirmed-to-work-before-deployment]
The owner can sign a session for the predicted HCA address before the account is deployed. Whether
the account accepts that session on its first use, before it is deployed, is not confirmed.
**What to do:** deploy the HCA with `hca.deploy` before the session runs.
### Session approvals use Rhinestone's signing format [#session-approvals-use-rhinestones-signing-format]
Session approvals are signed as Rhinestone Smart Session data, which an account with Smart Sessions
installed could also accept.
**What to do:** nothing yet. ENS plans its own signing format for sessions, and ensforge switches
to it once ENS deploys it.
## React server rendering [#react-server-rendering]
### Streamed reads need a serializer that streams promises [#streamed-reads-need-a-serializer-that-streams-promises]
`dehydrate(registry, { streaming: true })` puts a real Promise on every read that is still loading.
TanStack Start's serializer (seroval) sends it, and React Server Components do too. React Router's
turbo-stream should, by its documented behaviour, but this is not verified. A serializer that
writes plain JSON drops the Promise without an error, and the browser then fetches the read itself.
**What to do:** stream only through a serializer that supports promises, or await `prefetch` and
call `dehydrate(registry)` without `streaming`.
## Errors [#errors]
### Route errors are outside a write's error type [#route-errors-are-outside-a-writes-error-type]
A write sent through a `via` route can fail with the route package's own errors, such as
`HcaError`, which are not part of the action's `ErrorType`.
**What to do:** check for `HcaError` too when you send through `hca()`. See
[How errors work](/docs/sdk/errors-explained).
# useAddress
> For the complete documentation index, see [llms.txt](https://ensforge.com/llms.txt).
Reads the address a name points to, for ETH or another coin. Signature, options, result and examples for useAddress in @ensforge/react.
Source: https://ensforge.com/docs/reference/react/use-address
Reads the address a name points to, for ETH or another coin. Preset of `useRead(Actions.record.getAddress, …)`.
It wraps [`record.getAddress`](/docs/reference/sdk/record/get-address): the same options, result and errors.
## Signature [#signature]
```ts
function useAddress(options: Actions.record.getAddress.Options | undefined, config?: ReadConfig): ReadResult
```
## Examples [#examples]
```tsx title="Reading in a component"
import { useAddress } from "@ensforge/react"
function View() {
const { data: address } = useAddress({ name: "nick.eth" })
return {address}
}
```
## See also [#see-also]
- The [hook types](/docs/reference/react#types): `ReadResult`, `WriteResult` and `ReadConfig`.
# useAvailability
> For the complete documentation index, see [llms.txt](https://ensforge.com/llms.txt).
Checks whether a name can be registered now. Signature, options, result and examples for useAvailability in @ensforge/react.
Source: https://ensforge.com/docs/reference/react/use-availability
Checks whether a name can be registered now. Preset of `useRead(Actions.registration.isAvailable, …)`.
It wraps [`registration.isAvailable`](/docs/reference/sdk/registration/is-available): the same options, result and errors.
## Signature [#signature]
```ts
function useAvailability(options: Actions.registration.isAvailable.Options | undefined, config?: ReadConfig): ReadResult< Actions.registration.isAvailable.ReturnType, Actions.registration.isAvailable.ErrorType >
```
## Examples [#examples]
```tsx title="Reading in a component"
import { useAvailability } from "@ensforge/react"
function View() {
const { data: available } = useAvailability({ name: "alice.eth" })
return {String(available)}
}
```
## See also [#see-also]
- The [hook types](/docs/reference/react#types): `ReadResult`, `WriteResult` and `ReadConfig`.
# useAvatar
> For the complete documentation index, see [llms.txt](https://ensforge.com/llms.txt).
Reads a name's avatar as an image URL, with NFT avatars resolved. Signature, options, result and examples for useAvatar in @ensforge/react.
Source: https://ensforge.com/docs/reference/react/use-avatar
Reads a name's avatar as an image URL, with NFT avatars resolved. Preset of `useRead(Actions.record.getAvatar, …)`.
It wraps [`record.getAvatar`](/docs/reference/sdk/record/get-avatar): the same options, result and errors.
## Signature [#signature]
```ts
function useAvatar(options: Actions.record.getAvatar.Options | undefined, config?: ReadConfig): ReadResult
```
## Examples [#examples]
```tsx title="Reading in a component"
import { useAvatar } from "@ensforge/react"
function View() {
const { data: avatar } = useAvatar({ name: "nick.eth" })
return
}
```
## See also [#see-also]
- The [hook types](/docs/reference/react#types): `ReadResult`, `WriteResult` and `ReadConfig`.
# useCreateSubname
> For the complete documentation index, see [llms.txt](https://ensforge.com/llms.txt).
Creates a subname, optionally with records. Signature, options, result and examples for useCreateSubname in @ensforge/react.
Source: https://ensforge.com/docs/reference/react/use-create-subname
Creates a subname, optionally with records. Preset of `useWrite(Actions.subname.create)`.
It wraps [`subname.create`](/docs/reference/sdk/subname/create): the same options, result and errors.
## Signature [#signature]
```ts
function useCreateSubname(config?: Parameters[1]): WriteResult< Parameters[1], Actions.subname.create.ReturnType, Actions.subname.create.ErrorType >
```
## Examples [#examples]
```tsx title="A button that sends it"
import { useCreateSubname } from "@ensforge/react"
function Send() {
const { mutate, isPending } = useCreateSubname()
return
}
```
## See also [#see-also]
- The [hook types](/docs/reference/react#types): `ReadResult`, `WriteResult` and `ReadConfig`.
# useEnsforge
> For the complete documentation index, see [llms.txt](https://ensforge.com/llms.txt).
The client of the nearest EnsforgeProvider. Signature, options, result and examples for useEnsforge in @ensforge/react. Includes examples.
Source: https://ensforge.com/docs/reference/react/use-ensforge
The client of the nearest `EnsforgeProvider`.
## Signature [#signature]
```ts
function useEnsforge(): Ensforge.Client
```
## Examples [#examples]
```tsx title="Calling an action from an event handler"
import { Actions } from "@ensforge/sdk"
import { useEnsforge } from "@ensforge/react"
function Check({ name }: { name: string }) {
const ens = useEnsforge()
return
}
```
## See also [#see-also]
- The [hook types](/docs/reference/react#types): `ReadResult`, `WriteResult` and `ReadConfig`.
# useInfiniteRead
> For the complete documentation index, see [llms.txt](https://ensforge.com/llms.txt).
Reads an indexer list page by page, such as a name's subnames or an account's names. Signature, result and examples for useInfiniteRead.
Source: https://ensforge.com/docs/reference/react/use-infinite-read
Reads an indexer list page by page, such as a name's subnames or an account's names.
## When to use [#when-to-use]
Use for "load more" lists and infinite scroll. A write touching the list's name or account
starts it over once the indexer has caught up. Pass `undefined` options (or `enabled: false`)
to wait, e.g. until a name is typed.
## Signature [#signature]
```ts
function useInfiniteRead(action: action, options: Omit, "cursor"> | undefined, config: { /** * Load the list. Passing `undefined` options also disables it. * * @default true */ readonly enabled?: boolean | undefined; readonly client?: Ensforge.Client | undefined; } = {}): InfiniteReadResult, ActionError>
```
## Examples [#examples]
```tsx title="Subnames with \"Load more\""
import { Actions } from "@ensforge/sdk"
import { useInfiniteRead } from "@ensforge/react"
function Subnames({ name }: { name: string }) {
const { items, hasMore, loadMore } = useInfiniteRead(Actions.indexer.getSubnames, { name })
return (
<>
{items.map((item) =>
{item.name}
)}
{hasMore && }
>
)
}
```
## See also [#see-also]
- The [hook types](/docs/reference/react#types): `ReadResult`, `WriteResult` and `ReadConfig`.
# useMigrate
> For the complete documentation index, see [llms.txt](https://ensforge.com/llms.txt).
Moves names from ENSv1 to ENSv2. Signature, options, result and examples for useMigrate in @ensforge/react. Signature, result and examples for useMigrate.
Source: https://ensforge.com/docs/reference/react/use-migrate
Moves names from ENSv1 to ENSv2. Preset of `useWrite(Actions.migration.migrate)`.
It wraps [`migration.migrate`](/docs/reference/sdk/migration/migrate): the same options, result and errors.
## Signature [#signature]
```ts
function useMigrate(config?: Parameters[1]): WriteResult< Parameters[1], Actions.migration.migrate.ReturnType, Actions.migration.migrate.ErrorType >
```
## Examples [#examples]
```tsx title="A button that sends it"
import { useMigrate } from "@ensforge/react"
function Send() {
const { mutate, isPending } = useMigrate()
return
}
```
## See also [#see-also]
- The [hook types](/docs/reference/react#types): `ReadResult`, `WriteResult` and `ReadConfig`.
# useMigrationStatus
> For the complete documentation index, see [llms.txt](https://ensforge.com/llms.txt).
Reads whether and how a name can move from ENSv1 to ENSv2. Signature, options, result and examples for useMigrationStatus in @ensforge/react.
Source: https://ensforge.com/docs/reference/react/use-migration-status
Reads whether and how a name can move from ENSv1 to ENSv2. Preset of `useRead(Actions.migration.get, …)`.
It wraps [`migration.get`](/docs/reference/sdk/migration/get): the same options, result and errors.
## Signature [#signature]
```ts
function useMigrationStatus(options: Actions.migration.get.Options | undefined, config?: ReadConfig): ReadResult
```
## Examples [#examples]
```tsx title="Reading in a component"
import { useMigrationStatus } from "@ensforge/react"
function View() {
const { data: migration } = useMigrationStatus({ name: "alice.eth" })
return {migration?.status}
}
```
## See also [#see-also]
- The [hook types](/docs/reference/react#types): `ReadResult`, `WriteResult` and `ReadConfig`.
# useNameHistory
> For the complete documentation index, see [llms.txt](https://ensforge.com/llms.txt).
Lists a name's events (registrations, transfers, record changes), page by page, from the indexer. Signature, result and examples for useNameHistory.
Source: https://ensforge.com/docs/reference/react/use-name-history
Lists a name's events (registrations, transfers, record changes), page by page, from the indexer. Preset of `useInfiniteRead(Actions.indexer.getHistory, …)`.
It wraps [`indexer.getHistory`](/docs/reference/sdk/indexer/get-history): the same options, result and errors.
## Signature [#signature]
```ts
function useNameHistory(options: Omit, config?: { readonly client?: ReadConfig["client"] }): InfiniteReadResult< Actions.indexer.getHistory.ReturnType, Actions.indexer.getHistory.ErrorType >
```
## Examples [#examples]
```tsx title="A list with \"Load more\""
import { useNameHistory } from "@ensforge/react"
function List() {
const { items, hasMore, loadMore } = useNameHistory({ name: "nick.eth" })
return
}
```
## See also [#see-also]
- The [hook types](/docs/reference/react#types): `ReadResult`, `WriteResult` and `ReadConfig`.
# useName
> For the complete documentation index, see [llms.txt](https://ensforge.com/llms.txt).
Reads a name's state: owner, manager, expiry, resolver, registry and wrapper status. Signature, options, result and examples for useName in @ensforge/react.
Source: https://ensforge.com/docs/reference/react/use-name
Reads a name's state: owner, manager, expiry, resolver, registry and wrapper status. Preset of `useRead(Actions.name.get, …)`.
It wraps [`name.get`](/docs/reference/sdk/name/get): the same options, result and errors.
## Signature [#signature]
```ts
function useName(options: Actions.name.get.Options | undefined, config?: ReadConfig): ReadResult
```
## Examples [#examples]
```tsx title="Reading in a component"
import { useName } from "@ensforge/react"
function View() {
const { data } = useName({ name: "nick.eth" })
return {data?.owner}
}
```
## See also [#see-also]
- The [hook types](/docs/reference/react#types): `ReadResult`, `WriteResult` and `ReadConfig`.
# useNamesForAddress
> For the complete documentation index, see [llms.txt](https://ensforge.com/llms.txt).
Lists the names an address owns, manages or is the primary name of, page by page, from the indexer. Signature, result and examples for useNamesForAddress.
Source: https://ensforge.com/docs/reference/react/use-names-for-address
Lists the names an address owns, manages or is the primary name of, page by page, from the indexer. Preset of `useInfiniteRead(Actions.indexer.getNamesForAddress, …)`.
It wraps [`indexer.getNamesForAddress`](/docs/reference/sdk/indexer/get-names-for-address): the same options, result and errors.
## Signature [#signature]
```ts
function useNamesForAddress(options: Omit, config?: { readonly client?: ReadConfig["client"] }): InfiniteReadResult< Actions.indexer.getNamesForAddress.ReturnType, Actions.indexer.getNamesForAddress.ErrorType >
```
## Examples [#examples]
```tsx title="A list with \"Load more\""
import { useNamesForAddress } from "@ensforge/react"
function List() {
const { items, hasMore, loadMore } = useNamesForAddress({ address })
return
}
```
## See also [#see-also]
- The [hook types](/docs/reference/react#types): `ReadResult`, `WriteResult` and `ReadConfig`.
# usePermissions
> For the complete documentation index, see [llms.txt](https://ensforge.com/llms.txt).
Reads what an account may do with a name. Signature, options, result and examples for usePermissions in @ensforge/react.
Source: https://ensforge.com/docs/reference/react/use-permissions
Reads what an account may do with a name. Preset of `useRead(Actions.permission.get, …)`.
It wraps [`permission.get`](/docs/reference/sdk/permission/get): the same options, result and errors.
## Signature [#signature]
```ts
function usePermissions(options: Actions.permission.get.Options | undefined, config?: ReadConfig): ReadResult
```
## Examples [#examples]
```tsx title="Reading in a component"
import { usePermissions } from "@ensforge/react"
function View() {
const { data: permissions } = usePermissions({ name: "alice.eth", account: address })
return {String(permissions?.can.setRecords)}
}
```
## See also [#see-also]
- The [hook types](/docs/reference/react#types): `ReadResult`, `WriteResult` and `ReadConfig`.
# usePrepare
> For the complete documentation index, see [llms.txt](https://ensforge.com/llms.txt).
Plans a write without sending it: its steps, calls and warnings, for a review screen before the wallet prompt. Signature, result and examples for usePrepare.
Source: https://ensforge.com/docs/reference/react/use-prepare
Plans a write without sending it: its steps, calls and warnings, for a review screen before
the wallet prompt.
## When to use [#when-to-use]
Use to show what a write will do (how many transactions, approvals, warnings) and to disable
the submit button while it cannot be planned, e.g. when the account lacks permission.
## Signature [#signature]
```ts
function usePrepare(action: action, options: ActionOptions | undefined, config?: ReadConfig): ReadResult>
```
## Examples [#examples]
```tsx title="Reviewing a records update"
import { Actions } from "@ensforge/sdk"
import { usePrepare } from "@ensforge/react"
function Review({ name, url }: { name: string; url: string }) {
const { data: plan, error } = usePrepare(Actions.record.set, { name, texts: { url } })
if (error) return
{error.message}
return
{plan?.steps.length} transaction(s)
}
```
## See also [#see-also]
- The [hook types](/docs/reference/react#types): `ReadResult`, `WriteResult` and `ReadConfig`.
# usePrimaryName
> For the complete documentation index, see [llms.txt](https://ensforge.com/llms.txt).
Reads the primary name of an address, verified against its forward address. Signature, options, result and examples for usePrimaryName in @ensforge/react.
Source: https://ensforge.com/docs/reference/react/use-primary-name
Reads the primary name of an address, verified against its forward address. Preset of `useRead(Actions.primaryName.get, …)`.
It wraps [`primaryName.get`](/docs/reference/sdk/primary-name/get): the same options, result and errors.
## Signature [#signature]
```ts
function usePrimaryName(options: Actions.primaryName.get.Options | undefined, config?: ReadConfig): ReadResult
```
## Examples [#examples]
```tsx title="Reading in a component"
import { usePrimaryName } from "@ensforge/react"
function View() {
const { data: primary } = usePrimaryName({ address })
return {primary}
}
```
## See also [#see-also]
- The [hook types](/docs/reference/react#types): `ReadResult`, `WriteResult` and `ReadConfig`.
# useReadErrorReset
> For the complete documentation index, see [llms.txt](https://ensforge.com/llms.txt).
The reset handle of the nearest ReadErrorResetBoundary, or of the whole app without one. Signature, result and examples for useReadErrorReset.
Source: https://ensforge.com/docs/reference/react/use-read-error-reset
The reset handle of the nearest [`ReadErrorResetBoundary`](/docs/reference/react/components#readerrorresetboundary), or of the whole app without
one. Call `reset` from an error boundary's reset callback so `useSuspenseRead` reads again.
## Signature [#signature]
```ts
function useReadErrorReset(): ReadErrorReset
```
## Examples [#examples]
```tsx title="Resetting from a boundary component"
import { useReadErrorReset } from "@ensforge/react"
export function RetryButton({ onRetry }: { onRetry: () => void }) {
const { reset } = useReadErrorReset()
return
}
```
## See also [#see-also]
- The [hook types](/docs/reference/react#types): `ReadResult`, `WriteResult` and `ReadConfig`.
# useRead
> For the complete documentation index, see [llms.txt](https://ensforge.com/llms.txt).
Reads with any ensforge action and keeps the result fresh. Signature, options, result and examples for useRead in @ensforge/react.
Source: https://ensforge.com/docs/reference/react/use-read
Reads with any ensforge action and keeps the result fresh.
## When to use [#when-to-use]
Use for any read, from either `@ensforge/sdk` or `@ensforge/sdk/effect`. Named hooks such as
`useAddress` are presets of this one.
## Details [#details]
- Components reading the same action and options share one request and one cached result.
- Unmounting keeps the result, and a request in flight, cached for `idleTTL`; a remount within
it reuses them, and retries a failed read. Writes that touch the read's names or accounts
refetch it.
- Pass `undefined` options (or `enabled: false`) to wait, e.g. until a name is typed.
## Signature [#signature]
```ts
function useRead(action: action, options: ActionOptions | undefined, config: ReadConfig = {}): ReadResult, ActionError>
```
## Examples [#examples]
```tsx title="Reading a role"
import { Actions } from "@ensforge/sdk"
import { useRead } from "@ensforge/react"
function CanEdit({ name, account }: { name: string; account: `0x${string}` }) {
const { data, isLoading } = useRead(Actions.permission.get, { name, account })
return isLoading ? null : {String(data?.can.setRecords)}
}
```
## See also [#see-also]
- The [hook types](/docs/reference/react#types): `ReadResult`, `WriteResult` and `ReadConfig`.
# useReads
> For the complete documentation index, see [llms.txt](https://ensforge.com/llms.txt).
Runs several reads at once; their RPC calls share the client's multicall batches. Signature, options, result and examples for useReads in @ensforge/react.
Source: https://ensforge.com/docs/reference/react/use-reads
Runs several reads at once; their RPC calls share the client's multicall batches.
## When to use [#when-to-use]
Use for a list of reads whose length changes, such as an avatar per row. For a fixed set,
separate hooks read just as well.
## Signature [#signature]
```ts
function useReads(reads: reads, config: Omit = {}): ReadsResult
```
## Examples [#examples]
```tsx title="Addresses of several names"
import { Actions } from "@ensforge/sdk"
import { useReads } from "@ensforge/react"
function Addresses({ names }: { names: readonly string[] }) {
const results = useReads(names.map((name) => [Actions.record.getAddress, { name }] as const))
return
{results.map((result, index) =>
{result.data}
)}
}
```
## See also [#see-also]
- The [hook types](/docs/reference/react#types): `ReadResult`, `WriteResult` and `ReadConfig`.
# useRecords
> For the complete documentation index, see [llms.txt](https://ensforge.com/llms.txt).
Reads any mix of a name's records in one request; the result has exactly the requested fields. Signature, result and examples for useRecords.
Source: https://ensforge.com/docs/reference/react/use-records
Reads any mix of a name's records in one request; the result has exactly the requested fields.
Preset of `useRead(Actions.record.get, …)`.
It wraps [`record.get`](/docs/reference/sdk/record/get): the same options, result and errors.
## Signature [#signature]
```ts
function useRecords(options: options | undefined, config?: ReadConfig): ReadResult, Actions.record.get.ErrorType>
```
## Examples [#examples]
```tsx title="A profile card"
import { useRecords } from "@ensforge/react"
function Profile() {
const { data } = useRecords({ name: "nick.eth", texts: ["url", "avatar"], addresses: ["eth"] })
return {data?.texts.url}
}
```
## See also [#see-also]
- The [hook types](/docs/reference/react#types): `ReadResult`, `WriteResult` and `ReadConfig`.
# useRegister
> For the complete documentation index, see [llms.txt](https://ensforge.com/llms.txt).
Registers names: commit, wait the minimum age, then register, with every step in steps. Signature, result and examples for useRegister.
Source: https://ensforge.com/docs/reference/react/use-register
Registers names: commit, wait the minimum age, then register, with every step in `steps`. Preset of `useWrite(Actions.registration.register)`.
It wraps [`registration.register`](/docs/reference/sdk/registration/register): the same options, result and errors.
## Signature [#signature]
```ts
function useRegister(config?: Parameters[1]): WriteResult< Parameters[1], Actions.registration.register.ReturnType, Actions.registration.register.ErrorType >
```
## Examples [#examples]
```tsx title="A button that sends it"
import { Duration } from "@ensforge/sdk"
import { useRegister } from "@ensforge/react"
function Send() {
const { mutate, isPending } = useRegister()
return
}
```
## See also [#see-also]
- The [hook types](/docs/reference/react#types): `ReadResult`, `WriteResult` and `ReadConfig`.
# useRegistrationPrice
> For the complete documentation index, see [llms.txt](https://ensforge.com/llms.txt).
Reads what registering names for a duration costs. Signature, options, result and examples for useRegistrationPrice in @ensforge/react.
Source: https://ensforge.com/docs/reference/react/use-registration-price
Reads what registering names for a duration costs. Preset of `useRead(Actions.registration.getPrice, …)`.
It wraps [`registration.getPrice`](/docs/reference/sdk/registration/get-price): the same options, result and errors.
## Signature [#signature]
```ts
function useRegistrationPrice(options: Actions.registration.getPrice.Options | undefined, config?: ReadConfig): ReadResult
```
## Examples [#examples]
```tsx title="Reading in a component"
import { Duration } from "@ensforge/sdk"
import { useRegistrationPrice } from "@ensforge/react"
function View() {
const { data: price } = useRegistrationPrice({ name: "alice.eth", duration: Duration.years(1) })
return {String(price?.total)}
}
```
## See also [#see-also]
- The [hook types](/docs/reference/react#types): `ReadResult`, `WriteResult` and `ReadConfig`.
# useRenew
> For the complete documentation index, see [llms.txt](https://ensforge.com/llms.txt).
Renews names. Signature, options, result and examples for useRenew in @ensforge/react. Signature, result and examples for useRenew.
Source: https://ensforge.com/docs/reference/react/use-renew
Renews names. Preset of `useWrite(Actions.registration.renew)`.
It wraps [`registration.renew`](/docs/reference/sdk/registration/renew): the same options, result and errors.
## Signature [#signature]
```ts
function useRenew(config?: Parameters[1]): WriteResult< Parameters[1], Actions.registration.renew.ReturnType, Actions.registration.renew.ErrorType >
```
## Examples [#examples]
```tsx title="A button that sends it"
import { Duration } from "@ensforge/sdk"
import { useRenew } from "@ensforge/react"
function Send() {
const { mutate, isPending } = useRenew()
return
}
```
## See also [#see-also]
- The [hook types](/docs/reference/react#types): `ReadResult`, `WriteResult` and `ReadConfig`.
# useSetPrimaryName
> For the complete documentation index, see [llms.txt](https://ensforge.com/llms.txt).
Sets the signer's primary name. Signature, options, result and examples for useSetPrimaryName in @ensforge/react. Includes examples.
Source: https://ensforge.com/docs/reference/react/use-set-primary-name
Sets the signer's primary name. Preset of `useWrite(Actions.primaryName.set)`.
It wraps [`primaryName.set`](/docs/reference/sdk/primary-name/set): the same options, result and errors.
## Signature [#signature]
```ts
function useSetPrimaryName(config?: Parameters[1]): WriteResult< Parameters[1], Actions.primaryName.set.ReturnType, Actions.primaryName.set.ErrorType >
```
## Examples [#examples]
```tsx title="A button that sends it"
import { useSetPrimaryName } from "@ensforge/react"
function Send() {
const { mutate, isPending } = useSetPrimaryName()
return
}
```
## See also [#see-also]
- The [hook types](/docs/reference/react#types): `ReadResult`, `WriteResult` and `ReadConfig`.
# useSetRecords
> For the complete documentation index, see [llms.txt](https://ensforge.com/llms.txt).
Sets, changes or clears a name's records in one write. Signature, options, result and examples for useSetRecords in @ensforge/react.
Source: https://ensforge.com/docs/reference/react/use-set-records
Sets, changes or clears a name's records in one write. Preset of `useWrite(Actions.record.set)`.
It wraps [`record.set`](/docs/reference/sdk/record/set): the same options, result and errors.
## Signature [#signature]
```ts
function useSetRecords(config?: Parameters[1]): WriteResult< Parameters[1], Actions.record.set.ReturnType, Actions.record.set.ErrorType >
```
## Examples [#examples]
```tsx title="A button that sends it"
import { useSetRecords } from "@ensforge/react"
function Send() {
const { mutate, isPending } = useSetRecords()
return
}
```
## See also [#see-also]
- The [hook types](/docs/reference/react#types): `ReadResult`, `WriteResult` and `ReadConfig`.
# useSetResolver
> For the complete documentation index, see [llms.txt](https://ensforge.com/llms.txt).
Points a name at a resolver. Signature, options, result and examples for useSetResolver in @ensforge/react. Signature, result and examples for useSetResolver.
Source: https://ensforge.com/docs/reference/react/use-set-resolver
Points a name at a resolver. Preset of `useWrite(Actions.resolver.set)`.
It wraps [`resolver.set`](/docs/reference/sdk/resolver/set): the same options, result and errors.
## Signature [#signature]
```ts
function useSetResolver(config?: Parameters[1]): WriteResult< Parameters[1], Actions.resolver.set.ReturnType, Actions.resolver.set.ErrorType >
```
## Examples [#examples]
```tsx title="A button that sends it"
import { useSetResolver } from "@ensforge/react"
function Send() {
const { mutate, isPending } = useSetResolver()
return
}
```
## See also [#see-also]
- The [hook types](/docs/reference/react#types): `ReadResult`, `WriteResult` and `ReadConfig`.
# useSignClaim
> For the complete documentation index, see [llms.txt](https://ensforge.com/llms.txt).
Signs a claim to a primary name on L2s, with one signature and no transaction, for primaryName.set on each chain (or a relaying server).
Source: https://ensforge.com/docs/reference/react/use-sign-claim
Signs a claim to a primary name on L2s, with one signature and no transaction, for
`primaryName.set` on each chain (or a relaying server). Preset of
`useWrite(Actions.primaryName.signClaim)`; it refreshes no reads.
## Signature [#signature]
```ts
function useSignClaim(config?: Parameters[1]): WriteResult< Parameters[1], Actions.primaryName.signClaim.ReturnType, Actions.primaryName.signClaim.ErrorType >
```
## Examples [#examples]
```tsx title="Signing, then setting the name on Base"
import { useSetPrimaryName, useSignClaim } from "@ensforge/react"
function Send() {
const sign = useSignClaim()
const set = useSetPrimaryName()
const onClick = async () => {
const signed = await sign.mutateAsync({ name: "alice.eth", chainIds: [8453] })
set.mutate({ ...signed, coin: { chainId: 8453 } })
}
return
}
```
## See also [#see-also]
- The [hook types](/docs/reference/react#types): `ReadResult`, `WriteResult` and `ReadConfig`.
# useSubnames
> For the complete documentation index, see [llms.txt](https://ensforge.com/llms.txt).
Lists a name's subnames, page by page, from the indexer. Signature, options, result and examples for useSubnames in @ensforge/react.
Source: https://ensforge.com/docs/reference/react/use-subnames
Lists a name's subnames, page by page, from the indexer. Preset of `useInfiniteRead(Actions.indexer.getSubnames, …)`.
It wraps [`indexer.getSubnames`](/docs/reference/sdk/indexer/get-subnames): the same options, result and errors.
## Signature [#signature]
```ts
function useSubnames(options: Omit, config?: { readonly client?: ReadConfig["client"] }): InfiniteReadResult< Actions.indexer.getSubnames.ReturnType, Actions.indexer.getSubnames.ErrorType >
```
## Examples [#examples]
```tsx title="A list with \"Load more\""
import { useSubnames } from "@ensforge/react"
function List() {
const { items, hasMore, loadMore } = useSubnames({ name: "ens.eth" })
return
}
```
## See also [#see-also]
- The [hook types](/docs/reference/react#types): `ReadResult`, `WriteResult` and `ReadConfig`.
# useSuspenseRead
> For the complete documentation index, see [llms.txt](https://ensforge.com/llms.txt).
Reads with an action and suspends until the value is there; failures throw to the nearest error boundary. Signature, result and examples for useSuspenseRead.
Source: https://ensforge.com/docs/reference/react/use-suspense-read
Reads with an action and suspends until the value is there; failures throw to the nearest
error boundary.
## When to use [#when-to-use]
Use inside `` boundaries, including server-rendered pages whose reads were
prefetched.
## Details [#details]
- A failure is cached and thrown again until `reset` (`useReadErrorReset`, or
`ReadErrorResetBoundary`) is called, which an error boundary's reset does; the read then runs
again.
- On the server, a read that was not prefetched throws, so React renders the boundary's
fallback there and the read in the browser (React reports it as a recoverable error).
## Signature [#signature]
```ts
function useSuspenseRead(action: action, options: ActionOptions, config: Omit = {}): SuspenseReadResult>
```
## Examples [#examples]
```tsx title="A profile behind Suspense"
import { Actions } from "@ensforge/sdk"
import { useSuspenseRead } from "@ensforge/react"
function Url({ name }: { name: string }) {
const { data } = useSuspenseRead(Actions.record.getText, { name, key: "url" })
return {data}
}
```
## See also [#see-also]
- The [hook types](/docs/reference/react#types): `ReadResult`, `WriteResult` and `ReadConfig`.
# useText
> For the complete documentation index, see [llms.txt](https://ensforge.com/llms.txt).
Reads one text record, such as url, avatar or com.twitter. Signature, options, result and examples for useText in @ensforge/react.
Source: https://ensforge.com/docs/reference/react/use-text
Reads one text record, such as `url`, `avatar` or `com.twitter`. Preset of `useRead(Actions.record.getText, …)`.
It wraps [`record.getText`](/docs/reference/sdk/record/get-text): the same options, result and errors.
## Signature [#signature]
```ts
function useText(options: Actions.record.getText.Options | undefined, config?: ReadConfig): ReadResult
```
## Examples [#examples]
```tsx title="Reading in a component"
import { useText } from "@ensforge/react"
function View() {
const { data: url } = useText({ name: "nick.eth", key: "url" })
return {url}
}
```
## See also [#see-also]
- The [hook types](/docs/reference/react#types): `ReadResult`, `WriteResult` and `ReadConfig`.
# useTransferName
> For the complete documentation index, see [llms.txt](https://ensforge.com/llms.txt).
Transfers a name to another account. Signature, options, result and examples for useTransferName in @ensforge/react. Includes examples.
Source: https://ensforge.com/docs/reference/react/use-transfer-name
Transfers a name to another account. Preset of `useWrite(Actions.name.transfer)`.
It wraps [`name.transfer`](/docs/reference/sdk/name/transfer): the same options, result and errors.
## Signature [#signature]
```ts
function useTransferName(config?: Parameters[1]): WriteResult< Parameters[1], Actions.name.transfer.ReturnType, Actions.name.transfer.ErrorType >
```
## Examples [#examples]
```tsx title="A button that sends it"
import { useTransferName } from "@ensforge/react"
function Send() {
const { mutate, isPending } = useTransferName()
return
}
```
## See also [#see-also]
- The [hook types](/docs/reference/react#types): `ReadResult`, `WriteResult` and `ReadConfig`.
# useWrite
> For the complete documentation index, see [llms.txt](https://ensforge.com/llms.txt).
Sends any ensforge write and tracks it. Signature, options, result and examples for useWrite in @ensforge/react. Signature, result and examples for useWrite.
Source: https://ensforge.com/docs/reference/react/use-write
Sends any ensforge write and tracks it.
## When to use [#when-to-use]
Use for any write. Named hooks such as `useSetRecords` are presets of this one. Use the
`…Sync` action (e.g. `Actions.record.setSync`) to resolve with receipts.
## Details [#details]
- Each component gets its own state; two buttons never share a result.
- The state follows the latest write started; each `mutateAsync` settles with its own write.
- `steps` lists plan events as they happen, for multi-step writes (approve, commit, register).
- Afterwards, reads of the names and accounts it touched refetch: chain reads once mined,
indexer reads once indexed.
## Signature [#signature]
```ts
function useWrite(action: action, config: { readonly client?: Ensforge.Client | undefined } = {}): WriteResult, ActionValue, ActionError>
```
## Examples [#examples]
```tsx title="Saving records with progress"
import { Actions } from "@ensforge/sdk"
import { useWrite } from "@ensforge/react"
function Save({ name }: { name: string }) {
const { mutate, isPending, steps } = useWrite(Actions.record.set)
return (
)
}
```
## See also [#see-also]
- The [hook types](/docs/reference/react#types): `ReadResult`, `WriteResult` and `ReadConfig`.
# Atoms
> For the complete documentation index, see [llms.txt](https://ensforge.com/llms.txt).
Look up the atom layer of @ensforge/react/atoms that the hooks are built on, for reading ENS data outside of React components.
Source: https://ensforge.com/docs/reference/react/atoms
Exports of `@ensforge/react/atoms`. See [Atoms](/docs/react/atoms).
## Exports [#exports]
### `ensAtom` [#ensatom]
**Unstable**
The atom of one read: cached per client (chain, account and indexer), action and options,
refreshed when a write touches a name or address in its options, and serializable for server
rendering. Each freshness gets its own atom over the shared read.
```ts
function ensAtom(client: Ensforge.Client, action: action, options: ActionOptions, freshness: Freshness = {}): ReadAtom, ActionError>
```
Use to compose ENS reads into your own atoms, or to read them outside React hooks. Hooks such
as `useRead` use the same atoms.
```ts title="Composing reads"
import { Actions } from "@ensforge/sdk"
import { ensAtom } from "@ensforge/react/atoms"
import { Atom } from "effect/reactivity"
const profile = Atom.make((get) => ({
address: get(ensAtom(ens, Actions.record.getAddress, { name: "nick.eth" })),
avatar: get(ensAtom(ens, Actions.record.getAvatar, { name: "nick.eth" })),
}))
```
### `ensPagesAtom` [#enspagesatom]
**Unstable**
The paginated atom of an indexer list, such as `indexer.getSubnames`. Pages accumulate as
they load; a write touching the list's name or account starts it over.
```ts
function ensPagesAtom(client: Ensforge.Client, action: action, options: Omit, "cursor">): PagesAtom, ActionError>
```
```ts title="Loading subnames page by page"
import { Actions } from "@ensforge/sdk"
import { ensPagesAtom } from "@ensforge/react/atoms"
const subnames = ensPagesAtom(ens, Actions.indexer.getSubnames, { name: "ens.eth" })
registry.set(subnames, undefined) // load the next page
```
### `ensWriteAtom` [#enswriteatom]
**Unstable**
Atoms for one write action. Each call makes new atoms, so every form or button has its own
state; hooks keep one per component.
```ts
function ensWriteAtom(client: Ensforge.Client, action: action): WriteAtom, ActionValue, ActionError>
```
- `run` and `steps` show the latest write started; mount `run` while writing through it.
- Writes never interrupt each other, and resetting interrupts none: a sent transaction cannot
be taken back. Each `send` still ends with its own write's result.
- Plan events (`waiting`, `submitted`, `confirmed`, `failed`) collect in `steps`.
- After a write, reads of the names and accounts it touched refresh: chain reads once its
transactions are mined, indexer reads once the indexer has caught up. A write that fails
after a step was confirmed refreshes them too. Signatures (`primaryName.signClaim`) send no
transaction and refresh nothing.
```ts title="Sending a write from an atom"
import { Actions } from "@ensforge/sdk"
import { ensWriteAtom } from "@ensforge/react/atoms"
const setRecords = ensWriteAtom(ens, Actions.record.set)
registry.mount(setRecords.run)
registry.set(setRecords.run, { name: "alice.eth", texts: { url: "https://alice.xyz" } })
```
### `invalidate` [#invalidate]
**Unstable**
Refetches every cached read of the given names and accounts, chain and indexer reads alike.
```ts
function invalidate(registry: AtomRegistry.AtomRegistry, client: Ensforge.Client, subjects: { readonly names?: readonly string[]; readonly addresses?: readonly string[] }): void
```
Use after changes ensforge did not make, such as a transaction sent by another app. Writes
made through ensforge refresh their reads on their own.
```ts title="Refreshing a name after an external change"
import { invalidate } from "@ensforge/react/atoms"
invalidate(registry, ens, { names: ["alice.eth"] })
```
### `optionsKey` [#optionskey]
**Unstable**
A stable string for an action's options: keys sorted, `undefined`, callbacks and `signal`
dropped, the top-level `name`, `names` and `parent` normalized, top-level addresses lowercased
and bigints written as `123n`. Nested fields are data (a text record called `name`), kept as
given.
```ts
function optionsKey(options: unknown): string
```
### `readKey` [#readkey]
**Unstable**
The key a read is cached, hydrated and invalidated under:
`ensforge:::::`, with the client's account
(lowercase) and indexer key (`Indexer.key`) empty when it has none. It names the client by what changes a
read's answer, not by object, so it is the same on the server and in the browser.
```ts
function readKey(client: Ensforge.Client, action: Action, options: unknown): string
```
### `Action` [#action]
Any ensforge action from `@ensforge/sdk` or `@ensforge/sdk/effect`, or one of a write's
`.prepare`, `.simulate` and `.estimateGas`: a function of a client and options, named by its
`path`.
```ts
type Action = ((client: Ensforge.Client, options: never) => unknown) & { readonly path: string; };
```
| Field | Type | Description |
| --- | --- | --- |
| `path` | `string` | |
### `ActionError` [#actionerror]
Error an action fails with: the Effect action's error channel, or any ensforge error for
Promise actions.
```ts
type ActionError = ReturnType extends Effect.Effect ? error : Errors.AnyError;
```
### `ActionOptions` [#actionoptions]
Options an action takes.
```ts
type ActionOptions = Parameters[1];
```
### `ActionValue` [#actionvalue]
Value an action resolves with.
```ts
type ActionValue = ReturnType extends Promise ? value : ReturnType extends Effect.Effect ? value : never;
```
### `Freshness` [#freshness]
How long a read stays fresh and cached. Each hook's settings apply to it alone; hooks with
other settings still share the read's value and requests.
```ts
type Freshness
```
| Field | Type | Description |
| --- | --- | --- |
| `staleTime` (optional) | `Duration.Input` | After this long, the next mount or window focus refetches in the background while the cached value is shown (stale-while-revalidate). `Duration.infinity` never does. Without it, a value hydrated from the server is stale after 30 seconds; a failed read is always stale, so a remount retries it. |
| `idleTTL` (optional) | `Duration.Input \| "forever"` | How long an unused read stays cached; `"forever"` or `Duration.infinity` keeps it. With hooks of several settings, the longest applies. |
| `refetchInterval` (optional) | `Duration.Input` | Refetch on this interval while the read is in use, in the browser only. |
| `refreshOnWindowFocus` (optional) | `boolean` | Refetch when the window regains focus (respecting `staleTime` when set). |
### `PageAction` [#pageaction]
An indexer action that returns pages and takes a `cursor`, such as `indexer.getSubnames`.
```ts
type PageAction = Action & (( client: never, options: never, ) => | Promise<{ readonly items: readonly unknown[]; readonly cursor: string | null }> | Effect.Effect< { readonly items: readonly unknown[]; readonly cursor: string | null }, unknown >);
```
| Field | Type | Description |
| --- | --- | --- |
| `path` | `string` | |
### `PagesAtom` [#pagesatom]
**Unstable**
Pages of an indexer list as an atom: its value holds every page loaded so far, and writing to
it loads the next one.
```ts
type PagesAtom = Atom.Writable, void>;
```
### `ReadAtom` [#readatom]
**Unstable**
A read atom: an Effect Atom holding the read's `AsyncResult`.
```ts
type ReadAtom = Atom.Atom>;
```
### `WriteAtom` [#writeatom]
**Unstable**
A write as atoms: `run` holds the latest write's result and sends one when set; `steps` holds
that write's plan events; `send` sends one and ends with its own result.
```ts
type WriteAtom
```
| Field | Type | Description |
| --- | --- | --- |
| `run` | `Atom.Writable, options \| Atom.Reset>` | The latest write's result. Setting options sends a write; `Atom.Reset` clears the result. |
| `steps` | `Atom.Writable` | |
| `send` | `(options: options) => Effect.Effect` | Sends a write and ends with its own result, even when later writes start while it runs. `run` and `steps` show it until a later one starts. |
# Components
> For the complete documentation index, see [llms.txt](https://ensforge.com/llms.txt).
Look up EnsforgeProvider and the read error and hydration boundary components of @ensforge/react, with their props and examples.
Source: https://ensforge.com/docs/reference/react/components
Components exported from `@ensforge/react`. See [Set up the provider](/docs/react/set-up-the-provider).
## Components [#components]
### `EnsforgeProvider` [#ensforgeprovider]
Provides an ensforge client to the hooks below it.
```ts
function EnsforgeProvider({ client, defaults, registry = true, children, }: EnsforgeProviderProps): ReactNode
```
Use once near the root, inside the wagmi providers when the app has them. Nest another with
`registry={false}` for a second chain.
- Hooks run actions with this client; they do not need its action groups (`extend`).
- It renders an Effect Atom `RegistryProvider`, so each server request gets its own cache.
```tsx title="A wagmi app"
import { EnsforgeProvider } from "@ensforge/react"
import { Ensforge } from "@ensforge/sdk/wagmi"
const ens = Ensforge.fromWagmi(wagmiConfig)
export function Providers({ children }: { children: React.ReactNode }) {
return {children}
}
```
### `HydrationBoundary` [#hydrationboundary]
**Unstable**
Provides a React hydration boundary that loads dehydrated Atom values into
the current Atom registry.
```ts
const HydrationBoundary: React.FC
```
Use to apply dehydrated Atom state to a React subtree that reads from the
nearest `RegistryContext`.
New Atom values are hydrated during render so descendants can read them
immediately, while values for existing Atoms are deferred until after commit
so transition data does not update the current UI before React accepts it.
### `ReadErrorResetBoundary` [#readerrorresetboundary]
Scopes error resets of `useSuspenseRead`: a failure the reads below threw to an error boundary
is rethrown, from the cache, until `reset` is called; after that they read again. Place it
around the error boundary and call `reset` when that boundary resets. Like React Query's
`QueryErrorResetBoundary`.
```ts
function ReadErrorResetBoundary({ children }: ReadErrorResetBoundaryProps)
```
Use with `useSuspenseRead` and an error boundary that can reset, so "try again" fetches again
instead of showing the cached error. Without a boundary `useReadErrorReset` resets every read
in the app.
```tsx title="Wiring an error boundary's reset"
import { Component, Suspense, type ReactNode } from "react"
import { ReadErrorResetBoundary, useSuspenseRead } from "@ensforge/react"
import { Actions } from "@ensforge/sdk"
// Any error boundary with a reset callback works, such as react-error-boundary's `onReset`.
class Boundary extends Component<{ children: ReactNode; onReset: () => void }, { failed: boolean }> {
override state = { failed: false }
static getDerivedStateFromError() {
return { failed: true }
}
override render() {
if (!this.state.failed) return this.props.children
return (
)
}
}
function Owner({ name }: { name: string }) {
const { data } = useSuspenseRead(Actions.name.get, { name })
return {data.owner}
}
export const View = ({ name }: { name: string }) => (
{({ reset }) => (
)}
)
```
### `EnsforgeProviderProps` [#ensforgeproviderprops]
Props of [`EnsforgeProvider`](/docs/reference/react/components#ensforgeprovider).
```ts
type EnsforgeProviderProps
```
| Option | Type | Default | Description |
| --- | --- | --- | --- |
| `client` (required) | `Ensforge.Client` | | The client hooks use, as is: `Ensforge.create(…)`, or `Ensforge.fromWagmi(config)`. Writes ENS makes on other chains (L2 primary names) need them in its `chains`, which `fromWagmi` fills from the wagmi config's chains. |
| `defaults` | `Freshness` | | Freshness for every read below, unless a hook sets its own. |
| `registry` | `boolean` | `true` | Create an atom registry for the subtree. Pass `false` when the app already renders a `RegistryProvider` (to share atoms with it) or when nesting providers for other chains. |
| `children` | `ReactNode` | | |
### `ReadErrorResetBoundaryProps` [#readerrorresetboundaryprops]
Props of [`ReadErrorResetBoundary`](/docs/reference/react/components#readerrorresetboundary).
```ts
type ReadErrorResetBoundaryProps
```
| Option | Type | Default | Description |
| --- | --- | --- | --- |
| `children` (required) | `ReactNode \| ((reset: ReadErrorReset) => ReactNode)` | | The subtree, or a function of the reset handle for wiring it to an error boundary. |
# React
> For the complete documentation index, see [llms.txt](https://ensforge.com/llms.txt).
Look up every hook, component, server helper and atom of @ensforge/react, and the types the hooks take and return, with examples.
Source: https://ensforge.com/docs/reference/react
Generic hooks take any action; named hooks are presets of them for common actions. See [Read data](/docs/react/read-data) and [Write data](/docs/react/write-data).
## Named reads [#named-reads]
| Hook | Description |
| --- | --- |
| [`useAddress`](/docs/reference/react/use-address) | Reads the address a name points to, for ETH or another coin. |
| [`useAvailability`](/docs/reference/react/use-availability) | Checks whether a name can be registered now. |
| [`useAvatar`](/docs/reference/react/use-avatar) | Reads a name's avatar as an image URL, with NFT avatars resolved. |
| [`useMigrationStatus`](/docs/reference/react/use-migration-status) | Reads whether and how a name can move from ENSv1 to ENSv2. |
| [`useName`](/docs/reference/react/use-name) | Reads a name's state: owner, manager, expiry, resolver, registry and wrapper status. |
| [`useNameHistory`](/docs/reference/react/use-name-history) | Lists a name's events (registrations, transfers, record changes), page by page, from the indexer. |
| [`useNamesForAddress`](/docs/reference/react/use-names-for-address) | Lists the names an address owns, manages or is the primary name of, page by page, from the indexer. |
| [`usePermissions`](/docs/reference/react/use-permissions) | Reads what an account may do with a name. |
| [`usePrimaryName`](/docs/reference/react/use-primary-name) | Reads the primary name of an address, verified against its forward address. |
| [`useRecords`](/docs/reference/react/use-records) | Reads any mix of a name's records in one request; the result has exactly the requested fields. |
| [`useRegistrationPrice`](/docs/reference/react/use-registration-price) | Reads what registering names for a duration costs. |
| [`useSubnames`](/docs/reference/react/use-subnames) | Lists a name's subnames, page by page, from the indexer. |
| [`useText`](/docs/reference/react/use-text) | Reads one text record, such as `url`, `avatar` or `com.twitter`. |
## Named writes [#named-writes]
| Hook | Description |
| --- | --- |
| [`useCreateSubname`](/docs/reference/react/use-create-subname) | Creates a subname, optionally with records. |
| [`useMigrate`](/docs/reference/react/use-migrate) | Moves names from ENSv1 to ENSv2. |
| [`useRegister`](/docs/reference/react/use-register) | Registers names: commit, wait the minimum age, then register, with every step in `steps`. |
| [`useRenew`](/docs/reference/react/use-renew) | Renews names. |
| [`useSetPrimaryName`](/docs/reference/react/use-set-primary-name) | Sets the signer's primary name. |
| [`useSetRecords`](/docs/reference/react/use-set-records) | Sets, changes or clears a name's records in one write. |
| [`useSetResolver`](/docs/reference/react/use-set-resolver) | Points a name at a resolver. |
| [`useSignClaim`](/docs/reference/react/use-sign-claim) | Signs a claim to a primary name on L2s, with one signature and no transaction, for `primaryName.set` on each chain (or a relaying server). |
| [`useTransferName`](/docs/reference/react/use-transfer-name) | Transfers a name to another account. |
## Provider [#provider]
| Hook | Description |
| --- | --- |
| [`useEnsforge`](/docs/reference/react/use-ensforge) | The client of the nearest `EnsforgeProvider`. |
## Reads [#reads]
| Hook | Description |
| --- | --- |
| [`useInfiniteRead`](/docs/reference/react/use-infinite-read) | Reads an indexer list page by page, such as a name's subnames or an account's names. |
| [`useRead`](/docs/reference/react/use-read) | Reads with any ensforge action and keeps the result fresh. |
| [`useReadErrorReset`](/docs/reference/react/use-read-error-reset) | The reset handle of the nearest [`ReadErrorResetBoundary`](/docs/reference/react/components#readerrorresetboundary), or of the whole app without one. |
| [`useReads`](/docs/reference/react/use-reads) | Runs several reads at once; their RPC calls share the client's multicall batches. |
| [`useSuspenseRead`](/docs/reference/react/use-suspense-read) | Reads with an action and suspends until the value is there; failures throw to the nearest error boundary. |
## Writes [#writes]
| Hook | Description |
| --- | --- |
| [`usePrepare`](/docs/reference/react/use-prepare) | Plans a write without sending it: its steps, calls and warnings, for a review screen before the wallet prompt. |
| [`useWrite`](/docs/reference/react/use-write) | Sends any ensforge write and tracks it. |
## Types [#types]
### `InfiniteReadResult` [#infinitereadresult]
What [`useInfiniteRead`](/docs/reference/react/use-infinite-read) returns.
```ts
type InfiniteReadResult
```
| Field | Type | Description |
| --- | --- | --- |
| `pages` | `readonly page[]` | Every page loaded so far. |
| `items` | `readonly ItemOf[]` | The items of every page loaded so far, in order. |
| `hasMore` | `boolean` | More pages remain. |
| `loadMore` | `() => void` | Loads the next page. |
| `isLoading` | `boolean` | The first page is loading. |
| `isLoadingMore` | `boolean` | A further page is loading. |
| `error` | `error` | |
| `result` | `AsyncResult.AsyncResult< { readonly done: boolean; readonly items: readonly page[] }, error >` | |
### `PreparableAction` [#preparableaction]
A write action, with the `.prepare` that plans it.
```ts
type PreparableAction = Action & { readonly prepare: Action };
```
| Field | Type | Description |
| --- | --- | --- |
| `path` | `string` | |
| `prepare` | `Action` | |
### `ReadConfig` [#readconfig]
Settings of a read hook: its freshness, whether it runs, and an optional client.
```ts
type ReadConfig = Freshness & { /** * Run the read. Passing `undefined` options also disables it, e.g. until a name is typed. * * @default true */ readonly enabled?: boolean | undefined; /** Client to read with instead of the provider's. */ readonly client?: Ensforge.Client | undefined; };
```
| Option | Type | Default | Description |
| --- | --- | --- | --- |
| `staleTime` | `Duration.Input` | | After this long, the next mount or window focus refetches in the background while the cached value is shown (stale-while-revalidate). `Duration.infinity` never does. Without it, a value hydrated from the server is stale after 30 seconds; a failed read is always stale, so a remount retries it. |
| `idleTTL` | `Duration.Input \| "forever"` | `"1 minute"` | How long an unused read stays cached; `"forever"` or `Duration.infinity` keeps it. With hooks of several settings, the longest applies. |
| `refetchInterval` | `Duration.Input` | | Refetch on this interval while the read is in use, in the browser only. |
| `refreshOnWindowFocus` | `boolean` | `false` | Refetch when the window regains focus (respecting `staleTime` when set). |
| `enabled` | `boolean` | `true` | Run the read. Passing `undefined` options also disables it, e.g. until a name is typed. |
| `client` | `Ensforge.Client` | | Client to read with instead of the provider's. |
### `ReadErrorReset` [#readerrorreset]
What [`ReadErrorResetBoundary`](/docs/reference/react/components#readerrorresetboundary) and [`useReadErrorReset`](/docs/reference/react/use-read-error-reset) give.
```ts
type ReadErrorReset
```
| Field | Type | Description |
| --- | --- | --- |
| `reset` | `() => void` | Makes the reads below read again the failures they threw to an error boundary. Call it when the boundary resets; a failure is rethrown until then. |
### `ReadResult` [#readresult]
What a read hook returns.
```ts
type ReadResult
```
| Field | Type | Description |
| --- | --- | --- |
| `data` | `value` | The latest value, kept while refreshing. |
| `error` | `error` | The action's error when it failed. |
| `status` | `"idle" \| "loading" \| "success" \| "error"` | `idle` while disabled, `loading` until the first result, then `success` or `error`. |
| `isLoading` | `boolean` | No result yet and loading. |
| `isRefreshing` | `boolean` | Loading again with a previous result shown. |
| `result` | `AsyncResult.AsyncResult` | The Effect Atom result, for `AsyncResult.match`. |
| `refresh` | `() => void` | Refetches the read. |
### `ReadSpec` [#readspec]
One read of [`useReads`](/docs/reference/react/use-reads): an action and its options.
```ts
type ReadSpec = readonly [action: Action, options: unknown];
```
### `ReadsResult` [#readsresult]
Results of [`useReads`](/docs/reference/react/use-reads), in the order of the reads.
```ts
type ReadsResult = { readonly [index in keyof reads]: reads[index] extends readonly [ infer action extends Action, unknown, ] ? ReadResult, ActionError> : never; };
```
### `SuspenseReadResult` [#suspensereadresult]
What [`useSuspenseRead`](/docs/reference/react/use-suspense-read) returns: the value is always there.
```ts
type SuspenseReadResult
```
| Field | Type | Description |
| --- | --- | --- |
| `data` | `value` | |
| `isRefreshing` | `boolean` | Loading again with the current value shown. |
| `refresh` | `() => void` | |
### `WriteResult` [#writeresult]
What [`useWrite`](/docs/reference/react/use-write) returns.
```ts
type WriteResult
```
| Field | Type | Description |
| --- | --- | --- |
| `mutate` | `(options: options) => void` | Sends the write; the outcome lands in `status`, `data` and `error`. Stable across renders. |
| `mutateAsync` | `(options: options) => Promise` | Sends the write and resolves with its own result, or rejects with its error, even when later writes start while it runs. Stable across renders. |
| `data` | `value` | The latest write's value, once it succeeded. |
| `error` | `error` | |
| `status` | `"idle" \| "pending" \| "success" \| "error"` | Status of the latest write started. |
| `isPending` | `boolean` | |
| `steps` | `readonly Plan.Event[]` | Progress of the latest write's plan: `waiting`, `submitted`, `confirmed`, `failed`. |
| `result` | `AsyncResult.AsyncResult` | |
| `reset` | `() => void` | Clears the result and steps. Writes in flight are not interrupted (a sent transaction cannot be taken back): their `mutateAsync` promises still settle, but they no longer update the state. Stable across renders. |
# Server
> For the complete documentation index, see [llms.txt](https://ensforge.com/llms.txt).
Look up the server rendering helpers of @ensforge/react/server, which prefetch ENS reads on the server so the client hydrates with data.
Source: https://ensforge.com/docs/reference/react/server
Exports of `@ensforge/react/server`, for prefetching reads on the server.
## Exports [#exports]
### `dehydrate` [#dehydrate]
**Unstable**
Prefetched reads of `registry` as plain data for ``.
```ts
function dehydrate(registry: AtomRegistry.AtomRegistry, options: { readonly streaming?: boolean | undefined } = {}): readonly Hydration.DehydratedAtom[]
```
- Values are JSON (bigints and bytes are tagged), so they pass through server components and
loaders. Entries carry no `undefined` fields, so the result can be returned directly from
Next.js `getServerSideProps` and `getStaticProps`.
- `streaming: true` also sends reads still loading, as promises that resolve on the client
(React 19 server components, streaming SSR).
```tsx title="Streaming reads that are still loading"
import { Actions } from "@ensforge/sdk"
import { HydrationBoundary } from "@ensforge/react"
import { dehydrate, prefetch } from "@ensforge/react/server"
import { AtomRegistry } from "effect/reactivity"
const registry = AtomRegistry.make()
void prefetch(registry, ens, Actions.indexer.getSubnames, { name: "ens.eth" })
const state = dehydrate(registry, { streaming: true })
```
### `prefetch` [#prefetch]
**Unstable**
Runs a read on the server into `registry`, so `dehydrate` can send its result to the client.
```ts
function prefetch(registry: AtomRegistry.AtomRegistry, client: Ensforge.Client, action: action, options: ActionOptions, freshness?: Freshness): Promise
```
Use in server components, loaders and `getServerSideProps`/`getStaticProps` for the reads a
page renders first. Reads that are not prefetched render as loading on the server and run in
the browser.
- Resolves once the read settles; a failed read is not sent, so the browser retries it.
- Do not await it when streaming (`dehydrate(registry, { streaming: true })`): pending reads
then stream to the client as they resolve.
- Use a new registry per request.
```tsx title="Next.js App Router"
import { Actions } from "@ensforge/sdk"
import { HydrationBoundary } from "@ensforge/react"
import { dehydrate, prefetch } from "@ensforge/react/server"
import { AtomRegistry } from "effect/reactivity"
export default async function Page({ params }: { params: { name: string } }) {
const registry = AtomRegistry.make()
await prefetch(registry, ens, Actions.name.get, { name: params.name })
return {params.name}
}
```
# approval.getDelegate
> For the complete documentation index, see [llms.txt](https://ensforge.com/llms.txt).
Checks whether a delegate may edit a name's records on its public resolver (isApprovedFor). Options, result, errors and examples for approval.getDelegate.
Source: https://ensforge.com/docs/reference/sdk/approval/get-delegate
Checks whether a delegate may edit a name's records on its public resolver
(`isApprovedFor`).
## When to use [#when-to-use]
Use to see who besides the owner can edit a profile on a PublicResolver.
## Details [#details]
- The owner defaults to the one the resolver authorizes against: the ENS registry owner (or
NameWrapper owner) for ENSv1 resolvers, the ENSv2 owner for PublicResolverV2.
- PermissionedResolvers have roles instead of delegates and answer `false`.
## Signature [#signature]
```ts
function getDelegate(
client: Like,
options: getDelegate.Options,
): Promise
```
Call it as `ens.approval.getDelegate(options)` on a client, or `Actions.approval.getDelegate(client, options)`.
`approval.getDelegate.request(options)` builds a deferred read for `Actions.batch`. See [Look up many at once](/docs/sdk/look-up-many-at-once).
## Parameters [#parameters]
| Option | Type | Default | Description |
| --- | --- | --- | --- |
| `name` (required) | `string` | | ENS name. Normalized automatically. |
| `delegate` (required) | `string` | | Account that may be a delegate. |
| `owner` | `string` | the owner the resolver authorizes against | Owner who granted the delegation. |
Also takes the [read options](/docs/reference/sdk/client#read-options).
## Returns [#returns]
Resolves to `boolean`. Whether `delegate` may edit the name's records.
## Errors [#errors]
| Error | Codes | When |
| --- | --- | --- |
| [`InvalidInputError`](/docs/reference/errors/invalid-input-error) | [`INVALID_NAME`](/docs/reference/errors/INVALID_NAME), [`INVALID_ADDRESS`](/docs/reference/errors/INVALID_ADDRESS) | invalid input. |
| [`NotFoundError`](/docs/reference/errors/not-found-error) | [`RESOLVER_NOT_FOUND`](/docs/reference/errors/RESOLVER_NOT_FOUND) | the name has no resolver. |
| [`NetworkError`](/docs/reference/errors/network-error) | [`RPC_REQUEST_FAILED`](/docs/reference/errors/RPC_REQUEST_FAILED), [`RPC_TIMEOUT`](/docs/reference/errors/RPC_TIMEOUT), [`RATE_LIMITED`](/docs/reference/errors/RATE_LIMITED) | the RPC request fails. |
It can also fail with the errors every read can (`Errors.CommonError`: `ConfigError`, `ContractRevertError`, `InternalError`, `NetworkError`).
See [How errors work](/docs/sdk/errors-explained).
## Examples [#examples]
```ts title="Checking a delegate"
const approved = await ens.approval.getDelegate({ name: "alice.eth", delegate })
```
```ts title="Checking with a standalone call"
import { Actions } from "@ensforge/sdk"
const approved = await Actions.approval.getDelegate(publicClient, { name: "vitalik.eth", delegate })
```
```ts title="Checking in an Effect program"
import { Actions } from "@ensforge/sdk/effect"
const approved = yield* Actions.approval.getDelegate(ens, { name: "alice.eth", delegate })
```
## Example response [#example-response]
Recorded from Ethereum mainnet on 2026-11-18 at block 26443964. Values change as the chain does.
```ts
await ens.approval.getDelegate({ name: "nick.eth", delegate: "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045" })
```
```json
false
```
## See also [#see-also]
- [`approval.setDelegate`](/docs/reference/sdk/approval/set-delegate) to change it
# approval.getOperator
> For the complete documentation index, see [llms.txt](https://ensforge.com/llms.txt).
Checks whether an operator may manage everything an owner holds on an ENS contract (isApprovedForAll). Options, errors and examples for approval.getOperator.
Source: https://ensforge.com/docs/reference/sdk/approval/get-operator
Checks whether an operator may manage everything an owner holds on an ENS contract
(`isApprovedForAll`).
## When to use [#when-to-use]
Use to see whether a marketplace, manager or contract wallet is already approved.
## Details [#details]
- `contract`: the ENSv1 `"registry"`, `"registrar"` (BaseRegistrar) or `"wrapper"`
(NameWrapper), or any ENSv2 registry or resolver by address.
## Signature [#signature]
```ts
function getOperator(
client: Like,
options: getOperator.Options,
): Promise
```
Call it as `ens.approval.getOperator(options)` on a client, or `Actions.approval.getOperator(client, options)`.
`approval.getOperator.request(options)` builds a deferred read for `Actions.batch`. See [Look up many at once](/docs/sdk/look-up-many-at-once).
## Parameters [#parameters]
| Option | Type | Default | Description |
| --- | --- | --- | --- |
| `owner` (required) | `string` | | Account that granted the approval. |
| `operator` (required) | `string` | | Account that may be approved. |
| `contract` (required) | `ApprovalContract` | | `"registry"`, `"registrar"`, `"wrapper"`, or a registry or resolver address. |
Also takes the [read options](/docs/reference/sdk/client#read-options).
## Returns [#returns]
Resolves to `boolean`. Whether `operator` is approved for all of `owner`'s names on the contract.
## Errors [#errors]
| Error | Codes | When |
| --- | --- | --- |
| [`InvalidInputError`](/docs/reference/errors/invalid-input-error) | [`INVALID_ADDRESS`](/docs/reference/errors/INVALID_ADDRESS) | invalid addresses. |
| [`UnsupportedError`](/docs/reference/errors/unsupported-error) | [`UNSUPPORTED_ON_DEPLOYMENT`](/docs/reference/errors/UNSUPPORTED_ON_DEPLOYMENT) | ENSv1 contracts without ENSv1. |
| [`NetworkError`](/docs/reference/errors/network-error) | [`RPC_REQUEST_FAILED`](/docs/reference/errors/RPC_REQUEST_FAILED), [`RPC_TIMEOUT`](/docs/reference/errors/RPC_TIMEOUT), [`RATE_LIMITED`](/docs/reference/errors/RATE_LIMITED) | the RPC request fails. |
It can also fail with the errors every read can (`Errors.CommonError`: `ConfigError`, `ContractRevertError`, `InternalError`, `NetworkError`).
See [How errors work](/docs/sdk/errors-explained).
## Examples [#examples]
```ts title="Checking a NameWrapper operator"
const approved = await ens.approval.getOperator({ owner, operator, contract: "wrapper" })
```
```ts title="Checking an ENSv2 registry with a standalone call"
import { Actions } from "@ensforge/sdk"
const approved = await Actions.approval.getOperator(publicClient, { owner, operator, contract: registry })
```
```ts title="Checking in an Effect program"
import { Actions } from "@ensforge/sdk/effect"
const approved = yield* Actions.approval.getOperator(ens, { owner, operator, contract: "registry" })
```
## See also [#see-also]
- [`approval.setOperator`](/docs/reference/sdk/approval/set-operator) to change it
# approval.getToken
> For the complete documentation index, see [llms.txt](https://ensforge.com/llms.txt).
Reads the address approved to transfer one ENSv1 name token (getApproved). Parameters, return value, errors and examples for approval.getToken in @ensforge/sdk.
Source: https://ensforge.com/docs/reference/sdk/approval/get-token
Reads the address approved to transfer one ENSv1 name token (`getApproved`).
## When to use [#when-to-use]
Use to check a pending single-name approval, e.g. before listing a name for sale.
## Details [#details]
- Wrapped names use the NameWrapper token; unwrapped `.eth` names the BaseRegistrar token.
- ENSv2 names have no single-token approval; use operators.
## Signature [#signature]
```ts
function getToken(client: Like, options: getToken.Options): Promise
```
Call it as `ens.approval.getToken(options)` on a client, or `Actions.approval.getToken(client, options)`.
`approval.getToken.request(options)` builds a deferred read for `Actions.batch`. See [Look up many at once](/docs/sdk/look-up-many-at-once).
## Parameters [#parameters]
| Option | Type | Default | Description |
| --- | --- | --- | --- |
| `name` (required) | `string` | | ENS name. Normalized automatically. |
Also takes the [read options](/docs/reference/sdk/client#read-options).
## Returns [#returns]
Resolves to `Address | null`. The approved address, or `null`.
## Errors [#errors]
| Error | Codes | When |
| --- | --- | --- |
| [`InvalidInputError`](/docs/reference/errors/invalid-input-error) | [`INVALID_NAME`](/docs/reference/errors/INVALID_NAME) | the name cannot be normalized. |
| [`UnsupportedError`](/docs/reference/errors/unsupported-error) | [`UNSUPPORTED_PROTOCOL`](/docs/reference/errors/UNSUPPORTED_PROTOCOL) | ENSv2 names and unwrapped subnames. |
| [`NetworkError`](/docs/reference/errors/network-error) | [`RPC_REQUEST_FAILED`](/docs/reference/errors/RPC_REQUEST_FAILED), [`RPC_TIMEOUT`](/docs/reference/errors/RPC_TIMEOUT), [`RATE_LIMITED`](/docs/reference/errors/RATE_LIMITED) | the RPC request fails. |
It can also fail with the errors every read can (`Errors.CommonError`: `ConfigError`, `ContractRevertError`, `InternalError`, `NetworkError`).
See [How errors work](/docs/sdk/errors-explained).
## Examples [#examples]
```ts title="Reading a name's approval"
const approved = await ens.approval.getToken({ name: "alice.eth" })
```
```ts title="Reading with a standalone call"
import { Actions } from "@ensforge/sdk"
const approved = await Actions.approval.getToken(publicClient, { name: "vitalik.eth" })
```
```ts title="Reading in an Effect program"
import { Actions } from "@ensforge/sdk/effect"
const approved = yield* Actions.approval.getToken(ens, { name: "alice.eth" })
```
## See also [#see-also]
- [`approval.setToken`](/docs/reference/sdk/approval/set-token) to change it
# approval
> For the complete documentation index, see [llms.txt](https://ensforge.com/llms.txt).
List the 6 approval actions of @ensforge/sdk and whether each reads, writes or signs. Covers getDelegate, getOperator, getToken, setDelegate, setOperator.
Source: https://ensforge.com/docs/reference/sdk/approval
Call them as `ens.approval.(options)` on a client, or `Actions.approval.(client, options)`.
## Reads [#reads]
| Action | Description |
| --- | --- |
| [`getDelegate`](/docs/reference/sdk/approval/get-delegate) (batchable) | Checks whether a delegate may edit a name's records on its public resolver (`isApprovedFor`). |
| [`getOperator`](/docs/reference/sdk/approval/get-operator) (batchable) | Checks whether an operator may manage everything an owner holds on an ENS contract (`isApprovedForAll`). |
| [`getToken`](/docs/reference/sdk/approval/get-token) (batchable) | Reads the address approved to transfer one ENSv1 name token (`getApproved`). |
## Writes [#writes]
| Action | Description |
| --- | --- |
| [`setDelegate`](/docs/reference/sdk/approval/set-delegate) | Approves or revokes a delegate who may edit a name's records on its public resolver. |
| [`setOperator`](/docs/reference/sdk/approval/set-operator) | Approves or revokes an operator for everything the signer holds on an ENS contract (`setApprovalForAll`). |
| [`setToken`](/docs/reference/sdk/approval/set-token) | Approves one address to transfer one ENSv1 name token, or clears the approval. |
# approval.setDelegate
> For the complete documentation index, see [llms.txt](https://ensforge.com/llms.txt).
Approves or revokes a delegate who may edit a name's records on its public resolver. Options, result, errors and examples for approval.setDelegate.
Source: https://ensforge.com/docs/reference/sdk/approval/set-delegate
Approves or revokes a delegate who may edit a name's records on its public resolver. Resolves once the transaction is submitted.
## When to use [#when-to-use]
Use to let another account manage a profile on a PublicResolver. Use [`setDelegateSync`](/docs/reference/sdk/approval/set-delegate#wait-for-the-receipt-with-setdelegatesync) to wait for the receipt.
## Details [#details]
- A delegate can edit every record of the name; for per-record access on a
PermissionedResolver use [`permission.setRecordAccess`](/docs/reference/sdk/permission/set-record-access).
## Signature [#signature]
```ts
function setDelegate(
client: Like,
options: setDelegate.Options & Write.Options,
): Promise
```
Call it as `ens.approval.setDelegate(options)` on a client, or `Actions.approval.setDelegate(client, options)`.
## Parameters [#parameters]
| Option | Type | Default | Description |
| --- | --- | --- | --- |
| `name` (required) | `string` | | ENS name. Normalized automatically. |
| `delegate` (required) | `string` | | Account to approve or revoke. |
| `approved` (required) | `boolean` | | `true` to approve the delegate, `false` to revoke it. |
Also takes the [write options](/docs/reference/sdk/client#write-options).
## Returns [#returns]
Resolves to `Write.Result`. Submitted transaction hashes and the plan that produced them.
| Field | Type | Description |
| --- | --- | --- |
| `hash` | `Hex` | Hash of the last transaction. |
| `hashes` | `readonly Hex[]` | Every submitted transaction, in order. |
| `id` | `string` | EIP-5792 bundle id when the calls were sent as one batch. |
| `plan` | `Plan` | The plan the write executed: its steps, in order, as they were submitted. |
## Errors [#errors]
| Error | Codes | When |
| --- | --- | --- |
| [`InvalidInputError`](/docs/reference/errors/invalid-input-error) | [`INVALID_NAME`](/docs/reference/errors/INVALID_NAME), [`INVALID_ADDRESS`](/docs/reference/errors/INVALID_ADDRESS) | invalid input. |
| [`NotFoundError`](/docs/reference/errors/not-found-error) | [`RESOLVER_NOT_FOUND`](/docs/reference/errors/RESOLVER_NOT_FOUND) | the name has no resolver. |
| [`UnsupportedError`](/docs/reference/errors/unsupported-error) | [`RESOLVER_PROFILE_UNSUPPORTED`](/docs/reference/errors/RESOLVER_PROFILE_UNSUPPORTED) | PermissionedResolvers. |
| [`UnauthorizedError`](/docs/reference/errors/unauthorized-error) | [`NOT_OWNER`](/docs/reference/errors/NOT_OWNER) | the signer does not own the name. |
| [`UserRejectedError`](/docs/reference/errors/user-rejected-error) | [`USER_REJECTED`](/docs/reference/errors/USER_REJECTED) | the user rejects the request. |
| [`WalletError`](/docs/reference/errors/wallet-error) | [`CHAIN_MISMATCH`](/docs/reference/errors/CHAIN_MISMATCH), [`ACCOUNT_NOT_FOUND`](/docs/reference/errors/ACCOUNT_NOT_FOUND) | the wallet is on another chain or has no account to sign with. |
| [`UnsupportedError`](/docs/reference/errors/unsupported-error) | [`WALLET_BATCH_UNSUPPORTED`](/docs/reference/errors/WALLET_BATCH_UNSUPPORTED) | with `mode: "batch"` or a paymaster when the wallet cannot send calls as one batch. |
It can also fail with the errors every write can (`Errors.WriteError`: the common errors plus `InsufficientFundsError`, `TransactionError`, `UnsupportedError`, `UserRejectedError`, `WalletError`).
See [How errors work](/docs/sdk/errors-explained).
## Examples [#examples]
```ts title="Approving a delegate"
const { hash } = await ens.approval.setDelegate({ name: "alice.eth", delegate: "0xB0b0000000000000000000000000000000000000", approved: true })
```
```ts title="Approving a delegate with a standalone call"
import { Actions } from "@ensforge/sdk"
await Actions.approval.setDelegate(ens, { name: "alice.eth", delegate: "0xB0b0000000000000000000000000000000000000", approved: true })
```
```ts title="Approving a delegate in an Effect program"
import { Actions } from "@ensforge/sdk/effect"
yield* Actions.approval.setDelegate(ens, { name: "alice.eth", delegate: "0xB0b0000000000000000000000000000000000000", approved: true })
```
## Plan methods [#plan-methods]
Each method takes the same options as `approval.setDelegate` and sends nothing. See [Preview before sending](/docs/sdk/preview-before-sending).
| Method | Description |
| --- | --- |
| `approval.setDelegate.prepare(options)` | Builds the plan without sending anything. |
| `approval.setDelegate.simulate(options)` | Simulates the plan with `eth_call`, reporting each step. |
| `approval.setDelegate.estimateGas(options)` | Estimates the gas and ETH the plan needs. |
## Wait for the receipt with `setDelegateSync` [#wait-for-the-receipt-with-setdelegatesync]
Approves or revokes a delegate who may edit a name's records on its public resolver. Resolves once the receipt is in.
Use when the next step depends on the change being on-chain.
`approval.setDelegateSync` takes the same options plus [`confirmations` and `timeout`](/docs/reference/sdk/client#sync-options).
Resolves to `Write.SyncResult`. Receipts plus the submitted hashes and plan.
```ts title="Approving a delegate and waiting"
const { receipt } = await ens.approval.setDelegateSync({ name: "alice.eth", delegate: "0xB0b0000000000000000000000000000000000000", approved: true })
```
```ts title="Waiting with a standalone call"
import { Actions } from "@ensforge/sdk"
await Actions.approval.setDelegateSync(ens, { name: "alice.eth", delegate: "0xB0b0000000000000000000000000000000000000", approved: true })
```
```ts title="Waiting in an Effect program"
import { Actions } from "@ensforge/sdk/effect"
yield* Actions.approval.setDelegateSync(ens, { name: "alice.eth", delegate: "0xB0b0000000000000000000000000000000000000", approved: true })
```
## See also [#see-also]
- [`approval.getDelegate`](/docs/reference/sdk/approval/get-delegate) to read it
# approval.setOperator
> For the complete documentation index, see [llms.txt](https://ensforge.com/llms.txt).
Approves or revokes an operator for everything the signer holds on an ENS contract (setApprovalForAll). Options, errors and examples for approval.setOperator.
Source: https://ensforge.com/docs/reference/sdk/approval/set-operator
Approves or revokes an operator for everything the signer holds on an ENS contract (`setApprovalForAll`). Resolves once the transaction is submitted.
## When to use [#when-to-use]
Use to let a marketplace or manager act on all your names in one contract. Use [`setOperatorSync`](/docs/reference/sdk/approval/set-operator#wait-for-the-receipt-with-setoperatorsync) to wait for the receipt.
## Details [#details]
- `contract`: the ENSv1 `"registry"`, `"registrar"` or `"wrapper"`, or any ENSv2 registry
or resolver by address.
- On ENSv2 registries an operator can transfer names; other changes need roles.
## Signature [#signature]
```ts
function setOperator(
client: Like,
options: setOperator.Options & Write.Options,
): Promise
```
Call it as `ens.approval.setOperator(options)` on a client, or `Actions.approval.setOperator(client, options)`.
## Parameters [#parameters]
| Option | Type | Default | Description |
| --- | --- | --- | --- |
| `operator` (required) | `string` | | Account to approve or revoke. |
| `approved` (required) | `boolean` | | `true` to approve the operator, `false` to revoke it. |
| `contract` (required) | `ApprovalContract` | | `"registry"`, `"registrar"`, `"wrapper"`, or a registry or resolver address. |
Also takes the [write options](/docs/reference/sdk/client#write-options).
## Returns [#returns]
Resolves to `Write.Result`. Submitted transaction hashes and the plan that produced them.
| Field | Type | Description |
| --- | --- | --- |
| `hash` | `Hex` | Hash of the last transaction. |
| `hashes` | `readonly Hex[]` | Every submitted transaction, in order. |
| `id` | `string` | EIP-5792 bundle id when the calls were sent as one batch. |
| `plan` | `Plan` | The plan the write executed: its steps, in order, as they were submitted. |
## Errors [#errors]
| Error | Codes | When |
| --- | --- | --- |
| [`InvalidInputError`](/docs/reference/errors/invalid-input-error) | [`INVALID_ADDRESS`](/docs/reference/errors/INVALID_ADDRESS) | invalid addresses. |
| [`UnsupportedError`](/docs/reference/errors/unsupported-error) | [`UNSUPPORTED_ON_DEPLOYMENT`](/docs/reference/errors/UNSUPPORTED_ON_DEPLOYMENT) | ENSv1 contracts without ENSv1. |
| [`UserRejectedError`](/docs/reference/errors/user-rejected-error) | [`USER_REJECTED`](/docs/reference/errors/USER_REJECTED) | the user rejects the request. |
| [`WalletError`](/docs/reference/errors/wallet-error) | [`CHAIN_MISMATCH`](/docs/reference/errors/CHAIN_MISMATCH), [`ACCOUNT_NOT_FOUND`](/docs/reference/errors/ACCOUNT_NOT_FOUND) | the wallet is on another chain or has no account to sign with. |
| [`UnsupportedError`](/docs/reference/errors/unsupported-error) | [`WALLET_BATCH_UNSUPPORTED`](/docs/reference/errors/WALLET_BATCH_UNSUPPORTED) | with `mode: "batch"` or a paymaster when the wallet cannot send calls as one batch. |
It can also fail with the errors every write can (`Errors.WriteError`: the common errors plus `InsufficientFundsError`, `TransactionError`, `UnsupportedError`, `UserRejectedError`, `WalletError`).
See [How errors work](/docs/sdk/errors-explained).
## Examples [#examples]
```ts title="Approving a manager"
const { hash } = await ens.approval.setOperator({ operator: "0xB0b0000000000000000000000000000000000000", approved: true, contract: "wrapper" })
```
```ts title="Approving a manager with a standalone call"
import { Actions } from "@ensforge/sdk"
await Actions.approval.setOperator(ens, { operator: "0xB0b0000000000000000000000000000000000000", approved: true, contract: "wrapper" })
```
```ts title="Approving a manager in an Effect program"
import { Actions } from "@ensforge/sdk/effect"
yield* Actions.approval.setOperator(ens, { operator: "0xB0b0000000000000000000000000000000000000", approved: true, contract: "wrapper" })
```
## Plan methods [#plan-methods]
Each method takes the same options as `approval.setOperator` and sends nothing. See [Preview before sending](/docs/sdk/preview-before-sending).
| Method | Description |
| --- | --- |
| `approval.setOperator.prepare(options)` | Builds the plan without sending anything. |
| `approval.setOperator.simulate(options)` | Simulates the plan with `eth_call`, reporting each step. |
| `approval.setOperator.estimateGas(options)` | Estimates the gas and ETH the plan needs. |
## Wait for the receipt with `setOperatorSync` [#wait-for-the-receipt-with-setoperatorsync]
Approves or revokes an operator for everything the signer holds on an ENS contract (`setApprovalForAll`). Resolves once the receipt is in.
Use when the next step depends on the change being on-chain.
`approval.setOperatorSync` takes the same options plus [`confirmations` and `timeout`](/docs/reference/sdk/client#sync-options).
Resolves to `Write.SyncResult`. Receipts plus the submitted hashes and plan.
```ts title="Approving a manager and waiting"
const { receipt } = await ens.approval.setOperatorSync({ operator: "0xB0b0000000000000000000000000000000000000", approved: true, contract: "wrapper" })
```
```ts title="Waiting with a standalone call"
import { Actions } from "@ensforge/sdk"
await Actions.approval.setOperatorSync(ens, { operator: "0xB0b0000000000000000000000000000000000000", approved: true, contract: "wrapper" })
```
```ts title="Waiting in an Effect program"
import { Actions } from "@ensforge/sdk/effect"
yield* Actions.approval.setOperatorSync(ens, { operator: "0xB0b0000000000000000000000000000000000000", approved: true, contract: "wrapper" })
```
## See also [#see-also]
- [`approval.getOperator`](/docs/reference/sdk/approval/get-operator) to read it
# approval.setToken
> For the complete documentation index, see [llms.txt](https://ensforge.com/llms.txt).
Approves one address to transfer one ENSv1 name token, or clears the approval. Options, result, errors and examples for approval.setToken.
Source: https://ensforge.com/docs/reference/sdk/approval/set-token
Approves one address to transfer one ENSv1 name token, or clears the approval. Resolves once the transaction is submitted.
## When to use [#when-to-use]
Use to let a buyer or escrow take a single name. Use [`setTokenSync`](/docs/reference/sdk/approval/set-token#wait-for-the-receipt-with-settokensync) to wait for the receipt.
## Details [#details]
- Wrapped names approve on the NameWrapper (blocked by `cannotApprove`); unwrapped `.eth`
names on the BaseRegistrar.
- `to: null` clears it. ENSv2 names use operators instead.
## Signature [#signature]
```ts
function setToken(
client: Like,
options: setToken.Options & Write.Options,
): Promise
```
Call it as `ens.approval.setToken(options)` on a client, or `Actions.approval.setToken(client, options)`.
## Parameters [#parameters]
| Option | Type | Default | Description |
| --- | --- | --- | --- |
| `name` (required) | `string` | | ENS name. Normalized automatically. |
| `to` (required) | `string \| null` | | Address to approve, or `null` to clear. |
Also takes the [write options](/docs/reference/sdk/client#write-options).
## Returns [#returns]
Resolves to `Write.Result`. Submitted transaction hashes and the plan that produced them.
| Field | Type | Description |
| --- | --- | --- |
| `hash` | `Hex` | Hash of the last transaction. |
| `hashes` | `readonly Hex[]` | Every submitted transaction, in order. |
| `id` | `string` | EIP-5792 bundle id when the calls were sent as one batch. |
| `plan` | `Plan` | The plan the write executed: its steps, in order, as they were submitted. |
## Errors [#errors]
| Error | Codes | When |
| --- | --- | --- |
| [`InvalidInputError`](/docs/reference/errors/invalid-input-error) | [`INVALID_NAME`](/docs/reference/errors/INVALID_NAME), [`INVALID_ADDRESS`](/docs/reference/errors/INVALID_ADDRESS) | invalid input. |
| [`NameStateError`](/docs/reference/errors/name-state-error) | [`NAME_EXPIRED`](/docs/reference/errors/NAME_EXPIRED), [`NAME_NOT_REGISTERED`](/docs/reference/errors/NAME_NOT_REGISTERED) | the name is not registered. |
| [`NameStateError`](/docs/reference/errors/name-state-error) | [`NAME_UNREACHABLE`](/docs/reference/errors/NAME_UNREACHABLE) | ENSv2 resolution no longer reaches the name. |
| [`UnsupportedError`](/docs/reference/errors/unsupported-error) | [`UNSUPPORTED_PROTOCOL`](/docs/reference/errors/UNSUPPORTED_PROTOCOL) | ENSv2 names and unwrapped subnames. |
| [`UnauthorizedError`](/docs/reference/errors/unauthorized-error) | [`NOT_OWNER`](/docs/reference/errors/NOT_OWNER), [`FUSE_BURNED`](/docs/reference/errors/FUSE_BURNED) | the account may not approve it. |
| [`UserRejectedError`](/docs/reference/errors/user-rejected-error) | [`USER_REJECTED`](/docs/reference/errors/USER_REJECTED) | the user rejects the request. |
| [`WalletError`](/docs/reference/errors/wallet-error) | [`CHAIN_MISMATCH`](/docs/reference/errors/CHAIN_MISMATCH), [`ACCOUNT_NOT_FOUND`](/docs/reference/errors/ACCOUNT_NOT_FOUND) | the wallet is on another chain or has no account to sign with. |
| [`UnsupportedError`](/docs/reference/errors/unsupported-error) | [`WALLET_BATCH_UNSUPPORTED`](/docs/reference/errors/WALLET_BATCH_UNSUPPORTED) | with `mode: "batch"` or a paymaster when the wallet cannot send calls as one batch. |
It can also fail with the errors every write can (`Errors.WriteError`: the common errors plus `InsufficientFundsError`, `TransactionError`, `UnsupportedError`, `UserRejectedError`, `WalletError`).
See [How errors work](/docs/sdk/errors-explained).
## Examples [#examples]
```ts title="Approving a buyer"
const { hash } = await ens.approval.setToken({ name: "alice.eth", to: "0xB0b0000000000000000000000000000000000000" })
```
```ts title="Approving a buyer with a standalone call"
import { Actions } from "@ensforge/sdk"
await Actions.approval.setToken(ens, { name: "alice.eth", to: "0xB0b0000000000000000000000000000000000000" })
```
```ts title="Approving a buyer in an Effect program"
import { Actions } from "@ensforge/sdk/effect"
yield* Actions.approval.setToken(ens, { name: "alice.eth", to: "0xB0b0000000000000000000000000000000000000" })
```
## Plan methods [#plan-methods]
Each method takes the same options as `approval.setToken` and sends nothing. See [Preview before sending](/docs/sdk/preview-before-sending).
| Method | Description |
| --- | --- |
| `approval.setToken.prepare(options)` | Builds the plan without sending anything. |
| `approval.setToken.simulate(options)` | Simulates the plan with `eth_call`, reporting each step. |
| `approval.setToken.estimateGas(options)` | Estimates the gas and ETH the plan needs. |
## Wait for the receipt with `setTokenSync` [#wait-for-the-receipt-with-settokensync]
Approves one address to transfer one ENSv1 name token, or clears the approval. Resolves once the receipt is in.
Use when the next step depends on the change being on-chain.
`approval.setTokenSync` takes the same options plus [`confirmations` and `timeout`](/docs/reference/sdk/client#sync-options).
Resolves to `Write.SyncResult`. Receipts plus the submitted hashes and plan.
```ts title="Approving a buyer and waiting"
const { receipt } = await ens.approval.setTokenSync({ name: "alice.eth", to: "0xB0b0000000000000000000000000000000000000" })
```
```ts title="Waiting with a standalone call"
import { Actions } from "@ensforge/sdk"
await Actions.approval.setTokenSync(ens, { name: "alice.eth", to: "0xB0b0000000000000000000000000000000000000" })
```
```ts title="Waiting in an Effect program"
import { Actions } from "@ensforge/sdk/effect"
yield* Actions.approval.setTokenSync(ens, { name: "alice.eth", to: "0xB0b0000000000000000000000000000000000000" })
```
## See also [#see-also]
- [`approval.getToken`](/docs/reference/sdk/approval/get-token) to read it
# batch
> For the complete documentation index, see [llms.txt](https://ensforge.com/llms.txt).
Runs several reads together, in as few round trips as possible. Parameters, return value, errors and examples for batch in @ensforge/sdk.
Source: https://ensforge.com/docs/reference/sdk/batch
Runs several reads together, in as few round trips as possible.
## When to use [#when-to-use]
Use to load a page's data at once: profiles, names, prices, permissions.
## Details [#details]
- `requests` is a list (results come back as a tuple) or a record (results keep its keys).
- Contract reads coalesce into Multicall3 calls, per block; resolution reads (records, primary
names) keep their Universal Resolver call, so CCIP-Read and off-chain names work.
- With `allowFailure` (default) each result is `{ status: "success", result }` or
`{ status: "failure", error }`; with `allowFailure: false` the first failure rejects.
- Only reads with `.request` can be batched; writes combine with `Plan.merge`.
## Signature [#signature]
```ts
function batch(
client: Like,
options: BatchOptions,
): Promise>
```
Call it as `ens.batch(options)` on a client, or `Actions.batch(client, options)`.
## Parameters [#parameters]
| Option | Type | Default | Description |
| --- | --- | --- | --- |
| `requests` (required) | `Requests` | | Deferred reads from `action.request(options)`, as a list or a record. |
| `allowFailure` | `boolean` | `true` | Report each request's failure in its result instead of failing the batch. |
| `signal` | `AbortSignal` | | Cancels the batch; the Promise rejects with `signal.reason`. |
## Returns [#returns]
Resolves to `{ readonly results: Results; }`. Results in the requests' shape.
| Field | Type | Description |
| --- | --- | --- |
| `results` | `Results` | |
## Errors [#errors]
| Error | Codes | When |
| --- | --- | --- |
| [`InvalidInputError`](/docs/reference/errors/invalid-input-error) | [`INVALID_RECORD_VALUE`](/docs/reference/errors/INVALID_RECORD_VALUE) | a request that cannot be batched. |
| | | The first request's error with `allowFailure: false`. |
It can also fail with the errors every read can (`Errors.CommonError`: `ConfigError`, `ContractRevertError`, `InternalError`, `NetworkError`).
See [How errors work](/docs/sdk/errors-explained).
## Examples [#examples]
```ts title="Loading a profile"
import { Actions } from "@ensforge/sdk"
const { results } = await ens.batch({
requests: {
address: Actions.record.getAddress.request({ name: "nick.eth" }),
avatar: Actions.record.getText.request({ name: "nick.eth", key: "avatar" }),
},
})
```
```ts title="A list with a standalone call"
import { Actions } from "@ensforge/sdk"
const { results: [state, primary] } = await Actions.batch(publicClient, {
requests: [Actions.name.get.request({ name: "nick.eth" }), Actions.primaryName.get.request({ address })],
allowFailure: false,
})
```
```ts title="Batching in an Effect program"
import { Actions as Requests } from "@ensforge/sdk"
import { Actions } from "@ensforge/sdk/effect"
const { results } = yield* Actions.batch(ens, {
requests: [Requests.name.get.request({ name: "nick.eth" })],
})
```
## See also [#see-also]
- [`name.get`](/docs/reference/sdk/name/get) and every other read's `.request`
# Client
> For the complete documentation index, see [llms.txt](https://ensforge.com/llms.txt).
Look up the options of Ensforge.create, the action groups, and the read, write and plan option types that every @ensforge/sdk action shares.
Source: https://ensforge.com/docs/reference/sdk/client
The client, its options and the option and result types every action shares. See [Create a client](/docs/sdk/create-a-client).
## Create a client [#create-a-client]
### `Ensforge.create` [#ensforgecreate]
Creates an ensforge client from viem clients.
```ts
function create(options: CreateOptions): Client
```
Use once per chain, at app start, then add action groups with `extend`.
- The deployment is chosen by chain ID (mainnet, Sepolia); other chains need `deployment`.
- `walletClient` can be a getter, so a wallet that connects later works.
- `chains` adds clients for other chains, for the writes ENS makes there: primary names on L2s
(`primaryName.set` with `coin: { chainId }`).
- The client and its `config` are frozen.
```ts title="Creating a client"
import { Ensforge, ensActions } from "@ensforge/sdk"
const ens = Ensforge.create({ publicClient, walletClient }).extend(ensActions())
```
```ts title="A devnet"
import { Deployments } from "@ensforge/contracts"
import { Ensforge } from "@ensforge/sdk"
const ens = Ensforge.create({
publicClient: anvil,
deployment: Deployments.define({ name: "devnet", chainId: 31337, v2: devnetV2 }),
})
```
```ts title="Adding an L2 for primary names"
import { Ensforge, ensActions } from "@ensforge/sdk"
const ens = Ensforge.create({
publicClient,
walletClient,
chains: { 10: { publicClient: optimismClient, walletClient: optimismWallet } },
}).extend(ensActions())
await ens.primaryName.set({ name: "alice.eth", coin: { chainId: 10 } })
```
Errors:
- `ConfigError` ([`UNKNOWN_CHAIN`](/docs/reference/errors/UNKNOWN_CHAIN)) when the chain has no built-in deployment and none is given.
- `ConfigError` ([`INVALID_DEPLOYMENT`](/docs/reference/errors/INVALID_DEPLOYMENT)) when `deployment` is invalid or for another chain.
- `ConfigError` ([`CHAIN_NOT_CONFIGURED`](/docs/reference/errors/CHAIN_NOT_CONFIGURED)) when an entry of `chains` holds clients of another chain.
### `Ensforge.from` [#ensforgefrom]
Returns `client` when it is an ensforge client, otherwise an ensforge client for the viem
client, created once and reused.
```ts
function from(client: Like): Client
```
Use in your own helpers that accept either client. Every action already does this.
Errors:
- `ConfigError` ([`UNKNOWN_CHAIN`](/docs/reference/errors/UNKNOWN_CHAIN)) when a bare viem client is on a chain without a built-in deployment.
### `Ensforge.is` [#ensforgeis]
Whether `value` is an ensforge client.
```ts
function is(value: unknown): value is Client
```
### `Ensforge.fromWagmi` [#ensforgefromwagmi]
Creates an ensforge client from a wagmi config: reads use wagmi's client for the ENS chain, and
writes use whichever wallet is connected when they run.
```ts
function fromWagmi(config: WagmiConfig, options: fromWagmi.Options = {}): Client
```
Use in apps that already have a wagmi config (RainbowKit, ConnectKit, Dynamic, Privy, Reown
AppKit), instead of passing viem clients to `Ensforge.create`.
- Works with wagmi 2 and 3.
- The ENS chain is `chainId`, else mainnet when the config has it, else the first configured
chain ensforge has a deployment for. Its transport must be in the wagmi config.
- The wallet is looked up on every write, so account and connector changes are followed. With
no wallet connected, writes fail with [`WALLET_NOT_CONFIGURED`](/docs/reference/errors/WALLET_NOT_CONFIGURED).
- A wallet on another chain is asked to switch first, as wagmi's own `writeContract` does.
- Every other chain of the wagmi config becomes one of the client's `chains`, so writes ENS
makes there (an L2 primary name) use wagmi's clients and wallet; `chains` adds or overrides.
- `fromWagmi` lives on the `Ensforge` from `@ensforge/sdk/wagmi`, so apps without wagmi never
load it. The client it returns works with everything in `@ensforge/sdk`.
```ts title="A client for a wagmi app"
import { ensActions } from "@ensforge/sdk"
import { Ensforge } from "@ensforge/sdk/wagmi"
const ens = Ensforge.fromWagmi(wagmiConfig).extend(ensActions())
await ens.record.set({ name: "alice.eth", texts: { url: "https://alice.xyz" } })
```
```ts title="Sepolia, without automatic chain switching"
import { Ensforge } from "@ensforge/sdk/wagmi"
const ens = Ensforge.fromWagmi(wagmiConfig, { chainId: 11155111, switchChain: false })
```
Errors:
- `ConfigError` ([`UNKNOWN_CHAIN`](/docs/reference/errors/UNKNOWN_CHAIN)) when no ENS chain can be chosen or the wagmi config has no transport for it.
- `ConfigError` ([`INVALID_DEPLOYMENT`](/docs/reference/errors/INVALID_DEPLOYMENT)) when `deployment` is invalid or for another chain.
- `ConfigError` ([`CHAIN_NOT_CONFIGURED`](/docs/reference/errors/CHAIN_NOT_CONFIGURED)) when an entry of `chains` holds clients of another chain.
### `Ensforge.layer` [#ensforgelayer]
A layer that creates the client with `Ensforge.create`.
```ts
function layer(options: CreateOptions): Layer.Layer
```
### `Ensforge.ChainClients` [#ensforgechainclients]
viem clients for a chain other than the ENS chain, e.g. an L2 where an address sets its primary
name for that chain.
```ts
type ChainClients
```
| Field | Type | Description |
| --- | --- | --- |
| `publicClient` | `ViemClient` | viem client for reads and simulation on the chain. |
| `walletClient` (optional) | `ViemWalletClient \| (() => ViemWalletClient \| undefined \| Promise)` | viem client for writes on the chain, or a getter for wallets that change (wagmi connectors). |
### `Ensforge.Client` [#ensforgeclient]
The ensforge client. Its top level holds what app code reads day to day and `extend`; action
groups added by `extend` sit beside them.
```ts
type Client = actions & ClientBase;
```
| Field | Type | Description |
| --- | --- | --- |
| `chain` | `{ readonly id: number; readonly name: string }` | The chain the client reads and writes ENS on. |
| `account` | `Address` | Default signer address, or `undefined` without a wallet. |
| `deployment` | `Deployments.Profile` | ENS deployments on this chain (addresses, capabilities, provenance). |
| `publicClient` | `ViemClient` | The viem client used for reads, as an escape hatch. |
| `config` | `Config` | The configuration the client was created with. |
| `extend` | `( decorator: (client: Client