Emergency Kit for Recovery

Overview

The Emergency Kit is Muun Wallet’s comprehensive backup solution. It’s a PDF document containing all the information needed to recover your Bitcoin funds, even if Muun’s servers are permanently offline.

The Emergency Kit ensures true self-custody: you always maintain the ability to recover your funds independently, without Muun’s cooperation.

What’s in the Emergency Kit?

The Emergency Kit contains:

Two encrypted private keys:
- Your user key (encrypted)
- Muun’s key (encrypted)
Key fingerprints: For verification and derivation
Output descriptors: Scripts for generating all address types
Recovery code checksum: Validates your recovery code
Verification code: Ensures PDF integrity
Metadata: Birthday block, version info, technical details

The Emergency Kit PDF must be kept secure. Anyone with both the PDF and your recovery code can steal all your Bitcoin.

Emergency Kit Versions

Muun has evolved the Emergency Kit format over time:

// From emergency_kit.go:10
const (
    EKVersionNeverExported = -1
    // EKVersionOnlyKeys is the encrypted keys to be written down / emailed
    EKVersionOnlyKeys = 1
    // EKVersionDescriptors is the first PDF including the descriptors
    EKVersionDescriptors = 2
    // EKVersionMusig add the musig descriptors
    EKVersionMusig   = 3
    ekVersionCurrent = EKVersionMusig
)

Version History:

Version	Features	Use Case
-1	Never exported	Wallet has no backup yet
1	Keys only	Manual entry, early wallets
2	Keys + Descriptors	PDF with standard scripts
3	Keys + Descriptors + MuSig	Current version with Taproot support

Source: libwallet/emergency_kit.go:10-19

Generation Process

Step 1: Prepare Input Data

// From emergency_kit.go:21
type EKInput struct {
    FirstEncryptedKey  string  // User's encrypted key
    FirstFingerprint   string  // User key fingerprint
    SecondEncryptedKey string  // Muun's encrypted key
    SecondFingerprint  string  // Muun key fingerprint
    RcChecksum         string  // Recovery code checksum
}

The input contains:

Both keys encrypted with the recovery code
Fingerprints for key identification
Recovery code checksum for validation

Step 2: Generate HTML

// From emergency_kit.go:43
func GenerateEmergencyKitHTML(ekParams *EKInput, language string) (*EKOutput, error) {
    moduleInput := &emergencykit.Input{
        FirstEncryptedKey:  ekParams.FirstEncryptedKey,
        FirstFingerprint:   ekParams.FirstFingerprint,
        SecondEncryptedKey: ekParams.SecondEncryptedKey,
        SecondFingerprint:  ekParams.SecondFingerprint,
        Version:            ekVersionCurrent,
    }
    
    // Create the HTML and the verification code:
    htmlWithCode, err := emergencykit.GenerateHTML(moduleInput, language)
    if err != nil {
        return nil, fmt.Errorf("GenerateEkHtml failed to render: %w", err)
    }
    
    // Create and serialize the metadata:
    metadata, err := createEmergencyKitMetadata(ekParams)
    if err != nil {
        return nil, fmt.Errorf("GenerateEkHtml failed to create metadata: %w", err)
    }
    
    return &EKOutput{
        HTML:             htmlWithCode.HTML,
        VerificationCode: htmlWithCode.VerificationCode,
        Metadata:         string(metadataBytes),
        Version:          moduleInput.Version,
    }, nil
}

HTML Generation:

Takes encrypted keys and fingerprints
Generates localized HTML for PDF rendering
Creates a verification code for integrity checking
Serializes metadata for embedding

Source: libwallet/emergency_kit.go:43-77

Step 3: Render PDF

The HTML is rendered to PDF using the device’s WebKit/Chromium engine. This happens in the native app code (Android/iOS), not in libwallet.

Step 4: Embed Metadata

