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

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.

Writestable
Since v1.0.0View source

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 .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.

Gotchas

  • 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), 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

OptionTypeDefaultDescription
name (required)stringFull name of the child, e.g. pay.alice.eth. Normalized automatically.
ownerstringthe signing accountOwner of the child.
resolverstring | "parent" | nullResolver of the child. By default it gets its own PermissionedResolver; "parent" uses the parent's resolver and null none.
recordsOmit<recordSet.Options, "name" | "resolver" | "clear" | "pubkey">Records of the child.
expirybigintnever for ENSv2 children; for wrapped children, the maximum when parentCannotControl is burned, else noneExpiry as a Unix timestamp.
fusesreadonly Fuse.Name[]NameWrapper fuses to burn on the child (wrapped ENSv1 parents).
rolesreadonly Role.Name[] | bigintENSv2 roles for the child's owner, by name or bitmap.
emancipatebooleanEmancipate the parent's subregistry if this plan deploys it.
upsertbooleanUpdate 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.

FieldTypeDescription
hashHexHash of the last transaction.
hashesreadonly Hex[]Every submitted transaction, in order.
idstringEIP-5792 bundle id when the calls were sent as one batch.
planPlanThe plan the write executed: its steps, in order, as they were submitted.

Errors

ErrorCodesWhen
InvalidInputErrorINVALID_NAME, INVALID_ADDRESS, INVALID_ROLES, INVALID_RECORD_VALUEinvalid input.
NameStateErrorNAME_NOT_AVAILABLE, NAME_NOT_REGISTERED, NAME_EXPIREDthe child exists or the parent is not registered.
NameStateErrorNAME_RESERVED, NAME_UNREACHABLEthe parent is reserved or ENSv2 resolution no longer reaches it.
UnsupportedErrorUNSUPPORTED_PROTOCOLroles on ENSv1 or fuses on unwrapped parents.
UnauthorizedErrorMISSING_ROLES, NOT_OWNER, FUSE_BURNEDthe account may not create children.
ConfigErrorWALLET_NOT_CONFIGUREDno signing account is known.
UserRejectedErrorUSER_REJECTEDthe user rejects the request.
WalletErrorCHAIN_MISMATCH, ACCOUNT_NOT_FOUNDthe wallet is on another chain or has no account to sign with.
UnsupportedErrorWALLET_BATCH_UNSUPPORTEDwith 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

Creating a subname
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.

MethodDescription
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.

Creating a subname and waiting
const { receipt } = await ens.subname.createSync({ name: "pay.alice.eth", records: { texts: { url: "https://pay.alice.dev" } } })

See also

Was this page helpful?