SSeed

Secure, offline BIP39/SLIP39 cryptocurrency seed management with multi-language support

✨ Features

• 🌍 Multi-Language BIP-39 Support - Generate and restore mnemonics in 9 languages with automatic detection
• 🔐 Generate secure BIP-39 mnemonics with flexible word counts (12, 15, 18, 21, or 24 words) using cryptographically secure entropy
• 🌱 Generate master seeds from mnemonics using PBKDF2-HMAC-SHA512 per BIP-39 specification
• 🎯 BIP85 deterministic entropy derivation - unlimited child wallets, passwords, and keys from single master
• 💰 HD wallet address derivation - Generate Bitcoin, Ethereum, Litecoin addresses from mnemonics with BIP32/44/49/84 support
• 🔄 Split secrets using SLIP-39 with flexible group/threshold configurations
• 🔧 Reconstruct mnemonics from shards with integrity validation
• 🚫 100% offline operation - zero network calls, air-gapped security
• ⚡ Lightning fast - sub-millisecond operations, <100MB memory usage
• 🛡️ Secure memory handling - automatic cleanup of sensitive data
• 🧪 Mathematical verification - property-based testing with Hypothesis
• 🎯 Simple CLI interface - intuitive commands, version info, scriptable automation
• 📦 Zero dependencies - self-contained, easy deployment
• 🌍 Cross-platform - macOS, Linux, Windows compatibility

🌍 Multi-Language Support

SSeed supports all 9 official BIP-39 languages with automatic detection:

Language Features

• ✅ Automatic Detection - Identifies mnemonic language with 95%+ accuracy
• ✅ Unicode Support - Full support for international character sets
• ✅ Generate in Any Language - Use --language/-l flag for generation
• ✅ Seamless Recovery - Auto-detects language during restore operations
• ✅ 100% Backward Compatible - English remains default, existing code unchanged

✨ Key Features

• 🔐 Secure Generation: BIP-39 mnemonics with flexible word counts (12, 15, 18, 21, 24) using cryptographic entropy
• 🌍 Multi-Language: Generate and restore in 9 languages with auto-detection
• 🎯 BIP85 Deterministic Entropy: Generate unlimited child wallets, passwords, and hex entropy from one master seed
• 🧩 SLIP-39 Sharding: Split mnemonics into threshold-based secret shares
• 🔄 Perfect Recovery: Reconstruct original mnemonics from sufficient shards
• 🌱 Master Seed Generation: BIP-39 compliant PBKDF2-HMAC-SHA512 seed derivation
• 🎯 BIP85 Deterministic Entropy: Generate unlimited child wallets, passwords, and hex entropy from one master seed
• 🔍 Entropy Display: View underlying entropy alongside mnemonics for verification
• ⚡ Cross-Tool Compatibility: Full interoperability with official Trezor SLIP-39 CLI
• 🛡️ Security First: Memory cleanup, input validation, and comprehensive error handling
• 📁 Flexible I/O: File operations, stdin/stdout, and batch processing support
• 🧪 Battle Tested: 632 comprehensive tests with 95%+ code coverage

🚀 Quick Install

pip install sseed

📖 Quick Start

Generate → Shard → Restore Demo

# Generate a secure mnemonic (English by default)
$ sseed gen
abandon ability able about above absent absorb abstract absurd abuse access accident

# Generate in different languages
$ sseed gen -l es  # Spanish
ábaco abdomen abedul abeja abismo abogado abono aborto abrazo abrir absurdo abuelo

$ sseed gen -l zh-cn  # Chinese Simplified
的 一 是 在 不 了 有 和 人 这 中 大 为 上 个 国 我 以 要 他

# Generate master seed from mnemonic (BIP-39 → BIP-32 HD wallet seed)
$ sseed gen | sseed seed --hex
7adb1efaf1659636ca22a200c4e688a2041972ebb8d1d49a71c4cb40b4a283fc51d4cfe31d45c0f90eb08a246008f8707f961b674246b016aa303041ceccb848