// From emergency_kit.go:82
func AddEmergencyKitMetadata(metadataText string, srcFile string, dstFile string) error {
    // Initialize the MetadataWriter:
    metadataWriter := &emergencykit.MetadataWriter{
        SrcFile: srcFile,
        DstFile: dstFile,
    }
    
    // Deserialize the metadata:
    var metadata emergencykit.Metadata
    err := json.Unmarshal([]byte(metadataText), &metadata)
    if err != nil {
        return fmt.Errorf("AddEkMetadata failed to unmarshal: %w", err)
    }
    
    err = metadataWriter.WriteMetadata(&metadata)
    if err != nil {
        return fmt.Errorf("AddEkMetadata failed to write metadata: %w", err)
    }
    
    return nil
}

Metadata Embedding:

Takes the rendered PDF
Embeds machine-readable metadata
Writes to final PDF file
Preserves visual appearance

This allows recovery tools to extract all necessary information programmatically. Source: libwallet/emergency_kit.go:82-103

Metadata Structure

// From emergency_kit.go:105
func createEmergencyKitMetadata(ekParams *EKInput) (*emergencykit.Metadata, error) {
    // Decode both keys to extract inner properties
    firstKey, err := DecodeEncryptedPrivateKey(ekParams.FirstEncryptedKey)
    secondKey, err := DecodeEncryptedPrivateKey(ekParams.SecondEncryptedKey)
    
    // Obtain the list of checksumed output descriptors
    descriptors := emergencykit.GetDescriptors(&emergencykit.DescriptorsData{
        FirstFingerprint:  ekParams.FirstFingerprint,
        SecondFingerprint: ekParams.SecondFingerprint,
    })
    
    // Create the keys for the key array
    keys := []*emergencykit.MetadataKey{
        createEmergencyKitMetadataKey(firstKey),
        createEmergencyKitMetadataKey(secondKey),
    }
    
    metadata := &emergencykit.Metadata{
        Version:           ekVersionCurrent,
        BirthdayBlock:     secondKey.Birthday,
        EncryptedKeys:     keys,
        OutputDescriptors: descriptors,
        RcChecksum:        ekParams.RcChecksum,
    }
    return metadata, nil
}

Metadata Contents:

Version: Emergency Kit format version
Birthday Block: First block to scan during recovery
Encrypted Keys: Both user and Muun keys with encryption details
Output Descriptors: Scripts for all address types (V2-V6, Taproot, etc.)
Recovery Code Checksum: Validates recovery code during recovery

Source: libwallet/emergency_kit.go:105-143

Output Descriptors

Descriptors allow any Bitcoin wallet to derive your addresses:

// From emergency_kit.go:124
descriptors := emergencykit.GetDescriptors(&emergencykit.DescriptorsData{
    FirstFingerprint:  ekParams.FirstFingerprint,
    SecondFingerprint: ekParams.SecondFingerprint,
})

Descriptors include:

P2SH scripts: For v2 addresses
P2WSH scripts: For v3-v4 SegWit addresses
Taproot scripts: For v5-v6 Taproot addresses with MuSig2
Submarine swap scripts: For swap recovery
Incoming swap scripts: For Lightning recovery

This ensures compatibility with:

Bitcoin Core descriptor wallets
Other descriptor-compatible wallets
Custom recovery tools

Encrypted Key Format

// From emergency_kit.go:145
func createEmergencyKitMetadataKey(key *EncryptedPrivateKeyInfo) *emergencykit.MetadataKey {
    return &emergencykit.MetadataKey{
        DhPubKey:         key.EphPublicKey,
        EncryptedPrivKey: key.CipherText,
        Salt:             key.Salt,
    }
}

Each encrypted key contains:

Ephemeral Public Key: For ECDH key derivation
Cipher Text: Encrypted private key + chain code (64 bytes)
Salt: For key derivation function

Encryption scheme:

Recovery code → Scrypt → Challenge private key
Challenge key + Ephemeral public key → ECDH → Encryption key
Encryption key encrypts the master private key

See challenge_keys.go for implementation.

Verification Code

