Update gated-marketplace pallet documentation

Author: didiermis

pallets/gated-marketplace/README.md

@@ -49,6 +49,7 @@ This module allows to:
 - Enroll or reject applicants to your marketplace.
 - Add or remove users as supported authorities to your marketplace, like administrators and/or asset appraisers
 - WIP: Assign a rating to assets as an Appraiser.
+- Create sell or buy orders. Users can bid on the item if they don't like the sale price.  
 
 ### Terminology
 - **Authority**: Refers to any user that has special faculties within the marketplace, like enroll new users or grade assets.
@@ -60,6 +61,8 @@ This module allows to:
 - **Enroll**: When enrolled, the user's application becomes approved, gaining the ability to sell and buy assets.
 - **Reject**: If the user gets rejected, its application becomes rejected and won't have access to the marketplace.
 - **Custodian**: When submitting an application, the user can optionally specify a third account that will have access to the confidential documents. A custodian doesn't need to be an authority nor being part of the marketplace.
+- **Sell order**: The owner of the item creates sales offer fot the item.
+- **Buy order**: Users from the marketplace can bid for the item.
 
 ## Interface
 
@@ -72,16 +75,28 @@ This module allows to:
 - `remove_authority` is only callable by the marketplace owner or administrator. Removes the authority enforcer from the marketplace. The marketplace owner cannot be removed and the administrator cannot remove itself.
 - `update_label_marketplace`  is only callable by the marketplace owner or administrator. Changes the marketplace label. If the new label already exists, the old name won't be changed.
 - `remove_marketplace`  is only callable by the marketplace owner or administrator. This action allows the user to remove a marketplace as well as all the information related to this marketplace.
+- `enlist_sell_offer` is only callable by the owner of the item. It allows the user to sell an item in the selected marketplace. 
+- `take_sell_offer` any user interested to buy the item can call this extrinsic. User must have enough balance to buy it. When the transaction is completed, the item ownership is transferred to the buyer. 
+- `duplicate_offer` allows the owner of the item to duplicate an sell order in any marketplace. 
+- `remove_offer` is only callable by the creator of the offer, it deletes any offer type from all the storages.
+- `enlist_buy_offer` is callable by any market participant, the owner of the item can't create buy orders for their own items.  User must have the enough balance to call it. 
+- `take_buy_offer` is only callable by the owner of the item. If the owner accepts the offer, the buyer must have enough balance to finalize the transaction. 
 
 
 ### Getters
-- `marketplaces`
-- `marketplaces_by_authority` (double storage map)
-- `authorities_by_marketplace` (double storage map)
-- `applications` 
-- `applications_by_account` (double storage map)
-- `applicants_by_marketplace` (double storage map)
-- `custodians` (double storage map)
+|Name| Type |
+|--|--|
+|`marketplaces`| storage map|
+|`marketplaces_by_authority`|double storage map|
+|`authorities_by_marketplace`|double storage map|
+|`applications`| storage map|
+|`applications_by_account`|double storage map|
+|`applicants_by_marketplace`|double storage map|
+|`custodians`|double storage map|
+|`offers_info` |storage map|
+|`offers_by_item`|double storage map|
+|`offers_by_account`|storage map|
+|`offers_by_marketplace`|storage map|
 
 
 ## Usage
