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

Set a primary name

Choose the name wallets and apps show for an address, on Ethereum, on every EVM chain or on an L2, including with a signed claim.

You will set the primary name of an address: the name wallets and apps show instead of 0x…. It is stored as a reverse record, and readers check that the name resolves back to the address (ENSIP-19).

Prerequisites

  • A wallet client for the address you are naming. See Create a client.
  • A name that resolves to that address. ensforge checks this before sending and fails with PRIMARY_NAME_MISMATCH otherwise. See Set records.

1. Set the primary name on Ethereum

primaryName.set sets the name for the signer. primaryName.setSync also waits for the receipt.

Example (Setting Your Primary Name)

set-primary-name.ts
import { createPublicClient, createWalletClient, http, type Hex } from "viem";
import { privateKeyToAccount } from "viem/accounts";
import { sepolia } from "viem/chains";
import { Ensforge, ensActions } from "@ensforge/sdk";

const account = privateKeyToAccount(process.env.PRIVATE_KEY as Hex);
const transport = http(process.env.SEPOLIA_RPC_URL);

const ens = Ensforge.create({
  publicClient: createPublicClient({ chain: sepolia, transport }),
  walletClient: createWalletClient({ account, chain: sepolia, transport }),
}).extend(ensActions());

const { hash } = await ens.primaryName.setSync({ name: "ensforge-docs-demo.eth" });

Pass name: null to clear it. Names with encoded labels ([af2c…]) are rejected, because readers show only normalised names.

OptionTypeDefaultDescription
namestring | nullrequiredThe primary name, or null to clear it.
addressstringthe signerThe address to name. See Name another address.
coin"eth" | "default" | { chainId }"eth"Where to set it. See below.
verifybooleantrueCheck that name resolves to the address before sending.

2. Choose where it applies

coin picks the chain of the primary name.

coinStored inApplies to
"eth" (default)addr.reverseEthereum.
"default"default.reverseEvery EVM chain, as a fallback (ENSIP-19).
{ chainId: 8453 }That chain's reverse registrarThat L2 only.

A name in addr.reverse outranks default.reverse on Ethereum, so "default" also sets addr.reverse when it holds a different name. A default name whose only address record is an Ethereum address verifies on Ethereum alone. The plan carries a DEFAULT_PRIMARY_NAME_ETHEREUM_ONLY warning in that case.

3. Set a primary name on an L2

An L2 primary name is a transaction on that L2, so the client needs clients for it in chains. The signer is the same account on every chain.

Example (Setting a Primary Name on Base Sepolia)

set-primary-name-l2.ts
import { createPublicClient, createWalletClient, http, type Hex } from "viem";
import { privateKeyToAccount } from "viem/accounts";
import { baseSepolia, sepolia } from "viem/chains";
import { Ensforge, ensActions } from "@ensforge/sdk";

const account = privateKeyToAccount(process.env.PRIVATE_KEY as Hex);
const baseTransport = http(process.env.BASE_SEPOLIA_RPC_URL);
const transport = http(process.env.SEPOLIA_RPC_URL);

const ens = Ensforge.create({
  publicClient: createPublicClient({ chain: sepolia, transport }),
  walletClient: createWalletClient({ account, chain: sepolia, transport }),
  chains: {
    [baseSepolia.id]: {
      publicClient: createPublicClient({ chain: baseSepolia, transport: baseTransport }),
      walletClient: createWalletClient({ account, chain: baseSepolia, transport: baseTransport }),
    },
  },
}).extend(ensActions());

await ens.primaryName.setSync({
  name: "ensforge-docs-demo.eth",
  coin: { chainId: baseSepolia.id },
});

The plan is for the L2, and resumes there. 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.

Supported L2s are those with an L2 reverse registrar: OP Mainnet, Base, Arbitrum One, Linea and Scroll, and their Sepolia testnets. Other chains fail with UNSUPPORTED_ON_DEPLOYMENT.

4. Set it on several L2s with one signature

primaryName.signClaim signs one EIP-191 message that covers several L2s, with no transaction. Anyone can then submit the claim on each chain with primaryName.set, so the account needs no gas or wallet connection on the L2s.

Example (Signing One Claim for Two Chains)

sign-claim.ts
import { createPublicClient, createWalletClient, http, type Hex } from "viem";
import { privateKeyToAccount } from "viem/accounts";
import { baseSepolia, optimismSepolia, sepolia } from "viem/chains";
import { Ensforge, ensActions } from "@ensforge/sdk";

