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

pump_swap_sdk/validators.py

@@ -0,0 +1,315 @@
+"""
+Input validation utilities for the PumpSwap SDK
+"""
+
+from typing import Optional, Union
+from solders.pubkey import Pubkey
+from .constants import MAX_SLIPPAGE_BPS, BASIS_POINTS
+from .exceptions import ValidationError
+
+
+def validate_amount(amount: int, name: str = "amount", allow_zero: bool = False) -> None:
+    """
+    Validate token amount
+
+    Args:
+        amount: Amount to validate
+        name: Parameter name for error messages
+        allow_zero: Whether zero is allowed
+
+    Raises:
+        ValidationError: If amount is invalid
+    """
+    if not isinstance(amount, int):
+        raise ValidationError(f"{name} must be an integer")
+
+    if amount < 0:
+        raise ValidationError(f"{name} cannot be negative")
+
+    if not allow_zero and amount == 0:
+        raise ValidationError(f"{name} must be greater than zero")
+
+    # Check for unreasonably large values (overflow protection)
+    max_u64 = 2**64 - 1
+    if amount > max_u64:
+        raise ValidationError(f"{name} exceeds maximum allowed value")
+
+
+def validate_slippage(slippage_bps: int) -> None:
+    """
+    Validate slippage tolerance
+
+    Args:
+        slippage_bps: Slippage in basis points
+
+    Raises:
+        ValidationError: If slippage is invalid
+    """
+    validate_amount(slippage_bps, "slippage", allow_zero=True)
+
+    if slippage_bps > MAX_SLIPPAGE_BPS:
+        raise ValidationError(f"Slippage ({slippage_bps} bps) exceeds maximum ({MAX_SLIPPAGE_BPS} bps)")
+
+
+def validate_fee_rate(fee_bps: int, name: str = "fee rate") -> None:
+    """
+    Validate fee rate in basis points
+
+    Args:
+        fee_bps: Fee rate in basis points
+        name: Parameter name for error messages
+
+    Raises:
+        ValidationError: If fee rate is invalid
+    """
+    validate_amount(fee_bps, name, allow_zero=True)
+
+    if fee_bps > BASIS_POINTS:
+        raise ValidationError(f"{name} ({fee_bps} bps) cannot exceed 100% ({BASIS_POINTS} bps)")
+
+
+def validate_pubkey(pubkey: Union[str, Pubkey], name: str = "pubkey") -> Pubkey:
+    """
+    Validate and convert pubkey
+
+    Args:
+        pubkey: Pubkey as string or Pubkey object
+        name: Parameter name for error messages
+
+    Returns:
+        Validated Pubkey object
+
+    Raises:
+        ValidationError: If pubkey is invalid
+    """
+    if isinstance(pubkey, str):
+        try:
+            return Pubkey.from_string(pubkey)
+        except Exception as e:
+            raise ValidationError(f"Invalid {name}: {str(e)}")
+
+    if isinstance(pubkey, Pubkey):
+        return pubkey
+
+    raise ValidationError(f"{name} must be a string or Pubkey object")
+
+
+def validate_pool_reserves(base_reserve: int, quote_reserve: int) -> None:
+    """
+    Validate pool reserves
+
+    Args:
+        base_reserve: Base token reserve
+        quote_reserve: Quote token reserve
+
+    Raises:
+        ValidationError: If reserves are invalid
+    """
+    validate_amount(base_reserve, "base_reserve")
+    validate_amount(quote_reserve, "quote_reserve")
+
+    # Check for minimum liquidity
+    min_liquidity = 1000  # Minimum tokens to prevent precision issues
+    if base_reserve < min_liquidity:
+        raise ValidationError(f"Base reserve ({base_reserve}) below minimum ({min_liquidity})")
+
+    if quote_reserve < min_liquidity:
+        raise ValidationError(f"Quote reserve ({quote_reserve}) below minimum ({min_liquidity})")
+
+
+def validate_lp_supply(lp_supply: int, allow_zero: bool = False) -> None:
+    """
+    Validate LP token supply
+
+    Args:
+        lp_supply: LP token supply
+        allow_zero: Whether zero supply is allowed (for initial pools)
+
+    Raises:
+        ValidationError: If supply is invalid
+    """
+    validate_amount(lp_supply, "lp_supply", allow_zero=allow_zero)
+
+
+def validate_swap_parameters(
+    amount_in: int,
+    amount_out_min: int,
+    slippage_bps: int
+) -> None:
+    """
+    Validate swap parameters
+
+    Args:
+        amount_in: Input amount
+        amount_out_min: Minimum output amount
+        slippage_bps: Slippage tolerance
+
+    Raises:
+        ValidationError: If parameters are invalid
+    """
+    validate_amount(amount_in, "amount_in")
+    validate_amount(amount_out_min, "amount_out_min", allow_zero=True)
+    validate_slippage(slippage_bps)
+
+
+def validate_deposit_parameters(
+    base_amount: int,
+    quote_amount: int,
+    lp_amount: int,
+    slippage_bps: int
+) -> None:
+    """
+    Validate liquidity deposit parameters
+
+    Args:
+        base_amount: Base token amount
+        quote_amount: Quote token amount
+        lp_amount: Expected LP token amount
+        slippage_bps: Slippage tolerance
+
+    Raises:
+        ValidationError: If parameters are invalid
+    """
+    validate_amount(base_amount, "base_amount", allow_zero=True)
+    validate_amount(quote_amount, "quote_amount", allow_zero=True)
+    validate_amount(lp_amount, "lp_amount")
+    validate_slippage(slippage_bps)
+
+    # At least one token amount must be positive
+    if base_amount == 0 and quote_amount == 0:
+        raise ValidationError("Either base_amount or quote_amount must be positive")
+
+
+def validate_withdrawal_parameters(
+    lp_amount: int,
+    min_base: int,
+    min_quote: int,
+    slippage_bps: int
+) -> None:
+    """
+    Validate liquidity withdrawal parameters
+
+    Args:
+        lp_amount: LP token amount to burn
+        min_base: Minimum base token amount
+        min_quote: Minimum quote token amount
+        slippage_bps: Slippage tolerance
+
+    Raises:
+        ValidationError: If parameters are invalid
+    """
+    validate_amount(lp_amount, "lp_amount")
+    validate_amount(min_base, "min_base", allow_zero=True)
+    validate_amount(min_quote, "min_quote", allow_zero=True)
+    validate_slippage(slippage_bps)
+
+
+def validate_pool_creation_parameters(
+    index: int,
+    creator: Union[str, Pubkey],
+    base_mint: Union[str, Pubkey],
+    quote_mint: Union[str, Pubkey],
+    initial_base: int,
+    initial_quote: int
+) -> None:
+    """
+    Validate pool creation parameters
+
+    Args:
+        index: Pool index
+        creator: Pool creator address
+        base_mint: Base token mint
+        quote_mint: Quote token mint
+        initial_base: Initial base token amount
+        initial_quote: Initial quote token amount
+
+    Raises:
+        ValidationError: If parameters are invalid
+    """
+    validate_amount(index, "index", allow_zero=True)
+    validate_pubkey(creator, "creator")
+    validate_pubkey(base_mint, "base_mint")
+    validate_pubkey(quote_mint, "quote_mint")
+    validate_amount(initial_base, "initial_base")
+    validate_amount(initial_quote, "initial_quote")
+
+    # Base and quote mints must be different
+    base_pubkey = validate_pubkey(base_mint, "base_mint")
+    quote_pubkey = validate_pubkey(quote_mint, "quote_mint")
+
+    if base_pubkey == quote_pubkey:
+        raise ValidationError("Base mint and quote mint cannot be the same")
+
+
+def validate_fee_calculation_inputs(
+    market_cap: int,
+    volume: int,
+    fee_rates: dict
+) -> None:
+    """
+    Validate inputs for fee calculation
+
+    Args:
+        market_cap: Token market cap
+        volume: Trading volume
+        fee_rates: Dictionary of fee rates
+
+    Raises:
+        ValidationError: If inputs are invalid
+    """
+    validate_amount(market_cap, "market_cap", allow_zero=True)
+    validate_amount(volume, "volume", allow_zero=True)
+
+    required_rates = ["lp_fee_bps", "protocol_fee_bps", "creator_fee_bps"]
+    for rate_name in required_rates:
+        if rate_name not in fee_rates:
+            raise ValidationError(f"Missing required fee rate: {rate_name}")
+        validate_fee_rate(fee_rates[rate_name], rate_name)
+
+    # Validate total fee rate
+    total_fee_bps = sum(fee_rates[rate] for rate in required_rates)
+    if total_fee_bps > BASIS_POINTS:
+        raise ValidationError(f"Total fee rates ({total_fee_bps} bps) exceed 100%")
+
+
+def validate_range(
+    value: int,
+    min_value: int,
+    max_value: int,
+    name: str = "value"
+) -> None:
+    """
+    Validate that a value is within a specific range
+
+    Args:
+        value: Value to validate
+        min_value: Minimum allowed value
+        max_value: Maximum allowed value
+        name: Parameter name for error messages
+
+    Raises:
+        ValidationError: If value is out of range
+    """
+    if not isinstance(value, int):
+        raise ValidationError(f"{name} must be an integer")
+
+    if value < min_value or value > max_value:
+        raise ValidationError(f"{name} ({value}) must be between {min_value} and {max_value}")
+
+
+def validate_percentage(percentage: float, name: str = "percentage") -> None:
+    """
+    Validate percentage value (0-100)
+
+    Args:
+        percentage: Percentage value
+        name: Parameter name for error messages
+
+    Raises:
+        ValidationError: If percentage is invalid
+    """
+    if not isinstance(percentage, (int, float)):
+        raise ValidationError(f"{name} must be a number")
+
+    if percentage < 0 or percentage > 100:
+        raise ValidationError(f"{name} ({percentage}%) must be between 0 and 100")