The Emergency Kit includes a verification code:

// From emergency_kit.go:69
output := &EKOutput{
    HTML:             htmlWithCode.HTML,
    VerificationCode: htmlWithCode.VerificationCode,
    Metadata:         string(metadataBytes),
    Version:          moduleInput.Version,
}

Purpose:

Integrity check: Ensures PDF wasn’t corrupted or tampered with
User verification: Displayed in app and on PDF for comparison
Version tracking: Different codes for different kit versions

Before storing your Emergency Kit, verify that the verification code on the PDF matches the one shown in the app.

How to Use the Emergency Kit

Scenario 1: Muun Still Operational

If you lose your phone but Muun’s servers work:

Install Muun on a new device
Choose “Recover wallet”
Enter recovery code from your backup
Wallet restores automatically with server assistance

No Emergency Kit PDF needed in this case.

Scenario 2: Muun Permanently Offline

If Muun’s servers are gone forever:

Obtain Emergency Kit PDF from your backup
Extract encrypted keys from the PDF
Use recovery code to decrypt both keys
Import to recovery tool (Muun provides one, or use Bitcoin Core)
Scan blockchain from birthday block onward
Derive addresses using output descriptors
Create transaction to sweep funds (requires both keys to sign)

This process is technical and requires understanding of Bitcoin wallet recovery. Muun provides detailed documentation and tools for this scenario.

Scenario 3: Partial Emergency

If you can access wallet but want to migrate:

Use Emergency Kit to import keys elsewhere
Sweep funds to a new wallet
Maintains continuity even if you stop trusting Muun

Storage Best Practices

Physical Storage

Do:

Print multiple copies
Store in secure locations (safe, bank deposit box)
Keep separate from recovery code
Use waterproof/fireproof storage
Verify readability periodically

Don’t:

Store only digitally
Keep with your phone
Share or photograph
Store in cloud storage
Rely on a single copy

Digital Storage

If you must store digitally:

Encrypt the PDF with a strong password (separate from recovery code)
Use offline storage (USB drive, not cloud)
Multiple backups in different physical locations
Test recovery process before relying on it

Recovery Code Storage

Critical: Store recovery code separately from Emergency Kit!

Write on paper, never digital
Multiple copies in different locations
Consider splitting across trusted parties
Metal backup for fire/water resistance

Someone with both the Emergency Kit PDF and recovery code can steal all your Bitcoin.

Security Considerations

Threat Model

Protected Against:

Muun company disappearing
Muun servers being hacked
Muun becoming malicious
Loss of your phone
Forgotten passwords

Not Protected Against:

Theft of both Emergency Kit and recovery code
Physical attacks forcing you to reveal recovery code
Malware on the device during PDF generation
Backdoored PDF reader during recovery

Encryption Strength

Keys are encrypted using:

Scrypt: Memory-hard KDF resistant to brute force
ECDH: Elliptic curve Diffie-Hellman for key agreement
Recovery code entropy: 128+ bits of randomness

Brute-forcing the recovery code is computationally infeasible.

PDF Security

The PDF itself:

Not password-protected: Anyone can open it
Contains encrypted keys: Useless without recovery code
Includes metadata: Machine-readable for tools
Human-readable: Shows encrypted keys visually

Implementation Details

Why Two Keys?

The Emergency Kit contains both the user key and Muun’s key because:

2-of-2 multisig: All UTXOs require both signatures
Independent recovery: Don’t need Muun’s cooperation
Full control: Can sweep funds without any server
Trust minimization: Muun can’t prevent your recovery

This is the key to Muun’s “collaborative custody” model.

Birthday Block Optimization

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

The birthday block is the block height when the wallet was created. Recovery tools:

Start scanning here: No need to scan the entire blockchain
Skip empty blocks: Faster recovery
Reduce bandwidth: Only download relevant blocks

Typically reduces recovery time from days to minutes.

Advanced: Manual Decryption

For understanding or custom tools, the decryption process:

