mines/rin/wallet/cmd/WALLET_RESTORATION_REALITY.md

RinCoin Wallet Restoration: What Actually Works

❌ The Problem: RinCoin Doesn't Support xprv Key Imports

After extensive testing, we've discovered that RinCoin does NOT support direct xprv extended private key imports.

What We Tried (All Failed):

• ✗ sethdseed with xprv key → "Invalid private key"
• ✗ importprivkey with xprv key → "Invalid private key encoding"
• ✗ Direct HD seed restoration → Not supported

Why This Doesn't Work:

RinCoin, despite being based on Litecoin, appears to have limited RPC support for:

• BIP39 mnemonic seed phrases
• Extended private key (xprv) imports
• HD wallet seed restoration via RPC

✅ What DOES Work: Full Wallet Dump Restoration

The ONLY reliable method is using the complete wallet dump file:

./restore_wallet.sh /home/db/rin_wallet_backups/rin_wallet_backup_20250929_221522.txt restored_wallet

Why This Works:

• Uses importwallet RPC method (widely supported)
• Imports ALL individual private keys from the dump
• Blockchain rescans and finds all transactions
• Balance is restored: 1059.00155276 RIN ✓

The Address Issue:

The restored wallet shows different addresses but same balance:

• Original: rin1q... (SegWit addresses)
• Restored: R... (Legacy P2PKH addresses)

Why? The wallet dump contains individual private keys without HD structure, so importwallet creates a legacy wallet.

🎯 Practical Solutions for User-Friendly Wallets

Since direct key import doesn't work, here are realistic approaches:

Option 1: Wallet File Backup/Restore (BEST)

For same device or direct file transfer:

# Backup
tar -czf ~/rin_wallet_backup.tar.gz /mnt/data/docker_vol/rincoin/rincoin-node/data/main/

# Restore
tar -xzf ~/rin_wallet_backup.tar.gz -C /new/path/data/

Pros:

• ✅ Perfect restoration - same addresses, same structure
• ✅ Fast - no blockchain rescan needed
• ✅ Works 100% reliably

Cons:

• ✗ Requires file transfer (not just a text string)
• ✗ User must handle binary wallet files

Option 2: Full Dump File Restoration (CURRENT)

For text-based backup:

# Backup
./dump_wallet.sh  # Creates text file with all keys

# Restore
./restore_wallet.sh /path/to/backup.txt restored_wallet

Pros:

• ✅ Text file - easier to store/transfer
• ✅ Works reliably
• ✅ Balance fully restored

Cons:

• ✗ Changes address format (rin1q... → R...)
• ✗ Large file (~6000 lines for active wallet)
• ✗ Slower (requires blockchain rescan)

Option 3: Web Wallet with Server-Side Management (RECOMMENDED)

For browser extension/web wallet:

Instead of user managing keys directly, implement server-side wallet management:

// User creates wallet
const walletId = await createWallet(username, password);
// Server stores encrypted wallet file

// User restores wallet
const wallet = await restoreWallet(username, password);
// Server loads encrypted wallet file

Pros:

• ✅ User-friendly - just username/password
• ✅ No key management complexity
• ✅ Perfect restoration every time
• ✅ Can sync across devices

Cons:

• ✗ Requires trust in server
• ✗ Need secure server infrastructure

Option 4: Hybrid Approach (BALANCED)

Combine wallet file + optional manual backup:

// Primary: Encrypted wallet file stored locally/cloud
saveEncryptedWallet(walletFile, userPassword);

// Secondary: Export full dump for disaster recovery
exportFullDump();  // User downloads text file "just in case"

Pros:

• ✅ User-friendly primary method (file sync)
• ✅ Manual backup option for advanced users
• ✅ Best of both worlds

🔧 Technical Implementation for Web Wallet

Current Reality Check:

// ❌ This WON'T work (RinCoin doesn't support it):
async function restoreFromMnemonic(mnemonic) {
  await rpc('sethdseed', [true, mnemonic]);  // FAILS
}

// ❌ This WON'T work either:
async function restoreFromXprv(xprv) {
  await rpc('importprivkey', [xprv]);  // FAILS
}

// ✅ This DOES work:
async function restoreFromDumpFile(dumpFilePath) {
  await rpc('createwallet', [walletName, false, false]);
  await rpc('importwallet', [dumpFilePath]);  // WORKS!
}

Recommended Web Wallet Architecture:

class RinWebWallet {
  // Primary method: Wallet file management
  async backupWallet() {
    // Get wallet directory from node
    const walletDir = await getWalletDirectory();
    // Create encrypted archive
    const encrypted = await encryptWalletFiles(walletDir, userPassword);
    // Store locally/cloud
    await saveBackup(encrypted);
  }

  async restoreWallet(encryptedBackup, password) {
    // Decrypt backup
    const walletFiles = await decrypt(encryptedBackup, password);
    // Restore to node's wallet directory
    await restoreWalletFiles(walletFiles);
    // Load wallet
    await rpc('loadwallet', [walletName]);
  }

  // Secondary method: Dump file for advanced users
  async exportDumpFile() {
    const dumpFile = await rpc('dumpwallet', ['/tmp/backup.txt']);
    return downloadFile(dumpFile);
  }

  async importDumpFile(dumpFilePath) {
    await rpc('createwallet', [walletName]);
    await rpc('importwallet', [dumpFilePath]);
    // Note: Addresses will be different format but balance same
  }
}

📱 User Experience Design

For Browser Extension:

┌─────────────────────────────┐
│     RinCoin Wallet         │
├─────────────────────────────┤
│                             │
│  [Create New Wallet]        │
│                             │
│  [Restore from Backup]      │
│    ↓                        │
│    • Upload wallet file     │  ← Primary method
│    • Import dump file       │  ← Fallback method
│                             │
└─────────────────────────────┘

Backup Flow:

1. User clicks "Backup Wallet"
2. Extension prompts for password
3. Creates encrypted wallet file
4. Downloads: "rincoin-wallet-backup-2025-09-29.enc"
5. Shows: "✓ Backup created! Store this file safely."

Restore Flow:

1. User clicks "Restore Wallet"
2. User uploads "rincoin-wallet-backup-2025-09-29.enc"
3. Extension prompts for backup password
4. Restores wallet files to node
5. Shows: "✓ Wallet restored! Balance: 1059.00 RIN"

🎯 Recommendations

For MVP (Minimum Viable Product):

1. Use wallet file backup/restore - Most reliable
2. Encrypt with user password - Security
3. Store locally in browser storage - Simple start
4. Add cloud sync later - Future enhancement

For Production:

1. Primary: Encrypted wallet file sync
2. Secondary: Optional dump file export
3. Security: End-to-end encryption
4. UX: Hide complexity from users

⚠️ Important Disclaimers

For Users:

• The xprv key in your dump file cannot be used for quick restoration
• You must use the full dump file or wallet directory
• Different restoration methods may show different addresses (but same balance)

For Developers:

• RinCoin's RPC API has limited HD wallet support
• Extended key imports (xprv/xpub) are not supported
• BIP39 mnemonic restoration is not available via RPC
• The only reliable method is importwallet with full dump

🚀 Moving Forward

For a user-friendly RinCoin wallet/browser extension, don't try to mimic MetaMask's 12-word restore. Instead:

1. Accept the limitation: RinCoin doesn't support simple key restoration
2. Design around it: Use wallet file backups
3. Make it simple: Hide the complexity with good UX
4. Be honest: Tell users they need to backup their wallet file

The technology constraint is real, but good UX design can still make it user-friendly! 🎨