KeepKey Report Generator v2

Clean, simple report generator that gets LIVE data from a connected KeepKey device.

Features

✅ LIVE Data - No hardcoded or fake data ✅ ASCII Tables - Clean console output ✅ JSON Export - Structured data ready for PDF generation ✅ LOD System - Level of Detail from 0 (basic) to 5 (maximum) ✅ Vault Compatible - Matches vault reportGenerators structure

Quick Start

1. Configure Report

Edit src/config.ts:

export const REPORT_CONFIG = {
  chain: 'bitcoin',  // Chain to report on
  lod: 0,           // Level of detail (0-5)
  options: {
    includeEmpty: false,
    gapLimit: 20,
  }
};

2. Run Report

# Build and run
pnpm run dev

# Or rebuild and run
pnpm run rebuild && pnpm run dev

3. View Output

• Console: ASCII table output
• JSON: Saved to ./output/report-{chain}-lod{lod}-{timestamp}.json

LOD Levels

| LOD | Description | Sections | |-----|-------------|----------| | 0 | Basic Overview | Device features + XPUB balances | | 1 | Account Details | + Account-level data | | 2 | Address Details | + Address-level data | | 3 | Transaction List | + Transaction details | | 4 | Full History | + Complete transaction history | | 5 | Maximum Detail | + All addresses and transactions |

Currently Implemented: LOD 0

Structure

intergration-report-v2/
├── src/
│   ├── config.ts             # Report configuration (EDIT HERE)
│   ├── types.ts              # Type definitions (matches vault)
│   ├── report-generator.ts   # Single-file generator (ALL LOD levels)
│   ├── formatters/
│   │   └── ascii-table.ts    # ASCII table formatter
│   └── index.ts              # Main runner
├── output/                    # Generated reports (JSON)
└── dist/                      # Compiled JavaScript

Single-File Design: All LOD levels in one file (report-generator.ts), just like keepkey-vault! You can copy this file directly to keepkey-vault if needed.

Example Output

╔══════════════════════════════════════════════════════════════════════════════╗
║                        BITCOIN Report - LOD 0                                ║
║                           Basic Overview                                     ║
║                   Generated: 2025-10-18 12:00:00 PM                         ║
║                        Chain: bitcoin | LOD: 0                               ║
╚══════════════════════════════════════════════════════════════════════════════╝

════════════════════════════════════════════════════════════════════════════════
Device Features
════════════════════════════════════════════════════════════════════════════════

  • Vendor: keepkey.com
  • Model: K1-14AM
  • Device ID: ABC123...
  • Label: My KeepKey
  • Firmware: 7.9.3
  • Initialized: Yes
  • PIN Protection: Enabled

════════════════════════════════════════════════════════════════════════════════
XPUB Balances
════════════════════════════════════════════════════════════════════════════════

+------------------+---------------+----------+-----------+--------+------------------------+
| Path             | Type          | Balance  | USD Value | Symbol | XPUB                   |
+------------------+---------------+----------+-----------+--------+------------------------+
| m/44'/0'/0'      | p2pkh         | 0.12345  | $5,234.56 | BTC    | xpub6D3uXJmdUg4x...   |
| m/49'/0'/0'      | p2sh-p2wpkh   | 0.00000  | $0.00     | BTC    | ypub6WamSeXgTYgy...   |
+------------------+---------------+----------+-----------+--------+------------------------+

Next Steps

Implement LOD 1-5

All LOD levels are in the single file src/report-generator.ts:

• ✅ LOD 0: Basic overview (DONE)
• ⚠️ LOD 1: Account details (TODO - implement getAccountDetails())
• ⚠️ LOD 2: Address details (TODO - implement getAddressDetails())
• ⚠️ LOD 3: Transaction details (TODO - implement getTransactionSummary())
• ⚠️ LOD 4: Full history (TODO - implement getFullTransactionHistory())
• ⚠️ LOD 5: Maximum detail (TODO - implement getAllAddresses() + getAllTransactions())

Just fill in the methods marked with // TODO: Implement when needed

PDF Generation

Add PDF formatter:

• src/formatters/pdf-generator.ts
• Use existing JSON output
• Match vault's PDF styling

Copy to Vault

The single-file design makes it easy:

# Copy the generator to vault
cp src/report-generator.ts /path/to/keepkey-vault/src/components/asset/reportGenerators/

Important Notes

⚠️ NO FAKE DATA: This report generator ONLY uses live data from connected KeepKey device ⚠️ Device Required: A KeepKey device must be connected and unlocked ⚠️ LOD 0 Only: Currently only LOD 0 is implemented - other levels coming soon

SDK Integration Note

⚠️ Current Status: The SDK integration needs workspace packages to be built first.

To use this:

1. Build the pioneer monorepo: cd ../../../ && make
2. Or adapt the SDK initialization to your environment (browser, node, etc.)
3. See existing e2e tests for working SDK examples

The core report-generator.ts is ready - just needs proper SDK initialized and passed in!

Compatibility

Designed to match the structure of:

• /projects/keepkey-vault/src/components/asset/reportGenerators/

This ensures easy integration with vault's PDF generation system.