Documentation for agents: an index at /llms.txt, every docs page in one file at /llms-full.txt, and Markdown for any docs page by adding .md to its URL.

Skip to Content
ensforgeSDK

Registries and subregistries

Inspect, deploy, attach and upgrade the ENSv2 registries and subregistries that hold the children of a name, with role checks.

This page is about ENSv2 only. ENSv1 has one 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 or 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 deploys and attaches a registry when a parent has none.

How registries nest

A registry holds the names directly under it. Each name points to a subregistry for its own children.

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]
kindWhat the registry is
rootThe root registry.
ethThe .eth registry.
userA UserRegistry that holds a name's children.
wrapperA WrapperRegistry for a name migrated from the NameWrapper. See Move a name to ENSv2.
unknownAny other contract.

An emancipated registry is one whose root 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

1. Inspect a registry

registry.get reads a name's subregistry ({ name }) or any registry by address ({ registry }).

Example (Inspecting a Name's Subregistry)

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:

FieldMeaning
address, kindThe contract and what it is.
implementationThe implementation behind the proxy, or null when it is not a proxy.
parentThe registry above it and the label it sits under, as set with setParent.
canonicalNameThe name whose children it holds, or null when not reachable.
uri, rendererToken metadata settings.
emancipatedWhether root role holders can take children back.
upgradelatest implementation, whether this registry is eligible, and the blocker.

Pass account to include whether it holds the upgrade role.

2. Deploy a registry

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)

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",
});
OptionTypeDefaultDescription
ownerstringthe signerGets every root role.
grants{ account, roles }[]noneExtra root role grants.
emancipatedbooleanfalseWithhold the roles that would let owners take children back.
attachTostringnoneENSv2 name to attach it to.
saltbigintrandomCREATE2 salt. With the account, it decides the address.

3. Attach or detach a registry

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)

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

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)

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:

blockerMeaning
up-to-dateIt already runs the latest implementation.
not-approvedThe latest implementation does not accept the current one, or the registry is emancipated and its upgrade set does not list it.
unauthorizedThe account lacks the upgrade root role.
not-upgradeableensforge knows no upgrade target for this kind of registry.

Older registries cannot always be upgraded

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

registry.setUri 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)

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

UPGRADE_NOT_APPROVED

The latest implementation does not accept this registry's implementation. Read registry.get for the blocker. See UPGRADE_NOT_APPROVED.

MISSING_ROLES

The account lacks a root role the write needs: upgrade, setUri or the roles on the parent. See Roles and permissions and MISSING_ROLES.

UNSUPPORTED_PROTOCOL

The name is an ENSv1 name. Registries exist on ENSv2 only. See Move a name to ENSv2.

Was this page helpful?