pumpswap-python-sdk 1.0.0__py3-none-any.whl

pump_swap_sdk/sdk/swap_operations.py

@@ -0,0 +1,302 @@
+"""
+Swap operation implementations (buy/sell) for the PumpSwap SDK
+"""
+
+from typing import Dict, Any
+from ..types.sdk_types import (
+    BuyBaseInputResult, BuyQuoteInputResult,
+    SellBaseInputResult, SellQuoteInputResult
+)
+from ..types.amm_types import PoolReserves, GlobalConfig, ComputeFeesResult
+from .utils import (
+    ceil_div, floor_div, fee, apply_slippage,
+    calculate_swap_price, calculate_inverse_swap_price
+)
+from .fees import compute_fees_bps, calculate_swap_fees
+
+
+def buy_base_input(
+    base: int,
+    slippage: int,
+    base_reserve: int,
+    quote_reserve: int,
+    global_config: GlobalConfig,
+    creator=None,
+    fee_config=None,
+    market_cap: int = 0
+) -> BuyBaseInputResult:
+    """
+    Calculate quote amount needed to buy a specific base amount
+
+    Uses the constant product formula: quote_in = ceil_div(quote_reserve * base, base_reserve - base)
+
+    Args:
+        base: Desired base token amount to buy
+        slippage: Slippage tolerance in basis points
+        base_reserve: Current base token reserve
+        quote_reserve: Current quote token reserve
+        global_config: Global configuration
+        creator: Pool creator (for fee calculation)
+        fee_config: Fee configuration
+        market_cap: Token market cap (for fee tier calculation)
+
+    Returns:
+        BuyBaseInputResult with quote amounts and slippage protection
+    """
+    if base >= base_reserve:
+        raise ValueError("Insufficient base token liquidity")
+
+    if base <= 0:
+        raise ValueError("Base amount must be positive")
+
+    # Calculate fees
+    fees_result = compute_fees_bps(
+        global_config=global_config,
+        fee_config=fee_config or _default_fee_config(),
+        creator=creator,
+        market_cap=market_cap
+    )
+
+    # Calculate quote amount needed using constant product formula
+    # x * y = k, where x is base reserve, y is quote reserve
+    # When buying base tokens: new_base = base_reserve - base
+    # new_quote * new_base = k = quote_reserve * base_reserve
+    # new_quote = (quote_reserve * base_reserve) / (base_reserve - base)
+    # quote_in = new_quote - quote_reserve
+    numerator = quote_reserve * base
+    denominator = base_reserve - base
+    internal_quote_amount = ceil_div(numerator, denominator)
+
+    # Calculate fees on the quote input
+    fee_amounts = calculate_swap_fees(internal_quote_amount, fees_result)
+
+    # Total quote needed including fees
+    ui_quote = internal_quote_amount + fee_amounts["total_fee_amount"]
+
+    # Apply slippage protection for maximum quote
+    max_quote = apply_slippage(ui_quote, slippage, is_maximum=True)
+
+    return BuyBaseInputResult(
+        internal_quote_amount=internal_quote_amount,
+        ui_quote=ui_quote,
+        max_quote=max_quote
+    )
+
+
+def buy_quote_input(
+    quote: int,
+    slippage: int,
+    base_reserve: int,
+    quote_reserve: int,
+    global_config: GlobalConfig,
+    creator=None,
+    fee_config=None,
+    market_cap: int = 0
+) -> BuyQuoteInputResult:
+    """
+    Calculate base amount received when spending a specific quote amount
+
+    Args:
+        quote: Quote token amount to spend
+        slippage: Slippage tolerance in basis points
+        base_reserve: Current base token reserve
+        quote_reserve: Current quote token reserve
+        global_config: Global configuration
+        creator: Pool creator (for fee calculation)
+        fee_config: Fee configuration
+        market_cap: Token market cap (for fee tier calculation)
+
+    Returns:
+        BuyQuoteInputResult with base amount and fee details
+    """
+    if quote <= 0:
+        raise ValueError("Quote amount must be positive")
+
+    # Calculate fees
+    fees_result = compute_fees_bps(
+        global_config=global_config,
+        fee_config=fee_config or _default_fee_config(),
+        creator=creator,
+        market_cap=market_cap
+    )
+
+    # Calculate fee amounts
+    fee_amounts = calculate_swap_fees(quote, fees_result)
+    internal_quote_without_fees = fee_amounts["amount_after_fees"]
+
+    if internal_quote_without_fees <= 0:
+        raise ValueError("Quote amount too small after fees")
+
+    # Calculate base amount using constant product formula
+    # base_out = (base_reserve * internal_quote_without_fees) / (quote_reserve + internal_quote_without_fees)
+    numerator = base_reserve * internal_quote_without_fees
+    denominator = quote_reserve + internal_quote_without_fees
+    base = floor_div(numerator, denominator)
+
+    if base <= 0:
+        raise ValueError("Insufficient output amount")
+
+    # Apply slippage protection for maximum quote (in case of price movement)
+    max_quote = apply_slippage(quote, slippage, is_maximum=True)
+
+    return BuyQuoteInputResult(
+        base=base,
+        internal_quote_without_fees=internal_quote_without_fees,
+        max_quote=max_quote
+    )
+
+
+def sell_base_input(
+    base: int,
+    slippage: int,
+    base_reserve: int,
+    quote_reserve: int,
+    global_config: GlobalConfig,
+    creator=None,
+    fee_config=None,
+    market_cap: int = 0
+) -> SellBaseInputResult:
+    """
+    Calculate quote amount received when selling a specific base amount
+
+    Uses the constant product formula: quote_out = (quote_reserve * base) / (base_reserve + base)
+
+    Args:
+        base: Base token amount to sell
+        slippage: Slippage tolerance in basis points
+        base_reserve: Current base token reserve
+        quote_reserve: Current quote token reserve
+        global_config: Global configuration
+        creator: Pool creator (for fee calculation)
+        fee_config: Fee configuration
+        market_cap: Token market cap (for fee tier calculation)
+
+    Returns:
+        SellBaseInputResult with quote amounts and slippage protection
+    """
+    if base <= 0:
+        raise ValueError("Base amount must be positive")
+
+    # Calculate fees
+    fees_result = compute_fees_bps(
+        global_config=global_config,
+        fee_config=fee_config or _default_fee_config(),
+        creator=creator,
+        market_cap=market_cap
+    )
+
+    # Calculate quote output using constant product formula
+    # x * y = k, where x is base reserve, y is quote reserve
+    # When selling base tokens: new_base = base_reserve + base
+    # new_quote * new_base = k = quote_reserve * base_reserve
+    # new_quote = (quote_reserve * base_reserve) / (base_reserve + base)
+    # quote_out = quote_reserve - new_quote
+    numerator = quote_reserve * base
+    denominator = base_reserve + base
+    internal_quote_amount_out = floor_div(numerator, denominator)
+
+    # Calculate fees on the quote output
+    fee_amounts = calculate_swap_fees(internal_quote_amount_out, fees_result)
+
+    # Quote amount user receives after fees
+    ui_quote = internal_quote_amount_out - fee_amounts["total_fee_amount"]
+
+    if ui_quote <= 0:
+        raise ValueError("Output amount too small after fees")
+
+    # Apply slippage protection for minimum quote
+    min_quote = apply_slippage(ui_quote, slippage, is_maximum=False)
+
+    return SellBaseInputResult(
+        ui_quote=ui_quote,
+        min_quote=min_quote,
+        internal_quote_amount_out=internal_quote_amount_out
+    )
+
+
+def sell_quote_input(
+    quote: int,
+    slippage: int,
+    base_reserve: int,
+    quote_reserve: int,
+    global_config: GlobalConfig,
+    creator=None,
+    fee_config=None,
+    market_cap: int = 0
+) -> SellQuoteInputResult:
+    """
+    Calculate base amount needed to sell to receive a specific quote amount
+
+    Args:
+        quote: Desired quote token amount to receive
+        slippage: Slippage tolerance in basis points
+        base_reserve: Current base token reserve
+        quote_reserve: Current quote token reserve
+        global_config: Global configuration
+        creator: Pool creator (for fee calculation)
+        fee_config: Fee configuration
+        market_cap: Token market cap (for fee tier calculation)
+
+    Returns:
+        SellQuoteInputResult with base amount and fee details
+    """
+    if quote <= 0:
+        raise ValueError("Quote amount must be positive")
+
+    # Calculate fees
+    fees_result = compute_fees_bps(
+        global_config=global_config,
+        fee_config=fee_config or _default_fee_config(),
+        creator=creator,
+        market_cap=market_cap
+    )
+
+    # We need to find the raw quote amount before fees that would give us the desired quote after fees
+    # Let raw_quote = quote amount before fees
+    # quote_after_fees = raw_quote - fees
+    # quote = raw_quote * (1 - total_fee_rate)
+    # raw_quote = quote / (1 - total_fee_rate)
+
+    total_fee_rate = fees_result.total_fee_bps / 10000  # Convert to decimal
+    if total_fee_rate >= 1.0:
+        raise ValueError("Fee rate too high")
+
+    # Calculate raw quote needed before fees
+    internal_raw_quote = ceil_div(quote * 10000, 10000 - fees_result.total_fee_bps)
+
+    if internal_raw_quote >= quote_reserve:
+        raise ValueError("Insufficient quote token liquidity")
+
+    # Calculate base amount needed using inverse constant product formula
+    # base_in = (base_reserve * internal_raw_quote) / (quote_reserve - internal_raw_quote)
+    numerator = base_reserve * internal_raw_quote
+    denominator = quote_reserve - internal_raw_quote
+
+    if denominator <= 0:
+        raise ValueError("Insufficient liquidity for desired quote amount")
+
+    base = ceil_div(numerator, denominator)
+
+    if base <= 0:
+        raise ValueError("Invalid base amount calculated")
+
+    # Apply slippage protection for minimum quote
+    min_quote = apply_slippage(quote, slippage, is_maximum=False)
+
+    return SellQuoteInputResult(
+        internal_raw_quote=internal_raw_quote,
+        base=base,
+        min_quote=min_quote
+    )
+
+
+def _default_fee_config():
+    """Create a default fee configuration for testing"""
+    from ..types.amm_types import FeeConfig
+
+    return FeeConfig(
+        fee_tiers=[],
+        default_lp_fee_rate_bps=25,      # 0.25%
+        default_protocol_fee_rate_bps=5,  # 0.05%
+        default_creator_fee_rate_bps=0    # 0%
+    )

