subname.create
Creates a subname, routed by its parent: an ENSv2 subregistry, the ENSv1 registry or the NameWrapper. Options, result, errors and examples for 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
Use to give out names under one you own, such as pay.alice.eth. Use createSync to wait for the receipt.
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
.ethregistrar grants (resolver, subregistry, transfers);rolesandexpiryoverride them. - ENSv1 parents use
setSubnodeRecord; wrapped parents takefusesand anexpiry. - By default the child gets its own PermissionedResolver with
recordswritten at creation;resolver: "parent"shares the parent's resolver,nullcreates it without one. upsertupdates an existing child's resolver and records instead of failing.
Gotchas
- A subregistry deployed here is not emancipated unless
emancipateis set: its owners can remove and repoint children. - Under a wrapped parent,
parentCannotControlandcanExtendExpiryneedcannotUnwrapburned on the parent (INVALID_RECORD_VALUE), and an emancipated child cannot be updated until it expires (FUSE_BURNED).
Signature
function create(
client: Like,
options: create.Options & Write.Options,
): Promise<create.ReturnType>Call it as ens.subname.create(options) on a client, or Actions.subname.create(client, options).
In React, use useCreateSubname.
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<recordSet.Options, "name" | "resolver" | "clear" | "pubkey"> | 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.
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
| Error | Codes | When |
|---|---|---|
InvalidInputError | INVALID_NAME, INVALID_ADDRESS, INVALID_ROLES, INVALID_RECORD_VALUE | invalid input. |
NameStateError | NAME_NOT_AVAILABLE, NAME_NOT_REGISTERED, NAME_EXPIRED | the child exists or the parent is not registered. |
NameStateError | NAME_RESERVED, NAME_UNREACHABLE | the parent is reserved or ENSv2 resolution no longer reaches it. |
UnsupportedError | UNSUPPORTED_PROTOCOL | roles on ENSv1 or fuses on unwrapped parents. |
UnauthorizedError | MISSING_ROLES, NOT_OWNER, FUSE_BURNED | the account may not create children. |
ConfigError | WALLET_NOT_CONFIGURED | no signing account is known. |
UserRejectedError | USER_REJECTED | the user rejects the request. |
WalletError | CHAIN_MISMATCH, ACCOUNT_NOT_FOUND | the wallet is on another chain or has no account to sign with. |
UnsupportedError | 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.
Examples
const { hash } = await ens.subname.create({ name: "pay.alice.eth", records: { texts: { url: "https://pay.alice.dev" } } })Plan methods
Each method takes the same options as subname.create and sends nothing. See 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
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.
Resolves to Write.SyncResult. Receipts plus the submitted hashes and plan.
const { receipt } = await ens.subname.createSync({ name: "pay.alice.eth", records: { texts: { url: "https://pay.alice.dev" } } })See also
subname.removeto remove it
Was this page helpful?