# Split into 3-of-5 threshold shards (language auto-detected)
$ sseed gen -l es | sseed shard -g 3-of-5
# Language: Spanish (es) - Auto-detected
# Group 1 of 1 - Share 1 of 5: academic acid acrobat...
# Group 1 of 1 - Share 2 of 5: academic acid beard...
# Group 1 of 1 - Share 3 of 5: academic acid ceramic...
# Group 1 of 1 - Share 4 of 5: academic acid decision...
# Group 1 of 1 - Share 5 of 5: academic acid echo...

# Restore from any 3 shards (language auto-detected)
$ sseed restore shard1.txt shard2.txt shard3.txt
# Language: Spanish (es) - Auto-detected
ábaco abdomen abedul abeja abismo abogado abono aborto abrazo abrir absurdo abuelo

System Information

# Show comprehensive version information
$ sseed version
🔐 SSeed v1.12.0
========================================

📋 Core Information:
   Version: 1.12.0
   Python:  3.12.2 (CPython)

🖥️  System Information:
   OS:           Darwin 23.6.0
   Architecture: arm64 (64bit)

📦 Dependencies:
   ✅ bip-utils: 2.9.3
   ✅ shamir-mnemonic: 0.3.0

# JSON format for automation
$ sseed version --json
{"sseed": "1.12.0", "python": "3.12.2", "platform": {...}}

Advanced Usage

# Generate to file with timestamp
sseed gen -o "backup-$(date +%Y%m%d).txt"

# Generate 512-bit master seed from mnemonic (for HD wallets)
sseed seed -i mnemonic.txt --hex

# Generate master seed with passphrase (25th word protection)
sseed seed -i mnemonic.txt -p "my_passphrase" --hex

# Generate master seed with higher security (more PBKDF2 iterations)
sseed seed -i mnemonic.txt --iterations 4096 --hex

# Multi-group configuration (enterprise setup)
sseed shard -g "2:(2-of-3,3-of-5)" -i seed.txt --separate -o shards/

# Restore with passphrase protection
sseed restore -p "my-secure-passphrase" shard*.txt

# Generate with entropy display (for verification)
sseed gen --show-entropy

# Restore with entropy verification
sseed restore --show-entropy shard1.txt shard2.txt shard3.txt

# Entropy consistency verification workflow
ORIGINAL_ENTROPY=$(sseed gen --show-entropy | grep "# Entropy:" | cut -d' ' -f3)
echo "$ORIGINAL_ENTROPY" > entropy_backup.txt

HD Wallet Address Derivation

# Generate Bitcoin addresses from mnemonic
sseed derive-addresses -c bitcoin -n 5 < mnemonic.txt
# Outputs 5 Native SegWit addresses (bc1q...)

# Generate Bitcoin Legacy addresses  
sseed derive-addresses -c bitcoin -t legacy -n 3 < mnemonic.txt
# Outputs 3 Legacy addresses (1...)

# Generate Ethereum addresses
sseed derive-addresses -c ethereum -n 2 < mnemonic.txt
# Outputs 2 Ethereum addresses (0x...)

# Custom derivation parameters
sseed derive-addresses -c bitcoin -t native-segwit -a 1 --change 1 --start-index 10 -n 5
# Account 1, change addresses, starting from index 10

# JSON output with private keys (use with caution)
sseed derive-addresses --format json --include-private-keys -n 1 < mnemonic.txt

# CSV output for spreadsheet import
sseed derive-addresses --format csv -c bitcoin -n 10 > addresses.csv

# Generate extended keys (xpub/xprv)
sseed derive-addresses --extended-keys -c bitcoin -t native-segwit

🔬 Entropy Analysis & Verification

SSeed provides comprehensive entropy quality analysis to help you understand and verify the randomness quality of both system-generated and custom entropy sources.

System Entropy Analysis

# Analyze system-generated entropy quality
sseed gen --entropy-analysis

# Combined analysis with entropy display
sseed gen --entropy-analysis --show-entropy

Sample Output:

📊 System Entropy Quality Analysis:
   Quality: Excellent (cryptographically secure)
   Source: System (secrets.SystemRandom)
   Entropy: 256 bits (32 bytes)
   Randomness: ✅ Cryptographically secure distribution
   Security: ✅ Meets all cryptographic standards
   Recommendation: ✅ Optimal entropy source - no improvements needed

