npm package: @pioneer-platform/pioneer-signer
Description: Pioneer Platform signer module for generating addresses from seed phrases
Latest version: 1.0.21

# @pioneer-platform/pioneer-signer

Address generation module for the Pioneer Platform. Derives blockchain addresses from BIP39 mnemonic seed phrases using proper derivation paths.

## Features

- ✅ Solana address generation (Ed25519 HD derivation)
- ✅ BIP39 mnemonic validation
- ✅ BIP44 derivation path support
- ✅ Multiple chain support (Bitcoin, Ethereum, Cosmos, Solana)
- ✅ Deterministic address generation
- ✅ Custom derivation path support

## Installation

```bash
bun install @pioneer-platform/pioneer-signer
```

## Supported Chains

| Chain | SLIP44 | Derivation Path | Status |
|-------|---------|-----------------|--------|
| Solana | 501 | m/44'/501'/0'/0' | ✅ Implemented |
| Bitcoin | 0 | m/44'/0'/0'/0/0 | 📋 Path defined |
| Ethereum | 60 | m/44'/60'/0'/0/0 | 📋 Path defined |
| Cosmos | 118 | m/44'/118'/0'/0/0 | 📋 Path defined |

## Usage

### Generate Solana Address

```javascript
const signer = require('@pioneer-platform/pioneer-signer')

const mnemonic = 'your twelve word seed phrase goes here today example test'

// Generate Solana address
const wallet = signer.getSolanaAddress(mnemonic)

console.log('Address:', wallet.address)
// Output: Bk28J8xUs7RG2TZCES63abyKSgWPHA9BTnEt8g6NbydV

console.log('Public Key:', wallet.publicKey)
// Output: Bk28J8xUs7RG2TZCES63abyKSgWPHA9BTnEt8g6NbydV

console.log('Path:', wallet.path)
// Output: m/44'/501'/0'/0'
```

### Custom Derivation Path

```javascript
// Generate address for account index 1
const customWallet = signer.getSolanaAddress(mnemonic, "m/44'/501'/1'/0'")

console.log('Custom Address:', customWallet.address)
console.log('Path:', customWallet.path)
```

### Validate Mnemonic

```javascript
const isValid = signer.validateMnemonic(mnemonic)

if (!isValid) {
    throw new Error('Invalid seed phrase!')
}
```

### Generate New Mnemonic

```javascript
// Generate 12-word mnemonic (128 bits entropy)
const mnemonic12 = signer.generateMnemonic(128)

// Generate 24-word mnemonic (256 bits entropy)
const mnemonic24 = signer.generateMnemonic(256)

console.log('New 12-word:', mnemonic12)
console.log('New 24-word:', mnemonic24)
```

### Get Supported Derivation Paths

```javascript
const paths = signer.getDerivationPaths()

console.log('Solana:', paths.solana)  // m/44'/501'/0'/0'
console.log('Bitcoin:', paths.bitcoin) // m/44'/0'/0'/0/0
console.log('Ethereum:', paths.ethereum) // m/44'/60'/0'/0/0
console.log('Cosmos:', paths.cosmos)   // m/44'/118'/0'/0/0
```

## Full Example with Network Integration

```javascript
require('dotenv').config()
const signer = require('@pioneer-platform/pioneer-signer')
const solanaNetwork = require('@pioneer-platform/solana-network')

async function checkWallet() {
    // 1. Get seed phrase from environment
    const mnemonic = process.env.WALLET_MAIN

    // 2. Generate address
    const wallet = signer.getSolanaAddress(mnemonic)
    console.log('Solana Address:', wallet.address)

    // 3. Initialize network
    await solanaNetwork.init()

    // 4. Check balance
    const balance = await solanaNetwork.getBalance(wallet.address)
    console.log('Balance:', balance, 'SOL')

    // 5. Check SPL tokens
    const tokens = await solanaNetwork.getTokenBalances(wallet.address)
    console.log('Token accounts:', tokens.length)
}

checkWallet()
```

## API Reference

### `getSolanaAddress(mnemonic, derivationPath?)`

Generate Solana address from mnemonic seed phrase.

**Parameters:**
- `mnemonic` (string): BIP39 mnemonic seed phrase
- `derivationPath` (string, optional): Custom derivation path (default: m/44'/501'/0'/0')

