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

Create subnames

Create, update and remove subnames such as pay.ensforge-docs-demo.eth under a name you control, with their own owner and records.

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 subregistry, the ENSv1 registry or the Name Wrapper. You pass the same options.

Prerequisites

1. Create a subname

subname.create takes the full name of the child. subname.createSync also waits for the receipt.

Example (Creating a Subname With Records)

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, 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.
OptionTypeDefaultDescription
namestringrequiredFull name of the child.
ownerstringthe signerOwner of the child.
resolverstring | "parent" | nulla new resolverResolver of the child.
recordsobjectnoneRecords of the child, in the record.set shape.
expirybigintsee belowExpiry as a Unix timestamp.
fusesFuse.Name[]noneNameWrapper fuses to burn. Wrapped parents only.
rolesRole.Name[] | bigintthe .eth owner rolesENSv2 roles for the child's owner.
emancipatebooleanfalseEmancipate the parent's subregistry if this plan deploys it.
upsertbooleanfalseUpdate the child if it exists.

What differs by parent

ParentWhat happens
On ENSv2The 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 ENSv1One setSubnodeRecord call. roles and fuses are not supported.
Wrapped on ENSv1Takes fuses and an expiry. When parentCannotControl is burned, the default expiry is the maximum.

A subregistry deployed here is not emancipated by default

Owners of a subregistry that this plan deploys can remove and repoint its children, unless you pass emancipate: true. See Registries and subregistries.

2. Change a subname from its parent

subname.update changes a child's resolver or expiry without asking its owner. owner changes only on ENSv1.

Example (Repointing a Subname)

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, not with update. update({ owner }) on ENSv2 fails with 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. Pass expiry at creation when children should lapse.

3. Remove a subname

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)

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 child: an ENSv1 child with parentCannotControl burned, or a child of an emancipated ENSv2 subregistry.

Check the result

Read the child with name.get. See Get a name's owner, expiry and status.

Troubleshooting

NAME_NOT_AVAILABLE

The child already exists. Pass upsert: true to update it, or pick another label. See NAME_NOT_AVAILABLE.

NAME_NOT_REGISTERED or NAME_EXPIRED

The parent is not registered. See NAME_NOT_REGISTERED and NAME_EXPIRED.

INVALID_EXPIRY

The new expiry is lower than the current one, or the ENSv2 child never expires. See INVALID_EXPIRY.

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, NOT_OWNER and FUSE_BURNED.

INVALID_RECORD_VALUE

parentCannotControl and canExtendExpiry need cannotUnwrap burned on a wrapped parent first. See Lock permissions with fuses and INVALID_RECORD_VALUE.

INVALID_ROLES or UNSUPPORTED_PROTOCOL

roles is for ENSv2 parents and fuses for wrapped parents. See INVALID_ROLES.

Was this page helpful?