diff --git a/descriptors/eosio.nft.ft-descriptor.json b/descriptors/eosio.nft.ft-descriptor.json index c6b4f9f867..d252ada0ed 100644 --- a/descriptors/eosio.nft.ft-descriptor.json +++ b/descriptors/eosio.nft.ft-descriptor.json @@ -18,7 +18,7 @@ }, "promoter_basis_point": { "friendlyName": "Promoter Basis Points", - "description": "Promoter commission in basis points (0-1000)" + "description": "Promoter commission in basis points (200-1000)" }, "owner": { "friendlyName": "Owner", @@ -104,7 +104,7 @@ }, "promoter_basis_point": { "friendlyName": "Promoter Basis Points", - "description": "Promoter commission in basis points (0-1000)" + "description": "Promoter commission in basis points (200-1000)" }, "factory_id": { "friendlyName": "Token Factory ID", @@ -747,7 +747,7 @@ }, "promoter_basis_point": { "friendlyName": "Promoter Basis Points", - "description": "The resale promoter commission (0-1000)" + "description": "The resale promoter commission (200-1000)" }, "memo": { "friendlyName": "Memo", @@ -898,7 +898,7 @@ }, "promoter_basis_point": { "friendlyName": "Promoter basis point", - "description": "UOS share received by the promoter with each purchase done for this option. Specified in basis points (200-1000)" + "description": "UOS share received by the promoter with each purchase done for this option. Specified in basis points (0-1000)" }, "purchase_option_with_uniqs": { "friendlyName": "Purchase option with Uniqs", diff --git a/docs/blockchain/contracts/nft-contract/nft-actions/setprchsreq.a.md b/docs/blockchain/contracts/nft-contract/nft-actions/setprchsreq.a.md index 731cb47d34..543b950860 100644 --- a/docs/blockchain/contracts/nft-contract/nft-actions/setprchsreq.a.md +++ b/docs/blockchain/contracts/nft-contract/nft-actions/setprchsreq.a.md @@ -43,7 +43,7 @@ The factory manager can specify purchase options for users. Note that currently `purchase_limit` - how much users can buy via purchase action. It has to be less than factory limit setting and greater or equal to what was already minted via the action. If value provided is below the number of tokens already purchased from this option the `purchase_limit` will be set to be equal to the number of purchased tokens from this option -`promoter_basis_point` is used to specify how much % of a sale a promoter will get. Minimum value is `200` (2%), maximum value is `1000` (10%). Value range is controlled by `min_promoter_share_bp` and `max_promoter_share_bp` stored in `saleshrlimcfg` table under the scope of `1`. +`promoter_basis_point` is used to specify how much % of a sale a promoter will get. Minimum value is `0` (0%), maximum value is `1000` (10%). Value range is controlled by `min_promoter_share_bp` and `max_promoter_share_bp` stored in `saleshrlimcfg` table under the scope of `0`. `purchase_option_with_uniqs` - optional field used to set purchase options via uniqs. user has to have `count` tokens from listed uniq factories. They will be burned, transferred or checked as per `strategy` setting. @@ -122,7 +122,7 @@ By understanding this formalization, you can ensure a clear and standardized way | index | uint64_t | number | Index of the purchase option. Multiple purchase options can be added to a single factory | | price | eosio::asset | string | Price of the Uniqs from this purchase option either in UOS or USD. Can also set 0 price | | purchase_limit | optional\ | number / null | Maximum number of Uniqs that can be purchased from this purchase option. Must not exceed factory minting limit | -| promoter_basis_point | uint16_t | number | UOS share received by the promoter with each purchase done for this option. Specified in basis points. Must be in the range 200-1000 | +| promoter_basis_point | uint16_t | number | UOS share received by the promoter with each purchase done for this option. Specified in basis points. Must be in the range 0-1000 | | purchase_option_with_uniqs | std::optional\ | Object / null | Optional feature that allows the purchase option to require user to own uniqs from specific factories or to pay with uniqs from specific factories. Refer to a link below for more details | | sale_shares | std::vector\ | Array | A vector of [account, share] pairs setting the share each account receives during the purchase | | maximum_uos_payment | optional\ | asset / null | Maximum amount of UOS manager allows to be take for the creation of the purchase option. Since the price is fixed in USD the equivalent UOS payment may fluctuate. Using this option will prevent the manager from paying more then he is willing to | diff --git a/docs/blockchain/contracts/nft-contract/nft-actions/setprchsreq.b.md b/docs/blockchain/contracts/nft-contract/nft-actions/setprchsreq.b.md index aa5761a545..5e6607d821 100644 --- a/docs/blockchain/contracts/nft-contract/nft-actions/setprchsreq.b.md +++ b/docs/blockchain/contracts/nft-contract/nft-actions/setprchsreq.b.md @@ -39,7 +39,7 @@ The factory manager can specify purchase options for users. Note that currently `purchase_limit` - how much users can buy via purchase action. It has to be less than factory limit setting and greater or equal to what was already minted via the action. If value provided is below the number of tokens already purchased from this option the `purchase_limit` will be set to be equal to the number of purchased tokens from this option -`promoter_basis_point` is used to specify how much % of a sale a promoter will get. Minimum value is `200` (2%), maximum value is `1000` (10%). Value range is controlled by `min_promoter_share_bp` and `max_promoter_share_bp` stored in `saleshrlimcfg` table under the scope of `1`. +`promoter_basis_point` is used to specify how much % of a sale a promoter will get. Minimum value is `0` (0%), maximum value is `1000` (10%). Value range is controlled by `min_promoter_share_bp` and `max_promoter_share_bp` stored in `saleshrlimcfg` table under the scope of `0`. `purchase_option_with_uniqs` - optional field used to set purchase options via uniqs. user has to have `count` tokens from listed uniq factories. They will be burned, transferred or checked as per `strategy` setting. @@ -118,7 +118,7 @@ By understanding this formalization, you can ensure a clear and standardized way | index | uint64_t | number | Index of the purchase option. Multiple purchase options can be added to a single factory | | price | eosio::asset | string | Price of the Uniqs from this purchase option either in UOS or USD. Can also set 0 price | | purchase_limit | optional\ | number / null | Maximum number of Uniqs that can be purchased from this purchase option. Must not exceed factory minting limit | -| promoter_basis_point | uint16_t | number | UOS share received by the promoter with each purchase done for this option. Specified in basis points. Must be in the range 200-1000 | +| promoter_basis_point | uint16_t | number | UOS share received by the promoter with each purchase done for this option. Specified in basis points. Must be in the range 0-1000 | | purchase_option_with_uniqs | std::optional\ | Object / null | Optional feature that allows the purchase option to require user to own uniqs from specific factories or to pay with uniqs from specific factories. Refer to a link below for more details | | sale_shares | std::vector\ | Array | A vector of [account, share] pairs setting the share each account receives during the purchase | | maximum_uos_payment | optional\ | asset / null | Maximum amount of UOS manager allows to be take for the creation of the purchase option. Since the price is fixed in USD the equivalent UOS payment may fluctuate. Using this option will prevent the manager from paying more then he is willing to | diff --git a/docs/tutorials/index/index.md b/docs/tutorials/index/index.md index e940e03d40..a3161b33b7 100644 --- a/docs/tutorials/index/index.md +++ b/docs/tutorials/index/index.md @@ -167,11 +167,6 @@ General tutorials to help feed your curiosity. Learn how to validate uniq metadata files using Ultra Toolkit's schema validation feature Link - - How to perform advanced actions with Uniqs and Factories - Learn how to use Ultra Toolkit to add or remove a direct purchase from your Factory, transfer and burning Uniqs, add authorized minters - Link - How to create a Uniq Factory using Ultra Toolkit Learn how to create your first uniq factory using Ultra Toolkit @@ -188,15 +183,21 @@ General tutorials to help feed your curiosity. Link - How to perform advanced actions with Uniqs and Factories - Learn how to use Ultra Toolkit to add or remove a direct purchase from your Factory, transfer and burning Uniqs, add authorized minters + How to perform advanced actions with Uniqs and Factories using Ultra Toolkit + Learn how to transfer Uniqs, burn Uniqs add authorized minters to your factory using Ultra Toolkit Link + + How to add first-hand purchase options using Toolkit + Learn how to use Ultra Toolkit to add or remove a direct purchase option from your Factory + Link + Uniq Avatars Learn how to manage your uniq avatar as a user Link + ## Others diff --git a/docs/tutorials/uniq-factories/creating-uniq-factories/how-to-update-uniq-metadata-using-toolkit.md b/docs/tutorials/uniq-factories/creating-uniq-factories/how-to-update-uniq-metadata-using-toolkit.md index 3163cf7ff3..0392e2f9a5 100644 --- a/docs/tutorials/uniq-factories/creating-uniq-factories/how-to-update-uniq-metadata-using-toolkit.md +++ b/docs/tutorials/uniq-factories/creating-uniq-factories/how-to-update-uniq-metadata-using-toolkit.md @@ -179,4 +179,6 @@ You have now successfully disabled metadata updates for the uniq factory. To ver ## What's next? -TODO +After practicing the basic metadata actions, you can move on to advanced actions with Uniqs and Factories: + +- [How to perform advanced actions with Uniqs and Factories](../factory-management/how-to-perform-advanced-actions-with-uniqs-and-factories.md) diff --git a/docs/tutorials/uniq-factories/factory-management/exchange-a-uniq-using-smart-contract.md b/docs/tutorials/uniq-factories/factory-management/exchange-a-uniq-using-smart-contract.md index f7c1fa7f48..1389c294ba 100644 --- a/docs/tutorials/uniq-factories/factory-management/exchange-a-uniq-using-smart-contract.md +++ b/docs/tutorials/uniq-factories/factory-management/exchange-a-uniq-using-smart-contract.md @@ -1,7 +1,7 @@ --- title: 'Exchange a Uniq Using Smart Contract' -order: 3 +order: 5 --- # Exchange a Uniq Using Smart Contract diff --git a/docs/tutorials/uniq-factories/factory-management/factory-purchase-options-examples.md b/docs/tutorials/uniq-factories/factory-management/factory-purchase-options-examples.md index 71da4b3a09..d74b015676 100644 --- a/docs/tutorials/uniq-factories/factory-management/factory-purchase-options-examples.md +++ b/docs/tutorials/uniq-factories/factory-management/factory-purchase-options-examples.md @@ -1,7 +1,7 @@ --- title: 'Factory Purchase Options Examples' -order: 2 +order: 4 --- diff --git a/docs/tutorials/uniq-factories/factory-management/factory-purchase-options.md b/docs/tutorials/uniq-factories/factory-management/factory-purchase-options.md index 2cbe126f8c..fa81633cd2 100644 --- a/docs/tutorials/uniq-factories/factory-management/factory-purchase-options.md +++ b/docs/tutorials/uniq-factories/factory-management/factory-purchase-options.md @@ -1,7 +1,7 @@ --- title: 'Factory Purchase Options' -order: 1 +order: 3 --- diff --git a/docs/tutorials/uniq-factories/factory-management/how-to-add-first-hand-purchase-using-toolkit.md b/docs/tutorials/uniq-factories/factory-management/how-to-add-first-hand-purchase-using-toolkit.md new file mode 100644 index 0000000000..5829b63cfd --- /dev/null +++ b/docs/tutorials/uniq-factories/factory-management/how-to-add-first-hand-purchase-using-toolkit.md @@ -0,0 +1,167 @@ +--- +title: 'How to add a first-hand purchase options using Ultra Toolkit' +order: 2 +outline: [0, 4] +--- + +# How to add a first-hand purchase options using Ultra Toolkit + +Besides directly minting Uniqs or assigning authorized minters, it may be desired to allow users to directly purchase Uniqs from your factory. This can be achieved using the first-hand purchase feature which will be covered in this guide. + +## Prerequisites + +- Created a Uniq Factory. Follow the [Factory creation guide](../creating-uniq-factories/how-to-create-uniq-metadata.md) for details. +- Your account must have sufficient UOS tokens for transactions and fees. If you don't have tokens, see [how to use Faucet](../../fundamentals/tutorial-obtain-token-and-purchase-ram.md) for Testnet or [how to buy UOS](../../guides/how-to-buy-uos.md) for Mainnet. +- A developer account on the Ultra Testnet or Mainnet and to be logged into the Ultra Toolkit. If you don't have it, please follow our previous tutorial: [Tutorial - Log in to the Ultra Toolkit](../../fundamentals/tutorial-login-to-toolkit.md). + +## Goal + +The goal of this guide is to demonstrate the the process of adding and removing direct purchase options for your Factory. + +## How to add first-hand purchase to your factory + +First-hand purchase is a feature of NFT contract that allows factory managers to add a purchase option so that users can directly mint Uniqs themselves while paying some UOS or USD fee, or by potentially burning or transferring Uniqs. You can also require user to own some specific Uniq in order to use the purchase option. + +You can see the list of potential use cases of this feature on the dedicated [Factory Purchase Options](../factory-management/factory-purchase-options.md) page. + +To create a simple purchase option first navigate to [Factory management actions](https://toolkit.ultra.io/factoryManagement) and search for `setprchsreq`. + +![](./images/first-hand-purchase-search-setprchsreq.png) + +After finding it, select `Set first-hand purchase requirement (eosio.nft.ft::setprchsreq.b)` action. + +There are multiple fields, here we will provide a short breakdown for each of them. For more details, refer to [action documentation](../../../blockchain/contracts/nft-contract/nft-actions/setprchsreq.b.md). + +- **Token factory ID** - The ID of the token factory you manage and want to modify. You must be a manager of that factory +- **Purchase option index** - A number that will let you identify the purchase option, in case there are multiple options per factory. It can be any positive number you want, we advise you to start from 0 and increase it by one for any new purchase option you add. Note that if you set the purchase requirement with an existing index then it will overwrite it. +- **Purchase price** - Required payment in UOS or USD (will be converted to UOS at the time of purchase) to be able to purchase a Uniq. It can also be set to 0 but only if the `Purchase option with Uniqs` is set. +- **Purchase limit** - Dictates the maximum number of Uniqs that can be bought using this option specifically. The limit is not shared between the options. If you need to have a total cap then you better manage it though the minting limit of the factory. Optional, can leave it empty. +- **Promoter basis point** - A share of UOS that a promoter will get at the time of purchase, specified in basis points. Must be at least 200 (which is equal to 2%). +- **Purchase option with Uniqs** - Allows you to specify the price for this purchase option using Uniqs from other factories or to require the buyer to own Uniqs from specific factories. This field is covered in more detail in the later example in this guide. +- **Sale shares** - Specifies the list of accounts who will get a share of UOS from the purchase done using this purchase option. The `Basis points` field determines how much the account will get, specified in basis points (1 point = 0.01%). Optional, can leave it empty. +- **Maximum UOS payment** - The maximum amount of UOS you are ok to pay to create the purchase option. The payment is only used to cover RAM costs and is predictable. Optional, can leave it empty. +- **Group restriction** - Allows you to specify user groups who are able or not able to use this purchase option. Refer to [action documentation](../../../blockchain/contracts/nft-contract/nft-actions/setprchsreq.b.md) for a deeper explanation on how to use the user group restriction. Optional, can leave it empty. +- **Purchase window start** - Makes it so the purchase option is only available starting at some point in time in the format of `2021-05-01T00:00:00`. Optional, can leave it empty. +- **Purchase window end** - Makes it so the purchase option is only available until some point in time in the format of `2021-05-01T00:00:00`. Optional, can leave it empty. +- **Memo** - Simple text message that can be used for various purposes. Does not affect the result of the transaction. Optional, can leave it empty. + +![](./images/first-hand-purchase-simple-UOS-price.png) + +Click on `Send 1 Action`, review the details, and confirm your transaction. + +You can now navigate to [Factory explorer](https://toolkit.ultra.io/uniqFactory), enter your Factory ID. After scrolling down, you will see the newly added purchase option. + +![](./images/first-hand-purchase-simple-UOS-price-result.png) + +## How to buy a Uniq using a first-hand purchase option + +To purchase a Uniq directly using the new purchase option navigate to [Factory management actions](https://toolkit.ultra.io/factoryManagement). + +Search for `purchase` and select `Purchase Uniqs directly (eosio.nft.ft::purchase.a)`. + +![](./images/first-hand-purchase-search-purchase.png) + +Now you need to fill the action form. There are multiple fields that you need to fill and here we will provide a short breakdown for each one of them. + +- **Token factory ID** - The ID of the factory from which you want to purchase a Uniq. +- **Index** - Purchase option index that was specified in `setprchsreq.b` action. +- **Maximum UOS payment** - Maximum amount of UOS that you are willing to use for this purchase. It must be at least equal to the current price of the purchase option converted to UOS (in case it is originally specified in USD). You can put a larger value here but you will not be charged more than the current price at the time the transaction is executed. If the price of the purchase option is already in UOS then you can use the same value here. +- **Buyer** - The account that signs a transaction and who will pay the required amount of UOS and, if required, the Uniqs needed for this purchase option. +- **Receiver** - The account that will get the Uniq after the purchase is done. It can be the same as the `Buyer` in most cases. +- **Promoter** - The account that will get a share of UOS from this purchase. If you are building a marketplace you would want to specify your account as a promoter to receive a share of UOS from each purchase. If not specified then Ultra will be used as a promoter. +- **Provided Uniqs** - The list of Uniqs that you want to check, burn, or transfer. This is required if the purchase option specifies `Purchase option with Uniqs`. The example on how to fill this field will be provided later in this guide. +- **Memo** - Simple text message that can be used for various purposes. Does not affect the result of the transaction. Optional, can leave it empty. + +For more details see the [action documentation](../../../blockchain/contracts/nft-contract/nft-actions/purchase.a.md). + +![](./images/first-hand-purchase-purchase-simple-UOS-price.png) + +After you have filled the form, click on `Send 1 Action`, review the details, and confirm the transaction. + +Now you should be able to navigate to your inventory (either click on the `Inventory` on the home page of the Toolkit https://toolkit.ultra.io/ or go to https://toolkit.ultra.io/user and enter desired account name manually). + +You should be able to scroll down and see the list of Uniqs the account has. Note that it may take a minute for Ultra API to update and show your Uniq. + +![](./images/first-hand-purchase-Uniq-in-inventory.png) + +## How to set first-hand purchase requirement with a price in Uniqs + +We will now cover the usage of `Purchase option with Uniqs` when creating a purchase option. This option allows you to require a payment to be done using Uniqs from other factories or to simply require a user to own a Uniq from a specific factory. + +First, navigate to [Factory management actions](https://toolkit.ultra.io/factoryManagement), search again for `setprchsreq`, and select the `Set first-hand purchase requirement (eosio.nft.ft::setprchsreq.b)` action. + +To specify the price in Uniqs you use the `Purchase option with Uniqs` field. You can add multiple entries to this field, each field corresponds to a single factory. Here is a breakdown for each of the fields: + +- **Transfer tokens receiver account** - The account that will receive the Uniqs from the factories that use the strategy of 2 (transfer). This field is mandatory to specify if any of the factories use the strategy of 2 (transfer). +- **Required factories** - The list of factories required for this purchase option. Each one of them has the following fields: + - **Token factory ID** - The ID of the factory that is required for this purchase option. + - **Count** - How many Uniqs are required from the specified factory. Note that there is no way to specify any properties of the required Uniq, as long as it is from required factory it will work. + - **Strategy** - There are 3 ways you can require Uniqs within your purchase option: + - Check if account owns a Uniq from a specific factory (strategy 0) + - Burn required Uniqs (strategy 1) + - Transfer a Uniq from the owner to the account specified in `Transfer tokens receiver account` (strategy 2) + +For more details see the [action documentation](../../../blockchain/contracts/nft-contract/nft-actions/setprchsreq.b.md). + +In the following example we will configure a purchase option to burn a single Uniq in order to mint another one. This effectively swaps user's Uniq from one to another. The price will be set to 0 UOS so the only requirement is to have a Uniq from the specified factory. + +This effectively achieves a swap mechanism where you "swap" one Uniq which you have for another one from the same or different factory and, potentially, a different metadata. + +If you want to try and do the same you need to have a second factory or use the same one you already have. Note that if you reuse the same factory which does not have variants then it is effectively a useless operation as you will get a Uniq identical to the one you have burned. + +![](./images/first-hand-purchase-price-in-Uniqs.png) + +After filling out the form, click on `Send 1 Action`, review the details, and confirm the transaction. + +You can now navigate to [Factory explorer](https://toolkit.ultra.io/uniqFactory), enter your Factory ID, and scroll down to see the new purchase option created. + +![](./images/first-hand-purchase-price-in-Uniqs-result.png) + +## How to buy a Uniq using a first-hand purchase option with price in Uniqs + +The process of purchasing Uniq using the purchase option with Uniqs requirement is similar, but requires you to fill the `Provided Uniqs field`. + +To do so, first navigate to [Factory management actions](https://toolkit.ultra.io/factoryManagement), and search again for `purchase` and select `Purchase Uniqs directly (eosio.nft.ft::purchase.a)`. + +If the purchase option requires Uniqs from other factories then the account must have those Uniqs in its inventory. If you need to mint this Uniq then either refer to a [How to mint a Uniq using the Ultra Toolkit](../creating-uniq-factories/how-to-mint-uniq-using-toolkit.md) guide or add add a simple first-hand purchase option with UOS price to this factory and purchase it, as was described in this guide. + +Here we minted a Uniq from factory 4030, which was specified in the previous step as a requirement for the purchase option with index 1. + +![](./images/first-hand-purchase-required-Uniq-to-burn.png) + +Once you have the Uniq from the factory you specified in the purchase requirement, you will need to fill the `Provided user Uniqs` field. + +- **Uniqs** - The list of Uniqs you provide to satisfy the purchase requirement. Note that the number of Uniqs should match the sum of all counts specified in purchase requirement. Providing more Uniqs will result in error. + - **Uniq ID** - The ID of the Uniq you provide. It must be a Uniq the `Buyer` account owns. + - **Strategy** - Determines what will happen to the Uniq and it must be identical to the one specified in the purchase requirement. This ensures the fact that you agree that this Uniq will be checked, burned, or transferred. + +In this example we only need to provide a single Uniq and specify the strategy 1 (burn). + +![](./images/first-hand-purchase-purchase-with-burn.png) + +After clicking on `Send 1 Action`, reviewing the details, and confirming the transaction, you should be able to see your new Uniq in your [inventory](https://toolkit.ultra.io/user), as expected. + +![](./images/first-hand-purchase-Uniq-purchased-after-burn.png) + +## How to delete a first-hand purchase option + +If the purchase option you created is no longer needed, you can decide to remove it and get a UOS refund for the RAM payment made during the option creation. + +To delete a purchase option, navigate to [Factory management actions](https://toolkit.ultra.io/factoryManagement), and search again for `delprchsreq.a` and select `Delete first-hand purchase requirement (eosio.nft.ft::delprchsreq.a)`. + +![](./images/first-hand-purchase-delete-search.png) + +There are only a couple of fields you need to fill. For more details, refer to [action documentation](../../../blockchain/contracts/nft-contract/nft-actions/delprchsreq.a.md). + +- **Token factory ID** - The ID of the Uniq factory where the purchase option was first added. +- **Purchase option index** - The index of the existing purchase option. +- **Memo** - Simple text message that can be used for various purposes. Does not affect the result of the transaction. Optional, can leave it empty. + +![](./images/first-hand-purchase-delete-form.png) + +Click on `Send 1 Action`, review the details, and confirm your transaction. + +You can now navigate to [Factory explorer](https://toolkit.ultra.io/uniqFactory), enter your Factory ID. After scrolling down, you will see that the option has been deleted. In this example we have deleted the purchase option with index 1. + +![](./images/first-hand-purchase-delete-result.png) + diff --git a/docs/tutorials/uniq-factories/factory-management/how-to-perform-advanced-actions-with-uniqs-and-factories.md b/docs/tutorials/uniq-factories/factory-management/how-to-perform-advanced-actions-with-uniqs-and-factories.md index 4168772918..bc8705c254 100644 --- a/docs/tutorials/uniq-factories/factory-management/how-to-perform-advanced-actions-with-uniqs-and-factories.md +++ b/docs/tutorials/uniq-factories/factory-management/how-to-perform-advanced-actions-with-uniqs-and-factories.md @@ -1,149 +1,24 @@ --- -title: 'How to perform advanced actions with Uniqs and Factories' -order: 4 +title: 'How to perform advanced actions with Uniqs and Factories using Ultra Toolkit' +order: 1 outline: [0, 4] --- # How to perform advanced actions with Uniqs and Factories -After you have successfully created a factory and potentially minted some tokens, you may now want to check what else can you potentially do. +After you have successfully created a factory and minted some Uniqs, you may now want to check what else you can do potentially. -This guide will cover advanced actions that apply to Uniqs and Factories using the Ultra Toolkit. +This guide will cover some advanced actions that apply to Uniqs and Factories using the Ultra Toolkit. ## Prerequisites -- Created a Uniq Factory. Follow the [Factory creation guide](../creating-uniq-factories/how-to-create-uniq-metadata.md) for details. +- Created a Uniq Factory and minted some Uniqs. Follow the [Factory creation guide](../creating-uniq-factories/how-to-create-uniq-metadata.md) and the [Uniq minting guide](../creating-uniq-factories/how-to-mint-uniq-using-toolkit.md) for details. - Your account must have sufficient UOS tokens for transactions and fees. If you don't have tokens, see [how to use Faucet](../../fundamentals/tutorial-obtain-token-and-purchase-ram.md) for Testnet or [how to buy UOS](../../guides/how-to-buy-uos.md) for Mainnet. - A developer account on the Ultra Testnet or Mainnet and to be logged into the Ultra Toolkit. If you don't have it, please follow our previous tutorial: [Tutorial - Log in to the Ultra Toolkit](../../fundamentals/tutorial-login-to-toolkit.md). ## Goal -The goal of this guide is to demonstrate the range of actions you can perform with your Uniqs and Factories using Ultra Toolkit. This includes the process of adding or removing a direct purchase from your Factory; transferring and burning Uniqs; adding authorized minters. - -## How to add first-hand purchase to your factory - -First-hand purchase is a feature of NFT contract that allows factory managers to add a purchase option so that users can directly mint Uniqs themselves while paying some UOS or USD fee, or by potentially burning or transferring Uniqs. You can also require user to own some specific Uniq in order to use the purchase option. - -You can see the list of potential use cases of this feature on the dedicated [Factory Purchase Options](../factory-management/factory-purchase-options.md) page. - -To create a simple purchase option first navigate to [Factory management actions](https://toolkit.ultra.io/factoryManagement) and search for `setprchsreq`. - -![](./images/first-hand-purchase-search-setprchsreq.png) - -After finding it, select `Set first-hand purchase requirement (eosio.nft.ft::setprchsreq.b)` action. - -There are multiple fields, here we will provide a short breakdown for each of them. For more details refer to [action documentation](../../../blockchain/contracts/nft-contract/nft-actions/setprchsreq.b.md). - -- **Token factory ID** - The ID of the token factory you manage and want to modify. You must be a manager of that factory -- **Purchase option index** - A number that will let you identify the purchase option, in case there are multiple options per factory. It can be any positive number you want, we advise you to start from 0 and increase it by one for any new purchase option you add. Note that if you set the purchase requirement with an existing index then it will overwrite it. -- **Purchase price** - Required payment in UOS or USD (will be converted to UOS at the time of purchase) to be able to purchase a Uniq. It can also be set to 0 but only if the `Purchase option with Uniqs` is set. -- **Purchase limit** - Dictates the maximum number of Uniqs that can be bought using this option specifically. The limit is not shared between the options. If you need to have a total cap then you better manage it though the minting limit of the factory. Optional, can leave it empty. -- **Promoter basis point** - A share of UOS that a promoter will get at the time of purchase, specified in basis points. Must be at least 200 (which is equal to 2%). -- **Purchase option with Uniqs** - Allows you to specify the price for this purchase option using Uniqs from other factories or to require the buyer to own Uniqs from specific factories. This field is covered in more detail in the later example in this guide. -- **Sale shares** - Specifies the list of accounts who will get a share of UOS from the purchase done using this purchase option. The `Basis points` field determines how much the account will get, specified in basis points (1 point = 0.01%). Optional, can leave it empty. -- **Maximum UOS payment** - The maximum amount of UOS you are ok to pay to create the purchase option. The payment is only used to cover RAM costs and is predictable. Optional, can leave it empty. -- **Group restriction** - Allows you to specify user groups who are able or not able to use this purchase option. Refer to [action documentation](../../../blockchain/contracts/nft-contract/nft-actions/setprchsreq.b.md) for a deeper explanation on how to use the user group restriction. Optional, can leave it empty. -- **Purchase window start** - Makes it so the purchase option is only available starting at some point in time in the format of `2021-05-01T00:00:00`. Optional, can leave it empty. -- **Purchase window end** - Makes it so the purchase option is only available until some point in time in the format of `2021-05-01T00:00:00`. Optional, can leave it empty. -- **Memo** - Simple text message that can be used for various purposes. Does not affect the result of the transaction. Optional, can leave it empty. - -![](./images/first-hand-purchase-simple-UOS-price.png) - -Click on `Send 1 Action`, review the details, and confirm your transaction. - -You can now navigate to [Factory explorer](https://toolkit.ultra.io/uniqFactory), enter your Factory ID. After scrolling down you will see the newly added purchase option. - -![](./images/first-hand-purchase-simple-UOS-price-result.png) - -## How to buy a Uniq using a first-hand purchase option - -To purchase a Uniq directly using the new purchase option navigate to [Factory management actions](https://toolkit.ultra.io/factoryManagement). - -Search for `purchase` and select `Purchase Uniqs directly (eosio.nft.ft::purchase.a)`. - -![](./images/first-hand-purchase-search-purchase.png) - -Now you need to fill the action form. There are multiple fields that you need to fill and here we will provide a short breakdown for each one of them. - -- **Token factory ID** - The ID of the factory from which you want to purchase a Uniq. -- **Index** - Purchase option index that was specified in `setprchsreq.b` action. -- **Maximum UOS payment** - Maximum amount of UOS that you are willing to use for this purchase. It must be at least equal to the current price of the purchase option converted to UOS (in case it is originally specified in USD). You can put a larger value here but you will not be charged more than the current price at the time the transaction is executed. If the price of the purchase option is already in UOS then you can use the same value here. -- **Buyer** - The account that signs a transaction and who will pay the required amount of UOS and, if required, the Uniqs needed for this purchase option. -- **Receiver** - The account that will get the Uniq after the purchase is done. It can be the same as the `Buyer` in most cases. -- **Promoter** - The account that will get a share of UOS from this purchase. If you are building a marketplace you would want to specify your account as a promoter to receive a share of UOS from each purchase. If not specified then Ultra will be used as a promoter. -- **Provided Uniqs** - The list of Uniqs that you want to check, burn, or transfer. This is required if the purchase option specifies `Purchase option with Uniqs`. The example on how to fill this field will be provided later in this guide. -- **Memo** - Simple text message that can be used for various purposes. Does not affect the result of the transaction. Optional, can leave it empty. - -For more details see the [action documentation](../../../blockchain/contracts/nft-contract/nft-actions/purchase.a.md). - -![](./images/first-hand-purchase-purchase-simple-UOS-price.png) - -After you have filled the form, click on `Send 1 Action`, review the details, and confirm the transaction. - -Now you should be able to navigate to your inventory (either click on the `Inventory` on the hope page of the Toolkit https://toolkit.ultra.io/ or go to https://toolkit.ultra.io/user and enter desired account name manually). - -You should be able to scroll down and see the list of Uniqs the account has. Note that it may take a minute for Ultra API to update and show your Uniq. - -![](./images/first-hand-purchase-Uniq-in-inventory.png) - -## How to set first-hand purchase requirement with a price in Uniqs - -We will now cover the usage of `Purchase option with Uniqs` when creating a purchase option. This option allows you to require a payment to be done using Uniqs from other factories or to simply require a user to own a Uniq from a specific factory. - -First, navigate to [Factory management actions](https://toolkit.ultra.io/factoryManagement), search again for `setprchsreq`, and select the `Set first-hand purchase requirement (eosio.nft.ft::setprchsreq.b)` action. - -To specify the price in Uniqs you use the `Purchase option with Uniqs` field. You can add multiple entries to this field, each field corresponds to a single factory. Here is a breakdown for each of the fields: - -- **Transfer tokens receiver account** - The account that will receive the Uniqs from the factories that use the strategy of 2 (transfer). This field is mandatory to specify if any of the factories use the strategy of 2 (transfer). -- **Required factories** - The list of factories required for this purchase option. Each one of them has the following fields: - - **Token factory ID** - The ID of the factory that is required for this purchase option. - - **Count** - How many Uniqs are required from the specified factory. Note that there is no way to specify any properties of the required Uniq, as long as it is from required factory it will work. - - **Strategy** - There are 3 ways you can require Uniqs within your purchase option: - - Check if account owns a Uniq from a specific factory (strategy 0) - - Burn required Uniqs (strategy 1) - - Transfer a Uniq from the owner to the account specified in `Transfer tokens receiver account` (strategy 2) - -For more details see the [action documentation](../../../blockchain/contracts/nft-contract/nft-actions/setprchsreq.b.md). - -In the following example we will configure a purchase option to burn a single Uniq will to mint another one. This effectively swaps user's Uniq from one to another. The price will be set to 0 UOS so the only requirement is to have a Uniq from the specified factory. - -This effectively achieves a swap mechanism where you "swap" one Uniq which you have for another one from the same or different factory and, potentially, a different metadata. - -If you want to try and do the same you need to have a second factory or use the same one you already have. Note that if you reuse the same factory which does not have variants then it is effectively a useless operation as you will get a Uniq identical to the one you have burned. - -![](./images/first-hand-purchase-price-in-Uniqs.png) - -After filling out the form, click on `Send 1 Action`, review the details, and confirm the transaction. - -You can now navigate to [Factory explorer](https://toolkit.ultra.io/uniqFactory), enter your Factory ID, and scroll down to see the new purchase option created. - -![](./images/first-hand-purchase-price-in-Uniqs-result.png) - -## How to buy a Uniq using a first-hand purchase option with price in Uniqs - -The process of purchasing Uniq using the purchase option with Uniqs requirement is similar, but requires you to fill the `Provided Uniqs field`. - -To do so, first navigate to [Factory management actions](https://toolkit.ultra.io/factoryManagement), and search again for `purchase` and select `Purchase Uniqs directly (eosio.nft.ft::purchase.a)`. - -If the purchase option requires Uniqs from other factories then the account must have those Uniqs in its inventory. If you need to mint this Uniq then either refer to a [How to mint a Uniq using the Ultra Toolkit](../creating-uniq-factories/how-to-mint-uniq-using-toolkit.md) guide or add add a simple first-hand purchase option with UOS price to this factory and purchase it, as was described in this guide. - -Here we minted a Uniq from factory 4030, which was specified in the previous step as a requirement for the purchase option with index 1. - -![](./images/first-hand-purchase-required-Uniq-to-burn.png) - -Once you have the Uniq from the factory you specified in the purchase requirement, you will need to fill the `Provided user Uniqs` field. - -- **Uniqs** - The list of Uniqs you provide to satisfy the purchase requirement. Note that the number of Uniqs should match the sum of all counts specified in purchase requirement. Providing more Uniqs will result in error. - - **Uniq ID** - The ID of the Uniq you provide. It must be a Uniq the `Buyer` account owns. - - **Strategy** - Determines what will happen to the Uniq and it must be identical to the one specified in the purchase requirement. This ensures the fact that you agree that this Uniq will be checked, burned, or transferred. - -In this example we only need to provide a single Uniq and specify the strategy 1 (burn). - -![](./images/first-hand-purchase-purchase-with-burn.png) - -After clicking on `Send 1 Action`, reviewing the details, and confirming the transaction, you should be able to see your new Uniq in your [inventory](https://toolkit.ultra.io/user), as expected. - -![](./images/first-hand-purchase-Uniq-purchased-after-burn.png) +The goal of this guide is to demonstrate the usage of some of the actions you can perform with your Uniqs and Factories using Ultra Toolkit. This includes the transferring and burning Uniqs; adding authorized minters to a factory. ## How to transfer a Uniq to another account @@ -217,4 +92,4 @@ After clicking on `Send 1 Action`, reviewing the details, and confirming the tra ## What's next? -TBA +- [How to add a first-hand purchase options using Ultra Toolkit](../factory-management/how-to-add-first-hand-purchase-using-toolkit.md) diff --git a/docs/tutorials/uniq-factories/factory-management/images/first-hand-purchase-delete-form.png b/docs/tutorials/uniq-factories/factory-management/images/first-hand-purchase-delete-form.png new file mode 100644 index 0000000000..dff851e455 Binary files /dev/null and b/docs/tutorials/uniq-factories/factory-management/images/first-hand-purchase-delete-form.png differ diff --git a/docs/tutorials/uniq-factories/factory-management/images/first-hand-purchase-delete-result.png b/docs/tutorials/uniq-factories/factory-management/images/first-hand-purchase-delete-result.png new file mode 100644 index 0000000000..983eea2fb3 Binary files /dev/null and b/docs/tutorials/uniq-factories/factory-management/images/first-hand-purchase-delete-result.png differ diff --git a/docs/tutorials/uniq-factories/factory-management/images/first-hand-purchase-delete-search.png b/docs/tutorials/uniq-factories/factory-management/images/first-hand-purchase-delete-search.png new file mode 100644 index 0000000000..792d08dbcf Binary files /dev/null and b/docs/tutorials/uniq-factories/factory-management/images/first-hand-purchase-delete-search.png differ diff --git a/docs/tutorials/uniq-factories/factory-management/uniq-first-hand-purchase-example-project.md b/docs/tutorials/uniq-factories/factory-management/uniq-first-hand-purchase-example-project.md index 81d59f3c1a..9174e68e0b 100644 --- a/docs/tutorials/uniq-factories/factory-management/uniq-first-hand-purchase-example-project.md +++ b/docs/tutorials/uniq-factories/factory-management/uniq-first-hand-purchase-example-project.md @@ -1,7 +1,7 @@ --- title: 'Uniq First-Hand Purchase Example Project' -order: 4 +order: 6 ---