sseed 1.12.1

Offline BIP39/SLIP39 CLI Tool for secure cryptocurrency seed management

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	Code	Script	Example
English	en	Latin	abandon ability able...
Spanish	es	Latin	ábaco abdomen abedul...
French	fr	Latin	abaisser abandon abdiquer...
Italian	it	Latin	abaco abbaglio abbinare...
Portuguese	pt	Latin	abacate abalar abater...
Czech	cs	Latin	abdikace abeceda adresa...
Chinese (Simplified)	zh-cn	Ideographic	的 一 是 在 不 了...
Chinese (Traditional)	zh-tw	Ideographic	的 一 是 在 不 了...
Korean	ko	Hangul	가격 가끔 가난 가능...

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

Application	Purpose	Options	Example
bip39	Child BIP39 mnemonics	12/15/18/21/24 words, 9 languages	sseed bip85 bip39 -w 12 -l en -n 0
hex	Raw entropy bytes	16-64 bytes, upper/lowercase	sseed bip85 hex -b 32 -u -n 0
password	Secure passwords	4 character sets, 10-128 chars	sseed bip85 password -l 20 -c base64 -n 0

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

Command	Purpose	Example
sseed version	Show version and system info	sseed version --json
sseed gen	Generate BIP-39 mnemonic	sseed gen -l es -o backup.txt
sseed seed	Generate BIP-32 master seed from BIP-39 mnemonic	sseed seed -i mnemonic.txt --hex
sseed bip85	Generate BIP85 deterministic entropy	sseed bip85 bip39 --words 12 --index 0
sseed derive-addresses	Derive HD wallet addresses	sseed derive-addresses -c bitcoin -n 5
sseed shard	Split into SLIP-39 shards	sseed shard -g 3-of-5 -i seed.txt
sseed restore	Reconstruct from shards	sseed restore shard*.txt

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

Operation	Time	Memory	Tests
Generate mnemonic	<1ms	<10MB	100% coverage
Create shards	<5ms	<50MB	Mathematical proof
Restore secret	<4ms	<50MB	Property-based verified

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