solana-priority-fee 1.0.0

package/README.md

@@ -0,0 +1,179 @@
+# solana-priority-fee
+
+Priority fee estimation for Solana with caching, real-time monitoring, and success tracking.
+
+## Install
+
+```bash
+npm install solana-priority-fee @solana/web3.js
+```
+
+## Quick Start
+
+```javascript
+const { Connection } = require('@solana/web3.js');
+const { getPriorityFee } = require('solana-priority-fee');
+
+const connection = new Connection('https://api.mainnet-beta.solana.com');
+
+// Get a fee estimate
+const fee = await getPriorityFee(connection, 'fast');
+console.log(fee); // e.g., 50000 microlamports
+```
+
+## Fee Levels
+
+| Level | Percentile | Use Case |
+|-------|------------|----------|
+| `economy` | 25th | Can wait, saving costs |
+| `medium` | 50th | Normal transactions |
+| `fast` | 75th | Need quick confirmation |
+| `urgent` | 95th | Time-critical, willing to pay |
+
+## Full API
+
+### SolanaFeeEstimator
+
+```javascript
+const { SolanaFeeEstimator } = require('solana-priority-fee');
+
+const estimator = new SolanaFeeEstimator(connection, {
+  cacheMs: 5000,        // Cache duration (default: 5s)
+  minFee: 1000,         // Minimum fee (default: 1000)
+  maxFee: 10_000_000,   // Maximum fee cap (default: 10M)
+});
+```
+
+#### getFee(options)
+
+```javascript
+const fee = await estimator.getFee({
+  level: 'fast',           // economy | medium | fast | urgent
+  accountKeys: [pubkey],   // Optional: specific accounts for better accuracy
+  useCache: true           // Optional: use cached data (default: true)
+});
+```
+
+#### getAllFees(accountKeys?)
+
+```javascript
+const fees = await estimator.getAllFees();
+// {
+//   economy: 10000,
+//   medium: 25000,
+//   fast: 50000,
+//   urgent: 150000,
+//   raw: { min, max, median, samples }
+// }
+```
+
+#### Real-time Monitoring
+
+```javascript
+// Start monitoring (updates each slot)
+await estimator.startMonitoring((fees) => {
+  console.log(`Slot ${fees.slot}: medium=${fees.medium}`);
+});
+
+// Get trend analysis
+const trend = estimator.getTrend();
+// { trend: 'rising' | 'falling' | 'stable', change: '+15.2%' }
+
+// Stop monitoring
+await estimator.stopMonitoring();
+```
+
+#### Success Tracking
+
+```javascript
+// Record transaction results
+estimator.recordResult(50000, 'fast', true);  // landed
+estimator.recordResult(50000, 'fast', false); // dropped
+
+// Get success rates per level
+const rates = estimator.getSuccessRates();
+// { fast: { total: 10, landed: 8, rate: '80.0%' }, ... }
+```
+
+#### Stats
+
+```javascript
+const stats = estimator.getStats();
+// {
+//   requests: 100,
+//   cacheHits: 85,
+//   cacheHitRate: '85.0%',
+//   isMonitoring: true,
+//   ...
+// }
+```
+
+### Helper Functions
+
+#### createPriorityFeeInstruction
+
+```javascript
+const { createPriorityFeeInstruction } = require('solana-priority-fee');
+
+const ix = await createPriorityFeeInstruction(connection, 'fast');
+
+const tx = new Transaction().add(
+  ix,
+  // ... your other instructions
+);
+```
+
+## Account-Specific Fees
+
+For more accurate estimates, pass the accounts your transaction writes to:
+
+```javascript
+const fee = await estimator.getFee({
+  level: 'fast',
+  accountKeys: [poolAddress, userTokenAccount]
+});
+```
+
+This uses `getRecentPrioritizationFees` with `lockedWritableAccounts` for account-specific data.
+
+## Example: Full Transaction
+
+```javascript
+const { Connection, Transaction, SystemProgram } = require('@solana/web3.js');
+const { createPriorityFeeInstruction, SolanaFeeEstimator } = require('solana-priority-fee');
+
+const connection = new Connection('https://api.mainnet-beta.solana.com');
+const estimator = new SolanaFeeEstimator(connection);
+
+async function sendWithPriorityFee(fromKeypair, toAddress, amount) {
+  // Get priority fee instruction
+  const priorityFeeIx = await createPriorityFeeInstruction(connection, 'fast', [toAddress]);
+  
+  // Build transaction
+  const tx = new Transaction().add(
+    priorityFeeIx,
+    SystemProgram.transfer({
+      fromPubkey: fromKeypair.publicKey,
+      toPubkey: toAddress,
+      lamports: amount
+    })
+  );
+  
+  // Send and confirm
+  const sig = await connection.sendTransaction(tx, [fromKeypair]);
+  const result = await connection.confirmTransaction(sig);
+  
+  // Track result for success rate analysis
+  estimator.recordResult(
+    priorityFeeIx.data.readBigUInt64LE(1), // fee from instruction
+    'fast',
+    result.value.err === null
+  );
+  
+  return sig;
+}
+```
+
+## License
+
+MIT

