Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

task(devx) - Edit nft marketplace example readme #4357

Merged
merged 2 commits into from
Dec 5, 2024
+62 −33
Merged

task(devx) - Edit nft marketplace example readme #4357

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
5fcfb05
Added links and edited README
lucas-tortora Dec 4, 2024
d8cf9e2
change branch in links
lucas-tortora Dec 4, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
95 changes: 62 additions & 33 deletions docs/examples/move/nft_marketplace/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,18 +1,27 @@
# Marketplace Guide

The `marketplace_extension.move` module provides a straightforward implementation of a marketplace extension. To utilize it, follow the steps outlined below.
The `clothing_store.move` contains mocked item data for use within the marketplace.
The `rental_extension.move` is an extension adds functionality to enable item rentals.
## Modules

## Steps to Use the Marketplace
The [`marketplace_extension.move`](https://github.com/iotaledger/iota/blob/develop/docs/examples/move/nft_marketplace/sources/marketplace_extension.move)
module provides a straightforward implementation of a marketplace extension. To use it, follow the
[steps outlined below](#how-to-use-the-marketplace).

### 1. Connect to the Network
The [`clothing_store.move`](https://github.com/iotaledger/iota/blob/develop/docs/examples/move/nft_marketplace/sources/clothing_store.move) module contains mocked item data for
use within the marketplace.

Connect to the IOTA network (e.g., using a faucet to obtain tokens).
The [`rental_extension.move`](https://github.com/iotaledger/iota/blob/develop/docs/examples/move/nft_marketplace/sources/rental_extension.move) module adds the functionality to enable item rentals.

## How To Use the Marketplace

### 1. Install the IOTA CLI and Connect to the Network

The first thing you'll need to do is [install the IOTA CLI](https://docs.iota.org/developer/getting-started/install-iota), [connect to an IOTA network](https://docs.iota.org/developer/getting-started/connect) and [get some test tokens](https://docs.iota.org/developer/getting-started/get-coins) to pay for [gas](https://docs.iota.org/about-iota/tokenomics/gas-in-iota).

### 2. Install Kiosk

By installation, we mean creating a Kiosk object and an OwnerCap, then transferring them to the caller.
You can install the Kiosk by creating a `Kiosk` object, which will also create its `OwnerCap`, and then transferring
them to the caller.

Run the following command to install the Kiosk module:

```bash
Expand All @@ -24,37 +33,37 @@ iota client call \

After publishing, export the following variables:

- `KIOSK_ID`: The ID of installed Kiosk object.
- `KIOSK_ID`: The ID of the installed Kiosk object.
- `KIOSK_CAP_ID`: The ID of the installed Kiosk's owner cap

### 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):
You can publish Kiosk rules modules(package) using the following command:

```bash
iota client publish $IOTA_REPO_DIR/kiosk
```

After publishing, export the following variable:

- `RULES_PACKAGE_ID`: The ID of rules package.
- `RULES_PACKAGE_ID`: The ID of the rules package.

#### 3.2 Publish marketplace package
#### 3.2 Publish the `nft_marketplace` Package

```bash
iota client publish $IOTA_REPO_DIR/docs/examples/move/nft_marketplace
```

After publishing, export the following variables:

- `MARKETPLACE_PACKAGE_ID`: The ID of whole marketplace package.
- `MARKETPLACE_PACKAGE_ID`: The ID of the whole marketplace package.
- `MARKETPLACE_PUBLISHER_ID`: The ID of the publisher object created during marketplace package publishing."

### 4. Create an Clothing Store Item
### 4. Create a Clothing Store Item

Create an item, for instance:
Next, you should use the functions in the `clothing_store` module to create an item, for instance:

```bash
iota client call \
Expand All @@ -69,13 +78,15 @@ After creation, export the following variable:

### 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 `TransferPolicyCap`, then transferring them to the caller.
`TransferPolicy` is a generic-shared object that acts as a central authority enforcing that everyone checks their
purchase is valid against the defined policy before the purchased item is transferred to the buyer. The object is
specified by concrete type:
The `default` function creates a `TransferPolicy` object and a `TransferPolicyCap`, then transfers them to the caller.

`TransferPolicyCap` object serves as proof of ownership of the `TransferPolicy` object.
A capability granting the owner permission to `add/remove` rules as well as to `withdraw` and `destroy_and_withdraw` the `TransferPolicy`.
The `TransferPolicyCap` object serves as proof of ownership of the `TransferPolicy` object.
A capability granting the owner permission to `add/remove` rules, `withdraw`, and `destroy_and_withdraw` the `TransferPolicy`.

Set up a transfer policy for the created item using the command:
You can set up a transfer policy for the created item using the following command:

```bash
iota client call \
Expand All @@ -94,9 +105,9 @@ After publishing, export the following variables:

### 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:
The [`install`](https://github.com/iotaledger/iota/blob/develop/docs/examples/move/nft_marketplace/sources/marketplace_extension.move#L39-L45) function enables the installation of the Marketplace extension in a kiosk.
Under the hood, it invokes `kiosk_extension::add`, which adds an extension to the Kiosk via a [dynamic field](https://docs.iota.org/developer/iota-101/objects/dynamic-fields/).
You can install the marketplace extension on the created kiosk using the following command:

```bash
iota client call \
Expand All @@ -108,7 +119,7 @@ iota client call \

### 7. Set a Price for the Item

Set the price for the item:
You can use the [`set_price`](https://github.com/iotaledger/iota/blob/develop/docs/examples/move/nft_marketplace/sources/marketplace_extension.move#L98-L114) function to set the price for the item:

```bash
iota client call \
Expand All @@ -121,9 +132,9 @@ iota client call \

### 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.
Royalties are a percentage of the item's price or revenue paid to the owner for using or selling their asset.

Set royalties for the item:
You can use the [`set_royalties`](https://github.com/iotaledger/iota/blob/develop/docs/examples/move/nft_marketplace/sources/marketplace_extension.move#L58-L60) function to set royalties for the item:

```bash
iota client call \
Expand All @@ -134,45 +145,63 @@ iota client call \
--type-args "$MARKETPLACE_PACKAGE_ID::clothing_store::Jeans"
```

### 9. Buy an Item:
### 9. Buy an Item

#### 9.1 Get the Item Price:
#### 9.1 Get the Item Price

You can use the following [Programmable Transaction Block](https://docs.iota.org/developer/iota-101/transactions/ptb/programmable-transaction-blocks-overview) to call the
[`get_item_price`](https://github.com/iotaledger/iota/blob/develop/docs/examples/move/nft_marketplace/sources/marketplace_extension.move#L116-L127)
and assign it to an `item_price` variable. In this case, the Jeans item:

```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 royalties of the Item:
#### 9.2(Optional) Calculate the Royalties For the Item

You can use the following [move-call](https://docs.iota.org/references/cli/ptb#move-call) to get the royalties for any given product by calling the `kiosk::royalty_rule::fee_amount` function
and assign it to a `royalties_amount` variable. In this case, the Jeans 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):
#### 9.3 Create a Payment Coin With a Specific Amount (Price + Optional Royalties)

You can use the following command to [split your gas tokens](https://docs.iota.org/references/cli/ptb#split-destroy-and-merge-coins) to pay for the item's price and 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`:
#### 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.
You can use the following [move-call](https://docs.iota.org/references/cli/ptb#move-call) to 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 transfer to the buyer.

To purchase the item:

```bash
--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:
#### 9.5 Transfer an Item to the Buyer

Finally, you can set up the
[public_transfer](https://docs.iota.org/references/framework/iota-framework/transfer#function-public_transfer) to
transfer the purchased 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:
You can combine all the previous steps into one purchase
[PTB](https://docs.iota.org/developer/iota-101/transactions/ptb/programmable-transaction-blocks-overview) request,
including royalties, which should look like this:

```bash
iota client ptb \
Expand Down
Loading