fema-pf-calc 1.0.0

package/README.md

@@ -0,0 +1,265 @@
+# FEMA — Fee Estimation & Management for Solana
+
+FEMA is a TypeScript SDK that calculates optimal priority fees for Solana transactions in real time. Instead of hardcoding a fee or guessing, developers install FEMA and call one function to get the right fee based on what the network is actually paying right now.
+
+Supports **mainnet-beta** and **devnet**.
+
+---
+
+## The Problem
+
+Every Solana transaction can include a priority fee — a tip paid to validators to land the transaction faster. Set it too low and your transaction gets stuck or dropped. Set it too high and you overpay.
+
+The fee you need also depends on what kind of transaction you are sending. A Jupiter swap competes with other Jupiter swaps. An NFT mint competes with other NFT mints. They are not in the same queue, so they should not use the same fee.
+
+FEMA solves this by scanning recent blocks, building a real fee distribution, and giving you a number you can use directly.
+
+---
+
+## How It Works
+
+1. FEMA connects to a Solana RPC and fetches data from the last 30 blocks
+2. For each transaction in those blocks it extracts the fee paid in microLamports per compute unit
+3. It sorts these into a distribution and computes percentiles (p25, p50, p75)
+4. If you specify a protocol or pass your transaction, it filters the data to only transactions that used the same programs as yours
+5. It returns the fee at the percentile matching your chosen speed and strategy
+
+Results are cached for 5–10 seconds to avoid hammering the RPC on every call.
+
+---
+
+## Installation
+
+```bash
+npm install fema-pf-calc
+```
+
+---
+
+## Quick Start
+
+```ts
+import { init, estimateFee } from "fema-pf-calc";
+import { ComputeBudgetProgram } from "@solana/web3.js";
+
+// Configure once at app startup
+init({
+  cluster: "mainnet-beta", // or "devnet"
+  rpcUrl: "https://mainnet.helius-rpc.com/?api-key=YOUR_KEY", // optional override
+});
+
+// Get the recommended fee
+const { fee } = await estimateFee({ speed: "fast", strategy: "balanced" });
+
+// Apply it to your transaction
+const priorityIx = ComputeBudgetProgram.setComputeUnitPrice({
+  microLamports: fee,
+});
+```
+
+That is all a developer needs to do. No RPC calls, no math, no guessing.
+
+---
+
+## Options
+
+```ts
+const result = await estimateFee({
+  speed:        "slow" | "medium" | "fast",             // how urgently you need it to land
+  strategy:     "cheap" | "balanced" | "aggressive",    // how competitive to be
+  protocol:     "jupiter" | "raydium" | "orca" | "nft" | "pumpfun" | "openbook" | "system" | "token",
+  transaction:  myTransaction,   // pass your actual tx for automatic protocol detection
+  maxFee:       500_000,         // optional cap in microLamports
+  includeStats: true,            // include full distribution in response
+});
+```
+
+### Speed
+
+| Speed | Percentile | What it means |
+|-------|-----------|---------------|
+| `slow` | p25 | Cheaper. May take a few blocks to land. |
+| `medium` | p50 | Balanced. Lands within a couple of blocks. |
+| `fast` | p75 | More expensive. Designed to land in the next block. |
+
+### Strategy
+
+| Strategy | Adjustment | What it means |
+|----------|-----------|---------------|
+| `cheap` | −10 percentile points | Slightly undercut the target. Risk: might not land if the network spikes. |
+| `balanced` | none | Hit the target exactly. Safe default for most use cases. |
+| `aggressive` | +15 percentile points | Slightly overpay to guarantee landing. |
+
+---
+
+## Protocol-Aware Estimation
+
+The most powerful feature of FEMA. When you specify a protocol, FEMA filters the fee data to only transactions that used the same programs — giving you a fee based on your actual competition, not the whole network.
+
+```ts
+// Jupiter swap
+const { fee: swapFee } = await estimateFee({ speed: "fast", protocol: "jupiter" });
+
+// NFT mint
+const { fee: nftFee } = await estimateFee({ speed: "fast", protocol: "nft" });
+
+// Pump.fun trade
+const { fee: pumpFee } = await estimateFee({ speed: "fast", protocol: "pumpfun" });
+```
+
+Alternatively, pass your actual transaction and FEMA will detect the protocol automatically:
+
+```ts
+const { fee } = await estimateFee({
+  speed: "fast",
+  transaction: mySwapTransaction,
+});
+```
+
+### Supported Protocols
+
+| Protocol | Programs Included |
+|----------|------------------|
+| `jupiter` | Jupiter V4, Jupiter V6 |
+| `raydium` | Raydium AMM V4, AMM V5, CLMM |
+| `orca` | Orca Whirlpool, Orca V1 |
+| `nft` | Token Metadata, Candy Machine V2/V3, Auction House |
+| `pumpfun` | Pump.fun |
+| `openbook` | OpenBook V1, OpenBook V2 |
+| `system` | System Program (SOL transfers) |
+| `token` | Token Program, Token 2022, Associated Token Program |
+
+---
+
+## Response
+
+```ts
+{
+  fee: 253637,              // microLamports per CU — pass directly to setComputeUnitPrice
+  congestion: "high",       // "low" | "medium" | "high"
+  percentileUsed: 75,       // which percentile was used
+  sampleSize: 1203,         // number of transactions analyzed
+  programFiltered: true,    // true = fee is based on your protocol's txs specifically
+
+  // only included when includeStats: true
+  stats: {
+    avgFee: 180000,
+    medianFee: 28844,
+    distribution: {
+      p10: 1200,
+      p25: 5011,
+      p50: 28844,
+      p75: 253637,
+      p90: 480000,
+      p95: 820000,
+      p99: 2100000,
+    }
+  }
+}
+```
+
+The `fee` value is in **microLamports per compute unit** — the exact unit that `ComputeBudgetProgram.setComputeUnitPrice` expects. No conversion needed.
+
+---
+
+## Configuration
+
+```ts
+init({
+  cluster:         "mainnet-beta",          // "mainnet-beta" | "devnet" (default: "mainnet-beta")
+  rpcUrl:          "https://your-rpc.com",  // optional — overrides the cluster default
+  cacheDurationMs: 7000,                    // how long to cache results in ms (default: 7000)
+});
+```
+
+### Cluster RPC defaults
+
+| Cluster | Default RPC |
+|---------|-------------|
+| `mainnet-beta` | `https://api.mainnet-beta.solana.com` |
+| `devnet` | `https://api.devnet.solana.com` |
+
+Or configure via `.env`:
+
+```env
+# Network: mainnet-beta (default) or devnet
+SOLANA_CLUSTER=mainnet-beta
+
+# Optional: override the RPC URL for the selected cluster
+# SOLANA_RPC_URL=https://your-custom-rpc.com
+
+# How long to cache fee data in milliseconds (default: 7000)
+CACHE_DURATION_MS=7000
+
+# Express server port (default: 3000)
+PORT=3000
+```
+
+---
+
+## Test Script
+
+Run a live fee report from the terminal:
+
+```bash
+# Mainnet (default)
+ts-node test-fees.ts
+
+# Devnet
+ts-node test-fees.ts --network devnet
+ts-node test-fees.ts --network=devnet
+
+# Via env var
+SOLANA_CLUSTER=devnet ts-node test-fees.ts
+```
+
+---
+
+## Optional HTTP Server
+
+FEMA includes an Express server for teams who want to expose fee estimation over HTTP instead of importing the package directly.
+
+```bash
+npm run server
+```
+
+| Endpoint | Description |
+|----------|-------------|
+| `GET /health` | Check server status and active RPC URL |
+| `GET /estimate-fee?speed=fast&strategy=balanced` | Get a fee recommendation |
+| `GET /stats` | Get fee with full distribution stats |
+
+---
+
+## RPC Recommendations
+
+The public Solana RPC endpoints rate-limit aggressively. For reliable results use a private RPC:
+
+- [Helius](https://helius.dev) — free tier available
+- [QuickNode](https://quicknode.com)
+- [Alchemy](https://alchemy.com)
+
+---
+
+## Project Structure
+
+```
+src/
+├── index.ts              # SDK entry point — estimateFee() and init()
+├── server.ts             # Optional Express HTTP server
+├── types.ts              # TypeScript types and interfaces
+├── config.ts             # Configuration and cluster RPC resolution
+├── protocols.ts          # Known protocol registry (Jupiter, Raydium, etc.)
+├── engine/
+│   └── feeCalculator.ts  # Percentile math, strategy modifiers, outlier filtering
+└── services/
+    ├── solana.ts         # RPC data fetching and block scanning
+    ├── cache.ts          # In-memory TTL cache
+    └── database.ts       # In-memory snapshot store and fallback
+```
+
+---
+
+## License
+
+MIT

package/dist/config.d.ts

@@ -0,0 +1,6 @@
+import { FemaConfig, SolanaCluster } from "./types";
+declare const CLUSTER_RPC: Record<SolanaCluster, string>;
+export declare function init(overrides: Partial<FemaConfig>): void;
+export { CLUSTER_RPC };
+export declare function getConfig(): FemaConfig;
+//# sourceMappingURL=config.d.ts.map

package/dist/config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AAEpD,QAAA,MAAM,WAAW,EAAE,MAAM,CAAC,aAAa,EAAE,MAAM,CAG9C,CAAC;AAsBF,wBAAgB,IAAI,CAAC,SAAS,EAAE,OAAO,CAAC,UAAU,CAAC,GAAG,IAAI,CAIzD;AAED,OAAO,EAAE,WAAW,EAAE,CAAC;AAEvB,wBAAgB,SAAS,IAAI,UAAU,CAEtC"}

package/dist/config.js

@@ -0,0 +1,35 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CLUSTER_RPC = void 0;
+exports.init = init;
+exports.getConfig = getConfig;
+const CLUSTER_RPC = {
+    "mainnet-beta": "https://api.mainnet-beta.solana.com",
+    "devnet": "https://api.devnet.solana.com",
+};
+exports.CLUSTER_RPC = CLUSTER_RPC;
+const DEFAULT_CACHE_MS = 7000;
+function resolveCluster() {
+    const raw = process.env.SOLANA_CLUSTER ?? "mainnet-beta";
+    if (raw === "devnet")
+        return "devnet";
+    return "mainnet-beta";
+}
+function resolveRpc(cluster) {
+    return process.env.SOLANA_RPC_URL ?? CLUSTER_RPC[cluster];
+}
+const defaultCluster = resolveCluster();
+let _config = {
+    cluster: defaultCluster,
+    rpcUrl: resolveRpc(defaultCluster),
+    cacheDurationMs: Number(process.env.CACHE_DURATION_MS ?? DEFAULT_CACHE_MS),
+};
+function init(overrides) {
+    const cluster = overrides.cluster ?? _config.cluster;
+    const rpcUrl = overrides.rpcUrl ?? CLUSTER_RPC[cluster];
+    _config = { ..._config, ...overrides, cluster, rpcUrl };
+}
+function getConfig() {
+    return _config;
+}
+//# sourceMappingURL=config.js.map

package/dist/config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.js","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":";;;AA2BA,oBAIC;AAID,8BAEC;AAnCD,MAAM,WAAW,GAAkC;IACjD,cAAc,EAAE,qCAAqC;IACrD,QAAQ,EAAE,+BAA+B;CAC1C,CAAC;AA4BO,kCAAW;AA1BpB,MAAM,gBAAgB,GAAG,IAAI,CAAC;AAE9B,SAAS,cAAc;IACrB,MAAM,GAAG,GAAG,OAAO,CAAC,GAAG,CAAC,cAAc,IAAI,cAAc,CAAC;IACzD,IAAI,GAAG,KAAK,QAAQ;QAAE,OAAO,QAAQ,CAAC;IACtC,OAAO,cAAc,CAAC;AACxB,CAAC;AAED,SAAS,UAAU,CAAC,OAAsB;IACxC,OAAO,OAAO,CAAC,GAAG,CAAC,cAAc,IAAI,WAAW,CAAC,OAAO,CAAC,CAAC;AAC5D,CAAC;AAED,MAAM,cAAc,GAAG,cAAc,EAAE,CAAC;AAExC,IAAI,OAAO,GAAe;IACxB,OAAO,EAAE,cAAc;IACvB,MAAM,EAAE,UAAU,CAAC,cAAc,CAAC;IAClC,eAAe,EAAE,MAAM,CAAC,OAAO,CAAC,GAAG,CAAC,iBAAiB,IAAI,gBAAgB,CAAC;CAC3E,CAAC;AAEF,SAAgB,IAAI,CAAC,SAA8B;IACjD,MAAM,OAAO,GAAG,SAAS,CAAC,OAAO,IAAI,OAAO,CAAC,OAAO,CAAC;IACrD,MAAM,MAAM,GAAG,SAAS,CAAC,MAAM,IAAI,WAAW,CAAC,OAAO,CAAC,CAAC;IACxD,OAAO,GAAG,EAAE,GAAG,OAAO,EAAE,GAAG,SAAS,EAAE,OAAO,EAAE,MAAM,EAAE,CAAC;AAC1D,CAAC;AAID,SAAgB,SAAS;IACvB,OAAO,OAAO,CAAC;AACjB,CAAC"}

package/dist/engine/feeCalculator.d.ts

@@ -0,0 +1,19 @@
+import { Speed, Strategy, FeeSnapshot, FeeEntry } from "../types";
+/**
+ * Filter a fee entry dataset to entries that share at least one program
+ * with the target transaction. Falls back to the full dataset if too few matches.
+ */
+export declare function filterByPrograms(entries: FeeEntry[], programIds: string[]): {
+    fees: number[];
+    programFiltered: boolean;
+};
+export declare function percentile(sorted: number[], p: number): number;
+export declare function average(values: number[]): number;
+export interface CalcResult {
+    fee: number;
+    percentileUsed: number;
+    snapshot: FeeSnapshot;
+    rawFees: number[];
+}
+export declare function calculateFee(rawFees: number[], speed: Speed, strategy: Strategy, maxFee?: number, computeUnits?: number): CalcResult;
+//# sourceMappingURL=feeCalculator.d.ts.map

package/dist/engine/feeCalculator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"feeCalculator.d.ts","sourceRoot":"","sources":["../../src/engine/feeCalculator.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,KAAK,EACL,QAAQ,EAER,WAAW,EACX,QAAQ,EACT,MAAM,UAAU,CAAC;AAIlB;;;GAGG;AACH,wBAAgB,gBAAgB,CAC9B,OAAO,EAAE,QAAQ,EAAE,EACnB,UAAU,EAAE,MAAM,EAAE,GACnB;IAAE,IAAI,EAAE,MAAM,EAAE,CAAC;IAAC,eAAe,EAAE,OAAO,CAAA;CAAE,CAgB9C;AAID,wBAAgB,UAAU,CAAC,MAAM,EAAE,MAAM,EAAE,EAAE,CAAC,EAAE,MAAM,GAAG,MAAM,CAO9D;AAED,wBAAgB,OAAO,CAAC,MAAM,EAAE,MAAM,EAAE,GAAG,MAAM,CAGhD;AA6BD,MAAM,WAAW,UAAU;IACzB,GAAG,EAAE,MAAM,CAAC;IACZ,cAAc,EAAE,MAAM,CAAC;IACvB,QAAQ,EAAE,WAAW,CAAC;IACtB,OAAO,EAAE,MAAM,EAAE,CAAC;CACnB;AAED,wBAAgB,YAAY,CAC1B,OAAO,EAAE,MAAM,EAAE,EACjB,KAAK,EAAE,KAAK,EACZ,QAAQ,EAAE,QAAQ,EAClB,MAAM,CAAC,EAAE,MAAM,EACf,YAAY,CAAC,EAAE,MAAM,GACpB,UAAU,CA6CZ"}

package/dist/engine/feeCalculator.js

@@ -0,0 +1,98 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.filterByPrograms = filterByPrograms;
+exports.percentile = percentile;
+exports.average = average;
+exports.calculateFee = calculateFee;
+const MIN_PROGRAM_SAMPLES = 15;
+/**
+ * Filter a fee entry dataset to entries that share at least one program
+ * with the target transaction. Falls back to the full dataset if too few matches.
+ */
+function filterByPrograms(entries, programIds) {
+    if (programIds.length === 0) {
+        return { fees: entries.map((e) => e.fee), programFiltered: false };
+    }
+    const targetSet = new Set(programIds);
+    const matched = entries.filter((e) => e.programs.some((p) => targetSet.has(p)));
+    if (matched.length >= MIN_PROGRAM_SAMPLES) {
+        return { fees: matched.map((e) => e.fee), programFiltered: true };
+    }
+    // Not enough program-specific samples — fall back to full network data
+    return { fees: entries.map((e) => e.fee), programFiltered: false };
+}
+// ─── Percentile helpers ───────────────────────────────────────────────────────
+function percentile(sorted, p) {
+    if (sorted.length === 0)
+        return 0;
+    const idx = (p / 100) * (sorted.length - 1);
+    const lower = Math.floor(idx);
+    const upper = Math.ceil(idx);
+    if (lower === upper)
+        return sorted[lower];
+    return sorted[lower] + (sorted[upper] - sorted[lower]) * (idx - lower);
+}
+function average(values) {
+    if (values.length === 0)
+        return 0;
+    return values.reduce((a, b) => a + b, 0) / values.length;
+}
+// ─── Speed → base percentile ─────────────────────────────────────────────────
+const SPEED_PERCENTILE = {
+    slow: 25,
+    medium: 50,
+    fast: 75,
+};
+// ─── Strategy → percentile delta ─────────────────────────────────────────────
+const STRATEGY_DELTA = {
+    cheap: -10,
+    balanced: 0,
+    aggressive: 15,
+};
+// ─── Congestion thresholds (microLamports avg) ────────────────────────────────
+function deriveCongestion(medianFee, txCount) {
+    // Use median (not avg) so MEV outliers don't inflate congestion level
+    if (medianFee > 100000 || txCount > 1000)
+        return "high";
+    if (medianFee > 10000 || txCount > 300)
+        return "medium";
+    return "low";
+}
+function calculateFee(rawFees, speed, strategy, maxFee, computeUnits) {
+    let fees = rawFees.length > 0 ? [...rawFees].sort((a, b) => a - b) : [1];
+    // Strip MEV/bot outliers above p99 so they don't distort p75/avg
+    if (fees.length >= 10) {
+        const cap = percentile(fees, 99);
+        fees = fees.filter((f) => f <= cap);
+    }
+    const basePercentile = SPEED_PERCENTILE[speed];
+    const delta = STRATEGY_DELTA[strategy];
+    const targetPercentile = Math.max(1, Math.min(99, basePercentile + delta));
+    let fee = Math.round(percentile(fees, targetPercentile));
+    const avgFee = Math.round(average(fees));
+    const medianFee = Math.round(percentile(fees, 50));
+    const p25Fee = Math.round(percentile(fees, 25));
+    const p75Fee = Math.round(percentile(fees, 75));
+    // Scale by compute units if provided (fee is per-CU; default CU = 200_000)
+    if (computeUnits && computeUnits !== 200000) {
+        fee = Math.round(fee * (computeUnits / 200000));
+    }
+    // Apply maxFee cap
+    if (maxFee !== undefined && fee > maxFee) {
+        fee = maxFee;
+    }
+    // Ensure a sensible minimum (1 microLamport)
+    fee = Math.max(1, fee);
+    const congestionLevel = deriveCongestion(medianFee, fees.length);
+    const snapshot = {
+        timestamp: new Date().toISOString(),
+        avgFee,
+        medianFee,
+        p25Fee,
+        p75Fee,
+        congestionLevel,
+        txCount: fees.length,
+    };
+    return { fee, percentileUsed: targetPercentile, snapshot, rawFees: fees };
+}
+//# sourceMappingURL=feeCalculator.js.map

package/dist/engine/feeCalculator.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"feeCalculator.js","sourceRoot":"","sources":["../../src/engine/feeCalculator.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -0,0 +1,7 @@
+import { FemaConfig, EstimateFeeOptions, EstimateFeeResult } from "./types";
+export type { EstimateFeeOptions, EstimateFeeResult, FemaConfig, FeeSnapshot, FeeStats, FeeEntry, Speed, Strategy, CongestionLevel, SolanaCluster, } from "./types";
+export type { Protocol } from "./protocols";
+export { PROTOCOLS } from "./protocols";
+export declare function init(config: Partial<FemaConfig>): void;
+export declare function estimateFee(options?: EstimateFeeOptions): Promise<EstimateFeeResult>;
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,kBAAkB,EAAE,iBAAiB,EAA6B,MAAM,SAAS,CAAC;AAiBvG,YAAY,EACV,kBAAkB,EAClB,iBAAiB,EACjB,UAAU,EACV,WAAW,EACX,QAAQ,EACR,QAAQ,EACR,KAAK,EACL,QAAQ,EACR,eAAe,EACf,aAAa,GACd,MAAM,SAAS,CAAC;AACjB,YAAY,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AAC5C,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAMxC,wBAAgB,IAAI,CAAC,MAAM,EAAE,OAAO,CAAC,UAAU,CAAC,GAAG,IAAI,CAQtD;AAID,wBAAsB,WAAW,CAC/B,OAAO,GAAE,kBAAuB,GAC/B,OAAO,CAAC,iBAAiB,CAAC,CAsE5B"}

package/dist/index.js

@@ -0,0 +1,114 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PROTOCOLS = void 0;
+exports.init = init;
+exports.estimateFee = estimateFee;
+const config_1 = require("./config");
+const cache_1 = require("./services/cache");
+const solana_1 = require("./services/solana");
+const protocols_1 = require("./protocols");
+const database_1 = require("./services/database");
+const feeCalculator_1 = require("./engine/feeCalculator");
+var protocols_2 = require("./protocols");
+Object.defineProperty(exports, "PROTOCOLS", { enumerable: true, get: function () { return protocols_2.PROTOCOLS; } });
+// ─── SDK initialisation ───────────────────────────────────────────────────────
+let _started = false;
+function init(config) {
+    (0, config_1.init)(config);
+    (0, solana_1.resetConnection)();
+    if (!_started) {
+        (0, database_1.startPersistedInterval)(() => (0, database_1.getLatestSnapshotSync)(), 15000);
+        _started = true;
+    }
+}
+// ─── Primary API ──────────────────────────────────────────────────────────────
+async function estimateFee(options = {}) {
+    const { speed = "medium", strategy = "balanced", includeStats = false, maxFee, transaction, protocol, } = options;
+    // 1. Resolve program IDs from protocol shorthand or raw transaction
+    let programIds = [];
+    if (protocol) {
+        programIds = (0, protocols_1.getProtocolProgramIds)(protocol);
+    }
+    else if (transaction) {
+        const txPrograms = (0, solana_1.extractProgramIds)(transaction);
+        programIds = txPrograms;
+        // Auto-detect protocol from the transaction's programs (for logging)
+        const detected = (0, protocols_1.detectProtocol)(txPrograms);
+        if (detected) {
+            // Expand to full protocol program list for better coverage
+            programIds = (0, protocols_1.getProtocolProgramIds)(detected);
+        }
+    }
+    const needsProgramData = programIds.length > 0;
+    const computeUnits = transaction ? (0, solana_1.estimateComputeUnits)(transaction) : undefined;
+    // 2. Try in-memory cache first (only reuse if it has program data when needed)
+    const cached = (0, cache_1.getCached)();
+    const cacheHasProgramData = cached?.entries.some((e) => e.programs.length > 0) ?? false;
+    if (cached && (!needsProgramData || cacheHasProgramData)) {
+        const { fees, programFiltered } = (0, feeCalculator_1.filterByPrograms)(cached.entries, programIds);
+        const { fee, percentileUsed, snapshot, rawFees } = (0, feeCalculator_1.calculateFee)(fees, speed, strategy, maxFee, computeUnits);
+        return buildResult(fee, snapshot, percentileUsed, rawFees, includeStats, programFiltered);
+    }
+    // 3. Fetch fresh data from Solana RPC
+    let entries = [];
+    let fromFallback = false;
+    try {
+        entries = await (0, solana_1.fetchRecentPriorityFees)(30, needsProgramData);
+        if (entries.length === 0)
+            throw new Error("No fee data returned from RPC");
+    }
+    catch (err) {
+        console.warn("[FEMA] RPC fetch failed, using fallback:", err.message);
+        fromFallback = true;
+    }
+    // 4. Fallback: most recent in-memory snapshot
+    if (fromFallback || entries.length === 0) {
+        const cached = (0, database_1.getLatestSnapshotSync)();
+        const fallbackFees = cached
+            ? reconstructFees(cached.p25Fee, cached.medianFee, cached.p75Fee)
+            : [1000];
+        entries = fallbackFees.map((fee) => ({ fee, programs: [] }));
+    }
+    // 5. Filter to program-relevant transactions (if transaction was provided)
+    const { fees, programFiltered } = (0, feeCalculator_1.filterByPrograms)(entries, programIds);
+    // 6. Calculate
+    const { fee, percentileUsed, snapshot, rawFees } = (0, feeCalculator_1.calculateFee)(fees, speed, strategy, maxFee, computeUnits);
+    // 7. Update cache & latest snapshot reference
+    (0, cache_1.setCache)(snapshot, entries);
+    (0, database_1.setLatestSnapshot)(snapshot);
+    return buildResult(fee, snapshot, percentileUsed, rawFees, includeStats, programFiltered);
+}
+// ─── Helpers ──────────────────────────────────────────────────────────────────
+function buildResult(fee, snapshot, percentileUsed, rawFees, includeStats, programFiltered) {
+    const result = {
+        fee,
+        congestion: snapshot.congestionLevel,
+        percentileUsed,
+        sampleSize: rawFees.length,
+        programFiltered,
+    };
+    if (includeStats) {
+        result.stats = {
+            avgFee: snapshot.avgFee,
+            medianFee: snapshot.medianFee,
+            distribution: buildDistribution(rawFees),
+        };
+    }
+    return result;
+}
+function buildDistribution(sortedFees) {
+    const p = (n) => Math.round((0, feeCalculator_1.percentile)(sortedFees, n));
+    return { p10: p(10), p25: p(25), p50: p(50), p75: p(75), p90: p(90), p95: p(95), p99: p(99) };
+}
+function reconstructFees(p25, median, p75) {
+    return [
+        Math.round(p25 * 0.5),
+        p25,
+        Math.round((p25 + median) / 2),
+        median,
+        Math.round((median + p75) / 2),
+        p75,
+        Math.round(p75 * 1.5),
+    ];
+}
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/dist/protocols.d.ts

@@ -0,0 +1,10 @@
+export type Protocol = "jupiter" | "raydium" | "orca" | "nft" | "pumpfun" | "openbook" | "system" | "token";
+export interface ProtocolInfo {
+    name: string;
+    description: string;
+    programIds: string[];
+}
+export declare const PROTOCOLS: Record<Protocol, ProtocolInfo>;
+export declare function getProtocolProgramIds(protocol: Protocol): string[];
+export declare function detectProtocol(programIds: string[]): Protocol | null;
+//# sourceMappingURL=protocols.d.ts.map

package/dist/protocols.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"protocols.d.ts","sourceRoot":"","sources":["../src/protocols.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,QAAQ,GAChB,SAAS,GACT,SAAS,GACT,MAAM,GACN,KAAK,GACL,SAAS,GACT,UAAU,GACV,QAAQ,GACR,OAAO,CAAC;AAEZ,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,UAAU,EAAE,MAAM,EAAE,CAAC;CACtB;AAED,eAAO,MAAM,SAAS,EAAE,MAAM,CAAC,QAAQ,EAAE,YAAY,CA0EpD,CAAC;AAEF,wBAAgB,qBAAqB,CAAC,QAAQ,EAAE,QAAQ,GAAG,MAAM,EAAE,CAElE;AAED,wBAAgB,cAAc,CAAC,UAAU,EAAE,MAAM,EAAE,GAAG,QAAQ,GAAG,IAAI,CAUpE"}

package/dist/protocols.js

@@ -0,0 +1,86 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PROTOCOLS = void 0;
+exports.getProtocolProgramIds = getProtocolProgramIds;
+exports.detectProtocol = detectProtocol;
+exports.PROTOCOLS = {
+    jupiter: {
+        name: "Jupiter Aggregator",
+        description: "Token swaps via Jupiter V6",
+        programIds: [
+            "JUP6LkbZbjS1jKKwapdHNy74zcZ3tLUZoi5QNyVTaV4", // Jupiter V6
+            "JUP4Fb2cqiRUcaTHdrPC8h2gNsA2ETXiPDD33WcGuJB", // Jupiter V4
+        ],
+    },
+    raydium: {
+        name: "Raydium",
+        description: "Swaps and liquidity on Raydium AMM / CLMM",
+        programIds: [
+            "675kPX9MHTjS2zt1qfr1NYHuzeLXfQM9H24wFSUt1Mp8", // Raydium AMM V4
+            "CAMMCzo5YL8w4VFF8KVHrK22GGUsp5VTaW7grrKgrWqK", // Raydium CLMM
+            "5quBtoiQqxF9Jv6KYKctB59NT3gtJD2Y65kdnB1Uev3h", // Raydium AMM V5
+        ],
+    },
+    orca: {
+        name: "Orca Whirlpools",
+        description: "Swaps on Orca concentrated liquidity pools",
+        programIds: [
+            "whirLbMiicVdio4qvUfM5KAg6Ct8VwpYzGff3uctyCc", // Orca Whirlpool
+            "9W959DqEETiGZocYWCQPaJ6sBmUzgfxXfqGeTEdp3aQP", // Orca V1
+        ],
+    },
+    nft: {
+        name: "NFT / Metaplex",
+        description: "NFT mints, transfers, and metadata via Metaplex",
+        programIds: [
+            "metaqbxxUerdq28cj1RbAWkYQm3ybzjb6a8bt518x1s", // Token Metadata
+            "cndy3Z4yapfJBmL3ShUp5exZKqR3z33thTzeNMm2gRZ", // Candy Machine V3
+            "CndyV3LdqHUfDLmd1X2Rxm9e6CFBe8F6Qkx6kWX6YMEZ", // Candy Machine V2
+            "hausS13jsjafwWwGqZTUQRmWyvyxn9EQpqMwV1PBBmk", // Auction House
+        ],
+    },
+    pumpfun: {
+        name: "Pump.fun",
+        description: "Token launches and trades on Pump.fun",
+        programIds: [
+            "6EF8rrecthR5Dkzon8Nwu78hRvfCKubJ14M5uBEwF6P", // Pump.fun program
+        ],
+    },
+    openbook: {
+        name: "OpenBook",
+        description: "Order book trading on OpenBook (formerly Serum)",
+        programIds: [
+            "srmqPvymJeFKQ4zGQed1GFppgkRHL9kaELCbyksJtPX", // OpenBook V1
+            "opnb2LAfJYbRMAHHvqjCwQxanZn7n734bNfWLcQnB8c", // OpenBook V2
+        ],
+    },
+    system: {
+        name: "System Program",
+        description: "SOL transfers and basic account operations",
+        programIds: [
+            "11111111111111111111111111111111", // System Program
+        ],
+    },
+    token: {
+        name: "Token Program",
+        description: "SPL token transfers and token account operations",
+        programIds: [
+            "TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA", // Token Program
+            "TokenzQdBNbLqP5VEhdkAS6EPFLC1PHnBqCXEpPxuEb", // Token 2022
+            "ATokenGPvbdGVxr1b2hvZbsiqW5xWH25efTNsLJe1bj", // Associated Token Program
+        ],
+    },
+};
+function getProtocolProgramIds(protocol) {
+    return exports.PROTOCOLS[protocol].programIds;
+}
+function detectProtocol(programIds) {
+    const idSet = new Set(programIds);
+    for (const [protocol, info] of Object.entries(exports.PROTOCOLS)) {
+        if (info.programIds.some((id) => idSet.has(id))) {
+            return protocol;
+        }
+    }
+    return null;
+}
+//# sourceMappingURL=protocols.js.map

package/dist/protocols.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"protocols.js","sourceRoot":"","sources":["../src/protocols.ts"],"names":[],"mappings":";;;AA4FA,sDAEC;AAED,wCAUC;AA1FY,QAAA,SAAS,GAAmC;IACvD,OAAO,EAAE;QACP,IAAI,EAAE,oBAAoB;QAC1B,WAAW,EAAE,4BAA4B;QACzC,UAAU,EAAE;YACV,6CAA6C,EAAE,aAAa;YAC5D,6CAA6C,EAAG,aAAa;SAC9D;KACF;IAED,OAAO,EAAE;QACP,IAAI,EAAE,SAAS;QACf,WAAW,EAAE,2CAA2C;QACxD,UAAU,EAAE;YACV,8CAA8C,EAAE,iBAAiB;YACjE,8CAA8C,EAAE,eAAe;YAC/D,8CAA8C,EAAE,iBAAiB;SAClE;KACF;IAED,IAAI,EAAE;QACJ,IAAI,EAAE,iBAAiB;QACvB,WAAW,EAAE,4CAA4C;QACzD,UAAU,EAAE;YACV,6CAA6C,EAAG,iBAAiB;YACjE,8CAA8C,EAAE,UAAU;SAC3D;KACF;IAED,GAAG,EAAE;QACH,IAAI,EAAE,gBAAgB;QACtB,WAAW,EAAE,iDAAiD;QAC9D,UAAU,EAAE;YACV,6CAA6C,EAAG,iBAAiB;YACjE,6CAA6C,EAAG,mBAAmB;YACnE,8CAA8C,EAAE,mBAAmB;YACnE,6CAA6C,EAAG,gBAAgB;SACjE;KACF;IAED,OAAO,EAAE;QACP,IAAI,EAAE,UAAU;QAChB,WAAW,EAAE,uCAAuC;QACpD,UAAU,EAAE;YACV,6CAA6C,EAAG,mBAAmB;SACpE;KACF;IAED,QAAQ,EAAE;QACR,IAAI,EAAE,UAAU;QAChB,WAAW,EAAE,iDAAiD;QAC9D,UAAU,EAAE;YACV,6CAA6C,EAAG,cAAc;YAC9D,6CAA6C,EAAG,cAAc;SAC/D;KACF;IAED,MAAM,EAAE;QACN,IAAI,EAAE,gBAAgB;QACtB,WAAW,EAAE,4CAA4C;QACzD,UAAU,EAAE;YACV,kCAAkC,EAAgB,iBAAiB;SACpE;KACF;IAED,KAAK,EAAE;QACL,IAAI,EAAE,eAAe;QACrB,WAAW,EAAE,kDAAkD;QAC/D,UAAU,EAAE;YACV,6CAA6C,EAAG,gBAAgB;YAChE,6CAA6C,EAAG,aAAa;YAC7D,6CAA6C,EAAG,2BAA2B;SAC5E;KACF;CACF,CAAC;AAEF,SAAgB,qBAAqB,CAAC,QAAkB;IACtD,OAAO,iBAAS,CAAC,QAAQ,CAAC,CAAC,UAAU,CAAC;AACxC,CAAC;AAED,SAAgB,cAAc,CAAC,UAAoB;IACjD,MAAM,KAAK,GAAG,IAAI,GAAG,CAAC,UAAU,CAAC,CAAC;IAElC,KAAK,MAAM,CAAC,QAAQ,EAAE,IAAI,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,iBAAS,CAA+B,EAAE,CAAC;QACvF,IAAI,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,KAAK,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC,EAAE,CAAC;YAChD,OAAO,QAAQ,CAAC;QAClB,CAAC;IACH,CAAC;IAED,OAAO,IAAI,CAAC;AACd,CAAC"}

package/dist/server.d.ts

@@ -0,0 +1,3 @@
+declare const app: import("express-serve-static-core").Express;
+export default app;
+//# sourceMappingURL=server.d.ts.map

package/dist/server.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":"AAcA,QAAA,MAAM,GAAG,6CAAY,CAAC;AAiDtB,eAAe,GAAG,CAAC"}

package/dist/server.js

@@ -0,0 +1,61 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const express_1 = __importDefault(require("express"));
+const dotenv_1 = __importDefault(require("dotenv"));
+const index_1 = require("./index");
+const config_1 = require("./config");
+dotenv_1.default.config();
+// Initialise SDK from environment
+(0, index_1.init)({
+    cacheDurationMs: process.env.CACHE_DURATION_MS
+        ? Number(process.env.CACHE_DURATION_MS)
+        : undefined,
+});
+const app = (0, express_1.default)();
+app.use(express_1.default.json());
+// ─── GET /health ──────────────────────────────────────────────────────────────
+app.get("/health", (_req, res) => {
+    res.json({ status: "ok", rpcUrl: (0, config_1.getConfig)().rpcUrl });
+});
+// ─── GET /estimate-fee ────────────────────────────────────────────────────────
+app.get("/estimate-fee", async (req, res, next) => {
+    try {
+        const { speed, strategy, includeStats, maxFee } = req.query;
+        const result = await (0, index_1.estimateFee)({
+            speed: speed ?? "medium",
+            strategy: strategy ?? "balanced",
+            includeStats: includeStats === "true",
+            maxFee: maxFee ? Number(maxFee) : undefined,
+        });
+        res.json(result);
+    }
+    catch (err) {
+        next(err);
+    }
+});
+// ─── GET /stats ───────────────────────────────────────────────────────────────
+// Returns a comprehensive snapshot with stats
+app.get("/stats", async (_req, res, next) => {
+    try {
+        const result = await (0, index_1.estimateFee)({ speed: "medium", includeStats: true });
+        res.json(result);
+    }
+    catch (err) {
+        next(err);
+    }
+});
+// ─── Error handler ────────────────────────────────────────────────────────────
+app.use((err, _req, res, _next) => {
+    console.error("[FEMA server error]", err.message);
+    res.status(500).json({ error: err.message });
+});
+const PORT = Number(process.env.PORT ?? 3000);
+app.listen(PORT, () => {
+    console.log(`[FEMA] Server running on http://localhost:${PORT}`);
+    console.log(`[FEMA] RPC endpoint: ${(0, config_1.getConfig)().rpcUrl}`);
+});
+exports.default = app;
+//# sourceMappingURL=server.js.map

package/dist/server.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"server.js","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":"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"}

package/dist/services/cache.d.ts

@@ -0,0 +1,8 @@
+import { FeeSnapshot, FeeEntry } from "../types";
+export declare function getCached(): {
+    snapshot: FeeSnapshot;
+    entries: FeeEntry[];
+} | null;
+export declare function setCache(snapshot: FeeSnapshot, entries: FeeEntry[]): void;
+export declare function clearCache(): void;
+//# sourceMappingURL=cache.d.ts.map

package/dist/services/cache.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cache.d.ts","sourceRoot":"","sources":["../../src/services/cache.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,QAAQ,EAAE,MAAM,UAAU,CAAC;AAWjD,wBAAgB,SAAS,IAAI;IAAE,QAAQ,EAAE,WAAW,CAAC;IAAC,OAAO,EAAE,QAAQ,EAAE,CAAA;CAAE,GAAG,IAAI,CAKjF;AAED,wBAAgB,QAAQ,CAAC,QAAQ,EAAE,WAAW,EAAE,OAAO,EAAE,QAAQ,EAAE,GAAG,IAAI,CAOzE;AAED,wBAAgB,UAAU,IAAI,IAAI,CAEjC"}

package/dist/services/cache.js

@@ -0,0 +1,25 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getCached = getCached;
+exports.setCache = setCache;
+exports.clearCache = clearCache;
+const config_1 = require("../config");
+let _entry = null;
+function getCached() {
+    if (_entry && Date.now() < _entry.expiresAt) {
+        return { snapshot: _entry.snapshot, entries: _entry.entries };
+    }
+    return null;
+}
+function setCache(snapshot, entries) {
+    const { cacheDurationMs } = (0, config_1.getConfig)();
+    _entry = {
+        snapshot,
+        entries,
+        expiresAt: Date.now() + cacheDurationMs,
+    };
+}
+function clearCache() {
+    _entry = null;
+}
+//# sourceMappingURL=cache.js.map

package/dist/services/cache.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cache.js","sourceRoot":"","sources":["../../src/services/cache.ts"],"names":[],"mappings":";;AAWA,8BAKC;AAED,4BAOC;AAED,gCAEC;AA5BD,sCAAsC;AAQtC,IAAI,MAAM,GAAsB,IAAI,CAAC;AAErC,SAAgB,SAAS;IACvB,IAAI,MAAM,IAAI,IAAI,CAAC,GAAG,EAAE,GAAG,MAAM,CAAC,SAAS,EAAE,CAAC;QAC5C,OAAO,EAAE,QAAQ,EAAE,MAAM,CAAC,QAAQ,EAAE,OAAO,EAAE,MAAM,CAAC,OAAO,EAAE,CAAC;IAChE,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC;AAED,SAAgB,QAAQ,CAAC,QAAqB,EAAE,OAAmB;IACjE,MAAM,EAAE,eAAe,EAAE,GAAG,IAAA,kBAAS,GAAE,CAAC;IACxC,MAAM,GAAG;QACP,QAAQ;QACR,OAAO;QACP,SAAS,EAAE,IAAI,CAAC,GAAG,EAAE,GAAG,eAAe;KACxC,CAAC;AACJ,CAAC;AAED,SAAgB,UAAU;IACxB,MAAM,GAAG,IAAI,CAAC;AAChB,CAAC"}

package/dist/services/database.d.ts

@@ -0,0 +1,6 @@
+import { FeeSnapshot } from "../types";
+export declare function setLatestSnapshot(s: FeeSnapshot): void;
+export declare function getLatestSnapshotSync(): FeeSnapshot | null;
+export declare function startPersistedInterval(getSnapshot: () => FeeSnapshot | null, intervalMs?: number): void;
+export declare function stopPersistedInterval(): void;
+//# sourceMappingURL=database.d.ts.map

package/dist/services/database.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"database.d.ts","sourceRoot":"","sources":["../../src/services/database.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,UAAU,CAAC;AAKvC,wBAAgB,iBAAiB,CAAC,CAAC,EAAE,WAAW,GAAG,IAAI,CAEtD;AAED,wBAAgB,qBAAqB,IAAI,WAAW,GAAG,IAAI,CAE1D;AAED,wBAAgB,sBAAsB,CACpC,WAAW,EAAE,MAAM,WAAW,GAAG,IAAI,EACrC,UAAU,SAAS,GAClB,IAAI,CAON;AAED,wBAAgB,qBAAqB,IAAI,IAAI,CAK5C"}

package/dist/services/database.js

@@ -0,0 +1,30 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.setLatestSnapshot = setLatestSnapshot;
+exports.getLatestSnapshotSync = getLatestSnapshotSync;
+exports.startPersistedInterval = startPersistedInterval;
+exports.stopPersistedInterval = stopPersistedInterval;
+let _latestSnapshot = null;
+let _persistInterval = null;
+function setLatestSnapshot(s) {
+    _latestSnapshot = s;
+}
+function getLatestSnapshotSync() {
+    return _latestSnapshot;
+}
+function startPersistedInterval(getSnapshot, intervalMs = 15000) {
+    if (_persistInterval)
+        return;
+    _persistInterval = setInterval(() => {
+        const snapshot = getSnapshot();
+        if (snapshot)
+            setLatestSnapshot(snapshot);
+    }, intervalMs);
+}
+function stopPersistedInterval() {
+    if (_persistInterval) {
+        clearInterval(_persistInterval);
+        _persistInterval = null;
+    }
+}
+//# sourceMappingURL=database.js.map

package/dist/services/database.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"database.js","sourceRoot":"","sources":["../../src/services/database.ts"],"names":[],"mappings":";;AAKA,8CAEC;AAED,sDAEC;AAED,wDAUC;AAED,sDAKC;AA5BD,IAAI,eAAe,GAAuB,IAAI,CAAC;AAC/C,IAAI,gBAAgB,GAA0C,IAAI,CAAC;AAEnE,SAAgB,iBAAiB,CAAC,CAAc;IAC9C,eAAe,GAAG,CAAC,CAAC;AACtB,CAAC;AAED,SAAgB,qBAAqB;IACnC,OAAO,eAAe,CAAC;AACzB,CAAC;AAED,SAAgB,sBAAsB,CACpC,WAAqC,EACrC,UAAU,GAAG,KAAM;IAEnB,IAAI,gBAAgB;QAAE,OAAO;IAE7B,gBAAgB,GAAG,WAAW,CAAC,GAAG,EAAE;QAClC,MAAM,QAAQ,GAAG,WAAW,EAAE,CAAC;QAC/B,IAAI,QAAQ;YAAE,iBAAiB,CAAC,QAAQ,CAAC,CAAC;IAC5C,CAAC,EAAE,UAAU,CAAC,CAAC;AACjB,CAAC;AAED,SAAgB,qBAAqB;IACnC,IAAI,gBAAgB,EAAE,CAAC;QACrB,aAAa,CAAC,gBAAgB,CAAC,CAAC;QAChC,gBAAgB,GAAG,IAAI,CAAC;IAC1B,CAAC;AACH,CAAC"}

package/dist/services/solana.d.ts

@@ -0,0 +1,24 @@
+import { Transaction, VersionedTransaction } from "@solana/web3.js";
+import { FeeEntry } from "../types";
+export declare function resetConnection(): void;
+/**
+ * Fetch fee entries from recent blocks.
+ *
+ * - needsProgramData = false (no protocol/transaction passed):
+ *   Uses getRecentPrioritizationFees — fast, no program info needed.
+ *
+ * - needsProgramData = true (protocol or transaction passed):
+ *   Uses full block scan so each entry carries program IDs for accurate filtering.
+ */
+export declare function fetchRecentPriorityFees(blockCount?: number, needsProgramData?: boolean): Promise<FeeEntry[]>;
+/**
+ * Extract program IDs from a user-supplied Transaction or VersionedTransaction.
+ * This is what we use to filter the fee dataset to relevant transactions.
+ */
+export declare function extractProgramIds(tx: Transaction | VersionedTransaction): string[];
+/**
+ * Estimate the compute units a transaction is likely to consume.
+ * Parses ComputeBudgetProgram instructions if present; otherwise returns a default.
+ */
+export declare function estimateComputeUnits(tx: Transaction | VersionedTransaction): number;
+//# sourceMappingURL=solana.d.ts.map

package/dist/services/solana.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"solana.d.ts","sourceRoot":"","sources":["../../src/services/solana.ts"],"names":[],"mappings":"AAAA,OAAO,EAEL,WAAW,EACX,oBAAoB,EAGrB,MAAM,iBAAiB,CAAC;AAEzB,OAAO,EAAE,QAAQ,EAAE,MAAM,UAAU,CAAC;AAWpC,wBAAgB,eAAe,IAAI,IAAI,CAEtC;AAED;;;;;;;;GAQG;AACH,wBAAsB,uBAAuB,CAC3C,UAAU,GAAE,MAAW,EACvB,gBAAgB,GAAE,OAAe,GAChC,OAAO,CAAC,QAAQ,EAAE,CAAC,CAqBrB;AAsGD;;;GAGG;AACH,wBAAgB,iBAAiB,CAC/B,EAAE,EAAE,WAAW,GAAG,oBAAoB,GACrC,MAAM,EAAE,CAmBV;AAED;;;GAGG;AACH,wBAAgB,oBAAoB,CAClC,EAAE,EAAE,WAAW,GAAG,oBAAoB,GACrC,MAAM,CAgCR"}

