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

Changes a subname from its parent: owner, resolver or expiry, in one plan. Parameters, return value, errors and examples for subname.update in @ensforge/sdk.

Writestable
Since v1.0.0View source

Changes a subname from its parent: owner, resolver or expiry, in one plan. Resolves once the transaction is submitted.

When to use

Use to repoint or extend names you gave out without asking their owners. Use updateSync to wait for the receipt.

Details

  • ENSv2: setResolver and renew in the parent's subregistry. The owner moves with name.transfer, or by removing and recreating the child. On the deployment's current UserRegistry, extending the expiry needs the renew role at the subregistry's root; older registries also accept it on the child.
  • ENSv1: one setSubnodeRecord keeps what is not changed; wrapped children extend their expiry with extendExpiry. Unwrapped ENSv1 subnames have no expiry. Under an unwrapped parent the registry rewrites a wrapped child, which unwraps it.

Gotchas

  • An expired wrapped child the parent still controls keeps its owner, and the parent extends it. An emancipated child loses its owner when it expires: recreate it with subname.create.

Signature

function update(
  client: Like,
  options: update.Options & Write.Options,
): Promise<update.ReturnType>

Call it as ens.subname.update(options) on a client, or Actions.subname.update(client, options).

Parameters

OptionTypeDefaultDescription
name (required)stringFull name of the child. Normalized automatically.
ownerstringNew owner (ENSv1 only).
resolverstring | nullNew resolver, or null to remove it.
expirybigintNew expiry as a Unix timestamp; it can only grow.

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_RECORD_VALUE, INVALID_EXPIRYinvalid input.
NameStateErrorNAME_NOT_REGISTERED, NAME_EXPIREDthe child or parent does not exist, or an emancipated child expired.
NameStateErrorNAME_RESERVED, NAME_UNREACHABLEthe parent is reserved or ENSv2 resolution no longer reaches it.
UnsupportedErrorUNSUPPORTED_PROTOCOLan ENSv2 owner change or an unwrapped ENSv1 expiry.
UnauthorizedErrorMISSING_ROLES, NOT_OWNER, FUSE_BURNEDthe account may not change it.
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

Repointing a subname
const { hash } = await ens.subname.update({ name: "pay.alice.eth", resolver: "0x231b0Ee14048e9dCcD1d247744d114a4EB5E8E63" })

Plan methods

Each method takes the same options as subname.update and sends nothing. See Preview before sending.

MethodDescription
subname.update.prepare(options)Builds the plan without sending anything.
subname.update.simulate(options)Simulates the plan with eth_call, reporting each step.
subname.update.estimateGas(options)Estimates the gas and ETH the plan needs.

Wait for the receipt with updateSync

Changes a subname from its parent: owner, resolver or expiry, in one plan. Resolves once the receipt is in.

Use when the next step depends on the change being on-chain.

subname.updateSync takes the same options plus confirmations and timeout.

Resolves to Write.SyncResult. Receipts plus the submitted hashes and plan.

Repointing a subname and waiting
const { receipt } = await ens.subname.updateSync({ name: "pay.alice.eth", resolver: "0x231b0Ee14048e9dCcD1d247744d114a4EB5E8E63" })

See also

Was this page helpful?