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

pump_swap_sdk/__init__.py

@@ -0,0 +1,37 @@
+"""
+PumpSwap SDK - Python implementation for interacting with Pump Swap AMM protocol on Solana
+
+This SDK provides high-level and low-level interfaces for:
+- Creating AMM pools
+- Performing token swaps (buy/sell)
+- Managing liquidity (deposit/withdraw)
+- Collecting fees
+- Token incentives
+"""
+
+from .sdk.pump_amm_sdk import PumpAmmSdk
+from .sdk.online_pump_amm_sdk import OnlinePumpAmmSdk
+from .sdk.pump_amm_admin_sdk import PumpAmmAdminSdk
+from .sdk.swap_operations import buy_base_input, buy_quote_input, sell_base_input, sell_quote_input
+from .sdk.liquidity_operations import deposit_lp_token, withdraw
+from .sdk.token_incentives import total_unclaimed_tokens, current_day_tokens
+from .types.sdk_types import *
+from .types.amm_types import *
+from .constants import *
+
+__version__ = "1.0.0"
+__author__ = "PumpSwap Python SDK"
+
+__all__ = [
+    "PumpAmmSdk",
+    "OnlinePumpAmmSdk",
+    "PumpAmmAdminSdk",
+    "buy_base_input",
+    "buy_quote_input",
+    "sell_base_input",
+    "sell_quote_input",
+    "deposit_lp_token",
+    "withdraw",
+    "total_unclaimed_tokens",
+    "current_day_tokens",
+]

pump_swap_sdk/constants.py

@@ -0,0 +1,30 @@
+"""
+Constants used throughout the PumpSwap SDK
+"""
+
+from solders.pubkey import Pubkey
+from typing import Final
+
+# Program IDs
+PUMP_AMM_PROGRAM_ID: Final[Pubkey] = Pubkey.from_string("6EF8rrecthR5Dkzon8Nwu78hRvfCKubJ14M5uBEwF6P")
+TOKEN_PROGRAM_ID: Final[Pubkey] = Pubkey.from_string("TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA")
+TOKEN_2022_PROGRAM_ID: Final[Pubkey] = Pubkey.from_string("TokenzQdBNbLqP5VEhdkAS6EPFLC1PHnBqCXEpPxuEb")
+ASSOCIATED_TOKEN_PROGRAM_ID: Final[Pubkey] = Pubkey.from_string("ATokenGPvbdGVxr1b2hvZbsiqW5xWH25efTNsLJA8knL")
+NATIVE_MINT: Final[Pubkey] = Pubkey.from_string("So11111111111111111111111111111111111111112")
+
+# Pool Constants
+POOL_ACCOUNT_NEW_SIZE: Final[int] = 288
+
+# Global PDAs
+GLOBAL_CONFIG_SEED: Final[str] = "global_config"
+GLOBAL_VOLUME_ACCUMULATOR_SEED: Final[str] = "global_volume_accumulator"
+PUMP_AMM_EVENT_AUTHORITY_SEED: Final[str] = "event_authority"
+
+# Fee Configuration
+DEFAULT_SLIPPAGE_BPS: Final[int] = 100  # 1%
+MAX_SLIPPAGE_BPS: Final[int] = 1000     # 10%
+BASIS_POINTS: Final[int] = 10000        # 100%
+
+# Precision
+LAMPORTS_PER_SOL: Final[int] = 1_000_000_000
+TOKEN_DECIMALS: Final[int] = 6

pump_swap_sdk/exceptions.py

@@ -0,0 +1,83 @@
+"""
+Custom exceptions for the PumpSwap SDK
+"""
+
+
+class PumpSwapSDKError(Exception):
+    """Base exception class for PumpSwap SDK errors"""
+    pass
+
+
+class ValidationError(PumpSwapSDKError):
+    """Raised when input validation fails"""
+    pass
+
+
+class InsufficientLiquidityError(PumpSwapSDKError):
+    """Raised when there's insufficient liquidity for an operation"""
+    pass
+
+
+class SlippageExceededError(PumpSwapSDKError):
+    """Raised when slippage tolerance is exceeded"""
+    pass
+
+
+class InvalidPoolError(PumpSwapSDKError):
+    """Raised when pool data is invalid or corrupted"""
+    pass
+
+
+class AccountNotFoundError(PumpSwapSDKError):
+    """Raised when a required account is not found on-chain"""
+    pass
+
+
+class UnauthorizedError(PumpSwapSDKError):
+    """Raised when user lacks required permissions"""
+    pass
+
+
+class ConfigurationError(PumpSwapSDKError):
+    """Raised when SDK configuration is invalid"""
+    pass
+
+
+class FeeCalculationError(PumpSwapSDKError):
+    """Raised when fee calculation fails"""
+    pass
+
+
+class NetworkError(PumpSwapSDKError):
+    """Raised when network operations fail"""
+    pass
+
+
+class SerializationError(PumpSwapSDKError):
+    """Raised when data serialization/deserialization fails"""
+    pass
+
+
+class InstructionBuildError(PumpSwapSDKError):
+    """Raised when instruction building fails"""
+    pass
+
+
+class TokenAccountError(PumpSwapSDKError):
+    """Raised when token account operations fail"""
+    pass
+
+
+class PoolCreationError(PumpSwapSDKError):
+    """Raised when pool creation fails"""
+    pass
+
+
+class SwapError(PumpSwapSDKError):
+    """Raised when swap operations fail"""
+    pass
+
+
+class LiquidityError(PumpSwapSDKError):
+    """Raised when liquidity operations fail"""
+    pass

