record.set
Writes records of an ENS name and resolves once the transaction is submitted. Parameters, return value, errors and examples for record.set in @ensforge/sdk.
Writes records of an ENS name and resolves once the transaction is submitted.
When to use
Use to update a profile (texts, addresses, content hash and more) when the UI tracks
confirmation itself. Use setSync to wait for the receipt instead.
Details
nulldeletes a record.- All records are written in one
multicallon the resolver. - Works with ENSv1 resolvers and the ENSv2 PermissionedResolver; the kind is detected on-chain.
- The records go to the resolver set on the name in its registry, never to a wildcard resolver inherited from a parent.
resolverwrites the records to another resolver, then points the name at it, in one step: a rejected write never leaves the name on an empty resolver.- Each kind of record is checked against the profiles the resolver declares through ERC-165,
and
clearagainst its record versions, before anything is simulated; a resolver without ERC-165 is left to the simulation. - The plan is simulated before the wallet prompt, so permission errors surface first.
Gotchas
- The ENSv2 PermissionedResolver has no
pubkeyrecords.clearthere links the name to record 0 (needs the rootlinkrole), so it reads the resolver's default record until new records are written. - Older resolvers lack newer profiles (the 2020 public resolver has no
datarecords and cannotclear), and resolvers that keep their records off-chain (EIP-3668, ERC-5559, ERC-7884) take no on-chain writes. Both fail withRESOLVER_PROFILE_UNSUPPORTED; for an off-chain resolver,detailssay where its records live. resolver: "default"(the ENSv1 public resolver) is for ENSv1 names only; ENSv2 names pass the address of a resolver such as their own PermissionedResolver.
Signature
function set(client: Like, options: set.Options & Write.Options): Promise<set.ReturnType>Call it as ens.record.set(options) on a client, or Actions.record.set(client, options).
In React, use useSetRecords.
Parameters
| Option | Type | Default | Description |
|---|---|---|---|
name (required) | string | ENS name to update. Normalized automatically. | |
texts | Readonly<Record<string, string | null>> | Text records by key. null deletes the record. | |
addresses | Readonly<Record<string, string | null>> | Address records by coin symbol (eth, btc) or decimal coin type ("2147492101"). null deletes the record. | |
contentHash | string | null | Content hash URI such as ipfs://…. null deletes it. | |
abi | { contentType?: 1n | 2n | 4n | 8n | undefined; value: Abi | Hex | null } | ABI record (ENSIP-4). An Abi is stored as JSON (content type 1); hex bytes are stored as given under contentType. null deletes the record of that content type. | |
pubkey | { x: Hex; y: Hex } | null | SECP256k1 public key. null deletes it. Node-based resolvers only. | |
nameRecord | string | null | Name record (the name() of reverse names). null deletes it. | |
interfaces | Readonly<Record<Hex, Address | null>> | ERC-165 interface implementers by 4-byte interface ID. null deletes one. | |
data | Readonly<Record<string, Hex | null>> | Data records (ENSIP-24) by key. null deletes one. | |
clear | boolean | Deletes every existing record first. | |
resolver | Address | "default" | Writes the records to this resolver, then points the name at it. "default" is the ENSv1 public resolver, for ENSv1 names only. |
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_COIN_TYPE, INVALID_CONTENT_HASH, INVALID_RECORD_VALUE | invalid input. |
NotFoundError | RESOLVER_NOT_FOUND | the name has no resolver of its own. |
UnsupportedError | RESOLVER_PROFILE_UNSUPPORTED, UNSUPPORTED_PROTOCOL | records the resolver does not support (feature names them), a resolver that keeps its records off-chain or takes no writes, or resolver: "default" on an ENSv2 name. |
NameStateError | NAME_EXPIRED, NAME_RESERVED, NAME_NOT_REGISTERED | the name is not registered. |
NameStateError | NAME_UNREACHABLE | ENSv2 resolution no longer reaches the name. |
UnauthorizedError | NOT_OWNER, MISSING_ROLES | the account may not edit records. |
ConfigError | WALLET_NOT_CONFIGURED | the client has no wallet. |
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.record.set({
name: "alice.eth",
texts: { url: "https://alice.dev" },
addresses: { eth: "0x225f137127d9067788314bc7fcc1f36746a3c3B5" },
})Plan methods
Each method takes the same options as record.set and sends nothing. See Preview before sending.
| Method | Description |
|---|---|
record.set.prepare(options) | Builds the plan without sending anything. |
record.set.simulate(options) | Simulates the plan with eth_call, reporting each step. |
record.set.estimateGas(options) | Estimates the gas and ETH the plan needs. |
Wait for the receipt with setSync
Writes records of an ENS name and resolves once the receipt is in.
Use when the next step depends on the records being confirmed on-chain.
record.setSync takes the same options plus confirmations and timeout.
Resolves to Write.SyncResult. Receipts plus the submitted hashes and plan.
const { receipt } = await ens.record.setSync({ name: "alice.eth", texts: { url: "https://alice.dev" } })See also
record.getto read records
Was this page helpful?