registration.register
Registers one or more .eth names: approve, commit, wait, register, then records and primary name. Options, errors and examples for registration.register.
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
registerand 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
recordswritten at creation; its ETH address defaults to the owner (addresses: { eth: null }leaves it unset). - The result's
secretresumes an interrupted registration: call again with the same options andsecret.
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
| Option | Type | Default | Description |
|---|---|---|---|
names (required) | string | readonly string[] | One or more .eth second-level names; several share one plan. Normalized automatically. | |
duration (required) | bigint | Registration length in seconds, e.g. Duration.years(1). | |
owner | string | the signing account | Owner of the names. |
resolver | string | null | Resolver 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. | |
records | Omit<recordSet.Options, "name" | "resolver" | "clear" | "pubkey"> | Records for every name, written when its resolver is created (or right after registering). | |
primaryName | boolean | Set the (single) name as the signer's primary name; adds its eth address record. | |
paymentToken | PaymentToken | "usdc" | Token to pay with. |
subregistry | string | ENSv2 registry for the names' subnames. | |
referrer | Hex | Referrer recorded by the registrar: 32 bytes, or an address (left-padded). | |
secret | Hex | Secret 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
| Error | Codes | When |
|---|---|---|
InvalidInputError | INVALID_NAME, INVALID_ADDRESS, DURATION_TOO_SHORT, INVALID_RECORD_VALUE | invalid input. |
NameStateError | NAME_NOT_AVAILABLE | a name is taken or in its grace period. |
CommitmentError | COMMITMENT_TOO_NEW, COMMITMENT_TOO_OLD, COMMITMENT_EXISTS | a resumed commitment outside its window. |
InsufficientFundsError | INSUFFICIENT_TOKEN_BALANCE | the signer cannot pay in the payment token. |
UnsupportedError | PAYMENT_TOKEN_UNSUPPORTED, UNSUPPORTED_ON_DEPLOYMENT | an unaccepted token or without ENSv2. |
ConfigError | WALLET_NOT_CONFIGURED | no signing account is known. |
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 { 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.
| Method | Description |
|---|---|
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.
const { receipt } = await ens.registration.registerSync({ names: "alice.eth", duration: 31536000n, records: { texts: { url: "https://alice.dev" } } })See also
registration.getPriceto quote it first
Was this page helpful?