@kamiyo-org/helius-adapter

Helius RPC integration. Connection pooling, rate limiting, priority fees, transaction parsing, webhooks.

Installation

npm install @kamiyo-org/helius-adapter @solana/web3.js

Features

• Connection Pooling - Automatic failover with health checks
• Rate Limiting - Token bucket algorithm prevents API throttling
• Priority Fees - Helius-powered fee estimation with strategy selection
• Transaction Parsing - Parse escrow transactions from Helius Enhanced API
• Webhooks - Real-time event handling with signature verification
• TypeScript - Full type definitions for all operations

Quick Start

import { KamiyoHeliusClient } from '@kamiyo-org/helius-adapter';
import { PublicKey } from '@solana/web3.js';

const client = new KamiyoHeliusClient({
    apiKey: process.env.HELIUS_API_KEY,
    cluster: 'mainnet-beta'
});

await client.init();

// Derive escrow PDA
const user = new PublicKey('...');
const { pda } = client.deriveEscrowPDA(user, 'session-123');

// Get escrow state
const state = await client.getEscrowState(pda);
console.log('Escrow status:', state?.status);
console.log('Quality score:', state?.qualityScore);

// Get priority fee for operation
const fee = await client.getOperationFee('FINALIZE_DISPUTE', pda, 'urgent');
console.log('Priority fee:', fee.priorityFee, 'micro-lamports/CU');
console.log('Total fee:', fee.totalFee, 'lamports');

// Subscribe to escrow changes
const subscription = await client.subscribeToEscrow(pda, {
    onStateChange: (state) => {
        console.log('Escrow updated:', state.status);
    },
    onError: (error) => {
        console.error('Subscription error:', error);
    }
});

// Cleanup
await subscription.unsubscribe();
await client.shutdown();

Configuration

interface HeliusConfig {
    apiKey: string;              // Helius API key (required)
    cluster?: 'mainnet-beta' | 'devnet';  // Default: 'mainnet-beta'
    commitment?: Commitment;     // Default: 'confirmed'
    maxRetries?: number;         // Default: 3
    retryDelayMs?: number;       // Default: 1000
    rateLimitRps?: number;       // Default: 25
    enableWebsocket?: boolean;   // Default: true
}

Priority Fee Strategies

| Strategy | Multiplier | Max Fee | Use Case | |----------|------------|---------|----------| | economy | 0.5x | 10,000 | Non-urgent operations | | standard | 1.0x | 50,000 | Default operations | | fast | 1.5x | 100,000 | Time-sensitive | | urgent | 2.5x | 500,000 | Dispute resolution | | critical | 5.0x | 1,000,000 | Fund releases |

// Get fee for specific strategy
const fee = await client.getOperationFee('RATE_AND_RELEASE', escrowPda, 'critical');

// Get all strategy fees
const allFees = await client.feeCalculator.getAllStrategyFees([escrowPda]);
console.log(allFees);
// { economy: 2500, standard: 5000, fast: 7500, urgent: 12500, critical: 25000 }

Webhook Handler

Process escrow events in real-time via Helius webhooks:

import { createVerifiedWebhookHandler } from '@kamiyo-org/helius-adapter/webhooks';

// Express/Next.js handler
const handler = createVerifiedWebhookHandler(
    process.env.HELIUS_WEBHOOK_SECRET,
    {
        onEscrowCreated: async (event) => {
            console.log('Escrow created:', event.escrowPda);
            console.log('User:', event.user);
            console.log('Treasury:', event.treasury);
            console.log('Session ID (sha256 hex):', event.sessionId);
            console.log('Amount:', event.amount);
        },

        onDisputeInitiated: async (event) => {
            console.log('Dispute initiated:', event.escrowPda);
            // Trigger oracle assessment
            await initiateOracleReview(event.escrowPda);
        },

        onDisputeResolved: async (event) => {
            console.log('Quality score:', event.qualityScore);
            console.log('Refund percent:', event.refundPercentage);
            console.log('Refund amount:', event.refundAmount);
            console.log('Payment amount:', event.paymentAmount);
            // Update agent reputation
            await updateReputation(event.user, event.qualityScore);
        },

        onFundsReleased: async (event) => {
            console.log('Funds released:', event.amount);
            // Notify parties
            await notifyParties(event);
        },

        onFundsRefunded: async (event) => {
            console.log('Funds refunded:', event.amount);
            await notifyParties(event);
        },

        onError: (error, payload) => {
            console.error('Webhook error:', error);
        }
    }
);

