Recovery Mechanisms

​

Overview

​

Recovery Scenarios

​

Scenario 1: Lost or Broken Device (Muun Operational)

• Recovery code (written down during wallet creation)

1. Install Muun on a new device
2. Tap “Recover wallet” on the welcome screen
3. Enter recovery code (8 words or alphanumeric string)
4. Set new PIN for the new device
5. Wait for sync (wallet state downloads from server)
6. Access restored with full balance and history

​

Scenario 2: Forgotten PIN (Device Still Available)

• Recovery code
• Access to the device (locked)

1. Tap “Forgot PIN?” on the lock screen
2. Enter recovery code
3. Set new PIN
4. Wallet unlocked without losing any data

​

Scenario 3: Lost Recovery Code (Device Still Available)

• Access to unlocked wallet

1. Open Muun (unlock with PIN/biometrics)
2. Go to Settings → Security
3. Tap “Show Recovery Code”
4. Authenticate (PIN/biometrics/security card)
5. Write down new code on paper
6. Verify you’ve written it correctly
7. Store securely in multiple locations

​

Scenario 4: Complete Emergency (Muun Offline Forever)

• Emergency Kit PDF
• Recovery code
• Bitcoin recovery tool (Muun provides one, or use Bitcoin Core)

​

Recovery Code

​

What is the Recovery Code?

// From recoverycode.go:7
const RecoveryCodeAlphabet = recoverycode.Alphabet

func GenerateRecoveryCode() string {
    return recoverycode.Generate()
}

• Random generation: Uses cryptographically secure random number generator
• High entropy: 128+ bits of randomness
• Versioned format: Supports upgrades to the code format
• Checksum: Detects typos during entry

​

Recovery Code Format

// From recoverycode.go:22
func RecoveryCodeToKey(code, salt string) (*ChallengePrivateKey, error) {
    privKey, err := recoverycode.ConvertToKey(code, salt)
    if err != nil {
        return nil, err
    }
    return &ChallengePrivateKey{key: privKey}, nil
}

func GetRecoveryCodeVersion(code string) (int, error) {
    return recoverycode.Version(code)
}

​

Recovery Code Validation

// From recoverycode.go:32
func ValidateRecoveryCode(code string) error {
    return recoverycode.Validate(code)
}

• Correct alphabet (no confusing characters like 0/O or 1/I/l)
• Proper length
• Valid checksum
• Recognized version

​

Storing Your Recovery Code

• ❌ “I’ll remember it” (you won’t)
• ❌ Saving in password manager (defeats the purpose)
• ❌ Storing in cloud (can be hacked)
• ❌ Only one copy (can be lost/destroyed)
• ❌ Storing with Emergency Kit PDF (all-eggs-one-basket)

​

Emergency Recovery

​

When to Use Emergency Recovery

• Muun’s servers are permanently offline
• You don’t trust Muun anymore and want to migrate
• Normal recovery isn’t working
• You want to prove you can recover independently

​

Prerequisites

1. Emergency Kit PDF (from your backup)
2. Recovery Code (written down separately)
3. Bitcoin recovery tool:
   • Muun’s official recovery tool (recommended)
   • Bitcoin Core with descriptor wallet support
   • Custom tool following Muun’s specs

• A new Bitcoin wallet to sweep funds to
• Transactions signed with both recovered keys

​

Step-by-Step Emergency Recovery

​

Step 1: Extract Encrypted Keys

// From challenge_keys.go:117
func DecodeEncryptedPrivateKey(encodedKey string) (*EncryptedPrivateKeyInfo, error) {
    reader := bytes.NewReader(base58.Decode(encodedKey))
    version, err := reader.ReadByte()
    
    if version == KeySerializationVersion2 {
        return decodeEncryptedPrivateKeyV2(reader, encodedKey)
    }
    
    if version == KeySerializationVersion3 {
        return decodeEncryptedPrivateKeyV3(reader)
    }
    
    return nil, fmt.Errorf("unrecognized key version %v", version)
}