pump_swap_sdk/sdk/fees.py

@@ -0,0 +1,171 @@
+"""
+Fee calculation utilities for the PumpSwap SDK
+"""
+
+from typing import Optional
+from solders.pubkey import Pubkey
+from ..types.amm_types import FeeConfig, GlobalConfig, ComputeFeesResult
+from ..constants import BASIS_POINTS
+from .utils import is_pump_pool
+
+
+def calculate_fee_tier(fee_tiers: list, market_cap: int) -> Optional[FeeConfig.FeeTier]:
+    """
+    Find the appropriate fee tier based on market cap
+
+    Args:
+        fee_tiers: List of fee tiers ordered by market cap threshold
+        market_cap: Current market cap
+
+    Returns:
+        Matching fee tier or None
+    """
+    # Tiers should be ordered by threshold (ascending)
+    for tier in reversed(fee_tiers):
+        if market_cap >= tier.market_cap_threshold:
+            return tier
+    return None
+
+
+def compute_fees_bps(
+    global_config: GlobalConfig,
+    fee_config: FeeConfig,
+    creator: Optional[Pubkey] = None,
+    market_cap: int = 0,
+    mint: Optional[Pubkey] = None
+) -> ComputeFeesResult:
+    """
+    Compute fee rates in basis points for a swap
+
+    Args:
+        global_config: Global configuration
+        fee_config: Fee configuration with tiers
+        creator: Pool creator (for pump pool detection)
+        market_cap: Current market cap of the token
+        mint: Token mint (for pump pool detection)
+
+    Returns:
+        ComputeFeesResult with all fee rates
+    """
+    # Start with default fees
+    lp_fee_bps = fee_config.default_lp_fee_rate_bps
+    protocol_fee_bps = fee_config.default_protocol_fee_rate_bps
+    creator_fee_bps = fee_config.default_creator_fee_rate_bps
+
+    # Check if mayhem mode is active (higher fees)
+    if global_config.is_mayhem_mode:
+        # Apply mayhem mode multiplier (example: 2x fees)
+        lp_fee_bps *= 2
+        protocol_fee_bps *= 2
+        creator_fee_bps *= 2
+
+    # Find appropriate fee tier based on market cap
+    fee_tier = calculate_fee_tier(fee_config.fee_tiers, market_cap)
+    if fee_tier:
+        lp_fee_bps = fee_tier.lp_fee_rate_bps
+        protocol_fee_bps = fee_tier.protocol_fee_rate_bps
+        creator_fee_bps = fee_tier.creator_fee_rate_bps
+
+    # Special handling for pump pools
+    if mint and creator and is_pump_pool(mint, creator):
+        # Pump pools might have different fee structures
+        # This would be implemented based on specific pump.fun requirements
+        pass
+
+    # Calculate total fee rate
+    total_fee_bps = lp_fee_bps + protocol_fee_bps + creator_fee_bps
+
+    # Ensure total fees don't exceed 100%
+    if total_fee_bps > BASIS_POINTS:
+        raise ValueError(f"Total fees ({total_fee_bps} bps) exceed 100%")
+
+    return ComputeFeesResult(
+        lp_fee_bps=lp_fee_bps,
+        protocol_fee_bps=protocol_fee_bps,
+        creator_fee_bps=creator_fee_bps,
+        total_fee_bps=total_fee_bps
+    )
+
+
+def get_fee_recipient(
+    global_config: GlobalConfig,
+    pool_creator: Optional[Pubkey] = None
+) -> Pubkey:
+    """
+    Get the fee recipient address
+
+    Args:
+        global_config: Global configuration
+        pool_creator: Pool creator (unused for now, but could be used for dynamic routing)
+
+    Returns:
+        Fee recipient address
+    """
+    return global_config.fee_recipient
+
+
+def calculate_swap_fees(
+    amount_in: int,
+    fees_result: ComputeFeesResult
+) -> dict:
+    """
+    Calculate actual fee amounts for a swap
+
+    Args:
+        amount_in: Input amount
+        fees_result: Fee rates from compute_fees_bps
+
+    Returns:
+        Dictionary with fee amounts
+    """
+    from .utils import fee
+
+    lp_fee_amount = fee(amount_in, fees_result.lp_fee_bps)
+    protocol_fee_amount = fee(amount_in, fees_result.protocol_fee_bps)
+    creator_fee_amount = fee(amount_in, fees_result.creator_fee_bps)
+    total_fee_amount = lp_fee_amount + protocol_fee_amount + creator_fee_amount
+
+    return {
+        "lp_fee_amount": lp_fee_amount,
+        "protocol_fee_amount": protocol_fee_amount,
+        "creator_fee_amount": creator_fee_amount,
+        "total_fee_amount": total_fee_amount,
+        "amount_after_fees": amount_in - total_fee_amount
+    }
+
+
+def validate_fee_rates(
+    lp_fee_bps: int,
+    protocol_fee_bps: int,
+    creator_fee_bps: int
+) -> None:
+    """
+    Validate that fee rates are reasonable
+
+    Args:
+        lp_fee_bps: LP fee rate in basis points
+        protocol_fee_bps: Protocol fee rate in basis points
+        creator_fee_bps: Creator fee rate in basis points
+
+    Raises:
+        ValueError: If fees are invalid
+    """
+    # Check individual fee rates
+    if lp_fee_bps < 0 or lp_fee_bps > BASIS_POINTS:
+        raise ValueError(f"Invalid LP fee rate: {lp_fee_bps} bps")
+
+    if protocol_fee_bps < 0 or protocol_fee_bps > BASIS_POINTS:
+        raise ValueError(f"Invalid protocol fee rate: {protocol_fee_bps} bps")
+
+    if creator_fee_bps < 0 or creator_fee_bps > BASIS_POINTS:
+        raise ValueError(f"Invalid creator fee rate: {creator_fee_bps} bps")
+
+    # Check total fees
+    total_fee_bps = lp_fee_bps + protocol_fee_bps + creator_fee_bps
+    if total_fee_bps > BASIS_POINTS:
+        raise ValueError(f"Total fees exceed 100%: {total_fee_bps} bps")
+
+    # Reasonable maximum (e.g., 10% total fees)
+    max_reasonable_fee = BASIS_POINTS // 10  # 10%
+    if total_fee_bps > max_reasonable_fee:
+        raise ValueError(f"Total fees too high: {total_fee_bps} bps (max reasonable: {max_reasonable_fee} bps)")

