hippius 0.1.6__tar.gz → 0.1.9__tar.gz

{hippius-0.1.6 → hippius-0.1.9}/PKG-INFO

@@ -1,21 +1,22 @@
 Metadata-Version: 2.1
 Name: hippius
-Version: 0.1.6
+Version: 0.1.9
 Summary: Python SDK and CLI for Hippius blockchain storage
 Home-page: https://github.com/thenervelab/hippius-sdk
 Author: Dubs
 Author-email: dubs@dubs.rs
-Requires-Python: >=3.8,<4.0
+Requires-Python: >=3.8, !=2.7.*, !=3.0.*, !=3.1.*, !=3.2.*, !=3.3.*, !=3.4.*, !=3.5.*, !=3.6.*, !=3.7.*
 Classifier: Development Status :: 3 - Alpha
 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.9
 Provides-Extra: clipboard
 Requires-Dist: base58 (>=2.1.1,<3.0.0)
+Requires-Dist: cryptography (>=44.0.0,<45.0.0)
 Requires-Dist: ipfshttpclient (>=0.7.0,<0.8.0)
 Requires-Dist: pydantic (>=2.0.0,<3.0.0)
 Requires-Dist: pynacl (>=1.5.0,<2.0.0)
@@ -66,7 +67,7 @@ client = HippiusClient()
 # Or specify custom endpoints
 client = HippiusClient(
     ipfs_gateway="https://ipfs.io",                       # For downloads (default)
-    ipfs_api_url="http://relay-fr.hippius.network:5001",  # For uploads (default)
+    ipfs_api_url="https://store.hippius.network",  # For uploads (default)
 )
 
 # Upload a file to IPFS
@@ -271,6 +272,150 @@ The CLI provides detailed output during the process, including:
 - Storage confirmation in the marketplace
 - Instructions for reconstruction
 