package/example.js

@@ -0,0 +1,141 @@
+const { Connection, PublicKey, Transaction, SystemProgram, Keypair } = require('@solana/web3.js');
+const { SolanaFeeEstimator, getPriorityFee, createPriorityFeeInstruction } = require('./src/index');
+
+// Connect to Solana
+const connection = new Connection('https://api.mainnet-beta.solana.com');
+
+async function basicUsage() {
+  console.log('\n=== Basic Usage ===\n');
+  
+  // Quick one-liner
+  const fee = await getPriorityFee(connection, 'fast');
+  console.log('Quick estimate (fast):', fee, 'microlamports');
+  
+  // Get all levels
+  const estimator = new SolanaFeeEstimator(connection);
+  const allFees = await estimator.getAllFees();
+  console.log('All fee levels:', allFees);
+}
+
+async function accountSpecificFees() {
+  console.log('\n=== Account-Specific Fees ===\n');
+  
+  // For specific accounts you're writing to (more accurate)
+  const poolAddress = new PublicKey('8BnEgHoWFysVcuFFX7QztDmzuH8r5ZFvyP3sYwn1XTh6');
+  
+  const estimator = new SolanaFeeEstimator(connection);
+  const fee = await estimator.getFee({
+    level: 'fast',
+    accountKeys: [poolAddress]
+  });
+  
+  console.log('Account-specific fee:', fee, 'microlamports');
+}
+
+async function withCaching() {
+  console.log('\n=== Caching Demo ===\n');
+  
+  const estimator = new SolanaFeeEstimator(connection, {
+    cacheMs: 10000  // 10 second cache
+  });
+  
+  // First call - fetches from network
+  console.time('First call');
+  await estimator.getFee({ level: 'medium' });
+  console.timeEnd('First call');
+  
+  // Second call - from cache
+  console.time('Second call (cached)');
+  await estimator.getFee({ level: 'medium' });
+  console.timeEnd('Second call (cached)');
+  
+  console.log('Stats:', estimator.getStats());
+}
+
+async function realtimeMonitoring() {
+  console.log('\n=== Real-time Monitoring ===\n');
+  
+  const estimator = new SolanaFeeEstimator(connection);
+  
+  // Start monitoring (updates on each slot)
+  await estimator.startMonitoring((fees) => {
+    console.log(`Slot ${fees.slot}: economy=${fees.economy}, medium=${fees.medium}, fast=${fees.fast}`);
+  });
+  
+  // Let it run for 30 seconds
+  console.log('Monitoring for 30 seconds...');
+  await new Promise(resolve => setTimeout(resolve, 30000));
+  
+  // Check trend
+  console.log('Trend:', estimator.getTrend());
+  
+  // Stop monitoring
+  await estimator.stopMonitoring();
+}
+
+async function buildTransaction() {
+  console.log('\n=== Building a Transaction ===\n');
+  
+  // Get priority fee instruction
+  const priorityFeeIx = await createPriorityFeeInstruction(connection, 'fast');
+  
+  // Build your transaction
+  const tx = new Transaction().add(
+    priorityFeeIx,
+    // ... add your other instructions here
+    // SystemProgram.transfer({ ... })
+  );
+  
+  console.log('Transaction built with priority fee instruction');
+  console.log('Instructions:', tx.instructions.length);
+}
+
+async function successTracking() {
+  console.log('\n=== Success Rate Tracking ===\n');
+  
+  const estimator = new SolanaFeeEstimator(connection);
+  
+  // Simulate some transaction results
+  // In real usage, call this after each transaction confirms/fails
+  estimator.recordResult(50000, 'fast', true);   // landed
+  estimator.recordResult(50000, 'fast', true);   // landed
+  estimator.recordResult(50000, 'fast', false);  // dropped
+  estimator.recordResult(10000, 'economy', true);
+  estimator.recordResult(10000, 'economy', false);
+  estimator.recordResult(10000, 'economy', false);
+  
+  console.log('Success rates:', estimator.getSuccessRates());
+}
+
+async function customConfiguration() {
+  console.log('\n=== Custom Configuration ===\n');
+  
+  const estimator = new SolanaFeeEstimator(connection, {
+    cacheMs: 3000,           // 3 second cache
+    minFee: 5000,            // Minimum 5000 microlamports
+    maxFee: 5_000_000,       // Cap at 5M microlamports
+  });
+  
+  const fees = await estimator.getAllFees();
+  console.log('Fees with custom config:', fees);
+}
+
+// Run examples
+async function main() {
+  try {
+    await basicUsage();
+    await accountSpecificFees();
+    await withCaching();
+    await buildTransaction();
+    await successTracking();
+    await customConfiguration();
+    
+    // Uncomment to run real-time monitoring (takes 30 seconds)
+    // await realtimeMonitoring();
+    
+  } catch (error) {
+    console.error('Error:', error);
+  }
+}
+
+main();

