Stardust Migration
The migration documentation describes the processes needed to claim and migrate output types manually; However, for the average user, this knowledge is not needed and is abstracted in the wallet web application (dashboard). The specific migration knowledge described here is unnecessary for people using a regular wallet.
The legacy IOTA network runs the Stardust protocol version that represents assets and tokens in a UTXO-based ledger. IOTA Rebased introduces the Move-based object ledger, which necessitates the migration of assets and tokens from the Stardust ledger to the Move-based ledger.
The following pages describe the automated asset migration process into the new ledger model and serve as a guide for developers on how to use the new models and handle assets.
Why Migrate?
The Stardust ledger state, and hence the assets and tokens in the network, are represented via the Unspent Transaction Output (UTXO) model. Transactions consume previously unspent outputs, essentially removing them from the ledger, and create new outputs, thus updating the ledger state.
With the introduction of the object-based Move ledger in IOTA Rebased, transactions no longer consume and create outputs
but Move Objects instead.
A Move transaction names input objects that it intends to operate on (consume),
and executing the transaction produces the set of new objects to be written into the ledger, while the input objects are removed.
The two models are conceptually very similar, but the underlying data structures are different, as Move objects can take any shape and form, as opposed to the rigid format of UTXOs. The IOTA Foundation developed a Move package that emulates the Stardust output models in the Move language with all the previous Stardust functionality supported.
The IOTA Rebased network will be started with a ledger state where all previous outputs, and all tokens and assets held by them, are automatically converted into Move objects, coins, and balances.
How Is The Migration Done?
The migration is performed via a global snapshot, where all UTXOs are converted into Move objects. These objects then are part of the Move genesis that IOTA Rebased is started with.
The process is as follows:
- The IOTA Foundation announces the milestone indices at which snapshots of the IOTA network are taken.
- Once both milestones are reached in IOTA, global snapshots are taken via the Hornet node software. IOTAEVM stops processing deposits from and withdrawals to L1.
- The snapshots are then processed by the migration tool, which converts all UTXOs into Move objects.
- A Move genesis is prepared with all the Move objects from both snapshots.
- The genesis blob is published, and the IOTA Rebased network is started with it.
- IOTAEVM is connected to the IOTA Rebased network, deposits and withdrawals are enabled.
- IOTA and stardust native tokens can be immediately used on the IOTA Rebased network; However, more complex asset structures such as NFTs, Aliases or time-locked assets need to be claimed via the official tools.
What Breaks For Developers?
IOTA Rebased is a major change in the technology stack with the introduction of Move smart contracts and the object ledger. All previous IOTA integrations are broken and have to be reimplemented via the new APIs and SDKs.
What Does Not Break?
IOTA Rebased uses the same address scheme as IOTA Stardust, so all addresses and keys are still valid; there is no need to migrate secrets.
While the Ed25519 address scheme stays the same, address representation changes from Bech32 to Base58 hex encoding with
a 0x prefix. The Addresses and Keys guide provides help on how to parse Bech32 addresses to the new format.
How Can I Access Migrated Assets?
The IOTA Foundation provides a browser extension wallet where users can import their secrets from Stardust wallets and find their assets on the IOTA Rebased network. If necessary, based on the assets of the user, a web application that communicates with the browser extension wallet helps users claim their assets.
Developers can use the official SDKs and APIs to claim assets programmatically based on the information provided on the following pages. Example transactions on how to claim are described in the Claiming Stardust Assets guide.