+#### Erasure Coding
+
+Erasure coding offers redundancy by splitting files into chunks:
+
+```bash
+# Basic erasure coding with default parameters (k=3, m=5)
+hippius erasure-code my_large_file.zip
+
+# Erasure code with custom parameters for increased redundancy
+hippius erasure-code my_important_file.mp4 --k 4 --m 10 --chunk-size 2097152 --encrypt
+```
+
+To reconstruct a file from erasure-coded chunks:
+
+```bash
+hippius reconstruct QmMetadataCID reconstructed_filename
+```
+
+#### Listing Erasure Coded Files
+
+To view only your erasure-coded files:
+
+```bash
+# List all erasure-coded files
+hippius ec-files
+
+# Show all miners for each erasure-coded file
+hippius ec-files --all-miners
+
+# Show associated chunks for each erasure-coded file
+hippius ec-files --show-chunks
+```
+
+This command provides detailed information about each erasure-coded file including:
+- Original file name
+- Metadata CID
+- File size
+- Number of chunks
+- Miners storing the file
+- Reconstruction command
+
+The `ec-files` command is optimized for performance through parallel processing and intelligent filtering, making it efficient even with large numbers of files.
+
+#### Performance Considerations
+
+The erasure coding implementation has been optimized for:
+
+1. **Speed**: Parallel processing for file operations
+2. **Memory efficiency**: Files are processed in chunks to minimize memory usage
+3. **Auto-tuning**: Parameters like chunk size are automatically adjusted for small files
+4. **Intelligent filtering**: The system can quickly identify potential erasure-coded files
+
+For extremely large files (>1GB), consider using larger chunk sizes to improve performance:
+
+```bash
+hippius erasure-code large_video.mp4 --chunk-size 10485760  # 10MB chunks
+```
+
+#### Directory Support for Erasure Coding
+
+Hippius SDK now supports applying erasure coding to entire directories:
+
+```bash
+# Apply erasure coding to an entire directory
+hippius erasure-code my_directory/
+
+# The CLI will detect that it's a directory and offer two options:
+# 1. Archive the directory first, then erasure code the archive
+# 2. Apply erasure coding to each file in the directory individually
+```
+
+When choosing the second option, the system will process each file in the directory individually, adjusting parameters like chunk size automatically for small files. A summary of the operation will be displayed, showing:
+- Total files processed
+- Successfully coded files with their metadata CIDs
+- Any files that failed, with error details
+
+To reconstruct a file from erasure-coded chunks:
+
+```bash
+hippius reconstruct QmMetadataCID reconstructed_filename
+```
+
+#### Default Address Management
+
+Hippius SDK now allows setting a default address for read-only operations, making it easier to use commands like `files` and `ec-files` without specifying an account address each time:
+
+```bash
+# Set a default address for read-only operations
+hippius address set-default 5H1QBRF7T7dgKwzVGCgS4wioudvMRf9K4NEDzfuKLnuyBNzH
+
+# View the currently set default address
+hippius address get-default
+
+# Clear the default address
+hippius address clear-default
+```
+
+Once a default address is set, commands like `hippius files` and `hippius ec-files` will automatically use this address when no explicit address is provided.
+
+#### Troubleshooting
+
+1. **IPFS Connection Issues**: Make sure you have either:
+   - A local IPFS daemon running (`ipfs daemon` in a separate terminal)
+   - Or proper environment variables set in `.env` for remote connections
+
+2. **Missing Dependencies**: If you get import errors, ensure all dependencies are installed:
+   ```bash
+   poetry install --all-extras
+   ```
+
+3. **CLI Not Found**: If the `hippius` command isn't found after installing, try:
+   ```bash
+   # Verify it's installed
+   poetry show hippius
+   
+   # Check your PATH
+   which hippius
+   ```
+
+4. **Default Address Issues**: If you receive errors about missing account address:
+   ```bash
+   # Set a default address for read-only operations
+   hippius address set-default 5H1QBRF7T7dgKwzVGCgS4wioudvMRf9K4NEDzfuKLnuyBNzH
+   ```
+
+5. **Substrate Issues**: For marketplace operations, make sure your `.env` has the correct `SUBSTRATE_SEED_PHRASE` and `SUBSTRATE_URL` values.
+
+6. **Erasure Coding Problems**:
+   - **"Wrong length for input blocks"**: This typically happens with very small files
+     ```bash
+     # Try smaller k and m values for small files
+     hippius erasure-code small_file.txt --k 2 --m 3
+     ```
+   - **Directories can't be directly coded**: Use the directory support option when prompted
+   - **"zfec is required"**: Install the missing package
+     ```bash
+     pip install zfec
+     poetry add zfec
+     ```
+   - **Slow performance with large files**: Increase chunk size
+     ```bash
+     hippius erasure-code large_file.mp4 --chunk-size 5242880  # 5MB chunks
+     ```
+
 ## Command Line Interface
 
 The Hippius SDK includes a powerful command-line interface (CLI) that provides access to all major features of the SDK directly from your terminal.
@@ -282,7 +427,7 @@ The Hippius SDK includes a powerful command-line interface (CLI) that provides a
 hippius --help
 
 # Set global options
-hippius --gateway https://ipfs.io --api-url https://relay-fr.hippius.network --verbose
+hippius --gateway https://ipfs.io --api-url https://store.hippius.network --verbose
 ```
 
 ### IPFS Operations
@@ -321,6 +466,12 @@ hippius files 5H1QBRF7T7dgKwzVGCgS4wioudvMRf9K4NEDzfuKLnuyBNzH
 
 # Show all miners for each file
 hippius files --all-miners
+
+# View only erasure-coded files
+hippius ec-files
+
+# View erasure-coded files with details about chunks
+hippius ec-files --show-chunks
 ```
 
 ### Encryption
