# migration.migrate

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

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

Source: https://ensforge.com/docs/reference/sdk/migration/migrate

<ApiMeta kind="Write" stability="stable" since="1.0.0" source="packages/sdk/src/actions/migration/migrate/index.ts#L74" />

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

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

Use to upgrade `.eth` names (unwrapped, wrapped or locked) and locked subnames to ENSv2. Use [`migrateSync`](/docs/reference/sdk/migration/migrate#wait-for-the-receipt-with-migratesync) to wait for the receipt.

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

<Callout type="warn" title="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`](/docs/reference/sdk/migration/migrate#wait-for-the-receipt-with-migratesync) to also verify the migrated state.
</Callout>

## Signature [#signature]

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

## Parameters [#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](/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_RECORD_VALUE`](/docs/reference/errors/INVALID_RECORD_VALUE) | invalid input. |
| [`MigrationError`](/docs/reference/errors/migration-error) | [`NOT_ELIGIBLE`](/docs/reference/errors/NOT_ELIGIBLE), [`ALREADY_MIGRATED`](/docs/reference/errors/ALREADY_MIGRATED), [`RECORDS_UNKNOWN`](/docs/reference/errors/RECORDS_UNKNOWN), [`NAME_NOT_LOCKED`](/docs/reference/errors/NAME_NOT_LOCKED) | a name cannot migrate as asked. |
| [`NameStateError`](/docs/reference/errors/name-state-error) | [`NAME_LOCKED`](/docs/reference/errors/NAME_LOCKED) | the name is locked. |
| [`UnsupportedError`](/docs/reference/errors/unsupported-error) | [`UNSUPPORTED_ON_DEPLOYMENT`](/docs/reference/errors/UNSUPPORTED_ON_DEPLOYMENT) | where ENSv2 is not deployed. |
| [`UnauthorizedError`](/docs/reference/errors/unauthorized-error) | [`NOT_OWNER`](/docs/reference/errors/NOT_OWNER), [`FUSE_BURNED`](/docs/reference/errors/FUSE_BURNED) | the account may not move a token. |
| [`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="Migrating a name with its profile"
const { hash } = await ens.migration.migrate({ names: { name: "alice.eth", records: { texts: { url: "https://alice.dev" } }, subnames: ["pay"] } })
```
</Tab>

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

await Actions.migration.migrate(ens, { names: { name: "alice.eth", records: { texts: { url: "https://alice.dev" } }, subnames: ["pay"] } })
```
</Tab>

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

yield* Actions.migration.migrate(ens, { names: { name: "alice.eth", records: { texts: { url: "https://alice.dev" } }, subnames: ["pay"] } })
```
</Tab>
</Tabs>

## Plan methods [#plan-methods]

Each method takes the same options as `migration.migrate` and sends nothing. See [Preview before sending](/docs/sdk/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` [#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`](/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="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"] } })
```
</Tab>

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

await Actions.migration.migrateSync(ens, { names: { name: "alice.eth", records: { texts: { url: "https://alice.dev" } }, subnames: ["pay"] } })
```
</Tab>

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

yield* Actions.migration.migrateSync(ens, { names: { name: "alice.eth", records: { texts: { url: "https://alice.dev" } }, subnames: ["pay"] } })
```
</Tab>
</Tabs>

## See also [#see-also]

- [`migration.get`](/docs/reference/sdk/migration/get) to check a name first