May CPI Interface

This crate provides the abstract interface for interacting with the Mayflower protocol, a Solana-based automated market maker (AMM) with bonding curve mechanics. It defines the core data structures and Cross-Program Invocation (CPI) interfaces for the protocol.

Account Hierarchy

The Mayflower protocol follows a hierarchical structure for organizing markets and fees:

Tenant (Platform Operator)
    └── MarketGroup (Fee Configuration)
        └── MarketMeta (Market Configuration)
            ├── Market (LinearMarket or MultiCurveMarket)
            └── PersonalPosition (one per user per MarketMeta)

Core Entities

1. Tenant: The top-level platform operator that owns multiple market groups and collects platform fees
2. MarketGroup: A collection of markets sharing the same fee structure and admin
3. MarketMeta: Configuration and metadata for a specific market, linking all associated accounts
4. Market: The actual market implementation with bonding curve and liquidity state
5. PersonalPosition: User-specific account tracking collateral deposits and debt (one per user per MarketMeta)

Key Data Structures

Tenant

• Purpose: Platform-level administration and fee collection
• Key Fields:
  • admin: Platform administrator
  • platform_fee_micro_bps: Platform-wide fee rate (1 micro-bp = 1/100 basis point)
  • permissionless_group_creation: Whether anyone can create market groups

MarketGroup

• Purpose: Groups markets under common fee structure
• Key Fields:
  • tenant: Parent tenant account
  • admin: Group administrator
  • fees: Buy, sell, borrow, and exercise fee rates

MarketMeta

• Purpose: Central configuration hub for a market
• Key Fields:
  • market_group: Parent group
  • market: Associated market implementation
  • mint_main: Base currency (e.g., USDC)
  • mint_token: Market's derivative token
  • mint_options: Option tokens for the market
  • permissions: Bitfield controlling allowed operations
  • dutch_config: Optional Dutch auction price boost

Market (Linear)

• Purpose: Implements a linear bonding curve market
• Key Components:
  • Price Curve: Two-segment linear function
    • Shoulder segment: Steeper slope for early price discovery
    • Tail segment: Gentler slope for bulk liquidity
  • State:
    • token_supply: Total minted tokens
    • total_cash_liquidity: Available backing
    • total_debt: Outstanding borrows
    • total_collateral: Deposited collateral

PersonalPosition

• Purpose: Tracks individual user's collateral and debt
• Key Fields:
  • market_meta: Associated market
  • owner: Position owner
  • deposited_token_balance: Collateral amount
  • debt: Borrowed main tokens
  • escrow: Token account holding collateral

Core Operations

Administrative Operations

Tenant Management

• tenant_init: Initialize a new platform tenant
• tenant_propose_admin: Propose ownership transfer
• tenant_accept_new_admin: Accept ownership
• tenant_change_fee_mbps: Update platform fee rate
• tenant_collect_rev: Collect platform fees

Market Group Management

• market_group_init: Create a new market group
• market_group_propose_admin: Propose group ownership transfer
• market_group_accept_new_admin: Accept group ownership
• market_group_change_fees: Update group fee structure
• market_group_collect_rev: Collect group fees

Market Management

• market_linear_init: Create a linear bonding curve market
• market_linear_init_with_dutch: Create market with Dutch auction
• market_flags_change: Update market permissions
• raise_floor_preserve_area: Increase minimum price while preserving liquidity

User Operations

Trading

• buy_with_exact_cash_in: Purchase tokens with exact payment amount
• sell_with_exact_token_in: Sell exact number of tokens
• redeem_at_floor: Redeem tokens at guaranteed floor price

Collateral & Borrowing

• personal_position_init: Create a personal position account
• deposit: Add tokens as collateral
• withdraw: Remove collateral (if healthy)
• borrow: Take loan against collateral
• repay: Pay back borrowed funds

Options

• mint_options: Create option tokens
• exercise_options: Exercise options to buy at floor price

Combined Operations

• buy_with_exact_cash_in_and_deposit: Buy and immediately deposit as collateral
• sell_with_exact_token_in_after_withdraw: Withdraw collateral and sell

Market Mechanics

Linear Bonding Curve

The LinearMarket implements a three-segment piecewise linear price curve that creates a sophisticated price discovery mechanism:

Curve Structure

The price curve consists of three distinct regions:

1. Floor Region (0 to x1):

   • Constant price at the floor value
   • Provides guaranteed minimum redemption value
   • Protects early investors from downside risk

2. Shoulder Region (x1 to x2):

   • Steeper linear slope (m1) for rapid price discovery
   • Higher price sensitivity to supply changes
   • Encourages initial price establishment

