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
- A wallet client for an account that may create children of the parent. See Create a client.
- A registered parent name. See Register a name.
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)
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" } },
});ownerdefaults to the signer.- By default the child gets its own resolver, a PermissionedResolver, with
recordswritten at creation.resolver: "parent"shares the parent's resolver.resolver: nullcreates the child without one. upsert: trueupdates 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
| 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. |
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)
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
});expirycan only grow. Unwrapped ENSv1 subnames have no expiry.- An ENSv2 child's owner moves with
name.transfer, not withupdate.update({ owner })on ENSv2 fails withUNSUPPORTED_PROTOCOL. - An ENSv2 child created with the default (never expires) cannot get an expiry later, because
renewonly extends.update({ expiry })then fails withINVALID_EXPIRY. Passexpiryat 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)
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?