npm package: @pioneer-platform/solana-network
Description: Pioneer Platform Solana Network module
Latest version: 8.25.10

# @pioneer-platform/solana-network

Solana blockchain network integration module for the Pioneer Platform.

## Features

- ✅ SOL balance queries
- ✅ SPL token balance queries
- ✅ Transfer transaction building
- ✅ Fee estimation
- ✅ Transaction broadcasting
- ✅ Transaction status tracking
- ✅ Account information queries

## Installation

```bash
bun install @pioneer-platform/solana-network
```

## Network Information

- **Network ID**: `solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp`
- **Chain Symbol**: SOL
- **SLIP44**: 501
- **Decimals**: 9 (lamports)
- **Default RPC**: https://api.mainnet-beta.solana.com

## Usage

### Initialize Module

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

// Initialize with default RPC
await solanaNetwork.init()

// Or with custom RPC
await solanaNetwork.init('https://your-custom-rpc.com')

// Or with environment variable
// Set SOLANA_RPC_URL in .env
await solanaNetwork.init()
```

### Get SOL Balance

```javascript
const balance = await solanaNetwork.getBalance('9WzDXwBbmkg8ZTbNMqUxvQRAyrZzDsGYdLVL9zYtAWWM')
console.log('Balance:', balance, 'SOL')
```

### Get SPL Token Balances

```javascript
const tokens = await solanaNetwork.getTokenBalances('9WzDXwBbmkg8ZTbNMqUxvQRAyrZzDsGYdLVL9zYtAWWM')

tokens.forEach(token => {
    console.log(`Token: ${token.mint}`)
    console.log(`Balance: ${token.balance}`)
    console.log(`Decimals: ${token.decimals}`)
})
```

### Build Transfer Transaction

```javascript
const tx = await solanaNetwork.buildTransfer(
    '9WzDXwBbmkg8ZTbNMqUxvQRAyrZzDsGYdLVL9zYtAWWM', // from
    'DYw8jCTfwHNRJhhmFcbXvVDTqWMEVFBX6ZKUmG5CNSKK', // to
    0.001 // amount in SOL
)

console.log('Transaction:', {
    from: tx.from,
    to: tx.to,
    amount: tx.amount,
    lamports: tx.lamports,
    blockhash: tx.blockhash,
    serialized: tx.serialized // base64 encoded, ready for signing
})
```

### Estimate Transfer Fee

```javascript
const fee = await solanaNetwork.estimateFee()
console.log('Fee:', fee, 'SOL') // typically ~0.000005 SOL
```

### Broadcast Signed Transaction

```javascript
// After signing the transaction
const result = await solanaNetwork.broadcast(signedTransactionBase64)

if (result.success) {
    console.log('Transaction ID:', result.txid)
} else {
    console.error('Broadcast failed:', result.error)
}
```

### Get Transaction Details

```javascript
const txDetails = await solanaNetwork.getTransaction('signature...')
console.log('Transaction:', txDetails)
```

### Get Recent Blockhash

```javascript
const { blockhash, lastValidBlockHeight } = await solanaNetwork.getRecentBlockhash()
console.log('Blockhash:', blockhash)
console.log('Valid until block:', lastValidBlockHeight)
```

## API Reference

### Module Exports

#### `init(url?, settings?): Promise<boolean>`
Initialize the Solana network module.
- `url`: Optional RPC URL (defaults to env var or mainnet)
- `settings`: Optional configuration object
- Returns: `true` if successful

#### `isOnline(): boolean`
Check if module is initialized and connected.

#### `getBalance(address): Promise<number>`
Get SOL balance for an address.
- `address`: Solana public key (base58 encoded)
- Returns: Balance in SOL

#### `getTokenBalances(address): Promise<Array>`
Get all SPL token balances for an address.
- `address`: Solana public key (base58 encoded)
- Returns: Array of token accounts with balances

#### `buildTransfer(from, to, amount): Promise<Object>`
Build an unsigned SOL transfer transaction.
- `from`: Sender's public key (base58)
- `to`: Recipient's public key (base58)
- `amount`: Amount in SOL
- Returns: Transaction object with serialized data

#### `estimateFee(): Promise<number>`
Estimate transfer fee.
- Returns: Fee in SOL (typically ~0.000005 SOL)

#### `broadcast(tx): Promise<Object>`
Broadcast a signed transaction.
- `tx`: Base64 encoded signed transaction
- Returns: `{ success: boolean, txid?: string, error?: string }`

#### `getTransaction(signature): Promise<Object>`
Get transaction details by signature.
- `signature`: Transaction signature
- Returns: Transaction details or null

#### `getRecentBlockhash(): Promise<Object>`
Get recent blockhash for transaction building.
- Returns: `{ blockhash: string, lastValidBlockHeight: number }`

#### `getAccount(address): Promise<Object>`
Get account information.
- `address`: Solana public key (base58 encoded)
- Returns: Account info or null

### Constants

- `NETWORK_ID`: Solana network identifier
- `CHAIN_SYMBOL`: 'SOL'
- `DECIMALS`: 9

## Testing

```bash
# Run basic tests
bun run test

# Run transfer tests
cd __tests__
node test-transfer.js
```

## Environment Variables

```bash
# Optional: Custom RPC URL
SOLANA_RPC_URL=https://your-custom-rpc.com
```

## Integration with Pioneer Platform

This module integrates with the Pioneer Platform's multi-chain architecture:

1. **Balance Queries**: Used by `pioneer-balance` for portfolio calculations
2. **Transaction Building**: Used by transaction routers for SOL transfers
3. **Token Support**: SPL token discovery and balance tracking
4. **Network State**: Health checks and network status monitoring

## RPC Endpoints

### Mainnet
- https://api.mainnet-beta.solana.com (default)
- https://solana-api.projectserum.com

### Performance Tips
- Use private RPC endpoints for production (QuickNode, Alchemy, etc.)
- Default public RPCs have rate limits
- Consider connection pooling for high-frequency queries

## Transaction Signing

This module builds **unsigned** transactions. To sign and broadcast:

```javascript
// 1. Build transaction
const tx = await solanaNetwork.buildTransfer(from, to, amount)

// 2. Sign with your wallet/keypair (using @solana/web3.js)
const { Keypair } = require('@solana/web3.js')
const keypair = Keypair.fromSecretKey(secretKey)
tx.transaction.sign(keypair)

// 3. Serialize signed transaction
const signedTx = tx.transaction.serialize().toString('base64')

// 4. Broadcast
const result = await solanaNetwork.broadcast(signedTx)
```

## License

Pioneer Platform License