pumpswap_python_sdk-1.0.0.dist-info/METADATA

@@ -0,0 +1,399 @@
+Metadata-Version: 2.4
+Name: pumpswap-python-sdk
+Version: 1.0.0
+Summary: Python SDK for interacting with Pump Swap AMM protocol on Solana
+Home-page: https://github.com/pump-fun/pump-swap-sdk-python
+Author: PumpSwap Python SDK Contributors
+Author-email: PumpSwap Python SDK Contributors <dev@pump.fun>
+Maintainer-email: PumpSwap Team <dev@pump.fun>
+License: MIT
+Project-URL: Documentation, https://docs.pump.fun/sdk/python
+Project-URL: Repository, https://github.com/pump-fun/pump-swap-sdk-python
+Project-URL: Issues, https://github.com/pump-fun/pump-swap-sdk-python/issues
+Project-URL: Homepage, https://pump.fun
+Keywords: solana,blockchain,defi,amm,swap,liquidity,pump,cryptocurrency,trading
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: Office/Business :: Financial :: Investment
+Classifier: Topic :: System :: Networking
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: solders>=0.20.0
+Requires-Dist: solana>=0.32.0
+Requires-Dist: construct>=2.10.0
+Requires-Dist: typing-extensions>=4.0.0; python_version < "3.10"
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0.0; extra == "dev"
+Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.21.0; extra == "dev"
+Requires-Dist: black>=23.0.0; extra == "dev"
+Requires-Dist: isort>=5.0.0; extra == "dev"
+Requires-Dist: flake8>=6.0.0; extra == "dev"
+Requires-Dist: mypy>=1.0.0; extra == "dev"
+Requires-Dist: pre-commit>=3.0.0; extra == "dev"
+Provides-Extra: docs
+Requires-Dist: sphinx>=6.0.0; extra == "docs"
+Requires-Dist: sphinx-rtd-theme>=1.2.0; extra == "docs"
+Requires-Dist: myst-parser>=1.0.0; extra == "docs"
+Provides-Extra: testing
+Requires-Dist: pytest>=7.0.0; extra == "testing"
+Requires-Dist: pytest-cov>=4.0.0; extra == "testing"
+Requires-Dist: pytest-asyncio>=0.21.0; extra == "testing"
+Requires-Dist: responses>=0.23.0; extra == "testing"
+Dynamic: author
+Dynamic: home-page
+Dynamic: license-file
+Dynamic: requires-python
+
+# PumpSwap SDK Python
+
+A complete Python SDK for interacting with the Pump Swap AMM protocol on Solana. This SDK provides both high-level and low-level interfaces for creating pools, performing swaps, managing liquidity, and collecting fees.
+
+## Features
+
+- 🔄 **Token Swaps**: Buy and sell tokens using constant product AMM formula
+- 💧 **Liquidity Management**: Add and remove liquidity from pools
+- 🏭 **Pool Creation**: Create new AMM pools with custom parameters
+- 💰 **Fee Collection**: Collect protocol and creator fees
+- 🎁 **Token Incentives**: Claim trading rewards and incentives
+- 📊 **Real-time Data**: Fetch live pool data and user balances
+- 🔧 **Admin Functions**: Protocol administration and configuration
+- ✅ **Full Validation**: Comprehensive input validation and error handling
+
+## Installation
+
+```bash
+pip install pumpswap-python-sdk
+```
+
+For development:
+
+```bash
+pip install pumpswap-python-sdk[dev]
+```
+
+## Quick Start
+
+### Basic Usage
+
+```python
+from pump_swap_sdk import PumpAmmSdk, OnlinePumpAmmSdk
+from solana.rpc.api import Client
+from solders.pubkey import Pubkey
+
+# Initialize SDK with blockchain connection
+connection = Client("https://api.mainnet-beta.solana.com")
+sdk = OnlinePumpAmmSdk(connection=connection)
+
+# Get pool state for swaps
+pool_address = Pubkey.from_string("YOUR_POOL_ADDRESS")
+user_address = Pubkey.from_string("YOUR_WALLET_ADDRESS")
+
+swap_state = sdk.swap_solana_state(pool_address, user_address)
+
+# Calculate swap amounts
+result = sdk.buy_base_input(
+    swap_state=swap_state,
+    base=1_000_000,  # 1 token (6 decimals)
+    slippage=100     # 1% slippage
+)
+
+print(f"Quote needed: {result.ui_quote}")
+print(f"Max quote with slippage: {result.max_quote}")
+```
+
+### Creating a Pool
+
+```python
+from pump_swap_sdk import OnlinePumpAmmSdk
+from solders.keypair import Keypair
+
+# Initialize with your keypair
+creator_keypair = Keypair.from_secret_key(your_secret_key)
+sdk = OnlinePumpAmmSdk(connection=connection)
+
+# Create pool state
+create_state = sdk.create_pool_solana_state(
+    index=0,
+    creator=creator_keypair.pubkey(),
+    base_mint=Pubkey.from_string("BASE_TOKEN_MINT"),
+    quote_mint=Pubkey.from_string("QUOTE_TOKEN_MINT")
+)
+
+# Build creation instructions
+instructions = sdk.create_pool_instructions(
+    create_pool_state=create_state,
+    base_in=1_000_000_000,    # Initial base tokens
+    quote_in=1_000_000_000    # Initial quote tokens
+)
+```
+
+### Managing Liquidity
+
+```python
+# Get liquidity state
+liquidity_state = sdk.liquidity_solana_state(pool_address, user_address)
+
+# Add liquidity with base token amount
+deposit_result = sdk.deposit_base_input(
+    liquidity_state=liquidity_state,
+    base=1_000_000,  # Base token amount
+    slippage=100     # 1% slippage
+)
+
+print(f"Quote needed: {deposit_result.quote}")
+print(f"LP tokens to receive: {deposit_result.lp_token}")
+
+# Remove liquidity
+withdraw_result = sdk.withdraw_inputs(
+    liquidity_state=liquidity_state,
+    lp_amount=500_000,  # LP tokens to burn
+    slippage=100        # 1% slippage
+)
+
+print(f"Base tokens to receive: {withdraw_result.base}")
+print(f"Quote tokens to receive: {withdraw_result.quote}")
+```
+
+## Advanced Usage
+
+### Offline SDK (No Blockchain Connection)
+
+```python
+from pump_swap_sdk import PumpAmmSdk
+
+# Use offline SDK for calculations without network calls
+offline_sdk = PumpAmmSdk()
+
+# You'll need to provide the state data manually
+from pump_swap_sdk.types import SwapSolanaState, Pool, GlobalConfig
+
+# Build state with your data
+swap_state = SwapSolanaState(
+    pool=your_pool_data,
+    global_config=your_global_config,
+    pool_base_amount=base_reserve,
+    pool_quote_amount=quote_reserve,
+    # ... other required fields
+)
+
+# Perform calculations
+result = offline_sdk.buy_base_input(swap_state, 1_000_000, 100)
+```
+
+### Fee Calculations
+
+```python
+from pump_swap_sdk.sdk.fees import compute_fees_bps
+
+# Calculate current fee rates
+fees = compute_fees_bps(
+    global_config=global_config,
+    fee_config=fee_config,
+    market_cap=current_market_cap
+)
+
+print(f"LP Fee: {fees.lp_fee_bps} bps")
+print(f"Protocol Fee: {fees.protocol_fee_bps} bps")
+print(f"Creator Fee: {fees.creator_fee_bps} bps")
+print(f"Total Fee: {fees.total_fee_bps} bps")
+```
+
+### Token Incentives
+
+```python
+# Check unclaimed rewards
+unclaimed = sdk.get_total_unclaimed_tokens(user_address)
+print(f"Unclaimed tokens: {unclaimed}")
+
+# Check today's earned rewards
+today_rewards = sdk.get_current_day_tokens(user_address)
+print(f"Today's rewards: {today_rewards}")
+```
+
+## SDK Architecture
+
+### Core Classes
+
+- **`PumpAmmSdk`**: High-level offline SDK for calculations
+- **`OnlinePumpAmmSdk`**: Online SDK with blockchain connectivity
+- **`PumpAmmAdminSdk`**: Admin SDK for protocol management
+
+### Key Modules
+
+- **`swap_operations`**: Buy/sell token calculations
+- **`liquidity_operations`**: Deposit/withdraw liquidity calculations
+- **`fees`**: Fee calculation utilities
+- **`token_incentives`**: Trading reward calculations
+- **`pda`**: Program Derived Address utilities
+- **`utils`**: Mathematical and utility functions
+
+## Mathematical Formulas
+
+The SDK implements a **constant product AMM** using the formula `x * y = k`:
+
+### Swap Calculations
+
+**Buy tokens (base input)**:
+```
+quote_needed = ceil_div(quote_reserve * base_amount, base_reserve - base_amount)
+```
+
+**Sell tokens (base input)**:
+```
+quote_received = floor_div(quote_reserve * base_amount, base_reserve + base_amount)
+```
+
+### Liquidity Calculations
+
+**LP tokens for deposit**:
+```
+lp_tokens = min(
+    base_amount * total_lp_supply / base_reserve,
+    quote_amount * total_lp_supply / quote_reserve
+)
+```
+
+**Tokens from LP withdrawal**:
+```
+base_amount = lp_amount * base_reserve / total_lp_supply
+quote_amount = lp_amount * quote_reserve / total_lp_supply
+```
+
+## Error Handling
+
+The SDK provides comprehensive error handling:
+
+```python
+from pump_swap_sdk.exceptions import (
+    InsufficientLiquidityError,
+    SlippageExceededError,
+    ValidationError
+)
+
+try:
+    result = sdk.buy_base_input(swap_state, amount, slippage)
+except InsufficientLiquidityError:
+    print("Not enough liquidity for this trade")
+except SlippageExceededError:
+    print("Price moved beyond slippage tolerance")
+except ValidationError as e:
+    print(f"Invalid input: {e}")
+```
+
+## Configuration
+
+### Environment Variables
+
+```bash
+# Solana RPC endpoint
+SOLANA_RPC_URL=https://api.mainnet-beta.solana.com
+
+# Program ID (optional, defaults to mainnet)
+PUMP_AMM_PROGRAM_ID=6EF8rrecthR5Dkzon8Nwu78hRvfCKubJ14M5uBEwF6P
+```
+
+### Custom Configuration
+
+```python
+from pump_swap_sdk import OnlinePumpAmmSdk
+from solders.pubkey import Pubkey
+
+# Use custom program ID
+custom_program_id = Pubkey.from_string("YOUR_PROGRAM_ID")
+sdk = OnlinePumpAmmSdk(
+    connection=connection,
+    program_id=custom_program_id
+)
+```
+
+## Testing
+
+Run the test suite:
+
+```bash
+# Install development dependencies
+pip install -e .[dev]
+
+# Run tests
+pytest
+
+# Run with coverage
+pytest --cov=pump_swap_sdk --cov-report=html
+
+# Run specific test categories
+pytest -m unit        # Unit tests only
+pytest -m integration # Integration tests only
+```
+
+## Examples
+
+Check out the `examples/` directory for complete working examples:
+
+- **`basic_swap.py`**: Simple token swap
+- **`liquidity_management.py`**: Add/remove liquidity
+- **`pool_creation.py`**: Create a new AMM pool
+- **`fee_calculation.py`**: Calculate trading fees
+- **`admin_operations.py`**: Protocol administration
+
+## Contributing
+
+We welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md) for details.
+
+### Development Setup
+
+```bash
+# Clone the repository
+git clone https://github.com/pump-fun/pump-swap-sdk-python.git
+cd pump-swap-sdk-python
+
+# Create virtual environment
+python -m venv venv
+source venv/bin/activate  # Linux/Mac
+# or
+venv\\Scripts\\activate  # Windows
+
+# Install in development mode
+pip install -e .[dev]
+
+# Install pre-commit hooks
+pre-commit install
+
+# Run tests
+pytest
+```
+
+## Documentation
+
+- [Full API Documentation](https://docs.pump.fun/sdk/python)
+- [Protocol Documentation](https://docs.pump.fun)
+- [Examples](./examples/)
+
+## Support
+
+- [GitHub Issues](https://github.com/pump-fun/pump-swap-sdk-python/issues)
+- [Discord Community](https://discord.gg/pump)
+- [Documentation](https://docs.pump.fun)
+
+## License
+
+This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
+
+## Related Projects
+
+- [Pump Swap TypeScript SDK](https://github.com/pump-fun/pump-swap-sdk)
+- [Pump.fun Frontend](https://pump.fun)
+- [Solana Program](https://github.com/pump-fun/pump-swap-program)
+
+---
+
+Built with ❤️ by the Pump.fun team