@breeeve/solana-payment-core

A TypeScript library for processing Solana payments using temporary wallets. This package provides a secure and efficient way to handle payments by creating temporary wallets for receiving payments and forwarding them to a seller's address.

Features

• 🔒 Secure payment processing using temporary wallets
• 💰 Automatic gas fee management
• 💸 Automatic refund of remaining SOL
• ⏱️ Configurable payment window
• 🔄 Automatic payment status checking
• 📊 Detailed payment state tracking

Installation

npm install @breeeve/solana-payment-core

Usage

Basic Setup

import { Connection, Keypair } from '@solana/web3.js';
import { createPaymentProcessor, PaymentConfig } from '@breeeve/solana-payment-core';

// Create a connection to Solana network
const connection = new Connection('https://api.devnet.solana.com');

// Configure the payment processor
const config: PaymentConfig = {
  sellerAddress: '9RKnB9eWaBxX33spWTLm2333nE5QXgWfaC8BoS5Cj9Pf',
  amount: 1, // 1 USDC
  paymentWindow: 5 * 60, // 5 minutes
  pollingInterval: 5000 // 5 seconds
};

// Create a funding wallet (required for gas fees)
const fundingWalletPrivateKey = process.env.FUNDING_WALLET_PRIVATE_KEY;
const privateKeyBytes = new Uint8Array(JSON.parse(fundingWalletPrivateKey));
const fundingWallet = Keypair.fromSecretKey(privateKeyBytes);

// Create the payment processor
const paymentProcessor = createPaymentProcessor(connection, config, fundingWallet);

Starting a Payment Flow

// Start a new payment flow
await paymentProcessor.startPaymentFlow();

// Get the temporary wallet address
const state = paymentProcessor.getState();
const tempWalletAddress = state.tempWallet?.publicKey.toString();

Checking Payment Status

// Check payment status
const result = await paymentProcessor.checkPaymentStatus();
console.log(`Token balance: ${result.tokenBalance}`);
console.log(`SOL balance: ${result.solBalance}`);
console.log(`Needs gas: ${result.needsGas}`);

// If gas is needed, fund it
if (result.needsGas) {
  const fundingResult = await paymentProcessor.fundGasFee();
  console.log(`Gas funded: ${fundingResult.success}`);
}

Processing Payment

// If payment is received, process it
if (state.status === 'received') {
  const paymentResult = await paymentProcessor.processPayment();
  console.log(`Payment processed: ${paymentResult.success}`);
  console.log(`Transaction signature: ${paymentResult.txSignature}`);
}

React Integration Example

import { useEffect, useState } from 'react';
import { Connection, Keypair } from '@solana/web3.js';
import { createPaymentProcessor, PaymentConfig, PaymentState } from '@breeeve/solana-payment-core';

function PaymentComponent() {
  const [state, setState] = useState<PaymentState | null>(null);
  const [processor, setProcessor] = useState<any>(null);
  
  useEffect(() => {
    const connection = new Connection('https://api.devnet.solana.com');
    const config: PaymentConfig = {
      sellerAddress: '9RKnB9eWaBxX33spWTLm2333nE5QXgWfaC8BoS5Cj9Pf',
      amount: 1
    };
    
    // Initialize funding wallet from environment variable
    const fundingWalletPrivateKey = process.env.NEXT_PUBLIC_FUNDING_WALLET_PRIVATE_KEY;
    const privateKeyBytes = new Uint8Array(JSON.parse(fundingWalletPrivateKey));
    const fundingWallet = Keypair.fromSecretKey(privateKeyBytes);
    
    const paymentProcessor = createPaymentProcessor(connection, config, fundingWallet);
    setProcessor(paymentProcessor);
    setState(paymentProcessor.getState());
  }, []);
  
  const startPayment = async () => {
    if (!processor) return;
    await processor.startPaymentFlow();
    setState(processor.getState());
  };
  
  const checkStatus = async () => {
    if (!processor) return;
    const result = await processor.checkPaymentStatus();
    setState(processor.getState());
    
    if (result.needsGas) {
      await processor.fundGasFee();
    }
    
    if (processor.getState().status === 'received') {
      await processor.processPayment();
      setState(processor.getState());
    }
  };
  
  return (
    <div>
      <h1>Payment Status: {state?.status}</h1>
      {state?.tempWallet && (
        <div>
          <p>Temp Wallet Address: {state.tempWallet.publicKey.toString()}</p>
          <p>Token Balance: {state.tokenBalance}</p>
          <p>SOL Balance: {state.balance}</p>
        </div>
      )}
      <button onClick={startPayment}>Start Payment</button>
      <button onClick={checkStatus}>Check Status</button>
    </div>
  );
}

API Reference

Types

PaymentConfig

interface PaymentConfig {
  sellerAddress: string;
  amount: number;
  paymentWindow?: number; // in seconds
  pollingInterval?: number; // in milliseconds
}

PaymentState

interface PaymentState {
  tempWallet: Keypair | null;
  timeLeft: number;
  status: PaymentStatus;
  balance: number;
  tokenBalance: number;
  previousTokenBalance: number;
  txSignature?: string;
  error?: string;
}

PaymentStatus

type PaymentStatus = 'setup' | 'waiting' | 'received' | 'forwarding' | 'forwarded' | 'expired';

Methods

createPaymentProcessor(connection, config, fundingWallet?)

Creates a new payment processor instance.

• connection: Solana Connection instance
• config: Payment configuration
• fundingWallet: Keypair for funding gas fees (required)

PaymentProcessor

• getState(): Get the current payment state
• startPaymentFlow(): Start a new payment flow
• resetFlow(): Reset the payment flow
• checkPaymentStatus(): Check the current payment status
• processPayment(): Process the payment if received
• fundGasFee(): Fund gas fees for the temporary wallet
• refundRemainingSol(): Refund remaining SOL to the funding wallet

Security Considerations

1. Always store the funding wallet's private key securely in environment variables
2. Never expose the private key in client-side code
3. Use appropriate network endpoints (devnet/mainnet) for your use case
4. Monitor payment windows and handle expired payments appropriately

License

MIT

Support

For support, please open an issue in the GitHub repository or contact the maintainers.