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

migration.migrate

Migrates one or more ENSv1 names to ENSv2, carrying their resolver records and subnames. Options, result, errors and examples for migration.migrate.

Writestable
Since v1.0.0View source

Migrates one or more ENSv1 names to ENSv2, carrying their resolver records and subnames. Resolves once the transaction is submitted.

When to use

Use to upgrade .eth names (unwrapped, wrapped or locked) and locked subnames to ENSv2. Use migrateSync to wait for the receipt.

Details

  • Plan: renew names in grace (with renew) → create each name's resolver with its records, and UserRegistries for its subnames → recreate the subnames → transfer the tokens to the migration controllers (parents before locked children) → register a locked name's subnames in its WrapperRegistry → restore ENSv1 managers.
  • Direct token transfers from the holder: no approvals are needed.
  • By default a name on an ENS public resolver gets its own PermissionedResolver; custom resolvers are kept. resolver: "owned" uses the signer's shared resolver (the ENS app's).
  • Records and subnames are those given per name; otherwise, with an indexer, every record key it lists (values read on-chain) and the live subnames at every depth; without one, allowIncompleteRecords copies the common records. Locked names follow their fuses.
  • The sending account keeps no roles on a subname registry it deploys for someone else.
  • An interrupted migration can run again: existing resolvers and registries are reused.

Gotchas

  • ENSv2 drops ENSv1 subnames that are not recreated, and records left on an ENSv1 public resolver become read-only. Without an indexer, pass every record and subname to carry over.
  • Use migrateSync to also verify the migrated state.

Signature

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

Call it as ens.migration.migrate(options) on a client, or Actions.migration.migrate(client, options).

In React, use useMigrate.

Parameters

OptionTypeDefaultDescription
names (required)NameInput | readonly NameInput[]Names to migrate: a name, or a name with its records and subnames.
resolver"new" | "owned" | "keep" | (string & {})"new" for names on an ENS public resolver, "keep" otherwise"new", "owned", "keep" or a resolver address.
ownerstringENSv2 owner of the names. Defaults to each token's holder.
allowIncompleteRecordsbooleanCopy the common records when a name's records are not given.
allowLeavingSubnamesbooleanMigrate even when a listed subname cannot be recreated.
preserveManagerbooleanGive each unwrapped name's ENSv1 manager setResolver and the record setter roles.
migrateParentsbooleanMigrate the ENSv1 parents of locked subnames first.
renew{ readonly duration: bigint; readonly paymentToken?: PaymentToken | undefined }Renew names in their grace period first.

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_ADDRESS, INVALID_RECORD_VALUEinvalid input.
MigrationErrorNOT_ELIGIBLE, ALREADY_MIGRATED, RECORDS_UNKNOWN, NAME_NOT_LOCKEDa name cannot migrate as asked.
NameStateErrorNAME_LOCKEDthe name is locked.
UnsupportedErrorUNSUPPORTED_ON_DEPLOYMENTwhere ENSv2 is not deployed.
UnauthorizedErrorNOT_OWNER, FUSE_BURNEDthe account may not move a token.
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

Migrating a name with its profile
const { hash } = await ens.migration.migrate({ names: { name: "alice.eth", records: { texts: { url: "https://alice.dev" } }, subnames: ["pay"] } })

Plan methods

Each method takes the same options as migration.migrate and sends nothing. See Preview before sending.

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

Wait for the receipt with migrateSync

Migrates one or more ENSv1 names to ENSv2, carrying their resolver records and subnames. Resolves once the receipt is in.

Use when the next step depends on the migration being on-chain; once every receipt is in, each name's ENSv2 owner, resolver, subregistry and copied records are checked against the plan.

migration.migrateSync takes the same options plus confirmations and timeout.

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

Migrating a name with its profile and waiting
const { receipt } = await ens.migration.migrateSync({ names: { name: "alice.eth", records: { texts: { url: "https://alice.dev" } }, subnames: ["pay"] } })

See also

Was this page helpful?