pump_swap_sdk/sdk/token_incentives.py

@@ -0,0 +1,254 @@
+"""
+Token incentives functionality for the PumpSwap SDK
+"""
+
+from typing import Optional
+from solders.pubkey import Pubkey
+from ..types.amm_types import UserVolumeAccumulator, GlobalVolumeAccumulator
+
+
+def total_unclaimed_tokens(user_volume_accumulator: UserVolumeAccumulator) -> int:
+    """
+    Calculate total unclaimed token incentives for a user
+
+    Args:
+        user_volume_accumulator: User's volume accumulator data
+
+    Returns:
+        Total unclaimed token amount
+    """
+    return user_volume_accumulator.unclaimed_token_incentives
+
+
+def current_day_tokens(
+    user_volume_accumulator: UserVolumeAccumulator,
+    global_volume_accumulator: GlobalVolumeAccumulator,
+    daily_incentives_pool: int,
+    current_day: int
+) -> int:
+    """
+    Calculate token incentives earned for the current day
+
+    Args:
+        user_volume_accumulator: User's volume accumulator data
+        global_volume_accumulator: Global volume accumulator data
+        daily_incentives_pool: Total daily incentives available
+        current_day: Current day identifier
+
+    Returns:
+        Token incentives earned today
+    """
+    # Check if user has any volume today
+    if (user_volume_accumulator.last_updated_day != current_day or
+        user_volume_accumulator.daily_volume == 0):
+        return 0
+
+    # Check if global volume exists
+    if (global_volume_accumulator.last_updated_day != current_day or
+        global_volume_accumulator.daily_volume == 0):
+        return 0
+
+    # Calculate user's share of daily incentives
+    # Formula: user_daily_volume / global_daily_volume * daily_incentives_pool
+    user_share = (user_volume_accumulator.daily_volume * daily_incentives_pool) // global_volume_accumulator.daily_volume
+
+    return user_share
+
+
+def calculate_volume_based_incentives(
+    user_volume: int,
+    total_volume: int,
+    incentive_pool: int,
+    minimum_volume_threshold: int = 0
+) -> int:
+    """
+    Calculate incentives based on volume proportion
+
+    Args:
+        user_volume: User's trading volume
+        total_volume: Total trading volume
+        incentive_pool: Total incentives to distribute
+        minimum_volume_threshold: Minimum volume required to earn incentives
+
+    Returns:
+        User's share of incentives
+    """
+    if user_volume < minimum_volume_threshold:
+        return 0
+
+    if total_volume == 0:
+        return 0
+
+    # Proportional distribution
+    return (user_volume * incentive_pool) // total_volume
+
+
+def calculate_fee_based_incentives(
+    user_fees_paid: int,
+    total_fees_collected: int,
+    incentive_pool: int
+) -> int:
+    """
+    Calculate incentives based on fees paid proportion
+
+    Args:
+        user_fees_paid: Fees paid by user
+        total_fees_collected: Total fees collected
+        incentive_pool: Total incentives to distribute
+
+    Returns:
+        User's share of incentives
+    """
+    if total_fees_collected == 0:
+        return 0
+
+    return (user_fees_paid * incentive_pool) // total_fees_collected
+
+
+def calculate_time_weighted_incentives(
+    user_volume: int,
+    days_active: int,
+    base_incentive: int,
+    time_multiplier: float = 1.1
+) -> int:
+    """
+    Calculate incentives with time weighting for consistent users
+
+    Args:
+        user_volume: User's trading volume
+        days_active: Number of consecutive active days
+        base_incentive: Base incentive amount
+        time_multiplier: Multiplier per active day
+
+    Returns:
+        Time-weighted incentive amount
+    """
+    if user_volume == 0 or days_active == 0:
+        return 0
+
+    # Apply time multiplier (capped at reasonable maximum)
+    max_multiplier = 3.0  # 3x maximum
+    effective_multiplier = min(time_multiplier ** (days_active - 1), max_multiplier)
+
+    return int(base_incentive * effective_multiplier)
+
+
+def get_current_day() -> int:
+    """
+    Get current day identifier (days since epoch)
+
+    Returns:
+        Current day as integer
+    """
+    import time
+    return int(time.time()) // (24 * 60 * 60)  # Days since Unix epoch
+
+
+def is_eligible_for_incentives(
+    user_volume_accumulator: UserVolumeAccumulator,
+    minimum_volume: int = 0,
+    minimum_fees: int = 0
+) -> bool:
+    """
+    Check if user is eligible for token incentives
+
+    Args:
+        user_volume_accumulator: User's volume data
+        minimum_volume: Minimum volume requirement
+        minimum_fees: Minimum fees requirement
+
+    Returns:
+        True if eligible for incentives
+    """
+    return (user_volume_accumulator.daily_volume >= minimum_volume and
+            user_volume_accumulator.daily_fees >= minimum_fees)
+
+
+def estimate_daily_incentives(
+    projected_volume: int,
+    estimated_total_volume: int,
+    daily_incentive_pool: int
+) -> int:
+    """
+    Estimate daily incentives based on projected trading volume
+
+    Args:
+        projected_volume: User's projected daily volume
+        estimated_total_volume: Estimated total daily volume
+        daily_incentive_pool: Total daily incentives available
+
+    Returns:
+        Estimated daily incentive amount
+    """
+    if estimated_total_volume == 0:
+        return 0
+
+    return (projected_volume * daily_incentive_pool) // estimated_total_volume
+
+
+def calculate_claimable_amount(
+    user_volume_accumulator: UserVolumeAccumulator,
+    current_day: int
+) -> int:
+    """
+    Calculate total claimable token amount for a user
+
+    Args:
+        user_volume_accumulator: User's volume accumulator
+        current_day: Current day identifier
+
+    Returns:
+        Total claimable token amount
+    """
+    base_claimable = user_volume_accumulator.unclaimed_token_incentives
+
+    # If user has activity today and hasn't claimed today's rewards yet
+    if (user_volume_accumulator.last_updated_day == current_day and
+        user_volume_accumulator.last_claim_day < current_day):
+        # Add today's estimated rewards
+        # This would need global data to calculate precisely
+        # For now, return base amount
+        pass
+
+    return base_claimable
+
+
+def update_user_volume_accumulator(
+    user_volume_accumulator: UserVolumeAccumulator,
+    volume_increase: int,
+    fees_increase: int,
+    current_day: int
+) -> UserVolumeAccumulator:
+    """
+    Update user volume accumulator with new trading activity
+
+    Args:
+        user_volume_accumulator: Current user volume data
+        volume_increase: Additional volume to add
+        fees_increase: Additional fees to add
+        current_day: Current day identifier
+
+    Returns:
+        Updated user volume accumulator
+    """
+    # Create a copy to avoid mutating the original
+    updated = UserVolumeAccumulator(
+        user=user_volume_accumulator.user,
+        total_volume=user_volume_accumulator.total_volume + volume_increase,
+        total_fees=user_volume_accumulator.total_fees + fees_increase,
+        daily_volume=user_volume_accumulator.daily_volume,
+        daily_fees=user_volume_accumulator.daily_fees,
+        last_updated_day=current_day,
+        unclaimed_token_incentives=user_volume_accumulator.unclaimed_token_incentives,
+        last_claim_day=user_volume_accumulator.last_claim_day
+    )
+
+    # Reset daily counters if it's a new day
+    if user_volume_accumulator.last_updated_day != current_day:
+        updated.daily_volume = volume_increase
+        updated.daily_fees = fees_increase
+    else:
+        updated.daily_volume += volume_increase
+        updated.daily_fees += fees_increase
+
+    return updated