Merge branch 'sc-platform/Create-an-example-NFT-marketplace-using-the…

…-Kiosk-framework' into sc-platform/update-Kiosk-related-docs

docs/examples/move/nft_marketplace/README.md

@@ -1,6 +1,6 @@
 # Marketplace Guide
 
-The `nft_marketplace.move` module provides a straightforward implementation of a marketplace extension. To utilize it, follow the steps outlined below.
+The `marketplace_extension.move` module provides a straightforward implementation of a marketplace extension. To utilize it, follow the steps outlined below.
 The `item_for_market.move` contains mocked item data for use within the marketplace.
 The `rental_extension.move` is an extension adds functionality to enable item rentals.
 
@@ -12,107 +12,168 @@ Connect to the IOTA network (e.g., using a faucet to obtain tokens).
 
 ### 2. Install Kiosk
 
+By installation, we mean creating a Kiosk object and an OwnerCap, then transferring them to the caller.
 Run the following command to install the Kiosk module:
 
 ```bash
-iota client call \                                   
+iota client call \
     --package 0x2 \
     --module kiosk \
     --function default
 ```
 
-### 3. Publish `item_for_market.move`
+### 3. Publish `nft_marketplace` package
+
+#### 3.1(Optional) Publish Kiosk rules modules if these are not present in the network you are using
+
+Publish Kiosk rules modules(package):
 
 ```bash
-iota client publish
+iota client publish iota/kiosk
 ```
 
-### 4. Create an Item
+After publishing, export the following variable:
+
+- `RULES_PACKAGE_ID`: The ID of rules package.
+
+#### 3.2 Publish marketplace extension
+
+Publish the marketplace_extension.move module:
+
+```bash
+iota client publish iota/docs/examples/move/nft_marketplace
+```
+
+After publishing, export the following variables:
+
+- `MARKETPLACE_PACKAGE_ID`: The ID of whole marketplace package.
+- `MARKETPLACE_PUBLISHER_ID`: The ID of the publisher object created during marketplace package publishing."
+
+### 4. Create an Clothing Store Item
 
 Create an item, for instance:
 
 ```bash
 iota client call \
-    --package $M_ITEMS_ID \
-    --module market_items \
+    --package $MARKETPLACE_PACKAGE_ID \
+    --module clothing_store \
     --function new_jeans
 ```
 
-After creation, export the following variables:
+After creation, export the following variable:
 
-- PACKAGE_ID
-- ITEM_ID
-- PUBLISHER_ID
+- `CLOTHING_STORE_ITEM_ID`: The ID of the published item (in this case, Jeans).
 
 ### 5. Create a Transfer Policy
 
+`TransferPolicy` is a generic shared object acting as a central authority enforcing everyone to check their purchase is valid against the defined policy before the purchased item is transferred to the buyers. Object is specified by concrete type.
+`default` function creates `TransferPolicy` object and an OwnerCap, then transferring them to the caller.
+
 Set up a transfer policy for the created item using the command:
 
 ```bash
-iota client call \                                   
+iota client call \
     --package 0x2 \
     --module transfer_policy \
     --function default \
     --gas-budget 10000000 \
-    --args $PUBLISHER_ID \
-    --type-args "$ITEM_FOR_MARKET_PACKAGE_ID::market_items::Jeans"
+    --args $MARKETPLACE_PUBLISHER_ID \
+    --type-args "$MARKETPLACE_PACKAGE_ID::clothing_store::Jeans"
 ```
 
-### 6. Publish marketplac extension
+After publishing, export the following variables:
 
-Publish the nft_marketplace.move module:
-
-```bash
-iota client publish`
-```
+- `ITEM_TRANS_POLICY`: The ID of the item transfer policy object.
+- `ITEM_TRANS_POLICY_CAP`: The ID of the item transfer policy object owner capability"
 
-### 7. Install the Extension on the Kiosk
+### 6. Install the Extension on the Kiosk
 
+The install function enables installation of the Marketplace extension in a kiosk.
+Under the hood it invokes `kiosk_extension::add` that adds extension to the Kiosk via dynamic field.
 Install the marketplace extension on the created kiosk using the command:
 
 ```bash
 iota client call \
-    --package $MARKETPLACE_ID \
-    --module nft_marketplace \
+    --package $MARKETPLACE_PACKAGE_ID \
+    --module marketplace_extension \
     --function install \
     --args $KIOSK_ID $KIOSK_CAP_ID
 ```
 
-### 8. Set a Price for the Item
+### 7. Set a Price for the Item
 
 Set the price for the item:
 
 ```bash
 iota client call \