@@ -350,15 +501,26 @@ hippius erasure-code important_data.zip --k 4 --m 10 --chunk-size 2097152 --encr
 
 # Reconstruct a file from its metadata
 hippius reconstruct QmMetadataCID reconstructed_file.mp4
+
+# List all your erasure-coded files with metadata CIDs
+hippius ec-files
+
+# Show all miners for each erasure-coded file
+hippius ec-files --all-miners
+
+# Show detailed information including associated chunks
+hippius ec-files --show-chunks
 ```
 
+The `ec-files` command has been optimized for performance and can now handle large numbers of files efficiently through parallel processing.
+
 ### Using Environment Variables
 
 The CLI automatically reads from your `.env` file for common settings:
 
 ```
 IPFS_GATEWAY=https://ipfs.io
-IPFS_API_URL=https://relay-fr.hippius.network
+IPFS_API_URL=https://store.hippius.network
 SUBSTRATE_URL=wss://rpc.hippius.network
 SUBSTRATE_SEED_PHRASE="your twelve word seed phrase..."
 SUBSTRATE_DEFAULT_MINERS=miner1,miner2,miner3
@@ -432,6 +594,88 @@ The SDK provides robust connection handling for IPFS:
 
 This dual approach ensures maximum compatibility across different environments. The fallback happens automatically, so you don't need to worry about it.
 
+## Configuration
+
+Hippius SDK now supports persistent configuration stored in your home directory at `~/.hippius/config.json`. This makes it easier to manage your settings without having to specify them each time or maintain environment variables.
+
+### Configuration Management
+
+The configuration file is automatically created with default values when you first use the SDK. You can manage it using the CLI:
+
+```bash
+# List all configuration settings
+hippius config list
+
+# Get a specific configuration value
+hippius config get ipfs gateway
+
+# Set a configuration value
+hippius config set ipfs gateway https://ipfs.io
+
+# Import settings from your .env file
+hippius config import-env
+
+# Reset configuration to default values
+hippius config reset
+```
+
+### Configuration Structure
+
+The configuration is organized in the following sections:
+
+```json
+{
+  "ipfs": {
+    "gateway": "https://ipfs.io",
+    "api_url": "https://store.hippius.network",
+    "local_ipfs": false
+  },
+  "substrate": {
+    "url": "wss://rpc.hippius.network",
+    "seed_phrase": null,
+    "default_miners": [],
+    "default_address": null
+  },
+  "encryption": {
+    "encrypt_by_default": false,
+    "encryption_key": null
+  },
+  "erasure_coding": {
+    "default_k": 3,
+    "default_m": 5,
+    "default_chunk_size": 1048576
+  },
+  "cli": {
+    "verbose": false,
+    "max_retries": 3
+  }
+}
+```
+
+### Environment Variables and Configuration
+
+The SDK still supports environment variables for backward compatibility. You can import settings from your `.env` file to the configuration using:
+
+```bash
+hippius config import-env
+```
+
+### Using Configuration in Code
+
+```python
+from hippius_sdk import get_config_value, set_config_value, HippiusClient
+
+# Get a configuration value
+gateway = get_config_value("ipfs", "gateway")
+print(f"Current gateway: {gateway}")
+
+# Set a configuration value
+set_config_value("ipfs", "gateway", "https://dweb.link")
+
+# Client will automatically use configuration values
+client = HippiusClient()
+```
+
 ## Development
 
 ```bash
@@ -575,7 +819,13 @@ hippius --help
    which hippius
    ```
 
-4. **Substrate Issues**: For marketplace operations, make sure your `.env` has the correct `SUBSTRATE_SEED_PHRASE` and `SUBSTRATE_URL` values.
+4. **Default Address Issues**: If you receive errors about missing account address:
+   ```bash
+   # Set a default address for read-only operations
+   hippius address set-default 5H1QBRF7T7dgKwzVGCgS4wioudvMRf9K4NEDzfuKLnuyBNzH
+   ```
+
+5. **Substrate Issues**: For marketplace operations, make sure your `.env` has the correct `SUBSTRATE_SEED_PHRASE` and `SUBSTRATE_URL` values.
 
 ## Contributing
 