@@ -544,19 +559,34 @@ const removeAuthority = await api.tx.gatedMarketplace.removeAuthority(dave.addre
 
 ```rust
 /// Marketplaces stored. [owner, admin, market_id]
-MarketplaceStored(T::AccountId, T::AccountId, [u8;32]),
+1. MarketplaceStored(T::AccountId, T::AccountId, [u8;32])
+
 /// Application stored on the specified marketplace. [application_id, market_id]
-ApplicationStored([u8;32], [u8;32]),
+2. ApplicationStored([u8;32], [u8;32])
+
 /// An applicant was accepted or rejected on the marketplace. [AccountOrApplication, market_id, status]
-ApplicationProcessed(AccountOrApplication<T>,[u8;32], ApplicationStatus),
+3. ApplicationProcessed(AccountOrApplication<T>,[u8;32], ApplicationStatus)
+
 /// Add a new authority to the selected marketplace
-AuthorityAdded(T::AccountId, MarketplaceAuthority),
+4. AuthorityAdded(T::AccountId, MarketplaceAuthority)
+
 /// Remove the selected authority from the selected marketplace
-AuthorityRemoved(T::AccountId, MarketplaceAuthority),
+5. AuthorityRemoved(T::AccountId, MarketplaceAuthority)
+
 /// The label of the selected marketplace has been updated. [market_id]
-MarketplaceLabelUpdated([u8;32]),
+6. MarketplaceLabelUpdated([u8;32])
+
 /// The selected marketplace has been removed. [market_id]
-MarketplaceRemoved([u8;32])
+7. MarketplaceRemoved([u8;32])
+
+/// Offer stored. [collection_id, item_id]
+8. OfferStored(T::CollectionId, T::ItemId)
+
+/// Offer was accepted [offer_id, account]
+9. OfferWasAccepted([u8;32], T::AccountId)
+
+/// Offer was duplicated. [new_offer_id, new_marketplace_id]
+10. OfferDuplicated([u8;32], [u8;32])
 ```
 
 ## Errors
@@ -608,4 +638,32 @@ ApplicationIdNotFound,
 ApplicationStatusStillPending,
 /// The application has already been approved, application status is approved
 ApplicationHasAlreadyBeenApproved,
+/// Collection not found
+CollectionNotFound,
+/// User who calls the function is not the owner of the collection
+NotOwner,
+/// Offer already exists
+OfferAlreadyExists,
+/// Offer not found
+OfferNotFound,
+/// Offer is not available at the moment
+OfferIsNotAvailable,
+/// Owner cannnot buy its own offer
+CannotTakeOffer,
+/// User cannot remove the offer from the marketplace
+CannotRemoveOffer,
+/// Error related to the timestamp
+TimestampError,
+/// User does not have enough balance to buy the offer
+NotEnoughBalance,
+/// User cannot delete the offer because is closed
+CannotDeleteOffer,
+/// There was a problem storing the offer
+OfferStorageError,
+/// Price must be greater than zero
+PriceMustBeGreaterThanZero,
+/// User cannot create buy offers for their own items
+CannotCreateOffer,
+/// This items is not available for sale
+ItemNotForSale,
 ```

pallets/gated-marketplace/src/functions.rs

@@ -429,11 +429,13 @@ impl<T: Config> Pallet<T> {
         //ensure marketplace_id exits
         ensure!(<Marketplaces<T>>::contains_key(marketplace_id), Error::<T>::MarketplaceNotFound);
 
-        //ensure the offer_id exists & get the offer data 
-        let copy_offer_data = <OffersInfo<T>>::get(offer_id).ok_or(Error::<T>::OfferNotFound)?;
+        //ensure the offer_id exists
+        ensure!(<OffersInfo<T>>::contains_key(offer_id), Error::<T>::OfferNotFound);
+
 
         // ensure the owner is the same as the authority
-        ensure!(copy_offer_data.creator == authority.clone(), Error::<T>::CannotRemoveOffer);
+        let offer_creator = Self::get_offer_creator(offer_id).map_err(|_| Error::<T>::OfferNotFound)?;
+        ensure!(offer_creator == authority.clone(), Error::<T>::CannotRemoveOffer);
 
         //ensure the offer_id exists in OffersByItem
         Self::does_exist_offer_id_for_this_item(collection_id, item_id, offer_id)?;
@@ -719,6 +721,7 @@ impl<T: Config> Pallet<T> {
 
     fn get_timestamp_in_milliseconds() -> Option<(u64, u64)> {
         let timestamp: <T as pallet_timestamp::Config>::Moment = <pallet_timestamp::Pallet<T>>::get();
+        
         let timestamp2 = Self::convert_moment_to_u64_in_milliseconds(timestamp).unwrap_or(0);
         let timestamp3 = timestamp2 + (7 * 24 * 60 * 60 * 1000);
 
@@ -773,26 +776,6 @@ impl<T: Config> Pallet<T> {
     fn update_offers_status(buyer: T::AccountId, collection_id: T::CollectionId, item_id: T::ItemId, marketplace_id: [u8;32]) -> DispatchResult{
         let offer_ids = <OffersByItem<T>>::try_get(collection_id, item_id).map_err(|_| Error::<T>::OfferNotFound)?;
 
-        //This logic is no longer needed, when an offer_id is accepted, 
-        // all the other offers for this item are automatically closed. 
-        // It doesn't matter the offertype. 
-
-        // let mut sell_offer_ids: BoundedVec<[u8;32], T::MaxOffersPerMarket> = BoundedVec::default();
-
-        // for offer_id in offer_ids {
-        //     let offer_info = <OffersInfo<T>>::get(offer_id).ok_or(Error::<T>::OfferNotFound)?;
-        //     //ensure the offer_type is SellOrder, because this vector also contains offers of BuyOrder OfferType.
-        //     if offer_info.offer_type == OfferType::SellOrder {
-        //         sell_offer_ids.try_push(offer_id).map_err(|_| Error::<T>::OfferStorageError)?;
-        //     }
-        //     // //version 2
-        //     // if let Some(offer) = <OffersInfo<T>>::get(offer_id) {
-        //     //     if offer.offer_type == OfferType::SellOrder {
-        //     //         sell_offer_ids.try_push(offer_id).map_err(|_| Error::<T>::OfferStorageError)?;
-        //     //     }
-        //     // }
-        // }
-        
         for offer_id in offer_ids {
             <OffersInfo<T>>::try_mutate::<_,_,DispatchError,_>(offer_id, |offer|{
                 let offer = offer.as_mut().ok_or(Error::<T>::OfferNotFound)?;

pallets/gated-marketplace/src/lib.rs

@@ -513,6 +513,22 @@ pub mod pallet {
 			Self::do_remove_marketplace(who, marketplace_id)
 		}
 
+		/// Enlist a sell order.
+		/// 
+		/// This extrinsic creates a sell order in the selected marketplace.
+		/// 
+		/// ### Parameters:
+		/// - `origin`: The user who performs the action.
+		/// - `marketplace_id`: The id of the marketplace where we want to create the sell order.
+		/// - `collection_id`: The id of the collection.
+		/// - `item_id`: The id of the item inside the collection.
+		/// - `price`: The price of the item.
+		/// 
+		/// ### Considerations:
+		/// - You can only create a sell order in the marketplace if you are the owner of the item.
+		/// - You can create only one sell order for each item per marketplace.
+		/// - If the selected marketplace doesn't exist, it will throw an error.
+		/// - If the selected collection doesn't exist, it will throw an error.
 		#[transactional]
 		#[pallet::weight(10_000 + T::DbWeight::get().writes(1))]
 		pub fn enlist_sell_offer(origin: OriginFor<T>, marketplace_id: [u8;32], collection_id: T::CollectionId, item_id: T::ItemId, price: BalanceOf<T>,) -> DispatchResult {
@@ -521,6 +537,20 @@ pub mod pallet {
 			Self::do_enlist_sell_offer(who, marketplace_id, collection_id, item_id, price)
 		}
 
+		/// Accepts a sell order.
+		/// 
+		/// This extrinsic accepts a sell order in the selected marketplace.
+		/// 
+		/// ### Parameters:
+		/// - `origin`: The user who performs the action.
+		/// - `marketplace_id`: The id of the marketplace where we want to accept the sell order.
+		/// - `collection_id`: The id of the collection.
+		/// - `item_id`: The id of the item inside the collection.
+		/// 
+		/// ### Considerations:
+		/// - You don't need to be the owner of the item to accept the sell order.
+		/// - Once the sell order is accepted, the ownership of the item is transferred to the buyer.
+		/// - If you don't have the enough balance to accept the sell order, it will throw an error.
 		#[transactional]
 		#[pallet::weight(10_000 + T::DbWeight::get().writes(1))]
 		pub fn take_sell_offer(origin: OriginFor<T>, offer_id: [u8;32], marketplace_id: [u8;32], collection_id: T::CollectionId, item_id: T::ItemId,) -> DispatchResult {
@@ -529,6 +559,20 @@ pub mod pallet {
 			Self::do_take_sell_offer(who, offer_id, marketplace_id, collection_id, item_id)
 		}
 
+		/// Allows a user to duplicate a sell order.
+		/// 
+		/// This extrinsic allows a user to duplicate a sell order in any marketplace.
+		/// 
+		/// ### Parameters:
+		/// - `origin`: The user who performs the action.
+		/// - `marketplace_id`: The id of the marketplace where we want to duplicate the sell order.
+		/// - `collection_id`: The id of the collection.
+		/// - `item_id`: The id of the item inside the collection.
+		/// 
+		/// ### Considerations:
+		/// - You can only duplicate a sell order if you are the owner of the item.
+		/// - The expiration date of the sell order is the same as the original sell order.
+		/// - You can update the price of the sell order.
 		#[transactional]
 		#[pallet::weight(10_000 + T::DbWeight::get().writes(1))]	
 		pub fn duplicate_offer(origin: OriginFor<T>, offer_id: [u8;32], marketplace_id: [u8;32], collection_id: T::CollectionId, item_id: T::ItemId, modified_price: BalanceOf<T>) -> DispatchResult {
@@ -537,6 +581,23 @@ pub mod pallet {
 			Self::do_duplicate_offer(who, offer_id, marketplace_id, collection_id, item_id, modified_price)
 		}	
 
+
+		/// Delete an offer.
+		/// 
+		/// This extrinsic deletes an offer in the selected marketplace.
+		/// 
+		/// ### Parameters:
+		/// - `origin`: The user who performs the action.
+		/// - `marketplace_id`: The id of the marketplace where we want to delete the offer.
+		/// - `collection_id`: The id of the collection.
+		/// - `item_id`: The id of the item inside the collection.
+		/// 
+		/// ### Considerations:
+		/// - You can delete sell orders or buy orders.
+		/// - You can only delete an offer if you are the creator of the offer.
+		/// - Only open offers can be deleted.
+		/// - If you need to delete multiple offers for the same item, you need to 
+		///  delete them one by one.
 		#[transactional]
 		#[pallet::weight(10_000 + T::DbWeight::get().writes(1))]
 		pub fn remove_offer(origin: OriginFor<T>, offer_id: [u8;32], marketplace_id: [u8;32], collection_id: T::CollectionId, item_id: T::ItemId,) -> DispatchResult {
@@ -547,7 +608,21 @@ pub mod pallet {
 			Self::do_remove_offer(who, offer_id, marketplace_id, collection_id, item_id)
 		}
 
-
+		/// Enlist a buy order.
+		/// 
+		/// This extrinsic creates a buy order in the selected marketplace.
+		/// 
+		/// ### Parameters:
+		/// - `origin`: The user who performs the action.
+		/// - `marketplace_id`: The id of the marketplace where we want to create the buy order.
+		/// - `collection_id`: The id of the collection.
+		/// - `item_id`: The id of the item inside the collection.
+		/// - `price`: The price of the item.
+		/// 
+		/// ### Considerations:
+		/// - Any user can create a buy order in the marketplace.
+		/// - An item can receive multiple buy orders at a time.
+		/// - You need to have the enough balance to create the buy order.
 		#[transactional]
 		#[pallet::weight(10_000 + T::DbWeight::get().writes(1))]	
 		pub fn enlist_buy_offer(origin: OriginFor<T>, marketplace_id: [u8;32], collection_id: T::CollectionId, item_id: T::ItemId, price: BalanceOf<T>,) -> DispatchResult {
@@ -556,6 +631,23 @@ pub mod pallet {
 			Self::do_enlist_buy_offer(who, marketplace_id, collection_id, item_id, price)
 		}
 
+
+		/// Accepts a buy order.
+		/// 	
+		/// This extrinsic accepts a buy order in the selected marketplace.
+		/// 
+		/// ### Parameters:
+		/// - `origin`: The user who performs the action.
+		/// - `marketplace_id`: The id of the marketplace where we accept the buy order.
+		/// - `collection_id`: The id of the collection.
+		/// - `item_id`: The id of the item inside the collection.
+		/// 
+		/// ### Considerations:
+		/// - You need to be the owner of the item to accept a buy order.
+		/// - Owner of the item can accept only one buy order at a time.
+		/// - When an offer is accepted, all the other offers for this item are closed.
+		/// - The buyer needs to have the enough balance to accept the buy order.
+		/// - Once the buy order is accepted, the ownership of the item is transferred to the buyer.
 		#[transactional]
 		#[pallet::weight(10_000 + T::DbWeight::get().writes(1))]
 		pub fn take_buy_offer(origin: OriginFor<T>, offer_id: [u8;32], marketplace_id: [u8;32], collection_id: T::CollectionId, item_id: T::ItemId,) -> DispatchResult {