mm-sol 0.7.4__tar.gz → 0.8.0__tar.gz

mm_sol-0.8.0/.claude/settings.local.json

@@ -0,0 +1,7 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(just lint:*)"
+    ]
+  }
+}

mm_sol-0.8.0/CLAUDE.md

@@ -0,0 +1,24 @@
+# AI Agent Start Guide
+
+## Critical: Language
+RESPOND IN ENGLISH. Always. No exceptions.
+User's language does NOT determine your response language.
+Only switch if user EXPLICITLY requests it (e.g., "respond in {language}").
+Language switching applies ONLY to chat. All code, comments, commit messages, and files must ALWAYS be in English — no exceptions.
+
+## Mandatory Rules (external)
+These files are REQUIRED. Read them fully and follow all rules.
+- `~/.claude/shared-rules/general.md`
+- `~/.claude/shared-rules/python.md`
+
+## Project Reading (context)
+These files are REQUIRED for project understanding.
+- `README.md`
+
+## Preflight (mandatory)
+Before your first response:
+1. Read all files listed above.
+2. Do not answer until all are read.
+3. In your first reply, list every file you have read from this document.
+
+Failure to follow this protocol is considered an error.

{mm_sol-0.7.4 → mm_sol-0.8.0}/PKG-INFO

@@ -1,10 +1,10 @@
 Metadata-Version: 2.4
 Name: mm-sol
-Version: 0.7.4
-Requires-Python: >=3.13
+Version: 0.8.0
+Requires-Python: >=3.14
 Requires-Dist: base58~=2.1.1
 Requires-Dist: jinja2~=3.1.6
-Requires-Dist: mm-web3~=0.5.6
+Requires-Dist: mm-web3~=0.6.2
 Requires-Dist: mnemonic==0.21
 Requires-Dist: solana~=0.36.11
 Requires-Dist: typer~=0.21.1

mm_sol-0.8.0/pyproject.toml

@@ -0,0 +1,87 @@
+[project]
+name = "mm-sol"
+version = "0.8.0"
+description = ""
+requires-python = ">=3.14"
+dependencies = [
+    "mm-web3~=0.6.2",
+    "solana~=0.36.11",
+    "base58~=2.1.1",
+    "mnemonic==0.21",
+    "typer~=0.21.1",
+    "jinja2~=3.1.6",
+    # "socksio>=1.0.0",
+]
+[project.scripts]
+mm-sol = "mm_sol.cli.cli:app"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[dependency-groups]
+dev = [
+    "bandit~=1.9.3",
+    "mypy~=1.19.1",
+    "pip-audit~=2.10.0",
+    "pre-commit~=4.5.1",
+    "pytest~=9.0.2",
+    "pytest-asyncio~=1.3.0",
+    "pytest-xdist~=3.8.0",
+    "ruff~=0.15.0",
+    "python-dotenv~=1.2.0",
+]
+
+[tool.mypy]
+python_version = "3.14"
+mypy_path = "stubs"
+warn_no_return = false
+implicit_reexport = true
+strict = true
+exclude = ["^tests/", "^tmp/"]
+
+[tool.ruff]
+line-length = 130
+target-version = "py314"
+[tool.ruff.lint]
+select = ["ALL"]
+ignore = [
+    "TC",       # flake8-type-checking, TYPE_CHECKING is dangerous, for example it doesn't work with pydantic
+    "A005",     # flake8-builtins: stdlib-module-shadowing
+    "ERA001",   # eradicate: commented-out-code
+    "PT",       # flake8-pytest-style
+    "FIX",      # flake8-fixme
+    "PLR0911",  # pylint: too-many-return-statements
+    "PLR0912",  # pylint: too-many-branches
+    "PLR0913",  # pylint: too-many-arguments
+    "PLR2004",  # pylint: magic-value-comparison
+    "PLC0414",  # pylint: useless-import-alias
+    "FBT",      # flake8-boolean-trap
+    "EM",       # flake8-errmsg
+    "TRY003",   # tryceratops: raise-vanilla-args
+    "C901",     # mccabe: complex-structure,
+    "BLE001",   # flake8-blind-except
+    "S311",     # bandit: suspicious-non-cryptographic-random-usage
+    "TD002",    # flake8-todos: missing-todo-author
+    "TD003",    # flake8-todos: missing-todo-link
+    "RET503",   # flake8-return: implicit-return
+    "COM812",   # it's used in ruff formatter
+    "ASYNC109", # flake8-async: async-function-with-timeout
+    "D203",     # pydocstyle: one-blank-line-before-class (conflicts with D211)
+    "D213",     # pydocstyle: multi-line-summary-second-line (conflicts with D212)
+]
+[tool.ruff.lint.pep8-naming]
+classmethod-decorators = ["field_validator"]
+[tool.ruff.lint.per-file-ignores]
+"tests/*.py" = ["ANN", "S"]
+[tool.ruff.format]
+quote-style = "double"
+indent-style = "space"
+
+[tool.bandit]
+exclude_dirs = ["tests"]
+skips = ["B311"]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+asyncio_default_fixture_loop_scope = "function"

