Protocol Module

The Protocol Module is the foundation of the Cart.fun ecosystem, serving as the root authority that controls protocol-wide settings, fee management, feature enablement, and treasury operations. It establishes the governance framework for all platform and marketplace activities.

Overview

The Protocol Module is the core component of the Cart.fun infrastructure, providing essential functionality for the entire ecosystem. It is responsible for:

  • Managing global protocol settings such as fees and features
  • Handling treasury operations for fee collection and distribution
  • Controlling protocol upgrades and maintenance
  • Providing registry services for platforms and marketplaces
  • Establishing the security model for the entire protocol

The Protocol Module must be initialized before any other modules can be used in the Cart.fun ecosystem.

Account Structure

The Protocol Module consists of several key account structures that store critical data for the protocol's operation.

Protocol Account

The Protocol account is a Program Derived Address (PDA) that stores the core protocol configuration:

pub struct Protocol {
    pub authority: Pubkey,         // 32 bytes - Protocol administrator
    pub fee_basis_points: u16,     // 2 bytes - Protocol fee percentage (in basis points, 100 = 1%)
    pub treasury: Pubkey,          // 32 bytes - Protocol treasury account
    pub is_active: bool,           // 1 byte - Protocol activation state
    pub total_volume: u64,         // 8 bytes - Total transaction volume processed
    pub total_platforms: u32,      // 4 bytes - Number of platforms registered
    pub supported_features: ProtocolFeatures, // Variable - Feature flags
    pub bump: u8,                  // 1 byte - PDA bump seed
}

Treasury Account

The Treasury account is a PDA that manages protocol fee collection and distribution:

pub struct Treasury {
    pub authority: Pubkey,         // 32 bytes - Protocol 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
}

Protocol Features

The Protocol supports a wide range of marketplace features through a feature flag system:

pub struct ProtocolFeatures {
    pub supports_nft_marketplaces: bool,
    pub supports_subscriptions: bool,
    pub supports_token_gating: bool,
    pub supports_auctions: bool,
    pub supports_dynamic_pricing: bool,
    pub supports_ai_integration: bool,
    pub supports_rental_markets: bool,
    pub supports_loyalty_programs: bool,
    pub reserved: [bool; 24],      // Reserved for future features
}

Key Functions

The Protocol Module provides the following key functions:

  • Name
    initialize_protocol
    Type
    instruction
    Description

    Initializes the Protocol module with the specified settings.

  • Name
    update_protocol_settings
    Type
    instruction
    Description

    Updates protocol-wide settings such as fees and feature flags.

  • Name
    collect_fees
    Type
    instruction
    Description

    Collects fees from transactions and deposits them in the treasury.

  • Name
    withdraw_from_treasury
    Type
    instruction
    Description

    Allows the protocol authority to withdraw funds from the treasury.

  • Name
    register_platform
    Type
    instruction
    Description

    Registers a new platform in the protocol registry.

  • Name
    toggle_protocol_status
    Type
    instruction
    Description

    Activates or deactivates the entire protocol.

  • Name
    upgrade_protocol
    Type
    instruction
    Description

    Performs a protocol upgrade to a new program version.

Security Model

The Protocol Module implements a hierarchical security model with the following key principles:

  1. Authority-Based Access Control - Critical operations can only be performed by the protocol authority
  2. PDA-Based Derivations - All accounts use PDA derivation to ensure uniqueness and security
  3. Treasury Isolation - Treasury funds are managed through separate PDAs to isolate financial operations
  4. Feature-Based Access - Features can be selectively enabled or disabled without affecting other components
  5. Withdrawal Limits - Treasury withdrawals may be subject to time-based and amount-based limits

For a comprehensive description of the security model, see the Protocol Security Model documentation.

Usage Examples

Initializing the Protocol

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

async function initializeProtocol() {
  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,
  })

  const { transaction } = await cartProtocol.protocol.initialize({
    feeBasisPoints: 100, // 1% protocol fee
    supportedFeatures: {
      supportsNftMarketplaces: true,
      supportsSubscriptions: true,
      supportsTokenGating: true,
      // Other features...
    },
  })

  const signature = await cartProtocol.sendAndConfirmTransaction(transaction)
  console.log('Protocol initialized:', signature)
}

Managing Protocol Fees

async function updateProtocolFees() {
  // Assuming cartProtocol is already initialized with admin wallet

  const { transaction } = await cartProtocol.protocol.updateFees({
    feeBasisPoints: 150, // 1.5% protocol fee
  })

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

For more examples and detailed information, refer to the following resources:

Was this page helpful?