3. Main Region (x2 to infinity):

   • Gentler linear slope (m2) for bulk liquidity
   • More stable pricing for mature markets
   • Lower price volatility as supply grows

Mathematical Parameters

The curve is defined by six key parameters:

• floor: Minimum guaranteed price (constant in floor region)
• x1: End of floor region / start of shoulder (calculated as (floor - b1) / m1)
• x2: End of shoulder region / start of main region
• m1: Slope of shoulder region (steeper, m1 > m2)
• m2: Slope of main region (gentler)
• b1: Y-intercept of shoulder line (calculated as (m2 - m1) * x2 + b2)
• b2: Y-intercept of main line

Price Calculation

The price at any supply level x is determined by:

if x ≤ x1:      price = floor
if x1 < x ≤ x2: price = m1 * x + b1
if x > x2:      price = m2 * x + b2

Area Under Curve (Cash Requirements)

The bonding curve calculates cash requirements for trades using the area under the curve:

• Buying tokens: Requires cash equal to the area from current supply to new supply
• Selling tokens: Returns cash equal to the area from new supply to current supply
• The area_up_to(x) function computes the total area from 0 to x
• The area_between(x1, x2) function computes the area between two supply points

This three-segment design creates:

• Initial price stability through the floor
• Efficient price discovery through the shoulder
• Scalable liquidity through the main region

Floor Raising Mechanism

One of the most powerful features of the Mayflower protocol is the ability to raise the floor price while preserving the liquidity inside the bonding curve. This creates a ratchet effect that permanently increases the minimum token value.

How Floor Raising Works

The floor raising mechanism operates by:

1. Shifting the curve segments forward: When the floor is raised:

   • x1 (floor end) shifts forward by the same amount as x2
   • x2 (shoulder end) moves to a new, higher supply position
   • The curve maintains the same area (liquidity) up to the current supply

2. Preserving area under the curve: The critical innovation is that the total area from 0 to the current supply remains constant. This means:

   • The same amount of liquidity backs the existing token supply
   • No value is created or destroyed, only redistributed
   • Existing token holders benefit from the higher floor without dilution

3. Mathematical transformation:

   • New floor price is set (must be higher than current floor)
   • New x2 position is specified (must be beyond current x2)
   • The curve recalculates x1 as (floor - b1) / m1
   • Y-intercepts (b1, b2) are adjusted to maintain continuity
   • The slopes (m1, m2) remain unchanged

Benefits of Floor Raising

• Permanent value appreciation: Once raised, the floor cannot be lowered, creating a one-way ratchet for minimum value
• Liquidity preservation: All existing liquidity remains in the system, concentrated to support the higher floor
• Price stability: Higher floor reduces downside risk while maintaining upside potential
• Incentive alignment: Benefits long-term holders by increasing minimum redemption value

Trigger Conditions

Floor raising can be triggered when:

• Excess liquidity accumulates beyond what's needed for the current supply
• Market conditions warrant a higher baseline value
• Protocol governance decides to reward token holders
• Specific milestones or metrics are achieved

Safety Checks

The protocol enforces several constraints:

• New floor must be higher than current floor
• New shoulder end must be beyond current shoulder end
• Area tolerance ensures liquidity is preserved within acceptable bounds
• Price tolerance prevents excessive price discontinuities at current supply
• Liquidity ratio checks ensure sufficient backing remains

This mechanism makes Mayflower unique among bonding curve protocols by allowing the curve to evolve upward over time while maintaining mathematical consistency and liquidity guarantees.

Dutch Auction

Optional time-based price boost for new markets:

• Starts with multiplied prices (e.g., 2x)
• Gradually decays to normal pricing
• Incentivizes early participation

Collateralization

Users can deposit market tokens as collateral to:

• Borrow main tokens (e.g., USDC) up to LTV limit
• Maintain positions while accessing liquidity
• Risk liquidation if collateral value drops

Fee Structure

Fees are collected in micro basis points (1 micro-bp = 0.0001%):

• Platform fees: Go to tenant (platform operator)
• Group fees: Go to market group admin
• Fee types:
  • Buy fees: On token purchases
  • Sell fees: On token sales
  • Borrow fees: On loans
  • Exercise fees: On option exercise

Security Features

• Two-step ownership transfers: Prevent accidental loss of control
• Permission system: Fine-grained control over market operations
• PDA-based accounts: Program-controlled addresses for security
• Slippage protection: Min/max amounts on trades
• Health checks: Ensure positions remain solvent

Usage

This crate provides the CPI interface for interacting with deployed Mayflower programs. Import the necessary modules to:

• Build CPI calls to Mayflower instructions
• Deserialize Mayflower account data
• Integrate Mayflower markets into your Solana program

For implementation details and examples, refer to the main Mayflower program documentation.