hippius 0.1.0__py3-none-any.whl → 0.1.7__py3-none-any.whl

{hippius-0.1.0.dist-info → hippius-0.1.7.dist-info}/METADATA

@@ -1,21 +1,22 @@
 Metadata-Version: 2.1
 Name: hippius
-Version: 0.1.0
+Version: 0.1.7
 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)
@@ -23,6 +24,7 @@ Requires-Dist: pyperclip (>=1.8.2,<2.0.0) ; extra == "clipboard"
 Requires-Dist: python-dotenv (>=1.0.0,<2.0.0)
 Requires-Dist: requests (>=2.28.1,<3.0.0)
 Requires-Dist: substrate-interface (>=1.4.2,<2.0.0)
+Requires-Dist: zfec (>=1.5.3,<2.0.0)
 Project-URL: Documentation, https://github.com/thenervelab/hippius-sdk/docs
 Project-URL: Repository, https://github.com/thenervelab/hippius-sdk
 Description-Content-Type: text/markdown
@@ -65,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://relay-fr.hippius.network",  # For uploads (default)
 )
 
 # Upload a file to IPFS
@@ -172,6 +174,167 @@ raw_result = client.download_file(encrypted_result['cid'], "still_encrypted.txt"
 content = client.cat(encrypted_result['cid'], decrypt=True)
 ```
 
+## Erasure Coding
+
+Hippius SDK supports Reed-Solomon erasure coding for reliable and resilient file storage. This allows files to be split into chunks with added redundancy, so that the original file can be reconstructed even if some chunks are lost.
+
+### Erasure Coding Concepts
+
+- **k**: The number of data chunks needed to reconstruct the original file
+- **m**: The total number of chunks created (m > k)
+- The file can be reconstructed from any k chunks out of m total chunks
+- Higher redundancy (m-k) provides better protection against chunk loss
+
+### Using Erasure Coding
+
+```python
+from hippius_sdk import HippiusClient
+
+client = HippiusClient()
+
+# Erasure code a file with default parameters (k=3, m=5)
+result = client.erasure_code_file("large_file.mp4")
+metadata_cid = result["metadata_cid"]
+
+# Use custom parameters for more redundancy
+result = client.erasure_code_file(
+    file_path="important_data.zip",
+    k=4,               # Need 4 chunks to reconstruct
+    m=10,              # Create 10 chunks total (6 redundant)
+    chunk_size=2097152,  # 2MB chunks
+    encrypt=True       # Encrypt before splitting
+)
+
+# Store erasure-coded file in Hippius marketplace
+result = client.store_erasure_coded_file(
+    file_path="critical_backup.tar",
+    k=3,
+    m=5,
+    encrypt=True,
+    miner_ids=["miner1", "miner2", "miner3"]
+)
+
+# Reconstruct a file from its metadata
+reconstructed_path = client.reconstruct_from_erasure_code(
+    metadata_cid=metadata_cid,
+    output_file="reconstructed_file.mp4"
+)
+```
+
+### When to Use Erasure Coding
+
+Erasure coding is particularly useful for:
+
+- Large files where reliability is critical
+- Long-term archival storage
+- Data that must survive partial network failures
+- Situations where higher redundancy is needed without full replication
+
+### Advanced Features
+
+#### Small File Handling
+
+The SDK automatically adjusts parameters for small files:
+
+- If a file is too small to be split into `k` chunks, the SDK will adjust the chunk size
+- For very small files, the content is split into exactly `k` sub-blocks
+- Parameters are always optimized to provide the requested level of redundancy
+
+#### Robust Storage in Marketplace
+
+When using `store_erasure_coded_file`, the SDK now:
+
+- Stores both the metadata file AND all encoded chunks in the marketplace
+- Ensures miners can access all necessary data for redundancy and retrieval
+- Reports total number of files stored for verification
+
+#### CLI Commands
+
+The CLI provides powerful commands for erasure coding:
+
+```bash
+# Basic usage with automatic parameter adjustment
+hippius erasure-code myfile.txt
+
+# Specify custom parameters
+hippius erasure-code large_video.mp4 --k 4 --m 8 --chunk-size 4194304
+
+# For smaller files, using smaller parameters
+hippius erasure-code small_doc.txt --k 2 --m 5 --chunk-size 4096
+
+# Reconstruct a file from its metadata CID
+hippius reconstruct QmMetadataCID reconstructed_file.mp4
+```
+
+The CLI provides detailed output during the process, including:
+- Automatic parameter adjustments for optimal encoding
+- Progress of chunk creation and upload
+- 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
+
+#### 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. **Substrate Issues**: For marketplace operations, make sure your `.env` has the correct `SUBSTRATE_SEED_PHRASE` and `SUBSTRATE_URL` values.
+
 ## 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.
@@ -222,6 +385,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
@@ -240,6 +409,30 @@ hippius store my_file.txt --encrypt
 hippius download QmCID123 output_file.txt --decrypt
 ```
 
+### Erasure Coding
+
+```bash
+# Erasure code a file with default parameters (k=3, m=5)
+hippius erasure-code large_file.mp4
+
+# Erasure code with custom parameters
+hippius erasure-code important_data.zip --k 4 --m 10 --chunk-size 2097152 --encrypt
+
+# 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 makes it easy to track and manage your erasure-coded files separately from regular files. It provides the metadata CID needed for reconstruction and information about chunk distribution.
+
 ### Using Environment Variables
 
 The CLI automatically reads from your `.env` file for common settings:
@@ -320,6 +513,87 @@ 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://relay-fr.hippius.network",
+    "local_ipfs": false
+  },
+  "substrate": {
+    "url": "wss://rpc.hippius.network",
+    "seed_phrase": null,
+    "default_miners": []
+  },
+  "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
@@ -473,3 +747,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.
+

hippius-0.1.7.dist-info/RECORD

@@ -0,0 +1,10 @@
+hippius_sdk/__init__.py,sha256=fs2pZ_wIl3eaUz6qFprcRsZhYakqv6-qm468NZh-8h4,1260
+hippius_sdk/cli.py,sha256=RgRvBrrZ5PhFkfrkeGFP7byc1V_sbCJnLElrnCtr14A,76323
+hippius_sdk/client.py,sha256=RV9MPs9nFW7dd8rVMgJ2giPrX6ETOnvlJDqm9uwuQi8,14908
+hippius_sdk/config.py,sha256=NzAkmFaeE9-inHCCYL9cl97dZmSndx6OSgj9cQBWMAA,22872
+hippius_sdk/ipfs.py,sha256=RKIDFuYqPFZfbHTi-oMa_IfAUUmtJX1nFOFnOKlnbBk,63972
+hippius_sdk/substrate.py,sha256=ulLL3WcDHLm8eU_MuvqbzrCn2fbCdDDReJcxthMtFDw,29661
+hippius-0.1.7.dist-info/METADATA,sha256=u_wKxSFdznRWbflR4OLBJ7XbFBXBEB_sQjohUv5UD9g,24689
+hippius-0.1.7.dist-info/WHEEL,sha256=Zb28QaM1gQi8f4VCBhsUklF61CTlNYfs9YAZn-TOGFk,88
+hippius-0.1.7.dist-info/entry_points.txt,sha256=b1lo60zRXmv1ud-c5BC-cJcAfGE5FD4qM_nia6XeQtM,98
+hippius-0.1.7.dist-info/RECORD,,

hippius_sdk/__init__.py

@@ -4,8 +4,52 @@ Hippius SDK - Python interface for Hippius blockchain storage
 
 from hippius_sdk.client import HippiusClient
 from hippius_sdk.ipfs import IPFSClient
+from hippius_sdk.config import (
+    get_config_value,
+    set_config_value,
+    get_encryption_key,
+    set_encryption_key,
+    load_config,
+    save_config,
+    initialize_from_env,
+    get_all_config,
+    reset_config,
+    get_seed_phrase,
+    set_seed_phrase,
+    encrypt_seed_phrase,
+    decrypt_seed_phrase,
+    get_active_account,
+    set_active_account,
+    list_accounts,
+    delete_account,
+    get_account_address,
+)
 
 __version__ = "0.1.0"
-__all__ = ["HippiusClient", "IPFSClient"]
+__all__ = [
+    "HippiusClient",
+    "IPFSClient",
+    "get_config_value",
+    "set_config_value",
+    "get_encryption_key",
+    "set_encryption_key",
+    "load_config",
+    "save_config",
+    "initialize_from_env",
+    "get_all_config",
+    "reset_config",
+    "get_seed_phrase",
+    "set_seed_phrase",
+    "encrypt_seed_phrase",
+    "decrypt_seed_phrase",
+    "get_active_account",
+    "set_active_account",
+    "list_accounts",
+    "delete_account",
+    "get_account_address",
+]
+
+# Initialize configuration from environment variables for backward compatibility
+initialize_from_env()
 
 # Note: Substrate functionality will be added in a future release