npm package: @pioneer-platform/test-balance-worker
Description: Direct balance worker testing - bypass API and test worker queue directly
Latest version: 1.0.6

# 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!

```bash
# 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

```bash
# 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