Critter‐Craft Universe Wiki: Marketplace (pallet‐marketplace) - BigBossBoolingB/CritterCraftUniverse GitHub Wiki

Wiki: Marketplace (pallet-marketplace) Document ID: PAL-MKT-001 Status: Finalized Architect: Josephis K. Wade

  1. Overview The pallet-marketplace is a core gameplay module responsible for facilitating the peer-to-peer exchange of CritterCraft assets. Initially, it will support the listing and purchasing of PetNfts using the native $PTCN token. The architecture is designed to be extensible for future item trading.

  2. Pallet Dependencies pallet-nft: To verify ownership and handle the transfer of PetNfts.

pallet-balances: To handle the transfer of $PTCN between buyer, seller, and the treasury.

  1. Storage Listings<ListingId, ListingDetails>

Type: StorageMap

Key: ListingId (a u128)

Value: ListingDetails struct

Description: Stores the details of every active listing on the marketplace.

NextListingId

Type: StorageValue

Value: ListingId (u128)

Description: A simple counter to ensure every new listing receives a unique ID.

MarketplaceFee

Type: StorageValue

Value: Permill (a percentage, e.g., 2.5% would be Permill::from_percent(2.5))

Description: The commission fee taken by the marketplace on every sale. Can be updated via governance.

  1. Structs // Conceptual Rust struct for clarity

#[derive(Encode, Decode, Clone, PartialEq, Eq, TypeInfo)] pub struct ListingDetails<AccountId, Balance> { /// The account that created the listing. pub seller: AccountId, /// The ID of the PetNFT being sold. pub nft_id: u128, /// The asking price in PTCN. pub price: Balance, /// The block number when the listing was created. pub created_block: BlockNumber, }

  1. Dispatchable Functions (Extrinsics) list_pet(origin, nft_id: u128, price: Balance)

Description: Creates a new listing for a PetNFT.

Logic:

Verify origin is a signed transaction.

Check that origin is the owner of nft_id by querying pallet-nft.

Ensure the price is greater than zero.

Transfer ownership of the nft_id from the seller to the pallet-marketplace's account ID (escrow).

Generate a new ListingId.

Create a ListingDetails struct and store it in Listings.

Emit a PetListed event.

cancel_listing(origin, listing_id: u128)

Description: Allows a seller to cancel their active listing.

Logic:

Verify origin is a signed transaction.

Retrieve the listing from Listings. Ensure it exists.

Verify that origin is the seller of the listing.

Transfer the escrowed nft_id back to the seller.

Remove the listing from Listings.

Emit a ListingCancelled event.

buy_pet(origin, listing_id: u128)

Description: Allows a user to purchase a listed PetNFT.

Logic:

Verify origin is a signed transaction (the buyer).

Retrieve the listing from Listings. Ensure it exists.

Ensure the buyer is not the seller.

Check that the buyer has sufficient PTCN balance to afford the price.

Calculate the marketplace fee.

Transfer price from buyer to seller (minus the fee).

Transfer the fee amount from buyer to the Treasury/Burn address as per the economic model.

Transfer the escrowed nft_id to the buyer.

Remove the listing from Listings.

Emit a PetSold event.

  1. Events PetListed(seller: AccountId, nft_id: u128, price: Balance)

ListingCancelled(listing_id: u128, seller: AccountId)

PetSold(listing_id: u128, buyer: AccountId, seller: AccountId, price: Balance)