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

pump_swap_sdk/sdk/utils.py

@@ -0,0 +1,273 @@
+"""
+Utility functions for mathematical calculations and conversions
+"""
+
+import math
+from typing import Tuple, Optional
+from solders.pubkey import Pubkey
+from ..constants import BASIS_POINTS, LAMPORTS_PER_SOL
+from ..types.amm_types import PoolReserves, GlobalConfig
+
+
+def ceil_div(a: int, b: int) -> int:
+    """
+    Ceiling division - ensures no precision loss in token calculations
+
+    Args:
+        a: Dividend
+        b: Divisor
+
+    Returns:
+        Ceiling of a/b
+    """
+    if b == 0:
+        raise ValueError("Division by zero")
+    return (a + b - 1) // b
+
+
+def floor_div(a: int, b: int) -> int:
+    """
+    Floor division for token calculations
+
+    Args:
+        a: Dividend
+        b: Divisor
+
+    Returns:
+        Floor of a/b
+    """
+    if b == 0:
+        raise ValueError("Division by zero")
+    return a // b
+
+
+def fee(amount: int, basis_points: int) -> int:
+    """
+    Calculate fee amount from basis points
+
+    Args:
+        amount: Amount to calculate fee on
+        basis_points: Fee in basis points (1 bps = 0.01%)
+
+    Returns:
+        Fee amount
+    """
+    return ceil_div(amount * basis_points, BASIS_POINTS)
+
+
+def apply_slippage(amount: int, slippage_bps: int, is_maximum: bool = True) -> int:
+    """
+    Apply slippage to an amount
+
+    Args:
+        amount: Base amount
+        slippage_bps: Slippage in basis points
+        is_maximum: True for maximum amount (adds slippage), False for minimum (subtracts)
+
+    Returns:
+        Amount with slippage applied
+    """
+    slippage_amount = fee(amount, slippage_bps)
+
+    if is_maximum:
+        return amount + slippage_amount
+    else:
+        return max(0, amount - slippage_amount)
+
+
+def pool_market_cap(
+    supply: int,
+    base_reserve: int,
+    quote_reserve: int,
+    decimals: int = 6
+) -> int:
+    """
+    Calculate pool market cap based on current reserves and token supply
+
+    Args:
+        supply: Total token supply
+        base_reserve: Base token reserve in pool
+        quote_reserve: Quote token reserve in pool
+        decimals: Token decimals
+
+    Returns:
+        Market cap in lamports
+    """
+    if base_reserve == 0:
+        return 0
+
+    # Price = quote_reserve / base_reserve
+    # Market cap = supply * price
+    return floor_div(supply * quote_reserve, base_reserve)
+
+
+def is_pump_pool(mint: Pubkey, creator: Pubkey) -> bool:
+    """
+    Check if a pool is a pump pool (created via pump.fun)
+
+    Args:
+        mint: Token mint address
+        creator: Pool creator address
+
+    Returns:
+        True if it's a pump pool
+    """
+    # This would need to be implemented based on specific pump.fun detection logic
+    # For now, returning False as placeholder
+    return False
+
+
+def calculate_swap_price(
+    amount_in: int,
+    reserve_in: int,
+    reserve_out: int,
+    fee_bps: int = 0
+) -> int:
+    """
+    Calculate output amount for a swap using constant product formula
+
+    Args:
+        amount_in: Input token amount
+        reserve_in: Input token reserve
+        reserve_out: Output token reserve
+        fee_bps: Total fee in basis points
+
+    Returns:
+        Output token amount
+    """
+    if reserve_in == 0 or reserve_out == 0:
+        raise ValueError("Invalid reserves")
+
+    # Apply fees to input amount
+    amount_in_with_fee = amount_in - fee(amount_in, fee_bps)
+
+    # Constant product formula: x * y = k
+    # amount_out = (reserve_out * amount_in_with_fee) / (reserve_in + amount_in_with_fee)
+    numerator = reserve_out * amount_in_with_fee
+    denominator = reserve_in + amount_in_with_fee
+
+    return floor_div(numerator, denominator)
+
+
+def calculate_inverse_swap_price(
+    amount_out: int,
+    reserve_in: int,
+    reserve_out: int,
+    fee_bps: int = 0
+) -> int:
+    """
+    Calculate required input amount for a desired output amount
+
+    Args:
+        amount_out: Desired output token amount
+        reserve_in: Input token reserve
+        reserve_out: Output token reserve
+        fee_bps: Total fee in basis points
+
+    Returns:
+        Required input token amount
+    """
+    if reserve_in == 0 or reserve_out == 0:
+        raise ValueError("Invalid reserves")
+
+    if amount_out >= reserve_out:
+        raise ValueError("Insufficient liquidity")
+
+    # Calculate required input before fees
+    # amount_in_before_fee = (reserve_in * amount_out) / (reserve_out - amount_out)
+    numerator = reserve_in * amount_out
+    denominator = reserve_out - amount_out
+    amount_in_before_fee = ceil_div(numerator, denominator)
+
+    # Account for fees: amount_in = amount_in_before_fee / (1 - fee_rate)
+    if fee_bps > 0:
+        fee_rate = BASIS_POINTS - fee_bps
+        amount_in = ceil_div(amount_in_before_fee * BASIS_POINTS, fee_rate)
+    else:
+        amount_in = amount_in_before_fee
+
+    return amount_in
+
+
+def calculate_lp_tokens_for_deposit(
+    token0_amount: int,
+    token1_amount: int,
+    reserve0: int,
+    reserve1: int,
+    total_lp_supply: int
+) -> int:
+    """
+    Calculate LP tokens to mint for a deposit
+
+    Args:
+        token0_amount: Amount of token0 being deposited
+        token1_amount: Amount of token1 being deposited
+        reserve0: Current reserve of token0
+        reserve1: Current reserve of token1
+        total_lp_supply: Current total LP token supply
+
+    Returns:
+        LP tokens to mint
+    """
+    if total_lp_supply == 0:
+        # Initial deposit - LP tokens = sqrt(token0 * token1)
+        return int(math.sqrt(token0_amount * token1_amount))
+
+    # Proportional deposit - LP tokens based on smaller ratio to prevent exploits
+    lp_from_token0 = floor_div(token0_amount * total_lp_supply, reserve0) if reserve0 > 0 else 0
+    lp_from_token1 = floor_div(token1_amount * total_lp_supply, reserve1) if reserve1 > 0 else 0
+
+    return min(lp_from_token0, lp_from_token1)
+
+
+def calculate_tokens_for_lp_withdrawal(
+    lp_amount: int,
+    reserve0: int,
+    reserve1: int,
+    total_lp_supply: int
+) -> Tuple[int, int]:
+    """
+    Calculate token amounts for LP withdrawal
+
+    Args:
+        lp_amount: LP tokens to burn
+        reserve0: Current reserve of token0
+        reserve1: Current reserve of token1
+        total_lp_supply: Current total LP token supply
+
+    Returns:
+        Tuple of (token0_amount, token1_amount)
+    """
+    if total_lp_supply == 0:
+        return (0, 0)
+
+    token0_amount = floor_div(lp_amount * reserve0, total_lp_supply)
+    token1_amount = floor_div(lp_amount * reserve1, total_lp_supply)
+
+    return (token0_amount, token1_amount)
+
+
+def validate_slippage(slippage_bps: int) -> None:
+    """
+    Validate slippage is within acceptable bounds
+
+    Args:
+        slippage_bps: Slippage in basis points
+
+    Raises:
+        ValueError: If slippage is invalid
+    """
+    if slippage_bps < 0:
+        raise ValueError("Slippage cannot be negative")
+    if slippage_bps > 10000:  # 100%
+        raise ValueError("Slippage cannot exceed 100%")
+
+
+def lamports_to_sol(lamports: int) -> float:
+    """Convert lamports to SOL"""
+    return lamports / LAMPORTS_PER_SOL
+
+
+def sol_to_lamports(sol: float) -> int:
+    """Convert SOL to lamports"""
+    return int(sol * LAMPORTS_PER_SOL)

