Merge pull request #30 from helloissariel/main

[solana] Add Solana crypto toolkit

Author: moonpyt

spoon_toolkits/crypto/solana/__init__.py

@@ -0,0 +1,108 @@
+"""Solana toolkit exports for SpoonAI."""
+
+# Transfer tools
+from .transfer import SolanaTransferTool
+
+# Swap tools
+from .swap import SolanaSwapTool
+
+# Wallet management tools
+from .wallet import (
+    SolanaWalletInfoTool,
+)
+
+# Blockchain service tools and helpers
+from .service import (
+    create_request_headers,
+    detect_private_keys_from_string,
+    detect_pubkeys_from_string,
+    format_token_amount,
+    get_api_key,
+    get_rpc_url,
+    get_wallet_cache_scheduler,
+    is_native_sol,
+    lamports_to_sol,
+    parse_token_amount,
+    parse_transaction_error,
+    sol_to_lamports,
+    truncate_address,
+    validate_private_key,
+    validate_solana_address,
+    verify_solana_signature,
+)
+
+# Keypair utilities
+from .keypairUtils import get_wallet_keypair, get_wallet_key, get_private_key, get_public_key
+
+# Plugin integration
+from .index import solana_plugin, PluginManifest, ProviderDefinition, wallet_provider, init_plugin
+
+# Environment helpers
+from .environment import load_solana_config, SolanaConfig
+
+# Shared constants
+from .constants import NATIVE_SOL_ADDRESS, TOKEN_ADDRESSES, DEFAULT_SLIPPAGE_BPS, JUPITER_PRIORITY_LEVELS
+
+# Typed models
+from .types import (
+    WalletPortfolio,
+    Item,
+    Prices,
+    TransferContent,
+    SwapContent,
+    KeypairResult,
+    TokenMetadata,
+)
+
+__all__ = [
+    # Transfer tools
+    "SolanaTransferTool",
+    # Swap tools
+    "SolanaSwapTool",
+    # Wallet tools
+    "SolanaWalletInfoTool",
+    # Service tools & helpers
+    "create_request_headers",
+    "detect_private_keys_from_string",
+    "detect_pubkeys_from_string",
+    "format_token_amount",
+    "get_api_key",
+    "get_rpc_url",
+    "get_wallet_cache_scheduler",
+    "is_native_sol",
+    "lamports_to_sol",
+    "parse_token_amount",
+    "parse_transaction_error",
+    "sol_to_lamports",
+    "truncate_address",
+    "validate_private_key",
+    "validate_solana_address",
+    "verify_solana_signature",
+    # Key utilities
+    "get_wallet_keypair",
+    "get_wallet_key",
+    "get_private_key",
+    "get_public_key",
+    # Plugin integration
+    "solana_plugin",
+    "PluginManifest",
+    "ProviderDefinition",
+    "wallet_provider",
+    "init_plugin",
+    # Environment helpers
+    "load_solana_config",
+    "SolanaConfig",
+    # Constants
+    "NATIVE_SOL_ADDRESS",
+    "TOKEN_ADDRESSES",
+    "DEFAULT_SLIPPAGE_BPS",
+    "JUPITER_PRIORITY_LEVELS",
+    # Typed models
+    "WalletPortfolio",
+    "Item",
+    "Prices",
+    "TransferContent",
+    "SwapContent",
+    "KeypairResult",
+    "TokenMetadata",
+]

spoon_toolkits/crypto/solana/bignumber.py