-    --package $MARKETPLACE_ID \
-    --module nft_marketplace \
+    --package $MARKETPLACE_PACKAGE_ID \
+    --module marketplace_extension \
     --function set_price \
-    --args $KIOSK_ID $KIOSK_CAP_ID $ITEM_ID 50000 \
-    --type-args "&ITEM_FOR_MARKET_PACKAGE_ID::market_items::Jeans"
+    --args $KIOSK_ID $KIOSK_CAP_ID $CLOTHING_STORE_ITEM_ID 50000 \
+    --type-args "$MARKETPLACE_PACKAGE_ID::clothing_store::Jeans"
 ```
 
-### 9.(Optional) Set Royalties
+### 8.(Optional) Set Royalties
+
+Royalties are a percentage of the item's price or revenue paid to the owner for the use or sale of their asset.
 
 Set royalties for the item:
 
 ```bash
 iota client call \
-    --package $MARKETPLACE \
-    --module nft_marketplace \
+    --package $MARKETPLACE_PACKAGE_ID \
+    --module marketplace_extension \
     --function setup_royalties \
-    --args $ITEM_TRANS_POLICY_ID $ITEM_TRANS_POLICY_CAP_ID 5000 2000 \
-    --type-args "ITEM_FOR_MARKET_PACKAGE_ID::market_items::Jeans"
+    --args $ITEM_TRANS_POLICY $ITEM_TRANS_POLICY_CAP 5000 2000 \
+    --type-args "$MARKETPLACE_PACKAGE_ID::clothing_store::Jeans"
 ```
 
-### 10. Buy an Item:
+### 9. Buy an Item:
+
+#### 9.1 Get the Item Price:
+
+```bash
+iota client ptb \
+--move-call $MARKETPLACE_PACKAGE_ID::marketplace_extension::get_item_price "<$MARKETPLACE_PACKAGE_ID::clothing_store::Jeans>" @$KIOSK_ID @$CLOTHING_STORE_ITEM_ID --assign item_price \
+```
+
+#### 9.2(Optional) Calculate rolyalties of the Item:
+
+```bash
+--move-call $RULES_PACKAGE_ID::royalty_rule::fee_amount "<$MARKETPLACE_PACKAGE_ID::clothing_store::Jeans>" @$ITEM_TRANS_POLICY item_price --assign royalties_amount \
+```
+
+#### 9.3 Create a payment coin with a specific amount (price + optional royalties):
+
+```bash
+--split-coins gas "[item_price, royalties_amount]" --assign payment_coins \
+--merge-coins payment_coins.0 "[payment_coins.1]" \
+```
+
+#### 9.4 Buy an Item using `payment_coins.0`:
+
+Here, when we buy an item, we pay the owner the item's price. If the royalty rule is enabled, an additional royalty fee, calculated as a percentage of the initial item price, is also paid. Once both payments are completed, the item is ready for transferring to the buyer.
 
 To purchase the item:
 
 ```bash