1. Open PDF in any PDF reader
2. Locate encrypted keys section
3. Copy first encrypted key (user key)
4. Copy second encrypted key (Muun’s key)
5. Note the fingerprints for verification

​

Step 2: Decrypt Keys with Recovery Code

// From challenge_keys.go:55
func NewChallengePrivateKey(input, salt []byte) *ChallengePrivateKey {
    key := Scrypt256(input, salt)
    priv, _ := btcec.PrivKeyFromBytes(key)
    
    return &ChallengePrivateKey{key: priv}
}

func (k *ChallengePrivateKey) DecryptKey(decodedInfo *EncryptedPrivateKeyInfo,
    network *Network) (*DecryptedPrivateKey, error) {
    
    decoded, err := unwrapEncryptedPrivateKey(decodedInfo)
    
    plaintext, err := decryptWithPrivKey(k.key, decoded.EphPublicKey,
        decoded.CipherText)
    
    rawPrivKey := plaintext[0:32]
    rawChainCode := plaintext[32:]
    
    privKey, err := NewMasterHDPrivateKeyFromBytes(rawPrivKey, rawChainCode, network)
    
    return &DecryptedPrivateKey{
        privKey,
        int(decoded.Birthday),
    }, nil
}

1. Convert recovery code to key:
   • Apply Scrypt KDF with salt
   • Produces challenge private key
2. For each encrypted key:
   • Parse ephemeral public key from encrypted data
   • Perform ECDH: challenge_key × ephemeral_pubkey = shared_secret
   • Decrypt ciphertext using shared secret
   • Extract 32-byte private key + 32-byte chain code
   • Reconstruct BIP32 HD master key
3. Verify:
   • Derive public key from private key
   • Check fingerprint matches PDF
   • Confirm it’s the correct key

​

Step 3: Scan Blockchain for UTXOs

// From emergency_kit.go:137
metadata := &emergencykit.Metadata{
    BirthdayBlock:     secondKey.Birthday,
    OutputDescriptors: descriptors,
    // ...
}

1. Start at birthday block (no need to scan earlier)
2. Use output descriptors to generate all address types:
   • V2: P2SH multisig
   • V3-V4: P2WSH SegWit multisig
   • V5-V6: P2TR Taproot with MuSig2
   • Submarine swaps
   • Incoming swaps
3. Derive addresses using both keys:
   For each derivation path:
     user_pubkey = user_key.derive(path)
     muun_pubkey = muun_key.derive(path)
     address = create_multisig(user_pubkey, muun_pubkey)
   
4. Check each address for UTXOs on the blockchain
5. Build UTXO list with amounts and outpoints

• Bitcoin Core’s scantxoutset with descriptors
• Electrum server queries
• Block explorer APIs (less private)

​

Step 4: Create Sweep Transaction

// From V2.go:72
func (c *coinV2) FullySignInput(index int, tx *wire.MsgTx, userKey, 
    muunKey *HDPrivateKey) error {
    
    derivedUserKey, err := userKey.DeriveTo(c.KeyPath)
    derivedMuunKey, err := muunKey.DeriveTo(c.KeyPath)
    
    muunSignature, err := c.signature(index, tx, derivedUserKey.PublicKey(),
        derivedMuunKey.PublicKey(), derivedMuunKey)
    
    c.MuunSignature = muunSignature
    return c.SignInput(index, tx, userKey, muunKey.PublicKey())
}

1. Create transaction:
   • Inputs: All UTXOs you found
   • Output: Your new wallet’s address
   • Fee: Estimate current network fee
2. Sign inputs:
   • For each input, derive keys using its path
   • Create user signature
   • Create Muun signature (you have both keys!)
   • Build witness/scriptSig with both signatures
3. Verify transaction:
   • Check all inputs are signed correctly
   • Verify fee is reasonable
   • Confirm output address is yours
4. Broadcast transaction:
   • Submit to Bitcoin network via any node
   • Monitor for confirmation

​

Step 5: Wait for Confirmation

• First confirmation: 10 minutes average
• Full security: 6 confirmations (1 hour)
• Track status: Use block explorers
• Funds in new wallet: Once confirmed, emergency complete!

