fix(docs/content, docs/example): test example scenarios for claim/unl…

…ock outputs, documentation enhancement (#1862)

* feat(docs): Create an examples folder for Rust code (#1503)

* feat(docs): create an example folder for Rust code

* Update docs/examples/rust/Cargo.toml

---------

Co-authored-by: Dr-Electron <[email protected]>

* fix(docs/examples): remove base_keystore example

* feat(iota-sdk): added an alias output claim example (#1493)

* feat(iota-sdk): added an alias output claim example

* feat(docs): moved the alias output claim example

* refactor(docs): used the extract_and_send_to function to simplify the example

* fix(docs): added a license header and an example description

* fix(docs): alias-output-claim comments

* fix(docs): clippy

* fix(docs): move the alias-output-claim example into the stardust subfolder

* fix(docs): fixed the example after rebasing

* fix(docs): move the alias-output-claim example

* fix(docs): alias-output-claim logs improved

* feat(iota-sdk): add basic output claim example

* fix(iota-sdk): use the proper native token bag key

* fix(iota-sdk): move basic output example in docs

* fix(docs/examples): comments

* fix(docs/examples): license header

* fix(docs/examples): basic output address

* fix(docs/examples): fix clippy

* fix(docs/examples): fix from comments

* fix(docs/examples): move basic output example

* fix(docs/examples): remove src folder

* feat(docs/examples): nft output extraction example based on sdk (#1478)

* feat(docs): add nft output claiming test example based on sdk usage

* feat(ci): add docs examples in rust (#1539)

* fix(docs/examples): add license

* fix(docs/examples): cargo lock

* chore(docs/examples): add clarification comment

* feat(docs/examples): add unlock condition example based on rust sdk (#1559)

* feat(docs): add unlock condition example based on rust sdk
Add fund_address function for sponsoring the main transaction

* feat(docs/examples): Add foundry output claim example (#1575)

* feat(docs/examples): ad foundry output claim

* fix(docs/examples): cargo toml and clones

* feat(docs/examples): Test the positive scenarios for using an NFT object (#1615)

* Add example of third party simple nft package, PTB that creates custom nft from stardust::nft
Add a conversion function for custom NFTs to allow migrating custom NFTs from Stardust NFTs

* feat(docs/stardust): Add docs for basic output claim (#1639)

* feat(docs/stardust): add docs for basic output claim

* Update docs/examples/rust/stardust/check-basic-output-unlock-conditions.rs

Co-authored-by: Thoralf-M <[email protected]>

* Update docs/examples/rust/stardust/check-basic-output-unlock-conditions.rs

Co-authored-by: Thoralf-M <[email protected]>

---------

Co-authored-by: Thoralf-M <[email protected]>

* feat(docs/content): documentation - claim NFT Output (#1654)

* feat(docs/content): documentation - claim NFT Output

* fear(docs/content) example of conversion of a stardust NFT into a custom user's. (#1669)

* Add example ofr third party simple nft package, PTB that create custom nft from stardust::nft

* feat(examples/docs): Add a conversion function for custom NFTs to allow migrating custom NFTs from Stardust NFTs

* Add function that publishes random nft package via CLI.

* feat(examples): replace package publishing approach with iota-move-builder

* Fix chkecs

* Minor refactoring

* dprint fix

* Fix review comments

* feat(docs/content): add doc related to conversion of a NFT Output into sutom NFT

* Review comment fixes

* Fix Nft naming

* Fix review comments

---------

Co-authored-by: Mirko Zichichi <[email protected]>

* feat(docs): Using an Alias object test scenario (#1679)

* Add example ofr third party simple nft package, PTB that create custom nft from stardust::nft

* feat(examples/docs): Add a conversion function for custom NFTs to allow migrating custom NFTs from Stardust NFTs

* Add function that publishes random nft package via CLI.

* feat(examples): replace package publishing approach with iota-move-builder

* Fix chkecs

* Minor refactoring

* dprint fix

* Fix review comments

* feat(docs/content): add doc related to conversion of a NFT Output into sutom NFT

* feat(docs): extended the custom_nft package with collections

* Review comment fixes

* Fix Nft naming

* fix(docs): NFTs conversion docs were fixed after refactoring

* fix(docs): spelling issues

---------

Co-authored-by: Dkwcs <[email protected]>

* refactor(docs/content): Split claiming docs in a tree (#1710)

* refactor(docs/content): split claiming docs in a tree

* feat(docs/content): add address unlock condition claim

* fix(docs/content): claiming references

* fix(docs/content): claiming references 2

* chore(docs): fix doc tree for claiming

---------

Co-authored-by: Levente Pap <[email protected]>

* feat(docs): Alias usage documentation was added (#1723)

* Add example ofr third party simple nft package, PTB that create custom nft from stardust::nft

* feat(examples/docs): Add a conversion function for custom NFTs to allow migrating custom NFTs from Stardust NFTs

* Add function that publishes random nft package via CLI.

* feat(examples): replace package publishing approach with iota-move-builder

* Fix chkecs

* Minor refactoring

* dprint fix

* Fix review comments

* feat(docs/content): add doc related to conversion of a NFT Output into sutom NFT

* feat(docs): extended the custom_nft package with collections

* Review comment fixes

* Fix Nft naming

* fix(docs): NFTs conversion docs were fixed after refactoring

* fix(docs): spelling issues

* feat(docs): added alias documentation

* fix(docs): spelling issues

* fix(docs): review comments

---------

Co-authored-by: Dkwcs <[email protected]>

* feat(docs/content): docs implementation for address unlock condition example (#1706)

* feat(docs/content): docs impl for address unlock condition

* feat(docs/content): Create example doc for claiming a Foundry Output (#1724)

* feat(docs/content): add doc example of claiming foundry output

* fix(docs/content): enhance claiming and fix links (#1768)

* feat(docs/examples): Add self sponsor example for Shimmer assets (#1772)

* feat(docs/examples): add self sponsor example

* fix(docs/content): make self sponsor example for Shimmer

* fix(docs/examples): smr comment

* fix(docs/examples): dprint

* fix(docs/examples): remove double comment

Co-authored-by: Thoralf-M <[email protected]>

* fix(docs/examples): client server comments

---------

Co-authored-by: Thoralf-M <[email protected]>

* feat(docs/content): Add Shimmer self-sponsorship claim docs (#1773)

* feat(docs/examples): add self sponsor example

* fix(docs/content): make self sponsor example for Shimmer

* fix(docs/examples): smr comment

* fix(docs/examples): dprint

* feat(docs/content): add shimmer self-sponsorship claim

* fix(docs/content): spaces

Co-authored-by: Thoralf-M <[email protected]>

* fix(docs/content): code lines

---------

Co-authored-by: Thoralf-M <[email protected]>

* fix(docs/content): improvements of docs navigation by adding links (#1774)

* fix(docs/content): improvements of docs navigation by adding links

* fix(docs/content): add additional links, readable improvements.

* fix(docs/content/../claiming): simplify navigation with additional links for OTW, Bag, Coin, Unlock Condition

* refactor(docs/examples): Create a utility methods lib (#1821)

* refactor(docs/examples): create a utility methods lib

* refactor(docs/examples): update examples

* refactor(docs/content): update examples code lines in docs

* fix(docs/examples): move module path

* fix(docs/examples): address uc name

* Update docs/examples/rust/src/lib.rs

Co-authored-by: Thoralf-M <[email protected]>

* Update docs/content/developer/stardust/claiming/nft.mdx

Co-authored-by: Thoralf-M <[email protected]>

* fix(docs/examples): move utils out of lib

---------

Co-authored-by: Thoralf-M <[email protected]>

---------

Co-authored-by: Mirko Zichichi <[email protected]>
Co-authored-by: Dr-Electron <[email protected]>
Co-authored-by: Valerii Reutov <[email protected]>
Co-authored-by: Thoralf-M <[email protected]>
Co-authored-by: Levente Pap <[email protected]>

.github/actions/diffs/action.yml

@@ -32,6 +32,7 @@ runs:
             - "external-crates/**"
             - "narwhal/**"
             - "iota-execution/**"
+            - "docs/examples/rust/**"
             - ".github/workflows/hierarchy.yml"
             - ".github/workflows/codecov.yml"
             - ".github/workflows/_rust.yml"

Cargo.toml

@@ -146,6 +146,7 @@ members = [
   "crates/typed-store",
   "crates/typed-store-derive",
   "crates/typed-store-error",
+  "docs/examples/rust",
   "iota-execution",
   "iota-execution/cut",
   "iota-execution/latest/iota-adapter",

docs/content/developer/stardust/claiming.mdx

@@ -3,7 +3,42 @@ title: Claiming Stardust Assets
 description: Describes how to access the migrated assets and tokens
 ---
 
-  - Explains the resulting migrated state for simple coins (exchanges)
-  - Demonstrates through examples for each output type the resulting move objects
-  - Explains what commands need to be called in a PTB to claim the assets
-  - Describes transaction sponsorship from iota addresses for shimmer claiming
+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. 
+
+This process takes advantage of Move's unique features to ensure that assets are transferred and unlocked securely and efficiently to their rightful owners.
+
+
+## Output types to Move Objects
+
+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.
+
+
+## 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.
+
+### Basic Output
+
+Go to [Basic Output](claiming/basic.mdx).
+
+### Nft Output
+
+Go to [Nft Output](claiming/nft.mdx).
+
+### Alias Output
+
+Go to [Alias Output](claiming/alias.mdx).
+
+### Foundry Output
+
+Go to [Foundry Output](claiming/foundry.mdx).
+
+### Output unlockable by an Alias/Nft Address
+
+Go to [Output unlockable by an Alias/Nft Address](claiming/address-unlock-condition.mdx).
+
+## 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. 
+
+Go to [Self-sponsor Shimmer Claimings](claiming/self-sponsor.mdx).

docs/content/developer/stardust/claiming/address-unlock-condition.mdx

@@ -0,0 +1,66 @@
+---
+ title: Claiming an Output unlockable by an Alias/Nft Address
+---
+
+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.       
+
+## 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`.
+
+1. The first step is to fetch the `AliasOutput` object that is needed for claiming the `NftOutput`.
+
+<Tabs>
+<TabItem value="rs" label="Rust">
+
+```rust file=<rootDir>/docs/examples/rust/stardust/address-unlock-condition.rs#L70-L88
+```
+
+</TabItem>
+<TabItem value="ts" label="TypeScript">
+
+</TabItem>
+</Tabs>
+
+2. By using the dynamic field function with the "alias" dynamic field key filter, we gather the `Alias` object itself.
+
+<Tabs>
+<TabItem value="rs" label="Rust">
+
+```rust file=<rootDir>/docs/examples/rust/stardust/address-unlock-condition.rs#L90-L103
+```
+
+</TabItem>
+<TabItem value="ts" label="TypeScript">
+
+</TabItem>
+</Tabs>
+
+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`.
+
+<Tabs>
+<TabItem value="rs" label="Rust">
+
+```rust file=<rootDir>/docs/examples/rust/stardust/address-unlock-condition.rs#L105-L128
+```
+
+</TabItem>
+<TabItem value="ts" label="TypeScript">
+
+</TabItem>
+</Tabs>
+
+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`.
+
+<Tabs>
+<TabItem value="rs" label="Rust">
+
+```rust file=<rootDir>/docs/examples/rust/stardust/address-unlock-condition.rs#L130-L239
+```
+
+</TabItem>
+<TabItem value="ts" label="TypeScript">
+
+</TabItem>
+</Tabs>

docs/content/developer/stardust/claiming/alias.mdx

@@ -0,0 +1,100 @@
+---
+ title: Claiming Alias Outputs
+---
+
+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.
+
+## Claim of 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.
+
+<Tabs>
+<TabItem value="rs" label="Rust">
+
+```rust file=<rootDir>/docs/examples/rust/stardust/alias-output-claim.rs#L56-L81
+```
+
+</TabItem>
+<TabItem value="ts" label="TypeScript">
+
+</TabItem>
+</Tabs>
+
+
+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/iota-move-concepts/one-time-witness.mdx) used for the native token declaration.
+
+<Tabs>
+<TabItem value="rs" label="Rust">
+
+```rust file=<rootDir>/docs/examples/rust/stardust/alias-output-claim.rs#L83-L110
+```
+
+</TabItem>
+<TabItem value="ts" label="TypeScript">
+
+</TabItem>
+</Tabs>
+
+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`.
+
+<Tabs>
+<TabItem value="rs" label="Rust">
+
+```rust file=<rootDir>/docs/examples/rust/stardust/alias-output-claim.rs#L112-L180
+```
+
+</TabItem>
+<TabItem value="ts" label="TypeScript">
+
+</TabItem>
+</Tabs>
+
+## Conversion of 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. 
+
+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.
+
+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:
+
+<Tabs>
+<TabItem value="move" label="Move">
+
+The `collection.move` module extends the `custom_nft` package to make it possible to work with NFT collections:
+
+```move file=<rootDir>/docs/examples/move/custom_nft/sources/collection.move
+```
+
+Also, the `nft.move` module was extended with the following function:
+
+```move file=<rootDir>/docs/examples/move/custom_nft/sources/nft.move#L82-L97
+```
+
+</TabItem>
+
+</Tabs>
+
+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.
+
+<Tabs>
+<TabItem value="rs" label="Rust">
+
+```rust file=<rootDir>/docs/examples/rust/stardust/alias-migration.rs#L119-L244
+```
+
+</TabItem>
+<TabItem value="ts" label="TypeScript">
+
+</TabItem>
+</Tabs>
+

docs/content/developer/stardust/claiming/basic.mdx

@@ -0,0 +1,71 @@
+---
+ title: Claiming Basic Outputs
+---
+
+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.    
+
+<Tabs>
+<TabItem value="rs" label="Rust">
+
+```rust file=<rootDir>/docs/examples/rust/stardust/check-basic-output-unlock-conditions.rs#L20-L56
+```
+
+</TabItem>
+<TabItem value="ts" label="TypeScript">
+
+TODO
+
+</TabItem>
+</Tabs>
+
+## Claim of a Basic Output
+Once a Basic Output can be unlocked the claim of its assets can start
+
+1. The first step is to fetch the `BasicOutput` object that needs to be claimed.
+
+<Tabs>
+<TabItem value="rs" label="Rust">
+
+```rust file=<rootDir>/docs/examples/rust/stardust/basic-output-claim.rs#L56-L81
+```
+
+</TabItem>
+<TabItem value="ts" label="TypeScript">
+
+TODO
+
+</TabItem>
+</Tabs>
+
+
+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/iota-move-concepts/one-time-witness.mdx) used for the native token [`Coin`](../../../references/framework/iota-framework/coin.mdx#resource-coin).
+
+<Tabs>
+<TabItem value="rs" label="Rust">
+
+```rust file=<rootDir>/docs/examples/rust/stardust/basic-output-claim.rs#L83-L110
+```
+
+</TabItem>
+<TabItem value="ts" label="TypeScript">
+
+TODO
+
+</TabItem>
+</Tabs>
+
+3. Finally, a PTB can be created using the `basic_output` as input and the `Bag` keys for iterating the native tokens extracted. 
+
+<Tabs>
+<TabItem value="rs" label="Rust">
+
+```rust file=<rootDir>/docs/examples/rust/stardust/basic-output-claim.rs#L113-L177
+```
+
+</TabItem>
+<TabItem value="ts" label="TypeScript">
+
+TODO
+
+</TabItem>
+</Tabs>