Unicity WEB GUI Wallet v0.5.0

Interface Overview

• Main Page Tabs:
  • Wallet Tab: Main wallet operations (Create, Load, Save, Reset, Send, Broadcast)
  • Cold Wallet Tools Tab: UTXO management for offline transactions (Export/Import UTXOs)
• Help Tabs: This help window has two tabs - General Usage (this tab) and Cold Wallet (detailed cold wallet instructions)

Getting Started

• Create New Wallet: Click the "Create" button to generate a new wallet with a secure private key
• Load Existing Wallet: Click the "Load" button to import from:
  • Text Files (.txt): Import wallets from WIF private keys or previously saved BIP32 keys
  • BIP32 Wallet Database (.dat): Import BIP32 hierarchical deterministic wallets from wallet.dat files
  • Encrypted Backup: Restore from password-protected wallet backups (click "Decrypt" button after selecting file)
• Wallet Scanning (BIP32):
  • When opening a BIP32 wallet file, the wallet automatically scans for addresses with balances
  • The scanner will check up to 100 addresses (configurable) for funds
  • Found addresses are displayed with their balances and derivation paths
  • Select any discovered wallet to use for transactions
  • After initial scan, a "Rescan Wallets" button appears to force a fresh scan and clear cache
• Network Connection: The wallet automatically connects to the Unicity network when online. You can also manually connect/disconnect using the endpoint controls

Importing Wallets

• Standard Backup Import: Use the "Load" button to import wallet files. If the backup is encrypted, you'll need to enter the password.
• BIP32 wallet.dat Import (EXPERIMENTAL):
  ⚠️ Important Notes:

  • Only unencrypted wallet.dat files are currently supported
  • No backup copy of wallet.dat is needed - the file is only read, not modified
  • Verify imported addresses: We cannot guarantee correct address restoration. Always compare with alpha-qt or alpha-cli to ensure the right addresses were loaded
  • The scanner checks 100 regular addresses and 100 change addresses by default
  • You can select any non-empty address found during the scan
  • To decrypt wallet.dat: use alpha-cli walletpassphrase "yourpassword" 600 then copy the wallet.dat

Exporting from Alpha Core (alpha-cli/alpha-qt)

• Method 1: Direct wallet.dat Copy (Recommended for BIP32 wallets):
  1. Stop alpha-qt or alpha daemon: alpha-cli stop
  2. Locate your wallet.dat file (usually in ~/.alpha/ or datadir)
  3. If wallet is encrypted, temporarily decrypt it:
     • Start alpha daemon/qt again
     • Run: alpha-cli walletpassphrase "yourpassword" 600
     • Stop the daemon and copy wallet.dat while it's decrypted
  4. Copy the wallet.dat file to a safe location
  5. Use the "Load" button in this wallet to import the wallet.dat file
• Method 2: Export with dumpwallet (Alternative):
  1. If wallet is encrypted, unlock it: alpha-cli walletpassphrase "yourpassword" 600
  2. Export wallet keys: alpha-cli dumpwallet "wallet_export.txt"
  3. The exported file contains all private keys in WIF format
  4. You can import individual WIF keys using the "Load" button
  5. Lock wallet after export: alpha-cli walletlock
• Method 3: Backup wallet (For safekeeping):
  1. Create a backup: alpha-cli backupwallet "wallet_backup.dat"
  2. This creates a copy of your wallet.dat that can be imported the same way

Security

• Save Your Wallet: Click the "Save" button to export your wallet with optional password protection. Write down the password - there's no recovery if forgotten!
• Backup Regularly: Use the "Save" button to create wallet backups. Store backups in multiple secure locations
• Offline Mode: For maximum security, download this page and use it on an offline computer

Receiving Funds

• Your address is displayed in the wallet section
• Click the QR code icon to show a scannable code
• Share your address or QR code with the sender
• When connected, balance updates automatically

Sending Funds

• Online Mode: Enter recipient address and amount, review fees, then click Send and broadcast directly
• Offline Mode (Cold Wallet) - Two Options:
  Option A: Prepare Transaction Online (Recommended)

  1. On online computer: Enter watch-only address, create transaction, export template
  2. Transfer template to offline computer via USB
  3. On offline computer: Import template, sign transaction, export signed file
  4. Back online: Click Broadcast button to send to network
  Option B: Prepare Transaction Offline

  1. On online computer: Go to Cold Wallet Tools tab, export UTXOs
  2. Transfer UTXO file to offline computer
  3. On offline computer: Import UTXOs, create and sign transaction
  4. Back online: Click Broadcast button to send

  📘 Full Details: See the Cold Wallet tab in this help window for comprehensive step-by-step instructions, security setup, and best practices for cold wallet operations.

Transaction Broadcast Queue

• Automatic Queue Management: All transactions are added to a broadcast queue for reliable delivery
• Rate Limiting: Up to 30 transactions can be broadcast per block to prevent network congestion
• Queue Features:
  • Visual Progress: See pending, broadcasting, complete, failed, and cancelled transactions
  • Persistence: Queue survives page refreshes and connection drops
  • Automatic Retry: Failed transactions retry up to 3 times
  • UTXO Protection: Prevents double-spending by tracking consumed UTXOs
