Firefly Token Migration Guide for Ledger Users
To Download Firefly, Visit https://firefly.iota.org/
TL;DR:
This post serves as a supplementary guide for migrating your Ledger Nano to Chrysalis with Firefly. Think of it as a side-by-side reference to help you migrate smoothly. The General Use Guide for Ledger can be found here.
IOTA's recent Chrysalis upgrade requires migrating your tokens from the legacy IOTA mainnet to the new Chrysalis network. Firefly seamlessly guides Ledger users through the migration process. All you need to do is plug in your Ledger Nano device, open Firefly, and follow the step-by-step process. There is no rush to migrate your tokens but we recommend getting it over and done with to allow you to send your tokens on the Chrysalis network.
The migration from the legacy network to the new Chrysalis network involves migrating away from addresses based on Winternitz One-Time Signature to reusable EdDSA addresses. These protocol changes also mean we need to migrate away from the old Ledger Nano app to a new one, and from the old wallet, Trinity, to our new wallet, Firefly.
After plugging in your Ledger Nano, Firefly will guide you through a series of steps to migrate your tokens. This post serves as a supplementary guide to the automated process in Firefly. Think of it as a side-by-side reference to make sure everything is running smoothly!
We also advise everybody to read our blog post about Security During Token Migration.
Migrating funds
As you migrate your funds with Firefly, most users will follow the same migration process. In certain cases, some users will follow a slightly different flow, but even with these differences, remember that we have made the migration as simple as possible. Firefly will help you through the process. We outline each flow individually below.
All Ledger token migrations follow the same basic process:
- Create a new Firefly profile and set a PIN code
- Plug in your Ledger device
- Install both legacy and new IOTA apps on your device through Ledger Live
- Close Ledger Live, open the new IOTA app on your device and generate a Chrysalis address
- Swap to the old legacy Ledger app and check whether your balance is correct
- Initiate the automated migration process
- Begin exploring Firefly
Begin migration
First, download Firefly (Windows, Mac, or Linux). Open the app, read and accept the terms and conditions, set your theme, and choose a profile name.
The migration begins by selecting "Migrate or restore a wallet" from the wallet setup page.
Select "I have a Ledger backup" and then "I have a Trinity profile" on the following page.
Set up a wallet PIN code. Choose a PIN that only you know and re-enter the PIN code on the next page to confirm.
Now, Firefly will 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.
Note: If you do not have space on your device you can safely uninstall other cryptocurrency apps and reinstall them later.
Once installed, close Ledger Live and hit "Yes, I've installed these apps" in Firefly. Open the new IOTA app on your device and, on the next page, press "Continue".
On the next page, you will generate a new Chrysalis address to send your tokens to. Make sure the address in Firefly matches the one on your device by scrolling through. Confirm it matches by pressing both buttons on your device when prompted.
Now it is 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 index 0 which was the default index in Trinity. If you have more than one index, you can migrate them after you have 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 you can disconnect and reconnect the device and try again.
Once it finishes, if the balance is not correct hit “Check Again”. Once you are happy with your balance, press "Continue".
Note: If the balance is zero you likely selected the wrong account index.
Now it's time to migrate. Hit "Begin Migration".
You will need to confirm the transaction by checking the information displayed in Firefly 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, Firefly will transfer your tokens to your new Chrysalis address. Be warned, this step can take a few minutes.
Congratulations, you’ve successfully migrated to Chrysalis! Export a migration log (for your own records), reopen the new IOTA app and Firefly will navigate to the dashboard.
Once you get to the dashboard, you can choose to migrate another index or begin using Firefly.
Note: If you have more than one account index you can begin migrating the next one by pressing "Migrate another index". Each index's funds will be sent to a separate wallet within the same Firefly profile. Alternatively, you can migrate additional indexes later from the Advanced Settings.
If you have no more indexes to migrate you can hit "Close". Make sure your Ledger is connected and the new app is open. Your funds will become available after a short period of time.
Note: Once you have migrated all your account indexes you can safely remove the IOTA Legacy app from your device.
Other common migration cases
As mentioned above, there are a few different migration flows depending on how your funds were distributed across your addresses on the legacy network. Don't worry: each flow is simple and your funds can be migrated smoothly.
After you complete the preliminary steps, once you have confirmed your balance, you may see a page that says you need to send multiple migration transactions.
You can simply press “Migrate funds” and Firefly will send each transaction one after the other. As each migration completes, you will need to confirm them one by one on your Ledger device. Compare the information displayed and make sure it matches.
Once complete, you can continue with the remaining steps.
Rarer migrations
Migrating funds on an address that has already been spent from
If you accidentally received funds on an address you have already spent from in Trinity, you may encounter an unsettling screen after going through the preliminary setup. But everything is fine: Firefly will guide you through the process.
Note. In the legacy IOTA network, it was inadvisable to send funds from an address after it had already been spent from. This process helps to secure those funds during the migration. You can read more about spent addresses here.
This just means Firefly will perform what we call “bundle mining”. In this case, Firefly is spending some time trying to find a bundle for that spent address so you can migrate your tokens safely.
After selecting “Continue”, you can choose “Secure selected addresses” to secure your funds and allow you to migrate safely.
Be patient! This process will take 10 minutes per spent address as Firefly tries to create a secure bundle. Your computer will run at full capacity in this period, so do something else while you wait for this to complete.
Once the security check completes, you can choose to rerun the process (which may lower your risk level) or continue the migration process once you feel satisfied.
Your funds have now been securely migrated!
Additional occurrences
What if you find that you don’t have the minimum amount of funds to migrate?
If your balance is not correct, hit “Check Again'' to find your funds. Be aware that there is a minimum requirement of 1Mi for a successful migration due to our dust protection. It is not possible to migrate a Ledger account index with less than 1Mi.
If you have lots of small amounts (<1Mi) spread across lots of addresses it may not be possible to migrate them.
To read about Chrysalis and view the resources for the most substantial upgrade in the IOTA Foundation's history, visit: https://chrysalis.iota.org/. If you have further questions, join the #help channel on our Discord. You can also join the #firefly-discussion channel to make feature suggestions and follow the development.
Read the General Use Guide for Ledger Nano with Firefly here.
Read the announcement of the Ledger Nano Support in Firefly here.
