Jito Bundle Tip Service

A TypeScript service for handling Solana wallet balance checking and SOL transfer logic with Jito bundle tip support. This module provides utilities for managing wallet balances, checking fee requirements, and handling excess SOL transfers in Solana applications with special support for Jito bundle transactions.

Features

• ✅ Balance Checking: Check wallet SOL balances against fee requirements
• ✅ Excess SOL Transfer: Automatically transfer excess SOL to fee vaults
• ✅ Jito Tip Support: Handle Jito tip calculations for bundle transactions
• ✅ TypeScript Support: Full TypeScript support with comprehensive type definitions
• ✅ Configurable: Customizable thresholds and fee vault addresses
• ✅ Async/Await: Modern async/await API design

Installation

npm install jito-bundle-tip-service

Quick Start

import { 
  WalletBalanceService, 
  handleWalletBalance,
  WalletBalanceParams 
} from 'jito-bundle-tip-service';
import { Connection, Keypair, LAMPORTS_PER_SOL } from '@solana/web3.js';

// Initialize connection and keypairs
const connection = new Connection('https://api.mainnet-beta.solana.com');
const keypair = Keypair.generate();
const payerKeypair = Keypair.generate();

// Method 1: Using the service class
const service = new WalletBalanceService();
const result = await service.handleWalletBalance({
  keypair,
  connection,
  requiredForFees: 2039280, // ~0.002 SOL
  jitoTipAmountLamports: 1000000, // 0.001 SOL
  payerKeypair,
  currentIndex: 0,
  totalWallets: 10,
});

// Method 2: Using the static function
const result2 = await handleWalletBalance({
  keypair,
  connection,
  requiredForFees: 2039280,
  jitoTipAmountLamports: 1000000,
  payerKeypair,
  currentIndex: 0,
  totalWallets: 10,
});

// Handle the result
if (result.shouldSkip) {
  console.log('Skipping wallet:', result.reason);
} else if (result.transferInstruction) {
  console.log('Adding transfer instruction to transaction');
  // Add result.transferInstruction to your transaction
} else if (result.availableForSwap) {
  console.log('Available for swap:', result.availableForSwap / LAMPORTS_PER_SOL, 'SOL');
}

API Reference

WalletBalanceService

The main service class for handling wallet balance operations.

Constructor

new WalletBalanceService(config?: Partial<WalletBalanceConfig>)

Methods

handleWalletBalance(params: WalletBalanceParams): Promise<WalletBalanceResult>

Handles wallet balance checking and SOL transfer logic.

Parameters:

• params.keypair: The wallet keypair to check
• params.connection: Solana connection instance
• params.requiredForFees: Base fee requirement in lamports
• params.jitoTipAmountLamports: Jito tip amount in lamports
• params.payerKeypair: Payer keypair for tip calculation
• params.currentIndex: Current wallet index in the batch
• params.totalWallets: Total number of wallets in the batch

Returns: Promise<WalletBalanceResult>

updateConfig(config: Partial<WalletBalanceConfig>): void

Updates the service configuration.

getConfig(): WalletBalanceConfig

Gets the current configuration.

Static Functions

handleWalletBalance(params: WalletBalanceParams, config?: Partial<WalletBalanceConfig>): Promise<WalletBalanceResult>

Convenience function for one-time wallet balance handling.

Types

WalletBalanceParams

interface WalletBalanceParams {
  keypair: Keypair;
  connection: Connection;
  requiredForFees: number;
  jitoTipAmountLamports: number;
  payerKeypair: Keypair;
  currentIndex: number;
  totalWallets: number;
}

WalletBalanceResult

interface WalletBalanceResult {
  shouldSkip: boolean;
  transferInstruction?: TransactionInstruction;
  availableForSwap?: number;
  reason?: string;
}

WalletBalanceConfig

interface WalletBalanceConfig {
  feeVault: PublicKey;
  excessTransferThreshold: number;
  keepAmount: number;
}

Configuration

You can customize the service behavior by providing a configuration object:

import { WalletBalanceService } from 'jito-bundle-tip-service';
import { PublicKey, LAMPORTS_PER_SOL } from '@solana/web3.js';

const service = new WalletBalanceService({
  feeVault: new PublicKey('YourCustomFeeVaultAddress'),
  excessTransferThreshold: 1.0 * LAMPORTS_PER_SOL, // 1 SOL threshold
  keepAmount: 0.01 * LAMPORTS_PER_SOL, // Keep 0.01 SOL
});

Advanced Usage

Batch Processing

import { WalletBalanceService } from 'jito-bundle-tip-service';

const service = new WalletBalanceService();
const keypairs = [/* your keypairs */];
const payerKeypair = /* your payer keypair */;

for (let i = 0; i < keypairs.length; i++) {
  const result = await service.handleWalletBalance({
    keypair: keypairs[i],
    connection,
    requiredForFees: 2039280,
    jitoTipAmountLamports: 1000000,
    payerKeypair,
    currentIndex: i,
    totalWallets: keypairs.length,
  });

  if (result.shouldSkip) {
    console.log(`Skipping wallet ${i}:`, result.reason);
    continue;
  }

  if (result.transferInstruction) {
    // Add transfer instruction to your transaction
    instructions.push(result.transferInstruction);
  }

  if (result.availableForSwap) {
    // Use availableForSwap for your swap calculations
    const swapAmount = result.availableForSwap * 0.8; // Use 80% for swap
  }
}

Custom Configuration

import { WalletBalanceService } from 'jito-bundle-tip-service';
import { PublicKey, LAMPORTS_PER_SOL } from '@solana/web3.js';

// Create service with custom configuration
const service = new WalletBalanceService({
  feeVault: new PublicKey('DyVSLTLXm7G8QKn84Zaz3PxcorNuw39NvE4C8Ag873L2'),
  excessTransferThreshold: 0.5 * LAMPORTS_PER_SOL,
  keepAmount: 0.005 * LAMPORTS_PER_SOL,
});

// Update configuration later
service.updateConfig({
  excessTransferThreshold: 1.0 * LAMPORTS_PER_SOL, // Change to 1 SOL
});

Error Handling

The service handles various scenarios gracefully:

• Insufficient Balance: Returns shouldSkip: true with a descriptive reason
• Excess SOL: Returns a transfer instruction to move excess SOL to fee vault
• Normal Operation: Returns available SOL amount for swap operations

Dependencies

• @solana/web3.js: ^1.87.6

Development

Building

npm run build

Publishing

npm publish

License

MIT

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Support

If you encounter any issues or have questions, please file an issue on the GitHub repository.