package/index.js

@@ -0,0 +1,326 @@
+const { Connection } = require('@solana/web3.js');
+
+/**
+ * SolanaFeeEstimator - Priority fee estimation with caching and monitoring
+ */
+class SolanaFeeEstimator {
+  constructor(connection, options = {}) {
+    this.connection = connection;
+    
+    // Configuration
+    this.config = {
+      cacheMs: options.cacheMs ?? 5000,           // Cache duration
+      sampleSize: options.sampleSize ?? 150,       // Recent slots to analyze
+      minFee: options.minFee ?? 1000,              // Minimum fee (microlamports)
+      maxFee: options.maxFee ?? 10_000_000,        // Maximum fee cap
+      ...options
+    };
+    
+    // Percentiles for each level
+    this.levels = {
+      economy: 0.25,
+      medium: 0.50,
+      fast: 0.75,
+      urgent: 0.95
+    };
+    
+    // Cache
+    this.cache = {
+      global: null,
+      accounts: new Map(),
+      lastUpdate: 0
+    };
+    
+    // Stats tracking
+    this.stats = {
+      requests: 0,
+      cacheHits: 0,
+      estimates: [],  // { level, fee, timestamp }
+      confirmed: [],  // { level, fee, landed, timestamp }
+    };
+    
+    // WebSocket subscription
+    this.subscription = null;
+    this.realtimeFees = [];
+  }
+
+  /**
+   * Get priority fee recommendation
+   */
+  async getFee(options = {}) {
+    const {
+      level = 'medium',
+      accountKeys = [],
+      useCache = true
+    } = options;
+    
+    this.stats.requests++;
+    
+    // Check cache
+    const cacheKey = accountKeys.length > 0 
+      ? accountKeys.sort().join(',') 
+      : 'global';
+    
+    if (useCache && this._isCacheValid(cacheKey)) {
+      this.stats.cacheHits++;
+      return this._calculateFee(this._getCachedFees(cacheKey), level);
+    }
+    
+    // Fetch fresh data
+    const fees = await this._fetchFees(accountKeys);
+    this._updateCache(cacheKey, fees);
+    
+    const estimate = this._calculateFee(fees, level);
+    
+    // Track estimate
+    this.stats.estimates.push({
+      level,
+      fee: estimate,
+      timestamp: Date.now()
+    });
+    
+    return estimate;
+  }
+
+  /**
+   * Get all fee levels at once
+   */
+  async getAllFees(accountKeys = []) {
+    const fees = await this._fetchFees(accountKeys);
+    
+    return {
+      economy: this._calculateFee(fees, 'economy'),
+      medium: this._calculateFee(fees, 'medium'),
+      fast: this._calculateFee(fees, 'fast'),
+      urgent: this._calculateFee(fees, 'urgent'),
+      raw: {
+        min: fees.length > 0 ? fees[0] : this.config.minFee,
+        max: fees.length > 0 ? fees[fees.length - 1] : this.config.minFee,
+        median: fees.length > 0 ? fees[Math.floor(fees.length / 2)] : this.config.minFee,
+        samples: fees.length
+      }
+    };
+  }
+
+  /**
+   * Start real-time monitoring via WebSocket
+   */
+  async startMonitoring(callback) {
+    if (this.subscription) {
+      console.warn('Already monitoring');
+      return;
+    }
+    
+    // Subscribe to slot changes
+    this.subscription = this.connection.onSlotChange(async (slotInfo) => {
+      try {
+        const fees = await this._fetchFees([]);
+        this._updateCache('global', fees);
+        
+        const allFees = {
+          slot: slotInfo.slot,
+          economy: this._calculateFee(fees, 'economy'),
+          medium: this._calculateFee(fees, 'medium'),
+          fast: this._calculateFee(fees, 'fast'),
+          urgent: this._calculateFee(fees, 'urgent')
+        };
+        
+        this.realtimeFees.push(allFees);
+        
+        // Keep last 100 samples
+        if (this.realtimeFees.length > 100) {
+          this.realtimeFees.shift();
+        }
+        
+        if (callback) callback(allFees);
+      } catch (err) {
+        console.error('Monitoring error:', err);
+      }
+    });
+    
+    console.log('Fee monitoring started');
+  }
+
+  /**
+   * Stop real-time monitoring
+   */
+  async stopMonitoring() {
+    if (this.subscription) {
+      await this.connection.removeSlotChangeListener(this.subscription);
+      this.subscription = null;
+      console.log('Fee monitoring stopped');
+    }
+  }
+
+  /**
+   * Record transaction result for accuracy tracking
+   */
+  recordResult(fee, level, landed) {
+    this.stats.confirmed.push({
+      fee,
+      level,
+      landed,
+      timestamp: Date.now()
+    });
+    
+    // Keep last 1000 results
+    if (this.stats.confirmed.length > 1000) {
+      this.stats.confirmed.shift();
+    }
+  }
+
+  /**
+   * Get success rates per level
+   */
+  getSuccessRates() {
+    const rates = {};
+    
+    for (const level of Object.keys(this.levels)) {
+      const results = this.stats.confirmed.filter(r => r.level === level);
+      const landed = results.filter(r => r.landed).length;
+      
+      rates[level] = {
+        total: results.length,
+        landed,
+        rate: results.length > 0 ? (landed / results.length * 100).toFixed(1) + '%' : 'N/A'
+      };
+    }
+    
+    return rates;
+  }
+
+  /**
+   * Get trend analysis
+   */
+  getTrend() {
+    if (this.realtimeFees.length < 10) {
+      return { trend: 'insufficient_data', change: 0 };
+    }
+    
+    const recent = this.realtimeFees.slice(-10);
+    const older = this.realtimeFees.slice(-20, -10);
+    
+    if (older.length === 0) {
+      return { trend: 'insufficient_data', change: 0 };
+    }
+    
+    const recentAvg = recent.reduce((sum, f) => sum + f.medium, 0) / recent.length;
+    const olderAvg = older.reduce((sum, f) => sum + f.medium, 0) / older.length;
+    
+    const change = ((recentAvg - olderAvg) / olderAvg) * 100;
+    
+    let trend = 'stable';
+    if (change > 20) trend = 'rising';
+    else if (change < -20) trend = 'falling';
+    
+    return {
+      trend,
+      change: change.toFixed(1) + '%',
+      recentAvg: Math.round(recentAvg),
+      olderAvg: Math.round(olderAvg)
+    };
+  }
+
+  /**
+   * Get cache and request statistics
+   */
+  getStats() {
+    return {
+      requests: this.stats.requests,
+      cacheHits: this.stats.cacheHits,
+      cacheHitRate: this.stats.requests > 0 
+        ? ((this.stats.cacheHits / this.stats.requests) * 100).toFixed(1) + '%' 
+        : 'N/A',
+      estimatesTracked: this.stats.estimates.length,
+      resultsTracked: this.stats.confirmed.length,
+      realtimeSamples: this.realtimeFees.length,
+      isMonitoring: this.subscription !== null
+    };
+  }
+
+  // Private methods
+
+  async _fetchFees(accountKeys) {
+    const options = accountKeys.length > 0 
+      ? { lockedWritableAccounts: accountKeys }
+      : {};
+    
+    const fees = await this.connection.getRecentPrioritizationFees(options);
+    
+    return fees
+      .map(f => f.prioritizationFee)
+      .filter(f => f > 0)
+      .sort((a, b) => a - b);
+  }
+
+  _calculateFee(fees, level) {
+    if (fees.length === 0) return this.config.minFee;
+    
+    const percentile = this.levels[level] ?? 0.5;
+    const index = Math.floor(fees.length * percentile);
+    const fee = fees[Math.min(index, fees.length - 1)];
+    
+    return Math.max(this.config.minFee, Math.min(fee, this.config.maxFee));
+  }
+
+  _isCacheValid(key) {
+    const now = Date.now();
+    
+    if (key === 'global') {
+      return this.cache.global && (now - this.cache.lastUpdate) < this.config.cacheMs;
+    }
+    
+    const cached = this.cache.accounts.get(key);
+    return cached && (now - cached.timestamp) < this.config.cacheMs;
+  }
+
+  _getCachedFees(key) {
+    if (key === 'global') return this.cache.global;
+    return this.cache.accounts.get(key)?.fees ?? [];
+  }
+
+  _updateCache(key, fees) {
+    const now = Date.now();
+    
+    if (key === 'global') {
+      this.cache.global = fees;
+      this.cache.lastUpdate = now;
+    } else {
+      this.cache.accounts.set(key, { fees, timestamp: now });
+      
+      // Limit account cache size
+      if (this.cache.accounts.size > 100) {
+        const oldest = [...this.cache.accounts.entries()]
+          .sort((a, b) => a[1].timestamp - b[1].timestamp)[0];
+        this.cache.accounts.delete(oldest[0]);
+      }
+    }
+  }
+}
+
+/**
+ * Helper function for quick one-off estimates
+ */
+async function getPriorityFee(connection, level = 'medium', accountKeys = []) {
+  const estimator = new SolanaFeeEstimator(connection);
+  return estimator.getFee({ level, accountKeys });
+}
+
+/**
+ * Create compute budget instruction with estimated fee
+ */
+async function createPriorityFeeInstruction(connection, level = 'medium', accountKeys = []) {
+  const { ComputeBudgetProgram } = require('@solana/web3.js');
+  
+  const fee = await getPriorityFee(connection, level, accountKeys);
+  
+  return ComputeBudgetProgram.setComputeUnitPrice({
+    microLamports: fee
+  });
+}
+
+module.exports = {
+  SolanaFeeEstimator,
+  getPriorityFee,
+  createPriorityFeeInstruction
+};

package/package.json

@@ -0,0 +1,21 @@
+{
+  "name": "solana-priority-fee",
+  "version": "1.0.0",
+  "description": "Priority fee estimation for Solana with caching, monitoring, and success tracking",
+  "main": "src/index.js",
+  "scripts": {
+    "example": "node example.js"
+  },
+  "keywords": [
+    "solana",
+    "priority-fee",
+    "transaction",
+    "web3",
+    "blockchain"
+  ],
+  "author": "",
+  "license": "MIT",
+  "dependencies": {
+    "@solana/web3.js": "^1.98.4"
+  }
+}