pump_swap_sdk/types/amm_types.py

@@ -0,0 +1,153 @@
+"""
+AMM-specific type definitions and data classes based on the Anchor program
+"""
+
+from dataclasses import dataclass
+from typing import Optional, List, Dict
+from solders.pubkey import Pubkey
+from enum import Enum
+
+
+class PoolStatus(Enum):
+    """Pool status enumeration"""
+    ACTIVE = 0
+    PAUSED = 1
+    DISABLED = 2
+
+
+@dataclass
+class Pool:
+    """Pool account structure"""
+    # Basic pool info
+    index: int
+    creator: Pubkey
+    base_mint: Pubkey
+    quote_mint: Pubkey
+    lp_mint: Pubkey
+
+    # Vaults
+    base_vault: Pubkey
+    quote_vault: Pubkey
+    base_vault_authority: Pubkey
+    quote_vault_authority: Pubkey
+
+    # Pool state
+    status: PoolStatus
+    created_at: int
+    updated_at: int
+
+    # Reserves and liquidity
+    total_lp_supply: int
+
+    # Fee collection
+    coin_creator: Optional[Pubkey] = None
+    coin_creator_fee_rate_bps: int = 0
+
+
+@dataclass
+class GlobalConfig:
+    """Global configuration for the AMM"""
+    # Admin settings
+    admin: Pubkey
+    fee_recipient: Pubkey
+
+    # Protocol settings
+    protocol_fee_rate_bps: int
+    creator_fee_rate_bps: int
+    max_pool_count: int
+
+    # Feature flags
+    is_paused: bool
+    is_mayhem_mode: bool
+
+    # Token incentives
+    token_incentives_enabled: bool
+    token_incentives_mint: Optional[Pubkey] = None
+    daily_token_incentives_amount: int = 0
+
+
+@dataclass
+class FeeConfig:
+    """Fee configuration with market cap tiers"""
+
+    @dataclass
+    class FeeTier:
+        """Individual fee tier"""
+        market_cap_threshold: int
+        lp_fee_rate_bps: int
+        protocol_fee_rate_bps: int
+        creator_fee_rate_bps: int
+
+    fee_tiers: List[FeeTier]
+    default_lp_fee_rate_bps: int
+    default_protocol_fee_rate_bps: int
+    default_creator_fee_rate_bps: int
+
+
+@dataclass
+class GlobalVolumeAccumulator:
+    """Global volume tracking"""
+    total_volume: int
+    total_fees: int
+    daily_volume: int
+    daily_fees: int
+    last_updated_day: int
+
+
+@dataclass
+class UserVolumeAccumulator:
+    """User-specific volume tracking"""
+    user: Pubkey
+    total_volume: int
+    total_fees: int
+    daily_volume: int
+    daily_fees: int
+    last_updated_day: int
+
+    # Token incentives tracking
+    unclaimed_token_incentives: int
+    last_claim_day: int
+
+
+@dataclass
+class ComputeFeesResult:
+    """Result of fee calculations"""
+    lp_fee_bps: int
+    protocol_fee_bps: int
+    creator_fee_bps: int
+    total_fee_bps: int
+
+
+@dataclass
+class SwapParams:
+    """Parameters for swap operations"""
+    amount_in: int
+    minimum_amount_out: int
+    slippage_bps: int
+
+
+@dataclass
+class LiquidityParams:
+    """Parameters for liquidity operations"""
+    max_base: int
+    max_quote: int
+    lp_token_amount: int
+    slippage_bps: int
+
+
+@dataclass
+class PoolReserves:
+    """Pool reserve amounts"""
+    base_reserve: int
+    quote_reserve: int
+    lp_supply: int
+
+
+@dataclass
+class MarketData:
+    """Market data for a pool"""
+    market_cap: int
+    price: float
+    volume_24h: int
+    fees_24h: int
+    tvl: int  # Total Value Locked