​

Recovery Tool Recommendations

• Pre-built for Muun’s format
• Handles all address versions
• Automates the entire process
• Open source for verification

# Import descriptors from Emergency Kit
bitcoin-cli importdescriptors '[{"desc":"...", "timestamp":1234567890}]'

# Scan for UTXOs
bitcoin-cli scantxoutset start '["desc"]'

# Create and sign transaction
bitcoin-cli createrawtransaction '[...]' '{"address":amount}'
bitcoin-cli signrawtransactionwithkey "hex" '["privkey1","privkey2"]'

# Broadcast
bitcoin-cli sendrawtransaction "signed_hex"

• Follow Muun’s published recovery specs
• Test with small amounts first
• Verify against official tool’s output

​

Special Recovery Cases

​

Submarine Swap Recovery

// From submarineSwapV2.go:26
func (c *coinSubmarineSwapV2) SignInput(index int, tx *wire.MsgTx,
    userKey *HDPrivateKey, _ *HDPublicKey) error {
    
    if len(c.ServerSignature) == 0 {
        return errors.New("swap server must provide signature")
    }
    // ...
}

• If before timeout: Cannot complete without server
• If after timeout: Can reclaim to refund address (v1) or multisig (v2)
• Wait for timeout, then sweep

• If you have the preimage: Can claim the HTLC
• If you don’t have preimage: Server will refund after timeout
• Check Emergency Kit metadata for invoice data

​

Incoming Swap Recovery

// From incoming_swap.go:238
if len(c.Preimage) > 0 {
    // Houston can provide preimage for collaborative recovery
    secrets = &walletdb.Invoice{
        Preimage: c.Preimage,
        KeyPath:  invoiceBaseKeyPath,
    }
}

• Emergency Kit may contain invoice metadata
• If previously revealed, preimage may be recoverable
• Otherwise, server can refund after timeout

​

Multi-Signature Coordination

// From V2.go:53
// This is a standard 2 of 2 multisig script
// 0 because of a bug in bitcoind
// Then the 2 sigs: first the users and then muuns
// Last, the script that contains the two pub keys and OP_CHECKMULTISIG
builder := txscript.NewScriptBuilder()
builder.AddInt64(0)
builder.AddData(sig)
builder.AddData(c.MuunSignature)
builder.AddData(redeemScript)

• Normal operation: User signs, Muun’s server signs
• Emergency: User signs with both (has both keys from Emergency Kit)
• Fully self-sovereign: No dependency on Muun

​

Testing Your Recovery

​

Dry Run Recovery Test

1. Small test wallet: Create a wallet with a small amount
2. Export Emergency Kit: Generate and save the PDF
3. Write recovery code: Store securely
4. Uninstall app: Remove from device
5. Recover: Use recovery code to restore
6. Verify: Confirm balance appears
7. Keep testing wallet: Use it to practice emergency recovery later

​

Emergency Kit Verification

1. Check PDF readability: Ensure it’s not corrupted
2. Verify verification code: Match PDF to app
3. Test recovery code: Confirm you can read what you wrote
4. Update if needed: Regenerate if damaged

​

Security Considerations

​

What Can Go Wrong

• ❌ Only digital Emergency Kit → Device failure loses it
• ❌ Recovery code only in memory → Forgotten
• ❌ Emergency Kit + recovery code together → Theft = total loss
• ❌ Never tested recovery → Broken process discovered too late

• ✅ Multiple Emergency Kit copies (different locations)
• ✅ Multiple recovery code copies (different locations)
• ✅ Separate storage (never together)
• ✅ Regular testing (know it works)

​

Privacy During Recovery

• All your addresses to the recovery tool
• Your transaction history
• Your balance

• Run your own Bitcoin node for scanning
• Use recovery tools locally (not web-based)
• Sweep to a fresh wallet (don’t reuse addresses)

​

Recovery Code vs. Seed Phrase

• Allows protocol upgrades
• Supports collaborative custody
• Enables Emergency Kit encryption
• Maintains compatibility with future features

​

Related Features