Seed Management

Best practices for managing BIP39 seed phrases and mnemonic security in SatSigner

Overview

Seed phrases (mnemonics) are the master keys to your Bitcoin wallet. SatSigner implements comprehensive security measures to protect these critical secrets throughout their lifecycle.

BIP39 Seed Phrases

Supported Configurations

SatSigner supports standard BIP39 mnemonic configurations:

Word Counts:

• 12 words (128-bit entropy)
• 15 words (160-bit entropy)
• 18 words (192-bit entropy)
• 21 words (224-bit entropy)
• 24 words (256-bit entropy)

Word Lists:

• English (default)
• Multiple language support via BIP39 standard

Optional Passphrase:

• BIP39 25th word (“passphrase”)
• Adds additional layer of protection
• Creates entirely different wallet from same seed

Seed Generation

When generating a new seed (Creation Type: generateMnemonic):

1. Entropy Source: Cryptographically secure random number generator
2. Word Selection: From BIP39 standardized word list
3. Checksum: Automatically calculated and appended
4. Validation: Ensures valid BIP39 structure

// Secure random number generation (apps/mobile/utils/crypto.ts:21-24)
function randomNum() {
  return crypto.getRandomValues(new Uint32Array(1))[0] / MAX_UINT32
}

Seed Storage Architecture

Encryption at Rest

All seed phrases are encrypted before storage (apps/mobile/types/models/Account.ts:40-52):

type Secret = {
  mnemonic?: string              // BIP39 seed phrase
  passphrase?: string            // Optional 25th word
  externalDescriptor?: string    // Descriptor info
  internalDescriptor?: string    // Change descriptor
  extendedPublicKey?: string     // Watch-only xpub
  fingerprint?: string           // Key fingerprint
}

Storage Layers

Layer 1: Encryption

• Algorithm: AES-256-CBC
• Key: Derived from user PIN via PBKDF2
• IV: Unique per account

Layer 2: Secure Storage

• iOS: Keychain (hardware-backed)
• Android: SharedPreferences (encrypted)
• Platform: expo-secure-store

Layer 3: Application State

• MMKV storage for non-sensitive account metadata
• Encrypted secrets stored separately
• No plaintext seed phrases in logs

Seed Verification

Initial Verification Process

When creating a new wallet, users must verify their seed phrase to ensure proper backup:

1. Display Phase: Show all words in order
2. Write Down: User records words securely
3. Verification Phase: Random word challenges

Word Verification Challenge

SatSigner implements a secure verification system (apps/mobile/utils/seed.ts:4-35):

function getConfirmWordCandidates(
  currentWord: string,
  seedWords: string
): string[] {
  // Returns 3 candidates including the correct word
  // Candidates are shuffled randomly
  // Incorrect candidates chosen from same seed to prevent guessing
}

Security Feature: Decoy words come from the same seed phrase, making it impossible to verify the seed without proper backup.

Prefix Ambiguity Handling

Some BIP39 words are prefixes of others (apps/mobile/utils/seed.ts:40-90):

// Examples of ambiguous prefixes:
'act' vs 'action'
'add' vs 'address' 
'arm' vs 'army'

SatSigner maintains a list of these ambiguous words to ensure proper input validation and prevent user confusion.

Seed “Dropping” Feature

Watch-Only Mode

SatSigner supports “dropping” the seed while keeping watch-only capabilities:

What is Seed Dropping?

• Converts signing wallet to watch-only
• Deletes private key material (seed/mnemonic)
• Retains public keys and addresses
• Preserves transaction history viewing

When to Drop Seeds:

• Moving to cold storage
• Reducing mobile device risk
• Maintaining portfolio visibility without spending capability

Technical Implementation

After dropping seed (checked via seedDropped flag in apps/mobile/hooks/useKeyValidation.ts:7):

// Remaining data after seed drop:
- extendedPublicKey (xpub/tpub/ypub/zpub)
- externalDescriptor (for address generation)
- internalDescriptor (for change addresses)
- fingerprint (key identification)

What is Deleted:

• mnemonic - Seed phrase words
• passphrase - BIP39 passphrase if present
• Private key derivation capability

Irreversible Action: Dropping a seed is permanent. Ensure you have secure backup of seed phrase before dropping. Accounts become watch-only and cannot sign transactions.

Seed Import Methods

Manual Entry

Process:

1. Select word count (12/15/18/21/24)
2. Enter each word from BIP39 word list
3. Auto-completion prevents invalid words
4. Checksum validation ensures correct entry
5. Optional passphrase entry

Security Features:

• Only valid BIP39 words accepted
• Prefix matching for faster entry
• No clipboard access for word entry
• Immediate encryption after validation

QR Code Import