-iota client call \
-    --package $MARKETPLACE \
-    --module nft_marketplace \
-    --function buy_item \
-    --args $KIOSK_ID $ITEM_TRANS_POLICY_ID &ITEM_ID $COIN_ID \
-    --type-args "ITEM_FOR_MARKET_PACKAGE_ID::market_items::Jeans"
+--move-call $MARKETPLACE_PACKAGE_ID::marketplace_extension::buy_item "<$MARKETPLACE_PACKAGE_ID::clothing_store::Jeans>" @$KIOSK_ID @$ITEM_TRANS_POLICY @$CLOTHING_STORE_ITEM_ID payment_coins.0 --assign purchased_item
+```
+
+#### 9.5 Transfer an Item to the buyer:
+
+```bash
+--move-call 0x2::transfer::public_transfer "<$MARKETPLACE_PACKAGE_ID::clothing_store::Jeans>" purchased_item @<buyer address> \
+```
+
+The final purchase PTB request, including royalties, should look like this:
+
+```bash
+iota client ptb \
+--move-call $MARKETPLACE_PACKAGE_ID::marketplace_extension::get_item_price "<$MARKETPLACE_PACKAGE_ID::clothing_store::Jeans>" @$KIOSK_ID @$CLOTHING_STORE_ITEM_ID --assign item_price \
+--move-call $RULES_PACKAGE_ID::royalty_rule::fee_amount "<$MARKETPLACE_PACKAGE_ID::clothing_store::Jeans>" @$ITEM_TRANS_POLICY item_price --assign royalties_amount \
+--split-coins gas "[item_price, royalties_amount]" --assign payment_coins \
+--merge-coins payment_coins.0 "[payment_coins.1]" \
+--move-call $MARKETPLACE_PACKAGE_ID::marketplace_extension::buy_item "<$MARKETPLACE_PACKAGE_ID::clothing_store::Jeans>" @$KIOSK_ID @$ITEM_TRANS_POLICY @$CLOTHING_STORE_ITEM_ID payment_coins.0 --assign purchased_item \
+--move-call 0x2::transfer::public_transfer "<$MARKETPLACE_PACKAGE_ID::clothing_store::Jeans>" purchased_item @<buyer address>
 ```

docs/examples/move/nft_marketplace/sources/item_for_market.move → docs/examples/move/nft_marketplace/sources/clothing_store.move

@@ -1,10 +1,12 @@
-module nft_marketplace::market_items {
+/// Module provides `mock` items for using them in marketplace and rental extensions.
+#[allow(lint(self_transfer))]
+module nft_marketplace::clothing_store {
     use iota::package;
     /// One Time Witness.
-    public struct MARKET_ITEMS has drop {}
+    public struct CLOTHING_STORE has drop {}
 
 
-    fun init(otw: MARKET_ITEMS, ctx: &mut TxContext) {
+    fun init(otw: CLOTHING_STORE, ctx: &mut TxContext) {
         package::claim_and_keep(otw, ctx)
     }
 

docs/examples/move/nft_marketplace/sources/nft_marketplace.move → docs/examples/move/nft_marketplace/sources/marketplace_extension.move

@@ -1,4 +1,4 @@
-module nft_marketplace::nft_marketplace {
+module nft_marketplace::marketplace_extension {
     // iota imports
     use iota::{
         kiosk::{Kiosk, KioskOwnerCap, purchase},
@@ -10,38 +10,38 @@ module nft_marketplace::nft_marketplace {
     };
 
     // rules imports
-    // use kiosk::floor_price_rule::Rule as FloorPriceRule;
-    // use kiosk::personal_kiosk_rule::Rule as PersonalRule;
     use kiosk::royalty_rule::Rule as RoyaltyRule;
     use kiosk::royalty_rule;
-    // use kiosk::witness_rule::Rule as WitnessRule;
 
 
     // === Errors ===
     const EExtensionNotInstalled: u64 = 0;
-    const EObjectNotExist: u64 = 1;
+    const EWrongPaymentRoyalties: u64 = 1;
+    const ENotEnoughPaymentAmount: u64 = 2;
 
     // === Constants ===
-    const PERMISSIONS: u128 = 11;
+    const ALLOW_PLACE_AND_LOCK: u128 = 11;
 
     /// Extension Key for Kiosk Marketplace extension.
     public struct Marketplace has drop {}
 
     /// Used as a key for the item that has been up for sale that's placed in the Extension's Bag.
     public struct Listed has store, copy, drop { id: ID }
 
-    public struct ItemPrice<T: key + store> has store {
+    public struct ItemPrice<phantom T: key + store> has store {
         /// Total amount of time offered for renting in days.
         price: u64,
     }
 
+    // === Public Functions ===
+
     /// Enables someone to install the Marketplace extension in their Kiosk.
     public fun install(
         kiosk: &mut Kiosk,
         cap: &KioskOwnerCap,
         ctx: &mut TxContext,
     ) {
-        kiosk_extension::add(Marketplace {}, kiosk, cap, PERMISSIONS, ctx);
+        kiosk_extension::add(Marketplace {}, kiosk, cap, ALLOW_PLACE_AND_LOCK, ctx);
     }
 
     /// Remove the extension from the Kiosk. Can only be performed by the owner,
@@ -50,31 +50,52 @@ module nft_marketplace::nft_marketplace {
         kiosk_extension::remove<Marketplace>(kiosk, cap);
     }
 
-    public fun setup_royalties<T: key + store>(policy: &mut TransferPolicy<T>, cap: &TransferPolicyCap<T>, amount_bp: u16, min_amount: u64, ctx: &mut TxContext) {
+    /// Setup item royalty percentage
+    /// - amount_bp - the percentage of the purchase price to be paid as a
+    /// fee, denominated in basis points (100_00 = 100%, 1 = 0.01%).
+    /// - min_amount - the minimum amount to be paid as a fee if the relative
+    /// amount is lower than this setting.
+    public fun setup_royalties<T: key + store>(policy: &mut TransferPolicy<T>, cap: &TransferPolicyCap<T>, amount_bp: u16, min_amount: u64) {
         royalty_rule::add<T>(policy, cap, amount_bp, min_amount);
     }
 
-    /// Buy listed item and pay royalties if needed
-    public fun buy_item<T: key + store>(kiosk: &mut Kiosk, policy: &mut TransferPolicy<T>, item_id: object::ID, mut payment: Coin<IOTA>, ctx: &mut TxContext) {
+    /// Buy listed item with the indicated price and pay royalties if needed
+    public fun buy_item<T: key + store>(kiosk: &mut Kiosk, policy: &mut TransferPolicy<T>, item_id: object::ID, mut payment: Coin<IOTA>, ctx: &mut TxContext): T {
         assert!(kiosk_extension::is_installed<Marketplace>(kiosk), EExtensionNotInstalled);
-        let item_price = take_from_bag<T, Listed>(kiosk,  Listed { id: item_id });
-        let ItemPrice { price } = item_price;
-        let payment_amount = payment.split(price, ctx);
-        let payment_amount_value = payment_amount.value();
-        let (item, mut transfer_request) = purchase(kiosk, item_id, payment_amount);
+
+        // Get item price
+        let ItemPrice { price } = take_from_bag<T, Listed>(kiosk,  Listed { id: item_id });
+
+        // Compute the value of the coin in input
+        let payment_amount_value = payment.value();
+
+        // If the payment_amount_value is less than the item price, the request is invalid.
+        assert!(payment_amount_value >= price, ENotEnoughPaymentAmount);
+
+        // Prepare the payment coin for the purchase (if no royalties are present then the
+        // remaining balance will be 0 after this operation)
+        let coin_price = payment.split(price, ctx);
+
+        // Purchase and create the transfer request
+        let (item, mut transfer_request) = purchase(kiosk, item_id, coin_price);
+
+        // If the royalty is present, then update the request with a royalty payment
         if (policy.has_rule<T, RoyaltyRule>()) { 
-            let royalties_value = royalty_rule::fee_amount(policy, payment_amount_value);
-            let royalties_coin = payment.split(royalties_value, ctx);
-            royalty_rule::pay(policy, &mut transfer_request, royalties_coin);
+            let royalties_value = royalty_rule::fee_amount(policy, price);
+            assert!(payment_amount_value == price + royalties_value, EWrongPaymentRoyalties);
+            royalty_rule::pay(policy, &mut transfer_request, payment);
+        } else {
+            // Else clean the input coin (if the input payment amount is not exact, this will fail)
+            payment.destroy_zero();
         };
+
+        // Confirm the request
         transfer_policy::confirm_request(policy, transfer_request);
-        transfer::public_transfer<T>(item, ctx.sender());
-        // Send a leftover back to buyer
-        transfer::public_transfer(payment, ctx.sender());
+        item
     }
 
 
-  public fun set_price<T: key + store>(
+    public fun set_price<T: key + store>(
         kiosk: &mut Kiosk,
         cap: &KioskOwnerCap,
         item: T,
@@ -92,14 +113,27 @@ module nft_marketplace::nft_marketplace {
     }
 
 
+    public fun get_item_price<T: key + store>(
+        kiosk: &Kiosk,
+        item_id: ID,
+    ) : u64 {
+        let storage_ref = kiosk_extension::storage(Marketplace {}, kiosk);
+        let ItemPrice { price } = bag::borrow<Listed, ItemPrice<T>>(
+            storage_ref,
+            Listed { id: item_id },
+        );
+
+        *price
+    }
+
+
     // === Private Functions ===
 
     fun take_from_bag<T: key + store, Key: store + copy + drop>(
         kiosk: &mut Kiosk,
         item_key: Key,
     ) : ItemPrice<T> {
         let ext_storage_mut = kiosk_extension::storage_mut(Marketplace {}, kiosk);
-        assert!(bag::contains(ext_storage_mut, item_key), EObjectNotExist);
         bag::remove<Key, ItemPrice<T>>(
             ext_storage_mut,
             item_key,