mm-balance 0.1.18__tar.gz → 0.5.1__tar.gz

mm_balance-0.5.1/PKG-INFO

@@ -0,0 +1,10 @@
+Metadata-Version: 2.4
+Name: mm-balance
+Version: 0.5.1
+Requires-Python: >=3.13
+Requires-Dist: deepdiff==8.5.0
+Requires-Dist: mm-apt==0.4.2
+Requires-Dist: mm-btc==0.5.3
+Requires-Dist: mm-concurrency~=0.1.0
+Requires-Dist: mm-eth==0.7.1
+Requires-Dist: mm-sol==0.7.1

mm_balance-0.5.1/README.md

@@ -0,0 +1,122 @@
+# mm-balance
+
+A multi-cryptocurrency balance checker that allows you to track balances across multiple networks, wallets, and tokens.
+
+## Features
+
+- Support for multiple networks: Bitcoin, Ethereum, Solana, Aptos, Arbitrum, Optimism
+- Check balances of native tokens and custom tokens
+- Fetch current prices from CoinGecko
+- Group addresses for easier management
+- Compare balances between two points in time
+- Multiple output formats (table and JSON)
+- Proxy support
+
+## Installation
+
+### Ubuntu
+
+```shell
+sudo apt update && sudo apt-get install build-essential libgmp3-dev python3-dev -y
+sudo curl -LsSf https://astral.sh/uv/install.sh | sh
+source $HOME/.local/bin/env
+uv tool install mm-balance
+```
+
+### macOS
+
+```shell
+brew install gmp
+curl -LsSf https://astral.sh/uv/install.sh | sh
+source ~/.zshrc  # or appropriate shell config
+uv tool install mm-balance
+```
+
+### Windows (via WSL)
+
+```shell
+sudo apt update && sudo apt-get install build-essential libgmp3-dev python3-dev -y
+curl -LsSf https://astral.sh/uv/install.sh | sh
+source $HOME/.bashrc
+uv tool install mm-balance
+```
+
+## Usage
+
+Create a configuration file in TOML format, then run:
+
+```shell
+mm-balance your_config.toml
+```
+
+### Command Line Options
+
+```
+Options:
+  -f, --format [TABLE|JSON]     Print format
+  -s, --skip-empty              Skip empty balances
+  -d, --debug                   Print debug info
+  -c, --config                  Print config and exit
+  --price / --no-price          Print prices
+  --save-balances PATH          Save balances file
+  --diff-from-balances PATH     Diff from balances file
+  --example                     Print a config example
+  --networks                    Print supported networks
+  --version                     Show version and exit
+  --help                        Show this message and exit
+```
+
+## Configuration
+
+Create a TOML file with the following structure:
+
+```toml
+[[coins]]
+ticker = "BTC"
+network = "bitcoin"
+addresses = [
+  "bc1qgdjqv0av3q56jvd82tkdjpy7gdp9ut8tlqmgrpmv24sq90ecnvqqjwvw97",
+  "34xp4vRoCGJym3xR7yCVPFHoCNxv4Twseo"
+]
+
+[[coins]]
+ticker = "ETH"
+network = "ethereum"
+comment = "exchange_wallets"
+addresses = "group: exchange_wallets"
+
+[[addresses]]
+name = "exchange_wallets"
+addresses = [
+  "0xf977814e90da44bfa03b6295a0616a897441acec",
+  "0x47ac0fb4f2d84898e4d9e7b4dab3c24507a6d503"
+]
+
+[settings]
+round_ndigits = 4
+price = true
+skip_empty = false
+print_format = "table"  # table, json
+```
+
+For a full configuration example, run:
+
+```shell
+mm-balance --example
+```
+
+## Supported Networks
+
+Current supported networks include:
+- bitcoin
+- ethereum
+- solana
+- aptos
+- arbitrum-one
+- op-mainnet
+
+To see the complete list, run:
+
+```shell
+mm-balance --networks
+```

mm_balance-0.5.1/dict.dic

@@ -0,0 +1,10 @@
+ndigits
+fnumber
+stablecoin
+stablecoins
+usdc
+arbitrum
+nosec
+aptos
+solana
+blockstream

{mm_balance-0.1.18 → mm_balance-0.5.1}/justfile

@@ -20,8 +20,10 @@ lint: format
     uv run mypy src
 
 audit:
-    uv run pip-audit --ignore-vuln GHSA-f9vj-2wh5-fj8j --ignore-vuln GHSA-q34m-jh98-gwm2
-    uv run bandit -r -c "pyproject.toml" src
+    uv export --no-dev --all-extras --format requirements-txt --no-emit-project > requirements.txt
+    uv run pip-audit -r requirements.txt --disable-pip
+    rm requirements.txt
+    uv run bandit --silent --recursive --configfile "pyproject.toml" src
 
 publish: build
     git diff-index --quiet HEAD

mm_balance-0.5.1/pyproject.toml

@@ -0,0 +1,75 @@
+[project]
+name = "mm-balance"
+version = "0.5.1"
+description = ""
+requires-python = ">=3.13"
+dependencies = [
+    "mm-concurrency~=0.1.0",
+    "mm-apt==0.4.2",
+    "mm-btc==0.5.3",
+    "mm-eth==0.7.1",
+    "mm-sol==0.7.1",
+    "deepdiff==8.5.0",
+]
+[project.scripts]
+mm-balance = "mm_balance.cli:app"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.uv]
+dev-dependencies = [
+    "pytest~=8.4.0",
+    "pytest-xdist~=3.7.0",
+    "ruff~=0.11.13",
+    "pip-audit~=2.9.0",
+    "bandit~=1.8.3",
+    "mypy~=1.16.0",
+]
+
+[tool.mypy]
+python_version = "3.13"
+warn_no_return = false
+strict = true
+exclude = ["^tests/", "^tmp/"]
+
+[tool.ruff]
+line-length = 130
+target-version = "py313"
+[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
+    "D",       # pydocstyle
+    "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
+]
+[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"]

mm_balance-0.5.1/src/mm_balance/balance_fetcher.py

@@ -0,0 +1,77 @@
+from dataclasses import dataclass
+from decimal import Decimal
+
+from mm_concurrency import AsyncTaskRunner
+from mm_result import Result
+from rich.progress import TaskID
+
+from mm_balance import rpc
+from mm_balance.config import Config
+from mm_balance.constants import Network
+from mm_balance.output import utils
+from mm_balance.token_decimals import TokenDecimals
+from mm_balance.utils import PrintFormat
+
+
+@dataclass
+class Task:
+    group_index: int
+    wallet_address: str
+    token_address: str | None
+    balance: Result[Decimal] | None = None
+
+
+class BalanceFetcher:
+    def __init__(self, config: Config, token_decimals: TokenDecimals) -> None:
+        self.config = config
+        self.token_decimals = token_decimals
+        self.tasks: dict[Network, list[Task]] = {network: [] for network in config.networks()}
+        self.progress_bar = utils.create_progress_bar(config.settings.print_format is not PrintFormat.TABLE)
+        self.progress_bar_task: dict[Network, TaskID] = {}
+
+        for idx, group in enumerate(config.groups):
+            task_list = [Task(group_index=idx, wallet_address=a, token_address=group.token) for a in group.addresses]
+            self.tasks[group.network].extend(task_list)
+
+        for network in config.networks():
+            if self.tasks[network]:
+                self.progress_bar_task[network] = utils.create_progress_task(self.progress_bar, network, len(self.tasks[network]))
+
+    async def process(self) -> None:
+        with self.progress_bar:
+            runner = AsyncTaskRunner(max_concurrent_tasks=10)
+            for network in self.config.networks():
+                runner.add(f"process_{network}", self._process_network(network))
+            await runner.run()
+
+    def get_group_tasks(self, group_index: int, network: Network) -> list[Task]:
+        return [b for b in self.tasks[network] if b.group_index == group_index]
+
+    def get_errors(self) -> list[Task]:
+        result = []
+        for network in self.tasks:
+            result.extend([task for task in self.tasks[network] if task.balance is not None and task.balance.is_err()])
+        return result
+
+    async def _process_network(self, network: Network) -> None:
+        runner = AsyncTaskRunner(max_concurrent_tasks=self.config.workers[network])
+        for idx, task in enumerate(self.tasks[network]):
+            runner.add(str(idx), self._get_balance(network, task.wallet_address, task.token_address))
+        res = await runner.run()
+
+        # TODO: print job.exceptions if present
+        for idx, _task in enumerate(self.tasks[network]):
+            self.tasks[network][idx].balance = res.results.get(str(idx))
+
+    async def _get_balance(self, network: Network, wallet_address: str, token_address: str | None) -> Result[Decimal]:
+        res = await rpc.get_balance(
+            network=network,
+            nodes=self.config.nodes[network],
+            proxies=self.config.settings.proxies,
+            wallet_address=wallet_address,
+            token_address=token_address,
+            token_decimals=self.token_decimals[network][token_address],
+            ndigits=self.config.settings.round_ndigits,
+        )
+        self.progress_bar.update(self.progress_bar_task[network], advance=1)
+        return res

mm_balance-0.5.1/src/mm_balance/cli.py

@@ -0,0 +1,73 @@
+import asyncio
+import importlib.metadata
+import pkgutil
+from pathlib import Path
+from typing import Annotated
+
+import mm_print
+import typer
+
+from mm_balance import command_runner
+from mm_balance.command_runner import CommandParameters
+from mm_balance.constants import NETWORKS
+from mm_balance.utils import PrintFormat
+
+app = typer.Typer(no_args_is_help=True, pretty_exceptions_enable=False, add_completion=False)
+
+
+def version_callback(value: bool) -> None:
+    if value:
+        typer.echo(f"mm-balance: v{importlib.metadata.version('mm-balance')}")
+        raise typer.Exit
+
+
+def example_callback(value: bool) -> None:
+    if value:
+        data = pkgutil.get_data(__name__, "config/example.toml")
+        if data is None:
+            mm_print.fatal("Example config not found")
+        mm_print.toml(toml=data.decode("utf-8"))
+        raise typer.Exit
+
+
+def networks_callback(value: bool) -> None:
+    if value:
+        for network in NETWORKS:
+            typer.echo(network)
+        raise typer.Exit
+
+
+@app.command()
+def cli(
+    config_path: Annotated[Path, typer.Argument()],
+    print_format: Annotated[PrintFormat | None, typer.Option("--format", "-f", help="Print format.")] = None,
+    skip_empty: Annotated[bool | None, typer.Option("--skip-empty", "-s", help="Skip empty balances.")] = None,
+    debug: Annotated[bool | None, typer.Option("--debug", "-d", help="Print debug info.")] = None,
+    print_config: Annotated[bool | None, typer.Option("--config", "-c", help="Print config and exit.")] = None,
+    price: Annotated[bool | None, typer.Option("--price/--no-price", help="Print prices.")] = None,
+    save_balances: Annotated[Path | None, typer.Option("--save-balances", help="Save balances file.")] = None,
+    diff_from_balances: Annotated[Path | None, typer.Option("--diff-from-balances", help="Diff from balances file.")] = None,
+    _example: Annotated[bool | None, typer.Option("--example", callback=example_callback, help="Print a config example.")] = None,
+    _networks: Annotated[
+        bool | None, typer.Option("--networks", callback=networks_callback, help="Print supported networks.")
+    ] = None,
+    _version: bool = typer.Option(None, "--version", callback=version_callback, is_eager=True),
+) -> None:
+    asyncio.run(
+        command_runner.run(
+            CommandParameters(
+                config_path=config_path,
+                print_format=print_format,
+                skip_empty=skip_empty,
+                debug=debug,
+                print_config=print_config,
+                price=price,
+                save_balances=save_balances,
+                diff_from_balances=diff_from_balances,
+            )
+        )
+    )
+
+
+if __name__ == "__main__":
+    app()

mm_balance-0.5.1/src/mm_balance/command_runner.py

@@ -0,0 +1,75 @@
+import getpass
+from pathlib import Path
+
+import mm_print
+from pydantic import BaseModel
+
+from mm_balance.balance_fetcher import BalanceFetcher
+from mm_balance.config import Config
+from mm_balance.diff import BalancesDict, Diff
+from mm_balance.output.formats import json_format, table_format
+from mm_balance.price import Prices, get_prices
+from mm_balance.result import create_balances_result
+from mm_balance.token_decimals import get_token_decimals
+from mm_balance.utils import PrintFormat
+
+
+class CommandParameters(BaseModel):
+    config_path: Path
+    print_format: PrintFormat | None
+    skip_empty: bool | None
+    debug: bool | None
+    print_config: bool | None
+    price: bool | None
+    save_balances: Path | None
+    diff_from_balances: Path | None
+
+
+async def run(params: CommandParameters) -> None:
+    zip_password = ""  # nosec
+    if params.config_path.name.endswith(".zip"):
+        zip_password = getpass.getpass("zip password: ")
+    config = Config.read_toml_config_or_exit(params.config_path, zip_password=zip_password)
+    if params.print_config:
+        config.print_and_exit()
+
+    if params.print_format is not None:
+        config.settings.print_format = params.print_format
+    if params.debug is not None:
+        config.settings.print_debug = params.debug
+    if params.skip_empty is not None:
+        config.settings.skip_empty = params.skip_empty
+    if params.price is not None:
+        config.settings.price = params.price
+
+    if config.settings.print_debug and config.settings.print_format is PrintFormat.TABLE:
+        table_format.print_nodes(config)
+        table_format.print_proxy_count(config)
+
+    token_decimals = await get_token_decimals(config)
+    if config.settings.print_debug and config.settings.print_format is PrintFormat.TABLE:
+        table_format.print_token_decimals(token_decimals)
+
+    prices = await get_prices(config) if config.settings.price else Prices()
+    if config.settings.print_format is PrintFormat.TABLE:
+        table_format.print_prices(config, prices)
+
+    workers = BalanceFetcher(config, token_decimals)
+    await workers.process()
+
+    result = create_balances_result(config, prices, workers)
+    if config.settings.print_format is PrintFormat.TABLE:
+        table_format.print_result(config, result, workers)
+    elif config.settings.print_format is PrintFormat.JSON:
+        json_format.print_result(config, token_decimals, prices, workers, result)
+    else:
+        mm_print.fatal("Unsupported print format")
+
+    if params.save_balances:
+        BalancesDict.from_balances_result(result).save_to_path(params.save_balances)
+
+    if params.diff_from_balances:
+        old_balances = BalancesDict.from_file(params.diff_from_balances)
+        new_balances = BalancesDict.from_balances_result(result)
+        diff = Diff.calc(old_balances, new_balances)
+        diff.print(config.settings.print_format)

mm_balance-0.5.1/src/mm_balance/config/example.toml

@@ -0,0 +1,83 @@
+[[coins]]
+ticker = "SOL"
+network = "solana"
+addresses = "2ojv9BAiHUrvsm9gxDe7fJSzbNZSJcxZvf8dqmWGHG8S"  # binance
+
+[[coins]]
+ticker = "USDT"
+network = "solana"
+addresses = "2ojv9BAiHUrvsm9gxDe7fJSzbNZSJcxZvf8dqmWGHG8S"  # binance
+
+[[coins]]
+ticker = "BTC"
+network = "bitcoin"
+comment = "coldwallets"
+addresses = """
+34xp4vRoCGJym3xR7yCVPFHoCNxv4Twseo # binance
+bc1qgdjqv0av3q56jvd82tkdjpy7gdp9ut8tlqmgrpmv24sq90ecnvqqjwvw97 # bitfinex
+bc1ql49ydapnjafl5t2cp9zqpjwe6pdgmxy98859v2 # robinhood
+"""
+share = 0.1
+
+[[coins]]
+ticker = "ETH"
+network = "ethereum"
+comment = "okx"
+addresses = "group: okx_eth"
+
+[[coins]]
+ticker = "USDT"
+network = "ethereum"
+comment = "okx"
+addresses = "group: okx_eth"
+
+[[coins]]
+ticker = "ETH"
+network = "ethereum"
+comment = "binance"
+addresses = "group: binance_eth"
+
+[[coins]]
+ticker = "USDT"
+network = "ethereum"
+comment = "binance"
+addresses = "group: binance_eth"
+
+[[coins]]
+ticker = "USDC"
+network = "aptos"
+comment = "swap.thala.apt"
+token = "0xf22bede237a07e121b56d91a491eb7bcdfd1f5907926a9e58338f964a01b17fa::asset::USDC"
+decimals = 6
+addresses = "0x48271d39d0b05bd6efca2278f22277d6fcc375504f9839fd73f74ace240861af"
+
+
+[[addresses]]
+name = "okx_eth"
+addresses = """
+0xf59869753f41db720127ceb8dbb8afaf89030de4
+0x65a0947ba5175359bb457d3b34491edf4cbf7997
+0xe9172daf64b05b26eb18f07ac8d6d723acb48f99
+0x4d19c0a5357bc48be0017095d3c871d9afc3f21d
+"""
+
+[[addresses]]
+name = "binance_eth"
+addresses = """
+0xf977814e90da44bfa03b6295a0616a897441acec
+0x47ac0fb4f2d84898e4d9e7b4dab3c24507a6d503
+"""
+
+
+[settings] # all records are optional
+round_ndigits = 4
+price = true
+skip_empty = false
+print_debug = false
+print_format = "table"  # table, json
+format_number_separator = ","
+proxies = """
+# env_url: MM_BALANCE_PROXIES_URL
+# socks5://usr:pass@site.com:1234
+# http://site.com:1234
+"""

mm_balance-0.5.1/src/mm_balance/config.py

@@ -0,0 +1,131 @@
+from __future__ import annotations
+
+from decimal import Decimal
+from pathlib import Path
+from typing import Annotated, Self
+
+import mm_print
+import pydash
+from mm_web3 import ConfigValidators, Web3CliConfig
+from pydantic import BeforeValidator, Field, StringConstraints, model_validator
+
+from mm_balance.constants import DEFAULT_NODES, TOKEN_ADDRESS, Network
+from mm_balance.utils import PrintFormat
+
+
+class Validators(ConfigValidators):
+    pass
+
+
+class AssetGroup(Web3CliConfig):
+    """
+    Represents a group of cryptocurrency assets of the same type.
+
+    An asset group contains information about a specific cryptocurrency (token)
+    across multiple addresses/wallets.
+    """
+
+    comment: str = ""
+    ticker: Annotated[str, StringConstraints(to_upper=True)]
+    network: Network
+    token: str | None = None  # Token address. If None, it's a native token
+    decimals: int | None = None
+    coingecko_id: str | None = None
+    addresses: Annotated[list[str], BeforeValidator(Validators.addresses(deduplicate=True))]
+    share: Decimal = Decimal(1)
+
+    @property
+    def name(self) -> str:
+        result = self.ticker
+        if self.comment:
+            result += " / " + self.comment
+        result += " / " + self.network
+        return result
+
+    @model_validator(mode="after")
+    def final_validator(self) -> Self:
+        if self.token is None:
+            self.token = detect_token_address(self.ticker, self.network)
+        if self.token is not None and self.network.is_evm_network():
+            self.token = self.token.lower()
+        return self
+
+    def process_addresses(self, address_groups: list[AddressCollection]) -> None:
+        result = []
+        for line in self.addresses:
+            if line.startswith("file:"):
+                path = Path(line.removeprefix("file:").strip()).expanduser()
+                if path.is_file():
+                    result += path.read_text().strip().splitlines()
+                else:
+                    mm_print.fatal(f"File with addresses not found: {path}")
+            elif line.startswith("group:"):
+                group_name = line.removeprefix("group:").strip()
+                address_group = next((ag for ag in address_groups if ag.name == group_name), None)
+                if address_group is None:
+                    raise ValueError(f"Address group not found: {group_name}")
+                result += address_group.addresses
+            else:
+                result.append(line)
+        # TODO: check address is valid. There is network info in the group
+        if self.network.need_lowercase_address():
+            result = [address.lower() for address in result]
+        self.addresses = pydash.uniq(result)
+
+
+class AddressCollection(Web3CliConfig):
+    name: str
+    addresses: Annotated[list[str], BeforeValidator(Validators.addresses(deduplicate=True))]
+
+
+class Settings(Web3CliConfig):
+    proxies: Annotated[list[str], Field(default_factory=list), BeforeValidator(Validators.proxies())]
+    round_ndigits: int = 4
+    print_format: PrintFormat = PrintFormat.TABLE
+    price: bool = True
+    skip_empty: bool = False  # don't print the address with an empty balance
+    print_debug: bool = False  # print debug info: nodes, token_decimals
+    format_number_separator: str = ","  # as thousands separators
+
+
+class Config(Web3CliConfig):
+    groups: list[AssetGroup] = Field(alias="coins")
+    addresses: list[AddressCollection] = Field(default_factory=list)
+    nodes: dict[Network, list[str]] = Field(default_factory=dict)
+    workers: dict[Network, int] = Field(default_factory=dict)
+    settings: Settings = Field(default_factory=Settings)  # type: ignore[arg-type]
+
+    def has_share(self) -> bool:
+        return any(g.share != Decimal(1) for g in self.groups)
+
+    def networks(self) -> list[Network]:
+        return pydash.uniq([group.network for group in self.groups])
+
+    @model_validator(mode="after")
+    def final_validator(self) -> Self:
+        # check all addresses has uniq name
+        address_group_names = [ag.name for ag in self.addresses]
+        non_uniq_names = [name for name in address_group_names if address_group_names.count(name) > 1]
+        if non_uniq_names:
+            raise ValueError("There are non-unique address group names: " + ", ".join(non_uniq_names))
+
+        # load addresses from address_group
+        for group in self.groups:
+            group.process_addresses(self.addresses)
+
+        # load default rpc nodes
+        for network in self.networks():
+            if network not in self.nodes:
+                self.nodes[network] = DEFAULT_NODES[network]
+
+        # load default workers
+        for network in self.networks():
+            if network not in self.workers:
+                self.workers[network] = 5
+
+        return self
+
+
+def detect_token_address(ticker: str, network: Network) -> str | None:
+    if network in TOKEN_ADDRESS:
+        return TOKEN_ADDRESS[network].get(ticker)