Custom Entropy Analysis

# Analyze custom hex entropy
sseed gen --entropy-hex "a1b2c3d4..." --entropy-analysis

# Analyze dice entropy quality
sseed gen --entropy-dice "1,2,3,4,5,6..." --entropy-analysis

# Validate existing mnemonic entropy
sseed validate --mode entropy -i wallet.txt --json

Custom Entropy Output:

📊 Entropy Quality Analysis:
   Quality Score: 60/100
   Warnings:
     • Highly skewed byte distribution detected
   Recommendations:
     • Consider using system entropy instead of custom entropy

🎯 BIP85 Deterministic Entropy

SSeed implements BIP85 for deterministic entropy generation, enabling unlimited child wallets, passwords, and cryptographic secrets from a single master seed backup. This transforms SSeed into a complete cryptographic entropy management system.

What is BIP85?

BIP85 allows deriving multiple independent secrets from one master seed:

• 🔒 One Master Backup: Single mnemonic protects unlimited child wallets
• 🎲 Deterministic: Same parameters always produce identical output
• 🔐 Independent: Child entropy appears completely random
• 🌍 Multi-Purpose: BIP39 mnemonics, hex entropy, passwords
• 🛡️ Secure: Information-theoretic independence between children

Quick BIP85 Examples

# Generate master mnemonic
$ sseed gen -o master.txt

# Generate child BIP39 wallets
$ sseed bip85 bip39 -i master.txt -w 12 -n 0  # Child wallet #1
$ sseed bip85 bip39 -i master.txt -w 12 -n 1  # Child wallet #2
$ sseed bip85 bip39 -i master.txt -w 24 -l es -n 2  # Spanish child wallet

# Generate hex entropy (for keys, tokens)
$ sseed bip85 hex -i master.txt -b 32 -n 0    # 32 bytes entropy
$ sseed bip85 hex -i master.txt -b 16 -u -n 1 # 16 bytes uppercase

# Generate passwords 
$ sseed bip85 password -i master.txt -l 20 -c base64 -n 0      # Base64 password
$ sseed bip85 password -i master.txt -l 16 -c alphanumeric -n 1 # Alphanumeric

BIP85 Applications

Advanced BIP85 Workflows

# Master → Multiple Child Wallets
sseed gen -o master.txt
sseed bip85 bip39 -i master.txt -w 12 -n 0 -o wallet1.txt  # Personal wallet
sseed bip85 bip39 -i master.txt -w 12 -n 1 -o wallet2.txt  # Business wallet  
sseed bip85 bip39 -i master.txt -w 12 -n 2 -o wallet3.txt  # Backup wallet

# Multi-Language Child Wallets
sseed bip85 bip39 -i master.txt -w 24 -l en -n 0 -o english.txt
sseed bip85 bip39 -i master.txt -w 24 -l es -n 1 -o spanish.txt
sseed bip85 bip39 -i master.txt -w 24 -l zh-cn -n 2 -o chinese.txt

# BIP85 + SLIP39 Combination  
sseed bip85 bip39 -i master.txt -w 12 -n 0 | sseed shard -g 3-of-5
sseed bip85 bip39 -i master.txt -w 24 -l es -n 1 | sseed shard -g 2-of-3

# Application-Specific Entropy
sseed bip85 hex -i master.txt -b 32 -n 0 -o app1_key.hex     # App 1 encryption key
sseed bip85 hex -i master.txt -b 32 -n 1 -o app2_key.hex     # App 2 encryption key  
sseed bip85 password -i master.txt -l 32 -n 0 -o app.pwd     # Application password

🎯 Complete BIP85 Documentation →

📚 API Documentation

For programmatic integration, SSeed provides a clean Python API:

from sseed import generate_mnemonic, create_shards, restore_mnemonic

# Generate secure mnemonic
mnemonic = generate_mnemonic()

# Create threshold shards
shards = create_shards(mnemonic, groups="3-of-5")

# Restore from shards
restored = restore_mnemonic(shards[:3])

📖 Full API Documentation →

🛠️ Installation Options

From PyPI (Recommended)

pip install sseed

From Source

