Marketplace Module

The Marketplace Module is a core component of the Cart.fun protocol that enables the creation and management of decentralized marketplaces. It supports both direct protocol-managed marketplaces and platform-managed marketplaces, with various marketplace types and configurable features.

Overview

The Marketplace Module provides a comprehensive framework for creating and operating various types of marketplaces on the Cart.fun protocol. Key capabilities include:

Creating and configuring marketplaces with customized fee structures
Supporting different marketplace types (general, NFT, subscription, etc.)
Managing marketplace-specific treasuries for fee collection
Enabling or disabling specific marketplace features
Tracking marketplace performance metrics
Supporting both protocol-level and platform-level marketplace hierarchies

Marketplaces can be created directly under the Protocol or as part of a Platform. Platform-managed marketplaces have an additional layer of fee distribution.

Account Structure

The Marketplace Module uses several account structures to store marketplace configuration and operational data.

MarketplaceConfig

The primary account that stores marketplace configuration data:

pub struct MarketplaceConfig {
    pub authority: Pubkey,         // 32 bytes - Marketplace administrator
    pub platform: Option<Pubkey>,  // 33 bytes - Optional platform (if platform-managed)
    pub protocol: Pubkey,          // 32 bytes - Reference to the protocol account
    pub fee_basis_points: u16,     // 2 bytes - Marketplace fee percentage (in basis points)
    pub treasury: Pubkey,          // 32 bytes - Marketplace treasury account
    pub metadata: String,          // Variable - Marketplace metadata (name, description, etc.)
    pub marketplace_type: MarketplaceType, // 1 byte - Type of marketplace
    pub hierarchy: MarketplaceHierarchy,   // 1 byte - Protocol or platform managed
    pub features: MarketplaceFeatures,     // Variable - Enabled features
    pub is_active: bool,           // 1 byte - Marketplace activation state
    pub total_volume: u64,         // 8 bytes - Cumulative transaction volume
    pub total_sales: u64,          // 8 bytes - Number of sales
    pub total_vendors: u32,        // 4 bytes - Number of registered vendors
    pub total_products: u32,       // 4 bytes - Number of listed products
    pub bump: u8,                  // 1 byte - PDA bump seed
}

MarketplaceTreasury

The treasury account that manages marketplace fee collection and distribution:

pub struct Treasury {
    pub authority: Pubkey,         // 32 bytes - Marketplace PDA
    pub balance: u64,              // 8 bytes - Current SOL balance
    pub total_collected: u64,      // 8 bytes - Total fees collected
    pub total_withdrawn: u64,      // 8 bytes - Total amount withdrawn
    pub bump: u8,                  // 1 byte - PDA bump seed
}

Marketplace Types

The Marketplace Module supports various marketplace types to accommodate different commerce models:

Name
GeneralMarketplace
Type
enum
Description
Standard marketplace for digital and physical products.
Name
NFTMarketplace
Type
enum
Description
Specialized marketplace for NFT trading and collections.
Name
SubscriptionMarketplace
Type
enum
Description
Recurring payment and subscription-based marketplace.
Name
AuctionMarketplace
Type
enum
Description
Marketplace supporting various auction mechanisms.
Name
TokenGatedMarketplace
Type
enum
Description
Access-controlled marketplace requiring specific tokens for participation.
Name
CustomMarketplace
Type
enum
Description
Special-purpose marketplace with custom logic.

Marketplace Hierarchy

Marketplaces can exist in one of two hierarchical relationships:

Name
ProtocolManaged
Type
enum
Description
Directly managed by the Protocol with fees flowing to the Protocol treasury.
Name
PlatformManaged
Type
enum
Description
Managed by a Platform with fee splits between Platform and Protocol treasuries.

Features

Marketplaces can enable or disable various features based on their business requirements:

Name
supports_nft_listings
Type
boolean
Description
Support for non-fungible token listings and sales.
Name
supports_physical_goods
Type
boolean
Description
Support for physical product listings with shipping information.
Name
supports_subscriptions
Type
boolean
Description
Support for recurring subscription payments.
Name
supports_auctions
Type
boolean
Description
Support for auction-based sales formats.
Name
supports_token_gating
Type
boolean
Description
Support for token-based access controls.
Name
supports_ai_integration
Type
boolean
Description
Support for AI-powered recommendations and features.
Name
supports_categories
Type
boolean
Description
Support for product categorization and taxonomy.
Name
supports_reviews
Type
boolean
Description
Support for product and vendor reviews.

