primaryName.set
Sets or clears the primary name (reverse record) of an address. Parameters, return value, errors and examples for primaryName.set in @ensforge/sdk.
Sets or clears the primary name (reverse record) of an address. Resolves once the transaction is submitted.
When to use
Use to choose the name wallets and apps show for an address. Use setSync to wait for the receipt.
Details
coin: "eth"(default) sets the Ethereum primary name inaddr.reverse;"default"sets the fallback for every EVM chain indefault.reverse(ENSIP-19).- An L2 such as
coin: { chainId: 8453 }sets that chain's primary name in its reverse registrar, with a transaction on that chain: the client needs it inchains(Ensforge.create, or the wagmi config withfromWagmi). The plan is for that chain, and resumes there. claimandsignaturefromprimaryName.signClaimsubmit a signed claim instead, from any account: one signature sets the name on each of its chains, and a server can relay it.- An
addr.reversename outranksdefault.reverseon Ethereum, so"default"also setsaddr.reversewhen it holds a different name. - A default name with only an Ethereum address verifies on Ethereum alone; the plan carries a
DEFAULT_PRIMARY_NAME_ETHEREUM_ONLYwarning. addressnames another account: the signer must be its registry operator or, for a contract, its Ownable owner or ContractNamer (ENSv2IContractNamer); any other signer fails before sending. For"eth", a ContractNamer goes through the ENSv2 adapter: itclaims the contract'saddr.reversenode, which makes the signer that node's owner, then sets the name on the node's resolver.- Before sending, checks that the name resolves back to the address, as readers require.
name: nullclears it.- Names with encoded labels (
[af2c…]) are rejected: readers show only normalized names.
Gotchas
- A ContractNamer's
"eth"name takes two dependent calls: simulating them needs an RPC witheth_simulateV1(orsimulate: false). - Readers on Ethereum verify an L2 primary name against the L2's state as committed to Ethereum, so they see it only once that state is, which can take a while after the receipt.
Signature
function set(client: Like, options: set.Options & Write.Options): Promise<set.ReturnType>Call it as ens.primaryName.set(options) on a client, or Actions.primaryName.set(client, options).
In React, use useSetPrimaryName.
Parameters
With claim and signature:
| Option | Type | Default | Description |
|---|---|---|---|
claim (required) | signClaim.Claim | The claim from primaryName.signClaim. | |
signature (required) | Hex | Its signature. | |
coin | CoinType.Input | the claim's chain, when it covers one | The L2 to submit it on, one of the claim's chains. |
verify | boolean | true | Check that the claimed name resolves to the address on that chain before sending. |
With name:
| Option | Type | Default | Description |
|---|---|---|---|
name (required) | string | null | Primary name, or null to clear it. Normalized automatically. | |
address | string | the signing account | Address to name. |
coin | CoinType.Input | "default" | "eth" | Chain of the primary name: "eth" for Ethereum (addr.reverse), "default" for every EVM chain (default.reverse), or an L2 such as { chainId: 8453 } (its reverse registrar, sent on that chain through the client's chains). |
verify | boolean | true | Check that name resolves to the address before sending. |
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 input. |
InvalidInputError | INVALID_COIN_TYPE | a coin that is not an EVM chain, or a chain the claim does not cover. |
NotFoundError | PRIMARY_NAME_MISMATCH | the name does not resolve to the address. |
ConfigError | WALLET_NOT_CONFIGURED | no signing account is known. |
ConfigError | CHAIN_NOT_CONFIGURED | an L2 that is not in the client's chains. |
UnsupportedError | UNSUPPORTED_ON_DEPLOYMENT | a chain without an L2 reverse registrar. |
UnauthorizedError | NOT_APPROVED | the signer may not name the address. |
UnauthorizedError | SIGNATURE_INVALID, SIGNATURE_EXPIRED | the claim's signature is invalid or expired. |
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.primaryName.set({ name: "alice.eth" })import { Ensforge, ensActions } from "@ensforge/sdk"
const ens = Ensforge.create({
publicClient,
walletClient,
chains: { 8453: { publicClient: baseClient, walletClient: baseWallet } },
}).extend(ensActions())
await ens.primaryName.set({ name: "alice.eth", coin: { chainId: 8453 } })const signed = await ens.primaryName.signClaim({ name: "alice.eth", chainIds: [10, 8453] })
await ens.primaryName.set({ ...signed, coin: { chainId: 10 } })
await ens.primaryName.set({ ...signed, coin: { chainId: 8453 } })// `body` is the JSON the app posted: the result of `primaryName.signClaim`.
const { claim, signature } = JSON.parse(body)
await relayer.primaryName.set({ claim, signature, coin: { chainId: 8453 } })Plan methods
Each method takes the same options as primaryName.set and sends nothing. See Preview before sending.
| Method | Description |
|---|---|
primaryName.set.prepare(options) | Builds the plan without sending anything. |
primaryName.set.simulate(options) | Simulates the plan with eth_call, reporting each step. |
primaryName.set.estimateGas(options) | Estimates the gas and ETH the plan needs. |
Wait for the receipt with setSync
Sets or clears the primary name (reverse record) of an address. Resolves once the receipt is in.
Use when the next step depends on the change being on-chain.
primaryName.setSync takes the same options plus confirmations and timeout.
Resolves to Write.SyncResult. Receipts plus the submitted hashes and plan.
const { receipt } = await ens.primaryName.setSync({ name: "alice.eth" })See also
primaryName.getto read it
Was this page helpful?