Complete Cold Wallet Transaction Guide
🔒 Cold Wallet Overview
A cold wallet keeps your private keys on an permanently offline (air-gapped) computer. You prepare transactions online using watch-only mode, sign them offline, then broadcast online.
Key Components:
- Online Computer: Uses watch-only mode (public address only, no private keys)
- Offline Computer: Holds private keys, never connects to internet
- USB Drive: Transfers data between computers (JSON files only, never private keys)
Initial Setup
- 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, choose "Create a new wallet"
- Press "Backup" to save the wallet (with password protection)
- Write down the wallet address (alpha1...)
- Setup Online Computer:
- Open wallet in browser
- DO NOT create or load any wallet
- Once connected to a node, enter your cold wallet address in the field under "Watch an address" on the start screen
- This enables watch-only mode for monitoring
Understanding Watch-Only Mode
🔍 What is Watch-Only Mode?
Watch-only mode allows you to monitor any wallet address WITHOUT having its private key. This is the foundation of cold wallet security - you can prepare transactions on an online computer without ever exposing your private keys to the internet.
Key Features:
- Monitor balance and transaction history
- View all available UTXOs
- Create unsigned transaction templates
- Export data for offline signing
- No risk - private keys never touch online computer
How to Enable Watch-Only Mode:
- Leave any loaded wallet: If a wallet card is showing, press "Add wallet" above it to get back to the start screen. Your saved wallets stay in this browser.
- Locate Watch field: The address field under "Watch an address" appears on the start screen when no wallet is loaded and a node is connected
- Enter address: Type or paste your cold wallet's address (alpha1...)
- Automatic loading: Balance, UTXOs, and history load immediately
- Ready for transactions: You can now create unsigned transactions
PATH 1: Transaction Template Method (Recommended)
Create transaction template online → Sign offline → Broadcast online
Step-by-Step Instructions
- ONLINE: Create Watch-Only Session
- Open wallet in browser (do NOT load any wallet)
- Find the field under "Watch an address" on the start screen
- Enter your cold wallet address (alpha1...)
- Wait for balance and UTXOs to load
- Verify the displayed balance is correct
- ONLINE: Create Transaction Template
- Press "Send"
- In the "To" field: enter recipient address
- Enter amount to send
- Optional: Click "Max" for entire balance
- Press "Export for offline signing"
- The unsigned template downloads as alpha_tx_template_[amount]ALPHA_[time].json
- Save it to the USB drive
- Safely eject USB drive
- OFFLINE: Import and Sign Transaction
- Insert USB into offline computer
- Open wallet HTML file
- Choose "Open a backup file" and select your wallet file
- Enter password if encrypted
- Open the "Cold wallet tools" tab and press "Import UTXO data"
- Select the alpha_tx_template_….json file
- The review dialog opens with the transaction details
- VERIFY: recipient address matches exactly
- VERIFY: amount is correct
- Press "Confirm & Sign"
- With no node connection, the signed file downloads as alpha-transactions-[time].json
- Save it to the USB drive
- Safely eject USB drive
- ONLINE: Broadcast Signed Transaction
- Insert USB into online computer
- In wallet, stay on "Wallet" tab
- Press "Broadcast" in the tool bar (next to Cold tools and All wallets)
- Select the alpha-transactions-….json file from USB
- Transaction appears in broadcast queue
- Status changes: Pending → Broadcasting → Complete
- Transaction ID appears when complete
- Funds are now sent!
PATH 2: UTXO Export Method (Alternative)
Export UTXOs online → Create & sign offline → Broadcast online
Step-by-Step Instructions
- ONLINE: Export UTXOs
- Open wallet in browser (do NOT load any wallet)
- Enter cold wallet address in the field under "Watch an address"
- Wait for balance and UTXOs to load
- Click on "Cold wallet tools" tab (top of page)
- Verify UTXOs are displayed in the list
- Press "Export UTXO data"
- The file downloads as utxo_[address]_[block]_[time].json; save it to the USB drive
- File contains all available UTXOs with amounts
- Safely eject USB drive
- OFFLINE: Import UTXOs and Create Transaction
- Insert USB into offline computer
- Open wallet HTML file
- Choose "Open a backup file" and select your wallet file
- Enter password if encrypted
- Click on "Cold wallet tools" tab
- Press "Import UTXO data"
- Select the utxo_….json file from USB
- UTXOs appear in the list below
- Click back to "Wallet" tab and press "Send"
- In "To": enter recipient address
- Enter amount to send
- Fee is calculated automatically
- Optional: Click "Max" for entire balance minus fee
- OFFLINE: Sign and Export Transaction
- VERIFY: recipient address is correct
- VERIFY: amount and fee are acceptable
- Press "Review"
- Review confirmation dialog carefully
- Press "Confirm & Sign"
- With no node connection, the signed file downloads as alpha-transactions-[time].json; save it to the USB drive
- Transaction is signed with your private key
- Safely eject USB drive
- ONLINE: Broadcast Signed Transaction
- Insert USB into online computer
- In wallet, stay on "Wallet" tab
- Press "Broadcast" in the tool bar (next to Cold tools and All wallets)
- Select the alpha-transactions-….json file from USB
- Transaction appears in broadcast queue
- Status changes: Pending → Broadcasting → Complete
- Transaction ID appears when complete
- Funds are now sent!
Important Notes & Tips
⚠️ Critical Points:
- File Naming: The downloaded names already carry a timestamp; keep the unsigned template and the signed file apart on the USB drive
- Double Check: ALWAYS verify recipient address character-by-character on offline computer
- USB Safety: Use a dedicated USB only for wallet operations, never for general use
- Watch-Only Field: Only appears when NO wallet is loaded and a node is connected
- Transaction Template: Contains UTXOs and transaction details but NO signature
- Signed Transaction: Contains complete transaction ready for broadcast
Troubleshooting
- Watch field not visible? Connect to a node, and press "Add wallet" above the card if a wallet is loaded
- UTXOs not showing? Ensure you're connected (green connection status)
- Can't import transaction? On the offline computer, import an unsigned template with "Import UTXO data" in Cold wallet tools, not with "Broadcast" or "Open a backup file"
- 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)
⚠️ Important Reminders:
- Receiving funds only requires sharing your public address - this is always safe
- The private key should ONLY exist on the offline computer
- Cold wallets require more effort but provide maximum security for large holdings
- Always verify transaction details on the offline computer before signing
🐛 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
- Debug Button: Look for the gray "🐛 Debug" button in the bottom-right corner of the wallet interface
- Click to Open: Click the button to open the Debug Modal with all your transaction history and logs
- Automatic Tracking: The system automatically logs all transaction attempts, including successes and failures
Debug Modal Features
The Debug Modal has 4 tabs:
- Summary: Overview of the current debug session with statistics
- Logs: Detailed chronological log of all operations
- Errors: Filtered view showing only errors and warnings
- History: List of all recent transaction debug sessions
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)
- Open Debug Modal: Click the "🐛 Debug" button
- Click Submit Report: Press the blue "📤 Submit Report" button
- Automatic Processing: The report is sent to the debug service at https://unicity-debug-report.dyndns.org:3487
- Get Report ID: You'll receive a unique Report ID for tracking
- Optional Cleanup: Choose whether to clear local debug logs after submission
Option 2: Manual Export
- Open Debug Modal: Click the "🐛 Debug" button
- Click Export: Press the "Export Debug Log" button
- Save File: A JSON file will download with all debug data
- Share Manually: Send the file to developers via email or issue tracker
Failed Transaction Recovery
🔄 Retry Failed Transactions:
- Click "Show Failed TXs" in the Debug Modal
- Review the list of failed transactions with their error messages
- Click "Export for Retry" to save failed transactions
- Use "Broadcast" in the wallet's tool bar to retry
Privacy & Security
✅ Your Privacy is Protected:
- No Private Keys: Private keys are NEVER included in debug reports
- Automatic Sanitization: All sensitive fields are automatically removed
- Safe Transaction Data: Transaction IDs and hex are preserved (public once broadcast)
- Local Storage: Debug data is stored locally until you choose to share it
- You Control Sharing: Nothing is sent without your explicit action
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
⚠️ Important Notes:
- Debug logs are limited to 100 sessions to prevent storage overflow
- Logs persist across browser sessions until manually cleared
- If automatic submission fails, the system will fallback to manual download
- For sensitive issues, you can review the debug export before sharing