@@ -0,0 +1,36 @@
+from decimal import Decimal, getcontext
+from typing import Union
+
+getcontext().prec = 10
+
+class BigNumber(Decimal):
+    def __new__(cls, value: Union[str, float, int, Decimal, "BigNumber"]) -> "BigNumber":
+        return super().__new__(cls, str(value))
+
+    def plus(self, other: Union[str, float, int, Decimal, "BigNumber"]) -> "BigNumber":
+        return BigNumber(self + Decimal(str(other)))
+
+    def minus(self, other: Union[str, float, int, Decimal, "BigNumber"]) -> "BigNumber":
+        return BigNumber(self - Decimal(str(other)))
+
+    def multiplied_by(self, other: Union[str, float, int, Decimal, "BigNumber"]) -> "BigNumber":
+        return BigNumber(self * Decimal(str(other)))
+
+    def divided_by(self, other: Union[str, float, int, Decimal, "BigNumber"]) -> "BigNumber":
+        return BigNumber(self / Decimal(str(other)))
+
+    def pow(self, exponent: int) -> "BigNumber":
+        return BigNumber(self ** Decimal(exponent))
+
+    def to_number(self) -> float:
+        return float(self)
+
+    def to_string(self) -> str:
+        return format(self, "f")
+
+BN = BigNumber
+
+
+def toBN(value: Union[str, float, int, Decimal, BigNumber]) -> BigNumber:
+    """Convert a value to a BigNumber (Decimal) object."""
+    return BigNumber(value)

spoon_toolkits/crypto/solana/constants.py

@@ -0,0 +1,61 @@
+"""Solana toolkit constants，This module defines constants used throughout the Solana toolkit"""
+
+# Service and Cache Configuration
+SOLANA_SERVICE_NAME = "chain_solana"
+SOLANA_WALLET_DATA_CACHE_KEY = "solana/walletData"
+
+# Token Program IDs
+TOKEN_PROGRAM_ID = None
+TOKEN_2022_PROGRAM_ID = None
+ASSOCIATED_TOKEN_PROGRAM_ID = None
+
+# System Program ID
+SYSTEM_PROGRAM_ID = None
+
+# Metadata Program ID (Metaplex)
+METADATA_PROGRAM_ID = None
+
+TOKEN_ADDRESSES = {
+    "SOL": None, 
+    "USDC": None, 
+    "USDT": None, 
+    "BTC": None,  
+    "ETH": None,   
+}
+
+# Native SOL placeholder address (used for swaps)
+NATIVE_SOL_ADDRESS = None
+
+# Transaction Configuration
+DEFAULT_PRIORITY_FEE = 5  # micro-lamports per compute unit
+MAX_RETRIES = 3
+RETRY_DELAY = 2.0  # seconds
+
+# Slippage Configuration
+DEFAULT_SLIPPAGE_BPS = 100  # 1%
+MAX_SLIPPAGE_BPS = 3000     # 30%
+
+# Cache Configuration
+UPDATE_INTERVAL = 120  # seconds
+CACHE_TTL = 300       # seconds
+
+# Account Data Lengths
+TOKEN_ACCOUNT_DATA_LENGTH = 165
+TOKEN_MINT_DATA_LENGTH = 82
+
+# Environment Variable Keys
+ENV_KEYS = {
+    "RPC_URL": ["SOLANA_RPC_URL", "RPC_URL"],
+    "PRIVATE_KEY": ["SOLANA_PRIVATE_KEY", "WALLET_PRIVATE_KEY"],
+    "PUBLIC_KEY": ["SOLANA_PUBLIC_KEY", "WALLET_PUBLIC_KEY"],
+    "HELIUS_API_KEY": ["HELIUS_API_KEY"],
+    "BIRDEYE_API_KEY": ["BIRDEYE_API_KEY"],
+}
+
+# Priority Levels for Jupiter
+JUPITER_PRIORITY_LEVELS = {
+    "low": 50,
+    "medium": 200,
+    "high": 1000,
+    "veryHigh": 4_000_000,
+}

spoon_toolkits/crypto/solana/environment.py