pump_swap_sdk/types/sdk_types.py

@@ -0,0 +1,193 @@
+"""
+SDK-specific type definitions and data classes
+"""
+
+from dataclasses import dataclass
+from typing import Optional, List, Dict, Any
+from solders.pubkey import Pubkey
+from solders.account import Account
+from solana.rpc.types import TokenAccountOpts
+
+
+@dataclass
+class DepositBaseResult:
+    quote: int
+    lp_token: int
+    max_base: int
+    max_quote: int
+
+
+@dataclass
+class DepositQuoteAndLpTokenFromBaseResult:
+    quote: int
+    lp_token: int
+
+
+@dataclass
+class DepositQuoteResult:
+    base: int
+    lp_token: int
+    max_base: int
+    max_quote: int
+
+
+@dataclass
+class DepositBaseAndLpTokenFromQuoteResult:
+    base: int
+    lp_token: int
+
+
+@dataclass
+class DepositLpTokenResult:
+    max_base: int
+    max_quote: int
+
+
+@dataclass
+class WithdrawResult:
+    base: int
+    quote: int
+    min_base: int
+    min_quote: int
+
+
+@dataclass
+class WithdrawAutocompleteResult:
+    base: int
+    quote: int
+
+
+@dataclass
+class BuyBaseInputResult:
+    internal_quote_amount: int
+    ui_quote: int
+    max_quote: int
+
+
+@dataclass
+class BuyQuoteInputResult:
+    base: int
+    internal_quote_without_fees: int
+    max_quote: int
+
+
+@dataclass
+class SellBaseInputResult:
+    ui_quote: int
+    min_quote: int
+    internal_quote_amount_out: int
+
+
+@dataclass
+class SellQuoteInputResult:
+    internal_raw_quote: int
+    base: int
+    min_quote: int
+
+
+@dataclass
+class SwapAccounts:
+    """Accounts needed for swap operations"""
+    user: Pubkey
+    pool: Pubkey
+    base_mint: Pubkey
+    quote_mint: Pubkey
+    lp_mint: Pubkey
+    base_vault: Pubkey
+    quote_vault: Pubkey
+    user_base_ata: Pubkey
+    user_quote_ata: Pubkey
+    base_vault_authority: Pubkey
+    quote_vault_authority: Pubkey
+    fee_recipient: Pubkey
+
+
+@dataclass
+class LiquidityAccounts:
+    """Accounts needed for liquidity operations"""
+    user: Pubkey
+    pool: Pubkey
+    base_mint: Pubkey
+    quote_mint: Pubkey
+    lp_mint: Pubkey
+    base_vault: Pubkey
+    quote_vault: Pubkey
+    user_base_ata: Pubkey
+    user_quote_ata: Pubkey
+    user_lp_ata: Pubkey
+    base_vault_authority: Pubkey
+    quote_vault_authority: Pubkey
+
+
+@dataclass
+class CommonSolanaState:
+    """Base state common to all operations"""
+    global_config: "GlobalConfig"
+    fee_config: "FeeConfig"
+    global_volume_accumulator: "GlobalVolumeAccumulator"
+    user_volume_accumulator: Optional["UserVolumeAccumulator"] = None
+
+
+@dataclass
+class SwapSolanaState(CommonSolanaState):
+    """State for swap operations"""
+    pool: "Pool" = None
+    pool_base_amount: int = 0
+    pool_quote_amount: int = 0
+    accounts: SwapAccounts = None
+
+
+@dataclass
+class LiquiditySolanaState(CommonSolanaState):
+    """State for liquidity operations"""
+    pool: "Pool" = None
+    pool_base_amount: int = 0
+    pool_quote_amount: int = 0
+    lp_total_supply: int = 0
+    accounts: LiquidityAccounts = None
+
+
+@dataclass
+class CreatePoolSolanaState(CommonSolanaState):
+    """State for pool creation"""
+    index: int = 0
+    creator: Pubkey = None
+    base_mint: Pubkey = None
+    quote_mint: Pubkey = None
+    pool: Pubkey = None
+    lp_mint: Pubkey = None
+    base_vault: Pubkey = None
+    quote_vault: Pubkey = None
+    base_vault_authority: Pubkey = None
+    quote_vault_authority: Pubkey = None
+
+
+@dataclass
+class CollectCoinCreatorFeeSolanaState:
+    """State for collecting coin creator fees"""
+    creator: Pubkey
+    coin_creator_vault_ata: Pubkey
+    coin_creator_vault_authority: Pubkey
+    creator_ata: Pubkey
+    mint: Pubkey
+
+
+@dataclass
+class TokenAccount:
+    """Represents a token account"""
+    address: Pubkey
+    mint: Pubkey
+    owner: Pubkey
+    amount: int
+    decimals: int
+
+
+@dataclass
+class MintInfo:
+    """Represents mint information"""
+    address: Pubkey
+    mint_authority: Optional[Pubkey]
+    supply: int
+    decimals: int
+    is_initialized: bool
+    freeze_authority: Optional[Pubkey]