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.
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:
setResolverandrenewin the parent's subregistry. The owner moves withname.transfer, or by removing and recreating the child. On the deployment's current UserRegistry, extending the expiry needs therenewrole at the subregistry's root; older registries also accept it on the child. - ENSv1: one
setSubnodeRecordkeeps what is not changed; wrapped children extend their expiry withextendExpiry. 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
| Option | Type | Default | Description |
|---|---|---|---|
name (required) | string | Full name of the child. Normalized automatically. | |
owner | string | New owner (ENSv1 only). | |
resolver | string | null | New resolver, or null to remove it. | |
expiry | bigint | New 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.
| 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_RECORD_VALUE, INVALID_EXPIRY | invalid input. |
NameStateError | NAME_NOT_REGISTERED, NAME_EXPIRED | the child or parent does not exist, or an emancipated child expired. |
NameStateError | NAME_RESERVED, NAME_UNREACHABLE | the parent is reserved or ENSv2 resolution no longer reaches it. |
UnsupportedError | UNSUPPORTED_PROTOCOL | an ENSv2 owner change or an unwrapped ENSv1 expiry. |
UnauthorizedError | MISSING_ROLES, NOT_OWNER, FUSE_BURNED | the account may not change it. |
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.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.
| Method | Description |
|---|---|
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.
const { receipt } = await ens.subname.updateSync({ name: "pay.alice.eth", resolver: "0x231b0Ee14048e9dCcD1d247744d114a4EB5E8E63" })See also
name.getto read the child
Was this page helpful?