# primaryName.set

> For the complete documentation index, see [llms.txt](https://ensforge.com/llms.txt).

Sets or clears the primary name (reverse record) of an address. Parameters, return value, errors and examples for primaryName.set in @ensforge/sdk.

Source: https://ensforge.com/docs/reference/sdk/primary-name/set

<ApiMeta kind="Write" stability="stable" since="1.0.0" source="packages/sdk/src/actions/primaryName/set/index.ts#L119" />

Sets or clears the primary name (reverse record) of an address. Resolves once the transaction is submitted.

## When to use [#when-to-use]

Use to choose the name wallets and apps show for an address. Use [`setSync`](/docs/reference/sdk/primary-name/set#wait-for-the-receipt-with-setsync) to wait for the receipt.

## Details [#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 `claim`s 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.

<Callout type="warn" title="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.
</Callout>

## Signature [#signature]

```ts
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`](/docs/reference/react/use-set-primary-name).

## Parameters [#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](/docs/reference/sdk/client#write-options).

## Returns [#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 [#errors]

| Error | Codes | When |
| --- | --- | --- |
| [`InvalidInputError`](/docs/reference/errors/invalid-input-error) | [`INVALID_NAME`](/docs/reference/errors/INVALID_NAME), [`INVALID_ADDRESS`](/docs/reference/errors/INVALID_ADDRESS) | invalid input. |
| [`InvalidInputError`](/docs/reference/errors/invalid-input-error) | [`INVALID_COIN_TYPE`](/docs/reference/errors/INVALID_COIN_TYPE) | a coin that is not an EVM chain, or a chain the claim does not cover. |
| [`NotFoundError`](/docs/reference/errors/not-found-error) | [`PRIMARY_NAME_MISMATCH`](/docs/reference/errors/PRIMARY_NAME_MISMATCH) | the name does not resolve to the address. |
| [`ConfigError`](/docs/reference/errors/config-error) | [`WALLET_NOT_CONFIGURED`](/docs/reference/errors/WALLET_NOT_CONFIGURED) | no signing account is known. |
| [`ConfigError`](/docs/reference/errors/config-error) | [`CHAIN_NOT_CONFIGURED`](/docs/reference/errors/CHAIN_NOT_CONFIGURED) | an L2 that is not in the client's `chains`. |
| [`UnsupportedError`](/docs/reference/errors/unsupported-error) | [`UNSUPPORTED_ON_DEPLOYMENT`](/docs/reference/errors/UNSUPPORTED_ON_DEPLOYMENT) | a chain without an L2 reverse registrar. |
| [`UnauthorizedError`](/docs/reference/errors/unauthorized-error) | [`NOT_APPROVED`](/docs/reference/errors/NOT_APPROVED) | the signer may not name the address. |
| [`UnauthorizedError`](/docs/reference/errors/unauthorized-error) | [`SIGNATURE_INVALID`](/docs/reference/errors/SIGNATURE_INVALID), [`SIGNATURE_EXPIRED`](/docs/reference/errors/SIGNATURE_EXPIRED) | the claim's signature is invalid or expired. |
| [`UserRejectedError`](/docs/reference/errors/user-rejected-error) | [`USER_REJECTED`](/docs/reference/errors/USER_REJECTED) | the user rejects the request. |
| [`WalletError`](/docs/reference/errors/wallet-error) | [`CHAIN_MISMATCH`](/docs/reference/errors/CHAIN_MISMATCH), [`ACCOUNT_NOT_FOUND`](/docs/reference/errors/ACCOUNT_NOT_FOUND) | the wallet is on another chain or has no account to sign with. |
| [`UnsupportedError`](/docs/reference/errors/unsupported-error) | [`WALLET_BATCH_UNSUPPORTED`](/docs/reference/errors/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](/docs/sdk/errors-explained).

## Examples [#examples]

<Tabs groupId="api" items={["Client","Standalone","Effect"]} persist>
<Tab>
```ts title="Setting a primary name"
const { hash } = await ens.primaryName.set({ name: "alice.eth" })
```

```ts title="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 } })
```

```ts title="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 } })
```

```ts title="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 } })
```
</Tab>

<Tab>
```ts title="Setting a primary name with a standalone call"
import { Actions } from "@ensforge/sdk"

await Actions.primaryName.set(ens, { name: "alice.eth" })
```
</Tab>

<Tab>
```ts title="Setting a primary name in an Effect program"
import { Actions } from "@ensforge/sdk/effect"

yield* Actions.primaryName.set(ens, { name: "alice.eth" })
```
</Tab>
</Tabs>

## Plan methods [#plan-methods]

Each method takes the same options as `primaryName.set` and sends nothing. See [Preview before sending](/docs/sdk/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` [#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`](/docs/reference/sdk/client#sync-options).

Resolves to `Write.SyncResult`. Receipts plus the submitted hashes and plan.

<Tabs groupId="api" items={["Client","Standalone","Effect"]} persist>
<Tab>
```ts title="Setting a primary name and waiting"
const { receipt } = await ens.primaryName.setSync({ name: "alice.eth" })
```
</Tab>

<Tab>
```ts title="Waiting with a standalone call"
import { Actions } from "@ensforge/sdk"

await Actions.primaryName.setSync(ens, { name: "alice.eth" })
```
</Tab>

<Tab>
```ts title="Waiting in an Effect program"
import { Actions } from "@ensforge/sdk/effect"

yield* Actions.primaryName.setSync(ens, { name: "alice.eth" })
```
</Tab>
</Tabs>

## See also [#see-also]

- [`primaryName.get`](/docs/reference/sdk/primary-name/get) to read it