SatSigner supports multiple QR code formats (apps/mobile/utils/seedqr.ts):

Standard Format (SeedQR)

// Each word encoded as 4-digit decimal (0000-2047)
// Example: "word" at index 1985 becomes "1985"
encodeStandardSeedQR(mnemonic, wordList)

Format Details:

• 4 digits per word
• 48 digits for 12-word seed
• 96 digits for 24-word seed

Compact Format (CompactSeedQR)

// Each word encoded as 11-bit binary
// More efficient for QR code density
encodeCompactSeedQR(mnemonic, wordList)

Format Details:

• 11 bits per word (2048 possible values)
• 128 bits for 12-word seed (minus 4 checksum bits)
• 264 bits for 24-word seed

Descriptor Import

Watch-Only Import:

• Import output descriptors directly
• No seed phrase required
• Suitable for viewing accounts from hardware wallets
• Supports both external and internal (change) descriptors

Seed Re-Encryption

PIN Change Impact

When changing PIN, all encrypted seeds must be re-encrypted (apps/mobile/hooks/useReEncryptAccounts.ts:26-39):

// Re-encryption process:
1. Decrypt secret with old PIN
2. Parse decrypted Secret object
3. Encrypt secret with new PIN
4. Update stored encrypted secret
5. Update initialization vector (IV)

Security Considerations:

• Brief moment of decryption during re-encryption
• Process happens in secure memory
• No plaintext written to storage
• Atomic operation prevents partial updates

Best Practices

Seed Generation

Use Built-In Generator: Always use SatSigner’s built-in seed generation. Never:

• Generate seeds on computers or online
• Use “brain wallets” or personal phrases
• Trust third-party seed generators
• Use dice or manual methods without proper entropy

Seed Backup

Mandatory Practices:

1. Physical Backup

   • Write seed words on paper or metal
   • Store in secure physical location
   • Never digital copy (photo, file, cloud)
   • Consider multiple geographic locations

2. Verification

   • Verify backup immediately after writing
   • Test recovery process with small amount first
   • Periodic verification of backup readability

3. Passphrase Backup

   • If using passphrase, back up separately
   • Remember: seed + passphrase required for recovery
   • Consider multi-location storage

Seed Protection

Security Measures:

✓ Never Share - Seed phrase is complete access to funds ✓ No Digital Copies - No photos, screenshots, or cloud storage ✓ Physical Security - Fire-proof and water-proof storage ✓ Access Control - Limited people aware of location ✓ Duress Plan - Consider duress PIN for emergency situations

Passphrase as Duress Wallet: Use a small decoy amount without passphrase, keep main funds in same seed + passphrase. Provides plausible deniability.

Seed Exposure Response

If you suspect seed phrase compromise:

1. Immediate Action

   • Generate new seed phrase immediately
   • Transfer all funds to new wallet
   • Do not reuse compromised seed

2. Investigation

   • Identify exposure vector
   • Assess other potential compromises
   • Update security practices

3. Documentation

   • Record incident details
   • Note when/how exposure occurred
   • Update operational security procedures

Multi-Signature Considerations

Key Management

For multi-signature wallets:

Each Cosigner Key:

• Separate seed phrase
• Independent backup requirement
• Individual encryption
• Distinct fingerprints

Coordinator Responsibility:

• Track all cosigner fingerprints
• Maintain cosigner order
• Backup wallet descriptor
• Document signing threshold (m-of-n)

Seed Dropping in Multisig

Considerations:

• Can drop seeds for keys not needed for spending
• Maintain at least m keys with seeds for m-of-n wallet
• Example: In 2-of-3 wallet, can safely drop one seed if other two secure

Technical Security Details

Entropy Quality

SatSigner uses platform-provided CSPRNG:

// From react-native-get-random-values
crypto.getRandomValues(new Uint32Array(1))

Entropy Sources:

• iOS: SecRandomCopyBytes (hardware-backed)
• Android: SecureRandom (hardware-backed when available)
• Minimum 128-bit entropy for 12-word seeds

Memory Protection

Runtime Measures:

• Seed phrases only decrypted when needed
• Immediate zeroing after use (where possible)
• No logging of sensitive material
• Secure text input fields

Platform Limitations:

• JavaScript doesn’t guarantee memory clearing
• Relies on garbage collection
• Consider device-level encryption as additional layer

Fingerprint Calculation

Key fingerprints help identify seeds without exposing them:

// BIP32 fingerprint (first 32 bits of key hash)
// Used for:
- Key identification in multisig
- PSBT signing coordination
- Wallet descriptor tracking

Related Topics

• PIN Protection - Encryption key derivation
• Backup & Recovery - Comprehensive backup strategies
• Encryption - Technical encryption implementation
• Duress PIN - Emergency security feature