wnm 0.0.12__py3-none-any.whl

wnm/wallets.py

@@ -0,0 +1,177 @@
+"""Wallet address resolution and weighted distribution.
+
+This module provides functionality for:
+1. Resolving named wallets (faucet/donate) to actual addresses
+2. Parsing weighted wallet lists
+3. Selecting wallets based on weights for node assignment
+"""
+
+import logging
+import random
+import re
+from typing import List, Optional, Tuple
+
+from wnm.common import FAUCET
+
+
+def resolve_wallet_name(name: str, donate_address: str) -> str:
+    """Resolve named wallet to actual address.
+
+    Args:
+        name: Wallet name or address. Can be:
+            - "faucet" (case-insensitive) -> FAUCET constant (not changeable by user)
+            - "donate" (case-insensitive) -> donate_address from machine config (user can override)
+            - Ethereum address (0x...) -> returned as-is
+        donate_address: The donate address from machine config 
+
+    Returns:
+        Resolved Ethereum address
+
+    Raises:
+        ValueError: If name is neither a valid address nor known name
+    """
+    name_lower = name.lower().strip()
+
+    # Check for named wallets
+    if name_lower == "faucet":
+        return FAUCET  # Always use the constant (not changeable)
+    if name_lower == "donate":
+        return donate_address  # Use machine config value (user can override)
+
+    # Validate as Ethereum address (0x followed by 40 hex chars)
+    if re.match(r"^0x[0-9A-Fa-f]{40}$", name.strip()):
+        return name.strip()
+
+    raise ValueError(
+        f"Invalid wallet identifier: '{name}'. "
+        f"Must be 'donate', 'faucet', or a valid Ethereum address (0x...)"
+    )
+
+
+def parse_weighted_wallets(
+    wallet_string: str, donate_address: str
+) -> List[Tuple[str, int]]:
+    """Parse comma-separated weighted wallet list.
+
+    Supports formats:
+    - Single wallet: "0xABC" or "donate"
+    - Weighted list: "0xABC:100,faucet:1,donate:10"
+
+    Args:
+        wallet_string: Wallet specification string
+        donate_address: The donate address from machine config for resolving names
+
+    Returns:
+        List of (address, weight) tuples. For single wallet, weight=1.
+
+    Raises:
+        ValueError: If format is invalid or wallets cannot be resolved
+    """
+    if not wallet_string or not wallet_string.strip():
+        raise ValueError("Wallet string cannot be empty")
+
+    wallet_string = wallet_string.strip()
+
+    # Check if this is a weighted list (contains comma or colon)
+    if "," not in wallet_string and ":" not in wallet_string:
+        # Single wallet without weight
+        address = resolve_wallet_name(wallet_string, donate_address)
+        return [(address, 1)]
+
+    # Parse weighted list
+    weighted_wallets = []
+    parts = wallet_string.split(",")
+
+    for part in parts:
+        part = part.strip()
+        if not part:
+            continue
+
+        # Check for weight suffix
+        if ":" in part:
+            wallet_part, weight_part = part.rsplit(":", 1)
+            wallet_part = wallet_part.strip()
+            weight_part = weight_part.strip()
+
+            try:
+                weight = int(weight_part)
+            except ValueError:
+                raise ValueError(f"Invalid weight in '{part}': {weight_part}")
+
+            if weight <= 0:
+                raise ValueError(f"Weight must be positive: {part}")
+
+            address = resolve_wallet_name(wallet_part, donate_address)
+            weighted_wallets.append((address, weight))
+        else:
+            # No weight specified, default to 1
+            address = resolve_wallet_name(part, donate_address)
+            weighted_wallets.append((address, 1))
+
+    if not weighted_wallets:
+        raise ValueError("No valid wallets found in wallet string")
+
+    return weighted_wallets
+
+
+def select_wallet_for_node(
+    wallet_string: str, donate_address: str, seed: Optional[int] = None
+) -> str:
+    """Select a wallet address for a node based on weighted distribution.
+
+    Uses random weighted selection to choose from the wallet list.
+    Each node creation will randomly pick according to weights.
+
+    Args:
+        wallet_string: Wallet specification (single or weighted list)
+        donate_address: The donate address from machine config
+        seed: Optional random seed for deterministic testing
+
+    Returns:
+        Selected Ethereum address
+
+    Raises:
+        ValueError: If wallet_string is invalid
+    """
+    weighted_wallets = parse_weighted_wallets(wallet_string, donate_address)
+
+    # If only one wallet, return it
+    if len(weighted_wallets) == 1:
+        return weighted_wallets[0][0]
+
+    # Extract addresses and weights
+    addresses = [addr for addr, _ in weighted_wallets]
+    weights = [weight for _, weight in weighted_wallets]
+
+    # Set seed if provided (for testing)
+    if seed is not None:
+        random.seed(seed)
+
+    # Randomly select based on weights
+    selected = random.choices(addresses, weights=weights, k=1)[0]
+
+    logging.debug(
+        f"Selected wallet {selected} from {len(weighted_wallets)} options "
+        f"with weights {weights}"
+    )
+
+    return selected
+
+
+def validate_rewards_address(
+    rewards_address: str, donate_address: str
+) -> Tuple[bool, Optional[str]]:
+    """Validate a rewards address string.
+
+    Args:
+        rewards_address: The rewards address string to validate
+        donate_address: The donate address for resolving named wallets
+
+    Returns:
+        Tuple of (is_valid, error_message). error_message is None if valid.
+    """
+    try:
+        parse_weighted_wallets(rewards_address, donate_address)
+        return (True, None)
+    except ValueError as e:
+        return (False, str(e))

