@coinmasters/integration-coins
v1.14.10
Published
Comprehensive end-to-end testing for the Pioneer SDK that validates nearly all vault functionality except send/transfer/trade operations.
Readme
Integration Coins Test Suite
Comprehensive end-to-end testing for the Pioneer SDK that validates nearly all vault functionality except send/transfer/trade operations.
What This Test Covers
This integration test performs comprehensive validation of the Pioneer SDK and Vault, testing:
1. Vault Health & Cache ✅
- kkapi:// protocol connectivity
- Cache status endpoint validation
- Cached portfolio availability check
- Vault pubkey fetching speed benchmarks
2. Multi-Chain Fee Validation ⛽
Tests normalized fee structures across all supported blockchains:
- EVM Chains: ETH, MATIC, BASE, BSC
- UTXO Chains: BTC, LTC, DOGE, BCH, DASH
- Cosmos Chains: GAIA, OSMO
- Other: XRP
For each chain, validates:
- Normalized fee structure (slow/average/fastest)
- Fee progression (slow ≤ average ≤ fastest)
- Required metadata (labels, units, descriptions, priorities)
- Transaction fee estimation
3. Comprehensive Pubkey Testing 🔑
- Fetches all pubkeys for configured blockchains
- Validates pubkey structure (pubkey/xpub/address, networks)
- Groups and analyzes pubkeys by network
- Performance metrics (average time per pubkey)
- Path completeness validation
4. Complete Balance Portfolio Testing 💰
- Fetches all balances across all chains
- Separates native coins from tokens
- Calculates total portfolio value in USD
- Shows top 10 holdings by value
- Validates balance data quality
5. Context Switching 🔄
- Tests pubkey context switching functionality
- Validates context is properly set
- Verifies balances are filtered by active context
- Tests multiple context switches
6. Path Completeness Validation 🗺️
- Ensures every blockchain has at least one pubkey
- Checks that every path has a corresponding pubkey
- Identifies paths without pubkeys
- Reports path validation issues
7. Portfolio Completeness 📊
- Validates pubkeys have corresponding balances
- Checks balance data structure integrity
- Identifies data quality issues
- Reports pubkeys without balances (normal for unused addresses)
8. Performance Metrics ⚡
Tracks and reports:
- Total test execution time
- Pubkey fetch time and percentage
- Balance fetch time and percentage
- Average time per pubkey
- Time breakdown by operation
What This Test Does NOT Cover
This test intentionally excludes transaction operations:
- ❌ Send operations
- ❌ Transfer operations
- ❌ Trade/swap operations
These operations are covered by dedicated e2e tests:
e2e/transfers/e2e-transfer-suite- Transfer testinge2e/swaps/e2e-swap-suite- Swap/trade testing
Test Output
The test produces comprehensive output including:
🚀 [INTEGRATION TEST] Starting enhanced performance test...
🚀 [HEALTH CHECK] Testing kkapi:// protocol...
✅ [HEALTH CHECK] kkapi:// protocol is working!
💸 [FEES] Testing fees for eip155:1...
✅ [FEES] Got normalized fee data for eip155:1
📊 [FEES] Normalized fees for eip155:1 (EVM):
💰 Slow: 25.5 GWEI
💵 Average: 30.2 GWEI
🚀 Fastest: 35.8 GWEI
🔑 [PUBKEYS] Testing comprehensive pubkey fetching...
✅ [PUBKEYS] Fetched 27 pubkeys in 2450ms
⚡ [PERFORMANCE] Average per pubkey: 91ms
📊 [PUBKEYS] Distribution by network:
eip155:*: 3 pubkeys
bip122:000000000019d6689c085ae165831e93: 9 pubkeys
...
💰 [BALANCES] Testing comprehensive balance fetching...
✅ [BALANCES] Fetched 45 balances in 3200ms
📊 Native coins: 12
🪙 Tokens: 33
💵 Total portfolio value: $12,345.67 USD
🏆 [TOP HOLDINGS] Top 10 assets by value:
1. ETH: 2.5 ($5,234.50 USD)
2. BTC: 0.15 ($4,567.89 USD)
...
🔄 [CONTEXT] Testing pubkey context switching...
🎯 [CONTEXT 1/3] Setting context to: 0x1234567890...
📊 Balances for this context: 15
💵 Context value: $3,456.78 USD
⚡ ═══════════════════════════════════════════════════════════
⚡ PERFORMANCE SUMMARY
⚡ ═══════════════════════════════════════════════════════════
📊 Total test time: 8500ms
🔑 Pubkey fetch: 2450ms (28.8%)
💰 Balance fetch: 3200ms (37.6%)
⚡ Avg pubkey time: 91ms
⚡ ═══════════════════════════════════════════════════════════
📊 ═══════════════════════════════════════════════════════════
📊 TEST SUMMARY
📊 ═══════════════════════════════════════════════════════════
✅ Blockchains tested: 12
✅ Paths configured: 27
✅ Pubkeys fetched: 27
✅ Balances retrieved: 45
✅ Native coins: 12
✅ Tokens: 33
✅ Portfolio value: $12,345.67 USD
✅ Fees validated: 12 chains
✅ Context switching: 3 contexts tested
📊 ═══════════════════════════════════════════════════════════
🎉 All tests completed successfully! Exiting with code 0.Running the Test
# Build the test
bun run build
# Run the test
bun run start
# Run with optimizations (if available)
bun run start:optimizedPrerequisites
Pioneer Server must be running:
cd services/pioneer-server make dev-serverEnvironment Variables (optional):
KEEPKEY_API_KEY- KeepKey API keyVITE_PIONEER_URL_SPEC- Pioneer API spec URL (defaults to local)VITE_PIONEER_URL_WSS- WebSocket URL
KeepKey Device (optional):
- Connect KeepKey hardware wallet
- Or run KeepKey Vault v7 for kkapi:// protocol support
Architecture
┌─────────────────────────────────────────────────────────────┐
│ Integration Coins Test Suite │
├─────────────────────────────────────────────────────────────┤
│ │
│ 1. Health Check (kkapi://) │
│ └─> Vault availability & cache detection │
│ │
│ 2. Fee Validation (12 chains) │
│ └─> Normalized fee structures │
│ │
│ 3. Pubkey Testing │
│ └─> Fetch & validate all pubkeys │
│ └─> Performance metrics │
│ │
│ 4. Balance Testing │
│ └─> Fetch complete portfolio │
│ └─> Calculate USD values │
│ │
│ 5. Context Switching │
│ └─> Test pubkey context management │
│ │
│ 6. Validation & Completeness │
│ └─> Path validation │
│ └─> Data quality checks │
│ │
│ 7. Performance Summary │
│ └─> Timing breakdown & metrics │
│ │
└─────────────────────────────────────────────────────────────┘Test Flow
1. Initialize SDK
├─> Configure blockchains
├─> Generate paths
└─> Connect to Pioneer server
2. Validate Infrastructure
├─> Test kkapi:// protocol
├─> Check cache availability
└─> Benchmark vault performance
3. Validate Fees (per blockchain)
├─> Fetch normalized fees
├─> Validate structure
├─> Test fee progression
└─> Estimate transaction fees
4. Fetch & Validate Pubkeys
├─> Get all pubkeys
├─> Validate structure
├─> Group by network
└─> Check path completeness
5. Fetch & Validate Balances
├─> Get all balances
├─> Separate native/tokens
├─> Calculate portfolio value
└─> Validate data quality
6. Test Context Switching
├─> Set different contexts
├─> Verify context changes
└─> Filter balances by context
7. Generate Reports
├─> Performance metrics
├─> Test summary
└─> Exit with status codeIntegration with Other Tests
This test is part of a comprehensive e2e testing suite:
e2e/
├── wallets/
│ ├── intergration-coins/ <-- THIS TEST (read-only operations)
│ ├── intergration-fees/ (fee-specific testing)
│ ├── intergration-kkapi/ (kkapi protocol testing)
│ └── ...
├── transfers/
│ └── e2e-transfer-suite/ (send/transfer operations)
├── swaps/
│ └── e2e-swap-suite/ (swap/trade operations)
└── staking/
└── ... (staking operations)Troubleshooting
Test hangs during init
- Check Pioneer server is running on port 9001
- Verify network connectivity
- Check KeepKey device connection
Vault not available
- This is OK - test will continue with legacy support
- To enable vault features, run
keepkey-vault-v7
Balance validation fails
- Normal for fresh wallets with no transaction history
- Check that paths are properly configured
- Verify blockchain nodes are accessible
Context switching fails
- Ensure pubkeys are properly fetched
- Check that balances exist for test pubkeys
- Verify SDK version supports context switching
Development
To extend this test:
- Add new blockchain to
AllChainsSupportedarray - Add fee validation for the new chain
- Ensure paths are generated for the chain
- Run test and verify all validations pass