npm package: @pioneer-platform/e2e-sign-message
Description: Professional-grade end-to-end testing suite for multi-chain message signing with comprehensive validation.
Latest version: 1.0.19

# E2E Message Signing Test Suite

Professional-grade end-to-end testing suite for multi-chain message signing with comprehensive validation.

## Overview

This test suite validates off-chain message signing functionality for dApp authentication, proof-of-ownership, and governance use cases. It provides comprehensive testing for the Pioneer SDK's `signMessage` API across supported blockchains.

## Features

- **Multi-Chain Support**: Test message signing across all supported blockchains
- **Message Type Testing**: Validates simple ASCII, binary, and large messages
- **Signature Validation**: Verifies signature format and length
- **CLI Mode**: Single message signing for debugging
- **Performance Metrics**: Timing for SDK init, device pairing, and signing
- **Production Ready**: Comprehensive error handling and logging

## Supported Chains

Currently tested chains:
- ✅ **Solana** - Ed25519 signatures with Phantom/Solflare wallet compatibility

Planned support:
- Ethereum (EIP-191/EIP-712)
- Cosmos chains
- Other ECDSA/EdDSA chains

## Installation

```bash
# Install dependencies (from root of pioneer monorepo)
pnpm install
```

## Usage

### Default Mode - Test All Message Types

Runs comprehensive tests for all message types:

```bash
cd projects/pioneer/e2e/messages/e2e-sign-message
bun run sign
```

This will test:
1. Simple ASCII message (dApp authentication)
2. Binary message (hex data)
3. Large message (1KB)

### CLI Mode - Single Message Signing

Sign a specific message for debugging:

```bash
# Sign a simple text message
bun run sign solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp/slip44:501 "Welcome to MyDApp!"

# Sign with custom nonce
bun run sign solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp/slip44:501 "Auth request: $(date +%s)"
```

### Development Mode

Run with automatic rebuild:

```bash
bun run dev
```

## API Integration

### Using Pioneer SDK

```typescript
import SDK from '@pioneer-platform/pioneer-sdk';

// Initialize SDK
const sdk = new SDK.SDK(spec, config);
await sdk.init([], {});

// Sign a message
const caip = 'solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp/slip44:501';
const message = Buffer.from('Welcome to MyDApp!', 'utf8').toString('base64');
const addressNList = [2147483692, 2147484149, 2147483648, 2147483648]; // m/44'/501'/0'/0'

const result = await sdk.signMessage(caip, message, addressNList);

console.log('Signature:', result.signature);
console.log('Public Key:', result.publicKey);
```

### Direct Vault API

```typescript
import axios from 'axios';

const response = await axios.post('http://localhost:1646/solana/sign-message', {
  addressNList: [2147483692, 2147484149, 2147483648, 2147483648],
  message: Buffer.from('Welcome to MyDApp!', 'utf8').toString('base64'),
  showDisplay: true
});

const { signature, publicKey } = response.data;
```

## Message Format

### Solana Messages

Messages are automatically prefixed with `\x19Solana Signed Message:\n` before signing (wallet standard).

**Input Encoding**: UTF-8 text → Base64
**Signature Format**: Ed25519 (64 bytes) → Base64
**Public Key Format**: Ed25519 (32 bytes) → Base64

Example:
```typescript
const message = "Welcome to MyDApp!";
const messageBase64 = Buffer.from(message, 'utf8').toString('base64');
// messageBase64 = "V2VsY29tZSB0byBNeURBcHAh"
```

## Test Results

### Expected Output

```
🚀 TOTAL_RUNTIME: 45.231s
⚙️  SDK_INITIALIZATION: 1.234s
🔗 DEVICE_PAIRING: 5.678s
📊 PUBKEY_SYNC: 12.345s
✍️  MESSAGE_SIGNING: 25.974s

============================================================
📊 TEST SUMMARY
============================================================
Simple Message: ✅ PASS
Binary Message: ✅ PASS
Large Message: ✅ PASS (or expected to fail)

✅ E2E MESSAGE SIGNING TEST PASSED

📝 Notes:
   - Signatures are Ed25519 (64 bytes)
   - Messages are prefixed with '\x19Solana Signed Message:\n'
   - Device shows message preview (text or hex)
   - Compatible with Phantom/Solflare wallets
```

## Configuration

### Environment Variables

Create a `.env` file in the root of the pioneer monorepo:

```bash
KEEPKEY_API_KEY=your_api_key_here
ETHPLORER_API_KEY=your_api_key_here
COVALENT_API_KEY=your_api_key_here
UTXO_API_KEY=your_api_key_here
WALLET_CONNECT_PROJECT_ID=your_project_id_here
```

### API Endpoints

The test suite can use different backend endpoints:

```typescript
// Pioneer server (complete multi-chain support)
let spec = 'http://127.0.0.1:9001/spec/swagger.json'

// KeepKey vault (local development)
let spec = 'http://127.0.0.1:1646/spec/swagger.json'

// Production Pioneer API
let spec = 'https://api.keepkey.info/spec/swagger.json'
```

## Architecture

```
e2e-sign-message/
├── src/
│   └── index.ts          # Main test implementation
├── package.json          # Dependencies and scripts
├── tsconfig.json         # TypeScript configuration
├── jest.config.js        # Jest test configuration
├── LICENSE               # MIT License
└── README.md            # This file
```

## Development

### Building

```bash
bun run build
```

### Testing

```bash
# Run full test suite
bun run test

# Run with debug output
bun run test-debug
```

### Adding New Chains

To add support for a new blockchain:

1. Add chain to the `chains` array in `src/index.ts`
2. Implement message signing in `TransactionManager.signMessage()`
3. Add chain-specific message encoding if needed
4. Update README with chain-specific details

## Troubleshooting

### Device Not Found

Ensure your KeepKey is:
- Connected via USB
- Unlocked with PIN
- Running firmware v7.1.0 or later for Solana support

### Signature Verification Failed

Check that:
- Message encoding is correct (UTF-8 → Base64)
- Derivation path matches the public key
- Firmware supports the requested chain

### Timeout Errors

The test has a 5-minute timeout for device interaction. If you're experiencing timeouts:
- Ensure device is responsive
- Check USB connection
- Verify vault/server is running

## Related Documentation

- [Pioneer SDK Documentation](../../../modules/pioneer/pioneer-sdk/README.md)
- [KeepKey Vault API](../../../keepkey-vault-v10/README.md)
- [Message Signing Specification](./SPECIFICATION.md)

## License

MIT License - see [LICENSE](./LICENSE) file for details

## Support

For issues and questions:
- GitHub Issues: https://github.com/keepkey/keepkey-stack/issues
- Discord: https://discord.gg/keepkey