# 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 (
    {results.map((result, index) => (
  • {names[index]}: {result.isLoading ? "..." : result.data}
  • ))}
); } ``` 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) => (
  1. {event.step.description}: {event.status}
  2. ))}
{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) => added, ) => Client` | Adds action groups; returns a new client. | ### `Ensforge.ClientBase` [#ensforgeclientbase] Members every ensforge client has, whatever action groups it carries. ```ts interface 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) => added, ) => Client` | Adds action groups; returns a new client. | ### `Ensforge.Config` [#ensforgeconfig] Behaviour settings, set once in `Ensforge.create` and rarely read back. ```ts type Config ``` | Option | Type | Default | Description | | --- | --- | --- | --- | | `ccipRead` (required) | `{ readonly gatewayUrls: readonly string[] } \| false` | | Off-chain resolution (CCIP-Read) through the Universal Resolver's batch gateways. `false` disables it. | | `batch` (required) | `{ readonly multicall: false \| { readonly batchSize: number; readonly wait: number }; }` | | Coalescing of concurrent contract reads into multicall. | | `blockTag` (required) | `BlockTag` | | Default block tag for reads. | | `storage` (required) | `Plan.Storage` | | Where multi-step plans save their progress. | | `simulate` (required) | `boolean` | | Whether writes are simulated before the wallet prompt. | | `indexer` (required) | `Indexer` | | Indexer for `indexer.*` actions and migration discovery, when configured. | | `gateways` (required) | `{ readonly [protocol in keyof Gateways]-?: string }` | | Storage gateways for avatars and content-hash URLs, defaults filled in. | ### `Ensforge.CreateOptions` [#ensforgecreateoptions] Options for `Ensforge.create`. ```ts type CreateOptions ``` | Option | Type | Default | Description | | --- | --- | --- | --- | | `publicClient` (required) | `ViemClient` | | viem client for reads. Its chain selects the deployment. | | `walletClient` | `ViemWalletClient \| (() => ViemWalletClient \| undefined \| Promise)` | `publicClient` when it has an account | viem client for writes, or a getter for wallets that change (wagmi connectors). | | `chains` | `Readonly>` | none; writes for another chain fail with [`CHAIN_NOT_CONFIGURED`](/docs/reference/errors/CHAIN_NOT_CONFIGURED) | Clients for other chains, by chain ID: writes ENS makes there (an L2 primary name) run on them, and plans for them resume on them. The signer is the same account on every chain. | | `account` | `Account \| Address` | the wallet client's account | Default signer for writes. | | `deployment` | `Deployments.Profile` | `Deployments.get({ chainId })` | ENS deployments. Required for chains ensforge does not ship (devnets, forks, other chains). | | `ccipRead` | `{ readonly gatewayUrls?: readonly string[] \| undefined } \| false` | the Universal Resolver's own batch gateway | Off-chain resolution. `false` disables CCIP-Read. `gatewayUrls` are the Universal Resolver's batch gateways and replace its default, not the gateways of individual resolvers. | | `batch` | `{ readonly multicall?: \| boolean \| { readonly batchSize?: number; readonly wait?: number } \| undefined; }` | `{ multicall: true }` | Coalesce concurrent reads into multicall. `wait` is in milliseconds. | | `blockTag` | `BlockTag` | `"latest"` | Default block tag for reads. | | `storage` | `Plan.Storage` | `Plan.memoryStorage()` | Where multi-step plans save their progress. | | `simulate` | `boolean` | `true` | Simulate writes before the wallet prompt. | | `indexer` | `Indexer` | none; indexer actions fail with [`INDEXER_NOT_CONFIGURED`](/docs/reference/errors/INDEXER_NOT_CONFIGURED) | Indexer for `indexer.*` actions and for discovering records and subnames during migration: `bigname()`, `goldsky()`, `fallback([...])` or `defineIndexer({...})` from `@ensforge/sdk/indexer`. | | `gateways` | `Gateways` | https://ipfs.io, https://arweave.net and https://api.gateway.ethswarm.org | Storage gateways for avatars (`record.getAvatar`) and content-hash URLs (`ContentHash.toGatewayUrl(uri, ens.config.gateways)`). A call's own `gateways` override them. | ### `Ensforge.Gateways` [#ensforgegateways] HTTP gateways that turn decentralized-storage URIs (avatars, content hashes) into URLs a browser can load. Each is an origin, such as `https://ipfs.io`. ```ts type Gateways ``` | Field | Type | Description | | --- | --- | --- | | `ipfs` (optional) | `string` | IPFS gateway, for `ipfs://`, `ipns://` and bare CIDs. The public `ipfs.io` is rate limited: use a dedicated gateway in production. | | `arweave` (optional) | `string` | Arweave gateway, for `ar://`. | | `swarm` (optional) | `string` | Swarm gateway, for `bzz://` content hashes. | ### `Ensforge.Like` [#ensforgelike] Anything an action accepts: an ensforge client or a bare viem client. ```ts type Like = Client | ViemClient; ``` ### `Ensforge.ViemClient` [#ensforgeviemclient] A viem client used for reads. viem's base client type keeps type checking fast; any `PublicClient` or `WalletClient` fits. ```ts type ViemClient = ViemBaseClient; ``` ### `Ensforge.ViemWalletClient` [#ensforgeviemwalletclient] A viem client that can sign: any `WalletClient`, or a client created with an account. ```ts type ViemWalletClient = ViemBaseClient; ``` ### `Ensforge.fromWagmi.Options` [#ensforgefromwagmioptions] Options for `fromWagmi`: those of `Ensforge.create`, without the viem clients. ```ts type Options = Omit & { /** * The ENS chain. * * @default mainnet when configured, else the first configured chain with a built-in deployment */ chainId?: number | undefined; /** * Ask the wallet to switch to the ENS chain before a write. With `false`, a wallet on another * chain fails with `WalletError` (`CHAIN_MISMATCH`). * * @default true */ switchChain?: boolean | undefined; }; ``` | Option | Type | Default | Description | | --- | --- | --- | --- | | `chains` | `Readonly>` | none; writes for another chain fail with [`CHAIN_NOT_CONFIGURED`](/docs/reference/errors/CHAIN_NOT_CONFIGURED) | Clients for other chains, by chain ID: writes ENS makes there (an L2 primary name) run on them, and plans for them resume on them. The signer is the same account on every chain. | | `account` | `Account \| Address` | the wallet client's account | Default signer for writes. | | `deployment` | `Deployments.Profile` | `Deployments.get({ chainId })` | ENS deployments. Required for chains ensforge does not ship (devnets, forks, other chains). | | `ccipRead` | `{ readonly gatewayUrls?: readonly string[] \| undefined } \| false` | the Universal Resolver's own batch gateway | Off-chain resolution. `false` disables CCIP-Read. `gatewayUrls` are the Universal Resolver's batch gateways and replace its default, not the gateways of individual resolvers. | | `batch` | `{ readonly multicall?: \| boolean \| { readonly batchSize?: number; readonly wait?: number } \| undefined; }` | `{ multicall: true }` | Coalesce concurrent reads into multicall. `wait` is in milliseconds. | | `blockTag` | `BlockTag` | `"latest"` | Default block tag for reads. | | `storage` | `Plan.Storage` | `Plan.memoryStorage()` | Where multi-step plans save their progress. | | `simulate` | `boolean` | `true` | Simulate writes before the wallet prompt. | | `indexer` | `Indexer` | none; indexer actions fail with [`INDEXER_NOT_CONFIGURED`](/docs/reference/errors/INDEXER_NOT_CONFIGURED) | Indexer for `indexer.*` actions and for discovering records and subnames during migration: `bigname()`, `goldsky()`, `fallback([...])` or `defineIndexer({...})` from `@ensforge/sdk/indexer`. | | `gateways` | `Gateways` | https://ipfs.io, https://arweave.net and https://api.gateway.ethswarm.org | Storage gateways for avatars (`record.getAvatar`) and content-hash URLs (`ContentHash.toGatewayUrl(uri, ens.config.gateways)`). A call's own `gateways` override them. | | `chainId` | `number` | mainnet when configured, else the first configured chain with a built-in deployment | The ENS chain. | | `switchChain` | `boolean` | `true` | Ask the wallet to switch to the ENS chain before a write. With `false`, a wallet on another chain fails with `WalletError` ([`CHAIN_MISMATCH`](/docs/reference/errors/CHAIN_MISMATCH)). | ### `Ensforge.Ensforge` [#ensforgeensforge] The ensforge client as an Effect service. ```ts class Ensforge ``` ```ts title="Providing and using the client" import { Effect } from "effect" import { Actions, Ensforge } from "@ensforge/sdk/effect" const program = Effect.gen(function* () { const ens = yield* Ensforge.Ensforge return yield* Actions.record.getText(ens, { name: "nick.eth", key: "url" }) }) await Effect.runPromise(program.pipe(Effect.provide(Ensforge.layer({ publicClient })))) ``` ## Action groups [#action-groups] Decorators add action groups to a client: `Ensforge.create(options).extend(ensActions())`. ### `approvalActions` [#approvalactions] Adds the `approval` actions to a client. ```ts function approvalActions() ``` ### `batchActions` [#batchactions] Adds `batch` to a client. ```ts function batchActions() ``` ### `dnsActions` [#dnsactions] Adds the `dns` actions to a client. ```ts function dnsActions() ``` ### `ensActions` [#ensactions] Adds every ENS action group to a client. ```ts function ensActions() ``` ```ts title="A client with every action" import { Ensforge, ensActions } from "@ensforge/sdk" const ens = Ensforge.create({ publicClient, walletClient }).extend(ensActions()) ``` ### `eventActions` [#eventactions] Adds the `event` actions to a client. ```ts function eventActions() ``` ### `indexerActions` [#indexeractions] Adds the `indexer` actions to a client. ```ts function indexerActions() ``` ### `migrationActions` [#migrationactions] Adds the `migration` actions to a client. ```ts function migrationActions() ``` ### `nameActions` [#nameactions] Adds the `name` actions to a client. ```ts function nameActions() ``` ### `permissionActions` [#permissionactions] Adds the `permission` actions to a client. ```ts function permissionActions() ``` ### `planActions` [#planactions] Adds the `plan` actions to a client. ```ts function planActions() ``` ### `primaryNameActions` [#primarynameactions] Adds the `primaryName` actions to a client. ```ts function primaryNameActions() ``` ### `recordActions` [#recordactions] Adds the `record` actions to a client. ```ts function recordActions() ``` ### `registrationActions` [#registrationactions] Adds the `registration` actions to a client. ```ts function registrationActions() ``` ### `registryActions` [#registryactions] Adds the `registry` actions to a client. ```ts function registryActions() ``` ### `resolverActions` [#resolveractions] Adds the `resolver` actions to a client. ```ts function resolverActions() ``` ### `roleActions` [#roleactions] Adds the `role` actions to a client. ```ts function roleActions() ``` ### `subnameActions` [#subnameactions] Adds the `subname` actions to a client. ```ts function subnameActions() ``` ### `wrapperActions` [#wrapperactions] Adds the `wrapper` actions to a client. ```ts function wrapperActions() ``` ### `ApprovalActions` [#approvalactions-1] `approval` actions bound to a client. ```ts type ApprovalActions ``` | Field | Type | Description | | --- | --- | --- | | `approval` | `` { /** Checks whether a delegate may edit a name's records on its public resolver (`isApprovedFor`). */ readonly getDelegate: Bound; /** Checks whether an operator may manage everything an owner holds on an ENS contract (`isApprovedForAll`). */ readonly getOperator: Bound; /** Reads the address approved to transfer one ENSv1 name token (`getApproved`). */ readonly getToken: Bound; /** Approves or revokes a delegate who may edit a name's records on its public resolver. Resolves once the transaction is submitted. */ readonly setDelegate: BoundWrite; /** Approves or revokes a delegate who may edit a name's records on its public resolver. Resolves once the receipt is in. */ readonly setDelegateSync: Bound; /** Approves or revokes an operator for everything the signer holds on an ENS contract (`setApprovalForAll`). Resolves once the transaction is submitted. */ readonly setOperator: BoundWrite; /** Approves or revokes an operator for everything the signer holds on an ENS contract (`setApprovalForAll`). Resolves once the receipt is in. */ readonly setOperatorSync: Bound; /** Approves one address to transfer one ENSv1 name token, or clears the approval. Resolves once the transaction is submitted. */ readonly setToken: BoundWrite; /** Approves one address to transfer one ENSv1 name token, or clears the approval. Resolves once the receipt is in. */ readonly setTokenSync: Bound; } `` | | ### `BatchActions` [#batchactions-1] `batch` bound to a client. ```ts type BatchActions ``` | Field | Type | Description | | --- | --- | --- | | `batch` | `batch.Bound` | | ### `DnsActions` [#dnsactions-1] `dns` actions bound to a client. ```ts type DnsActions ``` | Field | Type | Description | | --- | --- | --- | | `dns` | `` { /** Imports a DNS name into ENS with a DNSSEC proof of its `_ens` TXT record. Resolves once the transaction is submitted. */ readonly claim: BoundWrite; /** Imports a DNS name into ENS with a DNSSEC proof of its `_ens` TXT record. Resolves once the receipt is in. */ readonly claimSync: Bound; /** Reads the gasless DNS resolver a DNS name sets in an `ENS1` TXT record. */ readonly getOffchainResolver: Bound; /** Fetches the DNSSEC proof of a DNS name's `_ens` TXT record. */ readonly getProof: Bound; /** Reads DNS records and the zonehash a name stores on its resolver. */ readonly getRecords: Bound; /** Reads whether a DNS name is imported into ENS, and what it needs to be. */ readonly getStatus: Bound; /** Sets DNS records or the zonehash of a name on its public resolver. Resolves once the transaction is submitted. */ readonly setRecords: BoundWrite; /** Sets DNS records or the zonehash of a name on its public resolver. Resolves once the receipt is in. */ readonly setRecordsSync: Bound; } `` | | ### `EnsActions` [#ensactions-1] Every action group bound to a client. ```ts type EnsActions = ApprovalActions & DnsActions & EventActions & MigrationActions & NameActions & PermissionActions & PlanActions & PrimaryNameActions & RecordActions & RegistrationActions & RegistryActions & ResolverActions & RoleActions & SubnameActions & WrapperActions & BatchActions; ``` | Field | Type | Description | | --- | --- | --- | | `approval` | `` { /** Checks whether a delegate may edit a name's records on its public resolver (`isApprovedFor`). */ readonly getDelegate: Bound; /** Checks whether an operator may manage everything an owner holds on an ENS contract (`isApprovedForAll`). */ readonly getOperator: Bound; /** Reads the address approved to transfer one ENSv1 name token (`getApproved`). */ readonly getToken: Bound; /** Approves or revokes a delegate who may edit a name's records on its public resolver. Resolves once the transaction is submitted. */ readonly setDelegate: BoundWrite; /** Approves or revokes a delegate who may edit a name's records on its public resolver. Resolves once the receipt is in. */ readonly setDelegateSync: Bound; /** Approves or revokes an operator for everything the signer holds on an ENS contract (`setApprovalForAll`). Resolves once the transaction is submitted. */ readonly setOperator: BoundWrite; /** Approves or revokes an operator for everything the signer holds on an ENS contract (`setApprovalForAll`). Resolves once the receipt is in. */ readonly setOperatorSync: Bound; /** Approves one address to transfer one ENSv1 name token, or clears the approval. Resolves once the transaction is submitted. */ readonly setToken: BoundWrite; /** Approves one address to transfer one ENSv1 name token, or clears the approval. Resolves once the receipt is in. */ readonly setTokenSync: Bound; } `` | | | `dns` | `` { /** Imports a DNS name into ENS with a DNSSEC proof of its `_ens` TXT record. Resolves once the transaction is submitted. */ readonly claim: BoundWrite; /** Imports a DNS name into ENS with a DNSSEC proof of its `_ens` TXT record. Resolves once the receipt is in. */ readonly claimSync: Bound; /** Reads the gasless DNS resolver a DNS name sets in an `ENS1` TXT record. */ readonly getOffchainResolver: Bound; /** Fetches the DNSSEC proof of a DNS name's `_ens` TXT record. */ readonly getProof: Bound; /** Reads DNS records and the zonehash a name stores on its resolver. */ readonly getRecords: Bound; /** Reads whether a DNS name is imported into ENS, and what it needs to be. */ readonly getStatus: Bound; /** Sets DNS records or the zonehash of a name on its public resolver. Resolves once the transaction is submitted. */ readonly setRecords: BoundWrite; /** Sets DNS records or the zonehash of a name on its public resolver. Resolves once the receipt is in. */ readonly setRecordsSync: Bound; } `` | | | `event` | `{ /** Normalizes the ENS events in logs or transaction receipts. */ readonly decode: Bound; /** Reads the ENS events of one name over a block range, across ENSv1 and ENSv2. */ readonly get: Bound; /** Watches one name's ENS events as new blocks arrive. Resolves to a function that stops watching. */ readonly watch: Bound; }` | | | `migration` | `{ /** Reads whether an ENSv1 name can migrate to ENSv2, how, and what it becomes. */ readonly get: Bound; /** Migrates one or more ENSv1 names to ENSv2, carrying their resolver records and subnames. Resolves once the transaction is submitted. */ readonly migrate: BoundWrite; /** Migrates one or more ENSv1 names to ENSv2, carrying their resolver records and subnames. Resolves once the receipt is in. */ readonly migrateSync: Bound; }` | | | `name` | `` { /** Reads the full state of a name across ENSv1 and ENSv2: where it lives, who owns it, its resolver, expiry and whether it can be registered or renewed. */ readonly get: Bound; /** Recovers a label from its labelhash through the ENSv2 LabelStore. */ readonly getLabel: Bound; /** Resets the ENSv1 registry owner (manager) of an unwrapped `.eth` name, as its registrant. Resolves once the transaction is submitted. */ readonly reclaim: BoundWrite; /** Resets the ENSv1 registry owner (manager) of an unwrapped `.eth` name, as its registrant. Resolves once the receipt is in. */ readonly reclaimSync: Bound; /** Sets the ENSv1 manager (registry owner) of a name. Resolves once the transaction is submitted. */ readonly setManager: BoundWrite; /** Sets the ENSv1 manager (registry owner) of a name. Resolves once the receipt is in. */ readonly setManagerSync: Bound; /** Sets the ENSv1 registry TTL of a name. Resolves once the transaction is submitted. */ readonly setTtl: BoundWrite; /** Sets the ENSv1 registry TTL of a name. Resolves once the receipt is in. */ readonly setTtlSync: Bound; /** Sends a name to another account and resolves once the transaction is submitted. */ readonly transfer: BoundWrite; /** Sends a name to another account and resolves once the receipt is in. */ readonly transferSync: Bound; } `` | | | `permission` | `{ /** Checks whether an account may perform one operation on an ENS name, and lists exactly what it lacks when it may not. */ readonly check: Bound; /** Reads what an account may do with an ENS name: transfer it, change its resolver, edit records, create subnames and more, across ENSv1 ownership and ENSv2 roles. */ readonly get: Bound; /** Lets another account edit a name's records, or takes that access back. Resolves once the transaction is submitted. */ readonly setRecordAccess: BoundWrite; /** Lets another account edit a name's records, or takes that access back. Resolves once the receipt is in. */ readonly setRecordAccessSync: Bound; }` | | | `plan` | `` { /** Reads a saved plan and its progress. */ readonly get: Bound; /** Lists the saved plans of this client's chain and of its `chains`, newest first. */ readonly list: Bound; /** Records a transaction sent outside ensforge as a plan step's submission. */ readonly reconcile: Bound; /** Continues a saved plan after a failure or a reload. Resolves once the remaining transactions are submitted. */ readonly resume: Bound; /** Continues a saved plan and resolves once every receipt is in. */ readonly resumeSync: Bound; /** Sends any plan: one prepared by a write's `.prepare`, or several combined with `Plan.merge`. Resolves once the transaction is submitted. */ readonly send: BoundWrite; /** Sends any plan: one prepared by a write's `.prepare`, or several combined with `Plan.merge`. Resolves once the receipt is in. */ readonly sendSync: Bound; } `` | | | `primaryName` | `` { /** Reads the primary name of an address (ENSIP-19 reverse resolution), verified against the name's address record. */ readonly get: Bound; /** Sets or clears the primary name (reverse record) of an address. Resolves once the transaction is submitted. */ readonly set: BoundWrite; /** Sets or clears the primary name (reverse record) of an address. Resolves once the receipt is in. */ readonly setSync: Bound; /** Signs a claim to a primary name on one or more L2s, with one signature and no transaction. Anyone can then submit it on each chain with `primaryName.set`, so the account needs no gas or wallet connection there. */ readonly signClaim: Bound; } `` | | | `record` | `` { /** Reads any mix of a name's records in one request: texts, addresses, content hash, ABI, public key, name record, interface implementers and data records. */ readonly get: record.get.Bound; /** Reads one address record of an ENS name, for Ethereum by default or any coin (ENSIP-9, ENSIP-11). */ readonly getAddress: record.getAddress.Bound; /** Reads the avatar of an ENS name and resolves it to a URL a browser can load (ENSIP-12). */ readonly getAvatar: Bound; /** Reads the content hash of an ENS name (ENSIP-7), decoded into its protocol, value and URI. */ readonly getContentHash: Bound; /** Reads one text record of an ENS name, such as `url`, `avatar` or `com.twitter`. */ readonly getText: Bound; /** Writes records of an ENS name and resolves once the transaction is submitted. */ readonly set: BoundWrite; /** Writes records of an ENS name and resolves once the receipt is in. */ readonly setSync: Bound; } `` | | | `registration` | `` { /** Commits to registering `.eth` names, the first half of a registration. Resolves once the transaction is submitted. */ readonly commit: BoundWrite; /** Commits to registering `.eth` names, the first half of a registration. Resolves once the receipt is in. */ readonly commitSync: Bound; /** Reads where a registration commitment is in its window. */ readonly getCommitmentStatus: Bound; /** Reads the `.eth` registration settings: contracts, commitment window, minimum duration, grace period and accepted payment tokens. */ readonly getParameters: Bound; /** Quotes the price of registering a `.eth` name, in an ERC-20 payment token. */ readonly getPrice: Bound; /** Quotes renewing one or more `.eth` names, in an ERC-20 payment token. */ readonly getRenewalPrice: Bound; /** Checks whether a `.eth` name can be registered now. */ readonly isAvailable: Bound; /** Registers one or more `.eth` names: approve, commit, wait, register, then records and primary name. Resolves once the transaction is submitted. */ readonly register: BoundWrite; /** Registers one or more `.eth` names: approve, commit, wait, register, then records and primary name. Resolves once the receipt is in. */ readonly registerSync: Bound; /** Renews one or more `.eth` names, ENSv1 or ENSv2, paying in an ERC-20 token. Resolves once the transaction is submitted. */ readonly renew: BoundWrite; /** Renews one or more `.eth` names, ENSv1 or ENSv2, paying in an ERC-20 token. Resolves once the receipt is in. */ readonly renewSync: Bound; } `` | | | `registry` | `{ /** Sets or removes the subregistry of an ENSv2 name. Resolves once the transaction is submitted. */ readonly attach: BoundWrite; /** Sets or removes the subregistry of an ENSv2 name. Resolves once the receipt is in. */ readonly attachSync: Bound; /** Deploys an ENSv2 UserRegistry, optionally attaching it as a name's subregistry. Resolves once the transaction is submitted. */ readonly deploy: BoundWrite; /** Deploys an ENSv2 UserRegistry, optionally attaching it as a name's subregistry. Resolves once the receipt is in. */ readonly deploySync: Bound; /** Reads an ENSv2 registry: its kind, implementation, parent, canonical name, URI, whether it is emancipated, and whether it can be upgraded. */ readonly get: Bound; /** Sets the metadata URI of an ENSv2 registry. Resolves once the transaction is submitted. */ readonly setUri: BoundWrite; /** Sets the metadata URI of an ENSv2 registry. Resolves once the receipt is in. */ readonly setUriSync: Bound; /** Upgrades an ENSv2 registry to the deployment's latest implementation. Resolves once the transaction is submitted. */ readonly upgrade: BoundWrite; /** Upgrades an ENSv2 registry to the deployment's latest implementation. Resolves once the receipt is in. */ readonly upgradeSync: Bound; }` | | | `resolver` | `{ /** Deploys an ENSv2 PermissionedResolver, optionally with records, and points a name at it. Resolves once the transaction is submitted. */ readonly create: BoundWrite; /** Deploys an ENSv2 PermissionedResolver, optionally with records, and points a name at it. Resolves once the receipt is in. */ readonly createSync: Bound; /** Reads the resolver of an ENS name: its address, what kind of resolver it is, who may write to it and which record profiles it supports. */ readonly get: Bound; /** Reads which record set an ENS name uses on its PermissionedResolver. */ readonly getLink: Bound; /** Links an ENS name to the records of another name on the same PermissionedResolver. Resolves once the transaction is submitted. */ readonly link: BoundWrite; /** Links an ENS name to the records of another name on the same PermissionedResolver. Resolves once the receipt is in. */ readonly linkSync: Bound; /** Calls the resolver of an ENS name with raw calldata through the Universal Resolver (ENSIP-10). */ readonly resolve: Bound; /** Points an ENS name at a resolver. Resolves once the transaction is submitted. */ readonly set: BoundWrite; /** Points an ENS name at a resolver. Resolves once the receipt is in. */ readonly setSync: Bound; /** Upgrades the PermissionedResolver of an ENS name to a newer implementation. Resolves once the transaction is submitted. */ readonly upgrade: BoundWrite; /** Upgrades the PermissionedResolver of an ENS name to a newer implementation. Resolves once the receipt is in. */ readonly upgradeSync: Bound; }` | | | `role` | `{ /** Reads the ENSv2 roles an account holds on a name, or at the root of a registry or resolver. */ readonly get: Bound; /** Grants ENSv2 roles to an account on a name, or at the root of a registry or resolver. Resolves once the transaction is submitted. */ readonly grant: BoundWrite; /** Grants ENSv2 roles to an account on a name, or at the root of a registry or resolver. Resolves once the receipt is in. */ readonly grantSync: Bound; /** Revokes ENSv2 roles from an account on a name, or at the root of a registry or resolver. Resolves once the transaction is submitted. */ readonly revoke: BoundWrite; /** Revokes ENSv2 roles from an account on a name, or at the root of a registry or resolver. Resolves once the receipt is in. */ readonly revokeSync: Bound; }` | | | `subname` | `{ /** Creates a subname, routed by its parent: an ENSv2 subregistry, the ENSv1 registry or the NameWrapper. Resolves once the transaction is submitted. */ readonly create: BoundWrite; /** Creates a subname, routed by its parent: an ENSv2 subregistry, the ENSv1 registry or the NameWrapper. Resolves once the receipt is in. */ readonly createSync: Bound; /** Removes a subname. Resolves once the transaction is submitted. */ readonly remove: BoundWrite; /** Removes a subname. Resolves once the receipt is in. */ readonly removeSync: Bound; /** Changes a subname from its parent: owner, resolver or expiry, in one plan. Resolves once the transaction is submitted. */ readonly update: BoundWrite; /** Changes a subname from its parent: owner, resolver or expiry, in one plan. Resolves once the receipt is in. */ readonly updateSync: Bound; }` | | | `wrapper` | `{ /** Reads the NameWrapper owner, fuses and expiry of an ENSv1 name. */ readonly getFuses: Bound; /** Burns fuses on, or extends, a wrapped ENSv1 subname as its parent's owner. Resolves once the transaction is submitted. */ readonly setChildFuses: BoundWrite; /** Burns fuses on, or extends, a wrapped ENSv1 subname as its parent's owner. Resolves once the receipt is in. */ readonly setChildFusesSync: Bound; /** Burns owner-controlled fuses on a wrapped ENSv1 name. Resolves once the transaction is submitted. */ readonly setFuses: BoundWrite; /** Burns owner-controlled fuses on a wrapped ENSv1 name. Resolves once the receipt is in. */ readonly setFusesSync: Bound; /** Unwraps an ENSv1 name from the NameWrapper. Resolves once the transaction is submitted. */ readonly unwrap: BoundWrite; /** Unwraps an ENSv1 name from the NameWrapper. Resolves once the receipt is in. */ readonly unwrapSync: Bound; /** Wraps an ENSv1 name in the NameWrapper. Resolves once the transaction is submitted. */ readonly wrap: BoundWrite; /** Wraps an ENSv1 name in the NameWrapper. Resolves once the receipt is in. */ readonly wrapSync: Bound; }` | | | `batch` | `batch.Bound` | | ### `EventActions` [#eventactions-1] `event` actions bound to a client. ```ts type EventActions ``` | Field | Type | Description | | --- | --- | --- | | `event` | `{ /** Normalizes the ENS events in logs or transaction receipts. */ readonly decode: Bound; /** Reads the ENS events of one name over a block range, across ENSv1 and ENSv2. */ readonly get: Bound; /** Watches one name's ENS events as new blocks arrive. Resolves to a function that stops watching. */ readonly watch: Bound; }` | | ### `IndexerActions` [#indexeractions-1] `indexer` actions bound to a client. ```ts type IndexerActions ``` | Field | Type | Description | | --- | --- | --- | | `indexer` | `{ /** Searches indexed ENS events by name, address, resolver, contract or block range. */ readonly getEvents: Bound; /** Reads the full history of a name, or of every name an address is related to. */ readonly getHistory: Bound; /** Reads one name from the indexer: owner, manager, expiry, resolver, records and protocol. */ readonly getName: Bound; /** Lists names by when they expire or leave their grace period. */ readonly getNamesByExpiry: Bound; /** Lists the names an address owns, manages, holds roles on, resolves to, or used to own. */ readonly getNamesForAddress: Bound; /** Reads what the indexer serves for a namespace: its networks and which features are complete. */ readonly getNamespace: Bound; /** Lists who can do what over a name, a registration, an account or an ENSv2 registry. */ readonly getPermissions: Bound; /** Reads an address's primary name from the indexer, verified on-chain when the indexer can. */ readonly getPrimaryName: Bound; /** Reads a name's records and its record inventory from the indexer. */ readonly getRecords: Bound; /** Reads an ENSv2 registry: the name it serves, its parent registry, when it was created and its counts. */ readonly getRegistry: Bound; /** Lists the labels of an ENSv2 registry, optionally only those an address holds or does not hold. */ readonly getRegistryLabels: Bound; /** Reads a resolver and one page of the names bound to it. */ readonly getResolver: Bound; /** Lists the names linked to record sets on an ENSv2 resolver. */ readonly getResolverLinks: Bound; /** Lists the role grants on an ENSv2 resolver. */ readonly getResolverRoles: Bound; /** Lists the ENSv2 resolvers on which an address holds roles. */ readonly getResolvers: Bound; /** Reads the indexer's health and how far each chain is indexed. */ readonly getStatus: Bound; /** Lists the direct subnames of a name. */ readonly getSubnames: Bound; /** Reads up to 1,000 names and addresses in one request. */ readonly lookup: Bound; /** Searches names by text. */ readonly search: Bound; }` | | ### `MigrationActions` [#migrationactions-1] `migration` actions bound to a client. ```ts type MigrationActions ``` | Field | Type | Description | | --- | --- | --- | | `migration` | `{ /** Reads whether an ENSv1 name can migrate to ENSv2, how, and what it becomes. */ readonly get: Bound; /** Migrates one or more ENSv1 names to ENSv2, carrying their resolver records and subnames. Resolves once the transaction is submitted. */ readonly migrate: BoundWrite; /** Migrates one or more ENSv1 names to ENSv2, carrying their resolver records and subnames. Resolves once the receipt is in. */ readonly migrateSync: Bound; }` | | ### `NameActions` [#nameactions-1] `name` actions bound to a client. ```ts type NameActions ``` | Field | Type | Description | | --- | --- | --- | | `name` | `` { /** Reads the full state of a name across ENSv1 and ENSv2: where it lives, who owns it, its resolver, expiry and whether it can be registered or renewed. */ readonly get: Bound; /** Recovers a label from its labelhash through the ENSv2 LabelStore. */ readonly getLabel: Bound; /** Resets the ENSv1 registry owner (manager) of an unwrapped `.eth` name, as its registrant. Resolves once the transaction is submitted. */ readonly reclaim: BoundWrite; /** Resets the ENSv1 registry owner (manager) of an unwrapped `.eth` name, as its registrant. Resolves once the receipt is in. */ readonly reclaimSync: Bound; /** Sets the ENSv1 manager (registry owner) of a name. Resolves once the transaction is submitted. */ readonly setManager: BoundWrite; /** Sets the ENSv1 manager (registry owner) of a name. Resolves once the receipt is in. */ readonly setManagerSync: Bound; /** Sets the ENSv1 registry TTL of a name. Resolves once the transaction is submitted. */ readonly setTtl: BoundWrite; /** Sets the ENSv1 registry TTL of a name. Resolves once the receipt is in. */ readonly setTtlSync: Bound; /** Sends a name to another account and resolves once the transaction is submitted. */ readonly transfer: BoundWrite; /** Sends a name to another account and resolves once the receipt is in. */ readonly transferSync: Bound; } `` | | ### `PermissionActions` [#permissionactions-1] `permission` actions bound to a client. ```ts type PermissionActions ``` | Field | Type | Description | | --- | --- | --- | | `permission` | `{ /** Checks whether an account may perform one operation on an ENS name, and lists exactly what it lacks when it may not. */ readonly check: Bound; /** Reads what an account may do with an ENS name: transfer it, change its resolver, edit records, create subnames and more, across ENSv1 ownership and ENSv2 roles. */ readonly get: Bound; /** Lets another account edit a name's records, or takes that access back. Resolves once the transaction is submitted. */ readonly setRecordAccess: BoundWrite; /** Lets another account edit a name's records, or takes that access back. Resolves once the receipt is in. */ readonly setRecordAccessSync: Bound; }` | | ### `PlanActions` [#planactions-1] `plan` actions bound to a client. ```ts type PlanActions ``` | Field | Type | Description | | --- | --- | --- | | `plan` | `` { /** Reads a saved plan and its progress. */ readonly get: Bound; /** Lists the saved plans of this client's chain and of its `chains`, newest first. */ readonly list: Bound; /** Records a transaction sent outside ensforge as a plan step's submission. */ readonly reconcile: Bound; /** Continues a saved plan after a failure or a reload. Resolves once the remaining transactions are submitted. */ readonly resume: Bound; /** Continues a saved plan and resolves once every receipt is in. */ readonly resumeSync: Bound; /** Sends any plan: one prepared by a write's `.prepare`, or several combined with `Plan.merge`. Resolves once the transaction is submitted. */ readonly send: BoundWrite; /** Sends any plan: one prepared by a write's `.prepare`, or several combined with `Plan.merge`. Resolves once the receipt is in. */ readonly sendSync: Bound; } `` | | ### `PrimaryNameActions` [#primarynameactions-1] `primaryName` actions bound to a client. ```ts type PrimaryNameActions ``` | Field | Type | Description | | --- | --- | --- | | `primaryName` | `` { /** Reads the primary name of an address (ENSIP-19 reverse resolution), verified against the name's address record. */ readonly get: Bound; /** Sets or clears the primary name (reverse record) of an address. Resolves once the transaction is submitted. */ readonly set: BoundWrite; /** Sets or clears the primary name (reverse record) of an address. Resolves once the receipt is in. */ readonly setSync: Bound; /** Signs a claim to a primary name on one or more L2s, with one signature and no transaction. Anyone can then submit it on each chain with `primaryName.set`, so the account needs no gas or wallet connection there. */ readonly signClaim: Bound; } `` | | ### `RecordActions` [#recordactions-1] `record` actions bound to a client. ```ts type RecordActions ``` | Field | Type | Description | | --- | --- | --- | | `record` | `` { /** Reads any mix of a name's records in one request: texts, addresses, content hash, ABI, public key, name record, interface implementers and data records. */ readonly get: record.get.Bound; /** Reads one address record of an ENS name, for Ethereum by default or any coin (ENSIP-9, ENSIP-11). */ readonly getAddress: record.getAddress.Bound; /** Reads the avatar of an ENS name and resolves it to a URL a browser can load (ENSIP-12). */ readonly getAvatar: Bound; /** Reads the content hash of an ENS name (ENSIP-7), decoded into its protocol, value and URI. */ readonly getContentHash: Bound; /** Reads one text record of an ENS name, such as `url`, `avatar` or `com.twitter`. */ readonly getText: Bound; /** Writes records of an ENS name and resolves once the transaction is submitted. */ readonly set: BoundWrite; /** Writes records of an ENS name and resolves once the receipt is in. */ readonly setSync: Bound; } `` | | ### `RegistrationActions` [#registrationactions-1] `registration` actions bound to a client. ```ts type RegistrationActions ``` | Field | Type | Description | | --- | --- | --- | | `registration` | `` { /** Commits to registering `.eth` names, the first half of a registration. Resolves once the transaction is submitted. */ readonly commit: BoundWrite; /** Commits to registering `.eth` names, the first half of a registration. Resolves once the receipt is in. */ readonly commitSync: Bound; /** Reads where a registration commitment is in its window. */ readonly getCommitmentStatus: Bound; /** Reads the `.eth` registration settings: contracts, commitment window, minimum duration, grace period and accepted payment tokens. */ readonly getParameters: Bound; /** Quotes the price of registering a `.eth` name, in an ERC-20 payment token. */ readonly getPrice: Bound; /** Quotes renewing one or more `.eth` names, in an ERC-20 payment token. */ readonly getRenewalPrice: Bound; /** Checks whether a `.eth` name can be registered now. */ readonly isAvailable: Bound; /** Registers one or more `.eth` names: approve, commit, wait, register, then records and primary name. Resolves once the transaction is submitted. */ readonly register: BoundWrite; /** Registers one or more `.eth` names: approve, commit, wait, register, then records and primary name. Resolves once the receipt is in. */ readonly registerSync: Bound; /** Renews one or more `.eth` names, ENSv1 or ENSv2, paying in an ERC-20 token. Resolves once the transaction is submitted. */ readonly renew: BoundWrite; /** Renews one or more `.eth` names, ENSv1 or ENSv2, paying in an ERC-20 token. Resolves once the receipt is in. */ readonly renewSync: Bound; } `` | | ### `RegistryActions` [#registryactions-1] `registry` actions bound to a client. ```ts type RegistryActions ``` | Field | Type | Description | | --- | --- | --- | | `registry` | `{ /** Sets or removes the subregistry of an ENSv2 name. Resolves once the transaction is submitted. */ readonly attach: BoundWrite; /** Sets or removes the subregistry of an ENSv2 name. Resolves once the receipt is in. */ readonly attachSync: Bound; /** Deploys an ENSv2 UserRegistry, optionally attaching it as a name's subregistry. Resolves once the transaction is submitted. */ readonly deploy: BoundWrite; /** Deploys an ENSv2 UserRegistry, optionally attaching it as a name's subregistry. Resolves once the receipt is in. */ readonly deploySync: Bound; /** Reads an ENSv2 registry: its kind, implementation, parent, canonical name, URI, whether it is emancipated, and whether it can be upgraded. */ readonly get: Bound; /** Sets the metadata URI of an ENSv2 registry. Resolves once the transaction is submitted. */ readonly setUri: BoundWrite; /** Sets the metadata URI of an ENSv2 registry. Resolves once the receipt is in. */ readonly setUriSync: Bound; /** Upgrades an ENSv2 registry to the deployment's latest implementation. Resolves once the transaction is submitted. */ readonly upgrade: BoundWrite; /** Upgrades an ENSv2 registry to the deployment's latest implementation. Resolves once the receipt is in. */ readonly upgradeSync: Bound; }` | | ### `ResolverActions` [#resolveractions-1] `resolver` actions bound to a client. ```ts type ResolverActions ``` | Field | Type | Description | | --- | --- | --- | | `resolver` | `{ /** Deploys an ENSv2 PermissionedResolver, optionally with records, and points a name at it. Resolves once the transaction is submitted. */ readonly create: BoundWrite; /** Deploys an ENSv2 PermissionedResolver, optionally with records, and points a name at it. Resolves once the receipt is in. */ readonly createSync: Bound; /** Reads the resolver of an ENS name: its address, what kind of resolver it is, who may write to it and which record profiles it supports. */ readonly get: Bound; /** Reads which record set an ENS name uses on its PermissionedResolver. */ readonly getLink: Bound; /** Links an ENS name to the records of another name on the same PermissionedResolver. Resolves once the transaction is submitted. */ readonly link: BoundWrite; /** Links an ENS name to the records of another name on the same PermissionedResolver. Resolves once the receipt is in. */ readonly linkSync: Bound; /** Calls the resolver of an ENS name with raw calldata through the Universal Resolver (ENSIP-10). */ readonly resolve: Bound; /** Points an ENS name at a resolver. Resolves once the transaction is submitted. */ readonly set: BoundWrite; /** Points an ENS name at a resolver. Resolves once the receipt is in. */ readonly setSync: Bound; /** Upgrades the PermissionedResolver of an ENS name to a newer implementation. Resolves once the transaction is submitted. */ readonly upgrade: BoundWrite; /** Upgrades the PermissionedResolver of an ENS name to a newer implementation. Resolves once the receipt is in. */ readonly upgradeSync: Bound; }` | | ### `RoleActions` [#roleactions-1] `role` actions bound to a client. ```ts type RoleActions ``` | Field | Type | Description | | --- | --- | --- | | `role` | `{ /** Reads the ENSv2 roles an account holds on a name, or at the root of a registry or resolver. */ readonly get: Bound; /** Grants ENSv2 roles to an account on a name, or at the root of a registry or resolver. Resolves once the transaction is submitted. */ readonly grant: BoundWrite; /** Grants ENSv2 roles to an account on a name, or at the root of a registry or resolver. Resolves once the receipt is in. */ readonly grantSync: Bound; /** Revokes ENSv2 roles from an account on a name, or at the root of a registry or resolver. Resolves once the transaction is submitted. */ readonly revoke: BoundWrite; /** Revokes ENSv2 roles from an account on a name, or at the root of a registry or resolver. Resolves once the receipt is in. */ readonly revokeSync: Bound; }` | | ### `SubnameActions` [#subnameactions-1] `subname` actions bound to a client. ```ts type SubnameActions ``` | Field | Type | Description | | --- | --- | --- | | `subname` | `{ /** Creates a subname, routed by its parent: an ENSv2 subregistry, the ENSv1 registry or the NameWrapper. Resolves once the transaction is submitted. */ readonly create: BoundWrite; /** Creates a subname, routed by its parent: an ENSv2 subregistry, the ENSv1 registry or the NameWrapper. Resolves once the receipt is in. */ readonly createSync: Bound; /** Removes a subname. Resolves once the transaction is submitted. */ readonly remove: BoundWrite; /** Removes a subname. Resolves once the receipt is in. */ readonly removeSync: Bound; /** Changes a subname from its parent: owner, resolver or expiry, in one plan. Resolves once the transaction is submitted. */ readonly update: BoundWrite; /** Changes a subname from its parent: owner, resolver or expiry, in one plan. Resolves once the receipt is in. */ readonly updateSync: Bound; }` | | ### `WrapperActions` [#wrapperactions-1] `wrapper` actions bound to a client. ```ts type WrapperActions ``` | Field | Type | Description | | --- | --- | --- | | `wrapper` | `{ /** Reads the NameWrapper owner, fuses and expiry of an ENSv1 name. */ readonly getFuses: Bound; /** Burns fuses on, or extends, a wrapped ENSv1 subname as its parent's owner. Resolves once the transaction is submitted. */ readonly setChildFuses: BoundWrite; /** Burns fuses on, or extends, a wrapped ENSv1 subname as its parent's owner. Resolves once the receipt is in. */ readonly setChildFusesSync: Bound; /** Burns owner-controlled fuses on a wrapped ENSv1 name. Resolves once the transaction is submitted. */ readonly setFuses: BoundWrite; /** Burns owner-controlled fuses on a wrapped ENSv1 name. Resolves once the receipt is in. */ readonly setFusesSync: Bound; /** Unwraps an ENSv1 name from the NameWrapper. Resolves once the transaction is submitted. */ readonly unwrap: BoundWrite; /** Unwraps an ENSv1 name from the NameWrapper. Resolves once the receipt is in. */ readonly unwrapSync: Bound; /** Wraps an ENSv1 name in the NameWrapper. Resolves once the transaction is submitted. */ readonly wrap: BoundWrite; /** Wraps an ENSv1 name in the NameWrapper. Resolves once the receipt is in. */ readonly wrapSync: Bound; }` | | ## Read options [#read-options] ### `Read.BlockOptions` [#readblockoptions] Read at one block, by number or by tag, never both. ```ts type BlockOptions = | { /** Block number to read at. */ blockNumber?: bigint | undefined; blockTag?: undefined; } | { blockNumber?: undefined; /** * Block tag to read at. * * @default the client's `config.blockTag` */ blockTag?: BlockTag | undefined; }; ``` ### `Read.Options` [#readoptions] Options every read action takes. ```ts type Options = { /** Cancels the call; the Promise rejects with `signal.reason`. */ signal?: AbortSignal | undefined; /** * Throw `NotFoundError` instead of returning `null` for missing data. * * @default false */ strict?: boolean | undefined; /** CCIP-Read gateways for this call, overriding the client's. */ gatewayUrls?: readonly string[] | undefined; } & BlockOptions; ``` | Option | Type | Default | Description | | --- | --- | --- | --- | | `signal` | `AbortSignal` | | Cancels the call; the Promise rejects with `signal.reason`. | | `strict` | `boolean` | `false` | Throw `NotFoundError` instead of returning `null` for missing data. | | `gatewayUrls` | `readonly string[]` | | CCIP-Read gateways for this call, overriding the client's. | | `blockNumber` | `bigint` | | Block number to read at. | | `blockTag` | `undefined` | | | ## Write options [#write-options] ### `Write.Method` [#writemethod] A write's `.prepare`, `.simulate` or `.estimateGas`: options plus `account` and `via`. ```ts type Method = (( client: Like, options: options & Pick, ) => Promise) & { /** Path of the method, e.g. `record.set.prepare`. */ readonly path: string; }; ``` | Field | Type | Description | | --- | --- | --- | | `path` | `string` | Path of the method, e.g. `record.set.prepare`. | ### `Write.Mode` [#writemode] How a plan's calls are sent: `batch` uses one EIP-5792 wallet call, `sequential` sends one transaction per call, each once the previous one is mined and with a fifth more gas than estimated, `auto` batches when the wallet supports atomic batches. ```ts type Mode = "auto" | "batch" | "sequential"; ``` ### `Write.Options` [#writeoptions] Options every write action takes. ```ts type Options ``` | Option | Type | Default | Description | | --- | --- | --- | --- | | `account` | `Account \| Address` | the client's `account` | Signer for this write. | | `simulate` | `boolean` | the client's `config.simulate` | Simulate every call before the wallet prompt, so reverts become typed errors first. | | `signal` | `AbortSignal` | | Cancels before the next wallet prompt; already submitted transactions are not undone. | | `mode` | `Mode` | `"auto"` | How calls are sent. | | `maxBundleCalls` | `number` | `10` | Most calls per wallet bundle. Consecutive steps share a bundle when the wallet supports atomic batches, up to this many calls and never across a chain-time wait. | | `onStep` | `((event: Plan.Event) => void)` | | Called as each step waits, is submitted, confirmed or fails. | | `via` | `Via` | | Send the write another way than the signer's own transactions, e.g. through a smart account (`hca()` from `@ensforge/hca`). Also applies to `.prepare`, `.simulate` and `.estimateGas`. | | `paymaster` | `{ readonly url: string; readonly context?: Readonly> }` | | EIP-5792 paymaster service for wallets that support it (`paymasterService` capability), so the wallet's calls are sponsored. Sends through `wallet_sendCalls` even for one call. | ### `Write.Via.Context` [#writeviacontext] What a route knows about the write it carries. ```ts type Context ``` | Field | Type | Description | | --- | --- | --- | | `client` | `Client` | The ensforge client the write runs on (deployment, reads). | | `chainId` | `number` | | | `account` | `Address` | Signer of the write. | | `publicClient` | `ViemClient` | | | `walletClient` | `ViemWalletClient` | The signer's wallet, when one is configured. | ### `Write.Via.Status` [#writeviastatus] Where a sent step is: still pending, mined (with its transactions), or failed. ```ts type Status = | { readonly status: "pending" } | { readonly status: "success"; readonly hashes: readonly Hex[] } | { readonly status: "failed"; readonly reason: string; readonly hashes?: readonly Hex[] }; ``` ## Write results [#write-results] ### `Write.Result` [#writeresult] Returned by every write: resolves once every call is submitted. ```ts type Result ``` | 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. | ## Sync options [#sync-options] ### `Write.SyncOptions` [#writesyncoptions] Options of a write's `…Sync` form, which waits for receipts. ```ts type SyncOptions = Options & { /** * Confirmations to wait for per transaction. * * @default 1 */ confirmations?: number | undefined; /** Milliseconds to wait for each receipt before failing with `RECEIPT_TIMEOUT`. */ timeout?: number | undefined; }; ``` | Option | Type | Default | Description | | --- | --- | --- | --- | | `account` | `Account \| Address` | the client's `account` | Signer for this write. | | `simulate` | `boolean` | the client's `config.simulate` | Simulate every call before the wallet prompt, so reverts become typed errors first. | | `signal` | `AbortSignal` | | Cancels before the next wallet prompt; already submitted transactions are not undone. | | `mode` | `Mode` | `"auto"` | How calls are sent. | | `maxBundleCalls` | `number` | `10` | Most calls per wallet bundle. Consecutive steps share a bundle when the wallet supports atomic batches, up to this many calls and never across a chain-time wait. | | `onStep` | `((event: Plan.Event) => void)` | | Called as each step waits, is submitted, confirmed or fails. | | `via` | `Via` | | Send the write another way than the signer's own transactions, e.g. through a smart account (`hca()` from `@ensforge/hca`). Also applies to `.prepare`, `.simulate` and `.estimateGas`. | | `paymaster` | `{ readonly url: string; readonly context?: Readonly> }` | | EIP-5792 paymaster service for wallets that support it (`paymasterService` capability), so the wallet's calls are sponsored. Sends through `wallet_sendCalls` even for one call. | | `confirmations` | `number` | `1` | Confirmations to wait for per transaction. | | `timeout` | `number` | | Milliseconds to wait for each receipt before failing with [`RECEIPT_TIMEOUT`](/docs/reference/errors/RECEIPT_TIMEOUT). | ### `Write.SyncResult` [#writesyncresult] Returned by every `…Sync` write: resolves once every receipt is in. ```ts type SyncResult = Result & { /** Receipt of the last transaction. */ readonly receipt: TransactionReceipt; readonly receipts: readonly TransactionReceipt[]; }; ``` | 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. | | `receipt` | `TransactionReceipt` | Receipt of the last transaction. | | `receipts` | `readonly TransactionReceipt[]` | | ## Requests [#requests] ### `Request` [#request] A deferred read built with `action.request(options)`, run later by `Actions.batch`. Plain data; the type parameters only carry the result types. ```ts interface Request ``` | Field | Type | Description | | --- | --- | --- | | `path` | `string` | Action path, e.g. `record.getText`. | | `options` | `unknown` | | ## Plans [#plans] ### `Plan` [#plan] A write, fully planned but not sent: the calls to make, in which order, and what they need. Plans are plain data, so they can be inspected, serialized, merged or handed to viem. ```ts interface Plan ``` ```ts title="Inspecting a plan" const plan = await ens.record.set.prepare({ name: "alice.eth", texts: { url: "https://alice.dev" } }) plan.calls // send with ensforge, or with viem's sendCalls ``` ### `Plan.Call` [#plancall] One contract call. ```ts type Call ``` | Field | Type | Description | | --- | --- | --- | | `to` | `Address` | | | `data` | `Hex` | | | `value` | `bigint` | | ### `Plan.Deployment` [#plandeployment] A contract the plan deploys. The address is known before sending (CREATE2). ```ts type Deployment ``` | Field | Type | Description | | --- | --- | --- | | `contract` | `"resolver" \| "registry"` | | | `address` | `Address` | | ### `Plan.Estimate` [#planestimate] Gas and ETH a plan needs. ```ts type Estimate ``` | Field | Type | Description | | --- | --- | --- | | `plan` | `Plan` | | | `gas` | `bigint` | Total gas limit across all calls: each call's estimate and the fifth more it is sent with. | | `value` | `bigint` | Total ETH sent across all calls. | ### `Plan.Event` [#planevent] Progress of a plan being sent: `waiting` for chain time before a step, `submitted` once its transactions are sent, `confirmed` once their receipts are in, `failed` with the error. ```ts type Event ``` | Field | Type | Description | | --- | --- | --- | | `step` | `Step` | | | `status` | `"waiting" \| "submitted" \| "confirmed" \| "failed"` | | | `hashes` (optional) | `readonly Hex[]` | Transactions of the step, once submitted. | | `bundleId` (optional) | `string` | EIP-5792 bundle the step was sent in. | | `reference` (optional) | `string` | Reference of a step sent through a route (`via`), e.g. a UserOperation hash. | | `error` (optional) | `AnyError` | | ### `Plan.Fee` [#planfee] A fee a route charges, in a token or in native currency. ```ts type Fee ``` | Field | Type | Description | | --- | --- | --- | | `kind` | `"gas" \| "execution" \| "bridge"` | | | `token` | `Address \| "native"` | Token address, or `native`. | | `amount` | `bigint` | Expected amount, in the token's smallest unit. | | `maximum` | `bigint` | Most the route may charge. | | `sponsored` | `boolean` | Paid by the route's sponsor instead of the account. | ### `Plan.Record` [#planrecord] A saved plan and its progress, for resuming after a failure or a reload. ```ts type Record ``` | Field | Type | Description | | --- | --- | --- | | `plan` | `Plan` | | | `status` | `"pending" \| "completed" \| "failed"` | `pending` while steps remain, `completed` once every step is submitted. | | `submitted` | `Readonly>` | Transaction hashes per submitted step id. | | `bundles` | `Readonly>` | EIP-5792 bundle id per step sent in a bundle. | | `references` (optional) | `Readonly>` | Route references per step sent through `via` (e.g. UserOperation hashes). | | `error` (optional) | `string` | Message of the last failure. | | `updatedAt` | `number` | Unix time in milliseconds. | ### `Plan.Requirement` [#planrequirement] Something the account must have before the plan can succeed. ```ts type Requirement = | { readonly kind: "balance"; readonly amount: bigint; readonly token?: Address | undefined } | { readonly kind: "approval"; readonly token: Address; readonly spender: Address; readonly amount: bigint; }; ``` ### `Plan.Simulation` [#plansimulation] Result of simulating every call. ```ts type Simulation ``` | Field | Type | Description | | --- | --- | --- | | `ok` | `boolean` | | | `plan` | `Plan` | | | `steps` | `readonly { readonly id: string; readonly ok: boolean; readonly error?: AnyError \| undefined; }[]` | | ### `Plan.Step` [#planstep] A group of calls sent together, optionally after a wait. ```ts type Step ``` | Field | Type | Description | | --- | --- | --- | | `id` | `string` | | | `description` | `string` | Short description for progress UIs, e.g. "Set records". | | `calls` | `readonly Call[]` | | | `waitFor` (optional) | `{ readonly seconds: bigint }` | Chain time to wait after the previous step is confirmed before sending this one, e.g. the registration commitment age. | | `from` (optional) | `"signer"` | `signer`: the signer must send it itself, even through a route (e.g. a token approval). | ### `Plan.Storage` [#planstorage] Where saved plans live. ```ts type Storage ``` | Field | Type | Description | | --- | --- | --- | | `get` | `(id: string) => Promise` | | | `set` | `(record: Record) => Promise` | | | `delete` | `(id: string) => Promise` | | | `list` | `() => Promise` | | ### `Plan.Warning` [#planwarning] A non-blocking note about the plan. ```ts type Warning ``` | Field | Type | Description | | --- | --- | --- | | `code` | `string` | | | `message` | `string` | | ### `PlanActions` [#planactions-2] `plan` actions bound to a client. ```ts type PlanActions ``` | Field | Type | Description | | --- | --- | --- | | `plan` | `` { /** Reads a saved plan and its progress. */ readonly get: Bound; /** Lists the saved plans of this client's chain and of its `chains`, newest first. */ readonly list: Bound; /** Records a transaction sent outside ensforge as a plan step's submission. */ readonly reconcile: Bound; /** Continues a saved plan after a failure or a reload. Resolves once the remaining transactions are submitted. */ readonly resume: Bound; /** Continues a saved plan and resolves once every receipt is in. */ readonly resumeSync: Bound; /** Sends any plan: one prepared by a write's `.prepare`, or several combined with `Plan.merge`. Resolves once the transaction is submitted. */ readonly send: BoundWrite; /** Sends any plan: one prepared by a write's `.prepare`, or several combined with `Plan.merge`. Resolves once the receipt is in. */ readonly sendSync: Bound; } `` | | # dns.claim > For the complete documentation index, see [llms.txt](https://ensforge.com/llms.txt). Imports a DNS name into ENS with a DNSSEC proof of its _ens TXT record. Parameters, return value, errors and examples for dns.claim in @ensforge/sdk. Source: https://ensforge.com/docs/reference/sdk/dns/claim Imports a DNS name into ENS with a DNSSEC proof of its `_ens` TXT record. Resolves once the transaction is submitted. ## When to use [#when-to-use] Use to claim a DNS name after adding the TXT record `_ens.` = `a=
`. Use [`claimSync`](/docs/reference/sdk/dns/claim#wait-for-the-receipt-with-claimsync) to wait for the receipt. ## Details [#details] - The name goes to the address in the TXT record, whoever sends the claim. - The proof comes from the deployment's DNSSEC gateway unless `proof` is given. - With `resolver`, the claim also sets it; then only the DNS owner may send it. Set records with [`record.set`](/docs/reference/sdk/record/set) afterwards. - Read [`dns.getStatus`](/docs/reference/sdk/dns/get-status) first: a proof that does not verify on-chain fails. ## Signature [#signature] ```ts function claim( client: Like, options: claim.Options & Write.Options, ): Promise ``` Call it as `ens.dns.claim(options)` on a client, or `Actions.dns.claim(client, options)`. ## Parameters [#parameters] | Option | Type | Default | Description | | --- | --- | --- | --- | | `name` (required) | `string` | | DNS name. Normalized automatically. | | `proof` | `Proof` | | Proof from [`dns.getProof`](/docs/reference/sdk/dns/get-proof), instead of fetching one. | | `resolver` | `string` | | Resolver to set while claiming. | | `gatewayUrls` | `readonly string[]` | | DNSSEC gateways to fetch the proof from, instead of the deployment's. | 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_RECORD_VALUE`](/docs/reference/errors/INVALID_RECORD_VALUE) | invalid input. | | [`DnsError`](/docs/reference/errors/dns-error) | [`DNS_RECORD_MISSING`](/docs/reference/errors/DNS_RECORD_MISSING), [`PROOF_STALE`](/docs/reference/errors/PROOF_STALE), [`DNSSEC_PROOF_FAILED`](/docs/reference/errors/DNSSEC_PROOF_FAILED), [`TLD_NOT_PUBLIC`](/docs/reference/errors/TLD_NOT_PUBLIC) | the name cannot be proven. | | [`GatewayError`](/docs/reference/errors/gateway-error) | [`GATEWAY_REQUEST_FAILED`](/docs/reference/errors/GATEWAY_REQUEST_FAILED), [`GATEWAY_RESPONSE_INVALID`](/docs/reference/errors/GATEWAY_RESPONSE_INVALID) | the proof cannot be fetched. | | [`UnauthorizedError`](/docs/reference/errors/unauthorized-error) | [`NOT_OWNER`](/docs/reference/errors/NOT_OWNER) | someone other than the DNS owner claims with a resolver. | | [`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="Claiming a DNS name" const { hash } = await ens.dns.claim({ name: "example.com" }) ``` ```ts title="Claiming a DNS name with a standalone call" import { Actions } from "@ensforge/sdk" await Actions.dns.claim(ens, { name: "example.com" }) ``` ```ts title="Claiming a DNS name in an Effect program" import { Actions } from "@ensforge/sdk/effect" yield* Actions.dns.claim(ens, { name: "example.com" }) ``` ## Plan methods [#plan-methods] Each method takes the same options as `dns.claim` and sends nothing. See [Preview before sending](/docs/sdk/preview-before-sending). | Method | Description | | --- | --- | | `dns.claim.prepare(options)` | Builds the plan without sending anything. | | `dns.claim.simulate(options)` | Simulates the plan with `eth_call`, reporting each step. | | `dns.claim.estimateGas(options)` | Estimates the gas and ETH the plan needs. | ## Wait for the receipt with `claimSync` [#wait-for-the-receipt-with-claimsync] Imports a DNS name into ENS with a DNSSEC proof of its `_ens` TXT record. Resolves once the receipt is in. Use when the next step depends on the change being on-chain. `dns.claimSync` 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="Claiming a DNS name and waiting" const { receipt } = await ens.dns.claimSync({ name: "example.com" }) ``` ```ts title="Waiting with a standalone call" import { Actions } from "@ensforge/sdk" await Actions.dns.claimSync(ens, { name: "example.com" }) ``` ```ts title="Waiting in an Effect program" import { Actions } from "@ensforge/sdk/effect" yield* Actions.dns.claimSync(ens, { name: "example.com" }) ``` ## See also [#see-also] - [`dns.getStatus`](/docs/reference/sdk/dns/get-status) to check the name first # dns.getOffchainResolver > For the complete documentation index, see [llms.txt](https://ensforge.com/llms.txt). Reads the gasless DNS resolver a DNS name sets in an ENS1 TXT record. Options, result, errors and examples for dns.getOffchainResolver. Source: https://ensforge.com/docs/reference/sdk/dns/get-offchain-resolver Reads the gasless DNS resolver a DNS name sets in an `ENS1` TXT record. ## When to use [#when-to-use] Use to check a gasless DNS setup, which resolves without importing the name. ## Details [#details] - Reads the TXT records of the name itself through the DNSSEC gateway, without verifying them on-chain. - Picks the record the DNS TLD resolver uses: the first `ENS1 [context]` record whose resolver is an address, or an ENS name with an address record. A record split into several strings (DNS splits values over 255 bytes) is read whole. - `null` when the name has no such record. ## Signature [#signature] ```ts function getOffchainResolver( client: Like, options: getOffchainResolver.Options, ): Promise ``` Call it as `ens.dns.getOffchainResolver(options)` on a client, or `Actions.dns.getOffchainResolver(client, options)`. `dns.getOffchainResolver.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` | | DNS name. Normalized automatically. | | `gatewayUrls` | `readonly string[]` | | DNSSEC gateways to use instead of the deployment's. | Also takes the [read options](/docs/reference/sdk/client#read-options). ## Returns [#returns] Resolves to `OffchainResolver | null`. The resolver and context, or `null`. | Field | Type | Description | | --- | --- | --- | | `resolver` | `string` | Resolver address or ENS name the record points to. | | `context` | `string \| null` | Extra data passed to the resolver, or `null`. | ## Errors [#errors] | Error | Codes | When | | --- | --- | --- | | [`InvalidInputError`](/docs/reference/errors/invalid-input-error) | [`INVALID_NAME`](/docs/reference/errors/INVALID_NAME) | names that are not DNS names. | | [`GatewayError`](/docs/reference/errors/gateway-error) | [`GATEWAY_REQUEST_FAILED`](/docs/reference/errors/GATEWAY_REQUEST_FAILED), [`GATEWAY_RESPONSE_INVALID`](/docs/reference/errors/GATEWAY_RESPONSE_INVALID) | the DNSSEC gateway fails. | | [`UnsupportedError`](/docs/reference/errors/unsupported-error) | [`UNSUPPORTED_ON_DEPLOYMENT`](/docs/reference/errors/UNSUPPORTED_ON_DEPLOYMENT) | without a DNSSEC gateway or `gatewayUrls`. | | [`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 gasless DNS resolver" const offchain = await ens.dns.getOffchainResolver({ name: "example.com" }) ``` ```ts title="Reading a gasless DNS resolver with a standalone call" import { Actions } from "@ensforge/sdk" const offchain = await Actions.dns.getOffchainResolver(publicClient, { name: "example.com" }) ``` ```ts title="Reading a gasless DNS resolver in an Effect program" import { Actions } from "@ensforge/sdk/effect" const offchain = yield* Actions.dns.getOffchainResolver(ens, { name: "example.com" }) ``` ## See also [#see-also] - [`record.get`](/docs/reference/sdk/record/get) to resolve its records # dns.getProof > For the complete documentation index, see [llms.txt](https://ensforge.com/llms.txt). Fetches the DNSSEC proof of a DNS name's _ens TXT record. Parameters, return value, errors and examples for dns.getProof in @ensforge/sdk. Source: https://ensforge.com/docs/reference/sdk/dns/get-proof Fetches the DNSSEC proof of a DNS name's `_ens` TXT record. ## When to use [#when-to-use] Use to fetch a proof once and pass it to [`dns.claim`](/docs/reference/sdk/dns/claim), or to inspect it. ## Details [#details] - Fetched from the deployment's DNSSEC gateway (ENSIP-17) unless `gatewayUrls` is given. - Not verified; [`dns.getStatus`](/docs/reference/sdk/dns/get-status) verifies it on-chain. ## Signature [#signature] ```ts function getProof(client: Like, options: getProof.Options): Promise ``` Call it as `ens.dns.getProof(options)` on a client, or `Actions.dns.getProof(client, options)`. `dns.getProof.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` | | DNS name. Normalized automatically. | | `gatewayUrls` | `readonly string[]` | | DNSSEC gateways to use instead of the deployment's. | Also takes the [read options](/docs/reference/sdk/client#read-options). ## Returns [#returns] Resolves to `Proof`. Signed RRSets, the record's TXT strings and its signature times. | Field | Type | Description | | --- | --- | --- | | `name` | `string` | DNS name the proof is for, e.g. `_ens.example.com`. | | `rrsets` | `readonly SignedRRSet[]` | Signed RRSets, root first. | | `inception` | `number` | Signature inception of the proven record set, as a Unix timestamp; `0` when it does not exist. | | `expiration` | `number` | Signature expiration of the proven record set, as a Unix timestamp; `0` when it does not exist. | | `txt` | `readonly string[]` | TXT strings of the proven record set; empty when the record does not exist. | ## Errors [#errors] | Error | Codes | When | | --- | --- | --- | | [`InvalidInputError`](/docs/reference/errors/invalid-input-error) | [`INVALID_NAME`](/docs/reference/errors/INVALID_NAME) | names that are not DNS names. | | [`GatewayError`](/docs/reference/errors/gateway-error) | [`GATEWAY_REQUEST_FAILED`](/docs/reference/errors/GATEWAY_REQUEST_FAILED), [`GATEWAY_RESPONSE_INVALID`](/docs/reference/errors/GATEWAY_RESPONSE_INVALID) | the DNSSEC gateway fails. | | [`UnsupportedError`](/docs/reference/errors/unsupported-error) | [`UNSUPPORTED_ON_DEPLOYMENT`](/docs/reference/errors/UNSUPPORTED_ON_DEPLOYMENT) | without a DNSSEC gateway or `gatewayUrls`. | | [`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="Fetching a proof" const proof = await ens.dns.getProof({ name: "example.com" }) ``` ```ts title="Fetching a proof with a standalone call" import { Actions } from "@ensforge/sdk" const proof = await Actions.dns.getProof(publicClient, { name: "example.com" }) ``` ```ts title="Fetching a proof in an Effect program" import { Actions } from "@ensforge/sdk/effect" const proof = yield* Actions.dns.getProof(ens, { name: "example.com" }) ``` ## See also [#see-also] - [`dns.claim`](/docs/reference/sdk/dns/claim) to import with it # dns.getRecords > For the complete documentation index, see [llms.txt](https://ensforge.com/llms.txt). Reads DNS records and the zonehash a name stores on its resolver. Parameters, return value, errors and examples for dns.getRecords in @ensforge/sdk. Source: https://ensforge.com/docs/reference/sdk/dns/get-records Reads DNS records and the zonehash a name stores on its resolver. ## When to use [#when-to-use] Use to read DNS data hosted in ENS for any name, not only imported DNS names. ## Details [#details] - Each query reads one record set by owner name and type (`1` for A, `16` for TXT, …), as DNS wire-format resource records. - Missing records, and resolvers without DNS records, read as `null`. ## Signature [#signature] ```ts function getRecords( client: Like, options: getRecords.Options, ): Promise ``` Call it as `ens.dns.getRecords(options)` on a client, or `Actions.dns.getRecords(client, options)`. `dns.getRecords.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. | | `records` | `readonly { readonly name: string; readonly type: number }[]` | | Record sets to read, by DNS owner name and record type. | Also takes the [read options](/docs/reference/sdk/client#read-options). ## Returns [#returns] Resolves to `getRecords.ReturnType`. The resolver, its zonehash and each queried record set (`null` when missing). | Field | Type | Description | | --- | --- | --- | | `resolver` | `Address \| null` | | | `zonehash` | `Hex \| null` | | | `records` | `readonly { readonly name: string; readonly type: number; readonly data: Hex \| null; }[]` | | ## Errors [#errors] | Error | Codes | When | | --- | --- | --- | | [`InvalidInputError`](/docs/reference/errors/invalid-input-error) | [`INVALID_NAME`](/docs/reference/errors/INVALID_NAME) | invalid names. | | [`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 TXT record set" const dns = await ens.dns.getRecords({ name: "alice.eth", records: [{ name: "alice.eth", type: 16 }] }) ``` ```ts title="Reading a TXT record set with a standalone call" import { Actions } from "@ensforge/sdk" const dns = await Actions.dns.getRecords(publicClient, { name: "alice.eth", records: [{ name: "alice.eth", type: 16 }] }) ``` ```ts title="Reading a TXT record set in an Effect program" import { Actions } from "@ensforge/sdk/effect" const dns = yield* Actions.dns.getRecords(ens, { name: "alice.eth", records: [{ name: "alice.eth", type: 16 }] }) ``` ## Example response [#example-response] Recorded from Ethereum mainnet on 2026-11-18 at block 26443964. Values change as the chain does. ```ts await ens.dns.getRecords({ name: "ens.domains" }) ``` ```json { "resolver": null, "zonehash": null, "records": [] } ``` ## See also [#see-also] - [`dns.setRecords`](/docs/reference/sdk/dns/set-records) to change them # dns.getStatus > For the complete documentation index, see [llms.txt](https://ensforge.com/llms.txt). Reads whether a DNS name is imported into ENS, and what it needs to be. Parameters, return value, errors and examples for dns.getStatus in @ensforge/sdk. Source: https://ensforge.com/docs/reference/sdk/dns/get-status Reads whether a DNS name is imported into ENS, and what it needs to be. ## When to use [#when-to-use] Use to tell the user which step comes next, before [`dns.claim`](/docs/reference/sdk/dns/claim). ## Details [#details] - Compares the ENSv1 registry owner with the address in the `_ens` TXT record, and verifies the record's DNSSEC proof against the on-chain DNSSEC oracle. - `action` is the next step: `none`, `claim`, `set-txt-record` or `proof-invalid`. - Gasless DNS names (`ENS1` TXT records) resolve without importing; see [`dns.getOffchainResolver`](/docs/reference/sdk/dns/get-offchain-resolver). ## Signature [#signature] ```ts function getStatus(client: Like, options: getStatus.Options): Promise ``` Call it as `ens.dns.getStatus(options)` on a client, or `Actions.dns.getStatus(client, options)`. `dns.getStatus.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` | | DNS name. Normalized automatically. | | `gatewayUrls` | `readonly string[]` | | DNSSEC gateways to use instead of the deployment's. | Also takes the [read options](/docs/reference/sdk/client#read-options). ## Returns [#returns] Resolves to `Status`. Import state and the next step. | Field | Type | Description | | --- | --- | --- | | `name` | `string` | Normalized name. | | `imported` | `boolean` | Whether the name is in the ENSv1 registry. | | `owner` | `Address \| null` | ENSv1 registry owner, or `null` when not imported. | | `dnsOwner` | `Address \| null` | Address in the `_ens` TXT record (`a=0x…`), or `null` when there is none. | | `proofValid` | `boolean` | Whether the DNSSEC proof of the TXT record verifies against the on-chain DNSSEC oracle. | | `importedInception` | `number \| null` | Inception of the last imported proof, or `null` when none was imported. | | `proofInception` | `number` | Inception of the current DNSSEC proof. | | `action` | `ImportAction` | | ## Errors [#errors] | Error | Codes | When | | --- | --- | --- | | [`InvalidInputError`](/docs/reference/errors/invalid-input-error) | [`INVALID_NAME`](/docs/reference/errors/INVALID_NAME) | names that are not DNS names. | | [`GatewayError`](/docs/reference/errors/gateway-error) | [`GATEWAY_REQUEST_FAILED`](/docs/reference/errors/GATEWAY_REQUEST_FAILED), [`GATEWAY_RESPONSE_INVALID`](/docs/reference/errors/GATEWAY_RESPONSE_INVALID) | the DNSSEC gateway fails. | | [`UnsupportedError`](/docs/reference/errors/unsupported-error) | [`UNSUPPORTED_ON_DEPLOYMENT`](/docs/reference/errors/UNSUPPORTED_ON_DEPLOYMENT) | without a DNSSEC gateway or `gatewayUrls`. | | [`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 DNS name" const status = await ens.dns.getStatus({ name: "example.com" }) ``` ```ts title="Checking a DNS name with a standalone call" import { Actions } from "@ensforge/sdk" const status = await Actions.dns.getStatus(publicClient, { name: "example.com" }) ``` ```ts title="Checking a DNS name in an Effect program" import { Actions } from "@ensforge/sdk/effect" const status = yield* Actions.dns.getStatus(ens, { name: "example.com" }) ``` ## Example response [#example-response] Recorded from Ethereum mainnet on 2026-11-18 at block 26443964. Values change as the chain does. ```ts await ens.dns.getStatus({ name: "ens.domains" }) ``` ```json { "name": "ens.domains", "imported": true, "owner": "0xb8c2C29ee19D8307cb7255e1Cd9CbDE883A267d5", "dnsOwner": "0xb8c2C29ee19D8307cb7255e1Cd9CbDE883A267d5", "proofValid": false, "importedInception": null, "proofInception": 1794939171, "action": "proof-invalid" } ``` ## See also [#see-also] - [`dns.claim`](/docs/reference/sdk/dns/claim) to import it # dns > For the complete documentation index, see [llms.txt](https://ensforge.com/llms.txt). List the 6 dns actions of @ensforge/sdk and whether each reads, writes or signs. Covers claim, getOffchainResolver, getProof, getRecords, getStatus, setRecords. Source: https://ensforge.com/docs/reference/sdk/dns Call them as `ens.dns.(options)` on a client, or `Actions.dns.(client, options)`. ## Reads [#reads] | Action | Description | | --- | --- | | [`getOffchainResolver`](/docs/reference/sdk/dns/get-offchain-resolver) (batchable) | Reads the gasless DNS resolver a DNS name sets in an `ENS1` TXT record. | | [`getProof`](/docs/reference/sdk/dns/get-proof) (batchable) | Fetches the DNSSEC proof of a DNS name's `_ens` TXT record. | | [`getRecords`](/docs/reference/sdk/dns/get-records) (batchable) | Reads DNS records and the zonehash a name stores on its resolver. | | [`getStatus`](/docs/reference/sdk/dns/get-status) (batchable) | Reads whether a DNS name is imported into ENS, and what it needs to be. | ## Writes [#writes] | Action | Description | | --- | --- | | [`claim`](/docs/reference/sdk/dns/claim) | Imports a DNS name into ENS with a DNSSEC proof of its `_ens` TXT record. | | [`setRecords`](/docs/reference/sdk/dns/set-records) | Sets DNS records or the zonehash of a name on its public resolver. | # dns.setRecords > For the complete documentation index, see [llms.txt](https://ensforge.com/llms.txt). Sets DNS records or the zonehash of a name on its public resolver. Parameters, return value, errors and examples for dns.setRecords in @ensforge/sdk. Source: https://ensforge.com/docs/reference/sdk/dns/set-records Sets DNS records or the zonehash of a name on its public resolver. Resolves once the transaction is submitted. ## When to use [#when-to-use] Use to host DNS records in ENS, for DNS servers that read them from ENS. Use [`setRecordsSync`](/docs/reference/sdk/dns/set-records#wait-for-the-receipt-with-setrecordssync) to wait for the receipt. ## Details [#details] - `records`: resource records in DNS wire format; a record with no data deletes it. Owner names are stored in lowercase, as `dns.getRecords` looks them up; record data is sent as given. - `zonehash: null` clears the zonehash. - Only the ENS public resolvers store DNS records. ## Signature [#signature] ```ts function setRecords( client: Like, options: setRecords.Options & Write.Options, ): Promise ``` Call it as `ens.dns.setRecords(options)` on a client, or `Actions.dns.setRecords(client, options)`. ## Parameters [#parameters] | Option | Type | Default | Description | | --- | --- | --- | --- | | `name` (required) | `string` | | ENS name. Normalized automatically. | | `records` | `Hex` | | Resource records in DNS wire format. | | `zonehash` | `Hex \| null` | | Zonehash, or `null` to clear 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_RECORD_VALUE`](/docs/reference/errors/INVALID_RECORD_VALUE) | invalid input, such as records that are not DNS wire format. | | [`NameStateError`](/docs/reference/errors/name-state-error) | [`NAME_EXPIRED`](/docs/reference/errors/NAME_EXPIRED), [`NAME_RESERVED`](/docs/reference/errors/NAME_RESERVED), [`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. | | [`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) | resolvers without DNS records. | | [`UnauthorizedError`](/docs/reference/errors/unauthorized-error) | [`NOT_OWNER`](/docs/reference/errors/NOT_OWNER) | the account may not edit the records. | | [`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="Setting a zonehash" const { hash } = await ens.dns.setRecords({ name: "alice.eth", zonehash: "0xe301…" }) ``` ```ts title="Setting a zonehash with a standalone call" import { Actions } from "@ensforge/sdk" await Actions.dns.setRecords(ens, { name: "alice.eth", zonehash: "0xe301…" }) ``` ```ts title="Setting a zonehash in an Effect program" import { Actions } from "@ensforge/sdk/effect" yield* Actions.dns.setRecords(ens, { name: "alice.eth", zonehash: "0xe301…" }) ``` ## Plan methods [#plan-methods] Each method takes the same options as `dns.setRecords` and sends nothing. See [Preview before sending](/docs/sdk/preview-before-sending). | Method | Description | | --- | --- | | `dns.setRecords.prepare(options)` | Builds the plan without sending anything. | | `dns.setRecords.simulate(options)` | Simulates the plan with `eth_call`, reporting each step. | | `dns.setRecords.estimateGas(options)` | Estimates the gas and ETH the plan needs. | ## Wait for the receipt with `setRecordsSync` [#wait-for-the-receipt-with-setrecordssync] Sets DNS records or the zonehash of a name on its public resolver. Resolves once the receipt is in. Use when the next step depends on the change being on-chain. `dns.setRecordsSync` 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="Setting a zonehash and waiting" const { receipt } = await ens.dns.setRecordsSync({ name: "alice.eth", zonehash: "0xe301…" }) ``` ```ts title="Waiting with a standalone call" import { Actions } from "@ensforge/sdk" await Actions.dns.setRecordsSync(ens, { name: "alice.eth", zonehash: "0xe301…" }) ``` ```ts title="Waiting in an Effect program" import { Actions } from "@ensforge/sdk/effect" yield* Actions.dns.setRecordsSync(ens, { name: "alice.eth", zonehash: "0xe301…" }) ``` ## See also [#see-also] - [`dns.getRecords`](/docs/reference/sdk/dns/get-records) to read them # event.decode > For the complete documentation index, see [llms.txt](https://ensforge.com/llms.txt). Normalizes the ENS events in logs or transaction receipts. Parameters, return value, errors and examples for event.decode in @ensforge/sdk. Source: https://ensforge.com/docs/reference/sdk/event/decode Normalizes the ENS events in logs or transaction receipts. ## When to use [#when-to-use] Use to read what a write did from its receipts, or to classify logs you fetched yourself. ## Details [#details] - Each event carries the indexer's `type` and `action` (bigname's model), the Solidity event name, protocol, emitter, decoded arguments and, when the event spells it, the name. - Logs that are not ENS events (token transfers, other contracts) are skipped. - No RPC calls. ## Signature [#signature] ```ts function decode(client: Like, options: decode.Options): Promise ``` Call it as `ens.event.decode(options)` on a client, or `Actions.event.decode(client, options)`. `event.decode.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 | | --- | --- | --- | --- | | `logs` | `readonly Log[]` | | Logs to decode. | | `receipts` | `readonly TransactionReceipt[]` | | Receipts whose logs to decode. | ## Returns [#returns] Resolves to `readonly Event[]`. The ENS events, in log order. | Field | Type | Description | | --- | --- | --- | | `type` | `EventType` | | | `action` | `EventAction` | | | `event` | `string` | Solidity event name, e.g. `LabelRegistered`. | | `protocol` | `"v1" \| "v2" \| null` | Protocol of the emitting contract; `null` for resolvers ensforge does not know. | | `contract` | `Address` | Emitting contract. | | `name` | `string \| null` | The name the event is about, when the event or the query reveals it. | | `node` | `Hex \| null` | ENS node the event is keyed by, for node-keyed events. | | `args` | `Readonly>` | Decoded event arguments. | | `blockNumber` | `bigint` | | | `transactionHash` | `Hex` | | | `logIndex` | `number` | | ## Errors [#errors] | Error | Codes | When | | --- | --- | --- | | [`InternalError`](/docs/reference/errors/internal-error) | [`UNEXPECTED`](/docs/reference/errors/UNEXPECTED) | malformed logs. | | [`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="Decoding a write's receipts" const events = await ens.event.decode({ receipts }) ``` ```ts title="Decoding a write's receipts with a standalone call" import { Actions } from "@ensforge/sdk" const events = await Actions.event.decode(publicClient, { receipts }) ``` ```ts title="Decoding a write's receipts in an Effect program" import { Actions } from "@ensforge/sdk/effect" const events = yield* Actions.event.decode(ens, { receipts }) ``` ## See also [#see-also] - [`event.get`](/docs/reference/sdk/event/get) to fetch a name's events # event.get > For the complete documentation index, see [llms.txt](https://ensforge.com/llms.txt). Reads the ENS events of one name over a block range, across ENSv1 and ENSv2. Parameters, return value, errors and examples for event.get in @ensforge/sdk. Source: https://ensforge.com/docs/reference/sdk/event/get Reads the ENS events of one name over a block range, across ENSv1 and ENSv2. ## When to use [#when-to-use] Use to show a name's recent activity, or to follow a write's effects, straight from the chain. ## Details [#details] - Scans the name's own contracts: the ENSv1 registry, `.eth` registrar and controllers, NameWrapper, resolver and DNS registrar; the ENSv2 registry holding it (following token regenerations), the ETHRegistrar, its resolver (record links) and its subregistry. - Ranges the RPC provider rejects are split; past `maxRequests` requests the read fails with [`LOG_RANGE_TOO_LARGE`](/docs/reference/errors/LOG_RANGE_TOO_LARGE) instead of sending more. - Address-wide and full history needs an indexer (`indexer.getHistory`). ## Signature [#signature] ```ts function get(client: Like, options: get.Options): Promise ``` Call it as `ens.event.get(options)` on a client, or `Actions.event.get(client, options)`. `event.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 | | --- | --- | --- | --- | | `name` (required) | `string` | | ENS name. Normalized automatically. | | `fromBlock` (required) | `bigint` | | First block, inclusive. | | `toBlock` | `bigint \| "latest"` | `"latest"` | Last block, inclusive. | | `types` | `readonly EventType[]` | | Only these event types. | | `maxRequests` | `number` | `500` | Most `eth_getLogs` requests to send. | Also takes the [read options](/docs/reference/sdk/client#read-options). ## Returns [#returns] Resolves to `readonly Event[]`. The name's ENS events, in chain order. | Field | Type | Description | | --- | --- | --- | | `type` | `EventType` | | | `action` | `EventAction` | | | `event` | `string` | Solidity event name, e.g. `LabelRegistered`. | | `protocol` | `"v1" \| "v2" \| null` | Protocol of the emitting contract; `null` for resolvers ensforge does not know. | | `contract` | `Address` | Emitting contract. | | `name` | `string \| null` | The name the event is about, when the event or the query reveals it. | | `node` | `Hex \| null` | ENS node the event is keyed by, for node-keyed events. | | `args` | `Readonly>` | Decoded event arguments. | | `blockNumber` | `bigint` | | | `transactionHash` | `Hex` | | | `logIndex` | `number` | | ## Errors [#errors] | Error | Codes | When | | --- | --- | --- | | [`InvalidInputError`](/docs/reference/errors/invalid-input-error) | [`INVALID_NAME`](/docs/reference/errors/INVALID_NAME), [`INVALID_RECORD_VALUE`](/docs/reference/errors/INVALID_RECORD_VALUE) | invalid input. | | [`NetworkError`](/docs/reference/errors/network-error) | [`LOG_RANGE_TOO_LARGE`](/docs/reference/errors/LOG_RANGE_TOO_LARGE) | the provider's log limits make the range too expensive. | | [`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 recent events" const events = await ens.event.get({ name: "nick.eth", fromBlock: 26_000_000n }) ``` ```ts title="Reading a name's recent events with a standalone call" import { Actions } from "@ensforge/sdk" const events = await Actions.event.get(publicClient, { name: "nick.eth", fromBlock: 26_000_000n }) ``` ```ts title="Reading a name's recent events in an Effect program" import { Actions } from "@ensforge/sdk/effect" const events = yield* Actions.event.get(ens, { name: "nick.eth", fromBlock: 26_000_000n }) ``` ## See also [#see-also] - [`event.watch`](/docs/reference/sdk/event/watch) to follow new events # event > For the complete documentation index, see [llms.txt](https://ensforge.com/llms.txt). List the 3 event actions of @ensforge/sdk and whether each reads, writes or signs. Covers decode, get, watch. Covers decode, get, watch. Source: https://ensforge.com/docs/reference/sdk/event Call them as `ens.event.(options)` on a client, or `Actions.event.(client, options)`. ## Reads [#reads] | Action | Description | | --- | --- | | [`decode`](/docs/reference/sdk/event/decode) (batchable) | Normalizes the ENS events in logs or transaction receipts. | | [`get`](/docs/reference/sdk/event/get) (batchable) | Reads the ENS events of one name over a block range, across ENSv1 and ENSv2. | | [`watch`](/docs/reference/sdk/event/watch) | Watches one name's ENS events as new blocks arrive. | # event.watch > For the complete documentation index, see [llms.txt](https://ensforge.com/llms.txt). Watches one name's ENS events as new blocks arrive. Parameters, return value, errors and examples for event.watch in @ensforge/sdk. Source: https://ensforge.com/docs/reference/sdk/event/watch Watches one name's ENS events as new blocks arrive. Resolves to a function that stops watching. ## When to use [#when-to-use] Use to update a name's page live, or to react when another account changes the name. ## Details [#details] - Every new block range is read like [`event.get`](/docs/reference/sdk/event/get), so resolver and registry changes during the watch are followed. - Polls at the public client's `pollingInterval` unless `pollingInterval` is given. ## Signature [#signature] ```ts function watch(client: Like, options: watch.Options): Promise ``` Call it as `ens.event.watch(options)` on a client, or `Actions.event.watch(client, options)`. ## Parameters [#parameters] | Option | Type | Default | Description | | --- | --- | --- | --- | | `name` (required) | `string` | | ENS name. Normalized automatically. | | `types` | `readonly EventType[]` | | Only these event types. | | `pollingInterval` | `number` | | Milliseconds between polls. | | `onEvents` (required) | `(events: readonly Event[]) => void` | | Called with each new batch of events. | | `onError` | `((error: AnyError) => void)` | | Called when a poll fails; watching continues. | ## Returns [#returns] Resolves to `() => void`. Stops watching. ## Errors [#errors] | Error | Codes | When | | --- | --- | --- | | [`InvalidInputError`](/docs/reference/errors/invalid-input-error) | [`INVALID_NAME`](/docs/reference/errors/INVALID_NAME) | invalid names. | 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="Watching a name" const unwatch = await ens.event.watch({ name: "nick.eth", onEvents: (events) => console.log(events) }) ``` ```ts title="Watching with a standalone call" import { Actions } from "@ensforge/sdk" const unwatch = await Actions.event.watch(publicClient, { name: "nick.eth", onEvents }) ``` ```ts title="Watching in an Effect program" import { Actions } from "@ensforge/sdk/effect" const unwatch = yield* Actions.event.watch(ens, { name: "nick.eth", onEvents }) ``` ## See also [#see-also] - [`event.get`](/docs/reference/sdk/event/get) to read past events # SDK > For the complete documentation index, see [llms.txt](https://ensforge.com/llms.txt). Browse every action of @ensforge/sdk by domain, with the client, batching, utilities and indexers it exports, each with its signature and examples. Source: https://ensforge.com/docs/reference/sdk Every action of `@ensforge/sdk`, by domain. Each page lists its signature, options, result, errors and examples. ## [approval](/docs/reference/sdk/approval) [#approval] | 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`). | | [`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. | ## [dns](/docs/reference/sdk/dns) [#dns] | Action | Description | | --- | --- | | [`claim`](/docs/reference/sdk/dns/claim) | Imports a DNS name into ENS with a DNSSEC proof of its `_ens` TXT record. | | [`getOffchainResolver`](/docs/reference/sdk/dns/get-offchain-resolver) (batchable) | Reads the gasless DNS resolver a DNS name sets in an `ENS1` TXT record. | | [`getProof`](/docs/reference/sdk/dns/get-proof) (batchable) | Fetches the DNSSEC proof of a DNS name's `_ens` TXT record. | | [`getRecords`](/docs/reference/sdk/dns/get-records) (batchable) | Reads DNS records and the zonehash a name stores on its resolver. | | [`getStatus`](/docs/reference/sdk/dns/get-status) (batchable) | Reads whether a DNS name is imported into ENS, and what it needs to be. | | [`setRecords`](/docs/reference/sdk/dns/set-records) | Sets DNS records or the zonehash of a name on its public resolver. | ## [event](/docs/reference/sdk/event) [#event] | Action | Description | | --- | --- | | [`decode`](/docs/reference/sdk/event/decode) (batchable) | Normalizes the ENS events in logs or transaction receipts. | | [`get`](/docs/reference/sdk/event/get) (batchable) | Reads the ENS events of one name over a block range, across ENSv1 and ENSv2. | | [`watch`](/docs/reference/sdk/event/watch) | Watches one name's ENS events as new blocks arrive. | ## [indexer](/docs/reference/sdk/indexer) [#indexer] | Action | Description | | --- | --- | | [`getEvents`](/docs/reference/sdk/indexer/get-events) (batchable) | Searches indexed ENS events by name, address, resolver, contract or block range. | | [`getHistory`](/docs/reference/sdk/indexer/get-history) (batchable) | Reads the full history of a name, or of every name an address is related to. | | [`getName`](/docs/reference/sdk/indexer/get-name) (batchable) | Reads one name from the indexer: owner, manager, expiry, resolver, records and protocol. | | [`getNamesByExpiry`](/docs/reference/sdk/indexer/get-names-by-expiry) (batchable) | Lists names by when they expire or leave their grace period. | | [`getNamesForAddress`](/docs/reference/sdk/indexer/get-names-for-address) (batchable) | Lists the names an address owns, manages, holds roles on, resolves to, or used to own. | | [`getNamespace`](/docs/reference/sdk/indexer/get-namespace) (batchable) | Reads what the indexer serves for a namespace: its networks and which features are complete. | | [`getPermissions`](/docs/reference/sdk/indexer/get-permissions) (batchable) | Lists who can do what over a name, a registration, an account or an ENSv2 registry. | | [`getPrimaryName`](/docs/reference/sdk/indexer/get-primary-name) (batchable) | Reads an address's primary name from the indexer, verified on-chain when the indexer can. | | [`getRecords`](/docs/reference/sdk/indexer/get-records) (batchable) | Reads a name's records and its record inventory from the indexer. | | [`getRegistry`](/docs/reference/sdk/indexer/get-registry) (batchable) | Reads an ENSv2 registry: the name it serves, its parent registry, when it was created and its counts. | | [`getRegistryLabels`](/docs/reference/sdk/indexer/get-registry-labels) (batchable) | Lists the labels of an ENSv2 registry, optionally only those an address holds or does not hold. | | [`getResolver`](/docs/reference/sdk/indexer/get-resolver) (batchable) | Reads a resolver and one page of the names bound to it. | | [`getResolverLinks`](/docs/reference/sdk/indexer/get-resolver-links) (batchable) | Lists the names linked to record sets on an ENSv2 resolver. | | [`getResolverRoles`](/docs/reference/sdk/indexer/get-resolver-roles) (batchable) | Lists the role grants on an ENSv2 resolver. | | [`getResolvers`](/docs/reference/sdk/indexer/get-resolvers) (batchable) | Lists the ENSv2 resolvers on which an address holds roles. | | [`getStatus`](/docs/reference/sdk/indexer/get-status) (batchable) | Reads the indexer's health and how far each chain is indexed. | | [`getSubnames`](/docs/reference/sdk/indexer/get-subnames) (batchable) | Lists the direct subnames of a name. | | [`lookup`](/docs/reference/sdk/indexer/lookup) (batchable) | Reads up to 1,000 names and addresses in one request. | | [`search`](/docs/reference/sdk/indexer/search) (batchable) | Searches names by text. | ## [migration](/docs/reference/sdk/migration) [#migration] | Action | Description | | --- | --- | | [`get`](/docs/reference/sdk/migration/get) (batchable) | Reads whether an ENSv1 name can migrate to ENSv2, how, and what it becomes. | | [`migrate`](/docs/reference/sdk/migration/migrate) | Migrates one or more ENSv1 names to ENSv2, carrying their resolver records and subnames. | ## [name](/docs/reference/sdk/name) [#name] | Action | Description | | --- | --- | | [`get`](/docs/reference/sdk/name/get) (batchable) | Reads the full state of a name across ENSv1 and ENSv2: where it lives, who owns it, its resolver, expiry and whether it can be registered or renewed. | | [`getLabel`](/docs/reference/sdk/name/get-label) (batchable) | Recovers a label from its labelhash through the ENSv2 LabelStore. | | [`reclaim`](/docs/reference/sdk/name/reclaim) | Resets the ENSv1 registry owner (manager) of an unwrapped `.eth` name, as its registrant. | | [`setManager`](/docs/reference/sdk/name/set-manager) | Sets the ENSv1 manager (registry owner) of a name. | | [`setTtl`](/docs/reference/sdk/name/set-ttl) | Sets the ENSv1 registry TTL of a name. | | [`transfer`](/docs/reference/sdk/name/transfer) | Sends a name to another account and resolves once the transaction is submitted. | ## [permission](/docs/reference/sdk/permission) [#permission] | Action | Description | | --- | --- | | [`check`](/docs/reference/sdk/permission/check) (batchable) | Checks whether an account may perform one operation on an ENS name, and lists exactly what it lacks when it may not. | | [`get`](/docs/reference/sdk/permission/get) (batchable) | Reads what an account may do with an ENS name: transfer it, change its resolver, edit records, create subnames and more, across ENSv1 ownership and ENSv2 roles. | | [`setRecordAccess`](/docs/reference/sdk/permission/set-record-access) | Lets another account edit a name's records, or takes that access back. | ## [plan](/docs/reference/sdk/plan) [#plan] | Action | Description | | --- | --- | | [`get`](/docs/reference/sdk/plan/get) (batchable) | Reads a saved plan and its progress. | | [`list`](/docs/reference/sdk/plan/list) (batchable) | Lists the saved plans of this client's chain and of its `chains`, newest first. | | [`reconcile`](/docs/reference/sdk/plan/reconcile) (batchable) | Records a transaction sent outside ensforge as a plan step's submission. | | [`resume`](/docs/reference/sdk/plan/resume) | Continues a saved plan after a failure or a reload. | | [`send`](/docs/reference/sdk/plan/send) | Sends any plan: one prepared by a write's `.prepare`, or several combined with `Plan.merge`. | ## [primaryName](/docs/reference/sdk/primary-name) [#primaryname] | Action | Description | | --- | --- | | [`get`](/docs/reference/sdk/primary-name/get) (batchable) | Reads the primary name of an address (ENSIP-19 reverse resolution), verified against the name's address record. | | [`set`](/docs/reference/sdk/primary-name/set) | Sets or clears the primary name (reverse record) of an address. | | [`signClaim`](/docs/reference/sdk/primary-name/sign-claim) | Signs a claim to a primary name on one or more L2s, with one signature and no transaction. | ## [record](/docs/reference/sdk/record) [#record] | Action | Description | | --- | --- | | [`get`](/docs/reference/sdk/record/get) (batchable) | Reads any mix of a name's records in one request: texts, addresses, content hash, ABI, public key, name record, interface implementers and data records. | | [`getAddress`](/docs/reference/sdk/record/get-address) (batchable) | Reads one address record of an ENS name, for Ethereum by default or any coin (ENSIP-9, ENSIP-11). | | [`getAvatar`](/docs/reference/sdk/record/get-avatar) (batchable) | Reads the avatar of an ENS name and resolves it to a URL a browser can load (ENSIP-12). | | [`getContentHash`](/docs/reference/sdk/record/get-content-hash) (batchable) | Reads the content hash of an ENS name (ENSIP-7), decoded into its protocol, value and URI. | | [`getText`](/docs/reference/sdk/record/get-text) (batchable) | Reads one text record of an ENS name, such as `url`, `avatar` or `com.twitter`. | | [`set`](/docs/reference/sdk/record/set) | Writes records of an ENS name and resolves once the transaction is submitted. | ## [registration](/docs/reference/sdk/registration) [#registration] | Action | Description | | --- | --- | | [`commit`](/docs/reference/sdk/registration/commit) | Commits to registering `.eth` names, the first half of a registration. | | [`getCommitmentStatus`](/docs/reference/sdk/registration/get-commitment-status) (batchable) | Reads where a registration commitment is in its window. | | [`getParameters`](/docs/reference/sdk/registration/get-parameters) (batchable) | Reads the `.eth` registration settings: contracts, commitment window, minimum duration, grace period and accepted payment tokens. | | [`getPrice`](/docs/reference/sdk/registration/get-price) (batchable) | Quotes the price of registering a `.eth` name, in an ERC-20 payment token. | | [`getRenewalPrice`](/docs/reference/sdk/registration/get-renewal-price) (batchable) | Quotes renewing one or more `.eth` names, in an ERC-20 payment token. | | [`isAvailable`](/docs/reference/sdk/registration/is-available) (batchable) | Checks whether a `.eth` name can be registered now. | | [`register`](/docs/reference/sdk/registration/register) | Registers one or more `.eth` names: approve, commit, wait, register, then records and primary name. | | [`renew`](/docs/reference/sdk/registration/renew) | Renews one or more `.eth` names, ENSv1 or ENSv2, paying in an ERC-20 token. | ## [registry](/docs/reference/sdk/registry) [#registry] | Action | Description | | --- | --- | | [`attach`](/docs/reference/sdk/registry/attach) | Sets or removes the subregistry of an ENSv2 name. | | [`deploy`](/docs/reference/sdk/registry/deploy) | Deploys an ENSv2 UserRegistry, optionally attaching it as a name's subregistry. | | [`get`](/docs/reference/sdk/registry/get) (batchable) | Reads an ENSv2 registry: its kind, implementation, parent, canonical name, URI, whether it is emancipated, and whether it can be upgraded. | | [`setUri`](/docs/reference/sdk/registry/set-uri) | Sets the metadata URI of an ENSv2 registry. | | [`upgrade`](/docs/reference/sdk/registry/upgrade) | Upgrades an ENSv2 registry to the deployment's latest implementation. | ## [resolver](/docs/reference/sdk/resolver) [#resolver] | Action | Description | | --- | --- | | [`create`](/docs/reference/sdk/resolver/create) | Deploys an ENSv2 PermissionedResolver, optionally with records, and points a name at it. | | [`get`](/docs/reference/sdk/resolver/get) (batchable) | Reads the resolver of an ENS name: its address, what kind of resolver it is, who may write to it and which record profiles it supports. | | [`getLink`](/docs/reference/sdk/resolver/get-link) (batchable) | Reads which record set an ENS name uses on its PermissionedResolver. | | [`link`](/docs/reference/sdk/resolver/link) | Links an ENS name to the records of another name on the same PermissionedResolver. | | [`resolve`](/docs/reference/sdk/resolver/resolve) (batchable) | Calls the resolver of an ENS name with raw calldata through the Universal Resolver (ENSIP-10). | | [`set`](/docs/reference/sdk/resolver/set) | Points an ENS name at a resolver. | | [`upgrade`](/docs/reference/sdk/resolver/upgrade) | Upgrades the PermissionedResolver of an ENS name to a newer implementation. | ## [role](/docs/reference/sdk/role) [#role] | Action | Description | | --- | --- | | [`get`](/docs/reference/sdk/role/get) (batchable) | Reads the ENSv2 roles an account holds on a name, or at the root of a registry or resolver. | | [`grant`](/docs/reference/sdk/role/grant) | Grants ENSv2 roles to an account on a name, or at the root of a registry or resolver. | | [`revoke`](/docs/reference/sdk/role/revoke) | Revokes ENSv2 roles from an account on a name, or at the root of a registry or resolver. | ## [subname](/docs/reference/sdk/subname) [#subname] | Action | Description | | --- | --- | | [`create`](/docs/reference/sdk/subname/create) | Creates a subname, routed by its parent: an ENSv2 subregistry, the ENSv1 registry or the NameWrapper. | | [`remove`](/docs/reference/sdk/subname/remove) | Removes a subname. | | [`update`](/docs/reference/sdk/subname/update) | Changes a subname from its parent: owner, resolver or expiry, in one plan. | ## [wrapper](/docs/reference/sdk/wrapper) [#wrapper] | Action | Description | | --- | --- | | [`getFuses`](/docs/reference/sdk/wrapper/get-fuses) (batchable) | Reads the NameWrapper owner, fuses and expiry of an ENSv1 name. | | [`setChildFuses`](/docs/reference/sdk/wrapper/set-child-fuses) | Burns fuses on, or extends, a wrapped ENSv1 subname as its parent's owner. | | [`setFuses`](/docs/reference/sdk/wrapper/set-fuses) | Burns owner-controlled fuses on a wrapped ENSv1 name. | | [`unwrap`](/docs/reference/sdk/wrapper/unwrap) | Unwraps an ENSv1 name from the NameWrapper. | | [`wrap`](/docs/reference/sdk/wrapper/wrap) | Wraps an ENSv1 name in the NameWrapper. | # indexer.getEvents > For the complete documentation index, see [llms.txt](https://ensforge.com/llms.txt). Searches indexed ENS events by name, address, resolver, contract or block range. Options, result, errors and examples for indexer.getEvents. Source: https://ensforge.com/docs/reference/sdk/indexer/get-events Searches indexed ENS events by name, address, resolver, contract or block range. ## When to use [#when-to-use] Use to audit events across names, e.g. every event a resolver emitted or a block range. ## Details [#details] - Filters combine; without any, the newest events of every name are listed. - Same event vocabulary as `event.get` and `indexer.getHistory`. ## Signature [#signature] ```ts function getEvents(client: Like, options: getEvents.Options): Promise ``` Call it as `ens.indexer.getEvents(options)` on a client, or `Actions.indexer.getEvents(client, options)`. `indexer.getEvents.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 | | --- | --- | --- | --- | | `limit` | `number` | | Rows per page, 1–200. @default 50 | | `cursor` | `string` | | The previous page's `cursor`. | | `includeTotal` | `boolean` | | Count every row (`totalCount`); slower. | | `types` | `readonly EventType[]` | | | | `excludeTypes` | `readonly EventType[]` | | | | `recordKey` | `string` | | Record key, e.g. `avatar`, `text:url` or `addr:60`. | | `from` | `bigint \| Date` | | Inclusive time bounds (Unix seconds or dates). | | `to` | `bigint \| Date` | | | | `order` | `"asc" \| "desc"` | `"desc"` | Sort direction. | | `includeData` | `boolean` | | Include each event's details (`data`, `action`). @default true | | `namespace` | `Namespace` | | Only this naming system; every namespace the indexer serves when omitted. | | `registrationId` | `string` | | | | `fromBlock` | `bigint` | | | | `toBlock` | `bigint` | | | | `name` | `string` | | Only events of this name. | | `address` | `string` | | Only events involving this address. | | `resolver` | `{ readonly address: string; readonly chainId?: number \| undefined }` | | Only events of this resolver (on the client's chain unless `chainId` is set). | | `contract` | `string` | | Only events emitted by this contract. | Also takes the [read options](/docs/reference/sdk/client#read-options). ## Returns [#returns] Resolves to `Page`. One page of events. ## 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. | | [`ConfigError`](/docs/reference/errors/config-error) | [`INDEXER_NOT_CONFIGURED`](/docs/reference/errors/INDEXER_NOT_CONFIGURED) | the client has no indexer. | | [`IndexerError`](/docs/reference/errors/indexer-error) | [`INDEXER_UNSUPPORTED`](/docs/reference/errors/INDEXER_UNSUPPORTED) | the indexer does not serve the query or its namespace. | | [`IndexerError`](/docs/reference/errors/indexer-error) | [`INDEXER_UNAVAILABLE`](/docs/reference/errors/INDEXER_UNAVAILABLE), [`INDEXER_RATE_LIMITED`](/docs/reference/errors/INDEXER_RATE_LIMITED), [`INDEXER_BEHIND`](/docs/reference/errors/INDEXER_BEHIND), [`INDEXER_REQUEST_REJECTED`](/docs/reference/errors/INDEXER_REQUEST_REJECTED), [`INDEXER_RESPONSE_INVALID`](/docs/reference/errors/INDEXER_RESPONSE_INVALID) | the indexer is unavailable, rate limiting, behind, rejects the request or answers unexpectedly. | 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 resolver's events" const page = await ens.indexer.getEvents({ resolver: { address: "0x231b…" } }) ``` ```ts title="Reading a block range with a standalone call" import { Actions } from "@ensforge/sdk" const page = await Actions.indexer.getEvents(ens, { fromBlock: 26_000_000n, toBlock: 26_000_100n }) ``` ```ts title="Reading registrations in an Effect program" import { Actions } from "@ensforge/sdk/effect" const page = yield* Actions.indexer.getEvents(ens, { types: ["registration"], order: "desc" }) ``` ## Example response [#example-response] Recorded from Ethereum mainnet on 2026-11-18 at block 26443964. Values change as the chain does. ```ts await ens.indexer.getEvents({ name: "ens.eth", limit: 3 }) ``` ```json { "asOf": { "chainId": 1, "blockNumber": "26443964n", "blockHash": "0xe75c58ea2f28bd7c6cc53c28a5ab4fc02023f3563661f0a7236a36b779e3ac86", "timestamp": "1795029143n" }, "snapshots": { "1": { "chainId": 1, "blockNumber": "26443964n", "blockHash": "0xe75c58ea2f28bd7c6cc53c28a5ab4fc02023f3563661f0a7236a36b779e3ac86", "timestamp": "1795029143n" } }, "asOfToken": null, "completeness": "full", "unsupportedReason": null, "unsupportedFields": [], "origin": null, "indexer": "bigname", "items": [ { "id": "c3632a2b4582290d29bcc6f8c3b3b542664ce1257e2783dd83dcf02554451942", "type": "record", "action": "record_changed", "kind": null, "name": "ens.eth", "namespace": "ens", "subject": null, "registrationId": "04316989-63d2-5789-b7a6-c454b62d0294", "contract": "0x4976fb03C32e5B8cfe2b6cCB31c09Ba78EBaBa41", "blockNumber": "26405156n", "timestamp": "1794562235n", "transactionHash": "0xfc3c4b113b1e57565527d606e84511ee168437c9579f1d7e18ce132b86176687", "logIndex": 434, "data": { "action": "record_changed", "key": "contenthash", "node": "0x4e34d3a81dc3a20f71bbdf2160492ddaa17ee7e5523757d47153379c13cb46df", "resolver": { "address": "0x4976fb03c32e5b8cfe2b6ccb31c09ba78ebaba41", "chainId": 1 } } }, { "id": "ba6ade15daa5bccf278f9290bfe87e3e673541adf7667e7afb436261a44b4ded", "type": "record", "action": "record_changed", "kind": null, "name": "ens.eth", "namespace": "ens", "subject": null, "registrationId": "04316989-63d2-5789-b7a6-c454b62d0294", "contract": "0x4976fb03C32e5B8cfe2b6cCB31c09Ba78EBaBa41", "blockNumber": "26350975n", "timestamp": "1793909915n", "transactionHash": "0xba75418b56c3b12e2702ad3e4436f799af3d544ddcd1a97d92ad7de7e458c166", "logIndex": 419, "data": { "action": "record_changed", "key": "contenthash", "node": "0x4e34d3a81dc3a20f71bbdf2160492ddaa17ee7e5523757d47153379c13cb46df", "resolver": { "address": "0x4976fb03c32e5b8cfe2b6ccb31c09ba78ebaba41", "chainId": 1 } } }, { "id": "5bcef94bca0d5de81f752ca12517fbf833d03f1ace6bf1aafd20a561601c3534", "type": "record", "action": "record_changed", "kind": null, "name": "ens.eth", "namespace": "ens", "subject": null, "registrationId": "04316989-63d2-5789-b7a6-c454b62d0294", "contract": "0x4976fb03C32e5B8cfe2b6cCB31c09Ba78EBaBa41", "blockNumber": "26350931n", "timestamp": "1793909387n", "transactionHash": "0x403b425f4242030a1beec24a67240f0fbca92cab8ff0768e0c055bbcbe467f53", "logIndex": 606, "data": { "action": "record_changed", "key": "contenthash", "node": "0x4e34d3a81dc3a20f71bbdf2160492ddaa17ee7e5523757d47153379c13cb46df", "resolver": { "address": "0x4976fb03c32e5b8cfe2b6ccb31c09ba78ebaba41", "chainId": 1 } } } ], "cursor": "7b2276657273696f6e223a312c22736f7274223a22636861696e5f706f736974696f6e5f64657363222c2266696c74657273223a7b22686973746f72795f636f6e7472616374223a2232222c226e616d65223a22656e733a307834653334643361383164633361323066373162626466323136303439326464616131376565376535353233373537643437313533333739633133636234366466222c226e616d657370616365223a22656e73227d2c226c6173745f6974656d223a7b22626c6f636b5f68617368223a22307864343233346166643533616636353032356364653662396364323032363136343164656138326661646333393432353833346361346331353733353238356637222c22626c6f636b5f6e756d626572223a223236333530393331222c22636861696e5f6964223a22657468657265756d2d6d61696e6e6574222c226576656e745f6964656e74697479223a22656e735f76315f756e777261707065645f617574686f726974793a31343a657468657265756d2d6d61696e6e65743a3078643432333461666435336166363530323563646536623963643230323631363431646561383266616463333934323538333463613463313537333532383566373a3078343033623432356634323432303330613162656563323461363732343066306662636139326361623866663037363865306330353562626362653436376635333a3630363a5265636f72644368616e6765643a30222c226c6f675f696e646578223a22363036222c227472616e73616374696f6e5f696e646578223a22343038227d2c22736e617073686f74223a6e756c6c7d", "hasMore": true, "totalCount": null } ``` ## See also [#see-also] - [`indexer.getHistory`](/docs/reference/sdk/indexer/get-history) for one name or address # indexer.getHistory > For the complete documentation index, see [llms.txt](https://ensforge.com/llms.txt). Reads the full history of a name, or of every name an address is related to. Options, result, errors and examples for indexer.getHistory. Source: https://ensforge.com/docs/reference/sdk/indexer/get-history Reads the full history of a name, or of every name an address is related to. ## When to use [#when-to-use] Use to show an activity feed for a name or an account, back to its first event. ## Details [#details] - Events use the same `type` and `action` vocabulary as `event.get`, which reads recent events straight from the chain. - Newest first by default (`order: "asc"` for oldest first); each event carries its details (`data`) unless `includeData: false`. - `scope` selects the name's own events, its registrations' events, or both (default). ## Signature [#signature] ```ts function getHistory( client: Like, options: getHistory.Options, ): Promise ``` Call it as `ens.indexer.getHistory(options)` on a client, or `Actions.indexer.getHistory(client, options)`. `indexer.getHistory.request(options)` builds a deferred read for `Actions.batch`. See [Look up many at once](/docs/sdk/look-up-many-at-once). In React, use [`useNameHistory`](/docs/reference/react/use-name-history). ## Parameters [#parameters] With `name`: | Option | Type | Default | Description | | --- | --- | --- | --- | | `limit` | `number` | | Rows per page, 1–200. @default 50 | | `cursor` | `string` | | The previous page's `cursor`. | | `includeTotal` | `boolean` | | Count every row (`totalCount`); slower. | | `types` | `readonly EventType[]` | | | | `excludeTypes` | `readonly EventType[]` | | | | `recordKey` | `string` | | Record key, e.g. `avatar`, `text:url` or `addr:60`. | | `from` | `bigint \| Date` | | Inclusive time bounds (Unix seconds or dates). | | `to` | `bigint \| Date` | | | | `order` | `"asc" \| "desc"` | `"desc"` | Sort direction. | | `includeData` | `boolean` | | Include each event's details (`data`, `action`). @default true | | `namespace` | `Namespace` | | Namespace; inferred from the name, or every namespace for an address. | | `scope` | `"name" \| "registration" \| "both"` | | Name events, registration events, or both. @default "both" | | `name` (required) | `string` | | The name whose history to read. | | `includeChildRegistrations` | `boolean` | | Also the registrations of its children. | With `address`: | Option | Type | Default | Description | | --- | --- | --- | --- | | `limit` | `number` | | Rows per page, 1–200. @default 50 | | `cursor` | `string` | | The previous page's `cursor`. | | `includeTotal` | `boolean` | | Count every row (`totalCount`); slower. | | `types` | `readonly EventType[]` | | | | `excludeTypes` | `readonly EventType[]` | | | | `recordKey` | `string` | | Record key, e.g. `avatar`, `text:url` or `addr:60`. | | `from` | `bigint \| Date` | | Inclusive time bounds (Unix seconds or dates). | | `to` | `bigint \| Date` | | | | `order` | `"asc" \| "desc"` | `"desc"` | Sort direction. | | `includeData` | `boolean` | | Include each event's details (`data`, `action`). @default true | | `namespace` | `Namespace` | | Namespace; inferred from the name, or every namespace for an address. | | `scope` | `"name" \| "registration" \| "both"` | | Name events, registration events, or both. @default "both" | | `address` (required) | `string` | | The address whose names' history to read. | | `relation` | `readonly ("owner" \| "manager" \| "roleHolder")[]` | | Relations to follow. @default ["owner", "manager", "roleHolder"] | Also takes the [read options](/docs/reference/sdk/client#read-options). ## Returns [#returns] Resolves to `Page`. One page of events. ## 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) | [`INDEXER_NOT_FOUND`](/docs/reference/errors/INDEXER_NOT_FOUND) | the indexer has no such name. | | [`ConfigError`](/docs/reference/errors/config-error) | [`INDEXER_NOT_CONFIGURED`](/docs/reference/errors/INDEXER_NOT_CONFIGURED) | the client has no indexer. | | [`IndexerError`](/docs/reference/errors/indexer-error) | [`INDEXER_UNSUPPORTED`](/docs/reference/errors/INDEXER_UNSUPPORTED) | the indexer does not serve the query or its namespace. | | [`IndexerError`](/docs/reference/errors/indexer-error) | [`INDEXER_UNAVAILABLE`](/docs/reference/errors/INDEXER_UNAVAILABLE), [`INDEXER_RATE_LIMITED`](/docs/reference/errors/INDEXER_RATE_LIMITED), [`INDEXER_BEHIND`](/docs/reference/errors/INDEXER_BEHIND), [`INDEXER_REQUEST_REJECTED`](/docs/reference/errors/INDEXER_REQUEST_REJECTED), [`INDEXER_RESPONSE_INVALID`](/docs/reference/errors/INDEXER_RESPONSE_INVALID) | the indexer is unavailable, rate limiting, behind, rejects the request or answers unexpectedly. | 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 history" const page = await ens.indexer.getHistory({ name: "nick.eth" }) ``` ```ts title="Reading an address's history with a standalone call" import { Actions } from "@ensforge/sdk" const page = await Actions.indexer.getHistory(ens, { address, types: ["transfer"] }) ``` ```ts title="Reading record changes in an Effect program" import { Actions } from "@ensforge/sdk/effect" const page = yield* Actions.indexer.getHistory(ens, { name: "nick.eth", recordKey: "avatar" }) ``` ## Example response [#example-response] Recorded from Ethereum mainnet on 2026-11-18 at block 26443964. Values change as the chain does. ```ts await ens.indexer.getHistory({ name: "ens.eth", namespace: "ens", limit: 3 }) ``` ```json { "asOf": { "chainId": 1, "blockNumber": "26443964n", "blockHash": "0xe75c58ea2f28bd7c6cc53c28a5ab4fc02023f3563661f0a7236a36b779e3ac86", "timestamp": "1795029143n" }, "snapshots": { "1": { "chainId": 1, "blockNumber": "26443964n", "blockHash": "0xe75c58ea2f28bd7c6cc53c28a5ab4fc02023f3563661f0a7236a36b779e3ac86", "timestamp": "1795029143n" } }, "asOfToken": null, "completeness": "full", "unsupportedReason": null, "unsupportedFields": [], "origin": null, "indexer": "bigname", "items": [ { "id": "c3632a2b4582290d29bcc6f8c3b3b542664ce1257e2783dd83dcf02554451942", "type": "record", "action": "record_changed", "kind": null, "name": "ens.eth", "namespace": "ens", "subject": null, "registrationId": "04316989-63d2-5789-b7a6-c454b62d0294", "contract": "0x4976fb03C32e5B8cfe2b6cCB31c09Ba78EBaBa41", "blockNumber": "26405156n", "timestamp": "1794562235n", "transactionHash": "0xfc3c4b113b1e57565527d606e84511ee168437c9579f1d7e18ce132b86176687", "logIndex": 434, "data": { "action": "record_changed", "key": "contenthash", "node": "0x4e34d3a81dc3a20f71bbdf2160492ddaa17ee7e5523757d47153379c13cb46df", "resolver": { "address": "0x4976fb03c32e5b8cfe2b6ccb31c09ba78ebaba41", "chainId": 1 } } }, { "id": "ba6ade15daa5bccf278f9290bfe87e3e673541adf7667e7afb436261a44b4ded", "type": "record", "action": "record_changed", "kind": null, "name": "ens.eth", "namespace": "ens", "subject": null, "registrationId": "04316989-63d2-5789-b7a6-c454b62d0294", "contract": "0x4976fb03C32e5B8cfe2b6cCB31c09Ba78EBaBa41", "blockNumber": "26350975n", "timestamp": "1793909915n", "transactionHash": "0xba75418b56c3b12e2702ad3e4436f799af3d544ddcd1a97d92ad7de7e458c166", "logIndex": 419, "data": { "action": "record_changed", "key": "contenthash", "node": "0x4e34d3a81dc3a20f71bbdf2160492ddaa17ee7e5523757d47153379c13cb46df", "resolver": { "address": "0x4976fb03c32e5b8cfe2b6ccb31c09ba78ebaba41", "chainId": 1 } } }, { "id": "5bcef94bca0d5de81f752ca12517fbf833d03f1ace6bf1aafd20a561601c3534", "type": "record", "action": "record_changed", "kind": null, "name": "ens.eth", "namespace": "ens", "subject": null, "registrationId": "04316989-63d2-5789-b7a6-c454b62d0294", "contract": "0x4976fb03C32e5B8cfe2b6cCB31c09Ba78EBaBa41", "blockNumber": "26350931n", "timestamp": "1793909387n", "transactionHash": "0x403b425f4242030a1beec24a67240f0fbca92cab8ff0768e0c055bbcbe467f53", "logIndex": 606, "data": { "action": "record_changed", "key": "contenthash", "node": "0x4e34d3a81dc3a20f71bbdf2160492ddaa17ee7e5523757d47153379c13cb46df", "resolver": { "address": "0x4976fb03c32e5b8cfe2b6ccb31c09ba78ebaba41", "chainId": 1 } } } ], "cursor": "7b2276657273696f6e223a312c22736f7274223a22636861696e5f706f736974696f6e5f64657363222c2266696c74657273223a7b22686973746f72795f636f6e7472616374223a2232222c226e616d65223a22656e733a307834653334643361383164633361323066373162626466323136303439326464616131376565376535353233373537643437313533333739633133636234366466222c226e616d657370616365223a22656e73222c2273636f7065223a22626f7468227d2c226c6173745f6974656d223a7b22626c6f636b5f68617368223a22307864343233346166643533616636353032356364653662396364323032363136343164656138326661646333393432353833346361346331353733353238356637222c22626c6f636b5f6e756d626572223a223236333530393331222c22636861696e5f6964223a22657468657265756d2d6d61696e6e6574222c226576656e745f6964656e74697479223a22656e735f76315f756e777261707065645f617574686f726974793a31343a657468657265756d2d6d61696e6e65743a3078643432333461666435336166363530323563646536623963643230323631363431646561383266616463333934323538333463613463313537333532383566373a3078343033623432356634323432303330613162656563323461363732343066306662636139326361623866663037363865306330353562626362653436376635333a3630363a5265636f72644368616e6765643a30222c226c6f675f696e646578223a22363036222c227472616e73616374696f6e5f696e646578223a22343038227d2c22736e617073686f74223a6e756c6c7d", "hasMore": true, "totalCount": 171 } ``` ## See also [#see-also] - [`event.get`](/docs/reference/sdk/event/get) for recent events from the chain - `paginate` from `@ensforge/sdk/indexer` to walk every page # indexer.getName > For the complete documentation index, see [llms.txt](https://ensforge.com/llms.txt). Reads one name from the indexer: owner, manager, expiry, resolver, records and protocol. Options, result, errors and examples for indexer.getName. Source: https://ensforge.com/docs/reference/sdk/indexer/get-name Reads one name from the indexer: owner, manager, expiry, resolver, records and protocol. ## When to use [#when-to-use] Use to show a name page, or anywhere an indexed answer is fast enough; for an authoritative on- chain read, use `name.get`. ## Details [#details] - Basenames (`*.base.eth`) are read from the `basenames` namespace. - `authority` says which protocol holds the name (`ensV0`, `ensV1` or `ensV2`). - `source: "verified"` asks the indexer to read the answer on-chain (bigname). - Returns `null` when the indexer has no such name, or throws with `strict: true`. ## Signature [#signature] ```ts function getName(client: Like, options: getName.Options): Promise ``` Call it as `ens.indexer.getName(options)` on a client, or `Actions.indexer.getName(client, options)`. `indexer.getName.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 | | --- | --- | --- | --- | | `at` | `{ readonly token: string } \| { readonly timestamp: bigint \| Date }` | | Read at a snapshot: an earlier answer's `asOfToken`, or a time. | | `finality` | `"latest" \| "safe" \| "finalized"` | `"latest"` | How settled the data must be: `latest`, `safe` or `finalized`. | | `name` (required) | `string` | | | | `source` | `"indexed" \| "verified"` | | `verified` reads the answer on-chain through the indexer. @default "indexed" | | `namespace` | `Namespace` | "basenames" for `*.base.eth`, otherwise "ens" | Namespace of the name. | Also takes the [read options](/docs/reference/sdk/client#read-options). ## Returns [#returns] Resolves to `Result | null`. The name, or `null` when the indexer does not know it. ## Errors [#errors] | Error | Codes | When | | --- | --- | --- | | [`InvalidInputError`](/docs/reference/errors/invalid-input-error) | [`INVALID_NAME`](/docs/reference/errors/INVALID_NAME) | the name does not normalize. | | [`NotFoundError`](/docs/reference/errors/not-found-error) | [`INDEXER_NOT_FOUND`](/docs/reference/errors/INDEXER_NOT_FOUND) | with `strict: true` when the indexer has no such name. | | [`ConfigError`](/docs/reference/errors/config-error) | [`INDEXER_NOT_CONFIGURED`](/docs/reference/errors/INDEXER_NOT_CONFIGURED) | the client has no indexer. | | [`IndexerError`](/docs/reference/errors/indexer-error) | [`INDEXER_UNSUPPORTED`](/docs/reference/errors/INDEXER_UNSUPPORTED) | the indexer does not serve the query or its namespace. | | [`IndexerError`](/docs/reference/errors/indexer-error) | [`INDEXER_UNAVAILABLE`](/docs/reference/errors/INDEXER_UNAVAILABLE), [`INDEXER_RATE_LIMITED`](/docs/reference/errors/INDEXER_RATE_LIMITED), [`INDEXER_BEHIND`](/docs/reference/errors/INDEXER_BEHIND), [`INDEXER_REQUEST_REJECTED`](/docs/reference/errors/INDEXER_REQUEST_REJECTED), [`INDEXER_RESPONSE_INVALID`](/docs/reference/errors/INDEXER_RESPONSE_INVALID) | the indexer is unavailable, rate limiting, behind, rejects the request or answers unexpectedly. | 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" const name = await ens.indexer.getName({ name: "nick.eth" }) ``` ```ts title="Reading a name with a standalone call" import { Actions } from "@ensforge/sdk" const name = await Actions.indexer.getName(ens, { name: "jesse.base.eth" }) ``` ```ts title="Reading a name in an Effect program" import { Actions } from "@ensforge/sdk/effect" const name = yield* Actions.indexer.getName(ens, { name: "nick.eth", strict: true }) ``` ## Example response [#example-response] Recorded from Ethereum mainnet on 2026-11-18 at block 26443964. Values change as the chain does. ```ts await ens.indexer.getName({ name: "ens.eth", namespace: "ens" }) ``` ```json { "name": "ens.eth", "displayName": "ens.eth", "namespace": "ens", "node": "0x4e34d3a81dc3a20f71bbdf2160492ddaa17ee7e5523757d47153379c13cb46df", "status": "active", "authority": "ensV1", "owner": "0x690F0581eCecCf8389c223170778cD9D029606F2", "manager": "0x2d2e339c93dA91682Db720ee73e3c8F854f5F246", "registeredAt": "1580760321n", "createdAt": "1566796141n", "expiresAt": "1919549217n", "graceEndsAt": "1921968417n", "expiryReason": null, "ensV1": { "resolver": { "chainId": 1, "address": "0x4976fb03C32e5B8cfe2b6cCB31c09Ba78EBaBa41" }, "expiresAt": "1914192417n", "wrapperState": "unwrapped", "wrapperExpiresAt": null, "wrapperFuses": null }, "chainId": 1, "registrationId": "04316989-63d2-5789-b7a6-c454b62d0294", "tokenId": "42033647921836720708986079437023664695436352815832009766988496528855301124570n", "resolver": { "chainId": 1, "address": "0x4976fb03C32e5B8cfe2b6cCB31c09Ba78EBaBa41" }, "subregistry": null, "primaryAddress": "0xFe89cc7aBB2C4183683ab71653C4cdc9B02D44b7", "migratedAt": null, "records": { "texts": { "avatar": "https://i.imgur.com/ga6y0c0.jpg", "com.github": "ensdomains", "com.twitter": "ensdomains", "snapshot": "ipns://storage.snapshot.page/registry/0xb6E040C9ECAaE172a89bD561c5F73e1C48d28cd9/ens.eth", "url": "https://ens.domains/" }, "addresses": { "60": "0xfe89cc7abb2c4183683ab71653c4cdc9b02d44b7" }, "contentHash": "0xe40101fa011b20f5909b5286d9279a1f6a23d5155ddd72bb0f28f56b6b82c32de54a6529e6b1b0", "name": null, "textKeys": [ "avatar", "com.github", "com.twitter", "snapshot", "url" ], "coinTypes": [ "60" ] }, "recordCount": null, "subnameCount": null, "asOf": { "chainId": 1, "blockNumber": "26443964n", "blockHash": "0xe75c58ea2f28bd7c6cc53c28a5ab4fc02023f3563661f0a7236a36b779e3ac86", "timestamp": "1795029143n" }, "snapshots": { "1": { "chainId": 1, "blockNumber": "26443964n", "blockHash": "0xe75c58ea2f28bd7c6cc53c28a5ab4fc02023f3563661f0a7236a36b779e3ac86", "timestamp": "1795029143n" } }, "asOfToken": "7b22657468657265756d223a7b22626c6f636b5f68617368223a22307865373563353865613266323862643763366363353363323861356162346663303230323366333536333636316630613732333661333662373739653361633836222c22626c6f636b5f6e756d626572223a32363434333936342c22636861696e5f6964223a22657468657265756d2d6d61696e6e6574222c2274696d657374616d70223a22323032362d31312d31385431393a31323a32335a227d7d", "completeness": "full", "unsupportedReason": null, "unsupportedFields": [], "origin": "indexed", "indexer": "bigname" } ``` ## See also [#see-also] - [`name.get`](/docs/reference/sdk/name/get) for the on-chain state # indexer.getNamesByExpiry > For the complete documentation index, see [llms.txt](https://ensforge.com/llms.txt). Lists names by when they expire or leave their grace period. Parameters, return value, errors and examples for indexer.getNamesByExpiry in @ensforge/sdk. Source: https://ensforge.com/docs/reference/sdk/indexer/get-names-by-expiry Lists names by when they expire or leave their grace period. ## When to use [#when-to-use] Use to find names expiring soon, e.g. renewal reminders or a drop-catching list. ## Details [#details] - Pass either expiry bounds (`expiresAfter`, `expiresBefore`, `windows`) or grace bounds (`graceEndsAfter`, `graceEndsBefore`, `graceWindows`), not both. - With `windows`, each name reports the window it matched (`windowIndex`). ## Signature [#signature] ```ts function getNamesByExpiry( client: Like, options: getNamesByExpiry.Options, ): Promise ``` Call it as `ens.indexer.getNamesByExpiry(options)` on a client, or `Actions.indexer.getNamesByExpiry(client, options)`. `indexer.getNamesByExpiry.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 | | --- | --- | --- | --- | | `limit` | `number` | | Rows per page, 1–200. @default 50 | | `cursor` | `string` | | The previous page's `cursor`. | | `includeTotal` | `boolean` | | Count every row (`totalCount`); slower. | | `expiresAfter` | `bigint \| Date` | | | | `expiresBefore` | `bigint \| Date` | | | | `windows` | `readonly Window[]` | | Up to 32 disjoint expiry windows; results report the matching `windowIndex`. | | `graceEndsAfter` | `bigint \| Date` | | | | `graceEndsBefore` | `bigint \| Date` | | | | `graceWindows` | `readonly Window[]` | | | | `authority` | `Authority \| readonly Authority[]` | | | | `parent` | `string` | | | | `sort` | `"expiry" \| "graceEnd"` | | Field the rows are sorted by. | | `order` | `"asc" \| "desc"` | | Sort direction. | | `namespace` | `Namespace` | `"ens"` | | Also takes the [read options](/docs/reference/sdk/client#read-options). ## Returns [#returns] Resolves to `Page`. One page of names, soonest first unless `order` says otherwise. ## Errors [#errors] | Error | Codes | When | | --- | --- | --- | | [`InvalidInputError`](/docs/reference/errors/invalid-input-error) | [`INVALID_NAME`](/docs/reference/errors/INVALID_NAME) | `parent` does not normalize. | | [`ConfigError`](/docs/reference/errors/config-error) | [`INDEXER_NOT_CONFIGURED`](/docs/reference/errors/INDEXER_NOT_CONFIGURED) | the client has no indexer. | | [`IndexerError`](/docs/reference/errors/indexer-error) | [`INDEXER_UNSUPPORTED`](/docs/reference/errors/INDEXER_UNSUPPORTED) | the indexer does not serve the query or its namespace. | | [`IndexerError`](/docs/reference/errors/indexer-error) | [`INDEXER_UNAVAILABLE`](/docs/reference/errors/INDEXER_UNAVAILABLE), [`INDEXER_RATE_LIMITED`](/docs/reference/errors/INDEXER_RATE_LIMITED), [`INDEXER_BEHIND`](/docs/reference/errors/INDEXER_BEHIND), [`INDEXER_REQUEST_REJECTED`](/docs/reference/errors/INDEXER_REQUEST_REJECTED), [`INDEXER_RESPONSE_INVALID`](/docs/reference/errors/INDEXER_RESPONSE_INVALID) | the indexer is unavailable, rate limiting, behind, rejects the request or answers unexpectedly. | 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="Listing names expiring this month" const page = await ens.indexer.getNamesByExpiry({ expiresAfter: new Date(), expiresBefore: inAMonth }) ``` ```ts title="Listing names leaving grace with a standalone call" import { Actions } from "@ensforge/sdk" const page = await Actions.indexer.getNamesByExpiry(ens, { graceEndsBefore: tomorrow }) ``` ```ts title="Listing subnames by expiry in an Effect program" import { Actions } from "@ensforge/sdk/effect" const page = yield* Actions.indexer.getNamesByExpiry(ens, { parent: "eth", expiresBefore: inAWeek }) ``` # indexer.getNamesForAddress > For the complete documentation index, see [llms.txt](https://ensforge.com/llms.txt). Lists the names an address owns, manages, holds roles on, resolves to, or used to own. Options, result, errors and examples for indexer.getNamesForAddress. Source: https://ensforge.com/docs/reference/sdk/indexer/get-names-for-address Lists the names an address owns, manages, holds roles on, resolves to, or used to own. ## When to use [#when-to-use] Use to show an account's names, e.g. a "my names" page or a name picker. ## Details [#details] - `relation` defaults to `any`: owner, manager and role holder. `resolvesTo` (with `coin`) and `formerOwner` are listed on their own. - Lists every namespace the indexer serves unless `namespace` is set. - Pages hold up to `limit` names (default 50, at most 200); pass `cursor` for the next page, or use `paginate`. ## Signature [#signature] ```ts function getNamesForAddress( client: Like, options: getNamesForAddress.Options, ): Promise ``` Call it as `ens.indexer.getNamesForAddress(options)` on a client, or `Actions.indexer.getNamesForAddress(client, options)`. `indexer.getNamesForAddress.request(options)` builds a deferred read for `Actions.batch`. See [Look up many at once](/docs/sdk/look-up-many-at-once). In React, use [`useNamesForAddress`](/docs/reference/react/use-names-for-address). ## Parameters [#parameters] | Option | Type | Default | Description | | --- | --- | --- | --- | | `limit` | `number` | | Rows per page, 1–200. @default 50 | | `cursor` | `string` | | The previous page's `cursor`. | | `includeTotal` | `boolean` | | Count every row (`totalCount`); slower. | | `namespace` | `Namespace` | | Every namespace the indexer serves when omitted. | | `relation` | `Relation \| "any" \| readonly Relation[]` | | Relations to list; `any` is owner, manager and role holder. `resolvesTo` and `formerOwner` stand alone. @default "any" | | `authority` | `Authority \| readonly Authority[]` | | | | `migrated` | `boolean` | | Only names migrated to ENSv2 (or only not migrated). | | `expiresAfter` | `bigint \| Date` | | Expiry bounds (Unix seconds or dates), with `formerOwner` only. | | `expiresBefore` | `bigint \| Date` | | | | `search` | `string` | | | | `match` | `"prefix" \| "contains"` | `"prefix"` | Whether `search` matches from the start of a label (`prefix`) or anywhere (`contains`). | | `sort` | `"name" \| "expiry" \| "registered" \| "created"` | | Field the rows are sorted by. | | `order` | `"asc" \| "desc"` | | Sort direction. | | `dedupe` | `"name" \| "registration"` | | One row per name, or per registration. @default "name" | | `address` (required) | `string` | | The address, all lowercase or checksummed. | | `coin` | `CoinType.Input \| "evm"` | | Coin type for `relation: "resolvesTo"`, or `evm` for every EVM chain. @default 60 | | `parent` | `string` | | Only direct children of this name. | Also takes the [read options](/docs/reference/sdk/client#read-options). ## Returns [#returns] Resolves to `Page`. One page of names, each with how the address relates to it. ## Errors [#errors] | Error | Codes | When | | --- | --- | --- | | [`InvalidInputError`](/docs/reference/errors/invalid-input-error) | [`INVALID_ADDRESS`](/docs/reference/errors/INVALID_ADDRESS), [`INVALID_COIN_TYPE`](/docs/reference/errors/INVALID_COIN_TYPE), [`INVALID_NAME`](/docs/reference/errors/INVALID_NAME) | invalid input. | | [`ConfigError`](/docs/reference/errors/config-error) | [`INDEXER_NOT_CONFIGURED`](/docs/reference/errors/INDEXER_NOT_CONFIGURED) | the client has no indexer. | | [`IndexerError`](/docs/reference/errors/indexer-error) | [`INDEXER_UNSUPPORTED`](/docs/reference/errors/INDEXER_UNSUPPORTED) | the indexer does not serve the query or its namespace. | | [`IndexerError`](/docs/reference/errors/indexer-error) | [`INDEXER_UNAVAILABLE`](/docs/reference/errors/INDEXER_UNAVAILABLE), [`INDEXER_RATE_LIMITED`](/docs/reference/errors/INDEXER_RATE_LIMITED), [`INDEXER_BEHIND`](/docs/reference/errors/INDEXER_BEHIND), [`INDEXER_REQUEST_REJECTED`](/docs/reference/errors/INDEXER_REQUEST_REJECTED), [`INDEXER_RESPONSE_INVALID`](/docs/reference/errors/INDEXER_RESPONSE_INVALID) | the indexer is unavailable, rate limiting, behind, rejects the request or answers unexpectedly. | 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="Listing an address's names" const page = await ens.indexer.getNamesForAddress({ address: "0xb8c2…" }) ``` ```ts title="Listing names that resolve to an address with a standalone call" import { Actions } from "@ensforge/sdk" const page = await Actions.indexer.getNamesForAddress(ens, { address, relation: "resolvesTo" }) ``` ```ts title="Listing an address's names in an Effect program" import { Actions } from "@ensforge/sdk/effect" const page = yield* Actions.indexer.getNamesForAddress(ens, { address, sort: "expiry" }) ``` ## Example response [#example-response] Recorded from Ethereum mainnet on 2026-11-18 at block 26443964. Values change as the chain does. ```ts await ens.indexer.getNamesForAddress({ address: "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045", limit: 3 }) ``` ```json { "asOf": { "chainId": 1, "blockNumber": "26443964n", "blockHash": "0xe75c58ea2f28bd7c6cc53c28a5ab4fc02023f3563661f0a7236a36b779e3ac86", "timestamp": "1795029143n" }, "snapshots": { "1": { "chainId": 1, "blockNumber": "26443964n", "blockHash": "0xe75c58ea2f28bd7c6cc53c28a5ab4fc02023f3563661f0a7236a36b779e3ac86", "timestamp": "1795029143n" } }, "asOfToken": null, "completeness": "full", "unsupportedReason": null, "unsupportedFields": [], "origin": null, "indexer": "bigname", "items": [ { "name": "$ethereum.eth", "displayName": "$ethereum.eth", "namespace": "ens", "node": "0x19dcf664810b0725d51d9e71dd02c5be734f14803394fb2d5574dfb8efd402a7", "status": "active", "authority": "ensV1", "owner": "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045", "manager": "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045", "registeredAt": "1715951615n", "createdAt": "1659177236n", "expiresAt": "1815916415n", "graceEndsAt": "1818335615n", "expiryReason": null, "ensV1": { "resolver": { "chainId": 1, "address": "0x231b0Ee14048e9dCcD1d247744d114a4EB5E8E63" }, "expiresAt": "1810559615n", "wrapperState": "locked", "wrapperExpiresAt": "1818335615n", "wrapperFuses": 196609 }, "relations": [ "owner", "manager" ], "isPrimary": false, "migratedAt": null, "recordCount": null, "subnameCount": null }, { "name": "$tmnt.eth", "displayName": "$tmnt.eth", "namespace": "ens", "node": "0x0b6f1e9f5b9f267f7d9b57fad7971998a4710835d0c9007a02edc5d0f59c7960", "status": "active", "authority": "ensV1", "owner": "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045", "manager": "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045", "registeredAt": "1750871663n", "createdAt": "1703971235n", "expiresAt": "1819300463n", "graceEndsAt": "1821719663n", "expiryReason": null, "ensV1": { "resolver": { "chainId": 1, "address": "0x231b0Ee14048e9dCcD1d247744d114a4EB5E8E63" }, "expiresAt": "1813943663n", "wrapperState": "emancipated", "wrapperExpiresAt": "1821719663n", "wrapperFuses": 196608 }, "relations": [ "owner", "manager" ], "isPrimary": false, "migratedAt": null, "recordCount": null, "subnameCount": null }, { "name": "0x2cd.eth", "displayName": "0x2cd.eth", "namespace": "ens", "node": "0x017e683f998ef30ad2d628fa36ade474ef6f40aa8fa042d87e41730273a7145c", "status": "active", "authority": "ensV1", "owner": "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045", "manager": "0x32869721EF080442ec128FC1ddb6673006bc5aa9", "registeredAt": "1651234372n", "createdAt": "1651234372n", "expiresAt": "1845932884n", "graceEndsAt": "1848352084n", "expiryReason": null, "ensV1": { "resolver": { "chainId": 1, "address": "0x4976fb03C32e5B8cfe2b6cCB31c09Ba78EBaBa41" }, "expiresAt": "1840576084n", "wrapperState": "unwrapped", "wrapperExpiresAt": null, "wrapperFuses": null }, "relations": [ "owner" ], "isPrimary": false, "migratedAt": null, "recordCount": null, "subnameCount": null } ], "cursor": "7b2276657273696f6e223a312c22736f7274223a226e616d65222c2266696c74657273223a7b2261646472657373223a22307864386461366266323639363461663964376565643965303365353334313564333761613936303435222c22617574686f72697479223a22222c22646564757065223a226e616d65222c2269735f6d69677261746564223a22222c226e616d657370616365223a22222c226f72646572223a22617363222c2271223a22222c2272656c6174696f6e223a22227d2c226c6173745f6974656d223a7b226c6f676963616c5f6e616d655f6964223a22656e733a307830313765363833663939386566333061643264363238666133366164653437346566366634306161386661303432643837653431373330323733613731343563222c227265736f757263655f6964223a2232643539636630332d613131382d353862372d623264382d373033646561653936316336222c22736f72745f6b696e64223a226e616d65222c22736f72745f76616c7565223a2230783263642e657468227d2c22736e617073686f74223a6e756c6c7d", "hasMore": true, "totalCount": 90 } ``` ## See also [#see-also] - `paginate` from `@ensforge/sdk/indexer` to walk every page # indexer.getNamespace > For the complete documentation index, see [llms.txt](https://ensforge.com/llms.txt). Reads what the indexer serves for a namespace: its networks and which features are complete. Options, result, errors and examples for indexer.getNamespace. Source: https://ensforge.com/docs/reference/sdk/indexer/get-namespace Reads what the indexer serves for a namespace: its networks and which features are complete. ## When to use [#when-to-use] Use to decide which features to show, e.g. hide verified records where they are unsupported. ## Signature [#signature] ```ts function getNamespace( client: Like, options?: getNamespace.Options, ): Promise ``` Call it as `ens.indexer.getNamespace(options)` on a client, or `Actions.indexer.getNamespace(client, options)`. `indexer.getNamespace.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 | | --- | --- | --- | --- | | `namespace` | `Namespace` | `"ens"` | | Also takes the [read options](/docs/reference/sdk/client#read-options). ## Returns [#returns] Resolves to `Result | null`. The namespace's coverage, or `null` when the indexer does not know it. ## Errors [#errors] | Error | Codes | When | | --- | --- | --- | | [`NotFoundError`](/docs/reference/errors/not-found-error) | [`INDEXER_NOT_FOUND`](/docs/reference/errors/INDEXER_NOT_FOUND) | with `strict: true` when the indexer does not know the namespace. | | [`ConfigError`](/docs/reference/errors/config-error) | [`INDEXER_NOT_CONFIGURED`](/docs/reference/errors/INDEXER_NOT_CONFIGURED) | the client has no indexer. | | [`IndexerError`](/docs/reference/errors/indexer-error) | [`INDEXER_UNSUPPORTED`](/docs/reference/errors/INDEXER_UNSUPPORTED) | the indexer does not serve the query or its namespace. | | [`IndexerError`](/docs/reference/errors/indexer-error) | [`INDEXER_UNAVAILABLE`](/docs/reference/errors/INDEXER_UNAVAILABLE), [`INDEXER_RATE_LIMITED`](/docs/reference/errors/INDEXER_RATE_LIMITED), [`INDEXER_BEHIND`](/docs/reference/errors/INDEXER_BEHIND), [`INDEXER_REQUEST_REJECTED`](/docs/reference/errors/INDEXER_REQUEST_REJECTED), [`INDEXER_RESPONSE_INVALID`](/docs/reference/errors/INDEXER_RESPONSE_INVALID) | the indexer is unavailable, rate limiting, behind, rejects the request or answers unexpectedly. | 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 ENS coverage" const ens_ = await ens.indexer.getNamespace() ``` ```ts title="Reading Basenames coverage with a standalone call" import { Actions } from "@ensforge/sdk" const basenames = await Actions.indexer.getNamespace(ens, { namespace: "basenames" }) ``` ```ts title="Reading coverage in an Effect program" import { Actions } from "@ensforge/sdk/effect" const info = yield* Actions.indexer.getNamespace(ens, { namespace: "ens" }) ``` ## Example response [#example-response] Recorded from Ethereum mainnet on 2026-11-18 at block 26443964. Values change as the chain does. ```ts await ens.indexer.getNamespace({ namespace: "ens" }) ``` ```json { "namespace": "ens", "capabilities": { "name_history": "full", "name_profile": "full", "subnames": "full", "verified_primary_name": "full", "verified_records": "full" }, "networks": [ { "network": "ethereum", "chainId": 1, "protocol": "ensV2", "sinceBlock": "26183742n" } ], "asOf": null, "snapshots": {}, "asOfToken": null, "completeness": "full", "unsupportedReason": null, "unsupportedFields": [], "origin": null, "indexer": "bigname" } ``` # indexer.getPermissions > For the complete documentation index, see [llms.txt](https://ensforge.com/llms.txt). Lists who can do what over a name, a registration, an account or an ENSv2 registry. Options, result, errors and examples for indexer.getPermissions. Source: https://ensforge.com/docs/reference/sdk/indexer/get-permissions Lists who can do what over a name, a registration, an account or an ENSv2 registry. ## When to use [#when-to-use] Use to show a name's permission table, or every grant an account holds. ## Details [#details] - Pass exactly one of `name`, `registrationId`, `address` or `registry`. - Powers use the indexer's vocabulary (`set_resolver`, `admin_renew`, …); `includeLineage` explains how each was obtained. - Surfaces the indexer cannot list (e.g. operator approvals) are reported through `completeness` and `unsupportedReason`. ## Signature [#signature] ```ts function getPermissions( client: Like, options: getPermissions.Options, ): Promise ``` Call it as `ens.indexer.getPermissions(options)` on a client, or `Actions.indexer.getPermissions(client, options)`. `indexer.getPermissions.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 | | --- | --- | --- | --- | | `limit` | `number` | | Rows per page, 1–200. @default 50 | | `cursor` | `string` | | The previous page's `cursor`. | | `includeTotal` | `boolean` | | Count every row (`totalCount`); slower. | | `namespace` | `Namespace` | | Only grants in this namespace. | | `includeLineage` | `boolean` | | Include how each grant was obtained. | | `name` | `string` | | Permissions over this name. | | `registrationId` | `string` | | Permissions over this registration (an indexer handle). | | `address` | `string` | | Grants this account holds. | | `registry` | `{ readonly address: string; readonly chainId?: number \| undefined }` | | Root grants of this ENSv2 registry (on the client's chain unless `chainId` is set). | Also takes the [read options](/docs/reference/sdk/client#read-options). ## Returns [#returns] Resolves to `Page`. One page of grants. ## 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_RECORD_VALUE`](/docs/reference/errors/INVALID_RECORD_VALUE) | invalid input. | | [`ConfigError`](/docs/reference/errors/config-error) | [`INDEXER_NOT_CONFIGURED`](/docs/reference/errors/INDEXER_NOT_CONFIGURED) | the client has no indexer. | | [`IndexerError`](/docs/reference/errors/indexer-error) | [`INDEXER_UNSUPPORTED`](/docs/reference/errors/INDEXER_UNSUPPORTED) | the indexer does not serve the query or its namespace. | | [`IndexerError`](/docs/reference/errors/indexer-error) | [`INDEXER_UNAVAILABLE`](/docs/reference/errors/INDEXER_UNAVAILABLE), [`INDEXER_RATE_LIMITED`](/docs/reference/errors/INDEXER_RATE_LIMITED), [`INDEXER_BEHIND`](/docs/reference/errors/INDEXER_BEHIND), [`INDEXER_REQUEST_REJECTED`](/docs/reference/errors/INDEXER_REQUEST_REJECTED), [`INDEXER_RESPONSE_INVALID`](/docs/reference/errors/INDEXER_RESPONSE_INVALID) | the indexer is unavailable, rate limiting, behind, rejects the request or answers unexpectedly. | 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="Listing a name's permissions" const page = await ens.indexer.getPermissions({ name: "nick.eth" }) ``` ```ts title="Listing an account's grants with a standalone call" import { Actions } from "@ensforge/sdk" const page = await Actions.indexer.getPermissions(ens, { address }) ``` ```ts title="Listing a registry's root grants in an Effect program" import { Actions } from "@ensforge/sdk/effect" const page = yield* Actions.indexer.getPermissions(ens, { registry: { address: registry } }) ``` ## Example response [#example-response] Recorded from Ethereum mainnet on 2026-11-18 at block 26443964. Values change as the chain does. ```ts await ens.indexer.getPermissions({ name: "ens.eth", limit: 3 }) ``` ```json { "asOf": { "chainId": 1, "blockNumber": "26443964n", "blockHash": "0xe75c58ea2f28bd7c6cc53c28a5ab4fc02023f3563661f0a7236a36b779e3ac86", "timestamp": "1795029143n" }, "snapshots": { "1": { "chainId": 1, "blockNumber": "26443964n", "blockHash": "0xe75c58ea2f28bd7c6cc53c28a5ab4fc02023f3563661f0a7236a36b779e3ac86", "timestamp": "1795029143n" } }, "asOfToken": null, "completeness": "partial", "unsupportedReason": "permissions_partially_listed", "unsupportedFields": [], "origin": null, "indexer": "bigname", "items": [ { "address": "0x2d2e339c93dA91682Db720ee73e3c8F854f5F246", "name": "ens.eth", "registrationId": "4f225413-df3a-50b3-832a-1b91e29b6a9c", "powers": [ "resolver_control" ], "scope": "resolver", "relation": null, "wrapperState": null, "lineage": null }, { "address": "0x2d2e339c93dA91682Db720ee73e3c8F854f5F246", "name": "ens.eth", "registrationId": "4f225413-df3a-50b3-832a-1b91e29b6a9c", "powers": [ "registration_control" ], "scope": "registration", "relation": null, "wrapperState": null, "lineage": null } ], "cursor": null, "hasMore": false, "totalCount": null } ``` ## See also [#see-also] - [`permission.get`](/docs/reference/sdk/permission/get) for the on-chain check # indexer.getPrimaryName > For the complete documentation index, see [llms.txt](https://ensforge.com/llms.txt). Reads an address's primary name from the indexer, verified on-chain when the indexer can. Options, result, errors and examples for indexer.getPrimaryName. Source: https://ensforge.com/docs/reference/sdk/indexer/get-primary-name Reads an address's primary name from the indexer, verified on-chain when the indexer can. ## When to use [#when-to-use] Use to label many accounts quickly; for an authoritative read, use `primaryName.get`. ## Details [#details] - `name` is the verified answer when there is one, otherwise the indexed one; `source` says which. - Every answer the indexer gave is in `answers`, with its status. ## Signature [#signature] ```ts function getPrimaryName( client: Like, options: getPrimaryName.Options, ): Promise ``` Call it as `ens.indexer.getPrimaryName(options)` on a client, or `Actions.indexer.getPrimaryName(client, options)`. `indexer.getPrimaryName.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 | | --- | --- | --- | --- | | `namespace` | `Namespace` | | Only this naming system; every namespace the indexer serves when omitted. | | `source` | `"indexed" \| "verified"` | | Both, verified first, when omitted. | | `address` (required) | `string` | | The address, all lowercase or checksummed. | | `coin` | `CoinType.Input` | | Chain of the primary name, as a coin type. @default 60 (Ethereum) | Also takes the [read options](/docs/reference/sdk/client#read-options). ## Returns [#returns] Resolves to `Result`. The primary name (`null` when none) and every answer. ## Errors [#errors] | Error | Codes | When | | --- | --- | --- | | [`InvalidInputError`](/docs/reference/errors/invalid-input-error) | [`INVALID_ADDRESS`](/docs/reference/errors/INVALID_ADDRESS), [`INVALID_COIN_TYPE`](/docs/reference/errors/INVALID_COIN_TYPE) | invalid input. | | [`ConfigError`](/docs/reference/errors/config-error) | [`INDEXER_NOT_CONFIGURED`](/docs/reference/errors/INDEXER_NOT_CONFIGURED) | the client has no indexer. | | [`IndexerError`](/docs/reference/errors/indexer-error) | [`INDEXER_UNSUPPORTED`](/docs/reference/errors/INDEXER_UNSUPPORTED) | the indexer does not serve the query or its namespace. | | [`IndexerError`](/docs/reference/errors/indexer-error) | [`INDEXER_UNAVAILABLE`](/docs/reference/errors/INDEXER_UNAVAILABLE), [`INDEXER_RATE_LIMITED`](/docs/reference/errors/INDEXER_RATE_LIMITED), [`INDEXER_BEHIND`](/docs/reference/errors/INDEXER_BEHIND), [`INDEXER_REQUEST_REJECTED`](/docs/reference/errors/INDEXER_REQUEST_REJECTED), [`INDEXER_RESPONSE_INVALID`](/docs/reference/errors/INDEXER_RESPONSE_INVALID) | the indexer is unavailable, rate limiting, behind, rejects the request or answers unexpectedly. | 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 primary name" const { name } = await ens.indexer.getPrimaryName({ address: "0xb8c2…" }) ``` ```ts title="Reading a Base primary name with a standalone call" import { Actions } from "@ensforge/sdk" const result = await Actions.indexer.getPrimaryName(ens, { address, coin: { chainId: 8453 } }) ``` ```ts title="Reading a primary name in an Effect program" import { Actions } from "@ensforge/sdk/effect" const { name } = yield* Actions.indexer.getPrimaryName(ens, { address }) ``` ## Example response [#example-response] Recorded from Ethereum mainnet on 2026-11-18 at block 26443964. Values change as the chain does. ```ts await ens.indexer.getPrimaryName({ address: "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045" }) ``` ```json { "address": "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045", "coinType": 60, "namespace": "ens", "name": "vitalik.eth", "source": "verified", "answers": [ { "source": "indexed", "status": "notFound", "name": null, "reason": null }, { "source": "verified", "status": "ok", "name": "vitalik.eth", "reason": null } ], "asOf": { "chainId": 1, "blockNumber": "26443964n", "blockHash": "0xe75c58ea2f28bd7c6cc53c28a5ab4fc02023f3563661f0a7236a36b779e3ac86", "timestamp": "1795029143n" }, "snapshots": { "1": { "chainId": 1, "blockNumber": "26443964n", "blockHash": "0xe75c58ea2f28bd7c6cc53c28a5ab4fc02023f3563661f0a7236a36b779e3ac86", "timestamp": "1795029143n" } }, "asOfToken": "7b22657468657265756d223a7b22626c6f636b5f68617368223a22307865373563353865613266323862643763366363353363323861356162346663303230323366333536333636316630613732333661333662373739653361633836222c22626c6f636b5f6e756d626572223a32363434333936342c22636861696e5f6964223a22657468657265756d2d6d61696e6e6574222c2274696d657374616d70223a22323032362d31312d31385431393a31323a32335a227d7d", "completeness": "full", "unsupportedReason": null, "unsupportedFields": [], "origin": null, "indexer": "bigname" } ``` ## See also [#see-also] - [`primaryName.get`](/docs/reference/sdk/primary-name/get) for the on-chain read # indexer.getRecords > For the complete documentation index, see [llms.txt](https://ensforge.com/llms.txt). Reads a name's records and its record inventory from the indexer. Parameters, return value, errors and examples for indexer.getRecords in @ensforge/sdk. Source: https://ensforge.com/docs/reference/sdk/indexer/get-records Reads a name's records and its record inventory from the indexer. ## When to use [#when-to-use] Use to show a profile, or to learn every record key a name has ever set (the inventory). ## Details [#details] - Without `keys`, reads the keys in the name's inventory; `values: false` returns only the inventory. - Keys are record keys: `avatar` (a text key), `text:url`, `addr:60` or `contenthash`. - `source: "verified"` reads the values on-chain through the indexer; `auto` falls back to it. - `resolver` reads the records the name has on another resolver (e.g. its ENSv1 resolver). ## Signature [#signature] ```ts function getRecords( client: Like, options: getRecords.Options, ): Promise ``` Call it as `ens.indexer.getRecords(options)` on a client, or `Actions.indexer.getRecords(client, options)`. `indexer.getRecords.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 | | --- | --- | --- | --- | | `at` | `{ readonly token: string } \| { readonly timestamp: bigint \| Date }` | | Read at a snapshot: an earlier answer's `asOfToken`, or a time. | | `finality` | `"latest" \| "safe" \| "finalized"` | `"latest"` | How settled the data must be: `latest`, `safe` or `finalized`. | | `name` (required) | `string` | | | | `keys` | `readonly string[]` | | Record keys (`avatar`, `text:url`, `addr:60`, `contenthash`); the inventory's when omitted. | | `values` | `boolean` | | `false` returns only the inventory, without values. @default true | | `source` | `"indexed" \| "verified" \| "auto"` | `"indexed"` | | | `namespace` | `Namespace` | "basenames" for `*.base.eth`, otherwise "ens" | Namespace of the name. | | `resolver` | `{ readonly address: string; readonly chainId?: number \| undefined }` | | Read from this resolver (on the client's chain unless `chainId` is set). | Also takes the [read options](/docs/reference/sdk/client#read-options). ## Returns [#returns] Resolves to `Result | null`. The records, or `null` when the indexer does not know the name. ## 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) | [`INDEXER_NOT_FOUND`](/docs/reference/errors/INDEXER_NOT_FOUND) | with `strict: true` when the indexer has no such name. | | [`ConfigError`](/docs/reference/errors/config-error) | [`INDEXER_NOT_CONFIGURED`](/docs/reference/errors/INDEXER_NOT_CONFIGURED) | the client has no indexer. | | [`IndexerError`](/docs/reference/errors/indexer-error) | [`INDEXER_UNSUPPORTED`](/docs/reference/errors/INDEXER_UNSUPPORTED) | the indexer does not serve the query or its namespace. | | [`IndexerError`](/docs/reference/errors/indexer-error) | [`INDEXER_UNAVAILABLE`](/docs/reference/errors/INDEXER_UNAVAILABLE), [`INDEXER_RATE_LIMITED`](/docs/reference/errors/INDEXER_RATE_LIMITED), [`INDEXER_BEHIND`](/docs/reference/errors/INDEXER_BEHIND), [`INDEXER_REQUEST_REJECTED`](/docs/reference/errors/INDEXER_REQUEST_REJECTED), [`INDEXER_RESPONSE_INVALID`](/docs/reference/errors/INDEXER_RESPONSE_INVALID) | the indexer is unavailable, rate limiting, behind, rejects the request or answers unexpectedly. | 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 profile" const records = await ens.indexer.getRecords({ name: "nick.eth" }) ``` ```ts title="Reading the inventory with a standalone call" import { Actions } from "@ensforge/sdk" const records = await Actions.indexer.getRecords(ens, { name: "nick.eth", values: false }) const keys = records?.inventory?.keys ?? [] ``` ```ts title="Reading chosen records in an Effect program" import { Actions } from "@ensforge/sdk/effect" const records = yield* Actions.indexer.getRecords(ens, { name: "nick.eth", keys: ["avatar", "addr:60"] }) ``` ## Example response [#example-response] Recorded from Ethereum mainnet on 2026-11-18 at block 26443964. Values change as the chain does. ```ts await ens.indexer.getRecords({ name: "ens.eth", namespace: "ens" }) ``` ```json { "namespace": "ens", "resolver": { "chainId": 1, "address": "0x4976fb03C32e5B8cfe2b6cCB31c09Ba78EBaBa41" }, "texts": { "avatar": "https://i.imgur.com/ga6y0c0.jpg", "com.github": "ensdomains", "com.twitter": "ensdomains", "snapshot": "ipns://storage.snapshot.page/registry/0xb6E040C9ECAaE172a89bD561c5F73e1C48d28cd9/ens.eth", "url": "https://ens.domains/" }, "addresses": { "60": "0xfe89cc7abb2c4183683ab71653c4cdc9b02d44b7" }, "contentHash": "0xe40101fa011b20f5909b5286d9279a1f6a23d5155ddd72bb0f28f56b6b82c32de54a6529e6b1b0", "answers": { "addr:60": { "status": "ok", "value": "0xfe89cc7abb2c4183683ab71653c4cdc9b02d44b7", "reason": null }, "contenthash": { "status": "ok", "value": "0xe40101fa011b20f5909b5286d9279a1f6a23d5155ddd72bb0f28f56b6b82c32de54a6529e6b1b0", "reason": null }, "text:avatar": { "status": "ok", "value": "https://i.imgur.com/ga6y0c0.jpg", "reason": null }, "text:com.github": { "status": "ok", "value": "ensdomains", "reason": null }, "text:com.twitter": { "status": "ok", "value": "ensdomains", "reason": null }, "text:snapshot": { "status": "ok", "value": "ipns://storage.snapshot.page/registry/0xb6E040C9ECAaE172a89bD561c5F73e1C48d28cd9/ens.eth", "reason": null }, "text:url": { "status": "ok", "value": "https://ens.domains/", "reason": null } }, "inventory": { "keys": [ "addr:60", "contenthash", "text:avatar", "text:com.github", "text:com.twitter", "text:snapshot", "text:url" ], "unsetKeys": [], "unsupportedKeys": [] }, "asOf": { "chainId": 1, "blockNumber": "26443964n", "blockHash": "0xe75c58ea2f28bd7c6cc53c28a5ab4fc02023f3563661f0a7236a36b779e3ac86", "timestamp": "1795029143n" }, "snapshots": { "1": { "chainId": 1, "blockNumber": "26443964n", "blockHash": "0xe75c58ea2f28bd7c6cc53c28a5ab4fc02023f3563661f0a7236a36b779e3ac86", "timestamp": "1795029143n" } }, "asOfToken": "7b22657468657265756d223a7b22626c6f636b5f68617368223a22307865373563353865613266323862643763366363353363323861356162346663303230323366333536333636316630613732333661333662373739653361633836222c22626c6f636b5f6e756d626572223a32363434333936342c22636861696e5f6964223a22657468657265756d2d6d61696e6e6574222c2274696d657374616d70223a22323032362d31312d31385431393a31323a32335a227d7d", "completeness": "full", "unsupportedReason": null, "unsupportedFields": [], "origin": "indexed", "indexer": "bigname" } ``` ## See also [#see-also] - [`record.get`](/docs/reference/sdk/record/get) for the on-chain read # indexer.getRegistryLabels > For the complete documentation index, see [llms.txt](https://ensforge.com/llms.txt). Lists the labels of an ENSv2 registry, optionally only those an address holds or does not hold. Options, errors and examples for indexer.getRegistryLabels. Source: https://ensforge.com/docs/reference/sdk/indexer/get-registry-labels Lists the labels of an ENSv2 registry, optionally only those an address holds or does not hold. ## When to use [#when-to-use] Use to browse a registry's names, e.g. the subnames recreated during migration. ## Details [#details] - `owner` and `excludeOwner` cannot be combined. ## Signature [#signature] ```ts function getRegistryLabels( client: Like, options: getRegistryLabels.Options, ): Promise ``` Call it as `ens.indexer.getRegistryLabels(options)` on a client, or `Actions.indexer.getRegistryLabels(client, options)`. `indexer.getRegistryLabels.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 | | --- | --- | --- | --- | | `limit` | `number` | | Rows per page, 1–200. @default 50 | | `cursor` | `string` | | The previous page's `cursor`. | | `includeTotal` | `boolean` | | Count every row (`totalCount`); slower. | | `address` (required) | `string` | | Contract address. | | `chainId` | `number` | | Chain of the contract. @default the client's chain | | `owner` | `string` | | Only labels this address holds. | | `excludeOwner` | `string` | | Only labels this address does not hold. | Also takes the [read options](/docs/reference/sdk/client#read-options). ## Returns [#returns] Resolves to `Page`. One page of labels. ## Errors [#errors] | Error | Codes | When | | --- | --- | --- | | [`InvalidInputError`](/docs/reference/errors/invalid-input-error) | [`INVALID_ADDRESS`](/docs/reference/errors/INVALID_ADDRESS) | an invalid address. | | [`ConfigError`](/docs/reference/errors/config-error) | [`INDEXER_NOT_CONFIGURED`](/docs/reference/errors/INDEXER_NOT_CONFIGURED) | the client has no indexer. | | [`IndexerError`](/docs/reference/errors/indexer-error) | [`INDEXER_UNSUPPORTED`](/docs/reference/errors/INDEXER_UNSUPPORTED) | the indexer does not serve the query or its namespace. | | [`IndexerError`](/docs/reference/errors/indexer-error) | [`INDEXER_UNAVAILABLE`](/docs/reference/errors/INDEXER_UNAVAILABLE), [`INDEXER_RATE_LIMITED`](/docs/reference/errors/INDEXER_RATE_LIMITED), [`INDEXER_BEHIND`](/docs/reference/errors/INDEXER_BEHIND), [`INDEXER_REQUEST_REJECTED`](/docs/reference/errors/INDEXER_REQUEST_REJECTED), [`INDEXER_RESPONSE_INVALID`](/docs/reference/errors/INDEXER_RESPONSE_INVALID) | the indexer is unavailable, rate limiting, behind, rejects the request or answers unexpectedly. | 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="Listing a registry's labels" const page = await ens.indexer.getRegistryLabels({ address: "0x02ca…" }) ``` ```ts title="Listing labels an address holds with a standalone call" import { Actions } from "@ensforge/sdk" const page = await Actions.indexer.getRegistryLabels(ens, { address, owner: account }) ``` ```ts title="Listing a registry's labels in an Effect program" import { Actions } from "@ensforge/sdk/effect" const page = yield* Actions.indexer.getRegistryLabels(ens, { address, limit: 200 }) ``` ## Example response [#example-response] Recorded from Ethereum mainnet on 2026-11-18 at block 26443964. Values change as the chain does. ```ts await ens.indexer.getRegistryLabels({ address: "0x00000000000C2E074eC69A0dFb2997BA6C7d2e1e", chainId: 1, limit: 3 }) ``` ```json { "asOf": { "chainId": 1, "blockNumber": "26443964n", "blockHash": "0xe75c58ea2f28bd7c6cc53c28a5ab4fc02023f3563661f0a7236a36b779e3ac86", "timestamp": "1795029143n" }, "snapshots": { "1": { "chainId": 1, "blockNumber": "26443964n", "blockHash": "0xe75c58ea2f28bd7c6cc53c28a5ab4fc02023f3563661f0a7236a36b779e3ac86", "timestamp": "1795029143n" } }, "asOfToken": null, "completeness": "full", "unsupportedReason": null, "unsupportedFields": [], "origin": null, "indexer": "bigname", "items": [], "cursor": null, "hasMore": false, "totalCount": 0 } ``` # indexer.getRegistry > For the complete documentation index, see [llms.txt](https://ensforge.com/llms.txt). Reads an ENSv2 registry: the name it serves, its parent registry, when it was created and its counts. Options, errors and examples for indexer.getRegistry. Source: https://ensforge.com/docs/reference/sdk/indexer/get-registry Reads an ENSv2 registry: the name it serves, its parent registry, when it was created and its counts. ## When to use [#when-to-use] Use to inspect a registry found through a name's `subregistry`, e.g. in an explorer. ## Details [#details] - `includeCounts` adds the number of labels, roles and events. ## Signature [#signature] ```ts function getRegistry( client: Like, options: getRegistry.Options, ): Promise ``` Call it as `ens.indexer.getRegistry(options)` on a client, or `Actions.indexer.getRegistry(client, options)`. `indexer.getRegistry.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 | | --- | --- | --- | --- | | `at` | `{ readonly token: string } \| { readonly timestamp: bigint \| Date }` | | Read at a snapshot: an earlier answer's `asOfToken`, or a time. | | `finality` | `"latest" \| "safe" \| "finalized"` | `"latest"` | How settled the data must be: `latest`, `safe` or `finalized`. | | `address` (required) | `string` | | Contract address. | | `chainId` | `number` | | Chain of the contract. @default the client's chain | | `includeCounts` | `boolean` | | Include label, role and event counts. | Also takes the [read options](/docs/reference/sdk/client#read-options). ## Returns [#returns] Resolves to `Result | null`. The registry, or `null` when the indexer does not know it. ## Errors [#errors] | Error | Codes | When | | --- | --- | --- | | [`InvalidInputError`](/docs/reference/errors/invalid-input-error) | [`INVALID_ADDRESS`](/docs/reference/errors/INVALID_ADDRESS) | an invalid address. | | [`NotFoundError`](/docs/reference/errors/not-found-error) | [`INDEXER_NOT_FOUND`](/docs/reference/errors/INDEXER_NOT_FOUND) | with `strict: true` when the indexer does not know the contract. | | [`ConfigError`](/docs/reference/errors/config-error) | [`INDEXER_NOT_CONFIGURED`](/docs/reference/errors/INDEXER_NOT_CONFIGURED) | the client has no indexer. | | [`IndexerError`](/docs/reference/errors/indexer-error) | [`INDEXER_UNSUPPORTED`](/docs/reference/errors/INDEXER_UNSUPPORTED) | the indexer does not serve the query or its namespace. | | [`IndexerError`](/docs/reference/errors/indexer-error) | [`INDEXER_UNAVAILABLE`](/docs/reference/errors/INDEXER_UNAVAILABLE), [`INDEXER_RATE_LIMITED`](/docs/reference/errors/INDEXER_RATE_LIMITED), [`INDEXER_BEHIND`](/docs/reference/errors/INDEXER_BEHIND), [`INDEXER_REQUEST_REJECTED`](/docs/reference/errors/INDEXER_REQUEST_REJECTED), [`INDEXER_RESPONSE_INVALID`](/docs/reference/errors/INDEXER_RESPONSE_INVALID) | the indexer is unavailable, rate limiting, behind, rejects the request or answers unexpectedly. | 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 registry" const registry = await ens.indexer.getRegistry({ address: "0x02ca…" }) ``` ```ts title="Reading a registry with counts with a standalone call" import { Actions } from "@ensforge/sdk" const registry = await Actions.indexer.getRegistry(ens, { address, includeCounts: true }) ``` ```ts title="Reading a registry in an Effect program" import { Actions } from "@ensforge/sdk/effect" const registry = yield* Actions.indexer.getRegistry(ens, { address }) ``` ## Example response [#example-response] Recorded from Ethereum mainnet on 2026-11-18 at block 26443964. Values change as the chain does. ```ts await ens.indexer.getRegistry({ address: "0x00000000000C2E074eC69A0dFb2997BA6C7d2e1e", chainId: 1 }) ``` ```json { "chainId": 1, "address": "0x00000000000C2E074eC69A0dFb2997BA6C7d2e1e", "name": "wh1tehat.eth", "parent": { "chainId": 1, "address": "0xf60aba43E1f7F3DAB1186Ff03B561401C9Df85E2" }, "createdAt": "1794139355n", "createdBlockNumber": "26370025n", "createdTransactionHash": "0xcd43345f1d89446fcf0f8d088a8b0d2f8d15e5a188fadee5000d4781c3ae7669", "counts": { "labels": null, "roles": null, "events": null }, "referencedBy": [ "wh1tehat.eth" ], "asOf": { "chainId": 1, "blockNumber": "26443964n", "blockHash": "0xe75c58ea2f28bd7c6cc53c28a5ab4fc02023f3563661f0a7236a36b779e3ac86", "timestamp": "1795029143n" }, "snapshots": { "1": { "chainId": 1, "blockNumber": "26443964n", "blockHash": "0xe75c58ea2f28bd7c6cc53c28a5ab4fc02023f3563661f0a7236a36b779e3ac86", "timestamp": "1795029143n" } }, "asOfToken": "7b22657468657265756d223a7b22626c6f636b5f68617368223a22307865373563353865613266323862643763366363353363323861356162346663303230323366333536333636316630613732333661333662373739653361633836222c22626c6f636b5f6e756d626572223a32363434333936342c22636861696e5f6964223a22657468657265756d2d6d61696e6e6574222c2274696d657374616d70223a22323032362d31312d31385431393a31323a32335a227d7d", "completeness": "full", "unsupportedReason": null, "unsupportedFields": [], "origin": null, "indexer": "bigname" } ``` ## See also [#see-also] - [`registry.get`](/docs/reference/sdk/registry/get) for the on-chain read # indexer.getResolverLinks > For the complete documentation index, see [llms.txt](https://ensforge.com/llms.txt). Lists the names linked to record sets on an ENSv2 resolver. Parameters, return value, errors and examples for indexer.getResolverLinks in @ensforge/sdk. Source: https://ensforge.com/docs/reference/sdk/indexer/get-resolver-links Lists the names linked to record sets on an ENSv2 resolver. ## When to use [#when-to-use] Use to see which names share a resolver's record sets, e.g. after `record.clear` relinked one. ## Details [#details] - Each link says whether it is the resolver's default record set (`isDefault`). ## Signature [#signature] ```ts function getResolverLinks( client: Like, options: getResolverLinks.Options, ): Promise ``` Call it as `ens.indexer.getResolverLinks(options)` on a client, or `Actions.indexer.getResolverLinks(client, options)`. `indexer.getResolverLinks.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 | | --- | --- | --- | --- | | `at` | `{ readonly token: string } \| { readonly timestamp: bigint \| Date }` | | Read at a snapshot: an earlier answer's `asOfToken`, or a time. | | `finality` | `"latest" \| "safe" \| "finalized"` | `"latest"` | How settled the data must be: `latest`, `safe` or `finalized`. | | `limit` | `number` | | Rows per page, 1–200. @default 50 | | `cursor` | `string` | | The previous page's `cursor`. | | `includeTotal` | `boolean` | | Count every row (`totalCount`); slower. | | `address` (required) | `string` | | Contract address. | | `chainId` | `number` | | Chain of the contract. @default the client's chain | Also takes the [read options](/docs/reference/sdk/client#read-options). ## Returns [#returns] Resolves to `Page`. One page of links. ## Errors [#errors] | Error | Codes | When | | --- | --- | --- | | [`InvalidInputError`](/docs/reference/errors/invalid-input-error) | [`INVALID_ADDRESS`](/docs/reference/errors/INVALID_ADDRESS) | an invalid address. | | [`ConfigError`](/docs/reference/errors/config-error) | [`INDEXER_NOT_CONFIGURED`](/docs/reference/errors/INDEXER_NOT_CONFIGURED) | the client has no indexer. | | [`IndexerError`](/docs/reference/errors/indexer-error) | [`INDEXER_UNSUPPORTED`](/docs/reference/errors/INDEXER_UNSUPPORTED) | the indexer does not serve the query or its namespace. | | [`IndexerError`](/docs/reference/errors/indexer-error) | [`INDEXER_UNAVAILABLE`](/docs/reference/errors/INDEXER_UNAVAILABLE), [`INDEXER_RATE_LIMITED`](/docs/reference/errors/INDEXER_RATE_LIMITED), [`INDEXER_BEHIND`](/docs/reference/errors/INDEXER_BEHIND), [`INDEXER_REQUEST_REJECTED`](/docs/reference/errors/INDEXER_REQUEST_REJECTED), [`INDEXER_RESPONSE_INVALID`](/docs/reference/errors/INDEXER_RESPONSE_INVALID) | the indexer is unavailable, rate limiting, behind, rejects the request or answers unexpectedly. | 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="Listing a resolver's links" const page = await ens.indexer.getResolverLinks({ address: "0xF4f1…" }) ``` ```ts title="Listing links with a standalone call" import { Actions } from "@ensforge/sdk" const page = await Actions.indexer.getResolverLinks(ens, { address }) ``` ```ts title="Listing links in an Effect program" import { Actions } from "@ensforge/sdk/effect" const page = yield* Actions.indexer.getResolverLinks(ens, { address, limit: 100 }) ``` ## Example response [#example-response] Recorded from Ethereum mainnet on 2026-11-18 at block 26443964. Values change as the chain does. ```ts await ens.indexer.getResolverLinks({ address: "0xF29100983E058B709F3D539b0c765937B804AC15", chainId: 1, limit: 3 }) ``` ```json { "asOf": { "chainId": 1, "blockNumber": "26443964n", "blockHash": "0xe75c58ea2f28bd7c6cc53c28a5ab4fc02023f3563661f0a7236a36b779e3ac86", "timestamp": "1795029143n" }, "snapshots": { "1": { "chainId": 1, "blockNumber": "26443964n", "blockHash": "0xe75c58ea2f28bd7c6cc53c28a5ab4fc02023f3563661f0a7236a36b779e3ac86", "timestamp": "1795029143n" } }, "asOfToken": "7b22657468657265756d223a7b22626c6f636b5f68617368223a22307865373563353865613266323862643763366363353363323861356162346663303230323366333536333636316630613732333661333662373739653361633836222c22626c6f636b5f6e756d626572223a32363434333936342c22636861696e5f6964223a22657468657265756d2d6d61696e6e6574222c2274696d657374616d70223a22323032362d31312d31385431393a31323a32335a227d7d", "completeness": "unsupported", "unsupportedReason": "record_links_not_applicable", "unsupportedFields": [ "links" ], "origin": null, "indexer": "bigname", "items": [], "cursor": null, "hasMore": false, "totalCount": null } ``` # indexer.getResolverRoles > For the complete documentation index, see [llms.txt](https://ensforge.com/llms.txt). Lists the role grants on an ENSv2 resolver. Parameters, return value, errors and examples for indexer.getResolverRoles in @ensforge/sdk. Source: https://ensforge.com/docs/reference/sdk/indexer/get-resolver-roles Lists the role grants on an ENSv2 resolver. ## When to use [#when-to-use] Use to audit who can edit the records a resolver holds. ## Details [#details] - Powers use the indexer's vocabulary (`set_text`, `admin_set_addr`, …). ## Signature [#signature] ```ts function getResolverRoles( client: Like, options: getResolverRoles.Options, ): Promise ``` Call it as `ens.indexer.getResolverRoles(options)` on a client, or `Actions.indexer.getResolverRoles(client, options)`. `indexer.getResolverRoles.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 | | --- | --- | --- | --- | | `at` | `{ readonly token: string } \| { readonly timestamp: bigint \| Date }` | | Read at a snapshot: an earlier answer's `asOfToken`, or a time. | | `finality` | `"latest" \| "safe" \| "finalized"` | `"latest"` | How settled the data must be: `latest`, `safe` or `finalized`. | | `limit` | `number` | | Rows per page, 1–200. @default 50 | | `cursor` | `string` | | The previous page's `cursor`. | | `includeTotal` | `boolean` | | Count every row (`totalCount`); slower. | | `address` (required) | `string` | | Contract address. | | `chainId` | `number` | | Chain of the contract. @default the client's chain | Also takes the [read options](/docs/reference/sdk/client#read-options). ## Returns [#returns] Resolves to `Page`. One page of grants. ## Errors [#errors] | Error | Codes | When | | --- | --- | --- | | [`InvalidInputError`](/docs/reference/errors/invalid-input-error) | [`INVALID_ADDRESS`](/docs/reference/errors/INVALID_ADDRESS) | an invalid address. | | [`ConfigError`](/docs/reference/errors/config-error) | [`INDEXER_NOT_CONFIGURED`](/docs/reference/errors/INDEXER_NOT_CONFIGURED) | the client has no indexer. | | [`IndexerError`](/docs/reference/errors/indexer-error) | [`INDEXER_UNSUPPORTED`](/docs/reference/errors/INDEXER_UNSUPPORTED) | the indexer does not serve the query or its namespace. | | [`IndexerError`](/docs/reference/errors/indexer-error) | [`INDEXER_UNAVAILABLE`](/docs/reference/errors/INDEXER_UNAVAILABLE), [`INDEXER_RATE_LIMITED`](/docs/reference/errors/INDEXER_RATE_LIMITED), [`INDEXER_BEHIND`](/docs/reference/errors/INDEXER_BEHIND), [`INDEXER_REQUEST_REJECTED`](/docs/reference/errors/INDEXER_REQUEST_REJECTED), [`INDEXER_RESPONSE_INVALID`](/docs/reference/errors/INDEXER_RESPONSE_INVALID) | the indexer is unavailable, rate limiting, behind, rejects the request or answers unexpectedly. | 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="Listing a resolver's roles" const page = await ens.indexer.getResolverRoles({ address: "0xF4f1…" }) ``` ```ts title="Listing roles with a standalone call" import { Actions } from "@ensforge/sdk" const page = await Actions.indexer.getResolverRoles(ens, { address }) ``` ```ts title="Listing roles in an Effect program" import { Actions } from "@ensforge/sdk/effect" const page = yield* Actions.indexer.getResolverRoles(ens, { address }) ``` ## Example response [#example-response] Recorded from Ethereum mainnet on 2026-11-18 at block 26443964. Values change as the chain does. ```ts await ens.indexer.getResolverRoles({ address: "0xF29100983E058B709F3D539b0c765937B804AC15", chainId: 1, limit: 3 }) ``` ```json { "asOf": { "chainId": 1, "blockNumber": "26443964n", "blockHash": "0xe75c58ea2f28bd7c6cc53c28a5ab4fc02023f3563661f0a7236a36b779e3ac86", "timestamp": "1795029143n" }, "snapshots": { "1": { "chainId": 1, "blockNumber": "26443964n", "blockHash": "0xe75c58ea2f28bd7c6cc53c28a5ab4fc02023f3563661f0a7236a36b779e3ac86", "timestamp": "1795029143n" } }, "asOfToken": "7b22657468657265756d223a7b22626c6f636b5f68617368223a22307865373563353865613266323862643763366363353363323861356162346663303230323366333536333636316630613732333661333662373739653361633836222c22626c6f636b5f6e756d626572223a32363434333936342c22636861696e5f6964223a22657468657265756d2d6d61696e6e6574222c2274696d657374616d70223a22323032362d31312d31385431393a31323a32335a227d7d", "completeness": "unsupported", "unsupportedReason": "binding_enumeration_not_supported", "unsupportedFields": [ "roles" ], "origin": null, "indexer": "bigname", "items": [], "cursor": null, "hasMore": false, "totalCount": null } ``` ## See also [#see-also] - [`role.get`](/docs/reference/sdk/role/get) for the on-chain read # indexer.getResolver > For the complete documentation index, see [llms.txt](https://ensforge.com/llms.txt). Reads a resolver and one page of the names bound to it. Parameters, return value, errors and examples for indexer.getResolver in @ensforge/sdk. Source: https://ensforge.com/docs/reference/sdk/indexer/get-resolver Reads a resolver and one page of the names bound to it. ## When to use [#when-to-use] Use to see which names use a resolver before changing or replacing it. ## Details [#details] - Bound names are paged: pass the answer's `cursor` for more. - ENSv1 compatibility resolvers report the registry they mirror (`mirrors`). ## Signature [#signature] ```ts function getResolver( client: Like, options: getResolver.Options, ): Promise ``` Call it as `ens.indexer.getResolver(options)` on a client, or `Actions.indexer.getResolver(client, options)`. `indexer.getResolver.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 | | --- | --- | --- | --- | | `at` | `{ readonly token: string } \| { readonly timestamp: bigint \| Date }` | | Read at a snapshot: an earlier answer's `asOfToken`, or a time. | | `finality` | `"latest" \| "safe" \| "finalized"` | `"latest"` | How settled the data must be: `latest`, `safe` or `finalized`. | | `limit` | `number` | | Rows per page, 1–200. @default 50 | | `cursor` | `string` | | The previous page's `cursor`. | | `includeTotal` | `boolean` | | Count every row (`totalCount`); slower. | | `address` (required) | `string` | | Contract address. | | `chainId` | `number` | | Chain of the contract. @default the client's chain | Also takes the [read options](/docs/reference/sdk/client#read-options). ## Returns [#returns] Resolves to `Result | null`. The resolver, or `null` when the indexer does not know it. ## Errors [#errors] | Error | Codes | When | | --- | --- | --- | | [`InvalidInputError`](/docs/reference/errors/invalid-input-error) | [`INVALID_ADDRESS`](/docs/reference/errors/INVALID_ADDRESS) | an invalid address. | | [`NotFoundError`](/docs/reference/errors/not-found-error) | [`INDEXER_NOT_FOUND`](/docs/reference/errors/INDEXER_NOT_FOUND) | with `strict: true` when the indexer does not know the contract. | | [`ConfigError`](/docs/reference/errors/config-error) | [`INDEXER_NOT_CONFIGURED`](/docs/reference/errors/INDEXER_NOT_CONFIGURED) | the client has no indexer. | | [`IndexerError`](/docs/reference/errors/indexer-error) | [`INDEXER_UNSUPPORTED`](/docs/reference/errors/INDEXER_UNSUPPORTED) | the indexer does not serve the query or its namespace. | | [`IndexerError`](/docs/reference/errors/indexer-error) | [`INDEXER_UNAVAILABLE`](/docs/reference/errors/INDEXER_UNAVAILABLE), [`INDEXER_RATE_LIMITED`](/docs/reference/errors/INDEXER_RATE_LIMITED), [`INDEXER_BEHIND`](/docs/reference/errors/INDEXER_BEHIND), [`INDEXER_REQUEST_REJECTED`](/docs/reference/errors/INDEXER_REQUEST_REJECTED), [`INDEXER_RESPONSE_INVALID`](/docs/reference/errors/INDEXER_RESPONSE_INVALID) | the indexer is unavailable, rate limiting, behind, rejects the request or answers unexpectedly. | 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 resolver" const resolver = await ens.indexer.getResolver({ address: "0xF4f1…" }) ``` ```ts title="Reading a resolver with a standalone call" import { Actions } from "@ensforge/sdk" const resolver = await Actions.indexer.getResolver(ens, { address, limit: 200 }) ``` ```ts title="Reading a resolver in an Effect program" import { Actions } from "@ensforge/sdk/effect" const resolver = yield* Actions.indexer.getResolver(ens, { address }) ``` ## Example response [#example-response] Recorded from Ethereum mainnet on 2026-11-18 at block 26443964. Values change as the chain does. ```ts await ens.indexer.getResolver({ address: "0xF29100983E058B709F3D539b0c765937B804AC15", chainId: 1, limit: 3 }) ``` ```json { "chainId": 1, "address": "0xF29100983E058B709F3D539b0c765937B804AC15", "names": [ "$$$$$$$$$$$.eth", "$-$-$.eth", "$$0$$.eth" ], "cursor": "7b2276657273696f6e223a312c22736f7274223a226e616d655f617363222c2266696c74657273223a7b22636861696e5f6964223a2231222c226e616d657370616365223a22222c227265736f6c766572223a22307866323931303039383365303538623730396633643533396230633736353933376238303461633135227d2c226c6173745f6974656d223a7b226e616d6568617368223a22307834356637383564353561643462313234613366356231653865376238353661363438623838376261386462653961613166313437393962373533636663633037222c226e616d657370616365223a22656e73222c226f726465725f6e616d65223a2224243024242e657468222c22736f72745f76616c7565223a2224243024242e657468227d2c22736e617073686f74223a6e756c6c7d", "hasMore": true, "mirrors": null, "asOf": { "chainId": 1, "blockNumber": "26443964n", "blockHash": "0xe75c58ea2f28bd7c6cc53c28a5ab4fc02023f3563661f0a7236a36b779e3ac86", "timestamp": "1795029143n" }, "snapshots": { "1": { "chainId": 1, "blockNumber": "26443964n", "blockHash": "0xe75c58ea2f28bd7c6cc53c28a5ab4fc02023f3563661f0a7236a36b779e3ac86", "timestamp": "1795029143n" } }, "asOfToken": "7b22657468657265756d223a7b22626c6f636b5f68617368223a22307865373563353865613266323862643763366363353363323861356162346663303230323366333536333636316630613732333661333662373739653361633836222c22626c6f636b5f6e756d626572223a32363434333936342c22636861696e5f6964223a22657468657265756d2d6d61696e6e6574222c2274696d657374616d70223a22323032362d31312d31385431393a31323a32335a227d7d", "completeness": "full", "unsupportedReason": null, "unsupportedFields": [], "origin": null, "indexer": "bigname" } ``` ## See also [#see-also] - [`resolver.get`](/docs/reference/sdk/resolver/get) for the on-chain read # indexer.getResolvers > For the complete documentation index, see [llms.txt](https://ensforge.com/llms.txt). Lists the ENSv2 resolvers on which an address holds roles. Parameters, return value, errors and examples for indexer.getResolvers in @ensforge/sdk. Source: https://ensforge.com/docs/reference/sdk/indexer/get-resolvers Lists the ENSv2 resolvers on which an address holds roles. ## When to use [#when-to-use] Use to find every resolver an account can edit, e.g. for a records dashboard. ## Details [#details] - bigname v0.14 and later; other indexers, and older bigname servers, fail with [`INDEXER_UNSUPPORTED`](/docs/reference/errors/INDEXER_UNSUPPORTED), so `fallback()` moves on to the next indexer. ## Signature [#signature] ```ts function getResolvers( client: Like, options: getResolvers.Options, ): Promise ``` Call it as `ens.indexer.getResolvers(options)` on a client, or `Actions.indexer.getResolvers(client, options)`. `indexer.getResolvers.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 | | --- | --- | --- | --- | | `limit` | `number` | | Rows per page, 1–200. @default 50 | | `cursor` | `string` | | The previous page's `cursor`. | | `includeTotal` | `boolean` | | Count every row (`totalCount`); slower. | | `chainId` | `number` | | | | `roleHolder` (required) | `string` | | The account holding roles. | Also takes the [read options](/docs/reference/sdk/client#read-options). ## Returns [#returns] Resolves to `Page`. One page of resolvers. ## Errors [#errors] | Error | Codes | When | | --- | --- | --- | | [`InvalidInputError`](/docs/reference/errors/invalid-input-error) | [`INVALID_ADDRESS`](/docs/reference/errors/INVALID_ADDRESS) | an invalid address. | | [`ConfigError`](/docs/reference/errors/config-error) | [`INDEXER_NOT_CONFIGURED`](/docs/reference/errors/INDEXER_NOT_CONFIGURED) | the client has no indexer. | | [`IndexerError`](/docs/reference/errors/indexer-error) | [`INDEXER_UNSUPPORTED`](/docs/reference/errors/INDEXER_UNSUPPORTED) | the indexer does not serve the query or its namespace. | | [`IndexerError`](/docs/reference/errors/indexer-error) | [`INDEXER_UNAVAILABLE`](/docs/reference/errors/INDEXER_UNAVAILABLE), [`INDEXER_RATE_LIMITED`](/docs/reference/errors/INDEXER_RATE_LIMITED), [`INDEXER_BEHIND`](/docs/reference/errors/INDEXER_BEHIND), [`INDEXER_REQUEST_REJECTED`](/docs/reference/errors/INDEXER_REQUEST_REJECTED), [`INDEXER_RESPONSE_INVALID`](/docs/reference/errors/INDEXER_RESPONSE_INVALID) | the indexer is unavailable, rate limiting, behind, rejects the request or answers unexpectedly. | 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="Listing an account's resolvers" const page = await ens.indexer.getResolvers({ roleHolder: account }) ``` ```ts title="Listing resolvers with a standalone call" import { Actions } from "@ensforge/sdk" const page = await Actions.indexer.getResolvers(ens, { roleHolder: account }) ``` ```ts title="Listing resolvers in an Effect program" import { Actions } from "@ensforge/sdk/effect" const page = yield* Actions.indexer.getResolvers(ens, { roleHolder: account }) ``` ## Example response [#example-response] Recorded from Ethereum mainnet on 2026-11-18 at block 26443964. Values change as the chain does. ```ts await ens.indexer.getResolvers({ roleHolder: "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045", limit: 3 }) ``` ```json { "asOf": { "chainId": 1, "blockNumber": "26443964n", "blockHash": "0xe75c58ea2f28bd7c6cc53c28a5ab4fc02023f3563661f0a7236a36b779e3ac86", "timestamp": "1795029143n" }, "snapshots": { "1": { "chainId": 1, "blockNumber": "26443964n", "blockHash": "0xe75c58ea2f28bd7c6cc53c28a5ab4fc02023f3563661f0a7236a36b779e3ac86", "timestamp": "1795029143n" } }, "asOfToken": null, "completeness": "full", "unsupportedReason": null, "unsupportedFields": [], "origin": null, "indexer": "bigname", "items": [], "cursor": null, "hasMore": false, "totalCount": null } ``` # indexer.getStatus > For the complete documentation index, see [llms.txt](https://ensforge.com/llms.txt). Reads the indexer's health and how far each chain is indexed. Parameters, return value, errors and examples for indexer.getStatus in @ensforge/sdk. Source: https://ensforge.com/docs/reference/sdk/indexer/get-status Reads the indexer's health and how far each chain is indexed. ## When to use [#when-to-use] Use to show a sync banner, or to wait until a write is indexed before reading it back. ## Details [#details] - Chains are keyed by chain ID; `safe` and `finalized` are `null` when the indexer does not track them. ## Signature [#signature] ```ts function getStatus( client: Like, options?: getStatus.Options, ): Promise ``` Call it as `ens.indexer.getStatus(options)` on a client, or `Actions.indexer.getStatus(client, options)`. `indexer.getStatus.request(options)` builds a deferred read for `Actions.batch`. See [Look up many at once](/docs/sdk/look-up-many-at-once). ## Parameters [#parameters] Also takes the [read options](/docs/reference/sdk/client#read-options). ## Returns [#returns] Resolves to `IndexerStatus`. Overall status and per-chain progress. | Field | Type | Description | | --- | --- | --- | | `status` | `"ready" \| "degraded" \| "stale"` | | | `chains` | `Readonly>` | | | `indexer` | `string` | | ## Errors [#errors] | Error | Codes | When | | --- | --- | --- | | [`ConfigError`](/docs/reference/errors/config-error) | [`INDEXER_NOT_CONFIGURED`](/docs/reference/errors/INDEXER_NOT_CONFIGURED) | the client has no indexer. | | [`IndexerError`](/docs/reference/errors/indexer-error) | [`INDEXER_UNSUPPORTED`](/docs/reference/errors/INDEXER_UNSUPPORTED) | the indexer does not serve the query or its namespace. | | [`IndexerError`](/docs/reference/errors/indexer-error) | [`INDEXER_UNAVAILABLE`](/docs/reference/errors/INDEXER_UNAVAILABLE), [`INDEXER_RATE_LIMITED`](/docs/reference/errors/INDEXER_RATE_LIMITED), [`INDEXER_BEHIND`](/docs/reference/errors/INDEXER_BEHIND), [`INDEXER_REQUEST_REJECTED`](/docs/reference/errors/INDEXER_REQUEST_REJECTED), [`INDEXER_RESPONSE_INVALID`](/docs/reference/errors/INDEXER_RESPONSE_INVALID) | the indexer is unavailable, rate limiting, behind, rejects the request or answers unexpectedly. | 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 status" const status = await ens.indexer.getStatus() ``` ```ts title="Reading the status with a standalone call" import { Actions } from "@ensforge/sdk" const { chains } = await Actions.indexer.getStatus(ens) ``` ```ts title="Reading the status in an Effect program" import { Actions } from "@ensforge/sdk/effect" const status = yield* Actions.indexer.getStatus(ens) ``` ## Example response [#example-response] Recorded from Ethereum mainnet on 2026-11-18 at block 26443964. Values change as the chain does. ```ts await ens.indexer.getStatus({}) ``` ```json { "status": "ready", "chains": { "1": { "status": "ready", "indexed": "26443964n", "latest": "26443965n", "safe": "26443916n", "finalized": "26443884n", "lagBlocks": 1, "lagSeconds": 12 } }, "indexer": "bigname" } ``` # indexer.getSubnames > For the complete documentation index, see [llms.txt](https://ensforge.com/llms.txt). Lists the direct subnames of a name. Parameters, return value, errors and examples for indexer.getSubnames in @ensforge/sdk. Source: https://ensforge.com/docs/reference/sdk/indexer/get-subnames Lists the direct subnames of a name. ## When to use [#when-to-use] Use to show a name's children, e.g. a subname table with search and sorting. ## Details [#details] - Includes expired and released children unless `includeExpired: false`. - `search` matches labels by prefix, or anywhere with `match: "contains"`. - Fails with `NotFoundError` ([`INDEXER_NOT_FOUND`](/docs/reference/errors/INDEXER_NOT_FOUND)) when the indexer has no such parent. ## Signature [#signature] ```ts function getSubnames( client: Like, options: getSubnames.Options, ): Promise ``` Call it as `ens.indexer.getSubnames(options)` on a client, or `Actions.indexer.getSubnames(client, options)`. `indexer.getSubnames.request(options)` builds a deferred read for `Actions.batch`. See [Look up many at once](/docs/sdk/look-up-many-at-once). In React, use [`useSubnames`](/docs/reference/react/use-subnames). ## Parameters [#parameters] | Option | Type | Default | Description | | --- | --- | --- | --- | | `limit` | `number` | | Rows per page, 1–200. @default 50 | | `cursor` | `string` | | The previous page's `cursor`. | | `includeTotal` | `boolean` | | Count every row (`totalCount`); slower. | | `name` (required) | `string` | | | | `search` | `string` | | | | `match` | `"prefix" \| "contains"` | | Whether `search` matches from the start of a label (`prefix`) or anywhere (`contains`). | | `sort` | `"name" \| "expiry" \| "registered"` | `"name"` | Field the rows are sorted by. | | `order` | `"asc" \| "desc"` | | Sort direction. | | `includeExpired` | `boolean` | `true` | | | `namespace` | `Namespace` | "basenames" for `*.base.eth`, otherwise "ens" | Namespace of the name. | Also takes the [read options](/docs/reference/sdk/client#read-options). ## Returns [#returns] Resolves to `Page`. One page of subnames. ## Errors [#errors] | Error | Codes | When | | --- | --- | --- | | [`InvalidInputError`](/docs/reference/errors/invalid-input-error) | [`INVALID_NAME`](/docs/reference/errors/INVALID_NAME) | the name does not normalize. | | [`NotFoundError`](/docs/reference/errors/not-found-error) | [`INDEXER_NOT_FOUND`](/docs/reference/errors/INDEXER_NOT_FOUND) | the indexer has no such name. | | [`ConfigError`](/docs/reference/errors/config-error) | [`INDEXER_NOT_CONFIGURED`](/docs/reference/errors/INDEXER_NOT_CONFIGURED) | the client has no indexer. | | [`IndexerError`](/docs/reference/errors/indexer-error) | [`INDEXER_UNSUPPORTED`](/docs/reference/errors/INDEXER_UNSUPPORTED) | the indexer does not serve the query or its namespace. | | [`IndexerError`](/docs/reference/errors/indexer-error) | [`INDEXER_UNAVAILABLE`](/docs/reference/errors/INDEXER_UNAVAILABLE), [`INDEXER_RATE_LIMITED`](/docs/reference/errors/INDEXER_RATE_LIMITED), [`INDEXER_BEHIND`](/docs/reference/errors/INDEXER_BEHIND), [`INDEXER_REQUEST_REJECTED`](/docs/reference/errors/INDEXER_REQUEST_REJECTED), [`INDEXER_RESPONSE_INVALID`](/docs/reference/errors/INDEXER_RESPONSE_INVALID) | the indexer is unavailable, rate limiting, behind, rejects the request or answers unexpectedly. | 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="Listing subnames" const page = await ens.indexer.getSubnames({ name: "ens.eth" }) ``` ```ts title="Searching subnames with a standalone call" import { Actions } from "@ensforge/sdk" const page = await Actions.indexer.getSubnames(ens, { name: "ens.eth", search: "dao" }) ``` ```ts title="Listing subnames in an Effect program" import { Actions } from "@ensforge/sdk/effect" const page = yield* Actions.indexer.getSubnames(ens, { name: "ens.eth", sort: "expiry" }) ``` ## Example response [#example-response] Recorded from Ethereum mainnet on 2026-11-18 at block 26443964. Values change as the chain does. ```ts await ens.indexer.getSubnames({ name: "ens.eth", namespace: "ens", limit: 3 }) ``` ```json { "asOf": { "chainId": 1, "blockNumber": "26443964n", "blockHash": "0xe75c58ea2f28bd7c6cc53c28a5ab4fc02023f3563661f0a7236a36b779e3ac86", "timestamp": "1795029143n" }, "snapshots": { "1": { "chainId": 1, "blockNumber": "26443964n", "blockHash": "0xe75c58ea2f28bd7c6cc53c28a5ab4fc02023f3563661f0a7236a36b779e3ac86", "timestamp": "1795029143n" } }, "asOfToken": null, "completeness": "full", "unsupportedReason": null, "unsupportedFields": [], "origin": null, "indexer": "bigname", "items": [ { "name": "app.ens.eth", "displayName": "app.ens.eth", "namespace": "ens", "node": "0x50a74dcf107973068dfc00db69ecf98b49d52f5361cb4db5feb740fc9f4f74d1", "status": "active", "authority": "ensV1", "owner": "0xb6E040C9ECAaE172a89bD561c5F73e1C48d28cd9", "manager": "0xb6E040C9ECAaE172a89bD561c5F73e1C48d28cd9", "registeredAt": null, "createdAt": "1611624962n", "expiresAt": null, "graceEndsAt": null, "expiryReason": null, "ensV1": { "resolver": { "chainId": 1, "address": "0x4976fb03C32e5B8cfe2b6cCB31c09Ba78EBaBa41" }, "expiresAt": null, "wrapperState": "unwrapped", "wrapperExpiresAt": null, "wrapperFuses": null }, "labelhash": "0xd6f028ca0e8edb4a8c9757ca4fdccab25fa1e0317da1188108f7d2dee14902fb", "subnameCount": null, "subregistry": null }, { "name": "attestations.ens.eth", "displayName": "attestations.ens.eth", "namespace": "ens", "node": "0x9e5c7a2f2ab8b565c6d2c4851a73decb53d1f6a23c97a2b5b66f21d8ace1bbd5", "status": "active", "authority": "ensV1", "owner": "0xb6E040C9ECAaE172a89bD561c5F73e1C48d28cd9", "manager": "0xb6E040C9ECAaE172a89bD561c5F73e1C48d28cd9", "registeredAt": null, "createdAt": "1744877879n", "expiresAt": null, "graceEndsAt": null, "expiryReason": null, "ensV1": { "resolver": { "chainId": 1, "address": "0x231b0Ee14048e9dCcD1d247744d114a4EB5E8E63" }, "expiresAt": null, "wrapperState": "unwrapped", "wrapperExpiresAt": null, "wrapperFuses": null }, "labelhash": "0x14a804be56ac3478cdc58c820cb1271d39e4a2511f4c5aec7d2c25d624f24918", "subnameCount": null, "subregistry": null }, { "name": "coldwallet.ens.eth", "displayName": "coldwallet.ens.eth", "namespace": "ens", "node": "0xc867d2bd24b8a88c7d5d416dfab28fec6858b5a86f3a1c94faeab450c34023f6", "status": "active", "authority": "ensV1", "owner": "0x690F0581eCecCf8389c223170778cD9D029606F2", "manager": "0x690F0581eCecCf8389c223170778cD9D029606F2", "registeredAt": null, "createdAt": "1614125684n", "expiresAt": null, "graceEndsAt": null, "expiryReason": null, "ensV1": { "resolver": { "chainId": 1, "address": "0x4976fb03C32e5B8cfe2b6cCB31c09Ba78EBaBa41" }, "expiresAt": null, "wrapperState": "unwrapped", "wrapperExpiresAt": null, "wrapperFuses": null }, "labelhash": "0x7d044acfeccf1426368be42c96e62a4cf73d3ea32c44c023cffe9c50ca329c62", "subnameCount": null, "subregistry": null } ], "cursor": "7b2276657273696f6e223a312c22736f7274223a226e616d65222c2266696c74657273223a7b22696e636c7564655f65787069726564223a2274727565222c226e616d657370616365223a22656e73222c226f72646572223a22617363222c22706172656e74223a22656e733a307834653334643361383164633361323066373162626466323136303439326464616131376565376535353233373537643437313533333739633133636234366466222c2271223a22227d2c226c6173745f6974656d223a7b226368696c645f6c6f676963616c5f6e616d655f6964223a22656e733a307863383637643262643234623861383863376435643431366466616232386665633638353862356138366633613163393466616561623435306333343032336636222c22646973706c61795f6e616d65223a22636f6c6477616c6c65742e656e732e657468222c22736f72745f6b696e64223a226e616d65222c22736f72745f76616c7565223a22227d2c22736e617073686f74223a6e756c6c7d", "hasMore": true, "totalCount": 23 } ``` ## See also [#see-also] - `paginate` from `@ensforge/sdk/indexer` to walk every page # indexer > For the complete documentation index, see [llms.txt](https://ensforge.com/llms.txt). List the 19 indexer actions of @ensforge/sdk and whether each reads, writes or signs. Covers getEvents, getHistory, getName, getNamesByExpiry. Source: https://ensforge.com/docs/reference/sdk/indexer Call them as `ens.indexer.(options)` on a client, or `Actions.indexer.(client, options)`. ## Reads [#reads] | Action | Description | | --- | --- | | [`getEvents`](/docs/reference/sdk/indexer/get-events) (batchable) | Searches indexed ENS events by name, address, resolver, contract or block range. | | [`getHistory`](/docs/reference/sdk/indexer/get-history) (batchable) | Reads the full history of a name, or of every name an address is related to. | | [`getName`](/docs/reference/sdk/indexer/get-name) (batchable) | Reads one name from the indexer: owner, manager, expiry, resolver, records and protocol. | | [`getNamesByExpiry`](/docs/reference/sdk/indexer/get-names-by-expiry) (batchable) | Lists names by when they expire or leave their grace period. | | [`getNamesForAddress`](/docs/reference/sdk/indexer/get-names-for-address) (batchable) | Lists the names an address owns, manages, holds roles on, resolves to, or used to own. | | [`getNamespace`](/docs/reference/sdk/indexer/get-namespace) (batchable) | Reads what the indexer serves for a namespace: its networks and which features are complete. | | [`getPermissions`](/docs/reference/sdk/indexer/get-permissions) (batchable) | Lists who can do what over a name, a registration, an account or an ENSv2 registry. | | [`getPrimaryName`](/docs/reference/sdk/indexer/get-primary-name) (batchable) | Reads an address's primary name from the indexer, verified on-chain when the indexer can. | | [`getRecords`](/docs/reference/sdk/indexer/get-records) (batchable) | Reads a name's records and its record inventory from the indexer. | | [`getRegistry`](/docs/reference/sdk/indexer/get-registry) (batchable) | Reads an ENSv2 registry: the name it serves, its parent registry, when it was created and its counts. | | [`getRegistryLabels`](/docs/reference/sdk/indexer/get-registry-labels) (batchable) | Lists the labels of an ENSv2 registry, optionally only those an address holds or does not hold. | | [`getResolver`](/docs/reference/sdk/indexer/get-resolver) (batchable) | Reads a resolver and one page of the names bound to it. | | [`getResolverLinks`](/docs/reference/sdk/indexer/get-resolver-links) (batchable) | Lists the names linked to record sets on an ENSv2 resolver. | | [`getResolverRoles`](/docs/reference/sdk/indexer/get-resolver-roles) (batchable) | Lists the role grants on an ENSv2 resolver. | | [`getResolvers`](/docs/reference/sdk/indexer/get-resolvers) (batchable) | Lists the ENSv2 resolvers on which an address holds roles. | | [`getStatus`](/docs/reference/sdk/indexer/get-status) (batchable) | Reads the indexer's health and how far each chain is indexed. | | [`getSubnames`](/docs/reference/sdk/indexer/get-subnames) (batchable) | Lists the direct subnames of a name. | | [`lookup`](/docs/reference/sdk/indexer/lookup) (batchable) | Reads up to 1,000 names and addresses in one request. | | [`search`](/docs/reference/sdk/indexer/search) (batchable) | Searches names by text. | # indexer.lookup > For the complete documentation index, see [llms.txt](https://ensforge.com/llms.txt). Reads up to 1,000 names and addresses in one request. Parameters, return value, errors and examples for indexer.lookup in @ensforge/sdk. Source: https://ensforge.com/docs/reference/sdk/indexer/lookup Reads up to 1,000 names and addresses in one request. ## When to use [#when-to-use] Use to render lists of names or accounts at once, e.g. a feed or a table of holders. ## Details [#details] - Each input answers on its own: names with their state, addresses with their primary name and related names. - An input that fails (an invalid name) reports `status` instead of failing the whole lookup. - `profile: "detail"` adds records and resolution to each answer. ## Signature [#signature] ```ts function lookup(client: Like, options: lookup.Options): Promise ``` Call it as `ens.indexer.lookup(options)` on a client, or `Actions.indexer.lookup(client, options)`. `indexer.lookup.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 | | --- | --- | --- | --- | | `inputs` (required) | `readonly string[]` | | Names and addresses, up to 1,000. | | `namespace` | `Namespace` | | Only this naming system; every namespace the indexer serves when omitted. | | `profile` | `"feed" \| "detail"` | | `detail` adds records and resolution. @default "feed" | Also takes the [read options](/docs/reference/sdk/client#read-options). ## Returns [#returns] Resolves to `Result<{ readonly results: readonly LookupResult[] }>`. One answer per input, in input order. ## Errors [#errors] | Error | Codes | When | | --- | --- | --- | | [`InvalidInputError`](/docs/reference/errors/invalid-input-error) | [`INVALID_RECORD_VALUE`](/docs/reference/errors/INVALID_RECORD_VALUE) | more than 1,000 inputs or none. | | [`ConfigError`](/docs/reference/errors/config-error) | [`INDEXER_NOT_CONFIGURED`](/docs/reference/errors/INDEXER_NOT_CONFIGURED) | the client has no indexer. | | [`IndexerError`](/docs/reference/errors/indexer-error) | [`INDEXER_UNSUPPORTED`](/docs/reference/errors/INDEXER_UNSUPPORTED) | the indexer does not serve the query or its namespace. | | [`IndexerError`](/docs/reference/errors/indexer-error) | [`INDEXER_UNAVAILABLE`](/docs/reference/errors/INDEXER_UNAVAILABLE), [`INDEXER_RATE_LIMITED`](/docs/reference/errors/INDEXER_RATE_LIMITED), [`INDEXER_BEHIND`](/docs/reference/errors/INDEXER_BEHIND), [`INDEXER_REQUEST_REJECTED`](/docs/reference/errors/INDEXER_REQUEST_REJECTED), [`INDEXER_RESPONSE_INVALID`](/docs/reference/errors/INDEXER_RESPONSE_INVALID) | the indexer is unavailable, rate limiting, behind, rejects the request or answers unexpectedly. | 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 names and addresses together" const { results } = await ens.indexer.lookup({ inputs: ["nick.eth", "0xd8dA…"] }) ``` ```ts title="Reading profiles with a standalone call" import { Actions } from "@ensforge/sdk" const { results } = await Actions.indexer.lookup(ens, { inputs: names, profile: "detail" }) ``` ```ts title="Reading names together in an Effect program" import { Actions } from "@ensforge/sdk/effect" const { results } = yield* Actions.indexer.lookup(ens, { inputs: ["nick.eth", "ens.eth"] }) ``` ## Example response [#example-response] Recorded from Ethereum mainnet on 2026-11-18 at block 26443964. Values change as the chain does. ```ts await ens.indexer.lookup({ inputs: ["nick.eth", "vitalik.eth"] }) ``` ```json { "results": [ { "input": "nick.eth", "kind": "name", "status": "ok", "name": { "name": "nick.eth", "displayName": "nick.eth", "namespace": "ens", "node": "0x05a67c0ee82964c4f7394cdd47fee7f4d9503a23c09c38341779ea012afe6e00", "status": "active", "authority": "ensV2", "owner": "0xb8c2C29ee19D8307cb7255e1Cd9CbDE883A267d5", "manager": "0xb8c2C29ee19D8307cb7255e1Cd9CbDE883A267d5", "registeredAt": "1600896646n", "createdAt": "1571924851n", "expiresAt": "2051983306n", "graceEndsAt": "2054402506n", "expiryReason": null, "ensV1": null, "chainId": 1, "registrationId": "0cf467d0-e851-5285-bf04-bcab99cab4da", "tokenId": "42219085255511335250589442208301538195142221433306354426240614732610656010240n", "resolver": { "chainId": 1, "address": "0xF4f1007EA430848F2fAd60e405A54Fc100fEc341" }, "subregistry": { "chainId": 1, "address": "0x02cA46F62f6C9F655364bf9Fd4f11Fb8f01C5753" }, "primaryAddress": "0xb8c2C29ee19D8307cb7255e1Cd9CbDE883A267d5", "migratedAt": "1793114183n", "records": { "texts": { "avatar": "https://euc.li/nick.eth", "com.discord": "nickjohnson", "com.github": "arachnid", "com.reddit": "nickjohnson", "com.twitter": "nicksdjohnson", "description": "Lead developer of ENS & Ethereum Foundation alum. Certified rat tickler. he/him.", "email": "arachnid@notdot.net", "eth.ens.delegate": "https://discuss.ens.domains/t/ens-dao-delegate-applications/815/716", "org.telegram": "nicksdjohnson", "snapshot": "ipns://storage.snapshot.page/registry/0xb8c2C29ee19D8307cb7255e1Cd9CbDE883A267d5/nick.eth", "url": "https://ens.domains/" }, "addresses": { "60": "0xb8c2c29ee19d8307cb7255e1cd9cbde883a267d5" }, "contentHash": "0xe5010172002408011220066e20f72cc583d769bc8df5fedff24942b3b8941e827f023d306bdc7aecf5ac", "name": null, "textKeys": [ "avatar", "com.discord", "com.github", "com.reddit", "com.twitter", "description", "email", "eth.ens.delegate", "org.telegram", "snapshot", "url" ], "coinTypes": [ "60" ] }, "recordCount": null, "subnameCount": null, "isPrimary": null }, "names": [], "reason": null }, { "input": "vitalik.eth", "kind": "name", "status": "ok", "name": { "name": "vitalik.eth", "displayName": "vitalik.eth", "namespace": "ens", "node": "0xee6c4522aab0003e8d14cd40a6af439055fd2577951148c14b6cea9a53475835", "status": "active", "authority": "ensV1", "owner": "0x220866B1A2219f40e72f5c628B65D54268cA3A9D", "manager": "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045", "registeredAt": "1581013420n", "createdAt": "1497775154n", "expiresAt": "2469399224n", "graceEndsAt": "2471818424n", "expiryReason": null, "ensV1": { "resolver": { "chainId": 1, "address": "0x231b0Ee14048e9dCcD1d247744d114a4EB5E8E63" }, "expiresAt": "2464042424n", "wrapperState": "unwrapped", "wrapperExpiresAt": null, "wrapperFuses": null }, "chainId": 1, "registrationId": "1e452d59-7d47-54a4-adfa-80a8ed0c09d2", "tokenId": "79233663829379634837589865448569342784712482819484549289560981379859480642508n", "resolver": { "chainId": 1, "address": "0x231b0Ee14048e9dCcD1d247744d114a4EB5E8E63" }, "subregistry": null, "primaryAddress": "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045", "migratedAt": null, "records": { "texts": { "avatar": "https://euc.li/vitalik.eth", "com.github": "vbuterin", "com.twitter": "VitalikButerin", "description": "mi pinxe lo crino tcati", "header": "https://pbs.twimg.com/profile_banners/295218901/1638557376/1500x500", "pgp": "527E406252E06A11416D7487698FEAC70F922A21", "url": "https://vitalik.ca" }, "addresses": { "60": "0xd8da6bf26964af9d7eed9e03e53415d37aa96045" }, "contentHash": "0xe301017012201d261cc098861d9952e6c8954801800e56aa34aabd8a9651b04b4e2498a45c53", "name": null, "textKeys": [ "avatar", "com.github", "com.twitter", "description", "header", "pgp", "url" ], "coinTypes": [ "60" ] }, "recordCount": null, "subnameCount": null, "isPrimary": null }, "names": [], "reason": null } ], "asOf": { "chainId": 1, "blockNumber": "26443965n", "blockHash": "0xc9de37cc3c9ec10dde4ac1f9abcd65d3dca66f5c50f248ff60d142bb09e0e52a", "timestamp": "1795029155n" }, "snapshots": { "1": { "chainId": 1, "blockNumber": "26443965n", "blockHash": "0xc9de37cc3c9ec10dde4ac1f9abcd65d3dca66f5c50f248ff60d142bb09e0e52a", "timestamp": "1795029155n" } }, "asOfToken": "7b22657468657265756d223a7b22626c6f636b5f68617368223a22307863396465333763633363396563313064646534616331663961626364363564336463613636663563353066323438666636306431343262623039653065353261222c22626c6f636b5f6e756d626572223a32363434333936352c22636861696e5f6964223a22657468657265756d2d6d61696e6e6574222c2274696d657374616d70223a22323032362d31312d31385431393a31323a33355a227d7d", "completeness": "full", "unsupportedReason": null, "unsupportedFields": [], "origin": null, "indexer": "bigname" } ``` ## See also [#see-also] - `Actions.batch` for on-chain reads together # indexer.search > For the complete documentation index, see [llms.txt](https://ensforge.com/llms.txt). Searches names by text. Parameters, return value, errors and examples for indexer.search in @ensforge/sdk. Options, errors and examples for indexer.search. Source: https://ensforge.com/docs/reference/sdk/indexer/search Searches names by text. ## When to use [#when-to-use] Use to back a name search box or autocomplete. ## Details [#details] - Matches from the start of a label by default; `match: "contains"` matches anywhere. - Searches every namespace the indexer serves unless `namespace` is set. ## Signature [#signature] ```ts function search(client: Like, options: search.Options): Promise ``` Call it as `ens.indexer.search(options)` on a client, or `Actions.indexer.search(client, options)`. `indexer.search.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 | | --- | --- | --- | --- | | `limit` | `number` | | Rows per page, 1–200. @default 50 | | `cursor` | `string` | | The previous page's `cursor`. | | `includeTotal` | `boolean` | | Count every row (`totalCount`); slower. | | `query` (required) | `string` | | | | `namespace` | `Namespace` | | Only this naming system; every namespace the indexer serves when omitted. | | `match` | `"prefix" \| "contains"` | `"prefix"` | Whether `search` matches from the start of a label (`prefix`) or anywhere (`contains`). | Also takes the [read options](/docs/reference/sdk/client#read-options). ## Returns [#returns] Resolves to `Page`. One page of matching names. ## Errors [#errors] | Error | Codes | When | | --- | --- | --- | | [`InvalidInputError`](/docs/reference/errors/invalid-input-error) | [`INVALID_RECORD_VALUE`](/docs/reference/errors/INVALID_RECORD_VALUE) | `query` is empty. | | [`ConfigError`](/docs/reference/errors/config-error) | [`INDEXER_NOT_CONFIGURED`](/docs/reference/errors/INDEXER_NOT_CONFIGURED) | the client has no indexer. | | [`IndexerError`](/docs/reference/errors/indexer-error) | [`INDEXER_UNSUPPORTED`](/docs/reference/errors/INDEXER_UNSUPPORTED) | the indexer does not serve the query or its namespace. | | [`IndexerError`](/docs/reference/errors/indexer-error) | [`INDEXER_UNAVAILABLE`](/docs/reference/errors/INDEXER_UNAVAILABLE), [`INDEXER_RATE_LIMITED`](/docs/reference/errors/INDEXER_RATE_LIMITED), [`INDEXER_BEHIND`](/docs/reference/errors/INDEXER_BEHIND), [`INDEXER_REQUEST_REJECTED`](/docs/reference/errors/INDEXER_REQUEST_REJECTED), [`INDEXER_RESPONSE_INVALID`](/docs/reference/errors/INDEXER_RESPONSE_INVALID) | the indexer is unavailable, rate limiting, behind, rejects the request or answers unexpectedly. | 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="Searching names" const page = await ens.indexer.search({ query: "vitalik" }) ``` ```ts title="Searching anywhere in a label with a standalone call" import { Actions } from "@ensforge/sdk" const page = await Actions.indexer.search(ens, { query: "dao", match: "contains" }) ``` ```ts title="Searching names in an Effect program" import { Actions } from "@ensforge/sdk/effect" const page = yield* Actions.indexer.search(ens, { query: "nick", limit: 10 }) ``` ## Example response [#example-response] Recorded from Ethereum mainnet on 2026-11-18 at block 26443964. Values change as the chain does. ```ts await ens.indexer.search({ query: "nick", limit: 3 }) ``` ```json { "asOf": { "chainId": 1, "blockNumber": "26443964n", "blockHash": "0xe75c58ea2f28bd7c6cc53c28a5ab4fc02023f3563661f0a7236a36b779e3ac86", "timestamp": "1795029143n" }, "snapshots": { "1": { "chainId": 1, "blockNumber": "26443964n", "blockHash": "0xe75c58ea2f28bd7c6cc53c28a5ab4fc02023f3563661f0a7236a36b779e3ac86", "timestamp": "1795029143n" } }, "asOfToken": null, "completeness": "full", "unsupportedReason": null, "unsupportedFields": [], "origin": null, "indexer": "bigname", "items": [ { "name": "nick$.eth", "displayName": "nick$.eth", "namespace": "ens", "node": "0xde12a72f054d0acbde40e76aac0645dfaccb693266992519cbe037cc63de6772", "status": "released", "authority": "ensV1", "owner": null, "manager": null, "registeredAt": "1686782675n", "createdAt": "1686782675n", "expiresAt": "1718318675n", "graceEndsAt": "1726094675n", "expiryReason": null, "ensV1": { "resolver": { "chainId": 1, "address": "0x231b0Ee14048e9dCcD1d247744d114a4EB5E8E63" }, "expiresAt": "1718318675n", "wrapperState": "lapsed", "wrapperExpiresAt": "1726094675n", "wrapperFuses": null } }, { "name": "nick000.eth", "displayName": "nick000.eth", "namespace": "ens", "node": "0xef756a95f9f619232d5086dc8d59281e17d3252ff42705f5a0930e30a37d3d8b", "status": "released", "authority": "ensV1", "owner": null, "manager": null, "registeredAt": "1650609765n", "createdAt": "1650609765n", "expiresAt": "1682166717n", "graceEndsAt": "1689942717n", "expiryReason": null, "ensV1": { "resolver": null, "expiresAt": "1682166717n", "wrapperState": null, "wrapperExpiresAt": null, "wrapperFuses": null } }, { "name": "nick007.eth", "displayName": "nick007.eth", "namespace": "ens", "node": "0x6c8a6fd915fddafd8238c2c23f8bf1f89421220a5ce071f2b9161cf2d84b0a1d", "status": "active", "authority": "ensV1", "owner": "0xAF09Db90C6Fa32326485bC9759c154D3AD1bA43F", "manager": "0xAF09Db90C6Fa32326485bC9759c154D3AD1bA43F", "registeredAt": "1644098284n", "createdAt": "1644098284n", "expiresAt": "1807239844n", "graceEndsAt": "1809659044n", "expiryReason": null, "ensV1": { "resolver": { "chainId": 1, "address": "0x4976fb03C32e5B8cfe2b6cCB31c09Ba78EBaBa41" }, "expiresAt": "1801883044n", "wrapperState": "unwrapped", "wrapperExpiresAt": null, "wrapperFuses": null } } ], "cursor": "7b2276657273696f6e223a312c22736f7274223a226e616d655f617363222c2266696c74657273223a7b226d61746368223a22707265666978222c226e616d657370616365223a227075626c69633a656e73222c2271223a226e69636b227d2c226c6173745f6974656d223a7b22646973706c61795f6e616d65223a226e69636b3030372e657468222c226e616d6568617368223a22307836633861366664393135666464616664383233386332633233663862663166383934323132323061356365303731663262393136316366326438346230613164222c226e616d657370616365223a22656e73222c226e6f726d616c697a65645f6e616d65223a226e69636b3030372e657468227d2c22736e617073686f74223a6e756c6c7d", "hasMore": true, "totalCount": null } ``` # Indexers > For the complete documentation index, see [llms.txt](https://ensforge.com/llms.txt). Look up the indexers, query options and result types of @ensforge/sdk/indexer, the adapters that serve search, history and name listings. Source: https://ensforge.com/docs/reference/sdk/indexers Exports of `@ensforge/sdk/indexer`. See [Connect an indexer](/docs/sdk/connect-an-indexer). ## Indexers [#indexers] ### `bigname` [#bigname] The bigname indexer (`api.bigname.sh`), the indexer the ENS app uses. ```ts function bigname(options: RestIndexerOptions & { /** Revalidate repeated reads with ETags. @default false */ cache?: boolean | undefined; } = {}): Indexer ``` Use for ENS names on mainnet and Sepolia: ENSv1 and ENSv2 state, records, subnames, history, permissions, and verified (on-chain) records and primary names. - Public hosts: `https://api.bigname.sh` (mainnet) and `https://sepolia.api.bigname.sh` (Sepolia); other chains need `url`. - Answers can be pinned to a snapshot (`at`) and read at `safe` or `finalized` finality. - What it serves is read from its `/status` and `/namespaces` routes on first use: a client on another chain, or a namespace it does not index yet (Basenames, at the time of writing), fails with [`INDEXER_UNSUPPORTED`](/docs/reference/errors/INDEXER_UNSUPPORTED), so `fallback` moves on. - `cache: true` revalidates repeated reads with ETags. ```ts title="Mainnet or Sepolia" import { Ensforge } from "@ensforge/sdk" import { bigname, indexerActions } from "@ensforge/sdk/indexer" const ens = Ensforge.create({ publicClient, indexer: bigname() }).extend(indexerActions()) ``` ```ts title="A self-hosted bigname" import { bigname } from "@ensforge/sdk/indexer" const indexer = bigname({ url: "https://bigname.internal", headers: { authorization } }) ``` ```ts title="With Goldsky for Basenames" import { bigname, fallback, goldsky } from "@ensforge/sdk/indexer" const indexer = fallback([bigname(), goldsky()]) ``` ### `defineIndexer` [#defineindexer] Builds an indexer from your own functions, e.g. for an in-house API or a test double. ```ts function defineIndexer(adapter: Adapter): Indexer ``` Use when your data source does not speak bigname's REST API; for one that does (a self-hosted bigname, a proxy), pass its URL to `bigname({ url })` instead. - Implement only the queries you serve; the others fail with [`INDEXER_UNSUPPORTED`](/docs/reference/errors/INDEXER_UNSUPPORTED), so `fallback` moves on to the next indexer. - Queries arrive validated: names normalized, addresses checksummed, the namespace resolved. - Return `null` from single-resource queries (`getName`, `getRecords`, …) when nothing exists. - Throw an ensforge error (e.g. `Errors.IndexerError`) to control how a failure is reported; anything else becomes [`INDEXER_UNAVAILABLE`](/docs/reference/errors/INDEXER_UNAVAILABLE). ```ts title="An adapter for an in-house API" import { defineIndexer } from "@ensforge/sdk/indexer" const inHouse = defineIndexer({ id: "in-house", getSubnames: async ({ name, cursor }, { signal }) => { const page = await api.subnames(name, cursor, { signal }) return { items: page.items, cursor: page.next, hasMore: page.next !== null, totalCount: null } }, }) ``` ```ts title="Trying it before bigname" import { Ensforge } from "@ensforge/sdk" import { bigname, fallback } from "@ensforge/sdk/indexer" const ens = Ensforge.create({ publicClient, indexer: fallback([inHouse, bigname()]) }) ``` ```ts title="A test double" import { defineIndexer } from "@ensforge/sdk/indexer" const indexer = defineIndexer({ id: "test", getName: async ({ name }) => (name === "nick.eth" ? fixture : null), }) ``` ### `fallback` [#fallback] Asks several indexers in order: each query goes to the first one that can answer it. ```ts function fallback(indexers: readonly Indexer[], options: { readonly on?: readonly FallbackReason[] | undefined } = {}): Indexer ``` Use to combine indexers with different coverage (bigname for Sepolia and verified reads, Goldsky for Basenames) or to keep reading when one is down. - The next indexer is asked when one is unavailable, rate limiting, behind, or does not serve the query or its namespace (`on` narrows this). Not found is an answer: it is not retried. - Every answer reports the indexer that gave it (`indexer`). - Cursors and `asOfToken`s are tagged with the indexer that issued them; follow-up pages and snapshot reads go back to that indexer only. - When every indexer fails, the last failure that was not [`INDEXER_UNSUPPORTED`](/docs/reference/errors/INDEXER_UNSUPPORTED) is reported. ```ts title="bigname first, Goldsky after" import { Ensforge } from "@ensforge/sdk" import { bigname, fallback, goldsky } from "@ensforge/sdk/indexer" const ens = Ensforge.create({ publicClient, indexer: fallback([bigname(), goldsky()]) }) ``` ```ts title="Only when the first is down" import { bigname, fallback, goldsky } from "@ensforge/sdk/indexer" const indexer = fallback([bigname(), goldsky()], { on: ["unavailable", "rateLimited"] }) ``` ```ts title="A self-hosted indexer first" import { bigname, fallback } from "@ensforge/sdk/indexer" const indexer = fallback([bigname({ url: "https://bigname.internal" }), bigname()]) ``` ### `goldsky` [#goldsky] Goldsky's ENS indexer (`ens-api.goldsky.com`), which serves bigname's API for ENS and Basenames. ```ts function goldsky(options: RestIndexerOptions = {}): Indexer ``` Use for Basenames (`*.base.eth`), or as a second indexer behind bigname on mainnet. - Mainnet only (ENS on chain 1, Basenames on Base); other chains need `url`. - Reads the latest state only: `at` and `finality: "safe" | "finalized"` fail with [`INDEXER_UNSUPPORTED`](/docs/reference/errors/INDEXER_UNSUPPORTED), as does `getResolvers`. - Answers carry fewer fields than bigname's (no verified records, subnames without expiry); missing fields are `null`. ```ts title="Basenames" import { Ensforge } from "@ensforge/sdk" import { goldsky, indexerActions } from "@ensforge/sdk/indexer" const ens = Ensforge.create({ publicClient, indexer: goldsky() }).extend(indexerActions()) const name = await ens.indexer.getName({ name: "jesse.base.eth" }) ``` ```ts title="Behind bigname" import { bigname, fallback, goldsky } from "@ensforge/sdk/indexer" const indexer = fallback([bigname(), goldsky()]) ``` ```ts title="With an API key header" import { goldsky } from "@ensforge/sdk/indexer" const indexer = goldsky({ headers: { "x-api-key": key } }) ``` ### `indexerActions` [#indexeractions] Adds the `indexer` actions to a client. ```ts function indexerActions() ``` ### `paginate` [#paginate] Iterates over every page of an indexer list, following `cursor` until the last page. ```ts async function* paginate( load: (options: options) => Promise>, options: options, ): AsyncGenerator, void, undefined> ``` Use to walk a whole list, such as a name's subnames or an address's names; `break` stops requesting further pages. ```ts title="Every subname of a name" import { paginate } from "@ensforge/sdk/indexer" for await (const page of paginate(ens.indexer.getSubnames, { name: "ens.eth", limit: 200 })) { render(page.items) } ``` ```ts title="Collecting names, at most 1,000" import { paginate } from "@ensforge/sdk/indexer" const names: string[] = [] for await (const page of paginate(ens.indexer.getNamesForAddress, { address })) { names.push(...page.items.map((item) => item.name)) if (names.length >= 1000) break } ``` ```ts title="With a standalone action" import { Actions } from "@ensforge/sdk" import { paginate } from "@ensforge/sdk/indexer" const pages = paginate( (options: Actions.indexer.getSubnames.Options) => Actions.indexer.getSubnames(ens, options), { name: "ens.eth" }, ) ``` ## Queries [#queries] ### `Query.Contract` [#querycontract] A contract on the client's chain unless `chainId` says otherwise. ```ts type Contract ``` | Field | Type | Description | | --- | --- | --- | | `address` | `Address` | | | `chainId` | `number` | | ### `Query.GetEvents` [#querygetevents] The query of `getEvents`. ```ts type GetEvents = HistoryFilters & { /** Only this naming system; every namespace the indexer serves when omitted. */ namespace?: Namespace | undefined; name?: string | undefined; address?: Address | undefined; resolver?: { readonly chainId: number; readonly address: Address } | undefined; /** Emitting contract. */ contract?: Address | undefined; registrationId?: string | undefined; fromBlock?: bigint | undefined; toBlock?: bigint | undefined; }; ``` | Field | Type | Description | | --- | --- | --- | | `limit` (optional) | `number` | Rows per page, 1–200. @default 50 | | `cursor` (optional) | `string` | The previous page's `cursor`. | | `includeTotal` (optional) | `boolean` | Count every row (`totalCount`); slower. | | `types` (optional) | `readonly EventType[]` | | | `excludeTypes` (optional) | `readonly EventType[]` | | | `recordKey` (optional) | `string` | Record key, e.g. `avatar`, `text:url` or `addr:60`. | | `from` (optional) | `bigint \| Date` | Inclusive time bounds (Unix seconds or dates). | | `to` (optional) | `bigint \| Date` | | | `order` (optional) | `"asc" \| "desc"` | Sort direction. | | `includeData` (optional) | `boolean` | Include each event's details (`data`, `action`). @default true | | `namespace` (optional) | `Namespace` | Only this naming system; every namespace the indexer serves when omitted. | | `name` (optional) | `string` | | | `address` (optional) | `Address` | | | `resolver` (optional) | `{ readonly chainId: number; readonly address: Address }` | | | `contract` (optional) | `Address` | Emitting contract. | | `registrationId` (optional) | `string` | | | `fromBlock` (optional) | `bigint` | | | `toBlock` (optional) | `bigint` | | ### `Query.GetHistory` [#querygethistory] The query of `getHistory`. ```ts type GetHistory = HistoryFilters & ( | { name: string; /** The naming system the name belongs to. */ namespace: Namespace; address?: undefined; /** Name events, registration events, or both. @default "both" */ scope?: "name" | "registration" | "both" | undefined; /** Also the registrations of its children. */ includeChildRegistrations?: boolean | undefined; } | { address: Address; /** Only this naming system; every namespace the indexer serves when omitted. */ namespace?: Namespace | undefined; name?: undefined; scope?: "name" | "registration" | "both" | undefined; /** @default ["owner", "manager", "roleHolder"] */ relation?: readonly ("owner" | "manager" | "roleHolder")[] | undefined; } ); ``` | Field | Type | Description | | --- | --- | --- | | `limit` (optional) | `number` | Rows per page, 1–200. @default 50 | | `cursor` (optional) | `string` | The previous page's `cursor`. | | `includeTotal` (optional) | `boolean` | Count every row (`totalCount`); slower. | | `types` (optional) | `readonly EventType[]` | | | `excludeTypes` (optional) | `readonly EventType[]` | | | `recordKey` (optional) | `string` | Record key, e.g. `avatar`, `text:url` or `addr:60`. | | `from` (optional) | `bigint \| Date` | Inclusive time bounds (Unix seconds or dates). | | `to` (optional) | `bigint \| Date` | | | `order` (optional) | `"asc" \| "desc"` | Sort direction. | | `includeData` (optional) | `boolean` | Include each event's details (`data`, `action`). @default true | | `name` (optional) | `string` | | | `namespace` (optional) | `Namespace` | The naming system the name belongs to. | | `address` (optional) | `undefined` | | | `scope` (optional) | `"name" \| "registration" \| "both"` | Name events, registration events, or both. @default "both" | ### `Query.GetName` [#querygetname] The query of `getName`. ```ts type GetName = Snapshot & { name: string; /** The naming system the name belongs to. */ namespace: Namespace; /** `verified` reads the answer on-chain through the indexer. @default "indexed" */ source?: "indexed" | "verified" | undefined; }; ``` | Field | Type | Description | | --- | --- | --- | | `at` (optional) | `{ readonly token: string } \| { readonly timestamp: bigint \| Date }` | Read at a snapshot: an earlier answer's `asOfToken`, or a time. | | `finality` (optional) | `"latest" \| "safe" \| "finalized"` | How settled the data must be: `latest`, `safe` or `finalized`. | | `name` | `string` | | | `namespace` | `Namespace` | The naming system the name belongs to. | | `source` (optional) | `"indexed" \| "verified"` | `verified` reads the answer on-chain through the indexer. @default "indexed" | ### `Query.GetNamesByExpiry` [#querygetnamesbyexpiry] The query of `getNamesByExpiry`. ```ts type GetNamesByExpiry = List & { /** The naming system the name belongs to. */ namespace: Namespace; expiresAfter?: bigint | Date | undefined; expiresBefore?: bigint | Date | undefined; /** Up to 32 disjoint expiry windows; results report the matching `windowIndex`. */ windows?: readonly Window[] | undefined; graceEndsAfter?: bigint | Date | undefined; graceEndsBefore?: bigint | Date | undefined; graceWindows?: readonly Window[] | undefined; authority?: Authority | readonly Authority[] | undefined; parent?: string | undefined; /** Field the rows are sorted by. */ sort?: "expiry" | "graceEnd" | undefined; /** Sort direction. */ order?: "asc" | "desc" | undefined; }; ``` | Field | Type | Description | | --- | --- | --- | | `limit` (optional) | `number` | Rows per page, 1–200. @default 50 | | `cursor` (optional) | `string` | The previous page's `cursor`. | | `includeTotal` (optional) | `boolean` | Count every row (`totalCount`); slower. | | `namespace` | `Namespace` | The naming system the name belongs to. | | `expiresAfter` (optional) | `bigint \| Date` | | | `expiresBefore` (optional) | `bigint \| Date` | | | `windows` (optional) | `readonly Window[]` | Up to 32 disjoint expiry windows; results report the matching `windowIndex`. | | `graceEndsAfter` (optional) | `bigint \| Date` | | | `graceEndsBefore` (optional) | `bigint \| Date` | | | `graceWindows` (optional) | `readonly Window[]` | | | `authority` (optional) | `Authority \| readonly Authority[]` | | | `parent` (optional) | `string` | | | `sort` (optional) | `"expiry" \| "graceEnd"` | Field the rows are sorted by. | | `order` (optional) | `"asc" \| "desc"` | Sort direction. | ### `Query.GetNamesForAddress` [#querygetnamesforaddress] The query of `getNamesForAddress`. ```ts type GetNamesForAddress = List & { address: Address; /** Every namespace the indexer serves when omitted. */ namespace?: Namespace | undefined; /** * Relations to list; `any` is owner, manager and role holder. `resolvesTo` and `formerOwner` * stand alone. @default "any" */ relation?: Relation | "any" | readonly Relation[] | undefined; /** Coin type for `resolvesTo`, or `evm` for every EVM chain. @default 60 */ coinType?: bigint | "evm" | undefined; /** Only direct children of this name. */ parent?: string | undefined; authority?: Authority | readonly Authority[] | undefined; /** Only names migrated to ENSv2 (or only not migrated). */ migrated?: boolean | undefined; /** Expiry bounds (Unix seconds or dates), with `formerOwner` only. */ expiresAfter?: bigint | Date | undefined; expiresBefore?: bigint | Date | undefined; search?: string | undefined; /** * Whether `search` matches from the start of a label (`prefix`) or anywhere (`contains`). * * @default "prefix" */ match?: "prefix" | "contains" | undefined; /** Field the rows are sorted by. */ sort?: "name" | "expiry" | "registered" | "created" | undefined; /** Sort direction. */ order?: "asc" | "desc" | undefined; /** One row per name, or per registration. @default "name" */ dedupe?: "name" | "registration" | undefined; }; ``` | Field | Type | Description | | --- | --- | --- | | `limit` (optional) | `number` | Rows per page, 1–200. @default 50 | | `cursor` (optional) | `string` | The previous page's `cursor`. | | `includeTotal` (optional) | `boolean` | Count every row (`totalCount`); slower. | | `address` | `Address` | | | `namespace` (optional) | `Namespace` | Every namespace the indexer serves when omitted. | | `relation` (optional) | `Relation \| "any" \| readonly Relation[]` | Relations to list; `any` is owner, manager and role holder. `resolvesTo` and `formerOwner` stand alone. @default "any" | | `coinType` (optional) | `bigint \| "evm"` | Coin type for `resolvesTo`, or `evm` for every EVM chain. @default 60 | | `parent` (optional) | `string` | Only direct children of this name. | | `authority` (optional) | `Authority \| readonly Authority[]` | | | `migrated` (optional) | `boolean` | Only names migrated to ENSv2 (or only not migrated). | | `expiresAfter` (optional) | `bigint \| Date` | Expiry bounds (Unix seconds or dates), with `formerOwner` only. | | `expiresBefore` (optional) | `bigint \| Date` | | | `search` (optional) | `string` | | | `match` (optional) | `"prefix" \| "contains"` | Whether `search` matches from the start of a label (`prefix`) or anywhere (`contains`). | | `sort` (optional) | `"name" \| "expiry" \| "registered" \| "created"` | Field the rows are sorted by. | | `order` (optional) | `"asc" \| "desc"` | Sort direction. | | `dedupe` (optional) | `"name" \| "registration"` | One row per name, or per registration. @default "name" | ### `Query.GetNamespace` [#querygetnamespace] The query of `getNamespace`. ```ts type GetNamespace ``` | Field | Type | Description | | --- | --- | --- | | `namespace` | `Namespace` | | ### `Query.GetPermissions` [#querygetpermissions] The query of `getPermissions`. ```ts type GetPermissions = List & { /** Only this naming system; every namespace the indexer serves when omitted. */ namespace?: Namespace | undefined; /** Include how each grant was obtained. */ includeLineage?: boolean | undefined; } & ( | { name: string; registrationId?: undefined; address?: undefined; registry?: undefined } | { registrationId: string; name?: undefined; address?: undefined; registry?: undefined } | { address: Address; name?: undefined; registrationId?: undefined; registry?: undefined } | { registry: { readonly chainId: number; readonly address: Address }; name?: undefined; registrationId?: undefined; address?: undefined; } ); ``` | Field | Type | Description | | --- | --- | --- | | `limit` (optional) | `number` | Rows per page, 1–200. @default 50 | | `cursor` (optional) | `string` | The previous page's `cursor`. | | `includeTotal` (optional) | `boolean` | Count every row (`totalCount`); slower. | | `namespace` (optional) | `Namespace` | Only this naming system; every namespace the indexer serves when omitted. | | `includeLineage` (optional) | `boolean` | Include how each grant was obtained. | | `name` (optional) | `string` | | | `registrationId` (optional) | `undefined` | | | `address` (optional) | `undefined` | | | `registry` (optional) | `undefined` | | ### `Query.GetPrimaryName` [#querygetprimaryname] The query of `getPrimaryName`. ```ts type GetPrimaryName ``` | Field | Type | Description | | --- | --- | --- | | `address` | `Address` | | | `coinType` (optional) | `bigint` | | | `namespace` (optional) | `Namespace` | Only this naming system; every namespace the indexer serves when omitted. | | `source` (optional) | `"indexed" \| "verified"` | Both, verified first, when omitted. | ### `Query.GetRecords` [#querygetrecords] The query of `getRecords`. ```ts type GetRecords = Snapshot & { name: string; /** The naming system the name belongs to. */ namespace: Namespace; /** Record keys (`avatar`, `text:url`, `addr:60`, `contenthash`); the inventory's when omitted. */ keys?: readonly string[] | undefined; /** `false` returns only the inventory, without values. @default true */ values?: boolean | undefined; /** @default "indexed" */ source?: "indexed" | "verified" | "auto" | undefined; /** Read the records the name has on this resolver instead of its current one. */ resolver?: { readonly chainId: number; readonly address: Address } | undefined; }; ``` | Field | Type | Description | | --- | --- | --- | | `at` (optional) | `{ readonly token: string } \| { readonly timestamp: bigint \| Date }` | Read at a snapshot: an earlier answer's `asOfToken`, or a time. | | `finality` (optional) | `"latest" \| "safe" \| "finalized"` | How settled the data must be: `latest`, `safe` or `finalized`. | | `name` | `string` | | | `namespace` | `Namespace` | The naming system the name belongs to. | | `keys` (optional) | `readonly string[]` | Record keys (`avatar`, `text:url`, `addr:60`, `contenthash`); the inventory's when omitted. | | `values` (optional) | `boolean` | `false` returns only the inventory, without values. @default true | | `source` (optional) | `"indexed" \| "verified" \| "auto"` | | | `resolver` (optional) | `{ readonly chainId: number; readonly address: Address }` | Read the records the name has on this resolver instead of its current one. | ### `Query.GetRegistry` [#querygetregistry] The query of `getRegistry`. ```ts type GetRegistry = Snapshot & Contract & { includeCounts?: boolean | undefined }; ``` | Field | Type | Description | | --- | --- | --- | | `at` (optional) | `{ readonly token: string } \| { readonly timestamp: bigint \| Date }` | Read at a snapshot: an earlier answer's `asOfToken`, or a time. | | `finality` (optional) | `"latest" \| "safe" \| "finalized"` | How settled the data must be: `latest`, `safe` or `finalized`. | | `address` | `Address` | | | `chainId` | `number` | | | `includeCounts` (optional) | `boolean` | | ### `Query.GetRegistryLabels` [#querygetregistrylabels] The query of `getRegistryLabels`. ```ts type GetRegistryLabels = List & Contract & { owner?: Address | undefined; excludeOwner?: Address | undefined }; ``` | Field | Type | Description | | --- | --- | --- | | `limit` (optional) | `number` | Rows per page, 1–200. @default 50 | | `cursor` (optional) | `string` | The previous page's `cursor`. | | `includeTotal` (optional) | `boolean` | Count every row (`totalCount`); slower. | | `address` | `Address` | | | `chainId` | `number` | | | `owner` (optional) | `Address` | | | `excludeOwner` (optional) | `Address` | | ### `Query.GetResolver` [#querygetresolver] The query of `getResolver`. ```ts type GetResolver = Snapshot & Contract & List; ``` | Field | Type | Description | | --- | --- | --- | | `at` (optional) | `{ readonly token: string } \| { readonly timestamp: bigint \| Date }` | Read at a snapshot: an earlier answer's `asOfToken`, or a time. | | `finality` (optional) | `"latest" \| "safe" \| "finalized"` | How settled the data must be: `latest`, `safe` or `finalized`. | | `address` | `Address` | | | `chainId` | `number` | | | `limit` (optional) | `number` | Rows per page, 1–200. @default 50 | | `cursor` (optional) | `string` | The previous page's `cursor`. | | `includeTotal` (optional) | `boolean` | Count every row (`totalCount`); slower. | ### `Query.GetResolverLinks` [#querygetresolverlinks] The query of `getResolverLinks`. ```ts type GetResolverLinks = Snapshot & Contract & List; ``` | Field | Type | Description | | --- | --- | --- | | `at` (optional) | `{ readonly token: string } \| { readonly timestamp: bigint \| Date }` | Read at a snapshot: an earlier answer's `asOfToken`, or a time. | | `finality` (optional) | `"latest" \| "safe" \| "finalized"` | How settled the data must be: `latest`, `safe` or `finalized`. | | `address` | `Address` | | | `chainId` | `number` | | | `limit` (optional) | `number` | Rows per page, 1–200. @default 50 | | `cursor` (optional) | `string` | The previous page's `cursor`. | | `includeTotal` (optional) | `boolean` | Count every row (`totalCount`); slower. | ### `Query.GetResolverRoles` [#querygetresolverroles] The query of `getResolverRoles`. ```ts type GetResolverRoles = Snapshot & Contract & List; ``` | Field | Type | Description | | --- | --- | --- | | `at` (optional) | `{ readonly token: string } \| { readonly timestamp: bigint \| Date }` | Read at a snapshot: an earlier answer's `asOfToken`, or a time. | | `finality` (optional) | `"latest" \| "safe" \| "finalized"` | How settled the data must be: `latest`, `safe` or `finalized`. | | `address` | `Address` | | | `chainId` | `number` | | | `limit` (optional) | `number` | Rows per page, 1–200. @default 50 | | `cursor` (optional) | `string` | The previous page's `cursor`. | | `includeTotal` (optional) | `boolean` | Count every row (`totalCount`); slower. | ### `Query.GetResolvers` [#querygetresolvers] The query of `getResolvers`. ```ts type GetResolvers = List & { roleHolder: Address; chainId?: number | undefined }; ``` | Field | Type | Description | | --- | --- | --- | | `limit` (optional) | `number` | Rows per page, 1–200. @default 50 | | `cursor` (optional) | `string` | The previous page's `cursor`. | | `includeTotal` (optional) | `boolean` | Count every row (`totalCount`); slower. | | `roleHolder` | `Address` | | | `chainId` (optional) | `number` | | ### `Query.GetStatus` [#querygetstatus] The query of `getStatus`. ```ts type GetStatus ``` ### `Query.GetSubnames` [#querygetsubnames] The query of `getSubnames`. ```ts type GetSubnames = List & { name: string; /** The naming system the name belongs to. */ namespace: Namespace; search?: string | undefined; /** Whether `search` matches from the start of a label (`prefix`) or anywhere (`contains`). */ match?: "prefix" | "contains" | undefined; /** * Field the rows are sorted by. * * @default "name" */ sort?: "name" | "expiry" | "registered" | undefined; /** Sort direction. */ order?: "asc" | "desc" | undefined; /** @default true */ includeExpired?: boolean | undefined; }; ``` | Field | Type | Description | | --- | --- | --- | | `limit` (optional) | `number` | Rows per page, 1–200. @default 50 | | `cursor` (optional) | `string` | The previous page's `cursor`. | | `includeTotal` (optional) | `boolean` | Count every row (`totalCount`); slower. | | `name` | `string` | | | `namespace` | `Namespace` | The naming system the name belongs to. | | `search` (optional) | `string` | | | `match` (optional) | `"prefix" \| "contains"` | Whether `search` matches from the start of a label (`prefix`) or anywhere (`contains`). | | `sort` (optional) | `"name" \| "expiry" \| "registered"` | Field the rows are sorted by. | | `order` (optional) | `"asc" \| "desc"` | Sort direction. | | `includeExpired` (optional) | `boolean` | | ### `Query.HistoryFilters` [#queryhistoryfilters] History filters shared by `getHistory` and `getEvents`. ```ts type HistoryFilters = List & { types?: readonly EventType[] | undefined; excludeTypes?: readonly EventType[] | undefined; /** Record key, e.g. `avatar`, `text:url` or `addr:60`. */ recordKey?: string | undefined; /** Inclusive time bounds (Unix seconds or dates). */ from?: bigint | Date | undefined; to?: bigint | Date | undefined; /** * Sort direction. * * @default "desc" */ order?: "asc" | "desc" | undefined; /** Include each event's details (`data`, `action`). @default true */ includeData?: boolean | undefined; }; ``` | Field | Type | Description | | --- | --- | --- | | `limit` (optional) | `number` | Rows per page, 1–200. @default 50 | | `cursor` (optional) | `string` | The previous page's `cursor`. | | `includeTotal` (optional) | `boolean` | Count every row (`totalCount`); slower. | | `types` (optional) | `readonly EventType[]` | | | `excludeTypes` (optional) | `readonly EventType[]` | | | `recordKey` (optional) | `string` | Record key, e.g. `avatar`, `text:url` or `addr:60`. | | `from` (optional) | `bigint \| Date` | Inclusive time bounds (Unix seconds or dates). | | `to` (optional) | `bigint \| Date` | | | `order` (optional) | `"asc" \| "desc"` | Sort direction. | | `includeData` (optional) | `boolean` | Include each event's details (`data`, `action`). @default true | ### `Query.List` [#querylist] Paging, on list routes. ```ts type List ``` | Field | Type | Description | | --- | --- | --- | | `limit` (optional) | `number` | Rows per page, 1–200. @default 50 | | `cursor` (optional) | `string` | The previous page's `cursor`. | | `includeTotal` (optional) | `boolean` | Count every row (`totalCount`); slower. | ### `Query.Lookup` [#querylookup] The query of `lookup`. ```ts type Lookup ``` | Field | Type | Description | | --- | --- | --- | | `inputs` | `readonly string[]` | Names and addresses, up to 1,000. | | `namespace` (optional) | `Namespace` | Only this naming system; every namespace the indexer serves when omitted. | | `profile` (optional) | `"feed" \| "detail"` | `detail` adds records and resolution. @default "feed" | ### `Query.Search` [#querysearch] The query of `search`. ```ts type Search = List & { query: string; /** Only this naming system; every namespace the indexer serves when omitted. */ namespace?: Namespace | undefined; /** * Whether `search` matches from the start of a label (`prefix`) or anywhere (`contains`). * * @default "prefix" */ match?: "prefix" | "contains" | undefined; }; ``` | Field | Type | Description | | --- | --- | --- | | `limit` (optional) | `number` | Rows per page, 1–200. @default 50 | | `cursor` (optional) | `string` | The previous page's `cursor`. | | `includeTotal` (optional) | `boolean` | Count every row (`totalCount`); slower. | | `query` | `string` | | | `namespace` (optional) | `Namespace` | Only this naming system; every namespace the indexer serves when omitted. | | `match` (optional) | `"prefix" \| "contains"` | Whether `search` matches from the start of a label (`prefix`) or anywhere (`contains`). | ### `Query.Snapshot` [#querysnapshot] Snapshot selection, on routes that read one snapshot (names, records, registries, resolvers). ```ts type Snapshot ``` | Field | Type | Description | | --- | --- | --- | | `at` (optional) | `{ readonly token: string } \| { readonly timestamp: bigint \| Date }` | Read at a snapshot: an earlier answer's `asOfToken`, or a time. | | `finality` (optional) | `"latest" \| "safe" \| "finalized"` | How settled the data must be: `latest`, `safe` or `finalized`. | ### `Query.Window` [#querywindow] A half-open window `[after, before)`, Unix seconds or dates. ```ts type Window ``` | Field | Type | Description | | --- | --- | --- | | `after` | `bigint \| Date` | | | `before` | `bigint \| Date` | | ## Types [#types] ### `Adapter` [#adapter] A custom adapter: an id and the queries it answers, as Promise functions. ```ts type Adapter = { readonly id: string; /** What distinguishes this indexer from others with the same id (see `Indexer.key`). */ readonly key?: string | undefined; } & { readonly [method in Method]?: ( query: Parameters[0], context: Context, ) => Promise>>; }; ``` | Field | Type | Description | | --- | --- | --- | | `id` | `string` | | | `key` (optional) | `string` | What distinguishes this indexer from others with the same id (see `Indexer.key`). | ### `AddressName` [#addressname] A name an address is related to. ```ts type AddressName = IndexedName & { readonly relations: readonly Relation[]; /** Whether it is the address's primary name. */ readonly isPrimary: boolean; readonly migratedAt: bigint | null; readonly recordCount: number | null; readonly subnameCount: number | null; }; ``` | Field | Type | Description | | --- | --- | --- | | `name` | `string` | Normalized name; unknown labels appear as `[labelhash]`. | | `displayName` | `string` | | | `namespace` | `string` | | | `node` | `Hex` | | | `status` | `NameStatus \| null` | | | `authority` | `Authority \| null` | | | `owner` | `Address \| null` | Token holder (ENSv2) or registrant; `null` when unowned or not reported. | | `manager` | `Address \| null` | ENSv1 registry owner (controller) when it differs in meaning from the holder. | | `registeredAt` | `bigint \| null` | Unix seconds of the current registration. Lineage rules differ between indexers. | | `createdAt` | `bigint \| null` | Unix seconds the name first appeared. | | `expiresAt` | `bigint \| null` | Unix seconds; `2^64 - 1` for names that never expire. | | `graceEndsAt` | `bigint \| null` | | | `expiryReason` | `"noExpiry" \| "notSet" \| "released" \| null` | Why `expiresAt` is `null`. | | `ensV1` | `EnsV1Facts \| null` | | | `relations` | `readonly Relation[]` | | | `isPrimary` | `boolean` | Whether it is the address's primary name. | | `migratedAt` | `bigint \| null` | | | `recordCount` | `number \| null` | | | `subnameCount` | `number \| null` | | ### `AnswerStatus` [#answerstatus] Outcome of one answer inside a result (a record, a primary name, a lookup input). ```ts type AnswerStatus = | "ok" | "notFound" | "invalidName" | "mismatch" | "unsupported" | "stale" | "failed"; ``` ### `Authority` [#authority] Which ENS protocol holds a name: `ensV0` is the pre-2020 registry, `ensV1` the current ENSv1 registry, `ensV2` an ENSv2 registry. ```ts type Authority = "ensV0" | "ensV1" | "ensV2"; ``` ### `ChainStatus` [#chainstatus] Indexing progress of one chain. ```ts type ChainStatus ``` | Field | Type | Description | | --- | --- | --- | | `status` | `"ready" \| "degraded" \| "stale"` | | | `indexed` | `bigint \| null` | | | `latest` | `bigint \| null` | | | `safe` | `bigint \| null` | | | `finalized` | `bigint \| null` | | | `lagBlocks` | `number \| null` | | | `lagSeconds` | `number \| null` | | ### `Completeness` [#completeness] How much of an answer the indexer could give. `partial` and `unsupported` come with a reason; a partial answer is never presented as complete. ```ts type Completeness = "full" | "partial" | "unsupported"; ``` ### `Context` [#context] What an adapter knows about the call besides its query. ```ts type Context ``` | Field | Type | Description | | --- | --- | --- | | `chainId` | `number` | Chain of the ensforge client, e.g. 1 for mainnet. | | `signal` | `AbortSignal` | Aborted when the call is cancelled. | ### `ContractRef` [#contractref] A contract on a chain. ```ts type ContractRef ``` | Field | Type | Description | | --- | --- | --- | | `chainId` | `number` | | | `address` | `Address` | | ### `Draft` [#draft] What an adapter returns for an answer type: the answer, with every [`Meta`](/docs/reference/sdk/indexers#meta) field optional. ensforge fills the missing ones (`completeness: "full"`, no snapshot) and sets `indexer` to the adapter id. ```ts type Draft = answer extends null ? null : Omit & Partial; ``` ### `EnsV1Facts` [#ensv1facts] ENSv1 facts about a name: its ENSv1 resolver and NameWrapper state. ```ts type EnsV1Facts ``` | Field | Type | Description | | --- | --- | --- | | `resolver` | `ContractRef \| null` | | | `expiresAt` | `bigint \| null` | | | `wrapperState` | `"wrapped" \| "emancipated" \| "locked" \| "lapsed" \| "unwrapped" \| "unknown" \| null` | | | `wrapperExpiresAt` | `bigint \| null` | | | `wrapperFuses` | `number \| null` | NameWrapper fuses as a bitmap; decode with `Fuse`. | ### `ExpiringName` [#expiringname] A name from `getNamesByExpiry`, with the window it matched. ```ts type ExpiringName = IndexedName & { /** Index into `windows` (or `graceWindows`) that matched. */ readonly windowIndex: number | null; }; ``` | Field | Type | Description | | --- | --- | --- | | `name` | `string` | Normalized name; unknown labels appear as `[labelhash]`. | | `displayName` | `string` | | | `namespace` | `string` | | | `node` | `Hex` | | | `status` | `NameStatus \| null` | | | `authority` | `Authority \| null` | | | `owner` | `Address \| null` | Token holder (ENSv2) or registrant; `null` when unowned or not reported. | | `manager` | `Address \| null` | ENSv1 registry owner (controller) when it differs in meaning from the holder. | | `registeredAt` | `bigint \| null` | Unix seconds of the current registration. Lineage rules differ between indexers. | | `createdAt` | `bigint \| null` | Unix seconds the name first appeared. | | `expiresAt` | `bigint \| null` | Unix seconds; `2^64 - 1` for names that never expire. | | `graceEndsAt` | `bigint \| null` | | | `expiryReason` | `"noExpiry" \| "notSet" \| "released" \| null` | Why `expiresAt` is `null`. | | `ensV1` | `EnsV1Facts \| null` | | | `windowIndex` | `number \| null` | Index into `windows` (or `graceWindows`) that matched. | ### `FallbackReason` [#fallbackreason] Failures after which `fallback` asks the next indexer. ```ts type FallbackReason = "unavailable" | "rateLimited" | "unsupported" | "behind"; ``` ### `IndexedEvent` [#indexedevent] One event from an indexer's history, in the same vocabulary as `event.*`. ```ts type IndexedEvent ``` | Field | Type | Description | | --- | --- | --- | | `id` | `string` | | | `type` | `EventType` | | | `action` | `EventAction \| null` | What happened; present when the event data was requested (`includeData`). | | `kind` | `string \| null` | Indexer event kind, e.g. `RegistrationGranted`. | | `name` | `string \| null` | The name the event is about; `null` when the indexer does not say. | | `namespace` | `string` | | | `subject` | `"name" \| "child" \| null` | Whether the event is about the name or one of its children. | | `registrationId` | `string \| null` | | | `contract` | `Address \| null` | | | `blockNumber` | `bigint \| null` | | | `timestamp` | `bigint \| null` | | | `transactionHash` | `Hex \| null` | | | `logIndex` | `number \| null` | | | `data` | `Readonly> \| null` | Event details with camelCase keys, when requested with `includeData`. | ### `IndexedName` [#indexedname] A name as lists return it. ```ts type IndexedName ``` | Field | Type | Description | | --- | --- | --- | | `name` | `string` | Normalized name; unknown labels appear as `[labelhash]`. | | `displayName` | `string` | | | `namespace` | `string` | | | `node` | `Hex` | | | `status` | `NameStatus \| null` | | | `authority` | `Authority \| null` | | | `owner` | `Address \| null` | Token holder (ENSv2) or registrant; `null` when unowned or not reported. | | `manager` | `Address \| null` | ENSv1 registry owner (controller) when it differs in meaning from the holder. | | `registeredAt` | `bigint \| null` | Unix seconds of the current registration. Lineage rules differ between indexers. | | `createdAt` | `bigint \| null` | Unix seconds the name first appeared. | | `expiresAt` | `bigint \| null` | Unix seconds; `2^64 - 1` for names that never expire. | | `graceEndsAt` | `bigint \| null` | | | `expiryReason` | `"noExpiry" \| "notSet" \| "released" \| null` | Why `expiresAt` is `null`. | | `ensV1` | `EnsV1Facts \| null` | | ### `IndexedNameDetail` [#indexednamedetail] One name in full. ```ts type IndexedNameDetail = IndexedName & { readonly chainId: number | null; /** Indexer handle for the current registration; opaque, differs between indexers. */ readonly registrationId: string | null; readonly tokenId: bigint | null; readonly resolver: ContractRef | null; /** ENSv2 registry for the name's children. */ readonly subregistry: ContractRef | null; /** The ETH address the name resolves to. */ readonly primaryAddress: Address | null; readonly migratedAt: bigint | null; readonly records: IndexedProfile | null; readonly recordCount: number | null; readonly subnameCount: number | null; }; ``` | Field | Type | Description | | --- | --- | --- | | `name` | `string` | Normalized name; unknown labels appear as `[labelhash]`. | | `displayName` | `string` | | | `namespace` | `string` | | | `node` | `Hex` | | | `status` | `NameStatus \| null` | | | `authority` | `Authority \| null` | | | `owner` | `Address \| null` | Token holder (ENSv2) or registrant; `null` when unowned or not reported. | | `manager` | `Address \| null` | ENSv1 registry owner (controller) when it differs in meaning from the holder. | | `registeredAt` | `bigint \| null` | Unix seconds of the current registration. Lineage rules differ between indexers. | | `createdAt` | `bigint \| null` | Unix seconds the name first appeared. | | `expiresAt` | `bigint \| null` | Unix seconds; `2^64 - 1` for names that never expire. | | `graceEndsAt` | `bigint \| null` | | | `expiryReason` | `"noExpiry" \| "notSet" \| "released" \| null` | Why `expiresAt` is `null`. | | `ensV1` | `EnsV1Facts \| null` | | | `chainId` | `number \| null` | | | `registrationId` | `string \| null` | Indexer handle for the current registration; opaque, differs between indexers. | | `tokenId` | `bigint \| null` | | | `resolver` | `ContractRef \| null` | | | `subregistry` | `ContractRef \| null` | ENSv2 registry for the name's children. | | `primaryAddress` | `Address \| null` | The ETH address the name resolves to. | | `migratedAt` | `bigint \| null` | | | `records` | `IndexedProfile \| null` | | | `recordCount` | `number \| null` | | | `subnameCount` | `number \| null` | | ### `IndexedPrimaryName` [#indexedprimaryname] An address's primary name from `getPrimaryName`. ```ts type IndexedPrimaryName ``` | Field | Type | Description | | --- | --- | --- | | `address` | `Address` | | | `coinType` | `number` | | | `namespace` | `string` | | | `name` | `string \| null` | The primary name: verified when the indexer verified it, otherwise indexed. | | `source` | `"indexed" \| "verified" \| null` | Which answer `name` came from. | | `answers` | `readonly PrimaryNameAnswer[]` | | ### `IndexedProfile` [#indexedprofile] A name's records as `getName` and `lookup` return them: values the indexer has seen. ```ts type IndexedProfile ``` | Field | Type | Description | | --- | --- | --- | | `texts` | `Readonly>` | | | `addresses` | `Readonly>` | Addresses by decimal coin type, encoded as the chain writes them. | | `contentHash` | `Hex \| null` | | | `name` | `string \| null` | Name record (ENSIP-3) of reverse names. | | `textKeys` | `readonly string[]` | Every text key ever set, including cleared ones. | | `coinTypes` | `readonly string[]` | Every coin type ever set, including cleared ones. | ### `IndexedRecords` [#indexedrecords] A name's records from `getRecords`. ```ts type IndexedRecords ``` | Field | Type | Description | | --- | --- | --- | | `namespace` | `string` | | | `resolver` | `ContractRef \| null` | | | `texts` | `Readonly>` | | | `addresses` | `Readonly>` | Addresses by decimal coin type. | | `contentHash` | `Hex \| null` | | | `answers` | `Readonly>` | Every answer by record key (`text:avatar`, `addr:60`, `contenthash`), including failures. | | `inventory` | `{ readonly keys: readonly string[]; readonly unsetKeys: readonly string[]; readonly unsupportedKeys: readonly string[]; } \| null` | Every record key the resolver has seen for the name. `keys` are set; `unsetKeys` were cleared; `unsupportedKeys` cannot be read through the indexer. | ### `IndexedRegistry` [#indexedregistry] An ENSv2 registry. ```ts type IndexedRegistry ``` | Field | Type | Description | | --- | --- | --- | | `chainId` | `number` | | | `address` | `Address` | | | `name` | `string \| null` | The name whose children it holds, when known. | | `parent` | `ContractRef \| null` | | | `createdAt` | `bigint \| null` | | | `createdBlockNumber` | `bigint \| null` | | | `createdTransactionHash` | `Hex \| null` | | | `counts` | `{ readonly labels: number \| null; readonly roles: number \| null; readonly events: number \| null; } \| null` | | | `referencedBy` | `readonly string[]` | Names whose subregistry pointer is this registry. | ### `IndexedResolver` [#indexedresolver] A resolver and the names bound to it. ```ts type IndexedResolver ``` | Field | Type | Description | | --- | --- | --- | | `chainId` | `number` | | | `address` | `Address` | | | `names` | `readonly string[]` | Names using this resolver, one page of them. | | `cursor` | `string \| null` | | | `hasMore` | `boolean` | | | `mirrors` | `ContractRef \| null` | ENSv1 registry this resolver mirrors, for ENSv1 compatibility resolvers. | ### `Indexer` [#indexer] An indexer ensforge reads through: `bigname()`, `goldsky()`, `fallback([...])` or `defineIndexer({...})`. Pass it to `Ensforge.create({ indexer })`. ```ts interface Indexer ``` | Field | Type | Description | | --- | --- | --- | | `id` | `string` | Adapter id, reported as `indexer` on every answer. | | `key` | `string` | The adapter and where it reads from, e.g. `bigname:https://bigname.internal`: two indexers with the same key answer alike, so caches (React's) can share their answers. | | `~ensforge/indexer` | `true` | | ### `IndexerActions` [#indexeractions-1] `indexer` actions bound to a client. ```ts type IndexerActions ``` | Field | Type | Description | | --- | --- | --- | | `indexer` | `{ /** Searches indexed ENS events by name, address, resolver, contract or block range. */ readonly getEvents: Bound; /** Reads the full history of a name, or of every name an address is related to. */ readonly getHistory: Bound; /** Reads one name from the indexer: owner, manager, expiry, resolver, records and protocol. */ readonly getName: Bound; /** Lists names by when they expire or leave their grace period. */ readonly getNamesByExpiry: Bound; /** Lists the names an address owns, manages, holds roles on, resolves to, or used to own. */ readonly getNamesForAddress: Bound; /** Reads what the indexer serves for a namespace: its networks and which features are complete. */ readonly getNamespace: Bound; /** Lists who can do what over a name, a registration, an account or an ENSv2 registry. */ readonly getPermissions: Bound; /** Reads an address's primary name from the indexer, verified on-chain when the indexer can. */ readonly getPrimaryName: Bound; /** Reads a name's records and its record inventory from the indexer. */ readonly getRecords: Bound; /** Reads an ENSv2 registry: the name it serves, its parent registry, when it was created and its counts. */ readonly getRegistry: Bound; /** Lists the labels of an ENSv2 registry, optionally only those an address holds or does not hold. */ readonly getRegistryLabels: Bound; /** Reads a resolver and one page of the names bound to it. */ readonly getResolver: Bound; /** Lists the names linked to record sets on an ENSv2 resolver. */ readonly getResolverLinks: Bound; /** Lists the role grants on an ENSv2 resolver. */ readonly getResolverRoles: Bound; /** Lists the ENSv2 resolvers on which an address holds roles. */ readonly getResolvers: Bound; /** Reads the indexer's health and how far each chain is indexed. */ readonly getStatus: Bound; /** Lists the direct subnames of a name. */ readonly getSubnames: Bound; /** Reads up to 1,000 names and addresses in one request. */ readonly lookup: Bound; /** Searches names by text. */ readonly search: Bound; }` | | ### `IndexerStatus` [#indexerstatus] An indexer's health. ```ts type IndexerStatus ``` | Field | Type | Description | | --- | --- | --- | | `status` | `"ready" \| "degraded" \| "stale"` | | | `chains` | `Readonly>` | | | `indexer` | `string` | | ### `LookupResult` [#lookupresult] One input's answer from `lookup`. ```ts type LookupResult ``` | Field | Type | Description | | --- | --- | --- | | `input` | `string` | | | `kind` | `"name" \| "address"` | | | `status` | `AnswerStatus` | | | `name` | `(IndexedNameDetail & { readonly isPrimary: boolean \| null }) \| null` | A name input, or an address's primary name. | | `names` | `readonly (IndexedNameDetail & { readonly isPrimary: boolean \| null })[]` | An address input's related names. | | `reason` | `string \| null` | | ### `Meta` [#meta] What every indexer answer carries besides its data. ```ts type Meta ``` | Field | Type | Description | | --- | --- | --- | | `asOf` | `Snapshot \| null` | Snapshot of the answer's main chain, or `null` when the indexer reports none. | | `snapshots` | `Readonly>` | Every chain the answer read, keyed by chain ID. | | `asOfToken` | `string \| null` | Pass back as `at: { token }` to read the same snapshot again (snapshot routes only). `null` when the indexer does not support snapshots. | | `completeness` | `Completeness` | | | `unsupportedReason` | `string \| null` | Why the answer is partial or unsupported. | | `unsupportedFields` | `readonly string[]` | Fields the indexer could not fill. | | `origin` | `"indexed" \| "verified" \| null` | Whether the indexer answered from its index or by an on-chain read. | | `indexer` | `string` | Id of the adapter that answered, e.g. `bigname`. | ### `Method` [#method] Name of an indexer query. ```ts type Method = keyof Methods; ``` ### `Methods` [#methods] Every query an adapter can answer, with its query and answer types. `null` answers mean "not found". ```ts type Methods ``` | Field | Type | Description | | --- | --- | --- | | `getName` | `(query: Query.GetName) => Result \| null` | | | `getNamesForAddress` | `(query: Query.GetNamesForAddress) => Page` | | | `getSubnames` | `(query: Query.GetSubnames) => Page` | | | `getHistory` | `(query: Query.GetHistory) => Page` | | | `getEvents` | `(query: Query.GetEvents) => Page` | | | `search` | `(query: Query.Search) => Page` | | | `lookup` | `(query: Query.Lookup) => Result<{ readonly results: readonly LookupResult[] }>` | | | `getNamesByExpiry` | `(query: Query.GetNamesByExpiry) => Page` | | | `getPrimaryName` | `(query: Query.GetPrimaryName) => Result` | | | `getRecords` | `(query: Query.GetRecords) => Result \| null` | | | `getPermissions` | `(query: Query.GetPermissions) => Page` | | | `getRegistry` | `(query: Query.GetRegistry) => Result \| null` | | | `getRegistryLabels` | `(query: Query.GetRegistryLabels) => Page` | | | `getResolver` | `(query: Query.GetResolver) => Result \| null` | | | `getResolverLinks` | `(query: Query.GetResolverLinks) => Page` | | | `getResolverRoles` | `(query: Query.GetResolverRoles) => Page` | | | `getResolvers` | `(query: Query.GetResolvers) => Page` | | | `getNamespace` | `(query: Query.GetNamespace) => Result \| null` | | | `getStatus` | `(query: Query.GetStatus) => IndexerStatus` | | ### `NameStatus` [#namestatus] A name's registration lifecycle. ```ts type NameStatus = "active" | "expired" | "released" | "unregistered"; ``` ### `Namespace` [#namespace] A naming system an indexer serves: ENS, or Basenames (`*.base.eth`, on Base). ```ts type Namespace = "ens" | "basenames"; ``` ### `NamespaceInfo` [#namespaceinfo] What an indexer serves for one namespace. ```ts type NamespaceInfo ``` | Field | Type | Description | | --- | --- | --- | | `namespace` | `string` | | | `capabilities` | `Readonly>` | Feature (e.g. `subnames`, `verified_records`) → completeness. | | `networks` | `readonly { readonly network: string; readonly chainId: number \| null; /** ENS protocol resolving on that network, and since which block. */ readonly protocol: "ensV1" \| "ensV2" \| null; readonly sinceBlock: bigint \| null; }[]` | | ### `Page` [#page] One page of a list, with its [`Meta`](/docs/reference/sdk/indexers#meta). ```ts type Page = Meta & { readonly items: readonly item[]; /** Pass as `cursor` for the next page; `null` on the last page. */ readonly cursor: string | null; readonly hasMore: boolean; /** Total across pages, when requested with `includeTotal` and the indexer can count. */ readonly totalCount: number | null; }; ``` | Field | Type | Description | | --- | --- | --- | | `asOf` | `Snapshot \| null` | Snapshot of the answer's main chain, or `null` when the indexer reports none. | | `snapshots` | `Readonly>` | Every chain the answer read, keyed by chain ID. | | `asOfToken` | `string \| null` | Pass back as `at: { token }` to read the same snapshot again (snapshot routes only). `null` when the indexer does not support snapshots. | | `completeness` | `Completeness` | | | `unsupportedReason` | `string \| null` | Why the answer is partial or unsupported. | | `unsupportedFields` | `readonly string[]` | Fields the indexer could not fill. | | `origin` | `"indexed" \| "verified" \| null` | Whether the indexer answered from its index or by an on-chain read. | | `indexer` | `string` | Id of the adapter that answered, e.g. `bigname`. | | `items` | `readonly item[]` | | | `cursor` | `string \| null` | Pass as `cursor` for the next page; `null` on the last page. | | `hasMore` | `boolean` | | | `totalCount` | `number \| null` | Total across pages, when requested with `includeTotal` and the indexer can count. | ### `PermissionRow` [#permissionrow] A permission one address holds over a name, registry or resolver. ```ts type PermissionRow ``` | Field | Type | Description | | --- | --- | --- | | `address` | `Address` | | | `name` | `string \| null` | | | `registrationId` | `string` | | | `powers` | `readonly string[]` | Powers in the indexer's vocabulary, e.g. `set_resolver`, `admin_renew`. | | `scope` | `string` | Where the grant applies: `registry`, `registration`, `resolver`, … | | `relation` | `"operator" \| "holder" \| null` | | | `wrapperState` | `"wrapped" \| "emancipated" \| "locked" \| null` | NameWrapper state the permission depends on. | | `lineage` | `Readonly> \| null` | | ### `PrimaryNameAnswer` [#primarynameanswer] One primary name answer. ```ts type PrimaryNameAnswer ``` | Field | Type | Description | | --- | --- | --- | | `source` | `"indexed" \| "verified"` | | | `status` | `AnswerStatus` | | | `name` | `string \| null` | | | `reason` | `string \| null` | | ### `RecordAnswer` [#recordanswer] One record answer from `getRecords`. ```ts type RecordAnswer ``` | Field | Type | Description | | --- | --- | --- | | `status` | `AnswerStatus` | | | `value` | `string \| null` | | | `reason` | `string \| null` | | ### `RegistryLabel` [#registrylabel] A label in an ENSv2 registry. ```ts type RegistryLabel = Subname & { readonly roleHolderCount: number | null; }; ``` | Field | Type | Description | | --- | --- | --- | | `name` | `string` | Normalized name; unknown labels appear as `[labelhash]`. | | `displayName` | `string` | | | `namespace` | `string` | | | `node` | `Hex` | | | `status` | `NameStatus \| null` | | | `authority` | `Authority \| null` | | | `owner` | `Address \| null` | Token holder (ENSv2) or registrant; `null` when unowned or not reported. | | `manager` | `Address \| null` | ENSv1 registry owner (controller) when it differs in meaning from the holder. | | `registeredAt` | `bigint \| null` | Unix seconds of the current registration. Lineage rules differ between indexers. | | `createdAt` | `bigint \| null` | Unix seconds the name first appeared. | | `expiresAt` | `bigint \| null` | Unix seconds; `2^64 - 1` for names that never expire. | | `graceEndsAt` | `bigint \| null` | | | `expiryReason` | `"noExpiry" \| "notSet" \| "released" \| null` | Why `expiresAt` is `null`. | | `ensV1` | `EnsV1Facts \| null` | | | `labelhash` | `Hex \| null` | | | `subnameCount` | `number \| null` | | | `subregistry` | `ContractRef \| null` | | | `roleHolderCount` | `number \| null` | | ### `Relation` [#relation] How an address relates to a name. ```ts type Relation = "owner" | "manager" | "roleHolder" | "resolvesTo" | "formerOwner"; ``` ### `ResolverLink` [#resolverlink] A name linked to a record set on an ENSv2 resolver. ```ts type ResolverLink ``` | Field | Type | Description | | --- | --- | --- | | `name` | `string` | | | `node` | `Hex` | | | `recordId` | `string` | | | `isDefault` | `boolean` | Whether it is the resolver's default record set. | | `blockNumber` | `bigint \| null` | | | `transactionHash` | `Hex \| null` | | ### `ResolverRole` [#resolverrole] A role grant on an ENSv2 resolver. ```ts type ResolverRole ``` | Field | Type | Description | | --- | --- | --- | | `address` | `Address` | | | `name` | `string \| null` | | | `registrationId` | `string` | | | `powers` | `readonly string[]` | | | `blockNumber` | `bigint \| null` | | ### `RestIndexerOptions` [#restindexeroptions] Connection options shared by the built-in REST indexers. ```ts type RestIndexerOptions ``` | Option | Type | Default | Description | | --- | --- | --- | --- | | `url` | `string` | the public host for the client's chain | Base URL of a server with the same API (self-hosted, a proxy). A version path (`/v1`) is added unless the URL ends with one. | | `headers` | `Readonly>` | | Extra request headers, e.g. an API key. | | `fetch` | `typeof fetch` | | `fetch` to send requests with. @default globalThis.fetch | | `timeout` | `number` | | Milliseconds per request before it is retried or fails. @default 15_000 | | `retryCount` | `number` | `2` | Retries of rate-limited, unavailable and timed-out requests; `Retry-After` is honoured. | ### `Result` [#result] One answer with its [`Meta`](/docs/reference/sdk/indexers#meta). ```ts type Result = data & Meta; ``` | Field | Type | Description | | --- | --- | --- | | `asOf` | `Snapshot \| null` | Snapshot of the answer's main chain, or `null` when the indexer reports none. | | `snapshots` | `Readonly>` | Every chain the answer read, keyed by chain ID. | | `asOfToken` | `string \| null` | Pass back as `at: { token }` to read the same snapshot again (snapshot routes only). `null` when the indexer does not support snapshots. | | `completeness` | `Completeness` | | | `unsupportedReason` | `string \| null` | Why the answer is partial or unsupported. | | `unsupportedFields` | `readonly string[]` | Fields the indexer could not fill. | | `origin` | `"indexed" \| "verified" \| null` | Whether the indexer answered from its index or by an on-chain read. | | `indexer` | `string` | Id of the adapter that answered, e.g. `bigname`. | ### `RoleHolderResolver` [#roleholderresolver] A resolver on which an address holds roles. ```ts type RoleHolderResolver = ContractRef & { readonly grantCount: number; readonly powers: readonly string[]; }; ``` | Field | Type | Description | | --- | --- | --- | | `chainId` | `number` | | | `address` | `Address` | | | `grantCount` | `number` | | | `powers` | `readonly string[]` | | ### `Snapshot` [#snapshot] The chain state an answer was read at. ```ts type Snapshot ``` | Field | Type | Description | | --- | --- | --- | | `chainId` | `number` | | | `blockNumber` | `bigint` | | | `blockHash` | `Hex` | | | `timestamp` | `bigint` | Unix seconds. | ### `Subname` [#subname] A direct child of a name. ```ts type Subname = IndexedName & { readonly labelhash: Hex | null; readonly subnameCount: number | null; readonly subregistry: ContractRef | null; }; ``` | Field | Type | Description | | --- | --- | --- | | `name` | `string` | Normalized name; unknown labels appear as `[labelhash]`. | | `displayName` | `string` | | | `namespace` | `string` | | | `node` | `Hex` | | | `status` | `NameStatus \| null` | | | `authority` | `Authority \| null` | | | `owner` | `Address \| null` | Token holder (ENSv2) or registrant; `null` when unowned or not reported. | | `manager` | `Address \| null` | ENSv1 registry owner (controller) when it differs in meaning from the holder. | | `registeredAt` | `bigint \| null` | Unix seconds of the current registration. Lineage rules differ between indexers. | | `createdAt` | `bigint \| null` | Unix seconds the name first appeared. | | `expiresAt` | `bigint \| null` | Unix seconds; `2^64 - 1` for names that never expire. | | `graceEndsAt` | `bigint \| null` | | | `expiryReason` | `"noExpiry" \| "notSet" \| "released" \| null` | Why `expiresAt` is `null`. | | `ensV1` | `EnsV1Facts \| null` | | | `labelhash` | `Hex \| null` | | | `subnameCount` | `number \| null` | | | `subregistry` | `ContractRef \| null` | | # migration.get > For the complete documentation index, see [llms.txt](https://ensforge.com/llms.txt). Reads whether an ENSv1 name can migrate to ENSv2, how, and what it becomes. Parameters, return value, errors and examples for migration.get in @ensforge/sdk. Source: https://ensforge.com/docs/reference/sdk/migration/get Reads whether an ENSv1 name can migrate to ENSv2, how, and what it becomes. ## When to use [#when-to-use] Use to drive a migration screen: route, blockers, resolver plan and the state after. ## Details [#details] - `status`: `eligible`, `blocked` (see `blockers`), `migrated` or `not-required` (already on ENSv2, or not registered). - `blockers` are checked for `account` (the client's account by default). - `resolver.plan` shows what [`migration.migrate`](/docs/reference/sdk/migration/migrate) does with the current resolver for the same `resolver` option. - With an indexer, `discovered` lists the records and subnames `migrate` carries over by default (read at the latest block). ## Signature [#signature] ```ts function get(client: Like, options: get.Options): Promise ``` Call it as `ens.migration.get(options)` on a client, or `Actions.migration.get(client, options)`. `migration.get.request(options)` builds a deferred read for `Actions.batch`. See [Look up many at once](/docs/sdk/look-up-many-at-once). In React, use [`useMigrationStatus`](/docs/reference/react/use-migration-status). ## Parameters [#parameters] | Option | Type | Default | Description | | --- | --- | --- | --- | | `name` (required) | `string` | | ENS name. Normalized automatically. | | `account` | `string` | | Account that would migrate. Defaults to the client's account. | | `resolver` | `"new" \| "owned" \| "keep" \| (string & {})` | | The `resolver` option `migrate` would get. | Also takes the [read options](/docs/reference/sdk/client#read-options). ## Returns [#returns] Resolves to `get.ReturnType`. Route, blockers, holder, resolver plan and the ENSv2 state after migrating. ## 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. | | [`UnsupportedError`](/docs/reference/errors/unsupported-error) | [`UNSUPPORTED_ON_DEPLOYMENT`](/docs/reference/errors/UNSUPPORTED_ON_DEPLOYMENT) | where ENSv2 is not deployed. | | [`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 name" const status = await ens.migration.get({ name: "alice.eth" }) ``` ```ts title="Checking a name with a standalone call" import { Actions } from "@ensforge/sdk" const status = await Actions.migration.get(publicClient, { name: "alice.eth" }) ``` ```ts title="Checking a name in an Effect program" import { Actions } from "@ensforge/sdk/effect" const status = yield* Actions.migration.get(ens, { name: "alice.eth" }) ``` ## Example response [#example-response] Recorded from Ethereum mainnet on 2026-11-18 at block 26443964. Values change as the chain does. ```ts await ens.migration.get({ name: "nick.eth" }) ``` ```json { "name": "nick.eth", "status": "migrated", "route": null, "blockers": [], "owner": null, "manager": null, "fuses": null, "expiry": null, "reservationExpiry": null, "resolver": { "current": null, "plan": "none" }, "after": { "registry": null, "subregistry": null, "expiry": null, "roles": [] }, "discovered": null } ``` ## See also [#see-also] - [`migration.migrate`](/docs/reference/sdk/migration/migrate) to migrate it # migration > For the complete documentation index, see [llms.txt](https://ensforge.com/llms.txt). List the 2 migration actions of @ensforge/sdk and whether each reads, writes or signs. Covers get, migrate. Covers get, migrate. Source: https://ensforge.com/docs/reference/sdk/migration Call them as `ens.migration.(options)` on a client, or `Actions.migration.(client, options)`. ## Reads [#reads] | Action | Description | | --- | --- | | [`get`](/docs/reference/sdk/migration/get) (batchable) | Reads whether an ENSv1 name can migrate to ENSv2, how, and what it becomes. | ## Writes [#writes] | Action | Description | | --- | --- | | [`migrate`](/docs/reference/sdk/migration/migrate) | Migrates one or more ENSv1 names to ENSv2, carrying their resolver records and subnames. | # migration.migrate > For the complete documentation index, see [llms.txt](https://ensforge.com/llms.txt). Migrates one or more ENSv1 names to ENSv2, carrying their resolver records and subnames. Options, result, errors and examples for migration.migrate. Source: https://ensforge.com/docs/reference/sdk/migration/migrate Migrates one or more ENSv1 names to ENSv2, carrying their resolver records and subnames. Resolves once the transaction is submitted. ## When to use [#when-to-use] Use to upgrade `.eth` names (unwrapped, wrapped or locked) and locked subnames to ENSv2. Use [`migrateSync`](/docs/reference/sdk/migration/migrate#wait-for-the-receipt-with-migratesync) to wait for the receipt. ## Details [#details] - Plan: renew names in grace (with `renew`) → create each name's resolver with its records, and UserRegistries for its subnames → recreate the subnames → transfer the tokens to the migration controllers (parents before locked children) → register a locked name's subnames in its WrapperRegistry → restore ENSv1 managers. - Direct token transfers from the holder: no approvals are needed. - By default a name on an ENS public resolver gets its own PermissionedResolver; custom resolvers are kept. `resolver: "owned"` uses the signer's shared resolver (the ENS app's). - Records and subnames are those given per name; otherwise, with an indexer, every record key it lists (values read on-chain) and the live subnames at every depth; without one, `allowIncompleteRecords` copies the common records. Locked names follow their fuses. - The sending account keeps no roles on a subname registry it deploys for someone else. - An interrupted migration can run again: existing resolvers and registries are reused. - ENSv2 drops ENSv1 subnames that are not recreated, and records left on an ENSv1 public resolver become read-only. Without an indexer, pass every record and subname to carry over. - Use [`migrateSync`](/docs/reference/sdk/migration/migrate#wait-for-the-receipt-with-migratesync) to also verify the migrated state. ## Signature [#signature] ```ts function migrate( client: Like, options: migrate.Options & Write.Options, ): Promise ``` Call it as `ens.migration.migrate(options)` on a client, or `Actions.migration.migrate(client, options)`. In React, use [`useMigrate`](/docs/reference/react/use-migrate). ## Parameters [#parameters] | Option | Type | Default | Description | | --- | --- | --- | --- | | `names` (required) | `NameInput \| readonly NameInput[]` | | Names to migrate: a name, or a name with its records and subnames. | | `resolver` | `"new" \| "owned" \| "keep" \| (string & {})` | `"new" for names on an ENS public resolver, "keep" otherwise` | `"new"`, `"owned"`, `"keep"` or a resolver address. | | `owner` | `string` | | ENSv2 owner of the names. Defaults to each token's holder. | | `allowIncompleteRecords` | `boolean` | | Copy the common records when a name's records are not given. | | `allowLeavingSubnames` | `boolean` | | Migrate even when a listed subname cannot be recreated. | | `preserveManager` | `boolean` | | Give each unwrapped name's ENSv1 manager `setResolver` and the record setter roles. | | `migrateParents` | `boolean` | | Migrate the ENSv1 parents of locked subnames first. | | `renew` | `{ readonly duration: bigint; readonly paymentToken?: PaymentToken \| undefined }` | | Renew names in their grace period first. | 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_RECORD_VALUE`](/docs/reference/errors/INVALID_RECORD_VALUE) | invalid input. | | [`MigrationError`](/docs/reference/errors/migration-error) | [`NOT_ELIGIBLE`](/docs/reference/errors/NOT_ELIGIBLE), [`ALREADY_MIGRATED`](/docs/reference/errors/ALREADY_MIGRATED), [`RECORDS_UNKNOWN`](/docs/reference/errors/RECORDS_UNKNOWN), [`NAME_NOT_LOCKED`](/docs/reference/errors/NAME_NOT_LOCKED) | a name cannot migrate as asked. | | [`NameStateError`](/docs/reference/errors/name-state-error) | [`NAME_LOCKED`](/docs/reference/errors/NAME_LOCKED) | the name is locked. | | [`UnsupportedError`](/docs/reference/errors/unsupported-error) | [`UNSUPPORTED_ON_DEPLOYMENT`](/docs/reference/errors/UNSUPPORTED_ON_DEPLOYMENT) | where ENSv2 is not deployed. | | [`UnauthorizedError`](/docs/reference/errors/unauthorized-error) | [`NOT_OWNER`](/docs/reference/errors/NOT_OWNER), [`FUSE_BURNED`](/docs/reference/errors/FUSE_BURNED) | the account may not move a token. | | [`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="Migrating a name with its profile" const { hash } = await ens.migration.migrate({ names: { name: "alice.eth", records: { texts: { url: "https://alice.dev" } }, subnames: ["pay"] } }) ``` ```ts title="Migrating a name with its profile with a standalone call" import { Actions } from "@ensforge/sdk" await Actions.migration.migrate(ens, { names: { name: "alice.eth", records: { texts: { url: "https://alice.dev" } }, subnames: ["pay"] } }) ``` ```ts title="Migrating a name with its profile in an Effect program" import { Actions } from "@ensforge/sdk/effect" yield* Actions.migration.migrate(ens, { names: { name: "alice.eth", records: { texts: { url: "https://alice.dev" } }, subnames: ["pay"] } }) ``` ## Plan methods [#plan-methods] Each method takes the same options as `migration.migrate` and sends nothing. See [Preview before sending](/docs/sdk/preview-before-sending). | Method | Description | | --- | --- | | `migration.migrate.prepare(options)` | Builds the plan without sending anything. | | `migration.migrate.simulate(options)` | Simulates the plan with `eth_call`, reporting each step. | | `migration.migrate.estimateGas(options)` | Estimates the gas and ETH the plan needs. | ## Wait for the receipt with `migrateSync` [#wait-for-the-receipt-with-migratesync] Migrates one or more ENSv1 names to ENSv2, carrying their resolver records and subnames. Resolves once the receipt is in. Use when the next step depends on the migration being on-chain; once every receipt is in, each name's ENSv2 owner, resolver, subregistry and copied records are checked against the plan. `migration.migrateSync` 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="Migrating a name with its profile and waiting" const { receipt } = await ens.migration.migrateSync({ names: { name: "alice.eth", records: { texts: { url: "https://alice.dev" } }, subnames: ["pay"] } }) ``` ```ts title="Waiting with a standalone call" import { Actions } from "@ensforge/sdk" await Actions.migration.migrateSync(ens, { names: { name: "alice.eth", records: { texts: { url: "https://alice.dev" } }, subnames: ["pay"] } }) ``` ```ts title="Waiting in an Effect program" import { Actions } from "@ensforge/sdk/effect" yield* Actions.migration.migrateSync(ens, { names: { name: "alice.eth", records: { texts: { url: "https://alice.dev" } }, subnames: ["pay"] } }) ``` ## See also [#see-also] - [`migration.get`](/docs/reference/sdk/migration/get) to check a name first # name.getLabel > For the complete documentation index, see [llms.txt](https://ensforge.com/llms.txt). Recovers a label from its labelhash through the ENSv2 LabelStore. Parameters, return value, errors and examples for name.getLabel in @ensforge/sdk. Source: https://ensforge.com/docs/reference/sdk/name/get-label Recovers a label from its labelhash through the ENSv2 LabelStore. ## When to use [#when-to-use] Use to display names that arrive as hashes, such as `[af2c…].eth` from events or indexers. ## Details [#details] - ENSv2 registries store every label they register, so this covers every ENSv2 name. - Returns `null` when the LabelStore has never seen the label. ## Signature [#signature] ```ts function getLabel(client: Like, options: getLabel.Options): Promise ``` Call it as `ens.name.getLabel(options)` on a client, or `Actions.name.getLabel(client, options)`. `name.getLabel.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 | | --- | --- | --- | --- | | `labelhash` (required) | `Hex` | | Keccak-256 hash of the label, as from `Name.labelhash`. | Also takes the [read options](/docs/reference/sdk/client#read-options). ## Returns [#returns] Resolves to `string | null`. The label, or `null` when unknown. ## Errors [#errors] | Error | Codes | When | | --- | --- | --- | | [`InvalidInputError`](/docs/reference/errors/invalid-input-error) | [`INVALID_RECORD_VALUE`](/docs/reference/errors/INVALID_RECORD_VALUE) | `labelhash` is not 32 bytes. | | [`UnsupportedError`](/docs/reference/errors/unsupported-error) | [`UNSUPPORTED_ON_DEPLOYMENT`](/docs/reference/errors/UNSUPPORTED_ON_DEPLOYMENT) | without an ENSv2 deployment. | | [`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="Recovering a label" const label = await ens.name.getLabel({ labelhash: "0x5d5727cb0fb76e4944eafb88ec9a3cf0b3c9025a4b2f947729137c5d7f84f68f" }) ``` ```ts title="Recovering with a bare viem client" import { Actions } from "@ensforge/sdk" const label = await Actions.name.getLabel(publicClient, { labelhash }) ``` ```ts title="Recovering in an Effect program" import { Actions } from "@ensforge/sdk/effect" const label = yield* Actions.name.getLabel(ens, { labelhash }) ``` ## Example response [#example-response] Recorded from Ethereum mainnet on 2026-11-18 at block 26443964. Values change as the chain does. ```ts await ens.name.getLabel({ labelhash: "0xaf2caa1c2ca1d027f1ac823b529d0a67cd144264b2789fa2ea4d63a67c7103cc" }) ``` ```json "vitalik" ``` # name.get > For the complete documentation index, see [llms.txt](https://ensforge.com/llms.txt). Reads the full state of a name across ENSv1 and ENSv2: where it lives, who owns it, its resolver, expiry and whether it can be registered or renewed. Source: https://ensforge.com/docs/reference/sdk/name/get Reads the full state of a name across ENSv1 and ENSv2: where it lives, who owns it, its resolver, expiry and whether it can be registered or renewed. ## When to use [#when-to-use] Use when a UI needs to know about a name: owner, expiry, grace period, availability, or which protocol to send writes to. ## Details [#details] - `kind` tells where the name lives (`v1-unwrapped`, `v1-wrapped`, `v2-native`, `v2-migrated`, `v2-reserved`, `available`); `protocol` is `v1` or `v2`. - Times come from the block the read runs at, not the local clock. - `inheritedResolver` is the resolver serving a name that has none of its own: a parent's wildcard or off-chain resolver, or the ENSv1 resolver behind the ENSv1 bridge. - Costs two batched RPC calls, whatever the name kind. A name without a resolver of its own that a parent's resolver serves costs one more (two behind the ENSv1 bridge). - `resolver` is the resolver set on the name itself. A name served only by a parent's wildcard or off-chain resolver (such as `jesse.base.eth`) has `resolver: null` and is in no registry, so it is `available` although it resolves: check `inheritedResolver`. ## Signature [#signature] ```ts function get(client: Like, options: get.Options): Promise ``` Call it as `ens.name.get(options)` on a client, or `Actions.name.get(client, options)`. `name.get.request(options)` builds a deferred read for `Actions.batch`. See [Look up many at once](/docs/sdk/look-up-many-at-once). In React, use [`useName`](/docs/reference/react/use-name). ## Parameters [#parameters] | Option | Type | Default | Description | | --- | --- | --- | --- | | `name` (required) | `string` | | ENS name to read. Normalized automatically. | Also takes the [read options](/docs/reference/sdk/client#read-options). ## Returns [#returns] Resolves to `NameState`. The name's full state. | Field | Type | Description | | --- | --- | --- | | `name` | `string` | The normalized name. | | `kind` | `NameKind` | | | `protocol` | `"v1" \| "v2"` | Protocol that controls the name. | | `status` | `NameStatus` | | | `owner` | `Address \| null` | Who ultimately controls the name: the ENSv2 token holder; on ENSv1 the NameWrapper token holder, the `.eth` registrant, or otherwise the registry owner. | | `manager` | `Address \| null` | ENSv1 registry owner of an unwrapped name (the ENS app's "manager"). | | `registrant` | `Address \| null` | ENSv1 `.eth` registrar token holder of an unwrapped second-level name. | | `registry` | `Address \| null` | Registry that holds the name: ENSv1 `ENSRegistry`, or the ENSv2 parent registry. | | `subregistry` | `Address \| null` | ENSv2 registry for the name's children. | | `resolver` | `Address \| null` | Resolver set on the name itself (not inherited from a parent). | | `inheritedResolver` | `Address \| null` | For a name without a resolver of its own, the resolver that serves it from an ancestor: a parent's ENSIP-10 wildcard or off-chain resolver, or, for an ENSv1 name ENSv2 serves through the ENSv1 bridge, the ENSv1 resolver behind it. `null` when the name has its own resolver or nothing serves it. A name only an inherited resolver serves is in no registry, so it can be `available` and still resolve. | | `expiry` | `bigint \| null` | Unix seconds when the registration ends, grace period excluded. `null` when it never expires. | | `gracePeriodEnd` | `bigint \| null` | Unix seconds when the `.eth` grace period ends. | | `tokenId` | `bigint \| null` | Token ID: ENSv2 registry token (changes on some role updates), NameWrapper or `.eth` registrar token. | | `resource` | `bigint \| null` | ENSv2 resource ID, stable across token changes. | | `ttl` | `bigint \| null` | ENSv1 registry TTL in seconds. | | `wrapped` | `boolean` | Whether the name is wrapped in the ENSv1 NameWrapper. | | `migrated` | `boolean` | Whether the name was migrated from ENSv1 to ENSv2. | | `reachable` | `boolean` | Whether ENSv2 resolution reaches the name. An ENSv1 name is reachable when the resolver ENSv2 resolution finds for it reads ENSv1: the ENSv1 bridge (a reservation, a migrated parent that kept it as resolver, an emancipated child of a locked parent) or a DNS TLD resolver. `false` when ENSv2 answers from elsewhere, e.g. a parent that migrated without the name or a `.eth` name without a reservation: its ENSv1 records no longer resolve, nor do its children's. Always `true` for ENSv2 names and on deployments without ENSv2. | | `available` | `boolean` | Whether the name can be registered now. | | `renewable` | `boolean` | Whether the name can be renewed now (`.eth` second-level names when registered or in grace). | ## Errors [#errors] | Error | Codes | When | | --- | --- | --- | | [`InvalidInputError`](/docs/reference/errors/invalid-input-error) | [`INVALID_NAME`](/docs/reference/errors/INVALID_NAME) | the name is invalid or the root. | | [`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="Showing a renewal banner" const state = await ens.name.get({ name: "alice.eth" }) if (state.status === "grace") showRenewBanner(state.gracePeriodEnd) ``` ```ts title="Reading with a bare viem client" import { Actions } from "@ensforge/sdk" const { owner, expiry } = await Actions.name.get(publicClient, { name: "nick.eth" }) ``` ```ts title="Reading in an Effect program" import { Actions } from "@ensforge/sdk/effect" const state = yield* Actions.name.get(ens, { name: "nick.eth" }) ``` ## Example response [#example-response] Recorded from Ethereum mainnet on 2026-11-18 at block 26443964. Values change as the chain does. ```ts await ens.name.get({ name: "nick.eth" }) ``` ```json { "name": "nick.eth", "kind": "v2-migrated", "protocol": "v2", "status": "registered", "owner": "0xb8c2C29ee19D8307cb7255e1Cd9CbDE883A267d5", "manager": null, "registrant": null, "registry": "0xf60aba43E1f7F3DAB1186Ff03B561401C9Df85E2", "subregistry": "0x02cA46F62f6C9F655364bf9Fd4f11Fb8f01C5753", "resolver": "0xF4f1007EA430848F2fAd60e405A54Fc100fEc341", "expiry": "2051983306n", "gracePeriodEnd": "2054402506n", "tokenId": "42219085255511335250589442208301538195142221433306354426240614732610656010240n", "resource": "42219085255511335250589442208301538195142221433306354426240614732610656010240n", "ttl": null, "wrapped": false, "migrated": true, "available": false, "renewable": true, "reachable": true, "inheritedResolver": null } ``` ## See also [#see-also] - [`resolver.get`](/docs/reference/sdk/resolver/get) to describe the resolver - [`name.transfer`](/docs/reference/sdk/name/transfer) to send a name # name > For the complete documentation index, see [llms.txt](https://ensforge.com/llms.txt). List the 6 name actions of @ensforge/sdk and whether each reads, writes or signs. Covers get, getLabel, reclaim, setManager, setTtl, transfer. Source: https://ensforge.com/docs/reference/sdk/name Call them as `ens.name.(options)` on a client, or `Actions.name.(client, options)`. ## Reads [#reads] | Action | Description | | --- | --- | | [`get`](/docs/reference/sdk/name/get) (batchable) | Reads the full state of a name across ENSv1 and ENSv2: where it lives, who owns it, its resolver, expiry and whether it can be registered or renewed. | | [`getLabel`](/docs/reference/sdk/name/get-label) (batchable) | Recovers a label from its labelhash through the ENSv2 LabelStore. | ## Writes [#writes] | Action | Description | | --- | --- | | [`reclaim`](/docs/reference/sdk/name/reclaim) | Resets the ENSv1 registry owner (manager) of an unwrapped `.eth` name, as its registrant. | | [`setManager`](/docs/reference/sdk/name/set-manager) | Sets the ENSv1 manager (registry owner) of a name. | | [`setTtl`](/docs/reference/sdk/name/set-ttl) | Sets the ENSv1 registry TTL of a name. | | [`transfer`](/docs/reference/sdk/name/transfer) | Sends a name to another account and resolves once the transaction is submitted. | # name.reclaim > For the complete documentation index, see [llms.txt](https://ensforge.com/llms.txt). Resets the ENSv1 registry owner (manager) of an unwrapped .eth name, as its registrant. Options, result, errors and examples for name.reclaim. Source: https://ensforge.com/docs/reference/sdk/name/reclaim Resets the ENSv1 registry owner (manager) of an unwrapped `.eth` name, as its registrant. Resolves once the transaction is submitted. ## When to use [#when-to-use] Use to take over the manager after receiving a `.eth` registrar token, or to repair a lost manager. Use [`reclaimSync`](/docs/reference/sdk/name/reclaim#wait-for-the-receipt-with-reclaimsync) to wait for the receipt. ## Details [#details] - Only the registrar token holder (registrant) can reclaim. - `owner` defaults to the signing account. ## Signature [#signature] ```ts function reclaim( client: Like, options: reclaim.Options & Write.Options, ): Promise ``` Call it as `ens.name.reclaim(options)` on a client, or `Actions.name.reclaim(client, options)`. ## Parameters [#parameters] | Option | Type | Default | Description | | --- | --- | --- | --- | | `name` (required) | `string` | | ENS name. Normalized automatically. | | `owner` | `string` | the signing account | New registry 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_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_RESERVED`](/docs/reference/errors/NAME_RESERVED), [`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) | wrapped, ENSv2 and non-`.eth` names. | | [`UnauthorizedError`](/docs/reference/errors/unauthorized-error) | [`NOT_OWNER`](/docs/reference/errors/NOT_OWNER) | the account is not the registrant. | | [`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="Reclaiming a name" const { hash } = await ens.name.reclaim({ name: "alice.eth" }) ``` ```ts title="Reclaiming a name with a standalone call" import { Actions } from "@ensforge/sdk" await Actions.name.reclaim(ens, { name: "alice.eth" }) ``` ```ts title="Reclaiming a name in an Effect program" import { Actions } from "@ensforge/sdk/effect" yield* Actions.name.reclaim(ens, { name: "alice.eth" }) ``` ## Plan methods [#plan-methods] Each method takes the same options as `name.reclaim` and sends nothing. See [Preview before sending](/docs/sdk/preview-before-sending). | Method | Description | | --- | --- | | `name.reclaim.prepare(options)` | Builds the plan without sending anything. | | `name.reclaim.simulate(options)` | Simulates the plan with `eth_call`, reporting each step. | | `name.reclaim.estimateGas(options)` | Estimates the gas and ETH the plan needs. | ## Wait for the receipt with `reclaimSync` [#wait-for-the-receipt-with-reclaimsync] Resets the ENSv1 registry owner (manager) of an unwrapped `.eth` name, as its registrant. Resolves once the receipt is in. Use when the next step depends on the change being on-chain. `name.reclaimSync` 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="Reclaiming a name and waiting" const { receipt } = await ens.name.reclaimSync({ name: "alice.eth" }) ``` ```ts title="Waiting with a standalone call" import { Actions } from "@ensforge/sdk" await Actions.name.reclaimSync(ens, { name: "alice.eth" }) ``` ```ts title="Waiting in an Effect program" import { Actions } from "@ensforge/sdk/effect" yield* Actions.name.reclaimSync(ens, { name: "alice.eth" }) ``` ## See also [#see-also] - [`name.get`](/docs/reference/sdk/name/get) to read the name's current state # name.setManager > For the complete documentation index, see [llms.txt](https://ensforge.com/llms.txt). Sets the ENSv1 manager (registry owner) of a name. Parameters, return value, errors and examples for name.setManager in @ensforge/sdk. Source: https://ensforge.com/docs/reference/sdk/name/set-manager Sets the ENSv1 manager (registry owner) of a name. Resolves once the transaction is submitted. ## When to use [#when-to-use] Use to let another account edit records and subnames while keeping ownership. Use [`setManagerSync`](/docs/reference/sdk/name/set-manager#wait-for-the-receipt-with-setmanagersync) to wait for the receipt. ## Details [#details] - Unwrapped `.eth` names: the registrant reclaims to the new manager; a manager who is not the registrant changes the registry owner directly. - Other unwrapped ENSv1 names change their registry owner. - Wrapped and ENSv2 names have no manager; ENSv2 uses roles instead. ## Signature [#signature] ```ts function setManager( client: Like, options: setManager.Options & Write.Options, ): Promise ``` Call it as `ens.name.setManager(options)` on a client, or `Actions.name.setManager(client, options)`. ## Parameters [#parameters] | Option | Type | Default | Description | | --- | --- | --- | --- | | `name` (required) | `string` | | ENS name. Normalized automatically. | | `manager` (required) | `string` | | New manager 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_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_RESERVED`](/docs/reference/errors/NAME_RESERVED), [`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) | wrapped and ENSv2 names. | | [`UnauthorizedError`](/docs/reference/errors/unauthorized-error) | [`NOT_OWNER`](/docs/reference/errors/NOT_OWNER) | the account is neither registrant nor manager. | | [`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="Setting a manager" const { hash } = await ens.name.setManager({ name: "alice.eth", manager: "0xB0b0000000000000000000000000000000000000" }) ``` ```ts title="Setting a manager with a standalone call" import { Actions } from "@ensforge/sdk" await Actions.name.setManager(ens, { name: "alice.eth", manager: "0xB0b0000000000000000000000000000000000000" }) ``` ```ts title="Setting a manager in an Effect program" import { Actions } from "@ensforge/sdk/effect" yield* Actions.name.setManager(ens, { name: "alice.eth", manager: "0xB0b0000000000000000000000000000000000000" }) ``` ## Plan methods [#plan-methods] Each method takes the same options as `name.setManager` and sends nothing. See [Preview before sending](/docs/sdk/preview-before-sending). | Method | Description | | --- | --- | | `name.setManager.prepare(options)` | Builds the plan without sending anything. | | `name.setManager.simulate(options)` | Simulates the plan with `eth_call`, reporting each step. | | `name.setManager.estimateGas(options)` | Estimates the gas and ETH the plan needs. | ## Wait for the receipt with `setManagerSync` [#wait-for-the-receipt-with-setmanagersync] Sets the ENSv1 manager (registry owner) of a name. Resolves once the receipt is in. Use when the next step depends on the change being on-chain. `name.setManagerSync` 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="Setting a manager and waiting" const { receipt } = await ens.name.setManagerSync({ name: "alice.eth", manager: "0xB0b0000000000000000000000000000000000000" }) ``` ```ts title="Waiting with a standalone call" import { Actions } from "@ensforge/sdk" await Actions.name.setManagerSync(ens, { name: "alice.eth", manager: "0xB0b0000000000000000000000000000000000000" }) ``` ```ts title="Waiting in an Effect program" import { Actions } from "@ensforge/sdk/effect" yield* Actions.name.setManagerSync(ens, { name: "alice.eth", manager: "0xB0b0000000000000000000000000000000000000" }) ``` ## See also [#see-also] - [`name.get`](/docs/reference/sdk/name/get) to read the name's current state # name.setTtl > For the complete documentation index, see [llms.txt](https://ensforge.com/llms.txt). Sets the ENSv1 registry TTL of a name. Parameters, return value, errors and examples for name.setTtl in @ensforge/sdk. Errors and examples for name.setTtl. Source: https://ensforge.com/docs/reference/sdk/name/set-ttl Sets the ENSv1 registry TTL of a name. Resolves once the transaction is submitted. ## When to use [#when-to-use] Use to change how long resolvers may cache the name's records. Use [`setTtlSync`](/docs/reference/sdk/name/set-ttl#wait-for-the-receipt-with-setttlsync) to wait for the receipt. ## Details [#details] - Wrapped names change their TTL through the NameWrapper. - ENSv2 has no registry TTL. ## Signature [#signature] ```ts function setTtl( client: Like, options: setTtl.Options & Write.Options, ): Promise ``` Call it as `ens.name.setTtl(options)` on a client, or `Actions.name.setTtl(client, options)`. ## Parameters [#parameters] | Option | Type | Default | Description | | --- | --- | --- | --- | | `name` (required) | `string` | | ENS name. Normalized automatically. | | `ttl` (required) | `bigint` | | TTL in seconds. | 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_RECORD_VALUE`](/docs/reference/errors/INVALID_RECORD_VALUE) | invalid input. | | [`NameStateError`](/docs/reference/errors/name-state-error) | [`NAME_EXPIRED`](/docs/reference/errors/NAME_EXPIRED), [`NAME_RESERVED`](/docs/reference/errors/NAME_RESERVED), [`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. | | [`UnauthorizedError`](/docs/reference/errors/unauthorized-error) | [`NOT_OWNER`](/docs/reference/errors/NOT_OWNER), [`FUSE_BURNED`](/docs/reference/errors/FUSE_BURNED) | the account may not change 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="Setting a TTL" const { hash } = await ens.name.setTtl({ name: "alice.eth", ttl: 3600n }) ``` ```ts title="Setting a TTL with a standalone call" import { Actions } from "@ensforge/sdk" await Actions.name.setTtl(ens, { name: "alice.eth", ttl: 3600n }) ``` ```ts title="Setting a TTL in an Effect program" import { Actions } from "@ensforge/sdk/effect" yield* Actions.name.setTtl(ens, { name: "alice.eth", ttl: 3600n }) ``` ## Plan methods [#plan-methods] Each method takes the same options as `name.setTtl` and sends nothing. See [Preview before sending](/docs/sdk/preview-before-sending). | Method | Description | | --- | --- | | `name.setTtl.prepare(options)` | Builds the plan without sending anything. | | `name.setTtl.simulate(options)` | Simulates the plan with `eth_call`, reporting each step. | | `name.setTtl.estimateGas(options)` | Estimates the gas and ETH the plan needs. | ## Wait for the receipt with `setTtlSync` [#wait-for-the-receipt-with-setttlsync] Sets the ENSv1 registry TTL of a name. Resolves once the receipt is in. Use when the next step depends on the change being on-chain. `name.setTtlSync` 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="Setting a TTL and waiting" const { receipt } = await ens.name.setTtlSync({ name: "alice.eth", ttl: 3600n }) ``` ```ts title="Waiting with a standalone call" import { Actions } from "@ensforge/sdk" await Actions.name.setTtlSync(ens, { name: "alice.eth", ttl: 3600n }) ``` ```ts title="Waiting in an Effect program" import { Actions } from "@ensforge/sdk/effect" yield* Actions.name.setTtlSync(ens, { name: "alice.eth", ttl: 3600n }) ``` ## See also [#see-also] - [`name.get`](/docs/reference/sdk/name/get) to read the name's current state # name.transfer > For the complete documentation index, see [llms.txt](https://ensforge.com/llms.txt). Sends a name to another account and resolves once the transaction is submitted. Options, result, errors and examples for name.transfer. Source: https://ensforge.com/docs/reference/sdk/name/transfer Sends a name to another account and resolves once the transaction is submitted. ## When to use [#when-to-use] Use to give a name away or move it between your own accounts. Use [`transferSync`](/docs/reference/sdk/name/transfer#wait-for-the-receipt-with-transfersync) to wait for the receipt. ## Details [#details] - ENSv2 names move their registry token. With `unsafe`, the transfer also succeeds while other accounts still hold roles on the name. - Wrapped ENSv1 names move their NameWrapper token. - Unwrapped `.eth` names: `role: "owner"` (default) moves the registrar token and the registry ownership (manager); `role: "registrant"` moves only the registrar token. - Other unwrapped ENSv1 names change their registry owner. - Expired, reserved and unregistered names cannot be transferred. - ENSv2: roles on the name's PermissionedResolver stay with the sender, who can still edit its records (the plan carries a `RECORD_CONTROL_RETAINED` warning). `records: "handover"` grants them to the recipient and revokes the sender's in the same step; it is refused for the sender's shared `"owned"` resolver, whose roles cover other names. ## Signature [#signature] ```ts function transfer( client: Like, options: transfer.Options & Write.Options, ): Promise ``` Call it as `ens.name.transfer(options)` on a client, or `Actions.name.transfer(client, options)`. In React, use [`useTransferName`](/docs/reference/react/use-transfer-name). ## Parameters [#parameters] | Option | Type | Default | Description | | --- | --- | --- | --- | | `name` (required) | `string` | | Name to send. Normalized automatically. | | `to` (required) | `string` | | Recipient address. | | `role` | `"owner" \| "registrant"` | `"owner"` | For unwrapped `.eth` names: `owner` moves the registrar token and the manager, `registrant` moves only the registrar token. | | `unsafe` | `boolean` | `false` | ENSv2 only: transfer even while other accounts hold roles on the name. | | `records` | `"keep" \| "handover"` | `"keep"` | ENSv2: what happens to the sender's roles on the name's PermissionedResolver. | 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_RESERVED`](/docs/reference/errors/NAME_RESERVED), [`NAME_NOT_REGISTERED`](/docs/reference/errors/NAME_NOT_REGISTERED) | the name cannot be sent. | | [`NameStateError`](/docs/reference/errors/name-state-error) | [`NAME_UNREACHABLE`](/docs/reference/errors/NAME_UNREACHABLE) | ENSv2 resolution no longer reaches the name. | | [`NameStateError`](/docs/reference/errors/name-state-error) | [`REGISTRY_NOT_EMANCIPATED`](/docs/reference/errors/REGISTRY_NOT_EMANCIPATED) | the name's registry is not emancipated and `unsafe` is not set. | | [`UnauthorizedError`](/docs/reference/errors/unauthorized-error) | [`NOT_OWNER`](/docs/reference/errors/NOT_OWNER), [`TRANSFER_DISALLOWED`](/docs/reference/errors/TRANSFER_DISALLOWED) | the account may not send it, or the recipient (an HCA) refuses it. | | [`UnsupportedError`](/docs/reference/errors/unsupported-error) | [`UNSUPPORTED_PROTOCOL`](/docs/reference/errors/UNSUPPORTED_PROTOCOL) | `role: "registrant"` on names without a registrant. | | [`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="Sending a name" const { hash } = await ens.name.transfer({ name: "alice.eth", to: "0xB0b0000000000000000000000000000000000000" }) ``` ```ts title="Moving only the registrar token" import { Actions } from "@ensforge/sdk" await Actions.name.transfer(ens, { name: "alice.eth", to: bob, role: "registrant" }) ``` ```ts title="Sending in an Effect program" import { Actions } from "@ensforge/sdk/effect" const { hash } = yield* Actions.name.transfer(ens, { name: "alice.eth", to: bob }) ``` ## Plan methods [#plan-methods] Each method takes the same options as `name.transfer` and sends nothing. See [Preview before sending](/docs/sdk/preview-before-sending). | Method | Description | | --- | --- | | `name.transfer.prepare(options)` | Builds the plan without sending anything. | | `name.transfer.simulate(options)` | Simulates the plan with `eth_call`, reporting each step. | | `name.transfer.estimateGas(options)` | Estimates the gas and ETH the plan needs. | ## Wait for the receipt with `transferSync` [#wait-for-the-receipt-with-transfersync] Sends a name to another account and resolves once the receipt is in. Use when the next step depends on the new owner being on-chain. `name.transferSync` 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="Sending and waiting" const { receipt } = await ens.name.transferSync({ name: "alice.eth", to: bob }) ``` ```ts title="Waiting with a standalone call" import { Actions } from "@ensforge/sdk" await Actions.name.transferSync(ens, { name: "alice.eth", to: bob }) ``` ```ts title="Waiting in an Effect program" import { Actions } from "@ensforge/sdk/effect" yield* Actions.name.transferSync(ens, { name: "alice.eth", to: bob }) ``` ## See also [#see-also] - [`name.get`](/docs/reference/sdk/name/get) to read the current owner # permission.check > For the complete documentation index, see [llms.txt](https://ensforge.com/llms.txt). Checks whether an account may perform one operation on an ENS name, and lists exactly what it lacks when it may not. Errors and examples for permission.check. Source: https://ensforge.com/docs/reference/sdk/permission/check Checks whether an account may perform one operation on an ENS name, and lists exactly what it lacks when it may not. ## When to use [#when-to-use] Use to explain to a user why a change is not possible, or which role or approval to request. ## Details [#details] - `via` says how the account is allowed: owner, operator, approved, delegate, roles or anyone. - `missing` lists ownership or approvals, roles on a resource, or what blocks the change for everyone (a burned fuse, the name's status, a transfer rule). - Writes use the same engine to explain failed simulations as `UnauthorizedError`. ## Signature [#signature] ```ts function check(client: Like, options: check.Options): Promise ``` Call it as `ens.permission.check(options)` on a client, or `Actions.permission.check(client, options)`. `permission.check.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. | | `operation` (required) | `Operation` | | The operation to check. | | `account` | `string` | the client's account | Account to check. | Also takes the [read options](/docs/reference/sdk/client#read-options). ## Returns [#returns] Resolves to `PermissionCheck`. Whether it is allowed, how, and what is missing. | Field | Type | Description | | --- | --- | --- | | `allowed` | `boolean \| null` | `null` when the contract's permission model is unknown (a custom resolver). | | `via` | `Authority \| null` | | | `contract` | `Address \| null` | Contract that enforces the operation. | | `resource` | `bigint \| null` | EAC resource checked, for role-based contracts. | | `missing` | `readonly UnauthorizedError.Requirement[]` | | ## 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_COIN_TYPE`](/docs/reference/errors/INVALID_COIN_TYPE) | invalid input. | | [`ConfigError`](/docs/reference/errors/config-error) | [`WALLET_NOT_CONFIGURED`](/docs/reference/errors/WALLET_NOT_CONFIGURED) | without `account` or a client account. | | [`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="Explaining a disabled button" const { allowed, missing } = await ens.permission.check({ name: "alice.eth", operation: "setResolver" }) ``` ```ts title="Checking a text record with a standalone call" import { Actions } from "@ensforge/sdk" const result = await Actions.permission.check(publicClient, { name: "alice.eth", account, operation: { setRecord: "text", key: "url" } }) ``` ```ts title="Checking in an Effect program" import { Actions } from "@ensforge/sdk/effect" const result = yield* Actions.permission.check(ens, { name: "alice.eth", operation: "transfer" }) ``` ## Example response [#example-response] Recorded from Ethereum mainnet on 2026-11-18 at block 26443964. Values change as the chain does. ```ts await ens.permission.check({ name: "nick.eth", operation: "transfer", account: "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045" }) ``` ```json { "allowed": false, "via": null, "contract": "0xf60aba43E1f7F3DAB1186Ff03B561401C9Df85E2", "resource": null, "missing": [ { "type": "owner", "contract": "0xf60aba43E1f7F3DAB1186Ff03B561401C9Df85E2", "owner": "0xb8c2C29ee19D8307cb7255e1Cd9CbDE883A267d5" } ] } ``` ## See also [#see-also] - [`permission.get`](/docs/reference/sdk/permission/get) for every operation at once # permission.get > For the complete documentation index, see [llms.txt](https://ensforge.com/llms.txt). Reads what an account may do with an ENS name: transfer it, change its resolver, edit records, create subnames and more, across ENSv1 ownership and ENSv2 roles. Source: https://ensforge.com/docs/reference/sdk/permission/get Reads what an account may do with an ENS name: transfer it, change its resolver, edit records, create subnames and more, across ENSv1 ownership and ENSv2 roles. ## When to use [#when-to-use] Use to enable or hide actions in a UI before the user tries them. ## Details [#details] - ENSv1: the owner, operators and approved addresses, limited by NameWrapper fuses. - ENSv2: the account's roles on the name and at the root of its registry. The deployment's current UserRegistry checks `renew` at its root only (contracts-v2 #505). - Records: PermissionedResolver roles, or owner, operator and delegates on public resolvers. Pass `records` for per-record answers, e.g. which text keys the account may write. - `null` means the permission model is unknown (a custom resolver). - Costs three batched calls. ## Signature [#signature] ```ts function get(client: Like, options: get.Options): Promise ``` Call it as `ens.permission.get(options)` on a client, or `Actions.permission.get(client, options)`. `permission.get.request(options)` builds a deferred read for `Actions.batch`. See [Look up many at once](/docs/sdk/look-up-many-at-once). In React, use [`usePermissions`](/docs/reference/react/use-permissions). ## Parameters [#parameters] | Option | Type | Default | Description | | --- | --- | --- | --- | | `name` (required) | `string` | | ENS name. Normalized automatically. | | `account` | `string` | the client's account | Account to check. | | `records` | `Selection` | | Records to answer for one by one, in the `record.get` selection shape. | Also takes the [read options](/docs/reference/sdk/client#read-options). ## Returns [#returns] Resolves to `get.ReturnType`. What the account may do; `null` when unknown. | Field | Type | Description | | --- | --- | --- | | `account` | `Address` | | | `status` | `NameStatus` | | | `can` | `{ readonly [operation in NameOperation \| "setRecords"]: boolean \| null }` | | | `records` (optional) | `Readonly>` | Per-record answers, shaped like the `records` selection. | | `fuses` | `readonly Fuse.Name[]` | Burned NameWrapper fuses (wrapped ENSv1 names). | ## 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. | | [`ConfigError`](/docs/reference/errors/config-error) | [`WALLET_NOT_CONFIGURED`](/docs/reference/errors/WALLET_NOT_CONFIGURED) | without `account` or a client account. | | [`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="Gating a UI" const { can } = await ens.permission.get({ name: "alice.eth", account }) if (can.setRecords) showEditButton() ``` ```ts title="Per-record access with a standalone call" import { Actions } from "@ensforge/sdk" const { records } = await Actions.permission.get(publicClient, { name: "alice.eth", account, records: { texts: ["url"] } }) ``` ```ts title="Reading in an Effect program" import { Actions } from "@ensforge/sdk/effect" const permissions = yield* Actions.permission.get(ens, { name: "alice.eth" }) ``` ## Example response [#example-response] Recorded from Ethereum mainnet on 2026-11-18 at block 26443964. Values change as the chain does. ```ts await ens.permission.get({ name: "nick.eth", account: "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045" }) ``` ```json { "account": "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045", "status": "registered", "can": { "transfer": false, "setResolver": false, "setSubregistry": false, "createSubname": false, "removeSubname": false, "renew": true, "setTtl": false, "setManager": false, "reclaim": false, "setRecords": false }, "fuses": [] } ``` ## See also [#see-also] - [`permission.check`](/docs/reference/sdk/permission/check) for one operation and what is missing # permission > For the complete documentation index, see [llms.txt](https://ensforge.com/llms.txt). List the 3 permission actions of @ensforge/sdk and whether each reads, writes or signs. Covers check, get, setRecordAccess. Source: https://ensforge.com/docs/reference/sdk/permission Call them as `ens.permission.(options)` on a client, or `Actions.permission.(client, options)`. ## Reads [#reads] | Action | Description | | --- | --- | | [`check`](/docs/reference/sdk/permission/check) (batchable) | Checks whether an account may perform one operation on an ENS name, and lists exactly what it lacks when it may not. | | [`get`](/docs/reference/sdk/permission/get) (batchable) | Reads what an account may do with an ENS name: transfer it, change its resolver, edit records, create subnames and more, across ENSv1 ownership and ENSv2 roles. | ## Writes [#writes] | Action | Description | | --- | --- | | [`setRecordAccess`](/docs/reference/sdk/permission/set-record-access) | Lets another account edit a name's records, or takes that access back. | # permission.setRecordAccess > For the complete documentation index, see [llms.txt](https://ensforge.com/llms.txt). Lets another account edit a name's records, or takes that access back. Options, result, errors and examples for permission.setRecordAccess. Source: https://ensforge.com/docs/reference/sdk/permission/set-record-access Lets another account edit a name's records, or takes that access back. Resolves once the transaction is submitted. ## When to use [#when-to-use] Use to let a teammate, bot or app manage some or all of a profile. Use [`setRecordAccessSync`](/docs/reference/sdk/permission/set-record-access#wait-for-the-receipt-with-setrecordaccesssync) to wait for the receipt. ## Details [#details] - PermissionedResolver: exact setter roles per record (one text key, coin, data key, ABI content type or interface), or every setter role with `records: "all"`. - Public resolvers: a per-name delegate, which can edit every record of the name. - `revoke` takes the same access back. - PermissionedResolver roles cover every name on that resolver. Names share a resolver with `resolver: "parent"`; give names their own resolver to keep access per name. - Delegates and `"all"` need `allowScopeWidening: true`. ## Signature [#signature] ```ts function setRecordAccess( client: Like, options: setRecordAccess.Options & Write.Options, ): Promise ``` Call it as `ens.permission.setRecordAccess(options)` on a client, or `Actions.permission.setRecordAccess(client, options)`. ## Parameters [#parameters] | Option | Type | Default | Description | | --- | --- | --- | --- | | `name` (required) | `string` | | ENS name. Normalized automatically. | | `grantee` (required) | `string` | | Account that gets (or loses) access. | | `records` | `Selection \| "all"` | `"all"` | Records in the `record.get` selection shape, or `"all"`. | | `allowScopeWidening` | `boolean` | | Confirm grants wider than the listed records (delegates, `"all"`). | | `revoke` | `boolean` | | Take the access back. | 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_RECORD_VALUE`](/docs/reference/errors/INVALID_RECORD_VALUE) | invalid input or an unconfirmed widening. | | [`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) | public keys on a PermissionedResolver. | | [`UnauthorizedError`](/docs/reference/errors/unauthorized-error) | [`CANNOT_GRANT_ROLES`](/docs/reference/errors/CANNOT_GRANT_ROLES), [`NOT_OWNER`](/docs/reference/errors/NOT_OWNER) | the account may not grant access. | | [`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="Letting an app edit a text record" const { hash } = await ens.permission.setRecordAccess({ name: "alice.eth", grantee: "0xB0b0000000000000000000000000000000000000", records: { texts: ["url"] } }) ``` ```ts title="Letting an app edit a text record with a standalone call" import { Actions } from "@ensforge/sdk" await Actions.permission.setRecordAccess(ens, { name: "alice.eth", grantee: "0xB0b0000000000000000000000000000000000000", records: { texts: ["url"] } }) ``` ```ts title="Letting an app edit a text record in an Effect program" import { Actions } from "@ensforge/sdk/effect" yield* Actions.permission.setRecordAccess(ens, { name: "alice.eth", grantee: "0xB0b0000000000000000000000000000000000000", records: { texts: ["url"] } }) ``` ## Plan methods [#plan-methods] Each method takes the same options as `permission.setRecordAccess` and sends nothing. See [Preview before sending](/docs/sdk/preview-before-sending). | Method | Description | | --- | --- | | `permission.setRecordAccess.prepare(options)` | Builds the plan without sending anything. | | `permission.setRecordAccess.simulate(options)` | Simulates the plan with `eth_call`, reporting each step. | | `permission.setRecordAccess.estimateGas(options)` | Estimates the gas and ETH the plan needs. | ## Wait for the receipt with `setRecordAccessSync` [#wait-for-the-receipt-with-setrecordaccesssync] Lets another account edit a name's records, or takes that access back. Resolves once the receipt is in. Use when the next step depends on the change being on-chain. `permission.setRecordAccessSync` 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="Letting an app edit a text record and waiting" const { receipt } = await ens.permission.setRecordAccessSync({ name: "alice.eth", grantee: "0xB0b0000000000000000000000000000000000000", records: { texts: ["url"] } }) ``` ```ts title="Waiting with a standalone call" import { Actions } from "@ensforge/sdk" await Actions.permission.setRecordAccessSync(ens, { name: "alice.eth", grantee: "0xB0b0000000000000000000000000000000000000", records: { texts: ["url"] } }) ``` ```ts title="Waiting in an Effect program" import { Actions } from "@ensforge/sdk/effect" yield* Actions.permission.setRecordAccessSync(ens, { name: "alice.eth", grantee: "0xB0b0000000000000000000000000000000000000", records: { texts: ["url"] } }) ``` ## See also [#see-also] - [`permission.get`](/docs/reference/sdk/permission/get) to read access # plan.get > For the complete documentation index, see [llms.txt](https://ensforge.com/llms.txt). Reads a saved plan and its progress. Parameters, return value, errors and examples for plan.get in @ensforge/sdk. Options, errors and examples for plan.get. Source: https://ensforge.com/docs/reference/sdk/plan/get Reads a saved plan and its progress. ## When to use [#when-to-use] Use to show where a registration, migration or other multi-step write stands. ## Details [#details] - Every write saves its plan to the client's `storage` as it sends. - `null` when no plan has the id (memory storage forgets plans on reload). ## Signature [#signature] ```ts function get(client: Like, options: get.Options): Promise ``` Call it as `ens.plan.get(options)` on a client, or `Actions.plan.get(client, options)`. `plan.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 | | --- | --- | --- | --- | | `id` (required) | `string` | | Plan id, from `result.plan.id` or a failure's `context.planId`. | ## Returns [#returns] Resolves to `Plan.Record | null`. The saved plan and its progress, or `null`. | Field | Type | Description | | --- | --- | --- | | `plan` | `Plan` | | | `status` | `"pending" \| "completed" \| "failed"` | `pending` while steps remain, `completed` once every step is submitted. | | `submitted` | `Readonly>` | Transaction hashes per submitted step id. | | `bundles` | `Readonly>` | EIP-5792 bundle id per step sent in a bundle. | | `references` (optional) | `Readonly>` | Route references per step sent through `via` (e.g. UserOperation hashes). | | `error` (optional) | `string` | Message of the last failure. | | `updatedAt` | `number` | Unix time in milliseconds. | ## Errors [#errors] | Error | Codes | When | | --- | --- | --- | | [`InternalError`](/docs/reference/errors/internal-error) | [`UNEXPECTED`](/docs/reference/errors/UNEXPECTED) | the storage fails. | | [`PlanError`](/docs/reference/errors/plan-error) | [`PLAN_INVALID`](/docs/reference/errors/PLAN_INVALID) | a saved plan cannot be read. | | [`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 plan" const record = await ens.plan.get({ id: planId }) ``` ```ts title="Reading a plan with a standalone call" import { Actions } from "@ensforge/sdk" const record = await Actions.plan.get(publicClient, { id: planId }) ``` ```ts title="Reading a plan in an Effect program" import { Actions } from "@ensforge/sdk/effect" const record = yield* Actions.plan.get(ens, { id: planId }) ``` ## See also [#see-also] - [`plan.resume`](/docs/reference/sdk/plan/resume) to continue it # plan > For the complete documentation index, see [llms.txt](https://ensforge.com/llms.txt). List the 5 plan actions of @ensforge/sdk and whether each reads, writes or signs. Covers get, list, reconcile, resume, send. Source: https://ensforge.com/docs/reference/sdk/plan Call them as `ens.plan.(options)` on a client, or `Actions.plan.(client, options)`. ## Reads [#reads] | Action | Description | | --- | --- | | [`get`](/docs/reference/sdk/plan/get) (batchable) | Reads a saved plan and its progress. | | [`list`](/docs/reference/sdk/plan/list) (batchable) | Lists the saved plans of this client's chain and of its `chains`, newest first. | | [`reconcile`](/docs/reference/sdk/plan/reconcile) (batchable) | Records a transaction sent outside ensforge as a plan step's submission. | ## Writes [#writes] | Action | Description | | --- | --- | | [`send`](/docs/reference/sdk/plan/send) | Sends any plan: one prepared by a write's `.prepare`, or several combined with `Plan.merge`. | ## Signing [#signing] | Action | Description | | --- | --- | | [`resume`](/docs/reference/sdk/plan/resume) | Continues a saved plan after a failure or a reload. | # plan.list > For the complete documentation index, see [llms.txt](https://ensforge.com/llms.txt). Lists the saved plans of this client's chain and of its chains, newest first. Parameters, return value, errors and examples for plan.list in @ensforge/sdk. Source: https://ensforge.com/docs/reference/sdk/plan/list Lists the saved plans of this client's chain and of its `chains`, newest first. ## When to use [#when-to-use] Use to offer unfinished registrations or migrations after a reload. ## Details [#details] - Filter by the account that prepared them and by status (`pending`, `completed`, `failed`). ## Signature [#signature] ```ts function list(client: Like, options: list.Options): Promise ``` Call it as `ens.plan.list(options)` on a client, or `Actions.plan.list(client, options)`. `plan.list.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 | | --- | --- | --- | --- | | `account` | `string` | | Only plans prepared for this account. | | `status` | `Plan.Record["status"]` | | Only plans with this status. | ## Returns [#returns] Resolves to `readonly Plan.Record[]`. The saved plans, newest first. | Field | Type | Description | | --- | --- | --- | | `plan` | `Plan` | | | `status` | `"pending" \| "completed" \| "failed"` | `pending` while steps remain, `completed` once every step is submitted. | | `submitted` | `Readonly>` | Transaction hashes per submitted step id. | | `bundles` | `Readonly>` | EIP-5792 bundle id per step sent in a bundle. | | `references` (optional) | `Readonly>` | Route references per step sent through `via` (e.g. UserOperation hashes). | | `error` (optional) | `string` | Message of the last failure. | | `updatedAt` | `number` | Unix time in milliseconds. | ## Errors [#errors] | Error | Codes | When | | --- | --- | --- | | [`InvalidInputError`](/docs/reference/errors/invalid-input-error) | [`INVALID_ADDRESS`](/docs/reference/errors/INVALID_ADDRESS) | an invalid account. | | [`PlanError`](/docs/reference/errors/plan-error) | [`PLAN_INVALID`](/docs/reference/errors/PLAN_INVALID) | a saved plan cannot be read. | | [`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="Listing unfinished plans" const records = await ens.plan.list({ status: "failed" }) ``` ```ts title="Listing unfinished plans with a standalone call" import { Actions } from "@ensforge/sdk" const records = await Actions.plan.list(publicClient, { status: "failed" }) ``` ```ts title="Listing unfinished plans in an Effect program" import { Actions } from "@ensforge/sdk/effect" const records = yield* Actions.plan.list(ens, { status: "failed" }) ``` ## See also [#see-also] - [`plan.get`](/docs/reference/sdk/plan/get) to read one # plan.reconcile > For the complete documentation index, see [llms.txt](https://ensforge.com/llms.txt). Records a transaction sent outside ensforge as a plan step's submission. Parameters, return value, errors and examples for plan.reconcile in @ensforge/sdk. Source: https://ensforge.com/docs/reference/sdk/plan/reconcile Records a transaction sent outside ensforge as a plan step's submission. ## When to use [#when-to-use] Use when a step was sent from another device or the wallet lost track, so resuming does not send it again. ## Details [#details] - The transaction must exist and come from the plan's account, or call one of the step's contracts. - [`plan.resume`](/docs/reference/sdk/plan/resume) then waits for it instead of sending the step. ## Signature [#signature] ```ts function reconcile(client: Like, options: reconcile.Options): Promise ``` Call it as `ens.plan.reconcile(options)` on a client, or `Actions.plan.reconcile(client, options)`. `plan.reconcile.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 | | --- | --- | --- | --- | | `id` (required) | `string` | | Plan id. | | `step` (required) | `string` | | Step id the transaction submitted. | | `hash` (required) | `Hex` | | Transaction hash. | ## Returns [#returns] Resolves to `Plan.Record`. The updated record. | Field | Type | Description | | --- | --- | --- | | `plan` | `Plan` | | | `status` | `"pending" \| "completed" \| "failed"` | `pending` while steps remain, `completed` once every step is submitted. | | `submitted` | `Readonly>` | Transaction hashes per submitted step id. | | `bundles` | `Readonly>` | EIP-5792 bundle id per step sent in a bundle. | | `references` (optional) | `Readonly>` | Route references per step sent through `via` (e.g. UserOperation hashes). | | `error` (optional) | `string` | Message of the last failure. | | `updatedAt` | `number` | Unix time in milliseconds. | ## Errors [#errors] | Error | Codes | When | | --- | --- | --- | | [`NotFoundError`](/docs/reference/errors/not-found-error) | [`PLAN_NOT_FOUND`](/docs/reference/errors/PLAN_NOT_FOUND) | an unknown plan. | | [`PlanError`](/docs/reference/errors/plan-error) | [`PLAN_INVALID`](/docs/reference/errors/PLAN_INVALID) | a saved plan cannot be read. | | [`InvalidInputError`](/docs/reference/errors/invalid-input-error) | [`INVALID_RECORD_VALUE`](/docs/reference/errors/INVALID_RECORD_VALUE) | an unknown step or an unrelated transaction. | | [`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="Attaching a recovered hash" const record = await ens.plan.reconcile({ id, step: "commit", hash }) ``` ```ts title="Attaching a recovered hash with a standalone call" import { Actions } from "@ensforge/sdk" const record = await Actions.plan.reconcile(publicClient, { id, step: "commit", hash }) ``` ```ts title="Attaching a recovered hash in an Effect program" import { Actions } from "@ensforge/sdk/effect" const record = yield* Actions.plan.reconcile(ens, { id, step: "commit", hash }) ``` ## See also [#see-also] - [`plan.resume`](/docs/reference/sdk/plan/resume) to continue the plan # plan.resume > For the complete documentation index, see [llms.txt](https://ensforge.com/llms.txt). Continues a saved plan after a failure or a reload. Parameters, return value, errors and examples for plan.resume in @ensforge/sdk. Source: https://ensforge.com/docs/reference/sdk/plan/resume Continues a saved plan after a failure or a reload. Resolves once the remaining transactions are submitted. ## When to use [#when-to-use] Use when a registration, migration or other multi-step write stopped part-way. Use [`resumeSync`](/docs/reference/sdk/plan/resume#wait-for-the-receipt-with-resumesync) to wait for the receipts. ## Details [#details] - Steps submitted before are confirmed, not sent again; a dropped transaction or a failed bundle is sent again. - Each remaining step is simulated against current state right before it is sent. - The plan id is `result.plan.id`, or `context.planId` on a write's error. - A plan for another chain (an L2 primary name) resumes on that chain's clients from the client's `chains`. - Plans live in the client's `storage`: pass `Plan.localStorage()` to survive page reloads. ## Signature [#signature] ```ts function resume( client: Like, options: resume.Options & Write.Options, ): Promise ``` Call it as `ens.plan.resume(options)` on a client, or `Actions.plan.resume(client, options)`. ## Parameters [#parameters] | Option | Type | Default | Description | | --- | --- | --- | --- | | `id` (required) | `string` | | Plan id. | ## Returns [#returns] Resolves to `Write.Result`. Submitted transaction hashes (earlier steps included) and the plan. | 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 | | --- | --- | --- | | [`NotFoundError`](/docs/reference/errors/not-found-error) | [`PLAN_NOT_FOUND`](/docs/reference/errors/PLAN_NOT_FOUND) | an unknown plan. | | [`PlanError`](/docs/reference/errors/plan-error) | [`PLAN_CHAIN_MISMATCH`](/docs/reference/errors/PLAN_CHAIN_MISMATCH), [`PLAN_ACCOUNT_MISMATCH`](/docs/reference/errors/PLAN_ACCOUNT_MISMATCH), [`PLAN_ROUTE_REQUIRED`](/docs/reference/errors/PLAN_ROUTE_REQUIRED) | the plan cannot continue here. | | [`PlanError`](/docs/reference/errors/plan-error) | [`PLAN_INVALID`](/docs/reference/errors/PLAN_INVALID) | a saved plan cannot be read. | | [`ContractRevertError`](/docs/reference/errors/contract-revert-error) | [`CONTRACT_REVERTED`](/docs/reference/errors/CONTRACT_REVERTED) | , or the failing step's own error (`Errors.AnyError`: a plan can hold any step), with `context.planId` and `context.step`. | 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="Resuming after a failure" const { hash } = await ens.plan.resume({ id: planId }) ``` ```ts title="Resuming with a standalone call" import { Actions } from "@ensforge/sdk" await Actions.plan.resume(ens, { id }) ``` ```ts title="Resuming in an Effect program" import { Actions } from "@ensforge/sdk/effect" yield* Actions.plan.resume(ens, { id }) ``` ## Wait for the receipt with `resumeSync` [#wait-for-the-receipt-with-resumesync] Continues a saved plan and resolves once every receipt is in. Use when the next step depends on the plan being finished on-chain. `plan.resumeSync` 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="Resuming and waiting" const { receipts } = await ens.plan.resumeSync({ id }) ``` ```ts title="Waiting with a standalone call" import { Actions } from "@ensforge/sdk" await Actions.plan.resumeSync(ens, { id }) ``` ```ts title="Waiting in an Effect program" import { Actions } from "@ensforge/sdk/effect" yield* Actions.plan.resumeSync(ens, { id }) ``` ## See also [#see-also] - [`plan.get`](/docs/reference/sdk/plan/get) to read its progress first # plan.send > For the complete documentation index, see [llms.txt](https://ensforge.com/llms.txt). Sends any plan: one prepared by a write's .prepare, or several combined with Plan.merge. Options, result, errors and examples for plan.send. Source: https://ensforge.com/docs/reference/sdk/plan/send Sends any plan: one prepared by a write's `.prepare`, or several combined with `Plan.merge`. Resolves once the transaction is submitted. ## When to use [#when-to-use] Use to review a plan before sending it, or to send several writes as one flow. Use [`sendSync`](/docs/reference/sdk/plan/send#wait-for-the-receipt-with-sendsync) to wait for the receipt. ## Details [#details] - The plan is simulated, then sent step by step; consecutive steps share one wallet bundle when the wallet supports atomic batches (`maxBundleCalls`), never across a chain-time wait. - Progress is saved to the client's `storage`, so a failed or interrupted plan continues with [`plan.resume`](/docs/reference/sdk/plan/resume); failures carry `context.planId`. - `onStep` reports each step as it waits, is submitted, confirmed or fails. - A plan for one of the client's `chains` (an L2 primary name) is simulated and sent there. ## Signature [#signature] ```ts function send( client: Like, options: send.Options & Write.Options, ): Promise ``` Call it as `ens.plan.send(options)` on a client, or `Actions.plan.send(client, options)`. ## Parameters [#parameters] | Option | Type | Default | Description | | --- | --- | --- | --- | | `plan` (required) | `Plan` | | The plan to send, for this client's chain and signer. | 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 | | --- | --- | --- | | [`PlanError`](/docs/reference/errors/plan-error) | [`PLAN_CHAIN_MISMATCH`](/docs/reference/errors/PLAN_CHAIN_MISMATCH), [`PLAN_ACCOUNT_MISMATCH`](/docs/reference/errors/PLAN_ACCOUNT_MISMATCH) | a plan prepared elsewhere. | | [`PlanError`](/docs/reference/errors/plan-error) | [`PLAN_STALE`](/docs/reference/errors/PLAN_STALE) | a token it transfers was reissued since it was prepared. | | [`ContractRevertError`](/docs/reference/errors/contract-revert-error) | [`CONTRACT_REVERTED`](/docs/reference/errors/CONTRACT_REVERTED) | , or the failing step's own error (`Errors.AnyError`: a plan can hold any step), with `context.planId` and `context.step`. | | [`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="Sending a merged plan" import { Plan } from "@ensforge/sdk" const { hash } = await ens.plan.send({ plan: Plan.merge([recordsPlan, primaryNamePlan]) }) ``` ```ts title="Sending a merged plan with a standalone call" import { Actions, Plan } from "@ensforge/sdk" await Actions.plan.send(ens, { plan: Plan.merge([recordsPlan, primaryNamePlan]) }) ``` ```ts title="Sending a merged plan in an Effect program" import { Actions, Plan } from "@ensforge/sdk/effect" yield* Actions.plan.send(ens, { plan: Plan.merge([recordsPlan, primaryNamePlan]) }) ``` ## Plan methods [#plan-methods] Each method takes the same options as `plan.send` and sends nothing. See [Preview before sending](/docs/sdk/preview-before-sending). | Method | Description | | --- | --- | | `plan.send.prepare(options)` | Builds the plan without sending anything. | | `plan.send.simulate(options)` | Simulates the plan with `eth_call`, reporting each step. | | `plan.send.estimateGas(options)` | Estimates the gas and ETH the plan needs. | ## Wait for the receipt with `sendSync` [#wait-for-the-receipt-with-sendsync] Sends any plan: one prepared by a write's `.prepare`, or several combined with `Plan.merge`. Resolves once the receipt is in. Use when the next step depends on the change being on-chain. `plan.sendSync` 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="Sending a merged plan and waiting" import { Plan } from "@ensforge/sdk" const { receipt } = await ens.plan.sendSync({ plan: Plan.merge([recordsPlan, primaryNamePlan]) }) ``` ```ts title="Waiting with a standalone call" import { Actions, Plan } from "@ensforge/sdk" await Actions.plan.sendSync(ens, { plan: Plan.merge([recordsPlan, primaryNamePlan]) }) ``` ```ts title="Waiting in an Effect program" import { Actions, Plan } from "@ensforge/sdk/effect" yield* Actions.plan.sendSync(ens, { plan: Plan.merge([recordsPlan, primaryNamePlan]) }) ``` ## See also [#see-also] - [`plan.resume`](/docs/reference/sdk/plan/resume) to continue a plan # primaryName.get > For the complete documentation index, see [llms.txt](https://ensforge.com/llms.txt). Reads the primary name of an address (ENSIP-19 reverse resolution), verified against the name's address record. Errors and examples for primaryName.get. Source: https://ensforge.com/docs/reference/sdk/primary-name/get Reads the primary name of an address (ENSIP-19 reverse resolution), verified against the name's address record. ## When to use [#when-to-use] Use to show a name instead of an address. ## Details [#details] - The name counts only when it resolves back to the address, so nobody can claim another account's name. `verify: false` skips this and returns the raw reverse record. - `coin` selects the chain: `"eth"` (default), any EVM chain such as `{ chainId: 8453 }`, or `"default"`. Chains without their own primary name fall back to `default.reverse`. - Names that are not normalized are treated as unset. - Returns `null` when there is no valid primary name, unless `strict` is set. With `strict`, an address whose reverse name has no resolver or name fails [`PRIMARY_NAME_NOT_SET`](/docs/reference/errors/PRIMARY_NAME_NOT_SET); a name that does not resolve back (no resolver, no address record or another address) fails [`PRIMARY_NAME_MISMATCH`](/docs/reference/errors/PRIMARY_NAME_MISMATCH), whose `cause` names the name or the profile that failed. A resolver that reverts without data says neither, and counts as not set. ## Signature [#signature] ```ts function get(client: Like, options: get.Options): Promise ``` Call it as `ens.primaryName.get(options)` on a client, or `Actions.primaryName.get(client, options)`. `primaryName.get.request(options)` builds a deferred read for `Actions.batch`. See [Look up many at once](/docs/sdk/look-up-many-at-once). In React, use [`usePrimaryName`](/docs/reference/react/use-primary-name). ## Parameters [#parameters] | Option | Type | Default | Description | | --- | --- | --- | --- | | `address` (required) | `string` | | Address to look up. | | `coin` | `CoinType.Input \| "default"` | `"eth"` | Chain of the primary name: a coin symbol, `{ chainId }`, a coin type, or `"default"`. | | `verify` | `boolean` | `true` | Require the name to resolve back to the address. | Also takes the [read options](/docs/reference/sdk/client#read-options). ## Returns [#returns] Resolves to `string | null`. The primary name, or `null` when there is no valid one. ## Errors [#errors] | Error | Codes | When | | --- | --- | --- | | [`InvalidInputError`](/docs/reference/errors/invalid-input-error) | [`INVALID_ADDRESS`](/docs/reference/errors/INVALID_ADDRESS), [`INVALID_COIN_TYPE`](/docs/reference/errors/INVALID_COIN_TYPE), [`INVALID_NAME`](/docs/reference/errors/INVALID_NAME) | invalid input, or with `strict` an unnormalized name. | | [`NotFoundError`](/docs/reference/errors/not-found-error) | [`PRIMARY_NAME_NOT_SET`](/docs/reference/errors/PRIMARY_NAME_NOT_SET), [`PRIMARY_NAME_MISMATCH`](/docs/reference/errors/PRIMARY_NAME_MISMATCH) | with `strict` when there is no valid primary name. | | [`GatewayError`](/docs/reference/errors/gateway-error) | [`GATEWAY_REQUEST_FAILED`](/docs/reference/errors/GATEWAY_REQUEST_FAILED), [`GATEWAY_RESPONSE_INVALID`](/docs/reference/errors/GATEWAY_RESPONSE_INVALID), [`OFFCHAIN_LOOKUP_INVALID`](/docs/reference/errors/OFFCHAIN_LOOKUP_INVALID) | an off-chain gateway fails. | | [`DnsError`](/docs/reference/errors/dns-error) | | a DNS name's DNSSEC proof does not verify. | | [`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="Showing a name for an address" const name = await ens.primaryName.get({ address: "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045" }) name // "vitalik.eth" ``` ```ts title="Reading the Base primary name with a bare viem client" import { Actions } from "@ensforge/sdk" const name = await Actions.primaryName.get(publicClient, { address, coin: { chainId: 8453 } }) ``` ```ts title="Reading in an Effect program" import { Actions } from "@ensforge/sdk/effect" const name = yield* Actions.primaryName.get(ens, { address, strict: true }) ``` ## Example response [#example-response] Recorded from Ethereum mainnet on 2026-11-18 at block 26443964. Values change as the chain does. ```ts await ens.primaryName.get({ address: "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045" }) ``` ```json "vitalik.eth" ``` ## See also [#see-also] - [`primaryName.set`](/docs/reference/sdk/primary-name/set) to set it # primaryName > For the complete documentation index, see [llms.txt](https://ensforge.com/llms.txt). List the 3 primaryName actions of @ensforge/sdk and whether each reads, writes or signs. Covers get, set, signClaim. Covers get, set, signClaim. Source: https://ensforge.com/docs/reference/sdk/primary-name Call them as `ens.primaryName.(options)` on a client, or `Actions.primaryName.(client, options)`. ## Reads [#reads] | Action | Description | | --- | --- | | [`get`](/docs/reference/sdk/primary-name/get) (batchable) | Reads the primary name of an address (ENSIP-19 reverse resolution), verified against the name's address record. | ## Writes [#writes] | Action | Description | | --- | --- | | [`set`](/docs/reference/sdk/primary-name/set) | Sets or clears the primary name (reverse record) of an address. | ## Signing [#signing] | Action | Description | | --- | --- | | [`signClaim`](/docs/reference/sdk/primary-name/sign-claim) | Signs a claim to a primary name on one or more L2s, with one signature and no transaction. | # primaryName.set > For the complete documentation index, see [llms.txt](https://ensforge.com/llms.txt). Sets or clears the primary name (reverse record) of an address. Parameters, return value, errors and examples for primaryName.set in @ensforge/sdk. Source: https://ensforge.com/docs/reference/sdk/primary-name/set Sets or clears the primary name (reverse record) of an address. Resolves once the transaction is submitted. ## When to use [#when-to-use] Use to choose the name wallets and apps show for an address. Use [`setSync`](/docs/reference/sdk/primary-name/set#wait-for-the-receipt-with-setsync) to wait for the receipt. ## Details [#details] - `coin: "eth"` (default) sets the Ethereum primary name in `addr.reverse`; `"default"` sets the fallback for every EVM chain in `default.reverse` (ENSIP-19). - An L2 such as `coin: { chainId: 8453 }` sets that chain's primary name in its reverse registrar, with a transaction on that chain: the client needs it in `chains` (`Ensforge.create`, or the wagmi config with `fromWagmi`). The plan is for that chain, and resumes there. - `claim` and `signature` from `primaryName.signClaim` submit a signed claim instead, from any account: one signature sets the name on each of its chains, and a server can relay it. - An `addr.reverse` name outranks `default.reverse` on Ethereum, so `"default"` also sets `addr.reverse` when it holds a different name. - A default name with only an Ethereum address verifies on Ethereum alone; the plan carries a `DEFAULT_PRIMARY_NAME_ETHEREUM_ONLY` warning. - `address` names another account: the signer must be its registry operator or, for a contract, its Ownable owner or ContractNamer (ENSv2 `IContractNamer`); any other signer fails before sending. For `"eth"`, a ContractNamer goes through the ENSv2 adapter: it `claim`s the contract's `addr.reverse` node, which makes the signer that node's owner, then sets the name on the node's resolver. - Before sending, checks that the name resolves back to the address, as readers require. - `name: null` clears it. - Names with encoded labels (`[af2c…]`) are rejected: readers show only normalized names. - A ContractNamer's `"eth"` name takes two dependent calls: simulating them needs an RPC with `eth_simulateV1` (or `simulate: false`). - Readers on Ethereum verify an L2 primary name against the L2's state as committed to Ethereum, so they see it only once that state is, which can take a while after the receipt. ## Signature [#signature] ```ts function set(client: Like, options: set.Options & Write.Options): Promise ``` Call it as `ens.primaryName.set(options)` on a client, or `Actions.primaryName.set(client, options)`. In React, use [`useSetPrimaryName`](/docs/reference/react/use-set-primary-name). ## Parameters [#parameters] With `claim` and `signature`: | Option | Type | Default | Description | | --- | --- | --- | --- | | `claim` (required) | `signClaim.Claim` | | The claim from `primaryName.signClaim`. | | `signature` (required) | `Hex` | | Its signature. | | `coin` | `CoinType.Input` | the claim's chain, when it covers one | The L2 to submit it on, one of the claim's chains. | | `verify` | `boolean` | `true` | Check that the claimed name resolves to the address on that chain before sending. | With `name`: | Option | Type | Default | Description | | --- | --- | --- | --- | | `name` (required) | `string \| null` | | Primary name, or `null` to clear it. Normalized automatically. | | `address` | `string` | the signing account | Address to name. | | `coin` | `CoinType.Input \| "default"` | `"eth"` | Chain of the primary name: `"eth"` for Ethereum (`addr.reverse`), `"default"` for every EVM chain (`default.reverse`), or an L2 such as `{ chainId: 8453 }` (its reverse registrar, sent on that chain through the client's `chains`). | | `verify` | `boolean` | `true` | Check that `name` resolves to the address before sending. | 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. | | [`InvalidInputError`](/docs/reference/errors/invalid-input-error) | [`INVALID_COIN_TYPE`](/docs/reference/errors/INVALID_COIN_TYPE) | a coin that is not an EVM chain, or a chain the claim does not cover. | | [`NotFoundError`](/docs/reference/errors/not-found-error) | [`PRIMARY_NAME_MISMATCH`](/docs/reference/errors/PRIMARY_NAME_MISMATCH) | the name does not resolve to the address. | | [`ConfigError`](/docs/reference/errors/config-error) | [`WALLET_NOT_CONFIGURED`](/docs/reference/errors/WALLET_NOT_CONFIGURED) | no signing account is known. | | [`ConfigError`](/docs/reference/errors/config-error) | [`CHAIN_NOT_CONFIGURED`](/docs/reference/errors/CHAIN_NOT_CONFIGURED) | an L2 that is not in the client's `chains`. | | [`UnsupportedError`](/docs/reference/errors/unsupported-error) | [`UNSUPPORTED_ON_DEPLOYMENT`](/docs/reference/errors/UNSUPPORTED_ON_DEPLOYMENT) | a chain without an L2 reverse registrar. | | [`UnauthorizedError`](/docs/reference/errors/unauthorized-error) | [`NOT_APPROVED`](/docs/reference/errors/NOT_APPROVED) | the signer may not name the address. | | [`UnauthorizedError`](/docs/reference/errors/unauthorized-error) | [`SIGNATURE_INVALID`](/docs/reference/errors/SIGNATURE_INVALID), [`SIGNATURE_EXPIRED`](/docs/reference/errors/SIGNATURE_EXPIRED) | the claim's signature is invalid or expired. | | [`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="Setting a primary name" const { hash } = await ens.primaryName.set({ name: "alice.eth" }) ``` ```ts title="Setting the primary name on an L2" import { Ensforge, ensActions } from "@ensforge/sdk" const ens = Ensforge.create({ publicClient, walletClient, chains: { 8453: { publicClient: baseClient, walletClient: baseWallet } }, }).extend(ensActions()) await ens.primaryName.set({ name: "alice.eth", coin: { chainId: 8453 } }) ``` ```ts title="Several L2s with one signature" const signed = await ens.primaryName.signClaim({ name: "alice.eth", chainIds: [10, 8453] }) await ens.primaryName.set({ ...signed, coin: { chainId: 10 } }) await ens.primaryName.set({ ...signed, coin: { chainId: 8453 } }) ``` ```ts title="A server relaying a claim" // `body` is the JSON the app posted: the result of `primaryName.signClaim`. const { claim, signature } = JSON.parse(body) await relayer.primaryName.set({ claim, signature, coin: { chainId: 8453 } }) ``` ```ts title="Setting a primary name with a standalone call" import { Actions } from "@ensforge/sdk" await Actions.primaryName.set(ens, { name: "alice.eth" }) ``` ```ts title="Setting a primary name in an Effect program" import { Actions } from "@ensforge/sdk/effect" yield* Actions.primaryName.set(ens, { name: "alice.eth" }) ``` ## Plan methods [#plan-methods] Each method takes the same options as `primaryName.set` and sends nothing. See [Preview before sending](/docs/sdk/preview-before-sending). | Method | Description | | --- | --- | | `primaryName.set.prepare(options)` | Builds the plan without sending anything. | | `primaryName.set.simulate(options)` | Simulates the plan with `eth_call`, reporting each step. | | `primaryName.set.estimateGas(options)` | Estimates the gas and ETH the plan needs. | ## Wait for the receipt with `setSync` [#wait-for-the-receipt-with-setsync] Sets or clears the primary name (reverse record) of an address. Resolves once the receipt is in. Use when the next step depends on the change being on-chain. `primaryName.setSync` 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="Setting a primary name and waiting" const { receipt } = await ens.primaryName.setSync({ name: "alice.eth" }) ``` ```ts title="Waiting with a standalone call" import { Actions } from "@ensforge/sdk" await Actions.primaryName.setSync(ens, { name: "alice.eth" }) ``` ```ts title="Waiting in an Effect program" import { Actions } from "@ensforge/sdk/effect" yield* Actions.primaryName.setSync(ens, { name: "alice.eth" }) ``` ## See also [#see-also] - [`primaryName.get`](/docs/reference/sdk/primary-name/get) to read it # primaryName.signClaim > For the complete documentation index, see [llms.txt](https://ensforge.com/llms.txt). Signs a claim to a primary name on one or more L2s, with one signature and no transaction. Options, result, errors and examples for primaryName.signClaim. Source: https://ensforge.com/docs/reference/sdk/primary-name/sign-claim Signs a claim to a primary name on one or more L2s, with one signature and no transaction. Anyone can then submit it on each chain with `primaryName.set`, so the account needs no gas or wallet connection there. ## When to use [#when-to-use] Use to set the same primary name on several L2s with one prompt, or to let a server relay it (sponsoring the L2 gas). ## Details [#details] - The claim is for the ens-contracts `L2ReverseRegistrar`: every mainnet L2 shares one, so one signature covers all of `chainIds`; testnets share another. - It expires `expiresIn` seconds (at most one hour, the registrar's limit) after the latest block of the earliest of those chains: read on the chains the client has in `chains`, and on the ENS chain for the others. - The account signs EIP-191 over the registrar's message. Smart accounts sign as themselves (ERC-1271, or ERC-6492 before they are deployed); the registrar checks the signature on each L2, where the account must exist (or be deployable). - `address` names a contract the signer owns (`Ownable`): the claim says so, and the registrar checks the ownership on each L2. - Before signing, checks that `name` resolves to the address on each chain (its address for that chain, or its default EVM address); `verify: false` skips this. - The claim is plain JSON: send it to a relaying server as is. ## Signature [#signature] ```ts function signClaim(client: Like, options: signClaim.Options): Promise ``` Call it as `ens.primaryName.signClaim(options)` on a client, or `Actions.primaryName.signClaim(client, options)`. ## Parameters [#parameters] | Option | Type | Default | Description | | --- | --- | --- | --- | | `name` (required) | `string \| null` | | Primary name, or `null` to clear it. Normalized automatically. | | `chainIds` (required) | `readonly number[]` | | The L2s the claim sets the primary name on, by chain ID. | | `address` | `string` | the signing account | Address to name: the signer's own, or a contract the signer owns (`Ownable`). | | `expiresIn` | `bigint` | `3600n` | Seconds until the claim expires, at most one hour. | | `verify` | `boolean` | `true` | Check that `name` resolves to the address on each chain before signing. | | `account` | `Account \| Address` | the client's account | Signer. | ## Returns [#returns] Resolves to `{ readonly claim: Claim; readonly signature: Hex }`. The claim and its signature, for `primaryName.set` on each chain. | Field | Type | Description | | --- | --- | --- | | `claim` | `Claim` | | | `signature` | `Hex` | | ## 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. | | [`InvalidInputError`](/docs/reference/errors/invalid-input-error) | [`INVALID_COIN_TYPE`](/docs/reference/errors/INVALID_COIN_TYPE) | `chainIds` is empty, includes the ENS chain, or mixes mainnet L2s and testnets. | | [`InvalidInputError`](/docs/reference/errors/invalid-input-error) | [`INVALID_DURATION`](/docs/reference/errors/INVALID_DURATION) | `expiresIn` is not between 1 and 3600 seconds. | | [`UnsupportedError`](/docs/reference/errors/unsupported-error) | [`UNSUPPORTED_ON_DEPLOYMENT`](/docs/reference/errors/UNSUPPORTED_ON_DEPLOYMENT) | a chain without an L2 reverse registrar. | | [`NotFoundError`](/docs/reference/errors/not-found-error) | [`PRIMARY_NAME_MISMATCH`](/docs/reference/errors/PRIMARY_NAME_MISMATCH) | the name does not resolve to the address on a chain. | | [`ConfigError`](/docs/reference/errors/config-error) | [`WALLET_NOT_CONFIGURED`](/docs/reference/errors/WALLET_NOT_CONFIGURED) | no signing account is known. | | [`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="One signature for several L2s" const signed = await ens.primaryName.signClaim({ name: "alice.eth", chainIds: [10, 8453] }) await ens.primaryName.set({ ...signed, coin: { chainId: 10 } }) await ens.primaryName.set({ ...signed, coin: { chainId: 8453 } }) ``` ```ts title="A server relaying a claim" // In the app: sign, and send the claim to your server. const signed = await ens.primaryName.signClaim({ name: "alice.eth", chainIds: [8453] }) await fetch("/api/primary-name", { method: "POST", body: JSON.stringify(signed) }) // On the server (`body` is the posted JSON), with a client whose `chains` has a funded // wallet for Base: const { claim, signature } = JSON.parse(body) await relayer.primaryName.set({ claim, signature }) ``` ```ts title="Signing with a standalone call" import { Actions } from "@ensforge/sdk" const signed = await Actions.primaryName.signClaim(ens, { name: "alice.eth", chainIds: [10] }) ``` ```ts title="Signing in an Effect program" import { Actions } from "@ensforge/sdk/effect" const signed = yield* Actions.primaryName.signClaim(ens, { name: "alice.eth", chainIds: [10] }) ``` ## See also [#see-also] - [`primaryName.set`](/docs/reference/sdk/primary-name/set) to submit the claim # record.getAddress > For the complete documentation index, see [llms.txt](https://ensforge.com/llms.txt). Reads one address record of an ENS name, for Ethereum by default or any coin (ENSIP-9, ENSIP-11). Options, result, errors and examples for record.getAddress. Source: https://ensforge.com/docs/reference/sdk/record/get-address Reads one address record of an ENS name, for Ethereum by default or any coin (ENSIP-9, ENSIP-11). ## When to use [#when-to-use] Use to find where to send funds for a name. Use `record.get` to read several coins at once. ## Details [#details] - `coin` is a symbol (`"btc"`), an EVM chain (`{ chainId: 8453 }`) or a coin type (`0n`). - EVM coins return a checksummed `Address`; other coins their native format. - EVM chains other than mainnet fall back to the default EVM address (ENSIP-19). - Returns `null` when the record is not set, unless `strict` is set. ## Signature [#signature] ```ts function getAddress( client: Like, options: getAddress.Options, ): Promise> ``` Call it as `ens.record.getAddress(options)` on a client, or `Actions.record.getAddress(client, options)`. `record.getAddress.request(options)` builds a deferred read for `Actions.batch`. See [Look up many at once](/docs/sdk/look-up-many-at-once). In React, use [`useAddress`](/docs/reference/react/use-address). ## Parameters [#parameters] | Option | Type | Default | Description | | --- | --- | --- | --- | | `name` (required) | `string` | | ENS name to read. Normalized automatically. | | `coin` | `CoinType.Input` | `"eth"` | Coin to read: a symbol, `{ chainId }` or a coin type. | Also takes the [read options](/docs/reference/sdk/client#read-options). ## Returns [#returns] Resolves to `getAddress.ReturnType`. An `Address` for EVM coins, the coin's native format otherwise; `null` when not set. ## Errors [#errors] | Error | Codes | When | | --- | --- | --- | | [`InvalidInputError`](/docs/reference/errors/invalid-input-error) | [`INVALID_NAME`](/docs/reference/errors/INVALID_NAME), [`INVALID_COIN_TYPE`](/docs/reference/errors/INVALID_COIN_TYPE) | invalid input. | | [`NotFoundError`](/docs/reference/errors/not-found-error) | [`RECORD_NOT_FOUND`](/docs/reference/errors/RECORD_NOT_FOUND), [`RESOLVER_NOT_FOUND`](/docs/reference/errors/RESOLVER_NOT_FOUND) | with `strict`. | | [`UnsupportedError`](/docs/reference/errors/unsupported-error) | [`RESOLVER_PROFILE_UNSUPPORTED`](/docs/reference/errors/RESOLVER_PROFILE_UNSUPPORTED) | with `strict` when the resolver supports none of the records. | | [`GatewayError`](/docs/reference/errors/gateway-error) | [`GATEWAY_REQUEST_FAILED`](/docs/reference/errors/GATEWAY_REQUEST_FAILED), [`GATEWAY_RESPONSE_INVALID`](/docs/reference/errors/GATEWAY_RESPONSE_INVALID), [`OFFCHAIN_LOOKUP_INVALID`](/docs/reference/errors/OFFCHAIN_LOOKUP_INVALID) | an off-chain gateway fails. | | [`DnsError`](/docs/reference/errors/dns-error) | | a DNS name's DNSSEC proof does not verify. | | [`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="Resolving an Ethereum address" const address = await ens.record.getAddress({ name: "nick.eth" }) ``` ```ts title="Resolving a Bitcoin address with a bare viem client" import { Actions } from "@ensforge/sdk" const btc = await Actions.record.getAddress(publicClient, { name: "nick.eth", coin: "btc" }) ``` ```ts title="Resolving a Base address in an Effect program" import { Actions } from "@ensforge/sdk/effect" const base = yield* Actions.record.getAddress(ens, { name: "nick.eth", coin: { chainId: 8453 } }) ``` ## Example response [#example-response] Recorded from Ethereum mainnet on 2026-11-18 at block 26443964. Values change as the chain does. ```ts await ens.record.getAddress({ name: "nick.eth" }) ``` ```json "0xb8c2C29ee19D8307cb7255e1Cd9CbDE883A267d5" ``` ## See also [#see-also] - [`record.get`](/docs/reference/sdk/record/get) to read several records # record.getAvatar > For the complete documentation index, see [llms.txt](https://ensforge.com/llms.txt). Reads the avatar of an ENS name and resolves it to a URL a browser can load (ENSIP-12). Options, result, errors and examples for record.getAvatar. Source: https://ensforge.com/docs/reference/sdk/record/get-avatar Reads the avatar of an ENS name and resolves it to a URL a browser can load (ENSIP-12). ## When to use [#when-to-use] Use to show a profile picture for a name. ## Details [#details] - `http(s)` and `data:` URIs are returned as-is; `ipfs://`, `ipns://`, `ar://` and bare CIDs go through `gateways`: the call's, else the client's (`Ensforge.create({ gateways })`), else `https://ipfs.io` and `https://arweave.net` (the client config also has a Swarm gateway, `https://api.gateway.ethswarm.org`, used for `bzz://` content hashes, not avatars). - NFT avatars (`eip155:1/erc721:…/…`, `erc1155`) read the token's metadata and return its image. They resolve only on the client's own chain, and only when the name's ETH address owns the token (ENSIP-12): `ownerOf` for ERC-721, a non-zero balance for ERC-1155. - Returns `null` when the avatar is not set or cannot be loaded, unless `strict` is set. - The public `ipfs.io` gateway is rate limited (HTTP 429 under load): set your own gateway in production. ## Signature [#signature] ```ts function getAvatar(client: Like, options: getAvatar.Options): Promise ``` Call it as `ens.record.getAvatar(options)` on a client, or `Actions.record.getAvatar(client, options)`. `record.getAvatar.request(options)` builds a deferred read for `Actions.batch`. See [Look up many at once](/docs/sdk/look-up-many-at-once). In React, use [`useAvatar`](/docs/reference/react/use-avatar). ## Parameters [#parameters] | Option | Type | Default | Description | | --- | --- | --- | --- | | `name` (required) | `string` | | ENS name to read. Normalized automatically. | | `gateways` | `Gateways` | | HTTP gateways for IPFS and Arweave content, overriding the client's `gateways`. | | `timeout` | `number` | `10000` | Milliseconds to wait for NFT metadata. | Also takes the [read options](/docs/reference/sdk/client#read-options). ## Returns [#returns] Resolves to `string | null`. An `http(s)` or `data:` URL, 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. | | [`NotFoundError`](/docs/reference/errors/not-found-error) | [`RECORD_NOT_FOUND`](/docs/reference/errors/RECORD_NOT_FOUND), [`RESOLVER_NOT_FOUND`](/docs/reference/errors/RESOLVER_NOT_FOUND) | with `strict`. | | [`UnsupportedError`](/docs/reference/errors/unsupported-error) | [`RESOLVER_PROFILE_UNSUPPORTED`](/docs/reference/errors/RESOLVER_PROFILE_UNSUPPORTED) | with `strict` when the resolver supports none of the records. | | [`GatewayError`](/docs/reference/errors/gateway-error) | [`GATEWAY_REQUEST_FAILED`](/docs/reference/errors/GATEWAY_REQUEST_FAILED), [`GATEWAY_RESPONSE_INVALID`](/docs/reference/errors/GATEWAY_RESPONSE_INVALID) | with `strict` when NFT metadata cannot be loaded. | | [`DnsError`](/docs/reference/errors/dns-error) | | a DNS name's DNSSEC proof does not verify. | | [`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="Showing a profile picture" const src = await ens.record.getAvatar({ name: "nick.eth" }) ``` ```ts title="Using your own IPFS gateway" import { Actions } from "@ensforge/sdk" const src = await Actions.record.getAvatar(publicClient, { name: "nick.eth", gateways: { ipfs: "https://gateway.pinata.cloud" } }) ``` ```ts title="Reading in an Effect program" import { Actions } from "@ensforge/sdk/effect" const src = yield* Actions.record.getAvatar(ens, { name: "nick.eth" }) ``` ## Example response [#example-response] Recorded from Ethereum mainnet on 2026-11-18 at block 26443964. Values change as the chain does. ```ts await ens.record.getAvatar({ name: "jesse.base.eth" }) ``` ```json "https://zku9gdedgba48lmr.public.blob.vercel-storage.com/basenames/avatar/jesse.base.eth/1722020142962/cryptopunk-diuDROjlL5OLY6EcC5keHTsNAiWMSL.png" ``` ## See also [#see-also] - [`record.getText`](/docs/reference/sdk/record/get-text) to read the raw avatar record # record.getContentHash > For the complete documentation index, see [llms.txt](https://ensforge.com/llms.txt). Reads the content hash of an ENS name (ENSIP-7), decoded into its protocol, value and URI. Options, result, errors and examples for record.getContentHash. Source: https://ensforge.com/docs/reference/sdk/record/get-content-hash Reads the content hash of an ENS name (ENSIP-7), decoded into its protocol, value and URI. ## When to use [#when-to-use] Use to find the website or content a name points to, such as an IPFS site. ## Details [#details] - Supports `ipfs`, `ipns`, `bzz` (Swarm), `onion`, `onion3`, `sia` (Skynet) and `ar` (Arweave). - Turn the URI into an HTTP URL through the client's gateways with `ContentHash.toGatewayUrl(uri, ens.config.gateways)`. - Returns `null` when the record is not set or cannot be decoded, unless `strict` is set. ## Signature [#signature] ```ts function getContentHash( client: Like, options: getContentHash.Options, ): Promise ``` Call it as `ens.record.getContentHash(options)` on a client, or `Actions.record.getContentHash(client, options)`. `record.getContentHash.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 to read. Normalized automatically. | Also takes the [read options](/docs/reference/sdk/client#read-options). ## Returns [#returns] Resolves to `Decoded | null`. The decoded content hash, or `null` when not set. | Field | Type | Description | | --- | --- | --- | | `protocol` | `Protocol` | | | `value` | `string` | The identifier without scheme, e.g. a CID. | | `uri` | `string` | `protocol://value`. | ## Errors [#errors] | Error | Codes | When | | --- | --- | --- | | [`InvalidInputError`](/docs/reference/errors/invalid-input-error) | [`INVALID_NAME`](/docs/reference/errors/INVALID_NAME) | the name cannot be normalized. | | [`NotFoundError`](/docs/reference/errors/not-found-error) | [`RECORD_NOT_FOUND`](/docs/reference/errors/RECORD_NOT_FOUND), [`RESOLVER_NOT_FOUND`](/docs/reference/errors/RESOLVER_NOT_FOUND) | with `strict`. | | [`UnsupportedError`](/docs/reference/errors/unsupported-error) | [`RESOLVER_PROFILE_UNSUPPORTED`](/docs/reference/errors/RESOLVER_PROFILE_UNSUPPORTED) | with `strict` when the resolver supports none of the records. | | [`GatewayError`](/docs/reference/errors/gateway-error) | [`GATEWAY_REQUEST_FAILED`](/docs/reference/errors/GATEWAY_REQUEST_FAILED), [`GATEWAY_RESPONSE_INVALID`](/docs/reference/errors/GATEWAY_RESPONSE_INVALID), [`OFFCHAIN_LOOKUP_INVALID`](/docs/reference/errors/OFFCHAIN_LOOKUP_INVALID) | an off-chain gateway fails. | | [`DnsError`](/docs/reference/errors/dns-error) | | a DNS name's DNSSEC proof does not verify. | | [`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 website" const site = await ens.record.getContentHash({ name: "vitalik.eth" }) site?.uri // "ipfs://…" ``` ```ts title="Reading with a bare viem client" import { Actions } from "@ensforge/sdk" const site = await Actions.record.getContentHash(publicClient, { name: "vitalik.eth" }) ``` ```ts title="Reading in an Effect program" import { Actions } from "@ensforge/sdk/effect" const site = yield* Actions.record.getContentHash(ens, { name: "vitalik.eth" }) ``` ## Example response [#example-response] Recorded from Ethereum mainnet on 2026-11-18 at block 26443964. Values change as the chain does. ```ts await ens.record.getContentHash({ name: "ens.eth" }) ``` ```json { "protocol": "bzz", "value": "f5909b5286d9279a1f6a23d5155ddd72bb0f28f56b6b82c32de54a6529e6b1b0", "uri": "bzz://f5909b5286d9279a1f6a23d5155ddd72bb0f28f56b6b82c32de54a6529e6b1b0" } ``` ## See also [#see-also] - [`record.get`](/docs/reference/sdk/record/get) to read several records # record.getText > For the complete documentation index, see [llms.txt](https://ensforge.com/llms.txt). Reads one text record of an ENS name, such as url, avatar or com.twitter. Parameters, return value, errors and examples for record.getText in @ensforge/sdk. Source: https://ensforge.com/docs/reference/sdk/record/get-text Reads one text record of an ENS name, such as `url`, `avatar` or `com.twitter`. ## When to use [#when-to-use] Use to read a single profile field. Use `record.get` to read several records in one call. ## Details [#details] - Resolves through the Universal Resolver, so ENSv1, ENSv2, wildcard and off-chain (CCIP-Read) names all work. - Returns `null` when the record, the resolver, or the resolver's text support is missing, unless `strict` is set. - Calls made in the same tick are batched into one multicall where possible. ## Signature [#signature] ```ts function getText(client: Like, options: getText.Options): Promise ``` Call it as `ens.record.getText(options)` on a client, or `Actions.record.getText(client, options)`. `record.getText.request(options)` builds a deferred read for `Actions.batch`. See [Look up many at once](/docs/sdk/look-up-many-at-once). In React, use [`useText`](/docs/reference/react/use-text). ## Parameters [#parameters] | Option | Type | Default | Description | | --- | --- | --- | --- | | `name` (required) | `string` | | ENS name to read. Normalized automatically. | | `key` (required) | `string` | | Text record key, e.g. `url`, `avatar`, `com.twitter`. | Also takes the [read options](/docs/reference/sdk/client#read-options). ## Returns [#returns] Resolves to `string | null`. The record value, or `null` when it is not set. ## Errors [#errors] | Error | Codes | When | | --- | --- | --- | | [`InvalidInputError`](/docs/reference/errors/invalid-input-error) | [`INVALID_NAME`](/docs/reference/errors/INVALID_NAME) | the name cannot be normalized. | | [`NotFoundError`](/docs/reference/errors/not-found-error) | [`RECORD_NOT_FOUND`](/docs/reference/errors/RECORD_NOT_FOUND), [`RESOLVER_NOT_FOUND`](/docs/reference/errors/RESOLVER_NOT_FOUND) | with `strict`. | | [`UnsupportedError`](/docs/reference/errors/unsupported-error) | [`RESOLVER_PROFILE_UNSUPPORTED`](/docs/reference/errors/RESOLVER_PROFILE_UNSUPPORTED) | with `strict` when the resolver supports none of the records. | | [`GatewayError`](/docs/reference/errors/gateway-error) | [`GATEWAY_REQUEST_FAILED`](/docs/reference/errors/GATEWAY_REQUEST_FAILED), [`GATEWAY_RESPONSE_INVALID`](/docs/reference/errors/GATEWAY_RESPONSE_INVALID), [`OFFCHAIN_LOOKUP_INVALID`](/docs/reference/errors/OFFCHAIN_LOOKUP_INVALID) | an off-chain gateway fails. | | [`DnsError`](/docs/reference/errors/dns-error) | | a DNS name's DNSSEC proof does not verify. | | [`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 profile URL" const url = await ens.record.getText({ name: "nick.eth", key: "url" }) ``` ```ts title="Reading with a bare viem client" import { Actions } from "@ensforge/sdk" const url = await Actions.record.getText(publicClient, { name: "nick.eth", key: "url" }) ``` ```ts title="Reading in an Effect program" import { Actions } from "@ensforge/sdk/effect" const url = yield* Actions.record.getText(ens, { name: "nick.eth", key: "url" }) ``` ## Example response [#example-response] Recorded from Ethereum mainnet on 2026-11-18 at block 26443964. Values change as the chain does. ```ts await ens.record.getText({ name: "vitalik.eth", key: "url" }) ``` ```json "https://vitalik.ca" ``` ## See also [#see-also] - [`record.set`](/docs/reference/sdk/record/set) to write text records # record.get > For the complete documentation index, see [llms.txt](https://ensforge.com/llms.txt). Reads any mix of a name's records in one request: texts, addresses, content hash, ABI, public key, name record, interface implementers and data records. Source: https://ensforge.com/docs/reference/sdk/record/get Reads any mix of a name's records in one request: texts, addresses, content hash, ABI, public key, name record, interface implementers and data records. ## When to use [#when-to-use] Use to load a profile or several records at once. Use `record.getText` or `record.getAddress` for a single value. ## Details [#details] - One Universal Resolver call, whatever the selection (ENSv1, ENSv2, wildcard and off-chain names). ENSv1 names answered through the ENSv1 bridge cost one more batched call, to report the ENSv1 resolver behind it in `resolver`. - The result has exactly the selected fields: `texts.url` exists only when `"url"` was requested. - Missing records are `null`. A missing resolver gives `resolver: null` and every record `null`, unless `strict` is set. - EVM chain addresses fall back to the default EVM address (ENSIP-19). ## Signature [#signature] ```ts function get( client: Like, options: get.Options & selection, ): Promise> ``` Call it as `ens.record.get(options)` on a client, or `Actions.record.get(client, options)`. `record.get.request(options)` builds a deferred read for `Actions.batch`. See [Look up many at once](/docs/sdk/look-up-many-at-once). In React, use [`useRecords`](/docs/reference/react/use-records). ## Parameters [#parameters] | Option | Type | Default | Description | | --- | --- | --- | --- | | `texts` | `readonly string[]` | | Text record keys, e.g. `["url", "avatar", "com.twitter"]`. | | `addresses` | `readonly (string \| bigint)[]` | | Coins by symbol (`"eth"`, `"btc"`, `"base"`) or coin type (`2147492101n`). EVM chains fall back to the default EVM address (ENSIP-19). | | `contentHash` | `true` | | Read the content hash (ENSIP-7). | | `abi` | `true \| { readonly contentTypes: bigint }` | | Read the ABI record (ENSIP-4); `contentTypes` is a bitmask of acceptable types. | | `pubkey` | `true` | | Read the SECP256k1 public key. | | `nameRecord` | `true` | | Read the `name` record (ENSIP-3), used for reverse resolution. | | `interfaces` | `readonly Hex[]` | | ERC-165 interface IDs to read implementers for. | | `data` | `readonly string[]` | | Data record keys (ENSIP-24). | | `name` (required) | `string` | | ENS name to read. Normalized automatically. | Also takes the [read options](/docs/reference/sdk/client#read-options). ## Returns [#returns] Resolves to `Records`. The selected records. ## Errors [#errors] | Error | Codes | When | | --- | --- | --- | | [`InvalidInputError`](/docs/reference/errors/invalid-input-error) | [`INVALID_NAME`](/docs/reference/errors/INVALID_NAME), [`INVALID_COIN_TYPE`](/docs/reference/errors/INVALID_COIN_TYPE) | invalid input. | | [`NotFoundError`](/docs/reference/errors/not-found-error) | [`RESOLVER_NOT_FOUND`](/docs/reference/errors/RESOLVER_NOT_FOUND) | with `strict` when the name has no resolver. | | [`UnsupportedError`](/docs/reference/errors/unsupported-error) | [`RESOLVER_PROFILE_UNSUPPORTED`](/docs/reference/errors/RESOLVER_PROFILE_UNSUPPORTED) | with `strict` when the resolver supports none of the records. | | [`GatewayError`](/docs/reference/errors/gateway-error) | [`GATEWAY_REQUEST_FAILED`](/docs/reference/errors/GATEWAY_REQUEST_FAILED), [`GATEWAY_RESPONSE_INVALID`](/docs/reference/errors/GATEWAY_RESPONSE_INVALID), [`OFFCHAIN_LOOKUP_INVALID`](/docs/reference/errors/OFFCHAIN_LOOKUP_INVALID) | an off-chain gateway fails. | | [`DnsError`](/docs/reference/errors/dns-error) | | a DNS name's DNSSEC proof does not verify. | | [`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="Loading a profile" const profile = await ens.record.get({ name: "nick.eth", texts: ["avatar", "url"], addresses: ["eth", "btc"] }) profile.texts.url // string | null ``` ```ts title="Reading with a bare viem client" import { Actions } from "@ensforge/sdk" const { contentHash } = await Actions.record.get(publicClient, { name: "vitalik.eth", contentHash: true }) ``` ```ts title="Reading in an Effect program" import { Actions } from "@ensforge/sdk/effect" const records = yield* Actions.record.get(ens, { name: "nick.eth", texts: ["url"] }) ``` ## Example response [#example-response] Recorded from Ethereum mainnet on 2026-11-18 at block 26443964. Values change as the chain does. ```ts await ens.record.get({ name: "vitalik.eth", texts: ["url", "com.twitter"], addresses: ["eth"] }) ``` ```json { "resolver": "0x231b0Ee14048e9dCcD1d247744d114a4EB5E8E63", "texts": { "url": "https://vitalik.ca", "com.twitter": "VitalikButerin" }, "addresses": { "eth": "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045" } } ``` ## See also [#see-also] - [`record.set`](/docs/reference/sdk/record/set) to write records # record > For the complete documentation index, see [llms.txt](https://ensforge.com/llms.txt). List the 6 record actions of @ensforge/sdk and whether each reads, writes or signs. Covers get, getAddress, getAvatar, getContentHash, getText, set. Source: https://ensforge.com/docs/reference/sdk/record Call them as `ens.record.(options)` on a client, or `Actions.record.(client, options)`. ## Reads [#reads] | Action | Description | | --- | --- | | [`get`](/docs/reference/sdk/record/get) (batchable) | Reads any mix of a name's records in one request: texts, addresses, content hash, ABI, public key, name record, interface implementers and data records. | | [`getAddress`](/docs/reference/sdk/record/get-address) (batchable) | Reads one address record of an ENS name, for Ethereum by default or any coin (ENSIP-9, ENSIP-11). | | [`getAvatar`](/docs/reference/sdk/record/get-avatar) (batchable) | Reads the avatar of an ENS name and resolves it to a URL a browser can load (ENSIP-12). | | [`getContentHash`](/docs/reference/sdk/record/get-content-hash) (batchable) | Reads the content hash of an ENS name (ENSIP-7), decoded into its protocol, value and URI. | | [`getText`](/docs/reference/sdk/record/get-text) (batchable) | Reads one text record of an ENS name, such as `url`, `avatar` or `com.twitter`. | ## Writes [#writes] | Action | Description | | --- | --- | | [`set`](/docs/reference/sdk/record/set) | Writes records of an ENS name and resolves once the transaction is submitted. | # record.set > For the complete documentation index, see [llms.txt](https://ensforge.com/llms.txt). Writes records of an ENS name and resolves once the transaction is submitted. Parameters, return value, errors and examples for record.set in @ensforge/sdk. Source: https://ensforge.com/docs/reference/sdk/record/set Writes records of an ENS name and resolves once the transaction is submitted. ## When to use [#when-to-use] Use to update a profile (texts, addresses, content hash and more) when the UI tracks confirmation itself. Use [`setSync`](/docs/reference/sdk/record/set#wait-for-the-receipt-with-setsync) to wait for the receipt instead. ## Details [#details] - `null` deletes a record. - All records are written in one `multicall` on the resolver. - Works with ENSv1 resolvers and the ENSv2 PermissionedResolver; the kind is detected on-chain. - The records go to the resolver set on the name in its registry, never to a wildcard resolver inherited from a parent. - `resolver` writes the records to another resolver, then points the name at it, in one step: a rejected write never leaves the name on an empty resolver. - Each kind of record is checked against the profiles the resolver declares through ERC-165, and `clear` against its record versions, before anything is simulated; a resolver without ERC-165 is left to the simulation. - The plan is simulated before the wallet prompt, so permission errors surface first. - The ENSv2 PermissionedResolver has no `pubkey` records. `clear` there links the name to record 0 (needs the root `link` role), so it reads the resolver's default record until new records are written. - Older resolvers lack newer profiles (the 2020 public resolver has no `data` records and cannot `clear`), and resolvers that keep their records off-chain (EIP-3668, ERC-5559, ERC-7884) take no on-chain writes. Both fail with [`RESOLVER_PROFILE_UNSUPPORTED`](/docs/reference/errors/RESOLVER_PROFILE_UNSUPPORTED); for an off-chain resolver, `details` say where its records live. - `resolver: "default"` (the ENSv1 public resolver) is for ENSv1 names only; ENSv2 names pass the address of a resolver such as their own PermissionedResolver. ## Signature [#signature] ```ts function set(client: Like, options: set.Options & Write.Options): Promise ``` Call it as `ens.record.set(options)` on a client, or `Actions.record.set(client, options)`. In React, use [`useSetRecords`](/docs/reference/react/use-set-records). ## Parameters [#parameters] | Option | Type | Default | Description | | --- | --- | --- | --- | | `name` (required) | `string` | | ENS name to update. Normalized automatically. | | `texts` | `Readonly>` | | Text records by key. `null` deletes the record. | | `addresses` | `Readonly>` | | Address records by coin symbol (`eth`, `btc`) or decimal coin type (`"2147492101"`). `null` deletes the record. | | `contentHash` | `string \| null` | | Content hash URI such as `ipfs://…`. `null` deletes it. | | `abi` | `{ contentType?: 1n \| 2n \| 4n \| 8n \| undefined; value: Abi \| Hex \| null }` | | ABI record (ENSIP-4). An `Abi` is stored as JSON (content type 1); hex bytes are stored as given under `contentType`. `null` deletes the record of that content type. | | `pubkey` | `{ x: Hex; y: Hex } \| null` | | SECP256k1 public key. `null` deletes it. Node-based resolvers only. | | `nameRecord` | `string \| null` | | Name record (the `name()` of reverse names). `null` deletes it. | | `interfaces` | `Readonly>` | | ERC-165 interface implementers by 4-byte interface ID. `null` deletes one. | | `data` | `Readonly>` | | Data records (ENSIP-24) by key. `null` deletes one. | | `clear` | `boolean` | | Deletes every existing record first. | | `resolver` | `Address \| "default"` | | Writes the records to this resolver, then points the name at it. `"default"` is the ENSv1 public resolver, for ENSv1 names only. | 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_COIN_TYPE`](/docs/reference/errors/INVALID_COIN_TYPE), [`INVALID_CONTENT_HASH`](/docs/reference/errors/INVALID_CONTENT_HASH), [`INVALID_RECORD_VALUE`](/docs/reference/errors/INVALID_RECORD_VALUE) | invalid input. | | [`NotFoundError`](/docs/reference/errors/not-found-error) | [`RESOLVER_NOT_FOUND`](/docs/reference/errors/RESOLVER_NOT_FOUND) | the name has no resolver of its own. | | [`UnsupportedError`](/docs/reference/errors/unsupported-error) | [`RESOLVER_PROFILE_UNSUPPORTED`](/docs/reference/errors/RESOLVER_PROFILE_UNSUPPORTED), [`UNSUPPORTED_PROTOCOL`](/docs/reference/errors/UNSUPPORTED_PROTOCOL) | 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. | | [`NameStateError`](/docs/reference/errors/name-state-error) | [`NAME_EXPIRED`](/docs/reference/errors/NAME_EXPIRED), [`NAME_RESERVED`](/docs/reference/errors/NAME_RESERVED), [`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. | | [`UnauthorizedError`](/docs/reference/errors/unauthorized-error) | [`NOT_OWNER`](/docs/reference/errors/NOT_OWNER), [`MISSING_ROLES`](/docs/reference/errors/MISSING_ROLES) | the account may not edit records. | | [`ConfigError`](/docs/reference/errors/config-error) | [`WALLET_NOT_CONFIGURED`](/docs/reference/errors/WALLET_NOT_CONFIGURED) | the client has no wallet. | | [`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="Updating a profile" const { hash } = await ens.record.set({ name: "alice.eth", texts: { url: "https://alice.dev" }, addresses: { eth: "0x225f137127d9067788314bc7fcc1f36746a3c3B5" }, }) ``` ```ts title="Deleting a record with a standalone call" import { Actions } from "@ensforge/sdk" await Actions.record.set(ens, { name: "alice.eth", texts: { url: null } }) ``` ```ts title="Switching to the public resolver in an Effect program" import { Actions } from "@ensforge/sdk/effect" const { hash } = yield* Actions.record.set(ens, { name: "alice.eth", resolver: "default", contentHash: "ipfs://bafybeigdyrzt5sfp7udm7hu76uh7y26nf3efuylqabf3oclgtqy55fbzdi", }) ``` ## Plan methods [#plan-methods] Each method takes the same options as `record.set` and sends nothing. See [Preview before sending](/docs/sdk/preview-before-sending). | Method | Description | | --- | --- | | `record.set.prepare(options)` | Builds the plan without sending anything. | | `record.set.simulate(options)` | Simulates the plan with `eth_call`, reporting each step. | | `record.set.estimateGas(options)` | Estimates the gas and ETH the plan needs. | ## Wait for the receipt with `setSync` [#wait-for-the-receipt-with-setsync] Writes records of an ENS name and resolves once the receipt is in. Use when the next step depends on the records being confirmed on-chain. `record.setSync` 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="Updating a profile URL and waiting" const { receipt } = await ens.record.setSync({ name: "alice.eth", texts: { url: "https://alice.dev" } }) ``` ```ts title="Waiting with a standalone call" import { Actions } from "@ensforge/sdk" await Actions.record.setSync(ens, { name: "alice.eth", texts: { url: "https://alice.dev" } }) ``` ```ts title="Waiting in an Effect program" import { Actions } from "@ensforge/sdk/effect" yield* Actions.record.setSync(ens, { name: "alice.eth", texts: { url: "https://alice.dev" } }) ``` ## See also [#see-also] - [`record.get`](/docs/reference/sdk/record/get) to read records # registration.commit > For the complete documentation index, see [llms.txt](https://ensforge.com/llms.txt). Commits to registering .eth names, the first half of a registration. Parameters, return value, errors and examples for registration.commit in @ensforge/sdk. Source: https://ensforge.com/docs/reference/sdk/registration/commit Commits to registering `.eth` names, the first half of a registration. Resolves once the transaction is submitted. ## When to use [#when-to-use] Use when registration is split across sessions or devices; `register` alone does both halves. Use [`commitSync`](/docs/reference/sdk/registration/commit#wait-for-the-receipt-with-commitsync) to wait for the receipt. ## Details [#details] - Takes the same options as [`registration.register`](/docs/reference/sdk/registration/register); they are hashed into the commitment. - Keep the returned `secret`, then call `register` with the same options and `secret` once the commitment is ready (see [`registration.getCommitmentStatus`](/docs/reference/sdk/registration/get-commitment-status)). - `.prepare` and `.simulate` without `secret` use a throwaway secret. ## Signature [#signature] ```ts function commit( client: Like, options: commit.Options & Write.Options, ): Promise ``` Call it as `ens.registration.commit(options)` on a client, or `Actions.registration.commit(client, options)`. ## Parameters [#parameters] | Option | Type | Default | Description | | --- | --- | --- | --- | | `names` (required) | `string \| readonly string[]` | | One or more `.eth` second-level names; several share one plan. Normalized automatically. | | `duration` (required) | `bigint` | | Registration length in seconds, e.g. `Duration.years(1)`. | | `owner` | `string` | the signing account | Owner of the names. | | `resolver` | `string \| null` | | Resolver for the names. By default each name gets its own PermissionedResolver, deployed in the same plan with `records` written at creation. `"owned"` uses the signer's shared PermissionedResolver (the ENS app's address), deployed once and reused; its roles cover every name on it. `null` registers without a resolver. | | `records` | `Omit` | | Records for every name, written when its resolver is created (or right after registering). | | `primaryName` | `boolean` | | Set the (single) name as the signer's primary name; adds its `eth` address record. | | `paymentToken` | `PaymentToken` | `"usdc"` | Token to pay with. | | `subregistry` | `string` | | ENSv2 registry for the names' subnames. | | `referrer` | `Hex` | | Referrer recorded by the registrar: 32 bytes, or an address (left-padded). | | `secret` | `Hex` | | Secret from an earlier `commit` or `register`, to finish that registration. | Also takes the [write options](/docs/reference/sdk/client#write-options). ## Returns [#returns] Resolves to `Write.Result & { readonly secret: Hex; readonly commitments: readonly Hex[] }`. Submitted hashes, the plan, the secret and the commitments. ## 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), [`DURATION_TOO_SHORT`](/docs/reference/errors/DURATION_TOO_SHORT), [`INVALID_RECORD_VALUE`](/docs/reference/errors/INVALID_RECORD_VALUE) | invalid input. | | [`NameStateError`](/docs/reference/errors/name-state-error) | [`NAME_NOT_AVAILABLE`](/docs/reference/errors/NAME_NOT_AVAILABLE) | a name is taken or in its grace period. | | [`CommitmentError`](/docs/reference/errors/commitment-error) | [`COMMITMENT_TOO_NEW`](/docs/reference/errors/COMMITMENT_TOO_NEW), [`COMMITMENT_TOO_OLD`](/docs/reference/errors/COMMITMENT_TOO_OLD), [`COMMITMENT_EXISTS`](/docs/reference/errors/COMMITMENT_EXISTS) | a resumed commitment outside its window. | | [`UnsupportedError`](/docs/reference/errors/unsupported-error) | [`PAYMENT_TOKEN_UNSUPPORTED`](/docs/reference/errors/PAYMENT_TOKEN_UNSUPPORTED), [`UNSUPPORTED_ON_DEPLOYMENT`](/docs/reference/errors/UNSUPPORTED_ON_DEPLOYMENT) | an unaccepted token or without ENSv2. | | [`ConfigError`](/docs/reference/errors/config-error) | [`WALLET_NOT_CONFIGURED`](/docs/reference/errors/WALLET_NOT_CONFIGURED) | no signing account is known. | | [`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="Committing to a name" const { secret, commitments } = await ens.registration.commit({ names: "alice.eth", duration: 31536000n }) ``` ```ts title="Committing to a name with a standalone call" import { Actions } from "@ensforge/sdk" await Actions.registration.commit(ens, { names: "alice.eth", duration: 31536000n }) ``` ```ts title="Committing to a name in an Effect program" import { Actions } from "@ensforge/sdk/effect" yield* Actions.registration.commit(ens, { names: "alice.eth", duration: 31536000n }) ``` ## Plan methods [#plan-methods] Each method takes the same options as `registration.commit` and sends nothing. See [Preview before sending](/docs/sdk/preview-before-sending). | Method | Description | | --- | --- | | `registration.commit.prepare(options)` | Builds the plan without sending anything. | | `registration.commit.simulate(options)` | Simulates the plan with `eth_call`, reporting each step. | | `registration.commit.estimateGas(options)` | Estimates the gas and ETH the plan needs. | ## Wait for the receipt with `commitSync` [#wait-for-the-receipt-with-commitsync] Commits to registering `.eth` names, the first half of a registration. Resolves once the receipt is in. Use when the next step depends on the change being on-chain. `registration.commitSync` takes the same options plus [`confirmations` and `timeout`](/docs/reference/sdk/client#sync-options). Resolves to `commitSync.ReturnType`. Receipts, the secret, the commitments and when they can be used. ```ts title="Committing to a name and waiting" const { receipt } = await ens.registration.commitSync({ names: "alice.eth", duration: 31536000n }) ``` ```ts title="Waiting with a standalone call" import { Actions } from "@ensforge/sdk" await Actions.registration.commitSync(ens, { names: "alice.eth", duration: 31536000n }) ``` ```ts title="Waiting in an Effect program" import { Actions } from "@ensforge/sdk/effect" yield* Actions.registration.commitSync(ens, { names: "alice.eth", duration: 31536000n }) ``` ## See also [#see-also] - [`registration.register`](/docs/reference/sdk/registration/register) to finish # registration.getCommitmentStatus > For the complete documentation index, see [llms.txt](https://ensforge.com/llms.txt). Reads where a registration commitment is in its window. Parameters, return value, errors and examples for registration.getCommitmentStatus in @ensforge/sdk. Source: https://ensforge.com/docs/reference/sdk/registration/get-commitment-status Reads where a registration commitment is in its window. ## When to use [#when-to-use] Use to show a countdown between `registration.commit` and `registration.register`. ## Details [#details] - `pending`: too new to register; `ready`: register now; `expired`: commit again. - `unknown`: never made, or already used by a registration. ## Signature [#signature] ```ts function getCommitmentStatus( client: Like, options: getCommitmentStatus.Options, ): Promise ``` Call it as `ens.registration.getCommitmentStatus(options)` on a client, or `Actions.registration.getCommitmentStatus(client, options)`. `registration.getCommitmentStatus.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 | | --- | --- | --- | --- | | `commitment` (required) | `Hex` | | Commitment hash returned by `registration.commit`. | Also takes the [read options](/docs/reference/sdk/client#read-options). ## Returns [#returns] Resolves to `getCommitmentStatus.ReturnType`. The status and the window's timestamps (`null` when unknown). | Field | Type | Description | | --- | --- | --- | | `status` | `"pending" \| "ready" \| "expired" \| "unknown"` | | | `committedAt` | `bigint \| null` | | | `readyAt` | `bigint \| null` | | | `expiresAt` | `bigint \| null` | | ## Errors [#errors] | Error | Codes | When | | --- | --- | --- | | [`InvalidInputError`](/docs/reference/errors/invalid-input-error) | [`INVALID_RECORD_VALUE`](/docs/reference/errors/INVALID_RECORD_VALUE) | the commitment is not 32 bytes. | | [`UnsupportedError`](/docs/reference/errors/unsupported-error) | [`UNSUPPORTED_ON_DEPLOYMENT`](/docs/reference/errors/UNSUPPORTED_ON_DEPLOYMENT) | without ENSv2. | | [`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="Waiting for a commitment" const { status, readyAt } = await ens.registration.getCommitmentStatus({ commitment }) ``` ```ts title="Reading with a standalone call" import { Actions } from "@ensforge/sdk" const status = await Actions.registration.getCommitmentStatus(publicClient, { commitment }) ``` ```ts title="Reading in an Effect program" import { Actions } from "@ensforge/sdk/effect" const status = yield* Actions.registration.getCommitmentStatus(ens, { commitment }) ``` ## See also [#see-also] - [`registration.commit`](/docs/reference/sdk/registration/commit) to make one # registration.getParameters > For the complete documentation index, see [llms.txt](https://ensforge.com/llms.txt). Reads the .eth registration settings: contracts, commitment window, minimum duration, grace period and accepted payment tokens. Source: https://ensforge.com/docs/reference/sdk/registration/get-parameters Reads the `.eth` registration settings: contracts, commitment window, minimum duration, grace period and accepted payment tokens. ## When to use [#when-to-use] Use to build registration UIs: the commitment wait, the shortest duration, and which tokens to offer. ## Signature [#signature] ```ts function getParameters( client: Like, options?: getParameters.Options, ): Promise ``` Call it as `ens.registration.getParameters(options)` on a client, or `Actions.registration.getParameters(client, options)`. `registration.getParameters.request(options)` builds a deferred read for `Actions.batch`. See [Look up many at once](/docs/sdk/look-up-many-at-once). ## Parameters [#parameters] Also takes the [read options](/docs/reference/sdk/client#read-options). ## Returns [#returns] Resolves to `getParameters.ReturnType`. Registration settings; durations and ages are in seconds. | Field | Type | Description | | --- | --- | --- | | `registrar` | `Address` | | | `renewer` | `Address` | | | `priceOracle` | `Address` | | | `minCommitmentAge` | `bigint` | | | `maxCommitmentAge` | `bigint` | | | `minDuration` | `bigint` | | | `gracePeriod` | `bigint` | | | `paymentTokens` | `readonly TokenInfo[]` | Tokens listed for the deployment that the price oracle currently accepts. | ## Errors [#errors] | Error | Codes | When | | --- | --- | --- | | [`UnsupportedError`](/docs/reference/errors/unsupported-error) | [`UNSUPPORTED_ON_DEPLOYMENT`](/docs/reference/errors/UNSUPPORTED_ON_DEPLOYMENT) | without ENSv2. | | [`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 the settings" const { minCommitmentAge, paymentTokens } = await ens.registration.getParameters() ``` ```ts title="Reading with a standalone call" import { Actions } from "@ensforge/sdk" const parameters = await Actions.registration.getParameters(publicClient) ``` ```ts title="Reading in an Effect program" import { Actions } from "@ensforge/sdk/effect" const parameters = yield* Actions.registration.getParameters(ens) ``` ## Example response [#example-response] Recorded from Ethereum mainnet on 2026-11-18 at block 26443964. Values change as the chain does. ```ts await ens.registration.getParameters({}) ``` ```json { "registrar": "0xD6D8369e55c94Ae8AFA714E6cF7AB5bE54D5CC81", "renewer": "0x56c447F308F463A01121C41E72b0E7e7557fCb68", "priceOracle": "0x76F29609A363a8A1a2a6abe2e859C0F8916Af469", "minCommitmentAge": "60n", "maxCommitmentAge": "86400n", "minDuration": "2419200n", "gracePeriod": "2419200n", "paymentTokens": [ { "address": "0x6B175474E89094C44Da98b954EedeAC495271d0F", "symbol": "DAI", "decimals": 18 }, { "address": "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48", "symbol": "USDC", "decimals": 6 } ] } ``` ## See also [#see-also] - [`registration.register`](/docs/reference/sdk/registration/register) to register # registration.getPrice > For the complete documentation index, see [llms.txt](https://ensforge.com/llms.txt). Quotes the price of registering a .eth name, in an ERC-20 payment token. Options, result, errors and examples for registration.getPrice. Source: https://ensforge.com/docs/reference/sdk/registration/get-price Quotes the price of registering a `.eth` name, in an ERC-20 payment token. ## When to use [#when-to-use] Use to show the cost before registering, or to see how a recently expired name's premium falls over time. ## Details [#details] - `base` is the yearly rent for the label length times the duration; `premium` is charged for names that recently became available and decays to zero. - Amounts are in the token's smallest unit (USDC has 6 decimals); `token` gives its symbol and decimals. - `at` prices the name at a future timestamp, e.g. to show when the premium ends. - The ENSv2 registrar is paid in ERC-20 only; there is no ETH price. ## Signature [#signature] ```ts function getPrice(client: Like, options: getPrice.Options): Promise ``` Call it as `ens.registration.getPrice(options)` on a client, or `Actions.registration.getPrice(client, options)`. `registration.getPrice.request(options)` builds a deferred read for `Actions.batch`. See [Look up many at once](/docs/sdk/look-up-many-at-once). In React, use [`useRegistrationPrice`](/docs/reference/react/use-registration-price). ## Parameters [#parameters] | Option | Type | Default | Description | | --- | --- | --- | --- | | `name` (required) | `string` | | `.eth` second-level name. Normalized automatically. | | `duration` (required) | `bigint` | | Registration length in seconds, e.g. `Duration.years(1)`. | | `paymentToken` | `PaymentToken` | `"usdc"` | Token to pay with. | | `at` | `bigint` | the current block's timestamp | Unix timestamp to price at, for the premium of a recently expired name. | Also takes the [read options](/docs/reference/sdk/client#read-options). ## Returns [#returns] Resolves to `getPrice.ReturnType`. Rent, premium and their total, in `token` units. | Field | Type | Description | | --- | --- | --- | | `base` | `bigint` | | | `premium` | `bigint` | | | `total` | `bigint` | | | `token` | `TokenInfo` | | ## 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), [`DURATION_TOO_SHORT`](/docs/reference/errors/DURATION_TOO_SHORT) | invalid input. | | [`UnsupportedError`](/docs/reference/errors/unsupported-error) | [`PAYMENT_TOKEN_UNSUPPORTED`](/docs/reference/errors/PAYMENT_TOKEN_UNSUPPORTED), [`UNSUPPORTED_ON_DEPLOYMENT`](/docs/reference/errors/UNSUPPORTED_ON_DEPLOYMENT) | an unaccepted token or without ENSv2. | | [`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="Quoting one year" import { Duration } from "@ensforge/sdk" const { total, token } = await ens.registration.getPrice({ name: "alice.eth", duration: Duration.years(1) }) ``` ```ts title="Quoting in DAI with a standalone call" import { Actions, Duration } from "@ensforge/sdk" const price = await Actions.registration.getPrice(ens, { name: "alice.eth", duration: Duration.years(1), paymentToken: "dai" }) ``` ```ts title="Quoting in an Effect program" import { Actions } from "@ensforge/sdk/effect" const price = yield* Actions.registration.getPrice(ens, { name: "alice.eth", duration: 31536000n }) ``` ## Example response [#example-response] Recorded from Ethereum mainnet on 2026-11-18 at block 26443964. Values change as the chain does. ```ts await ens.registration.getPrice({ name: "ensforge-example.eth", duration: 31_536_000n }) ``` ```json { "base": "8000021n", "premium": "0n", "total": "8000021n", "token": { "address": "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48", "symbol": "USDC", "decimals": 6 } } ``` ## See also [#see-also] - [`registration.register`](/docs/reference/sdk/registration/register) to register it # registration.getRenewalPrice > For the complete documentation index, see [llms.txt](https://ensforge.com/llms.txt). Quotes renewing one or more .eth names, in an ERC-20 payment token. Options, result, errors and examples for registration.getRenewalPrice. Source: https://ensforge.com/docs/reference/sdk/registration/get-renewal-price Quotes renewing one or more `.eth` names, in an ERC-20 payment token. ## When to use [#when-to-use] Use to show the cost of extending names before calling [`registration.renew`](/docs/reference/sdk/registration/renew). ## Details [#details] - ENSv2 names renew through the `ETHRegistrar`; names still on ENSv1 renew through `ETHRenewerV1`. Each item says which (`route`). - Costs one batched call for any number of names. ## Signature [#signature] ```ts function getRenewalPrice( client: Like, options: getRenewalPrice.Options, ): Promise ``` Call it as `ens.registration.getRenewalPrice(options)` on a client, or `Actions.registration.getRenewalPrice(client, options)`. `registration.getRenewalPrice.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 | | --- | --- | --- | --- | | `names` (required) | `string \| readonly string[]` | | One or more `.eth` second-level names. Normalized automatically. | | `duration` (required) | `bigint` | | Renewal length in seconds. | | `paymentToken` | `PaymentToken` | `"usdc"` | Token to pay with. | Also takes the [read options](/docs/reference/sdk/client#read-options). ## Returns [#returns] Resolves to `getRenewalPrice.ReturnType`. The total and one item per name, in `token` units. | Field | Type | Description | | --- | --- | --- | | `total` | `bigint` | | | `token` | `TokenInfo` | | | `items` | `readonly { readonly name: string; readonly route: RenewalRoute; readonly amount: bigint; }[]` | | ## 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_NOT_RENEWABLE`](/docs/reference/errors/NAME_NOT_RENEWABLE) | a name is neither registered nor in its grace period. | | [`UnsupportedError`](/docs/reference/errors/unsupported-error) | [`PAYMENT_TOKEN_UNSUPPORTED`](/docs/reference/errors/PAYMENT_TOKEN_UNSUPPORTED), [`UNSUPPORTED_ON_DEPLOYMENT`](/docs/reference/errors/UNSUPPORTED_ON_DEPLOYMENT) | an unaccepted token or without ENSv2. | | [`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="Quoting two names" const { total, items } = await ens.registration.getRenewalPrice({ names: ["alice.eth", "bob.eth"], duration: 31536000n }) ``` ```ts title="Quoting with a standalone call" import { Actions } from "@ensforge/sdk" const quote = await Actions.registration.getRenewalPrice(publicClient, { names: "nick.eth", duration: 31536000n }) ``` ```ts title="Quoting in an Effect program" import { Actions } from "@ensforge/sdk/effect" const quote = yield* Actions.registration.getRenewalPrice(ens, { names: "nick.eth", duration: 31536000n }) ``` ## Example response [#example-response] Recorded from Ethereum mainnet on 2026-11-18 at block 26443964. Values change as the chain does. ```ts await ens.registration.getRenewalPrice({ names: "nick.eth", duration: 31_536_000n }) ``` ```json { "total": "160000009n", "token": { "address": "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48", "symbol": "USDC", "decimals": 6 }, "items": [ { "name": "nick.eth", "route": "v2-registrar", "amount": "160000009n" } ] } ``` ## See also [#see-also] - [`registration.renew`](/docs/reference/sdk/registration/renew) to renew # registration > For the complete documentation index, see [llms.txt](https://ensforge.com/llms.txt). List the 8 registration actions of @ensforge/sdk and whether each reads, writes or signs. Covers commit, getCommitmentStatus, getParameters, getPrice. Source: https://ensforge.com/docs/reference/sdk/registration Call them as `ens.registration.(options)` on a client, or `Actions.registration.(client, options)`. ## Reads [#reads] | Action | Description | | --- | --- | | [`getCommitmentStatus`](/docs/reference/sdk/registration/get-commitment-status) (batchable) | Reads where a registration commitment is in its window. | | [`getParameters`](/docs/reference/sdk/registration/get-parameters) (batchable) | Reads the `.eth` registration settings: contracts, commitment window, minimum duration, grace period and accepted payment tokens. | | [`getPrice`](/docs/reference/sdk/registration/get-price) (batchable) | Quotes the price of registering a `.eth` name, in an ERC-20 payment token. | | [`getRenewalPrice`](/docs/reference/sdk/registration/get-renewal-price) (batchable) | Quotes renewing one or more `.eth` names, in an ERC-20 payment token. | | [`isAvailable`](/docs/reference/sdk/registration/is-available) (batchable) | Checks whether a `.eth` name can be registered now. | ## Writes [#writes] | Action | Description | | --- | --- | | [`commit`](/docs/reference/sdk/registration/commit) | Commits to registering `.eth` names, the first half of a registration. | | [`register`](/docs/reference/sdk/registration/register) | Registers one or more `.eth` names: approve, commit, wait, register, then records and primary name. | | [`renew`](/docs/reference/sdk/registration/renew) | Renews one or more `.eth` names, ENSv1 or ENSv2, paying in an ERC-20 token. | # registration.isAvailable > For the complete documentation index, see [llms.txt](https://ensforge.com/llms.txt). Checks whether a .eth name can be registered now. Parameters, return value, errors and examples for registration.isAvailable in @ensforge/sdk. Source: https://ensforge.com/docs/reference/sdk/registration/is-available Checks whether a `.eth` name can be registered now. ## When to use [#when-to-use] Use to show whether a name is free before quoting a price or starting a registration. ## Details [#details] - Every new `.eth` name is registered on ENSv2, including names that expired on ENSv1, so one check covers both. - Names in their grace period are not available; anyone can renew them, and the name is available again once the grace period ends. - Labels the price oracle rejects (for example shorter than 3 characters) are not available. ## Signature [#signature] ```ts function isAvailable( client: Like, options: isAvailable.Options, ): Promise ``` Call it as `ens.registration.isAvailable(options)` on a client, or `Actions.registration.isAvailable(client, options)`. `registration.isAvailable.request(options)` builds a deferred read for `Actions.batch`. See [Look up many at once](/docs/sdk/look-up-many-at-once). In React, use [`useAvailability`](/docs/reference/react/use-availability). ## Parameters [#parameters] | Option | Type | Default | Description | | --- | --- | --- | --- | | `name` (required) | `string` | | `.eth` second-level name, e.g. `alice.eth`. Normalized automatically. | Also takes the [read options](/docs/reference/sdk/client#read-options). ## Returns [#returns] Resolves to `boolean`. Whether the name can be registered. ## Errors [#errors] | Error | Codes | When | | --- | --- | --- | | [`InvalidInputError`](/docs/reference/errors/invalid-input-error) | [`INVALID_NAME`](/docs/reference/errors/INVALID_NAME) | names that are not `.eth` second-level names. | | [`UnsupportedError`](/docs/reference/errors/unsupported-error) | [`UNSUPPORTED_ON_DEPLOYMENT`](/docs/reference/errors/UNSUPPORTED_ON_DEPLOYMENT) | without ENSv2. | | [`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 name" const free = await ens.registration.isAvailable({ name: "alice.eth" }) ``` ```ts title="Checking with a bare viem client" import { Actions } from "@ensforge/sdk" const free = await Actions.registration.isAvailable(publicClient, { name: "alice.eth" }) ``` ```ts title="Checking in an Effect program" import { Actions } from "@ensforge/sdk/effect" const free = yield* Actions.registration.isAvailable(ens, { name: "alice.eth" }) ``` ## Example response [#example-response] Recorded from Ethereum mainnet on 2026-11-18 at block 26443964. Values change as the chain does. ```ts await ens.registration.isAvailable({ name: "nick.eth" }) ``` ```json false ``` ## See also [#see-also] - [`registration.getPrice`](/docs/reference/sdk/registration/get-price) to quote it # registration.register > For the complete documentation index, see [llms.txt](https://ensforge.com/llms.txt). Registers one or more .eth names: approve, commit, wait, register, then records and primary name. Options, errors and examples for registration.register. Source: https://ensforge.com/docs/reference/sdk/registration/register Registers one or more `.eth` names: approve, commit, wait, register, then records and primary name. Resolves once the transaction is submitted. ## When to use [#when-to-use] Use to buy names in one flow; the plan runs every transaction in order. Use [`registerSync`](/docs/reference/sdk/registration/register#wait-for-the-receipt-with-registersync) to wait for the receipt. ## Details [#details] - The plan: approve the token (if the allowance is short) with the commit → wait the registrar's minimum commitment age on chain time → register (deploying each name's resolver) → records → primary name. - The approval covers the quote plus 2%, since the price is charged at `register` and can drift (e.g. a decaying premium); only the actual price is paid. - Paid in ERC-20 (USDC by default); the registrar does not accept ETH. - By default each name gets its own PermissionedResolver with `records` written at creation; its ETH address defaults to the owner (`addresses: { eth: null }` leaves it unset). - The result's `secret` resumes an interrupted registration: call again with the same options and `secret`. - Resolves after the last transaction is submitted, at least a minute after the commit. - Resuming needs exactly the same options: they are part of the commitment. ## Signature [#signature] ```ts function register( client: Like, options: register.Options & Write.Options, ): Promise ``` Call it as `ens.registration.register(options)` on a client, or `Actions.registration.register(client, options)`. In React, use [`useRegister`](/docs/reference/react/use-register). ## Parameters [#parameters] | Option | Type | Default | Description | | --- | --- | --- | --- | | `names` (required) | `string \| readonly string[]` | | One or more `.eth` second-level names; several share one plan. Normalized automatically. | | `duration` (required) | `bigint` | | Registration length in seconds, e.g. `Duration.years(1)`. | | `owner` | `string` | the signing account | Owner of the names. | | `resolver` | `string \| null` | | Resolver for the names. By default each name gets its own PermissionedResolver, deployed in the same plan with `records` written at creation. `"owned"` uses the signer's shared PermissionedResolver (the ENS app's address), deployed once and reused; its roles cover every name on it. `null` registers without a resolver. | | `records` | `Omit` | | Records for every name, written when its resolver is created (or right after registering). | | `primaryName` | `boolean` | | Set the (single) name as the signer's primary name; adds its `eth` address record. | | `paymentToken` | `PaymentToken` | `"usdc"` | Token to pay with. | | `subregistry` | `string` | | ENSv2 registry for the names' subnames. | | `referrer` | `Hex` | | Referrer recorded by the registrar: 32 bytes, or an address (left-padded). | | `secret` | `Hex` | | Secret from an earlier `commit` or `register`, to finish that registration. | Also takes the [write options](/docs/reference/sdk/client#write-options). ## Returns [#returns] Resolves to `Write.Result & { readonly secret: Hex }`. Submitted hashes, the plan and the commitment secret. ## 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), [`DURATION_TOO_SHORT`](/docs/reference/errors/DURATION_TOO_SHORT), [`INVALID_RECORD_VALUE`](/docs/reference/errors/INVALID_RECORD_VALUE) | invalid input. | | [`NameStateError`](/docs/reference/errors/name-state-error) | [`NAME_NOT_AVAILABLE`](/docs/reference/errors/NAME_NOT_AVAILABLE) | a name is taken or in its grace period. | | [`CommitmentError`](/docs/reference/errors/commitment-error) | [`COMMITMENT_TOO_NEW`](/docs/reference/errors/COMMITMENT_TOO_NEW), [`COMMITMENT_TOO_OLD`](/docs/reference/errors/COMMITMENT_TOO_OLD), [`COMMITMENT_EXISTS`](/docs/reference/errors/COMMITMENT_EXISTS) | a resumed commitment outside its window. | | [`InsufficientFundsError`](/docs/reference/errors/insufficient-funds-error) | [`INSUFFICIENT_TOKEN_BALANCE`](/docs/reference/errors/INSUFFICIENT_TOKEN_BALANCE) | the signer cannot pay in the payment token. | | [`UnsupportedError`](/docs/reference/errors/unsupported-error) | [`PAYMENT_TOKEN_UNSUPPORTED`](/docs/reference/errors/PAYMENT_TOKEN_UNSUPPORTED), [`UNSUPPORTED_ON_DEPLOYMENT`](/docs/reference/errors/UNSUPPORTED_ON_DEPLOYMENT) | an unaccepted token or without ENSv2. | | [`ConfigError`](/docs/reference/errors/config-error) | [`WALLET_NOT_CONFIGURED`](/docs/reference/errors/WALLET_NOT_CONFIGURED) | no signing account is known. | | [`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="Registering a name" const { secret } = await ens.registration.register({ names: "alice.eth", duration: 31536000n, records: { texts: { url: "https://alice.dev" } } }) ``` ```ts title="Registering a name with a standalone call" import { Actions } from "@ensforge/sdk" await Actions.registration.register(ens, { names: "alice.eth", duration: 31536000n, records: { texts: { url: "https://alice.dev" } } }) ``` ```ts title="Registering a name in an Effect program" import { Actions } from "@ensforge/sdk/effect" yield* Actions.registration.register(ens, { names: "alice.eth", duration: 31536000n, records: { texts: { url: "https://alice.dev" } } }) ``` ## Plan methods [#plan-methods] Each method takes the same options as `registration.register` and sends nothing. See [Preview before sending](/docs/sdk/preview-before-sending). | Method | Description | | --- | --- | | `registration.register.prepare(options)` | Builds the plan without sending anything. | | `registration.register.simulate(options)` | Simulates the plan with `eth_call`, reporting each step. | | `registration.register.estimateGas(options)` | Estimates the gas and ETH the plan needs. | ## Wait for the receipt with `registerSync` [#wait-for-the-receipt-with-registersync] Registers one or more `.eth` names: approve, commit, wait, register, then records and primary name. Resolves once the receipt is in. Use when the next step depends on the change being on-chain. `registration.registerSync` takes the same options plus [`confirmations` and `timeout`](/docs/reference/sdk/client#sync-options). Resolves to `registerSync.ReturnType`. Receipts, the registered names with token IDs and expiries, and the amount paid. ```ts title="Registering a name and waiting" const { receipt } = await ens.registration.registerSync({ names: "alice.eth", duration: 31536000n, records: { texts: { url: "https://alice.dev" } } }) ``` ```ts title="Waiting with a standalone call" import { Actions } from "@ensforge/sdk" await Actions.registration.registerSync(ens, { names: "alice.eth", duration: 31536000n, records: { texts: { url: "https://alice.dev" } } }) ``` ```ts title="Waiting in an Effect program" import { Actions } from "@ensforge/sdk/effect" yield* Actions.registration.registerSync(ens, { names: "alice.eth", duration: 31536000n, records: { texts: { url: "https://alice.dev" } } }) ``` ## See also [#see-also] - [`registration.getPrice`](/docs/reference/sdk/registration/get-price) to quote it first # registration.renew > For the complete documentation index, see [llms.txt](https://ensforge.com/llms.txt). Renews one or more .eth names, ENSv1 or ENSv2, paying in an ERC-20 token. Parameters, return value, errors and examples for registration.renew in @ensforge/sdk. Source: https://ensforge.com/docs/reference/sdk/registration/renew Renews one or more `.eth` names, ENSv1 or ENSv2, paying in an ERC-20 token. Resolves once the transaction is submitted. ## When to use [#when-to-use] Use to extend names, including names in their grace period. Use [`renewSync`](/docs/reference/sdk/registration/renew#wait-for-the-receipt-with-renewsync) to wait for the receipt. ## Details [#details] - ENSv2 names renew through the `ETHRegistrar`, names still on ENSv1 through `ETHRenewerV1` (which also extends wrapped names); each route is one `renewBatch` call. - Token approvals are added for each contract whose allowance is short. - Anyone can renew any name; the payer is the signer. - A name listed twice is renewed once, for `duration`. ## Signature [#signature] ```ts function renew( client: Like, options: renew.Options & Write.Options, ): Promise ``` Call it as `ens.registration.renew(options)` on a client, or `Actions.registration.renew(client, options)`. In React, use [`useRenew`](/docs/reference/react/use-renew). ## Parameters [#parameters] | Option | Type | Default | Description | | --- | --- | --- | --- | | `names` (required) | `string \| readonly string[]` | | One or more `.eth` second-level names. Normalized automatically. | | `duration` (required) | `bigint` | | Renewal length in seconds. | | `paymentToken` | `PaymentToken` | `"usdc"` | Token to pay with. | | `referrer` | `Hex` | | Referrer recorded by the registrar: 32 bytes, or an address (left-padded). | 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), [`DURATION_TOO_SHORT`](/docs/reference/errors/DURATION_TOO_SHORT) | invalid input. | | [`NameStateError`](/docs/reference/errors/name-state-error) | [`NAME_NOT_RENEWABLE`](/docs/reference/errors/NAME_NOT_RENEWABLE) | a name is neither registered nor in its grace period. | | [`InsufficientFundsError`](/docs/reference/errors/insufficient-funds-error) | [`INSUFFICIENT_TOKEN_BALANCE`](/docs/reference/errors/INSUFFICIENT_TOKEN_BALANCE) | the signer cannot pay in the payment token. | | [`UnsupportedError`](/docs/reference/errors/unsupported-error) | [`PAYMENT_TOKEN_UNSUPPORTED`](/docs/reference/errors/PAYMENT_TOKEN_UNSUPPORTED), [`UNSUPPORTED_ON_DEPLOYMENT`](/docs/reference/errors/UNSUPPORTED_ON_DEPLOYMENT) | an unaccepted token or without ENSv2. | | [`ConfigError`](/docs/reference/errors/config-error) | [`WALLET_NOT_CONFIGURED`](/docs/reference/errors/WALLET_NOT_CONFIGURED) | no signing account is known. | | [`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="Renewing names" const { hash } = await ens.registration.renew({ names: ["alice.eth", "bob.eth"], duration: 31536000n }) ``` ```ts title="Renewing names with a standalone call" import { Actions } from "@ensforge/sdk" await Actions.registration.renew(ens, { names: ["alice.eth", "bob.eth"], duration: 31536000n }) ``` ```ts title="Renewing names in an Effect program" import { Actions } from "@ensforge/sdk/effect" yield* Actions.registration.renew(ens, { names: ["alice.eth", "bob.eth"], duration: 31536000n }) ``` ## Plan methods [#plan-methods] Each method takes the same options as `registration.renew` and sends nothing. See [Preview before sending](/docs/sdk/preview-before-sending). | Method | Description | | --- | --- | | `registration.renew.prepare(options)` | Builds the plan without sending anything. | | `registration.renew.simulate(options)` | Simulates the plan with `eth_call`, reporting each step. | | `registration.renew.estimateGas(options)` | Estimates the gas and ETH the plan needs. | ## Wait for the receipt with `renewSync` [#wait-for-the-receipt-with-renewsync] Renews one or more `.eth` names, ENSv1 or ENSv2, paying in an ERC-20 token. Resolves once the receipt is in. Use when the next step depends on the change being on-chain. `registration.renewSync` takes the same options plus [`confirmations` and `timeout`](/docs/reference/sdk/client#sync-options). Resolves to `renewSync.ReturnType`. Receipts, the new expiry of each name and the amount paid. ```ts title="Renewing names and waiting" const { receipt } = await ens.registration.renewSync({ names: ["alice.eth", "bob.eth"], duration: 31536000n }) ``` ```ts title="Waiting with a standalone call" import { Actions } from "@ensforge/sdk" await Actions.registration.renewSync(ens, { names: ["alice.eth", "bob.eth"], duration: 31536000n }) ``` ```ts title="Waiting in an Effect program" import { Actions } from "@ensforge/sdk/effect" yield* Actions.registration.renewSync(ens, { names: ["alice.eth", "bob.eth"], duration: 31536000n }) ``` ## See also [#see-also] - [`registration.getRenewalPrice`](/docs/reference/sdk/registration/get-renewal-price) to quote it # registry.attach > For the complete documentation index, see [llms.txt](https://ensforge.com/llms.txt). Sets or removes the subregistry of an ENSv2 name. Parameters, return value, errors and examples for registry.attach in @ensforge/sdk. Source: https://ensforge.com/docs/reference/sdk/registry/attach Sets or removes the subregistry of an ENSv2 name. Resolves once the transaction is submitted. ## When to use [#when-to-use] Use to move a name's children to another registry, or to detach them. Use [`attachSync`](/docs/reference/sdk/registry/attach#wait-for-the-receipt-with-attachsync) to wait for the receipt. ## Details [#details] - `setSubregistry` on the registry holding the name, then `setParent` on the new registry so its canonical name points back to the name (skip with `setParent: false`). - `registry: null` detaches the current subregistry. ## Signature [#signature] ```ts function attach( client: Like, options: attach.Options & Write.Options, ): Promise ``` Call it as `ens.registry.attach(options)` on a client, or `Actions.registry.attach(client, options)`. ## Parameters [#parameters] | Option | Type | Default | Description | | --- | --- | --- | --- | | `name` (required) | `string` | | ENSv2 name. Normalized automatically. | | `registry` (required) | `string \| null` | | Registry to attach, or `null` to detach. | | `setParent` | `boolean` | `true` | Also call `setParent` on the registry. | 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_NOT_REGISTERED`](/docs/reference/errors/NAME_NOT_REGISTERED), [`NAME_EXPIRED`](/docs/reference/errors/NAME_EXPIRED) | 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) | ENSv1 names. | | [`UnauthorizedError`](/docs/reference/errors/unauthorized-error) | [`MISSING_ROLES`](/docs/reference/errors/MISSING_ROLES) | the account may not change 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="Attaching a registry" const { hash } = await ens.registry.attach({ name: "alice.eth", registry: "0x02cA46F62f6C9F655364bf9Fd4f11Fb8f01C5753" }) ``` ```ts title="Attaching a registry with a standalone call" import { Actions } from "@ensforge/sdk" await Actions.registry.attach(ens, { name: "alice.eth", registry: "0x02cA46F62f6C9F655364bf9Fd4f11Fb8f01C5753" }) ``` ```ts title="Attaching a registry in an Effect program" import { Actions } from "@ensforge/sdk/effect" yield* Actions.registry.attach(ens, { name: "alice.eth", registry: "0x02cA46F62f6C9F655364bf9Fd4f11Fb8f01C5753" }) ``` ## Plan methods [#plan-methods] Each method takes the same options as `registry.attach` and sends nothing. See [Preview before sending](/docs/sdk/preview-before-sending). | Method | Description | | --- | --- | | `registry.attach.prepare(options)` | Builds the plan without sending anything. | | `registry.attach.simulate(options)` | Simulates the plan with `eth_call`, reporting each step. | | `registry.attach.estimateGas(options)` | Estimates the gas and ETH the plan needs. | ## Wait for the receipt with `attachSync` [#wait-for-the-receipt-with-attachsync] Sets or removes the subregistry of an ENSv2 name. Resolves once the receipt is in. Use when the next step depends on the change being on-chain. `registry.attachSync` 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="Attaching a registry and waiting" const { receipt } = await ens.registry.attachSync({ name: "alice.eth", registry: "0x02cA46F62f6C9F655364bf9Fd4f11Fb8f01C5753" }) ``` ```ts title="Waiting with a standalone call" import { Actions } from "@ensforge/sdk" await Actions.registry.attachSync(ens, { name: "alice.eth", registry: "0x02cA46F62f6C9F655364bf9Fd4f11Fb8f01C5753" }) ``` ```ts title="Waiting in an Effect program" import { Actions } from "@ensforge/sdk/effect" yield* Actions.registry.attachSync(ens, { name: "alice.eth", registry: "0x02cA46F62f6C9F655364bf9Fd4f11Fb8f01C5753" }) ``` ## See also [#see-also] - [`registry.get`](/docs/reference/sdk/registry/get) to inspect it # registry.deploy > For the complete documentation index, see [llms.txt](https://ensforge.com/llms.txt). Deploys an ENSv2 UserRegistry, optionally attaching it as a name's subregistry. Options, result, errors and examples for registry.deploy. Source: https://ensforge.com/docs/reference/sdk/registry/deploy Deploys an ENSv2 UserRegistry, optionally attaching it as a name's subregistry. Resolves once the transaction is submitted. ## When to use [#when-to-use] Use to set up the registry for a name's children ahead of time, or with custom roles. Use [`deploySync`](/docs/reference/sdk/registry/deploy#wait-for-the-receipt-with-deploysync) to wait for the receipt. ## Details [#details] - A verifiable proxy of the deployment's UserRegistry, at an address known before sending (`plan.deploys`, returned as `registry`). - `owner` (the signer by default) gets every root role; `emancipated` withholds the roles that would let owners take children back. - `attachTo` makes it that name's subregistry in the same plan. ## Signature [#signature] ```ts function deploy( client: Like, options: deploy.Options & Write.Options, ): Promise ``` Call it as `ens.registry.deploy(options)` on a client, or `Actions.registry.deploy(client, options)`. ## Parameters [#parameters] | Option | Type | Default | Description | | --- | --- | --- | --- | | `owner` | `string` | the signing account | Account that gets the root roles. | | `grants` | `readonly { account: string; roles: readonly Role.Name[] \| bigint }[]` | | Extra root role grants, by role name or bitmap. | | `emancipated` | `boolean` | | Withhold the roles that would let the owners take children back. | | `attachTo` | `string` | | ENSv2 name to attach it to as subregistry. Normalized automatically. | | `salt` | `bigint` | a random salt | CREATE2 salt; together with the account it decides the address. | Also takes the [write options](/docs/reference/sdk/client#write-options). ## Returns [#returns] Resolves to `Write.Result & { readonly registry: Address }`. Submitted hashes, the plan and the new registry's address. ## 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_ROLES`](/docs/reference/errors/INVALID_ROLES) | invalid input. | | [`UnsupportedError`](/docs/reference/errors/unsupported-error) | [`UNSUPPORTED_ON_DEPLOYMENT`](/docs/reference/errors/UNSUPPORTED_ON_DEPLOYMENT), [`UNSUPPORTED_PROTOCOL`](/docs/reference/errors/UNSUPPORTED_PROTOCOL) | without ENSv2, or for an ENSv1 `attachTo`. | | [`UnauthorizedError`](/docs/reference/errors/unauthorized-error) | [`MISSING_ROLES`](/docs/reference/errors/MISSING_ROLES) | the account may not set the name's subregistry. | | [`ConfigError`](/docs/reference/errors/config-error) | [`WALLET_NOT_CONFIGURED`](/docs/reference/errors/WALLET_NOT_CONFIGURED) | no signing account is known. | | [`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="Deploying a subregistry" const { registry } = await ens.registry.deploy({ attachTo: "alice.eth" }) ``` ```ts title="Deploying a subregistry with a standalone call" import { Actions } from "@ensforge/sdk" await Actions.registry.deploy(ens, { attachTo: "alice.eth" }) ``` ```ts title="Deploying a subregistry in an Effect program" import { Actions } from "@ensforge/sdk/effect" yield* Actions.registry.deploy(ens, { attachTo: "alice.eth" }) ``` ## Plan methods [#plan-methods] Each method takes the same options as `registry.deploy` and sends nothing. See [Preview before sending](/docs/sdk/preview-before-sending). | Method | Description | | --- | --- | | `registry.deploy.prepare(options)` | Builds the plan without sending anything. | | `registry.deploy.simulate(options)` | Simulates the plan with `eth_call`, reporting each step. | | `registry.deploy.estimateGas(options)` | Estimates the gas and ETH the plan needs. | ## Wait for the receipt with `deploySync` [#wait-for-the-receipt-with-deploysync] Deploys an ENSv2 UserRegistry, optionally attaching it as a name's subregistry. Resolves once the receipt is in. Use when the next step depends on the change being on-chain. `registry.deploySync` takes the same options plus [`confirmations` and `timeout`](/docs/reference/sdk/client#sync-options). Resolves to `Write.SyncResult & { readonly registry: Address }`. Receipts, hashes, the plan and the new registry's address. ```ts title="Deploying a subregistry and waiting" const { receipt } = await ens.registry.deploySync({ attachTo: "alice.eth" }) ``` ```ts title="Waiting with a standalone call" import { Actions } from "@ensforge/sdk" await Actions.registry.deploySync(ens, { attachTo: "alice.eth" }) ``` ```ts title="Waiting in an Effect program" import { Actions } from "@ensforge/sdk/effect" yield* Actions.registry.deploySync(ens, { attachTo: "alice.eth" }) ``` ## See also [#see-also] - [`registry.get`](/docs/reference/sdk/registry/get) to inspect it # registry.get > For the complete documentation index, see [llms.txt](https://ensforge.com/llms.txt). Reads an ENSv2 registry: its kind, implementation, parent, canonical name, URI, whether it is emancipated, and whether it can be upgraded. Source: https://ensforge.com/docs/reference/sdk/registry/get Reads an ENSv2 registry: its kind, implementation, parent, canonical name, URI, whether it is emancipated, and whether it can be upgraded. ## When to use [#when-to-use] Use to inspect the registry that holds a name's children before creating subnames or upgrading it. ## Details [#details] - `{ name }` reads the name's subregistry (where its children live); `{ registry }` reads any registry by address. - An emancipated registry's owners cannot take children back. - Every upgrade needs the target to accept the current implementation (`canUpgradeFrom`); emancipated registries also need it listed in their upgrade set. - Pass `account` to include whether it holds the `upgrade` role (`blocker: "unauthorized"`). - Returns `null` when the name has no subregistry, unless `strict` is set. ## Signature [#signature] ```ts function get(client: Like, options: get.Options): Promise ``` Call it as `ens.registry.get(options)` on a client, or `Actions.registry.get(client, options)`. `registry.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] With `name`: | Option | Type | Default | Description | | --- | --- | --- | --- | | `name` (required) | `string` | | | | `account` | `string` | | Account whose `upgrade` role is checked for `upgrade.blocker`. | With `registry`: | Option | Type | Default | Description | | --- | --- | --- | --- | | `registry` (required) | `string` | | | | `account` | `string` | | Account whose `upgrade` role is checked for `upgrade.blocker`. | Also takes the [read options](/docs/reference/sdk/client#read-options). ## Returns [#returns] Resolves to `RegistryInfo | null`. The registry, or `null` when the name has no subregistry. | Field | Type | Description | | --- | --- | --- | | `address` | `Address` | | | `kind` | `RegistryKind` | | | `implementation` | `Address \| null` | Current implementation behind the proxy; `null` when the registry is not a proxy. | | `parent` | `{ readonly registry: Address; readonly label: string } \| null` | The registry above it and the label it sits under, as set with `setParent`. | | `canonicalName` | `string \| null` | Name whose children this registry holds, e.g. `nick.eth`; `null` when not reachable. | | `uri` | `string \| null` | | | `renderer` | `Address \| null` | | | `emancipated` | `boolean` | No root role holder can take children back (unregister, repoint, control transfers). | | `upgrade` | `{ /** The deployment's latest implementation for this kind of registry. */ readonly latest: Address \| null; readonly eligible: boolean; readonly blocker: RegistryUpgradeBlocker \| null; }` | | ## 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) | [`REGISTRY_NOT_FOUND`](/docs/reference/errors/REGISTRY_NOT_FOUND) | with `strict` when the name has no subregistry. | | [`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="Inspecting a name's subregistry" const registry = await ens.registry.get({ name: "nick.eth" }) registry?.emancipated // false ``` ```ts title="Reading a registry by address with a standalone call" import { Actions } from "@ensforge/sdk" const registry = await Actions.registry.get(publicClient, { registry: "0x02cA46F62f6C9F655364bf9Fd4f11Fb8f01C5753" }) ``` ```ts title="Checking upgrade eligibility in an Effect program" import { Actions } from "@ensforge/sdk/effect" const registry = yield* Actions.registry.get(ens, { name: "nick.eth", account }) ``` ## Example response [#example-response] Recorded from Ethereum mainnet on 2026-11-18 at block 26443964. Values change as the chain does. ```ts await ens.registry.get({ name: "nick.eth" }) ``` ```json { "address": "0x02cA46F62f6C9F655364bf9Fd4f11Fb8f01C5753", "kind": "user", "implementation": "0xFAA23592ACA10A6d8875b18eA86954e8EB6d8d72", "parent": { "registry": "0xf60aba43E1f7F3DAB1186Ff03B561401C9Df85E2", "label": "nick" }, "canonicalName": "nick.eth", "uri": null, "renderer": "0x6f412Ff4144d525f791777d3384e9A1B170492Fb", "emancipated": false, "upgrade": { "latest": "0x3269b830b61b3186Dc6d2f57Cab118E2FBC3E2df", "eligible": false, "blocker": "not-approved" } } ``` ## See also [#see-also] - [`registry.upgrade`](/docs/reference/sdk/registry/upgrade) to upgrade it # registry > For the complete documentation index, see [llms.txt](https://ensforge.com/llms.txt). List the 5 registry actions of @ensforge/sdk and whether each reads, writes or signs. Covers attach, deploy, get, setUri, upgrade. Source: https://ensforge.com/docs/reference/sdk/registry Call them as `ens.registry.(options)` on a client, or `Actions.registry.(client, options)`. ## Reads [#reads] | Action | Description | | --- | --- | | [`get`](/docs/reference/sdk/registry/get) (batchable) | Reads an ENSv2 registry: its kind, implementation, parent, canonical name, URI, whether it is emancipated, and whether it can be upgraded. | ## Writes [#writes] | Action | Description | | --- | --- | | [`attach`](/docs/reference/sdk/registry/attach) | Sets or removes the subregistry of an ENSv2 name. | | [`deploy`](/docs/reference/sdk/registry/deploy) | Deploys an ENSv2 UserRegistry, optionally attaching it as a name's subregistry. | | [`setUri`](/docs/reference/sdk/registry/set-uri) | Sets the metadata URI of an ENSv2 registry. | | [`upgrade`](/docs/reference/sdk/registry/upgrade) | Upgrades an ENSv2 registry to the deployment's latest implementation. | # registry.setUri > For the complete documentation index, see [llms.txt](https://ensforge.com/llms.txt). Sets the metadata URI of an ENSv2 registry. Parameters, return value, errors and examples for registry.setUri in @ensforge/sdk. Source: https://ensforge.com/docs/reference/sdk/registry/set-uri Sets the metadata URI of an ENSv2 registry. Resolves once the transaction is submitted. ## When to use [#when-to-use] Use to point a registry's token metadata at your own service. Use [`setUriSync`](/docs/reference/sdk/registry/set-uri#wait-for-the-receipt-with-seturisync) to wait for the receipt. ## Details [#details] - Keeps the current URI renderer unless `renderer` is given; `null` removes it. - Needs the `setUri` root role. ## Signature [#signature] ```ts function setUri( client: Like, options: setUri.Options & Write.Options, ): Promise ``` Call it as `ens.registry.setUri(options)` on a client, or `Actions.registry.setUri(client, options)`. ## Parameters [#parameters] With `name` and `uri`: | Option | Type | Default | Description | | --- | --- | --- | --- | | `name` (required) | `string` | | | | `uri` (required) | `string` | | Metadata URI. | | `renderer` | `string \| null` | | URI renderer contract, or `null` for none. | With `registry` and `uri`: | Option | Type | Default | Description | | --- | --- | --- | --- | | `registry` (required) | `string` | | | | `uri` (required) | `string` | | Metadata URI. | | `renderer` | `string \| null` | | URI renderer contract, or `null` for none. | 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) | [`REGISTRY_NOT_FOUND`](/docs/reference/errors/REGISTRY_NOT_FOUND) | the name has no subregistry. | | [`UnauthorizedError`](/docs/reference/errors/unauthorized-error) | [`MISSING_ROLES`](/docs/reference/errors/MISSING_ROLES) | without the `setUri` root role. | | [`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="Setting a registry URI" const { hash } = await ens.registry.setUri({ name: "alice.eth", uri: "https://alice.dev/names/{id}.json" }) ``` ```ts title="Setting a registry URI with a standalone call" import { Actions } from "@ensforge/sdk" await Actions.registry.setUri(ens, { name: "alice.eth", uri: "https://alice.dev/names/{id}.json" }) ``` ```ts title="Setting a registry URI in an Effect program" import { Actions } from "@ensforge/sdk/effect" yield* Actions.registry.setUri(ens, { name: "alice.eth", uri: "https://alice.dev/names/{id}.json" }) ``` ## Plan methods [#plan-methods] Each method takes the same options as `registry.setUri` and sends nothing. See [Preview before sending](/docs/sdk/preview-before-sending). | Method | Description | | --- | --- | | `registry.setUri.prepare(options)` | Builds the plan without sending anything. | | `registry.setUri.simulate(options)` | Simulates the plan with `eth_call`, reporting each step. | | `registry.setUri.estimateGas(options)` | Estimates the gas and ETH the plan needs. | ## Wait for the receipt with `setUriSync` [#wait-for-the-receipt-with-seturisync] Sets the metadata URI of an ENSv2 registry. Resolves once the receipt is in. Use when the next step depends on the change being on-chain. `registry.setUriSync` 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="Setting a registry URI and waiting" const { receipt } = await ens.registry.setUriSync({ name: "alice.eth", uri: "https://alice.dev/names/{id}.json" }) ``` ```ts title="Waiting with a standalone call" import { Actions } from "@ensforge/sdk" await Actions.registry.setUriSync(ens, { name: "alice.eth", uri: "https://alice.dev/names/{id}.json" }) ``` ```ts title="Waiting in an Effect program" import { Actions } from "@ensforge/sdk/effect" yield* Actions.registry.setUriSync(ens, { name: "alice.eth", uri: "https://alice.dev/names/{id}.json" }) ``` ## See also [#see-also] - [`registry.get`](/docs/reference/sdk/registry/get) to read it # registry.upgrade > For the complete documentation index, see [llms.txt](https://ensforge.com/llms.txt). Upgrades an ENSv2 registry to the deployment's latest implementation. Parameters, return value, errors and examples for registry.upgrade in @ensforge/sdk. Source: https://ensforge.com/docs/reference/sdk/registry/upgrade Upgrades an ENSv2 registry to the deployment's latest implementation. Resolves once the transaction is submitted. ## When to use [#when-to-use] Use to move a subregistry to the current UserRegistry implementation. Use [`upgradeSync`](/docs/reference/sdk/registry/upgrade#wait-for-the-receipt-with-upgradesync) to wait for the receipt. ## Details [#details] - Checks before signing what [`registry.get`](/docs/reference/sdk/registry/get) reports: the `upgrade` root role, the target accepting the current implementation (`canUpgradeFrom`), and for emancipated registries the upgrade set. ## Signature [#signature] ```ts function upgrade( client: Like, options: upgrade.Options & Write.Options, ): Promise ``` Call it as `ens.registry.upgrade(options)` on a client, or `Actions.registry.upgrade(client, options)`. ## Parameters [#parameters] With `name`: | Option | Type | Default | Description | | --- | --- | --- | --- | | `name` (required) | `string` | | | | `implementation` | `string` | the deployment's implementation for this kind of registry | Implementation to upgrade to. | With `registry`: | Option | Type | Default | Description | | --- | --- | --- | --- | | `registry` (required) | `string` | | | | `implementation` | `string` | the deployment's implementation for this kind of registry | 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 | | --- | --- | --- | | [`InvalidInputError`](/docs/reference/errors/invalid-input-error) | [`INVALID_NAME`](/docs/reference/errors/INVALID_NAME), [`INVALID_ADDRESS`](/docs/reference/errors/INVALID_ADDRESS), [`INVALID_RECORD_VALUE`](/docs/reference/errors/INVALID_RECORD_VALUE) | invalid input or an up-to-date registry. | | [`NotFoundError`](/docs/reference/errors/not-found-error) | [`REGISTRY_NOT_FOUND`](/docs/reference/errors/REGISTRY_NOT_FOUND) | the name has no subregistry. | | [`UnsupportedError`](/docs/reference/errors/unsupported-error) | [`UPGRADE_NOT_APPROVED`](/docs/reference/errors/UPGRADE_NOT_APPROVED) | the target is not approved. | | [`UnauthorizedError`](/docs/reference/errors/unauthorized-error) | [`MISSING_ROLES`](/docs/reference/errors/MISSING_ROLES) | without the `upgrade` root role. | | [`ConfigError`](/docs/reference/errors/config-error) | [`WALLET_NOT_CONFIGURED`](/docs/reference/errors/WALLET_NOT_CONFIGURED) | no signing account is known. | | [`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="Upgrading a subregistry" const { hash } = await ens.registry.upgrade({ name: "alice.eth" }) ``` ```ts title="Upgrading a subregistry with a standalone call" import { Actions } from "@ensforge/sdk" await Actions.registry.upgrade(ens, { name: "alice.eth" }) ``` ```ts title="Upgrading a subregistry in an Effect program" import { Actions } from "@ensforge/sdk/effect" yield* Actions.registry.upgrade(ens, { name: "alice.eth" }) ``` ## Plan methods [#plan-methods] Each method takes the same options as `registry.upgrade` and sends nothing. See [Preview before sending](/docs/sdk/preview-before-sending). | Method | Description | | --- | --- | | `registry.upgrade.prepare(options)` | Builds the plan without sending anything. | | `registry.upgrade.simulate(options)` | Simulates the plan with `eth_call`, reporting each step. | | `registry.upgrade.estimateGas(options)` | Estimates the gas and ETH the plan needs. | ## Wait for the receipt with `upgradeSync` [#wait-for-the-receipt-with-upgradesync] Upgrades an ENSv2 registry to the deployment's latest implementation. Resolves once the receipt is in. Use when the next step depends on the change being on-chain. `registry.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 a subregistry and waiting" const { receipt } = await ens.registry.upgradeSync({ name: "alice.eth" }) ``` ```ts title="Waiting with a standalone call" import { Actions } from "@ensforge/sdk" await Actions.registry.upgradeSync(ens, { name: "alice.eth" }) ``` ```ts title="Waiting in an Effect program" import { Actions } from "@ensforge/sdk/effect" yield* Actions.registry.upgradeSync(ens, { name: "alice.eth" }) ``` ## See also [#see-also] - [`registry.get`](/docs/reference/sdk/registry/get) to check eligibility # resolver.create > For the complete documentation index, see [llms.txt](https://ensforge.com/llms.txt). Deploys an ENSv2 PermissionedResolver, optionally with records, and points a name at it. Options, result, errors and examples for resolver.create. Source: https://ensforge.com/docs/reference/sdk/resolver/create Deploys an ENSv2 PermissionedResolver, optionally with records, and points a name at it. Resolves once the transaction is submitted. ## When to use [#when-to-use] Use to give an ENSv2 name its own resolver, or to set up a resolver shared by several names. Use [`createSync`](/docs/reference/sdk/resolver/create#wait-for-the-receipt-with-createsync) to wait for the receipt. ## Details [#details] - The resolver is a verifiable proxy from the VerifiableFactory; its address is known before sending (`plan.deploys`) and returned as `resolver`. - `owner` (the signer by default) gets every role; `grants` add more accounts. - With `name`, `records` are written during initialization and the name is pointed at the new resolver in the same plan. - The address depends on the sending account and `salt`: send from the account the plan was prepared for. A `salt` already used by that account fails with [`SALT_TAKEN`](/docs/reference/errors/SALT_TAKEN), whose `context.contract` is the existing resolver; point the name at it with `resolver.set`. ## Signature [#signature] ```ts function create( client: Like, options: create.Options & Write.Options, ): Promise ``` Call it as `ens.resolver.create(options)` on a client, or `Actions.resolver.create(client, options)`. ## Parameters [#parameters] | Option | Type | Default | Description | | --- | --- | --- | --- | | `name` | `string` | | Name to point at the new resolver; required for `records`. Normalized automatically. | | `records` | `Omit` | | Records for `name`, written while the resolver is initialized. | | `owner` | `string` | the signing account | Account that gets every resolver role. | | `grants` | `readonly { account: string; roles: readonly Role.Name[] \| bigint }[]` | | Extra role grants, by role name or bitmap. | | `salt` | `bigint` | a random salt | CREATE2 salt; together with the account it decides the address. | Also takes the [write options](/docs/reference/sdk/client#write-options). ## Returns [#returns] Resolves to `Write.Result & { readonly resolver: Address }`. Submitted transaction hashes, the plan and the new resolver's address. ## 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_ROLES`](/docs/reference/errors/INVALID_ROLES), [`INVALID_RECORD_VALUE`](/docs/reference/errors/INVALID_RECORD_VALUE), [`SALT_TAKEN`](/docs/reference/errors/SALT_TAKEN) | invalid input, or a `salt` whose resolver already exists. | | [`NameStateError`](/docs/reference/errors/name-state-error) | [`NAME_EXPIRED`](/docs/reference/errors/NAME_EXPIRED), [`NAME_RESERVED`](/docs/reference/errors/NAME_RESERVED), [`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. | | [`ConfigError`](/docs/reference/errors/config-error) | [`WALLET_NOT_CONFIGURED`](/docs/reference/errors/WALLET_NOT_CONFIGURED) | no account is known to predict the address. | | [`UnsupportedError`](/docs/reference/errors/unsupported-error) | [`UNSUPPORTED_ON_DEPLOYMENT`](/docs/reference/errors/UNSUPPORTED_ON_DEPLOYMENT), [`RESOLVER_PROFILE_UNSUPPORTED`](/docs/reference/errors/RESOLVER_PROFILE_UNSUPPORTED) | without ENSv2, or for records a PermissionedResolver cannot store. | | [`UnauthorizedError`](/docs/reference/errors/unauthorized-error) | [`NOT_OWNER`](/docs/reference/errors/NOT_OWNER), [`MISSING_ROLES`](/docs/reference/errors/MISSING_ROLES) | the account may not point the name at 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="Creating a resolver with records" const { resolver } = await ens.resolver.create({ name: "alice.eth", records: { texts: { url: "https://alice.dev" } } }) ``` ```ts title="Creating a resolver with records with a standalone call" import { Actions } from "@ensforge/sdk" await Actions.resolver.create(ens, { name: "alice.eth", records: { texts: { url: "https://alice.dev" } } }) ``` ```ts title="Creating a resolver with records in an Effect program" import { Actions } from "@ensforge/sdk/effect" yield* Actions.resolver.create(ens, { name: "alice.eth", records: { texts: { url: "https://alice.dev" } } }) ``` ## Plan methods [#plan-methods] Each method takes the same options as `resolver.create` and sends nothing. See [Preview before sending](/docs/sdk/preview-before-sending). | Method | Description | | --- | --- | | `resolver.create.prepare(options)` | Builds the plan without sending anything. | | `resolver.create.simulate(options)` | Simulates the plan with `eth_call`, reporting each step. | | `resolver.create.estimateGas(options)` | Estimates the gas and ETH the plan needs. | ## Wait for the receipt with `createSync` [#wait-for-the-receipt-with-createsync] Deploys an ENSv2 PermissionedResolver, optionally with records, and points a name at it. Resolves once the receipt is in. Use when the next step depends on the change being on-chain. `resolver.createSync` takes the same options plus [`confirmations` and `timeout`](/docs/reference/sdk/client#sync-options). Resolves to `Write.SyncResult & { readonly resolver: Address }`. Receipts, hashes, the plan and the new resolver's address. ```ts title="Creating a resolver with records and waiting" const { receipt } = await ens.resolver.createSync({ name: "alice.eth", records: { texts: { url: "https://alice.dev" } } }) ``` ```ts title="Waiting with a standalone call" import { Actions } from "@ensforge/sdk" await Actions.resolver.createSync(ens, { name: "alice.eth", records: { texts: { url: "https://alice.dev" } } }) ``` ```ts title="Waiting in an Effect program" import { Actions } from "@ensforge/sdk/effect" yield* Actions.resolver.createSync(ens, { name: "alice.eth", records: { texts: { url: "https://alice.dev" } } }) ``` ## See also [#see-also] - [`resolver.get`](/docs/reference/sdk/resolver/get) to inspect it # resolver.getLink > For the complete documentation index, see [llms.txt](https://ensforge.com/llms.txt). Reads which record set an ENS name uses on its PermissionedResolver. Parameters, return value, errors and examples for resolver.getLink in @ensforge/sdk. Source: https://ensforge.com/docs/reference/sdk/resolver/get-link Reads which record set an ENS name uses on its PermissionedResolver. ## When to use [#when-to-use] Use to tell whether names share records: linked names have the same `recordId` on the same resolver. ## Details [#details] - Every name gets its own record ID on its first write; [`resolver.link`](/docs/reference/sdk/resolver/link) points a name at another name's record ID. - Returns `null` when the name has no records on the resolver yet, unless `strict` is set. ## Signature [#signature] ```ts function getLink(client: Like, options: getLink.Options): Promise ``` Call it as `ens.resolver.getLink(options)` on a client, or `Actions.resolver.getLink(client, options)`. `resolver.getLink.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 to read. Normalized automatically. | Also takes the [read options](/docs/reference/sdk/client#read-options). ## Returns [#returns] Resolves to `{ readonly resolver: Address; readonly recordId: bigint } | null`. The resolver and the name's record ID, or `null` when it has no records there. | Field | Type | Description | | --- | --- | --- | | `resolver` | `Address` | | | `recordId` | `bigint` | | ## Errors [#errors] | Error | Codes | When | | --- | --- | --- | | [`InvalidInputError`](/docs/reference/errors/invalid-input-error) | [`INVALID_NAME`](/docs/reference/errors/INVALID_NAME) | the name cannot be normalized. | | [`NotFoundError`](/docs/reference/errors/not-found-error) | [`RESOLVER_NOT_FOUND`](/docs/reference/errors/RESOLVER_NOT_FOUND), [`RECORD_NOT_FOUND`](/docs/reference/errors/RECORD_NOT_FOUND) | without a resolver, or with `strict` and no records. | | [`UnsupportedError`](/docs/reference/errors/unsupported-error) | [`RESOLVER_PROFILE_UNSUPPORTED`](/docs/reference/errors/RESOLVER_PROFILE_UNSUPPORTED) | the resolver is not a PermissionedResolver. | | [`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 whether two names share records" const [a, b] = await Promise.all([ ens.resolver.getLink({ name: "alice.eth" }), ens.resolver.getLink({ name: "alice-main.eth" }), ]) const shared = a !== null && b !== null && a.resolver === b.resolver && a.recordId === b.recordId ``` ```ts title="Reading with a standalone call" import { Actions } from "@ensforge/sdk" const link = await Actions.resolver.getLink(publicClient, { name: "alice.eth" }) ``` ```ts title="Reading in an Effect program" import { Actions } from "@ensforge/sdk/effect" const link = yield* Actions.resolver.getLink(ens, { name: "alice.eth" }) ``` ## Example response [#example-response] Recorded from Ethereum mainnet on 2026-11-18 at block 26443964. Values change as the chain does. ```ts await ens.resolver.getLink({ name: "nick.eth" }) ``` ```json { "resolver": "0xF4f1007EA430848F2fAd60e405A54Fc100fEc341", "recordId": "3n" } ``` ## See also [#see-also] - [`resolver.link`](/docs/reference/sdk/resolver/link) to link names # resolver.get > For the complete documentation index, see [llms.txt](https://ensforge.com/llms.txt). Reads the resolver of an ENS name: its address, what kind of resolver it is, who may write to it and which record profiles it supports. Source: https://ensforge.com/docs/reference/sdk/resolver/get Reads the resolver of an ENS name: its address, what kind of resolver it is, who may write to it and which record profiles it supports. ## When to use [#when-to-use] Use to show where a name's records live, or to check that its resolver can store a record before writing it. ## Details [#details] - The name's own resolver comes from the registry that holds the name (ENSv1 or ENSv2). - Without one, the resolver serving the name is returned with `inherited: true`: a parent's wildcard resolver or an off-chain resolver. For ENSv1 names that ENSv2 serves through the ENSv1 bridge, it is the ENSv1 resolver behind the bridge, as before the ENSv2 launch. - Costs three batched calls: name state, then one round of ERC-165 checks. - Returns `null` when nothing resolves the name, unless `strict` is set. - An inherited resolver belongs to a parent: records cannot be written there for this name. ## Signature [#signature] ```ts function get(client: Like, options: get.Options): Promise ``` Call it as `ens.resolver.get(options)` on a client, or `Actions.resolver.get(client, options)`. `resolver.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 | | --- | --- | --- | --- | | `name` (required) | `string` | | ENS name to read. Normalized automatically. | Also takes the [read options](/docs/reference/sdk/client#read-options). ## Returns [#returns] Resolves to `ResolverInfo | null`. The resolver, or `null` when nothing resolves the name. | Field | Type | Description | | --- | --- | --- | | `address` | `Address` | | | `inherited` | `boolean` | Whether the name has no resolver of its own and is served by another one (a parent's wildcard resolver, or the ENSv1 bridge). Records cannot be written for the name there. | | `serving` | `boolean` | Whether resolving the name reaches this resolver. `false` for a name's own resolver that resolution no longer uses, e.g. an ENSv1 name ENSv2 holds no reservation for after the launch: its records are kept there but do not resolve. | | `kind` | `ResolverKind` | | | `authorization` | `ResolverAuthorization` | | | `profiles` | `ResolverProfiles` | | | `version` | `bigint \| null` | ENSv1 record version of the name (bumped by `clear`); `null` when not versioned. | ## Errors [#errors] | Error | Codes | When | | --- | --- | --- | | [`InvalidInputError`](/docs/reference/errors/invalid-input-error) | [`INVALID_NAME`](/docs/reference/errors/INVALID_NAME) | the name cannot be normalized. | | [`NotFoundError`](/docs/reference/errors/not-found-error) | [`RESOLVER_NOT_FOUND`](/docs/reference/errors/RESOLVER_NOT_FOUND) | with `strict` when nothing resolves the name. | | [`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 resolver before writing" const resolver = await ens.resolver.get({ name: "nick.eth" }) if (resolver?.profiles.data) await ens.record.set({ name: "nick.eth", data: { key: "0x01" } }) ``` ```ts title="Reading with a bare viem client" import { Actions } from "@ensforge/sdk" const resolver = await Actions.resolver.get(publicClient, { name: "vitalik.eth" }) resolver?.kind // "public-resolver" ``` ```ts title="Reading in an Effect program" import { Actions } from "@ensforge/sdk/effect" const resolver = yield* Actions.resolver.get(ens, { name: "nick.eth", strict: true }) ``` ## Example response [#example-response] Recorded from Ethereum mainnet on 2026-11-18 at block 26443964. Values change as the chain does. ```ts await ens.resolver.get({ name: "nick.eth" }) ``` ```json { "address": "0xF4f1007EA430848F2fAd60e405A54Fc100fEc341", "inherited": false, "serving": true, "kind": "permissioned-resolver", "authorization": "roles", "profiles": { "addr": true, "addresses": true, "text": true, "contentHash": true, "abi": true, "pubkey": false, "name": true, "interfaces": true, "data": true, "extended": true }, "version": null } ``` ## See also [#see-also] - [`resolver.set`](/docs/reference/sdk/resolver/set) to change it # resolver > For the complete documentation index, see [llms.txt](https://ensforge.com/llms.txt). List the 7 resolver actions of @ensforge/sdk and whether each reads, writes or signs. Covers create, get, getLink, link, resolve, set, upgrade. Source: https://ensforge.com/docs/reference/sdk/resolver Call them as `ens.resolver.(options)` on a client, or `Actions.resolver.(client, options)`. ## Reads [#reads] | Action | Description | | --- | --- | | [`get`](/docs/reference/sdk/resolver/get) (batchable) | Reads the resolver of an ENS name: its address, what kind of resolver it is, who may write to it and which record profiles it supports. | | [`getLink`](/docs/reference/sdk/resolver/get-link) (batchable) | Reads which record set an ENS name uses on its PermissionedResolver. | | [`resolve`](/docs/reference/sdk/resolver/resolve) (batchable) | Calls the resolver of an ENS name with raw calldata through the Universal Resolver (ENSIP-10). | ## Writes [#writes] | Action | Description | | --- | --- | | [`create`](/docs/reference/sdk/resolver/create) | Deploys an ENSv2 PermissionedResolver, optionally with records, and points a name at it. | | [`link`](/docs/reference/sdk/resolver/link) | Links an ENS name to the records of another name on the same PermissionedResolver. | | [`set`](/docs/reference/sdk/resolver/set) | Points an ENS name at a resolver. | | [`upgrade`](/docs/reference/sdk/resolver/upgrade) | Upgrades the PermissionedResolver of an ENS name to a newer implementation. | # resolver.link > For the complete documentation index, see [llms.txt](https://ensforge.com/llms.txt). Links an ENS name to the records of another name on the same PermissionedResolver. Options, result, errors and examples for resolver.link. Source: https://ensforge.com/docs/reference/sdk/resolver/link Links an ENS name to the records of another name on the same PermissionedResolver. Resolves once the transaction is submitted. ## When to use [#when-to-use] Use to make several names share one set of records, such as aliases of a main name. Use [`linkSync`](/docs/reference/sdk/resolver/link#wait-for-the-receipt-with-linksync) to wait for the receipt. ## Details [#details] - `to` is a name whose records the name will read and write, or a record ID from [`resolver.getLink`](/docs/reference/sdk/resolver/get-link). - Both names must use the same PermissionedResolver, and the target must already have records. - Needs the `link` role on the resolver. ## Signature [#signature] ```ts function link( client: Like, options: link.Options & Write.Options, ): Promise ``` Call it as `ens.resolver.link(options)` on a client, or `Actions.resolver.link(client, options)`. ## Parameters [#parameters] | Option | Type | Default | Description | | --- | --- | --- | --- | | `name` (required) | `string` | | ENS name. Normalized automatically. | | `to` (required) | `string \| { recordId: bigint }` | | Name or record ID to link 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 | | --- | --- | --- | | [`InvalidInputError`](/docs/reference/errors/invalid-input-error) | [`INVALID_NAME`](/docs/reference/errors/INVALID_NAME), [`INVALID_RECORD_VALUE`](/docs/reference/errors/INVALID_RECORD_VALUE) | invalid input or a target without records. | | [`NameStateError`](/docs/reference/errors/name-state-error) | [`NAME_EXPIRED`](/docs/reference/errors/NAME_EXPIRED), [`NAME_RESERVED`](/docs/reference/errors/NAME_RESERVED), [`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. | | [`NotFoundError`](/docs/reference/errors/not-found-error) | [`RESOLVER_NOT_FOUND`](/docs/reference/errors/RESOLVER_NOT_FOUND) | the name has no resolver of its own. | | [`UnsupportedError`](/docs/reference/errors/unsupported-error) | [`RESOLVER_PROFILE_UNSUPPORTED`](/docs/reference/errors/RESOLVER_PROFILE_UNSUPPORTED) | the resolver is not a PermissionedResolver. | | [`UnauthorizedError`](/docs/reference/errors/unauthorized-error) | [`MISSING_ROLES`](/docs/reference/errors/MISSING_ROLES) | without the `link` role. | | [`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="Sharing records with another name" const { hash } = await ens.resolver.link({ name: "alice.eth", to: "alice-main.eth" }) ``` ```ts title="Sharing records with another name with a standalone call" import { Actions } from "@ensforge/sdk" await Actions.resolver.link(ens, { name: "alice.eth", to: "alice-main.eth" }) ``` ```ts title="Sharing records with another name in an Effect program" import { Actions } from "@ensforge/sdk/effect" yield* Actions.resolver.link(ens, { name: "alice.eth", to: "alice-main.eth" }) ``` ## Plan methods [#plan-methods] Each method takes the same options as `resolver.link` and sends nothing. See [Preview before sending](/docs/sdk/preview-before-sending). | Method | Description | | --- | --- | | `resolver.link.prepare(options)` | Builds the plan without sending anything. | | `resolver.link.simulate(options)` | Simulates the plan with `eth_call`, reporting each step. | | `resolver.link.estimateGas(options)` | Estimates the gas and ETH the plan needs. | ## Wait for the receipt with `linkSync` [#wait-for-the-receipt-with-linksync] Links an ENS name to the records of another name on the same PermissionedResolver. Resolves once the receipt is in. Use when the next step depends on the change being on-chain. `resolver.linkSync` 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="Sharing records with another name and waiting" const { receipt } = await ens.resolver.linkSync({ name: "alice.eth", to: "alice-main.eth" }) ``` ```ts title="Waiting with a standalone call" import { Actions } from "@ensforge/sdk" await Actions.resolver.linkSync(ens, { name: "alice.eth", to: "alice-main.eth" }) ``` ```ts title="Waiting in an Effect program" import { Actions } from "@ensforge/sdk/effect" yield* Actions.resolver.linkSync(ens, { name: "alice.eth", to: "alice-main.eth" }) ``` ## See also [#see-also] - [`resolver.getLink`](/docs/reference/sdk/resolver/get-link) to read a name's record ID # resolver.resolve > For the complete documentation index, see [llms.txt](https://ensforge.com/llms.txt). Calls the resolver of an ENS name with raw calldata through the Universal Resolver (ENSIP-10). Options, result, errors and examples for resolver.resolve. Source: https://ensforge.com/docs/reference/sdk/resolver/resolve Calls the resolver of an ENS name with raw calldata through the Universal Resolver (ENSIP-10). ## When to use [#when-to-use] Use to read resolver profiles ensforge has no action for. Use [`record.get`](/docs/reference/sdk/record/get) for the standard records. ## Details [#details] - Finds the resolver like any ENS client: the name's own, a parent's wildcard, or off-chain through CCIP-Read. - `data` is the resolver call, with the name's node as its first argument. - Returns the ABI-encoded result and the resolver the Universal Resolver called: for ENSv1 names ENSv2 serves through the ENSv1 bridge, the bridge itself (`record.get` and `resolver.get` report the ENSv1 resolver behind it). ## Signature [#signature] ```ts function resolve(client: Like, options: resolve.Options): Promise ``` Call it as `ens.resolver.resolve(options)` on a client, or `Actions.resolver.resolve(client, options)`. `resolver.resolve.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 to resolve. Normalized automatically. | | `data` (required) | `Hex` | | Resolver calldata, e.g. `text(node, key)`. | Also takes the [read options](/docs/reference/sdk/client#read-options). ## Returns [#returns] Resolves to `{ readonly data: Hex; readonly resolver: Address }`. The ABI-encoded result and the resolver that answered. | Field | Type | Description | | --- | --- | --- | | `data` | `Hex` | | | `resolver` | `Address` | | ## Errors [#errors] | Error | Codes | When | | --- | --- | --- | | [`InvalidInputError`](/docs/reference/errors/invalid-input-error) | [`INVALID_NAME`](/docs/reference/errors/INVALID_NAME), [`INVALID_RECORD_VALUE`](/docs/reference/errors/INVALID_RECORD_VALUE) | an invalid name or calldata. | | [`NotFoundError`](/docs/reference/errors/not-found-error) | [`RESOLVER_NOT_FOUND`](/docs/reference/errors/RESOLVER_NOT_FOUND) | nothing resolves the name. | | [`UnsupportedError`](/docs/reference/errors/unsupported-error) | [`RESOLVER_PROFILE_UNSUPPORTED`](/docs/reference/errors/RESOLVER_PROFILE_UNSUPPORTED) | the resolver does not answer the call. | | [`GatewayError`](/docs/reference/errors/gateway-error) | [`GATEWAY_REQUEST_FAILED`](/docs/reference/errors/GATEWAY_REQUEST_FAILED), [`GATEWAY_RESPONSE_INVALID`](/docs/reference/errors/GATEWAY_RESPONSE_INVALID), [`OFFCHAIN_LOOKUP_INVALID`](/docs/reference/errors/OFFCHAIN_LOOKUP_INVALID) | an off-chain gateway fails. | | [`DnsError`](/docs/reference/errors/dns-error) | | a DNS name's DNSSEC proof does not verify. | | [`ConfigError`](/docs/reference/errors/config-error) | [`CCIP_READ_DISABLED`](/docs/reference/errors/CCIP_READ_DISABLED) | off-chain names when CCIP-Read is disabled. | 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="Calling a custom profile" import { encodeFunctionData, namehash, parseAbi } from "viem" const abi = parseAbi(["function text(bytes32, string) view returns (string)"]) const data = encodeFunctionData({ abi, functionName: "text", args: [namehash("nick.eth"), "url"] }) const { data: result } = await ens.resolver.resolve({ name: "nick.eth", data }) ``` ```ts title="Resolving with a standalone call" import { Actions } from "@ensforge/sdk" const { resolver } = await Actions.resolver.resolve(publicClient, { name: "nick.eth", data }) ``` ```ts title="Resolving in an Effect program" import { Actions } from "@ensforge/sdk/effect" const result = yield* Actions.resolver.resolve(ens, { name: "nick.eth", data }) ``` ## Example response [#example-response] Recorded from Ethereum mainnet on 2026-11-18 at block 26443964. Values change as the chain does. ```ts await ens.resolver.resolve({ name: "nick.eth", data: "0x3b3b57de05a67c0ee82964c4f7394cdd47fee7f4d9503a23c09c38341779ea012afe6e00" }) ``` ```json { "data": "0x000000000000000000000000b8c2c29ee19d8307cb7255e1cd9cbde883a267d5", "resolver": "0xF4f1007EA430848F2fAd60e405A54Fc100fEc341" } ``` ## See also [#see-also] - [`resolver.get`](/docs/reference/sdk/resolver/get) to inspect the resolver # resolver.set > For the complete documentation index, see [llms.txt](https://ensforge.com/llms.txt). Points an ENS name at a resolver. Parameters, return value, errors and examples for resolver.set in @ensforge/sdk. Errors and examples for resolver.set. Source: https://ensforge.com/docs/reference/sdk/resolver/set Points an ENS name at a resolver. Resolves once the transaction is submitted. ## When to use [#when-to-use] Use to move a name to another resolver, or to remove it with `resolver: null`. Use [`setSync`](/docs/reference/sdk/resolver/set#wait-for-the-receipt-with-setsync) to wait for the receipt. ## Details [#details] - ENSv1 names change it in the ENS registry, or through the NameWrapper when wrapped. - ENSv2 names change it in the registry holding them (`setResolver` on the token). - `"default"` is the ENSv1 public resolver, for ENSv1 names. - Records stay on the old resolver; copy them with `record.set` first. - ENSv2 names have no shared default resolver: create one with [`resolver.create`](/docs/reference/sdk/resolver/create). ## Signature [#signature] ```ts function set(client: Like, options: set.Options & Write.Options): Promise ``` Call it as `ens.resolver.set(options)` on a client, or `Actions.resolver.set(client, options)`. In React, use [`useSetResolver`](/docs/reference/react/use-set-resolver). ## Parameters [#parameters] | Option | Type | Default | Description | | --- | --- | --- | --- | | `name` (required) | `string` | | ENS name. Normalized automatically. | | `resolver` (required) | `Address \| "default" \| null` | | New resolver, `"default"` for the ENSv1 public resolver, or `null` to remove 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. | | [`NameStateError`](/docs/reference/errors/name-state-error) | [`NAME_EXPIRED`](/docs/reference/errors/NAME_EXPIRED), [`NAME_RESERVED`](/docs/reference/errors/NAME_RESERVED), [`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) | `"default"` on ENSv2 names. | | [`UnauthorizedError`](/docs/reference/errors/unauthorized-error) | [`NOT_OWNER`](/docs/reference/errors/NOT_OWNER), [`MISSING_ROLES`](/docs/reference/errors/MISSING_ROLES), [`FUSE_BURNED`](/docs/reference/errors/FUSE_BURNED) | the account may not change 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="Switching to the public resolver" const { hash } = await ens.resolver.set({ name: "alice.eth", resolver: "default" }) ``` ```ts title="Switching to the public resolver with a standalone call" import { Actions } from "@ensforge/sdk" await Actions.resolver.set(ens, { name: "alice.eth", resolver: "default" }) ``` ```ts title="Switching to the public resolver in an Effect program" import { Actions } from "@ensforge/sdk/effect" yield* Actions.resolver.set(ens, { name: "alice.eth", resolver: "default" }) ``` ## Plan methods [#plan-methods] Each method takes the same options as `resolver.set` and sends nothing. See [Preview before sending](/docs/sdk/preview-before-sending). | Method | Description | | --- | --- | | `resolver.set.prepare(options)` | Builds the plan without sending anything. | | `resolver.set.simulate(options)` | Simulates the plan with `eth_call`, reporting each step. | | `resolver.set.estimateGas(options)` | Estimates the gas and ETH the plan needs. | ## Wait for the receipt with `setSync` [#wait-for-the-receipt-with-setsync] Points an ENS name at a resolver. Resolves once the receipt is in. Use when the next step depends on the change being on-chain. `resolver.setSync` 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="Switching to the public resolver and waiting" const { receipt } = await ens.resolver.setSync({ name: "alice.eth", resolver: "default" }) ``` ```ts title="Waiting with a standalone call" import { Actions } from "@ensforge/sdk" await Actions.resolver.setSync(ens, { name: "alice.eth", resolver: "default" }) ``` ```ts title="Waiting in an Effect program" import { Actions } from "@ensforge/sdk/effect" yield* Actions.resolver.setSync(ens, { name: "alice.eth", resolver: "default" }) ``` ## See also [#see-also] - [`resolver.get`](/docs/reference/sdk/resolver/get) to read the current resolver # resolver.upgrade > For the complete documentation index, see [llms.txt](https://ensforge.com/llms.txt). Upgrades the PermissionedResolver of an ENS name to a newer implementation. Parameters, return value, errors and examples for resolver.upgrade in @ensforge/sdk. Source: https://ensforge.com/docs/reference/sdk/resolver/upgrade Upgrades the PermissionedResolver of an ENS name to a newer implementation. Resolves once the transaction is submitted. ## When to use [#when-to-use] Use to move a name's resolver to the deployment's latest PermissionedResolver implementation. Use [`upgradeSync`](/docs/reference/sdk/resolver/upgrade#wait-for-the-receipt-with-upgradesync) to wait for the receipt. ## Details [#details] - Targets the deployment's current implementation unless `implementation` is given. - Checks that the target accepts the current implementation (`canUpgradeFrom`) before sending. - Needs the `upgrade` role on the resolver. ## Signature [#signature] ```ts function upgrade( client: Like, options: upgrade.Options & Write.Options, ): Promise ``` Call it as `ens.resolver.upgrade(options)` on a client, or `Actions.resolver.upgrade(client, options)`. ## Parameters [#parameters] | Option | Type | Default | Description | | --- | --- | --- | --- | | `name` (required) | `string` | | ENS name. Normalized automatically. | | `implementation` | `string` | the deployment's PermissionedResolver implementation | 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 | | --- | --- | --- | | [`InvalidInputError`](/docs/reference/errors/invalid-input-error) | [`INVALID_NAME`](/docs/reference/errors/INVALID_NAME), [`INVALID_ADDRESS`](/docs/reference/errors/INVALID_ADDRESS), [`INVALID_RECORD_VALUE`](/docs/reference/errors/INVALID_RECORD_VALUE) | invalid input or an up-to-date resolver. | | [`NotFoundError`](/docs/reference/errors/not-found-error) | [`RESOLVER_NOT_FOUND`](/docs/reference/errors/RESOLVER_NOT_FOUND) | the name has no resolver of its own. | | [`UnsupportedError`](/docs/reference/errors/unsupported-error) | [`RESOLVER_PROFILE_UNSUPPORTED`](/docs/reference/errors/RESOLVER_PROFILE_UNSUPPORTED), [`UPGRADE_NOT_APPROVED`](/docs/reference/errors/UPGRADE_NOT_APPROVED) | the resolver or target cannot be upgraded. | | [`UnauthorizedError`](/docs/reference/errors/unauthorized-error) | [`MISSING_ROLES`](/docs/reference/errors/MISSING_ROLES) | without the `upgrade` role. | | [`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="Upgrading a resolver" const { hash } = await ens.resolver.upgrade({ name: "alice.eth" }) ``` ```ts title="Upgrading a resolver with a standalone call" import { Actions } from "@ensforge/sdk" await Actions.resolver.upgrade(ens, { name: "alice.eth" }) ``` ```ts title="Upgrading a resolver in an Effect program" import { Actions } from "@ensforge/sdk/effect" yield* Actions.resolver.upgrade(ens, { name: "alice.eth" }) ``` ## Plan methods [#plan-methods] Each method takes the same options as `resolver.upgrade` and sends nothing. See [Preview before sending](/docs/sdk/preview-before-sending). | Method | Description | | --- | --- | | `resolver.upgrade.prepare(options)` | Builds the plan without sending anything. | | `resolver.upgrade.simulate(options)` | Simulates the plan with `eth_call`, reporting each step. | | `resolver.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 PermissionedResolver of an ENS name to a newer implementation. Resolves once the receipt is in. Use when the next step depends on the change being on-chain. `resolver.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 a resolver and waiting" const { receipt } = await ens.resolver.upgradeSync({ name: "alice.eth" }) ``` ```ts title="Waiting with a standalone call" import { Actions } from "@ensforge/sdk" await Actions.resolver.upgradeSync(ens, { name: "alice.eth" }) ``` ```ts title="Waiting in an Effect program" import { Actions } from "@ensforge/sdk/effect" yield* Actions.resolver.upgradeSync(ens, { name: "alice.eth" }) ``` ## See also [#see-also] - [`resolver.get`](/docs/reference/sdk/resolver/get) to inspect the resolver # role.get > For the complete documentation index, see [llms.txt](https://ensforge.com/llms.txt). Reads the ENSv2 roles an account holds on a name, or at the root of a registry or resolver. Options, result, errors and examples for role.get. Source: https://ensforge.com/docs/reference/sdk/role/get Reads the ENSv2 roles an account holds on a name, or at the root of a registry or resolver. ## When to use [#when-to-use] Use to inspect EnhancedAccessControl roles directly; [`permission.get`](/docs/reference/sdk/permission/get) answers the higher-level question of what the account may do. ## Details [#details] - `target: "registry"` reads roles on the name in the registry holding it (or the root with `root: true`); `"resolver"` reads root roles on the name's PermissionedResolver. - Root roles apply to every name, so `roles` includes them; `rootRoles` shows them alone. - `contract` reads another registry or resolver than the name's. ## Signature [#signature] ```ts function get(client: Like, options: get.Options): Promise ``` Call it as `ens.role.get(options)` on a client, or `Actions.role.get(client, options)`. `role.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 | | --- | --- | --- | --- | | `account` (required) | `string` | | Account whose roles to read. | | `target` (required) | `"registry" \| "resolver"` | | Registry or PermissionedResolver roles. | | `name` | `string` | | ENS name whose registry or resolver to use. Normalized automatically. | | `contract` | `string` | | Registry or resolver address, instead of the name's. | | `root` | `boolean` | | Read root roles instead of the name's. | Also takes the [read options](/docs/reference/sdk/client#read-options). ## Returns [#returns] Resolves to `get.ReturnType`. The roles held, as a bitmap and as role names. | Field | Type | Description | | --- | --- | --- | | `contract` | `Address` | | | `resource` | `bigint` | EAC resource read; `0n` is the root. | | `roles` | `bigint` | | | `rootRoles` | `bigint` | | | `names` | `readonly Role.Name[]` | | | `admin` | `readonly Role.Name[]` | Admin roles: the account may grant and revoke these roles. | ## 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_RECORD_VALUE`](/docs/reference/errors/INVALID_RECORD_VALUE) | invalid input or targets. | | [`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) | [`UNSUPPORTED_PROTOCOL`](/docs/reference/errors/UNSUPPORTED_PROTOCOL) | ENSv1 names. | | [`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 an account's roles on a name" const { names } = await ens.role.get({ name: "alice.eth", account, target: "registry" }) ``` ```ts title="Root roles on a resolver with a standalone call" import { Actions } from "@ensforge/sdk" const roles = await Actions.role.get(publicClient, { name: "alice.eth", account, target: "resolver", root: true }) ``` ```ts title="Reading in an Effect program" import { Actions } from "@ensforge/sdk/effect" const roles = yield* Actions.role.get(ens, { name: "alice.eth", account, target: "registry" }) ``` ## See also [#see-also] - [`role.grant`](/docs/reference/sdk/role/grant) to grant roles # role.grant > For the complete documentation index, see [llms.txt](https://ensforge.com/llms.txt). Grants ENSv2 roles to an account on a name, or at the root of a registry or resolver. Options, result, errors and examples for role.grant. Source: https://ensforge.com/docs/reference/sdk/role/grant Grants ENSv2 roles to an account on a name, or at the root of a registry or resolver. Resolves once the transaction is submitted. ## When to use [#when-to-use] Use to delegate specific powers, such as renewing or changing the resolver, without transferring a name. Use [`grantSync`](/docs/reference/sdk/role/grant#wait-for-the-receipt-with-grantsync) to wait for the receipt. ## Details [#details] - Name roles go to the name's resource in the registry holding it; root roles apply to every name in that registry or on that resolver. - Granting needs the matching admin roles. - Some roles regenerate the name's token ID; the plan carries a `TOKEN_ID_REGENERATED` warning. - `renew` granted on a name lets its holder renew it only in registries that predate contracts-v2 #505; the deployment's current UserRegistry checks it at the root (`root: true`). ## Signature [#signature] ```ts function grant( client: Like, options: grant.Options & Write.Options, ): Promise ``` Call it as `ens.role.grant(options)` on a client, or `Actions.role.grant(client, options)`. ## Parameters [#parameters] | Option | Type | Default | Description | | --- | --- | --- | --- | | `grantee` (required) | `string` | | Account that gets the roles. | | `roles` (required) | `readonly Role.Name[] \| bigint` | | Roles by name, e.g. `["setResolver"]`, or as a bitmap. | | `target` (required) | `"registry" \| "resolver"` | | Registry or PermissionedResolver roles (resolvers: root only). | | `name` | `string` | | ENS name whose registry or resolver to use. Normalized automatically. | | `contract` | `string` | | Registry or resolver address, instead of the name's. | | `root` | `boolean` | | Root roles, applying to every name, instead of the name's. | 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_ROLES`](/docs/reference/errors/INVALID_ROLES), [`INVALID_RECORD_VALUE`](/docs/reference/errors/INVALID_RECORD_VALUE) | invalid input or targets. | | [`UnsupportedError`](/docs/reference/errors/unsupported-error) | [`UNSUPPORTED_PROTOCOL`](/docs/reference/errors/UNSUPPORTED_PROTOCOL) | ENSv1 names. | | [`UnauthorizedError`](/docs/reference/errors/unauthorized-error) | [`CANNOT_GRANT_ROLES`](/docs/reference/errors/CANNOT_GRANT_ROLES) | without the admin roles. | | [`InvalidInputError`](/docs/reference/errors/invalid-input-error) | [`INVALID_ROLES`](/docs/reference/errors/INVALID_ROLES) | a role already has the maximum of 15 holders. | | [`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="Granting a role" const { hash } = await ens.role.grant({ name: "alice.eth", grantee: "0xB0b0000000000000000000000000000000000000", roles: ["renew"], target: "registry" }) ``` ```ts title="Granting a role with a standalone call" import { Actions } from "@ensforge/sdk" await Actions.role.grant(ens, { name: "alice.eth", grantee: "0xB0b0000000000000000000000000000000000000", roles: ["renew"], target: "registry" }) ``` ```ts title="Granting a role in an Effect program" import { Actions } from "@ensforge/sdk/effect" yield* Actions.role.grant(ens, { name: "alice.eth", grantee: "0xB0b0000000000000000000000000000000000000", roles: ["renew"], target: "registry" }) ``` ## Plan methods [#plan-methods] Each method takes the same options as `role.grant` and sends nothing. See [Preview before sending](/docs/sdk/preview-before-sending). | Method | Description | | --- | --- | | `role.grant.prepare(options)` | Builds the plan without sending anything. | | `role.grant.simulate(options)` | Simulates the plan with `eth_call`, reporting each step. | | `role.grant.estimateGas(options)` | Estimates the gas and ETH the plan needs. | ## Wait for the receipt with `grantSync` [#wait-for-the-receipt-with-grantsync] Grants ENSv2 roles to an account on a name, or at the root of a registry or resolver. Resolves once the receipt is in. Use when the next step depends on the change being on-chain. `role.grantSync` 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 a role and waiting" const { receipt } = await ens.role.grantSync({ name: "alice.eth", grantee: "0xB0b0000000000000000000000000000000000000", roles: ["renew"], target: "registry" }) ``` ```ts title="Waiting with a standalone call" import { Actions } from "@ensforge/sdk" await Actions.role.grantSync(ens, { name: "alice.eth", grantee: "0xB0b0000000000000000000000000000000000000", roles: ["renew"], target: "registry" }) ``` ```ts title="Waiting in an Effect program" import { Actions } from "@ensforge/sdk/effect" yield* Actions.role.grantSync(ens, { name: "alice.eth", grantee: "0xB0b0000000000000000000000000000000000000", roles: ["renew"], target: "registry" }) ``` ## See also [#see-also] - [`role.get`](/docs/reference/sdk/role/get) to read roles # role > For the complete documentation index, see [llms.txt](https://ensforge.com/llms.txt). List the 3 role actions of @ensforge/sdk and whether each reads, writes or signs. Covers get, grant, revoke. Covers get, grant, revoke. Source: https://ensforge.com/docs/reference/sdk/role Call them as `ens.role.(options)` on a client, or `Actions.role.(client, options)`. ## Reads [#reads] | Action | Description | | --- | --- | | [`get`](/docs/reference/sdk/role/get) (batchable) | Reads the ENSv2 roles an account holds on a name, or at the root of a registry or resolver. | ## Writes [#writes] | Action | Description | | --- | --- | | [`grant`](/docs/reference/sdk/role/grant) | Grants ENSv2 roles to an account on a name, or at the root of a registry or resolver. | | [`revoke`](/docs/reference/sdk/role/revoke) | Revokes ENSv2 roles from an account on a name, or at the root of a registry or resolver. | # role.revoke > For the complete documentation index, see [llms.txt](https://ensforge.com/llms.txt). Revokes ENSv2 roles from an account on a name, or at the root of a registry or resolver. Options, result, errors and examples for role.revoke. Source: https://ensforge.com/docs/reference/sdk/role/revoke Revokes ENSv2 roles from an account on a name, or at the root of a registry or resolver. Resolves once the transaction is submitted. ## When to use [#when-to-use] Use to take back powers granted with [`role.grant`](/docs/reference/sdk/role/grant). Use [`revokeSync`](/docs/reference/sdk/role/revoke#wait-for-the-receipt-with-revokesync) to wait for the receipt. ## Details [#details] - Revoking needs the matching admin roles. - Some roles regenerate the name's token ID; the plan carries a `TOKEN_ID_REGENERATED` warning. ## Signature [#signature] ```ts function revoke( client: Like, options: revoke.Options & Write.Options, ): Promise ``` Call it as `ens.role.revoke(options)` on a client, or `Actions.role.revoke(client, options)`. ## Parameters [#parameters] | Option | Type | Default | Description | | --- | --- | --- | --- | | `holder` (required) | `string` | | Account that loses the roles. | | `roles` (required) | `readonly Role.Name[] \| bigint` | | Roles by name, e.g. `["setResolver"]`, or as a bitmap. | | `target` (required) | `"registry" \| "resolver"` | | Registry or PermissionedResolver roles (resolvers: root only). | | `name` | `string` | | ENS name whose registry or resolver to use. Normalized automatically. | | `contract` | `string` | | Registry or resolver address, instead of the name's. | | `root` | `boolean` | | Root roles, applying to every name, instead of the name's. | 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_ROLES`](/docs/reference/errors/INVALID_ROLES), [`INVALID_RECORD_VALUE`](/docs/reference/errors/INVALID_RECORD_VALUE) | invalid input or targets. | | [`UnsupportedError`](/docs/reference/errors/unsupported-error) | [`UNSUPPORTED_PROTOCOL`](/docs/reference/errors/UNSUPPORTED_PROTOCOL) | ENSv1 names. | | [`UnauthorizedError`](/docs/reference/errors/unauthorized-error) | [`CANNOT_GRANT_ROLES`](/docs/reference/errors/CANNOT_GRANT_ROLES) | without the admin roles. | | [`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="Revoking a role" const { hash } = await ens.role.revoke({ name: "alice.eth", holder: "0xB0b0000000000000000000000000000000000000", roles: ["renew"], target: "registry" }) ``` ```ts title="Revoking a role with a standalone call" import { Actions } from "@ensforge/sdk" await Actions.role.revoke(ens, { name: "alice.eth", holder: "0xB0b0000000000000000000000000000000000000", roles: ["renew"], target: "registry" }) ``` ```ts title="Revoking a role in an Effect program" import { Actions } from "@ensforge/sdk/effect" yield* Actions.role.revoke(ens, { name: "alice.eth", holder: "0xB0b0000000000000000000000000000000000000", roles: ["renew"], target: "registry" }) ``` ## Plan methods [#plan-methods] Each method takes the same options as `role.revoke` and sends nothing. See [Preview before sending](/docs/sdk/preview-before-sending). | Method | Description | | --- | --- | | `role.revoke.prepare(options)` | Builds the plan without sending anything. | | `role.revoke.simulate(options)` | Simulates the plan with `eth_call`, reporting each step. | | `role.revoke.estimateGas(options)` | Estimates the gas and ETH the plan needs. | ## Wait for the receipt with `revokeSync` [#wait-for-the-receipt-with-revokesync] Revokes ENSv2 roles from an account on a name, or at the root of a registry or resolver. Resolves once the receipt is in. Use when the next step depends on the change being on-chain. `role.revokeSync` 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 a role and waiting" const { receipt } = await ens.role.revokeSync({ name: "alice.eth", holder: "0xB0b0000000000000000000000000000000000000", roles: ["renew"], target: "registry" }) ``` ```ts title="Waiting with a standalone call" import { Actions } from "@ensforge/sdk" await Actions.role.revokeSync(ens, { name: "alice.eth", holder: "0xB0b0000000000000000000000000000000000000", roles: ["renew"], target: "registry" }) ``` ```ts title="Waiting in an Effect program" import { Actions } from "@ensforge/sdk/effect" yield* Actions.role.revokeSync(ens, { name: "alice.eth", holder: "0xB0b0000000000000000000000000000000000000", roles: ["renew"], target: "registry" }) ``` ## See also [#see-also] - [`role.get`](/docs/reference/sdk/role/get) to read roles # subname.create > For the complete documentation index, see [llms.txt](https://ensforge.com/llms.txt). Creates a subname, routed by its parent: an ENSv2 subregistry, the ENSv1 registry or the NameWrapper. Options, result, errors and examples for subname.create. Source: https://ensforge.com/docs/reference/sdk/subname/create Creates a subname, routed by its parent: an ENSv2 subregistry, the ENSv1 registry or the NameWrapper. Resolves once the transaction is submitted. ## When to use [#when-to-use] Use to give out names under one you own, such as `pay.alice.eth`. Use [`createSync`](/docs/reference/sdk/subname/create#wait-for-the-receipt-with-createsync) to wait for the receipt. ## Details [#details] - ENSv2 parents: the child is registered in the parent's subregistry. A parent without one gets a UserRegistry deployed and attached in the same plan (`plan.deploys`). - ENSv2 children never expire by default and their owner gets the roles the `.eth` registrar grants (resolver, subregistry, transfers); `roles` and `expiry` override them. - ENSv1 parents use `setSubnodeRecord`; wrapped parents take `fuses` and an `expiry`. - By default the child gets its own PermissionedResolver with `records` written at creation; `resolver: "parent"` shares the parent's resolver, `null` creates it without one. - `upsert` updates an existing child's resolver and records instead of failing. - A subregistry deployed here is not emancipated unless `emancipate` is set: its owners can remove and repoint children. - Under a wrapped parent, `parentCannotControl` and `canExtendExpiry` need `cannotUnwrap` burned on the parent ([`INVALID_RECORD_VALUE`](/docs/reference/errors/INVALID_RECORD_VALUE)), and an emancipated child cannot be updated until it expires ([`FUSE_BURNED`](/docs/reference/errors/FUSE_BURNED)). ## Signature [#signature] ```ts function create( client: Like, options: create.Options & Write.Options, ): Promise ``` Call it as `ens.subname.create(options)` on a client, or `Actions.subname.create(client, options)`. In React, use [`useCreateSubname`](/docs/reference/react/use-create-subname). ## Parameters [#parameters] | Option | Type | Default | Description | | --- | --- | --- | --- | | `name` (required) | `string` | | Full name of the child, e.g. `pay.alice.eth`. Normalized automatically. | | `owner` | `string` | the signing account | Owner of the child. | | `resolver` | `string \| "parent" \| null` | | Resolver of the child. By default it gets its own PermissionedResolver; `"parent"` uses the parent's resolver and `null` none. | | `records` | `Omit` | | Records of the child. | | `expiry` | `bigint` | never for ENSv2 children; for wrapped children, the maximum when `parentCannotControl` is burned, else none | Expiry as a Unix timestamp. | | `fuses` | `readonly Fuse.Name[]` | | NameWrapper fuses to burn on the child (wrapped ENSv1 parents). | | `roles` | `readonly Role.Name[] \| bigint` | | ENSv2 roles for the child's owner, by name or bitmap. | | `emancipate` | `boolean` | | Emancipate the parent's subregistry if this plan deploys it. | | `upsert` | `boolean` | | Update the child's resolver and records if it already exists. | 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_ROLES`](/docs/reference/errors/INVALID_ROLES), [`INVALID_RECORD_VALUE`](/docs/reference/errors/INVALID_RECORD_VALUE) | invalid input. | | [`NameStateError`](/docs/reference/errors/name-state-error) | [`NAME_NOT_AVAILABLE`](/docs/reference/errors/NAME_NOT_AVAILABLE), [`NAME_NOT_REGISTERED`](/docs/reference/errors/NAME_NOT_REGISTERED), [`NAME_EXPIRED`](/docs/reference/errors/NAME_EXPIRED) | the child exists or the parent is not registered. | | [`NameStateError`](/docs/reference/errors/name-state-error) | [`NAME_RESERVED`](/docs/reference/errors/NAME_RESERVED), [`NAME_UNREACHABLE`](/docs/reference/errors/NAME_UNREACHABLE) | the parent is reserved or ENSv2 resolution no longer reaches it. | | [`UnsupportedError`](/docs/reference/errors/unsupported-error) | [`UNSUPPORTED_PROTOCOL`](/docs/reference/errors/UNSUPPORTED_PROTOCOL) | `roles` on ENSv1 or `fuses` on unwrapped parents. | | [`UnauthorizedError`](/docs/reference/errors/unauthorized-error) | [`MISSING_ROLES`](/docs/reference/errors/MISSING_ROLES), [`NOT_OWNER`](/docs/reference/errors/NOT_OWNER), [`FUSE_BURNED`](/docs/reference/errors/FUSE_BURNED) | the account may not create children. | | [`ConfigError`](/docs/reference/errors/config-error) | [`WALLET_NOT_CONFIGURED`](/docs/reference/errors/WALLET_NOT_CONFIGURED) | no signing account is known. | | [`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="Creating a subname" const { hash } = await ens.subname.create({ name: "pay.alice.eth", records: { texts: { url: "https://pay.alice.dev" } } }) ``` ```ts title="Creating a subname with a standalone call" import { Actions } from "@ensforge/sdk" await Actions.subname.create(ens, { name: "pay.alice.eth", records: { texts: { url: "https://pay.alice.dev" } } }) ``` ```ts title="Creating a subname in an Effect program" import { Actions } from "@ensforge/sdk/effect" yield* Actions.subname.create(ens, { name: "pay.alice.eth", records: { texts: { url: "https://pay.alice.dev" } } }) ``` ## Plan methods [#plan-methods] Each method takes the same options as `subname.create` and sends nothing. See [Preview before sending](/docs/sdk/preview-before-sending). | Method | Description | | --- | --- | | `subname.create.prepare(options)` | Builds the plan without sending anything. | | `subname.create.simulate(options)` | Simulates the plan with `eth_call`, reporting each step. | | `subname.create.estimateGas(options)` | Estimates the gas and ETH the plan needs. | ## Wait for the receipt with `createSync` [#wait-for-the-receipt-with-createsync] Creates a subname, routed by its parent: an ENSv2 subregistry, the ENSv1 registry or the NameWrapper. Resolves once the receipt is in. Use when the next step depends on the change being on-chain. `subname.createSync` 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="Creating a subname and waiting" const { receipt } = await ens.subname.createSync({ name: "pay.alice.eth", records: { texts: { url: "https://pay.alice.dev" } } }) ``` ```ts title="Waiting with a standalone call" import { Actions } from "@ensforge/sdk" await Actions.subname.createSync(ens, { name: "pay.alice.eth", records: { texts: { url: "https://pay.alice.dev" } } }) ``` ```ts title="Waiting in an Effect program" import { Actions } from "@ensforge/sdk/effect" yield* Actions.subname.createSync(ens, { name: "pay.alice.eth", records: { texts: { url: "https://pay.alice.dev" } } }) ``` ## See also [#see-also] - [`subname.remove`](/docs/reference/sdk/subname/remove) to remove it # subname > For the complete documentation index, see [llms.txt](https://ensforge.com/llms.txt). List the 3 subname actions of @ensforge/sdk and whether each reads, writes or signs. Covers create, remove, update. Covers create, remove, update. Source: https://ensforge.com/docs/reference/sdk/subname Call them as `ens.subname.(options)` on a client, or `Actions.subname.(client, options)`. ## Writes [#writes] | Action | Description | | --- | --- | | [`create`](/docs/reference/sdk/subname/create) | Creates a subname, routed by its parent: an ENSv2 subregistry, the ENSv1 registry or the NameWrapper. | | [`remove`](/docs/reference/sdk/subname/remove) | Removes a subname. | | [`update`](/docs/reference/sdk/subname/update) | Changes a subname from its parent: owner, resolver or expiry, in one plan. | # subname.remove > For the complete documentation index, see [llms.txt](https://ensforge.com/llms.txt). Removes a subname. Parameters, return value, errors and examples for subname.remove in @ensforge/sdk. Options, result, errors and examples for subname.remove. Source: https://ensforge.com/docs/reference/sdk/subname/remove Removes a subname. Resolves once the transaction is submitted. ## When to use [#when-to-use] Use to take back a name you gave out, or to drop your own subname. Use [`removeSync`](/docs/reference/sdk/subname/remove#wait-for-the-receipt-with-removesync) to wait for the receipt. ## Details [#details] - ENSv2: `unregister` in the parent's subregistry, which also clears the child's resolver and subregistry so nothing carries over to a later owner. - ENSv1: owner and resolver are set to zero, from the parent when the signer owns it or is its operator, otherwise as the child's owner. Under an unwrapped parent the registry clears a wrapped child, which unwraps it. - Emancipated children (ENSv1 `parentCannotControl`, or an emancipated ENSv2 subregistry) cannot be removed by their parent. ## Signature [#signature] ```ts function remove( client: Like, options: remove.Options & Write.Options, ): Promise ``` Call it as `ens.subname.remove(options)` on a client, or `Actions.subname.remove(client, options)`. ## Parameters [#parameters] | Option | Type | Default | Description | | --- | --- | --- | --- | | `name` (required) | `string` | | Full name of the child. Normalized automatically. | 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 input. | | [`NameStateError`](/docs/reference/errors/name-state-error) | [`NAME_NOT_REGISTERED`](/docs/reference/errors/NAME_NOT_REGISTERED), [`NAME_EXPIRED`](/docs/reference/errors/NAME_EXPIRED) | the child or parent does not exist. | | [`NameStateError`](/docs/reference/errors/name-state-error) | [`NAME_RESERVED`](/docs/reference/errors/NAME_RESERVED), [`NAME_UNREACHABLE`](/docs/reference/errors/NAME_UNREACHABLE) | the parent is reserved or ENSv2 resolution no longer reaches it. | | [`UnauthorizedError`](/docs/reference/errors/unauthorized-error) | [`MISSING_ROLES`](/docs/reference/errors/MISSING_ROLES), [`NOT_OWNER`](/docs/reference/errors/NOT_OWNER), [`FUSE_BURNED`](/docs/reference/errors/FUSE_BURNED) | the account may not remove it. | | [`ConfigError`](/docs/reference/errors/config-error) | [`WALLET_NOT_CONFIGURED`](/docs/reference/errors/WALLET_NOT_CONFIGURED) | no signing account is known. | | [`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="Removing a subname" const { hash } = await ens.subname.remove({ name: "pay.alice.eth" }) ``` ```ts title="Removing a subname with a standalone call" import { Actions } from "@ensforge/sdk" await Actions.subname.remove(ens, { name: "pay.alice.eth" }) ``` ```ts title="Removing a subname in an Effect program" import { Actions } from "@ensforge/sdk/effect" yield* Actions.subname.remove(ens, { name: "pay.alice.eth" }) ``` ## Plan methods [#plan-methods] Each method takes the same options as `subname.remove` and sends nothing. See [Preview before sending](/docs/sdk/preview-before-sending). | Method | Description | | --- | --- | | `subname.remove.prepare(options)` | Builds the plan without sending anything. | | `subname.remove.simulate(options)` | Simulates the plan with `eth_call`, reporting each step. | | `subname.remove.estimateGas(options)` | Estimates the gas and ETH the plan needs. | ## Wait for the receipt with `removeSync` [#wait-for-the-receipt-with-removesync] Removes a subname. Resolves once the receipt is in. Use when the next step depends on the change being on-chain. `subname.removeSync` 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="Removing a subname and waiting" const { receipt } = await ens.subname.removeSync({ name: "pay.alice.eth" }) ``` ```ts title="Waiting with a standalone call" import { Actions } from "@ensforge/sdk" await Actions.subname.removeSync(ens, { name: "pay.alice.eth" }) ``` ```ts title="Waiting in an Effect program" import { Actions } from "@ensforge/sdk/effect" yield* Actions.subname.removeSync(ens, { name: "pay.alice.eth" }) ``` ## See also [#see-also] - [`subname.create`](/docs/reference/sdk/subname/create) to create it again # subname.update > For the complete documentation index, see [llms.txt](https://ensforge.com/llms.txt). Changes a subname from its parent: owner, resolver or expiry, in one plan. Parameters, return value, errors and examples for subname.update in @ensforge/sdk. Source: https://ensforge.com/docs/reference/sdk/subname/update Changes a subname from its parent: owner, resolver or expiry, in one plan. Resolves once the transaction is submitted. ## When to use [#when-to-use] Use to repoint or extend names you gave out without asking their owners. Use [`updateSync`](/docs/reference/sdk/subname/update#wait-for-the-receipt-with-updatesync) to wait for the receipt. ## Details [#details] - ENSv2: `setResolver` and `renew` in the parent's subregistry. The owner moves with [`name.transfer`](/docs/reference/sdk/name/transfer), or by removing and recreating the child. On the deployment's current UserRegistry, extending the expiry needs the `renew` role at the subregistry's root; older registries also accept it on the child. - ENSv1: one `setSubnodeRecord` keeps what is not changed; wrapped children extend their expiry with `extendExpiry`. Unwrapped ENSv1 subnames have no expiry. Under an unwrapped parent the registry rewrites a wrapped child, which unwraps it. - An expired wrapped child the parent still controls keeps its owner, and the parent extends it. An emancipated child loses its owner when it expires: recreate it with [`subname.create`](/docs/reference/sdk/subname/create). ## Signature [#signature] ```ts function update( client: Like, options: update.Options & Write.Options, ): Promise ``` Call it as `ens.subname.update(options)` on a client, or `Actions.subname.update(client, options)`. ## Parameters [#parameters] | Option | Type | Default | Description | | --- | --- | --- | --- | | `name` (required) | `string` | | Full name of the child. Normalized automatically. | | `owner` | `string` | | New owner (ENSv1 only). | | `resolver` | `string \| null` | | New resolver, or `null` to remove it. | | `expiry` | `bigint` | | New expiry as a Unix timestamp; it can only grow. | 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_RECORD_VALUE`](/docs/reference/errors/INVALID_RECORD_VALUE), [`INVALID_EXPIRY`](/docs/reference/errors/INVALID_EXPIRY) | invalid input. | | [`NameStateError`](/docs/reference/errors/name-state-error) | [`NAME_NOT_REGISTERED`](/docs/reference/errors/NAME_NOT_REGISTERED), [`NAME_EXPIRED`](/docs/reference/errors/NAME_EXPIRED) | the child or parent does not exist, or an emancipated child expired. | | [`NameStateError`](/docs/reference/errors/name-state-error) | [`NAME_RESERVED`](/docs/reference/errors/NAME_RESERVED), [`NAME_UNREACHABLE`](/docs/reference/errors/NAME_UNREACHABLE) | the parent is reserved or ENSv2 resolution no longer reaches it. | | [`UnsupportedError`](/docs/reference/errors/unsupported-error) | [`UNSUPPORTED_PROTOCOL`](/docs/reference/errors/UNSUPPORTED_PROTOCOL) | an ENSv2 owner change or an unwrapped ENSv1 expiry. | | [`UnauthorizedError`](/docs/reference/errors/unauthorized-error) | [`MISSING_ROLES`](/docs/reference/errors/MISSING_ROLES), [`NOT_OWNER`](/docs/reference/errors/NOT_OWNER), [`FUSE_BURNED`](/docs/reference/errors/FUSE_BURNED) | the account may not change 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="Repointing a subname" const { hash } = await ens.subname.update({ name: "pay.alice.eth", resolver: "0x231b0Ee14048e9dCcD1d247744d114a4EB5E8E63" }) ``` ```ts title="Repointing a subname with a standalone call" import { Actions } from "@ensforge/sdk" await Actions.subname.update(ens, { name: "pay.alice.eth", resolver: "0x231b0Ee14048e9dCcD1d247744d114a4EB5E8E63" }) ``` ```ts title="Repointing a subname in an Effect program" import { Actions } from "@ensforge/sdk/effect" yield* Actions.subname.update(ens, { name: "pay.alice.eth", resolver: "0x231b0Ee14048e9dCcD1d247744d114a4EB5E8E63" }) ``` ## Plan methods [#plan-methods] Each method takes the same options as `subname.update` and sends nothing. See [Preview before sending](/docs/sdk/preview-before-sending). | Method | Description | | --- | --- | | `subname.update.prepare(options)` | Builds the plan without sending anything. | | `subname.update.simulate(options)` | Simulates the plan with `eth_call`, reporting each step. | | `subname.update.estimateGas(options)` | Estimates the gas and ETH the plan needs. | ## Wait for the receipt with `updateSync` [#wait-for-the-receipt-with-updatesync] Changes a subname from its parent: owner, resolver or expiry, in one plan. Resolves once the receipt is in. Use when the next step depends on the change being on-chain. `subname.updateSync` 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="Repointing a subname and waiting" const { receipt } = await ens.subname.updateSync({ name: "pay.alice.eth", resolver: "0x231b0Ee14048e9dCcD1d247744d114a4EB5E8E63" }) ``` ```ts title="Waiting with a standalone call" import { Actions } from "@ensforge/sdk" await Actions.subname.updateSync(ens, { name: "pay.alice.eth", resolver: "0x231b0Ee14048e9dCcD1d247744d114a4EB5E8E63" }) ``` ```ts title="Waiting in an Effect program" import { Actions } from "@ensforge/sdk/effect" yield* Actions.subname.updateSync(ens, { name: "pay.alice.eth", resolver: "0x231b0Ee14048e9dCcD1d247744d114a4EB5E8E63" }) ``` ## See also [#see-also] - [`name.get`](/docs/reference/sdk/name/get) to read the child # Utilities > For the complete documentation index, see [llms.txt](https://ensforge.com/llms.txt). Look up the name, coin type, content hash, duration, fuse, role and error helpers that @ensforge/sdk exports besides its actions. Source: https://ensforge.com/docs/reference/sdk/utilities Helpers exported from `@ensforge/sdk` (and the same from `@ensforge/sdk/effect`). ## Name [#name] ### `Name.dnsDecode` [#namednsdecode] Name from its DNS wire-format encoding, as returned by ENSv2 registries and the Universal Resolver. The labels are returned as stored, without normalizing them. ```ts function dnsDecode(data: Hex): string ``` ```ts title="Decoding a canonical name" import { Name } from "@ensforge/sdk" Name.dnsDecode(Name.dnsEncode("nick.eth")) // "nick.eth" ``` Errors: - `InvalidInputError` ([`INVALID_NAME`](/docs/reference/errors/INVALID_NAME)) when the bytes are not a DNS-encoded name, or a label contains a dot. ### `Name.dnsEncode` [#namednsencode] DNS wire-format encoding of a name, as the Universal Resolver and ENSv2 registries expect. ```ts function dnsEncode(name: string): Hex ``` ```ts title="Encoding a name for a resolver call" import { Name } from "@ensforge/sdk" const dnsName = Name.dnsEncode("alice.eth") ``` Errors: - `InvalidInputError` ([`INVALID_NAME`](/docs/reference/errors/INVALID_NAME)) when the name cannot be normalized. ### `Name.fromLabelhash` [#namefromlabelhash] Encoded label for a labelhash whose plain label is unknown: `[af2c…]`. ```ts function fromLabelhash(hash: Hex): string ``` ```ts title="Showing an unknown label" import { Name } from "@ensforge/sdk" const label = Name.fromLabelhash(Name.labelhash("alice")) ``` ### `Name.getParent` [#namegetparent] Parent of a name, or `null` for top-level names and the root. ```ts function getParent(name: string): string | null ``` ```ts title="Finding the parent" import { Name } from "@ensforge/sdk" Name.getParent("sub.alice.eth") // "alice.eth" Name.getParent("eth") // null ``` Errors: - `InvalidInputError` ([`INVALID_NAME`](/docs/reference/errors/INVALID_NAME)) when the name cannot be normalized. ### `Name.isValid` [#nameisvalid] Whether `name` normalizes without error. It may still differ from its normalized form. ```ts function isValid(name: string): boolean ``` ```ts title="Validating user input" import { Name } from "@ensforge/sdk" Name.isValid("alice.eth") // true Name.isValid("bad name") // false ``` ### `Name.labelhash` [#namelabelhash] Keccak-256 hash of one label, normalizing it first. Encoded labels return their hash. ```ts function labelhash(label: string): Hex ``` ```ts title="Hashing a label" import { Name } from "@ensforge/sdk" const hash = Name.labelhash("alice") ``` Errors: - `InvalidInputError` ([`INVALID_NAME`](/docs/reference/errors/INVALID_NAME)) when the label is empty, contains a dot or cannot be normalized. ### `Name.namehash` [#namenamehash] ENS node (EIP-137 namehash) of a name, normalizing it first. ```ts function namehash(name: string): Hex ``` ```ts title="Computing a node" import { Name } from "@ensforge/sdk" const node = Name.namehash("alice.eth") ``` Errors: - `InvalidInputError` ([`INVALID_NAME`](/docs/reference/errors/INVALID_NAME)) when the name cannot be normalized. ### `Name.normalize` [#namenormalize] Normalizes an ENS name (ENSIP-15). ```ts function normalize(name: string): string ``` - `""` is the root name and is returned as-is. - Uses viem's ENSIP-15 normalizer (ENSIP-15 rejects alternative full stops such as `。`). - Encoded labels such as `[af2c…]` (64 hex digits) are kept, so names from indexers round-trip. ```ts title="Normalizing user input" import { Name } from "@ensforge/sdk" Name.normalize("Nick.ETH") // "nick.eth" ``` Errors: - `InvalidInputError` ([`INVALID_NAME`](/docs/reference/errors/INVALID_NAME)) when a label cannot be normalized. ### `Name.parse` [#nameparse] Splits a name into its labels, TLD and parent after normalizing it. ```ts function parse(name: string): Parsed ``` ```ts title="Parsing a subname" import { Name } from "@ensforge/sdk" Name.parse("pay.nick.eth") // { labels: ["pay", "nick", "eth"], label: "pay", tld: "eth", parent: "nick.eth", is2ld: false, isSubname: true } ``` Errors: - `InvalidInputError` ([`INVALID_NAME`](/docs/reference/errors/INVALID_NAME)) when the name cannot be normalized. ### `Name.toTokenId` [#nametotokenid] ENSv1 `.eth` registrar token ID of a second-level name: the labelhash of its first label as a number. ENSv2 token IDs change over time; read them with `name.getTokenId`. ```ts function toTokenId(name: string): bigint ``` ```ts title="Finding an ENSv1 token ID" import { Name } from "@ensforge/sdk" const tokenId = Name.toTokenId("alice.eth") ``` Errors: - `InvalidInputError` ([`INVALID_NAME`](/docs/reference/errors/INVALID_NAME)) when the name cannot be normalized. ### `Name.Parsed` [#nameparsed] Parts of a name. ```ts type Parsed ``` | Field | Type | Description | | --- | --- | --- | | `labels` | `readonly string[]` | Normalized labels, leftmost first. | | `label` | `string` | Leftmost label, e.g. `nick` for `nick.eth`. Empty for the root name. | | `tld` | `string` | Top-level domain, e.g. `eth`. Empty for the root name. | | `parent` | `string \| null` | Parent name, or `null` for top-level names and the root. | | `is2ld` | `boolean` | Whether the name is a second-level name such as `nick.eth`. | | `isSubname` | `boolean` | Whether the name has two or more levels below its TLD, such as `pay.nick.eth`. | ## CoinType [#cointype] ### `CoinType.decodeAddress` [#cointypedecodeaddress] Decodes the bytes of an ENS address record into a display address, or `null` when empty (or the zero address, for EVM coins). ```ts function decodeAddress(coinType: bigint, data: Hex): string | null ``` ```ts title="Decoding an address record" import { CoinType } from "@ensforge/sdk" const shown = CoinType.decodeAddress(CoinType.from("eth"), data) ``` Errors: - `InvalidInputError` ([`INVALID_COIN_TYPE`](/docs/reference/errors/INVALID_COIN_TYPE)) when no codec exists for the coin. - `InvalidInputError` ([`INVALID_ADDRESS`](/docs/reference/errors/INVALID_ADDRESS)) when the bytes are not an address of the coin. ### `CoinType.encodeAddress` [#cointypeencodeaddress] Encodes an address as the bytes stored in an ENS address record. ```ts function encodeAddress(coinType: bigint, address: string): Hex ``` EVM addresses are stored as 20 raw bytes for any EVM coin type, including chains the codec library does not list. Other coins use `@ensdomains/address-encoder`. ```ts title="Encoding an address record" import { CoinType } from "@ensforge/sdk" const bytes = CoinType.encodeAddress(CoinType.from("eth"), address) ``` Errors: - `InvalidInputError` ([`INVALID_ADDRESS`](/docs/reference/errors/INVALID_ADDRESS)) when the address is invalid for the coin. ### `CoinType.from` [#cointypefrom] Resolves any coin input to its numeric coin type. ```ts function from(input: Input): bigint ``` ```ts title="Coin types" import { CoinType } from "@ensforge/sdk" CoinType.from("btc") // 0n CoinType.from({ chainId: 8453 }) // 2147492101n (Base) ``` Errors: - `InvalidInputError` ([`INVALID_COIN_TYPE`](/docs/reference/errors/INVALID_COIN_TYPE)) for unknown symbols or negative values. ### `CoinType.fromChainId` [#cointypefromchainid] ENSIP-11 coin type of an EVM chain. Ethereum mainnet is `60`. ```ts function fromChainId(chainId: number): bigint ``` ```ts title="Coin type of a chain" import { CoinType } from "@ensforge/sdk" CoinType.fromChainId(8453) // 2147492101n (Base) ``` Errors: - `InvalidInputError` ([`INVALID_COIN_TYPE`](/docs/reference/errors/INVALID_COIN_TYPE)) when `chainId` is not a valid chain ID. ### `CoinType.isEvm` [#cointypeisevm] Whether a coin type is an EVM chain (Ethereum mainnet or ENSIP-11). ```ts function isEvm(coinType: bigint): boolean ``` ```ts title="Telling EVM coins apart" import { CoinType } from "@ensforge/sdk" CoinType.isEvm(CoinType.from("eth")) // true CoinType.isEvm(CoinType.from("btc")) // false ``` ### `CoinType.toChainId` [#cointypetochainid] EVM chain ID of a coin type, or `null` for non-EVM coins. ```ts function toChainId(coinType: bigint): number | null ``` ```ts title="Recovering a chain ID" import { CoinType } from "@ensforge/sdk" CoinType.toChainId(2147492101n) // 8453 ``` ### `CoinType.toSymbol` [#cointypetosymbol] Symbol of a coin type, such as `btc`, or `null` when unknown. ```ts function toSymbol(coinType: bigint): string | null ``` ```ts title="Naming a coin type" import { CoinType } from "@ensforge/sdk" CoinType.toSymbol(0n) // "btc" ``` ### `CoinType.Input` [#cointypeinput] What identifies a coin: a symbol (`"btc"`), an EVM chain (`{ chainId: 8453 }`) or a numeric coin type. ```ts type Input = string | bigint | { readonly chainId: number }; ``` ## ContentHash [#contenthash] ### `ContentHash.decode` [#contenthashdecode] Decodes the bytes of an ENS `contenthash` record, or returns `null` when empty. ```ts function decode(data: Hex): Decoded | null ``` ```ts title="Decoding a content hash" import { ContentHash } from "@ensforge/sdk" const decoded = ContentHash.decode(data) decoded?.uri // "ipfs://…" ``` Errors: - `InvalidInputError` ([`INVALID_CONTENT_HASH`](/docs/reference/errors/INVALID_CONTENT_HASH)) when the bytes are malformed or use an unsupported codec. ### `ContentHash.encode` [#contenthashencode] Encodes a content URI as the bytes stored in an ENS `contenthash` record (ENSIP-7). ```ts function encode(uri: string): Hex ``` ```ts title="Encoding an IPFS link" import { ContentHash } from "@ensforge/sdk" ContentHash.encode("ipfs://bafybeigdyrzt5sfp7udm7hu76uh7y26nf3efuylqabf3oclgtqy55fbzdi") ``` Errors: - `InvalidInputError` ([`INVALID_CONTENT_HASH`](/docs/reference/errors/INVALID_CONTENT_HASH)) for unsupported schemes or values. ### `ContentHash.toGatewayUrl` [#contenthashtogatewayurl] HTTP URL for a content URI through a gateway: `ipfs://` and `ipns://` through `gateways.ipfs`, `ar://` through `gateways.arweave` and `bzz://` through `gateways.swarm`. Unset gateways are the public defaults (`https://ipfs.io`, `https://arweave.net`, `https://api.gateway.ethswarm.org`). URIs without a gateway (`onion://`, `sia://`, anything else) are returned as-is. ```ts function toGatewayUrl(uri: string, gateways?: Gateways | undefined): string ``` ```ts title="Using the client's gateways" import { ContentHash } from "@ensforge/sdk" const contentHash = await ens.record.getContentHash({ name: "vitalik.eth" }) const url = contentHash && ContentHash.toGatewayUrl(contentHash.uri, ens.config.gateways) ``` ### `ContentHash.Decoded` [#contenthashdecoded] A decoded content hash. ```ts type Decoded ``` | Field | Type | Description | | --- | --- | --- | | `protocol` | `Protocol` | | | `value` | `string` | The identifier without scheme, e.g. a CID. | | `uri` | `string` | `protocol://value`. | ### `ContentHash.Protocol` [#contenthashprotocol] URI scheme of a supported content hash, e.g. `ipfs` in `ipfs://bafy…`. ```ts type Protocol = keyof typeof schemes; ``` ## Duration [#duration] ### `Duration.days` [#durationdays] `n` days in seconds. ```ts function days(n: number | bigint): bigint ``` ```ts title="Extending by a month" import { Duration } from "@ensforge/sdk" await ens.registration.renew({ names: "alice.eth", duration: Duration.days(30) }) ``` Errors: - `InvalidInputError` ([`INVALID_DURATION`](/docs/reference/errors/INVALID_DURATION)) for negative or fractional values. ### `Duration.years` [#durationyears] `n` 365-day years in seconds, as ENS registrars count them. ```ts function years(n: number | bigint): bigint ``` ```ts title="A one-year registration" import { Duration } from "@ensforge/sdk" await ens.registration.register({ names: "alice.eth", duration: Duration.years(1) }) ``` Errors: - `InvalidInputError` ([`INVALID_DURATION`](/docs/reference/errors/INVALID_DURATION)) for negative or fractional values. ## Fuse [#fuse] ### `Fuse.decode` [#fusedecode] Every fuse in `mask`, by name. ```ts function decode(mask: number): Decoded ``` ```ts title="Reading a fuse mask" import { Fuse } from "@ensforge/sdk" const { cannotUnwrap, cannotTransfer } = Fuse.decode(Fuse.from(["cannotUnwrap"])) ``` ### `Fuse.from` [#fusefrom] Fuse mask with every fuse in `names` burned. ```ts function from(names: readonly Name[]): number ``` ```ts title="Building a fuse mask" import { Fuse } from "@ensforge/sdk" const mask = Fuse.from(["cannotUnwrap", "cannotSetResolver"]) ``` Errors: - `InvalidInputError` ([`INVALID_RECORD_VALUE`](/docs/reference/errors/INVALID_RECORD_VALUE)) for unknown fuse names. ### `Fuse.has` [#fusehas] Whether `name` is burned in `mask`. ```ts function has(mask: number, name: Name): boolean ``` ```ts title="Checking one fuse" import { Fuse } from "@ensforge/sdk" const locked = Fuse.has(Fuse.from(["cannotUnwrap"]), "cannotUnwrap") ``` ### `Fuse.Decoded` [#fusedecoded] Every fuse with whether it is burned. ```ts type Decoded = { readonly [name in Name]: boolean }; ``` ### `Fuse.Name` [#fusename] An ENSv1 NameWrapper fuse name. ```ts type Name = keyof typeof fuses; ``` ## Role [#role] ### `Role.admin` [#roleadmin] Admin role that grants and revokes `name`, e.g. `setResolver` → `setResolverAdmin`. ```ts function admin(name: name): `${name}Admin` ``` ```ts title="Granting a role with its admin" import { Role } from "@ensforge/sdk" const bitmap = Role.from(["setText", Role.admin("setText")]) ``` ### `Role.from` [#rolefrom] Bitmap with every role in `names` set. ```ts function from(names: readonly Name[]): bigint ``` ```ts title="Building a bitmap" import { Role } from "@ensforge/sdk" Role.from(["setText", "setAddr"]) ``` Errors: - `InvalidInputError` ([`INVALID_ROLES`](/docs/reference/errors/INVALID_ROLES)) for unknown role names. ### `Role.has` [#rolehas] Whether `bitmap` has every role in `names`. ```ts function has(bitmap: bigint, names: Name | readonly Name[]): boolean ``` ```ts title="Checking roles" import { Role } from "@ensforge/sdk" const bitmap = Role.from(["setText", "setAddr"]) Role.has(bitmap, "setText") // true Role.has(bitmap, ["setText", "setAddr"]) // true ``` Errors: - `InvalidInputError` ([`INVALID_ROLES`](/docs/reference/errors/INVALID_ROLES)) for unknown role names. ### `Role.registry` [#roleregistry] Registry role bits from contracts-v2 v1.0.1 (`canTransfer` is `1n << 28n`). ```ts const registry: typeof Roles.registry ``` ```ts title="Reading a registry role" import { Role } from "@ensforge/sdk" const canRenew = Role.registry.renew ``` ### `Role.resolver` [#roleresolver] PermissionedResolver role bits from contracts-v2 v1.0.1. ```ts const resolver: typeof Roles.resolver ``` ```ts title="Reading a resolver role" import { Role } from "@ensforge/sdk" const canSetText = Role.resolver.setText ``` ### `Role.toNames` [#roletonames] Names of the roles set in `bitmap` for a registry or resolver. ```ts function toNames(bitmap: bigint, target: Target): readonly Name[] ``` ```ts title="Listing roles" import { Role } from "@ensforge/sdk" Role.toNames(Role.from(["setText"]), "resolver") // ["setText"] ``` ### `Role.Name` [#rolename] A registry or resolver role name. ```ts type Name = keyof typeof registry | keyof typeof resolver; ``` ### `Role.Target` [#roletarget] Which contract a role bitmap belongs to. Registry and resolver roles share bit positions. ```ts type Target = "registry" | "resolver"; ``` ## Errors [#errors] ### `Errors.describe` [#errorsdescribe] Turns any thrown value into a title, message and suggested action that are safe to show users. ```ts function describe(value: unknown, options: DescribeOptions = {}): Description ``` Use in UI error handlers instead of showing `error.message`, which is written for developers. - Accepts any value; non-ensforge errors go through `Errors.fromCause` first. - Packages that extend ensforge, such as `@ensforge/hca`, add copy for their own codes; a code without copy gets the generic [`UNEXPECTED`](/docs/reference/errors/UNEXPECTED) copy. - Override copy per code with `messages`, for example to translate. ```ts title="Showing an error toast" import { Errors } from "@ensforge/sdk" try { await ens.record.set({ name: "alice.eth", texts: { url: "https://alice.dev" } }) } catch (error) { const { title, message, action } = Errors.describe(error) toast({ title, description: action === undefined ? message : `${message} ${action}` }) } ``` ```ts title="Translating one code" import { Errors } from "@ensforge/sdk" Errors.describe(error, { messages: { NAME_NOT_AVAILABLE: (e) => ({ title: "Nombre no disponible", message: `${e.context.name} ya está registrado.` }) }, }) ``` ### `Errors.fromCause` [#errorsfromcause] Translates any thrown value into an ensforge error and adds `context`. ```ts function fromCause(cause: unknown, context?: EnsforgeError.Context): EnsforgeError ``` Use when calling viem directly next to ensforge actions, to get the same error classes, codes and `Errors.describe` messages. Every ensforge action already does this. - ensforge errors are returned as-is, with `context` merged in. - viem errors are matched along their `cause` chain; contract reverts are decoded against every ENS contract error, unwrapping `ResolverError` and the mainnet `ResolutionError`. - Anything else becomes `InternalError` ([`UNEXPECTED`](/docs/reference/errors/UNEXPECTED)) with the original as `cause`. ```ts title="Translating a viem error" import { Errors } from "@ensforge/sdk" try { await walletClient.writeContract(request) } catch (cause) { const error = Errors.fromCause(cause, { operation: "custom.write" }) toast(Errors.describe(error).title) } ``` ### `Errors.hasCode` [#errorshascode] Returns a type guard that matches ensforge errors with one of `codes`. ```ts function hasCode(...codes: codes) ``` ```ts title="Branching on a code" import { Errors } from "@ensforge/sdk" if (Errors.hasCode("NAME_NOT_AVAILABLE", "NAME_RESERVED")(error)) suggestAlternatives() ``` ### `Errors.is` [#errorsis] Whether `value` is an ensforge error. Uses a brand instead of `instanceof`, so it also works when two copies of `@ensforge/sdk` are installed. ```ts function is(value: unknown): value is AnyError ``` ### `Errors.setConfig` [#errorssetconfig] Changes global error settings, e.g. to point `docsUrl` at a self-hosted docs mirror. ```ts function setConfig(config: Partial): void ``` ### `Errors.AnyError` [#errorsanyerror] Every error class ensforge throws. ```ts type AnyError = | Classes.CommitmentError | Classes.ConfigError | Classes.ContractRevertError | Classes.DnsError | Classes.GatewayError | Classes.IndexerError | Classes.InsufficientFundsError | Classes.InternalError | Classes.InvalidInputError | Classes.MigrationError | Classes.NameStateError | Classes.NetworkError | Classes.NotFoundError | Classes.PlanError | Classes.TransactionError | Classes.UnauthorizedError | Classes.UnsupportedError | Classes.UserRejectedError | Classes.WalletError; ``` ### `Errors.Code` [#errorscode] Every error code. Codes are stable: renaming or removing one is a breaking change. ```ts type Code = AnyError["code"]; ``` ### `Errors.CommonError` [#errorscommonerror] Errors every action can fail with, besides the ones its `@throws` documents: a misconfigured client or a contract missing on the chain (`ConfigError`, [`CONTRACT_NOT_DEPLOYED`](/docs/reference/errors/CONTRACT_NOT_DEPLOYED)), a failing RPC (`NetworkError`), a contract call reverting with an error ensforge does not map (`ContractRevertError`), and anything ensforge could not translate (`InternalError` [`UNEXPECTED`](/docs/reference/errors/UNEXPECTED)). ```ts type CommonError = | Classes.ConfigError | Classes.ContractRevertError | Classes.InternalError | Classes.NetworkError; ``` ### `Errors.Config` [#errorsconfig] Global error settings. ```ts type Config ``` | Option | Type | Default | Description | | --- | --- | --- | --- | | `docsOrigin` (required) | `string` | | Origin of the documentation site used in `docsUrl`. @default "https://ensforge.com" | ### `Errors.DescribeOptions` [#errorsdescribeoptions] Options for `describe`. `error` is the union of error classes whose codes `messages` may override: every sdk error by default; add a package's class to override its codes too, e.g. `DescribeOptions`. ```ts type DescribeOptions ``` | Option | Type | Default | Description | | --- | --- | --- | --- | | `messages` | `{ readonly [code in EnsforgeError["code"]]?: ( EnsforgeError: EnsforgeError extends { readonly code: infer codes } ? code extends codes ? EnsforgeError : never : never, ) => Partial; }` | | Replacement copy by code, e.g. translations. Missing fields fall back to the English copy. | ### `Errors.Description` [#errorsdescription] User-facing description of an error. ```ts type Description = Copy & { /** A code of `Errors.Code`, or of a package that extends ensforge (e.g. `HcaError`). */ readonly code: Code | (string & {}); readonly retryable: boolean; /** `info`: expected outcome; `warning`: temporary, retry later; `error`: needs attention. */ readonly severity: "info" | "warning" | "error"; }; ``` | Field | Type | Description | | --- | --- | --- | | `title` | `string` | | | `message` | `string` | | | `action` (optional) | `string` | | | `code` | `Code \| (string & {})` | A code of `Errors.Code`, or of a package that extends ensforge (e.g. `HcaError`). | | `retryable` | `boolean` | | | `severity` | `"info" \| "warning" \| "error"` | `info`: expected outcome; `warning`: temporary, retry later; `error`: needs attention. | ### `Errors.ErrorOf` [#errorserrorof] The error class that can carry `code`, e.g. `ErrorOf<"MISSING_ROLES">` is `UnauthorizedError`. ```ts type ErrorOf = AnyError extends infer error ? error extends { readonly code: infer codes } ? code extends codes ? error : never : never : never; ``` ### `Errors.WriteError` [#errorswriteerror] Errors every write can fail with, besides the ones its `@throws` documents: `CommonError` and the errors of signing and sending, also on `.prepare`, `.simulate`, `.estimateGas` and the `…Sync` form. ```ts type WriteError = | CommonError | Classes.InsufficientFundsError | Classes.TransactionError | Classes.UnsupportedError | Classes.UserRejectedError | Classes.WalletError; ``` - `WalletError`, or `ConfigError` ([`WALLET_NOT_CONFIGURED`](/docs/reference/errors/WALLET_NOT_CONFIGURED)), when the wallet cannot sign. - `UserRejectedError` when the wallet's user declines. - `InsufficientFundsError` ([`INSUFFICIENT_ETH`](/docs/reference/errors/INSUFFICIENT_ETH)) when the account cannot pay for gas or the ETH the call sends. - `UnsupportedError` ([`WALLET_BATCH_UNSUPPORTED`](/docs/reference/errors/WALLET_BATCH_UNSUPPORTED)) when the wallet cannot send a batch. - `TransactionError` when a transaction reverts, conflicts or is not mined in time. - A `via` route can also fail with its own package's errors (e.g. `HcaError`). # wrapper.getFuses > For the complete documentation index, see [llms.txt](https://ensforge.com/llms.txt). Reads the NameWrapper owner, fuses and expiry of an ENSv1 name. Parameters, return value, errors and examples for wrapper.getFuses in @ensforge/sdk. Source: https://ensforge.com/docs/reference/sdk/wrapper/get-fuses Reads the NameWrapper owner, fuses and expiry of an ENSv1 name. ## When to use [#when-to-use] Use to see which powers an owner or parent has given up on a wrapped name. ## Details [#details] - `null` when the name is not wrapped, or is an expired emancipated name. - Expired names report no fuses. ## Signature [#signature] ```ts function getFuses(client: Like, options: getFuses.Options): Promise ``` Call it as `ens.wrapper.getFuses(options)` on a client, or `Actions.wrapper.getFuses(client, options)`. `wrapper.getFuses.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 `getFuses.ReturnType`. Wrapped owner, fuse mask, burned fuses by name and expiry, or `null`. | Field | Type | Description | | --- | --- | --- | | `owner` | `Address` | | | `fuses` | `number` | | | `burned` | `Fuse.Decoded` | | | `expiry` | `bigint` | | ## Errors [#errors] | Error | Codes | When | | --- | --- | --- | | [`InvalidInputError`](/docs/reference/errors/invalid-input-error) | [`INVALID_NAME`](/docs/reference/errors/INVALID_NAME) | invalid names. | | [`UnsupportedError`](/docs/reference/errors/unsupported-error) | [`UNSUPPORTED_ON_DEPLOYMENT`](/docs/reference/errors/UNSUPPORTED_ON_DEPLOYMENT) | 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="Reading fuses" const wrapped = await ens.wrapper.getFuses({ name: "alice.eth" }) ``` ```ts title="Reading fuses with a standalone call" import { Actions } from "@ensforge/sdk" const wrapped = await Actions.wrapper.getFuses(publicClient, { name: "alice.eth" }) ``` ```ts title="Reading fuses in an Effect program" import { Actions } from "@ensforge/sdk/effect" const wrapped = yield* Actions.wrapper.getFuses(ens, { name: "alice.eth" }) ``` ## Example response [#example-response] Recorded from Ethereum mainnet on 2026-11-18 at block 26443964. Values change as the chain does. ```ts await ens.wrapper.getFuses({ name: "ens.eth" }) ``` ```json null ``` ## See also [#see-also] - [`wrapper.setFuses`](/docs/reference/sdk/wrapper/set-fuses) to burn fuses # wrapper > For the complete documentation index, see [llms.txt](https://ensforge.com/llms.txt). List the 5 wrapper actions of @ensforge/sdk and whether each reads, writes or signs. Covers getFuses, setChildFuses, setFuses, unwrap, wrap. Source: https://ensforge.com/docs/reference/sdk/wrapper Call them as `ens.wrapper.(options)` on a client, or `Actions.wrapper.(client, options)`. ## Reads [#reads] | Action | Description | | --- | --- | | [`getFuses`](/docs/reference/sdk/wrapper/get-fuses) (batchable) | Reads the NameWrapper owner, fuses and expiry of an ENSv1 name. | ## Writes [#writes] | Action | Description | | --- | --- | | [`setChildFuses`](/docs/reference/sdk/wrapper/set-child-fuses) | Burns fuses on, or extends, a wrapped ENSv1 subname as its parent's owner. | | [`setFuses`](/docs/reference/sdk/wrapper/set-fuses) | Burns owner-controlled fuses on a wrapped ENSv1 name. | | [`unwrap`](/docs/reference/sdk/wrapper/unwrap) | Unwraps an ENSv1 name from the NameWrapper. | | [`wrap`](/docs/reference/sdk/wrapper/wrap) | Wraps an ENSv1 name in the NameWrapper. | # wrapper.setChildFuses > For the complete documentation index, see [llms.txt](https://ensforge.com/llms.txt). Burns fuses on, or extends, a wrapped ENSv1 subname as its parent's owner. Options, result, errors and examples for wrapper.setChildFuses. Source: https://ensforge.com/docs/reference/sdk/wrapper/set-child-fuses Burns fuses on, or extends, a wrapped ENSv1 subname as its parent's owner. Resolves once the transaction is submitted. ## When to use [#when-to-use] Use to emancipate a subname (`parentCannotControl`), let it renew itself (`canExtendExpiry`), or extend it. Use [`setChildFusesSync`](/docs/reference/sdk/wrapper/set-child-fuses#wait-for-the-receipt-with-setchildfusessync) to wait for the receipt. ## Details [#details] - Sent by the owner of the wrapped parent. - `expiry` only grows, and is capped at the parent's expiry. Burning `parentCannotControl` without `expiry` uses the parent's expiry, so the emancipated name does not expire at once. - Burning `parentCannotControl` or `canExtendExpiry` needs `cannotUnwrap` on the parent ([`INVALID_RECORD_VALUE`](/docs/reference/errors/INVALID_RECORD_VALUE)). `parentCannotControl` gives up the parent's control of the subname until it expires: the parent can then only extend it ([`FUSE_BURNED`](/docs/reference/errors/FUSE_BURNED) for new fuses). ## Signature [#signature] ```ts function setChildFuses( client: Like, options: setChildFuses.Options & Write.Options, ): Promise ``` Call it as `ens.wrapper.setChildFuses(options)` on a client, or `Actions.wrapper.setChildFuses(client, options)`. ## Parameters [#parameters] | Option | Type | Default | Description | | --- | --- | --- | --- | | `name` (required) | `string` | | Wrapped ENSv1 subname. Normalized automatically. | | `fuses` | `readonly Fuse.Name[]` | | Fuses to burn, including the parent-controlled ones. | | `expiry` | `bigint` | | New expiry as a Unix timestamp. | 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_RECORD_VALUE`](/docs/reference/errors/INVALID_RECORD_VALUE), [`INVALID_EXPIRY`](/docs/reference/errors/INVALID_EXPIRY) | invalid input or fuses. | | [`NameStateError`](/docs/reference/errors/name-state-error) | [`NAME_EXPIRED`](/docs/reference/errors/NAME_EXPIRED), [`NAME_NOT_REGISTERED`](/docs/reference/errors/NAME_NOT_REGISTERED), [`NAME_NOT_WRAPPED`](/docs/reference/errors/NAME_NOT_WRAPPED) | the name is not wrapped. | | [`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; migrated names have no NameWrapper. | | [`UnauthorizedError`](/docs/reference/errors/unauthorized-error) | [`NOT_OWNER`](/docs/reference/errors/NOT_OWNER), [`FUSE_BURNED`](/docs/reference/errors/FUSE_BURNED) | the account may not change 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="Emancipating a subname" const { hash } = await ens.wrapper.setChildFuses({ name: "pay.alice.eth", fuses: ["parentCannotControl"], expiry: 1_900_000_000n }) ``` ```ts title="Emancipating a subname with a standalone call" import { Actions } from "@ensforge/sdk" await Actions.wrapper.setChildFuses(ens, { name: "pay.alice.eth", fuses: ["parentCannotControl"], expiry: 1_900_000_000n }) ``` ```ts title="Emancipating a subname in an Effect program" import { Actions } from "@ensforge/sdk/effect" yield* Actions.wrapper.setChildFuses(ens, { name: "pay.alice.eth", fuses: ["parentCannotControl"], expiry: 1_900_000_000n }) ``` ## Plan methods [#plan-methods] Each method takes the same options as `wrapper.setChildFuses` and sends nothing. See [Preview before sending](/docs/sdk/preview-before-sending). | Method | Description | | --- | --- | | `wrapper.setChildFuses.prepare(options)` | Builds the plan without sending anything. | | `wrapper.setChildFuses.simulate(options)` | Simulates the plan with `eth_call`, reporting each step. | | `wrapper.setChildFuses.estimateGas(options)` | Estimates the gas and ETH the plan needs. | ## Wait for the receipt with `setChildFusesSync` [#wait-for-the-receipt-with-setchildfusessync] Burns fuses on, or extends, a wrapped ENSv1 subname as its parent's owner. Resolves once the receipt is in. Use when the next step depends on the change being on-chain. `wrapper.setChildFusesSync` 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="Emancipating a subname and waiting" const { receipt } = await ens.wrapper.setChildFusesSync({ name: "pay.alice.eth", fuses: ["parentCannotControl"], expiry: 1_900_000_000n }) ``` ```ts title="Waiting with a standalone call" import { Actions } from "@ensforge/sdk" await Actions.wrapper.setChildFusesSync(ens, { name: "pay.alice.eth", fuses: ["parentCannotControl"], expiry: 1_900_000_000n }) ``` ```ts title="Waiting in an Effect program" import { Actions } from "@ensforge/sdk/effect" yield* Actions.wrapper.setChildFusesSync(ens, { name: "pay.alice.eth", fuses: ["parentCannotControl"], expiry: 1_900_000_000n }) ``` ## See also [#see-also] - [`wrapper.getFuses`](/docs/reference/sdk/wrapper/get-fuses) to read them # wrapper.setFuses > For the complete documentation index, see [llms.txt](https://ensforge.com/llms.txt). Burns owner-controlled fuses on a wrapped ENSv1 name. Parameters, return value, errors and examples for wrapper.setFuses in @ensforge/sdk. Source: https://ensforge.com/docs/reference/sdk/wrapper/set-fuses Burns owner-controlled fuses on a wrapped ENSv1 name. Resolves once the transaction is submitted. ## When to use [#when-to-use] Use to give up powers over a name for good, such as unwrapping or changing its resolver. Use [`setFusesSync`](/docs/reference/sdk/wrapper/set-fuses#wait-for-the-receipt-with-setfusessync) to wait for the receipt. ## Details [#details] - Fuses cannot be unburned before the name expires. - Needs `parentCannotControl`, burned by the parent or set on every wrapped `.eth` name; every fuse besides `cannotUnwrap` needs `cannotUnwrap`. - Burning `cannotUnwrap` keeps the name in the NameWrapper until it expires. ## Signature [#signature] ```ts function setFuses( client: Like, options: setFuses.Options & Write.Options, ): Promise ``` Call it as `ens.wrapper.setFuses(options)` on a client, or `Actions.wrapper.setFuses(client, options)`. ## Parameters [#parameters] | Option | Type | Default | Description | | --- | --- | --- | --- | | `name` (required) | `string` | | Wrapped ENSv1 name. Normalized automatically. | | `fuses` (required) | `readonly Fuse.Name[]` | | Owner-controlled fuses to burn. | 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_RECORD_VALUE`](/docs/reference/errors/INVALID_RECORD_VALUE) | invalid input or fuses. | | [`NameStateError`](/docs/reference/errors/name-state-error) | [`NAME_EXPIRED`](/docs/reference/errors/NAME_EXPIRED), [`NAME_NOT_REGISTERED`](/docs/reference/errors/NAME_NOT_REGISTERED), [`NAME_NOT_WRAPPED`](/docs/reference/errors/NAME_NOT_WRAPPED) | the name is not wrapped. | | [`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; migrated names have no NameWrapper. | | [`UnauthorizedError`](/docs/reference/errors/unauthorized-error) | [`NOT_OWNER`](/docs/reference/errors/NOT_OWNER), [`FUSE_BURNED`](/docs/reference/errors/FUSE_BURNED) | the account may not burn them. | | [`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="Burning fuses" const { hash } = await ens.wrapper.setFuses({ name: "alice.eth", fuses: ["cannotUnwrap"] }) ``` ```ts title="Burning fuses with a standalone call" import { Actions } from "@ensforge/sdk" await Actions.wrapper.setFuses(ens, { name: "alice.eth", fuses: ["cannotUnwrap"] }) ``` ```ts title="Burning fuses in an Effect program" import { Actions } from "@ensforge/sdk/effect" yield* Actions.wrapper.setFuses(ens, { name: "alice.eth", fuses: ["cannotUnwrap"] }) ``` ## Plan methods [#plan-methods] Each method takes the same options as `wrapper.setFuses` and sends nothing. See [Preview before sending](/docs/sdk/preview-before-sending). | Method | Description | | --- | --- | | `wrapper.setFuses.prepare(options)` | Builds the plan without sending anything. | | `wrapper.setFuses.simulate(options)` | Simulates the plan with `eth_call`, reporting each step. | | `wrapper.setFuses.estimateGas(options)` | Estimates the gas and ETH the plan needs. | ## Wait for the receipt with `setFusesSync` [#wait-for-the-receipt-with-setfusessync] Burns owner-controlled fuses on a wrapped ENSv1 name. Resolves once the receipt is in. Use when the next step depends on the change being on-chain. `wrapper.setFusesSync` 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="Burning fuses and waiting" const { receipt } = await ens.wrapper.setFusesSync({ name: "alice.eth", fuses: ["cannotUnwrap"] }) ``` ```ts title="Waiting with a standalone call" import { Actions } from "@ensforge/sdk" await Actions.wrapper.setFusesSync(ens, { name: "alice.eth", fuses: ["cannotUnwrap"] }) ``` ```ts title="Waiting in an Effect program" import { Actions } from "@ensforge/sdk/effect" yield* Actions.wrapper.setFusesSync(ens, { name: "alice.eth", fuses: ["cannotUnwrap"] }) ``` ## See also [#see-also] - [`wrapper.getFuses`](/docs/reference/sdk/wrapper/get-fuses) to read them # wrapper.unwrap > For the complete documentation index, see [llms.txt](https://ensforge.com/llms.txt). Unwraps an ENSv1 name from the NameWrapper. Parameters, return value, errors and examples for wrapper.unwrap in @ensforge/sdk. Source: https://ensforge.com/docs/reference/sdk/wrapper/unwrap Unwraps an ENSv1 name from the NameWrapper. Resolves once the transaction is submitted. ## When to use [#when-to-use] Use to return a wrapped name to the ENSv1 registry (and the `.eth` registrar). Use [`unwrapSync`](/docs/reference/sdk/wrapper/unwrap#wait-for-the-receipt-with-unwrapsync) to wait for the receipt. ## Details [#details] - `owner` becomes the registry owner and, for `.eth` names, the registrant. Defaults to the signer. - Blocked once `cannotUnwrap` is burned. ## Signature [#signature] ```ts function unwrap( client: Like, options: unwrap.Options & Write.Options, ): Promise ``` Call it as `ens.wrapper.unwrap(options)` on a client, or `Actions.wrapper.unwrap(client, options)`. ## Parameters [#parameters] | Option | Type | Default | Description | | --- | --- | --- | --- | | `name` (required) | `string` | | ENSv1 name. Normalized automatically. | | `owner` | `string` | | Owner after unwrapping. Defaults to the signer. | 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), [`NAME_NOT_WRAPPED`](/docs/reference/errors/NAME_NOT_WRAPPED) | the name is not wrapped. | | [`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; migrated names have no NameWrapper. | | [`UnauthorizedError`](/docs/reference/errors/unauthorized-error) | [`NOT_OWNER`](/docs/reference/errors/NOT_OWNER), [`FUSE_BURNED`](/docs/reference/errors/FUSE_BURNED) | the account may not unwrap 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="Unwrapping a name" const { hash } = await ens.wrapper.unwrap({ name: "alice.eth" }) ``` ```ts title="Unwrapping a name with a standalone call" import { Actions } from "@ensforge/sdk" await Actions.wrapper.unwrap(ens, { name: "alice.eth" }) ``` ```ts title="Unwrapping a name in an Effect program" import { Actions } from "@ensforge/sdk/effect" yield* Actions.wrapper.unwrap(ens, { name: "alice.eth" }) ``` ## Plan methods [#plan-methods] Each method takes the same options as `wrapper.unwrap` and sends nothing. See [Preview before sending](/docs/sdk/preview-before-sending). | Method | Description | | --- | --- | | `wrapper.unwrap.prepare(options)` | Builds the plan without sending anything. | | `wrapper.unwrap.simulate(options)` | Simulates the plan with `eth_call`, reporting each step. | | `wrapper.unwrap.estimateGas(options)` | Estimates the gas and ETH the plan needs. | ## Wait for the receipt with `unwrapSync` [#wait-for-the-receipt-with-unwrapsync] Unwraps an ENSv1 name from the NameWrapper. Resolves once the receipt is in. Use when the next step depends on the change being on-chain. `wrapper.unwrapSync` 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="Unwrapping a name and waiting" const { receipt } = await ens.wrapper.unwrapSync({ name: "alice.eth" }) ``` ```ts title="Waiting with a standalone call" import { Actions } from "@ensforge/sdk" await Actions.wrapper.unwrapSync(ens, { name: "alice.eth" }) ``` ```ts title="Waiting in an Effect program" import { Actions } from "@ensforge/sdk/effect" yield* Actions.wrapper.unwrapSync(ens, { name: "alice.eth" }) ``` ## See also [#see-also] - [`wrapper.wrap`](/docs/reference/sdk/wrapper/wrap) to wrap it # wrapper.wrap > For the complete documentation index, see [llms.txt](https://ensforge.com/llms.txt). Wraps an ENSv1 name in the NameWrapper. Parameters, return value, errors and examples for wrapper.wrap in @ensforge/sdk. Source: https://ensforge.com/docs/reference/sdk/wrapper/wrap Wraps an ENSv1 name in the NameWrapper. Resolves once the transaction is submitted. ## When to use [#when-to-use] Use to turn an ENSv1 name into an ERC-1155 token, or to burn fuses on a `.eth` name. Use [`wrapSync`](/docs/reference/sdk/wrapper/wrap#wait-for-the-receipt-with-wrapsync) to wait for the receipt. ## Details [#details] - `.eth` second-level names: one transaction from the registrant, which may burn owner fuses (`cannotUnwrap` first). - Other names: the registry owner approves the NameWrapper, if needed, then wraps. - The wrapped name stays with its current holder (registrant or manager) unless `owner` is given, also when an approved operator wraps it. - Keeps the current resolver unless `resolver` is given. - ENSv2 has no NameWrapper. Wrapped names migrate to ENSv2 like unwrapped ones. - An operator of a non-`.eth` name's manager cannot approve the NameWrapper for the manager: the manager approves it first ([`NOT_APPROVED`](/docs/reference/errors/NOT_APPROVED)). ## Signature [#signature] ```ts function wrap( client: Like, options: wrap.Options & Write.Options, ): Promise ``` Call it as `ens.wrapper.wrap(options)` on a client, or `Actions.wrapper.wrap(client, options)`. ## Parameters [#parameters] | Option | Type | Default | Description | | --- | --- | --- | --- | | `name` (required) | `string` | | ENSv1 name. Normalized automatically. | | `owner` | `string` | | Owner of the wrapped name. Defaults to its current holder, else the signer. | | `fuses` | `readonly Fuse.Name[]` | | Fuses to burn while wrapping (`.eth` second-level names only). | | `resolver` | `string` | | Resolver to set. Defaults to the current one. | 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_RECORD_VALUE`](/docs/reference/errors/INVALID_RECORD_VALUE) | invalid input or fuses. | | [`NameStateError`](/docs/reference/errors/name-state-error) | [`NAME_EXPIRED`](/docs/reference/errors/NAME_EXPIRED), [`NAME_NOT_REGISTERED`](/docs/reference/errors/NAME_NOT_REGISTERED), [`NAME_WRAPPED`](/docs/reference/errors/NAME_WRAPPED) | the name cannot be wrapped. | | [`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; migrated names have no NameWrapper. | | [`UnauthorizedError`](/docs/reference/errors/unauthorized-error) | [`NOT_OWNER`](/docs/reference/errors/NOT_OWNER), [`NOT_APPROVED`](/docs/reference/errors/NOT_APPROVED) | the account does not own the name, or the manager has not approved the NameWrapper. | | [`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="Wrapping a name" const { hash } = await ens.wrapper.wrap({ name: "alice.eth" }) ``` ```ts title="Wrapping a name with a standalone call" import { Actions } from "@ensforge/sdk" await Actions.wrapper.wrap(ens, { name: "alice.eth" }) ``` ```ts title="Wrapping a name in an Effect program" import { Actions } from "@ensforge/sdk/effect" yield* Actions.wrapper.wrap(ens, { name: "alice.eth" }) ``` ## Plan methods [#plan-methods] Each method takes the same options as `wrapper.wrap` and sends nothing. See [Preview before sending](/docs/sdk/preview-before-sending). | Method | Description | | --- | --- | | `wrapper.wrap.prepare(options)` | Builds the plan without sending anything. | | `wrapper.wrap.simulate(options)` | Simulates the plan with `eth_call`, reporting each step. | | `wrapper.wrap.estimateGas(options)` | Estimates the gas and ETH the plan needs. | ## Wait for the receipt with `wrapSync` [#wait-for-the-receipt-with-wrapsync] Wraps an ENSv1 name in the NameWrapper. Resolves once the receipt is in. Use when the next step depends on the change being on-chain. `wrapper.wrapSync` 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="Wrapping a name and waiting" const { receipt } = await ens.wrapper.wrapSync({ name: "alice.eth" }) ``` ```ts title="Waiting with a standalone call" import { Actions } from "@ensforge/sdk" await Actions.wrapper.wrapSync(ens, { name: "alice.eth" }) ``` ```ts title="Waiting in an Effect program" import { Actions } from "@ensforge/sdk/effect" yield* Actions.wrapper.wrapSync(ens, { name: "alice.eth" }) ``` ## See also [#see-also] - [`wrapper.unwrap`](/docs/reference/sdk/wrapper/unwrap) to unwrap it # Custom indexers > For the complete documentation index, see [llms.txt](https://ensforge.com/llms.txt). Build an indexer from your own data source with defineIndexer, or combine bigname and Goldsky, so lists, search and history work on your data. Source: https://ensforge.com/docs/sdk/custom-indexers An **indexer** is a service that has already collected ENS data into a searchable form, so `ens.indexer.getSubnames` or `getNamesForAddress` can answer in one request. ensforge ships `bigname()` and `goldsky()`. `defineIndexer` lets you serve the same actions from your own API, database or test data. ## Prerequisites [#prerequisites] - Know what an indexer is and how to connect one. See [Connect an indexer](/docs/sdk/connect-an-indexer) and [Name lists and indexers](/docs/sdk/name-lists-and-indexers). - A data source you can query from TypeScript. ## When to write one [#when-to-write-one] Use `defineIndexer` when your data source does not speak bigname's REST API. If it does, such as a self-hosted bigname or a proxy, pass its URL to `bigname({ url })` instead. ## 1. Define the adapter [#1-define-the-adapter] An adapter is an `id` and the queries it answers, as Promise functions. Implement only the queries you serve. The others fail with [`INDEXER_UNSUPPORTED`](/docs/reference/errors/INDEXER_UNSUPPORTED), which lets `fallback` ask the next indexer. **Example** (An Adapter for an In-House Subnames API) ```ts title="in-house.ts" import { defineIndexer } from "@ensforge/sdk/indexer"; import { namehash } from "viem"; declare const api: { subnames( name: string, cursor: string | undefined, options: { signal: AbortSignal | undefined }, ): Promise<{ names: string[]; next: string | null }>; }; export const inHouse = defineIndexer({ id: "in-house", getSubnames: async ({ name, cursor }, { signal }) => { const page = await api.subnames(name, cursor, { signal }); return { items: page.names.map((subname) => ({ name: subname, displayName: subname, namespace: "ens", node: namehash(subname), status: null, authority: null, owner: null, manager: null, registeredAt: null, createdAt: null, expiresAt: null, graceEndsAt: null, expiryReason: null, ensV1: null, labelhash: null, subnameCount: null, subregistry: null, })), cursor: page.next, hasMore: page.next !== null, totalCount: null, }; }, }); ``` What the adapter gets and returns: - The first argument is the query. Actions validate it first: names are normalised, addresses checksummed and the namespace resolved. - The second argument has `chainId` (the client's chain) and `signal`, aborted when the call is cancelled. Pass `signal` to your fetches. - A page needs `items`, `cursor` (the value to pass back for the next page, or `null`), `hasMore` and `totalCount`. - Every answer also has metadata (`asOf`, `snapshots`, `completeness`, `origin` and more). Leave it out and ensforge fills it: no snapshot, `completeness: "full"`, and `indexer` set to your `id`. Set `completeness` yourself when the answer is partial. The adapter can answer any of these queries: `getName`, `getNamesForAddress`, `getSubnames`, `getHistory`, `getEvents`, `search`, `lookup`, `getNamesByExpiry`, `getPrimaryName`, `getRecords`, `getPermissions`, `getRegistry`, `getRegistryLabels`, `getResolver`, `getResolverLinks`, `getResolverRoles`, `getResolvers`, `getNamespace` and `getStatus`. ## 2. Report failures with the right error [#2-report-failures-with-the-right-error] Throw an ensforge `IndexerError` to control how a failure is reported. Anything else you throw becomes [`INDEXER_UNAVAILABLE`](/docs/reference/errors/INDEXER_UNAVAILABLE). Return `null` from `getName`, `getRecords`, `getRegistry`, `getResolver` and `getNamespace` when nothing exists. Other queries must return an object, or the call fails with [`INDEXER_RESPONSE_INVALID`](/docs/reference/errors/INDEXER_RESPONSE_INVALID). **Example** (Reporting a Rate Limit) ```ts title="errors.ts" import { Errors } from "@ensforge/sdk"; import { defineIndexer } from "@ensforge/sdk/indexer"; declare const fetchProfile: (name: string) => Promise; export const guarded = defineIndexer({ id: "guarded", getName: async () => { const response = await fetchProfile("nick.eth"); if (response.status === 429) { throw new Errors.IndexerError({ code: "INDEXER_RATE_LIMITED", status: 429 }); } return null; }, }); ``` `INDEXER_RATE_LIMITED`, `INDEXER_UNAVAILABLE` and `INDEXER_BEHIND` are retryable and make `fallback` move on. ## 3. Use it [#3-use-it] Pass the indexer to the client. Combine it with others using `fallback`: each query goes to the first indexer that can answer it. **Example** (Yours First, bigname After) ```ts title="client.ts" import { Ensforge, ensActions } from "@ensforge/sdk"; import { bigname, fallback, indexerActions, type Indexer } from "@ensforge/sdk/indexer"; import { createPublicClient, http } from "viem"; import { mainnet } from "viem/chains"; declare const inHouse: Indexer; const publicClient = createPublicClient({ chain: mainnet, transport: http() }); export const ens = Ensforge.create({ publicClient, indexer: fallback([inHouse, bigname()]), }) .extend(ensActions()) .extend(indexerActions()); ``` `fallback` asks the next indexer when one is unavailable, rate limiting, behind, or does not serve the query. Not found is an answer and is not retried. Cursors are tagged with the indexer that issued them, so the next page goes back to the same one. ## Walk every page [#walk-every-page] `paginate` follows `cursor` until the last page. `break` stops requesting pages. **Example** (Walking Every Page of a Custom Indexer) ```ts title="paginate.ts" import { Ensforge, indexerActions } from "@ensforge/sdk"; import { paginate, type Indexer } from "@ensforge/sdk/indexer"; import { createPublicClient, http } from "viem"; import { mainnet } from "viem/chains"; declare const inHouse: Indexer; const publicClient = createPublicClient({ chain: mainnet, transport: http() }); const ens = Ensforge.create({ publicClient, indexer: inHouse }).extend(indexerActions()); for await (const page of paginate(ens.indexer.getSubnames, { name: "ens.eth" })) { console.log(page.items.length); } ``` ## Use one as a test double [#use-one-as-a-test-double] A small adapter makes tests independent of a live service. See [Test your integration](/docs/sdk/testing). **Example** (An Indexer That Finds Nothing) ```ts title="double.ts" import { defineIndexer } from "@ensforge/sdk/indexer"; export const empty = defineIndexer({ id: "test", getName: async () => null }); ``` ## Effect adapters [#effect-adapters] `Indexer.define` in `@ensforge/sdk/effect` takes Effect functions instead of Promises, and fails with ensforge errors in the error channel. `Indexer.paginate` returns a `Stream`. See [The Effect API](/docs/sdk/effect-api). ## Limits [#limits] ensforge checks that an answer is an object, and that a page has an `items` array. It trusts the types of the fields to your TypeScript types. Built-in adapters check every response against the indexer's schema. Two indexers can also disagree on semantics, so apps that compare answers should stick to one. ## Check the result [#check-the-result] Call an action you implemented and read `indexer` on the answer. It should be your adapter's `id`. ## Troubleshooting [#troubleshooting] ### `INDEXER_NOT_CONFIGURED` [#indexer_not_configured] The client has no `indexer`. Pass it to `Ensforge.create`. See [`INDEXER_NOT_CONFIGURED`](/docs/reference/errors/INDEXER_NOT_CONFIGURED). ### `INDEXER_UNSUPPORTED` [#indexer_unsupported] The adapter does not implement that query, or does not serve the namespace. Add the method, or put another indexer after it in `fallback`. See [`INDEXER_UNSUPPORTED`](/docs/reference/errors/INDEXER_UNSUPPORTED). ### `INDEXER_RESPONSE_INVALID` [#indexer_response_invalid] The adapter answered `null` for a query that cannot be `null`, or a page without `items`. See [`INDEXER_RESPONSE_INVALID`](/docs/reference/errors/INDEXER_RESPONSE_INVALID). # The Effect API > For the complete documentation index, see [llms.txt](https://ensforge.com/llms.txt). Run every ensforge action as an Effect with typed errors, a client service and streams, when your app already uses Effect. Source: https://ensforge.com/docs/sdk/effect-api The Effect API is optional. Everything in ensforge works with Promises. Use `@ensforge/sdk/effect` when your program is already written with [Effect](https://effect.website): you get typed errors in the error channel, interruption, services and streams. ## Prerequisites [#prerequisites] - `effect` version 4 (`^4.1.4`) installed. It is a peer dependency of `@ensforge/sdk`. - Familiarity with `Effect.gen`. ## Same actions, returned as Effects [#same-actions-returned-as-effects] `@ensforge/sdk/effect` exports the same action tree as the root entry. Each action takes a client first and returns an `Effect` whose error channel is the action's documented error union. **Example** (Reading an Address in an Effect Program) ```ts title="read.ts" import { Actions, Ensforge } from "@ensforge/sdk/effect"; import { Effect } from "effect"; import { createPublicClient, http } from "viem"; import { mainnet } from "viem/chains"; const publicClient = createPublicClient({ chain: mainnet, transport: http() }); const ens = Ensforge.create({ publicClient }); const program = Actions.record.getAddress(ens, { name: "nick.eth" }); const address = await Effect.runPromise(program); ``` - The Effect client has no `ens.record.*` methods. Pass the client to `Actions..`. - Reads accept a bare viem client too, as in the Promise API. ## Provide the client as a service [#provide-the-client-as-a-service] `Ensforge.Ensforge` is an Effect `Context.Service`, and `Ensforge.layer(options)` builds a `Layer` for it. The layer fails with `ConfigError` when the options are invalid, such as an unknown chain. **Example** (Using the Service) ```ts title="service.ts" import { Actions, Ensforge } from "@ensforge/sdk/effect"; import { Effect } from "effect"; import { createPublicClient, http } from "viem"; import { mainnet } from "viem/chains"; const publicClient = createPublicClient({ chain: mainnet, transport: http() }); const program = Effect.gen(function* () { const ens = yield* Ensforge.Ensforge; return yield* Actions.record.getText(ens, { name: "nick.eth", key: "url" }); }); await Effect.runPromise(program.pipe(Effect.provide(Ensforge.layer({ publicClient })))); ``` The service key is `@ensforge/sdk/Ensforge`. In tests, provide a different client with `Layer.succeed(Ensforge.Ensforge, client)`. ## Handle typed errors [#handle-typed-errors] Errors are the same instances Promise users catch, so `_tag` matches the class name. Use `Effect.catchTag` to handle one class and let the others stay in the error type. **Example** (Recovering from a Missing Record) ```ts title="errors.ts" import { Actions, Ensforge } from "@ensforge/sdk/effect"; import { Effect } from "effect"; import { createPublicClient, http } from "viem"; import { mainnet } from "viem/chains"; const publicClient = createPublicClient({ chain: mainnet, transport: http() }); const ens = Ensforge.create({ publicClient }); const program = Actions.record .getAddress(ens, { name: "nobody-here.eth", strict: true }) .pipe(Effect.catchTag("NotFoundError", () => Effect.succeed(null))); ``` After `catchTag`, `NotFoundError` is gone from the error type. See [Handle errors](/docs/sdk/handle-errors) for the codes. **Example** (Retrying Only What Is Retryable) ```ts title="retry.ts" import { Actions, Ensforge } from "@ensforge/sdk/effect"; import { Effect } from "effect"; import { createPublicClient, http } from "viem"; import { mainnet } from "viem/chains"; const publicClient = createPublicClient({ chain: mainnet, transport: http() }); const ens = Ensforge.create({ publicClient }); const program = Actions.record .getAddress(ens, { name: "nick.eth" }) .pipe(Effect.retry({ times: 3, while: (error) => error.retryable })); ``` ## Write, preview and resume [#write-preview-and-resume] Writes keep their methods as Effects: `Actions.record.set`, `Actions.record.set.prepare`, `.simulate` and `.estimateGas`, and the `…Sync` forms. Plans are plain data, so they are the same values as in the Promise API. **Example** (Preparing, Simulating and Sending) ```ts title="write.ts" import { Actions, Ensforge } from "@ensforge/sdk/effect"; import { Effect } from "effect"; import { createPublicClient, http } from "viem"; import { sepolia } from "viem/chains"; const publicClient = createPublicClient({ chain: sepolia, transport: http() }); const ens = Ensforge.create({ publicClient, account: "0x225f137127d9067788314bc7fcc1f36746a3c3B5", }); const options = { name: "ensforge-docs-demo.eth", texts: { url: "https://example.com" } }; const program = Effect.gen(function* () { const simulation = yield* Actions.record.set.simulate(ens, options); if (!simulation.ok) return simulation; const plan = yield* Actions.record.set.prepare(ens, options); return yield* Actions.plan.send(ens, { plan }); }); ``` See [Preview before sending](/docs/sdk/preview-before-sending) and [Continue after a failure](/docs/sdk/continue-after-a-failure). ## Batch reads [#batch-reads] `Actions.batch` is an Effect too. Build the requests with the Promise entry's `.request` helpers. **Example** (Batching Reads in an Effect Program) ```ts title="batch.ts" import { Actions as Requests } from "@ensforge/sdk"; import { Actions, Ensforge } from "@ensforge/sdk/effect"; import { createPublicClient, http } from "viem"; import { mainnet } from "viem/chains"; const publicClient = createPublicClient({ chain: mainnet, transport: http() }); const ens = Ensforge.create({ publicClient }); const program = Actions.batch(ens, { requests: [Requests.name.get.request({ name: "nick.eth" })], }); ``` ## Validate names with a schema [#validate-names-with-a-schema] `Name.Normalized` is a branded `Schema` for names that are already normalised (ENSIP-15). It exists only in the Effect entry. **Example** (Decoding a Normalised Name) ```ts title="schema.ts" import { Name } from "@ensforge/sdk/effect"; import { Schema } from "effect"; const name = Schema.decodeUnknownSync(Name.Normalized)("nick.eth"); ``` ## Stream indexer pages [#stream-indexer-pages] `Indexer.paginate` turns a list into a `Stream` of pages, following `cursor` until the last page. `Indexer.define` is the Effect form of `defineIndexer`. See [Custom indexers](/docs/sdk/custom-indexers) and [Load more results](/docs/sdk/load-more-results). **Example** (Streaming Three Pages of Subnames) ```ts title="stream.ts" import { Actions, Ensforge, Indexer } from "@ensforge/sdk/effect"; import { bigname } from "@ensforge/sdk/indexer"; import { Effect, Stream } from "effect"; import { createPublicClient, http } from "viem"; import { mainnet } from "viem/chains"; const publicClient = createPublicClient({ chain: mainnet, transport: http() }); const ens = Ensforge.create({ publicClient, indexer: bigname() }); const subnames = Indexer.paginate((cursor) => Actions.indexer.getSubnames(ens, { name: "ens.eth", namespace: "ens", limit: 200, cursor }), ).pipe(Stream.take(3)); const pages = await Effect.runPromise(Stream.runCollect(subnames)); ``` ## Check the result [#check-the-result] Run the program with `Effect.runPromise`. A failure rejects with the error instance, with its `code` and `context`. ## Troubleshooting [#troubleshooting] ### `ens.record` is undefined [#ensrecord-is-undefined] The Effect client does not carry action methods. Call `Actions.record.(ens, options)`. ### The error type is a long union [#the-error-type-is-a-long-union] Each action declares only the classes it can fail with, plus the common ones. Narrow with `Effect.catchTag`, or map to your own error at a boundary. # ENS versions under the hood > For the complete documentation index, see [llms.txt](https://ensforge.com/llms.txt). Understand ENSv1, ENSv2, the bridge between them and the kinds of name, and what ensforge unifies so your code does not have to. Source: https://ensforge.com/docs/sdk/ens-versions ENS runs on two sets of contracts at once. **ENSv1** is the original protocol. **ENSv2** is its successor, which names move to over time. ensforge reads and writes both, and picks the right one for each name, so most code never needs this page. Read it when you build tools that show where a name lives, move names to ENSv2, or use features only one version has. ## ENSv1 and ENSv2 [#ensv1-and-ensv2] | | ENSv1 | ENSv2 | | ------------------------ | ------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------- | | Where names are kept | One registry for every name | A tree of registries: each name can have its own registry for its subnames (a **subregistry**) | | How a name is held | Registry owner, plus a `.eth` registration token or a Name Wrapper token | One ERC-1155 token in the parent's registry | | Who else may act | Operators, token approvals, resolver delegates; Name Wrapper fuses | **Roles**, granted per name or per registry | | Default resolver | Shared public resolver | A **PermissionedResolver** per name, with roles per record | | New `.eth` registrations | Not offered by ensforge: new names register on ENSv2 | Paid in an ERC-20 token (USDC by default), as are renewals on both versions | Both share what matters to most apps: names, [records](/docs/reference/glossary#record), [resolvers](/docs/reference/glossary#resolver) and primary names work the same way. See [Names and records](/docs/sdk/names-and-records). ## The bridge [#the-bridge] ENSv2 did not copy every ENSv1 name. Instead, ENSv2 lookups start in the ENSv2 registries and fall through to ENSv1 for names that have not moved. ENSv1 `.eth` names are reserved in ENSv2, and each reservation points at a read-only resolver that answers from ENSv1: the **ENSv1 bridge**. ```mermaid flowchart LR U[Universal Resolver] -->|look up| V2[ENSv2 registries] V2 -->|moved or new name| R2[The name's ENSv2 resolver] V2 -->|reserved ENSv1 name| B[ENSv1 bridge] B -->|reads| R1[The name's ENSv1 resolver] ``` The bridge is why a lookup works for every name with one call. It also means ENSv2 decides which ENSv1 names it still reaches. An ENSv1 name whose parent moved to ENSv2 without it is no longer reached: its ENSv1 records stop resolving, and so do its subnames'. `name.get` reports this as `reachable: false`. A second bridge works the other way: a read-only resolver on the ENSv1 side reads migrated names from ENSv2. `resolver.get` reports the two bridges as `"ens-v1-resolver"` and `"ens-v2-resolver"`. Nothing can be written to either. ## Kinds of name [#kinds-of-name] `name.get` reports where each name lives as `kind`, and which protocol controls it as `protocol`. | `kind` | `protocol` | Meaning | | ---------------- | ---------------- | ----------------------------------------------------------------------------------------------- | | `"v1-unwrapped"` | `"v1"` | On ENSv1, held directly. | | `"v1-wrapped"` | `"v1"` | On ENSv1, held through the Name Wrapper. See [What wrapped names are](/docs/sdk/wrapped-names). | | `"v2-native"` | `"v2"` | Registered on ENSv2. | | `"v2-migrated"` | `"v2"` | Moved from ENSv1 to ENSv2. Its ENSv1 entry is retired to a contract called the Graveyard. | | `"v2-reserved"` | `"v2"` | Reserved on ENSv2, with no ENSv1 owner. | | `"available"` | `"v2"` or `"v1"` | Not registered. May still resolve through a parent's resolver: check `inheritedResolver`. | **Example** (Reading Where Names Live) ```ts title="kinds.ts" import { Ensforge, ensActions } from "@ensforge/sdk"; import { createPublicClient, http } from "viem"; import { mainnet } from "viem/chains"; const ens = Ensforge.create({ publicClient: createPublicClient({ chain: mainnet, transport: http() }), }).extend(ensActions()); for (const name of ["nick.eth", "vitalik.eth"]) { const { kind, protocol, migrated } = await ens.name.get({ name }); console.log(name, kind, protocol, migrated); } ``` ```text title="Output (mainnet, November 2026)" nick.eth v2-migrated v2 true vitalik.eth v1-unwrapped v1 false ``` Both names resolve with the same `record.getAddress` call. The kind matters only for the tasks below. ## What ensforge unifies [#what-ensforge-unifies] These work the same for every kind of name. ensforge picks the contracts: - Every read: records, addresses, avatars, primary names, `name.get`, `permission.get`. - Writing records (`record.set`), changing the resolver (`resolver.set`), transferring (`name.transfer`), creating subnames (`subname.create`). - Renewing `.eth` names (`registration.renew`), on either version. - Setting primary names (`primaryName.set`). - Batching, plans, errors and resuming. `permission.get` maps ENSv1 ownership, approvals and fuses and ENSv2 roles to the same answers, so a UI can show the same buttons for any name. ## Where the version shows through [#where-the-version-shows-through] Some features exist in one version only. Their actions say so in their reference page. Where the protocol would refuse the call, they fail with a typed error before anything is sent. | Only on ENSv1 | Only on ENSv2 | | ------------------------------------------------------------------------- | -------------------------------------------------------------------------- | | `name.setManager`, `name.setTtl`, `name.reclaim` (manager and registrant) | `role.*` (roles) | | `approval.setToken`, `approval.getToken` (token approvals) | `registry.*` (subregistries) | | `wrapper.*` (the Name Wrapper and fuses) | `resolver.create`, `resolver.link`, `resolver.getLink`, `resolver.upgrade` | | `dns.claim` (importing a DNS name) | `name.getLabel` (recovering a label from its hash) | - Name, approval, role, registry and Name Wrapper actions called on the other version fail with [`UNSUPPORTED_PROTOCOL`](/docs/reference/errors/UNSUPPORTED_PROTOCOL). - A task that needs the name on ENSv2 first fails with [`NAME_REQUIRES_MIGRATION`](/docs/reference/errors/NAME_REQUIRES_MIGRATION). - A feature the chain's deployment lacks fails with [`UNSUPPORTED_ON_DEPLOYMENT`](/docs/reference/errors/UNSUPPORTED_ON_DEPLOYMENT). See [Upgrading names](/docs/sdk/move-a-name-to-ensv2) for the ENSv2-only features and [Wrapped names](/docs/sdk/wrapped-names) for the ENSv1 ones. ## Moving a name to ENSv2 [#moving-a-name-to-ensv2] An ENSv1 name moves to ENSv2 by [migration](/docs/reference/glossary#migration). `migration.get` says whether a name can move, how, and what it would become. `migration.migrate` moves one or more names with their records and subnames. A [locked](/docs/reference/glossary#locked) subname can move only after its parent; `migrateParents` moves those parents first. See [Move a name to ENSv2](/docs/sdk/move-a-name-to-ensv2). ## Deployments [#deployments] ensforge ships the ENS contracts for Ethereum mainnet and Sepolia, both with ENSv1 and ENSv2. The client picks them from the chain of its viem client and exposes them as `ens.deployment`. Devnets and forks pass their own with `deployment`. See [Addresses and chains](/docs/contracts/addresses-and-chains). # Extend the client > For the complete documentation index, see [llms.txt](https://ensforge.com/llms.txt). Add your own action group to an ensforge client, or write a custom route for writes, with the unstable extension entry point. Source: https://ensforge.com/docs/sdk/extend-the-client ensforge clients are extended with **decorators**: functions that add a group of actions, such as `ensActions()` or `hcaActions()`. This page shows how to write your own, and how to write a route (`via`) for writes. The exports of `@ensforge/sdk/extension` are marked `unstable`. They can change or be removed in any minor release, and each change is described in its changeset. `Write.Via` and `client.extend` are stable. Pin the SDK version if you depend on the extension entry. ## Prerequisites [#prerequisites] - Read [Ways to call actions](/docs/sdk/ways-to-call-actions) for the client, standalone and Effect forms of an action. - Familiarity with Effect's `Effect.fn`. Actions are implemented as Effects and wrapped as Promises. ## How an action is built [#how-an-action-is-built] Each ensforge action has three layers: 1. An Effect implementation that takes the client and the options. 2. A Promise function that runs the implementation with `Action.promise`, so a bare viem client works and errors carry context. 3. A decorator that binds the client, so `ens.group.action(options)` works. ## 1. Write the Effect implementation [#1-write-the-effect-implementation] The implementation fails only with ensforge errors (`AnyError`). `Action.withContext` adds the action's path, name, account and chain to every error, so Promise and Effect users see the same `error.context`. **Example** (A Profile Read Built from Two Actions) ```ts title="profile/effect.ts" import { Actions } from "@ensforge/sdk/effect"; import { Action, type AnyError, type Client } from "@ensforge/sdk/extension"; import { Effect } from "effect"; export type Options = { name: string }; export const get = Effect.fn("my.profile.get")(function* ( client: Client, options: Options, ): Effect.fn.Return<{ address: string | null; url: string | null }, AnyError> { const address = yield* Actions.record.getAddress(client, { name: options.name }); const url = yield* Actions.record.getText(client, { name: options.name, key: "url" }); return { address, url }; }, Action.withContext("profile.get")); ``` ## 2. Wrap it as a Promise [#2-wrap-it-as-a-promise] `Action.promise(path, implementation, client, options)` accepts an ensforge client or a bare viem client, rejects with `signal.reason` when the call is aborted, and otherwise rejects with an ensforge error. **Example** (Wrapping the Profile Read as a Promise) ```ts title="profile/index.ts" import { Actions } from "@ensforge/sdk/effect"; import { Action, type AnyError, type Client, type Like } from "@ensforge/sdk/extension"; import { Effect } from "effect"; type Options = { name: string }; type Profile = { address: string | null; url: string | null }; const getImpl = Effect.fn("my.profile.get")(function* ( client: Client, options: Options, ): Effect.fn.Return { const address = yield* Actions.record.getAddress(client, { name: options.name }); const url = yield* Actions.record.getText(client, { name: options.name, key: "url" }); return { address, url }; }, Action.withContext("profile.get")); export function get(client: Like, options: Options): Promise { return Action.promise("profile.get", getImpl, client, options); } get.path = "profile.get" as const; ``` ## 3. Add the decorator [#3-add-the-decorator] A decorator is a function that takes the client and returns the groups to add. Add it with `client.extend`. **Example** (Adding the Profile Group to a Client) ```ts title="profile/decorator.ts" import { Ensforge, ensActions } from "@ensforge/sdk"; import type { Client, Like } from "@ensforge/sdk/extension"; import { createPublicClient, http } from "viem"; import { mainnet } from "viem/chains"; declare const get: (client: Like, options: { name: string }) => Promise<{ url: string | null }>; const profileActions = () => (client: Client) => ({ profile: { get: (options: { name: string }) => get(client, options) }, }); const publicClient = createPublicClient({ chain: mainnet, transport: http() }); const ens = Ensforge.create({ publicClient }).extend(ensActions()).extend(profileActions()); const { url } = await ens.profile.get({ name: "nick.eth" }); ``` Group names must not be `chain`, `account`, `deployment`, `publicClient`, `config` or `extend`. A decorator that uses one throws [`INVALID_ACTION_GROUP`](/docs/reference/errors/INVALID_ACTION_GROUP). Groups with the same name merge, so you can add actions to an existing group. For a write, the same pattern applies with `Action.write(path, planner)`, which gives you the action, its `…Sync` form and `.prepare`, `.simulate` and `.estimateGas` from one planner, and `makePlan` to build the plan. `@ensforge/hca` is the reference extension: see its source. ## Write a route [#write-a-route] A route (`via`) changes how a plan is sent. It is a plain object, and `Write.Via` is stable. | Member | Purpose | | ---------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- | | `id` | Name shown in progress and errors. | | `sender(context)` | The account the calls run as (`msg.sender`), when it is not the signer. | | `prepare(plan, context)` | Rewrites the plan before it is simulated or sent. The plan's id stays the same. Steps marked `from: "signer"` must stay transactions of the signer. | | `send(step, context)` | Sends one step itself and returns a reference to follow it, such as a UserOperation hash. | | `status(reference, context)` | Reports `pending`, `success` with hashes, or `failed` for a step sent with `send`. | Without `send`, the signer sends the rewritten plan as usual. **Example** (A Route That Adds a Warning) ```ts title="route.ts" import type { Write } from "@ensforge/sdk"; export const audited: Write.Via = { id: "audited", prepare: async (plan) => ({ ...plan, warnings: [...plan.warnings, { code: "AUDITED", message: "Sent through the audit route." }], }), }; ``` Pass it as `via: audited` to any write, `.prepare`, `.simulate` or `.estimateGas`. A route fails with its own errors, which are outside the action's `ErrorType`. See [Use smart accounts](/docs/sdk/use-smart-accounts). ## Other building blocks [#other-building-blocks] The entry also exports `from` (wrap a viem client), `withDefaults` and `fromCause` for errors, `requireAddress`, `Rpc` helpers, `receiptsOf` and `waitForReceipts`, `resolveSigner`, `simulatePlan` and `simulateStep`, and `makePlan`. They are not documented further because they can change. ## Check the result [#check-the-result] Call `ens.profile.get` with an ensforge client and with a bare viem client through the standalone function. Both should return the same value. ## Troubleshooting [#troubleshooting] ### `INVALID_ACTION_GROUP` [#invalid_action_group] The decorator returned a reserved group name. Rename the group. See [`INVALID_ACTION_GROUP`](/docs/reference/errors/INVALID_ACTION_GROUP). ### A type error after upgrading [#a-type-error-after-upgrading] Extension exports are unstable and can change in a minor release. Read the changeset for the version you upgraded to. # Save and resume plans > For the complete documentation index, see [llms.txt](https://ensforge.com/llms.txt). Keep plan progress in browser storage or your own database, so a multi-step write survives reloads, crashes and restarts. Source: https://ensforge.com/docs/sdk/save-and-resume-plans Every write saves its **plan** and progress to the client's storage after each step. With storage that outlives your process, a registration or migration survives a page reload, a crash or a serverless cold start. This page shows the built-in stores, how to write your own, and how to serialise a plan. ## Prerequisites [#prerequisites] - Know what [`plan.resume`](/docs/sdk/continue-after-a-failure) does. - Read [How writes work](/docs/sdk/writing-to-ens) for what a plan is. ## What is saved [#what-is-saved] A saved plan is a `Plan.Record`: | Field | Description | | ------------ | ------------------------------------------------------------------------------------------------------ | | `plan` | The plan: id, steps, calls, requirements, warnings, deployments and fees. | | `status` | `"pending"` while steps remain, `"completed"` once every step is submitted, `"failed"` after an error. | | `submitted` | Transaction hashes per submitted step id. | | `bundles` | EIP-5792 bundle id per step sent in a bundle. | | `references` | Route references per step sent through `via`, such as UserOperation hashes. | | `error` | Message of the last failure. | | `updatedAt` | Unix time in milliseconds. | The record is written before the first step, after every submission, and when the write fails or completes. Saving is best effort: if the store throws, the write still runs, but it cannot be resumed. ## Choose a store [#choose-a-store] Pass `storage` to `Ensforge.create`. | Store | Survives reload | Where it works | | -------------------------------- | --------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- | | `Plan.memoryStorage()` (default) | No | Everywhere. Lost when the process or page reloads. | | `Plan.localStorage(key?)` | Yes | Browsers. Records are kept as JSON under one key, `ensforge:plans` by default. Calls reject where `localStorage` does not exist, such as server rendering. | | Your own `Plan.Storage` | Yes | Anywhere, such as a database or key-value store. | **Example** (Plans That Survive a Page Reload) ```ts title="storage.ts" import { Ensforge, Plan, ensActions } from "@ensforge/sdk"; import { createPublicClient, http } from "viem"; import { sepolia } from "viem/chains"; const publicClient = createPublicClient({ chain: sepolia, transport: http() }); export const ens = Ensforge.create({ publicClient, storage: Plan.localStorage("my-app:plans"), }).extend(ensActions()); ``` After a reload, list what did not finish and resume it: **Example** (Resuming Unfinished Plans) ```ts title="recover.ts" import { Ensforge, Plan, ensActions } from "@ensforge/sdk"; import { createPublicClient, http } from "viem"; import { sepolia } from "viem/chains"; const publicClient = createPublicClient({ chain: sepolia, transport: http() }); const ens = Ensforge.create({ publicClient, storage: Plan.localStorage("my-app:plans"), }).extend(ensActions()); const unfinished = await ens.plan.list({ status: "pending" }); for (const record of unfinished) { await ens.plan.resume({ id: record.plan.id }); } ``` ## Write your own store [#write-your-own-store] A store implements four Promise functions: `get`, `set`, `delete` and `list`. It holds `Plan.Record` values, which contain `bigint`s, so a store that writes text needs a bigint-safe encoding. `Plan.serialize` turns a record into text and `Plan.deserializeRecord` reads it back. **Example** (A Key-Value Store) ```ts title="kv-storage.ts" import { Plan } from "@ensforge/sdk"; type KeyValue = { get(key: string): Promise; put(key: string, value: string): Promise; delete(key: string): Promise; keys(prefix: string): Promise; }; export const kvStorage = (kv: KeyValue, prefix = "ensforge:plan:"): Plan.Storage => ({ get: async (id) => { const text = await kv.get(prefix + id); return text === null ? undefined : Plan.deserializeRecord(text); }, set: (record) => kv.put(prefix + record.plan.id, Plan.serialize(record)), delete: (id) => kv.delete(prefix + id), list: async () => { const keys = await kv.keys(prefix); const texts = await Promise.all(keys.map((key) => kv.get(key))); return texts.flatMap((text) => (text === null ? [] : [Plan.deserializeRecord(text)])); }, }); ``` - `set` stores the whole record as `Plan.serialize` text, which keeps bigints exact. - `get` returns `undefined` for an unknown id. `plan.get` reports it as `null`. - `list` returns every record. - `Plan.deserializeRecord` throws [`PLAN_INVALID`](/docs/reference/errors/PLAN_INVALID) when the text is not a serialised record. A store that keeps objects without text, such as IndexedDB or an in-process `Map`, needs none of this. ## Serialise a plan [#serialise-a-plan] Plans are plain data. `Plan.serialize` turns a plan or a record into JSON text with bigints preserved. `Plan.deserialize` reads a plan back and `Plan.deserializeRecord` reads a record back. Use them to send a prepared plan to another service, for review or signing elsewhere. **Example** (Sending a Plan to Another Process) ```ts title="serialize.ts" import { Ensforge, Plan, ensActions } from "@ensforge/sdk"; import { createPublicClient, http } from "viem"; import { sepolia } from "viem/chains"; const publicClient = createPublicClient({ chain: sepolia, transport: http() }); const account = "0x225f137127d9067788314bc7fcc1f36746a3c3B5"; const ens = Ensforge.create({ publicClient, account }).extend(ensActions()); const plan = await ens.record.set.prepare({ name: "ensforge-docs-demo.eth", texts: { url: "https://example.com" }, }); const text = Plan.serialize(plan); const restored = Plan.deserialize(text); ``` `Plan.deserialize` throws [`PLAN_INVALID`](/docs/reference/errors/PLAN_INVALID) when the text is not a serialised plan. A restored plan is for one chain and account: send it with [`plan.send`](/docs/reference/sdk/plan/send) on a client for the same ones. ## Check the result [#check-the-result] Start a write, reload the page or restart the process, and call `plan.list`. The plan should be there with the steps already submitted. ## Troubleshooting [#troubleshooting] ### `PLAN_NOT_FOUND` [#plan_not_found] The store has no plan with that id. With the default memory store, plans are lost on reload. See [`PLAN_NOT_FOUND`](/docs/reference/errors/PLAN_NOT_FOUND). ### `localStorage is not available in this environment` [#localstorage-is-not-available-in-this-environment] `Plan.localStorage()` ran where there is no `localStorage`. Use a custom store on the server. ### `PLAN_INVALID` [#plan_invalid] The stored text is not a serialised plan or record. `Plan.localStorage()` rejects a broken record with this error instead of returning bad data. Delete the entry, or clear the storage key. See [`PLAN_INVALID`](/docs/reference/errors/PLAN_INVALID). ### Plans from two tabs overwrite each other [#plans-from-two-tabs-overwrite-each-other] `Plan.localStorage` keeps every record under one key and rewrites the whole value on each save. Two tabs writing at once can lose a record. Use a different key per tab, or a store that writes one row per plan. # Use ensforge with AI agents > For the complete documentation index, see [llms.txt](https://ensforge.com/llms.txt). Give a coding agent the ensforge docs as llms.txt and Markdown, plus a short AGENTS.md that helps it write correct ensforge code. Source: https://ensforge.com/docs/sdk/use-with-ai-agents A coding agent writes better ENS code when it reads the ensforge docs instead of guessing from memory. This page shows where the agent-readable docs live and gives you a snippet and a prompt to paste into your project. ## Prerequisites [#prerequisites] - A project that uses (or will use) `@ensforge/sdk`. - A coding agent that reads an instruction file such as `AGENTS.md` or `CLAUDE.md`, or lets you paste a prompt. ## Where agents read the docs [#where-agents-read-the-docs] Every docs page exists as plain Markdown, and the whole site has an index for agents. | URL | What it is | | ----------------- | ------------------------------------------------------------------------------------------- | | `/llms.txt` | A short index: instructions for agents, the core pages first, the rest under `## Optional`. | | `/llms-full.txt` | Every docs page in one file, for tools that load all context up front. | | `/docs/.md` | One page as Markdown. Append `.md` to any docs URL. | Each docs page also carries a `` that points to its `.md` version, and the page actions have **Copy Markdown**, **Open in Claude** and **Open in ChatGPT** buttons. Those open a chat that starts from the page you are reading. Agents that send `Accept: text/markdown` to a docs URL get the Markdown version directly. ## 1. Add a short AGENTS.md [#1-add-a-short-agentsmd] Put this in the root of your project. It tells the agent which package to use, the shape of the API and where to look up the rest. **Example** (AGENTS.md Snippet for ensforge) ```md title="AGENTS.md" ## ENS Use `@ensforge/sdk` for every ENS read and write. Docs for agents: https://ensforge.com/llms.txt - Create one client and reuse it: `Ensforge.create({ publicClient }).extend(ensActions())`. - Call actions on the client, for example `await ens.record.getAddress({ name: "nick.eth" })`. Use the Promise API. Use `@ensforge/sdk/effect` only in code that already uses Effect. - Pass names as the user typed them. ensforge normalises and validates them; do not call `normalize` yourself. - A missing record is `null`, not an error. Real failures reject with an error that has a `code` and a `docsUrl`; read that page before writing a fix. - Writes need a `walletClient` on the client. Test writes on Sepolia, never on mainnet. - Look up exact options on the page for the action: https://ensforge.com/docs/.md ``` - The first line links `llms.txt`, so the agent can find every other page. - The list holds the facts a model most often gets wrong: normalisation, `null` records and the error codes. ## 2. Ask the agent to set ensforge up [#2-ask-the-agent-to-set-ensforge-up] Paste this prompt to add ensforge to an existing project. **Example** (Setup Prompt) ```text title="Prompt" Add ensforge to this project. Read https://ensforge.com/llms.txt first, then the Quick start and "Create a client" pages as Markdown. Install @ensforge/sdk, viem and effect with the project's package manager. Create one shared client in its own module, then replace the existing ENS lookups with ensforge actions. Keep the Promise API. Run the type checker and the tests when you are done, and list anything you could not verify. ``` ## 3. Point the agent at one page [#3-point-the-agent-at-one-page] When you ask about a single action, give the agent that page and nothing else. Copy the page as Markdown with the page action, or paste its `.md` URL: ```text title="Prompt" Read https://ensforge.com/docs/sdk/get-an-address.md and show me how to read the Base address of vitalik.eth. ``` One page fits in context with room left for your code, so the agent answers from the docs instead of its memory. ## Troubleshooting [#troubleshooting] ### The agent uses an old API [#the-agent-uses-an-old-api] Models learn from older code. Link `llms.txt` in `AGENTS.md`, as above, and ask the agent to read the page for the action before it writes the call. ### The agent calls `normalize` or `namehash` itself [#the-agent-calls-normalize-or-namehash-itself] ensforge does both. Add the line "Pass names as the user typed them" to your instructions, and see [Names and records](/docs/sdk/names-and-records) for why. ## Related [#related] The first read and the first write. The error codes an agent will meet. # How errors work > For the complete documentation index, see [llms.txt](https://ensforge.com/llms.txt). Learn how ensforge errors are grouped into classes and codes, what each error carries, and how to turn one into a message for users. Source: https://ensforge.com/docs/sdk/errors-explained When an ENS call fails, ensforge never hands you a raw contract revert or an RPC message. It translates every failure into an **ensforge error** with a class that says what kind of problem it is, a **code** that says exactly what happened, and the context you need to fix or report it. ## Classes and codes [#classes-and-codes] Each error has two names. The class groups related failures; the code is precise and stable. | Class | Example codes | Means | | ------------------- | ---------------------------------------- | ---------------------------------------- | | `InvalidInputError` | `INVALID_NAME`, `INVALID_ADDRESS` | The input is wrong. Nothing was sent. | | `NotFoundError` | `RESOLVER_NOT_FOUND`, `RECORD_NOT_FOUND` | The data does not exist. | | `NameStateError` | `NAME_NOT_AVAILABLE`, `NAME_EXPIRED` | The name is in the wrong state for this. | | `UnauthorizedError` | `NOT_OWNER`, `MISSING_ROLES` | The account may not do this. | | `UserRejectedError` | `USER_REJECTED` | The user declined in their wallet. | | `NetworkError` | `RPC_TIMEOUT`, `RATE_LIMITED` | The RPC failed. Often worth a retry. | | `GatewayError` | `GATEWAY_REQUEST_FAILED` | An off-chain gateway failed. | There are 19 classes in all. Every code has its own page under [Errors](/docs/reference/errors), with its causes and how to fix it. Codes are stable: renaming or removing one is a breaking change, made only in a major release. Branch on codes, never on message text. ## What an error carries [#what-an-error-carries] **Example** (Catching an Error) ```ts title="catch.ts" import { Ensforge, Errors, ensActions } from "@ensforge/sdk"; import { createPublicClient, http } from "viem"; import { mainnet } from "viem/chains"; const ens = Ensforge.create({ publicClient: createPublicClient({ chain: mainnet, transport: http() }), }).extend(ensActions()); try { await ens.record.getText({ name: "no-such-name-ensforge-docs.eth", key: "url", strict: true }); } catch (error) { if (Errors.is(error)) console.log(error.toJSON()); } ``` ```text title="Output (trimmed)" { name: 'NotFoundError', code: 'RESOLVER_NOT_FOUND', shortMessage: 'The name no-such-name-ensforge-docs.eth has no resolver.', hint: 'Set one with resolver.set.', details: [], retryable: false, context: { operation: 'record.getText', name: 'no-such-name-ensforge-docs.eth', chainId: 1, contract: '0xeEeEEEeE14D718C2B47D9923Deab1335E144EeEe', functionName: 'resolve', ... }, docsUrl: 'https://ensforge.com/docs/reference/errors/RESOLVER_NOT_FOUND' } ``` | Field | What it is | | -------------- | ----------------------------------------------------------------------------------------------------------------- | | `name`, `_tag` | The class name, such as `"NotFoundError"`. | | `code` | What happened, such as `"RESOLVER_NOT_FOUND"`. | | `shortMessage` | One line for developers. | | `hint` | How to fix it, when ensforge knows. | | `retryable` | Whether the same call can succeed if you try again. | | `context` | Where it happened: the action, name, account, chain, contract and, for writes, the `planId` and `step` to resume. | | `docsUrl` | The page for this code. | | `cause` | The original error, such as viem's, when there was one. | `error.message` combines these into a readable block for logs, ending with the code, the docs link and the SDK version. `toJSON()` returns a plain object that is safe to send to an error tracker. ## Every action declares its errors [#every-action-declares-its-errors] Each action lists the errors it can throw, as a type: `Actions.record.getText.ErrorType`. It is the union of the classes the action documents, plus a few every action can hit (a misconfigured client, a failing RPC, an unexpected revert). Writes add the errors of signing and sending, such as `UserRejectedError`. Each action's reference page lists them with their codes. `Errors.hasCode` narrows an unknown error to the codes you name: **Example** (Handling One Code) ```ts title="has-code.ts" import { Ensforge, Errors, ensActions } from "@ensforge/sdk"; import { createPublicClient, http } from "viem"; import { mainnet } from "viem/chains"; const ens = Ensforge.create({ publicClient: createPublicClient({ chain: mainnet, transport: http() }), }).extend(ensActions()); try { await ens.record.getAddress({ name: "nick.eth", coin: "btc", strict: true }); } catch (error) { if (Errors.hasCode("RECORD_NOT_FOUND", "RESOLVER_NOT_FOUND")(error)) { console.log("Nothing to show for", error.context.name); } else { throw error; } } ``` `Errors.is(value)` tells whether a value is an ensforge error at all. It also works when two copies of the SDK are installed, where `instanceof` would not. ## Missing data is not an error [#missing-data-is-not-an-error] Reads return `null` for data that is not there: a record that is not set, a name without a resolver, an address without a primary name. Pass `strict: true` when you want a `NotFoundError` instead. Invalid input, network and gateway failures are always errors. ## Show users a message, not the error [#show-users-a-message-not-the-error] `error.message` is written for developers. `Errors.describe` turns any error, from ensforge or not, into a title, message and suggested action that are safe to show users. **Example** (Describing an Error for Users) ```ts title="describe.ts" import { Errors } from "@ensforge/sdk"; declare const error: unknown; const { title, message, action, severity } = Errors.describe(error); ``` For the error above, it returns: ```text title="Output" { title: 'No resolver', message: 'no-such-name-ensforge-docs.eth is not set up to hold records yet.', action: 'Set a resolver first.', code: 'RESOLVER_NOT_FOUND', retryable: false, severity: 'info' } ``` - `severity` is `"info"` for expected outcomes (a declined prompt, a taken name), `"warning"` for temporary problems worth retrying, and `"error"` for anything that needs attention. - Pass `messages` to replace the copy for some codes, for example to translate it. - Every code has copy, including the HCA codes. An unknown code gets a generic message; `describe` never throws. See [Handle errors](/docs/sdk/handle-errors). ## Errors in the Effect API [#errors-in-the-effect-api] The Effect API throws the same error instances. Each action's error channel is its `ErrorType`, and the `_tag` is the class name, so `Effect.catchTag("NotFoundError", …)` handles one class. See [The Effect API](/docs/sdk/effect-api). # How a lookup works > For the complete documentation index, see [llms.txt](https://ensforge.com/llms.txt). Learn how ensforge finds a name's resolver, follows wildcard and off-chain lookups through gateways, and batches reads into few requests. Source: https://ensforge.com/docs/sdk/looking-up-a-name A **lookup** (resolution) turns a name into one of its records. It has two parts: find the [resolver](/docs/reference/glossary#resolver) that serves the name, then ask that resolver for the record. ensforge does both in a single call to the **Universal Resolver**, a contract ENS deploys for exactly this. ## The path of one lookup [#the-path-of-one-lookup] When you call `ens.record.getAddress({ name: "nick.eth" })`, the request travels like this: ```mermaid sequenceDiagram participant App as Your app participant SDK as ensforge participant UR as Universal Resolver participant R as Resolver App->>SDK: getAddress("nick.eth") SDK->>SDK: normalise and encode the name SDK->>UR: resolve(name, addr call) UR->>UR: find the resolver UR->>R: addr(...) R-->>UR: address bytes UR-->>SDK: result SDK-->>App: 0xb8c2...67d5 ``` - ensforge [normalises](/docs/reference/glossary#normalisation) the name first. An invalid name fails with [`INVALID_NAME`](/docs/reference/errors/INVALID_NAME) before any request is made. - The Universal Resolver finds the right resolver wherever the name lives, so ensforge never has to ask you where a name is registered. - ensforge decodes the answer: an address for the right chain, a text string, a website link. ## When a name has no resolver of its own [#when-a-name-has-no-resolver-of-its-own] Not every name has its own resolver. A parent name can serve all of its [subnames](/docs/reference/glossary#subname) from one **wildcard resolver** (ENSIP-10), without creating each subname on-chain. To find the resolver, the Universal Resolver walks up the name: `pay.nick.eth`, then `nick.eth`, then `eth`, and uses the first resolver it finds. A resolver found on a parent answers only if it supports wildcard lookups. ```mermaid flowchart LR A["pay.nick.eth: no resolver"] -->|try the parent| B["nick.eth: wildcard resolver"] B -->|answers for pay.nick.eth| C[Records] ``` Basenames resolve this way: `jesse.base.eth` has no resolver of its own and is served by the resolver of `base.eth`. `name.get` reports such a resolver as `inheritedResolver`, because the name has none of its own. **Example** (Seeing an Inherited Resolver) ```ts title="inherited.ts" import { Ensforge, ensActions } from "@ensforge/sdk"; import { createPublicClient, http } from "viem"; import { mainnet } from "viem/chains"; const ens = Ensforge.create({ publicClient: createPublicClient({ chain: mainnet, transport: http() }), }).extend(ensActions()); const state = await ens.name.get({ name: "jesse.base.eth" }); console.log(state.resolver, state.inheritedResolver, state.available); console.log(await ens.record.getAddress({ name: "jesse.base.eth" })); ``` ```text title="Output" null 0xde9049636F4a1dfE0a64d1bFe3155C0A14C54F31 true 0x2211d1D0020DAEA8039E46Cf1367962070d77DA9 ``` `available` is `true` because the name is in no registry on Ethereum, yet it resolves. Check `inheritedResolver` before you tell a user that such a name is free. Writes go to the name's own resolver only, never to an inherited one. ## When records live off-chain [#when-records-live-off-chain] Some resolvers do not store records on Ethereum at all. They answer with a pointer to a **gateway**: a server that holds the records, often with a proof that they are correct. This protocol is called **CCIP-Read** (EIP-3668), and names served this way are **off-chain names**. `jesse.base.eth` is one. ```mermaid sequenceDiagram participant SDK as ensforge participant UR as Universal Resolver participant G as Gateway SDK->>UR: resolve(name) UR-->>SDK: look it up off-chain, at this gateway SDK->>G: request with the lookup data G-->>SDK: records and proof SDK->>UR: here is the gateway's answer UR-->>SDK: verified result ``` ensforge follows these steps for you, so an off-chain name reads exactly like an on-chain one. The Universal Resolver sends off-chain lookups through a **batch gateway**, which collects them and forwards each one to the resolver's own gateway. By default ensforge uses the Universal Resolver's own batch gateway. `ccipRead: { gatewayUrls }` on the client, or `gatewayUrls` on one call, replaces it with batch gateways you choose. `ccipRead: false` turns off-chain lookups off, after which they fail with [`CCIP_READ_DISABLED`](/docs/reference/errors/CCIP_READ_DISABLED). A gateway that fails or answers badly raises a `GatewayError`. See [Look up off-chain names](/docs/sdk/off-chain-names). DNS names such as `example.com` can resolve in a similar way: a DNSSEC proof shows that the DNS owner set the name's ENS data. A proof that does not verify raises a `DnsError`. See [Known limitations](/docs/reference/known-limitations#dns-names). ## Missing data is `null`, unless you ask for errors [#missing-data-is-null-unless-you-ask-for-errors] A lookup that finds nothing is a normal answer. A missing record, a name without a resolver or an address without a primary name returns `null`, so you handle it with an `if`, not a `try`. Pass `strict: true` to get an error instead. The error says why nothing was found: [`RESOLVER_NOT_FOUND`](/docs/reference/errors/RESOLVER_NOT_FOUND) when the name has no resolver, [`RECORD_NOT_FOUND`](/docs/reference/errors/RECORD_NOT_FOUND) when the record is not set. Network, gateway and input errors are thrown either way. ## Many lookups, few requests [#many-lookups-few-requests] ensforge keeps the number of requests low without any work on your side: - `record.get` reads any mix of records for one name in one Universal Resolver call. - Reads made at the same time are grouped into multicall requests (`batch.multicall` on the client, on by default). - `ens.batch` runs many reads, for many names, together. Lookups keep their Universal Resolver call inside the batch, so off-chain names still work. See [Look up many at once](/docs/sdk/look-up-many-at-once). ## What ensforge does for you [#what-ensforge-does-for-you] - Normalises, validates and encodes the name. - Finds the resolver through the Universal Resolver, including wildcard and inherited resolvers. - Follows off-chain lookups through gateways, including DNS names proven with DNSSEC. - Decodes every record type into plain values, and returns `null` for missing data. - Reads at the block you choose, with `blockNumber` or `blockTag`. - Batches concurrent reads. # Name lists and indexers > For the complete documentation index, see [llms.txt](https://ensforge.com/llms.txt). Learn why name lists, search and history come from an indexer instead of the chain, and how ensforge connects to one for you. Source: https://ensforge.com/docs/sdk/name-lists-and-indexers The chain answers questions about one name well: its owner, its resolver, its records. It cannot answer questions about many names at once, such as "which names does this address own?" or "which names start with `vit`?". Those come from an **indexer**: a service that reads every ENS event from the chain and keeps a database you can query. ## What comes from where [#what-comes-from-where] | Question | Answered by | Actions | | ---------------------------------------------------- | ---------------------------------------------------- | -------------------------------------------- | | What is this name's address, owner, expiry, records? | The chain | `record.*`, `name.get`, `primaryName.get`, … | | Which names does this address hold? | An indexer | `indexer.getNamesForAddress` | | What are the subnames of this name? | An indexer | `indexer.getSubnames` | | Which names match this text? | An indexer | `indexer.search` | | What happened to this name over time? | An indexer (full history), the chain (a block range) | `indexer.getHistory`, `event.get` | The chain is the source of truth, and every read action asks it directly. An indexer is fast and can list and search, but it is a copy that can be a few blocks behind. Use the chain for anything a decision depends on, such as whether a name is available or who may change it. ```mermaid flowchart LR C[Ethereum and L2s] -->|events| I[Indexer database] C -->|direct reads| S[ensforge] I -->|lists, search, history| S S -->|answers| A[Your app] ``` ## Connect an indexer [#connect-an-indexer] Indexer actions are a separate group, because they need an indexer service. Pass one as `indexer` when you create the client, and add `indexerActions()`. **Example** (Listing Subnames Through an Indexer) ```ts title="subnames.ts" import { Ensforge } from "@ensforge/sdk"; import { bigname, fallback, goldsky, indexerActions } 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: fallback([bigname(), goldsky()]), }).extend(indexerActions()); const page = await ens.indexer.getSubnames({ name: "ens.eth", limit: 3 }); console.log( page.items.map((subname) => subname.name), page.hasMore, page.indexer, ); ``` ```text title="Output" [ 'app.ens.eth', 'attestations.ens.eth', 'coldwallet.ens.eth' ] true bigname ``` Two indexers are built in, and `fallback` combines them: | Indexer | Serves | Notes | | ---------------------- | ----------------------------- | ----------------------------------------------------------------------------------------------- | | `bigname()` | ENS on mainnet and Sepolia | The indexer the ENS app uses. Supports snapshots and finality, and verified (on-chain) answers. | | `goldsky()` | ENS on mainnet, and Basenames | Latest state only, with fewer fields. | | `fallback([a, b])` | Whatever its indexers serve | Asks the next indexer when one is down, rate limited, behind, or does not serve the query. | | `defineIndexer({...})` | Your own source | Adapts any API to the same actions. See [Custom indexers](/docs/sdk/custom-indexers). | Without an indexer, indexer actions fail with [`INDEXER_NOT_CONFIGURED`](/docs/reference/errors/INDEXER_NOT_CONFIGURED). See [Connect an indexer](/docs/sdk/connect-an-indexer). ## Pages and cursors [#pages-and-cursors] Lists come in pages. Each page has `items`, `hasMore`, and a `cursor` you pass back for the next page. `paginate` from `@ensforge/sdk/indexer` walks every page with `for await`, and stops requesting when you `break`. See [Load more results](/docs/sdk/load-more-results). ## Every answer says how complete it is [#every-answer-says-how-complete-it-is] Indexers differ in what they serve, and can be behind the chain. So every answer carries metadata next to its data: - `indexer`: which indexer answered, such as `"bigname"`. - `completeness`: `"full"`, `"partial"` or `"unsupported"`, with `unsupportedReason` and `unsupportedFields` when it is not full. - `asOf`: the block the answer reflects, with its number and timestamp. - `origin`: whether the answer came from the index or was `"verified"` by an on-chain read. Check `completeness` before you show a list as complete, and `asOf` when freshness matters. Indexers can disagree on some fields, so compare answers from one indexer only. See [Known limitations](/docs/reference/known-limitations#indexers). ## What ensforge does for you [#what-ensforge-does-for-you] - Gives every indexer the same actions and result types, so you can switch or combine them. - Falls back to the next indexer on failure, and sends follow-up pages to the indexer that issued the cursor. - Retries rate-limited and timed-out requests, and reports failures as typed `IndexerError`s. - Uses the indexer during migration to find a name's records and subnames for you. # Names and records > For the complete documentation index, see [llms.txt](https://ensforge.com/llms.txt). Learn what an ENS name is, who can hold it, and which records it can carry, such as addresses, text, avatars and content hashes. Source: https://ensforge.com/docs/sdk/names-and-records ENS, the Ethereum Name Service, maps human-readable names such as `nick.eth` to data: addresses on any chain, a profile, a website. A name is held by an account, like a token. The data a name points to lives in its **records**, which a contract called a **resolver** stores and answers for. ## What a name is made of [#what-a-name-is-made-of] A **name** is a list of **labels** separated by dots. Read from the right, each label is a level. ```mermaid flowchart LR A["pay"] -->|is a subname of| B["nick"] B -->|is a name under| C["eth"] ``` - `eth` is the **top-level domain** (TLD). Most ENS names end in `.eth`, but DNS names such as `example.com` can be imported too. - `nick.eth` is a **`.eth` name**: a second-level name bought from the `.eth` registrar for a period of time. - `pay.nick.eth` is a **subname**. The holder of `nick.eth` creates it, and decides who holds it. Names are case-insensitive and can contain emoji and most scripts. Before a name is used, it is **normalised** (ENSIP-15): `Nick.ETH` becomes `nick.eth`, and names that could be confused with others are rejected. Contracts identify a name by a hash of it called the **namehash**. ensforge normalises and hashes every name you pass, so you work with plain strings. An invalid name fails with [`INVALID_NAME`](/docs/reference/errors/INVALID_NAME). See the [glossary](/docs/reference/glossary#namehash) and the `Name` utilities in the [utilities reference](/docs/reference/sdk/utilities). ## Who holds a name [#who-holds-a-name] ENS keeps track of every name in a **registry**: who holds it, which resolver serves it and, for names that are bought, when it expires. The account that holds a name is its **owner**. The owner can transfer the name, change its resolver, create subnames and edit its records, and can let other accounts do some of these things. A `.eth` name is registered for a period and then renewed. After its **expiry** it enters a **grace period**, during which it can still be renewed but nobody else can register it; after that, anyone can register it again. `name.get` reads all of this in one call: owner, expiry, status and resolver. See [Get a name's owner, expiry and status](/docs/sdk/get-name-details) and [Who can change a name](/docs/sdk/who-can-change-a-name). ## Where records live [#where-records-live] A name does not store its records itself. The registry points the name at a **resolver**, and the resolver stores the records and answers questions about them. ```mermaid flowchart LR N["nick.eth"] -->|registry points to| R[Resolver] R -->|stores| T["Text records: url, avatar, com.github"] R -->|stores| A["Addresses: Ethereum, Bitcoin, Base, ..."] R -->|stores| C["Content hash: website"] ``` Most names use a public resolver that ENS deploys, so any owner can store records there. Some names use a resolver that fetches records from a server, so a name can resolve without anything on Ethereum. Either way, reading looks the same. See [How a lookup works](/docs/sdk/looking-up-a-name). ## Kinds of record [#kinds-of-record] | Record | What it holds | Read it with | | ------------ | ----------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------- | | Address | An address for one chain or coin, chosen by its **coin type** (ENSIP-9, ENSIP-11). Ethereum is the default. | [`record.getAddress`](/docs/reference/sdk/record/get-address) | | Text | A string under a key: `url`, `avatar`, `description`, `com.twitter`, `com.github`, or any key you choose (ENSIP-5). | [`record.getText`](/docs/reference/sdk/record/get-text) | | Avatar | A text record with an image link: HTTPS, IPFS, Arweave or an NFT (ENSIP-12). ensforge turns it into a URL a browser can load. | [`record.getAvatar`](/docs/reference/sdk/record/get-avatar) | | Content hash | A website or file on IPFS, IPNS, Swarm, Arweave and similar (ENSIP-7). | [`record.getContentHash`](/docs/reference/sdk/record/get-content-hash) | | ABI | A contract ABI (ENSIP-4). | [`record.get`](/docs/reference/sdk/record/get) | | Public key | A SECP256k1 public key. | [`record.get`](/docs/reference/sdk/record/get) | | Name | The name an address is known by, used for primary names (ENSIP-3). | [`record.get`](/docs/reference/sdk/record/get) | | Interface | The contract implementing an ERC-165 interface for the name. | [`record.get`](/docs/reference/sdk/record/get) | | Data | Raw bytes under a key (ENSIP-24). | [`record.get`](/docs/reference/sdk/record/get) | `record.get` reads any mix of these in one request. Its result has exactly the fields you asked for, and a record that is not set is `null`. **Example** (Reading Several Records at Once) ```ts title="records.ts" import { Ensforge, ensActions } from "@ensforge/sdk"; import { createPublicClient, http } from "viem"; import { mainnet } from "viem/chains"; const ens = Ensforge.create({ publicClient: createPublicClient({ chain: mainnet, transport: http() }), }).extend(ensActions()); const profile = await ens.record.get({ name: "nick.eth", texts: ["url", "com.github"], addresses: ["eth", "btc"], }); console.log(profile); ``` ```text title="Output" { resolver: '0xF4f1007EA430848F2fAd60e405A54Fc100fEc341', texts: { url: 'https://ens.domains/', 'com.github': 'arachnid' }, addresses: { eth: '0xb8c2C29ee19D8307cb7255e1Cd9CbDE883A267d5', btc: null } } ``` `btc` is `null` because `nick.eth` has no Bitcoin address. `resolver` is the contract that answered. See [Get text records](/docs/sdk/get-text-records). ## From an address back to a name [#from-an-address-back-to-a-name] Records go from a name to data. A **primary name** goes the other way: from an address to the one name its owner chose to be known by (ENSIP-19). Wallets and apps show it instead of a `0x` address. Anyone can claim any name in their own reverse record, so a primary name only counts when the name also points back to the same address. `primaryName.get` checks this for you, and returns `null` when the check fails. An address can have a different primary name on each chain. See [Get the name for an address](/docs/sdk/get-a-primary-name). ## What ensforge does for you [#what-ensforge-does-for-you] - Normalises and hashes every name, and rejects invalid ones with a typed error. - Finds the resolver of any name and reads every record you ask for in one request. - Encodes and decodes addresses for each coin, content hashes and ABIs, so you pass and receive plain strings and objects. - Turns avatars into loadable URLs, including NFT avatars and IPFS links. - Verifies primary names before returning them. # Who can change a name > For the complete documentation index, see [llms.txt](https://ensforge.com/llms.txt). Learn how owners, approved accounts, managers and roles decide who may change a name, and how ensforge answers it in one call. Source: https://ensforge.com/docs/sdk/who-can-change-a-name Every change to a name, from editing a record to creating a subname, is checked by a contract against the account that sends it. The **owner** can do almost everything. Other accounts can be allowed to do some things ([permissions](/docs/reference/glossary#permission)). ensforge reads all of these rules and answers one question for you: what may this account do with this name? ## The owner [#the-owner] The **owner** is the account that holds the name. It can transfer the name, point it at a resolver, create and remove subnames, and edit its records. Renewing a `.eth` name is open to anyone, because paying for more time never hurts the owner. `name.get` returns the owner. See [Get a name's owner, expiry and status](/docs/sdk/get-name-details). ## Accounts the owner allows [#accounts-the-owner-allows] An owner can let other accounts act without giving the name away. ENS has a few ways to do this, each with a different reach: | Allowed account | Can do | Set with | | -------------------- | ------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------- | | **Operator** | Everything the owner can do, for every name the owner holds on that contract. | [`approval.setOperator`](/docs/reference/sdk/approval/set-operator) | | **Approved address** | Transfer one name token. | [`approval.setToken`](/docs/reference/sdk/approval/set-token) | | **Delegate** | Edit the records of one name on a public [resolver](/docs/reference/glossary#resolver). | [`approval.setDelegate`](/docs/reference/sdk/approval/set-delegate) | | **Role holder** | Exactly the actions its roles name, such as `setResolver` or `setText`, on one name or on every name of a contract. | [`role.grant`](/docs/reference/sdk/role/grant) | To let someone edit a name's records, whatever kind of resolver it has, use [`permission.setRecordAccess`](/docs/reference/sdk/permission/set-record-access): it picks the right mechanism. ## Owner, manager and registrant [#owner-manager-and-registrant] Names still on [ENSv1](/docs/reference/glossary#ensv1), the original ENS contracts, can split control in two. The **registrant** holds the `.eth` registration, and the **manager** controls the name in the registry: its resolver, records and subnames. The registrant can always take management back. ```mermaid flowchart TD R[Registrant] -->|holds the registration, can reclaim| N["ensforge-docs-demo.eth"] M[Manager] -->|sets resolver, records, subnames| N ``` Most names have the same account in both places, and `name.transfer` moves both by default. When they differ, `name.get` reports both, and `owner` is the account with final control. Names wrapped in the [Name Wrapper](/docs/reference/glossary#name-wrapper) add **fuses**, permanent switches that remove permissions. See [What wrapped names are](/docs/sdk/wrapped-names). ## Roles [#roles] Names on [ENSv2](/docs/reference/glossary#ensv2) replace the split above with **roles**: named permissions that an owner grants to other accounts, one by one. A role can apply to one name, or to every name of a registry or resolver. Each role has an admin role that may grant and revoke it. ```mermaid flowchart LR O[Owner] -->|grants setText, setAddr| E[Editor account] O -->|grants setResolver| T[Team multisig] E -->|can edit records only| N["ensforge-docs-demo.eth"] T -->|can change the resolver| N ``` Roles let a team share a name without sharing a key. See [Roles and permissions](/docs/sdk/roles-and-permissions). ## One question, one answer [#one-question-one-answer] The rules above differ by name, but you never have to work them out. `permission.get` reads every source of permission that applies to a name and returns the same shape for any name. **Example** (Reading What an Account May Do) ```ts title="permissions.ts" import { Ensforge, ensActions } from "@ensforge/sdk"; import { createPublicClient, http } from "viem"; import { mainnet } from "viem/chains"; const ens = Ensforge.create({ publicClient: createPublicClient({ chain: mainnet, transport: http() }), }).extend(ensActions()); const { can } = await ens.permission.get({ name: "nick.eth", account: "0xb8c2C29ee19D8307cb7255e1Cd9CbDE883A267d5", }); console.log(can); ``` ```text title="Output" { transfer: true, setResolver: true, setSubregistry: true, createSubname: true, removeSubname: true, renew: true, setTtl: false, setManager: false, reclaim: false, setRecords: true } ``` - Each answer is `true`, `false`, or `null` when the rules are unknown, as with a custom resolver. - `setTtl`, `setManager` and `reclaim` are `false` here because they only exist for names with a manager, and `nick.eth` has moved to ENSv2, which has none. - Use it to show or hide buttons before the user tries anything. `permission.check` answers for one operation and lists exactly what is missing, such as the roles to request. See [`permission.check`](/docs/reference/sdk/permission/check). ## What ensforge does for you [#what-ensforge-does-for-you] - Reads ownership, approvals, roles and fuses for any name, and combines them into one answer. - Checks permission before planning a write, so a write the account may not make fails with [`NOT_OWNER`](/docs/reference/errors/NOT_OWNER) or [`MISSING_ROLES`](/docs/reference/errors/MISSING_ROLES) before the wallet prompt, naming what is missing. - Picks the right contract and mechanism when you grant access or transfer a name. # How writes work > For the complete documentation index, see [llms.txt](https://ensforge.com/llms.txt). Learn how ensforge turns every write into a plan that it checks, simulates, sends in steps and can resume after a failure. Source: https://ensforge.com/docs/sdk/writing-to-ens A **write** changes ENS: it sets [records](/docs/reference/glossary#record), registers or transfers a name, creates a subname. Writes are transactions signed by a wallet. Many ENS tasks need more than one transaction, sometimes with a wait in between, so ensforge first turns every write into a **plan**: a list of steps, each with the contract calls it makes. Then it checks the plan, sends it, and saves its progress. ## The life of a write [#the-life-of-a-write] Every write goes through the same stages. You can stop after any of the first three to show the user what will happen. ```mermaid flowchart LR P[Prepare] -->|plan| S[Simulate] S -->|no errors| W[Wallet prompt] W -->|signed| T[Submitted] T -->|mined| C[Confirmed] S -->|would fail| E[Typed error, nothing sent] ``` 1. **Prepare.** ensforge reads the current state of the name, checks that the account is allowed to make the change, and builds the plan. Wrong input or a missing permission fails here, with a typed error such as [`NOT_OWNER`](/docs/reference/errors/NOT_OWNER). 2. **Simulate.** Every call is run against the current chain state without sending it, so a call that would revert becomes a typed error before the wallet asks the user to sign. 3. **Send.** The wallet signs and submits each step in order. 4. **Confirm.** The `…Sync` form waits for the receipts. ensforge never sends a transaction during prepare or simulate. Simulation is on by default; set `simulate: false` on the client or on one write to skip it. ## Methods for each stage [#methods-for-each-stage] Each write action carries methods for each stage. | Call | Returns | Sends? | | ------------------------------------- | --------------------------------------------------------- | ------ | | `ens.record.set.prepare(options)` | `Plan` | No | | `ens.record.set.simulate(options)` | `Plan.Simulation`: `ok`, and each step's error | No | | `ens.record.set.estimateGas(options)` | `Plan.Estimate`: total `gas` and ETH `value` | No | | `ens.record.set(options)` | `{ hash, hashes, id, plan }` once every step is submitted | Yes | | `ens.record.setSync(options)` | The same, plus `receipt` and `receipts` once mined | Yes | **Example** (Reviewing a Plan Before Sending) ```ts title="review.ts" import { Ensforge, ensActions } from "@ensforge/sdk"; import { createPublicClient, createWalletClient, custom, http, type EIP1193Provider } from "viem"; import { sepolia } from "viem/chains"; declare const provider: EIP1193Provider; const ens = Ensforge.create({ publicClient: createPublicClient({ chain: sepolia, transport: http() }), walletClient: createWalletClient({ chain: sepolia, transport: custom(provider) }), }).extend(ensActions()); const options = { name: "ensforge-docs-demo.eth", texts: { url: "https://example.com" } }; const plan = await ens.record.set.prepare(options); const { gas } = await ens.record.set.estimateGas(options); console.log( plan.steps.map((step) => step.description), plan.warnings, gas, ); ``` - `plan.steps` lists what will happen, in words a UI can show (`"Set records"`). - `plan.warnings` holds notes that do not block the write, and `plan.requirements` what the account needs first, such as a token balance. - A plan is plain data: you can save it, or send its `calls` with any tool. See [Preview before sending](/docs/sdk/preview-before-sending). Every write can also fail with [`INSUFFICIENT_ETH`](/docs/reference/errors/INSUFFICIENT_ETH) when the account cannot pay for a step, and every action with [`CONTRACT_NOT_DEPLOYED`](/docs/reference/errors/CONTRACT_NOT_DEPLOYED) when the chain has no ENS contract where the action calls. ## Steps, waits and bundles [#steps-waits-and-bundles] Most writes are one [step](/docs/reference/glossary#step) with one call. Some are longer. Registering a `.eth` name commits first, waits at least a minute of chain time, then registers. When you ask for them, later steps write records to a resolver you chose and set the primary name. The plan holds each wait, so ensforge sends the next step only when the chain allows it. ```mermaid flowchart LR A["Step 1: approve payment and commit"] -->|wait about a minute| B["Step 2: register"] B -->|if asked| C["Later steps: records and primary name"] ``` How the steps reach the wallet depends on the wallet, set with `mode`: - `"auto"` (default) sends consecutive steps as one [bundle](/docs/reference/glossary#bundle) when the wallet supports atomic batches (EIP-5792), and one transaction per call otherwise. - `"batch"` always uses one EIP-5792 call per bundle. `"sequential"` sends one transaction at a time, each after the previous one is mined. - A bundle holds at most `maxBundleCalls` calls (default 10) and never spans a wait. `onStep` reports each step as it is `waiting`, `submitted`, `confirmed` or `failed`, for progress UIs. See [Send a transaction](/docs/sdk/send-a-transaction) and [Bundle transactions](/docs/sdk/bundle-transactions). ## When something fails halfway [#when-something-fails-halfway] A user can reject the second signature, close the tab during a wait, or lose their connection. The plan's progress is saved in the client's `storage` as each step is submitted, so the write does not start over. - The error of a failed write carries `context.planId`. - `ens.plan.resume({ id })` continues from the first step not yet submitted. Steps already sent are confirmed, not sent again, and each remaining step is simulated again right before it is sent. - The default storage is in memory. Pass `storage: Plan.localStorage()` when creating the client to survive a page reload. See [Continue after a failure](/docs/sdk/continue-after-a-failure). ## Combine and route plans [#combine-and-route-plans] Plans are data, so they compose: - `Plan.merge([a, b])` joins plans from several writes, and `ens.plan.send({ plan })` sends them as one flow. - `via` sends a write another way than the signer's own transactions, for example through a smart account with `hca()` from `@ensforge/hca`. - `paymaster` asks an EIP-5792 wallet to have the gas sponsored. See [Use smart accounts](/docs/sdk/use-smart-accounts) and [Pay gas for users](/docs/sdk/pay-gas-for-users). ## What ensforge does for you [#what-ensforge-does-for-you] - Picks the right contracts for the name, wherever it lives. - Checks permissions and name state before planning, so failures come with a precise code. - Simulates every call before the wallet prompt. - Splits work into steps, waits on chain time where ENS requires it, and bundles calls for wallets that can take them. - Saves progress and resumes after a failure. # Connect an indexer > For the complete documentation index, see [llms.txt](https://ensforge.com/llms.txt). Add an indexer to your ensforge client so you can list names, search them and read history, and learn how to read its freshness metadata. Source: https://ensforge.com/docs/sdk/connect-an-indexer By the end of this guide your client can answer questions the chain cannot answer on its own, such as "which names does this address own?", by asking an **indexer**: a service that reads every ENS event as it happens and keeps the results in a searchable database. ## Prerequisites [#prerequisites] - A viem public client for Ethereum mainnet or Sepolia. See [Create a client](/docs/sdk/create-a-client). ## 1. Add an indexer to the client [#1-add-an-indexer-to-the-client] Pass an indexer to `Ensforge.create`, then add the `indexerActions()` group. `bigname()` is the built-in indexer for ENS on mainnet and Sepolia. **Example** (Creating a Client with bigname) ```ts title="indexer-client.ts" import { ensActions, Ensforge } from "@ensforge/sdk"; import { bigname, indexerActions } 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: bigname(), }) .extend(ensActions()) .extend(indexerActions()); const page = await ens.indexer.search({ query: "vitalik" }); ``` - `indexer: bigname()` tells the client where to send list queries. The client's chain picks the host: `https://api.bigname.sh` for mainnet and `https://sepolia.api.bigname.sh` for Sepolia. - `indexerActions()` adds the `ens.indexer.*` actions. `ensActions()` does not include them, because they need an indexer. - On-chain actions such as `record.getAddress` do not use the indexer. See [Name lists and indexers](/docs/sdk/name-lists-and-indexers) and [`bigname`](/docs/reference/sdk/indexers). ## 2. Check the connection [#2-check-the-connection] `indexer.getStatus` reads the indexer's health and how far each chain is indexed. **Example** (Reading the Indexer Status) ```ts title="indexer-status.ts" import { ensActions, Ensforge } from "@ensforge/sdk"; import { bigname, indexerActions } 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: bigname(), }) .extend(ensActions()) .extend(indexerActions()); const status = await ens.indexer.getStatus(); console.log(status.status, status.indexer); for (const [chainId, chain] of Object.entries(status.chains)) { console.log(chainId, chain.status, chain.lagBlocks); } ``` `status` is `"ready"`, `"degraded"` or `"stale"`. Each chain reports the block it has `indexed`, the `latest` block, and `lagBlocks` and `lagSeconds`. See [`indexer.getStatus`](/docs/reference/sdk/indexer/get-status). ## 3. Read answers with care [#3-read-answers-with-care] Every indexer answer carries metadata besides its data: | Field | Description | | ------------------- | ------------------------------------------------------------------------------------------ | | `asOf` | The chain snapshot (block and time) the answer was read at. | | `completeness` | `"full"`, `"partial"` or `"unsupported"`. A partial answer is never presented as complete. | | `unsupportedReason` | Why the answer is partial or unsupported. | | `origin` | `"indexed"` when answered from the index, `"verified"` when read on-chain. | | `indexer` | The id of the indexer that answered, such as `bigname`. | An indexer is fast but can lag the chain by a few blocks. For an authoritative answer about one name, read the chain with [`name.get`](/docs/reference/sdk/name/get). ## Use Basenames and Goldsky [#use-basenames-and-goldsky] `goldsky()` serves ENS and Basenames (`*.base.eth`) on mainnet. It reads only the latest state. It has fewer fields than bigname: no verified records, and subnames without expiry. Missing fields are `null`. **Example** (Reading a Basename) ```ts title="goldsky-client.ts" import { ensActions, Ensforge } from "@ensforge/sdk"; import { goldsky, indexerActions } 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(), }) .extend(ensActions()) .extend(indexerActions()); const name = await ens.indexer.getName({ name: "jesse.base.eth" }); ``` ## Use more than one indexer [#use-more-than-one-indexer] `fallback` asks indexers in order. Each query goes to the first one that can answer it. The next one is asked when an indexer is unavailable, rate limiting, behind, or does not serve the query or namespace. A name that is not found is an answer, so it is not retried. **Example** (bigname First, Goldsky After) ```ts title="fallback-client.ts" import { ensActions, Ensforge } from "@ensforge/sdk"; import { bigname, fallback, goldsky, indexerActions } 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: fallback([bigname(), goldsky()]), }) .extend(ensActions()) .extend(indexerActions()); ``` - Every answer reports which indexer gave it, in `indexer`. - A cursor or snapshot token goes back to the indexer that issued it, so paging never switches indexer halfway. - `fallback([...], { on: ["unavailable", "rateLimited"] })` limits when the next indexer is asked. The reasons are `"unavailable"`, `"rateLimited"`, `"unsupported"` and `"behind"`. ## Point at your own server [#point-at-your-own-server] Both built-in indexers take the same connection options, for a self-hosted server, a proxy or an API key. **Example** (A Self-Hosted bigname with a Header) ```ts title="self-hosted.ts" import { bigname } from "@ensforge/sdk/indexer"; const authorization = "Bearer "; const indexer = bigname({ url: "https://bigname.internal", headers: { authorization }, timeout: 10_000, retryCount: 1, cache: true, }); ``` | Option | Type | Default | Description | | ------------ | ------------------------ | -------------------------------------- | ------------------------------------------------------------------------------------------- | | `url` | `string` | the public host for the client's chain | Base URL of a server with the same API. A `/v1` path is added unless the URL ends with one. | | `headers` | `Record` | none | Extra request headers, such as an API key. | | `fetch` | `typeof fetch` | `globalThis.fetch` | The `fetch` to send requests with. | | `timeout` | `number` | `15000` | Milliseconds per request before it is retried or fails. | | `retryCount` | `number` | `2` | Retries of rate-limited, unavailable and timed-out requests. `Retry-After` is honoured. | | `cache` | `boolean` | `false` | `bigname` only. Revalidates repeated reads with ETags. | To adapt another data source, see [Custom indexers](/docs/sdk/custom-indexers). ## Troubleshooting [#troubleshooting] ### `INDEXER_NOT_CONFIGURED` [#indexer_not_configured] The client has no indexer. Pass `indexer` to `Ensforge.create`. See [`INDEXER_NOT_CONFIGURED`](/docs/reference/errors/INDEXER_NOT_CONFIGURED). ### `Property 'indexer' does not exist` in TypeScript [#property-indexer-does-not-exist-in-typescript] You did not add `indexerActions()` with `.extend(...)`. `ensActions()` does not include the indexer actions. ### `INDEXER_UNSUPPORTED` [#indexer_unsupported] The indexer does not serve the query or its namespace. Examples: the client's chain has no public host (pass `url`), the namespace is not indexed (bigname does not serve Basenames at the time of writing), or Goldsky was asked for a snapshot (`at`) or a `safe` or `finalized` read. Combine indexers with `fallback`. See [`INDEXER_UNSUPPORTED`](/docs/reference/errors/INDEXER_UNSUPPORTED). ### `INDEXER_UNAVAILABLE` or `INDEXER_RATE_LIMITED` [#indexer_unavailable-or-indexer_rate_limited] The indexer is down or limiting you. Both are marked retryable. ensforge already retries `retryCount` times, so add a second indexer with `fallback`. See [`INDEXER_UNAVAILABLE`](/docs/reference/errors/INDEXER_UNAVAILABLE) and [`INDEXER_RATE_LIMITED`](/docs/reference/errors/INDEXER_RATE_LIMITED). ### `INDEXER_BEHIND` [#indexer_behind] The indexer is behind the chain. Retry shortly, or read on-chain instead. See [`INDEXER_BEHIND`](/docs/reference/errors/INDEXER_BEHIND). # List names for an address > For the complete documentation index, see [llms.txt](https://ensforge.com/llms.txt). List the names an address owns, manages, holds roles on, resolves to or used to own, with filters, sorting and pagination. Source: https://ensforge.com/docs/sdk/list-names-for-an-address By the end of this guide you can show an account's names, for a "my names" page or a name picker. ## Prerequisites [#prerequisites] - A client with an [indexer](/docs/reference/glossary#indexer) and `indexerActions()`. See [Connect an indexer](/docs/sdk/connect-an-indexer). The chain cannot list the names of an address, so this needs an indexer. ## List the names an address is related to [#list-the-names-an-address-is-related-to] `indexer.getNamesForAddress` returns one page of names. By default it lists every name the address owns, manages or holds a role on. **Example** (Listing an Account's Names) ```ts title="list-names.ts" import { ensActions, Ensforge } from "@ensforge/sdk"; import { bigname, indexerActions } 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: bigname(), }) .extend(ensActions()) .extend(indexerActions()); const page = await ens.indexer.getNamesForAddress({ address: "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045", }); for (const item of page.items) { console.log(item.name, item.relations, item.isPrimary); } ``` - `page.items` holds up to `limit` names. The default is 50 and the most is 200. - Each item is a name with `relations`, the ways the address relates to it, and `isPrimary`, whether it is the address's primary name. - `page.hasMore` and `page.cursor` tell you whether there is another page. See [Load more results](/docs/sdk/load-more-results). The address can be all lowercase or checksummed. Without `namespace`, the list covers every namespace the indexer serves. See [`indexer.getNamesForAddress`](/docs/reference/sdk/indexer/get-names-for-address). ## Choose how the address is related [#choose-how-the-address-is-related] `relation` is one value or a list of these: | Relation | The address… | | --------------- | ------------------------------------------------------- | | `"owner"` | owns the name. | | `"manager"` | manages the name. | | `"roleHolder"` | holds a role on the name. | | `"resolvesTo"` | is the address the name points to. Pair it with `coin`. | | `"formerOwner"` | used to own the name. | `"any"`, the default, means owner, manager and role holder. `"resolvesTo"` and `"formerOwner"` are listed on their own, never inside `"any"`. **Example** (Listing Names that Point at an Address) ```ts title="list-resolves-to.ts" import { ensActions, Ensforge } from "@ensforge/sdk"; import { bigname, indexerActions } 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: bigname(), }) .extend(ensActions()) .extend(indexerActions()); const address = "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045"; const pointing = await ens.indexer.getNamesForAddress({ address, relation: "resolvesTo" }); const owned = await ens.indexer.getNamesForAddress({ address, relation: "owner", sort: "expiry", order: "asc", limit: 20, }); ``` See [Who can change a name](/docs/sdk/who-can-change-a-name) for what owner, manager and role holder mean. ## Filter, search and sort [#filter-search-and-sort] | Option | Type | Default | Description | | ------------------------------- | --------------------------------------------------- | ---------------------------------- | -------------------------------------------------------------------------- | | `address` | `string` | required | The address to list names for. | | `namespace` | `"ens"` or `"basenames"` | every namespace the indexer serves | Limits the list to one naming system. | | `relation` | relation, list of relations, or `"any"` | `"any"` | Which relations to list. | | `coin` | symbol, `{ chainId }`, `bigint` or `"evm"` | `60` | Coin type for `relation: "resolvesTo"`. `"evm"` means every EVM chain. | | `parent` | `string` | none | Only direct children of this name. | | `authority` | `"ensV0"`, `"ensV1"`, `"ensV2"`, or a list | none | Only names held by that protocol. | | `migrated` | `boolean` | none | Only names that moved to ENSv2, or only those that did not. | | `search` | `string` | none | Only names that match this text. | | `match` | `"prefix"` or `"contains"` | `"prefix"` | How `search` matches. | | `sort` | `"name"`, `"expiry"`, `"registered"` or `"created"` | the indexer's default | What to sort by. bigname sorts by name, and `formerOwner` lists by expiry. | | `order` | `"asc"` or `"desc"` | the indexer's default | Sort direction. bigname sorts ascending. | | `dedupe` | `"name"` or `"registration"` | `"name"` | One row per name, or per registration. | | `expiresAfter`, `expiresBefore` | `bigint` or `Date` | none | Expiry bounds. Only with `relation: "formerOwner"`. | | `limit` | `number` | `50` | Names per page, 1 to 200. | | `cursor` | `string` | none | The previous page's `cursor`. | | `includeTotal` | `boolean` | `false` | Count every row into `totalCount`. Slower. | | `signal` | `AbortSignal` | none | Cancels the call. | ## Read the result [#read-the-result] Each item in `page.items` has: | Field | Description | | ----------------------------- | ------------------------------------------------------------------------------ | | `name` | The normalised name. Unknown labels appear as `[labelhash]`. | | `relations` | How the address relates to the name. | | `isPrimary` | Whether it is the address's primary name. | | `owner`, `manager` | Who holds the name. | | `status` | `"active"`, `"expired"`, `"released"` or `"unregistered"`, or `null`. | | `expiresAt`, `graceEndsAt` | Unix seconds as `bigint`, or `null`. A name that never expires has `2^64 - 1`. | | `recordCount`, `subnameCount` | How many records and subnames the name has, when reported. | The page also carries the indexer metadata (`asOf`, `completeness`, `indexer`) described in [Connect an indexer](/docs/sdk/connect-an-indexer#3-read-answers-with-care). ## Troubleshooting [#troubleshooting] ### `INDEXER_NOT_CONFIGURED` [#indexer_not_configured] The client has no indexer, or you forgot `indexerActions()`. See [Connect an indexer](/docs/sdk/connect-an-indexer) and [`INDEXER_NOT_CONFIGURED`](/docs/reference/errors/INDEXER_NOT_CONFIGURED). ### `INVALID_ADDRESS` [#invalid_address] The `address` is not a valid address. [`INVALID_ADDRESS`](/docs/reference/errors/INVALID_ADDRESS) is thrown before any request is sent. `INVALID_COIN_TYPE` and `INVALID_NAME` are thrown the same way for a bad `coin` or `parent`. ### The list is missing a name you registered recently [#the-list-is-missing-a-name-you-registered-recently] The indexer can lag the chain by a few blocks. Read `ens.indexer.getStatus()` to see how far it has indexed, or read the name on-chain with [`name.get`](/docs/reference/sdk/name/get). ### `INDEXER_UNSUPPORTED` [#indexer_unsupported] The indexer does not serve the query or the namespace. See [`INDEXER_UNSUPPORTED`](/docs/reference/errors/INDEXER_UNSUPPORTED). # Load more results > For the complete documentation index, see [llms.txt](https://ensforge.com/llms.txt). Walk through every page of a name list with a cursor, or let the paginate helper fetch all pages, for infinite scroll and exports. Source: https://ensforge.com/docs/sdk/load-more-results By the end of this guide you can load a long list one page at a time, or walk every page in a loop. ## Prerequisites [#prerequisites] - A client with an [indexer](/docs/reference/glossary#indexer) and `indexerActions()`. See [Connect an indexer](/docs/sdk/connect-an-indexer). ## How pages work [#how-pages-work] Every indexer list (names for an address, search, subnames, history) returns a page: | Field | Description | | ------------ | ------------------------------------------------------------------------------------------------------- | | `items` | The rows of this page. | | `hasMore` | Whether there is another page. | | `cursor` | Pass it as `cursor` to get the next page. `null` on the last page. | | `totalCount` | The total across pages, when you pass `includeTotal: true` and the indexer can count. Otherwise `null`. | `limit` sets the page size: 1 to 200, 50 by default. ## Load the next page on demand [#load-the-next-page-on-demand] Keep the `cursor` and pass it back. This fits a "Load more" button. **Example** (Loading Pages with a Cursor) ```ts title="load-more.ts" import { ensActions, Ensforge } from "@ensforge/sdk"; import { bigname, indexerActions } 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: bigname(), }) .extend(ensActions()) .extend(indexerActions()); const address = "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045"; const first = await ens.indexer.getNamesForAddress({ address, limit: 20 }); if (first.hasMore && first.cursor !== null) { const second = await ens.indexer.getNamesForAddress({ address, limit: 20, cursor: first.cursor, }); console.log(second.items.length); } ``` Send the same options with each request and change only `cursor`. A cursor belongs to the query that produced it. When you use `fallback`, it also belongs to the indexer that issued it, so the next page always comes from that indexer. ## Walk every page [#walk-every-page] `paginate` follows the cursor for you. It is an async generator that yields one page at a time. `break` stops it from requesting more. **Example** (Collecting at Most 1,000 Names) ```ts title="paginate.ts" import { ensActions, Ensforge } from "@ensforge/sdk"; import { bigname, indexerActions, paginate } 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: bigname(), }) .extend(ensActions()) .extend(indexerActions()); const names: string[] = []; for await (const page of paginate(ens.indexer.getNamesForAddress, { address: "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045", limit: 200, })) { names.push(...page.items.map((item) => item.name)); if (names.length >= 1000) break; } ``` - The first argument is the action that loads a page. The second is its options. - Pages load one at a time, because each depends on the previous cursor. - A larger `limit` means fewer requests. `paginate` works with any list action, such as `indexer.getSubnames`. With a standalone action, wrap it so it takes the options: `paginate((options) => Actions.indexer.getSubnames(ens, options), { name: "ens.eth" })`. For the Effect form, see [The Effect API](/docs/sdk/effect-api). ## Show a total [#show-a-total] Pass `includeTotal: true` to fill `totalCount` on the first request. It makes the request slower, so ask for it once and keep the number. **Example** (Counting Names) ```ts title="total-count.ts" import { ensActions, Ensforge } from "@ensforge/sdk"; import { bigname, indexerActions } 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: bigname(), }) .extend(ensActions()) .extend(indexerActions()); const page = await ens.indexer.getNamesForAddress({ address: "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045", includeTotal: true, limit: 1, }); console.log(page.totalCount); ``` ## Options [#options] | Option | Type | Default | Description | | -------------- | --------- | ------- | ------------------------------------------ | | `limit` | `number` | `50` | Rows per page, 1 to 200. | | `cursor` | `string` | none | The previous page's `cursor`. | | `includeTotal` | `boolean` | `false` | Count every row into `totalCount`. Slower. | See [`indexer.getNamesForAddress`](/docs/reference/sdk/indexer/get-names-for-address), [`indexer.search`](/docs/reference/sdk/indexer/search) and [`indexer.getSubnames`](/docs/reference/sdk/indexer/get-subnames). ## Troubleshooting [#troubleshooting] ### `totalCount` is `null` [#totalcount-is-null] You did not pass `includeTotal: true`, or the indexer cannot count. The page still works without it. ### The next page fails or repeats [#the-next-page-fails-or-repeats] Check that you send the same options and only change `cursor`. A cursor from one query is not valid for another. ### `INDEXER_UNSUPPORTED` with a cursor under `fallback` [#indexer_unsupported-with-a-cursor-under-fallback] The cursor was issued by an indexer that cannot serve this method. [`INDEXER_UNSUPPORTED`](/docs/reference/errors/INDEXER_UNSUPPORTED) is thrown instead of asking another indexer, because it could not read the cursor. Start the list again. ### `INDEXER_RATE_LIMITED` while walking many pages [#indexer_rate_limited-while-walking-many-pages] Raise `limit` to 200 to use fewer requests, or add a second indexer. See [Connect an indexer](/docs/sdk/connect-an-indexer#use-more-than-one-indexer) and [`INDEXER_RATE_LIMITED`](/docs/reference/errors/INDEXER_RATE_LIMITED). # Name history > For the complete documentation index, see [llms.txt](https://ensforge.com/llms.txt). Read everything that happened to a name or an account, from its first event to the latest, as a list of ownership and record events. Source: https://ensforge.com/docs/sdk/name-history By the end of this guide you can show an activity feed for a name or an account: registrations, renewals, transfers, resolver and record changes. ## Prerequisites [#prerequisites] - For full history, a client with an [indexer](/docs/reference/glossary#indexer) and `indexerActions()`. See [Connect an indexer](/docs/sdk/connect-an-indexer). - For recent events only, a plain client is enough. See [Read recent events from the chain](#read-recent-events-from-the-chain). ## Read the full history of a name [#read-the-full-history-of-a-name] `indexer.getHistory` returns one page of events, newest first. **Example** (Reading a Name's History) ```ts title="name-history.ts" import { ensActions, Ensforge } from "@ensforge/sdk"; import { bigname, indexerActions } 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: bigname(), }) .extend(ensActions()) .extend(indexerActions()); const page = await ens.indexer.getHistory({ name: "nick.eth", limit: 25 }); for (const event of page.items) { console.log(event.type, event.action, event.timestamp, event.transactionHash); } ``` - Events carry the same `type` and `action` vocabulary as the on-chain `event.get`. - `order: "asc"` returns the oldest first. - Each event includes its details in `data`, unless you pass `includeData: false`. - `scope` picks the name's own events, its registrations' events, or `"both"` (the default). See [`indexer.getHistory`](/docs/reference/sdk/indexer/get-history) and [Load more results](/docs/sdk/load-more-results). ## Filter the history [#filter-the-history] **Example** (Reading Transfers and Avatar Changes) ```ts title="history-filters.ts" import { ensActions, Ensforge } from "@ensforge/sdk"; import { bigname, indexerActions } 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: bigname(), }) .extend(ensActions()) .extend(indexerActions()); const transfers = await ens.indexer.getHistory({ name: "nick.eth", types: ["transfer"] }); const avatarChanges = await ens.indexer.getHistory({ name: "nick.eth", recordKey: "avatar", order: "asc", }); ``` ## Read the history of an account [#read-the-history-of-an-account] Pass an `address` instead of a `name` to read the events of every name the address is related to. By default `relation` follows owner, manager and role holder. **Example** (Reading an Account's Activity) ```ts title="account-history.ts" import { ensActions, Ensforge } from "@ensforge/sdk"; import { bigname, indexerActions } 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: bigname(), }) .extend(ensActions()) .extend(indexerActions()); const page = await ens.indexer.getHistory({ address: "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045", types: ["registration", "renewal", "transfer"], }); ``` ## Read recent events from the chain [#read-recent-events-from-the-chain] `event.get` reads a name's events straight from the chain over a block range. It needs no indexer, and shows the same kinds of events. Use it for recent activity, or to see the effect of a write. **Example** (Reading Recent Events) ```ts title="recent-events.ts" import { ensActions, Ensforge } from "@ensforge/sdk"; import { createPublicClient, http } from "viem"; import { mainnet } from "viem/chains"; const publicClient = createPublicClient({ chain: mainnet, transport: http() }); const ens = Ensforge.create({ publicClient }).extend(ensActions()); const head = await publicClient.getBlockNumber(); const events = await ens.event.get({ name: "nick.eth", fromBlock: head - 50_000n }); for (const event of events) { console.log(event.type, event.action, event.blockNumber); } ``` - `fromBlock` is required. `toBlock` defaults to `"latest"`. - Events come back in chain order. - Ranges the RPC provider rejects are split. After `maxRequests` `eth_getLogs` requests (default 500), the read fails with [`LOG_RANGE_TOO_LARGE`](/docs/reference/errors/LOG_RANGE_TOO_LARGE) instead of sending more. - `event.get` covers one name. Address-wide and full history needs an indexer. See [`event.get`](/docs/reference/sdk/event/get). ## Options [#options] `indexer.getHistory` takes a `name` or an `address`, plus: | Option | Type | Default | Description | | --------------------------------- | ---------------------------------------------- | ------------------------------------------------------ | ----------------------------------------------------------------------- | | `name` | `string` | required without `address` | The name whose history to read. | | `address` | `string` | required without `name` | The account whose names' history to read. | | `namespace` | `"ens"` or `"basenames"` | inferred from the name, every namespace for an address | Naming system to read. | | `scope` | `"name"`, `"registration"` or `"both"` | `"both"` | Name events, registration events, or both. | | `types` | list of event types | none | Only these types. | | `excludeTypes` | list of event types | none | Leave these types out. | | `recordKey` | `string` | none | Only changes to this record, such as `avatar`, `text:url` or `addr:60`. | | `from`, `to` | `bigint` or `Date` | none | Inclusive time bounds, in Unix seconds or dates. | | `order` | `"asc"` or `"desc"` | `"desc"` | Newest first by default. | | `includeData` | `boolean` | `true` | Include each event's `data` and `action`. | | `includeChildRegistrations` | `boolean` | none | With `name`: also the registrations of its children. | | `relation` | list of `"owner"`, `"manager"`, `"roleHolder"` | all three | With `address`: which relations to follow. | | `limit`, `cursor`, `includeTotal` | | | Paging. See [Load more results](/docs/sdk/load-more-results). | Event types are `registration`, `renewal`, `release`, `expiry`, `transfer`, `authority`, `resolver`, `record`, `primary_name`, `permission`, `subregistry`, `migration`, `reservation`, `token` and `contract`. ## Troubleshooting [#troubleshooting] ### `INDEXER_NOT_FOUND` [#indexer_not_found] The indexer has no such name. [`INDEXER_NOT_FOUND`](/docs/reference/errors/INDEXER_NOT_FOUND) is thrown for a name that has never been indexed. Check the spelling, or read the name on-chain. ### `INDEXER_NOT_CONFIGURED` [#indexer_not_configured] The client has no indexer, or you forgot `indexerActions()`. See [Connect an indexer](/docs/sdk/connect-an-indexer) and [`INDEXER_NOT_CONFIGURED`](/docs/reference/errors/INDEXER_NOT_CONFIGURED). ### `LOG_RANGE_TOO_LARGE` [#log_range_too_large] The block range for `event.get` is too large for your RPC provider's log limits. Use a smaller range, or read the history from an indexer. ### A recent change is missing [#a-recent-change-is-missing] The indexer can lag the chain by a few blocks. Read `ens.indexer.getStatus()`, or use `event.get` for the latest blocks. See [Watch for changes](/docs/sdk/watch-for-changes). # Search names > For the complete documentation index, see [llms.txt](https://ensforge.com/llms.txt). Find ENS names by text for a search box or autocomplete, with name.search, and learn what the indexer returns for each match. Source: https://ensforge.com/docs/sdk/search-names By the end of this guide you can back a name search box: type `vitalik`, get a list of names that start with it. ## Prerequisites [#prerequisites] - A client with an [indexer](/docs/reference/glossary#indexer) and `indexerActions()`. See [Connect an indexer](/docs/sdk/connect-an-indexer). The chain cannot search names by text, so this needs an indexer. ## Search by text [#search-by-text] `indexer.search` returns one page of names that match a text query. By default it matches from the start of a label. **Example** (Searching Names) ```ts title="search-names.ts" import { ensActions, Ensforge } from "@ensforge/sdk"; import { bigname, indexerActions } 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: bigname(), }) .extend(ensActions()) .extend(indexerActions()); const page = await ens.indexer.search({ query: "vitalik", limit: 10 }); for (const item of page.items) { console.log(item.name, item.status, item.owner); } ``` - `query` is the text to look for. It must not be empty. - `limit` is the most names per page, 1 to 200. The default is 50. - Without `namespace`, the search covers every namespace the indexer serves, ENS and Basenames where available. See [`indexer.search`](/docs/reference/sdk/indexer/search). ## Match anywhere in a label [#match-anywhere-in-a-label] `match: "contains"` finds the text anywhere in a label. `match: "prefix"`, the default, finds names that start with it. **Example** (Searching Anywhere in a Label) ```ts title="search-contains.ts" import { ensActions, Ensforge } from "@ensforge/sdk"; import { bigname, indexerActions } 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: bigname(), }) .extend(ensActions()) .extend(indexerActions()); const page = await ens.indexer.search({ query: "dao", match: "contains", namespace: "ens" }); ``` ## Cancel stale searches in a search box [#cancel-stale-searches-in-a-search-box] Each keystroke starts a new search, so cancel the one before it with an `AbortSignal`. The cancelled call rejects with the signal's reason. **Example** (Cancelling the Previous Search) ```ts title="search-as-you-type.ts" import { ensActions, Ensforge } from "@ensforge/sdk"; import { bigname, indexerActions } 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: bigname(), }) .extend(ensActions()) .extend(indexerActions()); let controller: AbortController | undefined; export async function suggest(text: string) { controller?.abort(); controller = new AbortController(); const page = await ens.indexer.search({ query: text, limit: 8, signal: controller.signal, }); return page.items.map((item) => item.name); } ``` ## Options [#options] | Option | Type | Default | Description | | -------------- | -------------------------- | ---------------------------------- | ----------------------------------------------------------------------------------- | | `query` | `string` | required | The text to search for. | | `namespace` | `"ens"` or `"basenames"` | every namespace the indexer serves | Limits the search to one naming system. | | `match` | `"prefix"` or `"contains"` | `"prefix"` | Match from the start of a label, or anywhere. | | `limit` | `number` | `50` | Names per page, 1 to 200. | | `cursor` | `string` | none | The previous page's `cursor`. See [Load more results](/docs/sdk/load-more-results). | | `includeTotal` | `boolean` | `false` | Count every match into `totalCount`. Slower. | | `signal` | `AbortSignal` | none | Cancels the call. | ## Read the result [#read-the-result] `page.items` holds names, each with its `name`, `displayName`, `namespace`, `status`, `owner`, `manager`, `expiresAt` and `graceEndsAt`. Times are Unix seconds as `bigint`. A name that never expires has `2^64 - 1`. The page also carries `cursor`, `hasMore` and the indexer metadata described in [Connect an indexer](/docs/sdk/connect-an-indexer#3-read-answers-with-care). Search finds names the indexer knows about. To check one specific name, read it on-chain with [`name.get`](/docs/reference/sdk/name/get). See [Get a name's owner, expiry and status](/docs/sdk/get-name-details). ## Troubleshooting [#troubleshooting] ### `INVALID_RECORD_VALUE` [#invalid_record_value] The `query` is empty. [`INVALID_RECORD_VALUE`](/docs/reference/errors/INVALID_RECORD_VALUE) is thrown before any request is sent, so do not search until the user has typed something. ### `INDEXER_NOT_CONFIGURED` [#indexer_not_configured] The client has no indexer, or you forgot `indexerActions()`. See [Connect an indexer](/docs/sdk/connect-an-indexer) and [`INDEXER_NOT_CONFIGURED`](/docs/reference/errors/INDEXER_NOT_CONFIGURED). ### `INDEXER_UNSUPPORTED` [#indexer_unsupported] The indexer does not serve the query or the namespace you asked for. Combine indexers with `fallback`. See [`INDEXER_UNSUPPORTED`](/docs/reference/errors/INDEXER_UNSUPPORTED). ### `INDEXER_RATE_LIMITED` [#indexer_rate_limited] A search box sends many requests. Debounce the input, cancel stale searches as shown above, and add a second indexer with `fallback`. See [`INDEXER_RATE_LIMITED`](/docs/reference/errors/INDEXER_RATE_LIMITED). # Watch for changes > For the complete documentation index, see [llms.txt](https://ensforge.com/llms.txt). Subscribe to a name's owner, resolver, record and registration changes, so your app updates live without polling every few seconds. Source: https://ensforge.com/docs/sdk/watch-for-changes By the end of this guide you can update a name's page as it changes, or react when another account edits the name. ## Prerequisites [#prerequisites] - A client with the ENS actions added. See [Create a client](/docs/sdk/create-a-client). Watching reads the chain, so it needs no indexer. ## Watch a name [#watch-a-name] `event.watch` starts watching and resolves to a function that stops it. **Example** (Watching a Name) ```ts title="watch-name.ts" import { ensActions, Ensforge } from "@ensforge/sdk"; import { createPublicClient, http } from "viem"; import { mainnet } from "viem/chains"; const ens = Ensforge.create({ publicClient: createPublicClient({ chain: mainnet, transport: http() }), }).extend(ensActions()); const unwatch = await ens.event.watch({ name: "nick.eth", onEvents: (events) => { for (const event of events) { console.log(event.type, event.action, event.transactionHash); } }, onError: (error) => console.error(error.code), }); // Later, when the page closes: unwatch(); ``` - `onEvents` runs with each new batch of events. It does not run for blocks with no events. - Watching starts at the current block. Events from before the call are not delivered: for those, see [Name history](/docs/sdk/name-history). - `onError` runs when a poll fails. Watching continues, and the next poll reads the block range that failed again. - `unwatch()` stops watching. See [`event.watch`](/docs/reference/sdk/event/watch). ## Watch only some events [#watch-only-some-events] `types` limits the events. Each event has a `type` and an `action` that says what it did. **Example** (Watching Records and Resolver Changes) ```ts title="watch-records.ts" import { ensActions, Ensforge } from "@ensforge/sdk"; import { createPublicClient, http } from "viem"; import { mainnet } from "viem/chains"; const ens = Ensforge.create({ publicClient: createPublicClient({ chain: mainnet, transport: http() }), }).extend(ensActions()); const unwatch = await ens.event.watch({ name: "nick.eth", types: ["record", "resolver"], pollingInterval: 4_000, onEvents: (events) => { for (const event of events) console.log(event.action, event.args); }, }); ``` ## How watching works [#how-watching-works] ensforge polls for new blocks. For each new block range it reads the name's events as [`event.get`](/docs/reference/sdk/event/get) does, so a change of resolver or registry during the watch is followed from the next block on. It polls at the public client's `pollingInterval`, unless you pass `pollingInterval` in milliseconds. An event has `type`, `action`, `event` (the contract's event name), `contract`, `name`, `args`, `blockNumber`, `transactionHash` and `logIndex`. ## Options [#options] | Option | Type | Default | Description | | ----------------- | ------------------- | ------------------- | --------------------------------------------- | | `name` | `string` | required | The name to watch. Normalised for you. | | `onEvents` | `(events) => void` | required | Called with each new batch of events. | | `types` | list of event types | all | Only these event types. | | `pollingInterval` | `number` | the public client's | Milliseconds between polls. | | `onError` | `(error) => void` | none | Called when a poll fails. Watching continues. | ## Troubleshooting [#troubleshooting] ### `onEvents` never runs [#onevents-never-runs] Nothing changed after you started watching. Watching does not replay past events. Use [`event.get`](/docs/reference/sdk/event/get) or [Name history](/docs/sdk/name-history) for those. ### Changes arrive late [#changes-arrive-late] ensforge polls, so a change shows up at the next poll after its block. Lower `pollingInterval` to see changes sooner, at the cost of more RPC requests. ### `onError` keeps firing [#onerror-keeps-firing] Polls are failing, for example because of RPC rate limits. The error is a typed ensforge error, so log its `code`. See [Configure RPC and gateways](/docs/sdk/rpc-and-gateways) and [`RATE_LIMITED`](/docs/reference/errors/RATE_LIMITED). ### `INVALID_NAME` [#invalid_name] The name cannot be normalised. [`INVALID_NAME`](/docs/reference/errors/INVALID_NAME) is thrown by `event.watch` before it starts watching. # Get the name for an address > For the complete documentation index, see [llms.txt](https://ensforge.com/llms.txt). Find the primary name an address has chosen, to show a name instead of 0x... in your app, with the verified reverse lookup (ENSIP-19). Source: https://ensforge.com/docs/sdk/get-a-primary-name By the end of this guide you can show `vitalik.eth` instead of `0xd8dA…6045`. The name an address picks to represent itself is its **primary name** (stored in a reverse record, which makes this reverse resolution). ## Prerequisites [#prerequisites] - An ensforge client with the ENS actions added. See [Create a client](/docs/sdk/create-a-client). ## Get the primary name [#get-the-primary-name] `primaryName.get` takes an address and returns its primary name. **Example** (Showing a Name for an Address) ```ts title="get-primary-name.ts" import { ensActions, Ensforge } from "@ensforge/sdk"; import { createPublicClient, http } from "viem"; import { mainnet } from "viem/chains"; const ens = Ensforge.create({ publicClient: createPublicClient({ chain: mainnet, transport: http() }), }).extend(ensActions()); const address = "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045"; const name = await ens.primaryName.get({ address }); console.log(name); ``` ```text title="Output" vitalik.eth ``` The result is a `string`, or `null` when the address has no valid primary name. Show the address itself in that case. See [`primaryName.get`](/docs/reference/sdk/primary-name/get). ## Why a name can come back as `null` even when one is set [#why-a-name-can-come-back-as-null-even-when-one-is-set] Anyone can write any name into their own reverse record, including a name they do not own. ensforge therefore checks the answer in the other direction: the name counts only when it resolves back to the same address. This stops an account from claiming another account's name. ```mermaid flowchart LR A[Address] -->|reverse record| B[Claimed name] B -->|forward lookup| C[Address it points to] C -->|same as the start?| D{Verified} D -->|yes| E[Return the name] D -->|no| F[Return null] ``` Names that are not normalised are treated as unset. To skip the check and read the raw reverse record, pass `verify: false`. Only do that when you display the name next to the address and never use it to make a trust decision. ## Get the name on another chain [#get-the-name-on-another-chain] A primary name is stored per chain. `coin` selects the chain. It takes `"eth"` (the default), an EVM chain such as `{ chainId: 8453 }`, or `"default"`. **Example** (Reading the Base Primary Name) ```ts title="get-base-primary-name.ts" import { ensActions, Ensforge } from "@ensforge/sdk"; import { createPublicClient, http } from "viem"; import { mainnet } from "viem/chains"; const ens = Ensforge.create({ publicClient: createPublicClient({ chain: mainnet, transport: http() }), }).extend(ensActions()); const baseName = await ens.primaryName.get({ address: "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045", coin: { chainId: 8453 }, }); ``` A chain without its own primary name falls back to the address's default primary name (`default.reverse`, [ENSIP-19](https://docs.ens.domains/ensip/19)). For Ethereum, the name set for Ethereum itself takes priority over the default. To set a primary name, see [Set a primary name](/docs/sdk/set-a-primary-name). ## Options [#options] | Option | Type | Default | Description | | --------- | ---------------------------------------------- | -------- | ------------------------------------------------ | | `address` | `string` | required | The address to look up. | | `coin` | symbol, `{ chainId }`, `bigint` or `"default"` | `"eth"` | The chain whose primary name to read. | | `verify` | `boolean` | `true` | Require the name to resolve back to the address. | The action also takes the options every read takes: `signal`, `strict`, `gatewayUrls` and `blockNumber` or `blockTag`. ## Result [#result] The result is the name, or `null` when there is no valid primary name. With `strict: true`, the two ways to have none are told apart: | Situation | Error | | -------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------- | | The address has no reverse name, or its reverse name has no resolver or no name | [`PRIMARY_NAME_NOT_SET`](/docs/reference/errors/PRIMARY_NAME_NOT_SET) | | The name does not resolve back to the address (no resolver, no address record, or another address) | [`PRIMARY_NAME_MISMATCH`](/docs/reference/errors/PRIMARY_NAME_MISMATCH) | The `cause` of a mismatch names the name or the profile that failed. A resolver that reverts without data says neither, and counts as not set. To label many addresses at once, see [Look up many at once](/docs/sdk/look-up-many-at-once). ## Troubleshooting [#troubleshooting] ### The result is `null` [#the-result-is-null] The address has no primary name, or the name it set does not resolve back to it. Pass `strict: true` to get [`PRIMARY_NAME_NOT_SET`](/docs/reference/errors/PRIMARY_NAME_NOT_SET) or [`PRIMARY_NAME_MISMATCH`](/docs/reference/errors/PRIMARY_NAME_MISMATCH). To fix a mismatch, the owner sets the name's address record to the address, or picks another primary name. ### `INVALID_ADDRESS` [#invalid_address] The `address` is not a valid address. [`INVALID_ADDRESS`](/docs/reference/errors/INVALID_ADDRESS) is thrown before any request is sent. [`INVALID_COIN_TYPE`](/docs/reference/errors/INVALID_COIN_TYPE) means the `coin` is unknown. ### `GATEWAY_REQUEST_FAILED` on an L2 name [#gateway_request_failed-on-an-l2-name] Primary names on other chains can be proven through off-chain gateways, and the gateway failed. See [Look up off-chain names](/docs/sdk/off-chain-names) and [`GATEWAY_REQUEST_FAILED`](/docs/reference/errors/GATEWAY_REQUEST_FAILED). # Get a website > For the complete documentation index, see [llms.txt](https://ensforge.com/llms.txt). Read a name's content hash and turn it into a gateway link to the IPFS, Arweave or Swarm site or file that the name points to. Source: https://ensforge.com/docs/sdk/get-a-website By the end of this guide you can read the **content hash** of a name (a pointer to decentralized content, such as a website on IPFS) and turn it into a link a browser can open. ## Prerequisites [#prerequisites] - An ensforge client with the ENS actions added. See [Create a client](/docs/sdk/create-a-client). ## Read the content hash [#read-the-content-hash] `record.getContentHash` reads the content hash [record](/docs/reference/glossary#record) ([ENSIP-7](https://docs.ens.domains/ensip/7)) and decodes it. **Example** (Reading a Website) ```ts title="get-website.ts" import { ensActions, Ensforge } from "@ensforge/sdk"; import { createPublicClient, http } from "viem"; import { mainnet } from "viem/chains"; const ens = Ensforge.create({ publicClient: createPublicClient({ chain: mainnet, transport: http() }), }).extend(ensActions()); const site = await ens.record.getContentHash({ name: "vitalik.eth" }); console.log(site?.uri); ``` The result is `null` when the record is not set or cannot be decoded. Otherwise it has three fields: | Field | Description | | ---------- | ----------------------------------------------------------------------------------------------- | | `protocol` | The scheme: `ipfs`, `ipns`, `bzz` (Swarm), `onion`, `onion3`, `sia` (Skynet) or `ar` (Arweave). | | `value` | The identifier without the scheme, such as an IPFS CID. | | `uri` | `protocol://value`. | See [`record.getContentHash`](/docs/reference/sdk/record/get-content-hash). ## Turn it into a link [#turn-it-into-a-link] A `uri` such as `ipfs://…` is not a link a browser opens. `ContentHash.toGatewayUrl` turns it into an HTTP URL through a storage [gateway](/docs/reference/glossary#gateway). **Example** (Building a Gateway Link) ```ts title="website-link.ts" import { ContentHash, ensActions, Ensforge } from "@ensforge/sdk"; import { createPublicClient, http } from "viem"; import { mainnet } from "viem/chains"; const ens = Ensforge.create({ publicClient: createPublicClient({ chain: mainnet, transport: http() }), gateways: { ipfs: "https://gateway.pinata.cloud" }, }).extend(ensActions()); const site = await ens.record.getContentHash({ name: "vitalik.eth" }); const url = site && ContentHash.toGatewayUrl(site.uri, ens.config.gateways); ``` - `ens.config.gateways` holds the client's gateways, so the link uses the gateway you configured. - `ipfs://` and `ipns://` go through the IPFS gateway, `ar://` through the Arweave gateway and `bzz://` through the Swarm gateway. - Unset gateways are the public defaults: `https://ipfs.io`, `https://arweave.net` and `https://api.gateway.ethswarm.org`. - A URI with no gateway form (`onion://`, `sia://`) comes back unchanged. The public `ipfs.io` gateway is rate limited, so set your own in production. See [Configure RPC and gateways](/docs/sdk/rpc-and-gateways). ## Options [#options] | Option | Type | Default | Description | | ------ | -------- | -------- | ------------------------------------- | | `name` | `string` | required | The name to read. Normalised for you. | The action also takes the options every read takes: `signal`, `strict`, `gatewayUrls` and `blockNumber` or `blockTag`. ## Troubleshooting [#troubleshooting] ### The result is `null` [#the-result-is-null] The name has no content hash, no resolver, or the bytes use a codec ensforge does not decode. With `strict: true`, a missing record fails with [`RECORD_NOT_FOUND`](/docs/reference/errors/RECORD_NOT_FOUND) or [`RESOLVER_NOT_FOUND`](/docs/reference/errors/RESOLVER_NOT_FOUND). ### `INVALID_CONTENT_HASH` [#invalid_content_hash] `ContentHash.encode` and `ContentHash.decode` throw [`INVALID_CONTENT_HASH`](/docs/reference/errors/INVALID_CONTENT_HASH) when a value is malformed or uses an unsupported scheme. The read itself returns `null` instead. ### The link does not load [#the-link-does-not-load] The gateway is rate limiting or down. Pass a gateway you control in `gateways` when you create the client. # Get a name's address > For the complete documentation index, see [llms.txt](https://ensforge.com/llms.txt). Read the address a name points to, for Ethereum or for any other coin or chain, using coin types from ENSIP-9 and ENSIP-11. Source: https://ensforge.com/docs/sdk/get-an-address By the end of this guide you can turn a [name](/docs/reference/glossary#name) such as `nick.eth` into the address it points to (forward resolution), on Ethereum or on any other chain. ## Prerequisites [#prerequisites] - An ensforge client with the ENS actions added. See [Create a client](/docs/sdk/create-a-client). ## Get the Ethereum address [#get-the-ethereum-address] `record.getAddress` reads the **address record** of a name: the address its owner chose to receive funds at. Without a `coin`, it reads the Ethereum address. **Example** (Reading an Ethereum Address) ```ts title="get-address.ts" import { ensActions, Ensforge } from "@ensforge/sdk"; import { createPublicClient, http } from "viem"; import { mainnet } from "viem/chains"; const ens = Ensforge.create({ publicClient: createPublicClient({ chain: mainnet, transport: http() }), }).extend(ensActions()); const address = await ens.record.getAddress({ name: "nick.eth" }); console.log(address); ``` ```text title="Output" 0xb8c2C29ee19D8307cb7255e1Cd9CbDE883A267d5 ``` ensforge normalises the name before it reads, so `Nick.ETH` and `nick.eth` give the same answer. It finds the name's [resolver](/docs/reference/glossary#resolver), including parent, wildcard and off-chain resolvers, and returns a checksummed address. See [How a lookup works](/docs/sdk/looking-up-a-name) and [`record.getAddress`](/docs/reference/sdk/record/get-address). To read with a plain viem public client instead, call the action directly. ```ts title="get-address.ts" import { ensActions, Ensforge } from "@ensforge/sdk"; import { createPublicClient, http } from "viem"; import { mainnet } from "viem/chains"; const ens = Ensforge.create({ publicClient: createPublicClient({ chain: mainnet, transport: http() }), }).extend(ensActions()); const address = await ens.record.getAddress({ name: "ens.eth" }); ``` ```ts title="get-address.ts" import { Actions } from "@ensforge/sdk"; import { createPublicClient, http } from "viem"; import { mainnet } from "viem/chains"; const publicClient = createPublicClient({ chain: mainnet, transport: http() }); const address = await Actions.record.getAddress(publicClient, { name: "ens.eth" }); ``` The standalone form imports only the action you call, which keeps bundles small. See [Ways to call actions](/docs/sdk/ways-to-call-actions). ## Get an address on another chain [#get-an-address-on-another-chain] A name can hold one address per coin. Set `coin` to pick which one to read. It takes a symbol, an EVM chain or a numeric coin type. **Example** (Reading Bitcoin, Base and a Raw Coin Type) ```ts title="get-other-coins.ts" import { ensActions, Ensforge } from "@ensforge/sdk"; import { createPublicClient, http } from "viem"; import { mainnet } from "viem/chains"; const ens = Ensforge.create({ publicClient: createPublicClient({ chain: mainnet, transport: http() }), }).extend(ensActions()); const btc = await ens.record.getAddress({ name: "nick.eth", coin: "btc" }); const base = await ens.record.getAddress({ name: "nick.eth", coin: { chainId: 8453 } }); const sameBtc = await ens.record.getAddress({ name: "nick.eth", coin: 0n }); ``` - A symbol such as `"btc"` or `"eth"` names the coin. - `{ chainId: 8453 }` names an EVM chain (here Base). EVM chains get a checksummed `Address`; other coins return their native format as a string. - A `bigint` is the raw coin type (`0n` is Bitcoin). - An EVM chain with no address of its own falls back to the name's default EVM address ([ENSIP-19](https://docs.ens.domains/ensip/19)). ## Options [#options] | Option | Type | Default | Description | | ------ | --------------------------------- | -------- | ------------------------------------- | | `name` | `string` | required | The name to read. Normalised for you. | | `coin` | symbol, `{ chainId }` or `bigint` | `"eth"` | Which coin's address to read. | The action also takes the options every read takes: `signal` to cancel, `strict` to throw instead of returning `null`, `gatewayUrls` for off-chain lookups, and `blockNumber` or `blockTag` to read at one block. See [`record.getAddress`](/docs/reference/sdk/record/get-address). ## Result [#result] The result is `Address | null` for Ethereum and EVM chains, and `string | null` for other coins. It is `null` when the name has no address for that coin. Pass `strict: true` to fail instead, as in [Troubleshooting](#the-result-is-null). To read an address together with other records, use [`record.get`](/docs/reference/sdk/record/get). See [Get text records](/docs/sdk/get-text-records). ## Troubleshooting [#troubleshooting] ### The result is `null` [#the-result-is-null] The name has no address record for that coin, no resolver, or a resolver that does not store addresses. Pass `strict: true` to find out which one: it fails with [`RECORD_NOT_FOUND`](/docs/reference/errors/RECORD_NOT_FOUND), [`RESOLVER_NOT_FOUND`](/docs/reference/errors/RESOLVER_NOT_FOUND) or [`RESOLVER_PROFILE_UNSUPPORTED`](/docs/reference/errors/RESOLVER_PROFILE_UNSUPPORTED). ### `INVALID_NAME` [#invalid_name] The name cannot be normalised, for example because it contains a character ENS does not allow. [`INVALID_NAME`](/docs/reference/errors/INVALID_NAME) is thrown before any request is sent. ### `INVALID_COIN_TYPE` [#invalid_coin_type] The `coin` is an unknown symbol or a negative value. Some defunct coins, such as EOS (coin type 194), are no longer supported and fail with [`INVALID_COIN_TYPE`](/docs/reference/errors/INVALID_COIN_TYPE) or `INVALID_ADDRESS`. ### `GATEWAY_REQUEST_FAILED` or `OFFCHAIN_LOOKUP_INVALID` [#gateway_request_failed-or-offchain_lookup_invalid] The name resolves off-chain and the gateway failed or answered wrongly. See [Look up off-chain names](/docs/sdk/off-chain-names) and [`GATEWAY_REQUEST_FAILED`](/docs/reference/errors/GATEWAY_REQUEST_FAILED). ### `DNSSEC_PROOF_FAILED` [#dnssec_proof_failed] The name is a DNS name that resolves through a DNSSEC proof, such as `ens.domains`, and the proof does not verify. At the time of writing, no DNSSEC proof verifies on Ethereum mainnet or Sepolia, so these names fail this way until ENS updates its DNSSEC trust anchor. See [`DNSSEC_PROOF_FAILED`](/docs/reference/errors/DNSSEC_PROOF_FAILED). # Get an avatar > For the complete documentation index, see [llms.txt](https://ensforge.com/llms.txt). Read a name's avatar record, check ownership of NFT avatars, and turn the result into an image URL that a browser can load (ENSIP-12). Source: https://ensforge.com/docs/sdk/get-an-avatar By the end of this guide you can show a profile picture for a name, whether it is stored as a web link, on IPFS or Arweave, or as an NFT. ## Prerequisites [#prerequisites] - An ensforge client with the ENS actions added. See [Create a client](/docs/sdk/create-a-client). ## Get the avatar URL [#get-the-avatar-url] An **avatar** is a text record named `avatar` ([ENSIP-12](https://docs.ens.domains/ensip/12)). It holds a link, an IPFS or Arweave address, or a reference to an NFT. `record.getAvatar` reads it and returns a URL you can put in an `` tag. **Example** (Showing a Profile Picture) ```ts title="get-avatar.ts" import { ensActions, Ensforge } from "@ensforge/sdk"; import { createPublicClient, http } from "viem"; import { mainnet } from "viem/chains"; const ens = Ensforge.create({ publicClient: createPublicClient({ chain: mainnet, transport: http() }), }).extend(ensActions()); const src = await ens.record.getAvatar({ name: "nick.eth" }); ``` The result is an `http(s)` or `data:` URL, or `null` when the avatar is not set or cannot be loaded. See [`record.getAvatar`](/docs/reference/sdk/record/get-avatar). ## What ensforge does with each kind of avatar [#what-ensforge-does-with-each-kind-of-avatar] | The record holds | The result is | | ----------------------------------------------------- | ---------------------------------------------- | | An `http(s)` or `data:` URI | The same URI. | | An `ipfs://`, `ipns://` or `ar://` URI, or a bare CID | A URL on the IPFS or Arweave gateway. | | An NFT reference (`eip155:1/erc721:…/…` or `erc1155`) | The image from the token's metadata, as a URL. | An NFT avatar resolves only on the client's own chain, and only when the name's Ethereum address owns the token ([ENSIP-12](https://docs.ens.domains/ensip/12)): `ownerOf` for ERC-721, a non-zero balance for ERC-1155. To read the raw record without resolving it, use [`record.getText`](/docs/reference/sdk/record/get-text) with `key: "avatar"`. See [Get text records](/docs/sdk/get-text-records). ## Use your own gateway [#use-your-own-gateway] IPFS and Arweave avatars load through a storage [gateway](/docs/reference/glossary#gateway). The defaults are `https://ipfs.io` and `https://arweave.net`. The public `ipfs.io` gateway is rate limited and answers HTTP 429 under load, so set your own gateway in production. Set the gateways once on the client, or per call. **Example** (Setting an IPFS Gateway) ```ts title="avatar-gateway.ts" import { ensActions, Ensforge } from "@ensforge/sdk"; import { createPublicClient, http } from "viem"; import { mainnet } from "viem/chains"; const publicClient = createPublicClient({ chain: mainnet, transport: http() }); // For every call made with this client. const ens = Ensforge.create({ publicClient, gateways: { ipfs: "https://gateway.pinata.cloud" }, }).extend(ensActions()); // For one call only. const src = await ens.record.getAvatar({ name: "nick.eth", gateways: { ipfs: "https://gateway.pinata.cloud" }, }); ``` A call's `gateways` override the client's. Each gateway is an origin such as `https://gateway.pinata.cloud`. See [Configure RPC and gateways](/docs/sdk/rpc-and-gateways). ## Options [#options] | Option | Type | Default | Description | | ---------- | ----------------------------- | -------------------------------------- | ------------------------------------------ | | `name` | `string` | required | The name to read. Normalised for you. | | `gateways` | `{ ipfs?, arweave?, swarm? }` | the client's, then the public defaults | Gateway origins for decentralized storage. | | `timeout` | `number` | `10000` | Milliseconds to wait for NFT metadata. | The action also takes the options every read takes: `signal`, `strict`, `gatewayUrls` and `blockNumber` or `blockTag`. ## Troubleshooting [#troubleshooting] ### The result is `null` [#the-result-is-null] The avatar is not set, or it cannot be loaded. With `strict: true`, a missing record fails with [`RECORD_NOT_FOUND`](/docs/reference/errors/RECORD_NOT_FOUND) or [`RESOLVER_NOT_FOUND`](/docs/reference/errors/RESOLVER_NOT_FOUND). ### `GATEWAY_REQUEST_FAILED` or `GATEWAY_RESPONSE_INVALID` [#gateway_request_failed-or-gateway_response_invalid] With `strict: true`, NFT metadata that cannot be loaded fails with [`GATEWAY_REQUEST_FAILED`](/docs/reference/errors/GATEWAY_REQUEST_FAILED) or [`GATEWAY_RESPONSE_INVALID`](/docs/reference/errors/GATEWAY_RESPONSE_INVALID). Without `strict`, the result is `null`. ### Images fail to load with HTTP 429 [#images-fail-to-load-with-http-429] The public `ipfs.io` gateway is rate limiting you. Set your own IPFS gateway, as shown above. ### `INVALID_NAME` [#invalid_name] The name cannot be normalised. See [`INVALID_NAME`](/docs/reference/errors/INVALID_NAME). # Get a name's owner, expiry and status > For the complete documentation index, see [llms.txt](https://ensforge.com/llms.txt). Read who owns a name, when it expires, which resolver it uses, and whether it can be registered or renewed, in a single call. Source: https://ensforge.com/docs/sdk/get-name-details By the end of this guide you can read the full state of a name in one call: who owns it, when it expires, which resolver it uses, and whether anyone can register or renew it. ## Prerequisites [#prerequisites] - An ensforge client with the ENS actions added. See [Create a client](/docs/sdk/create-a-client). ## Get the state of a name [#get-the-state-of-a-name] `name.get` returns everything ensforge knows about a name's registration. ensforge finds out where the name lives and reads it there, so you do not choose a contract. **Example** (Showing a Renewal Banner) ```ts title="get-name-details.ts" import { ensActions, Ensforge } from "@ensforge/sdk"; import { createPublicClient, http } from "viem"; import { mainnet } from "viem/chains"; const ens = Ensforge.create({ publicClient: createPublicClient({ chain: mainnet, transport: http() }), }).extend(ensActions()); const state = await ens.name.get({ name: "ens.eth" }); if (state.status === "grace") { console.log("In the grace period until", new Date(Number(state.gracePeriodEnd) * 1000)); } else if (state.expiry !== null) { console.log("Expires", new Date(Number(state.expiry) * 1000)); } ``` - `status` tells where the name is in its life. See the table below. - `expiry` and `gracePeriodEnd` are Unix seconds as `bigint`, or `null` when they do not apply. Multiply by 1000 for a JavaScript `Date`. - Times come from the block the read runs at, not from your local clock. See [`name.get`](/docs/reference/sdk/name/get). ## Read the result [#read-the-result] | Field | Description | | --------------------- | -------------------------------------------------------------------------------------------------------------------------- | | `name` | The normalised name. | | `status` | `"available"`, `"registered"`, `"grace"`, `"expired"` or `"reserved"`. | | `owner` | Who ultimately controls the name ([owner](/docs/reference/glossary#owner)). | | `manager` | The registry owner of an unwrapped name (the "manager" in the ENS app), or `null`. | | `registrant` | The holder of an unwrapped `.eth` name's registration token, or `null`. | | `resolver` | The [resolver](/docs/reference/glossary#resolver) set on the name itself, or `null`. | | `inheritedResolver` | The resolver serving a name that has none of its own, such as a parent's wildcard or off-chain resolver. `null` otherwise. | | `expiry` | Unix seconds when the registration ends, grace period excluded. `null` when it never expires. | | `gracePeriodEnd` | Unix seconds when the `.eth` grace period ends. | | `available` | Whether the name can be registered now. | | `renewable` | Whether the name can be renewed now: `.eth` names that are registered or in grace. | | `kind` and `protocol` | Where the name lives. Most apps never need them. See [ENS versions under the hood](/docs/sdk/ens-versions). | `status: "grace"` applies to `.eth` names after they expire: during the [grace period](/docs/reference/glossary#grace-period) anyone can still renew the name, but nobody can register it. `"expired"` names can be registered again. For who may change a name, see [Who can change a name](/docs/sdk/who-can-change-a-name). ## Check availability [#check-availability] `available` and `renewable` answer the two questions a registration page asks. For prices and the full flow, see [Check if a name is available](/docs/sdk/check-if-a-name-is-available). **Example** (Checking Availability) ```ts title="is-available.ts" import { ensActions, Ensforge } from "@ensforge/sdk"; import { createPublicClient, http } from "viem"; import { mainnet } from "viem/chains"; const ens = Ensforge.create({ publicClient: createPublicClient({ chain: mainnet, transport: http() }), }).extend(ensActions()); const { available, renewable } = await ens.name.get({ name: "nick.eth" }); ``` `name.get` costs two batched RPC calls whatever the name kind. A name with no resolver of its own that a parent's resolver serves costs one more. ## Options [#options] | Option | Type | Default | Description | | --------------------------- | ----------------------- | ---------------------- | ------------------------------------- | | `name` | `string` | required | The name to read. Normalised for you. | | `signal` | `AbortSignal` | none | Cancels the call. | | `blockNumber` or `blockTag` | `bigint` or a block tag | the client's block tag | Reads at one block, never both. | ## Troubleshooting [#troubleshooting] ### A name that resolves is reported as `available` [#a-name-that-resolves-is-reported-as-available] A name served only by a parent's wildcard or off-chain resolver, such as `jesse.base.eth`, is in no registry. Its `resolver` is `null` and its `status` is `"available"`, although it resolves. Check `inheritedResolver`: when it is not `null`, something serves the name. See [Look up off-chain names](/docs/sdk/off-chain-names). ### `INVALID_NAME` [#invalid_name] The name is invalid, or it is the root. [`INVALID_NAME`](/docs/reference/errors/INVALID_NAME) is thrown before any request is sent. ### `RPC_REQUEST_FAILED` or `RPC_TIMEOUT` [#rpc_request_failed-or-rpc_timeout] The RPC request failed or timed out, with [`RPC_REQUEST_FAILED`](/docs/reference/errors/RPC_REQUEST_FAILED) or [`RPC_TIMEOUT`](/docs/reference/errors/RPC_TIMEOUT). Check your RPC endpoint. See [Configure RPC and gateways](/docs/sdk/rpc-and-gateways). # Get text records > For the complete documentation index, see [llms.txt](https://ensforge.com/llms.txt). Read text records such as a URL, a description or a social handle from a name, one key at a time or many keys in one call. Source: https://ensforge.com/docs/sdk/get-text-records By the end of this guide you can read one **text record** (a key and a string value that a name's owner stores, such as `url` or `com.twitter`), or load several at once. ## Prerequisites [#prerequisites] - An ensforge client with the ENS actions added. See [Create a client](/docs/sdk/create-a-client). ## Read one record [#read-one-record] `record.getText` reads a single text record. Pass the `name` and the record's `key`. **Example** (Reading a Profile URL) ```ts title="get-text.ts" import { ensActions, Ensforge } from "@ensforge/sdk"; import { createPublicClient, http } from "viem"; import { mainnet } from "viem/chains"; const ens = Ensforge.create({ publicClient: createPublicClient({ chain: mainnet, transport: http() }), }).extend(ensActions()); const url = await ens.record.getText({ name: "nick.eth", key: "url" }); ``` The result is a `string`, or `null` when the record is not set. ensforge [normalises](/docs/reference/glossary#normalisation) the name and finds its [resolver](/docs/reference/glossary#resolver), so wildcard names and [off-chain names](/docs/reference/glossary#off-chain-name) work too. Calls made in the same tick are batched into one multicall where possible. See [`record.getText`](/docs/reference/sdk/record/get-text) and [How a lookup works](/docs/sdk/looking-up-a-name). ## Read several records in one call [#read-several-records-in-one-call] `record.get` reads any mix of records in one request. List the keys in `texts`, and the result has exactly the fields you asked for. **Example** (Loading a Profile) ```ts title="get-profile.ts" import { ensActions, Ensforge } from "@ensforge/sdk"; import { createPublicClient, http } from "viem"; import { mainnet } from "viem/chains"; const ens = Ensforge.create({ publicClient: createPublicClient({ chain: mainnet, transport: http() }), }).extend(ensActions()); const profile = await ens.record.get({ name: "nick.eth", texts: ["avatar", "url", "com.twitter"], addresses: ["eth", "btc"], }); profile.texts.url; profile.addresses.btc; profile.resolver; ``` - `texts` lists text keys. Each key becomes a field of `profile.texts`, typed `string | null`. - `addresses` lists coins by symbol or coin type. Each becomes a field of `profile.addresses`. - `resolver` is the address of the resolver that answered, or `null` when the name has none. - A field you did not ask for does not exist on the result: `profile.texts.url` is there only because `"url"` was requested. `record.get` is one Universal Resolver call whatever you select. It can also read the content hash (`contentHash: true`), the public key, the `name` record and more. See [`record.get`](/docs/reference/sdk/record/get), [Get a name's address](/docs/sdk/get-an-address) and [Get a website](/docs/sdk/get-a-website). ## Options [#options] `record.getText` takes: | Option | Type | Default | Description | | ------ | -------- | -------- | -------------------------------------------------------------- | | `name` | `string` | required | The name to read. Normalised for you. | | `key` | `string` | required | The text record key, such as `url`, `avatar` or `com.twitter`. | `record.get` takes `name` and any of these selections: | Option | Type | Default | Description | | ------------- | ------------------------------------ | ------- | -------------------------------------------------- | | `texts` | `readonly string[]` | none | Text record keys to read. | | `addresses` | `readonly (string \| bigint)[]` | none | Coins to read, by symbol or coin type. | | `contentHash` | `true` | none | Read the content hash. | | `abi` | `true` or `{ contentTypes: bigint }` | none | Read the ABI record. | | `pubkey` | `true` | none | Read the public key. | | `nameRecord` | `true` | none | Read the `name` record. | | `interfaces` | `readonly Hex[]` | none | ERC-165 interface IDs to look up implementers for. | | `data` | `readonly string[]` | none | Data record keys. | Both actions also take the options every read takes: `signal` to cancel, `strict` to throw instead of returning `null`, `gatewayUrls` for off-chain lookups, and `blockNumber` or `blockTag` to read at one block. ## Troubleshooting [#troubleshooting] ### A record is `null` [#a-record-is-null] The record is not set, the name has no resolver, or its resolver does not store text records. With `strict: true`, `getText` fails with [`RECORD_NOT_FOUND`](/docs/reference/errors/RECORD_NOT_FOUND), [`RESOLVER_NOT_FOUND`](/docs/reference/errors/RESOLVER_NOT_FOUND) or [`RESOLVER_PROFILE_UNSUPPORTED`](/docs/reference/errors/RESOLVER_PROFILE_UNSUPPORTED), so you can tell which. `record.get` with `strict: true` fails with `RESOLVER_NOT_FOUND` when the name has no resolver. Without `strict`, it returns `resolver: null` and every record `null`. ### `INVALID_NAME` [#invalid_name] The name cannot be normalised. [`INVALID_NAME`](/docs/reference/errors/INVALID_NAME) is thrown before any request is sent. ### `GATEWAY_REQUEST_FAILED` [#gateway_request_failed] The name's resolver sends the lookup to an off-chain gateway, and the gateway failed. See [Look up off-chain names](/docs/sdk/off-chain-names) and [`GATEWAY_REQUEST_FAILED`](/docs/reference/errors/GATEWAY_REQUEST_FAILED). # Look up many at once > For the complete documentation index, see [llms.txt](https://ensforge.com/llms.txt). Read many names, records and addresses together with Actions.batch and request forms, so a page loads with as few RPC requests as possible. Source: https://ensforge.com/docs/sdk/look-up-many-at-once By the end of this guide you can load a whole page of data, such as a profile, a table of names or a list of holders, without one network request per value. ## Prerequisites [#prerequisites] - An ensforge client with the ENS actions added. See [Create a client](/docs/sdk/create-a-client). - For the second approach, an [indexer](/docs/reference/glossary#indexer). See [Connect an indexer](/docs/sdk/connect-an-indexer). There are two ways to read many values. Use `batch` for reads from the chain ([batch](/docs/reference/glossary#batch)). Use `indexer.lookup` for up to 1,000 names and addresses at once, answered from an indexer. ## Batch reads from the chain [#batch-reads-from-the-chain] Every read action has a `.request` form that builds a deferred read. `batch` runs a group of them together. Contract reads are combined into Multicall3 calls per block. Resolution reads (records and primary names) keep their own Universal Resolver call, so off-chain names still work. The [HCA](/docs/hca) reads (`hca.get`, `hca.predictAddress` and the others) have `.request` too, so they batch next to the SDK's reads. **Example** (Loading a Profile in One Batch) ```ts title="batch-profile.ts" import { Actions, ensActions, Ensforge } from "@ensforge/sdk"; import { createPublicClient, http } from "viem"; import { mainnet } from "viem/chains"; const ens = Ensforge.create({ publicClient: createPublicClient({ chain: mainnet, transport: http() }), }).extend(ensActions()); const { results } = await ens.batch({ requests: { address: Actions.record.getAddress.request({ name: "nick.eth" }), avatar: Actions.record.getAvatar.request({ name: "nick.eth" }), state: Actions.name.get.request({ name: "nick.eth" }), }, }); if (results.address.status === "success") { console.log(results.address.result); } ``` - `requests` is a record or a list. A record returns a record of results with the same keys. A list returns a tuple in the same order. - Each result is `{ status: "success", result }` or `{ status: "failure", error }`. One failed read does not fail the others. - Only reads have `.request`. Writes combine with `Plan.merge`. See [How writes work](/docs/sdk/writing-to-ens). ### Get the values directly [#get-the-values-directly] Set `allowFailure: false` to get plain values. The first failure rejects the whole batch. **Example** (Failing the Batch on the First Error) ```ts title="batch-values.ts" import { Actions, ensActions, Ensforge } from "@ensforge/sdk"; import { createPublicClient, http } from "viem"; import { mainnet } from "viem/chains"; const ens = Ensforge.create({ publicClient: createPublicClient({ chain: mainnet, transport: http() }), }).extend(ensActions()); const { results } = await ens.batch({ requests: [ Actions.record.getAddress.request({ name: "nick.eth" }), Actions.record.getAddress.request({ name: "vitalik.eth" }), Actions.record.getAddress.request({ name: "ens.eth" }), ], allowFailure: false, }); const [nickAddress, vitalikAddress, ensAddress] = results; ``` ### Batch options [#batch-options] | Option | Type | Default | Description | | -------------- | -------------------------- | -------- | ----------------------------------------------------------------- | | `requests` | list or record of requests | required | Deferred reads from `action.request(options)`. | | `allowFailure` | `boolean` | `true` | Report each failure in its result instead of rejecting the batch. | | `signal` | `AbortSignal` | none | Cancels the batch. | ## Look up names and addresses from an indexer [#look-up-names-and-addresses-from-an-indexer] `indexer.lookup` answers up to 1,000 inputs in one request. Names come back with their state. Addresses come back with their primary name and related names. It needs an indexer on the client. **Example** (Reading Names and an Address Together) ```ts title="lookup-many.ts" import { ensActions, Ensforge } from "@ensforge/sdk"; import { bigname, indexerActions } 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: bigname(), }) .extend(ensActions()) .extend(indexerActions()); const { results } = await ens.indexer.lookup({ inputs: ["nick.eth", "ens.eth", "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045"], }); for (const answer of results) { console.log(answer.input, answer.kind, answer.status); } ``` - `results` has one answer per input, in input order. - `kind` is `"name"` or `"address"`. A name input fills `name`. An address input fills `names` with its related names. - An input that fails, such as an invalid name, reports its own `status` and `reason`. It does not fail the lookup. - `profile: "detail"` adds records and resolution to each answer. The default is `"feed"`. See [`indexer.lookup`](/docs/reference/sdk/indexer/lookup) and [Name lists and indexers](/docs/sdk/name-lists-and-indexers). ### Lookup options [#lookup-options] | Option | Type | Default | Description | | ----------- | ------------------------ | ---------------------------------- | --------------------------------------- | | `inputs` | `readonly string[]` | required | Names and addresses, up to 1,000. | | `namespace` | `"ens"` or `"basenames"` | every namespace the indexer serves | Limits the lookup to one naming system. | | `profile` | `"feed"` or `"detail"` | `"feed"` | `"detail"` adds records and resolution. | | `signal` | `AbortSignal` | none | Cancels the call. | ## Choose between them [#choose-between-them] | You need | Use | | ------------------------------------------------------ | ---------------- | | Records, avatars or primary names, read from the chain | `batch` | | An authoritative, on-chain answer | `batch` | | Hundreds of names or addresses in one request | `indexer.lookup` | | Related names for an address | `indexer.lookup` | ## Troubleshooting [#troubleshooting] ### `INVALID_RECORD_VALUE` from `batch` [#invalid_record_value-from-batch] A request cannot be batched. Only reads built with `.request` run in a batch. [`INVALID_RECORD_VALUE`](/docs/reference/errors/INVALID_RECORD_VALUE) is also what `indexer.lookup` throws for more than 1,000 inputs, or for none. ### A result has `status: "failure"` [#a-result-has-status-failure] Read `result.error`. It is the same typed error the action would have thrown on its own. Handle it as in [Handle errors](/docs/sdk/handle-errors). ### `INDEXER_NOT_CONFIGURED` [#indexer_not_configured] `indexer.lookup` needs an indexer. Pass `indexer: bigname()` to `Ensforge.create` and add `indexerActions()`. See [`INDEXER_NOT_CONFIGURED`](/docs/reference/errors/INDEXER_NOT_CONFIGURED) and [Connect an indexer](/docs/sdk/connect-an-indexer). ### `INDEXER_UNSUPPORTED` [#indexer_unsupported] The indexer does not serve the query or the namespace. See [`INDEXER_UNSUPPORTED`](/docs/reference/errors/INDEXER_UNSUPPORTED) and [Connect an indexer](/docs/sdk/connect-an-indexer#use-more-than-one-indexer). # Look up off-chain names > For the complete documentation index, see [llms.txt](https://ensforge.com/llms.txt). Read records of names whose data lives off-chain (CCIP-Read, EIP-3668), such as Basenames, and choose which gateways ensforge asks. Source: https://ensforge.com/docs/sdk/off-chain-names By the end of this guide you can read the records of an **off-chain name** (a name whose records are not stored on Ethereum, but served by a **gateway**) with the same calls you use for any other name, and configure or turn off the gateway lookup ([CCIP-Read](/docs/reference/glossary#ccip-read)). ## Prerequisites [#prerequisites] - An ensforge client with the ENS actions added. See [Create a client](/docs/sdk/create-a-client). ## Read an off-chain name [#read-an-off-chain-name] Nothing changes in your code. Ask for a record as usual. **Example** (Reading an Off-Chain Name) ```ts title="off-chain.ts" import { ensActions, Ensforge } from "@ensforge/sdk"; import { createPublicClient, http } from "viem"; import { mainnet } from "viem/chains"; const ens = Ensforge.create({ publicClient: createPublicClient({ chain: mainnet, transport: http() }), }).extend(ensActions()); // jesse.base.eth is a subname of an on-chain name, answered off-chain by its parent's resolver. const address = await ens.record.getAddress({ name: "jesse.base.eth" }); const url = await ens.record.getText({ name: "jesse.base.eth", key: "url" }); ``` `record.getAddress`, `record.getText`, `record.get`, `record.getAvatar`, `record.getContentHash` and `primaryName.get` all follow an off-chain lookup when the name needs one. See [Get a name's address](/docs/sdk/get-an-address). ## How an off-chain lookup works [#how-an-off-chain-lookup-works] The name's [resolver](/docs/reference/glossary#resolver) does not hold the answer. It replies with a request to ask a gateway ([CCIP-Read, EIP-3668](https://eips.ethereum.org/EIPS/eip-3668)). ensforge asks the gateway and hands its answer back to the resolver contract, which checks it and returns the result. ```mermaid sequenceDiagram participant App as Your app participant ENS as ensforge participant R as Resolver participant G as Gateway App->>ENS: getAddress("jesse.base.eth") ENS->>R: resolve the name R-->>ENS: ask this gateway ENS->>G: request the answer G-->>ENS: signed answer ENS->>R: hand the answer back R-->>ENS: verified address ENS-->>App: 0x… ``` Two kinds of name need this: - A name with an off-chain resolver of its own. - A name that has no resolver of its own, where a parent's **wildcard resolver** ([ENSIP-10](https://docs.ens.domains/ensip/10)) answers for every subname. `jesse.base.eth` is one. ensforge only follows a lookup that the resolver it called asked for. If a resolver sends a lookup that names another contract as the sender, ensforge refuses it with [`OFFCHAIN_LOOKUP_INVALID`](/docs/reference/errors/OFFCHAIN_LOOKUP_INVALID) and never returns the gateway's answer. See [How a lookup works](/docs/sdk/looking-up-a-name). ## Choose the gateways [#choose-the-gateways] The Universal Resolver sends off-chain lookups through a batch gateway, which collects them and forwards each one to the resolver's own gateway. By default, ensforge uses the Universal Resolver's own batch gateway. To use batch gateways you choose, set `ccipRead` when you create the client, or `gatewayUrls` on one call. The resolver's own gateway is set by the resolver and cannot be changed. `x-batch-gateway:true` makes viem answer the batch itself. A URL works too, for a batch gateway you run. See [Configure RPC and gateways](/docs/sdk/rpc-and-gateways#set-off-chain-lookup-gateways). **Example** (Setting Batch Gateways) ```ts title="gateways.ts" import { ensActions, Ensforge } from "@ensforge/sdk"; import { createPublicClient, http } from "viem"; import { mainnet } from "viem/chains"; const publicClient = createPublicClient({ chain: mainnet, transport: http() }); // For every call made with this client. const ens = Ensforge.create({ publicClient, ccipRead: { gatewayUrls: ["x-batch-gateway:true"] }, }).extend(ensActions()); // For one call only. const address = await ens.record.getAddress({ name: "jesse.base.eth", gatewayUrls: ["x-batch-gateway:true"], }); ``` A call's `gatewayUrls` override the client's. To read through the chain only, pass `ccipRead: false` to `Ensforge.create`. Off-chain names then fail with [`CCIP_READ_DISABLED`](/docs/reference/errors/CCIP_READ_DISABLED). ## Options [#options] | Option | Where | Type | Default | Description | | ------------- | ----------------- | ----------------------------- | ------------------------------------------ | ------------------------------------------------------------- | | `ccipRead` | `Ensforge.create` | `{ gatewayUrls? }` or `false` | the Universal Resolver's own batch gateway | Batch gateways for off-chain lookups. `false` turns them off. | | `gatewayUrls` | any read | `readonly string[]` | the client's | Batch gateways for one call. | ## Names that are in no registry [#names-that-are-in-no-registry] A name served only by a parent's resolver is in no registry. [`name.get`](/docs/reference/sdk/name/get) reports `resolver: null` and `status: "available"` for it, although it resolves. Its `inheritedResolver` is the resolver that serves it. See [Get a name's owner, expiry and status](/docs/sdk/get-name-details). ## Troubleshooting [#troubleshooting] ### `GATEWAY_REQUEST_FAILED` [#gateway_request_failed] The gateway could not be reached, or answered with an error status. The error carries the HTTP `status` and the gateway `url` when there is one. It is the one gateway failure ensforge marks as retryable. See [`GATEWAY_REQUEST_FAILED`](/docs/reference/errors/GATEWAY_REQUEST_FAILED). ### `GATEWAY_RESPONSE_INVALID` [#gateway_response_invalid] The gateway answered with something ensforge cannot use. Retrying the same gateway does not help. See [`GATEWAY_RESPONSE_INVALID`](/docs/reference/errors/GATEWAY_RESPONSE_INVALID). ### `CCIP_READ_DISABLED` [#ccip_read_disabled] The name resolves off-chain and the client was created with `ccipRead: false`. Remove that option. See [`CCIP_READ_DISABLED`](/docs/reference/errors/CCIP_READ_DISABLED). ### `OFFCHAIN_LOOKUP_INVALID` [#offchain_lookup_invalid] The resolver asked for a lookup from an unexpected sender. ensforge refuses these on purpose. See [`OFFCHAIN_LOOKUP_INVALID`](/docs/reference/errors/OFFCHAIN_LOOKUP_INVALID). ### `DNSSEC_PROOF_FAILED` on a DNS name [#dnssec_proof_failed-on-a-dns-name] DNS names without a resolver of their own in ENS, such as `ens.domains`, resolve through DNSSEC proofs. At the time of writing, no proof verifies on-chain on Ethereum mainnet or Sepolia, so these reads fail with [`DNSSEC_PROOF_FAILED`](/docs/reference/errors/DNSSEC_PROOF_FAILED) until ENS updates its DNSSEC trust anchor. See [Use a DNS name](/docs/sdk/use-a-dns-name). ### Writing records to an off-chain name fails [#writing-records-to-an-off-chain-name-fails] Resolvers that keep records off-chain refuse on-chain writes. The write fails with [`RESOLVER_PROFILE_UNSUPPORTED`](/docs/reference/errors/RESOLVER_PROFILE_UNSUPPORTED) and says where the records live. See [Set records](/docs/sdk/set-records). # Change the resolver > For the complete documentation index, see [llms.txt](https://ensforge.com/llms.txt). Point a name at another resolver, or create a new one, without losing its records, and check that lookups still resolve afterwards. Source: https://ensforge.com/docs/sdk/change-the-resolver You will move a name to a different [resolver](/docs/reference/glossary#resolver), the contract that stores its [records](/docs/reference/glossary#record). The records stay on the old resolver, so you copy them in the same step or before you switch. ## Prerequisites [#prerequisites] - A wallet client for an account that may change the name's resolver. See [Create a client](/docs/sdk/create-a-client). - A registered name. ## 1. Read the current resolver [#1-read-the-current-resolver] [`resolver.get`](/docs/reference/sdk/resolver/get) tells you where the records live, who may write to them and which record kinds the resolver supports. **Example** (Reading a Name's Resolver) ```ts title="get-resolver.ts" import { createPublicClient, http } from "viem"; import { sepolia } from "viem/chains"; import { Ensforge, ensActions } from "@ensforge/sdk"; const ens = Ensforge.create({ publicClient: createPublicClient({ chain: sepolia, transport: http() }), }).extend(ensActions()); const resolver = await ens.resolver.get({ name: "ensforge-docs-demo.eth" }); ``` - `kind` says what the contract is, for example `"public-resolver"` or `"permissioned-resolver"`. - `authorization` says who may change records: the name's `"owner"`, accounts holding `"roles"`, `"none"` (read-only) or `"unknown"`. - `profiles` lists the record kinds the resolver supports. - `inherited: true` means the name has no resolver of its own and a parent's wildcard or off-chain resolver serves it. You cannot write records there for this name. ## 2. Move the name and its records together [#2-move-the-name-and-its-records-together] [`record.set`](/docs/reference/sdk/record/set) with `resolver` writes the records to the new resolver, then points the name at it, in one step. A rejected write never leaves the name on an empty resolver. **Example** (Switching Resolver and Copying a Profile) ```ts title="switch-resolver.ts" import { createPublicClient, createWalletClient, http, type Hex } from "viem"; import { privateKeyToAccount } from "viem/accounts"; import { sepolia } from "viem/chains"; import { Ensforge, ensActions } from "@ensforge/sdk"; const account = privateKeyToAccount(process.env.PRIVATE_KEY as Hex); const transport = http(process.env.SEPOLIA_RPC_URL); const ens = Ensforge.create({ publicClient: createPublicClient({ chain: sepolia, transport }), walletClient: createWalletClient({ account, chain: sepolia, transport }), }).extend(ensActions()); await ens.record.setSync({ name: "ensforge-docs-demo.eth", resolver: "0x1111111111111111111111111111111111111111", // the new resolver texts: { url: "https://example.com" }, addresses: { eth: account.address }, }); ``` ## 3. Or only change the pointer [#3-or-only-change-the-pointer] [`resolver.set`](/docs/reference/sdk/resolver/set) changes the resolver and nothing else. `resolver.setSync` also waits for the receipt. **Example** (Pointing a Name at Another Resolver) ```ts title="set-resolver.ts" import { createPublicClient, createWalletClient, http, type Hex } from "viem"; import { privateKeyToAccount } from "viem/accounts"; import { sepolia } from "viem/chains"; import { Ensforge, ensActions } from "@ensforge/sdk"; const account = privateKeyToAccount(process.env.PRIVATE_KEY as Hex); const transport = http(process.env.SEPOLIA_RPC_URL); const ens = Ensforge.create({ publicClient: createPublicClient({ chain: sepolia, transport }), walletClient: createWalletClient({ account, chain: sepolia, transport }), }).extend(ensActions()); await ens.resolver.setSync({ name: "ensforge-docs-demo.eth", resolver: "0x1111111111111111111111111111111111111111", }); ``` | `resolver` value | Effect | | ---------------- | --------------------------------------------------------------- | | An address | Points the name at that resolver. | | `"default"` | Points the name at the ENSv1 public resolver. ENSv1 names only. | | `null` | Removes the resolver. | The change is made in the [registry](/docs/reference/glossary#registry) that holds the name: the ENS registry on [ENSv1](/docs/reference/glossary#ensv1) (through the NameWrapper when the name is wrapped), or the name's registry on [ENSv2](/docs/reference/glossary#ensv2). ## Create a resolver for an ENSv2 name [#create-a-resolver-for-an-ensv2-name] ENSv2 names have no shared default resolver, so `resolver: "default"` fails for them with [`UNSUPPORTED_PROTOCOL`](/docs/reference/errors/UNSUPPORTED_PROTOCOL). [`resolver.create`](/docs/reference/sdk/resolver/create) deploys a PermissionedResolver, optionally writes records into it and points the name at it, in one plan. **Example** (Creating a Resolver With Records) ```ts title="create-resolver.ts" import { createPublicClient, createWalletClient, http, type Hex } from "viem"; import { privateKeyToAccount } from "viem/accounts"; import { sepolia } from "viem/chains"; import { Ensforge, ensActions } from "@ensforge/sdk"; const account = privateKeyToAccount(process.env.PRIVATE_KEY as Hex); const transport = http(process.env.SEPOLIA_RPC_URL); const ens = Ensforge.create({ publicClient: createPublicClient({ chain: sepolia, transport }), walletClient: createWalletClient({ account, chain: sepolia, transport }), }).extend(ensActions()); const { resolver } = await ens.resolver.createSync({ name: "ensforge-docs-demo.eth", records: { texts: { url: "https://example.com" } }, }); ``` `resolver` is the new contract's address, known before the transaction is sent. See [Resolvers and shared records](/docs/sdk/resolvers-and-shared-records) for the options and for sharing one resolver between names. ## Check the result [#check-the-result] Call `resolver.get` again and compare `address` with the one you set. See [Get a name's owner, expiry and status](/docs/sdk/get-name-details). ## Troubleshooting [#troubleshooting] ### `NOT_OWNER`, `MISSING_ROLES` or `FUSE_BURNED` [#not_owner-missing_roles-or-fuse_burned] The account may not change the resolver. On ENSv2 it needs the `setResolver` [role](/docs/reference/glossary#role). On a wrapped name, a burned `cannotSetResolver` fuse forbids it for good. See [`NOT_OWNER`](/docs/reference/errors/NOT_OWNER), [`MISSING_ROLES`](/docs/reference/errors/MISSING_ROLES), [`FUSE_BURNED`](/docs/reference/errors/FUSE_BURNED) and [Lock permissions with fuses](/docs/sdk/fuses). ### `UNSUPPORTED_PROTOCOL` [#unsupported_protocol] You passed `"default"` for an ENSv2 name. Pass an address, or create a resolver with `resolver.create`. See [`UNSUPPORTED_PROTOCOL`](/docs/reference/errors/UNSUPPORTED_PROTOCOL). ### `NAME_EXPIRED`, `NAME_RESERVED` or `NAME_NOT_REGISTERED` [#name_expired-name_reserved-or-name_not_registered] Only registered names can change their resolver. See [`NAME_NOT_REGISTERED`](/docs/reference/errors/NAME_NOT_REGISTERED). ### Records disappeared after the switch [#records-disappeared-after-the-switch] `resolver.set` does not copy records. Read them from the old resolver and write them with `record.set` and `resolver`, as in step 2. # Check if a name is available > For the complete documentation index, see [llms.txt](https://ensforge.com/llms.txt). Check whether a .eth name can be registered, then quote its price for a duration and read the registration settings of the chain. Source: https://ensforge.com/docs/sdk/check-if-a-name-is-available You will check that a [`.eth` name](/docs/reference/glossary#eth-name) is free, read what it costs, and read the rules a registration follows. These are reads: they need no wallet and never send a transaction. ## Prerequisites [#prerequisites] - A client with a public client. See [Create a client](/docs/sdk/create-a-client). - A chain with [ENSv2](/docs/reference/glossary#ensv2) deployed, such as Sepolia. Registration actions fail with [`UNSUPPORTED_ON_DEPLOYMENT`](/docs/reference/errors/UNSUPPORTED_ON_DEPLOYMENT) elsewhere. ## 1. Check the name [#1-check-the-name] [`registration.isAvailable`](/docs/reference/sdk/registration/is-available) returns `true` when the name can be registered now. **Example** (Checking One Name) ```ts title="is-available.ts" import { createPublicClient, http } from "viem"; import { sepolia } from "viem/chains"; import { Ensforge, ensActions } from "@ensforge/sdk"; const ens = Ensforge.create({ publicClient: createPublicClient({ chain: sepolia, transport: http() }), }).extend(ensActions()); const free = await ens.registration.isAvailable({ name: "ensforge-docs-demo.eth" }); ``` - The name is [normalised](/docs/reference/glossary#normalisation) for you, so `"QQQ.eth"` is checked as `qqq.eth`. - Only `.eth` second-level names are accepted. Other names fail with [`INVALID_NAME`](/docs/reference/errors/INVALID_NAME). - Every new `.eth` name is registered on ENSv2, including names that expired on ENSv1. One check covers both. A name is not available in these cases: - It is registered. - It is in its [grace period](/docs/reference/glossary#grace-period): it has expired, but it can still be renewed, and nobody can register it yet. - The price oracle rejects its label, for example because it is shorter than three characters. ## 2. Quote the price [#2-quote-the-price] [`registration.getPrice`](/docs/reference/sdk/registration/get-price) returns the cost in an ERC-20 token. The ENSv2 registrar does not accept ETH. **Example** (Quoting One Year) ```ts title="get-price.ts" import { createPublicClient, http } from "viem"; import { sepolia } from "viem/chains"; import { Duration, Ensforge, ensActions } from "@ensforge/sdk"; const ens = Ensforge.create({ publicClient: createPublicClient({ chain: sepolia, transport: http() }), }).extend(ensActions()); const { base, premium, total, token } = await ens.registration.getPrice({ name: "ensforge-docs-demo.eth", duration: Duration.years(1), }); ``` | Field | Meaning | | --------- | ----------------------------------------------------------------------------------------------------------------------------- | | `base` | The yearly rent for the label length, times the duration. | | `premium` | The [premium](/docs/reference/glossary#premium): an extra charge for names that recently became available. It decays to zero. | | `total` | `base` plus `premium`. | | `token` | The payment token's `address`, `symbol` and `decimals`. | Amounts are in the token's smallest unit. USDC has 6 decimals, so `1_000_000n` is one USDC. | Option | Type | Default | Description | | -------------- | --------------------------- | ----------------------------- | -------------------------------------------------------------------------- | | `name` | `string` | required | The `.eth` name. | | `duration` | `bigint` | required | Registration length in seconds. Use `Duration.years(1)`. | | `paymentToken` | `"usdc" \| "dai" \| string` | `"usdc"` | A token listed for the deployment, or an address the price oracle accepts. | | `at` | `bigint` | the current block's timestamp | Unix time to price at. Use it to show when a premium ends. | ## 3. Read the registration settings [#3-read-the-registration-settings] [`registration.getParameters`](/docs/reference/sdk/registration/get-parameters) returns the rules to show in a registration screen. **Example** (Reading the Settings) ```ts title="get-parameters.ts" import { createPublicClient, http } from "viem"; import { sepolia } from "viem/chains"; import { Ensforge, ensActions } from "@ensforge/sdk"; const ens = Ensforge.create({ publicClient: createPublicClient({ chain: sepolia, transport: http() }), }).extend(ensActions()); const { minCommitmentAge, minDuration, gracePeriod, paymentTokens } = await ens.registration.getParameters(); ``` All durations and ages are in seconds. `minCommitmentAge` is the wait between the two halves of a registration. `paymentTokens` lists the deployment's tokens that the price oracle accepts right now. ## Check the result [#check-the-result] `isAvailable` returns a `boolean`. `getPrice` returns `{ base, premium, total, token }`. Pass the same `name` and `duration` to [Register a name](/docs/sdk/register-a-name) to pay the quote. ## Troubleshooting [#troubleshooting] ### `UNSUPPORTED_ON_DEPLOYMENT` [#unsupported_on_deployment] The chain has no ENSv2 deployment, so the registrar does not exist there. Use Sepolia or a fork of a chain with ENSv2. See [`UNSUPPORTED_ON_DEPLOYMENT`](/docs/reference/errors/UNSUPPORTED_ON_DEPLOYMENT). ### `PAYMENT_TOKEN_UNSUPPORTED` [#payment_token_unsupported] The price oracle does not accept `paymentToken`. Read `paymentTokens` from `registration.getParameters` and pick one of them. See [`PAYMENT_TOKEN_UNSUPPORTED`](/docs/reference/errors/PAYMENT_TOKEN_UNSUPPORTED). ### `DURATION_TOO_SHORT` [#duration_too_short] `duration` is below the registrar's `minDuration`. See [`DURATION_TOO_SHORT`](/docs/reference/errors/DURATION_TOO_SHORT). # Create subnames > For the complete documentation index, see [llms.txt](https://ensforge.com/llms.txt). Create, update and remove subnames such as pay.ensforge-docs-demo.eth under a name you control, with their own owner and records. Source: https://ensforge.com/docs/sdk/create-subnames You will create a **subname** (a name under one you own, such as `pay.ensforge-docs-demo.eth`), change it and remove it. ensforge routes the write by the parent: an [ENSv2](/docs/reference/glossary#ensv2) subregistry, the [ENSv1](/docs/reference/glossary#ensv1) [registry](/docs/reference/glossary#registry) or the [Name Wrapper](/docs/reference/glossary#name-wrapper). You pass the same options. ## Prerequisites [#prerequisites] - A wallet client for an account that may create children of the parent. See [Create a client](/docs/sdk/create-a-client). - A registered parent name. See [Register a name](/docs/sdk/register-a-name). ## 1. Create a subname [#1-create-a-subname] [`subname.create`](/docs/reference/sdk/subname/create) takes the full name of the child. `subname.createSync` also waits for the receipt. **Example** (Creating a Subname With Records) ```ts title="create-subname.ts" import { createPublicClient, createWalletClient, http, type Hex } from "viem"; import { privateKeyToAccount } from "viem/accounts"; import { sepolia } from "viem/chains"; import { Ensforge, ensActions } from "@ensforge/sdk"; const account = privateKeyToAccount(process.env.PRIVATE_KEY as Hex); const transport = http(process.env.SEPOLIA_RPC_URL); const ens = Ensforge.create({ publicClient: createPublicClient({ chain: sepolia, transport }), walletClient: createWalletClient({ account, chain: sepolia, transport }), }).extend(ensActions()); const { hash } = await ens.subname.createSync({ name: "pay.ensforge-docs-demo.eth", owner: "0xB0b0000000000000000000000000000000000000", records: { texts: { url: "https://pay.example.com" } }, }); ``` - `owner` defaults to the signer. - By default the child gets its own [resolver](/docs/reference/glossary#resolver), a PermissionedResolver, with `records` written at creation. `resolver: "parent"` shares the parent's resolver. `resolver: null` creates the child without one. - `upsert: true` updates an existing child's resolver and records instead of failing. | Option | Type | Default | Description | | ------------ | ---------------------------- | ---------------------- | ------------------------------------------------------------ | | `name` | `string` | required | Full name of the child. | | `owner` | `string` | the signer | Owner of the child. | | `resolver` | `string \| "parent" \| null` | a new resolver | Resolver of the child. | | `records` | `object` | none | Records of the child, in the `record.set` shape. | | `expiry` | `bigint` | see below | Expiry as a Unix timestamp. | | `fuses` | `Fuse.Name[]` | none | NameWrapper fuses to burn. Wrapped parents only. | | `roles` | `Role.Name[] \| bigint` | the `.eth` owner roles | ENSv2 roles for the child's owner. | | `emancipate` | `boolean` | `false` | Emancipate the parent's subregistry if this plan deploys it. | | `upsert` | `boolean` | `false` | Update the child if it exists. | ## What differs by parent [#what-differs-by-parent] | Parent | What happens | | ------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | On ENSv2 | The child is registered in the parent's subregistry. A parent without one gets a UserRegistry deployed and attached in the same plan. Children never expire by default. Their owner gets the roles the `.eth` registrar grants: resolver, subregistry and transfers. | | Unwrapped on ENSv1 | One `setSubnodeRecord` call. `roles` and `fuses` are not supported. | | Wrapped on ENSv1 | Takes `fuses` and an `expiry`. When `parentCannotControl` is burned, the default `expiry` is the maximum. | Owners of a subregistry that this plan deploys can remove and repoint its children, unless you pass `emancipate: true`. See [Registries and subregistries](/docs/sdk/registries-and-subregistries). ## 2. Change a subname from its parent [#2-change-a-subname-from-its-parent] [`subname.update`](/docs/reference/sdk/subname/update) changes a child's resolver or [expiry](/docs/reference/glossary#expiry) without asking its owner. `owner` changes only on ENSv1. **Example** (Repointing a Subname) ```ts title="update-subname.ts" import { createPublicClient, createWalletClient, http, type Hex } from "viem"; import { privateKeyToAccount } from "viem/accounts"; import { sepolia } from "viem/chains"; import { Ensforge, ensActions } from "@ensforge/sdk"; const account = privateKeyToAccount(process.env.PRIVATE_KEY as Hex); const transport = http(process.env.SEPOLIA_RPC_URL); const ens = Ensforge.create({ publicClient: createPublicClient({ chain: sepolia, transport }), walletClient: createWalletClient({ account, chain: sepolia, transport }), }).extend(ensActions()); await ens.subname.updateSync({ name: "pay.ensforge-docs-demo.eth", resolver: "0x1111111111111111111111111111111111111111", // a resolver you control }); ``` - `expiry` can only grow. Unwrapped ENSv1 subnames have no expiry. - An ENSv2 child's owner moves with [`name.transfer`](/docs/sdk/transfer-a-name), not with `update`. `update({ owner })` on ENSv2 fails with [`UNSUPPORTED_PROTOCOL`](/docs/reference/errors/UNSUPPORTED_PROTOCOL). - An ENSv2 child created with the default (never expires) cannot get an expiry later, because `renew` only extends. `update({ expiry })` then fails with [`INVALID_EXPIRY`](/docs/reference/errors/INVALID_EXPIRY). Pass `expiry` at creation when children should lapse. ## 3. Remove a subname [#3-remove-a-subname] [`subname.remove`](/docs/reference/sdk/subname/remove) takes a child back. On ENSv2 it also clears the child's resolver and subregistry, so nothing carries over to a later owner. **Example** (Removing a Subname) ```ts title="remove-subname.ts" import { createPublicClient, createWalletClient, http, type Hex } from "viem"; import { privateKeyToAccount } from "viem/accounts"; import { sepolia } from "viem/chains"; import { Ensforge, ensActions } from "@ensforge/sdk"; const account = privateKeyToAccount(process.env.PRIVATE_KEY as Hex); const transport = http(process.env.SEPOLIA_RPC_URL); const ens = Ensforge.create({ publicClient: createPublicClient({ chain: sepolia, transport }), walletClient: createWalletClient({ account, chain: sepolia, transport }), }).extend(ensActions()); await ens.subname.removeSync({ name: "pay.ensforge-docs-demo.eth" }); ``` A parent cannot remove an [emancipated](/docs/reference/glossary#emancipated) child: an ENSv1 child with `parentCannotControl` burned, or a child of an emancipated ENSv2 subregistry. ## Check the result [#check-the-result] Read the child with [`name.get`](/docs/reference/sdk/name/get). See [Get a name's owner, expiry and status](/docs/sdk/get-name-details). ## Troubleshooting [#troubleshooting] ### `NAME_NOT_AVAILABLE` [#name_not_available] The child already exists. Pass `upsert: true` to update it, or pick another label. See [`NAME_NOT_AVAILABLE`](/docs/reference/errors/NAME_NOT_AVAILABLE). ### `NAME_NOT_REGISTERED` or `NAME_EXPIRED` [#name_not_registered-or-name_expired] The parent is not registered. See [`NAME_NOT_REGISTERED`](/docs/reference/errors/NAME_NOT_REGISTERED) and [`NAME_EXPIRED`](/docs/reference/errors/NAME_EXPIRED). ### `INVALID_EXPIRY` [#invalid_expiry] The new expiry is lower than the current one, or the ENSv2 child never expires. See [`INVALID_EXPIRY`](/docs/reference/errors/INVALID_EXPIRY). ### `MISSING_ROLES`, `NOT_OWNER` or `FUSE_BURNED` [#missing_roles-not_owner-or-fuse_burned] The account may not create children, or a burned fuse forbids it. On a wrapped parent, an emancipated child cannot be updated until it expires. See [`MISSING_ROLES`](/docs/reference/errors/MISSING_ROLES), [`NOT_OWNER`](/docs/reference/errors/NOT_OWNER) and [`FUSE_BURNED`](/docs/reference/errors/FUSE_BURNED). ### `INVALID_RECORD_VALUE` [#invalid_record_value] `parentCannotControl` and `canExtendExpiry` need `cannotUnwrap` burned on a wrapped parent first. See [Lock permissions with fuses](/docs/sdk/fuses) and [`INVALID_RECORD_VALUE`](/docs/reference/errors/INVALID_RECORD_VALUE). ### `INVALID_ROLES` or `UNSUPPORTED_PROTOCOL` [#invalid_roles-or-unsupported_protocol] `roles` is for ENSv2 parents and `fuses` for wrapped parents. See [`INVALID_ROLES`](/docs/reference/errors/INVALID_ROLES). # Register a name > For the complete documentation index, see [llms.txt](https://ensforge.com/llms.txt). Register a .eth name with the commit, wait and register flow, optionally with records and a primary name, and resume it if it stops. Source: https://ensforge.com/docs/sdk/register-a-name You will register a new [`.eth` name](/docs/reference/glossary#eth-name), paying in an ERC-20 token. A registration is a **commit-reveal** flow: you first send a [commitment](/docs/reference/glossary#commitment), wait on-chain for it to age, then register. This stops anyone from front-running your name. ensforge runs the whole flow as one [plan](/docs/reference/glossary#plan). Every new `.eth` name is registered on [ENSv2](/docs/reference/glossary#ensv2), so you never choose a version. ## Prerequisites [#prerequisites] - A wallet client that holds the payment token and gas. See [Create a client](/docs/sdk/create-a-client). - A chain with ENSv2 deployed. The examples use Sepolia and a placeholder name. Never test with a mainnet name you care about. - A name that is available. See [Check if a name is available](/docs/sdk/check-if-a-name-is-available). ## How the flow works [#how-the-flow-works] A registration is a commit, a wait and a register, followed by optional steps. The plan has up to six steps. The wait is measured in chain time, so ensforge cannot skip it. In the diagram, your app asks the wallet to sign, and the wallet sends each transaction to the registrar. ```mermaid sequenceDiagram participant App as Your app participant W as Wallet participant R as Registrar App->>W: sign the commit step activate W W->>R: commit(commitment) deactivate W Note over App,R: the commitment must age (at least a minute of chain time) App->>W: sign the register step activate W W->>R: register(name, owner, duration) deactivate W App->>W: sign the records and primary name steps, if you asked for them W->>R: set records and primary name ``` | Step id | What it sends | | ------------- | -------------------------------------------------------------------------------------- | | `approve` | The token approval, only when the commit step does not already carry it. | | `commit` | The token approval (when the allowance is short) and the commitment. | | `resolver` | Deploys the signer's shared resolver, only for `resolver: "owned"` with a `via` route. | | `register` | Deploys each name's resolver, then registers. Waits for the commitment age first. | | `records` | Records on the owner's resolver, when `resolver` is explicit. | | `primaryName` | The reverse record, when `primaryName` is set. | By default each name gets its own [resolver](/docs/reference/glossary#resolver), deployed in the `register` step with `records` written at creation. See [Resolvers and shared records](/docs/sdk/resolvers-and-shared-records). ## 1. Register and wait [#1-register-and-wait] [`registration.registerSync`](/docs/reference/sdk/registration/register) sends every step and resolves after the last receipt. [`registration.register`](/docs/reference/sdk/registration/register) resolves as soon as the last transaction is submitted. **Example** (Registering With Records and a Primary Name) ```ts title="register.ts" import { createPublicClient, createWalletClient, http, type Hex } from "viem"; import { privateKeyToAccount } from "viem/accounts"; import { sepolia } from "viem/chains"; import { Duration, Ensforge, ensActions } from "@ensforge/sdk"; const account = privateKeyToAccount(process.env.PRIVATE_KEY as Hex); const transport = http(process.env.SEPOLIA_RPC_URL); const ens = Ensforge.create({ publicClient: createPublicClient({ chain: sepolia, transport }), walletClient: createWalletClient({ account, chain: sepolia, transport }), }).extend(ensActions()); const { names, paid, secret } = await ens.registration.registerSync({ names: "ensforge-docs-demo.eth", duration: Duration.years(1), records: { texts: { url: "https://example.com" } }, primaryName: true, onStep: (event) => console.log(event.step.id, event.status), }); ``` - `names` takes one name or an array. Several names share one plan. - `records` are written when each name's resolver is created. Their shape is the one `record.set` takes. See [Set records](/docs/sdk/set-records). - `primaryName: true` sets the single name as the signer's [primary name](/docs/reference/glossary#primary-name) and adds its `eth` address record. It needs exactly one name, owned by the signer. See [Set a primary name](/docs/sdk/set-a-primary-name). - `onStep` is called as each step waits, is submitted, is confirmed or fails. - The wallet prompts once per step, or once for several steps when it supports EIP-5792 batches. See [Send a transaction](/docs/sdk/send-a-transaction). ## 2. Read the result [#2-read-the-result] `registerSync` returns the receipts, the registered names and what you paid. | Field | Description | | ------------------------ | ------------------------------------------------------------------------------------ | | `names` | One entry per name: `name` (normalised), `tokenId` and `expiry` as a Unix timestamp. | | `paid` | The amount charged, in the payment token's smallest unit. | | `secret` | The commitment secret. Keep it if you may need to resume. | | `receipt`, `receipts` | The last receipt, and every receipt in order. | | `hash`, `hashes`, `plan` | The submitted hashes and the plan that produced them. | ## Options [#options] | Option | Type | Default | Description | | -------------- | --------------------------- | ----------------------- | --------------------------------------------------------------------------------- | | `names` | `string \| string[]` | required | `.eth` second-level names. Normalised automatically. | | `duration` | `bigint` | required | Length in seconds. Use `Duration.years(1)`. | | `owner` | `string` | the signer | Owner of the names. | | `resolver` | `string \| null` | a new resolver per name | `"owned"` uses the signer's shared resolver. `null` registers without a resolver. | | `records` | `object` | none | Records for every name. | | `primaryName` | `boolean` | `false` | Set the single name as the signer's primary name. | | `paymentToken` | `"usdc" \| "dai" \| string` | `"usdc"` | Token to pay with. The registrar does not accept ETH. | | `subregistry` | `string` | none | ENSv2 registry for the names' subnames. | | `referrer` | `Hex` | none | Referrer the registrar records: 32 bytes, or an address. | | `secret` | `Hex` | a random secret | Secret from an earlier `commit` or `register`, to finish that registration. | All write options also apply: `account`, `simulate`, `signal`, `mode`, `maxBundleCalls`, `onStep`, `via` and `paymaster`. See [How writes work](/docs/sdk/writing-to-ens). The approval covers the quote plus 2%, because the price is charged at `register` and can drift, for example while a premium decays. You pay only the actual price. ## Split the flow across sessions [#split-the-flow-across-sessions] [`registration.commit`](/docs/reference/sdk/registration/commit) sends only the first half. Use it when the user commits now and finishes later, or on another device. Keep the returned `secret`, then call `register` with exactly the same options and the `secret`. **Example** (Committing Now and Registering Later) ```ts title="commit-then-register.ts" import { createPublicClient, createWalletClient, http, type Hex } from "viem"; import { privateKeyToAccount } from "viem/accounts"; import { sepolia } from "viem/chains"; import { Duration, Ensforge, ensActions } from "@ensforge/sdk"; const account = privateKeyToAccount(process.env.PRIVATE_KEY as Hex); const transport = http(process.env.SEPOLIA_RPC_URL); const ens = Ensforge.create({ publicClient: createPublicClient({ chain: sepolia, transport }), walletClient: createWalletClient({ account, chain: sepolia, transport }), }).extend(ensActions()); const options = { names: "ensforge-docs-demo.eth", duration: Duration.years(1) }; const { secret, commitments } = await ens.registration.commitSync(options); // Later, once the commitment is ready: const [commitment] = commitments; if (commitment === undefined) throw new Error("no commitment"); const { status } = await ens.registration.getCommitmentStatus({ commitment }); if (status === "ready") { await ens.registration.registerSync({ ...options, secret }); } ``` [`registration.getCommitmentStatus`](/docs/reference/sdk/registration/get-commitment-status) reports where the commitment is in its window. | `status` | Meaning | | --------- | ----------------------------------------------------- | | `pending` | Too new to register. `readyAt` says when it is ready. | | `ready` | Register now. | | `expired` | The window passed. Commit again. | | `unknown` | Never made, or already used by a registration. | Resuming needs the same options, because they are part of the commitment. With a valid `secret`, only the `register` step is left to send. The options are hashed into the commitment. Change the owner, resolver, records or duration and the original commitment no longer matches. ## Preview before you pay [#preview-before-you-pay] `registration.register.prepare`, `.simulate` and `.estimateGas` build, simulate and price the plan without sending anything. See [Preview before sending](/docs/sdk/preview-before-sending). ## Troubleshooting [#troubleshooting] ### `NAME_NOT_AVAILABLE` [#name_not_available] The name is registered or in its [grace period](/docs/reference/glossary#grace-period). Check it first. See [`NAME_NOT_AVAILABLE`](/docs/reference/errors/NAME_NOT_AVAILABLE). ### `INSUFFICIENT_TOKEN_BALANCE` [#insufficient_token_balance] The signer cannot pay the quote in the payment token. Fund the account, or pick another `paymentToken`. See [`INSUFFICIENT_TOKEN_BALANCE`](/docs/reference/errors/INSUFFICIENT_TOKEN_BALANCE). ### `COMMITMENT_TOO_NEW` [#commitment_too_new] You resumed before the commitment aged. The error's `readyAt` is the Unix time from which `register` works. See [`COMMITMENT_TOO_NEW`](/docs/reference/errors/COMMITMENT_TOO_NEW). ### `COMMITMENT_TOO_OLD` [#commitment_too_old] The commitment expired before you registered. Commit again. See [`COMMITMENT_TOO_OLD`](/docs/reference/errors/COMMITMENT_TOO_OLD). ### `COMMITMENT_EXISTS` [#commitment_exists] An unexpired commitment with the same data already exists. Resume it with its `secret` instead of committing again. See [`COMMITMENT_EXISTS`](/docs/reference/errors/COMMITMENT_EXISTS). ### `DURATION_TOO_SHORT` [#duration_too_short] `duration` is shorter than the registrar's minimum. Read `minDuration` from `registration.getParameters`. See [`DURATION_TOO_SHORT`](/docs/reference/errors/DURATION_TOO_SHORT). ### `PAYMENT_TOKEN_UNSUPPORTED` [#payment_token_unsupported] The registrar does not accept `paymentToken`. See [`PAYMENT_TOKEN_UNSUPPORTED`](/docs/reference/errors/PAYMENT_TOKEN_UNSUPPORTED). ### `WALLET_NOT_CONFIGURED` [#wallet_not_configured] The client has no wallet client and you passed no `account`. Pass `walletClient` to `Ensforge.create`. See [`WALLET_NOT_CONFIGURED`](/docs/reference/errors/WALLET_NOT_CONFIGURED). ### `RECEIPT_TIMEOUT` or `TRANSACTION_REVERTED` [#receipt_timeout-or-transaction_reverted] `registerSync` stopped waiting, or a transaction reverted. A timed-out transaction may still confirm: check it by hash before retrying. See [Continue after a failure](/docs/sdk/continue-after-a-failure), [`RECEIPT_TIMEOUT`](/docs/reference/errors/RECEIPT_TIMEOUT) and [`TRANSACTION_REVERTED`](/docs/reference/errors/TRANSACTION_REVERTED). ### The register step reverts after the wait [#the-register-step-reverts-after-the-wait] If `owner` is a contract that rejects ERC-1155 tokens, the register step reverts after the commit was already sent. Use an owner that can receive them, such as an account or a contract that implements `onERC1155Received`. # Renew a name > For the complete documentation index, see [llms.txt](https://ensforge.com/llms.txt). Quote and renew one or more .eth names for a chosen duration, including names that are already in their grace period after expiry. Source: https://ensforge.com/docs/sdk/renew-a-name You will extend the registration of one or more [`.eth` names](/docs/reference/glossary#eth-name). Anyone can renew any name: the signer pays, and the owner does not change. ensforge picks the right contract for each name, so [ENSv1](/docs/reference/glossary#ensv1) and [ENSv2](/docs/reference/glossary#ensv2) names renew in the same call. ## Prerequisites [#prerequisites] - A wallet client that holds the payment token and gas. See [Create a client](/docs/sdk/create-a-client). - Names that are registered or in their [grace period](/docs/reference/glossary#grace-period) (the time after [expiry](/docs/reference/glossary#expiry) when the name can still be renewed and nobody else can register it). Names past the grace period are registered again, not renewed. See [Register a name](/docs/sdk/register-a-name). ## 1. Quote the renewal [#1-quote-the-renewal] [`registration.getRenewalPrice`](/docs/reference/sdk/registration/get-renewal-price) quotes any number of names in one batched call. **Example** (Quoting Two Names) ```ts title="renewal-price.ts" import { createPublicClient, http } from "viem"; import { sepolia } from "viem/chains"; import { Duration, Ensforge, ensActions } from "@ensforge/sdk"; const ens = Ensforge.create({ publicClient: createPublicClient({ chain: sepolia, transport: http() }), }).extend(ensActions()); const { total, token, items } = await ens.registration.getRenewalPrice({ names: ["ensforge-docs-demo.eth", "ensforge-docs-demo-2.eth"], duration: Duration.years(1), }); ``` Each entry of `items` has the `name`, its `amount` and its `route`: | `route` | Contract | Names | | ---------------- | ------------------------- | ---------------------------------------------- | | `"v2-registrar"` | The ENSv2 `ETHRegistrar`. | Names registered on ENSv2. | | `"v1-renewer"` | `ETHRenewerV1`. | Names still on ENSv1, including wrapped names. | ## 2. Renew [#2-renew] [`registration.renew`](/docs/reference/sdk/registration/renew) sends one `renewBatch` call per route, with a token approval for each contract whose allowance is short. `registration.renewSync` also waits for the receipts. **Example** (Renewing Two Names) ```ts title="renew.ts" import { createPublicClient, createWalletClient, http, type Hex } from "viem"; import { privateKeyToAccount } from "viem/accounts"; import { sepolia } from "viem/chains"; import { Duration, Ensforge, ensActions } from "@ensforge/sdk"; const account = privateKeyToAccount(process.env.PRIVATE_KEY as Hex); const transport = http(process.env.SEPOLIA_RPC_URL); const ens = Ensforge.create({ publicClient: createPublicClient({ chain: sepolia, transport }), walletClient: createWalletClient({ account, chain: sepolia, transport }), }).extend(ensActions()); const { hashes } = await ens.registration.renewSync({ names: ["ensforge-docs-demo.eth", "ensforge-docs-demo-2.eth"], duration: Duration.years(1), }); ``` | Option | Type | Default | Description | | -------------- | --------------------------- | -------- | --------------------------------------------------------------- | | `names` | `string \| string[]` | required | `.eth` second-level names. A name listed twice is renewed once. | | `duration` | `bigint` | required | Renewal length in seconds. | | `paymentToken` | `"usdc" \| "dai" \| string` | `"usdc"` | Token to pay with. | | `referrer` | `Hex` | none | Referrer the registrar records. | `renew` returns `{ hash, hashes, id, plan }`. `renewSync` adds `receipt` and `receipts`, the renewed `names` with their new `expiry`, and `paid`, the amount charged in the token's smallest unit. All write options apply too. See [How writes work](/docs/sdk/writing-to-ens). ## Check the result [#check-the-result] Read the name again to see its new `expiry`. See [Get a name's owner, expiry and status](/docs/sdk/get-name-details). A `.eth` owner cannot grant the `renew` role to another account (`CANNOT_GRANT_ROLES`). It is not needed: anyone can renew through the registrar. ## Troubleshooting [#troubleshooting] ### `NAME_NOT_RENEWABLE` [#name_not_renewable] A name is neither registered nor in its grace period. Register it instead. See [`NAME_NOT_RENEWABLE`](/docs/reference/errors/NAME_NOT_RENEWABLE). ### `INSUFFICIENT_TOKEN_BALANCE` [#insufficient_token_balance] The signer cannot pay the quote. See [`INSUFFICIENT_TOKEN_BALANCE`](/docs/reference/errors/INSUFFICIENT_TOKEN_BALANCE). ### `DURATION_TOO_SHORT` [#duration_too_short] `duration` is shorter than the registrar's minimum. See [`DURATION_TOO_SHORT`](/docs/reference/errors/DURATION_TOO_SHORT). ### `PAYMENT_TOKEN_UNSUPPORTED` [#payment_token_unsupported] The registrar does not accept `paymentToken`. See [`PAYMENT_TOKEN_UNSUPPORTED`](/docs/reference/errors/PAYMENT_TOKEN_UNSUPPORTED). ### `UNSUPPORTED_ON_DEPLOYMENT` [#unsupported_on_deployment] The chain has no ENSv2 deployment. See [`UNSUPPORTED_ON_DEPLOYMENT`](/docs/reference/errors/UNSUPPORTED_ON_DEPLOYMENT). # Set a primary name > For the complete documentation index, see [llms.txt](https://ensforge.com/llms.txt). Choose the name wallets and apps show for an address, on Ethereum, on every EVM chain or on an L2, including with a signed claim. Source: https://ensforge.com/docs/sdk/set-a-primary-name You will set the **primary name** of an address: the name wallets and apps show instead of `0x…`. It is stored as a **reverse record**, and readers check that the name resolves back to the address (ENSIP-19). ## Prerequisites [#prerequisites] - A wallet client for the address you are naming. See [Create a client](/docs/sdk/create-a-client). - A [name](/docs/reference/glossary#name) that resolves to that address. ensforge checks this before sending and fails with `PRIMARY_NAME_MISMATCH` otherwise. See [Set records](/docs/sdk/set-records). ## 1. Set the primary name on Ethereum [#1-set-the-primary-name-on-ethereum] [`primaryName.set`](/docs/reference/sdk/primary-name/set) sets the name for the signer. `primaryName.setSync` also waits for the receipt. **Example** (Setting Your Primary Name) ```ts title="set-primary-name.ts" import { createPublicClient, createWalletClient, http, type Hex } from "viem"; import { privateKeyToAccount } from "viem/accounts"; import { sepolia } from "viem/chains"; import { Ensforge, ensActions } from "@ensforge/sdk"; const account = privateKeyToAccount(process.env.PRIVATE_KEY as Hex); const transport = http(process.env.SEPOLIA_RPC_URL); const ens = Ensforge.create({ publicClient: createPublicClient({ chain: sepolia, transport }), walletClient: createWalletClient({ account, chain: sepolia, transport }), }).extend(ensActions()); const { hash } = await ens.primaryName.setSync({ name: "ensforge-docs-demo.eth" }); ``` Pass `name: null` to clear it. Names with encoded [labels](/docs/reference/glossary#label) (`[af2c…]`) are rejected, because readers show only [normalised](/docs/reference/glossary#normalisation) names. | Option | Type | Default | Description | | --------- | ----------------------------------- | ---------- | ----------------------------------------------------------------------- | | `name` | `string \| null` | required | The primary name, or `null` to clear it. | | `address` | `string` | the signer | The address to name. See [Name another address](#name-another-address). | | `coin` | `"eth" \| "default" \| { chainId }` | `"eth"` | Where to set it. See below. | | `verify` | `boolean` | `true` | Check that `name` resolves to the address before sending. | ## 2. Choose where it applies [#2-choose-where-it-applies] `coin` picks the chain of the primary name. | `coin` | Stored in | Applies to | | ------------------- | ------------------------------ | ------------------------------------------ | | `"eth"` (default) | `addr.reverse` | Ethereum. | | `"default"` | `default.reverse` | Every EVM chain, as a fallback (ENSIP-19). | | `{ chainId: 8453 }` | That chain's reverse registrar | That L2 only. | A name in `addr.reverse` outranks `default.reverse` on Ethereum, so `"default"` also sets `addr.reverse` when it holds a different name. A default name whose only address record is an Ethereum address verifies on Ethereum alone. The plan carries a `DEFAULT_PRIMARY_NAME_ETHEREUM_ONLY` warning in that case. ## 3. Set a primary name on an L2 [#3-set-a-primary-name-on-an-l2] An L2 primary name is a transaction on that L2, so the client needs clients for it in `chains`. The signer is the same account on every chain. **Example** (Setting a Primary Name on Base Sepolia) ```ts title="set-primary-name-l2.ts" import { createPublicClient, createWalletClient, http, type Hex } from "viem"; import { privateKeyToAccount } from "viem/accounts"; import { baseSepolia, sepolia } from "viem/chains"; import { Ensforge, ensActions } from "@ensforge/sdk"; const account = privateKeyToAccount(process.env.PRIVATE_KEY as Hex); const baseTransport = http(process.env.BASE_SEPOLIA_RPC_URL); const transport = http(process.env.SEPOLIA_RPC_URL); const ens = Ensforge.create({ publicClient: createPublicClient({ chain: sepolia, transport }), walletClient: createWalletClient({ account, chain: sepolia, transport }), chains: { [baseSepolia.id]: { publicClient: createPublicClient({ chain: baseSepolia, transport: baseTransport }), walletClient: createWalletClient({ account, chain: baseSepolia, transport: baseTransport }), }, }, }).extend(ensActions()); await ens.primaryName.setSync({ name: "ensforge-docs-demo.eth", coin: { chainId: baseSepolia.id }, }); ``` The plan is for the L2, and resumes there. Readers on Ethereum verify an L2 primary name against the L2's state as committed to Ethereum, so they see it only once that state is, which can take a while after the receipt. Supported L2s are those with an L2 reverse registrar: OP Mainnet, Base, Arbitrum One, Linea and Scroll, and their Sepolia testnets. Other chains fail with [`UNSUPPORTED_ON_DEPLOYMENT`](/docs/reference/errors/UNSUPPORTED_ON_DEPLOYMENT). ## 4. Set it on several L2s with one signature [#4-set-it-on-several-l2s-with-one-signature] [`primaryName.signClaim`](/docs/reference/sdk/primary-name/sign-claim) signs one EIP-191 message that covers several L2s, with no transaction. Anyone can then submit the claim on each chain with `primaryName.set`, so the account needs no gas or wallet connection on the L2s. **Example** (Signing One Claim for Two Chains) ```ts title="sign-claim.ts" import { createPublicClient, createWalletClient, http, type Hex } from "viem"; import { privateKeyToAccount } from "viem/accounts"; import { baseSepolia, optimismSepolia, sepolia } from "viem/chains"; import { Ensforge, ensActions } from "@ensforge/sdk"; const account = privateKeyToAccount(process.env.PRIVATE_KEY as Hex); const transport = http(process.env.SEPOLIA_RPC_URL); const ens = Ensforge.create({ publicClient: createPublicClient({ chain: sepolia, transport }), walletClient: createWalletClient({ account, chain: sepolia, transport }), chains: { [baseSepolia.id]: { publicClient: createPublicClient({ chain: baseSepolia, transport: http() }), walletClient: createWalletClient({ account, chain: baseSepolia, transport: http() }), }, [optimismSepolia.id]: { publicClient: createPublicClient({ chain: optimismSepolia, transport: http() }), walletClient: createWalletClient({ account, chain: optimismSepolia, transport: http() }), }, }, }).extend(ensActions()); const signed = await ens.primaryName.signClaim({ name: "ensforge-docs-demo.eth", chainIds: [baseSepolia.id, optimismSepolia.id], }); await ens.primaryName.set({ ...signed, coin: { chainId: baseSepolia.id } }); await ens.primaryName.set({ ...signed, coin: { chainId: optimismSepolia.id } }); ``` - Every mainnet L2 shares one registrar, and testnets share another. One claim cannot mix mainnet chains and testnets, and it cannot include the ENS chain. - The claim expires `expiresIn` seconds after signing, at most one hour (`3600n`, the default). - Smart accounts sign as themselves (ERC-1271, or ERC-6492 before they are deployed). The account must exist, or be deployable, on each L2. ### Relay a claim from a server [#relay-a-claim-from-a-server] The claim is plain JSON. The app signs and posts it. A server with a funded wallet on the L2 submits it. **Example** (Relaying a Signed Claim) ```ts title="relay-claim.ts" import { createPublicClient, createWalletClient, http, type Hex } from "viem"; import { privateKeyToAccount } from "viem/accounts"; import { baseSepolia, sepolia } from "viem/chains"; import { Ensforge, ensActions } from "@ensforge/sdk"; const relayerAccount = privateKeyToAccount(process.env.RELAYER_PRIVATE_KEY as Hex); const relayer = Ensforge.create({ publicClient: createPublicClient({ chain: sepolia, transport: http() }), chains: { [baseSepolia.id]: { publicClient: createPublicClient({ chain: baseSepolia, transport: http() }), walletClient: createWalletClient({ account: relayerAccount, chain: baseSepolia, transport: http(), }), }, }, }).extend(ensActions()); export async function relayClaim(body: string) { const { claim, signature } = JSON.parse(body); return relayer.primaryName.set({ claim, signature, coin: { chainId: baseSepolia.id } }); } ``` `relayer` is a client whose `chains` holds a funded wallet for that L2, and the relayer pays the gas. Validate the posted body before you submit it. The signature, not the sender, authorises the name. ## Name another address [#name-another-address] `address` names another account. The signer must be the address's registry operator or, for a contract, its `Ownable` owner or its ContractNamer. Any other signer fails before sending with [`NOT_APPROVED`](/docs/reference/errors/NOT_APPROVED). For `"eth"`, a ContractNamer goes through the ENSv2 adapter: it claims the contract's `addr.reverse` node, which makes the signer that node's owner, then sets the name. Those two dependent calls can only be simulated on an RPC that supports `eth_simulateV1`, or with `simulate: false`. ## Check the result [#check-the-result] Read it back with [`primaryName.get`](/docs/reference/sdk/primary-name/get). See [Get the name for an address](/docs/sdk/get-a-primary-name). ## Troubleshooting [#troubleshooting] ### `PRIMARY_NAME_MISMATCH` [#primary_name_mismatch] The name does not resolve to the address. Add an address record with `record.set`, then set the primary name. For an L2, the name needs an address for that chain's coin type or a default EVM address. See [`PRIMARY_NAME_MISMATCH`](/docs/reference/errors/PRIMARY_NAME_MISMATCH). ### `CHAIN_NOT_CONFIGURED` [#chain_not_configured] The L2 is not in the client's `chains`. Add it to `Ensforge.create`, or to the wagmi config with `fromWagmi`. See [`CHAIN_NOT_CONFIGURED`](/docs/reference/errors/CHAIN_NOT_CONFIGURED). ### `INVALID_COIN_TYPE` [#invalid_coin_type] `coin` is not an EVM chain, or the claim does not cover the chain. For `signClaim`, `chainIds` is empty, includes the ENS chain, or mixes mainnet and testnets. See [`INVALID_COIN_TYPE`](/docs/reference/errors/INVALID_COIN_TYPE). ### `SIGNATURE_INVALID` or `SIGNATURE_EXPIRED` [#signature_invalid-or-signature_expired] The claim's signature does not match, or the claim has expired. Sign again, for the same name, chains and expiry. See [`SIGNATURE_INVALID`](/docs/reference/errors/SIGNATURE_INVALID) and [`SIGNATURE_EXPIRED`](/docs/reference/errors/SIGNATURE_EXPIRED). ### `INVALID_DURATION` [#invalid_duration] `expiresIn` is not between 1 and 3600 seconds. See [`INVALID_DURATION`](/docs/reference/errors/INVALID_DURATION). ### `NOT_APPROVED` [#not_approved] The signer may not name `address`. See [Name another address](#name-another-address) and [`NOT_APPROVED`](/docs/reference/errors/NOT_APPROVED). Setting L2 primary names through an [HCA](/docs/reference/glossary#hca) (`via: hca()`) is not supported, because the HCA lives on Ethereum. The contracts-v2 L2 registrar is not deployed. # Set records > For the complete documentation index, see [llms.txt](https://ensforge.com/llms.txt). Write text, address and content hash records to a name you manage, or delete them, in one transaction with one wallet prompt. Source: https://ensforge.com/docs/sdk/set-records You will write [records](/docs/reference/glossary#record) (a website, an avatar, an address, a content hash) to a name you can edit. ensforge writes them all in one `multicall` on the name's [resolver](/docs/reference/glossary#resolver), and detects whether that resolver is an [ENSv1](/docs/reference/glossary#ensv1) resolver or an [ENSv2](/docs/reference/glossary#ensv2) PermissionedResolver. You do not choose. ## Prerequisites [#prerequisites] - A wallet client for an account that may edit the name's records. See [Create a client](/docs/sdk/create-a-client). - A registered name with a resolver of its own. See [Register a name](/docs/sdk/register-a-name). ## 1. Write the records [#1-write-the-records] [`record.set`](/docs/reference/sdk/record/set) takes the name and any mix of record kinds. `record.setSync` also waits for the receipt. **Example** (Updating a Profile) ```ts title="set-records.ts" import { createPublicClient, createWalletClient, http, type Hex } from "viem"; import { privateKeyToAccount } from "viem/accounts"; import { sepolia } from "viem/chains"; import { Ensforge, ensActions } from "@ensforge/sdk"; const account = privateKeyToAccount(process.env.PRIVATE_KEY as Hex); const transport = http(process.env.SEPOLIA_RPC_URL); const ens = Ensforge.create({ publicClient: createPublicClient({ chain: sepolia, transport }), walletClient: createWalletClient({ account, chain: sepolia, transport }), }).extend(ensActions()); const { hash } = await ens.record.setSync({ name: "ensforge-docs-demo.eth", texts: { url: "https://example.com", avatar: "https://example.com/avatar.png" }, addresses: { eth: account.address }, contentHash: "ipfs://bafybeigdyrzt5sfp7udm7hu76uh7y26nf3efuylqabf3oclgtqy55fbzdi", }); ``` - `texts` maps a key to a string. The key `avatar` sets the name's [avatar](/docs/reference/glossary#avatar). - `addresses` maps a coin symbol (`eth`, `btc`) or a decimal **coin type** (`"2147492101"`) to an address. ensforge validates and encodes it for that chain. - `contentHash` takes a URI such as `ipfs://…`. | Option | Type | Description | | ------------- | -------------------------------- | ------------------------------------------------------ | | `name` | `string` | The name to update. Normalised automatically. | | `texts` | `Record` | Text records by key. | | `addresses` | `Record` | Address records by coin symbol or coin type. | | `contentHash` | `string \| null` | Content hash URI. | | `abi` | `{ contentType?, value }` | ABI record (ENSIP-4). An `Abi` is stored as JSON. | | `pubkey` | `{ x, y } \| null` | SECP256k1 public key. Not on the PermissionedResolver. | | `nameRecord` | `string \| null` | The `name` record, used by reverse names. | | `interfaces` | `Record` | ERC-165 implementers by 4-byte interface ID. | | `data` | `Record` | Data records (ENSIP-24) by key. | | `clear` | `boolean` | Delete every existing record first. | | `resolver` | `Address \| "default"` | Write to this resolver, then point the name at it. | ## 2. Delete records [#2-delete-records] Pass `null` to delete a record. `clear: true` deletes every record first, then writes the rest. **Example** (Deleting a Record) ```ts title="delete-record.ts" import { createPublicClient, createWalletClient, http, type Hex } from "viem"; import { privateKeyToAccount } from "viem/accounts"; import { sepolia } from "viem/chains"; import { Ensforge, ensActions } from "@ensforge/sdk"; const account = privateKeyToAccount(process.env.PRIVATE_KEY as Hex); const transport = http(process.env.SEPOLIA_RPC_URL); const ens = Ensforge.create({ publicClient: createPublicClient({ chain: sepolia, transport }), walletClient: createWalletClient({ account, chain: sepolia, transport }), }).extend(ensActions()); await ens.record.setSync({ name: "ensforge-docs-demo.eth", texts: { url: null }, }); ``` On an ENSv2 PermissionedResolver, `clear` links the name to record 0 instead of deleting. The name then reads the resolver's default record, which is empty unless someone set it. It also needs the root `link` [role](/docs/reference/glossary#role). ## 3. Write to a new resolver and switch to it [#3-write-to-a-new-resolver-and-switch-to-it] `resolver` writes the records to another resolver, then points the name at it, in one step. A rejected write never leaves the name on an empty resolver. **Example** (Moving to a New Resolver With Records) ```ts title="set-records-resolver.ts" import { createPublicClient, createWalletClient, http, type Hex } from "viem"; import { privateKeyToAccount } from "viem/accounts"; import { sepolia } from "viem/chains"; import { Ensforge, ensActions } from "@ensforge/sdk"; const account = privateKeyToAccount(process.env.PRIVATE_KEY as Hex); const transport = http(process.env.SEPOLIA_RPC_URL); const ens = Ensforge.create({ publicClient: createPublicClient({ chain: sepolia, transport }), walletClient: createWalletClient({ account, chain: sepolia, transport }), }).extend(ensActions()); await ens.record.setSync({ name: "ensforge-docs-demo.eth", resolver: "0x1111111111111111111111111111111111111111", // a resolver you control texts: { url: "https://example.com" }, }); ``` `resolver: "default"` is the ENSv1 public resolver, for ENSv1 names only. ENSv2 names pass the address of a resolver such as their own PermissionedResolver. See [Change the resolver](/docs/sdk/change-the-resolver). ## What ensforge checks first [#what-ensforge-checks-first] - Each kind of record is checked against the profiles the resolver declares through ERC-165, and `clear` against its record versions, before anything is simulated. A resolver that does not declare ERC-165 is left to the simulation. - The plan is simulated before the wallet prompt, so permission errors appear first. - Records go to the resolver set on the name in its registry, never to a wildcard resolver inherited from a parent. ## Check the result [#check-the-result] Read the records back with [`record.get`](/docs/reference/sdk/record/get). See [Get text records](/docs/sdk/get-text-records) and [Get a name's address](/docs/sdk/get-an-address). ## Troubleshooting [#troubleshooting] ### `RESOLVER_PROFILE_UNSUPPORTED` [#resolver_profile_unsupported] The resolver cannot store this kind of record, or keeps its records off-chain. Older resolvers lack newer profiles: the 2020 public resolver has no `data` records and cannot `clear`. Resolvers that keep records off-chain (EIP-3668, ERC-5559, ERC-7884) take no on-chain writes, and the error's details say where the records live. Point the name at a resolver that supports the record. See [`RESOLVER_PROFILE_UNSUPPORTED`](/docs/reference/errors/RESOLVER_PROFILE_UNSUPPORTED) and [Change the resolver](/docs/sdk/change-the-resolver). ### `RESOLVER_NOT_FOUND` [#resolver_not_found] The name has no resolver of its own. Pass `resolver`, or create one. See [`RESOLVER_NOT_FOUND`](/docs/reference/errors/RESOLVER_NOT_FOUND). ### `NOT_OWNER` or `MISSING_ROLES` [#not_owner-or-missing_roles] The account may not edit the records. On a PermissionedResolver the account needs the setter roles. See [Roles and permissions](/docs/sdk/roles-and-permissions), [`NOT_OWNER`](/docs/reference/errors/NOT_OWNER) and [`MISSING_ROLES`](/docs/reference/errors/MISSING_ROLES). ### `INVALID_COIN_TYPE`, `INVALID_ADDRESS` or `INVALID_CONTENT_HASH` [#invalid_coin_type-invalid_address-or-invalid_content_hash] A coin, address or content hash does not parse. See [`INVALID_COIN_TYPE`](/docs/reference/errors/INVALID_COIN_TYPE), [`INVALID_ADDRESS`](/docs/reference/errors/INVALID_ADDRESS) and [`INVALID_CONTENT_HASH`](/docs/reference/errors/INVALID_CONTENT_HASH). ### `UNSUPPORTED_PROTOCOL` [#unsupported_protocol] You passed `resolver: "default"` for an ENSv2 name. Pass a resolver address. See [`UNSUPPORTED_PROTOCOL`](/docs/reference/errors/UNSUPPORTED_PROTOCOL). # Transfer a name > For the complete documentation index, see [llms.txt](https://ensforge.com/llms.txt). Send a name to another account, or hand its manager role or its record control to someone else, and check the new owner afterwards. Source: https://ensforge.com/docs/sdk/transfer-a-name You will send a [name](/docs/reference/glossary#name) you own to another address. ensforge moves the right token for the name's kind, so one call works for [ENSv2](/docs/reference/glossary#ensv2) names, unwrapped [ENSv1](/docs/reference/glossary#ensv1) names and wrapped names. ## Prerequisites [#prerequisites] - A wallet client for the account that owns the name. See [Create a client](/docs/sdk/create-a-client). - A registered name. Expired, reserved and unregistered names cannot be transferred. ## 1. Send the name [#1-send-the-name] [`name.transfer`](/docs/reference/sdk/name/transfer) takes the name and the recipient. `name.transferSync` also waits for the receipt. **Example** (Sending a Name) ```ts title="transfer.ts" import { createPublicClient, createWalletClient, http, type Hex } from "viem"; import { privateKeyToAccount } from "viem/accounts"; import { sepolia } from "viem/chains"; import { Ensforge, ensActions } from "@ensforge/sdk"; const account = privateKeyToAccount(process.env.PRIVATE_KEY as Hex); const transport = http(process.env.SEPOLIA_RPC_URL); const ens = Ensforge.create({ publicClient: createPublicClient({ chain: sepolia, transport }), walletClient: createWalletClient({ account, chain: sepolia, transport }), }).extend(ensActions()); const { hash } = await ens.name.transfer({ name: "ensforge-docs-demo.eth", to: "0xB0b0000000000000000000000000000000000000", }); ``` What moves depends on where the name lives: | Name | What `transfer` moves | | ------------------------------ | ------------------------------------------------------------- | | On ENSv2 | The name's registry token. | | Wrapped on ENSv1 | The NameWrapper token. | | Unwrapped `.eth` name on ENSv1 | The registrar token and the registry ownership (the manager). | | Other unwrapped ENSv1 name | The registry owner. | | Option | Type | Default | Description | | --------- | ------------------------- | --------- | --------------------------------------------------------------------------- | | `name` | `string` | required | The name to send. Normalised automatically. | | `to` | `string` | required | The recipient address. | | `role` | `"owner" \| "registrant"` | `"owner"` | Unwrapped `.eth` names only. `"registrant"` moves only the registrar token. | | `unsafe` | `boolean` | `false` | ENSv2 only. Send even while other accounts still hold roles on the name. | | `records` | `"keep" \| "handover"` | `"keep"` | ENSv2 only. What happens to the sender's roles on the name's resolver. | ## 2. Decide who keeps control of the records [#2-decide-who-keeps-control-of-the-records] On ENSv2, a name's [resolver](/docs/reference/glossary#resolver) has its own [roles](/docs/reference/glossary#role). By default they stay with the sender, who can still edit the records after the transfer. The plan carries a `RECORD_CONTROL_RETAINED` warning. Pass `records: "handover"` to grant them to the recipient and revoke the sender's in the same step. **Example** (Handing Over Record Control) ```ts title="transfer-handover.ts" import { createPublicClient, createWalletClient, http, type Hex } from "viem"; import { privateKeyToAccount } from "viem/accounts"; import { sepolia } from "viem/chains"; import { Ensforge, ensActions } from "@ensforge/sdk"; const account = privateKeyToAccount(process.env.PRIVATE_KEY as Hex); const transport = http(process.env.SEPOLIA_RPC_URL); const ens = Ensforge.create({ publicClient: createPublicClient({ chain: sepolia, transport }), walletClient: createWalletClient({ account, chain: sepolia, transport }), }).extend(ensActions()); await ens.name.transferSync({ name: "ensforge-docs-demo.eth", to: "0xB0b0000000000000000000000000000000000000", records: "handover", }); ``` `"handover"` is refused for the sender's shared `"owned"` resolver, because its roles cover other names too. See [Resolvers and shared records](/docs/sdk/resolvers-and-shared-records). ## Give only the registrar token (ENSv1) [#give-only-the-registrar-token-ensv1] An unwrapped `.eth` name on ENSv1 has two holders. The [registrant](/docs/reference/glossary#registrant) holds the registrar token and owns the name. The [manager](/docs/reference/glossary#manager) is the registry owner and edits records and subnames. See [Who can change a name](/docs/sdk/who-can-change-a-name). - `role: "registrant"` on `name.transfer` moves only the registrar token. - [`name.setManager`](/docs/reference/sdk/name/set-manager) lets another account edit records and subnames while you keep ownership. - [`name.reclaim`](/docs/reference/sdk/name/reclaim) resets the manager to the registrant (or to `owner`). Use it after receiving a registrar token, or to repair a lost manager. `setManager` and `reclaim` fail with [`UNSUPPORTED_PROTOCOL`](/docs/reference/errors/UNSUPPORTED_PROTOCOL) for ENSv2 names and wrapped names, and `reclaim` also for names that are not `.eth` names. ENSv2 uses roles instead. See [Roles and permissions](/docs/sdk/roles-and-permissions). ## Check the result [#check-the-result] Read the name with [`name.get`](/docs/reference/sdk/name/get) and compare `owner` with the recipient. See [Get a name's owner, expiry and status](/docs/sdk/get-name-details). ## Troubleshooting [#troubleshooting] ### `NOT_OWNER` [#not_owner] The signer does not own the name. Send from the owner's account. See [`NOT_OWNER`](/docs/reference/errors/NOT_OWNER). ### `TRANSFER_DISALLOWED` [#transfer_disallowed] The owner lacks the role to transfer, other accounts hold roles on an ENSv2 name, or the recipient (an HCA) refuses it. Revoke the other roles, or pass `unsafe: true`. See [`TRANSFER_DISALLOWED`](/docs/reference/errors/TRANSFER_DISALLOWED). ### `NAME_EXPIRED`, `NAME_RESERVED` or `NAME_NOT_REGISTERED` [#name_expired-name_reserved-or-name_not_registered] Only registered names can be sent. See [`NAME_EXPIRED`](/docs/reference/errors/NAME_EXPIRED), [`NAME_RESERVED`](/docs/reference/errors/NAME_RESERVED) and [`NAME_NOT_REGISTERED`](/docs/reference/errors/NAME_NOT_REGISTERED). ### `UNSUPPORTED_PROTOCOL` [#unsupported_protocol] You passed `role: "registrant"` for a name that has no registrant. See [`UNSUPPORTED_PROTOCOL`](/docs/reference/errors/UNSUPPORTED_PROTOCOL). ### `INVALID_ADDRESS` [#invalid_address] `to` is not an address. See [`INVALID_ADDRESS`](/docs/reference/errors/INVALID_ADDRESS). # Use a DNS name > For the complete documentation index, see [llms.txt](https://ensforge.com/llms.txt). Import a DNS name such as example.com into ENS with a DNSSEC proof, claim it for an owner, and then manage its records on ENS. Source: https://ensforge.com/docs/sdk/use-a-dns-name You will import a DNS name you own into ENS, so it can have an [owner](/docs/reference/glossary#owner), a [resolver](/docs/reference/glossary#resolver) and [records](/docs/reference/glossary#record) like any other name. You prove ownership with a **DNSSEC** proof of a TXT record in your DNS zone, and ensforge fetches and sends the proof for you. DNS names are imported into [ENSv1](/docs/reference/glossary#ensv1). [ENSv2](/docs/reference/glossary#ensv2) resolves them through the ENSv1 [registry](/docs/reference/glossary#registry), so you do not choose a version. ## Prerequisites [#prerequisites] - A DNS name whose zone uses DNSSEC. - A wallet client. Anyone can send the claim: the name goes to the address in the TXT record. See [Create a client](/docs/sdk/create-a-client). - A chain with a DNSSEC [gateway](/docs/reference/glossary#gateway) in its deployment, or your own `gatewayUrls`. The mainnet and Sepolia deployments list their gateways on-chain. Without either, the DNS actions fail with [`UNSUPPORTED_ON_DEPLOYMENT`](/docs/reference/errors/UNSUPPORTED_ON_DEPLOYMENT). Since the DNSSEC root KSK rollover in October 2026, the on-chain DNSSEC oracle on mainnet and Sepolia cannot verify any proof: it lacks the new root key. `dns.getStatus` reports `proof-invalid` and `dns.claim` fails with `DNSSEC_PROOF_FAILED` until ENS adds the trust anchor. ensforge has no client-side workaround. See [`DNSSEC_PROOF_FAILED`](/docs/reference/errors/DNSSEC_PROOF_FAILED). ## 1. Check what the name needs [#1-check-what-the-name-needs] [`dns.getStatus`](/docs/reference/sdk/dns/get-status) compares the ENSv1 registry owner with the address in the `_ens` TXT record, and verifies the record's proof against the on-chain DNSSEC oracle. **Example** (Checking a DNS Name) ```ts title="dns-status.ts" import { createPublicClient, http } from "viem"; import { sepolia } from "viem/chains"; import { Ensforge, ensActions } from "@ensforge/sdk"; const ens = Ensforge.create({ publicClient: createPublicClient({ chain: sepolia, transport: http() }), }).extend(ensActions()); const status = await ens.dns.getStatus({ name: "example.com" }); ``` `status.action` is the next step: | `action` | What to do | | ---------------- | --------------------------------------------------------------------------------------- | | `set-txt-record` | Add the TXT record in step 2. | | `claim` | Import the name (step 3), or re-import it to move it to the address in its TXT record. | | `proof-invalid` | The TXT record exists, but its proof does not verify on-chain. Do not send a claim yet. | | `none` | The name is imported and owned by the address in its TXT record. | `status` also has `imported`, `owner` (the ENSv1 registry owner), `dnsOwner` (the address in the TXT record) and `proofValid`. ## 2. Add the TXT record [#2-add-the-txt-record] In your DNS zone, add a TXT record at `_ens.` with the value `a=
`. The address becomes the owner. For `example.com` it is the record `_ens.example.com`. ```text title="DNS record" _ens.example.com. TXT "a=0xB0b0000000000000000000000000000000000000" ``` ## 3. Claim the name [#3-claim-the-name] [`dns.claim`](/docs/reference/sdk/dns/claim) fetches the proof from the deployment's DNSSEC gateway and sends it. `dns.claimSync` also waits for the receipt. **Example** (Claiming a DNS Name) ```ts title="dns-claim.ts" import { createPublicClient, createWalletClient, http, type Hex } from "viem"; import { privateKeyToAccount } from "viem/accounts"; import { sepolia } from "viem/chains"; import { Ensforge, ensActions } from "@ensforge/sdk"; const account = privateKeyToAccount(process.env.PRIVATE_KEY as Hex); const transport = http(process.env.SEPOLIA_RPC_URL); const ens = Ensforge.create({ publicClient: createPublicClient({ chain: sepolia, transport }), walletClient: createWalletClient({ account, chain: sepolia, transport }), }).extend(ensActions()); const status = await ens.dns.getStatus({ name: "example.com" }); if (status.action === "claim") { await ens.dns.claimSync({ name: "example.com" }); } ``` | Option | Type | Description | | ------------- | ---------- | -------------------------------------------------------------------------------------- | | `name` | `string` | The DNS name. Normalised automatically. | | `proof` | `Proof` | A proof from `dns.getProof`, instead of fetching one. | | `resolver` | `string` | A resolver to set while claiming. Only the DNS owner may send a claim with a resolver. | | `gatewayUrls` | `string[]` | DNSSEC gateways to fetch the proof from, instead of the deployment's. | [`dns.getProof`](/docs/reference/sdk/dns/get-proof) fetches a proof without sending anything. It does not verify the proof: `dns.getStatus` does. `dns.claim` cannot set an address record while claiming. Set records afterwards with [`record.set`](/docs/sdk/set-records). ## Use a gasless DNS name [#use-a-gasless-dns-name] A gasless DNS name resolves without being imported, as an [off-chain name](/docs/reference/glossary#off-chain-name). Its owner adds a TXT record `ENS1 [context]` on the name itself. [`dns.getOffchainResolver`](/docs/reference/sdk/dns/get-offchain-resolver) reads it and returns `{ resolver, context }`, or `null` when there is none. **Example** (Reading a Gasless DNS Setup) ```ts title="dns-offchain.ts" import { createPublicClient, http } from "viem"; import { sepolia } from "viem/chains"; import { Ensforge, ensActions } from "@ensforge/sdk"; const ens = Ensforge.create({ publicClient: createPublicClient({ chain: sepolia, transport: http() }), }).extend(ensActions()); const offchain = await ens.dns.getOffchainResolver({ name: "example.com" }); ``` The record is read through the DNSSEC gateway without on-chain verification. See [Look up off-chain names](/docs/sdk/off-chain-names). ## Host DNS records in ENS [#host-dns-records-in-ens] [`dns.setRecords`](/docs/reference/sdk/dns/set-records) stores resource records, or a zonehash, on an ENS name's public resolver, for DNS servers that read them from ENS. Records are in DNS wire format. `zonehash: null` clears the zonehash. Only the ENS public resolvers store DNS records. ## Check the result [#check-the-result] Call `dns.getStatus` again. `action` is `none` and `imported` is `true` when the claim worked. Then read the name with [`name.get`](/docs/reference/sdk/name/get). ## Troubleshooting [#troubleshooting] ### `DNS_RECORD_MISSING` [#dns_record_missing] The `_ens` TXT record is missing, or its value does not parse as `a=
`. Add it and wait for DNS to update. See [`DNS_RECORD_MISSING`](/docs/reference/errors/DNS_RECORD_MISSING). ### `PROOF_STALE` [#proof_stale] The proof is older than the one already on-chain. Fetch a fresh proof and retry. See [`PROOF_STALE`](/docs/reference/errors/PROOF_STALE). ### `DNSSEC_PROOF_FAILED` [#dnssec_proof_failed] The proof could not be built or verified. Check that DNSSEC is enabled for the domain, and see the warning at the top of this page. See [`DNSSEC_PROOF_FAILED`](/docs/reference/errors/DNSSEC_PROOF_FAILED). ### `TLD_NOT_PUBLIC` [#tld_not_public] The name's top-level domain is not a public suffix, so it cannot be imported. See [`TLD_NOT_PUBLIC`](/docs/reference/errors/TLD_NOT_PUBLIC). ### `GATEWAY_REQUEST_FAILED` or `GATEWAY_RESPONSE_INVALID` [#gateway_request_failed-or-gateway_response_invalid] The DNSSEC gateway failed or answered with data that does not parse. Retry, or pass another `gatewayUrls`. See [`GATEWAY_REQUEST_FAILED`](/docs/reference/errors/GATEWAY_REQUEST_FAILED) and [`GATEWAY_RESPONSE_INVALID`](/docs/reference/errors/GATEWAY_RESPONSE_INVALID). ### `NOT_OWNER` [#not_owner] You passed `resolver`, but the sender is not the DNS owner. Claim without `resolver`, or send from the address in the TXT record. See [`NOT_OWNER`](/docs/reference/errors/NOT_OWNER). # From ensforge 0.x > For the complete documentation index, see [llms.txt](https://ensforge.com/llms.txt). Move an app from ensforge 0.x (@ensforge/core and the Ensforge class) to the 1.0 client and actions, with before and after code. Source: https://ensforge.com/docs/sdk/from-ensforge-0x ensforge 1.0 is a new API. Reads and writes are simpler and more uniform, and errors are typed by code. This guide maps every 0.x concept to its 1.0 form, with before and after code. The code marked `before` is the 0.x API as published in `@ensforge/sdk@0.6.1` and `@ensforge/core@0.6.1`. Code blocks that mark lines with `[!code --]` and `[!code ++]` are diffs: they show the old and the new line together, so the docs build does not compile them. ## What changed [#what-changed] | 0.x | 1.0 | | ----------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- | | `@ensforge/core` (actions) and `@ensforge/sdk` (the `Ensforge` class) | One package, `@ensforge/sdk`. `@ensforge/core` is gone. | | `new Ensforge({ network, publicClient })` or `createConfig` | `Ensforge.create({ publicClient })`. The chain of the public client picks the deployment. | | Groups on the instance: `sdk.records`, `sdk.name`, `sdk.resolution`, `sdk.reverse` … | Decorators you add: `.extend(ensActions())`. Groups are `record`, `name`, `resolver`, `primaryName`, `registration`, `subname`, `wrapper` and more. | | One setter per record kind (`setText`, `setAddress`, `setContentHash` …) | One action, `record.set`, with `texts`, `addresses`, `contentHash` and more. | | Writes that waited for the receipt by default, with `status`, `hash` and `receipt` | Writes resolve once submitted with `Write.Result` (`hash`, `hashes`, `id`, `plan`). The `…Sync` form waits for receipts. | | `writes: { simulation, confirmation }` in the config | `simulate` and `…Sync` per call or per client. | | Workflows (`sdk.workflows`) | [Plans](/docs/reference/glossary#plan) (`plan.get`, `plan.list`, `plan.resume`). | | `ContractError`, `RpcError`, `NameError` … | `Errors.*` classes with stable codes. | | `createEnsforge` from `@ensforge/sdk/wagmi`, or `createWagmiConfig` from `@ensforge/core/wagmi` | `Ensforge.fromWagmi` from `@ensforge/sdk/wagmi`. | | [HCA](/docs/reference/glossary#hca) actions on `sdk.hca` | The `@ensforge/hca` package, as `ens.hca.*` and `via: hca()`. | ## 1. Update the packages [#1-update-the-packages] ```sh title="terminal" pnpm remove @ensforge/core pnpm add @ensforge/sdk@latest ``` Also update `@ensforge/react` and `@ensforge/contracts` to 1.x. The public packages version together. ## 2. Create the client [#2-create-the-client] The 0.x `network` option is gone. The public client's chain picks the deployment (Ethereum mainnet or Sepolia). For another chain, pass `deployment`. ```ts no-check title="client.ts" import { Ensforge } from "@ensforge/sdk"; // [!code --] import { Ensforge, ensActions } from "@ensforge/sdk"; // [!code ++] import { createPublicClient, http } from "viem"; import { mainnet } from "viem/chains"; const publicClient = createPublicClient({ chain: mainnet, transport: http() }); const sdk = new Ensforge({ network: "mainnet", publicClient }); // [!code --] const ens = Ensforge.create({ publicClient }).extend(ensActions()); // [!code ++] ``` Other options moved too: | 0.x | 1.0 | | ---------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------- | | `network` | Gone. The public client's chain picks the deployment, or pass `deployment`. | | `walletClient` | `walletClient` (also a function for wallets that connect later) | | `reads: { concurrency, multicallBatchSize }` | `batch: { multicall: { batchSize, wait } }`. See [Configure RPC and gateways](/docs/sdk/rpc-and-gateways). | | `gateways` (allowed hosts and limits for gateway requests) | No counterpart. 1.0 `gateways` sets storage gateways for avatars and content hashes, and `ccipRead` sets the off-chain lookup gateways. | | `writes.simulation: "required" \| "skip"` | `simulate: true \| false` | | `writes.confirmation` | The `…Sync` form of a write, with `confirmations` and `timeout`. | | `storage` (workflow storage) | `storage` (plan storage). See [Save and resume plans](/docs/sdk/save-and-resume-plans). | | `indexer` (GraphQL endpoints) or `false` | `indexer: bigname()`, `goldsky()`, `fallback([...])` from `@ensforge/sdk/indexer`. Without it, no indexer. | | `hca` | The `@ensforge/hca` package. | ## 3. Reads [#3-reads] Reads return the value, not a wrapper. A missing value is `null`. ```ts no-check title="reads.ts" const { address } = await sdk.records.getAddress({ name: "nick.eth" }); // [!code --] const address = await ens.record.getAddress({ name: "nick.eth" }); // [!code ++] const { owner } = await sdk.name.getOwner({ name: "nick.eth" }); // [!code --] const { owner } = await ens.name.get({ name: "nick.eth" }); // [!code ++] const primary = await sdk.reverse.getPrimaryName({ address }); // [!code --] const primary = await ens.primaryName.get({ address }); // [!code ++] ``` - `getAddress` took `coinType`. 1.0 takes `coin`: a symbol (`"btc"`), a chain (`{ chainId: 8453 }`) or a coin type. See [Get a name's address](/docs/sdk/get-an-address). - `getPrimaryName` returned `{ name, match }` or `null`. 1.0 returns the name, or `null`, and checks that the name resolves back to the address by default (`verify`). - `name.get` returns the whole state in one call: `owner`, `manager`, `registrant`, `expiry`, `resolver`, `wrapped`, `available`, `renewable` and more. The single-fact reads of 0.x (`getOwner`, `getExpiry`, `isWrapped` …) map to its fields. See [Get a name's owner, expiry and status](/docs/sdk/get-name-details). ### Batched reads [#batched-reads] `readBatch` returned a record of values. `batch` returns `{ results }`, where each result is `{ status: "success", result }` or `{ status: "failure", error }` by default. `readBatchSettled` returned `{ status, value }` outcomes; 1.0 names the field `result`. ```ts no-check title="batch.ts" const profile = await sdk.batch.readBatch({ // [!code --] owner: sdk.name.getOwner.request({ name: "nick.eth" }), // [!code --] }); // [!code --] const { results } = await ens.batch({ // [!code ++] requests: { owner: Actions.name.get.request({ name: "nick.eth" }) }, // [!code ++] allowFailure: false, // [!code ++] }); // [!code ++] ``` `Actions` comes from `@ensforge/sdk`. Settled results are now the default (`allowFailure: true`), and `allowFailure: false` behaves like `readBatch`. See [Look up many at once](/docs/sdk/look-up-many-at-once). ## 4. Writes [#4-writes] One `record.set` replaces the setters. 0.x writes waited for the receipt by default (`confirmation: { type: "confirmed" }`). 1.0 writes resolve once submitted. Use `…Sync` to wait for the receipt, as the examples below do. ```ts no-check title="writes.ts" await sdk.records.setText({ name: "ensforge-docs-demo.eth", key: "url", value: "https://example.com", }); // [!code --] await ens.record.setSync({ name: "ensforge-docs-demo.eth", texts: { url: "https://example.com" } }); // [!code ++] await sdk.records.setAddress({ name: "ensforge-docs-demo.eth", coinType: 60n, address }); // [!code --] await ens.record.setSync({ name: "ensforge-docs-demo.eth", addresses: { eth: address } }); // [!code ++] ``` See [Set records](/docs/sdk/set-records) and [Send a transaction](/docs/sdk/send-a-transaction). ### Where each 0.x action went [#where-each-0x-action-went] | 0.x group and actions | 1.0 | | -------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- | | `records.get*` | [`record.get`](/docs/reference/sdk/record/get), `record.getText`, `record.getAddress`, `record.getAvatar`, `record.getContentHash` | | `records.set*`, `records.clearRecords`, `records.clearAvatar` | [`record.set`](/docs/reference/sdk/record/set) (`null` deletes a value; `clear: true` deletes everything first) | | `name.getOwner`, `getManager`, `getRegistrant`, `getExpiry`, `getNameState`, `isWrapped`, `isMigrated` … | [`name.get`](/docs/reference/sdk/name/get) | | `name.isAvailable` | `registration.isAvailable` | | `resolution.getResolver`, `resolve*` | `resolver.get`, `resolver.resolve` | | `records.setAlias`, `resolution.getAlias` | `resolver.link`, `resolver.getLink`. See [Resolvers and shared records](/docs/sdk/resolvers-and-shared-records). | | `resolution.setResolver`, `setResolverAndRecords`, `createResolver`, `upgradeResolver` | `resolver.set`, `record.set({ resolver })`, `resolver.create`, `resolver.upgrade` | | `reverse.setPrimaryName`, `clearPrimaryName`, `setPrimaryNameForAddress`, `setContractPrimaryName` | [`primaryName.set`](/docs/reference/sdk/primary-name/set) (`name: null` clears) | | `registration.registerName(s)`, `commitName`, `completeRegistration` | `registration.register` (several names in one call), `registration.commit`; finish with the result's `secret` | | `registration.getRegistrationPrice`, `getRenewalPrice`, `getCommitmentStatus` | `registration.getPrice`, `getRenewalPrice`, `getCommitmentStatus` | | `registration.renewName(s)` | `registration.renew` | | `ownership.transferName`, `transferRegistrant`, `reclaimName`, `setManager`, `setTtl` | `name.transfer` (`role: "registrant"`), `name.reclaim`, `name.setManager`, `name.setTtl` | | `subnames.*` | `subname.create`, `subname.update`, `subname.remove` | | `wrapping.*` | `wrapper.wrap`, `unwrap`, `getFuses`, `setFuses`, `setChildFuses` | | `migration.*` | `migration.get`, `migration.migrate` | | `dns.*` | `dns.getStatus`, `dns.claim`, `dns.getProof`, `dns.getRecords`, `dns.setRecords` | | `events.*` | `event.get`, `event.watch`, `event.decode` | | `permissions.*`, `capabilities.*` | `permission.check`, `permission.get`, `permission.setRecordAccess`, `role.get`, `role.grant`, `role.revoke`, `approval.*` | | `indexer.*` | `indexer.*` (19 actions; add `indexerActions()`) | | `batch.prepareCalls`, `simulateCalls`, `estimateCalls`, `sendCalls`, `executeWritePlan` | `.prepare`, `.simulate`, `.estimateGas` on any write, and `plan.send`. See [Preview before sending](/docs/sdk/preview-before-sending). | | `batch.getCallsStatus`, `resumeCalls`, `workflows.*` | `plan.get`, `plan.list`, `plan.resume`, `plan.reconcile`. See [Continue after a failure](/docs/sdk/continue-after-a-failure). | | `hca.*`, `hcaAdmin` | `@ensforge/hca`. See [Use smart accounts](/docs/sdk/use-smart-accounts). | Some 0.x helpers, such as `resolution.predictResolverAddress` and `name.getProtocol`, have no action of their own in 1.0: `resolver.create.prepare` returns the address in `plan.deploys`, and `name.get` returns `protocol`. Browse the [reference](/docs/reference/sdk/record) for what exists. ## 5. Errors [#5-errors] 0.x errors were Effect `TaggedError`s per area (`ContractError`, `RpcError`, `NameError`, `TransactionError` …) with codes such as `REVERTED`. 1.0 errors are `Errors.*` classes with stable codes (`CONTRACT_REVERTED`, `NOT_OWNER`, `RECORD_NOT_FOUND`) that Promise and Effect users receive as the same instance. ```ts no-check title="errors.ts" if (error._tag === "ContractError" && error.code === "REVERTED") { /* … */ } // [!code --] if (Errors.hasCode("CONTRACT_REVERTED")(error)) { /* … */ } // [!code ++] ``` Each action now documents its errors, and `Errors.describe` gives user-safe copy. See [Handle errors](/docs/sdk/handle-errors). ## 6. wagmi [#6-wagmi] ```ts no-check title="wagmi.ts" import { createEnsforge } from "@ensforge/sdk/wagmi"; // [!code --] import { Ensforge } from "@ensforge/sdk/wagmi"; // [!code ++] import { ensActions } from "@ensforge/sdk"; // [!code ++] const sdk = createEnsforge({ network: "mainnet", wagmiConfig }); // [!code --] const ens = Ensforge.fromWagmi(wagmiConfig).extend(ensActions()); // [!code ++] ``` `Ensforge.fromWagmi(config, { chainId?, switchChain? })` reads through wagmi's transports and writes through the connected wallet, switching chain when needed. ## 7. Effect users [#7-effect-users] 0.x actions in `@ensforge/core` returned Effects. In 1.0 the Effect API is `@ensforge/sdk/effect`, and Promises are the default. See [The Effect API](/docs/sdk/effect-api). ## Check the result [#check-the-result] Build and run your tests. TypeScript flags every renamed action and option. Read a name, change a record on Sepolia, and confirm the read-back. ## Troubleshooting [#troubleshooting] ### `ens.records is undefined` [#ensrecords-is-undefined] The group is called `record` in 1.0. See the table above. ### `UNKNOWN_CHAIN` [#unknown_chain] 0.x took `network: "mainnet"`. In 1.0 the public client needs a `chain`, or you pass `deployment`. See [`UNKNOWN_CHAIN`](/docs/reference/errors/UNKNOWN_CHAIN). ### Receipts are missing from a write result [#receipts-are-missing-from-a-write-result] Writes resolve on submission. Use the `…Sync` form for `receipt` and `receipts`. # From ensjs > For the complete documentation index, see [llms.txt](https://ensforge.com/llms.txt). Replace ensjs (@ensdomains/ensjs) public, wallet and subgraph actions with ensforge actions, with before and after code for each one. Source: https://ensforge.com/docs/sdk/from-ensjs ensjs and ensforge are both action libraries on top of viem, so the move is mostly renaming. The differences are that ensforge needs no chain wrapper, routes between [ENSv1](/docs/reference/glossary#ensv1) and [ENSv2](/docs/reference/glossary#ensv2) for you, has one `record.set` for all record writes, and fails with typed errors. This guide maps the ensjs 5.x actions. Code blocks that mark lines with `[!code --]` and `[!code ++]` are diffs: they show the old and the new line together, so the docs build does not compile them. ## Prerequisites [#prerequisites] - An app using `@ensdomains/ensjs`. - `@ensforge/sdk` installed. See [Installation](/docs/sdk/installation). ## 1. Replace the client setup [#1-replace-the-client-setup] ensjs needs `addEnsContracts(chain)` so the viem chain knows the ENS addresses. ensforge picks the deployment from the chain ID (Ethereum mainnet and Sepolia), so the chain stays a plain viem chain. ```ts no-check title="client.ts" import { addEnsContracts } from "@ensdomains/ensjs"; // [!code --] import { Ensforge, ensActions } from "@ensforge/sdk"; // [!code ++] import { createPublicClient, http } from "viem"; import { mainnet } from "viem/chains"; const client = createPublicClient({ chain: addEnsContracts(mainnet), transport: http() }); // [!code --] const publicClient = createPublicClient({ chain: mainnet, transport: http() }); // [!code ++] const ens = Ensforge.create({ publicClient }).extend(ensActions()); // [!code ++] ``` ensjs actions are free functions you call with a client, and ensforge supports the same style: `Actions.record.getAddress(publicClient, options)`. Use that form to keep your call sites close to what they were. See [Ways to call actions](/docs/sdk/ways-to-call-actions). ## 2. Reads [#2-reads] ensjs read results are objects with a `value`, or `null`. ensforge returns the value. ```ts no-check title="reads.ts" import { getAddressRecord, getName, getTextRecord } from "@ensdomains/ensjs/public"; // [!code --] const record = await getAddressRecord(client, { name: "nick.eth" }); // [!code --] const address = record?.value ?? null; // [!code --] const address = await ens.record.getAddress({ name: "nick.eth" }); // [!code ++] const url = await getTextRecord(client, { name: "nick.eth", key: "url" }); // [!code --] const url = await ens.record.getText({ name: "nick.eth", key: "url" }); // [!code ++] const result = await getName(client, { address }); // [!code --] const primary = result?.match === true ? result.name : null; // [!code --] const primary = await ens.primaryName.get({ address }); // [!code ++] ``` `primaryName.get` returns the name only when it resolves back to the address, so the `match` check is built in. | ensjs | ensforge | | ------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------- | | `getAddressRecord({ name, coin })` | [`record.getAddress({ name, coin })`](/docs/reference/sdk/record/get-address) | | `getTextRecord({ name, key })` | [`record.getText`](/docs/reference/sdk/record/get-text) | | `getContentHashRecord`, `getAbiRecord` | [`record.getContentHash`](/docs/reference/sdk/record/get-content-hash), [`record.get`](/docs/reference/sdk/record/get) with `abi: true` | | `getRecords({ name, texts, coins, contentHash, abi })` | [`record.get({ name, texts, addresses, contentHash, abi })`](/docs/reference/sdk/record/get) | | `getName({ address })` | [`primaryName.get({ address })`](/docs/reference/sdk/primary-name/get) | | `getResolver({ name })` | [`resolver.get({ name })`](/docs/reference/sdk/resolver/get) | | `resolveNameData` | [`resolver.resolve({ name, data })`](/docs/reference/sdk/resolver/resolve) | | `getAvailable`, `isRenewable` | `registration.isAvailable`, or `name.get` (`available`, `renewable`) | | `getRegisterPrice`, `getRenewPrice` | `registration.getPrice`, `registration.getRenewalPrice` | | `public/v1`: `getOwner`, `getExpiry`, `getWrapperData` | [`name.get`](/docs/reference/sdk/name/get): `owner`, `manager`, `registrant`, `expiry`, `wrapped` | | `public/v2`: `getNameRegistries`, `getExpiry`, `getTokenId`, `getNameRolesAccounts` … | `name.get`, `registry.get`, `role.get`, `permission.get` | | `getSupportedInterfaces` | `resolver.get`: `profiles` lists what the resolver supports | | `dns`: `getDnsImportData`, `importDnsName`, `getDnsOwner`, `getDnsOffchainData` | `dns.getProof`, `dns.claim`, `dns.getStatus`, `dns.getOffchainResolver` | You do not pick `public/v1` or `public/v2`. ensforge finds which version a name lives on. See [ENS versions under the hood](/docs/sdk/ens-versions). ## 3. Records in one call [#3-records-in-one-call] `getRecords` maps directly. The `coins` option is `addresses` in ensforge, and the result has exactly the fields you asked for. ensjs returns `texts` as an array of `{ key, value }`. ensforge returns an object keyed by the text key. ```ts no-check title="records.ts" const records = await getRecords(client, { name: "ens.eth", texts: ["com.twitter", "avatar"], contentHash: true, }); // [!code --] const records = await ens.record.get({ name: "ens.eth", texts: ["com.twitter", "avatar"], contentHash: true, }); // [!code ++] records.texts["com.twitter"]; // string | null ``` ## 4. Writes [#4-writes] ensjs has one write per record kind (`setTextRecord`, `setAddressRecord`, `setContentHashRecord`, `setAbiRecord`), a `setRecords` for ENSv1 and ENSv2, and wallet actions you call with a wallet client. ensforge has [`record.set`](/docs/reference/sdk/record/set) for all of them, and sends with the wallet you gave the client. ```ts no-check title="writes.ts" await setTextRecord(walletClient, { name: "ensforge-docs-demo.eth", key: "url", value: "https://example.com", resolverAddress, }); // [!code --] await ens.record.setSync({ name: "ensforge-docs-demo.eth", texts: { url: "https://example.com" } }); // [!code ++] ``` ensforge reads the name's resolver itself, so you do not pass `resolverAddress`. Writes resolve when submitted. The `…Sync` form waits for the receipt. See [Send a transaction](/docs/sdk/send-a-transaction). | ensjs | ensforge | | --------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- | | `setTextRecord`, `setAddressRecord`, `setContentHashRecord`, `setAbiRecord`, `setRecords`, `clearRecords` | [`record.set`](/docs/reference/sdk/record/set) (`clear: true` deletes everything first) | | `commitName`, `registerName` | [`registration.register`](/docs/reference/sdk/registration/register) (one call runs commit, wait and register), `registration.commit` | | `renewName` | `registration.renew` | | `setPrimaryName` | [`primaryName.set`](/docs/reference/sdk/primary-name/set) | | `transferName` | [`name.transfer`](/docs/reference/sdk/name/transfer) | | `setResolver` | `resolver.set` | | `createSubname`, `deleteSubname` | `subname.create`, `subname.remove` | | `wrapName`, `unwrapName`, `setFuses`, `setChildFuses` | `wrapper.wrap`, `wrapper.unwrap`, `wrapper.setFuses`, `wrapper.setChildFuses` | | `grantRoles`, `revokeRoles`, `grantResolverRoles`, `revokeResolverRoles` | `role.grant`, `role.revoke` | | `linkToNode`, `linkToRecord` | `resolver.link` | | `deploySubregistry`, `setSubregistry`, `setParent` | `registry.deploy`, `registry.attach` | A registration does the commit, the wait and the register in one call, with progress through `onStep`. See [Register a name](/docs/sdk/register-a-name). ## 5. Subgraph reads [#5-subgraph-reads] ensjs queries ENS's subgraph through `@ensdomains/ensjs/subgraph` (`getNamesForAddress`, `getSubnames`, `getNameHistory`, `getSubgraphRecords`) and needs `graphql`. ensforge reads lists from an [indexer](/docs/reference/glossary#indexer) you connect to the client. | ensjs subgraph | ensforge | | -------------------------------------------------- | --------------------------------------------------------------------------------- | | `getNamesForAddress`, `getResolvedNamesForAddress` | [`indexer.getNamesForAddress`](/docs/reference/sdk/indexer/get-names-for-address) | | `getSubnames` | `indexer.getSubnames` | | `getNameHistory` | `indexer.getHistory`, or `event.get` over RPC | | `getSubgraphRecords` | `indexer.getRecords` | See [Connect an indexer](/docs/sdk/connect-an-indexer) and [List names for an address](/docs/sdk/list-names-for-an-address). ## 6. Errors [#6-errors] ensjs throws viem and ensjs `BaseError`s. ensforge throws `Errors.*` with stable codes. See [Handle errors](/docs/sdk/handle-errors). ## 7. Know what behaves differently [#7-know-what-behaves-differently] - **Encoded labels.** ensjs refuses `[labelhash]` labels. ensforge resolves the name. - **A reverting resolver.** ensjs throws when a resolver reverts or answers malformed data. ensforge reads no record. - **Gateways.** ensforge reports an unreachable or invalid gateway as a `GatewayError`. ensjs returns `null`. ## Check the result [#check-the-result] Compare old and new results for a few names, including one with no records. Values should match, and `null` should stay `null`. ## Troubleshooting [#troubleshooting] ### `UNKNOWN_CHAIN` [#unknown_chain] The chain is not mainnet or Sepolia, or it was wrapped with `addEnsContracts` for a custom setup. Pass a plain viem chain, or give `deployment`. See [`UNKNOWN_CHAIN`](/docs/reference/errors/UNKNOWN_CHAIN). ### An ensjs option has no equivalent [#an-ensjs-option-has-no-equivalent] ensjs `resolverAddress`, `universalResolverAddress` and similar overrides are not needed: ensforge reads them from the deployment. For a custom deployment, see [Create a client](/docs/sdk/create-a-client). # From viem's ENS actions > For the complete documentation index, see [llms.txt](https://ensforge.com/llms.txt). Replace viem's getEnsAddress, getEnsName, getEnsAvatar, getEnsText and getEnsResolver with ensforge actions, and see what changes. Source: https://ensforge.com/docs/sdk/from-viem ensforge is built on viem and takes viem clients, so you can move one call at a time. viem's ENS actions cover reads. ensforge adds the same reads with typed errors, plus records in one call, lists, and every write. You keep your viem transports and wallet. Code blocks that mark lines with `[!code --]` and `[!code ++]` are diffs: they show the old and the new line together, so the docs build does not compile them. ## Prerequisites [#prerequisites] - An app that calls viem's ENS actions. - `@ensforge/sdk` installed next to `viem`. See [Installation](/docs/sdk/installation). ## 1. Start with a bare viem client [#1-start-with-a-bare-viem-client] Every ensforge action takes a client first, and a viem public client is accepted as it is. You do not have to create an ensforge client to replace a read. ```ts no-check title="addresses.ts" import { getEnsAddress } from "viem/actions"; // [!code --] import { Actions } from "@ensforge/sdk"; // [!code ++] import { normalize } from "viem/ens"; // [!code --] const address = await getEnsAddress(publicClient, { name: normalize("nick.eth") }); // [!code --] const address = await Actions.record.getAddress(publicClient, { name: "nick.eth" }); // [!code ++] ``` ensforge [normalises](/docs/reference/glossary#normalisation) the name for you, so you can drop `normalize`. **Example** (The same read, after) ```ts title="addresses.ts" import { Actions } from "@ensforge/sdk"; import { createPublicClient, http } from "viem"; import { mainnet } from "viem/chains"; const publicClient = createPublicClient({ chain: mainnet, transport: http() }); const address = await Actions.record.getAddress(publicClient, { name: "nick.eth" }); ``` ## 2. Map each action [#2-map-each-action] | viem | ensforge | Notes | | ----------------------------------- | ----------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------ | | `getEnsAddress({ name, coinType })` | [`record.getAddress({ name, coin })`](/docs/reference/sdk/record/get-address) | `coin` is a symbol (`"btc"`), a chain (`{ chainId: 8453 }`) or a coin type. Default is Ethereum. | | `getEnsName({ address })` | [`primaryName.get({ address })`](/docs/reference/sdk/primary-name/get) | Checks that the name resolves back to the address by default. | | `getEnsAvatar({ name })` | [`record.getAvatar({ name })`](/docs/reference/sdk/record/get-avatar) | Returns a URL a browser can load. Set storage gateways with `gateways`. | | `getEnsText({ name, key })` | [`record.getText({ name, key })`](/docs/reference/sdk/record/get-text) | | | `getEnsResolver({ name })` | [`resolver.get({ name })`](/docs/reference/sdk/resolver/get) | Returns the resolver's `address`, its `kind`, who may write to it and its profiles. | | `normalize(name)` from `viem/ens` | `Name.normalize(name)` | ensforge actions normalise their inputs already. | These ensforge reads also take `blockNumber` or `blockTag`, `gatewayUrls`, `strict` and `signal`. ```ts no-check title="reads.ts" const name = await getEnsName(publicClient, { address }); // [!code --] const name = await Actions.primaryName.get(publicClient, { address }); // [!code ++] const avatar = await getEnsAvatar(publicClient, { name: "nick.eth" }); // [!code --] const avatar = await Actions.record.getAvatar(publicClient, { name: "nick.eth" }); // [!code ++] const resolver = await getEnsResolver(publicClient, { name: "nick.eth" }); // [!code --] const resolver = (await Actions.resolver.get(publicClient, { name: "nick.eth" }))?.address; // [!code ++] ``` ## 3. Know what behaves differently [#3-know-what-behaves-differently] - **Gateway failures are errors.** For an [off-chain name](/docs/reference/glossary#off-chain-name) whose [gateway](/docs/reference/glossary#gateway) is unreachable or invalid, ensforge throws a `GatewayError` ([`GATEWAY_REQUEST_FAILED`](/docs/reference/errors/GATEWAY_REQUEST_FAILED), [`GATEWAY_RESPONSE_INVALID`](/docs/reference/errors/GATEWAY_RESPONSE_INVALID)). viem returns `null`. - **`strict` means something else.** In ensforge, `strict: true` throws a `NotFoundError` when data is missing instead of returning `null`. - **Errors carry codes.** Every action throws `Errors.*` classes with a stable `code`, so you can branch without parsing messages. See [Handle errors](/docs/sdk/handle-errors). - **A name with a resolver that reverts reads as empty, as in viem.** Neither reads a record in that case. ## 4. Use what viem does not have [#4-use-what-viem-does-not-have] Once reads work, move to the parts viem has no action for: - Several records in one request with [`record.get`](/docs/reference/sdk/record/get). See [Get text records](/docs/sdk/get-text-records). - A whole profile for many names with [`Actions.batch`](/docs/reference/sdk/batch). See [Look up many at once](/docs/sdk/look-up-many-at-once). - A name's owner, expiry and status in one call. See [Get a name's owner, expiry and status](/docs/sdk/get-name-details). - Writes: [set records](/docs/sdk/set-records), [register a name](/docs/sdk/register-a-name), [transfer a name](/docs/sdk/transfer-a-name), and the rest of [Register and manage](/docs/sdk/check-if-a-name-is-available). For those, create a client once: ```ts title="client.ts" import { Ensforge, ensActions } from "@ensforge/sdk"; import { createPublicClient, http } from "viem"; import { mainnet } from "viem/chains"; const publicClient = createPublicClient({ chain: mainnet, transport: http() }); export const ens = Ensforge.create({ publicClient }).extend(ensActions()); await ens.record.getAddress({ name: "nick.eth" }); ``` ## Check the result [#check-the-result] Compare the old and the new result for a few names you know, such as `nick.eth` and one without an avatar. The values should match. A `GatewayError` instead of `null` for an off-chain name is the one expected difference. ## Troubleshooting [#troubleshooting] ### `UNKNOWN_CHAIN` [#unknown_chain] The viem client's chain is not Ethereum mainnet or Sepolia. Create an ensforge client with `deployment`. See [`UNKNOWN_CHAIN`](/docs/reference/errors/UNKNOWN_CHAIN). ### A read that returned `null` in viem throws [#a-read-that-returned-null-in-viem-throws] You passed `strict: true`, or the name is off-chain and its gateway failed. See [`RECORD_NOT_FOUND`](/docs/reference/errors/RECORD_NOT_FOUND) and [`GATEWAY_REQUEST_FAILED`](/docs/reference/errors/GATEWAY_REQUEST_FAILED). # Keep bundles small > For the complete documentation index, see [llms.txt](https://ensforge.com/llms.txt). Ship only the ensforge actions you use, with standalone actions, per-domain groups and tree-shaking, to keep your bundle small. Source: https://ensforge.com/docs/sdk/bundle-size `ensActions()` adds every action except the indexer group to your client, which is the easiest way to start and the largest thing to ship. For a browser app that reads one or two values, import the actions you use instead. ## Prerequisites [#prerequisites] - A bundler that tree-shakes ES modules (Vite, Rollup, esbuild, webpack in production mode). - Your app already ships `viem`. ensforge uses it as a peer and does not bundle it. ## What each choice costs [#what-each-choice-costs] ensforge's CI bundles typical imports with viem excluded and fails when one grows more than 5% over its recorded budget. At the time of writing the recorded sizes are: | Import | Gzipped size | | ------------------------------------------------------ | ------------ | | `Actions.record.getText` | about 41 kB | | `Ensforge.create(...).extend(ensActions())` | about 106 kB | | `ensActions()` plus `indexerActions()` and `bigname()` | about 128 kB | The numbers move with each release. The point is the ratio: one action costs well under half of the full client. ## Import one action [#import-one-action] Every action is a function that takes a client first. Pass a bare viem public client, so you do not create an ensforge client at all. **Example** (One read, nothing else) ```ts title="standalone.ts" import { Actions } from "@ensforge/sdk"; import { createPublicClient, http } from "viem"; import { mainnet } from "viem/chains"; const publicClient = createPublicClient({ chain: mainnet, transport: http() }); const url = await Actions.record.getText(publicClient, { name: "nick.eth", key: "url" }); ``` `Actions` is a namespace tree (`Actions.record.getText`). The package marks itself side-effect free and ships ES modules built so that bundlers drop every action you do not reference. The flat entry `@ensforge/sdk/actions` exports the same tree if you prefer named imports: ```ts title="flat-entry.ts" import { record } from "@ensforge/sdk/actions"; import { createPublicClient, http } from "viem"; import { mainnet } from "viem/chains"; const publicClient = createPublicClient({ chain: mainnet, transport: http() }); const address = await record.getAddress(publicClient, { name: "nick.eth" }); ``` Standalone actions give up client-wide settings (`ccipRead`, `gateways`, plan `storage`). To keep them, create a client with `Ensforge.create` and pass it where you passed `publicClient`. Creating the client adds no actions until you extend it. ## Add only some groups to a client [#add-only-some-groups-to-a-client] When you want `ens.record.*` methods without the rest, extend the client with the domain groups you need. Each domain has its own decorator. **Example** (Records and names only) ```ts title="groups.ts" import { Ensforge, nameActions, recordActions } from "@ensforge/sdk"; import { createPublicClient, http } from "viem"; import { mainnet } from "viem/chains"; const publicClient = createPublicClient({ chain: mainnet, transport: http() }); const ens = Ensforge.create({ publicClient }).extend(recordActions()).extend(nameActions()); await ens.record.getAddress({ name: "nick.eth" }); ``` `ensActions()` is all the domains except `indexer`, plus `batch`. Add the [indexer](/docs/reference/glossary#indexer) group with `indexerActions()` only if you use it. See [Ways to call actions](/docs/sdk/ways-to-call-actions). ## Choose the entry that matches your style [#choose-the-entry-that-matches-your-style] The root entry `@ensforge/sdk` is the Promise API. `@ensforge/sdk/effect` is the Effect API, for programs written with Effect. Import it only where you write those programs. See [The Effect API](/docs/sdk/effect-api). ## Check the result [#check-the-result] Build your app and inspect the output with your bundler's analyzer. A page that reads one record should not contain the registration, migration or indexer code. ## Troubleshooting [#troubleshooting] ### The bundle still includes every action [#the-bundle-still-includes-every-action] Something imports `ensActions` or the whole `Actions` object (for example by spreading it or iterating over it). Reference actions by name. Also check that your bundler is not set to treat `@ensforge/sdk` as having side effects. # Handle errors > For the complete documentation index, see [llms.txt](https://ensforge.com/llms.txt). Catch ensforge's typed errors, show users safe messages with Errors.describe, and retry only the failures that are safe to retry. Source: https://ensforge.com/docs/sdk/handle-errors Every action fails with an ensforge error that has a stable `code`. This guide shows how to catch them, what to show users, and when a retry is safe. For the ideas behind it, see [How errors work](/docs/sdk/errors-explained). ## Prerequisites [#prerequisites] - An `ens` client. See [Create a client](/docs/sdk/create-a-client). ## 1. Catch an error [#1-catch-an-error] All errors extend `EnsforgeError`, which extends the native `Error`. Check with `Errors.is`, then read the fields. **Example** (Reading the fields of an error) ```ts title="catch.ts" import { Ensforge, Errors, ensActions } from "@ensforge/sdk"; import { createPublicClient, http } from "viem"; import { mainnet } from "viem/chains"; const publicClient = createPublicClient({ chain: mainnet, transport: http() }); const ens = Ensforge.create({ publicClient }).extend(ensActions()); try { await ens.record.getAddress({ name: "nobody-here.eth", strict: true }); } catch (error) { if (Errors.is(error)) { console.log(error.code); // "RESOLVER_NOT_FOUND": the name has no resolver console.log(error.shortMessage); // one line for developers console.log(error.hint); // how to fix it, when ensforge knows console.log(error.retryable); // whether the same call can succeed later console.log(error.docsUrl); // /docs/reference/errors/ } } ``` | Field | Description | | -------------- | ----------------------------------------------------------------------------------------------------------------------------- | | `_tag` | The class name, such as `"NotFoundError"`. Also `error.name`. | | `code` | What happened, exactly. Stable across releases. | | `shortMessage` | One developer-facing line. | | `hint` | How to fix it, when ensforge knows. | | `details` | Extra developer-facing lines. | | `retryable` | Whether retrying the same call can succeed. | | `context` | Where it happened: `operation`, `name`, `account`, `chainId`, `contract`, `functionName`, and for writes `planId` and `step`. | | `docsUrl` | The page for this code. | `error.toJSON()` returns these fields as plain data that is safe to log or send to an error tracker. `Errors.is` uses a brand, not `instanceof`, so it also works when two copies of `@ensforge/sdk` are installed. ## 2. Branch on the code [#2-branch-on-the-code] `Errors.hasCode` takes one or more codes and narrows the error to the class that carries them. **Example** (Offering alternatives for a taken name) ```ts title="branch.ts" import { Duration, Ensforge, Errors, ensActions } from "@ensforge/sdk"; import { createPublicClient, http } from "viem"; import { sepolia } from "viem/chains"; const publicClient = createPublicClient({ chain: sepolia, transport: http() }); const account = "0xA11Ce00000000000000000000000000000000000"; const ens = Ensforge.create({ publicClient, account }).extend(ensActions()); try { await ens.registration.register({ names: "ensforge-docs-demo.eth", duration: Duration.years(1) }); } catch (error) { if (Errors.hasCode("NAME_NOT_AVAILABLE", "NAME_RESERVED")(error)) { console.log(error.context.name, "cannot be registered"); } else if (Errors.hasCode("USER_REJECTED")(error)) { // a normal outcome, not a failure } else { throw error; } } ``` Each action also lists the errors it can fail with, as `ErrorType` on its namespace (`record.set.ErrorType`). They are narrowed by class, so `switch (error._tag)` is exhaustive over the classes an action declares. [Route](/docs/reference/glossary#route) errors, such as `HcaError` from `via: hca()`, are outside those unions. Two codes can come from any action. [`CONTRACT_NOT_DEPLOYED`](/docs/reference/errors/CONTRACT_NOT_DEPLOYED) means the chain has no ENS contract at the address the action calls, usually a client on the wrong chain. [`INSUFFICIENT_ETH`](/docs/reference/errors/INSUFFICIENT_ETH) means the account cannot pay for a write's gas or value. Handle both in one place, next to your other generic errors. ## 3. Show users a safe message [#3-show-users-a-safe-message] `error.message` is written for developers and includes contract details. Use `Errors.describe` for anything a user sees. It accepts any thrown value and returns a title, a message and a suggested action. **Example** (An error toast) ```ts title="describe.ts" import { Errors } from "@ensforge/sdk"; declare const toast: (toast: { title: string; description: string }) => void; declare const error: unknown; const { title, message, action, severity, retryable } = Errors.describe(error); toast({ title, description: action === undefined ? message : `${message} ${action}` }); ``` `severity` is `"info"` for expected outcomes (`USER_REJECTED`, name state, not found and commitment errors), `"warning"` for a retryable failure, and `"error"` for anything that needs attention. **Example** (Translating one code) ```ts title="translate.ts" import { Errors } from "@ensforge/sdk"; declare const error: unknown; const copy = Errors.describe(error, { messages: { NAME_NOT_AVAILABLE: (e) => ({ title: "Nombre no disponible", message: `${e.context.name} ya está registrado.`, }), }, }); ``` An override returns only the fields it changes. The rest fall back to the English copy. `Errors.describe` has copy for every code, including the HCA codes. For a code it does not know, such as one from a newer release, it returns a generic message instead of throwing, so it is safe in an error boundary. ## 4. Decide whether to retry [#4-decide-whether-to-retry] Retry only when `error.retryable` is `true`. ensforge sets it for transient failures: - every `NetworkError` code: `RPC_REQUEST_FAILED`, `RPC_TIMEOUT`, `RATE_LIMITED`, `LOG_RANGE_TOO_LARGE` - the `IndexerError` codes `INDEXER_UNAVAILABLE`, `INDEXER_RATE_LIMITED` and `INDEXER_BEHIND`, from an [indexer](/docs/reference/glossary#indexer) - `GATEWAY_REQUEST_FAILED`, when an off-chain [gateway](/docs/reference/glossary#gateway) did not answer - `COMMITMENT_TOO_NEW`, when a registration's [commitment](/docs/reference/glossary#commitment) needs more time to age - `NONCE_CONFLICT`, when another transaction from the account is still pending - the HCA code `HCA_BUNDLER_REJECTED` ```mermaid flowchart TD A[An action failed] --> B{Is it a write?} B -->|no| C{retryable?} C -->|yes| D[Retry with backoff] C -->|no| E[Fix the input or show the message] B -->|yes| F{Did a plan start?} F -->|"context.planId is set"| G[plan.resume with that id] F -->|no| H{retryable?} H -->|yes| D H -->|no| E ``` A write that failed after a step was submitted has already spent gas. Sending it again can repeat that step. Resume the [plan](/docs/reference/glossary#plan) instead: it confirms the finished steps and sends the rest. See [Continue after a failure](/docs/sdk/continue-after-a-failure). **Example** (Retrying a read with backoff) ```ts title="retry.ts" import { Ensforge, Errors, ensActions } from "@ensforge/sdk"; import { createPublicClient, http } from "viem"; import { mainnet } from "viem/chains"; const publicClient = createPublicClient({ chain: mainnet, transport: http() }); const ens = Ensforge.create({ publicClient }).extend(ensActions()); const withRetry = async (run: () => Promise, attempts = 3): Promise => { for (let attempt = 1; ; attempt++) { try { return await run(); } catch (error) { if (attempt >= attempts || !Errors.is(error) || !error.retryable) throw error; await new Promise((resolve) => setTimeout(resolve, 2 ** attempt * 250)); } } }; const address = await withRetry(() => ens.record.getAddress({ name: "nick.eth" })); ``` For a write that timed out waiting for a receipt ([`RECEIPT_TIMEOUT`](/docs/reference/errors/RECEIPT_TIMEOUT)), `retryable` is `false` on purpose. The transaction may still land. Check its hash before you act. ## Reads return `null`, not errors, for missing data [#reads-return-null-not-errors-for-missing-data] Reads return `null` when a [record](/docs/reference/glossary#record) or [resolver](/docs/reference/glossary#resolver) is missing. Pass `strict: true` to get a `NotFoundError` instead, such as [`RECORD_NOT_FOUND`](/docs/reference/errors/RECORD_NOT_FOUND) or [`RESOLVER_NOT_FOUND`](/docs/reference/errors/RESOLVER_NOT_FOUND). ## Translate errors from viem [#translate-errors-from-viem] When you call viem next to ensforge, `Errors.fromCause(cause, context)` gives the same classes, codes and `Errors.describe` copy. Anything it does not recognise becomes [`UNEXPECTED`](/docs/reference/errors/UNEXPECTED), with the original error as `cause`. ## Point `docsUrl` at your own docs [#point-docsurl-at-your-own-docs] `docsUrl` uses `https://ensforge.com` by default. For a self-hosted mirror, call `Errors.setConfig({ docsOrigin: "https://docs.example.com" })` once at startup. ## Check the result [#check-the-result] Trigger a known failure, such as a read with `strict: true` on a missing record, and confirm that `Errors.describe` returns copy you are happy to show. ## Troubleshooting [#troubleshooting] ### `UNEXPECTED` [#unexpected] ensforge could not classify the failure. The original error is in `error.cause`. See [`UNEXPECTED`](/docs/reference/errors/UNEXPECTED), and open an issue with the `cause` and `context`. ### `RATE_LIMITED` or `RPC_TIMEOUT` [#rate_limited-or-rpc_timeout] Your RPC provider is limiting or slow. Retry with backoff, or use a provider with higher limits. See [Configure RPC and gateways](/docs/sdk/rpc-and-gateways), [`RATE_LIMITED`](/docs/reference/errors/RATE_LIMITED) and [`RPC_TIMEOUT`](/docs/reference/errors/RPC_TIMEOUT). For symptoms by message, see [Troubleshooting](/docs/sdk/troubleshooting). # Configure RPC and gateways > For the complete documentation index, see [llms.txt](https://ensforge.com/llms.txt). Choose RPC transports, off-chain lookup gateways, read batching and storage gateways for a production-ready ensforge client. Source: https://ensforge.com/docs/sdk/rpc-and-gateways ensforge reads and writes through your viem clients and a few services around them. This guide covers each setting you may want to change before you go live. ## Prerequisites [#prerequisites] - An `Ensforge.create` call. See [Create a client](/docs/sdk/create-a-client). ## Use a dedicated RPC URL [#use-a-dedicated-rpc-url] ensforge makes the RPC requests your public client makes. Public endpoints are rate limited, which shows up as [`RATE_LIMITED`](/docs/reference/errors/RATE_LIMITED) or [`RPC_TIMEOUT`](/docs/reference/errors/RPC_TIMEOUT). Give the public client a dedicated URL, and use viem's `fallback` transport to add a second provider. **Example** (Two providers with fallback) ```ts title="rpc.ts" import { Ensforge, ensActions } from "@ensforge/sdk"; import { createPublicClient, fallback, http } from "viem"; import { mainnet } from "viem/chains"; const publicClient = createPublicClient({ chain: mainnet, transport: fallback([http("https://rpc-a.example.com"), http("https://rpc-b.example.com")]), }); export const ens = Ensforge.create({ publicClient }).extend(ensActions()); ``` Two features need more from the RPC: - Plans simulate calls in order with `eth_simulateV1`. Without it, each call is simulated alone and a call that depends on an earlier one can fail in the simulation. See [Preview before sending](/docs/sdk/preview-before-sending). - Reads at an old `blockNumber`, and `event.get` over long ranges, need an archive node and wide `eth_getLogs` ranges. A provider that limits log ranges fails with [`LOG_RANGE_TOO_LARGE`](/docs/reference/errors/LOG_RANGE_TOO_LARGE). Use an indexer for history. See [Connect an indexer](/docs/sdk/connect-an-indexer). ## Set off-chain lookup gateways [#set-off-chain-lookup-gateways] Some names keep their records off-chain and resolve through [CCIP-Read](/docs/reference/glossary#ccip-read) (EIP-3668): the resolver names the [gateway](/docs/reference/glossary#gateway) that holds its records. ensforge reads names through the Universal Resolver, which sends these lookups through a batch gateway. By default that is the Universal Resolver's own batch gateway. `ccipRead.gatewayUrls` sets the batch gateways instead, and `ccipRead: false` turns off-chain lookups off. **Example** (Answering Lookups Locally) ```ts title="ccip.ts" import { Ensforge } from "@ensforge/sdk"; import { createPublicClient, http } from "viem"; import { mainnet } from "viem/chains"; const publicClient = createPublicClient({ chain: mainnet, transport: http() }); const ens = Ensforge.create({ publicClient, ccipRead: { gatewayUrls: ["x-batch-gateway:true"] }, }); ``` `x-batch-gateway:true` makes viem answer the batch itself, so ensforge calls each resolver's gateway directly instead of going through a hosted batch gateway. A URL works too, for a batch gateway you run. A single call can override the client's gateways with `gatewayUrls`. When a gateway fails, the action throws a `GatewayError` such as [`GATEWAY_REQUEST_FAILED`](/docs/reference/errors/GATEWAY_REQUEST_FAILED) or [`GATEWAY_RESPONSE_INVALID`](/docs/reference/errors/GATEWAY_RESPONSE_INVALID). With `ccipRead: false`, reading an off-chain name fails with [`CCIP_READ_DISABLED`](/docs/reference/errors/CCIP_READ_DISABLED). See [Look up off-chain names](/docs/sdk/off-chain-names). ## Tune read batching [#tune-read-batching] ensforge coalesces concurrent contract reads into Multicall3 calls ([batching](/docs/reference/glossary#batch)). It is on by default. | Option | Default | Description | | --------------------------- | ------- | ----------------------------------------------------------- | | `batch.multicall` | `true` | `false` turns batching off. | | `batch.multicall.batchSize` | `16384` | Calldata bytes per multicall chunk. | | `batch.multicall.wait` | `0` | Milliseconds to wait for more reads before sending a chunk. | ```ts title="batching.ts" import { Ensforge } from "@ensforge/sdk"; import { createPublicClient, http } from "viem"; import { mainnet } from "viem/chains"; const publicClient = createPublicClient({ chain: mainnet, transport: http() }); const ens = Ensforge.create({ publicClient, batch: { multicall: { batchSize: 8_192, wait: 10 } }, }); ``` Lower `batchSize` if your provider rejects large calls. To batch reads yourself, see [Look up many at once](/docs/sdk/look-up-many-at-once). ## Set storage gateways [#set-storage-gateways] [Avatars](/docs/reference/glossary#avatar) and content hashes point at decentralized storage (`ipfs://`, `ar://`, `bzz://`). [`record.getAvatar`](/docs/reference/sdk/record/get-avatar) turns them into URLs a browser can load through gateways. The defaults are `https://ipfs.io`, `https://arweave.net` and `https://api.gateway.ethswarm.org`. The public `ipfs.io` gateway is rate limited. Use a dedicated gateway in production. ```ts title="gateways.ts" import { Ensforge } from "@ensforge/sdk"; import { createPublicClient, http } from "viem"; import { mainnet } from "viem/chains"; const publicClient = createPublicClient({ chain: mainnet, transport: http() }); const ens = Ensforge.create({ publicClient, gateways: { ipfs: "https://gateway.pinata.cloud" }, }); ``` A call's own `gateways` option overrides the client's. `ContentHash.toGatewayUrl(uri, ens.config.gateways)` reuses the client's gateways for content hashes. ## Other defaults [#other-defaults] | Option | Default | Description | | ---------- | ---------- | ------------------------------------------------------------------------------------------------------------------------------------------ | | `blockTag` | `"latest"` | Block tag for reads. A call can pass `blockNumber` or `blockTag`. | | `simulate` | `true` | Simulate writes before the wallet prompt. | | `chains` | none | Clients for other chains, needed to set L2 primary names. Otherwise [`CHAIN_NOT_CONFIGURED`](/docs/reference/errors/CHAIN_NOT_CONFIGURED). | ## Check the result [#check-the-result] Read a name that needs a gateway, such as an off-chain name, and an avatar. Both should resolve without `RATE_LIMITED` or gateway errors. ## Troubleshooting [#troubleshooting] ### `RATE_LIMITED` [#rate_limited] The RPC provider is limiting requests. Use a dedicated URL or a `fallback` transport. See [`RATE_LIMITED`](/docs/reference/errors/RATE_LIMITED). ### Avatar URLs return HTTP 429 [#avatar-urls-return-http-429] The default `ipfs.io` gateway is rate limited. Set `gateways.ipfs`. ### `CONTRACT_NOT_DEPLOYED` [#contract_not_deployed] The chain has no ENS contracts at the addresses ensforge uses. Check the chain of your public client. See [`CONTRACT_NOT_DEPLOYED`](/docs/reference/errors/CONTRACT_NOT_DEPLOYED). # Servers and edge runtimes > For the complete documentation index, see [llms.txt](https://ensforge.com/llms.txt). Run ensforge in Node, serverless functions and edge runtimes, with a server-side signer and plan storage that outlives the request. Source: https://ensforge.com/docs/sdk/servers-and-edge ensforge depends on no browser or Node APIs, so the same code can run in a Node server, a serverless function or an edge runtime. Three things differ from the browser: where the signer comes from, where plans are saved, and how long a process lives. ## Prerequisites [#prerequisites] - An `ens` client. See [Create a client](/docs/sdk/create-a-client). ## What ensforge needs from the runtime [#what-ensforge-needs-from-the-runtime] The SDK imports no Node built-ins and reads no browser globals, except `localStorage` when you use `Plan.localStorage()`. It makes network requests through your viem transports and, for off-chain data ([indexers](/docs/reference/glossary#indexer), avatars, DNS proofs), through the global `fetch`. A runtime with `fetch` and viem support can run ensforge. The built-in indexers, `bigname()` and `goldsky()`, take a `fetch` option if you need to supply one. ensforge's own tests run on Node only. See [Connect an indexer](/docs/sdk/connect-an-indexer). ## Create the client once per process [#create-the-client-once-per-process] An ensforge client's settings are fixed when you create it, and it keeps no per-request state, so create it at module scope and reuse it. Create a separate client only when the signer differs per request. ## Sign on the server [#sign-on-the-server] There is no wallet extension on a server. Give the wallet client an account built from a key, and load the key from a secret store or environment variable. Never put a key in source code. **Example** (A server-side signer) ```ts title="server.ts" 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(process.env.SIGNER_KEY as `0x${string}`); const publicClient = createPublicClient({ chain: sepolia, transport: http(process.env.RPC_URL) }); const walletClient = createWalletClient({ account, chain: sepolia, transport: http(process.env.RPC_URL), }); export const ens = Ensforge.create({ publicClient, walletClient }).extend(ensActions()); ``` A server signer has no wallet prompt, so there is no [`USER_REJECTED`](/docs/reference/errors/USER_REJECTED) and no EIP-5792 bundle: ensforge sends one transaction per call. Handle the failures that remain with [Handle errors](/docs/sdk/handle-errors). ## Save plans somewhere that outlives the process [#save-plans-somewhere-that-outlives-the-process] By default [plans](/docs/reference/glossary#plan) are kept in memory. A serverless function starts fresh on each cold start, so a plan from an earlier invocation is gone and `plan.resume` fails with [`PLAN_NOT_FOUND`](/docs/reference/errors/PLAN_NOT_FOUND). `Plan.localStorage()` does not exist on a server: its calls reject, and a write ignores a store that fails to save, so the write still runs but cannot be resumed. Pass your own `Plan.Storage` backed by a database or key-value store. See [Save and resume plans](/docs/sdk/save-and-resume-plans). ## Set deadlines [#set-deadlines] A function with a time limit should cancel work that runs long. Every read takes a `signal`, and the Promise rejects with `signal.reason` when it aborts. **Example** (A five-second deadline) ```ts title="deadline.ts" import { Ensforge, ensActions } from "@ensforge/sdk"; import { createPublicClient, http } from "viem"; import { mainnet } from "viem/chains"; const publicClient = createPublicClient({ chain: mainnet, transport: http() }); const ens = Ensforge.create({ publicClient }).extend(ensActions()); const address = await ens.record.getAddress({ name: "nick.eth", signal: AbortSignal.timeout(5_000), }); ``` A write's `signal` cancels before the next wallet prompt. Transactions already submitted are not undone. ## Avoid long-lived subscriptions [#avoid-long-lived-subscriptions] [`event.watch`](/docs/reference/sdk/event/watch) polls for new blocks until you stop it, which does not fit a function that exits after a request. Use [`event.get`](/docs/reference/sdk/event/get) over a block range, or an indexer, for request-scoped history. See [Watch for changes](/docs/sdk/watch-for-changes). ## Check the result [#check-the-result] Call the server route once. It should read a name, and a write should return a `hash` you can find on a block explorer. ## Troubleshooting [#troubleshooting] ### `ACCOUNT_NOT_FOUND` [#account_not_found] The wallet client has no account. Create it with `account`, as above. See [`ACCOUNT_NOT_FOUND`](/docs/reference/errors/ACCOUNT_NOT_FOUND). ### `localStorage is not available in this environment` [#localstorage-is-not-available-in-this-environment] You used `Plan.localStorage()` on a server. Use a custom `Plan.Storage`. ### `RPC_TIMEOUT` on cold starts [#rpc_timeout-on-cold-starts] Your RPC provider is slow to answer. Set a `timeout` on viem's `http` transport and retry. See [`RPC_TIMEOUT`](/docs/reference/errors/RPC_TIMEOUT). # Test your integration > For the complete documentation index, see [llms.txt](https://ensforge.com/llms.txt). Test code that uses ensforge against a local anvil fork, with test doubles for indexers, plan storage and typed errors in unit tests. Source: https://ensforge.com/docs/sdk/testing The most faithful test of an ENS integration runs it against a copy of the real chain. This guide sets up a local fork with anvil, sends a write on it, and shows what to replace with test doubles in unit tests. ## Prerequisites [#prerequisites] - [Foundry](https://book.getfoundry.sh) for `anvil`. - An archive-capable RPC URL for the chain you fork. ## 1. Start a fork [#1-start-a-fork] A fork keeps the chain ID of the chain it copies, so ensforge picks the right ENS deployment with no extra configuration. ```sh title="terminal" anvil --fork-url "$MAINNET_RPC_URL" --fork-block-number 26441000 ``` Pin `--fork-block-number` so the state your tests read does not change. Anvil fetches state on demand, so a rate-limited RPC can slow a run. Anvil's `--compute-units-per-second` option throttles its requests. ## 2. Point ensforge at the fork [#2-point-ensforge-at-the-fork] Create the clients against the local URL and use viem's test client to control the chain. **Example** (Clients for a mainnet fork) ```ts title="fork.ts" import { Ensforge, ensActions } from "@ensforge/sdk"; import { createPublicClient, createTestClient, createWalletClient, http } from "viem"; import { mainnet } from "viem/chains"; const transport = http("http://127.0.0.1:8545"); export const publicClient = createPublicClient({ chain: mainnet, transport }); export const testClient = createTestClient({ chain: mainnet, mode: "anvil", transport }); export const forkEns = (account: `0x${string}`) => Ensforge.create({ publicClient, walletClient: createWalletClient({ chain: mainnet, transport, account }), }).extend(ensActions()); ``` `createWalletClient` with an address as `account` makes viem ask the node to sign, which works for accounts the node controls or impersonates. ## 3. Write as an existing owner [#3-write-as-an-existing-owner] Impersonate the owner of a real name, fund the account, and send the write. **Example** (Changing a record on a fork) ```ts title="fork-write.ts" import { Ensforge, ensActions } from "@ensforge/sdk"; import { createPublicClient, createTestClient, createWalletClient, http, parseEther } from "viem"; import { mainnet } from "viem/chains"; const transport = http("http://127.0.0.1:8545"); const publicClient = createPublicClient({ chain: mainnet, transport }); const testClient = createTestClient({ chain: mainnet, mode: "anvil", transport }); const reader = Ensforge.create({ publicClient }).extend(ensActions()); const state = await reader.name.get({ name: "nick.eth" }); const owner = state.owner; if (owner === null) throw new Error("nick.eth has no owner on this fork"); await testClient.impersonateAccount({ address: owner }); await testClient.setBalance({ address: owner, value: parseEther("10") }); const ens = Ensforge.create({ publicClient, walletClient: createWalletClient({ chain: mainnet, transport, account: owner }), }).extend(ensActions()); await ens.record.setSync({ name: "nick.eth", texts: { url: "https://example.com" } }); await ens.record.getText({ name: "nick.eth", key: "url" }); // "https://example.com" ``` On a fork of a real network, anvil's well-known accounts may carry contract code (for example EIP-7702 delegations), and then reject token callbacks. If a test that registers or receives a name reverts, clear the account's code first with `testClient.setCode({ address, bytecode: "0x" })`. ## 4. Move time forward [#4-move-time-forward] A registration waits for the registrar's [commitment](/docs/reference/glossary#commitment) age on chain time, and a fork's time only moves with its blocks. Use `onStep` to advance it when a step waits. **Example** (Skipping a registration wait) ```ts title="fork-wait.ts" import { Duration, Ensforge, ensActions } from "@ensforge/sdk"; import { createPublicClient, createTestClient, createWalletClient, http } from "viem"; import { mainnet } from "viem/chains"; const transport = http("http://127.0.0.1:8545"); const publicClient = createPublicClient({ chain: mainnet, transport }); const testClient = createTestClient({ chain: mainnet, mode: "anvil", transport }); declare const account: `0x${string}`; const ens = Ensforge.create({ publicClient, walletClient: createWalletClient({ chain: mainnet, transport, account }), }).extend(ensActions()); await ens.registration.registerSync({ names: "ensforge-docs-demo.eth", duration: Duration.years(1), onStep: async ({ status, step }) => { if (status !== "waiting" || step.waitFor === undefined) return; await testClient.increaseTime({ seconds: Number(step.waitFor.seconds) }); await testClient.mine({ blocks: 1 }); }, }); ``` Isolate tests from each other with `testClient.snapshot()` before and `testClient.revert({ id })` after. ## Use test doubles in unit tests [#use-test-doubles-in-unit-tests] Fast tests should not need a chain. Replace the parts that reach outside: - **An [indexer](/docs/reference/glossary#indexer).** `defineIndexer` builds an indexer from your own functions. See [Custom indexers](/docs/sdk/custom-indexers). - **[Plan](/docs/reference/glossary#plan) storage.** The default `Plan.memoryStorage()` is already a fresh store per client. Pass your own `Plan.Storage` to check what a write saves. - **Errors.** Error classes can be built directly, so you can test how your UI reacts. **Example** (Testing UI copy for a failure) ```ts title="errors.test.ts" import { Errors } from "@ensforge/sdk"; const error = new Errors.NotFoundError({ code: "RECORD_NOT_FOUND", context: { name: "ensforge-docs-demo.eth" }, }); Errors.describe(error).title; Errors.hasCode("RECORD_NOT_FOUND")(error); // true ``` To test your own wrapper around ensforge without any chain, depend on a small interface of the actions you use and fake it in tests. Run the real actions only in the fork lane. ## Check the result [#check-the-result] Run your tests twice against the pinned fork. The second run should read the same state and pass. ## Troubleshooting [#troubleshooting] ### `UNKNOWN_CHAIN` [#unknown_chain] The fork or devnet has a chain ID ensforge does not ship. Pass `deployment` to `Ensforge.create`. See [`UNKNOWN_CHAIN`](/docs/reference/errors/UNKNOWN_CHAIN) and [Create a client](/docs/sdk/create-a-client). ### `CONTRACT_NOT_DEPLOYED` [#contract_not_deployed] The fork has no ENS contracts at the pinned block, or the clients point at the wrong chain. See [`CONTRACT_NOT_DEPLOYED`](/docs/reference/errors/CONTRACT_NOT_DEPLOYED). ### `RATE_LIMITED` while forking [#rate_limited-while-forking] Anvil reads state from the upstream RPC on demand. Pin the block so anvil can cache, and throttle it with `--compute-units-per-second`. See [`RATE_LIMITED`](/docs/reference/errors/RATE_LIMITED). # Troubleshooting > For the complete documentation index, see [llms.txt](https://ensforge.com/llms.txt). Find the cause and the fix for common ensforge symptoms and error messages, each one linked to its page in the error reference. Source: https://ensforge.com/docs/sdk/troubleshooting Find your symptom or error message below. Every error has a stable `code`, and each code has a page at `/docs/reference/errors/` with causes and fixes. For how to catch and show errors, see [Handle errors](/docs/sdk/handle-errors). ## Reads [#reads] ### A read returns `null` [#a-read-returns-null] `null` means the data is not set, not that the call failed. Check, in order: 1. The name is spelled as you meant. ensforge [normalises](/docs/reference/glossary#normalisation) names (ENSIP-15), and [`INVALID_NAME`](/docs/reference/errors/INVALID_NAME) reports names that cannot be normalised. 2. The name has a [resolver](/docs/reference/glossary#resolver) and the [record](/docs/reference/glossary#record) exists. Call `resolver.get`, or pass `strict: true` to turn `null` into [`RESOLVER_NOT_FOUND`](/docs/reference/errors/RESOLVER_NOT_FOUND) or [`RECORD_NOT_FOUND`](/docs/reference/errors/RECORD_NOT_FOUND). 3. The client is on the chain you expect. A Sepolia client does not see mainnet names. ### `This name resolves off-chain, and CCIP-Read is disabled.` [#this-name-resolves-off-chain-and-ccip-read-is-disabled] The name keeps its records off-chain ([CCIP-Read](/docs/reference/glossary#ccip-read)) and the client was created with `ccipRead: false`. Remove that option. See [`CCIP_READ_DISABLED`](/docs/reference/errors/CCIP_READ_DISABLED) and [Look up off-chain names](/docs/sdk/off-chain-names). ### An off-chain name fails with a gateway error [#an-off-chain-name-fails-with-a-gateway-error] The [gateway](/docs/reference/glossary#gateway) did not answer or returned data ensforge cannot use. A failed request is worth retrying. See [`GATEWAY_REQUEST_FAILED`](/docs/reference/errors/GATEWAY_REQUEST_FAILED) and [`GATEWAY_RESPONSE_INVALID`](/docs/reference/errors/GATEWAY_RESPONSE_INVALID). ### `The primary name does not resolve back to this address.` [#the-primary-name-does-not-resolve-back-to-this-address] The address's [primary name](/docs/reference/glossary#primary-name) record names a name whose address record points elsewhere. Set the name's address record to the address, or set another primary name. See [`PRIMARY_NAME_MISMATCH`](/docs/reference/errors/PRIMARY_NAME_MISMATCH) and [Get the name for an address](/docs/sdk/get-a-primary-name). ### `The RPC provider is rate limiting requests.` [#the-rpc-provider-is-rate-limiting-requests] Use a dedicated RPC URL or a `fallback` transport. See [`RATE_LIMITED`](/docs/reference/errors/RATE_LIMITED) and [Configure RPC and gateways](/docs/sdk/rpc-and-gateways). ### `The RPC provider's eth_getLogs limits make this block range too expensive.` [#the-rpc-providers-eth_getlogs-limits-make-this-block-range-too-expensive] `event.get` needs wide log ranges. Narrow the block range, use an RPC URL with wider ranges, or read history from an indexer. See [`LOG_RANGE_TOO_LARGE`](/docs/reference/errors/LOG_RANGE_TOO_LARGE) and [Name history](/docs/sdk/name-history). ### `This action needs an indexer.` [#this-action-needs-an-indexer] You called an `indexer.*` action on a client without an [indexer](/docs/reference/glossary#indexer). Pass `indexer` to `Ensforge.create`, and add `indexerActions()` to the client. See [`INDEXER_NOT_CONFIGURED`](/docs/reference/errors/INDEXER_NOT_CONFIGURED) and [Connect an indexer](/docs/sdk/connect-an-indexer). ### DNS names fail with `DNSSEC_PROOF_FAILED` [#dns-names-fail-with-dnssec_proof_failed] Since the root key rollover in October 2026 the on-chain DNSSEC oracle cannot verify proofs, so DNS name resolution and claims fail on mainnet and Sepolia. ensforge has no client-side workaround. The fix is upstream: ENS must add the new trust anchor to the oracle. See [`DNSSEC_PROOF_FAILED`](/docs/reference/errors/DNSSEC_PROOF_FAILED) and [Use a DNS name](/docs/sdk/use-a-dns-name). ## Writes [#writes] ### `This action needs a wallet client with an account.` [#this-action-needs-a-wallet-client-with-an-account] The client has no wallet. Pass `walletClient` to `Ensforge.create`, or `account` to the action. See [`WALLET_NOT_CONFIGURED`](/docs/reference/errors/WALLET_NOT_CONFIGURED). ### `The wallet has no account to sign with.` [#the-wallet-has-no-account-to-sign-with] The wallet client was created without an account and no default `account` was given. Pass `account` to `Ensforge.create` or the write. See [`ACCOUNT_NOT_FOUND`](/docs/reference/errors/ACCOUNT_NOT_FOUND). ### `The wallet is on chain …, expected ….` [#the-wallet-is-on-chain--expected-] The wallet's chain differs from the client's. Switch the wallet or create the client for its chain. See [`CHAIN_MISMATCH`](/docs/reference/errors/CHAIN_MISMATCH). ### `... does not own this name.` [#-does-not-own-this-name] The signer is not the owner. Send from the owner's account, or check who may change the name. See [`NOT_OWNER`](/docs/reference/errors/NOT_OWNER) and [Who can change a name](/docs/sdk/who-can-change-a-name). ### `... is missing the roles this change needs.` [#-is-missing-the-roles-this-change-needs] On [ENSv2](/docs/reference/glossary#ensv2) names a change needs a [role](/docs/reference/glossary#role). `error.missingRoles` names them. See [`MISSING_ROLES`](/docs/reference/errors/MISSING_ROLES) and [Roles and permissions](/docs/sdk/roles-and-permissions). ### `The resolver does not support this record type.` [#the-resolver-does-not-support-this-record-type] The name's resolver cannot store that kind of record, for example an older resolver without `data` records, or a resolver that keeps records off-chain. Point the name at a resolver that supports it. See [`RESOLVER_PROFILE_UNSUPPORTED`](/docs/reference/errors/RESOLVER_PROFILE_UNSUPPORTED) and [Change the resolver](/docs/sdk/change-the-resolver). ### `The name must be migrated to ENSv2 first.` [#the-name-must-be-migrated-to-ensv2-first] The write needs the name on ENSv2. [Migrate](/docs/reference/glossary#migration) it with `migration.migrate`. See [`NAME_REQUIRES_MIGRATION`](/docs/reference/errors/NAME_REQUIRES_MIGRATION) and [Move a name to ENSv2](/docs/sdk/move-a-name-to-ensv2). ### `Timed out waiting for the transaction receipt.` [#timed-out-waiting-for-the-transaction-receipt] The transaction may still confirm. Check it by hash before sending again. See [`RECEIPT_TIMEOUT`](/docs/reference/errors/RECEIPT_TIMEOUT). ### `The transaction nonce conflicts with another transaction.` [#the-transaction-nonce-conflicts-with-another-transaction] Another transaction from the account is pending. Wait for it to confirm, then retry. See [`NONCE_CONFLICT`](/docs/reference/errors/NONCE_CONFLICT). ### A registration takes more than a minute [#a-registration-takes-more-than-a-minute] That is expected. A registration sends a [commitment](/docs/reference/glossary#commitment), waits for the registrar's minimum commitment age on chain time, then registers. With a wallet that does not send atomic bundles, a single name is four to five transactions. Use `onStep` to show progress. See [Register a name](/docs/sdk/register-a-name) and [Send a transaction](/docs/sdk/send-a-transaction). ### A write stopped half-way [#a-write-stopped-half-way] Resume it with `plan.resume`. Do not send it again. See [Continue after a failure](/docs/sdk/continue-after-a-failure) and [`PLAN_NOT_FOUND`](/docs/reference/errors/PLAN_NOT_FOUND). ## Setup [#setup] ### `No contract is deployed at the called address.` [#no-contract-is-deployed-at-the-called-address] The client's chain does not match the deployment ensforge uses. Check the chain of your public client. See [`CONTRACT_NOT_DEPLOYED`](/docs/reference/errors/CONTRACT_NOT_DEPLOYED). ### `ensforge has no ENS deployment for this chain.` [#ensforge-has-no-ens-deployment-for-this-chain] ensforge ships deployments for Ethereum mainnet and Sepolia. For another chain, a fork with a different chain ID or a devnet, pass `deployment`. See [`UNKNOWN_CHAIN`](/docs/reference/errors/UNKNOWN_CHAIN) and [Create a client](/docs/sdk/create-a-client). ### `A decorator added an action group with a reserved name.` [#a-decorator-added-an-action-group-with-a-reserved-name] An extension added a group named `chain`, `account`, `deployment`, `publicClient`, `config` or `extend`. Rename the group. See [`INVALID_ACTION_GROUP`](/docs/reference/errors/INVALID_ACTION_GROUP) and [Extend the client](/docs/sdk/extend-the-client). ### `An unexpected error occurred.` [#an-unexpected-error-occurred] ensforge could not classify the failure. The original error is in `error.cause`. If it persists, report it at the [ensforge issue tracker](https://github.com/thenamespace/ensforge/issues) with the cause. See [`UNEXPECTED`](/docs/reference/errors/UNEXPECTED). ## Still stuck [#still-stuck] Log `error.toJSON()`. It holds the code, hint, context and docs URL, and is safe to share. # Bundle transactions > For the complete documentation index, see [llms.txt](https://ensforge.com/llms.txt). Send several calls in one wallet prompt with EIP-5792 atomic batches, and combine separate writes into one plan with Plan.merge. Source: https://ensforge.com/docs/sdk/bundle-transactions A **bundle** (EIP-5792) is a group of calls a wallet sends together after one approval. ensforge bundles the [steps](/docs/reference/glossary#step) of a write for you when the wallet supports it, and `Plan.merge` lets you bundle several writes into one [plan](/docs/reference/glossary#plan). ## Prerequisites [#prerequisites] - A client with a wallet. See [Send a transaction](/docs/sdk/send-a-transaction). - A wallet that supports EIP-5792 atomic batches for the bundle to form. Other wallets still work; ensforge falls back to one transaction per call. ## How ensforge picks a mode [#how-ensforge-picks-a-mode] Every write takes `mode`. The default, `"auto"`, asks the wallet what it supports and chooses. ```mermaid flowchart TD A[Write with several calls] --> B{mode} B -->|sequential| S[One transaction per call] B -->|batch| W[One wallet_sendCalls bundle] B -->|auto| C{Wallet reports atomic support?} C -->|yes| W C -->|no, or no EIP-5792| S ``` | Mode | What it does | | -------------- | ---------------------------------------------------------------------------------------------------------- | | `"auto"` | Sends one atomic bundle when the wallet reports `atomic` support, otherwise one transaction per call. | | `"batch"` | Always sends through `wallet_sendCalls`, even for a single call, and asks the wallet for an atomic bundle. | | `"sequential"` | Sends one transaction per call. Each waits for the previous receipt, with a fifth more gas than estimated. | `"auto"` only bundles when the wallet already sends atomic bundles. A wallet that would first ask the user to upgrade the account (EIP-7702) is treated as unsupported. `mode: "batch"` does not make that distinction, so the wallet may show the upgrade prompt. Without a bundle, the calls of a step go out one at a time, because a later call may depend on an earlier one, such as a payment after its approval. ## Send a write as a bundle [#send-a-write-as-a-bundle] Nothing changes in your code. A write with several calls bundles itself. **Example** (Forcing one bundle) ```ts title="bundle.ts" import type { EIP1193Provider } from "viem"; declare global { interface Window { ethereum?: EIP1193Provider; } } import { Ensforge, ensActions } from "@ensforge/sdk"; import { createPublicClient, createWalletClient, custom, http } from "viem"; import { sepolia } from "viem/chains"; const publicClient = createPublicClient({ chain: sepolia, transport: http() }); const walletClient = createWalletClient({ chain: sepolia, transport: custom(window.ethereum!) }); const [account] = await walletClient.requestAddresses(); const ens = Ensforge.create({ publicClient, walletClient, account }).extend(ensActions()); const { id, hashes } = await ens.record.set({ name: "ensforge-docs-demo.eth", texts: { url: "https://example.com", "com.twitter": "alice" }, mode: "batch", }); ``` `id` is the bundle id. A bundle has no transaction hash until it is included, so the write waits for the bundle to settle before it resolves, and `hashes` holds the transactions it landed in. A bundle that reverts fails with [`TRANSACTION_REVERTED`](/docs/reference/errors/TRANSACTION_REVERTED). Without a `timeout` ensforge waits five minutes, then fails with [`RECEIPT_TIMEOUT`](/docs/reference/errors/RECEIPT_TIMEOUT). ## Share one bundle across steps [#share-one-bundle-across-steps] Consecutive steps without a chain-time wait join one bundle, up to `maxBundleCalls` calls (default 10, the limit MetaMask accepts). A step that waits, such as a registration's register step, starts a new bundle. Raise `maxBundleCalls` for wallets that accept more. ```ts title="max-bundle-calls.ts" import type { EIP1193Provider } from "viem"; declare global { interface Window { ethereum?: EIP1193Provider; } } import { Ensforge, ensActions } from "@ensforge/sdk"; import { createPublicClient, createWalletClient, custom, http } from "viem"; import { sepolia } from "viem/chains"; const publicClient = createPublicClient({ chain: sepolia, transport: http() }); const walletClient = createWalletClient({ chain: sepolia, transport: custom(window.ethereum!) }); const [account] = await walletClient.requestAddresses(); const ens = Ensforge.create({ publicClient, walletClient, account }).extend(ensActions()); await ens.record.set({ name: "ensforge-docs-demo.eth", texts: { url: "https://example.com" }, maxBundleCalls: 20, }); ``` ## Combine several writes into one plan [#combine-several-writes-into-one-plan] `Plan.merge` joins prepared plans so one prompt covers them all. Steps keep their order, and their ids get the plan's position as a prefix to stay unique. **Example** (Records and primary name in one prompt) ```ts title="merge.ts" import type { EIP1193Provider } from "viem"; declare global { interface Window { ethereum?: EIP1193Provider; } } import { Ensforge, ensActions, Plan } from "@ensforge/sdk"; import { createPublicClient, createWalletClient, custom, http } from "viem"; import { sepolia } from "viem/chains"; const publicClient = createPublicClient({ chain: sepolia, transport: http() }); const walletClient = createWalletClient({ chain: sepolia, transport: custom(window.ethereum!) }); const [account] = await walletClient.requestAddresses(); const ens = Ensforge.create({ publicClient, walletClient, account }).extend(ensActions()); const records = await ens.record.set.prepare({ name: "ensforge-docs-demo.eth", texts: { url: "https://example.com" }, }); const primary = await ens.primaryName.set.prepare({ name: "ensforge-docs-demo.eth" }); const { hashes } = await ens.plan.send({ plan: Plan.merge([records, primary]) }); ``` - Every plan must be for the same chain and account. Otherwise `Plan.merge` throws [`PLAN_CHAIN_MISMATCH`](/docs/reference/errors/PLAN_CHAIN_MISMATCH) or [`PLAN_ACCOUNT_MISMATCH`](/docs/reference/errors/PLAN_ACCOUNT_MISMATCH). - A merged plan keeps the steps' requirements, warnings and deployments. - [`plan.send`](/docs/reference/sdk/plan/send) simulates and sends the merged plan like any write, and saves it so [`plan.resume`](/docs/sdk/continue-after-a-failure) can continue it. ## Batch reads [#batch-reads] Reads [batch](/docs/reference/glossary#batch) differently. [`Actions.batch`](/docs/reference/sdk/batch) runs several reads through Multicall3. It does not take writes. See [Look up many at once](/docs/sdk/look-up-many-at-once). ## Check the result [#check-the-result] With a bundle, `result.id` is set and `result.hashes` lists the transactions it landed in. With sequential sending, `id` is `undefined` and each call has its own hash. ## Troubleshooting [#troubleshooting] ### `WALLET_BATCH_UNSUPPORTED` [#wallet_batch_unsupported] You set `mode: "batch"` and the wallet refused an atomic bundle. Use `mode: "auto"` or `mode: "sequential"`. See [`WALLET_BATCH_UNSUPPORTED`](/docs/reference/errors/WALLET_BATCH_UNSUPPORTED). ### The wallet shows one prompt per call [#the-wallet-shows-one-prompt-per-call] `"auto"` found no atomic support, so it sent transactions one by one. Check what the wallet reports with viem's `getCapabilities`, or pass `mode: "batch"` if you accept the wallet's upgrade prompt. ### A bundle was sent and the page reloaded [#a-bundle-was-sent-and-the-page-reloaded] A bundle sent before a reload is still known to the wallet. Resume the plan to follow it instead of sending it again. Only the wallet that sent a bundle can report its status. See [Continue after a failure](/docs/sdk/continue-after-a-failure). # Continue after a failure > For the complete documentation index, see [llms.txt](https://ensforge.com/llms.txt). Resume a multi-step write that stopped part-way with plan.resume, without sending the steps that already finished a second time. Source: https://ensforge.com/docs/sdk/continue-after-a-failure A registration or a [migration](/docs/reference/glossary#migration) is several transactions, grouped in a [plan](/docs/reference/glossary#plan). When one fails, or the page reloads in the middle, `plan.resume` finishes the rest and skips what already landed. ## Prerequisites [#prerequisites] - A client with a wallet. See [Send a transaction](/docs/sdk/send-a-transaction). - Plan storage that survives your failure. The default is in memory and forgets plans when the process or page reloads. See [Save and resume plans](/docs/sdk/save-and-resume-plans). ## How a plan is tracked [#how-a-plan-is-tracked] Every write saves its progress to the client's storage after each submission. A failed write keeps the record, so you can continue it. ```mermaid stateDiagram-v2 [*] --> pending: write starts pending --> pending: step submitted pending --> failed: a step fails failed --> pending: plan.resume pending --> completed: last step submitted completed --> [*] ``` ## 1. Find the plan id [#1-find-the-plan-id] A failure carries the id of its plan in `error.context.planId`, and `error.context.step` names the step that failed. A write that finished has it on `result.plan.id`. **Example** (Catching a failed registration) ```ts title="catch.ts" import type { EIP1193Provider } from "viem"; declare global { interface Window { ethereum?: EIP1193Provider; } } import { Duration, Ensforge, Errors, ensActions } from "@ensforge/sdk"; import { createPublicClient, createWalletClient, custom, http } from "viem"; import { sepolia } from "viem/chains"; const publicClient = createPublicClient({ chain: sepolia, transport: http() }); const walletClient = createWalletClient({ chain: sepolia, transport: custom(window.ethereum!) }); const [account] = await walletClient.requestAddresses(); const ens = Ensforge.create({ publicClient, walletClient, account }).extend(ensActions()); let planId: string | undefined; try { await ens.registration.register({ names: "ensforge-docs-demo.eth", duration: Duration.years(1) }); } catch (error) { if (Errors.is(error)) planId = error.context.planId; } ``` An aborted write (`signal`) rejects with `signal.reason`, which has no plan id. Look the plan up with [`plan.list`](/docs/reference/sdk/plan/list), newest first. **Example** (Listing plans that did not finish) ```ts title="list.ts" import { Ensforge, ensActions } from "@ensforge/sdk"; import { createPublicClient, http } from "viem"; import { sepolia } from "viem/chains"; const publicClient = createPublicClient({ chain: sepolia, transport: http() }); const account = "0xA11Ce00000000000000000000000000000000000"; // the account that sent the plans const ens = Ensforge.create({ publicClient, account }).extend(ensActions()); const failed = await ens.plan.list({ account, status: "failed" }); ``` ## 2. Look at the progress [#2-look-at-the-progress] [`plan.get`](/docs/reference/sdk/plan/get) returns the saved record, or `null` when no plan has that id. ```ts title="get.ts" import { Ensforge, ensActions } from "@ensforge/sdk"; import { createPublicClient, http } from "viem"; import { sepolia } from "viem/chains"; const publicClient = createPublicClient({ chain: sepolia, transport: http() }); const ens = Ensforge.create({ publicClient }).extend(ensActions()); declare const planId: string; const record = await ens.plan.get({ id: planId }); record?.status; // "pending" | "completed" | "failed" record?.submitted; // transaction hashes per step id record?.error; // message of the last failure ``` ## 3. Resume the plan [#3-resume-the-plan] [`plan.resume`](/docs/reference/sdk/plan/resume) continues the plan and resolves once the remaining transactions are submitted. Use `plan.resumeSync` to wait for the receipts. **Example** (Resuming and waiting) ```ts title="resume.ts" import type { EIP1193Provider } from "viem"; declare global { interface Window { ethereum?: EIP1193Provider; } } import { Ensforge, ensActions } from "@ensforge/sdk"; import { createPublicClient, createWalletClient, custom, http } from "viem"; import { sepolia } from "viem/chains"; const publicClient = createPublicClient({ chain: sepolia, transport: http() }); const walletClient = createWalletClient({ chain: sepolia, transport: custom(window.ethereum!) }); const [account] = await walletClient.requestAddresses(); const ens = Ensforge.create({ publicClient, walletClient, account }).extend(ensActions()); declare const planId: string; const { receipts } = await ens.plan.resumeSync({ id: planId }); ``` What resuming does: - A step submitted before is confirmed, not sent again. - A transaction that was dropped, or a bundle that failed, is sent again. - Each remaining step is simulated against current state right before it is sent, because the earlier steps already changed it. - A plan for another chain, such as an L2 primary name, resumes on that chain's clients from the client's `chains`. Resume takes the usual write options, such as `onStep`, `mode` and `account`. ## Register again with the same secret [#register-again-with-the-same-secret] A registration has a second way to continue. The result of `registration.register` carries a `secret`. Call it again with the same options and that `secret` to finish the registration. The options are part of the commitment, so they must match exactly. ## Record a transaction sent elsewhere [#record-a-transaction-sent-elsewhere] When you sent a step's transaction outside ensforge, tell the plan with [`plan.reconcile`](/docs/reference/sdk/plan/reconcile), passing the plan `id`, the `step` id and the `hash`. Resuming then treats the step as submitted. ## Check the result [#check-the-result] After `resumeSync` resolves, `plan.get` reports `status: "completed"`, and `receipts` includes the steps that were submitted before. ## Troubleshooting [#troubleshooting] ### `PLAN_NOT_FOUND` [#plan_not_found] The storage has no plan with that id. The default memory storage forgets plans on reload. Pass `Plan.localStorage()` or your own storage. See [`PLAN_NOT_FOUND`](/docs/reference/errors/PLAN_NOT_FOUND). ### `PLAN_ROUTE_REQUIRED` [#plan_route_required] Some [steps](/docs/reference/glossary#step) were sent through a [route](/docs/reference/glossary#route) (`via`), such as a smart account. Only that route can follow them, and sending them again from the wallet would run them twice. Pass the same `via` to `plan.resume`. See [`PLAN_ROUTE_REQUIRED`](/docs/reference/errors/PLAN_ROUTE_REQUIRED). ### `PLAN_CHAIN_MISMATCH` or `PLAN_ACCOUNT_MISMATCH` [#plan_chain_mismatch-or-plan_account_mismatch] The plan was prepared for another chain or account than the client's. Resume it with the client and account that started it. See [`PLAN_CHAIN_MISMATCH`](/docs/reference/errors/PLAN_CHAIN_MISMATCH) and [`PLAN_ACCOUNT_MISMATCH`](/docs/reference/errors/PLAN_ACCOUNT_MISMATCH). ### `COMMITMENT_TOO_OLD` [#commitment_too_old] A resumed registration passed the registrar's [commitment](/docs/reference/glossary#commitment) window. Start the registration again. See [`COMMITMENT_TOO_OLD`](/docs/reference/errors/COMMITMENT_TOO_OLD). # Pay gas for users > For the complete documentation index, see [llms.txt](https://ensforge.com/llms.txt). Sponsor the gas of a write with an EIP-5792 paymaster service, or through an HCA bundler, so users do not need ETH for fees. Source: https://ensforge.com/docs/sdk/pay-gas-for-users A [paymaster](/docs/reference/glossary#paymaster) pays the gas of a transaction on the user's behalf. ensforge supports two ways to sponsor a write: a paymaster service your wallet understands, and the sponsorship of an [HCA](/docs/reference/glossary#hca) bundler. ## Prerequisites [#prerequisites] - A client with a wallet. See [Send a transaction](/docs/sdk/send-a-transaction). - For the first way, a wallet that supports the EIP-5792 `paymasterService` capability, and the URL of a paymaster service (ERC-7677) that accepts your users. ## Sponsor with a paymaster service [#sponsor-with-a-paymaster-service] Pass `paymaster` to any write. ensforge sends the write through `wallet_sendCalls` with the `paymasterService` capability, so the wallet asks the service to sponsor it. **Example** (Sponsoring a record update) ```ts title="paymaster.ts" import type { EIP1193Provider } from "viem"; declare global { interface Window { ethereum?: EIP1193Provider; } } import { Ensforge, ensActions } from "@ensforge/sdk"; import { createPublicClient, createWalletClient, custom, http } from "viem"; import { sepolia } from "viem/chains"; const publicClient = createPublicClient({ chain: sepolia, transport: http() }); const walletClient = createWalletClient({ chain: sepolia, transport: custom(window.ethereum!) }); const [account] = await walletClient.requestAddresses(); const ens = Ensforge.create({ publicClient, walletClient, account }).extend(ensActions()); const { id } = await ens.record.set({ name: "ensforge-docs-demo.eth", texts: { url: "https://example.com" }, paymaster: { url: "https://paymaster.example.com/rpc", context: { policyId: "ens-profile-updates" }, }, }); ``` - `url` is the paymaster service the wallet calls. - `context` is passed to the service as it is, for example a sponsorship policy. It is optional. - The write goes out as a [bundle](/docs/reference/glossary#bundle) even when it has one call, and the bundle is atomic. `id` is the bundle id. See [Bundle transactions](/docs/sdk/bundle-transactions). `paymaster` is a write option, so `…Sync` forms, `plan.send` and `plan.resume` take it too. ## Sponsor through an HCA bundler [#sponsor-through-an-hca-bundler] An HCA can run a write as a UserOperation through a bundler, and the bundler's paymaster can pay for it. The [executors](/docs/reference/glossary#executor) take their own sponsorship settings: `bundler({ paymaster })`, `pimlico({ sponsor, sponsorshipPolicyId })` and `rhinestone({ sponsored })`. This path is experimental. See [Bundlers](/docs/hca/bundlers), [Rhinestone](/docs/hca/rhinestone) and [Deposits and gas](/docs/hca/deposits-and-gas), and [Use smart accounts](/docs/sdk/use-smart-accounts) for `via`. With the default `owner()` executor, the HCA's transactions come from your wallet, so pass `paymaster` on the write as above. A [route](/docs/reference/glossary#route)'s `plan.fees` shows each fee with `sponsored: true` when the sponsor pays it. ## Check the result [#check-the-result] Use a `…Sync` write, then compare the account's ETH balance before and after. A sponsored write leaves it unchanged except for any `value` the calls send. ## Troubleshooting [#troubleshooting] ### `WALLET_BATCH_UNSUPPORTED` [#wallet_batch_unsupported] The wallet does not support the `paymasterService` capability, or does not send atomic bundles. Remove `paymaster`, or let the user pay. See [`WALLET_BATCH_UNSUPPORTED`](/docs/reference/errors/WALLET_BATCH_UNSUPPORTED). ### `INSUFFICIENT_ETH` [#insufficient_eth] The wallet could not cover the gas, for example because the sponsor did not pay for the bundle. Check the paymaster service's policy. See [`INSUFFICIENT_ETH`](/docs/reference/errors/INSUFFICIENT_ETH). ### `HCA_PAYMASTER_REJECTED` [#hca_paymaster_rejected] An HCA bundler's paymaster refused the operation. See [`HCA_PAYMASTER_REJECTED`](/docs/reference/errors/HCA_PAYMASTER_REJECTED). # Preview before sending > For the complete documentation index, see [llms.txt](https://ensforge.com/llms.txt). Build, simulate and price a write without sending it, then send the exact plan you reviewed, for confirm screens and dry runs. Source: https://ensforge.com/docs/sdk/preview-before-sending Every write can run in three previews first: `.prepare` builds the plan, `.simulate` runs it against the chain, and `.estimateGas` prices it. ensforge never sends a transaction during any of them. ## Prerequisites [#prerequisites] - A client with an account. A wallet client is not needed to preview, only an account address. See [Create a client](/docs/sdk/create-a-client). - Read [How writes work](/docs/sdk/writing-to-ens) if the word [plan](/docs/reference/glossary#plan) is new: a plan is the list of calls a write will make, as plain data. ## 1. Prepare the plan [#1-prepare-the-plan] `.prepare` takes the same options as the write and returns a [`Plan`](/docs/sdk/writing-to-ens). It reads the chain to plan but sends nothing. **Example** (Planning a record update) ```ts title="prepare.ts" import { Ensforge, ensActions } from "@ensforge/sdk"; import { createPublicClient, http } from "viem"; import { sepolia } from "viem/chains"; const publicClient = createPublicClient({ chain: sepolia, transport: http() }); const account = "0xA11Ce00000000000000000000000000000000000"; // the account that will send it const ens = Ensforge.create({ publicClient, account }).extend(ensActions()); const plan = await ens.record.set.prepare({ name: "ensforge-docs-demo.eth", texts: { url: "https://example.com" }, }); plan.steps.map((step) => step.description); plan.calls.length; plan.requirements; // balance or token approval the account needs plan.warnings; // notes for the user, such as an unusual resolver ``` - `plan.steps` are the groups of calls ([steps](/docs/reference/glossary#step)) in order. Most writes have one step; a registration waits between two. - `plan.calls` is every call of every step, flattened. Each has `to`, `data` and `value`. - `plan.requirements` lists what the account must hold first, such as a balance or an ERC-20 approval. - `plan.warnings` are notes that do not block the write. - `plan.deploys` lists contracts the plan creates, at addresses known before sending. `.prepare`, `.simulate` and `.estimateGas` accept the write's own options plus `account` and `via`. They do not take the options that only matter when sending, such as `mode`, `onStep` or `signal`. ## 2. Simulate the plan [#2-simulate-the-plan] `.simulate` runs the plan's calls on the chain without sending them. It returns whether each step would succeed, with the typed error when it would not. **Example** (Checking a write before the wallet prompt) ```ts title="simulate.ts" import { Ensforge, ensActions } from "@ensforge/sdk"; import { createPublicClient, http } from "viem"; import { sepolia } from "viem/chains"; const publicClient = createPublicClient({ chain: sepolia, transport: http() }); const account = "0xA11Ce00000000000000000000000000000000000"; // the account that will send it const ens = Ensforge.create({ publicClient, account }).extend(ensActions()); const simulation = await ens.record.set.simulate({ name: "ensforge-docs-demo.eth", texts: { url: "https://example.com" }, }); if (!simulation.ok) { for (const step of simulation.steps) { if (!step.ok) console.log(step.id, step.error?.code, step.error?.hint); } } ``` A failing step is a value in `simulation.steps`, not a thrown error. `.simulate` throws only when it cannot plan at all, for example [`INVALID_NAME`](/docs/reference/errors/INVALID_NAME). Simulation runs the calls in order, so a call sees the state the earlier ones leave (an approval before a payment). It uses `eth_simulateV1` when the RPC supports it. On other RPCs each call runs alone against current state, and a call that depends on an earlier one can fail in the simulation even though sending would succeed. Send with `simulate: false` there. A registration waits for chain time between its commit and its register transaction. `.simulate` and `.estimateGas` cover the steps before that wait. ensforge simulates each later step right before it sends it. ## 3. Estimate the gas [#3-estimate-the-gas] `.estimateGas` returns the gas and the ETH a plan needs. **Example** (Pricing a write) ```ts title="estimate.ts" import { Ensforge, ensActions } from "@ensforge/sdk"; import { createPublicClient, formatEther, http } from "viem"; import { sepolia } from "viem/chains"; const publicClient = createPublicClient({ chain: sepolia, transport: http() }); const account = "0xA11Ce00000000000000000000000000000000000"; // the account that will send it const ens = Ensforge.create({ publicClient, account }).extend(ensActions()); const { gas, value } = await ens.record.set.estimateGas({ name: "ensforge-docs-demo.eth", texts: { url: "https://example.com" }, }); const gasPrice = await publicClient.getGasPrice(); console.log(`about ${formatEther(gas * gasPrice)} ETH for gas`); ``` - `gas` is the total gas limit across the calls. It includes the fifth more that ensforge adds to each call's estimate when it sends, so a call sent at its estimate cannot run out of gas. - `value` is the total ETH the calls send. ## 4. Send the plan you reviewed [#4-send-the-plan-you-reviewed] Pass the prepared plan to [`plan.send`](/docs/reference/sdk/plan/send). It simulates the plan again, sends it step by step and saves its progress, exactly as the write itself would. **Example** (Reviewing, then sending) ```ts title="review-then-send.ts" import type { EIP1193Provider } from "viem"; declare global { interface Window { ethereum?: EIP1193Provider; } } import { Ensforge, ensActions } from "@ensforge/sdk"; import { createPublicClient, createWalletClient, custom, http } from "viem"; import { sepolia } from "viem/chains"; const publicClient = createPublicClient({ chain: sepolia, transport: http() }); const walletClient = createWalletClient({ chain: sepolia, transport: custom(window.ethereum!) }); const [account] = await walletClient.requestAddresses(); const ens = Ensforge.create({ publicClient, walletClient, account }).extend(ensActions()); const plan = await ens.record.set.prepare({ name: "ensforge-docs-demo.eth", texts: { url: "https://example.com" }, }); const approved = window.confirm(`Send ${plan.calls.length} call(s)?`); if (approved) await ens.plan.send({ plan }); ``` A plan is for one chain and one account. [`plan.send`](/docs/reference/sdk/plan/send) fails with [`PLAN_ACCOUNT_MISMATCH`](/docs/reference/errors/PLAN_ACCOUNT_MISMATCH) or [`PLAN_CHAIN_MISMATCH`](/docs/reference/errors/PLAN_CHAIN_MISMATCH) for a plan prepared for another. A plan that transfers a name token fails with [`PLAN_STALE`](/docs/reference/errors/PLAN_STALE) when the token it moves was reissued since you prepared it. Prepare again in both cases. Plans are plain data, so you can also inspect `plan.calls` and send them with viem yourself, or combine several plans with `Plan.merge`. See [Bundle transactions](/docs/sdk/bundle-transactions). ## Check the result [#check-the-result] A plan sent through `plan.send` returns the same result as any write: `hash`, `hashes`, `id` and `plan`. See [Send a transaction](/docs/sdk/send-a-transaction). ## Troubleshooting [#troubleshooting] ### A simulated step fails with `CONTRACT_REVERTED` [#a-simulated-step-fails-with-contract_reverted] The contract rejected the call and ensforge has no more specific explanation. Read `step.error.context.revert` for the contract's error name. See [`CONTRACT_REVERTED`](/docs/reference/errors/CONTRACT_REVERTED). ### `NOT_OWNER` or `MISSING_ROLES` in a simulation [#not_owner-or-missing_roles-in-a-simulation] The account may not make this change. ensforge checks the account's authority and reports it as a typed error instead of an opaque revert. See [`NOT_OWNER`](/docs/reference/errors/NOT_OWNER) and [`MISSING_ROLES`](/docs/reference/errors/MISSING_ROLES). ### The simulation passes but sending fails [#the-simulation-passes-but-sending-fails] State changed between the preview and the send, or the RPC could not simulate calls that depend on each other. Sending simulates again, so read the error it throws. See [Handle errors](/docs/sdk/handle-errors). # Send a transaction > For the complete documentation index, see [llms.txt](https://ensforge.com/llms.txt). Send any ensforge write with a wallet client, read the transaction hash, and wait for the receipt when the next step needs it. Source: https://ensforge.com/docs/sdk/send-a-transaction Every write in ensforge (`record.set`, `registration.register`, `name.transfer` and the rest) sends the same way. You pass a wallet, call the action, and read the transaction hash it returns. ## Prerequisites [#prerequisites] - A client that can read and sign. See [Create a client](/docs/sdk/create-a-client). - A name your account may change. Examples use Sepolia and the name `ensforge-docs-demo.eth`; replace it with a name you own. ## 1. Create a client with a wallet [#1-create-a-client-with-a-wallet] A write needs a viem wallet client and the account that signs. ensforge reads the chain from the public client and checks that the wallet is on the same chain before it sends anything. **Example** (A Sepolia client with a browser wallet) ```ts title="client.ts" import type { EIP1193Provider } from "viem"; declare global { interface Window { ethereum?: EIP1193Provider; } } import { Ensforge, ensActions } from "@ensforge/sdk"; import { createPublicClient, createWalletClient, custom, http } from "viem"; import { sepolia } from "viem/chains"; const publicClient = createPublicClient({ chain: sepolia, transport: http() }); const walletClient = createWalletClient({ chain: sepolia, transport: custom(window.ethereum!) }); const [account] = await walletClient.requestAddresses(); export const ens = Ensforge.create({ publicClient, walletClient, account }).extend(ensActions()); ``` - `walletClient` signs and sends. It can also be a function that returns the client, for wallets that connect later. - `account` is the default signer. Without it, and without an account on the wallet client, a write fails with [`ACCOUNT_NOT_FOUND`](/docs/reference/errors/ACCOUNT_NOT_FOUND). ## 2. Send the write [#2-send-the-write] Call the action and wait for it to resolve. The Promise resolves once every transaction of the write is submitted, not mined. **Example** (Setting a text record) ```ts title="send.ts" import type { EIP1193Provider } from "viem"; declare global { interface Window { ethereum?: EIP1193Provider; } } import { Ensforge, ensActions } from "@ensforge/sdk"; import { createPublicClient, createWalletClient, custom, http } from "viem"; import { sepolia } from "viem/chains"; const publicClient = createPublicClient({ chain: sepolia, transport: http() }); const walletClient = createWalletClient({ chain: sepolia, transport: custom(window.ethereum!) }); const [account] = await walletClient.requestAddresses(); const ens = Ensforge.create({ publicClient, walletClient, account }).extend(ensActions()); const { hash, hashes, plan } = await ens.record.set({ name: "ensforge-docs-demo.eth", texts: { url: "https://example.com" }, }); ``` [`record.set`](/docs/reference/sdk/record/set) simulates the write first, so a revert becomes a typed error before the wallet prompt. It then asks the wallet to sign. The result holds: | Field | Description | | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------- | | `hash` | Hash of the last transaction. | | `hashes` | Every submitted transaction, in order. Writes with several [steps](/docs/reference/glossary#step), such as a registration, have more than one. | | `id` | The EIP-5792 [bundle](/docs/reference/glossary#bundle) id when the calls went out as one batch, otherwise `undefined`. | | `plan` | The [plan](/docs/sdk/writing-to-ens) that was sent. `plan.id` is what [`plan.resume`](/docs/sdk/continue-after-a-failure) needs. | ## 3. Wait for the receipt [#3-wait-for-the-receipt] Use the `…Sync` form of an action when the next step depends on the transaction being mined. It takes the same options and adds `confirmations` and `timeout`. **Example** (Waiting for two confirmations) ```ts title="send-sync.ts" import type { EIP1193Provider } from "viem"; declare global { interface Window { ethereum?: EIP1193Provider; } } import { Ensforge, ensActions } from "@ensforge/sdk"; import { createPublicClient, createWalletClient, custom, http } from "viem"; import { sepolia } from "viem/chains"; const publicClient = createPublicClient({ chain: sepolia, transport: http() }); const walletClient = createWalletClient({ chain: sepolia, transport: custom(window.ethereum!) }); const [account] = await walletClient.requestAddresses(); const ens = Ensforge.create({ publicClient, walletClient, account }).extend(ensActions()); const { receipt, receipts } = await ens.record.setSync({ name: "ensforge-docs-demo.eth", texts: { url: "https://example.com" }, confirmations: 2, timeout: 120_000, }); receipt.status; // "success" ``` - `confirmations` is the number of confirmations to wait for per transaction. The default is 1. - `timeout` is the milliseconds to wait for each receipt. When it passes, the call fails with [`RECEIPT_TIMEOUT`](/docs/reference/errors/RECEIPT_TIMEOUT). The transaction may still land. - `receipt` is the receipt of the last transaction and `receipts` holds all of them. - A reverted transaction fails with [`TRANSACTION_REVERTED`](/docs/reference/errors/TRANSACTION_REVERTED). ## Follow progress [#follow-progress] Pass `onStep` to see each step of a write wait, submit, confirm or fail. It is how a UI shows "Step 2 of 3". **Example** (Logging every step) ```ts title="progress.ts" import type { EIP1193Provider } from "viem"; declare global { interface Window { ethereum?: EIP1193Provider; } } import { Ensforge, ensActions } from "@ensforge/sdk"; import { createPublicClient, createWalletClient, custom, http } from "viem"; import { sepolia } from "viem/chains"; const publicClient = createPublicClient({ chain: sepolia, transport: http() }); const walletClient = createWalletClient({ chain: sepolia, transport: custom(window.ethereum!) }); const [account] = await walletClient.requestAddresses(); const ens = Ensforge.create({ publicClient, walletClient, account }).extend(ensActions()); await ens.record.setSync({ name: "ensforge-docs-demo.eth", texts: { url: "https://example.com" }, onStep: ({ step, status, hashes }) => { console.log(step.description, status, hashes); }, }); ``` `status` is `waiting` while ensforge waits for chain time before a step (a registration waits at least a minute between its commit and register steps), `submitted` once the step's transactions are sent, `confirmed` once their receipts are in, and `failed` with the error. With `setSync`, the last step reports `confirmed` too. ## Change how a write is sent [#change-how-a-write-is-sent] These options work on every write and every `…Sync` form. | Option | Default | Effect | | ---------------- | --------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `account` | the client's `account` | Signer for this write. | | `simulate` | `true` (the client's `config.simulate`) | Simulate every call before the wallet prompt. | | `mode` | `"auto"` | `"batch"` sends one EIP-5792 call, `"sequential"` one transaction per call, `"auto"` batches when the wallet supports atomic batches. See [Bundle transactions](/docs/sdk/bundle-transactions). | | `maxBundleCalls` | `10` | Most calls in one wallet bundle. | | `signal` | none | Cancels before the next wallet prompt. Transactions already submitted are not undone. | | `onStep` | none | Called as each step waits, is submitted, is confirmed or fails. | | `via` | none | Send through another [route](/docs/reference/glossary#route), such as a smart account. See [Use smart accounts](/docs/sdk/use-smart-accounts). | | `paymaster` | none | Sponsor the gas with an EIP-5792 [paymaster](/docs/reference/glossary#paymaster). See [Pay gas for users](/docs/sdk/pay-gas-for-users). | An aborted write rejects with `signal.reason`, so its plan id is not on the error. Read it from [`plan.list`](/docs/reference/sdk/plan/list) when you need to resume. ## Check the result [#check-the-result] Read the change back with the matching read. After `setSync` resolves, the new value is on chain. ```ts title="check.ts" import { Ensforge, ensActions } from "@ensforge/sdk"; import { createPublicClient, http } from "viem"; import { sepolia } from "viem/chains"; const publicClient = createPublicClient({ chain: sepolia, transport: http() }); const ens = Ensforge.create({ publicClient }).extend(ensActions()); const url = await ens.record.getText({ name: "ensforge-docs-demo.eth", key: "url" }); ``` ## Troubleshooting [#troubleshooting] ### `WALLET_NOT_CONFIGURED` [#wallet_not_configured] The client has no wallet. Pass `walletClient` to `Ensforge.create`. See [`WALLET_NOT_CONFIGURED`](/docs/reference/errors/WALLET_NOT_CONFIGURED). ### `CHAIN_MISMATCH` [#chain_mismatch] The wallet is on another chain than the client. Switch the wallet's network or create the client for the wallet's chain. See [`CHAIN_MISMATCH`](/docs/reference/errors/CHAIN_MISMATCH). ### `USER_REJECTED` [#user_rejected] The user closed or rejected the wallet prompt. Nothing was sent. Treat it as a normal outcome, not a failure. See [`USER_REJECTED`](/docs/reference/errors/USER_REJECTED). ### `RECEIPT_TIMEOUT` [#receipt_timeout] `setSync` stopped waiting, but the transaction may still be pending. Check the hash before you send again. See [`RECEIPT_TIMEOUT`](/docs/reference/errors/RECEIPT_TIMEOUT). ### `INSUFFICIENT_ETH` [#insufficient_eth] The account cannot pay for the gas or value of a step. Every write can fail this way. Fund the account, or sponsor the gas with a [paymaster](/docs/sdk/pay-gas-for-users). See [`INSUFFICIENT_ETH`](/docs/reference/errors/INSUFFICIENT_ETH). ### `CONTRACT_NOT_DEPLOYED` [#contract_not_deployed] The chain has no ENS contract at an address the write calls. Every action can fail this way when the client is on the wrong chain. See [`CONTRACT_NOT_DEPLOYED`](/docs/reference/errors/CONTRACT_NOT_DEPLOYED). For the rest of the codes and when a retry is safe, see [Handle errors](/docs/sdk/handle-errors). # Use smart accounts > For the complete documentation index, see [llms.txt](https://ensforge.com/llms.txt). Send writes from a smart-contract wallet, or route them through an ENS Hosted Contract Account (HCA) with the via option. Source: https://ensforge.com/docs/sdk/use-smart-accounts A **smart account** is an account that is a contract, so it can run several calls in one transaction. ensforge works with smart accounts in two ways: through your wallet, with no code change, and through a [route](/docs/reference/glossary#route) (`via`), which sends a write another way. ## Prerequisites [#prerequisites] - A client with a wallet. See [Send a transaction](/docs/sdk/send-a-transaction). - For routes, the `@ensforge/hca` package. It is experimental: its API can change in a minor release. See [How HCAs work](/docs/hca/how-it-works). ## A smart-account wallet needs nothing extra [#a-smart-account-wallet-needs-nothing-extra] When the wallet is a smart account (a contract wallet, or an account upgraded with EIP-7702) and it supports EIP-5792 atomic batches, `mode: "auto"` sends a write's calls as one [bundle](/docs/reference/glossary#bundle). The signer is the wallet's account and ENS sees it as the sender. See [Bundle transactions](/docs/sdk/bundle-transactions). ## Route a write with `via` [#route-a-write-with-via] A route changes how a [plan](/docs/reference/glossary#plan) is sent. Pass `via` to any write and ensforge hands the plan to the route, which can rewrite it and, if it has its own sender, send it too. `hca()` from `@ensforge/hca` is the route that ships with ensforge. It runs the write from the signer's ENS Hosted Contract Account ([HCA](/docs/reference/glossary#hca)): the account is deployed on first use, consecutive steps run as one atomic `executeByOwner` call, and the approvals it needs to move the owner's names are added as owner transactions. **Example** (Migrating several names in one or two transactions) ```ts title="route.ts" import type { EIP1193Provider } from "viem"; declare global { interface Window { ethereum?: EIP1193Provider; } } import { hca, hcaActions } from "@ensforge/hca"; import { Ensforge, ensActions } from "@ensforge/sdk"; import { createPublicClient, createWalletClient, custom, http } from "viem"; import { sepolia } from "viem/chains"; const publicClient = createPublicClient({ chain: sepolia, transport: http() }); const walletClient = createWalletClient({ chain: sepolia, transport: custom(window.ethereum!) }); const [account] = await walletClient.requestAddresses(); const ens = Ensforge.create({ publicClient, walletClient, account }) .extend(ensActions()) .extend(hcaActions()); await ens.migration.migrateSync({ names: ["ensforge-docs-demo.eth", "ensforge-docs-demo-2.eth"], via: hca(), }); ``` - `hcaActions()` adds `ens.hca.*`, such as `ens.hca.get()` to read the account. - `via: hca()` is never chosen for you. Route through an HCA only with the user's agreement. - The HCA is the sender (`msg.sender`) of the calls, so it needs authority over what they touch, such as the [roles](/docs/reference/glossary#role) a write uses. Migration and registration plan for it; other writes need the HCA to hold the roles they use. ## Preview a routed write [#preview-a-routed-write] `via` also applies to `.prepare`, `.simulate` and `.estimateGas`, so a preview shows the plan as the route will send it. A route may report extra costs in `plan.fees`, each marked `sponsored` or not. See [Preview before sending](/docs/sdk/preview-before-sending). ## Resume a routed write [#resume-a-routed-write] A route sends some steps itself and ensforge saves a reference for each, such as a UserOperation hash. Resume the plan with the same `via`, so the route can follow those steps. Without it, `plan.resume` fails with [`PLAN_ROUTE_REQUIRED`](/docs/reference/errors/PLAN_ROUTE_REQUIRED). See [Continue after a failure](/docs/sdk/continue-after-a-failure). ## Handle route errors [#handle-route-errors] A route fails with its own errors. `hca()` fails with `HcaError`, which is outside the SDK's per-action error types. Check for it separately. ```ts title="route-errors.ts" import { HcaError } from "@ensforge/hca"; declare const error: unknown; if (error instanceof HcaError) { console.log(error.code, error.executor); } ``` The codes, such as [`HCA_NOT_VERIFIED`](/docs/reference/errors/HCA_NOT_VERIFIED) and [`HCA_EXECUTOR_UNSUPPORTED`](/docs/reference/errors/HCA_EXECUTOR_UNSUPPORTED), have their own pages. ## Limits [#limits] - `via: hca()` does not run L2 primary-name plans. The HCA lives on Ethereum. - A route's `send` reports a reference, not a transaction hash, until the step lands. To build a route of your own, see [Extend the client](/docs/sdk/extend-the-client). To choose how the HCA executes, its [executor](/docs/reference/glossary#executor) (your wallet, a bundler, a session), see [Your wallet](/docs/hca/your-wallet) and [Bundlers](/docs/hca/bundlers). ## Check the result [#check-the-result] `migrateSync` resolves with `receipts` like any write. Read the account with `ens.hca.get()`. ## Troubleshooting [#troubleshooting] ### `HCA_NOT_VERIFIED` [#hca_not_verified] The signer's HCA has problems ensforge will not route through, or the write has no signer. Read `details` on the error. See [`HCA_NOT_VERIFIED`](/docs/reference/errors/HCA_NOT_VERIFIED). ### `HCA_EXECUTOR_UNSUPPORTED` [#hca_executor_unsupported] No executor in `executors` can run the request, for example a `session` with only `owner()`. See [`HCA_EXECUTOR_UNSUPPORTED`](/docs/reference/errors/HCA_EXECUTOR_UNSUPPORTED). ### `MISSING_ROLES` after routing [#missing_roles-after-routing] The HCA, not your wallet, is the sender, and it lacks a role the write needs. Grant the role to the HCA, or send the write without `via`. See [`MISSING_ROLES`](/docs/reference/errors/MISSING_ROLES). # Move a name to ENSv2 > For the complete documentation index, see [llms.txt](https://ensforge.com/llms.txt). Check whether an ENSv1 name can migrate to ENSv2, then migrate it together with its resolver records and subnames, step by step. Source: https://ensforge.com/docs/sdk/move-a-name-to-ensv2 This page is about ENS versions: a name registered on [ENSv1](/docs/reference/glossary#ensv1) (the original contracts) can [migrate](/docs/reference/glossary#migration) to [ENSv2](/docs/reference/glossary#ensv2) (the new registries). Most tasks in these docs work on either version without a choice from you. Migration is the task where the version matters, because it moves a name from one to the other. You will check a name, migrate it, and confirm it now lives on ENSv2. For the background, see [ENS versions under the hood](/docs/sdk/ens-versions). ## Prerequisites [#prerequisites] - A wallet client for the account that holds the name's token (the [registrant](/docs/reference/glossary#registrant) or the [Name Wrapper](/docs/reference/glossary#name-wrapper) owner), or an approved operator. See [Create a client](/docs/sdk/create-a-client). - A chain with ENSv2 deployed, such as Sepolia. - Optional: an [indexer](/docs/reference/glossary#indexer), so ensforge can discover the name's records and subnames. See [Connect an indexer](/docs/sdk/connect-an-indexer). ## What migration does [#what-migration-does] Migration transfers the name's token to the migration controllers, creates the ENSv2 state, and recreates what you want to keep. Your account sends the transactions and no token approvals are needed. ```mermaid flowchart LR A[ENSv1 name] -->|renews if in grace| B[Resolver and records] B -->|recreates| C[Subnames] C -->|sends the token to| D[Migration controllers] D -->|creates| E[ENSv2 name] ``` After it, ENSv2 holds the name and its ENSv1 record is held by the Graveyard. Resolver, subregistry and roles follow the route the name took. ## 1. Check the name [#1-check-the-name] [`migration.get`](/docs/reference/sdk/migration/get) reports the route, what blocks it, the resolver plan and what the name becomes. **Example** (Checking a Name Before Migrating) ```ts title="migration-get.ts" import { createPublicClient, createWalletClient, http, type Hex } from "viem"; import { privateKeyToAccount } from "viem/accounts"; import { sepolia } from "viem/chains"; import { Ensforge, ensActions } from "@ensforge/sdk"; const account = privateKeyToAccount(process.env.PRIVATE_KEY as Hex); const transport = http(process.env.SEPOLIA_RPC_URL); const ens = Ensforge.create({ publicClient: createPublicClient({ chain: sepolia, transport }), walletClient: createWalletClient({ account, chain: sepolia, transport }), }).extend(ensActions()); const status = await ens.migration.get({ name: "ensforge-docs-demo.eth" }); ``` `status.status` is one of: | `status` | Meaning | | -------------- | ------------------------------------------------------- | | `eligible` | The name can migrate now. | | `blocked` | See `blockers`. | | `migrated` | The name was already migrated to ENSv2. | | `not-required` | The name was registered on ENSv2, or is not registered. | `status.route` says how the name moves: | `route` | Name | | ------------------ | ----------------------------------------------------------------------------------------------------------------- | | `unwrapped` | A `.eth` second-level name on the ENSv1 registrar. | | `wrapped-unlocked` | A wrapped `.eth` name without `cannotUnwrap` burned. | | `wrapped-locked` | A wrapped `.eth` name with `cannotUnwrap` burned. ENSv2 gives it a WrapperRegistry whose roles follow its fuses. | | `locked-child` | A locked or emancipated wrapped subname. It moves into its parent's WrapperRegistry once the parent has migrated. | `blockers` explain why a name cannot migrate: | Blocker | Meaning | | --------------------- | ---------------------------------------------------------------------------------------------------------------------------------- | | `not-eth` | Not a `.eth` name or one of its subnames. | | `expired` | The ENSv1 registration expired. A name in its [grace period](/docs/reference/glossary#grace-period): renew first, or pass `renew`. | | `not-reserved` | ENSv2 holds no reservation for the name. | | `not-owner` | The account neither holds the token nor is an approved operator. | | `cannot-transfer` | The `cannotTransfer` fuse is burned. | | `frozen-approval` | `cannotApprove` is burned while a token approval is set. | | `parent-not-migrated` | A locked child whose parent is still on ENSv1. | | `unlocked-child` | A subname without its own token route. It is recreated through its parent. | | `locked-resolver` | `cannotSetResolver` keeps a resolver that could no longer be edited. | | `unknown-label` | Only the label's hash is known. | `status.resolver.plan` shows what `migrate` does with the current resolver for the same `resolver` option, and `status.after` shows the registry, subregistry, expiry and roles the name gets. With an indexer, `status.discovered` lists the records and subnames that `migrate` carries over by default. ## 2. Migrate [#2-migrate] [`migration.migrate`](/docs/reference/sdk/migration/migrate) takes names, each as a string or with the records and subnames to keep. `migration.migrateSync` waits for the receipts and verifies the migrated state. **Example** (Migrating a Name With Its Profile) ```ts title="migrate.ts" import { createPublicClient, createWalletClient, http, type Hex } from "viem"; import { privateKeyToAccount } from "viem/accounts"; import { sepolia } from "viem/chains"; import { Ensforge, ensActions } from "@ensforge/sdk"; const account = privateKeyToAccount(process.env.PRIVATE_KEY as Hex); const transport = http(process.env.SEPOLIA_RPC_URL); const ens = Ensforge.create({ publicClient: createPublicClient({ chain: sepolia, transport }), walletClient: createWalletClient({ account, chain: sepolia, transport }), }).extend(ensActions()); const { plan } = await ens.migration.migrateSync({ names: { name: "ensforge-docs-demo.eth", records: { texts: { url: "https://example.com" } }, subnames: ["pay"], }, }); ``` - `records` is the name's full profile, written to its new resolver. - `subnames` lists the subnames to recreate, at any depth, as full names or relative to the name (`"pay"`, `"b.a"`). `[]` recreates none. - An interrupted migration can run again. Existing resolvers and registries are reused. | Option | Type | Default | Description | | ------------------------ | -------------------------------------- | ---------------------------------------------------------- | ------------------------------------------------------------------------------------ | | `names` | `string \| NameInput \| NameInput[]` | required | Names, or names with `records` and `subnames`. | | `resolver` | `"new" \| "owned" \| "keep" \| string` | `"new"` for names on an ENS public resolver, else `"keep"` | What happens to the resolver. | | `owner` | `string` | each token's holder | ENSv2 owner of the names. | | `allowIncompleteRecords` | `boolean` | `false` | Copy the common records when a name's records are not given and there is no indexer. | | `allowLeavingSubnames` | `boolean` | `false` | Migrate even when a listed subname cannot be recreated. | | `preserveManager` | `boolean` | `false` | Give each unwrapped name's ENSv1 manager `setResolver` and the record setter roles. | | `migrateParents` | `boolean` | `false` | Migrate the ENSv1 parents of locked subnames first. | | `renew` | `{ duration, paymentToken? }` | none | Renew names in their grace period first. | `resolver` choices: | Value | Result | | ---------- | ---------------------------------------------------------------------------------- | | `"new"` | A PermissionedResolver created for the name, with its records copied in. | | `"owned"` | The account's shared PermissionedResolver (the ENS app's address), records copied. | | `"keep"` | The current resolver. Records on an ENSv1 public resolver become read-only. | | An address | A resolver you name. | ENSv2 drops ENSv1 subnames that are not recreated, and records left on an ENSv1 public resolver become read-only. Without an indexer, a name whose resolver holds records fails with `RECORDS_UNKNOWN` unless you pass `records` or `allowIncompleteRecords`. Pass every record and subname you want to keep. Subname records stay on their ENSv1 resolvers. ## 3. Check the result [#3-check-the-result] Read the name with [`name.get`](/docs/reference/sdk/name/get). A migrated name has `kind: "v2-migrated"` and `migrated: true`. `migrateSync` also verifies the state: a mismatch fails with `VERIFICATION_FAILED`. ## Wrapped and locked names [#wrapped-and-locked-names] - A wrapped name that is not locked migrates like an unwrapped one. - A [locked](/docs/reference/glossary#locked) name gets a WrapperRegistry. Its non-emancipated children are registered there after it migrates, which works only when the account sending the migration becomes its owner and `cannotCreateSubdomain` is not burned. - [Emancipated](/docs/reference/glossary#emancipated) children of a locked name migrate on their own, and the plan carries a warning. Use `migrateParents` to move a locked child's parent first. See [Wrapped names](/docs/sdk/wrapped-names) and [Lock permissions with fuses](/docs/sdk/fuses). ## Troubleshooting [#troubleshooting] ### `NOT_ELIGIBLE` [#not_eligible] A blocker applies. The error lists them, and `migration.get` shows them before you send. See [`NOT_ELIGIBLE`](/docs/reference/errors/NOT_ELIGIBLE). ### `ALREADY_MIGRATED` [#already_migrated] The name is already on ENSv2. See [`ALREADY_MIGRATED`](/docs/reference/errors/ALREADY_MIGRATED). ### `RECORDS_UNKNOWN` [#records_unknown] The name's records are not known, so they cannot be copied. Connect an indexer, pass `records`, or pass `allowIncompleteRecords`. See [`RECORDS_UNKNOWN`](/docs/reference/errors/RECORDS_UNKNOWN). ### `VERIFICATION_FAILED` [#verification_failed] The migration was sent, but the name's ENSv2 state differs from the plan. See [`VERIFICATION_FAILED`](/docs/reference/errors/VERIFICATION_FAILED). ### `NOT_OWNER` or `FUSE_BURNED` [#not_owner-or-fuse_burned] The account may not move a token. See [`NOT_OWNER`](/docs/reference/errors/NOT_OWNER) and [`FUSE_BURNED`](/docs/reference/errors/FUSE_BURNED). ### `UNSUPPORTED_ON_DEPLOYMENT` [#unsupported_on_deployment] The chain has no ENSv2 deployment. See [`UNSUPPORTED_ON_DEPLOYMENT`](/docs/reference/errors/UNSUPPORTED_ON_DEPLOYMENT). # Registries and subregistries > For the complete documentation index, see [llms.txt](https://ensforge.com/llms.txt). Inspect, deploy, attach and upgrade the ENSv2 registries and subregistries that hold the children of a name, with role checks. Source: https://ensforge.com/docs/sdk/registries-and-subregistries This page is about [ENSv2](/docs/reference/glossary#ensv2) only. [ENSv1](/docs/reference/glossary#ensv1) has one [registry](/docs/reference/glossary#registry) for every name. ENSv2 gives each name that has children its own registry, and calls it the name's **subregistry**. Everything here fails with [`UNSUPPORTED_PROTOCOL`](/docs/reference/errors/UNSUPPORTED_PROTOCOL) or [`UNSUPPORTED_ON_DEPLOYMENT`](/docs/reference/errors/UNSUPPORTED_ON_DEPLOYMENT) for ENSv1 names and chains without ENSv2. You will inspect the registry that holds a name's children, deploy one, attach it, upgrade it and set its metadata URI. Most apps never need this: [`subname.create`](/docs/sdk/create-subnames) deploys and attaches a registry when a parent has none. ## How registries nest [#how-registries-nest] A registry holds the names directly under it. Each name points to a subregistry for its own children. ```mermaid flowchart TD R[root registry] -->|eth| E[.eth registry] E -->|ensforge-docs-demo| U[ensforge-docs-demo.eth subregistry] U -->|pay| C[pay.ensforge-docs-demo.eth] ``` | `kind` | What the registry is | | --------- | ----------------------------------------------------------------------------------------------------------------------- | | `root` | The root registry. | | `eth` | The `.eth` registry. | | `user` | A UserRegistry that holds a name's children. | | `wrapper` | A WrapperRegistry for a name migrated from the NameWrapper. See [Move a name to ENSv2](/docs/sdk/move-a-name-to-ensv2). | | `unknown` | Any other contract. | An **emancipated** registry is one whose root [role](/docs/reference/glossary#role) holders cannot take children back: they cannot unregister them, repoint them or control their transfers. Children of an emancipated registry keep what they were given. ## Prerequisites [#prerequisites] - A wallet client for an account with the roles each write needs. See [Roles and permissions](/docs/sdk/roles-and-permissions). - An ENSv2 name. See [Register a name](/docs/sdk/register-a-name). ## 1. Inspect a registry [#1-inspect-a-registry] [`registry.get`](/docs/reference/sdk/registry/get) reads a name's subregistry (`{ name }`) or any registry by address (`{ registry }`). **Example** (Inspecting a Name's Subregistry) ```ts title="registry-get.ts" import { createPublicClient, http } from "viem"; import { sepolia } from "viem/chains"; import { Ensforge, ensActions } from "@ensforge/sdk"; const ens = Ensforge.create({ publicClient: createPublicClient({ chain: sepolia, transport: http() }), }).extend(ensActions()); const registry = await ens.registry.get({ name: "ensforge-docs-demo.eth" }); ``` It returns `null` when the name has no subregistry, unless you pass `strict: true`. The result has: | Field | Meaning | | ----------------- | -------------------------------------------------------------------------------- | | `address`, `kind` | The contract and what it is. | | `implementation` | The implementation behind the proxy, or `null` when it is not a proxy. | | `parent` | The registry above it and the label it sits under, as set with `setParent`. | | `canonicalName` | The name whose children it holds, or `null` when not reachable. | | `uri`, `renderer` | Token metadata settings. | | `emancipated` | Whether root role holders can take children back. | | `upgrade` | `latest` implementation, whether this registry is `eligible`, and the `blocker`. | Pass `account` to include whether it holds the `upgrade` role. ## 2. Deploy a registry [#2-deploy-a-registry] [`registry.deploy`](/docs/reference/sdk/registry/deploy) deploys a UserRegistry as a verifiable proxy at an address known before sending. With `attachTo` it also becomes that name's subregistry in the same plan. **Example** (Deploying and Attaching a Subregistry) ```ts title="registry-deploy.ts" import { createPublicClient, createWalletClient, http, type Hex } from "viem"; import { privateKeyToAccount } from "viem/accounts"; import { sepolia } from "viem/chains"; import { Ensforge, ensActions } from "@ensforge/sdk"; const account = privateKeyToAccount(process.env.PRIVATE_KEY as Hex); const transport = http(process.env.SEPOLIA_RPC_URL); const ens = Ensforge.create({ publicClient: createPublicClient({ chain: sepolia, transport }), walletClient: createWalletClient({ account, chain: sepolia, transport }), }).extend(ensActions()); const { registry } = await ens.registry.deploySync({ attachTo: "ensforge-docs-demo.eth", }); ``` | Option | Type | Default | Description | | ------------- | ---------------------- | ---------- | ------------------------------------------------------------ | | `owner` | `string` | the signer | Gets every root role. | | `grants` | `{ account, roles }[]` | none | Extra root role grants. | | `emancipated` | `boolean` | `false` | Withhold the roles that would let owners take children back. | | `attachTo` | `string` | none | ENSv2 name to attach it to. | | `salt` | `bigint` | random | CREATE2 salt. With the account, it decides the address. | ## 3. Attach or detach a registry [#3-attach-or-detach-a-registry] [`registry.attach`](/docs/reference/sdk/registry/attach) sets a name's subregistry. It calls `setSubregistry` on the registry holding the name, then `setParent` on the new registry so its canonical name points back. Pass `setParent: false` to skip the second call. `registry: null` detaches the current subregistry. **Example** (Attaching a Registry) ```ts title="registry-attach.ts" import { createPublicClient, createWalletClient, http, type Hex } from "viem"; import { privateKeyToAccount } from "viem/accounts"; import { sepolia } from "viem/chains"; import { Ensforge, ensActions } from "@ensforge/sdk"; const account = privateKeyToAccount(process.env.PRIVATE_KEY as Hex); const transport = http(process.env.SEPOLIA_RPC_URL); const ens = Ensforge.create({ publicClient: createPublicClient({ chain: sepolia, transport }), walletClient: createWalletClient({ account, chain: sepolia, transport }), }).extend(ensActions()); await ens.registry.attachSync({ name: "ensforge-docs-demo.eth", registry: "0x1111111111111111111111111111111111111111", // a registry you deployed }); ``` ## 4. Upgrade a registry [#4-upgrade-a-registry] [`registry.upgrade`](/docs/reference/sdk/registry/upgrade) moves a registry to the deployment's latest implementation. It checks before signing what `registry.get` reports: you hold the `upgrade` root role, the target accepts the current implementation, and, for emancipated registries, the upgrade set lists it. **Example** (Upgrading a Subregistry) ```ts title="registry-upgrade.ts" import { createPublicClient, createWalletClient, http, type Hex } from "viem"; import { privateKeyToAccount } from "viem/accounts"; import { sepolia } from "viem/chains"; import { Ensforge, ensActions } from "@ensforge/sdk"; const account = privateKeyToAccount(process.env.PRIVATE_KEY as Hex); const transport = http(process.env.SEPOLIA_RPC_URL); const ens = Ensforge.create({ publicClient: createPublicClient({ chain: sepolia, transport }), walletClient: createWalletClient({ account, chain: sepolia, transport }), }).extend(ensActions()); const info = await ens.registry.get({ name: "ensforge-docs-demo.eth", account: account.address }); if (info?.upgrade.eligible) { await ens.registry.upgradeSync({ name: "ensforge-docs-demo.eth" }); } ``` When `upgrade.eligible` is `false`, `upgrade.blocker` says why: | `blocker` | Meaning | | ----------------- | ------------------------------------------------------------------------------------------------------------------------------- | | `up-to-date` | It already runs the latest implementation. | | `not-approved` | The latest implementation does not accept the current one, or the registry is emancipated and its upgrade set does not list it. | | `unauthorized` | The account lacks the `upgrade` root role. | | `not-upgradeable` | ensforge knows no upgrade target for this kind of registry. | On mainnet, user registries created before the 2026-11-17 redeploy report `not-approved`: the current UserRegistry does not accept their implementation, and `registry.upgrade` fails with `UPGRADE_NOT_APPROVED`. They keep their token-level `renew` behaviour. ## 5. Set the metadata URI [#5-set-the-metadata-uri] [`registry.setUri`](/docs/reference/sdk/registry/set-uri) points a registry's token metadata at your own service. It needs the `setUri` root role. It keeps the current URI renderer unless you pass `renderer`, and `renderer: null` removes it. **Example** (Setting a Metadata URI) ```ts title="registry-set-uri.ts" import { createPublicClient, createWalletClient, http, type Hex } from "viem"; import { privateKeyToAccount } from "viem/accounts"; import { sepolia } from "viem/chains"; import { Ensforge, ensActions } from "@ensforge/sdk"; const account = privateKeyToAccount(process.env.PRIVATE_KEY as Hex); const transport = http(process.env.SEPOLIA_RPC_URL); const ens = Ensforge.create({ publicClient: createPublicClient({ chain: sepolia, transport }), walletClient: createWalletClient({ account, chain: sepolia, transport }), }).extend(ensActions()); await ens.registry.setUriSync({ name: "ensforge-docs-demo.eth", uri: "https://example.com/names/{id}.json", }); ``` ## Troubleshooting [#troubleshooting] ### `UPGRADE_NOT_APPROVED` [#upgrade_not_approved] The latest implementation does not accept this registry's implementation. Read `registry.get` for the `blocker`. See [`UPGRADE_NOT_APPROVED`](/docs/reference/errors/UPGRADE_NOT_APPROVED). ### `MISSING_ROLES` [#missing_roles] The account lacks a root role the write needs: `upgrade`, `setUri` or the roles on the parent. See [Roles and permissions](/docs/sdk/roles-and-permissions) and [`MISSING_ROLES`](/docs/reference/errors/MISSING_ROLES). ### `UNSUPPORTED_PROTOCOL` [#unsupported_protocol] The name is an ENSv1 name. Registries exist on ENSv2 only. See [Move a name to ENSv2](/docs/sdk/move-a-name-to-ensv2). # Resolvers and shared records > For the complete documentation index, see [llms.txt](https://ensforge.com/llms.txt). Create ENSv2 permissioned resolvers, share one set of records between several names, and upgrade a resolver in place safely. Source: https://ensforge.com/docs/sdk/resolvers-and-shared-records This page is about [ENSv2](/docs/reference/glossary#ensv2) [resolvers](/docs/reference/glossary#resolver). On [ENSv1](/docs/reference/glossary#ensv1) most names use the shared public resolver, which has no roles. ENSv2 uses the **PermissionedResolver**: a resolver whose writes are controlled by [roles](/docs/reference/glossary#role), and in which each name has a **record ID** that says which set of records it reads and writes. Two names with the same record ID on the same resolver share their records. You will create a resolver, link names to one record set and upgrade the resolver. ## Prerequisites [#prerequisites] - A wallet client. See [Create a client](/docs/sdk/create-a-client). - An ENSv2 name. Names registered with ensforge already get their own resolver. See [Register a name](/docs/sdk/register-a-name). - For roles, see [Roles and permissions](/docs/sdk/roles-and-permissions). ## 1. Create a resolver [#1-create-a-resolver] [`resolver.create`](/docs/reference/sdk/resolver/create) deploys a PermissionedResolver as a verifiable proxy from the VerifiableFactory. Its address is known before sending (`plan.deploys`) and returned as `resolver`. **Example** (Creating a Resolver for a Name) ```ts title="resolver-create.ts" import { createPublicClient, createWalletClient, http, type Hex } from "viem"; import { privateKeyToAccount } from "viem/accounts"; import { sepolia } from "viem/chains"; import { Ensforge, ensActions } from "@ensforge/sdk"; const account = privateKeyToAccount(process.env.PRIVATE_KEY as Hex); const transport = http(process.env.SEPOLIA_RPC_URL); const ens = Ensforge.create({ publicClient: createPublicClient({ chain: sepolia, transport }), walletClient: createWalletClient({ account, chain: sepolia, transport }), }).extend(ensActions()); const { resolver } = await ens.resolver.createSync({ name: "ensforge-docs-demo.eth", records: { texts: { url: "https://example.com" } }, }); ``` With `name`, the `records` are written while the resolver is initialised and the name is pointed at it in the same plan. | Option | Type | Default | Description | | --------- | ---------------------- | ---------- | --------------------------------------------------------------- | | `name` | `string` | none | Name to point at the new resolver. Required for `records`. | | `records` | `object` | none | Records for `name`. | | `owner` | `string` | the signer | Gets every resolver role. | | `grants` | `{ account, roles }[]` | none | Extra role grants. | | `salt` | `bigint` | random | CREATE2 salt. With the sending account, it decides the address. | The address comes from the sending account and `salt`. Send from the account the plan was prepared for. A relayer or a bundler that is not the account itself produces a different address. If you reuse a `salt` that the account already used, `resolver.create` fails with `SALT_TAKEN` before sending. The error's `context.contract` is the existing resolver. Point the name at it with [`resolver.set`](/docs/sdk/change-the-resolver). ## 2. Share records between names [#2-share-records-between-names] [`resolver.link`](/docs/reference/sdk/resolver/link) makes a name read and write the records of another name on the same resolver. Use it for aliases of a main name. **Example** (Making an Alias Share a Main Name's Records) ```ts title="resolver-link.ts" import { createPublicClient, createWalletClient, http, type Hex } from "viem"; import { privateKeyToAccount } from "viem/accounts"; import { sepolia } from "viem/chains"; import { Ensforge, ensActions } from "@ensforge/sdk"; const account = privateKeyToAccount(process.env.PRIVATE_KEY as Hex); const transport = http(process.env.SEPOLIA_RPC_URL); const ens = Ensforge.create({ publicClient: createPublicClient({ chain: sepolia, transport }), walletClient: createWalletClient({ account, chain: sepolia, transport }), }).extend(ensActions()); await ens.resolver.linkSync({ name: "ensforge-docs-alias.eth", to: "ensforge-docs-demo.eth", }); ``` - Both names must use the same PermissionedResolver, and the target must already have records. - It needs the `link` role on the resolver. - `to` is a name, or `{ recordId }` from `resolver.getLink`. Check whether two names share records with [`resolver.getLink`](/docs/reference/sdk/resolver/get-link). Linked names have the same `recordId` on the same `resolver`. **Example** (Checking Whether Names Share Records) ```ts title="resolver-get-link.ts" import { createPublicClient, http } from "viem"; import { sepolia } from "viem/chains"; import { Ensforge, ensActions } from "@ensforge/sdk"; const ens = Ensforge.create({ publicClient: createPublicClient({ chain: sepolia, transport: http() }), }).extend(ensActions()); const [a, b] = await Promise.all([ ens.resolver.getLink({ name: "ensforge-docs-alias.eth" }), ens.resolver.getLink({ name: "ensforge-docs-demo.eth" }), ]); const shared = a !== null && b !== null && a.resolver === b.resolver && a.recordId === b.recordId; ``` `getLink` returns `null` when the name has no records on the resolver yet. Every name gets its own record ID on its first write. Setter roles on a PermissionedResolver cover every name that uses it. Names that share a resolver, for example subnames created with `resolver: "parent"`, share who can edit. Keep the default of one resolver per name to scope access per name. ## 3. Upgrade a resolver [#3-upgrade-a-resolver] [`resolver.upgrade`](/docs/reference/sdk/resolver/upgrade) moves a name's PermissionedResolver to the deployment's latest implementation, or to `implementation` if you pass one. It checks that the target accepts the current implementation (`canUpgradeFrom`) before sending, and it needs the `upgrade` role on the resolver. **Example** (Upgrading a Resolver) ```ts title="resolver-upgrade.ts" import { createPublicClient, createWalletClient, http, type Hex } from "viem"; import { privateKeyToAccount } from "viem/accounts"; import { sepolia } from "viem/chains"; import { Ensforge, ensActions } from "@ensforge/sdk"; const account = privateKeyToAccount(process.env.PRIVATE_KEY as Hex); const transport = http(process.env.SEPOLIA_RPC_URL); const ens = Ensforge.create({ publicClient: createPublicClient({ chain: sepolia, transport }), walletClient: createWalletClient({ account, chain: sepolia, transport }), }).extend(ensActions()); await ens.resolver.upgradeSync({ name: "ensforge-docs-demo.eth" }); ``` ## Limits to know [#limits-to-know] - The PermissionedResolver has no `pubkey` or DNS records, so [migration](/docs/reference/glossary#migration) does not copy them. - `record.set({ clear: true })` links the name to record 0, which reads the resolver's default record. See [Set records](/docs/sdk/set-records). - `resolver: "default"` is for ENSv1 names only. ENSv2's public resolver (PublicResolverV2) only serves names the NameWrapper knows, so ENSv2 names fail with `UNSUPPORTED_PROTOCOL`. ## Troubleshooting [#troubleshooting] ### `SALT_TAKEN` [#salt_taken] The account already deployed a resolver with this salt. Use the one in `context.contract`, or pass another `salt`. See [`SALT_TAKEN`](/docs/reference/errors/SALT_TAKEN). ### `MISSING_ROLES` [#missing_roles] The account lacks `link` or `upgrade` on the resolver. See [`MISSING_ROLES`](/docs/reference/errors/MISSING_ROLES). ### `UPGRADE_NOT_APPROVED` [#upgrade_not_approved] The target implementation does not accept the current one. See [`UPGRADE_NOT_APPROVED`](/docs/reference/errors/UPGRADE_NOT_APPROVED). # Roles and permissions > For the complete documentation index, see [llms.txt](https://ensforge.com/llms.txt). Read, grant and revoke ENSv2 roles, and check what an account may do with a name before it tries to change anything on it. Source: https://ensforge.com/docs/sdk/roles-and-permissions This page is about [ENSv2](/docs/reference/glossary#ensv2) roles. On [ENSv1](/docs/reference/glossary#ensv1) an [owner](/docs/reference/glossary#owner), a [manager](/docs/reference/glossary#manager) and operators control a name, limited by [Name Wrapper](/docs/reference/glossary#name-wrapper) [fuses](/docs/reference/glossary#fuse). ENSv2 replaces that with **roles**: each account holds specific powers, such as changing the resolver, on a name or at the root of a [registry](/docs/reference/glossary#registry) or [resolver](/docs/reference/glossary#resolver). The [permission](/docs/reference/glossary#permission) reads below answer for both versions, so UIs need no branch. You will check what an account may do, grant and revoke roles, and give an app access to some records. ## Prerequisites [#prerequisites] - A client. Reads need only a public client. Writes need a wallet client. See [Create a client](/docs/sdk/create-a-client). - An ENSv2 name for the role actions. See [Who can change a name](/docs/sdk/who-can-change-a-name). ## 1. Check what an account may do [#1-check-what-an-account-may-do] [`permission.get`](/docs/reference/sdk/permission/get) answers every operation at once. Use it to show or hide buttons. **Example** (Gating a UI) ```ts title="permission-get.ts" import { createPublicClient, http } from "viem"; import { sepolia } from "viem/chains"; import { Ensforge, ensActions } from "@ensforge/sdk"; const ens = Ensforge.create({ publicClient: createPublicClient({ chain: sepolia, transport: http() }), }).extend(ensActions()); const { can, fuses } = await ens.permission.get({ name: "ensforge-docs-demo.eth", account: "0xB0b0000000000000000000000000000000000000", }); if (can.setRecords) console.log("show the edit button"); ``` - `can` maps each operation to `true`, `false` or `null`. `null` means the permission model is unknown, as with a custom resolver. - `fuses` lists burned NameWrapper fuses on wrapped ENSv1 names. - Pass `records` for per-record answers, such as which text keys the account may write. - On ENSv2 the answer uses the account's roles on the name and at the root of its registry. [`permission.check`](/docs/reference/sdk/permission/check) checks one operation and lists what is missing. **Example** (Explaining a Disabled Button) ```ts title="permission-check.ts" import { createPublicClient, http } from "viem"; import { sepolia } from "viem/chains"; import { Ensforge, ensActions } from "@ensforge/sdk"; const ens = Ensforge.create({ publicClient: createPublicClient({ chain: sepolia, transport: http() }), }).extend(ensActions()); const { allowed, via, missing } = await ens.permission.check({ name: "ensforge-docs-demo.eth", account: "0xB0b0000000000000000000000000000000000000", operation: "setResolver", }); ``` `via` says how the account is allowed: owner, operator, approved, delegate, roles or anyone. `missing` lists the ownership, approvals or roles it lacks, or what blocks the change for everyone, such as a burned fuse. ## 2. Read an account's roles [#2-read-an-accounts-roles] [`role.get`](/docs/reference/sdk/role/get) reads the roles directly. `target` is `"registry"` or `"resolver"`. **Example** (Reading Roles on a Name) ```ts title="role-get.ts" import { createPublicClient, http } from "viem"; import { sepolia } from "viem/chains"; import { Ensforge, ensActions } from "@ensforge/sdk"; const ens = Ensforge.create({ publicClient: createPublicClient({ chain: sepolia, transport: http() }), }).extend(ensActions()); const { names, admin, rootRoles } = await ens.role.get({ name: "ensforge-docs-demo.eth", account: "0xB0b0000000000000000000000000000000000000", target: "registry", }); ``` - `names` lists the roles held, including root roles, which apply to every name. - `admin` lists the roles the account may grant and revoke. - `rootRoles` is the bitmap of the root roles alone. - `root: true` reads root roles alone. `contract` reads another registry or resolver than the name's. ## 3. Grant and revoke roles [#3-grant-and-revoke-roles] [`role.grant`](/docs/reference/sdk/role/grant) and [`role.revoke`](/docs/reference/sdk/role/revoke) take role names or a bitmap. Granting or revoking needs the matching admin roles. **Example** (Granting and Revoking a Role) ```ts title="role-grant.ts" import { createPublicClient, createWalletClient, http, type Hex } from "viem"; import { privateKeyToAccount } from "viem/accounts"; import { sepolia } from "viem/chains"; import { Ensforge, ensActions } from "@ensforge/sdk"; const account = privateKeyToAccount(process.env.PRIVATE_KEY as Hex); const transport = http(process.env.SEPOLIA_RPC_URL); const ens = Ensforge.create({ publicClient: createPublicClient({ chain: sepolia, transport }), walletClient: createWalletClient({ account, chain: sepolia, transport }), }).extend(ensActions()); const bob = "0xB0b0000000000000000000000000000000000000"; await ens.role.grantSync({ name: "ensforge-docs-demo.eth", grantee: bob, roles: ["setResolver"], target: "registry", }); await ens.role.revokeSync({ name: "ensforge-docs-demo.eth", holder: bob, roles: ["setResolver"], target: "registry", }); ``` | Option | Description | | -------------------- | ------------------------------------------------------------- | | `grantee` / `holder` | The account that gains or loses the roles. | | `roles` | Role names such as `["setResolver"]`, or a bitmap. | | `target` | `"registry"` or `"resolver"`. Resolver roles are root only. | | `name` | The name whose registry or resolver to use. | | `contract` | A registry or resolver address, instead of the name's. | | `root` | Root roles, which apply to every name, instead of the name's. | Each role has an admin role named `Admin`. `Role.admin("setResolver")` returns `"setResolverAdmin"`. Some roles regenerate the name's token ID. The plan then carries a `TOKEN_ID_REGENERATED` warning, so read the token ID again afterwards. ### Registry roles [#registry-roles] `registrar`, `registerReserved`, `setParent`, `unregister`, `renew`, `setSubregistry`, `setResolver`, `canTransfer`, `setUri`, `canName` and `upgrade`, each with an `Admin` form. The `.eth` registrar grants a new owner the roles for the resolver, the subregistry and transfers. ### Resolver roles [#resolver-roles] `setAddr`, `setText`, `setContenthash`, `setAbi`, `setInterface`, `setName`, `setData`, `link`, `canName` and `upgrade`, each with an `Admin` form. A `.eth` owner cannot grant `renew` (`CANNOT_GRANT_ROLES`). Anyone can renew a `.eth` name through the registrar. See [Renew a name](/docs/sdk/renew-a-name). ## 4. Let an app edit some records [#4-let-an-app-edit-some-records] [`permission.setRecordAccess`](/docs/reference/sdk/permission/set-record-access) gives an account access to the records you list, or to all of them. `revoke: true` takes it back. **Example** (Letting an App Edit One Text Record) ```ts title="set-record-access.ts" import { createPublicClient, createWalletClient, http, type Hex } from "viem"; import { privateKeyToAccount } from "viem/accounts"; import { sepolia } from "viem/chains"; import { Ensforge, ensActions } from "@ensforge/sdk"; const account = privateKeyToAccount(process.env.PRIVATE_KEY as Hex); const transport = http(process.env.SEPOLIA_RPC_URL); const ens = Ensforge.create({ publicClient: createPublicClient({ chain: sepolia, transport }), walletClient: createWalletClient({ account, chain: sepolia, transport }), }).extend(ensActions()); await ens.permission.setRecordAccessSync({ name: "ensforge-docs-demo.eth", grantee: "0xB0b0000000000000000000000000000000000000", records: { texts: ["url"] }, }); ``` - On a PermissionedResolver it grants the exact setter roles for each record. With `records: "all"` it grants every setter role. - On a public resolver it sets a per-name delegate, which can edit every record of the name. - Delegates and `"all"` need `allowScopeWidening: true`. Setter roles are per record kind, not per name. If names share a resolver (`resolver: "parent"`), the grantee edits the same records on all of them. By default each name has its own resolver. See [Resolvers and shared records](/docs/sdk/resolvers-and-shared-records). ## Troubleshooting [#troubleshooting] ### `MISSING_ROLES` [#missing_roles] The account lacks a role. The error lists them. See [`MISSING_ROLES`](/docs/reference/errors/MISSING_ROLES). ### `CANNOT_GRANT_ROLES` [#cannot_grant_roles] The signer lacks the admin role for what it tries to grant or revoke. See [`CANNOT_GRANT_ROLES`](/docs/reference/errors/CANNOT_GRANT_ROLES). ### `INVALID_ROLES` [#invalid_roles] A role name or bitmap is not valid. See [`INVALID_ROLES`](/docs/reference/errors/INVALID_ROLES). ### `permission.get` returns `null` for an operation [#permissionget-returns-null-for-an-operation] The resolver is custom, so ensforge cannot know its permission model. # Lock permissions with fuses > For the complete documentation index, see [llms.txt](https://ensforge.com/llms.txt). Read and burn Name Wrapper fuses to lock a name's permissions, and emancipate or extend a subname as its parent on ENSv1. Source: https://ensforge.com/docs/sdk/fuses This page is about [ENSv1](/docs/reference/glossary#ensv1) only, because fuses belong to the [Name Wrapper](/docs/reference/glossary#name-wrapper). A **fuse** is a permission on a wrapped name that can be burned, for good, until the name [expires](/docs/reference/glossary#expiry). You will read a name's fuses, burn some, and [emancipate](/docs/reference/glossary#emancipated) a [subname](/docs/reference/glossary#subname) as its parent. See [What wrapped names are](/docs/sdk/wrapped-names). Fuses cannot be unburned before the name expires. Simulate first. See [Preview before sending](/docs/sdk/preview-before-sending). ## Prerequisites [#prerequisites] - A wallet client for the name's owner, or for the parent's owner when you set child fuses. See [Create a client](/docs/sdk/create-a-client). - A wrapped ENSv1 name. See [Wrap and unwrap a name](/docs/sdk/wrap-and-unwrap). ## The fuses [#the-fuses] | Fuse | Who burns it | | ----------------------- | --------------------------------------------------------------------------------------------------- | | `cannotUnwrap` | The owner, or the parent. The name stays wrapped until it expires. Every other owner fuse needs it. | | `cannotBurnFuses` | The owner, or the parent. | | `cannotTransfer` | The owner, or the parent. | | `cannotSetResolver` | The owner, or the parent. | | `cannotSetTtl` | The owner, or the parent. | | `cannotCreateSubdomain` | The owner, or the parent. | | `cannotApprove` | The owner, or the parent. | | `parentCannotControl` | Only the parent. Emancipates the name. | | `canExtendExpiry` | Only the parent. Lets the name's owner extend its expiry. | | `isDotEth` | Nobody. The NameWrapper sets it on wrapped `.eth` names. | The first seven are owner-controlled fuses. The owner burns them with `wrapper.setFuses`. The parent can burn them too, with `wrapper.setChildFuses`, until it burns `parentCannotControl` on the subname. After that, only the owner can. A `.eth` name has no parent owner, so only its owner burns its fuses. `Fuse.from(names)` builds the mask, `Fuse.has(mask, name)` tests one fuse and `Fuse.decode(mask)` returns every fuse by name. ## 1. Read the fuses [#1-read-the-fuses] [`wrapper.getFuses`](/docs/reference/sdk/wrapper/get-fuses) returns the owner, the mask, the burned fuses by name and the expiry. **Example** (Reading Fuses) ```ts title="get-fuses.ts" import { createPublicClient, http } from "viem"; import { sepolia } from "viem/chains"; import { Ensforge, ensActions } from "@ensforge/sdk"; const ens = Ensforge.create({ publicClient: createPublicClient({ chain: sepolia, transport: http() }), }).extend(ensActions()); const wrapped = await ens.wrapper.getFuses({ name: "ensforge-docs-demo.eth" }); ``` It returns `null` when the name is not wrapped, or is an expired emancipated name. Expired names report no fuses. ## 2. Burn fuses [#2-burn-fuses] [`wrapper.setFuses`](/docs/reference/sdk/wrapper/set-fuses) burns owner-controlled fuses. **Example** (Locking a Name) ```ts title="set-fuses.ts" import { createPublicClient, createWalletClient, http, type Hex } from "viem"; import { privateKeyToAccount } from "viem/accounts"; import { sepolia } from "viem/chains"; import { Ensforge, ensActions } from "@ensforge/sdk"; const account = privateKeyToAccount(process.env.PRIVATE_KEY as Hex); const transport = http(process.env.SEPOLIA_RPC_URL); const ens = Ensforge.create({ publicClient: createPublicClient({ chain: sepolia, transport }), walletClient: createWalletClient({ account, chain: sepolia, transport }), }).extend(ensActions()); await ens.wrapper.setFusesSync({ name: "ensforge-docs-demo.eth", fuses: ["cannotUnwrap"], }); ``` - It needs `parentCannotControl`, which the parent burns, or which every wrapped `.eth` name has. - Every fuse other than `cannotUnwrap` needs `cannotUnwrap` burned first. - Burning `cannotUnwrap` keeps the name in the NameWrapper until it expires. To burn fuses while wrapping a `.eth` name, pass `fuses` to `wrapper.wrap`. ## 3. Emancipate or extend a subname [#3-emancipate-or-extend-a-subname] [`wrapper.setChildFuses`](/docs/reference/sdk/wrapper/set-child-fuses) is sent by the owner of the wrapped parent. It burns fuses on a subname, including the parent-controlled ones, and extends its expiry. **Example** (Emancipating a Subname) ```ts title="set-child-fuses.ts" import { createPublicClient, createWalletClient, http, type Hex } from "viem"; import { privateKeyToAccount } from "viem/accounts"; import { sepolia } from "viem/chains"; import { Ensforge, ensActions } from "@ensforge/sdk"; const account = privateKeyToAccount(process.env.PRIVATE_KEY as Hex); const transport = http(process.env.SEPOLIA_RPC_URL); const ens = Ensforge.create({ publicClient: createPublicClient({ chain: sepolia, transport }), walletClient: createWalletClient({ account, chain: sepolia, transport }), }).extend(ensActions()); await ens.wrapper.setChildFusesSync({ name: "pay.ensforge-docs-demo.eth", fuses: ["parentCannotControl"], expiry: 1_900_000_000n, }); ``` - `expiry` is a Unix timestamp. It only grows, and it is capped at the parent's expiry. - Burning `parentCannotControl` without `expiry` uses the parent's expiry, so the subname does not expire at once. - `parentCannotControl` and `canExtendExpiry` need `cannotUnwrap` burned on the parent first, or the write fails with `INVALID_RECORD_VALUE`. - After `parentCannotControl`, the parent can only extend the subname. New fuses fail with `FUSE_BURNED`. You can also burn fuses while creating a subname under a wrapped parent. See [Create subnames](/docs/sdk/create-subnames). ## Check the result [#check-the-result] Call `wrapper.getFuses` again, or use [`permission.get`](/docs/reference/sdk/permission/get), whose `fuses` field lists what is burned. See [Roles and permissions](/docs/sdk/roles-and-permissions). ## Troubleshooting [#troubleshooting] ### `INVALID_RECORD_VALUE` [#invalid_record_value] A fuse name is unknown, or a parent-controlled fuse needs `cannotUnwrap` on the parent first. See [`INVALID_RECORD_VALUE`](/docs/reference/errors/INVALID_RECORD_VALUE). ### `INVALID_EXPIRY` [#invalid_expiry] The expiry is not valid for the subname. See [`INVALID_EXPIRY`](/docs/reference/errors/INVALID_EXPIRY). ### `FUSE_BURNED` [#fuse_burned] A burned fuse forbids the change. See [`FUSE_BURNED`](/docs/reference/errors/FUSE_BURNED). ### `NOT_OWNER` [#not_owner] The account may not burn these fuses. See [`NOT_OWNER`](/docs/reference/errors/NOT_OWNER). ### `NAME_NOT_WRAPPED` [#name_not_wrapped] The name is not wrapped. Wrap it first. See [`NAME_NOT_WRAPPED`](/docs/reference/errors/NAME_NOT_WRAPPED). ### `UNSUPPORTED_PROTOCOL` [#unsupported_protocol] ENSv2 and migrated names have no NameWrapper. See [`UNSUPPORTED_PROTOCOL`](/docs/reference/errors/UNSUPPORTED_PROTOCOL). # Wrap and unwrap a name > For the complete documentation index, see [llms.txt](https://ensforge.com/llms.txt). Wrap an ENSv1 name in the Name Wrapper, optionally burning fuses on the way, and unwrap it again when you need the registry back. Source: https://ensforge.com/docs/sdk/wrap-and-unwrap This page is about [ENSv1](/docs/reference/glossary#ensv1) only, because the [Name Wrapper](/docs/reference/glossary#name-wrapper) does not exist on [ENSv2](/docs/reference/glossary#ensv2). You will wrap an ENSv1 name, which turns it into an ERC-1155 token, and unwrap it back. See [What wrapped names are](/docs/sdk/wrapped-names). ## Prerequisites [#prerequisites] - A wallet client for the account that holds the name. See [Create a client](/docs/sdk/create-a-client). - An ENSv1 name. ENSv2 names fail with [`UNSUPPORTED_PROTOCOL`](/docs/reference/errors/UNSUPPORTED_PROTOCOL), and migrated names have no NameWrapper. ## 1. Wrap the name [#1-wrap-the-name] [`wrapper.wrap`](/docs/reference/sdk/wrapper/wrap) wraps a name. `wrapper.wrapSync` also waits for the receipt. **Example** (Wrapping a Name) ```ts title="wrap.ts" import { createPublicClient, createWalletClient, http, type Hex } from "viem"; import { privateKeyToAccount } from "viem/accounts"; import { sepolia } from "viem/chains"; import { Ensforge, ensActions } from "@ensforge/sdk"; const account = privateKeyToAccount(process.env.PRIVATE_KEY as Hex); const transport = http(process.env.SEPOLIA_RPC_URL); const ens = Ensforge.create({ publicClient: createPublicClient({ chain: sepolia, transport }), walletClient: createWalletClient({ account, chain: sepolia, transport }), }).extend(ensActions()); const { hash } = await ens.wrapper.wrapSync({ name: "ensforge-docs-demo.eth" }); ``` | Option | Type | Default | Description | | ---------- | ------------- | ----------------------------------- | ------------------------------------------------------------- | | `name` | `string` | required | The ENSv1 name. | | `owner` | `string` | the current holder, else the signer | Owner of the wrapped name. | | `fuses` | `Fuse.Name[]` | none | Fuses to burn while wrapping. `.eth` second-level names only. | | `resolver` | `string` | the current resolver | Resolver to set. | - A [`.eth` name](/docs/reference/glossary#eth-name) is wrapped in one transaction from the [registrant](/docs/reference/glossary#registrant), which may burn owner [fuses](/docs/reference/glossary#fuse) (`cannotUnwrap` first). - Any other name needs its registry owner to approve the NameWrapper first. ensforge adds the approval when it is needed. - The wrapped name stays with its current holder unless you pass `owner`. This also holds when an approved operator wraps it. If the name's [manager](/docs/reference/glossary#manager) is not the signer, the manager must approve the NameWrapper first. An operator of the manager cannot approve it for them, and the write fails with `NOT_APPROVED`. ## 2. Unwrap the name [#2-unwrap-the-name] [`wrapper.unwrap`](/docs/reference/sdk/wrapper/unwrap) returns a wrapped name to the ENSv1 registry and, for `.eth` names, to the registrar. `owner` becomes the registry owner and, for `.eth` names, the registrant. It defaults to the signer. **Example** (Unwrapping a Name) ```ts title="unwrap.ts" import { createPublicClient, createWalletClient, http, type Hex } from "viem"; import { privateKeyToAccount } from "viem/accounts"; import { sepolia } from "viem/chains"; import { Ensforge, ensActions } from "@ensforge/sdk"; const account = privateKeyToAccount(process.env.PRIVATE_KEY as Hex); const transport = http(process.env.SEPOLIA_RPC_URL); const ens = Ensforge.create({ publicClient: createPublicClient({ chain: sepolia, transport }), walletClient: createWalletClient({ account, chain: sepolia, transport }), }).extend(ensActions()); await ens.wrapper.unwrapSync({ name: "ensforge-docs-demo.eth" }); ``` Once `cannotUnwrap` is burned, `unwrap` fails with `FUSE_BURNED` until the name expires. See [Lock permissions with fuses](/docs/sdk/fuses). ## Check the result [#check-the-result] Read the name with [`wrapper.getFuses`](/docs/reference/sdk/wrapper/get-fuses). It returns `null` when the name is not wrapped. Or use `name.get` and read `wrapped`. See [Get a name's owner, expiry and status](/docs/sdk/get-name-details). ## Troubleshooting [#troubleshooting] ### `NAME_WRAPPED` or `NAME_NOT_WRAPPED` [#name_wrapped-or-name_not_wrapped] You wrapped a name that is already wrapped, or unwrapped one that is not. See [`NAME_WRAPPED`](/docs/reference/errors/NAME_WRAPPED) and [`NAME_NOT_WRAPPED`](/docs/reference/errors/NAME_NOT_WRAPPED). ### `NAME_EXPIRED` or `NAME_NOT_REGISTERED` [#name_expired-or-name_not_registered] Only registered names can be wrapped. See [`NAME_EXPIRED`](/docs/reference/errors/NAME_EXPIRED) and [`NAME_NOT_REGISTERED`](/docs/reference/errors/NAME_NOT_REGISTERED). ### `NOT_OWNER` or `NOT_APPROVED` [#not_owner-or-not_approved] The account does not own the name, or the manager has not approved the NameWrapper. See [`NOT_OWNER`](/docs/reference/errors/NOT_OWNER) and [`NOT_APPROVED`](/docs/reference/errors/NOT_APPROVED). ### `FUSE_BURNED` [#fuse_burned] A burned fuse forbids it, such as `cannotUnwrap`. See [`FUSE_BURNED`](/docs/reference/errors/FUSE_BURNED). ### `INVALID_RECORD_VALUE` [#invalid_record_value] A fuse name is not valid. See [`INVALID_RECORD_VALUE`](/docs/reference/errors/INVALID_RECORD_VALUE). # What wrapped names are > For the complete documentation index, see [llms.txt](https://ensforge.com/llms.txt). Learn what the ENSv1 Name Wrapper does, how it changes who controls a name, and what happens to wrapped names on ENSv2 later. Source: https://ensforge.com/docs/sdk/wrapped-names This page is about [ENSv1](/docs/reference/glossary#ensv1) only. The **Name Wrapper** is an ENSv1 contract that turns a name into an ERC-1155 token and adds **fuses**: permissions that can be burned, for good, until the name expires. [ENSv2](/docs/reference/glossary#ensv2) has no Name Wrapper. Wrapped names [migrate](/docs/reference/glossary#migration) to ENSv2 like unwrapped ones. You never need to wrap a name to use ensforge. Wrapping matters when you want the token form or want to give up powers permanently. ## What wrapping changes [#what-wrapping-changes] | | Unwrapped | Wrapped | | --------------- | ------------------------------------------------------------------------------------------------------- | -------------------------------------------- | | Token | `.eth` names: an ERC-721 registrar token. Others: none. | An ERC-1155 token in the NameWrapper. | | Who controls it | A **registrant** (the registrar token holder, for `.eth` names) and a **manager** (the registry owner). | One **owner**: the NameWrapper token holder. | | Fuses | None. | Yes. | | Subnames | The manager creates them freely. | Created with fuses and an expiry. | On a wrapped name there is no separate manager. `name.get` reports the token holder as `owner`. ## Fuses and name states [#fuses-and-name-states] A **fuse** is a permission that can be burned. A burned fuse cannot be unburned before the name expires. Two states matter: - **Emancipated** (`parentCannotControl` burned): a [subname](/docs/reference/glossary#subname) its parent can no longer control. The parent can only extend it, until it expires. - **Locked** (`cannotUnwrap` burned): a name that stays in the NameWrapper until it expires. Every other owner-controlled fuse needs it first. See [Lock permissions with fuses](/docs/sdk/fuses) for the full list. ## What ensforge does for you [#what-ensforge-does-for-you] - [`name.get`](/docs/reference/sdk/name/get) reports `kind: "v1-wrapped"` and `wrapped: true` for wrapped names. See [Get a name's owner, expiry and status](/docs/sdk/get-name-details). - Writes such as `name.transfer`, `resolver.set` and `subname.create` use the NameWrapper when the name is wrapped. You pass the same options. - [`wrapper.getFuses`](/docs/reference/sdk/wrapper/get-fuses) reads the owner, the burned fuses and the expiry. - Wrapper actions on ENSv2 names fail with [`UNSUPPORTED_PROTOCOL`](/docs/reference/errors/UNSUPPORTED_PROTOCOL). - Locked names migrate into a WrapperRegistry whose roles follow their fuses. See [Move a name to ENSv2](/docs/sdk/move-a-name-to-ensv2). ## Renewal [#renewal] `.eth` names still on ENSv1, wrapped or not, renew through `ETHRenewerV1`, which also extends the wrapped name's expiry. `registration.renew` picks it for you. See [Renew a name](/docs/sdk/renew-a-name). To wrap or unwrap a name, see [Wrap and unwrap a name](/docs/sdk/wrap-and-unwrap). # Create a client > For the complete documentation index, see [llms.txt](https://ensforge.com/llms.txt). Create an ensforge client from viem clients or a wagmi config, add the actions you need, and set options such as indexer and storage. Source: https://ensforge.com/docs/sdk/create-a-client The **client** is the object you call ENS actions on. You create it once, at app start, from the viem clients your app already has, then add groups of actions to it with `extend`. ## Create a client for reads [#create-a-client-for-reads] A viem public client is all a client needs to read. Its chain selects the ENS contracts: ensforge ships them for Ethereum mainnet and Sepolia. **Example** (Creating a Client for Reads) ```ts title="ens.ts" import { Ensforge, ensActions } from "@ensforge/sdk"; import { createPublicClient, http } from "viem"; import { mainnet } from "viem/chains"; const ens = Ensforge.create({ publicClient: createPublicClient({ chain: mainnet, transport: http("https://your-rpc.example") }), }).extend(ensActions()); const name = await ens.primaryName.get({ address: "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045" }); ``` - `Ensforge.create` returns a client with no actions yet. - `extend(ensActions())` returns a new client with every ENS action on it. The original client is left unchanged: clients are frozen. A viem client on another chain fails with [`UNKNOWN_CHAIN`](/docs/reference/errors/UNKNOWN_CHAIN) unless you pass `deployment`. See [Custom deployments](/docs/contracts/custom-deployments). ## Add a wallet for writes [#add-a-wallet-for-writes] Writes need a signer. Pass a viem wallet client as `walletClient`. Reads still go through the public client. **Example** (Adding a Wallet Client) ```ts title="ens.ts" import { Ensforge, ensActions } from "@ensforge/sdk"; import { createPublicClient, createWalletClient, custom, http, type EIP1193Provider } from "viem"; import { sepolia } from "viem/chains"; declare const provider: EIP1193Provider; // e.g. window.ethereum const ens = Ensforge.create({ publicClient: createPublicClient({ chain: sepolia, transport: http() }), walletClient: createWalletClient({ chain: sepolia, transport: custom(provider) }), }).extend(ensActions()); ``` - When the public client was created with an `account`, it is also used as the wallet, so `walletClient` can be left out. - `walletClient` can also be a function that returns the wallet, or `undefined` while none is connected. ensforge calls it on every write, so a wallet that connects later works. - Without a wallet, writes fail with [`WALLET_NOT_CONFIGURED`](/docs/reference/errors/WALLET_NOT_CONFIGURED). Reads keep working. ## From a wagmi config [#from-a-wagmi-config] Apps on wagmi create the client with `Ensforge.fromWagmi`, from `@ensforge/sdk/wagmi`. Reads use wagmi's client for the ENS chain. Writes use whichever wallet is connected when they run. **Example** (Creating a Client From wagmi) ```ts no-check title="ens.ts" import { ensActions } from "@ensforge/sdk"; import { Ensforge } from "@ensforge/sdk/wagmi"; import { wagmiConfig } from "./wagmi"; // your app's createConfig(...) const ens = Ensforge.fromWagmi(wagmiConfig).extend(ensActions()); ``` - The ENS chain is mainnet when the wagmi config has it, otherwise the first configured chain ensforge has contracts for. Pass `{ chainId: 11155111 }` to pick Sepolia. - A wallet connected to another chain is asked to switch first. Pass `{ switchChain: false }` to turn that off. - Every other chain in the wagmi config is added to `chains`, so a [primary name](/docs/reference/glossary#primary-name) on an L2 uses wagmi's client and wallet there. - `fromWagmi` takes every option of `Ensforge.create` except the viem clients. It works with wagmi 2 (2.14 or later) and wagmi 3. For React apps, see [Use with wagmi](/docs/react/with-wagmi). ## Add actions with extend [#add-actions-with-extend] `extend` adds a group of actions and returns a new client. Choose the groups by what your app does. | Decorator | From | Adds | | ------------------------------------- | ---------------------------------------------- | ------------------------------------------------------------------------------------------------------------ | | `ensActions()` | `@ensforge/sdk` | Every ENS action (`ens.name`, `ens.record`, `ens.registration`, …) and `ens.batch`. Not the indexer actions. | | `recordActions()`, `nameActions()`, … | `@ensforge/sdk` | One group each, for smaller bundles. There is one per group, plus `batchActions()`. | | `indexerActions()` | `@ensforge/sdk/indexer` (also `@ensforge/sdk`) | `ens.indexer.*`: lists, search and history. Needs an `indexer`. | | `hcaActions()` | `@ensforge/hca` | Smart-account actions (experimental). See [HCA](/docs/hca). | **Example** (Adding Indexer Actions) ```ts title="ens.ts" import { Ensforge, ensActions } from "@ensforge/sdk"; import { bigname, indexerActions } 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: bigname(), }) .extend(ensActions()) .extend(indexerActions()); const page = await ens.indexer.getNamesForAddress({ address: "0xb8c2C29ee19D8307cb7255e1Cd9CbDE883A267d5", }); ``` The indexer actions are a separate group because they need an indexer service. Calling them on a client without `indexer` fails with [`INDEXER_NOT_CONFIGURED`](/docs/reference/errors/INDEXER_NOT_CONFIGURED). See [Name lists and indexers](/docs/sdk/name-lists-and-indexers). **Example** (Only the Record Actions) ```ts title="ens.ts" import { Ensforge, recordActions } from "@ensforge/sdk"; import { createPublicClient, http } from "viem"; import { mainnet } from "viem/chains"; const ens = Ensforge.create({ publicClient: createPublicClient({ chain: mainnet, transport: http() }), }).extend(recordActions()); const url = await ens.record.getText({ name: "nick.eth", key: "url" }); ``` A client with only `recordActions()` has `ens.record` and nothing else, so the other groups stay out of your bundle. See [Keep bundles small](/docs/sdk/bundle-size). ## Options [#options] Every option except `publicClient` is optional. | Option | Type | Default | Description | | -------------- | -------------------------------------------------- | ---------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `publicClient` | viem client | (required) | Client for reads. Its chain selects the ENS deployment. | | `walletClient` | viem wallet client, or a function returning one | `publicClient` when it has an account | Client for writes. A function is called on every write. | | `account` | `Account \| Address` | the wallet client's account | Default signer for writes. A write's own `account` overrides it. | | `chains` | `Record` | none | Clients for other chains, for writes ENS makes there, such as a primary name on an L2. Without one, such writes fail with [`CHAIN_NOT_CONFIGURED`](/docs/reference/errors/CHAIN_NOT_CONFIGURED). | | `deployment` | `Deployments.Profile` | the built-in deployment for the chain | ENS contract addresses. Required for devnets, forks and other chains. | | `ccipRead` | `{ gatewayUrls? } \| false` | the Universal Resolver's own batch gateway | Off-chain lookups ([CCIP-Read](/docs/reference/glossary#ccip-read)): the batch gateways the Universal Resolver sends them through. `false` turns them off. | | `batch` | `{ multicall?: boolean \| { batchSize?, wait? } }` | `{ multicall: true }` | Groups reads made at the same time into multicall requests. `wait` is in milliseconds. | | `blockTag` | `BlockTag` | `"latest"` | Block that reads run at. | | `storage` | `Plan.Storage` | `Plan.memoryStorage()` | Where multi-step writes save their [plan](/docs/reference/glossary#plan) progress. Use `Plan.localStorage()` to survive a reload. | | `simulate` | `boolean` | `true` | Simulate writes before the wallet prompt. | | `indexer` | `Indexer` | none | [Indexer](/docs/reference/glossary#indexer) for `indexer.*` actions and for finding records and subnames during migration, from `@ensforge/sdk/indexer`. | | `gateways` | `{ ipfs?, arweave?, swarm? }` | `https://ipfs.io`, `https://arweave.net`, `https://api.gateway.ethswarm.org` | HTTP gateways for avatars and website links. The public IPFS gateway is rate limited: set your own in production. | See [Configure RPC and gateways](/docs/sdk/rpc-and-gateways). **Example** (Adding an L2 for Primary Names) ```ts title="ens.ts" import { Ensforge, ensActions } from "@ensforge/sdk"; import { createPublicClient, createWalletClient, custom, http, type EIP1193Provider } from "viem"; import { base, mainnet } from "viem/chains"; declare const provider: EIP1193Provider; const ens = Ensforge.create({ publicClient: createPublicClient({ chain: mainnet, transport: http() }), walletClient: createWalletClient({ chain: mainnet, transport: custom(provider) }), chains: { [base.id]: { publicClient: createPublicClient({ chain: base, transport: http() }), walletClient: createWalletClient({ chain: base, transport: custom(provider) }), }, }, }).extend(ensActions()); await ens.primaryName.set({ name: "ensforge-docs-demo.eth", coin: { chainId: base.id } }); ``` Each key of `chains` must match the chain of its clients. A mismatch fails at creation with `CHAIN_NOT_CONFIGURED`. See [Set a primary name](/docs/sdk/set-a-primary-name). ## What the client holds [#what-the-client-holds] Besides its actions, every client has a few fields you can read. | Field | Description | | -------------- | ----------------------------------------------------------------- | | `chain` | `{ id, name }` of the ENS chain. | | `account` | The default signer's address, or `undefined` without a wallet. | | `deployment` | The ENS contracts on this chain: addresses and what they support. | | `publicClient` | The viem client used for reads. | | `config` | The resolved options, with defaults filled in. | | `extend` | Adds a group of actions and returns a new client. | These names are reserved: an action group cannot use them. ## Use a bare viem client [#use-a-bare-viem-client] Every action also accepts a plain viem client in place of an ensforge client. ensforge creates a client for it with default options on first use, and reuses it for later calls. **Example** (Calling an Action With a viem Client) ```ts title="viem-client.ts" import { Actions } from "@ensforge/sdk"; import { createPublicClient, http } from "viem"; import { mainnet } from "viem/chains"; const publicClient = createPublicClient({ chain: mainnet, transport: http() }); const address = await Actions.record.getAddress(publicClient, { name: "nick.eth" }); ``` `Ensforge.from(client)` does the same in your own helpers: it returns an ensforge client for either kind of client. See [Ways to call actions](/docs/sdk/ways-to-call-actions). # Quick start > For the complete documentation index, see [llms.txt](https://ensforge.com/llms.txt). Install ensforge, read your first ENS name in under five minutes, then preview and send your first write on the Sepolia test network. Source: https://ensforge.com/docs/sdk By the end of this page you will have read an address, an avatar, a text record and a [primary name](/docs/reference/glossary#primary-name) from ENS in one batch. The second part sends your first write, on the Sepolia test network. You need Node.js 20.19 or later. Nothing else: the first part reads from Ethereum mainnet and needs no wallet. ## 1. Create a project [#1-create-a-project] Create an empty folder, make it an ES module project, and install the SDK with viem and Effect. ```sh mkdir ens-quickstart && cd ens-quickstart npm init -y && npm pkg set type=module npm install @ensforge/sdk viem effect@^4 tsx ``` `tsx` runs the TypeScript files on this page directly. Any other way of running TypeScript works too. ## 2. Create a client [#2-create-a-client] The client is the object you call ENS actions on. Create it once from a viem public client; the chain of that client tells ensforge which ENS contracts to use. **Example** (Creating a Mainnet Client) ```ts title="ens.ts" import { Ensforge, ensActions } from "@ensforge/sdk"; import { createPublicClient, http } from "viem"; import { mainnet } from "viem/chains"; export const ens = Ensforge.create({ publicClient: createPublicClient({ chain: mainnet, transport: http() }), }).extend(ensActions()); ``` - `Ensforge.create` takes the viem client. No wallet is needed to read. - `.extend(ensActions())` adds every ENS action to the client: `ens.record`, `ens.name`, `ens.primaryName` and the rest. See [Create a client](/docs/sdk/create-a-client) for every option. ## 3. Get an address [#3-get-an-address] Ask for the Ethereum address of `nick.eth`. This is the most common ENS lookup: turning a name into the address it points to. **Example** (Getting an Address) ```ts no-check title="address.ts" import { ens } from "./ens"; const address = await ens.record.getAddress({ name: "nick.eth" }); console.log(address); ``` Run it: ```sh npx tsx address.ts ``` ```text title="Output" 0xb8c2C29ee19D8307cb7255e1Cd9CbDE883A267d5 ``` The result is `null` when the name has no address, so your code handles a missing record without a `try`. ensforge also checks and [normalises](/docs/reference/glossary#normalisation) the name for you: `Nick.ETH` reads the same record. See [Get a name's address](/docs/sdk/get-an-address) for other chains and coins. ## 4. Look up several things at once [#4-look-up-several-things-at-once] A profile page needs more than an address. `ens.batch` runs several lookups together, in as few requests to the chain as possible. **Example** (Loading a Profile in One Batch) ```ts no-check title="profile.ts" import { Actions } from "@ensforge/sdk"; import { ens } from "./ens"; const { results } = await ens.batch({ requests: { address: Actions.record.getAddress.request({ name: "nick.eth" }), avatar: Actions.record.getAvatar.request({ name: "nick.eth" }), github: Actions.record.getText.request({ name: "nick.eth", key: "com.github" }), primaryName: Actions.primaryName.get.request({ address: "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045", }), }, }); console.log(results); ``` ```sh npx tsx profile.ts ``` ```text title="Output" { address: { status: 'success', result: '0xb8c2C29ee19D8307cb7255e1Cd9CbDE883A267d5' }, avatar: { status: 'success', result: 'https://euc.li/nick.eth' }, github: { status: 'success', result: 'arachnid' }, primaryName: { status: 'success', result: 'vitalik.eth' } } ``` - Every read action has a `.request(...)` form. It describes the lookup without running it, so `batch` can run them together. - `record.getAvatar` returns a URL a browser can load, not the raw record. - `primaryName.get` goes the other way: from an address to its name. ensforge only returns the name when it points back to the same address. - One failed lookup does not fail the others: each result has its own `status`. You have read ENS. The next part writes to it. See [Look up many at once](/docs/sdk/look-up-many-at-once) and [How a lookup works](/docs/sdk/looking-up-a-name). ## 5. Get a test name and test ETH [#5-get-a-test-name-and-test-eth] Writes change data on a chain, so they need a wallet that pays for gas and controls the name. Use the Sepolia test network, where both are free. - A private key for a test account. Never use a key that holds real funds. - Some Sepolia ETH in that account, from any Sepolia faucet. - A `.eth` name on Sepolia owned by that account. Register one in the [ENS app on Sepolia](https://sepolia.app.ens.domains). Put the key in an environment variable so it stays out of your code: ```sh export PRIVATE_KEY=0x... ``` ## 6. Preview the write [#6-preview-the-write] Add a wallet client to a Sepolia client, then ask ensforge to plan a text record change without sending it. Replace `ensforge-docs-demo.eth` with your Sepolia name. **Example** (Planning a Write on Sepolia) ```ts title="write.ts" import { Ensforge, ensActions } from "@ensforge/sdk"; import { createPublicClient, createWalletClient, http, type Hex } from "viem"; import { privateKeyToAccount } from "viem/accounts"; import { sepolia } from "viem/chains"; const account = privateKeyToAccount(process.env.PRIVATE_KEY as Hex); const ens = Ensforge.create({ publicClient: createPublicClient({ chain: sepolia, transport: http() }), walletClient: createWalletClient({ account, chain: sepolia, transport: http() }), }).extend(ensActions()); const records = { name: "ensforge-docs-demo.eth", texts: { url: "https://example.com" } }; const plan = await ens.record.set.prepare(records); console.log(plan.steps.map((step) => step.description)); ``` ```text title="Output" [ 'Set records' ] ``` - The wallet client signs. The public client still does every read. - `record.set.prepare` returns a **plan**: the transactions the write needs, in order. Nothing is sent and the wallet is not asked to sign. - Every write has `.prepare`, so a UI can show what will happen before the user confirms. See [How writes work](/docs/sdk/writing-to-ens). ## 7. Send it and wait [#7-send-it-and-wait] Send the same write with `record.setSync`. The `Sync` form waits until the transaction is mined, then you read the record back to see the change. **Example** (Setting a Text Record and Reading It Back) ```ts title="write.ts" import { Ensforge, ensActions } from "@ensforge/sdk"; import { createPublicClient, createWalletClient, http, type Hex } from "viem"; import { privateKeyToAccount } from "viem/accounts"; import { sepolia } from "viem/chains"; const account = privateKeyToAccount(process.env.PRIVATE_KEY as Hex); const ens = Ensforge.create({ publicClient: createPublicClient({ chain: sepolia, transport: http() }), walletClient: createWalletClient({ account, chain: sepolia, transport: http() }), }).extend(ensActions()); const records = { name: "ensforge-docs-demo.eth", texts: { url: "https://example.com" } }; const { hash } = await ens.record.setSync(records); console.log("Mined:", hash); console.log(await ens.record.getText({ name: "ensforge-docs-demo.eth", key: "url" })); ``` ```text title="Output" Mined: 0x... https://example.com ``` - ensforge simulates the transaction before the wallet prompt. A write that would fail, for example because the account does not own the name, throws a typed error such as [`NOT_OWNER`](/docs/reference/errors/NOT_OWNER) and sends nothing. - `record.set` (without `Sync`) returns as soon as the transaction is submitted. Use it when your UI tracks confirmation itself. ## Choose where to go next [#choose-where-to-go-next] You have read ENS records, batched lookups, and planned and sent a write. From here: What ensforge does for you, and when to use something else. What a name, a resolver and a record are, in plain words. Client methods, standalone actions, and the Effect API. The same actions as React hooks. # Installation > For the complete documentation index, see [llms.txt](https://ensforge.com/llms.txt). Install @ensforge/sdk with viem and Effect, and check that your runtime and TypeScript settings can load the package correctly. Source: https://ensforge.com/docs/sdk/installation `@ensforge/sdk` is the SDK for ENS. It builds on the [viem](https://viem.sh) clients your app already has, and works the same in a browser app and on a server. ## Install the package [#install-the-package] Install the SDK with its two required peer dependencies, `viem` and `effect`. ```package-install @ensforge/sdk viem effect@^4 ``` - `viem` (2.57 or later) talks to the chain. You create the viem clients; ensforge uses them. - `effect` (4.1.4 or later, version 4 only) is required even if you never use it directly. ensforge runs on it internally. You never have to write Effect code: every action returns a Promise. See [Ways to call actions](/docs/sdk/ways-to-call-actions) if you want the Effect API. ## Add wagmi support (optional) [#add-wagmi-support-optional] Apps built on wagmi (RainbowKit, ConnectKit, Dynamic, Privy, Reown AppKit) can create the client from their wagmi config. ensforge supports wagmi 2.14 and later, and wagmi 3. There is nothing more to install: `wagmi` is an optional peer dependency, and apps without it never load that code. See [Create a client](/docs/sdk/create-a-client#from-a-wagmi-config). ## Check your setup [#check-your-setup] ensforge ships ES modules only, with an `exports` map. | Requirement | Value | | ----------------------------- | --------------------------------------------- | | Node.js | 20.19 or later | | Module format | ES modules (`"type": "module"`, or a bundler) | | TypeScript `moduleResolution` | `"bundler"`, `"node16"` or `"nodenext"` | The `moduleResolution` setting matters because ensforge has several entry points (`@ensforge/sdk/indexer`, `@ensforge/sdk/wagmi`, …). Older settings such as `"node"` cannot see them. See [Entry points](/docs/reference/entry-points) for the full list. ## Verify the install [#verify-the-install] This script reads the address of `nick.eth` on Ethereum mainnet. If it prints an address, the SDK, viem and Effect are installed correctly. **Example** (Checking the Install) ```ts title="check.ts" import { Ensforge, ensActions } from "@ensforge/sdk"; import { createPublicClient, http } from "viem"; import { mainnet } from "viem/chains"; const ens = Ensforge.create({ publicClient: createPublicClient({ chain: mainnet, transport: http() }), }).extend(ensActions()); console.log(await ens.record.getAddress({ name: "nick.eth" })); ``` ```text title="Output" 0xb8c2C29ee19D8307cb7255e1Cd9CbDE883A267d5 ``` `http()` without a URL uses the chain's public RPC, which is rate limited. Pass your own RPC URL in production. See [Configure RPC and gateways](/docs/sdk/rpc-and-gateways). ## Other packages [#other-packages] The SDK is the core. The other packages build on it and are installed only when you need them. | Package | What it adds | | --------------------- | ---------------------------------------------------------------------------------------------- | | `@ensforge/react` | React hooks and a provider. See [React](/docs/react). | | `@ensforge/contracts` | ENS ABIs, addresses and deployments. Installed with the SDK. See [Contracts](/docs/contracts). | | `@ensforge/hca` | Writes through an ENS smart account (experimental). See [HCA](/docs/hca). | # Ways to call actions > For the complete documentation index, see [llms.txt](https://ensforge.com/llms.txt). Choose between client methods, standalone actions and the Effect API; all three run the same actions with the same errors. Source: https://ensforge.com/docs/sdk/ways-to-call-actions An **action** is one thing ensforge can do: `record.getAddress`, `name.transfer`, `registration.register`. Every action can be called three ways. They run the same code and return the same results; they differ only in how you import and call them. | Way | Looks like | Choose it when | | ----------------- | --------------------------------------------------- | --------------------------------------------------------------- | | Client method | `ens.record.getAddress(options)` | Most apps. Short to write, everything in one place. | | Standalone action | `Actions.record.getAddress(client, options)` | Bundle size matters, or you write helpers that take any client. | | Effect API | `yield* Actions.record.getAddress(client, options)` | Your app is an Effect program. | ## Client methods [#client-methods] Add actions to a client with `extend`, then call them on it. This is the form the docs use by default. **Example** (Calling a Client Method) ```ts title="client-method.ts" import { Ensforge, ensActions } from "@ensforge/sdk"; import { createPublicClient, http } from "viem"; import { mainnet } from "viem/chains"; const ens = Ensforge.create({ publicClient: createPublicClient({ chain: mainnet, transport: http() }), }).extend(ensActions()); const url = await ens.record.getText({ name: "nick.eth", key: "url" }); ``` `ensActions()` adds every action group. To keep a bundle small, add only the groups you use, such as `recordActions()`. See [Create a client](/docs/sdk/create-a-client#add-actions-with-extend). ## Standalone actions [#standalone-actions] `Actions` holds every action as a plain function that takes the client first. Bundlers keep only the actions you call, so this is the smallest form. **Example** (Calling a Standalone Action) ```ts title="standalone.ts" 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() }), }); const url = await Actions.record.getText(ens, { name: "nick.eth", key: "url" }); ``` - The first argument is an ensforge client, or a bare viem client. A viem client gets an ensforge client with default options, created once and reused. - No `extend` is needed: the client carries only configuration. - `@ensforge/sdk/actions` exports the same actions by group: `import { record } from "@ensforge/sdk/actions"`. See [Entry points](/docs/reference/entry-points). ## The Effect API [#the-effect-api] `@ensforge/sdk/effect` has the same actions, but each returns an [Effect](https://effect.website) instead of a Promise. Its error channel is the action's typed error union, so you handle failures with `Effect.catchTag` and the other Effect tools. **Example** (Calling an Action in an Effect Program) ```ts title="effect.ts" import { Actions, Ensforge } from "@ensforge/sdk/effect"; import { Effect } from "effect"; import { createPublicClient, http } from "viem"; import { mainnet } from "viem/chains"; const program = Effect.gen(function* () { const ens = yield* Ensforge.Ensforge; return yield* Actions.record.getText(ens, { name: "nick.eth", key: "url" }); }); const url = await Effect.runPromise( program.pipe( Effect.provide( Ensforge.layer({ publicClient: createPublicClient({ chain: mainnet, transport: http() }) }), ), ), ); ``` - `Ensforge.layer(options)` creates the client as an Effect service, `Ensforge.Ensforge`. - Errors are the same instances in both APIs. Their `_tag` is the class name, so `Effect.catchTag("NotFoundError", …)` works. - You never need this API to use ensforge. See [The Effect API](/docs/sdk/effect-api). ## Extra forms every action has [#extra-forms-every-action-has] The three ways above call an action. Actions also carry a few related functions, the same in every way of calling. | Form | On | What it does | | ----------------------------- | ---------- | ------------------------------------------------------------------- | | `action.request(options)` | Most reads | Describes the read without running it, for `Actions.batch`. | | `action.prepare(options)` | Writes | Builds the plan without sending anything. | | `action.simulate(options)` | Writes | Simulates every call of the plan. | | `action.estimateGas(options)` | Writes | Estimates the gas and ETH the plan needs. | | `actionSync(options)` | Writes | Sends, then waits for the receipts (`record.setSync`). | | `action.path` | All | The action's name, such as `"record.get"`, for logs and cache keys. | **Example** (Batching Two Reads With Requests) ```ts title="requests.ts" import { Actions, Ensforge, ensActions } from "@ensforge/sdk"; import { createPublicClient, http } from "viem"; import { mainnet } from "viem/chains"; const ens = Ensforge.create({ publicClient: createPublicClient({ chain: mainnet, transport: http() }), }).extend(ensActions()); const { results: [state, address], } = await ens.batch({ requests: [ Actions.name.get.request({ name: "nick.eth" }), Actions.record.getAddress.request({ name: "nick.eth" }), ], allowFailure: false, }); ``` - Requests are built from `Actions`, whichever way you call `batch`. - A list of requests returns a list of results; a record returns a record with the same keys. - With `allowFailure: false` the first failure rejects; by default each result carries its own `status`. See [Look up many at once](/docs/sdk/look-up-many-at-once) and [How writes work](/docs/sdk/writing-to-ens). ## Mix them freely [#mix-them-freely] The three ways share clients and errors, so you can mix them in one app: client methods in UI code, standalone actions in a small server function, the Effect API in an Effect service. The React hooks in `@ensforge/react` take the action itself, as in `useRead(Actions.record.getText, options)` and `useReads`, not its `.request`. See [React](/docs/react). # Why ensforge > For the complete documentation index, see [llms.txt](https://ensforge.com/llms.txt). See what ensforge does for you when you work with ENS, and when a smaller tool such as viem alone is the better choice for you. Source: https://ensforge.com/docs/sdk/why-ensforge ensforge is the SDK for ENS. You ask for a name, an address, a record or a registration, and ensforge does the work in between: it finds the right contracts, reads them in as few requests as possible, plans and checks every write, and tells you exactly what went wrong when something fails. ## Everything works the same for every name [#everything-works-the-same-for-every-name] ENS has grown over the years. Names can live in different places, be held in different ways, and have their records on-chain or on a server. ensforge hides those differences: one call works for every name. **Example** (Reading Two Very Different Names) ```ts title="same-call.ts" import { Ensforge, ensActions } from "@ensforge/sdk"; import { createPublicClient, http } from "viem"; import { mainnet } from "viem/chains"; const ens = Ensforge.create({ publicClient: createPublicClient({ chain: mainnet, transport: http() }), }).extend(ensActions()); const nick = await ens.record.getAddress({ name: "nick.eth" }); const jesse = await ens.record.getAddress({ name: "jesse.base.eth" }); ``` `nick.eth` keeps its records on Ethereum. `jesse.base.eth` is a Basename whose records live off Ethereum and are fetched through a [gateway](/docs/reference/glossary#gateway). The call and the result type are the same. Writes work the same way: `record.set`, `name.transfer` and `subname.create` pick the right contracts for the name you pass. See [How a lookup works](/docs/sdk/looking-up-a-name). For the details ensforge handles under the hood, see [ENS versions under the hood](/docs/sdk/ens-versions). ## Typed errors with a code for every failure [#typed-errors-with-a-code-for-every-failure] Every error ensforge throws has a class, a stable `code`, a link to its own page and, when ensforge knows one, a hint to fix it. Every action declares the errors it can throw, so TypeScript knows them too. **Example** (Branching on an Error Code) ```ts title="errors.ts" import { Ensforge, Errors, ensActions } from "@ensforge/sdk"; import { createPublicClient, http } from "viem"; import { mainnet } from "viem/chains"; const ens = Ensforge.create({ publicClient: createPublicClient({ chain: mainnet, transport: http() }), }).extend(ensActions()); try { await ens.record.getText({ name: "unregistered-example.eth", key: "url", strict: true }); } catch (error) { if (Errors.hasCode("RESOLVER_NOT_FOUND")(error)) { console.log(error.hint, error.docsUrl); } console.log(Errors.describe(error).title); } ``` - `Errors.hasCode` narrows the error to the codes you name. - `Errors.describe` turns any error into a title, message and suggested action you can show to users, so `error.message` (written for developers) stays out of your UI. See [How errors work](/docs/sdk/errors-explained). ## Writes you can inspect before sending [#writes-you-can-inspect-before-sending] Many ENS tasks take more than one transaction. Registering a name approves a payment, commits, waits at least a minute, then registers ([commitment](/docs/reference/glossary#commitment)). ensforge turns every write into a **plan** you can look at, simulate, estimate and save before anything is signed. - Every write is simulated before the wallet prompt, so a write that would fail throws a typed error and sends nothing. - Wallets that support atomic batches (EIP-5792) get each step's calls as one bundle. - A plan that stops halfway, because of a rejection or a closed tab, resumes where it stopped with `plan.resume`. See [How writes work](/docs/sdk/writing-to-ens). ## Built on viem, shaped like viem [#built-on-viem-shaped-like-viem] ensforge takes the viem clients you already have and returns plain values: `0x` addresses as viem `Address`, amounts as `bigint`. The API is Promise-based, with one options object per call, as in viem. Apps on wagmi create the client from their wagmi config in one line. See [Create a client](/docs/sdk/create-a-client). ## Pay only for what you import [#pay-only-for-what-you-import] Every action is a separate function, and the package has no side effects, so bundlers drop what you do not import. Two ways of importing keep a bundle small: - `Actions.record.getText(client, options)`: one action, no client methods. - `recordActions()` instead of `ensActions()`: only the `record` methods on the client. The repository checks these sizes on every change. As of release 1.0, `Actions.record.getText` alone costs about 41 kB gzipped and a client with `ensActions()` about 106 kB, viem excluded. See [Ways to call actions](/docs/sdk/ways-to-call-actions) and [Keep bundles small](/docs/sdk/bundle-size). ## More than lookups [#more-than-lookups] ensforge covers the whole of ENS from one client: - Lookups: addresses for any chain, text records, avatars, websites, [primary names](/docs/reference/glossary#primary-name). - Registration and renewal of `.eth` names, records, subnames, transfers and primary names on L2s. - Permissions: who can do what with a name, before they try. - Lists, search and history through an [indexer](/docs/reference/glossary#indexer). - React hooks in `@ensforge/react`, and an optional Effect API for Effect programs. ## When to use something else [#when-to-use-something-else] ensforge is not always the right tool. Choose something smaller when: - **You only show a name or an address.** viem's built-in ENS actions (`getEnsAddress`, `getEnsName`, `getEnsAvatar`, `getEnsText`) cover simple lookups with nothing more to install. - **Every kilobyte matters on one page.** One ensforge action is about 41 kB gzipped on top of viem, because ensforge runs on Effect internally. viem's ENS actions are smaller. - **You need lists or search but no chain access.** Lists of names come from an indexer, not from the chain. If that is all you need, the indexer's own API may be enough. - **Your runtime cannot load ES modules.** ensforge needs Node.js 20.19 or later, or a bundler. See [Installation](/docs/sdk/installation). Moving from another library? See [From viem](/docs/sdk/from-viem) and [From ensjs](/docs/sdk/from-ensjs).