Balance Worker Queue Injection Test

Injects test jobs directly into the Redis queue that the LIVE running worker (from make start) is processing.

Purpose

Isolate and debug the balance worker to understand:

• How xpubs are processed
• How tokens array is populated (derived addresses)
• How receive vs change addresses are filtered
• Why addresses might not be appearing in integration tests

What This Tests

UTXO Chains (BTC, LTC, DOGE, BCH, DASH, DGB)

• Input: Xpub/Ypub/Zpub
• Process: Calls Blockbook getPubkeyInfo() to get derived addresses
• Expected Output: tokens[] array with addresses and paths
• Validation:
  • Check token count >= gap limit (20)
  • Verify receive addresses (/0/N) vs change addresses (/1/N)
  • Confirm address derivation paths

Account-Based Chains (ETH, COSMOS, XRP)

• Input: Single address
• Process: Calls chain-specific balance endpoint
• Expected Output: Balance for single address
• Validation: Balance returned successfully

Fixtures

Uses hardcoded real xpubs from KeepKey integration test wallet:

• BTC: legacy (xpub), segwit (ypub), native segwit (zpub)
• LTC: legacy (xpub), native segwit (zpub)
• DOGE, BCH, DASH, DGB: legacy (xpub)
• ETH, COSMOS, XRP: single addresses

Prerequisites

CRITICAL: Pioneer server must be running!

# Terminal 1: Start pioneer-server with worker
cd /Users/highlander/WebstormProjects/keepkey-stack/projects/pioneer
make start

# Verify worker is running
tail -f logs/server.log | grep -i "sync worker\|sync job"

Usage

# Terminal 2: Run queue injection test
cd e2e/workers/test-balance-worker
bun run dev

# The test will:
# 1. Connect to Redis
# 2. Inject job with hardcoded xpubs
# 3. Watch the LIVE worker process it
# 4. Check Redis for derived addresses

Expected Output

Success Case (tokens[] populated):

🔗 Testing BTC:
  📍 LEGACY (xpub):
     ✅ Response received:
        Balance: 0 satoshis
        Tokens: 20 addresses

        🎯 First 5 derived addresses:
           [1] bc1qxy2kgdygjrsqtzq2n0yrf2493p83kkfjhx0wlh
               Path: m/84'/0'/0'/0/0
               Balance: 0 satoshis

        📊 Address breakdown:
           Receive addresses (/0/N): 10
           Change addresses (/1/N): 10
           Total: 20
        ✅ Gap limit reached

Failure Case (no tokens[]):

🔗 Testing BTC:
  📍 LEGACY (xpub):
     ✅ Response received:
        Balance: 0 satoshis
        Tokens: 0 addresses
        ⚠️  NO TOKENS ARRAY - This is the problem!
        📝 Full response structure: {...}

Debugging

If tokens array is empty, check:

1. Blockbook API: Is getPubkeyInfo() returning data?
2. Response parsing: Is the response structure correct?
3. Token filtering: Are tokens being filtered out?
4. Network module: Is utxo-network module initialized?

Integration with Server

Once this test passes, addresses from tokens[] should:

1. Be stored in Redis: user:{username}:addresses:{networkId}
2. Be published to watchtower via user_connect event
3. Be subscribed to Blockbook WebSocket by watchtower
4. Receive transaction events when payments arrive

Next Steps

If this test reveals issues:

• Add logging to utxo-network module
• Check Blockbook API responses
• Verify token parsing logic
• Test with different xpub types