Integration Report - Bitcoin Server-Side Reports

Server-side Bitcoin report generation with LOD (Level of Detail) support.

Quick Start

1. Start Pioneer Server

cd /Users/highlander/WebstormProjects/keepkey-stack/projects/pioneer/services/pioneer-server
make start

2. Build and Run Reports

cd /Users/highlander/WebstormProjects/keepkey-stack/projects/pioneer/e2e/reports/intergration-report

# Build
pnpm run build

# Generate reports at different LOD levels
pnpm run server-report:lod0  # Portfolio overview
pnpm run server-report:lod1  # XPUB summary
pnpm run server-report:lod2  # Account details (default)
pnpm run server-report:lod3  # Address level
pnpm run server-report:lod4  # Transaction IDs
pnpm run server-report:lod5  # Full details with LLM

# Or with custom LOD and account count
node dist/server-side-report-example.js 3 1  # LOD 3, 1 account

Reports Output

Reports are saved to ./reports/ directory:

• bitcoin_report_lod0_YYYY-MM-DD.json
• bitcoin_report_lod1_YYYY-MM-DD.json
• etc.

LOD Levels

| LOD | Description | Size | Time | Use Case | |-----|-------------|------|------|----------| | 0 | Portfolio overview | ~200B | 500ms | Dashboard widget | | 1 | XPUB summary | ~1KB | 1s | Multi-account view | | 2 | Account details | ~2KB | 1.5s | Account analysis | | 3 | Address level | ~50KB | 3s | Address auditing | | 4 | Transaction IDs | ~500KB | 10s | Tax reporting | | 5 | Full details + LLM | ~2MB | 30s | User-facing history |

Configuration

Enable LLM (Optional)

Edit /projects/pioneer/services/pioneer-server/.env:

# Use mock LLM (default, no API calls)
ENABLE_LLM=true
LLM_PROVIDER=mock

# Or use OpenAI (requires API key)
ENABLE_LLM=true
LLM_PROVIDER=openai
OPENAI_API_KEY=sk-...

Architecture

Client (integration-report)
    ↓
    1. Get XPUBs from KeepKey (Pioneer SDK)
    ↓
    2. POST to http://localhost:9001/api/v1/reports/bitcoin
    ↓
Pioneer Server
    ↓
    3. Bitcoin Report Service (LOD processors)
    ↓
    4. UTXO Network Module (Blockbook API)
    ↓
    5. LLM Service (optional, LOD 5 only)
    ↓
    6. Return structured JSON
    ↓
Client
    ↓
    7. Save JSON to ./reports/
    ↓
    8. (Optional) Generate PDF from JSON

Example Output

LOD 0 Response

{
  "lod": 0,
  "totalBalanceBTC": 0.12345678,
  "totalBalanceUSD": 8024.69,
  "totalXpubs": 9,
  "lastUpdated": "2025-01-17T10:30:00.000Z"
}

LOD 2 Response

{
  "lod": 2,
  "totalBalanceBTC": 0.12345678,
  "totalBalanceUSD": 8024.69,
  "totalXpubs": 9,
  "lastUpdated": "2025-01-17T10:30:00.000Z",
  "xpubs": [
    {
      "xpub": "zpub6rFR7y4Q2AijBEqTUquhVz398htDFrtym...",
      "type": "p2wpkh",
      "path": "m/84'/0'/0'",
      "label": "Native SegWit Account 0",
      "balance": 0.05000000,
      "addressCount": 15,
      "txCount": 42,
      "receiveIndex": 14,
      "changeIndex": 8,
      "totalReceived": 0.15000000,
      "totalSent": 0.10000000
    }
  ]
}

Development

Test Single LOD Level

node dist/server-side-report-example.js 2  # LOD 2

Test Multiple Accounts

node dist/server-side-report-example.js 2 5  # LOD 2, 5 accounts

This will generate 3 XPUBs per account (Legacy, SegWit, Native SegWit) × 5 accounts = 15 XPUBs total.

Troubleshooting

"No XPUBs retrieved from KeepKey"

• Ensure KeepKey is connected and unlocked
• Check Pioneer SDK initialization

"Server returned 500"

• Check pioneer-server logs: tail -f /projects/pioneer/services/pioneer-server/logs/server.log
• Verify server is running: curl http://localhost:9001/api/v1/health

"Connection refused"

• Start pioneer-server: cd /projects/pioneer/services/pioneer-server && make start

Related Documentation

• Bitcoin Reports API Documentation
• Pioneer Server README

License

MIT