**Returns:**
```javascript
{
    address: string,      // Base58 encoded Solana address
    publicKey: string,    // Same as address
    path: string          // Derivation path used
}
```

### `validateMnemonic(mnemonic)`

Validate a BIP39 mnemonic seed phrase.

**Parameters:**
- `mnemonic` (string): Seed phrase to validate

**Returns:** `boolean` - true if valid

### `generateMnemonic(strength?)`

Generate a new random mnemonic.

**Parameters:**
- `strength` (number, optional): Entropy bits (128 = 12 words, 256 = 24 words, default: 128)

**Returns:** `string` - New mnemonic phrase

### `getDerivationPaths()`

Get all supported derivation paths.

**Returns:**
```javascript
{
    solana: "m/44'/501'/0'/0'",
    bitcoin: "m/44'/0'/0'/0/0",
    ethereum: "m/44'/60'/0'/0/0",
    cosmos: "m/44'/118'/0'/0/0"
}
```

## Security Notes

⚠️ **CRITICAL SECURITY WARNINGS:**

1. **Never commit seed phrases to git** - Use environment variables
2. **Never log or expose private keys** - Module doesn't return private keys by default
3. **Validate user input** - Always validate mnemonics before use
4. **Use secure storage** - Store mnemonics encrypted at rest
5. **HTTPS only** - Never transmit mnemonics over unencrypted connections

## Testing

The module includes comprehensive tests:

```bash
# Run basic tests
bun run test

# Run Solana integration tests
cd __tests__
node test-solana-integration.js
```

### Test with .env

Create a `.env` file in the project root:

```bash
WALLET_MAIN=your twelve word seed phrase goes here today example test
```

Then run:

```bash
bun run test
```

Expected output:
```
✓ Mnemonic is valid: true
✓ Solana address generated successfully
  Address: Bk28J8xUs7RG2TZCES63abyKSgWPHA9BTnEt8g6NbydV
  Derivation Path: m/44'/501'/0'/0'
```

## Derivation Path Standard

### Solana (BIP44)

```
m / purpose' / coin_type' / account' / change'
m / 44'      / 501'       / 0'       / 0'
```

- **Purpose**: Always 44' for BIP44
- **Coin Type**: 501 for Solana (SLIP44)
- **Account**: Account index (0, 1, 2, ...)
- **Change**: Change address index (typically 0 for Solana)

### Multiple Accounts

Generate multiple accounts from the same seed:

```javascript
// Account 0 (default)
const account0 = signer.getSolanaAddress(mnemonic, "m/44'/501'/0'/0'")

// Account 1
const account1 = signer.getSolanaAddress(mnemonic, "m/44'/501'/1'/0'")

// Account 2
const account2 = signer.getSolanaAddress(mnemonic, "m/44'/501'/2'/0'")
```

## Dependencies

- `@solana/web3.js` - Solana JavaScript SDK
- `bip39` - BIP39 mnemonic generation and validation
- `ed25519-hd-key` - Ed25519 HD key derivation for Solana

## Technical Details

### Solana Key Derivation

1. **Mnemonic → Seed**: Convert BIP39 mnemonic to 512-bit seed
2. **Seed → Key**: Derive Ed25519 key using BIP44 path
3. **Key → Address**: Convert public key to base58 encoding

### Why Ed25519?

Solana uses Ed25519 elliptic curve cryptography:
- Fast signature verification
- Small signature size (64 bytes)
- Deterministic signatures (RFC 8032)
- Hardened derivation for security

## Future Enhancements

- [ ] Bitcoin address generation (P2PKH, P2SH, Bech32)
- [ ] Ethereum address generation
- [ ] Cosmos SDK chains
- [ ] Multi-signature support
- [ ] Hardware wallet integration
- [ ] Ledger derivation path support

## Integration with Pioneer Platform

This module is used by:
- `pioneer-balance` - Portfolio tracking
- `pioneer-network` - Multi-chain operations
- Pioneer SDK - Wallet management

## License

Pioneer Platform License

## Support

For issues and questions:
- GitHub Issues: [keepkey-stack/issues](https://github.com/keepkey/keepkey-stack/issues)
- Documentation: [Pioneer Platform Docs](https://docs.pioneer.dev)