> For the complete documentation index, see [llms.txt](https://docs.nftx.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.nftx.io/contracts/migrator-zap.md).

# Migrator Zap

Atomic NFTX v2/v3 → v4 migration — redeem whole NFTs from a legacy vault and mint v4 floor tokens in one call — plus an owner-settled dust escrow for sub-unit legacy balances.

`MigratorZap` moves holders of legacy NFTX vault tokens into v4. A migration call redeems the named NFTs from a v2 or v3 vault, deposits them into the v4 `Locker`, and mints the collection token straight to the recipient — one transaction, whole units only (`N * 1e18` vault tokens for `N` NFTs). For balances below one whole unit it carries a **dust escrow**: the owner registers legacy → replacement token pairs, holders escrow their dust, and the owner settles batches at exactly 1:1.

Ethereum Mainnet only — the legacy v2/v3 factories were never deployed elsewhere. Every state-changing entry point is `nonReentrant`; `migrateFromV3` is `payable`. NFTs land on the contract only between redeem and deposit within a single transaction; beyond escrowed dust and pre-funded replacement tokens, nothing settles here.

Signatures, events and errors below come from the `IMigratorZap` interface, which integrators should build against.

{% hint style="info" %}
Legacy vaults key their fee exclusion off `msg.sender`, so excluding this one router (a legacy-factory-owner action) waives redeem fees for everyone who migrates through it. Until then, quotes include the fee.
{% endhint %}

## Migration

### `migrateFromV2`

Redeems named NFTs from a v2 vault and mints v4 collection tokens. Flow: `vault tokens → v2 redeemTo → NFTs → locker.deposit() → collection tokens to recipient`.

```solidity
function migrateFromV2(uint vaultId, uint[] calldata tokenIds, address recipient, uint maxVTokenIn) external returns (uint vTokenSpent);
```

| Parameter     | Type      | Description                                                   |
| ------------- | --------- | ------------------------------------------------------------- |
| `vaultId`     | `uint`    | Legacy v2 vault ID                                            |
| `tokenIds`    | `uint[]`  | Exact IDs to withdraw (must be held by the vault)             |
| `recipient`   | `address` | Who receives the minted collection tokens                     |
| `maxVTokenIn` | `uint`    | Ceiling on vault tokens spent — pass `quoteV2`'s first return |

| Return        | Type   | Description                                                            |
| ------------- | ------ | ---------------------------------------------------------------------- |
| `vTokenSpent` | `uint` | Vault tokens pulled from the caller (principal plus any v2 redeem fee) |

### `migrateFromV3`

As above against a v3 vault, where the redeem fee and item premiums are paid in ETH. Send at least `quoteV3Eth`'s `ethRequired`; unused ETH is refunded in the same transaction.

```solidity
function migrateFromV3(uint vaultId, uint[] calldata tokenIds, address recipient, uint premiumLimit) external payable returns (uint ethSpent);
```

| Parameter      | Type      | Description                                                                                             |
| -------------- | --------- | ------------------------------------------------------------------------------------------------------- |
| `vaultId`      | `uint`    | Legacy v3 vault ID                                                                                      |
| `tokenIds`     | `uint[]`  | Exact IDs to withdraw                                                                                   |
| `recipient`    | `address` | Who receives the minted collection tokens                                                               |
| `premiumLimit` | `uint`    | Cap on premium vTokens charged by the vault; pass `0` to derive it from the live quote plus a 5% buffer |

| Return     | Type   | Description                             |
| ---------- | ------ | --------------------------------------- |
| `ethSpent` | `uint` | ETH consumed by the vault after refunds |

### Quotes

```solidity
function quoteV2(uint vaultId, uint count) external view returns (uint vTokenIn, uint feePortion);
function quoteV3VToken(uint count) external pure returns (uint);
function quoteV3Eth(uint vaultId, uint[] calldata tokenIds) external view returns (uint ethRequired, uint premiumVToken);
function isFeeExemptV2() external view returns (bool);
function isFeeExemptV3() external view returns (bool);
```

| Function                          | Returns                                                                                                                                                                                            |
| --------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `quoteV2`                         | Vault tokens needed to redeem `count` NFTs, and the fee portion inside that figure (`0` when fee-excluded)                                                                                         |
| `quoteV3VToken`                   | Vault tokens burned by a v3 redeem — always `count * 1e18`                                                                                                                                         |
| `quoteV3Eth`                      | ETH required for the v3 fee + premium on the exact `tokenIds`, and the premium expressed in vTokens. Premiums are priced whether or not the fee is waived; the vault refunds what it does not take |
| `isFeeExemptV2` / `isFeeExemptV3` | Whether the legacy factory currently fee-excludes this router                                                                                                                                      |

## Dust escrow

Sub-unit legacy balances can never redeem an NFT. The escrow retires them: deposits are only accepted for owner-registered pairs, settlement pays the deposited raw amount straight across (both sides of every pair are 18-decimal), and until settlement the depositor can always exit.

### `setDustSwapTokens`

Owner-only. Registers legacy → replacement pairs in one batch; a zero `newToken` unregisters that pair (no new deposits, no settlement — withdrawal keeps working). A registered pair is exactly one whose replacement is non-zero.

```solidity
function setDustSwapTokens(address[] calldata legacyTokens, address[] calldata newTokens) external;
```

| Parameter      | Type        | Description                                           |
| -------------- | ----------- | ----------------------------------------------------- |
| `legacyTokens` | `address[]` | The tokens being retired                              |
| `newTokens`    | `address[]` | Their replacements, index-aligned; zero to unregister |

### `depositDust`

Escrows legacy dust against a later owner settlement. The amount credited is the balance the contract actually received. Closed while the zap is paused.

```solidity
function depositDust(address legacyToken, uint amount) external returns (uint depositId);
```

| Parameter     | Type      | Description                        |
| ------------- | --------- | ---------------------------------- |
| `legacyToken` | `address` | A registered legacy token          |
| `amount`      | `uint`    | Raw amount to pull from the caller |

| Return      | Type   | Description                                     |
| ----------- | ------ | ----------------------------------------------- |
| `depositId` | `uint` | Handle for `withdrawDust` / `finaliseDustSwaps` |

### `withdrawDust`

Reclaims an escrowed deposit that has not been settled. Depositor-only, and deliberately not gated on pause or the pair still being registered — once escrowed, the exit is always open.

```solidity
function withdrawDust(uint depositId) external;
```

### `finaliseDustSwaps`

Owner-only. Settles a batch of deposits: pays each depositor the deposited amount in the replacement token (from the contract's pre-funded balance) and forwards the legacy tokens to `legacyRecipient`. All-or-nothing — an unknown ID, an unregistered pair, or an underfunded payout reverts the whole batch. Each settled deposit is closed and cannot be withdrawn or settled again.

```solidity
function finaliseDustSwaps(uint[] calldata depositIds, address legacyRecipient) external;
```

| Parameter         | Type      | Description                                            |
| ----------------- | --------- | ------------------------------------------------------ |
| `depositIds`      | `uint[]`  | The deposits to settle (need not share a legacy token) |
| `legacyRecipient` | `address` | Where the escrowed legacy tokens are sent              |

## Administration

```solidity
function setPaused(bool _paused) external;
function sweep(address token, address recipient, uint amount) external;
```

| Function    | Description                                                                                                                                                      |
| ----------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `setPaused` | Owner-only. Closes the migrate and deposit entry points; withdrawal and settlement stay open                                                                     |
| `sweep`     | Owner-only. Recovers tokens mistakenly sent to the contract. Escrowed dust is excluded from the sweepable balance — depositors' withdraw rights outrank recovery |

## Events

```solidity
event MigratedFromV2(address indexed caller, address indexed vault, address indexed collection, address recipient, uint[] tokenIds, uint vTokenSpent, uint feePaid);
event MigratedFromV3(address indexed caller, address indexed vault, address indexed collection, address recipient, uint[] tokenIds, uint vTokenSpent, uint ethSpent);
event DustSwapTokenSet(address indexed legacyToken, address indexed newToken);
event DustDeposited(uint indexed depositId, address indexed depositor, address indexed legacyToken, uint amount);
event DustWithdrawn(uint indexed depositId, address indexed depositor, address indexed legacyToken, uint amount);
event DustSwapFinalised(uint indexed depositId, address indexed depositor, address indexed legacyToken, address newToken, address legacyRecipient, uint amount);
event PausedSet(bool paused);
event Swept(address indexed token, address indexed recipient, uint amount);
```

## Errors

| Error                                       | Raised when                                                                                     |
| ------------------------------------------- | ----------------------------------------------------------------------------------------------- |
| `ZapPaused`                                 | A migrate or deposit call arrives while paused                                                  |
| `NoTokenIdsGiven` / `NoDepositsGiven`       | An empty batch is passed                                                                        |
| `UnknownVault(vaultId)`                     | The legacy factory has no vault at that ID                                                      |
| `TargetRedeemDisabled(vault)`               | The v2 vault has targeted redeems switched off                                                  |
| `CostExceedsMaximum(required, maxVTokenIn)` | The v2 quote exceeds the caller's ceiling                                                       |
| `InsufficientEth(required, supplied)`       | `migrateFromV3` was sent less than the quote                                                    |
| `CollectionNotRegistered(collection)`       | The collection has no v4 vault yet                                                              |
| `InvalidToken` / `TokenPairLengthMismatch`  | A degenerate pair (zero legacy, self-mapping) or mismatched batch arrays in `setDustSwapTokens` |
| `DustSwapNotConfigured(legacyToken)`        | A deposit or settlement references an unregistered pair                                         |
| `ZeroAmount`                                | A deposit of zero, or one where nothing arrived                                                 |
| `UnknownDeposit(depositId)`                 | The deposit was never opened, or was already withdrawn or settled                               |
| `NotDepositor(depositId, depositor)`        | A withdrawal from anyone but the depositor                                                      |
| `AmountExceedsFreeBalance(requested, free)` | A sweep that would touch escrowed dust                                                          |
| `InvalidRecipient` / `RefundFailed`         | A zero recipient, or a failed ETH refund                                                        |
