From a9e2da87b31b5a748da95317a3be1d28cf3f98cd Mon Sep 17 00:00:00 2001 From: Lucas Tortora <85233773+lucas-tortora@users.noreply.github.com> Date: Tue, 3 Sep 2024 18:13:44 -0300 Subject: [PATCH] feat(devx): Edit Developer > Stardust docs (#2063) * feat(devx): edit stardust docs * feat(devx): archive stardust doc stubs * feat(devx): archive stardust doc stubs * feat(devx): add warning * fix(devx): fix sidebar after merge * feat(devx): change tabs groupId from code-language to language * Update docs/content/developer/stardust/claiming/self-sponsor.mdx Co-authored-by: Dr-Electron --------- Co-authored-by: Dr-Electron --- docs/content/_snippets/migration-warning.mdx | 5 + .../objects/transfers/transfer-to-object.mdx | 2 +- .../transactions/sign-and-send-txn.mdx | 4 +- .../stardust/{advanced.mdx => _advanced.mdx} | 0 .../developer/stardust/{faq.mdx => _faq.mdx} | 0 .../stardust/{if-tools.mdx => _if-tools.mdx} | 0 .../stardust/{testing.mdx => _testing.mdx} | 0 .../stardust/{vested.mdx => _vested.mdx} | 0 docs/content/developer/stardust/addresses.mdx | 3 + docs/content/developer/stardust/claiming.mdx | 35 +++--- .../claiming/address-unlock-condition.mdx | 54 ++++++---- .../developer/stardust/claiming/alias.mdx | 84 +++++++++------ .../developer/stardust/claiming/basic.mdx | 76 ++++++++----- .../developer/stardust/claiming/foundry.mdx | 75 ++++++++----- .../developer/stardust/claiming/nft.mdx | 101 ++++++++++++------ .../stardust/claiming/self-sponsor.mdx | 59 ++++++---- docs/content/developer/stardust/exchanges.mdx | 76 +++++++------ .../developer/stardust/migration-process.mdx | 43 ++++---- .../developer/stardust/move-models.mdx | 3 +- .../developer/stardust/stardust-migration.mdx | 62 ++++++----- docs/content/developer/stardust/units.mdx | 3 + docs/content/sidebars/developer.js | 5 - 22 files changed, 426 insertions(+), 264 deletions(-) create mode 100644 docs/content/_snippets/migration-warning.mdx rename docs/content/developer/stardust/{advanced.mdx => _advanced.mdx} (100%) rename docs/content/developer/stardust/{faq.mdx => _faq.mdx} (100%) rename docs/content/developer/stardust/{if-tools.mdx => _if-tools.mdx} (100%) rename docs/content/developer/stardust/{testing.mdx => _testing.mdx} (100%) rename docs/content/developer/stardust/{vested.mdx => _vested.mdx} (100%) diff --git a/docs/content/_snippets/migration-warning.mdx b/docs/content/_snippets/migration-warning.mdx new file mode 100644 index 00000000000..c7cf9e6a8fb --- /dev/null +++ b/docs/content/_snippets/migration-warning.mdx @@ -0,0 +1,5 @@ +:::warning Exchanges and dApp Devs Only + +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. + +::: \ No newline at end of file diff --git a/docs/content/developer/iota-101/objects/transfers/transfer-to-object.mdx b/docs/content/developer/iota-101/objects/transfers/transfer-to-object.mdx index 33e7c0a1982..0132211d789 100644 --- a/docs/content/developer/iota-101/objects/transfers/transfer-to-object.mdx +++ b/docs/content/developer/iota-101/objects/transfers/transfer-to-object.mdx @@ -147,7 +147,7 @@ You can combine these restrictions to create complex rules, such as implementing When creating transactions, you interact with `Receiving` transaction inputs in a similar way to other object arguments in the IOTA TypeScript SDK. For example, if you want to receive a coin object with ID `0xc0ffee` that was sent to your account at `0xcafe`, you can do the following: - + diff --git a/docs/content/developer/iota-101/transactions/sign-and-send-txn.mdx b/docs/content/developer/iota-101/transactions/sign-and-send-txn.mdx index bef5ba03130..391ef445503 100644 --- a/docs/content/developer/iota-101/transactions/sign-and-send-txn.mdx +++ b/docs/content/developer/iota-101/transactions/sign-and-send-txn.mdx @@ -36,9 +36,9 @@ If you want to use a specific gas coin, first find the gas coin object ID to be The following examples demonstrate how to sign and execute transactions using Rust, TypeScript, or the IOTA CLI. - + - + There are various ways to instantiate a key pair and to derive its public key and IOTA address using the [IOTA TypeScript SDK](../../../references/ts-sdk/typescript/index.mdx#iota-typescript-sdk). diff --git a/docs/content/developer/stardust/advanced.mdx b/docs/content/developer/stardust/_advanced.mdx similarity index 100% rename from docs/content/developer/stardust/advanced.mdx rename to docs/content/developer/stardust/_advanced.mdx diff --git a/docs/content/developer/stardust/faq.mdx b/docs/content/developer/stardust/_faq.mdx similarity index 100% rename from docs/content/developer/stardust/faq.mdx rename to docs/content/developer/stardust/_faq.mdx diff --git a/docs/content/developer/stardust/if-tools.mdx b/docs/content/developer/stardust/_if-tools.mdx similarity index 100% rename from docs/content/developer/stardust/if-tools.mdx rename to docs/content/developer/stardust/_if-tools.mdx diff --git a/docs/content/developer/stardust/testing.mdx b/docs/content/developer/stardust/_testing.mdx similarity index 100% rename from docs/content/developer/stardust/testing.mdx rename to docs/content/developer/stardust/_testing.mdx diff --git a/docs/content/developer/stardust/vested.mdx b/docs/content/developer/stardust/_vested.mdx similarity index 100% rename from docs/content/developer/stardust/vested.mdx rename to docs/content/developer/stardust/_vested.mdx diff --git a/docs/content/developer/stardust/addresses.mdx b/docs/content/developer/stardust/addresses.mdx index e705d7f780d..c606fee0560 100644 --- a/docs/content/developer/stardust/addresses.mdx +++ b/docs/content/developer/stardust/addresses.mdx @@ -2,6 +2,9 @@ title: Addresses and Keys description: Explains how "previous" addresses are treated in the new ledger --- +import MigrationWarning from '../../_snippets/migration-warning.mdx'; + + ## Addresses diff --git a/docs/content/developer/stardust/claiming.mdx b/docs/content/developer/stardust/claiming.mdx index 4c8b8384552..922b5b3c34d 100644 --- a/docs/content/developer/stardust/claiming.mdx +++ b/docs/content/developer/stardust/claiming.mdx @@ -1,21 +1,28 @@ --- -title: Claiming Stardust Assets -description: Describes how to access the migrated assets and tokens +description: How to access the migrated Stardust assets and tokens --- +import MigrationWarning from '../../_snippets/migration-warning.mdx'; -As detailed in the [Stardust Move Models](move-models.mdx), Stardust assets are represented as Move objects within the ledger. Claiming these assets involves enabling original owners to utilize a [Programmable Transaction Block](../iota-101/transactions/ptb/prog-txn-blocks.mdx) to "unlock" assets such as IOTA, Shimmer, custom [`Coin`](../../references/framework/iota-framework/coin.mdx#resource-coin)s, or even `Alias` and `Nft` objects. +# Claiming Stardust Assets -This process takes advantage of Move's unique features to ensure that assets are transferred and unlocked securely and efficiently to their rightful owners. + +As detailed in the [Stardust Move Models](move-models.mdx), Stardust assets are represented as Move objects within the ledger. Claiming these assets involves enabling original owners to utilize a [Programmable Transaction Block](../iota-101/transactions/ptb/prog-txn-blocks.mdx) to "unlock" assets such as IOTA, Shimmer, custom [`Coin`](../../references/framework/iota-framework/coin.mdx#resource-coin)s, or even `Alias` and `Nft` objects. -## Output types to Move Objects +This process takes advantage of Move's unique features to ensure that assets are transferred and unlocked securely and efficiently to their rightful owners. -Stardust assets come in the form of Outputs and each Output can be of a different type. For understanding how Outputs have been transformed into Move Objects based on their types, please refer to the [Stardust Move Models](move-models.mdx#summary) page. In here, one or more claiming examples for each Output type will be shown. +## Output Types to Move Objects +Stardust assets come in the form of Outputs, and each Output can be of a different type. +To understand how Outputs have been transformed into Move Objects based on their types, +please refer to the [Stardust Move Models](move-models.mdx#summary) page. +Below, you will find one or more examples of claiming each Output type. -## Examples of Stardust asset claim transactions +## Examples of Stardust Asset Claim Transactions -In the following, some examples of transactions for claiming the Stardust assets will be presented. Different commands in a [PTB](../iota-101/transactions/ptb/prog-txn-blocks.mdx) are used depending on the claiming scenario, that varies depending on the Stardust Output type and composition. +Here are some examples of transactions for claiming Stardust assets. +Different commands in a [PTB](../iota-101/transactions/ptb/prog-txn-blocks.mdx) are used depending on the claiming scenario, +which varies based on the Stardust Output type and composition. ### Basic Output @@ -33,12 +40,14 @@ Go to [Alias Output](claiming/alias.mdx). Go to [Foundry Output](claiming/foundry.mdx). -### Output unlockable by an Alias/Nft Address +### Output Unlockable by an Alias/Nft Address -Go to [Output unlockable by an Alias/Nft Address](claiming/address-unlock-condition.mdx). +Go to [Output Unlockable by an Alias/Nft Address](claiming/address-unlock-condition.mdx). -## Sponsoring your Shimmer claiming +## Sponsoring Your Shimmer Claiming -In the case in which some assets are owned by a Shimmer address that helds no IOTA tokens (needed to pay for gas), then a claiming can benefit by the process of self-sponsoring. This means that an address owning IOTA tokens can be used by the same user to sponsor a transaction claiming Shimmer assets. +If some assets are owned by a Shimmer address that holds no IOTA tokens (needed to pay for gas), +the claiming process can benefit from self-sponsorship. +This means that an address owning IOTA tokens can be used by the same user to sponsor a transaction claiming Shimmer assets. -Go to [Self-sponsor Shimmer Claimings](claiming/self-sponsor.mdx). \ No newline at end of file +Go to [Self-sponsor Shimmer Claims](claiming/self-sponsor.mdx). diff --git a/docs/content/developer/stardust/claiming/address-unlock-condition.mdx b/docs/content/developer/stardust/claiming/address-unlock-condition.mdx index f61a5f737fa..6cf7bde7bf7 100644 --- a/docs/content/developer/stardust/claiming/address-unlock-condition.mdx +++ b/docs/content/developer/stardust/claiming/address-unlock-condition.mdx @@ -1,66 +1,76 @@ --- - title: Claiming an Output unlockable by an Alias/Nft Address +description: A guide on how to claim Outputs Unlockable by an Alias/NFT Address in the Move-based IOTA ledger. --- +import MigrationWarning from '../../../_snippets/migration-warning.mdx'; -In Stardust outputs presented an Address Unlock Condition or similarly, in the case of the Alias Output, a [Governor Address Unlock Condition](https://github.com/iotaledger/tips/blob/main/tips/TIP-0018/tip-0018.md#governor-address-unlock-condition). In the new ledger, this mechanism is represented as an address owning the associated Output object. Most of the times the address is directly managed through a keypair by a user, but sometimes this address could represent another object. In this case, that object owns the interested Output object. Coming from the [Stardust migration](../migration-process.mdx#stardust-migration), only `Alias` and `Nft` objects can own other Output objects. +# Claiming an Output Unlockable by an Alias/NFT Address -## Claim of an Output owned by another Alias/Nft object + -For this example, we're using an `AliasOutput` to extract an `Alias` object that owns an `NftOutput`. +In Stardust, outputs had an Address Unlock Condition or, in the case of Alias Outputs, +a [Governor Address Unlock Condition](https://github.com/iotaledger/tips/blob/main/tips/TIP-0018/tip-0018.md#governor-address-unlock-condition). +In the new ledger, this mechanism is represented by an address owning the associated Output object. +Most of the time, the address is directly managed by a user through a keypair. +However, sometimes the address could represent another object. +In this case, that object owns the associated Output object. +After the [Stardust migration](../migration-process.mdx), only `Alias` and `Nft` objects can own other Output objects. -1. The first step is to fetch the `AliasOutput` object that is needed for claiming the `NftOutput`. +## Claiming an Output Owned by Another Alias/NFT Object - - +For this example, we use an `AliasOutput` to extract an `Alias` object that owns an `NftOutput`. + +1. The first step is to fetch the `AliasOutput` object that is needed to claim the `NftOutput`. + + + ```rust file=/docs/examples/rust/stardust/address-unlock-condition.rs#L70-L88 ``` - + -2. By using the dynamic field function with the "alias" dynamic field key filter, we gather the `Alias` object itself. +2. Use the dynamic field function with the "alias" dynamic field key filter to gather the `Alias` object itself. - - + + ```rust file=/docs/examples/rust/stardust/address-unlock-condition.rs#L90-L103 ``` - + -3. Some objects are owned by the `Alias` object. In this case we filter them by type using the `NftOutput` type tag. -Applying the filter to get `NftOutput`s owned by the `Alias`. +3. Some objects are owned by the `Alias` object. In this case, filter them by type using the `NftOutput` type tag. Apply the filter to get `NftOutput`s owned by the `Alias`. - - + + ```rust file=/docs/examples/rust/stardust/address-unlock-condition.rs#L105-L128 ``` - + -4. Create PTB that firstly extracts the assets from the `AliasOutput` and then it uses the extracted `Alias` to "address unlock" the `NftOutput` using the funсtion `unlock_alias_address_owned_nft`. +4. Create a PTB that first extracts the assets from the `AliasOutput`, and then uses the extracted `Alias` to "address unlock" the `NftOutput` using the function `unlock_alias_address_owned_nft`. - - + + ```rust file=/docs/examples/rust/stardust/address-unlock-condition.rs#L130-L239 ``` - + - \ No newline at end of file + diff --git a/docs/content/developer/stardust/claiming/alias.mdx b/docs/content/developer/stardust/claiming/alias.mdx index f5fc76a6b86..2c2016a2c34 100644 --- a/docs/content/developer/stardust/claiming/alias.mdx +++ b/docs/content/developer/stardust/claiming/alias.mdx @@ -1,75 +1,93 @@ --- - title: Claiming Alias Outputs +description: A guide on how to claim Alias Outputs in the Move-based IOTA ledger. --- -An address can own `AliasOutput` objects only if before the migration it was set as the Alias Governor Address. -In this case, the `AliasOutput` object is an owned object in the ledger and its owner is the Governor address. -Such address can be directly controlled by a user or by another object (either an `Alias` or `Nft` object). For the latter use case, check the [`Claiming an Output unlockable by an Alias/Nft Address`](address-unlock-condition.mdx) example. +import MigrationWarning from '../../../_snippets/migration-warning.mdx'; -## Claim of an Alias Output +# Claiming Alias Outputs + + + +An address can own `AliasOutput` objects only if it was set as the Alias Governor Address before the migration. +In this case, the `AliasOutput` object is an owned object in the ledger, and its owner is the Governor address. +This address can be directly controlled by a user or by another object (either an `Alias` or `Nft` object). +For the latter use case, +check the [`Claiming an Output Unlockable by an Alias/Nft Address`](address-unlock-condition.mdx) example. + +## Claim an Alias Output A Governor address can claim the `AliasOutput` assets at any time: -1. The first step is to fetch an `AliasOutput` object needed to be claimed. +### 1. Fetch the `AliasOutput` - - +The first step is to fetch the `AliasOutput` object that needs to be claimed. + + + ```rust file=/docs/examples/rust/stardust/alias-output-claim.rs#L56-L81 ``` - + + +Coming soon +### 2. Check the Native Token Balance -2. Then we check the native tokens that were possibly held by this output. -A [`Bag`](../../../references/framework/iota-framework/bag) is used for holding these tokens, so in this step we are interested in obtaining the dynamic field keys that are bag indexes. -In the case of the native tokens, the keys are strings representing the [`OTW`](../../iota-101/move-overview/one-time-witness.mdx) used for the native token declaration. +Next, check the native tokens that might be held by this output. A [`Bag`](../../../references/framework/iota-framework/bag.mdx) is used for holding these tokens. In this step, we are interested in obtaining the dynamic field keys that are bag indexes. For native tokens, the keys are strings representing the [`OTW`](../../iota-101/iota-move-concepts/one-time-witness.mdx) used for the native token declaration. - - + + + ```rust file=/docs/examples/rust/stardust/alias-output-claim.rs#L83-L110 ``` - + + +Coming soon -3. Finally, a PTB can be created using the `alias_output_object_ref` as input and the native token keys. -An `AliasOutput` is different from an `NftOutput` or a `BasicOutput` as it contains the `Alias` object. -In fact, the main purpose of claiming is extracting the `Alias` object from the `AliasOutput`. +### 3. Create the PTB - - +Finally, create a [Programmable Transaction Block (PTB)](../../iota-101/transactions/ptb/building-ptb.mdx) +using the `alias_output_object_ref` as input along with the native token keys. +An `AliasOutput` differs from an `NftOutput` or a `BasicOutput` because it contains the `Alias` object. +The main purpose of claiming is to extract the `Alias` object from the `AliasOutput`. + + + ```rust file=/docs/examples/rust/stardust/alias-output-claim.rs#L112-L180 ``` - + -## Conversion of an Alias Output into a custom Object +## Convert an Alias Output into a Custom Object -We need to have a custom package prepared that contains a logic for converting an `Alias` into a new entity usable for your project. +To convert an `Alias` into a new entity usable for your project, +you need to have a custom package prepared with the necessary logic. -In Stardust, an alias can be used for different purposes. One of them is acting as an NFT collection controller. -In the following, an example of the process of converting a Stardust `Alias` into a `CollectionControllerCap` is outlined. +In Stardust, an alias can serve various purposes, such as acting as an NFT collection controller. +The following example outlines the process of converting a Stardust `Alias` into a `CollectionControllerCap`. -The following example extends the one described in the [Conversion of an Nft Output into a custom Nft](nft.mdx#conversion-of-an-nft-output-into-a-custom-nft) documentation: +This example extends the one described in the [Conversion of an Nft Output into a Custom Nft](nft.mdx#converting-an-nft-output-into-a-custom-nft) documentation: - + -The `collection.move` module extends the `custom_nft` package to make it possible to work with NFT collections: +The `collection.move` module extends the `custom_nft` package to enable working with NFT collections: ```move file=/docs/examples/move/custom_nft/sources/collection.move ``` @@ -83,18 +101,16 @@ Also, the `nft.move` module was extended with the following function: -Once the package is prepared, we can extract and use a Stardust `Alias` in a single transaction to create a `CollectionControllerCap`. -This capability is then used in later transactions for managing new collections. +Once the package is prepared, you can extract and use a Stardust `Alias` in a single transaction to create a `CollectionControllerCap`. This capability is then used in later transactions to manage new collections. - - + + ```rust file=/docs/examples/rust/stardust/alias-migration.rs#L119-L244 ``` - + - diff --git a/docs/content/developer/stardust/claiming/basic.mdx b/docs/content/developer/stardust/claiming/basic.mdx index b3899fcdbad..f2237afd53e 100644 --- a/docs/content/developer/stardust/claiming/basic.mdx +++ b/docs/content/developer/stardust/claiming/basic.mdx @@ -1,71 +1,99 @@ --- - title: Claiming Basic Outputs +description: A guide on how to claim Basic Outputs in Move by assessing and unlocking owned objects. --- -An address can own `BasicOutput` objects that needs to be unlocked. In this case, some off-chain queries can be used to check the unlock conditions of the `BasicOutput` and assess if it can be unlocked. +import MigrationWarning from '../../../_snippets/migration-warning.mdx'; - - +# Claiming Basic Outputs + + + +:::info Claiming might not be needed + +Most basic outputs have no special unlock conditions and don't need to be claimed. They will simply be available as normal `Coin` objects for your account with no further action required. Manual claiming is only needed if special unlock conditions like unexpired timelocks apply. + +::: + +As a user, you may own `BasicOutput` objects that need to be unlocked before you can claim them. This guide walks you through the process of evaluating the unlock conditions for a `BasicOutput` and the steps to claim the associated assets. + +## Assessing Unlock Conditions + +To begin, you need to determine if your `BasicOutput` can be unlocked. You can achieve this by performing specific off-chain queries that will check the unlock conditions for the `BasicOutput`. + + + ```rust file=/docs/examples/rust/stardust/check-basic-output-unlock-conditions.rs#L20-L56 ``` - + -TODO +Coming soon -## Claim of a Basic Output -Once a Basic Output can be unlocked the claim of its assets can start +## Claim a Basic Output + +Once you've confirmed that the `BasicOutput` can be unlocked, you can start the process of claiming its assets. -1. The first step is to fetch the `BasicOutput` object that needs to be claimed. +### 1. Retrieve the `BasicOutput` - - +The first step is to fetch the `BasicOutput` object that you intend to claim. + + + ```rust file=/docs/examples/rust/stardust/basic-output-claim.rs#L56-L81 ``` - + -TODO +Coming soon +### 2. Check the Native Token Balance + +After fetching the `BasicOutput`, you need to check for any native tokens that might be stored within it. +These tokens are typically stored in a [`Bag`](../../../references/framework/iota-framework/bag.mdx). +You'll need to obtain the dynamic field keys used as bag indexes to access the native tokens. +For native tokens, +these keys are strings representing the [`OTW`](../../iota-101/iota-move-concepts/one-time-witness.mdx) used for the native token [`Coin`](../../../references/framework/iota-framework/coin.mdx#resource-coin). -2. Then we check the native tokens that were possibly held by this output. A [`Bag`](../../../references/framework/iota-framework/bag) is used for holding these tokens, so in this step we are interested in obtaining the dynamic field keys that are used as bag index. In the case of the native tokens `Bag` the keys are strings representing the [`OTW`](../../iota-101/move-overview/one-time-witness.mdx) used for the native token [`Coin`](../../../references/framework/iota-framework/coin.mdx#resource-coin). - - + + ```rust file=/docs/examples/rust/stardust/basic-output-claim.rs#L83-L110 ``` - + -TODO +Coming soon -3. Finally, a PTB can be created using the `basic_output` as input and the `Bag` keys for iterating the native tokens extracted. +### 3. Construct the PTB + +Finally, you can create a Programmable Transaction Block (PTB) using the `basic_output` as an input, +along with the `Bag` keys to iterate over the extracted native tokens. - - + + ```rust file=/docs/examples/rust/stardust/basic-output-claim.rs#L113-L177 ``` - + -TODO +Coming soon - + \ No newline at end of file diff --git a/docs/content/developer/stardust/claiming/foundry.mdx b/docs/content/developer/stardust/claiming/foundry.mdx index 6f0d3e4b43e..55d68cc4feb 100644 --- a/docs/content/developer/stardust/claiming/foundry.mdx +++ b/docs/content/developer/stardust/claiming/foundry.mdx @@ -1,79 +1,104 @@ --- - title: Claiming Foundry Outputs +description: A guide to claiming Foundry Outputs by extracting the CoinManagerTreasuryCap from an AliasOutput in the Move-based IOTA ledger. --- +import MigrationWarning from '../../../_snippets/migration-warning.mdx'; -As seen in the [Move Models](../move-models) page, the Foundry Output does not have a direct representation in Move. So claiming a Foundry Output actually means claiming a [`CoinManagerTreasuryCap`](../../../references/framework/iota-framework/coin_manager.mdx#resource-coinmanagertreasurycap) extracted from the [`AliasOutput`](../../../references/framework/stardust/alias_output#resource-aliasoutput) originally controlling the Foundry in Stardust. This capability can be used to manage the supply of the [`Coin`](../../../references/framework/iota-framework/coin.mdx#resource-coin) created during the migration to represent the native token controlled by the Foundry. - -## Claim of a Foundry Output +# Claiming Foundry Outputs -1. The first step is to fetch an `AliasOutput` object that needs to be claimed. + - - +In the Move-based IOTA ledger, Foundry Outputs don't have a direct equivalent representation. +Instead, claiming a Foundry Output involves extracting a [`CoinManagerTreasuryCap`](../../../references/framework/iota-framework/coin_manager.mdx#resource-coinmanagertreasurycap) from the [`AliasOutput`](../../../references/framework/stardust/alias_output#resource-aliasoutput) that originally controlled the Foundry in Stardust. This capability allows you to manage the supply of the [`Coin`](../../../references/framework/iota-framework/coin.mdx#resource-coin) created during migration to represent the native token controlled by the Foundry. + +## Steps to Claim a Foundry Output + +### 1. Fetch the `AliasOutput` + +The first step is to retrieve the `AliasOutput` object that you intend to claim. + + + ```rust file=/docs/examples/rust/stardust/foundry-output-claim.rs#L60-L74 ``` - + + +Coming soon +### 2. Gather the `Alias` Object -2. By using the dynamic field function with the "alias" dynamic field key filter, we gather the `Alias` object itself. +Next, use the dynamic field function with the "alias" dynamic field key filter to obtain the `Alias` object itself. - - + + ```rust file=/docs/examples/rust/stardust/foundry-output-claim.rs#L76-L89 ``` - + + +Coming soon -3. Some objects are owned by the `Alias` object (check the [Output unlockable by an Alias/Nft Address](address-unlock-condition.mdx) page for more info). In this case we filter them by type using the `CoinManagerTreasuryCap` type tag. +### 3. Filter Owned Objects by Type + +The `Alias` object may own various other objects (for more details, refer to the [Output Unlockable by an Alias/Nft Address](address-unlock-condition.mdx) page). In this step, you filter these objects by type, specifically looking for the `CoinManagerTreasuryCap` type. - - + + ```rust file=/docs/examples/rust/stardust/foundry-output-claim.rs#L91-L131 ``` - + + +Coming soon -4. Since each native token has its own package, a Foundry's native token as a dedicated [`OTW`](../../iota-101/move-overview/one-time-witness.mdx). Here we need to extract this `OTW` from the `CoinManagerTreasuryCap` object. +### 4. Extract the One-Time Witness (OTW) + +Since each native token is tied to its own package, a Foundry's native token has a specific [`OTW`](../../iota-101/iota-move-concepts/one-time-witness.mdx). Here, you will extract the `OTW` from the `CoinManagerTreasuryCap` object. - - + + ```rust file=/docs/examples/rust/stardust/foundry-output-claim.rs#L133-L142 ``` - + + +Coming soon -5. Create a PTB that claims the `CoinManagerTreasuryCap` related to the Foundry Output from the `AliasOutput` using the `unlock_alias_address_owned_coinmanager_treasury` function. +### 5. Create the PTB to Claim the `CoinManagerTreasuryCap` +Finally, you should create a Programmable Transaction Block (PTB) that claims the `CoinManagerTreasuryCap` associated with the Foundry Output from the `AliasOutput` using the `unlock_alias_address_owned_coinmanager_treasury` function. - - + + ```rust file=/docs/examples/rust/stardust/foundry-output-claim.rs#L144-L215 ``` - + + +Coming soon - \ No newline at end of file + + diff --git a/docs/content/developer/stardust/claiming/nft.mdx b/docs/content/developer/stardust/claiming/nft.mdx index 1bb5ab850f7..c481bb754d5 100644 --- a/docs/content/developer/stardust/claiming/nft.mdx +++ b/docs/content/developer/stardust/claiming/nft.mdx @@ -1,88 +1,123 @@ --- - title: Claiming Nft Outputs +description: A guide on how to claim and convert NFT Outputs in the Move-based IOTA ledger. --- -An address can own `NftOutput` objects that needs to be unlocked. -In this case, some off-chain queries can be used to check the unlock conditions of the `NftOutput` and assess if it can be unlocked. -Check the example above, as it works the same as the [`Basic Output`](basic.mdx). - -## Claim of an Nft Output -Once an Nft Output can be unlocked the claim of its assets can start +import MigrationWarning from '../../../_snippets/migration-warning.mdx'; -1. The first step is to fetch the `NftOutput` object that needs to be claimed. +# Claiming NFT Outputs - - + + +As an owner of `NftOutput` objects, you may need to unlock these assets before you can claim them. +This guide will help you understand how to evaluate the unlock conditions for an `NftOutput` and proceed with claiming the associated NFT. + +## Evaluating Unlock Conditions + +To start, you must determine whether your `NftOutput` can be unlocked. +This involves using off-chain queries to check the unlock conditions, +similar to the process for [`Basic Outputs`](basic.mdx). + +## Steps to Claim an NFT Output + +### 1. Fetch the `NftOutput` + +The first step in claiming your NFT is to retrieve the `NftOutput` object that you intend to claim. + + + ```rust file=/docs/examples/rust/stardust/nft-output-claim.rs#L56-L80 ``` - + + +Coming soon +### 2. Verify the Native Token Balance + +After fetching the `NftOutput`, you need to check for any native tokens that might be held by this output. +These tokens are stored in a [`Bag`](../../../references/framework/iota-framework/bag). +You'll need to obtain the dynamic field keys used as bag indexes to access the native tokens. +For native tokens, these keys are strings +representing the [`OTW`](../../iota-101/iota-move-concepts/one-time-witness.mdx) used for the native token +[`Coin`](../../../references/framework/iota-framework/coin.mdx#resource-coin). -2. Then we check the native tokens that were possibly held by this output. A [`Bag`](../../../references/framework/iota-framework/bag) is used for holding these tokens, so in this step we are interested in obtaining the dynamic field keys that are used as bag index. In the case of the native tokens `Bag` the keys are strings representing the [`OTW`](../../iota-101/move-overview/one-time-witness.mdx) used for the native token [`Coin`](../../../references/framework/iota-framework/coin.mdx#resource-coin). - - + + ```rust file=/docs/examples/rust/stardust/nft-output-claim.rs#L82-L107 ``` - + + +Coming soon -3. Finally, a PTB can be created using the `nft_output` as input and the `Bag` keys for iterating the native tokens extracted. -An Nft Output is different from a Basic Output as it contains the `Nft` object. -In fact, the main purpose of claiming is extracting the `Nft` object from the `NftOutput`. +### 3. Create the PTB + +Finally, +you can create a [Programmable Transaction Block (PTB)](../../iota-101/transactions/ptb/building-ptb.mdx) using the `nft_output` as an input, +along with the `Bag` keys to iterate over the extracted native tokens. +The primary goal of this process is to extract the `Nft` object from the `NftOutput`. - - + + ```rust file=/docs/examples/rust/stardust/nft-output-claim.rs#L109-L175 ``` - + + +Coming soon -## Conversion of an Nft Output into a custom Nft -This topic outlines the process of converting an stardust Nft into a custom Nft. +## Converting an Nft Output into a Custom Nft + +Once you've claimed the `Nft`, you may want to convert it into a custom NFT. +This section outlines the process of transforming a Stardust `Nft` into a custom NFT tailored to your specific needs. -You need to have a prepared custom Nft package that you want to convert the Stardust Nft You need to have a prepared custom Nft package that you want to convert the Stardust Nft into. -The following is an example of a simple module for representing a custom NFT, minting it, burning it and converting it from a Stardust `Nft`: +### Preparing a Custom Nft Package - +Before proceeding with the conversion, ensure you have a prepared custom NFT package. +This package will represent the custom NFT. +The following is an example of a simple module for representing, minting, burning, +and converting the custom NFT from the Stardust `Nft`. + + ```move file=/docs/examples/move/custom_nft/sources/nft.move ``` - +### Creating the PTB for Conversion -Create a PTB that extracts the Stardust `Nft` from an `NftOutput` and then converts it into a custom NFT of the collection just published. -This conversion method extracts the Stardust `Nft` metadata and uses it for minting a new NFT. +You can then create a PTB that extracts the Stardust `Nft` from an `NftOutput` and converts it into a custom NFT within your collection. +This method uses the metadata from the Stardust `Nft` to mint a new NFT. - - + + ```rust file=/docs/examples/rust/stardust/nft-migration.rs#L77-L137 ``` - + + +Coming soon - diff --git a/docs/content/developer/stardust/claiming/self-sponsor.mdx b/docs/content/developer/stardust/claiming/self-sponsor.mdx index 8ecd7374180..9e50ecb61bf 100644 --- a/docs/content/developer/stardust/claiming/self-sponsor.mdx +++ b/docs/content/developer/stardust/claiming/self-sponsor.mdx @@ -1,59 +1,76 @@ --- - title: Self-sponsoring Shimmer Assets Claiming +description: A guide to claiming Shimmer assets using self-sponsorship when the address lacks IOTA coins for transaction fees. --- -In the case in which an address owns some assets but no IOTA coins, the self-sponsorship can be of help for claiming those coins. -[Sponsoring a transaction](../../iota-101/transactions/sponsored-transactions) means having an IOTA address (i.e., the sponsor) to pay the transaction gas fees for another address (i.e., the user). In the case of a claim a sponsor can pay for the claiming transaction gas. +import MigrationWarning from '../../../_snippets/migration-warning.mdx'; -This is useful for Shimmer assets, because none of the Move objects obtained from migrating the Shimmer Stardust Outputs contain any IOTA coin. It means that addresses owning these Objects have no IOTA coins to pay for gas. +# Self-Sponsoring Shimmer Assets Claims -## Claim of a Shimmer Basic Output with self-sponsorship + -1. A Shimmer derivation path uses a `coin_type` (4219) which is different from the IOTA's one (4218). A user's self-sponsoring address could be then found using the IOTA `coin_type`. +If you own Shimmer assets but don't have any IOTA coins to cover transaction fees, +self-sponsorship can help you claim those assets. +In this process, a sponsor (an IOTA address) pays the transaction gas fees for another address (the user). +When claiming assets, a sponsor can cover the gas fees required for the transaction. - - +This is particularly useful for Shimmer assets because the Move objects derived from Shimmer Stardust Outputs don't contain IOTA coins. +As a result, addresses holding these objects lack the IOTA coins necessary to pay for gas. + +## Claim a Shimmer Basic Output with Self-Sponsorship + +### 1. Identify the Self-Sponsoring Address + +Shimmer uses a different `coin_type` (4219) than IOTA (4218). +To find the self-sponsoring address, use the IOTA `coin_type`. + + + ```rust file=/docs/examples/rust/stardust/shimmer-self-sponsor.rs#L44-L50 ``` - + -TODO +Coming soon +### 2. Create the PTB for Claiming -2. A PTB for claiming a `BasicOutput` owned by the derived Shimmer address can be created similarly to what is shown in [Basic Output](basic.mdx). +Next, create a [Programmable Transaction Block (PTB)](../../iota-101/transactions/ptb/building-ptb.mdx) +to claim a `BasicOutput` owned by the derived Shimmer address. +This process is similar to the one outlined in the [Basic Output](basic.mdx) guide. - - + + ```rust file=/docs/examples/rust/stardust/shimmer-self-sponsor.rs#L85-L135 ``` - + -TODO +Coming soon -3. In this case, the transaction must be signed by both the sender address (i.e., the objects' owner) and the sponsor address. +### 3. Sign the Transaction + +For this transaction, both the sender address (the object's owner) and the sponsor address must sign the transaction. - - + + ```rust file=/docs/examples/rust/stardust/shimmer-self-sponsor.rs#L151-L177 ``` - + -TODO +Coming soon - \ No newline at end of file + diff --git a/docs/content/developer/stardust/exchanges.mdx b/docs/content/developer/stardust/exchanges.mdx index e90107ddd52..d5f1cba2f13 100644 --- a/docs/content/developer/stardust/exchanges.mdx +++ b/docs/content/developer/stardust/exchanges.mdx @@ -1,20 +1,21 @@ --- -title: Exchange and Custody Providers Migration sidebar_label: Exchanges & Custody Providers -description: Relevant information for exchanges and custody providers that want to migrate to the new Move based IOTA network. +description: Relevant information for exchanges and custody providers that want to migrate to the new Move-based IOTA network. --- +# Exchange and Custody Providers Migration + In 2024, the IOTA Foundation made the strategic decision to replace the existing Stardust protocol with a completely new technology stack based on the Move programming model. This fast-tracks IOTA to have programmability on the base layer (not just Layer-2 chains) without needing several additional breaking releases in between working towards that milestone. This is the biggest change ever happening to the IOTA technology stack, which has implications for integrators like exchanges and custody providers: - Most concepts from IOTA Stardust will be replaced by new concepts. - All APIs and SDKs will be replaced as well; existing IOTA integrations will have to be replaced completely. -- The relevant current network state, including token and NFT balances, will be available on the new network with your existing private keys from the start - no manual migration steps besides integration are needed for this. -- Existing addresses will remain the same in their hex format. However, the Bech32 human-readable format (identified by the `iota1` prefix) will no longer be available -- With programmability, IOTA will no longer be fee-less; a small execution fee will be charged for interactions given there is no difference between a transfer and another smart contract execution. +- The relevant current network state, including token and NFT balances, will be available on the new network with your existing private keys from the start — no manual migration steps besides integration are needed for this. +- Existing addresses will remain the same in their hex format. However, the Bech32 human-readable format (identified by the `iota1` prefix) will no longer be available. +- With programmability, IOTA will no longer be fee-less; a small execution fee will be charged for interactions, given there is no difference between a transfer and another smart contract execution. - IOTA will include staking; the rewards will in most cases offset transaction fees for any staking token holders. -- The Firefly wallet currently used by end-users will not support the new protocol, instead a browser extension wallet will be offered. -- The amount of decimals for the IOTA token will change to 9, for the SMR token it will remain at 6 decimals. -- Integration is similar to other Move based protocols; integration concepts could potentially partially be re-used from those integrations. +- The Firefly wallet currently used by end-users will not support the new protocol; instead, a browser extension wallet will be offered. +- The number of decimals for the IOTA token will change to 9, while for the SMR token it will remain at 6 decimals. +- Integration is similar to other Move-based protocols; integration concepts could potentially partially be re-used from those integrations. This guide will take you through the process of migrating from your current IOTA integration to a new one that is compatible with the latest version of the network and technology stack. @@ -22,9 +23,11 @@ This guide will take you through the process of migrating from your current IOTA :::warning -Once the new network goes live, the old network will be shut down immediately. It will no longer be possible to interact with it. To minimize any impact on your customer base regarding withdrawals and deposits for the IOTA and SMR tokens, it's crucial that the new integration is available at that time. +Once the new network goes live, the old network will be shut down immediately. +It will no longer be possible to interact with it. +To minimize any impact on your customer base regarding withdrawals and deposits for the IOTA and SMR tokens, it's crucial that the new integration is available at that time. -::: +::: With the new network, we are moving away from the UTXO model (which offers limited functionality) towards a fully programmable [object-based](../iota-101/objects/object-model.mdx) representation of assets. No assets will be lost, and functionality will be inherited, but interaction with those assets will be different from how it used to work. @@ -38,60 +41,73 @@ The most common use case for exchanges and custody providers regarding integrati - All `Coin` objects can be freely transferred by the owner of this object. - Only the owner of the `Coin` object can interact with it. -- The only restriction that can be added to a `Coin` object is the optional blocking of transfers for addresses on a [`DenyList`](../iota-101/create-coin/regulated.mdx#deny-list). This only applies to `Coin` objects that have been instantiated as [Regulated Coins](../standards/coin.mdx#regulated-coins). -* It is not possible to add other limiting functionality to `Coin` objects directly, like vesting or time-locks; this can only be done by wrapping the unrestricted `Coin` object within another restricting object. It's safe to assume that if you receive a `Coin` object, you can use it without limitations. -- A `Coin` is tied to a `CoinMetadata` object containing `name`, `symbol`, `decimals`, `description`, and an `icon_url` -- The holder of the TreasuryCap handles administrative tasks of a Coin like minting new tokens or changing metadata; Without a `TreasuryCap` these actions can no longer be performed. -- All `Coin` based tokens work in the same way, integrate once, and use for any other `Coin` used on the network without the need for modifications or exceptions. Unlike with ERC-20, tokens functionality on `Coin` objects can not be modified. +- The only restriction that can be added to a `Coin` object is the optional blocking of transfers for addresses on a [`DenyList`](../iota-101/create-coin/regulated.mdx#denylist). This only applies to `Coin` objects that have been instantiated as [Regulated Coins](../standards/coin.mdx#regulated-coins). +- It is not possible to add other limiting functionality to `Coin` objects directly, like vesting or time-locks; this can only be done by wrapping the unrestricted `Coin` object within another restricting object. It's safe to assume that if you receive a `Coin` object, you can use it without limitations. +- A `Coin` is tied to a `CoinMetadata` object containing `name`, `symbol`, `decimals`, `description`, and an `icon_url`. +- The holder of the TreasuryCap handles administrative tasks of a Coin like minting new tokens or changing metadata; without a `TreasuryCap` these actions can no longer be performed. +- All `Coin`-based tokens work in the same way—integrate once, and use for any other `Coin` used on the network without the need for modifications or exceptions. Unlike with ERC-20, tokens functionality on `Coin` objects cannot be modified. #### Supporting IOTA tokens All IOTA tokens will automatically be available on the new network, represented as `Coin` objects, or, if limitations are imposed on that coin like a time-lock, as a `Coin` wrapped inside a limiting other object. We highly encourage only accepting `Coin` objects for the IOTA token to simplify integration, given there are assurances that `Coin` objects can be freely transferred and only accessed by the holder of that `Coin` object. `Coin` is a normal `Coin` implementation and not a Regulated Coin, so it should always be transferable by the holder of the Coin object. -Given that the key derivation and addresses remain the same as those of the IOTA Stardust network, existing key pairs can still be used on the new network. All balances will remain on the same addresses but represented as a `Coin` object instead of a `BasicOutput` UTXO. What does change is the address representation. In IOTA Stardust, we had a hex-format address representation and a Bech32 human-readably representation of the address. In the new version, we only use the hex-format address and no longer support the addresses starting with `iota1` in Bech32 format. For address input and deposit address generation, the new integration must ensure that the addresses are presented in hex format. +Given that the key derivation and addresses remain the same as those of the IOTA Stardust network, existing key pairs can still be used on the new network. +All balances will remain on the same addresses but represented as a `Coin` object instead of a `BasicOutput` UTXO. +What does change is the address representation. +In IOTA Stardust, we had a hex-format address representation and a Bech32 human-readable representation of the address. +In the new version, we only use the hex-format address and no longer support the addresses starting with `iota1` in Bech32 format. +For address input and deposit address generation, the new integration must ensure that the addresses are presented in hex format. For IOTA, token integration can be as simple as generating deposit addresses, monitoring those addresses for incoming `Coin` objects, crediting balances once a `Coin` object has been received and finalized, and allowing withdrawals. Further integration depends on the needs and could include features like automatically collecting incoming balances and having incoming deposits handled by a smart contract instead. :::warning IOTA Decimals - -This release changes the number of decimals IOTA uses. Please take this into account with your implementation. IOTA had 6 decimals before; now it's 9. - + +This release changes the number of decimals IOTA uses. Please take this into account with your implementation. IOTA had 6 decimals before; now it's 9. + ::: :::info IOTA Gas - -IOTA is the token used for GAS on the IOTA network, small amounts of IOTA will be needed to pay for execution of functionality on the network. + +IOTA is the token used for GAS on the IOTA network; small amounts of IOTA will be needed to pay for the execution of functionality on the network. ::: #### Supporting SMR tokens -Shimmer used to be a separate network, but this no longer holds since this upgrade. The Shimmer EVM Layer-2 chain will be anchored into IOTA directly, and the SMR token will also be on IOTA. Like IOTA, SMR will also be available without requiring a manual migration from the start. However, the token will now reside on the IOTA Network directly and can be accessed with your existing Shimmer key pairs on the hex addresses you had before. +Shimmer used to be a separate network, but this no longer holds since this upgrade. +The Shimmer EVM Layer-2 chain will be anchored into IOTA directly, and the SMR token will also be on IOTA. +Like IOTA, SMR will also be available without requiring a manual migration from the start. +However, the token will now reside on the IOTA Network directly and can be accessed with your existing Shimmer key pairs on the hex addresses you had before. -Integration is the same as with IOTA; all accessible and transferable SMR tokens are available as `Coin` objects. +Integration is the same as with IOTA; all accessible and transferable SMR tokens are available as `Coin` objects. :::info SMR Decimals - + Unlike IOTA the amount of decimals for SMR remains the same, 6. ::: :::info SMR GAS - -Gas fees to interact with SMR tokens are paid in IOTA, like any other interaction on the network. To deal with SMR tokens you will need some IOTA to pay for these execution fees as well. + +Gas fees to interact with SMR tokens are paid in IOTA, like any other interaction on the network. +To deal with SMR tokens, you will need some IOTA to pay for these execution fees as well. ::: #### Supporting other tokens -Native assets, both new and existing assets from the IOTA and Shimmer networks, are represented as `Coin` objects and work similarly and can re-use the same integration. +Native assets, both new and existing assets from the IOTA and Shimmer networks, are represented as `Coin` objects and work similarly and can re-use the same integration. :::info Custom Token Gas - -Gas fees to interact with custom tokens are paid in IOTA, like any other interaction on the network. To deal with these tokens you will need some IOTA to pay for these execution fees as well. + +Gas fees to interact with custom tokens are paid in IOTA, like any other interaction on the network. +To deal with these tokens, you will need some IOTA to pay for these execution fees as well. ::: #### Integration -Depending on your preferences, you can integrate your exchange in multiple ways. You can go from a low-level implementation to directly talking to a node's RPC server or use one of our [SDKs](../../references/iota-sdks) (the official TypeScript or Rust SDK is recommended). For details on how to integrate, please check out the [Exchange Integration Guide](../exchange-integration/exchange-integration.mdx). \ No newline at end of file +Depending on your preferences, you can integrate your exchange in multiple ways. +You can go from a low-level implementation directly talking to a node's RPC server +or use one of our [SDKs](../../references/iota-sdks) (the official TypeScript or Rust SDK is recommended). +For details on how to integrate, please check out the [Exchange Integration Guide](../exchange-integration/exchange-integration.mdx). diff --git a/docs/content/developer/stardust/migration-process.mdx b/docs/content/developer/stardust/migration-process.mdx index 65849b79f6f..5ff847f02a1 100644 --- a/docs/content/developer/stardust/migration-process.mdx +++ b/docs/content/developer/stardust/migration-process.mdx @@ -2,29 +2,25 @@ title: Migration Process description: Explains how IOTA and Shimmer assets are handled during migration --- +import MigrationWarning from '../../_snippets/migration-warning.mdx'; + + :::note Edge Cases -This guide doesn't describe every possible edge case. For that, please check out the code, which -is part of a subdirectory in the -[`iota-genesis-builder`](https://github.com/iotaledger/iota/tree/develop/crates/iota-genesis-builder/src/stardust) -crate. This document will give a high to mid-level overview of the migration process. +This guide doesn't describe every possible edge case. +For that, please check out the code, +which is part of a subdirectory in the [`iota-genesis-builder`](https://github.com/iotaledger/iota/tree/develop/crates/iota-genesis-builder/src/stardust) crate. +This document will give a high to mid-level overview of the migration process. ::: ## Design Principles -- The migration aims to move away from the Stardust-based ledger concepts and transform assets into their pure -object-based Move representation. After completing the migration flow, users should see move assets that semantically -resemble the former Stardust assets in their wallet. -- Stardust Assets on the legacy ledger level are encapsulated in Outputs. An asset is semantically a valuable resource, -while an output is a container with spending rules that holds the valuable resource. -- We aim to mimic this hierarchy between assets and their containers in the genesis move ledger state, that is, to -ensure that spending conditions still hold. Once the containers are unlocked and destroyed during a user-initiated -claiming/migration transaction, the encapsulated assets will be extracted and sent to the user address and the move -containers will be destroyed. -- We intentionally do not include constructors in move for such containers, as we want to discourage their use after the -migration. They will only be created in the genesis ledger state via the migration script. +- The migration aims to move away from the Stardust-based ledger concepts and transform assets into their pure object-based Move representation. After completing the migration flow, users should see Move assets that semantically resemble the former Stardust assets in their wallet. +- Stardust Assets on the legacy ledger level are encapsulated in Outputs. An asset is semantically a valuable resource, while an output is a container with spending rules that holds the valuable resource. +- We aim to mimic this hierarchy between assets and their containers in the genesis Move ledger state, ensuring that spending conditions still hold. Once the containers are unlocked and destroyed during a user-initiated claiming/migration transaction, the encapsulated assets will be extracted and sent to the user address, and the Move containers will be destroyed. +- We intentionally do not include constructors in Move for such containers, as we want to discourage their use after the migration. They will only be created in the genesis ledger state via the migration script. ## Foundry Outputs & Native Tokens @@ -33,7 +29,7 @@ are established ways for these operations, in particular using [`Coin`](../../references/framework/iota-framework/coin.mdx#resource-coin) and [`TreasuryCap`](../../references/framework/iota-framework/coin.mdx#resource-treasurycap). The two main goals of the foundry migration are to convert it to a [`CoinManager`](../../references/framework/iota-framework/coin_manager.mdx), -a type introduced in the Move IOTA framework in order to simplify working with the `TreasuryCap`, and to a `Coin` +a type introduced in the Move IOTA framework simplify working with the `TreasuryCap`, and to a `Coin` to hold the IOTA tokens of the foundry itself. A unique coin type, `Coin,` is represented by the one-time witness `XYZ` defined in its own package. Therefore, a @@ -43,15 +39,15 @@ operations. To that end, a is populated with the native token's metadata, e.g., its symbol, circulating supply, and description, as well as any other metadata. -To collect this metadata, the foundry output's IRC-30 Metadata is extracted. In the majority of cases, this is possible. -However, for example, if the metadata does not follow the IRC-30 standard or the symbol of the token is not a valid move +To collect this metadata, the foundry output's IRC-30 Metadata is extracted. In most cases, this is possible. +However, for example, if the metadata does not follow the IRC-30 standard or the symbol of the token is not a valid Move identifier (e.g., containing UTF-8 characters), a random identifier for the token package is generated, and the metadata -uses generic defaults. As much as possible, though, the migration attempts to do as little modifications to the UTXO as +uses generic defaults. As much as possible, though, the migration attempts to do as little modification to the UTXO as possible. The package template is filled with the extracted data, compiled, and published. The result of the foundry migration is the following: -- A package representing the native token, in particular containing a one-time witness representing the unique type of +- A package representing the native token, particularly containing a one-time witness representing the unique type of the native token (to be used as `Coin`; abbreviated in the rest of this document). - A `CoinManager` and [`CoinManagerTreasuryCap`](../../references/framework/iota-framework/coin_manager.mdx#resource-coinmanagertreasurycap) object, the latter of which is owned by the address of the alias that @@ -62,7 +58,7 @@ by the `0x0` address. owned the original foundry. After this process, the minted coin sits on the `0x0` address with the entire minted supply. When other output types are -migrated that contain a balance of _this_ native token, then that balance is split off of the minted coin into a new +migrated that contain a balance of _this_ native token, that balance is split off of the minted coin into a new `Coin` object, which is then owned by the migrated output. If, by the end of this process, a non-zero balance remains on the minted coin, it is left at the zero address. This means they were burned in Stardust and, therefore, are effectively also burned on the Move ledger, as no one controls the `0x0` address. @@ -160,8 +156,7 @@ Other noteworthy points: - The `NftOutput` object has a freshly generated `UID` while the `Nft` has its `UID` set to the `Nft ID` of the Stardust output. If the `Nft ID` was zeroed in the Stardust output, it is computed according to the protocol rules from [TIP-18](https://github.com/iotaledger/tips/blob/main/tips/TIP-0018/tip-0018.md) and then set. Hence, no `Nft` object in Move has a zeroed `UID`. -- The `Nft` move object contains an `Irc27Metadata` object. It is extracted from the immutable metadata of the Stardust +- The `Nft` Move object contains an `Irc27Metadata` object. It is extracted from the immutable metadata of the Stardust NFT, if possible. If the Stardust NFT does not have valid IRC-27 metadata, it is migrated on a best-effort basis. -You can examine the `convert_immutable_metadata` function in the migration code for more -details. +You can examine the `convert_immutable_metadata` function in the migration code for more details. diff --git a/docs/content/developer/stardust/move-models.mdx b/docs/content/developer/stardust/move-models.mdx index 20c3ca31f11..a4fd1171edc 100644 --- a/docs/content/developer/stardust/move-models.mdx +++ b/docs/content/developer/stardust/move-models.mdx @@ -2,7 +2,9 @@ title: Stardust Move Models description: Describes how stardust assets are represented in the object-based Move ledger. --- +import MigrationWarning from '../../_snippets/migration-warning.mdx'; + This document describes what move models the Stardust UTXOs are migrated to in the Move-based ledger in IOTA Rebased. First, the Stardust Move Package is discussed that emulates the legacy UTXO models in object-based move. @@ -160,7 +162,6 @@ foundry controllers. The Stardust Move Package preserves the Alias concept and models it as a separate object in the move ledger: [`Alias`](../../references/framework/stardust/alias.mdx#resource-alias). Applications that use aliases (ISC, DID, token issuer) can implement their own move models where the `Alias` asset migrated from Stardust is required to initialize the new object. -A more detailed description on the process can be found in [Advanced Topics](./advanced.mdx). The unique `AliasID` of the Stardust asset is persisted as the `ObjectID` of the migrated `Alias` object. All assets and outputs that were owned by the `Alias Address` in Stardust are now owned by the `Alias` object in move. There is a special [receiving diff --git a/docs/content/developer/stardust/stardust-migration.mdx b/docs/content/developer/stardust/stardust-migration.mdx index 14bf3415796..c3bb0018713 100644 --- a/docs/content/developer/stardust/stardust-migration.mdx +++ b/docs/content/developer/stardust/stardust-migration.mdx @@ -1,9 +1,13 @@ --- -title: Stardust Migration description: Describes the migration from IOTA Stardust to the IOTA Move-based ledger. --- +import MigrationWarning from '../../_snippets/migration-warning.mdx'; -The (legacy) IOTA and Shimmer networks run the Stardust protocol version that represents assets and tokens in a UTXO-based ledger. +# Stardust Migration + + + +The legacy IOTA and Shimmer networks run 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. @@ -15,60 +19,60 @@ developers on how to use the new models and handle assets. The Stardust ledger state, and hence the assets and tokens in the network, are represented via the [Unspent Transaction Output (UTXO) model.](https://github.com/iotaledger/tips/blob/main/tips/TIP-0020/tip-0020.md#utxo) 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`](../iota-101/objects/object-model.mdx) 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. +With the introduction of the object-based Move ledger in IOTA Rebased, transactions no longer consume and create outputs +but [`Move Objects`](../iota-101/objects/object-model.mdx) 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 really similar, but the underlying data structures are different, since move objects can -take any shape and form as opposed to the rigid format of UTXOs. The IOTA Foundation developed a move package (TODO link to stardust pkg in iota framework) -that emulates the stardust output models in the move language with all the previous stardust functionality supported. +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](../../references/framework/stardust/) 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, furthermore all tokens and assets held - by them, are automatically converted into move objects, coins and balances.** +**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.** ## What Happens To Shimmer? -The Shimmer network state is migrated to the IOTA Rebased network, using the very same move models as the IOTA Stardust network. +The Shimmer network state is migrated to the IOTA Rebased network, using the very same Move models as the IOTA Stardust network. The SMR token, and all native tokens and assets on the Shimmer network, live on in the IOTA Rebased network, under the same addresses. ## 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 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: - 1. The IOTA Foundation announces the milestone indices at which snapshots of the IOTA and Shimmer networks are taken. - 2. Once both milestones are reached in IOTA and SMR, global snapshots are taken via the Hornet node software. Both ShimmerEVM and IOTAEVM are stopped. - 3. The snapshots are then processed by the migration tool, which converts all UTXOs into move objects. - 4. A move genesis is prepared with all the move objects from both snapshots. - 5. The genesis blob is published and the IOTA Rebased network is started with it. - 6. ShimmerEVM and IOTAEVM are started with a new node software that connects to the IOTA Rebased network. - 7. IOTA, SMR 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. +1. The IOTA Foundation announces the milestone indices at which snapshots of the IOTA and Shimmer networks are taken. +2. Once both milestones are reached in IOTA and SMR, global snapshots are taken via the Hornet node software. Both ShimmerEVM and IOTAEVM are stopped. +3. The snapshots are then processed by the migration tool, which converts all UTXOs into Move objects. +4. A Move genesis is prepared with all the Move objects from both snapshots. +5. The genesis blob is published, and the IOTA Rebased network is started with it. +6. ShimmerEVM and IOTAEVM are started with new node software that connects to the IOTA Rebased network. +7. IOTA, SMR 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 introduction of move smart contracts and the object ledger. +IOTA Rebased is a major change in the technology stack with the introduction of Move smart contracts and the object ledger. All previous IOTA and Shimmer 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/SMR Stardust, so all addresses and keys are still valid, there is no +**IOTA Rebased uses the same address scheme as IOTA/SMR 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](./addresses.mdx) guide provides help on how to acquire how to parse Bech32 addresses to the new format. +a `0x` prefix. The [Addresses and Keys](./addresses.mdx) 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. Should it be necessary based on the assets of the user, a web application -that talks to the browser extension wallet helps users to claim their assets. +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 +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](./claiming.mdx) guide. -## What Tools Can I Use? +[//]: # (## What Tools Can I Use?) -## Highlights (main differences) \ No newline at end of file +[//]: # (## Highlights (Main Differences)) diff --git a/docs/content/developer/stardust/units.mdx b/docs/content/developer/stardust/units.mdx index 34cd8c58801..bc5aa9a2ac6 100644 --- a/docs/content/developer/stardust/units.mdx +++ b/docs/content/developer/stardust/units.mdx @@ -2,6 +2,9 @@ title: Units and Conversions description: Explains the units for IOTA and Shimmer tokens --- +import MigrationWarning from '../../_snippets/migration-warning.mdx'; + + ## IOTA diff --git a/docs/content/sidebars/developer.js b/docs/content/sidebars/developer.js index 31db2c502fe..74d82667b90 100644 --- a/docs/content/sidebars/developer.js +++ b/docs/content/sidebars/developer.js @@ -317,11 +317,6 @@ const developer = [ }, ], }, - 'developer/stardust/vested', - 'developer/stardust/testing', - 'developer/stardust/if-tools', - 'developer/stardust/faq', - 'developer/stardust/advanced', ], }, {