mm_sol-0.8.0/src/mm_sol/__init__.py

@@ -0,0 +1 @@
+"""Library for interacting with Solana blockchain."""

{mm_sol-0.7.4 → mm_sol-0.8.0}/src/mm_sol/account.py

@@ -1,3 +1,5 @@
+"""Solana account management: key generation, derivation, and validation."""
+
 import contextlib
 from dataclasses import dataclass
 
@@ -8,10 +10,15 @@ from solders.keypair import Keypair
 from solders.pubkey import Pubkey
 
 PHANTOM_DERIVATION_PATH = "m/44'/501'/{i}'/0'"
+"""Default Phantom wallet derivation path template."""
+
 WORD_STRENGTH = {12: 128, 15: 160, 18: 192, 21: 224, 24: 256}
+"""Mapping of mnemonic word count to entropy bits."""
 
 
 class NewAccount(BaseModel):
+    """Newly generated Solana account with public and private keys."""
+
     public_key: str
     private_key_base58: str
     private_key_arr: list[int]
@@ -19,6 +26,8 @@ class NewAccount(BaseModel):
 
 @dataclass
 class DerivedAccount:
+    """Account derived from a mnemonic at a specific derivation path."""
+
     index: int
     path: str
     address: str
@@ -26,6 +35,7 @@ class DerivedAccount:
 
 
 def generate_mnemonic(num_words: int = 24) -> str:
+    """Generate a BIP39 mnemonic phrase with the specified number of words."""
     if num_words not in WORD_STRENGTH:
         raise ValueError(f"num_words must be one of {list(WORD_STRENGTH.keys())}")
     mnemonic = Mnemonic("english")
@@ -33,6 +43,7 @@ def generate_mnemonic(num_words: int = 24) -> str:
 
 
 def derive_accounts(mnemonic: str, passphrase: str, derivation_path: str, limit: int) -> list[DerivedAccount]:
+    """Derive multiple accounts from a mnemonic using the given derivation path template."""
     if "{i}" not in derivation_path:
         raise ValueError("derivation_path must contain {i}, for example: m/44'/501'/{i}'/0'")
 