// From challenge_keys.go:84
func (k *ChallengePrivateKey) DecryptKey(decodedInfo *EncryptedPrivateKeyInfo, 
    network *Network) (*DecryptedPrivateKey, error) {
    
    decoded, err := unwrapEncryptedPrivateKey(decodedInfo)
    
    // ECDH to derive decryption key
    plaintext, err := decryptWithPrivKey(k.key, decoded.EphPublicKey, 
        decoded.CipherText)
    
    // Split into private key and chain code
    rawPrivKey := plaintext[0:32]
    rawChainCode := plaintext[32:]
    
    // Create HD private key
    privKey, err := NewMasterHDPrivateKeyFromBytes(rawPrivKey, rawChainCode, network)
    
    return &DecryptedPrivateKey{
        privKey,
        int(decoded.Birthday),
    }, nil
}

Steps:

Recovery code → Challenge private key (via Scrypt)
Challenge private key + Ephemeral public key → Shared secret (via ECDH)
Shared secret decrypts cipher text
Plaintext = 32 bytes private key + 32 bytes chain code
Reconstruct BIP32 HD key from these 64 bytes

Source: libwallet/challenge_keys.go:92-115

Recovery

Step-by-step recovery procedures using the Emergency Kit

Recovery Code

Understanding and managing your recovery code

Multisig

Why the Emergency Kit contains both multisig keys

Security Cards

How security cards integrate with emergency recovery

Get Started

Architecture

Core Features

Building & Development

Security

Emergency Kit for Recovery

Overview

What’s in the Emergency Kit?

Emergency Kit Versions

Generation Process

Step 1: Prepare Input Data

Step 2: Generate HTML

Step 3: Render PDF

Step 4: Embed Metadata

Metadata Structure

Output Descriptors

Encrypted Key Format

Verification Code

How to Use the Emergency Kit

Scenario 1: Muun Still Operational

Scenario 2: Muun Permanently Offline

Scenario 3: Partial Emergency

Storage Best Practices

Physical Storage

Digital Storage

Recovery Code Storage

Security Considerations

Threat Model

Encryption Strength

PDF Security

Implementation Details

Why Two Keys?

Birthday Block Optimization

Advanced: Manual Decryption

Recovery

Recovery Code

Multisig

Security Cards

Build docs developers (and LLMs) love

Get Started

Architecture

Core Features

Building & Development

Security

​Overview

​What’s in the Emergency Kit?

​Emergency Kit Versions

​Generation Process

​Step 1: Prepare Input Data

​Step 2: Generate HTML

​Step 3: Render PDF

​Step 4: Embed Metadata

​Metadata Structure

​Output Descriptors

​Encrypted Key Format

​Verification Code

​How to Use the Emergency Kit

​Scenario 1: Muun Still Operational

​Scenario 2: Muun Permanently Offline

​Scenario 3: Partial Emergency

​Storage Best Practices

​Physical Storage

​Digital Storage

​Recovery Code Storage

​Security Considerations

​Threat Model

​Encryption Strength

​PDF Security

​Implementation Details

​Why Two Keys?

​Birthday Block Optimization

​Advanced: Manual Decryption

​Related Features

Recovery

Recovery Code

Multisig

Security Cards

Build docs developers (and LLMs) love

Overview

What’s in the Emergency Kit?

Emergency Kit Versions

Generation Process

Step 1: Prepare Input Data

Step 2: Generate HTML

Step 3: Render PDF

Step 4: Embed Metadata

Metadata Structure

Output Descriptors

Encrypted Key Format

Verification Code

How to Use the Emergency Kit

Scenario 1: Muun Still Operational

Scenario 2: Muun Permanently Offline

Scenario 3: Partial Emergency

Storage Best Practices

Physical Storage

Digital Storage

Recovery Code Storage

Security Considerations

Threat Model

Encryption Strength

PDF Security

Implementation Details

Why Two Keys?

Birthday Block Optimization

Advanced: Manual Decryption

Related Features