wnm-0.0.12.dist-info/METADATA

@@ -0,0 +1,367 @@
+Metadata-Version: 2.4
+Name: wnm
+Version: 0.0.12
+Summary: Manager for Autonomi nodes
+Author-email: Troy Johnson <troy@weave.sh>
+License: GPL-3.0
+Project-URL: Repository, https://github.com/iweave/weave-node-manager.git
+Project-URL: Issues, https://github.com/iweave/weave-node-manager/issues
+Keywords: Autonomi,antnode,weave,xd7
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: GNU General Public License v3 (GPLv3)
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: System :: Distributed Computing
+Requires-Python: >=3.12.3
+Description-Content-Type: text/markdown
+Requires-Dist: python-dotenv
+Requires-Dist: requests
+Requires-Dist: packaging
+Requires-Dist: sqlalchemy
+Requires-Dist: alembic
+Requires-Dist: json-fix
+Requires-Dist: psutil
+Requires-Dist: configargparse
+Provides-Extra: dev
+Requires-Dist: black; extra == "dev"
+Requires-Dist: isort; extra == "dev"
+Requires-Dist: build; extra == "dev"
+Requires-Dist: twine; extra == "dev"
+Requires-Dist: pytest>=8.0.0; extra == "dev"
+Requires-Dist: pytest-cov>=4.1.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.23.0; extra == "dev"
+Requires-Dist: pytest-mock>=3.12.0; extra == "dev"
+Requires-Dist: pytest-docker>=3.1.0; extra == "dev"
+Requires-Dist: docker>=7.0.0; extra == "dev"
+
+# Weave Node Manager
+
+## Overview
+Weave Node Manager (wnm) is a Python application designed to manage Autonomi nodes on Linux and macOS systems.
+
+**Platforms**:
+- **Linux**: systemd or setsid for process management, UFW for firewall
+- **macOS**: launchd for process management (native support)
+- **Python 3.12.3+** required
+
+## Features
+- Automatic node lifecycle management (create, start, stop, upgrade, remove)
+- Resource-based decision engine (CPU, memory, disk, I/O, load average thresholds)
+- Platform-specific process management (systemd on Linux, launchd on macOS)
+- Per-node binary copies for independent upgrades
+- SQLite database for configuration and state tracking
+- Support for configuration via environment variables, config files, or command-line parameters
+
+## Warning - Alpha Software
+
+This code is Alpha. On Linux, it can migrate from an existing [anm](https://github.com/safenetforum-community/NTracking/tree/main/anm) installation. On macOS, it provides native development and testing support using launchd.
+
+## Installation
+
+### macOS (Development & Testing)
+
+macOS support uses launchd for process management and is ideal for development and testing.
+
+#### 1. Install antup (Autonomi binary manager)
+```bash
+curl -sSL https://raw.githubusercontent.com/maidsafe/antup/main/install.sh | bash
+```
+
+#### 2. Download antnode binary
+```bash
+~/.local/bin/antup node
+```
+
+#### 3. Install WNM from PyPI
+```bash
+pip3 install weave-node-manager
+```
+
+#### 4. Or install from source
+```bash
+git clone https://github.com/dawn-code/weave-node-manager.git
+cd weave-node-manager
+pip3 install -e .
+```
+
+#### 5. Initialize and configure
+```bash
+# Initialize with your rewards address
+wnm --init --rewards_address 0xYourEthereumAddress
+
+# Run in dry-run mode to test
+wnm --dry_run
+
+# Or run normally to start managing nodes
+wnm
+```
+
+#### 6. Optional: Add to cron for automatic management
+```bash
+# Add to crontab (runs every minute)
+crontab -e
+
+# Add this line:
+*/1 * * * * /usr/local/bin/wnm >> ~/Library/Logs/autonomi/wnm-cron.log 2>&1
+```
+
+**macOS Notes:**
+- Uses `~/Library/Application Support/autonomi/node/` for data
+- Uses `~/Library/Logs/autonomi/` for logs
+- Nodes managed via launchd (`~/Library/LaunchAgents/`)
+- No root/sudo access required
+
+### Linux (User-Level, Recommended)
+
+Non-root installation using setsid for process management.
+
+#### 1. Install antup (Autonomi binary manager)
+```bash
+curl -sSL https://raw.githubusercontent.com/maidsafe/antup/main/install.sh | bash
+```
+
+#### 2. Download antnode binary
+```bash
+~/.local/bin/antup node
+```
+
+#### 3. Install WNM from PyPI
+```bash
+pip3 install weave-node-manager
+```
+
+#### 4. Or install from source
+```bash
+git clone https://github.com/dawn-code/weave-node-manager.git
+cd weave-node-manager
+pip3 install -e .
+```
+
+#### 5. Initialize and configure
+```bash
+# Initialize with your rewards address
+wnm --init --rewards_address 0xYourEthereumAddress
+
+# Run in dry-run mode to test
+wnm --dry_run
+
+# Or run normally
+wnm
+```
+
+#### 6. Optional: Add to cron
+```bash
+crontab -e
+
+# Add this line:
+*/1 * * * * ~/.local/bin/wnm >> ~/.local/share/autonomi/logs/wnm-cron.log 2>&1
+```
+
+**Linux User-Level Notes:**
+- Uses `~/.local/share/autonomi/node/` for data (XDG spec)
+- Uses `~/.local/share/autonomi/logs/` for logs
+- Nodes run as background processes (setsid)
+- No root/sudo required
+
+### Linux (Root-Level, Production)
+
+Root installation using systemd for process management.
+
+#### 1. Install system dependencies
+```bash
+sudo apt install -y python3.12-venv python3-pip
+```
+
+#### 2. Install antup and antnode
+```bash
+curl -sSL https://raw.githubusercontent.com/maidsafe/antup/main/install.sh | bash
+~/.local/bin/antup node
+sudo cp ~/.local/bin/antnode /usr/local/bin/
+```
+
+#### 3. Install WNM
+```bash
+sudo pip3 install weave-node-manager
+```
+
+#### 4. Initialize as root
+```bash
+# Migrate from existing anm installation
+sudo wnm --init --migrate_anm
+
+# Or initialize fresh
+sudo wnm --init --rewards_address 0xYourEthereumAddress
+```
+
+#### 5. Add to cron
+```bash
+sudo crontab -e
+
+# Add this line:
+*/1 * * * * /usr/local/bin/wnm >> /var/log/antnode/wnm-cron.log 2>&1
+```
+
+**Linux Root-Level Notes:**
+- Uses `/var/antctl/` for data (legacy anm compatibility)
+- Uses `/var/log/antnode/` for logs
+- Nodes managed via systemd (`/etc/systemd/system/`)
+- Requires root/sudo access
+- Supports migration from anm
+
+## Configuration
+
+Configuration follows a multi-layer priority system (highest to lowest):
+
+1. **Command-line arguments**: `wnm --cpu_less_than 70 --node_cap 50`
+2. **Environment variables**: Set in `.env` file or shell
+3. **Config files**:
+   - macOS: `~/Library/Application Support/autonomi/config`
+   - Linux (user): `~/.local/share/autonomi/config`
+   - Linux (root): `/var/antctl/config`
+4. **Database-stored config**: Persisted in `colony.db` after initialization
+5. **Default values**: Built-in defaults
+
+### Key Configuration Parameters
+
+Resource thresholds control when nodes are added or removed:
+
+- `--cpu_less_than` / `--cpu_remove`: CPU percentage thresholds (default: 70% / 80%)
+- `--mem_less_than` / `--mem_remove`: Memory percentage thresholds (default: 70% / 80%)
+- `--hd_less_than` / `--hd_remove`: Disk usage percentage thresholds (default: 70% / 80%)
+- `--desired_load_average` / `--max_load_average_allowed`: Load average thresholds
+- `--node_cap`: Maximum number of nodes (default: 50)
+- `--rewards_address`: Wallet address(es) for node rewards (required) - see Wallet Configuration below
+- `--node_storage`: Root directory for node data (auto-detected per platform)
+
+### Wallet Configuration
+
+The `--rewards_address` parameter supports multiple formats for flexible reward distribution:
+
+#### Single Wallet
+Use a single Ethereum address or named wallet:
+```bash
+# Ethereum address
+wnm --init --rewards_address 0xYourEthereumAddress
+
+# Named wallet: "donate" (uses your custom donate_address or the community foucet if not deefined)
+wnm --init --rewards_address donate
+
+# Named wallet: "faucet" (always uses the autonomi community faucet address)
+wnm --init --rewards_address faucet
+```
+
+#### Weighted Distribution
+Distribute rewards across multiple wallets using weighted random selection:
+```bash
+# Format: wallet1:weight1,wallet2:weight2,...
+wnm --init --rewards_address "0xYourAddress:100,faucet:1,donate:10"
+```
+
+In this example:
+- Your address receives ~90% of nodes (100 out of 111 weight)
+- Faucet receives ~1% of nodes (1 out of 111 weight)
+- Donate address receives ~9% of nodes (10 out of 111 weight)
+
+**Key Features:**
+- **Random per node**: Each new node randomly selects a wallet based on weights
+- **Named wallets**: Use `faucet` (project faucet) or `donate` (your custom donation address)
+- **Case-insensitive**: `faucet`, `FAUCET`, and `Faucet` all work
+- **Mix addresses and names**: Combine Ethereum addresses with named wallets
+- **Changeable**: Update `--rewards_address` anytime to change distribution for new nodes
+
+**Examples:**
+```bash
+# 50/50 split between your address and faucet
+wnm --rewards_address "0xYourAddress:1,faucet:1"
+
+# Your address only
+wnm --rewards_address 0xYourAddress
+
+# Mostly yours, small donation to faucet
+wnm --rewards_address "0xYourAddress:99,faucet:1"
+
+# Multiple addresses with custom weights
+wnm --rewards_address "0xAddress1:100,0xAddress2:50,faucet:10"
+```
+
+### anm Migration (Linux Only)
+
+Upon finding an existing [anm](https://github.com/safenetforum-community/NTracking/tree/main/anm) installation, wnm will:
+1. Disable anm by removing `/etc/cron.d/anm`
+2. Import configuration from `/var/antctl/config`
+3. Discover and import existing nodes from systemd
+4. Take over management of the cluster
+
+Use `wnm --init --migrate_anm` to trigger migration.
+
+## Usage
+
+### Run Once
+```bash
+# macOS or Linux
+wnm
+
+# With dry-run (no actual changes)
+wnm --dry_run
+
+# Initialize first time
+wnm --init --rewards_address 0xYourEthereumAddress
+```
+
+### Run via Cron (Recommended)
+
+WNM is designed to run every minute via cron, making one decision per cycle:
+
+**macOS:**
+```bash
+crontab -e
+# Add: */1 * * * * /usr/local/bin/wnm >> ~/Library/Logs/autonomi/wnm-cron.log 2>&1
+```
+
+**Linux (user):**
+```bash
+crontab -e
+# Add: */1 * * * * ~/.local/bin/wnm >> ~/.local/share/autonomi/logs/wnm-cron.log 2>&1
+```
+
+**Linux (root):**
+```bash
+sudo crontab -e
+# Add: */1 * * * * /usr/local/bin/wnm >> /var/log/antnode/wnm-cron.log 2>&1
+```
+
+### Development Mode
+
+For development with live code reloading:
+
+**macOS (native):**
+```bash
+python3 -m wnm --dry_run
+```
+
+**Linux (Docker):**
+```bash
+./scripts/dev.sh
+# Inside container:
+python3 -m wnm --dry_run
+```
+
+See `DOCKER-DEV.md` for comprehensive Docker development workflow.
+
+## Platform Support
+
+See `PLATFORM-SUPPORT.md` for detailed information about:
+- Platform-specific process managers (systemd, launchd, setsid)
+- Firewall management (UFW, null)
+- Path conventions per platform
+- Binary management and upgrades
+- Testing strategies
+
+## Contributing
+Contributions are welcome! Please submit a pull request or open an issue for any enhancements or bug fixes.
+
+## License
+This project is licensed under the MIT License. See the LICENSE file for more details.

wnm-0.0.12.dist-info/RECORD

@@ -0,0 +1,29 @@
+wnm/__init__.py,sha256=7iYQD6abjHiZLWlLDOBAFIcPQNdSQpPKfUtgN418lM0,92
+wnm/__main__.py,sha256=fMlM5gQIFGeFp19oowxmSKwtAE7-xS5-_ThTPaO7J-0,7989
+wnm/actions.py,sha256=h3ieTbQQIggKHqCLVWe5eph5YGif39tZRW3ch82tqys,1314
+wnm/common.py,sha256=mjKPTCN1pSkxRqQJ6sUnB2JRcXGxRJ4D_eHK6LW7SnE,1116
+wnm/config.py,sha256=Jt9CtaNwSThg5RvQ_rxjZPtmf4TysXD5wg07_RlQKbg,27272
+wnm/decision_engine.py,sha256=l_vqrw7imj9EsueLKWkz94P0TtA7UCyNPxBCfgkmNUg,13817
+wnm/executor.py,sha256=eNn4cLkHyhqlYQd5KrKIw3qs9FEdzC4-MrFmYpH1uKI,52519
+wnm/migration.py,sha256=QcfvN9S0FIrEDq68IrgM1JBO288ub1tiSXdsrg53eSQ,1389
+wnm/models.py,sha256=qCCNu-Beg5TSQtIi7_1qnfuv5YmzzMq3We9PGektR1E,16684
+wnm/reports.py,sha256=m_EW_-_CjlKPE6uXMWC_02RDPMlL0LirdctmgnGfpEM,9133
+wnm/utils.py,sha256=Zmzg729olHfjDBc5XFCu30b9RR70sjNxIvx_PzGTn7c,15897
+wnm/wallets.py,sha256=cITjHPHXJ2BVKIDzcZzwLzgBYbI54mlFvNzD3D2rQZM,5554
+wnm/firewall/__init__.py,sha256=2Ur3cSiP2hKVJp9guuuyDDgE2vklyU46KnstDfRq12Q,471
+wnm/firewall/base.py,sha256=cQQ8v7pYgVIjDcXj2jsU4_iZDXRyw7xtlfoJhcy8Gps,1882
+wnm/firewall/factory.py,sha256=zm_SVd1d_NaKkTaj73ai_4oMOhTb1SoHOu0-ylpu2M4,2870
+wnm/firewall/null_firewall.py,sha256=ENmQM0UIubhuqpSqyjSRBCxb3GRPIOYVkMzdZyhUE0Q,1834
+wnm/firewall/ufw_manager.py,sha256=CqkjSr4j8kdIsOdjUbj0h0ZeWhrvsxh_cLvxWUAWaoc,3171
+wnm/process_managers/__init__.py,sha256=ohFXPcqpSBHEkclSaVMfPZdym2KNjcrCfxV6Kbl_3ZY,739
+wnm/process_managers/base.py,sha256=kODNaXY302bCR8BRCISe6g47uDUjA4T7yPKP2s7DlIg,5721
+wnm/process_managers/docker_manager.py,sha256=U-_VMkWK7WzxpWGtMStIRsXBKez8QOcCLZ0pHiHJzZY,11015
+wnm/process_managers/factory.py,sha256=TVkcN-o3kRtf1VylsTXMvpcTM2rwfcZT6QY3JsG5HkQ,2437
+wnm/process_managers/launchd_manager.py,sha256=c0QV_0eowCaNga81mNINvJM3We8BJm2_UvPX0v6-4v4,19860
+wnm/process_managers/setsid_manager.py,sha256=DW3BylkmmdUa4_mk68wpdwy5kqG-IJ_s13vG5eKE_Rs,10650
+wnm/process_managers/systemd_manager.py,sha256=dzEKngo2Bz5562h8PZRA1-m51JMcqU5Qc-f9CullNzk,18718
+wnm-0.0.12.dist-info/METADATA,sha256=cKawc6sumk4JjiADIS-paSA8lRCz2ByM-L7dLaGrQ8o,10617
+wnm-0.0.12.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+wnm-0.0.12.dist-info/entry_points.txt,sha256=jfoemjoLVPeeiBMHKqAExrHQ4Rhf9IXxL4JCnS7ZYFo,42
+wnm-0.0.12.dist-info/top_level.txt,sha256=E6dTE5k6efMEB9LaJAZSBu8zzs__l4R55t0-F-LwufI,4
+wnm-0.0.12.dist-info/RECORD,,

wnm-0.0.12.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (80.9.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

wnm-0.0.12.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+wnm = wnm.__main__:main

wnm-0.0.12.dist-info/top_level.txt

@@ -0,0 +1 @@
+wnm