@@ -54,6 +65,7 @@ def derive_accounts(mnemonic: str, passphrase: str, derivation_path: str, limit:
 
 
 def generate_account() -> NewAccount:
+    """Generate a new random Solana keypair and return it as a NewAccount."""
     keypair = Keypair()
     public_key = str(keypair.pubkey())
     private_key_base58 = base58.b58encode(bytes(keypair.to_bytes())).decode("utf-8")
@@ -62,6 +74,7 @@ def generate_account() -> NewAccount:
 
 
 def get_keypair(private_key: str | list[int]) -> Keypair:
+    """Create a Keypair from a base58 string, JSON array string, or integer list."""
     if isinstance(private_key, str):
         if "[" in private_key:
             private_key_ = [int(x) for x in private_key.replace("[", "").replace("]", "").split(",")]
@@ -73,12 +86,14 @@ def get_keypair(private_key: str | list[int]) -> Keypair:
 
 
 def check_private_key(public_key: str | Pubkey, private_key: str | list[int]) -> bool:
+    """Check whether a private key corresponds to the given public key."""
     if isinstance(public_key, str):
         public_key = Pubkey.from_string(public_key)
     return get_keypair(private_key).pubkey() == public_key
 
 
 def get_public_key(private_key: str) -> str:
+    """Derive the public key address from a private key string."""
     if "[" in private_key:
         private_key_ = [int(x) for x in private_key.replace("[", "").replace("]", "").split(",")]
     else:
@@ -87,20 +102,24 @@ def get_public_key(private_key: str) -> str:
 
 
 def get_private_key_base58(private_key: str) -> str:
+    """Convert a private key to base58 encoding."""
     keypair = get_keypair(private_key)
     return base58.b58encode(bytes(keypair.to_bytes())).decode("utf-8")
 
 
 def get_private_key_arr(private_key: str) -> list[int]:
+    """Convert a private key to a list of byte integers."""
     keypair = get_keypair(private_key)
     return list(x for x in keypair.to_bytes())  # noqa: C400
 
 
 def get_private_key_arr_str(private_key: str) -> str:
+    """Convert a private key to a JSON-style array string."""
     return f"[{','.join(str(x) for x in get_private_key_arr(private_key))}]"
 
 
 def is_address(pubkey: str) -> bool:
+    """Check whether a string is a valid Solana address."""
     with contextlib.suppress(Exception):
         Pubkey.from_string(pubkey)
         return True

mm_sol-0.8.0/src/mm_sol/cli/__init__.py

@@ -0,0 +1 @@
+"""CLI interface for mm-sol."""

{mm_sol-0.7.4 → mm_sol-0.8.0}/src/mm_sol/cli/calcs.py

@@ -1,3 +1,5 @@
+"""Value expression calculators for SOL and token amounts with optional balance variables."""
+
 from mm_result import Result
 from mm_web3 import Nodes, Proxies
 from mm_web3.calcs import calc_expression_with_vars
@@ -7,16 +9,19 @@ from mm_sol.constants import UNIT_DECIMALS
 
 
 def calc_sol_expression(expression: str, variables: dict[str, int] | None = None) -> int:
+    """Evaluate a SOL expression string into lamports."""
     return calc_expression_with_vars(expression, variables, unit_decimals=UNIT_DECIMALS)
 
 
 def calc_token_expression(expression: str, token_decimals: int, variables: dict[str, int] | None = None) -> int:
+    """Evaluate a token expression string into smallest units."""
     return calc_expression_with_vars(expression, variables, unit_decimals={"t": token_decimals})
 
 
 async def calc_sol_value_for_address(
     *, nodes: Nodes, value_expression: str, address: str, proxies: Proxies, fee: int
 ) -> Result[int]:
+    """Calculate SOL value in lamports for an address, resolving 'balance' variable if used."""
     value_expression = value_expression.lower()
     variables: dict[str, int] | None = None
     if "balance" in value_expression:
@@ -34,6 +39,7 @@ async def calc_sol_value_for_address(
 async def calc_token_value_for_address(
     *, nodes: Nodes, value_expression: str, owner: str, token: str, token_decimals: int, proxies: Proxies
 ) -> Result[int]:
+    """Calculate token value in smallest units for an address, resolving 'balance' variable if used."""
     variables: dict[str, int] | None = None
     value_expression = value_expression.lower()
     if "balance" in value_expression:

{mm_sol-0.7.4 → mm_sol-0.8.0}/src/mm_sol/cli/cli.py

@@ -1,10 +1,12 @@
+"""Main CLI entry point and command definitions for mm-sol."""
+
 import asyncio
-from enum import Enum
+from enum import StrEnum
 from pathlib import Path
 from typing import Annotated
 
-import mm_print
 import typer
+from mm_print import print_plain
 
 from mm_sol.account import PHANTOM_DERIVATION_PATH
 
@@ -13,8 +15,10 @@ from .cmd import balance_cmd, balances_cmd, example_cmd, node_cmd, transfer_cmd
 from .cmd.transfer_cmd import TransferCmdParams
 from .cmd.wallet import keypair_cmd, mnemonic_cmd
 
+"""Main CLI application."""
 app = typer.Typer(no_args_is_help=True, pretty_exceptions_enable=False, add_completion=False)
 
+"""Wallet subcommand group."""
 wallet_app = typer.Typer(
     no_args_is_help=True, help="Wallet-related commands: generate new accounts, derive addresses from private keys, and more"
 )
@@ -23,23 +27,27 @@ app.add_typer(wallet_app, name="w", hidden=True)
 
 
 def version_callback(value: bool) -> None:
+    """Print version and exit when --version is passed."""
     if value:
-        mm_print.plain(f"mm-sol: {cli_utils.get_version()}")
+        print_plain(f"mm-sol: {cli_utils.get_version()}")
         raise typer.Exit
 
 
 @app.callback()
 def main(_version: bool = typer.Option(None, "--version", callback=version_callback, is_eager=True)) -> None:
-    pass
+    """Solana CLI tool."""
+
 
+class ConfigExample(StrEnum):
+    """Available example configuration names."""
 
-class ConfigExample(str, Enum):
     balances = "balances"
     transfer = "transfer"
 
 
 @app.command(name="example", help="Displays an example configuration for a command")
 def example_command(command: Annotated[ConfigExample, typer.Argument()]) -> None:
+    """Display an example configuration for the given command."""
     example_cmd.run(command.value)
 
 
@@ -51,6 +59,7 @@ def balance_command(
     proxies_url: Annotated[str, typer.Option("--proxies-url", envvar="MM_SOL_PROXIES_URL")] = "",  # nosec
     lamport: bool = typer.Option(False, "--lamport", "-l", help="Print balances in lamports"),
 ) -> None:
+    """Fetch and print SOL and optional token balance for an account."""
     asyncio.run(balance_cmd.run(rpc_url, wallet_address, token_address, lamport, proxies_url))
 
 
@@ -58,6 +67,7 @@ def balance_command(
 def balances_command(
     config_path: Path, print_config: Annotated[bool, typer.Option("--config", "-c", help="Print config and exit")] = False
 ) -> None:
+    """Display SOL and token balances for multiple accounts from a config file."""
     asyncio.run(balances_cmd.run(config_path, print_config))
 
 
@@ -72,6 +82,7 @@ def transfer_command(
     no_confirmation: bool = typer.Option(False, "--no-confirmation", "-nc", help="Do not wait for confirmation"),
     debug: bool = typer.Option(False, "--debug", "-d", help="Print debug info"),
 ) -> None:
+    """Execute SOL or SPL token transfers based on a config file."""
     asyncio.run(
         transfer_cmd.run(
             TransferCmdParams(
@@ -93,6 +104,7 @@ def node_command(
     urls: Annotated[list[str], typer.Argument()],
     proxy: Annotated[str | None, typer.Option("--proxy", "-p", help="Proxy")] = None,
 ) -> None:
+    """Check RPC node availability by fetching block height."""
     asyncio.run(node_cmd.run(urls, proxy))
 
 
@@ -105,11 +117,13 @@ def wallet_mnemonic_command(  # nosec
     words: int = typer.Option(12, "--words", "-w", help="Number of mnemonic words"),
     limit: int = typer.Option(5, "--limit", "-l"),
 ) -> None:
+    """Generate or derive accounts from a mnemonic phrase."""
     mnemonic_cmd.run(mnemonic, passphrase, words, derivation_path, limit)
 
 
 @wallet_app.command(name="keypair", help="Print public, private_base58, private_arr by a private key")
 def keypair_command(private_key: str) -> None:
+    """Print keypair details from a private key."""
     keypair_cmd.run(private_key)
 
 

{mm_sol-0.7.4 → mm_sol-0.8.0}/src/mm_sol/cli/cli_utils.py

@@ -1,9 +1,13 @@
+"""Shared CLI utilities: config printing, RPC URL resolution, and helpers."""
+
 import importlib.metadata
 import time
 from pathlib import Path
+from typing import NoReturn
 
-import mm_print
+import typer
 from loguru import logger
+from mm_print import print_json
 from mm_web3 import Nodes, Proxies, Web3CliConfig, random_node, random_proxy
 from pydantic import BaseModel
 from solders.signature import Signature
@@ -12,23 +16,28 @@ from mm_sol.utils import get_client
 
 
 def get_version() -> str:
+    """Return the installed mm-sol package version."""
     return importlib.metadata.version("mm-sol")
 
 
 class BaseConfigParams(BaseModel):
+    """Base parameters shared by CLI commands that read a config file."""
+
     config_path: Path
     print_config_and_exit: bool
 
 
 def print_config(config: Web3CliConfig, exclude: set[str] | None = None, count: set[str] | None = None) -> None:
+    """Print a config as JSON, optionally replacing list fields with their counts."""
     data = config.model_dump(exclude=exclude)
     if count:
         for k in count:
             data[k] = len(data[k])
-    mm_print.json(data)
+    print_json(data)
 
 
 def public_rpc_url(url: str | None) -> str:
+    """Resolve a shorthand network name (mainnet/testnet/devnet) to its full RPC URL."""
     if not url:
         return "https://api.mainnet-beta.solana.com"
 
@@ -44,6 +53,7 @@ def public_rpc_url(url: str | None) -> str:
 
 
 def wait_confirmation(nodes: Nodes, proxies: Proxies, signature: Signature, log_prefix: str) -> bool:
+    """Poll for transaction confirmation, returning True if confirmed within 30 seconds."""
     count = 0
     while True:
         try:
@@ -60,3 +70,9 @@ def wait_confirmation(nodes: Nodes, proxies: Proxies, signature: Signature, log_
         if count > 30:
             logger.error(f"{log_prefix}: can't get confirmation, timeout")
             return False
+
+
+def fatal(message: str) -> NoReturn:
+    """Print an error message and exit with code 1."""
+    typer.echo(message)
+    raise typer.Exit(1)

mm_sol-0.8.0/src/mm_sol/cli/cmd/__init__.py

@@ -0,0 +1 @@
+"""CLI command implementations."""

{mm_sol-0.7.4 → mm_sol-0.8.0}/src/mm_sol/cli/cmd/balance_cmd.py

@@ -1,6 +1,8 @@
+"""Single account balance query command."""
+
 from decimal import Decimal
 
-import mm_print
+from mm_print import print_json
 from mm_web3 import fetch_proxies
 from pydantic import BaseModel, Field
 
@@ -10,6 +12,8 @@ from mm_sol.cli import cli_utils
 
 
 class HumanReadableBalanceResult(BaseModel):
+    """Balance result with SOL and token values in human-readable decimals."""
+
     sol_balance: Decimal | None
     token_balance: Decimal | None
     token_decimals: int | None
@@ -17,12 +21,15 @@ class HumanReadableBalanceResult(BaseModel):
 
 
 class BalanceResult(BaseModel):
+    """Balance result with SOL and token values in smallest units."""
+
     sol_balance: int | None = None
     token_balance: int | None = None
     token_decimals: int | None = None
     errors: list[str] = Field(default_factory=list)
 
     def to_human_readable(self) -> HumanReadableBalanceResult:
+        """Convert balances from smallest units to human-readable decimals."""
         sol_balance = Decimal(self.sol_balance) / 10**9 if self.sol_balance is not None else None
         token_balance = None
         if self.token_balance is not None and self.token_decimals is not None:
@@ -39,6 +46,7 @@ async def run(
     lamport: bool,
     proxies_url: str | None,
 ) -> None:
+    """Fetch and print SOL and optional token balance for a single account."""
     result = BalanceResult()
 
     rpc_url = cli_utils.public_rpc_url(rpc_url)
@@ -68,6 +76,6 @@ async def run(
             result.errors.append("token_decimals: " + decimals_res.unwrap_err())
 
     if lamport:
-        mm_print.json(result)
+        print_json(result)
     else:
-        mm_print.json(result.to_human_readable())
+        print_json(result.to_human_readable())

{mm_sol-0.7.4 → mm_sol-0.8.0}/src/mm_sol/cli/cmd/balances_cmd.py

@@ -1,18 +1,23 @@
+"""Multi-account balances query command."""
+
 import random
 from decimal import Decimal
 from pathlib import Path
 from typing import Annotated, Any
 
-import mm_print
+from mm_print import print_json
 from mm_web3 import ConfigValidators, Web3CliConfig
 from pydantic import BeforeValidator, Field
 
 import mm_sol.retry
 from mm_sol import converters, retry
+from mm_sol.cli.cli_utils import fatal
 from mm_sol.cli.validators import Validators
 
 
 class Config(Web3CliConfig):
+    """Configuration for the balances command."""
+
     accounts: Annotated[list[str], BeforeValidator(Validators.sol_addresses(unique=True))]
     tokens: Annotated[list[str], BeforeValidator(Validators.sol_addresses(unique=True))]
     nodes: Annotated[list[str], BeforeValidator(ConfigValidators.nodes())]
@@ -20,10 +25,12 @@ class Config(Web3CliConfig):
 
     @property
     def random_node(self) -> str:
+        """Return a randomly selected RPC node URL."""
         return random.choice(self.nodes)
 
 
 async def run(config_path: Path, print_config: bool) -> None:
+    """Fetch and print SOL and token balances for all configured accounts."""
     config = Config.read_toml_config_or_exit(config_path)
     if print_config:
         config.print_and_exit()
@@ -35,19 +42,20 @@ async def run(config_path: Path, print_config: bool) -> None:
         for token_address in config.tokens:
             res = await mm_sol.retry.get_token_decimals(3, config.nodes, config.proxies, token=token_address)
             if res.is_err():
-                mm_print.exit_with_error(f"Failed to get decimals for token {token_address}: {res.unwrap_err()}")
+                fatal(f"Failed to get decimals for token {token_address}: {res.unwrap_err()}")
 
             token_decimals = res.unwrap()
             result[token_address] = await _get_token_balances(token_address, token_decimals, config.accounts, config)
             result[token_address + "_decimals"] = token_decimals
             result[token_address + "_sum"] = sum([v for v in result[token_address].values() if v is not None])
 
-    mm_print.json(result)
+    print_json(result)
 
 
 async def _get_token_balances(
     token_address: str, token_decimals: int, accounts: list[str], config: Config
 ) -> dict[str, Decimal | None]:
+    """Fetch token balances for all accounts, returning a dict of address to balance."""
     result: dict[str, Decimal | None] = {}
     for account in accounts:
         result[account] = (
@@ -60,12 +68,11 @@ async def _get_token_balances(
 
 
 async def _get_sol_balances(accounts: list[str], config: Config) -> dict[str, Decimal | None]:
+    """Fetch SOL balances for all accounts, returning a dict of address to balance."""
     result = {}
     for account in accounts:
         result[account] = (
-            (await retry.get_sol_balance(3, config.nodes, config.proxies, address=account))
-            .map(lambda v: converters.lamports_to_sol(v))
-            .value
+            (await retry.get_sol_balance(3, config.nodes, config.proxies, address=account)).map(converters.lamports_to_sol).value
         )
 
     return result

mm_sol-0.8.0/src/mm_sol/cli/cmd/example_cmd.py

@@ -0,0 +1,11 @@
+"""Example config display command."""
+
+from pathlib import Path
+
+from mm_print import print_toml
+
+
+def run(module: str) -> None:
+    """Print the example TOML configuration for the given command module."""
+    example_file = Path(Path(__file__).parent.absolute(), "../examples", f"{module}.toml")
+    print_toml(example_file.read_text())

{mm_sol-0.7.4 → mm_sol-0.8.0}/src/mm_sol/cli/cmd/node_cmd.py

@@ -1,11 +1,14 @@
-import mm_print
+"""RPC node health check command."""
+
+from mm_print import print_json
 
 from mm_sol import rpc
 from mm_sol.cli import cli_utils
 
 
 async def run(urls: list[str], proxy: str | None) -> None:
+    """Check each RPC URL by fetching block height and print results."""
     result = {}
     for url in [cli_utils.public_rpc_url(u) for u in urls]:
         result[url] = (await rpc.get_block_height(url, proxy=proxy, timeout=10)).value_or_error()
-    mm_print.json(data=result)
+    print_json(data=result)