// Use with Express
app.post('/webhooks/kamiyo', handler);

Transaction Parsing

Parse escrow transactions from Helius Enhanced API:

import {
    parseTransaction,
    groupByEscrow,
    calculateEscrowLifecycle
} from '@kamiyo-org/helius-adapter';

// Fetch enhanced transactions
const txs = await client.fetchEnhancedTransactions([
    'signature1',
    'signature2'
]);

// Parse into structured data
const parsed = txs.map(parseTransaction);

// Group by escrow
const grouped = groupByEscrow(parsed);

// Calculate lifecycle
for (const [pda, transactions] of grouped) {
    const lifecycle = calculateEscrowLifecycle(transactions);
    console.log(`Escrow ${pda}:`);
    console.log(`  Duration: ${lifecycle.duration}s`);
    console.log(`  Was disputed: ${lifecycle.wasDisputed}`);
    console.log(`  Quality score: ${lifecycle.finalQualityScore}`);
}

Protocol Statistics

const stats = await client.getProtocolStats(100);

console.log('Total escrows:', stats.totalEscrows);
console.log('Active:', stats.activeEscrows);
console.log('Disputed:', stats.disputedEscrows);
console.log('Resolved:', stats.resolvedEscrows);
console.log('Avg quality:', stats.averageQualityScore);
console.log('Total volume:', stats.totalVolume, 'lamports');

Connection Pool Stats

Monitor connection health:

const poolStats = client.getPoolStats();

console.log('Connections:', poolStats.total);
console.log('Healthy:', poolStats.healthy);
console.log('Avg latency:', poolStats.avgLatency, 'ms');

for (const conn of poolStats.connections) {
    console.log(`  ${conn.endpoint}: ${conn.healthy ? 'OK' : 'FAIL'}`);
}

Error Handling

import {
    HeliusAdapterError,
    ConnectionError,
    RateLimitError,
    ParseError
} from '@kamiyo-org/helius-adapter';

try {
    const state = await client.getEscrowState(pda);
} catch (error) {
    if (error instanceof RateLimitError) {
        console.log('Rate limited, waiting...');
        await delay(error.retryAfterMs);
    } else if (error instanceof ConnectionError) {
        console.log('Connection failed:', error.message);
    } else if (error instanceof ParseError) {
        console.log('Parse error:', error.message);
    } else if (error instanceof HeliusAdapterError) {
        console.log('Adapter error:', error.code, error.message);
    }
}

Helius Webhook Setup

1. Go to Helius Dashboard
2. Create new webhook
3. Set webhook URL to your endpoint
4. Select "Enhanced Transactions" type
5. Add KAMIYO escrow program ID: FVnvAs8bahMwAvjcLq5ZrXksuu5Qeu2MRkbjwB9mua3u
6. Copy webhook secret for signature verification

API Reference

KamiyoHeliusClient

| Method | Description | |--------|-------------| | init() | Initialize connection pool | | getConnection() | Get current active connection | | deriveEscrowPDA(user, sessionId) | Derive escrow PDA from user + session ID | | getEscrowState(pda) | Fetch escrow account state | | getEscrowStates(pdas) | Batch fetch multiple escrows | | getRecentTransactions(filter?) | Get recent program transactions | | getTransaction(signature) | Get single transaction | | getEscrowHistory(escrowPda) | Get escrow transaction history | | getPriorityFee(accounts) | Get fee estimate | | getOperationFee(op, pda, strategy) | Calculate operation fee | | subscribeToEscrow(pda, options) | Subscribe to state changes | | unsubscribeAll() | Remove all subscriptions | | getProtocolStats(sampleSize) | Get protocol statistics | | getPoolStats() | Get connection pool stats | | getRateLimiterStats() | Get rate limiter stats | | shutdown() | Cleanup and close connections |

License

MIT