• Queue Actions:
  • Click transaction counts to see detailed information
  • Export failed/cancelled transactions for troubleshooting
  • Cancel pending transactions if needed
  • Resend, save, or delete individual cancelled transactions
  • Clear completed transactions manually or wait for auto-cleanup after 24 hours
• Broadcast Button: Located in the wallet actions bar (with Create, Load, Save, Reset). Click to import and broadcast signed transaction files
• Max Available Button: Quickly calculate the maximum sendable amount accounting for fees

Additional Features

• Reset Wallet: Click the "Reset" button to clear the current wallet data and start fresh

Complete Cold Wallet Transaction Guide

Initial Setup

1. Prepare Offline Computer:
   • Use a computer that will NEVER connect to internet
   • Download wallet HTML file on online computer
   • Transfer HTML file via USB to offline computer
   • Open wallet, click "Create" to generate new wallet
   • Click "Save" to backup wallet (with password protection)
   • Write down the wallet address (alpha1...)
2. Setup Online Computer:
   • Open wallet in browser
   • DO NOT create or load any wallet
   • Enter your cold wallet address in "Watch:" field
   • This enables watch-only mode for monitoring

Understanding Watch-Only Mode

How to Enable Watch-Only Mode:

1. Clear any loaded wallet: If you see wallet buttons, click "Reset" first
2. Locate Watch field: The "Watch:" input appears in wallet section when no wallet is loaded
3. Enter address: Type or paste your cold wallet's address (alpha1...)
4. Automatic loading: Balance, UTXOs, and history load immediately
5. Ready for transactions: You can now create unsigned transactions

PATH 1: Transaction Template Method (Recommended)

Create transaction template online → Sign offline → Broadcast online

PATH 2: UTXO Export Method (Alternative)

Export UTXOs online → Create & sign offline → Broadcast online

Important Notes & Tips

Troubleshooting

• Watch field not visible? Click "Reset" to clear any loaded wallet first
• UTXOs not showing? Ensure you're connected (green connection status)
• Can't import transaction? Use "Load" button, not "Broadcast" for unsigned files
• Broadcast fails? Check connection status and transaction queue for errors
• Wrong balance? Click "Rescan Wallets" if using BIP32 wallet

Security Best Practices

• Air Gap: Offline computer must NEVER connect to internet, even temporarily
• USB Hygiene:
  • Use dedicated USB for wallet operations only
  • Format USB between uses if possible
  • Never plug wallet USB into untrusted computers
• Verification: Always verify on offline computer:
  • Recipient address (every character)
  • Amount being sent
  • Fee is reasonable (usually 0.0001-0.001 ALPHA)
• Backups: Keep multiple encrypted backups of wallet in different physical locations
• Practice: Test entire process with tiny amounts first (0.001 ALPHA)

🐛 Debug & Bug Reporting System

The wallet includes a comprehensive debug system that automatically tracks all transaction operations to help developers diagnose and fix issues. All debug data is stored locally and you control what gets shared.

How to Access Debug Features

1. Debug Button: Look for the gray "🐛 Debug" button in the bottom-right corner of the wallet interface
2. Click to Open: Click the button to open the Debug Modal with all your transaction history and logs
3. Automatic Tracking: The system automatically logs all transaction attempts, including successes and failures

Debug Modal Features

What Gets Logged

• Transaction Preparation: Address validation, UTXO selection, fee calculation
• Transaction Signing: Key derivation, signature creation, witness data
• Broadcasting: Network submission, server responses, confirmations
• Errors: Detailed error messages, stack traces, and context
• Transaction Hex: Complete signed transaction data for debugging

How to Report a Bug

Option 1: Automatic Submission (Recommended)

1. Open Debug Modal: Click the "🐛 Debug" button
2. Click Submit Report: Press the blue "📤 Submit Report" button
3. Automatic Processing: The report is sent to the debug service at https://unicity-debug-report.dyndns.org:3487
4. Get Report ID: You'll receive a unique Report ID for tracking
5. Optional Cleanup: Choose whether to clear local debug logs after submission

Option 2: Manual Export

1. Open Debug Modal: Click the "🐛 Debug" button
2. Click Export: Press the green "Export Debug Log" button
3. Save File: A JSON file will download with all debug data
4. Share Manually: Send the file to developers via email or issue tracker

Failed Transaction Recovery

Privacy & Security

Debug Service Web Interface

Developers can view submitted reports at: https://unicity-debug-report.dyndns.org:3487

• Browse Reports: See all submitted debug reports with search and filtering
• Analyze Issues: View detailed logs, errors, and transaction data
• Extract Transactions: Export transaction hex for testing and analysis
• Track Patterns: Identify common issues across multiple reports

Common Issues to Report

• Transaction Failures: "Transaction failed to broadcast" or "Invalid transaction" errors
• Balance Issues: Incorrect balance display or UTXO problems
• Signing Errors: "Failed to sign transaction" or key-related errors
• Network Problems: Connection issues with Fulcrum/Electrum servers
• Import/Export Issues: Problems with wallet.dat import or UTXO import
• UI Problems: Buttons not working, displays not updating

Tips for Better Bug Reports

• Reproduce First: Try to reproduce the issue before reporting
• Clear Steps: Note the exact steps that led to the problem
• Check Console: Open browser console (F12) for additional error messages
• Include Context: Mention if you're using cold wallet, BIP32, or watch-only mode
• Submit Promptly: Submit debug reports soon after issues occur for complete logs