Vendor Module

The Vendor Module is a core component of the Cart.fun protocol that enables storefront management on decentralized marketplaces. It allows users to register as vendors (sellers) within a marketplace and manage their store settings, payment options, and product listings.

Overview

The Vendor Module serves as the foundational layer for seller operations in Cart.fun marketplaces. By registering as a vendor, users gain the ability to list products, conduct sales, manage their store presence, and build a reputation within the ecosystem.

Vendors can participate in multiple marketplaces across different platforms, with separate profiles and customizations for each marketplace they join. The module also tracks vendor performance and sales statistics to help with reputation building and store optimization.

To become a vendor, a user must register within a specific marketplace. A user can register as a vendor in multiple marketplaces with different store profiles.

Key Features

Name
Vendor Registration
Type
feature
Description
Users can register as vendors in marketplaces
Name
Store Management
Type
feature
Description
Vendors can customize their storefront with metadata
Name
Payment Settings
Type
feature
Description
Configure accepted payment types and methods
Name
Statistics Tracking
Type
feature
Description
Monitor sales, listings, and performance metrics
Name
Access Control
Type
feature
Description
Integration with marketplace permissions system
Name
Status Management
Type
feature
Description
Control vendor active/inactive status

Core Components

Vendor Account

The primary data structure that stores vendor information:

pub struct Vendor {
    pub owner: Pubkey,            // The vendor's wallet address
    pub store_metadata: String,   // Basic store information
    pub marketplace: Pubkey,      // Reference to parent marketplace
    pub is_active: bool,          // Vendor active status
    pub total_sales: u64,         // Count of completed sales
    pub total_volume: u64,        // Total sales volume in lamports
    pub bump: u8,                 // PDA derivation bump
}

Vendor Metadata

Extended information about the vendor's store:

pub struct VendorMetadata {
    pub name: String,             // Store name
    pub description: String,      // Store description
    pub logo_url: String,         // Store logo URL
    pub banner_url: String,       // Store banner URL
    pub contact_email: String,    // Contact email
    pub social_links: Vec<String>,// Social media links
    pub categories: Vec<String>,  // Store categories
}

Vendor Settings

Configuration options for the vendor's store operations:

pub struct VendorSettings {
    pub accepted_payment_methods: Vec<PaymentMethod>, // Accepted payment methods
    pub auto_accept_orders: bool,         // Automatically accept valid orders
    pub shipping_options: Vec<ShippingOption>, // Available shipping options
    pub notification_preferences: NotificationPreferences, // How to notify vendor
    pub display_options: DisplayOptions,  // Store display preferences
}

Vendor Operations

The Vendor Module supports the following key operations:

Name
register_vendor
Type
instruction
Description
Register a new vendor within a marketplace
Name
update_vendor_metadata
Type
instruction
Description
Update the vendor's store metadata and information
Name
update_vendor_settings
Type
instruction
Description
Change the vendor's operational settings
Name
toggle_vendor_status
Type
instruction
Description
Activate or deactivate a vendor account
Name
get_vendor_products
Type
instruction
Description
Retrieve all products listed by the vendor
Name
get_vendor_sales
Type
instruction
Description
Get the sales history for a vendor
Name
get_vendor_statistics
Type
instruction
Description
Retrieve performance statistics for a vendor

Usage Examples

Registering as a Vendor

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

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

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

  const { transaction, vendorId } = await cartProtocol.vendor.registerVendor({
    marketplaceId,
    name: 'Digital Creations Studio',
    description: 'Premium digital art and collectibles by independent artists',
    contactEmail: 'contact@digitalcreations.example',
    categories: ['art', 'digital', 'collectibles'],
    storeMetadata: {
      logoUrl: 'https://example.com/logo.png',
      bannerUrl: 'https://example.com/banner.png',
      socialLinks: {
        twitter: 'https://twitter.com/digitalcreations',
        instagram: 'https://instagram.com/digitalcreations',
      },
    },
  })

  const signature = await cartProtocol.sendAndConfirmTransaction(transaction)
  console.log('Vendor registered:', signature)
  console.log('Vendor ID:', vendorId)

  return { vendorId, signature }
}

Updating Vendor Profile

async function updateVendorProfile(vendorId) {
  // Assuming cartProtocol is already initialized with vendor wallet

  const { transaction } = await cartProtocol.vendor.updateVendorMetadata({
    vendorId,
    name: 'Digital Creations Studio Pro',
    description:
      'Expanded premium digital art and collectibles by award-winning artists',
    storeMetadata: {
      logoUrl: 'https://example.com/new-logo.png',
      bannerUrl: 'https://example.com/new-banner.png',
      socialLinks: {
        twitter: 'https://twitter.com/digitalcreationspro',
        instagram: 'https://instagram.com/digitalcreationspro',
        discord: 'https://discord.gg/digitalcreations',
      },
    },
  })

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

Getting Vendor Statistics

async function getVendorStats(vendorId) {
  // Fetch vendor statistics
  const stats = await cartProtocol.vendor.getVendorStatistics(vendorId)

  console.log('Vendor Statistics:')
  console.log('-----------------')
  console.log(`Total Sales: ${stats.totalSales}`)
  console.log(`Total Volume: ${stats.totalVolume / 1e9} SOL`)
  console.log(`Average Rating: ${stats.averageRating}`)
  console.log(`Active Listings: ${stats.activeListings}`)
  console.log(`Most Popular Category: ${stats.popularCategory}`)

  // Get recent sales
  const recentSales = await cartProtocol.vendor.getVendorSales(vendorId, 5)
  console.log('Recent Sales:', recentSales)

  // Get best-selling products
  const topProducts = await cartProtocol.vendor.getTopProducts(vendorId, 3)
  console.log('Top Products:', topProducts)
}

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