git clone https://github.com/ethene/sseed.git
cd sseed
pip install .

Development Setup

# Install in development mode
pip install -e ".[dev]"

# Run comprehensive test suite
pytest  # 290+ tests with 87.8% coverage

# Version management (follows PEP 440)
make bump-patch          # 1.0.1 → 1.0.2
make bump-minor          # 1.0.1 → 1.1.0
make bump-major          # 1.0.1 → 2.0.0
make bump-patch DRY_RUN=1  # Preview changes

# Quality assurance
make test               # Run tests with coverage
make check             # Code quality checks
make ci-test           # Run CI-style tests (lint + mypy + pytest)
make build             # Build distribution packages

🔧 Command Reference

Configuration Examples

Simple Threshold:

• 3-of-5 - Any 3 of 5 shards required

Multi-Group Security:

• 2:(2-of-3,3-of-5) - Need 2 groups: 2-of-3 AND 3-of-5 shards

Enterprise Setup:

• 3:(3-of-5,4-of-7,2-of-3) - Geographic distribution across 3 locations

🔒 Security Features

• ✅ Cryptographically secure entropy using secrets.SystemRandom()
• ✅ Offline operation - never connects to internet
• ✅ Memory security - sensitive data cleared after use
• ✅ Input validation - comprehensive checksum verification
• ✅ Standard compliance - BIP-39 and SLIP-39 specifications
• ✅ Mathematical verification - property-based testing ensures correctness

Standards Compliance

BIP-39 Implementation:

• Full BIP-39 specification compliance for mnemonic generation
• 2048-word English wordlist with 11 bits per word
• SHA-256 based checksum validation
• PBKDF2-HMAC-SHA512 for master seed derivation (2048 iterations default)

SLIP-39 Implementation:

• Standard: SLIP-0039 (SatoshiLabs Improvement Proposal 39)
• Library: shamir-mnemonic v0.3.0+ (Official Trezor reference implementation)
• Word List: 1024-word SLIP-39 wordlist (10 bits per word, 4-8 characters each)
• Algorithm: Shamir's Secret Sharing in GF(256) finite field
• Security: Information-theoretic security with perfect secrecy
• Maintainers: Trezor/SatoshiLabs team (matejcik, satoshilabs, stick)
• Specification: https://github.com/satoshilabs/slips/blob/master/slip-0039.md
• Repository: https://github.com/trezor/python-shamir-mnemonic

Cross-Tool Compatibility

SSeed is fully compatible with the official Trezor shamir CLI tool from python-shamir-mnemonic:

• Perfect Interoperability: Both use shamir-mnemonic>=0.3.0
• Interchangeable Shards: SLIP-39 shards work between both tools
• No Vendor Lock-in: Migrate freely between implementations

# Install official Trezor CLI alongside sseed
pip install shamir-mnemonic[cli]

# Full cross-tool compatibility
sseed shard -i mnemonic.txt -g 2-of-3 --separate -o shards
shamir recover  # Works with sseed-generated shards

shamir create 2of3  # Create with official Trezor tool
sseed restore shard1.txt shard2.txt  # Recover with sseed

⚡ Performance

Benchmarks: Exceeds enterprise requirements by 5-75x

🧪 Quality Assurance

• 87.0% test coverage with 300+ comprehensive tests
• Property-based testing using Hypothesis framework
• 9.86/10 code quality score (Pylint)
• Zero security vulnerabilities (Bandit audit)
• Mathematical verification of cryptographic properties

📋 Requirements

• Python: 3.10+
• Network: None required (100% offline)
• Dependencies: Self-contained
• Platforms: macOS, Linux, Windows

🤝 Contributing

Contributions welcome! Please ensure:

• Tests pass: pytest
• Code quality: pylint sseed/
• Coverage maintained: pytest --cov=sseed

📄 License

MIT License - see LICENSE file for details.

⚠️ Security Notice

For Educational and Legitimate Use Only

• Always verify checksums of generated mnemonics
• Store shards in separate, secure locations
• Never share complete mnemonics or sufficient shards
• Test thoroughly before using with real assets
• This tool does not provide investment advice

Made with ❤️ for the cryptocurrency community