migration.migrate
Migrates one or more ENSv1 names to ENSv2, carrying their resolver records and subnames. Options, result, errors and examples for migration.migrate.
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,
allowIncompleteRecordscopies 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
migrateSyncto 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
| Option | Type | Default | Description |
|---|---|---|---|
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. |
owner | string | ENSv2 owner of the names. Defaults to each token's holder. | |
allowIncompleteRecords | boolean | Copy the common records when a name's records are not given. | |
allowLeavingSubnames | boolean | Migrate even when a listed subname cannot be recreated. | |
preserveManager | boolean | Give each unwrapped name's ENSv1 manager setResolver and the record setter roles. | |
migrateParents | boolean | Migrate 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.
| 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
| Error | Codes | When |
|---|---|---|
InvalidInputError | INVALID_NAME, INVALID_ADDRESS, INVALID_RECORD_VALUE | invalid input. |
MigrationError | NOT_ELIGIBLE, ALREADY_MIGRATED, RECORDS_UNKNOWN, NAME_NOT_LOCKED | a name cannot migrate as asked. |
NameStateError | NAME_LOCKED | the name is locked. |
UnsupportedError | UNSUPPORTED_ON_DEPLOYMENT | where ENSv2 is not deployed. |
UnauthorizedError | NOT_OWNER, FUSE_BURNED | the account may not move a token. |
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 { 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.
| Method | Description |
|---|---|
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.
const { receipt } = await ens.migration.migrateSync({ names: { name: "alice.eth", records: { texts: { url: "https://alice.dev" } }, subnames: ["pay"] } })See also
migration.getto check a name first
Was this page helpful?