libcrypto 1.6.0__tar.gz → 1.6.2__tar.gz

libcrypto-1.6.2/PKG-INFO

@@ -0,0 +1,601 @@
+Metadata-Version: 2.4
+Name: libcrypto
+Version: 1.6.2
+Summary: Pure Python cryptocurrency address generation and cryptographic utilities.
+Author-email: Pymmdrza <pymmdrza@gmail.com>
+License: MIT
+Project-URL: Homepage, https://gitlab.com/0xmdrza/libcrypto
+Project-URL: Repository, https://gitlab.com/0xmdrza/libcrypto
+Project-URL: Issues, https://gitlab.com/0xmdrza/libcrypto/-/issues
+Project-URL: Documentation, https://gitlab.com/0xmdrza/libcrypto
+Keywords: bitcoin,ethereum,tron,wallet,address,cryptocurrency,secp256k1,keccak,base58,bech32
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Topic :: Security :: Cryptography
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+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.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Operating System :: OS Independent
+Classifier: Typing :: Typed
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# libcrypto
+
+A lightweight, dependency-free Python library for deterministic cryptocurrency key and address generation.
+
+`libcrypto` is designed for developers who need a clean, portable, and auditable cryptographic address engine without unnecessary runtime dependencies. It provides pure Python implementations for core wallet operations, including private key handling, public key derivation, address encoding, WIF conversion, mnemonic-based HD wallets, and multi-chain address generation.
+
+The library focuses on predictable output, compatibility with established address formats, and a stable public API suitable for production tools, research utilities, wallet infrastructure, offline generators, and blockchain automation systems.
+
+---
+
+## Key Features
+
+* Pure Python implementation
+* No required runtime dependencies
+* Deterministic private key to public address conversion
+* secp256k1 public key derivation
+* Real Keccak-256 implementation for Ethereum and TRON
+* RIPEMD-160 support with internal fallback
+* Base58Check, Bech32, Bech32m, and CashAddr support
+* Bitcoin legacy, nested SegWit, native SegWit, and Taproot addresses
+* Ethereum-compatible EVM address generation
+* TRON Base58 and hex address generation
+* WIF import and export
+* Public key based address generation
+* BIP39 mnemonic utilities
+* BIP32/BIP44-style HD wallet support
+* Clean API for single-wallet and batch generation workflows
+* Suitable for offline and local-first key/address operations
+
+---
+
+## Installation
+
+```bash
+pip install libcrypto
+```
+
+Upgrade to the latest version:
+
+```bash
+pip install --upgrade libcrypto
+```
+
+---
+
+## Examples
+
+Practical usage examples are available in the [`examples/`](examples/) directory.
+
+The Examples Cover Multi-chain Address Generation, Secure Wallet Creation, WIF import/export, Public-key-only Workflows, HD wallet Derivation, Batch CSV Generation, and Deterministic Address Test Vectors.
+
+> See [More Details](examples/README.md) for the Full Example Guide.
+
+---
+
+## Basic Usage
+
+Generate multiple blockchain addresses from a single private key:
+
+```python
+from libcrypto import Wallet
+
+
+private_key = "0000000000000000000000000000000000000000000000000000000000000001"
+
+wallet = Wallet(private_key)
+
+print("Bitcoin P2PKH:", wallet.get_address("bitcoin", "p2pkh"))
+print("Bitcoin P2SH-P2WPKH:", wallet.get_address("bitcoin", "p2sh-p2wpkh"))
+print("Bitcoin P2WPKH:", wallet.get_address("bitcoin", "p2wpkh"))
+print("Bitcoin Taproot:", wallet.get_address("bitcoin", "p2tr"))
+
+print("Ethereum:", wallet.get_address("ethereum"))
+
+print("TRON:", wallet.get_address("tron"))
+print("TRON Hex:", wallet.get_address("tron", "hex"))
+```
+
+Expected deterministic output for private key `1`:
+
+```text
+Bitcoin P2PKH: 1BgGZ9tcN4rm9KBzDn7KprQz87SZ26SAMH
+Bitcoin P2SH-P2WPKH: 3JvL6Ymt8MVWiCNHC7oWU6nLeHNJKLZGLN
+Bitcoin P2WPKH: bc1qw508d6qejxtdg4y5r3zarvary0c5xw7kv8f3t4
+Bitcoin Taproot: bc1pmfr3p9j00pfxjh0zmgp99y8zftmd3s5pmedqhyptwy6lm87hf5sspknck9
+Ethereum: 0x7E5F4552091A69125d5DfCb7b8C2659029395Bdf
+TRON: TMVQGm1qAQYVdetCeGRRkTWYYrLXuHK2HC
+TRON Hex: 417E5F4552091A69125D5DFCB7B8C2659029395BDF
+```
+
+---
+
+## Generate a New Wallet
+
+```python
+from libcrypto import Wallet
+
+
+wallet = Wallet.generate()
+
+print("Private key:", wallet.private_key.hex)
+print("WIF:", wallet.private_key.to_wif(compressed=True))
+
+print("Bitcoin:", wallet.get_address("bitcoin", "p2pkh"))
+print("Ethereum:", wallet.get_address("ethereum"))
+print("TRON:", wallet.get_address("tron"))
+```
+
+Security note: never expose, log, upload, or commit real private keys.
+
+---
+
+## Supported Address Types
+
+### Bitcoin
+
+```python
+from libcrypto import Wallet
+
+
+wallet = Wallet.generate()
+
+print(wallet.get_address("bitcoin", "p2pkh"))
+print(wallet.get_address("bitcoin", "p2sh-p2wpkh"))
+print(wallet.get_address("bitcoin", "p2wpkh"))
+print(wallet.get_address("bitcoin", "p2tr"))
+```
+
+Supported Bitcoin formats:
+
+| Type          | Description                   | Prefix |
+| ------------- | ----------------------------- | ------ |
+| `p2pkh`       | Legacy Pay-to-Public-Key-Hash | `1`    |
+| `p2sh-p2wpkh` | Nested SegWit                 | `3`    |
+| `p2wpkh`      | Native SegWit v0              | `bc1q` |
+| `p2tr`        | Taproot / Native SegWit v1    | `bc1p` |
+
+---
+
+### Ethereum and EVM Networks
+
+Ethereum and EVM-compatible chains use the same address derivation method.
+
+```python
+from libcrypto import Wallet
+
+
+wallet = Wallet.generate()
+
+print("Ethereum:", wallet.get_address("ethereum"))
+print("BSC:", wallet.get_address("bsc"))
+print("Polygon:", wallet.get_address("polygon"))
+print("Avalanche:", wallet.get_address("avalanche"))
+print("Arbitrum:", wallet.get_address("arbitrum"))
+print("Optimism:", wallet.get_address("optimism"))
+print("Base:", wallet.get_address("base"))
+print("Ethereum Classic:", wallet.get_address("ethereum_classic"))
+```
+
+EVM addresses are generated using Keccak-256 and returned with EIP-55 checksum formatting.
+
+---
+
+### TRON
+
+```python
+from libcrypto import Wallet
+
+
+wallet = Wallet.generate()
+
+print("TRON Base58:", wallet.get_address("tron"))
+print("TRON Hex:", wallet.get_address("tron", "hex"))
+```
+
+TRON addresses are generated from the same secp256k1 public key model used by Ethereum, but encoded with TRON's `0x41` address prefix and Base58Check representation.
+
+---
+
+### Litecoin, Dogecoin, Dash, Bitcoin Cash, DigiByte, and Namecoin
+
+```python
+from libcrypto import Wallet
+
+
+wallet = Wallet.generate()
+
+print("Litecoin:", wallet.get_address("litecoin", "p2pkh"))
+print("Dogecoin:", wallet.get_address("dogecoin", "p2pkh"))
+print("Dash:", wallet.get_address("dash", "p2pkh"))
+print("Bitcoin Cash:", wallet.get_address("bitcoin_cash", "cashaddr"))
+print("DigiByte:", wallet.get_address("digibyte", "p2pkh"))
+print("Namecoin:", wallet.get_address("namecoin", "p2pkh"))
+```
+
+---
+
+## Get All Addresses for a Coin
+
+```python
+from libcrypto import Wallet
+
+
+wallet = Wallet.generate()
+
+addresses = wallet.get_all_addresses("bitcoin")
+
+for address_type, address in addresses.items():
+    print(address_type, address)
+```
+
+Example output:
+
+```text
+p2pkh 1...
+p2sh-p2wpkh 3...
+p2wpkh bc1q...
+p2tr bc1p...
+```
+
+---
+
+## Private Key Handling
+
+Create a private key from hex:
+
+```python
+from libcrypto import PrivateKey
+
+
+private_key = PrivateKey(
+    "0000000000000000000000000000000000000000000000000000000000000001"
+)
+
+print(private_key.hex)
+```
+
+Generate a secure private key:
+
+```python
+from libcrypto import PrivateKey
+
+
+private_key = PrivateKey.generate()
+
+print(private_key.hex)
+```
+
+Export to WIF:
+
+```python
+from libcrypto import PrivateKey
+
+
+private_key = PrivateKey.generate(network="bitcoin")
+
+print(private_key.to_wif(compressed=True))
+print(private_key.to_wif(compressed=False))
+```
+
+Import from WIF:
+
+```python
+from libcrypto import PrivateKey, Wallet
+
+
+wif = "your_wif_private_key_here"
+
+private_key = PrivateKey(wif)
+wallet = Wallet(private_key)
+
+print(wallet.get_address("bitcoin", "p2pkh"))
+```
+
+---
+
+## Public Key Usage
+
+Generate addresses directly from public keys:
+
+```python
+from libcrypto import PrivateKey, PublicKey
+
+
+private_key = PrivateKey(
+    "0000000000000000000000000000000000000000000000000000000000000001"
+)
+
+compressed_public_key = private_key.get_public_key(compressed=True)
+uncompressed_public_key = private_key.get_public_key(compressed=False)
+
+bitcoin_public_key = PublicKey(compressed_public_key.hex)
+ethereum_public_key = PublicKey(uncompressed_public_key.hex)
+
+print(bitcoin_public_key.get_address("p2pkh", "bitcoin"))
+print(bitcoin_public_key.get_address("p2wpkh", "bitcoin"))
+print(ethereum_public_key.get_address("default", "ethereum"))
+```
+
+---
+
+## HD Wallets and Mnemonics
+
+Generate a mnemonic phrase:
+
+```python
+from libcrypto import generate_mnemonic, validate_mnemonic
+
+
+mnemonic = generate_mnemonic(12)
+
+print(mnemonic)
+print(validate_mnemonic(mnemonic))
+```
+
+Create an HD wallet from a mnemonic:
+
+```python
+from libcrypto import HDWallet, Wallet, generate_mnemonic
+
+
+mnemonic = generate_mnemonic(12)
+
+hd_wallet = HDWallet.from_mnemonic(
+    mnemonic,
+    passphrase="",
+    network="mainnet",
+)
+
+node = hd_wallet.derive_from_path("m/44'/60'/0'/0/0")
+
+if node.private_key is None:
+    raise RuntimeError("Derived node does not contain a private key.")
+
+wallet = Wallet(node.private_key)
+
+print(wallet.get_address("ethereum"))
+```
+
+Bitcoin derivation example:
+
+```python
+from libcrypto import HDWallet, Wallet, generate_mnemonic
+
+
+mnemonic = generate_mnemonic(12)
+
+hd_wallet = HDWallet.from_mnemonic(
+    mnemonic,
+    passphrase="",
+    network="mainnet",
+)
+
+node = hd_wallet.derive_from_path("m/84'/0'/0'/0/0")
+
+if node.private_key is None:
+    raise RuntimeError("Derived node does not contain a private key.")
+
+wallet = Wallet(node.private_key)
+
+print(wallet.get_address("bitcoin", "p2wpkh"))
+```
+
+TRON derivation example:
+
+```python
+from libcrypto import HDWallet, Wallet, generate_mnemonic
+
+
+mnemonic = generate_mnemonic(12)
+
+hd_wallet = HDWallet.from_mnemonic(
+    mnemonic,
+    passphrase="",
+    network="mainnet",
+)
+
+node = hd_wallet.derive_from_path("m/44'/195'/0'/0/0")
+
+if node.private_key is None:
+    raise RuntimeError("Derived node does not contain a private key.")
+
+wallet = Wallet(node.private_key)
+
+print(wallet.get_address("tron"))
+```
+
+---
+
+## Batch Wallet Generation
+
+```python
+import csv
+from pathlib import Path
+
+from libcrypto import Wallet
+
+
+output_path = Path("wallets.csv")
+
+fieldnames = [
+    "index",
+    "private_key_hex",
+    "bitcoin_p2pkh",
+    "bitcoin_p2wpkh",
+    "bitcoin_p2tr",
+    "ethereum",
+    "tron",
+]
+
+with output_path.open("w", newline="", encoding="utf-8") as file:
+    writer = csv.DictWriter(file, fieldnames=fieldnames)
+    writer.writeheader()
+
+    for index in range(1, 11):
+        wallet = Wallet.generate()
+
+        writer.writerow(
+            {
+                "index": index,
+                "private_key_hex": wallet.private_key.hex,
+                "bitcoin_p2pkh": wallet.get_address("bitcoin", "p2pkh"),
+                "bitcoin_p2wpkh": wallet.get_address("bitcoin", "p2wpkh"),
+                "bitcoin_p2tr": wallet.get_address("bitcoin", "p2tr"),
+                "ethereum": wallet.get_address("ethereum"),
+                "tron": wallet.get_address("tron"),
+            }
+        )
+
+print(f"Wallets written to {output_path.resolve()}")
+```
+
+Warning: this CSV file contains private keys. Store it offline and protect it carefully.
+
+---
+
+## Deterministic Test Vector
+
+This example verifies that the library produces deterministic and standard addresses from a known secp256k1 private key.
+
+```python
+from libcrypto import Wallet
+
+
+private_key = "0000000000000000000000000000000000000000000000000000000000000001"
+
+wallet = Wallet(private_key)
+
+assert wallet.get_address("bitcoin", "p2pkh") == "1BgGZ9tcN4rm9KBzDn7KprQz87SZ26SAMH"
+assert wallet.get_address("bitcoin", "p2sh-p2wpkh") == "3JvL6Ymt8MVWiCNHC7oWU6nLeHNJKLZGLN"
+assert wallet.get_address("bitcoin", "p2wpkh") == "bc1qw508d6qejxtdg4y5r3zarvary0c5xw7kv8f3t4"
+assert wallet.get_address("bitcoin", "p2tr") == "bc1pmfr3p9j00pfxjh0zmgp99y8zftmd3s5pmedqhyptwy6lm87hf5sspknck9"
+
+assert wallet.get_address("ethereum") == "0x7E5F4552091A69125d5DfCb7b8C2659029395Bdf"
+
+assert wallet.get_address("tron") == "TMVQGm1qAQYVdetCeGRRkTWYYrLXuHK2HC"
+assert wallet.get_address("tron", "hex") == "417E5F4552091A69125D5DFCB7B8C2659029395BDF"
+
+print("All deterministic address vectors passed.")
+```
+
+---
+
+## Command Line Usage
+
+If installed with console script support:
+
+```bash
+libcrypto --help
+```
+
+Example usage:
+
+```bash
+libcrypto generate
+```
+
+Depending on the installed version, CLI commands may expose wallet generation, address conversion, and inspection utilities.
+
+---
+
+## Design Goals
+
+`libcrypto` is built around a few strict design principles:
+
+1. Keep the public API simple and stable.
+2. Avoid unnecessary runtime dependencies.
+3. Provide deterministic and reproducible address generation.
+4. Use correct cryptographic primitives for each chain.
+5. Keep private key operations local and offline-friendly.
+6. Make the implementation easy to inspect, test, and package.
+
+---
+
+## Security Considerations
+
+`libcrypto` performs local cryptographic key and address operations. It does not protect users from unsafe operational practices.
+
+Follow these rules carefully:
+
+* Never use demo private keys for real funds.
+* Never commit private keys, mnemonic phrases, WIF keys, or seed material.
+* Never log private keys in production systems.
+* Never send private keys to remote APIs unless your application explicitly requires it and users fully understand the risk.
+* Prefer offline execution for sensitive key generation workflows.
+* Always verify address output with independent test vectors before integrating into high-value systems.
+* Use secure backups for mnemonic phrases and private keys.
+* Treat generated CSV, JSON, and text files containing private keys as highly sensitive data.
+
+This library is intended for developers who understand the responsibility of handling private keys and wallet material.
+
+---
+
+## Testing
+
+Run the test suite:
+
+```bash
+python -m pytest -q
+```
+
+Build the package locally:
+
+```bash
+python -m pip install --upgrade build twine
+python -m build --sdist --wheel
+python -m twine check dist/*
+```
+
+Install locally from source:
+
+```bash
+pip install .
+```
+
+---
+
+## Packaging
+
+The package is designed to be distributed as a pure Python wheel:
+
+```bash
+python -m build --wheel
+```
+
+Generated distributions are placed in:
+
+```text
+dist/
+```
+
+---
+
+## Project Links
+
+* Repository: https://gitlab.com/0xmdrza/libcrypto
+* PyPI: https://pypi.org/project/libcrypto/
+
+---
+
+## License
+
+This project is distributed under the MIT License.
+
+---
+
+## Disclaimer
+
+This software is provided for development, research, and infrastructure use. Cryptocurrency private key handling is security-critical. The authors and contributors are not responsible for lost funds, insecure deployments, compromised keys, incorrect integrations, or misuse of the library.
+
+Always test carefully before using any cryptographic tool in production.