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

registration.register

Registers one or more .eth names: approve, commit, wait, register, then records and primary name. Options, errors and examples for registration.register.

Writestable
Since v1.0.0View source

Registers one or more .eth names: approve, commit, wait, register, then records and primary name. Resolves once the transaction is submitted.

When to use

Use to buy names in one flow; the plan runs every transaction in order. Use registerSync to wait for the receipt.

Details

  • The plan: approve the token (if the allowance is short) with the commit → wait the registrar's minimum commitment age on chain time → register (deploying each name's resolver) → records → primary name.
  • The approval covers the quote plus 2%, since the price is charged at register and can drift (e.g. a decaying premium); only the actual price is paid.
  • Paid in ERC-20 (USDC by default); the registrar does not accept ETH.
  • By default each name gets its own PermissionedResolver with records written at creation; its ETH address defaults to the owner (addresses: { eth: null } leaves it unset).
  • The result's secret resumes an interrupted registration: call again with the same options and secret.

Gotchas

  • Resolves after the last transaction is submitted, at least a minute after the commit.
  • Resuming needs exactly the same options: they are part of the commitment.

Signature

function register(
  client: Like,
  options: register.Options & Write.Options,
): Promise<register.ReturnType>

Call it as ens.registration.register(options) on a client, or Actions.registration.register(client, options).

In React, use useRegister.

Parameters

OptionTypeDefaultDescription
names (required)string | readonly string[]One or more .eth second-level names; several share one plan. Normalized automatically.
duration (required)bigintRegistration length in seconds, e.g. Duration.years(1).
ownerstringthe signing accountOwner of the names.
resolverstring | nullResolver for the names. By default each name gets its own PermissionedResolver, deployed in the same plan with records written at creation. "owned" uses the signer's shared PermissionedResolver (the ENS app's address), deployed once and reused; its roles cover every name on it. null registers without a resolver.
recordsOmit<recordSet.Options, "name" | "resolver" | "clear" | "pubkey">Records for every name, written when its resolver is created (or right after registering).
primaryNamebooleanSet the (single) name as the signer's primary name; adds its eth address record.
paymentTokenPaymentToken"usdc"Token to pay with.
subregistrystringENSv2 registry for the names' subnames.
referrerHexReferrer recorded by the registrar: 32 bytes, or an address (left-padded).
secretHexSecret from an earlier commit or register, to finish that registration.

Also takes the write options.

Returns

Resolves to Write.Result & { readonly secret: Hex }. Submitted hashes, the plan and the commitment secret.

Errors

ErrorCodesWhen
InvalidInputErrorINVALID_NAME, INVALID_ADDRESS, DURATION_TOO_SHORT, INVALID_RECORD_VALUEinvalid input.
NameStateErrorNAME_NOT_AVAILABLEa name is taken or in its grace period.
CommitmentErrorCOMMITMENT_TOO_NEW, COMMITMENT_TOO_OLD, COMMITMENT_EXISTSa resumed commitment outside its window.
InsufficientFundsErrorINSUFFICIENT_TOKEN_BALANCEthe signer cannot pay in the payment token.
UnsupportedErrorPAYMENT_TOKEN_UNSUPPORTED, UNSUPPORTED_ON_DEPLOYMENTan unaccepted token or without ENSv2.
ConfigErrorWALLET_NOT_CONFIGUREDno signing account is known.
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

Registering a name
const { secret } = await ens.registration.register({ names: "alice.eth", duration: 31536000n, records: { texts: { url: "https://alice.dev" } } })

Plan methods

Each method takes the same options as registration.register and sends nothing. See Preview before sending.

MethodDescription
registration.register.prepare(options)Builds the plan without sending anything.
registration.register.simulate(options)Simulates the plan with eth_call, reporting each step.
registration.register.estimateGas(options)Estimates the gas and ETH the plan needs.

Wait for the receipt with registerSync

Registers one or more .eth names: approve, commit, wait, register, then records and primary name. Resolves once the receipt is in.

Use when the next step depends on the change being on-chain.

registration.registerSync takes the same options plus confirmations and timeout.

Resolves to registerSync.ReturnType. Receipts, the registered names with token IDs and expiries, and the amount paid.

Registering a name and waiting
const { receipt } = await ens.registration.registerSync({ names: "alice.eth", duration: 31536000n, records: { texts: { url: "https://alice.dev" } } })

See also

Was this page helpful?