npm package: @pioneer-platform/integration-custom-tokens
Description: This integration test validates the complete custom token functionality in the Pioneer Platform.
Latest version: 1.1.51

# Custom Tokens E2E Integration Test

This integration test validates the complete custom token functionality in the Pioneer Platform.

## What This Tests

This test covers the full CRUD cycle for custom tokens:

1. **Add Custom Tokens** - Add ERC-20 tokens across multiple networks (Ethereum, Base, BSC)
2. **Fetch by Network** - Retrieve custom tokens filtered by specific network
3. **Fetch All** - Get all custom tokens for a user across all networks
4. **getCharts() Integration** - Verify custom tokens appear in SDK balance queries
5. **Remove Specific** - Remove a single custom token
6. **Remove All** - Clean up all custom tokens for a user

## Test Tokens

The test uses real USDC token addresses across three networks:

- **Ethereum (eip155:1)**: USDC at `0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48`
- **Base (eip155:8453)**: USDC at `0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913`
- **BSC (eip155:56)**: USDC at `0x8AC76a51cc950d9822D68b83fE1Ad97B32Cd580d`

## Running the Test

```bash
# From this directory
bun run test

# Or from monorepo root
cd e2e/wallets/intergration-custom-tokens
bun run test
```

## Prerequisites

1. **Pioneer Server** must be running at `http://127.0.0.1:9001` (or set `API_URL` env var)
2. **MongoDB** must be connected and available (for CustomTokenService)
3. **KeepKey Device** connected (for wallet initialization)

## Test Flow

```
┌─────────────────────────────────────────────────────────────┐
│ STEP 1: Initialize SDK with EVM blockchains                │
├─────────────────────────────────────────────────────────────┤
│ STEP 2: Clean up existing custom tokens                    │
├─────────────────────────────────────────────────────────────┤
│ STEP 3: Add 3 custom tokens (ETH, Base, BSC)               │
├─────────────────────────────────────────────────────────────┤
│ STEP 4: Fetch custom tokens by network (validate each)     │
├─────────────────────────────────────────────────────────────┤
│ STEP 5: Fetch all custom tokens (validate total count)     │
├─────────────────────────────────────────────────────────────┤
│ STEP 6: Call getCharts() and validate integration          │
│         - Verify custom tokens appear in app.balances      │
│         - Check balances have correct CAIP identifiers      │
├─────────────────────────────────────────────────────────────┤
│ STEP 7: Remove specific token and verify                   │
├─────────────────────────────────────────────────────────────┤
│ STEP 8: Remove all tokens and verify cleanup               │
└─────────────────────────────────────────────────────────────┘
```

## Expected Output

```
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
🧪 CUSTOM TOKENS E2E INTEGRATION TEST
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

📋 [STEP 1] Initializing Pioneer SDK...
✅ SDK initialized successfully

📍 Using EVM address for tests: 0x...

📋 [STEP 2] Cleaning up existing custom tokens...
✅ Removed 0 existing custom tokens

📋 [STEP 3] Adding custom tokens...
✅ Added USDC on Ethereum
✅ Added USDC on Base
✅ Added USDC on BSC

... (more steps)

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
✅ ALL TESTS PASSED
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
```

## Known Issues

### SDK Parameter Mismatch (FIXED)

The SDK was calling `GetCustomTokens({ address: ... })` but the controller expects `userAddress`. This has been fixed in:

- `/modules/pioneer/pioneer-sdk/src/charts/custom-tokens.ts` (line 57)

Change:
```typescript
// BEFORE (incorrect)
const response = await pioneer.GetCustomTokens({ networkId, address: primaryAddress });

// AFTER (correct)
const response = await pioneer.GetCustomTokens({ networkId, userAddress: primaryAddress });
```

## API Endpoints Used

- `POST /api/v1/custom-tokens/add` - Add custom token
- `POST /api/v1/custom-tokens/get` - Get custom tokens (with optional networkId filter)
- `POST /api/v1/custom-tokens/remove` - Remove specific token
- `POST /api/v1/custom-tokens/remove-all` - Remove all tokens for user

## Architecture

```
┌─────────────────────────────────────────────────┐
│ Integration Test (this package)                │
│ - Tests all CRUD operations                    │
│ - Validates getCharts() integration            │
└────────────────┬────────────────────────────────┘
                 │
                 ▼
┌─────────────────────────────────────────────────┐
│ Pioneer SDK                                     │
│ - getCharts() calls fetchCustomTokens()         │
│ - fetchCustomTokens() calls GetCustomTokens API │
└────────────────┬────────────────────────────────┘
                 │
                 ▼
┌─────────────────────────────────────────────────┐
│ Pioneer Server                                  │
│ - CustomTokensController (CRUD endpoints)       │
│ - CustomTokenService (MongoDB operations)       │
└─────────────────────────────────────────────────┘
```

## Debugging

If the test fails, check:

1. **Server logs**: `tail -f logs/server.log` - Look for custom token errors
2. **MongoDB**: Verify `customTokens` collection exists and is writable
3. **Network**: Ensure MongoDB connection string is correct in `.env`
4. **API spec**: Visit `http://127.0.0.1:9001/spec/swagger.json` to verify custom token endpoints exist

## Related Files

- SDK Charts Module: `/modules/pioneer/pioneer-sdk/src/charts/custom-tokens.ts`
- Server Controller: `/services/pioneer-server/src/controllers/custom-tokens.controller.ts`
- Server Service: `/services/pioneer-server/src/services/custom-token.service.ts`
- Integration Test: `/e2e/wallets/intergration-coins/src/index.ts` (shows custom token errors)