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

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.

Writestable
Since v1.0.0View source

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 in addr.reverse; "default" sets the fallback for every EVM chain in default.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 in chains (Ensforge.create, or the wagmi config with fromWagmi). The plan is for that chain, and resumes there.
  • claim and signature from primaryName.signClaim submit 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.reverse name outranks default.reverse on Ethereum, so "default" also sets addr.reverse when 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_ONLY warning.
  • address names another account: the signer must be its registry operator or, for a contract, its Ownable owner or ContractNamer (ENSv2 IContractNamer); any other signer fails before sending. For "eth", a ContractNamer goes through the ENSv2 adapter: it claims the contract's addr.reverse node, 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: null clears 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 with eth_simulateV1 (or simulate: 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:

OptionTypeDefaultDescription
claim (required)signClaim.ClaimThe claim from primaryName.signClaim.
signature (required)HexIts signature.
coinCoinType.Inputthe claim's chain, when it covers oneThe L2 to submit it on, one of the claim's chains.
verifybooleantrueCheck that the claimed name resolves to the address on that chain before sending.

With name:

OptionTypeDefaultDescription
name (required)string | nullPrimary name, or null to clear it. Normalized automatically.
addressstringthe signing accountAddress to name.
coinCoinType.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).
verifybooleantrueCheck 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.

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_ADDRESSinvalid input.
InvalidInputErrorINVALID_COIN_TYPEa coin that is not an EVM chain, or a chain the claim does not cover.
NotFoundErrorPRIMARY_NAME_MISMATCHthe name does not resolve to the address.
ConfigErrorWALLET_NOT_CONFIGUREDno signing account is known.
ConfigErrorCHAIN_NOT_CONFIGUREDan L2 that is not in the client's chains.
UnsupportedErrorUNSUPPORTED_ON_DEPLOYMENTa chain without an L2 reverse registrar.
UnauthorizedErrorNOT_APPROVEDthe signer may not name the address.
UnauthorizedErrorSIGNATURE_INVALID, SIGNATURE_EXPIREDthe claim's signature is invalid or expired.
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

Setting a primary name
const { hash } = await ens.primaryName.set({ name: "alice.eth" })
Setting the primary name on an L2
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 } })
Several L2s with one signature
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 } })
A server relaying a claim
// `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.

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

Setting a primary name and waiting
const { receipt } = await ens.primaryName.setSync({ name: "alice.eth" })

See also

Was this page helpful?