Instructions

The Marketplace Module provides these key instructions:

Name
create_marketplace
Type
instruction
Description
Creates a new marketplace with specified configuration.
Name
update_marketplace
Type
instruction
Description
Updates marketplace settings and configuration.
Name
toggle_marketplace_feature
Type
instruction
Description
Enables or disables specific marketplace features.
Name
withdraw_from_treasury
Type
instruction
Description
Withdraws funds from the marketplace treasury.
Name
register_vendor
Type
instruction
Description
Registers a vendor in the marketplace.
Name
create_listing
Type
instruction
Description
Creates a new product listing in the marketplace.
Name
transfer_marketplace_ownership
Type
instruction
Description
Transfers marketplace administration rights.
Name
close_marketplace
Type
instruction
Description
Closes a marketplace and recovers resources.

Usage Examples

Creating a Marketplace

import { Connection, Keypair } from '@solana/web3.js'
import { CartProtocol, NetworkType, MarketplaceType } from '@cartdotfun/sdk'

async function createMarketplace() {
  const connection = new Connection(
    'https://api.devnet.solana.com',
    'confirmed',
  )
  const adminWallet = Keypair.fromSecretKey(/* your secret key */)

  const cartProtocol = new CartProtocol({
    connection,
    wallet: adminWallet,
    network: NetworkType.Devnet,
  })

  // For a platform-managed marketplace
  const { transaction, marketplaceId } =
    await cartProtocol.marketplace.createMarketplace({
      platformId: 'your-platform-id', // Optional: Remove for protocol-managed marketplace
      name: 'Digital Art Gallery',
      description: 'Premium marketplace for digital art and collectibles',
      marketplaceType: MarketplaceType.NFTMarketplace,
      feeBasisPoints: 250, // 2.5% marketplace fee
      categories: ['art', 'illustration', 'photography', '3d'],
      features: {
        supportsNftListings: true,
        supportsAuctions: true,
        supportsTokenGating: true,
        supportsAiIntegration: true,
        supportsCategories: true,
        supportsReviews: true,
      },
    })

  const signature = await cartProtocol.sendAndConfirmTransaction(transaction)
  console.log('Marketplace created:', signature)
  console.log('Marketplace ID:', marketplaceId)

  return { marketplaceId, signature }
}

Managing Marketplace Features

async function toggleMarketplaceFeatures(marketplaceId) {
  // Enable auction support on an existing marketplace
  const { transaction } = await cartProtocol.marketplace.toggleFeature({
    marketplaceId,
    feature: 'supportsAuctions',
    enabled: true,
  })

  const signature = await cartProtocol.sendAndConfirmTransaction(transaction)
  console.log('Feature updated:', signature)

  // Get current marketplace configuration
  const marketplaceConfig =
    await cartProtocol.marketplace.getMarketplace(marketplaceId)
  console.log('Updated features:', marketplaceConfig.features)
}

Retrieving Marketplace Statistics

async function getMarketplaceStats(marketplaceId) {
  // Get marketplace configuration
  const marketplace =
    await cartProtocol.marketplace.getMarketplace(marketplaceId)

  console.log('Marketplace Statistics:')
  console.log('-----------------------')
  console.log(`Total Volume: ${marketplace.totalVolume} SOL`)
  console.log(`Total Sales: ${marketplace.totalSales}`)
  console.log(`Total Vendors: ${marketplace.totalVendors}`)
  console.log(`Total Products: ${marketplace.totalProducts}`)

  // Get recent sales activity
  const recentSales = await cartProtocol.marketplace.getRecentSales(
    marketplaceId,
    10,
  )
  console.log('Recent Sales:', recentSales)

  // Get top vendors by volume
  const topVendors = await cartProtocol.marketplace.getTopVendors(
    marketplaceId,
    5,
  )
  console.log('Top Vendors:', topVendors)
}

For more detailed information about the Marketplace Module, refer to these resources: