Introducing the IOTA Legacy Migration Tool
Migrate Your Tokens from Legacy Network to Stardust
TL;DR:
The IOTA Legacy Migration Tool is a standalone app that helps users migrate their tokens from the legacy IOTA network to the Stardust version. As with previous migrations within the Firefly wallet, this new tool allows users to migrate from an 81-character seed, a Trinity seed vault file, or a Ledger device. After successful migration, users must then use a trusted wallet and import their new mnemonic, Stronghold, or Ledger device. The tool simplifies the migration process and offers step-by-step guidance. This blog post repeats that information and covers different migration scenarios for users with software profiles or Ledger devices. Users are recommended to use the tool from 21 February 2024 to ensure a smooth transition to the Stardust network.
The Chrysalis protocol update was released in 2021, and three years on, the Stardust protocol upgrade replaced Chrysalis in 2023. As a result, it will eventually become impossible to migrate IOTA tokens from the legacy IOTA network to the new Stardust version. Now we’re inviting all IOTA token holders to migrate their tokens from the Legacy network to the Stardust network. To assist with this transition, we have developed the IOTA Legacy Migration Tool. This blog post provides instructions on how to use this tool and successfully migrate your tokens to the Stardust network.
This guide to the IOTA Legacy Migration Tool will take you through these chapters:
- Seamless Token Migration to Stardust
- Migration Processes Overview
- Step-by-Step: The Most Common Token Migration Process
1: Users with Software Profiles
2: Users with Ledger Devices - Migrating Multiple Transactions
- Ledger Users: Threshold Considerations
- Addressing Balance Challenges
Seamless Token Migration to Stardust
The migration period commences on 21 February 2024. The IOTA Foundation will review the demand for the tool regularly before deciding on its future availability. Therefore, to ensure a smooth transition to the Stardust network, you are advised to complete your migration in a timely manner, since other forms of migration will be costly and less convenient.
To initiate migration, you must enter your legacy seed in the IOTA Legacy Migration Tool and follow the step-by-step instructions.
After entering your seed into the IOTA Legacy Migration Tool, a new mnemonic and Stronghold file will be created, and an Ed25519 address specific to the Stardust network will be generated for your tokens. This address will be the receiving address for the migrated tokens, so you really must write down the mnemonic and save the Stronghold file!
The IOTA Legacy Migration Tool streamlines the entire process, automating the heavy lifting, and provides a user-friendly interface to guide you through the migration. This blog post serves as a supplementary guide, offering a side-by-side reference to ensure an even smoother transition.
Migration Processes Overview
Most users will follow the same process when using the IOTA Legacy Migration Tool, regardless of whether they use software profiles or a Ledger device. Some users may follow a slightly different process but, even with these differences taken into account, the transition has been designed to be as simple as possible. There are built-in options to help you throughout the process, which are outlined below on a case-by-case basis.
Note, if you have lots of small amounts of $IOTA (<1Mi) spread across lots of addresses, it may not be possible to migrate these small amounts, particularly if their total is less than the minimum required storage deposit on the Stardust network.
Users with Software Profiles:
1. Input seed or .kdbx file into the IOTA Legacy Migration Tool desktop app.
2. Check whether the balance is correct.
3. Create a new password for your Stronghold file.
4. The IOTA Legacy Migration Tool will generate a mnemonic and Stronghold backup file. Save them!
5. Initiate the automated migration process.
6. Export Stronghold Backup and Migration Log.
Users with Ledger Devices:
1. Connect your Ledger device to your computer.
2. Install both the IOTA Legacy App (0.5.8) and the new IOTA App v0.8.6 on your Ledger device using Ledger Live.
3. Close Ledger Live, open the new IOTA App on your Ledger device and generate a Stardust address.
4. Swap to the legacy Ledger App and verify the accuracy of your balance.
5. Initiate the automated migration process.
Next, we’ll explore each step in more detail.
Step-by-Step: The Most Common Token Migration Process
First, download the IOTA Legacy Migration Tool (available on Windows, Mac, or Linux). You’ll be presented with three options to load your existing seed into the IOTA Legacy Migration Tool: importing a text backup, a file backup, or your Ledger device backup.
1. Users with Software Profiles
Text backup: Enter your IOTA seed (81 characters).
File backup: Import a Trinity SeedVault file (with the extension .kdbx).
If you select the text backup option, you’ll be prompted to enter your seed before continuing.
Once you’ve entered your seed (or SeedVault), you can check if your balance is correct before beginning the migration. If it isn't correct, hit “Check Again”.
After confirming your seed balance, you’ll create a password for your Stronghold backup file; it’s used for protecting your funds and restoring from backup. It’s important to back up your wallet to make sure you can always access your funds.
In the next step, you begin the backup process, which involves generating a 24-word recovery phrase (mnemonic) and the Stronghold backup file. The recovery phrase will help you retrieve your funds should you lose access to your wallet and other backups. But the recovery phrase and Stronghold file do more than just provide a backup: you can use either one to access your funds in your preferred wallet post-migration, whether it's Firefly, Bloom, TanglePay, or any other compatible wallet of your choice.
Copy down the words in their exact order. It is important that you keep a physical copy because digital files can fail.
Next, you’ll have to verify your recovery phrase to ensure you captured it correctly.
Finally, you’ll be prompted to back up to a Stronghold file by entering your wallet password. Having both a digital and physical backup is the best way to ensure you can always restore your wallet.
Now, let's begin the migration of your funds. The only thing you need to do is select the “Begin Migration” button since this is an automated process. But please note that you can select “Learn about the migration” should you have any further questions.
Be patient! The next step could take a few moments...
Congratulations, you’ve successfully migrated your funds to the Stardust network!
To ensure a comprehensive record of your migration, we recommend taking the following steps:
Export Migration Log: Generate a detailed record of your migration journey by clicking on "Export Migration Log". Save this log for future reference or as documentation of your successful transition.
Export Stronghold File: Secure your Stronghold file by clicking on "Export Stronghold File". This file is essential for accessing your tokens and should be stored securely. This file can be imported into any wallet, ensuring versatile access to your assets.
If you haven't exported these files yet, we strongly recommend doing so now! They will help you maintain comprehensive records and ensure secure management of your tokens on the Stardust network. Your migration is complete, and safeguarding these files is essential for future interactions with your assets.
2. Users with Ledger Devices
Start by selecting "I have a Ledger backup" and then "Continue" on the next page.
The IOTA Legacy Migration Tool will now instruct you to make sure you have both the new IOTA App and the IOTA Legacy App installed through Ledger Live.
In Ledger Live, open the "Manager" tab and allow the manager onto your device by pressing both buttons together. Make sure your Ledger firmware is up to date. Then search for "iota" and install the latest version of both apps.
Once installed, close Ledger Live and hit "Yes, I've installed these apps" in the IOTA Legacy Migration Tool. Open the new IOTA app on your device and, on the next page, press "Continue".
On the next page, you can generate a new Stardust address to send your tokens to. Make sure the address in the IOTA Legacy Migration Tool matches the one on your ledger device. Confirm it matches by pressing both buttons on your device when prompted.
Now it’s time to switch back to the Legacy app on your device and begin migrating your tokens.
On the following page, you need to select the account index you used with Trinity. For most users, this will be the default index in Trinity, which was 0. If you have more than one index, you can migrate them after you’ve finished migrating the first index.
On the next page, check if your balance is correct before beginning the migration. This can take a few minutes.
Make sure your Ledger Nano reads "Generating address..." on the device screen. If nothing is happening on your device, disconnect and reconnect the device and try again.
If your balance is still incorrect after the address has been generated, hit “Check Again”.
Once you're happy with your balance, press "Continue".
Now it's time to migrate! Hit "Begin Migration".
You’ll need to confirm the transaction by checking the information displayed in the IOTA Legacy Migration Tool against what is displayed on your device. Scroll through, make sure it matches, and approve the transaction by pressing both buttons on the device.
Once approved, the IOTA Legacy Migration Tool will transfer your tokens to your new Stardust address. Be warned, this step can take a few minutes.
Congratulations on completing the migration to the Stardust network!
If you have more than one account index, you can begin migrating the next one by pressing "Migrate another profile".
Once you’ve migrated all your account indexes you can safely remove the IOTA Legacy App from your Ledger device.
Migrating Multiple Transactions
Say you make it through the preliminary stages to the step where you check your balance is correct but find that you have multiple bundles to migrate, this scenario can occur due to the large number of addresses that need to be migrated.
You don't have to worry: Just select “Migrate funds” and the IOTA Legacy Migration Tool will bundle multiple transactions!
You can then continue to a successful migration.
Ledger Users: Threshold Considerations
This section concerns Ledger device users with funds greater than the Minimum Required Storage Deposit on the Stardust network but less than the 1Mi legacy network threshold.
Due to limitations of the legacy network, addresses holding amounts below the migratable threshold (1Mi) will display an input amount of 1 IOTA on their Ledger devices during the migration process.
Despite this discrepancy, users can confirm the transaction on their Ledger devices, ensuring the secure transfer of their assets to the new network.
Addressing Balance Challenges
What if you discover that your funds don’t meet the minimum required amount for migration?
If your balance appears incorrect, click "Check Again'' to locate your funds. It's important to note that, for a successful migration, a balance of minimum required storage deposit is required due to Stardust’s dust protection policy.
The IOTA Legacy Migration Tool is a standalone app designed for a smooth transition to the Stardust network. Remember that this tool is not a wallet; you must transfer the recovery phrase (mnemonic) or Stronghold file to a compatible wallet to access your migrated funds.
For more information about Stardust and the IOTA Foundation's resources, check out this blog post.
If you have further questions, join the #help channel on our Discord.