@@ -0,0 +1,120 @@
+"""Solana environment configuration validation."""
+
+from __future__ import annotations
+
+import os
+import logging
+from typing import Any, Optional
+
+from pydantic import BaseModel, Field, ValidationError, model_validator, ConfigDict
+
+logger = logging.getLogger(__name__)
+
+
+class SolanaConfig(BaseModel):
+    """Validated configuration required for Solana toolkit operations."""
+
+    wallet_secret_salt: Optional[str] = Field(default=None, alias="WALLET_SECRET_SALT")
+    wallet_secret_key: Optional[str] = Field(default=None, alias="WALLET_SECRET_KEY")
+    wallet_public_key: Optional[str] = Field(default=None, alias="WALLET_PUBLIC_KEY")
+
+    sol_address: str = Field(alias="SOL_ADDRESS")
+    slippage: str = Field(alias="SLIPPAGE")
+    solana_rpc_url: str = Field(alias="SOLANA_RPC_URL")
+    helius_api_key: str = Field(alias="HELIUS_API_KEY")
+    birdeye_api_key: str = Field(alias="BIRDEYE_API_KEY")
+
+    model_config = ConfigDict(populate_by_name=True, extra="forbid")
+
+    @model_validator(mode="after")
+    def _validate_key_material(cls, values: "SolanaConfig") -> "SolanaConfig":
+        """Ensure either a secret salt or keypair credentials are present."""
+        has_salt = bool(values.wallet_secret_salt)
+        has_keypair = bool(values.wallet_secret_key and values.wallet_public_key)
+
+        if not (has_salt or has_keypair):
+            raise ValueError(
+                "Provide WALLET_SECRET_SALT or both WALLET_SECRET_KEY and WALLET_PUBLIC_KEY."
+            )
+        return values
+
+
+def _runtime_get(runtime: Any, key: str) -> Optional[str]:
+    """Attempt to read a setting from a runtime object if available."""
+    if runtime is None:
+        return None
+
+    for attr in ("get_setting", "getSetting", "get"):
+        getter = getattr(runtime, attr, None)
+        if callable(getter):
+            try:
+                value = getter(key)
+            except TypeError:
+                # Getter signature mismatch – try next option
+                continue
+            if value is not None:
+                return value
+
+    # Common pattern: runtime.settings dict
+    settings = getattr(runtime, "settings", None)
+    if isinstance(settings, dict):
+        return settings.get(key)
+
+    return None
+
+
+def _read_config_value(runtime: Any, *keys: str) -> Optional[str]:
+    """Return the first non-empty value from runtime or environment for the provided keys."""
+    for key in keys:
+        value = _runtime_get(runtime, key)
+        if value is None:
+            value = os.getenv(key)
+
+        if isinstance(value, str):
+            value = value.strip()
+
+        if value:
+            return value
+
+    return None
+
+
+def load_solana_config(runtime: Any = None) -> SolanaConfig:
+    """Validate and return Solana configuration based on runtime settings and environment variables.
+
+    Args:
+        runtime: Optional runtime object providing a ``get_setting``-style API.
+
+    Returns:
+        SolanaConfig: Validated configuration object.
+
+    Raises:
+        ValueError: When validation fails or required fields are missing.
+    """
+    config_payload = {
+        "WALLET_SECRET_SALT": _read_config_value(runtime, "WALLET_SECRET_SALT"),
+        "WALLET_SECRET_KEY": _read_config_value(runtime, "WALLET_SECRET_KEY"),
+        "WALLET_PUBLIC_KEY": _read_config_value(
+            runtime,
+            "SOLANA_PUBLIC_KEY",
+            "WALLET_PUBLIC_KEY",
+        ),
+        "SOL_ADDRESS": _read_config_value(runtime, "SOL_ADDRESS"),
+        "SLIPPAGE": _read_config_value(runtime, "SLIPPAGE"),
+        "SOLANA_RPC_URL": _read_config_value(runtime, "SOLANA_RPC_URL"),
+        "HELIUS_API_KEY": _read_config_value(runtime, "HELIUS_API_KEY"),
+        "BIRDEYE_API_KEY": _read_config_value(runtime, "BIRDEYE_API_KEY"),
+    }
+
+    try:
+        return SolanaConfig(**config_payload)
+    except ValidationError as exc:
+        messages = []
+        for error in exc.errors():
+            location = ".".join(str(part) for part in error.get("loc", ()))
+            messages.append(f"{location or 'configuration'}: {error.get('msg')}")
+
+        detail = "\n".join(messages) or str(exc)
+        logger.error("Solana configuration validation failed:\n%s", detail)
+        raise ValueError(f"Solana configuration validation failed:\n{detail}") from exc
+