const account = privateKeyToAccount(process.env.PRIVATE_KEY as Hex);
const transport = http(process.env.SEPOLIA_RPC_URL);

const ens = Ensforge.create({
  publicClient: createPublicClient({ chain: sepolia, transport }),
  walletClient: createWalletClient({ account, chain: sepolia, transport }),
  chains: {
    [baseSepolia.id]: {
      publicClient: createPublicClient({ chain: baseSepolia, transport: http() }),
      walletClient: createWalletClient({ account, chain: baseSepolia, transport: http() }),
    },
    [optimismSepolia.id]: {
      publicClient: createPublicClient({ chain: optimismSepolia, transport: http() }),
      walletClient: createWalletClient({ account, chain: optimismSepolia, transport: http() }),
    },
  },
}).extend(ensActions());

const signed = await ens.primaryName.signClaim({
  name: "ensforge-docs-demo.eth",
  chainIds: [baseSepolia.id, optimismSepolia.id],
});

await ens.primaryName.set({ ...signed, coin: { chainId: baseSepolia.id } });
await ens.primaryName.set({ ...signed, coin: { chainId: optimismSepolia.id } });
  • Every mainnet L2 shares one registrar, and testnets share another. One claim cannot mix mainnet chains and testnets, and it cannot include the ENS chain.
  • The claim expires expiresIn seconds after signing, at most one hour (3600n, the default).
  • Smart accounts sign as themselves (ERC-1271, or ERC-6492 before they are deployed). The account must exist, or be deployable, on each L2.

Relay a claim from a server

The claim is plain JSON. The app signs and posts it. A server with a funded wallet on the L2 submits it.

Example (Relaying a Signed Claim)

relay-claim.ts
import { createPublicClient, createWalletClient, http, type Hex } from "viem";
import { privateKeyToAccount } from "viem/accounts";
import { baseSepolia, sepolia } from "viem/chains";
import { Ensforge, ensActions } from "@ensforge/sdk";

const relayerAccount = privateKeyToAccount(process.env.RELAYER_PRIVATE_KEY as Hex);

const relayer = Ensforge.create({
  publicClient: createPublicClient({ chain: sepolia, transport: http() }),
  chains: {
    [baseSepolia.id]: {
      publicClient: createPublicClient({ chain: baseSepolia, transport: http() }),
      walletClient: createWalletClient({
        account: relayerAccount,
        chain: baseSepolia,
        transport: http(),
      }),
    },
  },
}).extend(ensActions());

export async function relayClaim(body: string) {
  const { claim, signature } = JSON.parse(body);
  return relayer.primaryName.set({ claim, signature, coin: { chainId: baseSepolia.id } });
}

relayer is a client whose chains holds a funded wallet for that L2, and the relayer pays the gas. Validate the posted body before you submit it. The signature, not the sender, authorises the name.

Name another address

address names another account. The signer must be the address's registry operator or, for a contract, its Ownable owner or its ContractNamer. Any other signer fails before sending with NOT_APPROVED.

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. Those two dependent calls can only be simulated on an RPC that supports eth_simulateV1, or with simulate: false.

Check the result

Read it back with primaryName.get. See Get the name for an address.

Troubleshooting

PRIMARY_NAME_MISMATCH

The name does not resolve to the address. Add an address record with record.set, then set the primary name. For an L2, the name needs an address for that chain's coin type or a default EVM address. See PRIMARY_NAME_MISMATCH.

CHAIN_NOT_CONFIGURED

The L2 is not in the client's chains. Add it to Ensforge.create, or to the wagmi config with fromWagmi. See CHAIN_NOT_CONFIGURED.

INVALID_COIN_TYPE

coin is not an EVM chain, or the claim does not cover the chain. For signClaim, chainIds is empty, includes the ENS chain, or mixes mainnet and testnets. See INVALID_COIN_TYPE.

SIGNATURE_INVALID or SIGNATURE_EXPIRED

The claim's signature does not match, or the claim has expired. Sign again, for the same name, chains and expiry. See SIGNATURE_INVALID and SIGNATURE_EXPIRED.

INVALID_DURATION

expiresIn is not between 1 and 3600 seconds. See INVALID_DURATION.

NOT_APPROVED

The signer may not name address. See Name another address and NOT_APPROVED.

Not supported yet

Setting L2 primary names through an HCA (via: hca()) is not supported, because the HCA lives on Ethereum. The contracts-v2 L2 registrar is not deployed.

Was this page helpful?