@@ -585,3 +835,111 @@ Contributions are welcome! Please feel free to submit a Pull Request.
 
 This project is licensed under the MIT License - see the LICENSE file for details.
 
+### Seed Phrase Management
+
+For enhanced security, Hippius SDK supports encrypting your Substrate seed phrase with a password:
+
+```bash
+# Set a seed phrase in plain text
+hippius seed set "your twelve word seed phrase here"
+
+# Set a seed phrase and encrypt it with a password
+hippius seed set "your twelve word seed phrase here" --encode
+# You will be prompted to enter and confirm a password
+
+# Check the status of your seed phrase
+hippius seed status
+
+# Encrypt an existing seed phrase with a password
+hippius seed encode
+# You will be prompted to enter and confirm a password
+
+# Temporarily decrypt and view your seed phrase
+hippius seed decode
+# You will be prompted to enter your password
+```
+
+> **Note:** Password-based encryption requires both the `pynacl` and `cryptography` Python packages, which are included as dependencies when you install Hippius SDK.
+
+To use password-based seed phrase encryption:
+1. Set your seed phrase with encryption: `hippius seed set "your seed phrase" --encode`
+2. You'll be prompted to enter and confirm a secure password
+3. The seed phrase will be encrypted using your password and stored safely
+4. When the SDK needs to use your seed phrase, you'll be prompted for your password
+5. Your password is never stored - it's only used temporarily to decrypt the seed phrase
+
+This provides enhanced security by:
+- Protecting your seed phrase with a password only you know
+- Never storing the seed phrase in plain text
+- Using strong cryptography (PBKDF2 with SHA-256) to derive encryption keys
+- Requiring your password every time the seed phrase is needed
+
+When interacting with the Hippius SDK programmatically, you can provide the password when initializing clients:
+
+```python
+from hippius_sdk import HippiusClient
+
+# The client will prompt for password when needed to decrypt the seed phrase
+client = HippiusClient()
+
+# Or you can provide a password when initializing
+client = HippiusClient(seed_phrase_password="your-password")
+```
+
+### Multi-Account Management
+
+Hippius SDK now supports managing multiple named accounts, each with their own seed phrase:
+
+```bash
+# Set a seed phrase for a named account
+hippius seed set "your seed phrase here" --account "my-validator"
+
+# Set another seed phrase for a different account
+hippius seed set "another seed phrase" --account "my-developer-account" --encode
+
+# List all configured accounts
+hippius account list
+
+# Switch the active account
+hippius account switch my-developer-account
+
+# Check the status of a specific account
+hippius seed status --account my-validator
+
+# Delete an account
+hippius account delete my-developer-account
+```
+
+Key features of the multi-account system:
+
+1. **Named Accounts**: Each account has a unique name for easy identification
+2. **SS58 Address Storage**: Addresses are stored unencrypted for convenient access
+3. **Active Account**: One account is designated as "active" and used by default
+4. **Shared Password**: All accounts use the same password for encryption
+5. **Separate Encryption**: Each account can choose whether to encrypt its seed phrase
+
+To use multiple accounts in your code:
+
+```python
+from hippius_sdk import HippiusClient, set_active_account, list_accounts
+
+# List all accounts
+accounts = list_accounts()
+for name, data in accounts.items():
+    print(f"{name}: {data.get('ss58_address')}")
+
+# Switch the active account
+set_active_account("my-validator")
+
+# Create a client with the active account
+client = HippiusClient(seed_phrase_password="your-password")
+
+# Or specify a different account to use
+client = HippiusClient(
+    account_name="my-developer-account",
+    seed_phrase_password="your-password"
+)
+```
+
+The multi-account system makes it easier to manage multiple identities while maintaining security and convenience.
+