pump_swap_sdk/sdk/liquidity_operations.py

@@ -0,0 +1,328 @@
+"""
+Liquidity operation implementations (deposit/withdraw) for the PumpSwap SDK
+"""
+
+import math
+from typing import Tuple
+from ..types.sdk_types import (
+    DepositBaseResult, DepositQuoteResult, DepositLpTokenResult,
+    DepositBaseAndLpTokenFromQuoteResult, DepositQuoteAndLpTokenFromBaseResult,
+    WithdrawResult, WithdrawAutocompleteResult
+)
+from .utils import (
+    ceil_div, floor_div, apply_slippage,
+    calculate_lp_tokens_for_deposit, calculate_tokens_for_lp_withdrawal
+)
+
+
+def deposit_token0(
+    token0: int,
+    slippage: int,
+    token0_reserve: int,
+    token1_reserve: int,
+    total_lp_supply: int
+) -> DepositBaseResult:
+    """
+    Calculate deposit amounts when user provides token0 amount
+
+    Args:
+        token0: Amount of token0 to deposit
+        slippage: Slippage tolerance in basis points
+        token0_reserve: Current token0 reserve
+        token1_reserve: Current token1 reserve
+        total_lp_supply: Current total LP supply
+
+    Returns:
+        DepositBaseResult with calculated amounts
+    """
+    if token0 <= 0:
+        raise ValueError("Token0 amount must be positive")
+
+    if total_lp_supply == 0:
+        # Initial liquidity - special case
+        # For initial deposit, we can accept any ratio
+        # LP tokens = sqrt(token0 * token1) where token1 is provided
+        raise ValueError("Use deposit_lp_token for initial liquidity provision")
+
+    if token0_reserve == 0:
+        raise ValueError("Invalid token0 reserve")
+
+    # Calculate proportional token1 amount needed
+    # token1 = token0 * token1_reserve / token0_reserve
+    quote = ceil_div(token0 * token1_reserve, token0_reserve)
+
+    # Calculate LP tokens to be minted
+    # lp_tokens = token0 * total_lp_supply / token0_reserve
+    lp_token = floor_div(token0 * total_lp_supply, token0_reserve)
+
+    if lp_token == 0:
+        raise ValueError("Deposit amount too small")
+
+    # Apply slippage protection
+    max_base = apply_slippage(token0, slippage, is_maximum=True)
+    max_quote = apply_slippage(quote, slippage, is_maximum=True)
+
+    return DepositBaseResult(
+        quote=quote,
+        lp_token=lp_token,
+        max_base=max_base,
+        max_quote=max_quote
+    )
+
+
+def deposit_quote_and_lp_token_from_base(
+    base: int,
+    slippage: int,
+    base_reserve: int,
+    quote_reserve: int,
+    total_lp_supply: int
+) -> DepositQuoteAndLpTokenFromBaseResult:
+    """
+    Calculate quote amount and LP tokens when user provides base amount
+
+    Args:
+        base: Base token amount to deposit
+        slippage: Slippage tolerance in basis points
+        base_reserve: Current base token reserve
+        quote_reserve: Current quote token reserve
+        total_lp_supply: Current total LP supply
+
+    Returns:
+        DepositQuoteAndLpTokenFromBaseResult
+    """
+    if base <= 0:
+        raise ValueError("Base amount must be positive")
+
+    if total_lp_supply == 0 or base_reserve == 0:
+        raise ValueError("Pool not initialized")
+
+    # Calculate proportional quote amount needed
+    quote = ceil_div(base * quote_reserve, base_reserve)
+
+    # Calculate LP tokens to be minted
+    lp_token = floor_div(base * total_lp_supply, base_reserve)
+
+    if lp_token == 0:
+        raise ValueError("Deposit amount too small")
+
+    return DepositQuoteAndLpTokenFromBaseResult(
+        quote=quote,
+        lp_token=lp_token
+    )
+
+
+def deposit_base_and_lp_token_from_quote(
+    quote: int,
+    slippage: int,
+    base_reserve: int,
+    quote_reserve: int,
+    total_lp_supply: int
+) -> DepositBaseAndLpTokenFromQuoteResult:
+    """
+    Calculate base amount and LP tokens when user provides quote amount
+
+    Args:
+        quote: Quote token amount to deposit
+        slippage: Slippage tolerance in basis points
+        base_reserve: Current base token reserve
+        quote_reserve: Current quote token reserve
+        total_lp_supply: Current total LP supply
+
+    Returns:
+        DepositBaseAndLpTokenFromQuoteResult
+    """
+    if quote <= 0:
+        raise ValueError("Quote amount must be positive")
+
+    if total_lp_supply == 0 or quote_reserve == 0:
+        raise ValueError("Pool not initialized")
+
+    # Calculate proportional base amount needed
+    base = ceil_div(quote * base_reserve, quote_reserve)
+
+    # Calculate LP tokens to be minted
+    lp_token = floor_div(quote * total_lp_supply, quote_reserve)
+
+    if lp_token == 0:
+        raise ValueError("Deposit amount too small")
+
+    return DepositBaseAndLpTokenFromQuoteResult(
+        base=base,
+        lp_token=lp_token
+    )
+
+
+def deposit_lp_token(
+    lp_token: int,
+    slippage: int,
+    base_reserve: int,
+    quote_reserve: int,
+    total_lp_supply: int
+) -> DepositLpTokenResult:
+    """
+    Calculate token amounts needed for a specific LP token amount
+
+    Args:
+        lp_token: Desired LP token amount
+        slippage: Slippage tolerance in basis points
+        base_reserve: Current base token reserve
+        quote_reserve: Current quote token reserve
+        total_lp_supply: Current total LP supply
+
+    Returns:
+        DepositLpTokenResult with maximum token amounts needed
+    """
+    if lp_token <= 0:
+        raise ValueError("LP token amount must be positive")
+
+    if total_lp_supply == 0:
+        # Initial liquidity case
+        # For initial deposit, we use the geometric mean
+        # lp_token = sqrt(base_amount * quote_amount)
+        # This means base_amount * quote_amount = lp_token^2
+        # We need to determine the ratio, but for now return equal amounts
+        estimated_base = int(math.sqrt(lp_token))
+        estimated_quote = int(math.sqrt(lp_token))
+
+        max_base = apply_slippage(estimated_base, slippage, is_maximum=True)
+        max_quote = apply_slippage(estimated_quote, slippage, is_maximum=True)
+
+        return DepositLpTokenResult(
+            max_base=max_base,
+            max_quote=max_quote
+        )
+
+    # Calculate required token amounts proportionally
+    # base_amount = lp_token * base_reserve / total_lp_supply
+    max_base_needed = ceil_div(lp_token * base_reserve, total_lp_supply)
+    max_quote_needed = ceil_div(lp_token * quote_reserve, total_lp_supply)
+
+    # Apply slippage protection
+    max_base = apply_slippage(max_base_needed, slippage, is_maximum=True)
+    max_quote = apply_slippage(max_quote_needed, slippage, is_maximum=True)
+
+    return DepositLpTokenResult(
+        max_base=max_base,
+        max_quote=max_quote
+    )
+
+
+def withdraw(
+    lp_amount: int,
+    slippage: int,
+    base_reserve: int,
+    quote_reserve: int,
+    total_lp_supply: int
+) -> WithdrawResult:
+    """
+    Calculate token amounts received when withdrawing LP tokens
+
+    Args:
+        lp_amount: LP token amount to withdraw
+        slippage: Slippage tolerance in basis points
+        base_reserve: Current base token reserve
+        quote_reserve: Current quote token reserve
+        total_lp_supply: Current total LP supply
+
+    Returns:
+        WithdrawResult with token amounts and slippage protection
+    """
+    if lp_amount <= 0:
+        raise ValueError("LP amount must be positive")
+
+    if lp_amount > total_lp_supply:
+        raise ValueError("LP amount exceeds total supply")
+
+    if total_lp_supply == 0:
+        raise ValueError("No liquidity to withdraw")
+
+    # Calculate proportional token amounts
+    base, quote = calculate_tokens_for_lp_withdrawal(
+        lp_amount, base_reserve, quote_reserve, total_lp_supply
+    )
+
+    if base == 0 and quote == 0:
+        raise ValueError("Withdrawal amount too small")
+
+    # Apply slippage protection for minimum amounts
+    min_base = apply_slippage(base, slippage, is_maximum=False)
+    min_quote = apply_slippage(quote, slippage, is_maximum=False)
+
+    return WithdrawResult(
+        base=base,
+        quote=quote,
+        min_base=min_base,
+        min_quote=min_quote
+    )
+
+
+def withdraw_autocomplete_base_and_quote_from_lp_token(
+    lp_amount: int,
+    slippage: int,
+    base_reserve: int,
+    quote_reserve: int,
+    total_lp_supply: int
+) -> WithdrawAutocompleteResult:
+    """
+    Simple autocomplete calculation for withdrawal amounts
+
+    Args:
+        lp_amount: LP token amount to withdraw
+        slippage: Slippage tolerance in basis points
+        base_reserve: Current base token reserve
+        quote_reserve: Current quote token reserve
+        total_lp_supply: Current total LP supply
+
+    Returns:
+        WithdrawAutocompleteResult with base and quote amounts
+    """
+    if lp_amount <= 0:
+        raise ValueError("LP amount must be positive")
+
+    if total_lp_supply == 0:
+        return WithdrawAutocompleteResult(base=0, quote=0)
+
+    # Calculate proportional amounts without slippage
+    base, quote = calculate_tokens_for_lp_withdrawal(
+        lp_amount, base_reserve, quote_reserve, total_lp_supply
+    )
+
+    return WithdrawAutocompleteResult(
+        base=base,
+        quote=quote
+    )
+
+
+def validate_deposit_amounts(
+    base_amount: int,
+    quote_amount: int,
+    base_reserve: int,
+    quote_reserve: int,
+    tolerance_bps: int = 100  # 1% tolerance
+) -> bool:
+    """
+    Validate that deposit amounts maintain proper pool ratio
+
+    Args:
+        base_amount: Base token amount to deposit
+        quote_amount: Quote token amount to deposit
+        base_reserve: Current base token reserve
+        quote_reserve: Current quote token reserve
+        tolerance_bps: Allowed deviation in basis points
+
+    Returns:
+        True if amounts are within tolerance
+    """
+    if base_reserve == 0 or quote_reserve == 0:
+        # Initial deposit - any ratio is acceptable
+        return True
+
+    # Calculate expected ratio
+    expected_ratio = quote_reserve * 10000 // base_reserve  # Scale up for precision
+    actual_ratio = quote_amount * 10000 // base_amount
+
+    # Check if within tolerance
+    deviation = abs(actual_ratio - expected_ratio)
+    max_deviation = expected_ratio * tolerance_bps // 10000
+
+    return deviation <= max_deviation