package/dist/services/solana.js

@@ -0,0 +1,168 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resetConnection = resetConnection;
+exports.fetchRecentPriorityFees = fetchRecentPriorityFees;
+exports.extractProgramIds = extractProgramIds;
+exports.estimateComputeUnits = estimateComputeUnits;
+const web3_js_1 = require("@solana/web3.js");
+const config_1 = require("../config");
+let _connection = null;
+function getConnection() {
+    if (!_connection) {
+        _connection = new web3_js_1.Connection((0, config_1.getConfig)().rpcUrl, "confirmed");
+    }
+    return _connection;
+}
+function resetConnection() {
+    _connection = null;
+}
+/**
+ * Fetch fee entries from recent blocks.
+ *
+ * - needsProgramData = false (no protocol/transaction passed):
+ *   Uses getRecentPrioritizationFees — fast, no program info needed.
+ *
+ * - needsProgramData = true (protocol or transaction passed):
+ *   Uses full block scan so each entry carries program IDs for accurate filtering.
+ */
+async function fetchRecentPriorityFees(blockCount = 30, needsProgramData = false) {
+    const connection = getConnection();
+    if (!needsProgramData) {
+        // Fast path — just need general fee distribution
+        try {
+            const recentFees = await connection.getRecentPrioritizationFees();
+            if (recentFees.length > 0) {
+                const entries = recentFees
+                    .slice(0, blockCount)
+                    .filter((e) => e.prioritizationFee > 0)
+                    .map((e) => ({ fee: e.prioritizationFee, programs: [] }));
+                if (entries.length >= 10)
+                    return entries;
+            }
+        }
+        catch {
+            // fall through to block scan
+        }
+    }
+    // Program-aware path — full block scan with program IDs per transaction
+    return scanBlocks(connection, blockCount);
+}
+async function scanBlocks(connection, blockCount) {
+    const slot = await connection.getSlot();
+    const targetSlots = [];
+    for (let i = 0; i < blockCount; i++) {
+        targetSlots.push(slot - i);
+    }
+    const entries = [];
+    await Promise.all(targetSlots.map(async (s) => {
+        try {
+            const block = await connection.getBlock(s, {
+                maxSupportedTransactionVersion: 0,
+                rewards: false,
+                transactionDetails: "full",
+            });
+            if (!block?.transactions)
+                return;
+            for (const tx of block.transactions) {
+                const meta = tx.meta;
+                if (!meta)
+                    continue;
+                const totalFeeLamports = meta.fee ?? 0;
+                const cuConsumed = meta.computeUnitsConsumed ?? 0;
+                const sigCount = "signatures" in tx.transaction
+                    ? tx.transaction.signatures.length
+                    : 1;
+                const baseFee = 5000 * sigCount;
+                const priorityFeeLamports = totalFeeLamports - baseFee;
+                if (priorityFeeLamports <= 0 || cuConsumed <= 0)
+                    continue;
+                const microLamportsPerCU = Math.round((priorityFeeLamports * 1000000) / cuConsumed);
+                if (microLamportsPerCU <= 0)
+                    continue;
+                // Extract program IDs from the transaction's instructions
+                const programs = extractProgramIdsFromBlock(tx.transaction);
+                entries.push({ fee: microLamportsPerCU, programs });
+            }
+        }
+        catch {
+            // skip failed blocks silently
+        }
+    }));
+    return entries;
+}
+/** Pull program IDs out of a raw block transaction (legacy or versioned). */
+function extractProgramIdsFromBlock(tx) {
+    try {
+        const t = tx;
+        const msg = t.message;
+        if (!msg)
+            return [];
+        // Account key list (legacy)
+        const keys = (msg.accountKeys ?? msg.staticAccountKeys ?? []).map((k) => (typeof k.toBase58 === "function"
+            ? k.toBase58()
+            : String(k)));
+        const ixs = msg.instructions ?? msg.compiledInstructions ?? [];
+        const programIds = new Set();
+        for (const ix of ixs) {
+            const id = keys[ix.programIdIndex];
+            if (id)
+                programIds.add(id);
+        }
+        return Array.from(programIds);
+    }
+    catch {
+        return [];
+    }
+}
+/**
+ * Extract program IDs from a user-supplied Transaction or VersionedTransaction.
+ * This is what we use to filter the fee dataset to relevant transactions.
+ */
+function extractProgramIds(tx) {
+    try {
+        if (tx instanceof web3_js_1.Transaction) {
+            return [
+                ...new Set(tx.instructions.map((ix) => ix.programId.toBase58())),
+            ];
+        }
+        // VersionedTransaction
+        const msg = tx.message;
+        const keys = msg.staticAccountKeys.map((k) => k.toBase58());
+        return [
+            ...new Set(msg.compiledInstructions.map((ix) => keys[ix.programIdIndex])),
+        ];
+    }
+    catch {
+        return [];
+    }
+}
+/**
+ * Estimate the compute units a transaction is likely to consume.
+ * Parses ComputeBudgetProgram instructions if present; otherwise returns a default.
+ */
+function estimateComputeUnits(tx) {
+    const DEFAULT_CU = 200000;
+    try {
+        const instructions = tx instanceof web3_js_1.Transaction
+            ? tx.instructions
+            : tx.message.compiledInstructions;
+        const COMPUTE_BUDGET_PROGRAM_ID = web3_js_1.ComputeBudgetProgram.programId;
+        for (const ix of instructions) {
+            const programId = "programId" in ix
+                ? ix.programId
+                : null;
+            if (programId && programId.equals(COMPUTE_BUDGET_PROGRAM_ID)) {
+                const data = "data" in ix ? ix.data : new Uint8Array();
+                // Instruction type 2 = SetComputeUnitLimit
+                if (data[0] === 2 && data.length >= 5) {
+                    return new DataView(data.buffer, data.byteOffset).getUint32(1, true);
+                }
+            }
+        }
+    }
+    catch {
+        // ignore parse errors
+    }
+    return DEFAULT_CU;
+}
+//# sourceMappingURL=solana.js.map

package/dist/services/solana.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"solana.js","sourceRoot":"","sources":["../../src/services/solana.ts"],"names":[],"mappings":"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"}

package/dist/types.d.ts

@@ -0,0 +1,55 @@
+import { Transaction, VersionedTransaction } from "@solana/web3.js";
+import { Protocol } from "./protocols";
+export type SolanaCluster = "mainnet-beta" | "devnet";
+export interface FemaConfig {
+    rpcUrl: string;
+    cluster: SolanaCluster;
+    cacheDurationMs: number;
+}
+export type Speed = "slow" | "medium" | "fast";
+export type Strategy = "cheap" | "balanced" | "aggressive";
+export type CongestionLevel = "low" | "medium" | "high";
+export interface EstimateFeeOptions {
+    speed?: Speed;
+    strategy?: Strategy;
+    includeStats?: boolean;
+    maxFee?: number;
+    transaction?: Transaction | VersionedTransaction;
+    protocol?: Protocol;
+}
+export interface FeeDistribution {
+    p10: number;
+    p25: number;
+    p50: number;
+    p75: number;
+    p90: number;
+    p95: number;
+    p99: number;
+}
+export interface FeeStats {
+    avgFee: number;
+    medianFee: number;
+    distribution: FeeDistribution;
+}
+export interface EstimateFeeResult {
+    fee: number;
+    congestion: CongestionLevel;
+    percentileUsed: number;
+    sampleSize: number;
+    programFiltered: boolean;
+    stats?: FeeStats;
+}
+export interface FeeEntry {
+    fee: number;
+    programs: string[];
+}
+export interface FeeSnapshot {
+    timestamp: string;
+    avgFee: number;
+    medianFee: number;
+    p25Fee: number;
+    p75Fee: number;
+    congestionLevel: CongestionLevel;
+    txCount: number;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,oBAAoB,EAAE,MAAM,iBAAiB,CAAC;AACpE,OAAO,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AAIvC,MAAM,MAAM,aAAa,GAAG,cAAc,GAAG,QAAQ,CAAC;AAEtD,MAAM,WAAW,UAAU;IACzB,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,aAAa,CAAC;IACvB,eAAe,EAAE,MAAM,CAAC;CACzB;AAID,MAAM,MAAM,KAAK,GAAG,MAAM,GAAG,QAAQ,GAAG,MAAM,CAAC;AAC/C,MAAM,MAAM,QAAQ,GAAG,OAAO,GAAG,UAAU,GAAG,YAAY,CAAC;AAC3D,MAAM,MAAM,eAAe,GAAG,KAAK,GAAG,QAAQ,GAAG,MAAM,CAAC;AAExD,MAAM,WAAW,kBAAkB;IACjC,KAAK,CAAC,EAAE,KAAK,CAAC;IACd,QAAQ,CAAC,EAAE,QAAQ,CAAC;IACpB,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,WAAW,CAAC,EAAE,WAAW,GAAG,oBAAoB,CAAC;IACjD,QAAQ,CAAC,EAAE,QAAQ,CAAC;CACrB;AAED,MAAM,WAAW,eAAe;IAC9B,GAAG,EAAE,MAAM,CAAC;IACZ,GAAG,EAAE,MAAM,CAAC;IACZ,GAAG,EAAE,MAAM,CAAC;IACZ,GAAG,EAAE,MAAM,CAAC;IACZ,GAAG,EAAE,MAAM,CAAC;IACZ,GAAG,EAAE,MAAM,CAAC;IACZ,GAAG,EAAE,MAAM,CAAC;CACb;AAED,MAAM,WAAW,QAAQ;IACvB,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,EAAE,MAAM,CAAC;IAClB,YAAY,EAAE,eAAe,CAAC;CAC/B;AAED,MAAM,WAAW,iBAAiB;IAChC,GAAG,EAAE,MAAM,CAAC;IACZ,UAAU,EAAE,eAAe,CAAC;IAC5B,cAAc,EAAE,MAAM,CAAC;IACvB,UAAU,EAAE,MAAM,CAAC;IACnB,eAAe,EAAE,OAAO,CAAC;IACzB,KAAK,CAAC,EAAE,QAAQ,CAAC;CAClB;AAID,MAAM,WAAW,QAAQ;IACvB,GAAG,EAAE,MAAM,CAAC;IACZ,QAAQ,EAAE,MAAM,EAAE,CAAC;CACpB;AAID,MAAM,WAAW,WAAW;IAC1B,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,eAAe,EAAE,eAAe,CAAC;IACjC,OAAO,EAAE,MAAM,CAAC;CACjB"}

package/dist/types.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":""}

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "fema-pf-calc",
+  "version": "1.0.0",
+  "description": "Intelligent Solana priority fee estimation engine",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "require": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=16"
+  },
+  "scripts": {
+    "build": "tsc",
+    "prepublishOnly": "npm run build",
+    "dev": "ts-node test-fees.ts",
+    "server": "ts-node src/server.ts",
+    "start": "node dist/server.js",
+    "lint": "eslint src/**/*.ts"
+  },
+  "keywords": [
+    "solana",
+    "priority-fee",
+    "web3",
+    "blockchain"
+  ],
+  "license": "MIT",
+  "peerDependencies": {
+    "@solana/web3.js": "^1.x"
+  },
+  "devDependencies": {
+    "@solana/web3.js": "^1.98.0",
+    "@types/express": "^5.0.1",
+    "@types/node": "^22.15.2",
+    "dotenv": "^16.5.0",
+    "express": "^4.21.2",
+    "ts-node": "^10.9.2",
+    "typescript": "^5.8.3"
+  }
+}