fema-pf-calc 1.0.6 → 1.1.0

package/README.md

@@ -1,24 +1,20 @@
-# FEMA — Fee Estimation & Management for Solana
+# Fema
 
-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.
+Fema is a TypeScript SDK for Solana with two tools: `estimateFee` calculates the right priority fee based on what the network is actually paying right now, and `safeSend` handles the full transaction lifecycle including simulation, signing, submission, and confirmation.
 
 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.
-
----
+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 Solana via a built-in Helius-backed RPC proxy — no API key or RPC setup required
+1. Fema connects to Solana via a built-in Helius-backed RPC proxy — no API key or RPC setup required
 2. For each transaction in the last 30 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
@@ -26,17 +22,13 @@ FEMA solves this by scanning recent blocks, building a real fee distribution, an
 
 Results are cached for 7 seconds to avoid hammering the RPC on every call.
 
----
-
 ## Installation
 
 ```bash
 npm install fema-pf-calc
 ```
 
----
-
-## Quick Start
+## estimateFee Quick Start
 
 ```ts
 import { init, estimateFee } from "fema-pf-calc";
@@ -56,18 +48,16 @@ const priorityIx = ComputeBudgetProgram.setComputeUnitPrice({
 
 That is all a developer needs to do. No RPC key, no math, no guessing.
 
----
-
-## Options
+## estimateFee Options
 
 ```ts
 const result = await estimateFee({
-  speed: "fast",            // "slow" | "medium" | "fast"
-  strategy: "balanced",     // "cheap" | "balanced" | "aggressive"
-  protocol: "jupiter",      // see supported protocols below
+  speed: "fast",             // "slow" | "medium" | "fast"
+  strategy: "balanced",      // "cheap" | "balanced" | "aggressive"
+  protocol: "jupiter",       // see supported protocols below
   transaction: myTransaction, // pass your actual tx for automatic protocol detection
-  maxFee: 500_000,          // optional cap in microLamports
-  includeStats: true,       // include full distribution in response
+  maxFee: 500_000,           // optional cap in microLamports
+  includeStats: true,        // include full distribution in response
 });
 ```
 
@@ -87,11 +77,9 @@ const result = await estimateFee({
 | `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.
+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
@@ -110,7 +98,7 @@ const { fee: pumpFee } = await estimateFee({
 });
 ```
 
-Alternatively, pass your actual transaction and FEMA will detect the protocol automatically:
+Alternatively, pass your actual transaction and Fema will detect the protocol automatically:
 
 ```ts
 const { fee } = await estimateFee({
@@ -132,17 +120,15 @@ const { fee } = await estimateFee({
 | `system`   | System Program (SOL transfers)                      |
 | `token`    | Token Program, Token 2022, Associated Token Program |
 
----
-
-## Response
+## estimateFee 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
+  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: {
@@ -163,36 +149,15 @@ const { fee } = await estimateFee({
 
 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 — bring your own RPC to override the default
-  cacheDurationMs: 7000,        // how long to cache results in ms (default: 7000)
+  cluster: "mainnet-beta", // "mainnet-beta" | "devnet" (default: "mainnet-beta")
+  cacheDurationMs: 7000,   // how long to cache results in ms (default: 7000)
 });
 ```
 
-You can also override the RPC via environment variables:
-
-```env
-# Optional: use your own RPC provider (overrides the built-in default)
-SOLANA_RPC_URL=https://your-custom-rpc.com
-
-# Or use your own Helius API key
-HELIUS_API_KEY=your-api-key-here
-
-# Network: mainnet-beta (default) or devnet
-SOLANA_CLUSTER=mainnet-beta
-
-# How long to cache fee data in milliseconds (default: 7000)
-CACHE_DURATION_MS=7000
-```
-
----
-
 ## Sample Code
 
 ```ts
@@ -226,25 +191,98 @@ app.listen(8000, () => {
 export default app;
 ```
 
----
+## safeSend
+
+`safeSend` handles the full lifecycle of sending a Solana transaction. It simulates before sending, signs with your wallet, submits, and confirms on-chain. It catches errors before they cost SOL, retries automatically when safe to do so, and tells you exactly what went wrong when it isn't.
+
+## safeSend Quick Start
+
+```ts
+import { safeSend } from "fema-pf-calc";
+
+const result = await safeSend({
+  tx: myTransaction,
+  wallet: walletAdapter, // any wallet with signTransaction (Phantom, Backpack, etc.)
+  network: "mainnet-beta",
+  mode: "safe",
+});
+
+if (result.success) {
+  console.log("Confirmed:", result.signature);
+} else {
+  console.log("Failed:", result.error?.type);
+}
+```
+
+## safeSend Options
 
-## Project Structure
+```ts
+const result = await safeSend({
+  tx: myTransaction,          // Transaction | VersionedTransaction
+  wallet: walletAdapter,      // must implement signTransaction
+  network: "mainnet-beta",    // "devnet" | "mainnet-beta" (default: "devnet")
+  mode: "safe",               // "safe" | "fast" (default: "safe")
+  ai: true,                   // enable AI diagnostics on failure (default: false)
+});
+```
+
+### Mode
+
+| Mode   | What it does                                                               |
+| ------ | -------------------------------------------------------------------------- |
+| `safe` | Simulates first, retries up to 3× on recoverable errors, confirms on-chain |
+| `fast` | Simulates first, sends once, returns immediately — no retries              |
+
+## safeSend Response
+
+```ts
+// Success
+{ success: true, signature: "5Kj...", network: "mainnet-beta", retriesUsed: 0 }
 
+// Failure
+{
+  success: false,
+  network: "mainnet-beta",
+  retriesUsed: 2,
+  error: {
+    type: "INSUFFICIENT_FUNDS",
+    logs: ["..."],
+
+    // only included when ai: true
+    explanation: "The sender account does not have enough lamports...",
+    suggestedFix: "Fund the account with at least 0.05 SOL before retrying.",
+  }
+}
 ```
-src/
-├── index.ts              # SDK entry point — estimateFee() and init()
-├── types.ts              # TypeScript types and interfaces
-├── config.ts             # Configuration and 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
+
+### Error Types
+
+| Type                   | Recoverable | What happened                                     |
+| ---------------------- | ----------- | ------------------------------------------------- |
+| `INSUFFICIENT_FUNDS`   | No          | Sender cannot cover the transfer + fees           |
+| `BLOCKHASH_EXPIRED`    | Yes         | Blockhash went stale, retried with a fresh one    |
+| `COMPUTE_EXCEEDED`     | Yes         | Compute limit too low, auto-bumped and retried    |
+| `INVALID_INSTRUCTION`  | No          | Instruction references a wrong or unknown program |
+| `NETWORK_FAILURE`      | No          | Could not reach the RPC                           |
+| `SEND_FAILED`          | No          | Transaction was rejected at submission            |
+| `SIGNING_REJECTED`     | No          | Wallet refused to sign                            |
+| `CONFIRMATION_TIMEOUT` | No          | Transaction was sent but not confirmed in time    |
+| `MAX_RETRIES_EXCEEDED` | No          | Hit the 3-retry limit without landing             |
+
+## AI Diagnostics
+
+Set `ai: true` and add a `GROQ_API_KEY` to your environment to get a plain-English explanation and a concrete fix suggestion on every failure.
+
+```ts
+const result = await safeSend({ tx, wallet, network: "mainnet-beta", ai: true });
+
+if (!result.success) {
+  console.log(result.error?.explanation);  // "The compute budget was exceeded..."
+  console.log(result.error?.suggestedFix); // "Add ComputeBudgetProgram.setComputeUnitLimit..."
+}
 ```
 
----
+Get a free Groq API key at console.groq.com. Fema uses Llama 3.3-70b under the hood and falls back silently if the key is missing or the API is unavailable.
 
 ## License
 

package/dist/index.d.ts

@@ -2,6 +2,8 @@ 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 { safeSend } from "./safeSend";
+export type { SafeSendOptions, SafeSendResult, SafeSendNetwork, SafeSendMode, SafeSendError, WalletAdapter, AIExplanation, } from "./safeSend/types";
 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

@@ -1 +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;AAkBxC,wBAAgB,IAAI,CAAC,MAAM,EAAE,OAAO,CAAC,UAAU,CAAC,GAAG,IAAI,CAiBtD;AAID,wBAAsB,WAAW,CAC/B,OAAO,GAAE,kBAAuB,GAC/B,OAAO,CAAC,iBAAiB,CAAC,CAsE5B"}
+{"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;AAIxC,OAAO,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AACtC,YAAY,EACV,eAAe,EACf,cAAc,EACd,eAAe,EACf,YAAY,EACZ,aAAa,EACb,aAAa,EACb,aAAa,GACd,MAAM,kBAAkB,CAAC;AAkB1B,wBAAgB,IAAI,CAAC,MAAM,EAAE,OAAO,CAAC,UAAU,CAAC,GAAG,IAAI,CAiBtD;AAID,wBAAsB,WAAW,CAC/B,OAAO,GAAE,kBAAuB,GAC/B,OAAO,CAAC,iBAAiB,CAAC,CAsE5B"}

package/dist/index.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.PROTOCOLS = void 0;
+exports.safeSend = exports.PROTOCOLS = void 0;
 exports.init = init;
 exports.estimateFee = estimateFee;
 const config_1 = require("./config");
@@ -11,6 +11,9 @@ 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; } });
+// ─── safeSend ─────────────────────────────────────────────────────────────────
+var safeSend_1 = require("./safeSend");
+Object.defineProperty(exports, "safeSend", { enumerable: true, get: function () { return safeSend_1.safeSend; } });
 // ─── SDK initialisation ───────────────────────────────────────────────────────
 let _started = false;
 // Deduplicate concurrent fetches — if a block scan is already in flight,

package/dist/index.js.map

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

package/dist/safeSend/aiExplainer.d.ts

@@ -0,0 +1,9 @@
+import type { ErrorType, AIExplanation } from "./types";
+/**
+ * Use Groq (Llama 3.3-70b) to analyze a Solana transaction failure.
+ * AI layer is post-process only — it never mutates transactions or controls retries.
+ *
+ * Falls back gracefully when GROQ_API_KEY is not set or the API call fails.
+ */
+export declare function explain(errorType: ErrorType, logs: string[], network: string, attempts: number): Promise<AIExplanation>;
+//# sourceMappingURL=aiExplainer.d.ts.map

package/dist/safeSend/aiExplainer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"aiExplainer.d.ts","sourceRoot":"","sources":["../../src/safeSend/aiExplainer.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,SAAS,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AA+BxD;;;;;GAKG;AACH,wBAAsB,OAAO,CAC3B,SAAS,EAAE,SAAS,EACpB,IAAI,EAAE,MAAM,EAAE,EACd,OAAO,EAAE,MAAM,EACf,QAAQ,EAAE,MAAM,GACf,OAAO,CAAC,aAAa,CAAC,CAgCxB"}

package/dist/safeSend/aiExplainer.js

@@ -0,0 +1,99 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.explain = explain;
+const groq_sdk_1 = __importDefault(require("groq-sdk"));
+const MODEL = "llama-3.3-70b-versatile";
+const SYSTEM_PROMPT = `You are a Solana blockchain transaction diagnostics expert.
+
+You receive failed Solana transaction data — error type, simulation logs, network, and attempt count — and you return a precise diagnosis.
+
+Respond ONLY with a valid JSON object in this exact shape:
+{
+  "explanation": "<1–2 sentences explaining the root cause>",
+  "fixSuggestion": "<specific, actionable steps the developer should take now>",
+  "confidenceScore": <float 0.0–1.0>
+}
+
+Rules:
+- Read the simulation logs carefully. Programs emit custom error codes and messages — use them.
+- Do not repeat the error type label verbatim. Explain WHY it happened.
+- fixSuggestion must be concrete (e.g. "Add ComputeBudgetProgram.setComputeUnitLimit({ units: 400000 }) as the first instruction").
+- confidenceScore reflects how certain you are given the available log detail.
+- No markdown, no prose outside the JSON.`;
+let _client = null;
+function getClient() {
+    if (!_client) {
+        _client = new groq_sdk_1.default({ apiKey: process.env.GROQ_API_KEY });
+    }
+    return _client;
+}
+/**
+ * Use Groq (Llama 3.3-70b) to analyze a Solana transaction failure.
+ * AI layer is post-process only — it never mutates transactions or controls retries.
+ *
+ * Falls back gracefully when GROQ_API_KEY is not set or the API call fails.
+ */
+async function explain(errorType, logs, network, attempts) {
+    if (!process.env.GROQ_API_KEY?.trim()) {
+        return noKeyFallback(errorType);
+    }
+    const userMessage = buildUserMessage(errorType, logs, network, attempts);
+    try {
+        const client = getClient();
+        const response = await client.chat.completions.create({
+            model: MODEL,
+            temperature: 0.1,
+            max_tokens: 512,
+            response_format: { type: "json_object" },
+            messages: [
+                { role: "system", content: SYSTEM_PROMPT },
+                { role: "user", content: userMessage },
+            ],
+        });
+        const raw = response.choices[0]?.message?.content?.trim() ?? "{}";
+        const parsed = JSON.parse(raw);
+        return {
+            explanation: String(parsed.explanation ?? ""),
+            fixSuggestion: String(parsed.fixSuggestion ?? ""),
+            confidenceScore: clamp(Number(parsed.confidenceScore ?? 0.5)),
+        };
+    }
+    catch {
+        return apiFallback(errorType);
+    }
+}
+// ─── Helpers ──────────────────────────────────────────────────────────────────
+function buildUserMessage(errorType, logs, network, attempts) {
+    const logsBlock = logs.length > 0 ? logs.join("\n") : "(no simulation logs returned)";
+    return `Analyze this failed Solana transaction and diagnose the root cause.
+
+Error Type : ${errorType}
+Network    : ${network}
+Attempts   : ${attempts}
+
+Simulation Logs:
+\`\`\`
+${logsBlock}
+\`\`\``;
+}
+function noKeyFallback(errorType) {
+    return {
+        explanation: `Transaction failed with error: ${errorType}. Set the GROQ_API_KEY environment variable to enable AI-powered diagnostics.`,
+        fixSuggestion: "Add GROQ_API_KEY to your .env file. Get a free key at console.groq.com.",
+        confidenceScore: 0,
+    };
+}
+function apiFallback(errorType) {
+    return {
+        explanation: `Transaction failed with error: ${errorType}. AI analysis is temporarily unavailable.`,
+        fixSuggestion: "Inspect the simulation logs in the error object for program-specific error codes.",
+        confidenceScore: 0.1,
+    };
+}
+function clamp(n) {
+    return Math.min(1, Math.max(0, n));
+}
+//# sourceMappingURL=aiExplainer.js.map

package/dist/safeSend/aiExplainer.js.map

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

package/dist/safeSend/autoFix.d.ts

@@ -0,0 +1,14 @@
+import { Transaction, VersionedTransaction } from "@solana/web3.js";
+import type { ErrorType } from "./types";
+/**
+ * Apply an automatic fix for a recoverable simulation error.
+ *
+ * BLOCKHASH_EXPIRED — no-op here; the state machine's Step 2 always refreshes
+ * the blockhash at the top of every retry iteration, so no extra RPC call needed.
+ *
+ * COMPUTE_EXCEEDED — adds or increases the SetComputeUnitLimit instruction.
+ * Only possible for legacy Transaction; VersionedTransaction messages are
+ * compiled and cannot be modified post-construction.
+ */
+export declare function applyFix(tx: Transaction | VersionedTransaction, errorType: ErrorType): Transaction | VersionedTransaction;
+//# sourceMappingURL=autoFix.d.ts.map

package/dist/safeSend/autoFix.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"autoFix.d.ts","sourceRoot":"","sources":["../../src/safeSend/autoFix.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,WAAW,EACX,oBAAoB,EAErB,MAAM,iBAAiB,CAAC;AACzB,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,SAAS,CAAC;AASzC;;;;;;;;;GASG;AACH,wBAAgB,QAAQ,CACtB,EAAE,EAAE,WAAW,GAAG,oBAAoB,EACtC,SAAS,EAAE,SAAS,GACnB,WAAW,GAAG,oBAAoB,CAMpC"}

package/dist/safeSend/autoFix.js

@@ -0,0 +1,49 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.applyFix = applyFix;
+const web3_js_1 = require("@solana/web3.js");
+const MAX_COMPUTE_UNITS = 1400000;
+const DEFAULT_COMPUTE_UNITS = 400000;
+const COMPUTE_UNIT_SCALE_FACTOR = 1.5;
+// Discriminator byte for ComputeBudgetProgram.setComputeUnitLimit
+const SET_UNIT_LIMIT_DISCRIMINATOR = 2;
+/**
+ * Apply an automatic fix for a recoverable simulation error.
+ *
+ * BLOCKHASH_EXPIRED — no-op here; the state machine's Step 2 always refreshes
+ * the blockhash at the top of every retry iteration, so no extra RPC call needed.
+ *
+ * COMPUTE_EXCEEDED — adds or increases the SetComputeUnitLimit instruction.
+ * Only possible for legacy Transaction; VersionedTransaction messages are
+ * compiled and cannot be modified post-construction.
+ */
+function applyFix(tx, errorType) {
+    if (errorType === "COMPUTE_EXCEEDED") {
+        return increaseComputeBudget(tx);
+    }
+    // BLOCKHASH_EXPIRED: Step 2 handles this — return unchanged.
+    return tx;
+}
+function increaseComputeBudget(tx) {
+    if (!(tx instanceof web3_js_1.Transaction)) {
+        // VersionedTransaction messages are immutable after compilation.
+        // Callers should build the transaction with a sufficient compute budget upfront.
+        return tx;
+    }
+    const BUDGET_PROGRAM_ID = web3_js_1.ComputeBudgetProgram.programId.toBase58();
+    const existingIdx = tx.instructions.findIndex((ix) => ix.programId.toBase58() === BUDGET_PROGRAM_ID &&
+        ix.data.length >= 5 &&
+        ix.data[0] === SET_UNIT_LIMIT_DISCRIMINATOR);
+    if (existingIdx >= 0) {
+        const current = new DataView(tx.instructions[existingIdx].data.buffer, tx.instructions[existingIdx].data.byteOffset).getUint32(1, true);
+        const increased = Math.min(Math.round(current * COMPUTE_UNIT_SCALE_FACTOR), MAX_COMPUTE_UNITS);
+        tx.instructions[existingIdx] = web3_js_1.ComputeBudgetProgram.setComputeUnitLimit({
+            units: increased,
+        });
+    }
+    else {
+        tx.instructions.unshift(web3_js_1.ComputeBudgetProgram.setComputeUnitLimit({ units: DEFAULT_COMPUTE_UNITS }));
+    }
+    return tx;
+}
+//# sourceMappingURL=autoFix.js.map

package/dist/safeSend/autoFix.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"autoFix.js","sourceRoot":"","sources":["../../src/safeSend/autoFix.ts"],"names":[],"mappings":";;AAwBA,4BASC;AAjCD,6CAIyB;AAGzB,MAAM,iBAAiB,GAAG,OAAS,CAAC;AACpC,MAAM,qBAAqB,GAAG,MAAO,CAAC;AACtC,MAAM,yBAAyB,GAAG,GAAG,CAAC;AAEtC,kEAAkE;AAClE,MAAM,4BAA4B,GAAG,CAAC,CAAC;AAEvC;;;;;;;;;GASG;AACH,SAAgB,QAAQ,CACtB,EAAsC,EACtC,SAAoB;IAEpB,IAAI,SAAS,KAAK,kBAAkB,EAAE,CAAC;QACrC,OAAO,qBAAqB,CAAC,EAAE,CAAC,CAAC;IACnC,CAAC;IACD,6DAA6D;IAC7D,OAAO,EAAE,CAAC;AACZ,CAAC;AAED,SAAS,qBAAqB,CAC5B,EAAsC;IAEtC,IAAI,CAAC,CAAC,EAAE,YAAY,qBAAW,CAAC,EAAE,CAAC;QACjC,iEAAiE;QACjE,iFAAiF;QACjF,OAAO,EAAE,CAAC;IACZ,CAAC;IAED,MAAM,iBAAiB,GAAG,8BAAoB,CAAC,SAAS,CAAC,QAAQ,EAAE,CAAC;IAEpE,MAAM,WAAW,GAAG,EAAE,CAAC,YAAY,CAAC,SAAS,CAC3C,CAAC,EAAE,EAAE,EAAE,CACL,EAAE,CAAC,SAAS,CAAC,QAAQ,EAAE,KAAK,iBAAiB;QAC7C,EAAE,CAAC,IAAI,CAAC,MAAM,IAAI,CAAC;QACnB,EAAE,CAAC,IAAI,CAAC,CAAC,CAAC,KAAK,4BAA4B,CAC9C,CAAC;IAEF,IAAI,WAAW,IAAI,CAAC,EAAE,CAAC;QACrB,MAAM,OAAO,GAAG,IAAI,QAAQ,CAC1B,EAAE,CAAC,YAAY,CAAC,WAAW,CAAC,CAAC,IAAI,CAAC,MAAM,EACxC,EAAE,CAAC,YAAY,CAAC,WAAW,CAAC,CAAC,IAAI,CAAC,UAAU,CAC7C,CAAC,SAAS,CAAC,CAAC,EAAE,IAAI,CAAC,CAAC;QAErB,MAAM,SAAS,GAAG,IAAI,CAAC,GAAG,CACxB,IAAI,CAAC,KAAK,CAAC,OAAO,GAAG,yBAAyB,CAAC,EAC/C,iBAAiB,CAClB,CAAC;QAEF,EAAE,CAAC,YAAY,CAAC,WAAW,CAAC,GAAG,8BAAoB,CAAC,mBAAmB,CAAC;YACtE,KAAK,EAAE,SAAS;SACjB,CAAC,CAAC;IACL,CAAC;SAAM,CAAC;QACN,EAAE,CAAC,YAAY,CAAC,OAAO,CACrB,8BAAoB,CAAC,mBAAmB,CAAC,EAAE,KAAK,EAAE,qBAAqB,EAAE,CAAC,CAC3E,CAAC;IACJ,CAAC;IAED,OAAO,EAAE,CAAC;AACZ,CAAC"}

package/dist/safeSend/connection.d.ts

@@ -0,0 +1,4 @@
+import { Connection } from "@solana/web3.js";
+import type { SafeSendNetwork } from "./types";
+export declare function getConnection(network: SafeSendNetwork): Connection;
+//# sourceMappingURL=connection.d.ts.map

package/dist/safeSend/connection.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"connection.d.ts","sourceRoot":"","sources":["../../src/safeSend/connection.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAC7C,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,SAAS,CAAC;AAwB/C,wBAAgB,aAAa,CAAC,OAAO,EAAE,eAAe,GAAG,UAAU,CAElE"}

package/dist/safeSend/connection.js

@@ -0,0 +1,27 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getConnection = getConnection;
+const web3_js_1 = require("@solana/web3.js");
+const HELIUS_ENDPOINTS = {
+    "mainnet-beta": "https://mainnet.helius-rpc.com",
+    devnet: "https://devnet.helius-rpc.com",
+};
+// Zero-config fallback — FEMA proxy is Helius-backed; no API key required.
+const FEMA_PROXY = "https://fema-rpc-proxy.fema-proxy.workers.dev";
+/**
+ * Build the RPC URL for the given network.
+ * Uses HELIUS_API_KEY env var when available; falls back to the FEMA proxy.
+ * The URL is intentionally not exported — callers get a Connection, not a URL,
+ * to prevent the API key from leaking into application code.
+ */
+function buildRpcUrl(network) {
+    const apiKey = process.env.HELIUS_API_KEY?.trim();
+    if (apiKey) {
+        return `${HELIUS_ENDPOINTS[network]}/?api-key=${apiKey}`;
+    }
+    return FEMA_PROXY;
+}
+function getConnection(network) {
+    return new web3_js_1.Connection(buildRpcUrl(network), "confirmed");
+}
+//# sourceMappingURL=connection.js.map

package/dist/safeSend/connection.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"connection.js","sourceRoot":"","sources":["../../src/safeSend/connection.ts"],"names":[],"mappings":";;AAyBA,sCAEC;AA3BD,6CAA6C;AAG7C,MAAM,gBAAgB,GAAoC;IACxD,cAAc,EAAE,gCAAgC;IAChD,MAAM,EAAE,+BAA+B;CACxC,CAAC;AAEF,2EAA2E;AAC3E,MAAM,UAAU,GAAG,+CAA+C,CAAC;AAEnE;;;;;GAKG;AACH,SAAS,WAAW,CAAC,OAAwB;IAC3C,MAAM,MAAM,GAAG,OAAO,CAAC,GAAG,CAAC,cAAc,EAAE,IAAI,EAAE,CAAC;IAClD,IAAI,MAAM,EAAE,CAAC;QACX,OAAO,GAAG,gBAAgB,CAAC,OAAO,CAAC,aAAa,MAAM,EAAE,CAAC;IAC3D,CAAC;IACD,OAAO,UAAU,CAAC;AACpB,CAAC;AAED,SAAgB,aAAa,CAAC,OAAwB;IACpD,OAAO,IAAI,oBAAU,CAAC,WAAW,CAAC,OAAO,CAAC,EAAE,WAAW,CAAC,CAAC;AAC3D,CAAC"}

package/dist/safeSend/errorClassifier.d.ts

@@ -0,0 +1,7 @@
+import type { SimulationError } from "./types";
+/**
+ * Pure function — converts raw simulation logs into a structured SimulationError.
+ * Order matters: more specific patterns are checked before UNKNOWN.
+ */
+export declare function classifySimulationError(logs: string[]): SimulationError;
+//# sourceMappingURL=errorClassifier.d.ts.map

package/dist/safeSend/errorClassifier.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errorClassifier.d.ts","sourceRoot":"","sources":["../../src/safeSend/errorClassifier.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAa,eAAe,EAAE,MAAM,SAAS,CAAC;AAK1D;;;GAGG;AACH,wBAAgB,uBAAuB,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,eAAe,CAGvE"}

package/dist/safeSend/errorClassifier.js

@@ -0,0 +1,40 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.classifySimulationError = classifySimulationError;
+// Error types that can be automatically recovered from.
+const RECOVERABLE = new Set(["BLOCKHASH_EXPIRED", "COMPUTE_EXCEEDED"]);
+/**
+ * Pure function — converts raw simulation logs into a structured SimulationError.
+ * Order matters: more specific patterns are checked before UNKNOWN.
+ */
+function classifySimulationError(logs) {
+    const type = detectType(logs);
+    return { type, logs, recoverable: RECOVERABLE.has(type) };
+}
+function detectType(logs) {
+    const text = logs.join(" ").toLowerCase();
+    if (text.includes("insufficient funds") ||
+        text.includes("insufficient lamports") ||
+        text.includes("0x1") // common Solana insufficient-funds error code
+    ) {
+        return "INSUFFICIENT_FUNDS";
+    }
+    if (text.includes("blockhash not found") ||
+        text.includes("blockhash expired") ||
+        text.includes("recent blockhash") ||
+        text.includes("blockhashnot")) {
+        return "BLOCKHASH_EXPIRED";
+    }
+    if (text.includes("exceeded") &&
+        (text.includes("compute") || text.includes("budget") || text.includes("units"))) {
+        return "COMPUTE_EXCEEDED";
+    }
+    if (text.includes("invalid instruction") ||
+        text.includes("invalid program id") ||
+        text.includes("incorrect program id") ||
+        text.includes("unknown instruction")) {
+        return "INVALID_INSTRUCTION";
+    }
+    return "UNKNOWN";
+}
+//# sourceMappingURL=errorClassifier.js.map

package/dist/safeSend/errorClassifier.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errorClassifier.js","sourceRoot":"","sources":["../../src/safeSend/errorClassifier.ts"],"names":[],"mappings":";;AASA,0DAGC;AAVD,wDAAwD;AACxD,MAAM,WAAW,GAAG,IAAI,GAAG,CAAY,CAAC,mBAAmB,EAAE,kBAAkB,CAAC,CAAC,CAAC;AAElF;;;GAGG;AACH,SAAgB,uBAAuB,CAAC,IAAc;IACpD,MAAM,IAAI,GAAG,UAAU,CAAC,IAAI,CAAC,CAAC;IAC9B,OAAO,EAAE,IAAI,EAAE,IAAI,EAAE,WAAW,EAAE,WAAW,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC;AAC5D,CAAC;AAED,SAAS,UAAU,CAAC,IAAc;IAChC,MAAM,IAAI,GAAG,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,WAAW,EAAE,CAAC;IAE1C,IACE,IAAI,CAAC,QAAQ,CAAC,oBAAoB,CAAC;QACnC,IAAI,CAAC,QAAQ,CAAC,uBAAuB,CAAC;QACtC,IAAI,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC,8CAA8C;MACnE,CAAC;QACD,OAAO,oBAAoB,CAAC;IAC9B,CAAC;IAED,IACE,IAAI,CAAC,QAAQ,CAAC,qBAAqB,CAAC;QACpC,IAAI,CAAC,QAAQ,CAAC,mBAAmB,CAAC;QAClC,IAAI,CAAC,QAAQ,CAAC,kBAAkB,CAAC;QACjC,IAAI,CAAC,QAAQ,CAAC,cAAc,CAAC,EAC7B,CAAC;QACD,OAAO,mBAAmB,CAAC;IAC7B,CAAC;IAED,IACE,IAAI,CAAC,QAAQ,CAAC,UAAU,CAAC;QACzB,CAAC,IAAI,CAAC,QAAQ,CAAC,SAAS,CAAC,IAAI,IAAI,CAAC,QAAQ,CAAC,QAAQ,CAAC,IAAI,IAAI,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC,EAC/E,CAAC;QACD,OAAO,kBAAkB,CAAC;IAC5B,CAAC;IAED,IACE,IAAI,CAAC,QAAQ,CAAC,qBAAqB,CAAC;QACpC,IAAI,CAAC,QAAQ,CAAC,oBAAoB,CAAC;QACnC,IAAI,CAAC,QAAQ,CAAC,sBAAsB,CAAC;QACrC,IAAI,CAAC,QAAQ,CAAC,qBAAqB,CAAC,EACpC,CAAC;QACD,OAAO,qBAAqB,CAAC;IAC/B,CAAC;IAED,OAAO,SAAS,CAAC;AACnB,CAAC"}

package/dist/safeSend/index.d.ts

@@ -0,0 +1,3 @@
+import type { SafeSendOptions, SafeSendResult } from "./types";
+export declare function safeSend(options: SafeSendOptions): Promise<SafeSendResult>;
+//# sourceMappingURL=index.d.ts.map

package/dist/safeSend/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/safeSend/index.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EACV,eAAe,EACf,cAAc,EAMf,MAAM,SAAS,CAAC;AAejB,wBAAsB,QAAQ,CAAC,OAAO,EAAE,eAAe,GAAG,OAAO,CAAC,cAAc,CAAC,CAsJhF"}

package/dist/safeSend/index.js

@@ -0,0 +1,202 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.safeSend = safeSend;
+const web3_js_1 = require("@solana/web3.js");
+const connection_1 = require("./connection");
+const errorClassifier_1 = require("./errorClassifier");
+const autoFix_1 = require("./autoFix");
+const aiExplainer_1 = require("./aiExplainer");
+const utils_1 = require("./utils");
+// ─── Constants ────────────────────────────────────────────────────────────────
+const MAX_RETRIES = 3;
+const CONFIRMATION_TIMEOUT_MS = 60000;
+const CONFIRMATION_POLL_MS = 2000;
+// ─── Public API ───────────────────────────────────────────────────────────────
+async function safeSend(options) {
+    // ── STEP 1: INPUT NORMALIZATION ─────────────────────────────────────────────
+    const validationError = (0, utils_1.validateInput)(options);
+    if (validationError) {
+        return buildFailure(options.network ?? "devnet", 0, {
+            type: "INVALID_INPUT",
+            explanation: validationError,
+        });
+    }
+    const { tx, wallet, network = "devnet", mode = "safe", ai = false } = options;
+    const connection = (0, connection_1.getConnection)(network);
+    let workingTx = tx;
+    let retriesUsed = 0;
+    // ── STATE MACHINE ───────────────────────────────────────────────────────────
+    for (;;) {
+        if (retriesUsed > MAX_RETRIES) {
+            return buildFailure(network, retriesUsed, { type: "MAX_RETRIES_EXCEEDED" });
+        }
+        // ── STEP 2: GET LATEST BLOCKHASH ──────────────────────────────────────────
+        let lastValidBlockHeight = 0;
+        try {
+            const bh = await connection.getLatestBlockhash("confirmed");
+            lastValidBlockHeight = bh.lastValidBlockHeight;
+            attachBlockhash(workingTx, bh.blockhash, bh.lastValidBlockHeight);
+        }
+        catch (err) {
+            const msg = (0, utils_1.sanitizeMessage)(err.message);
+            if (mode === "fast" || retriesUsed >= MAX_RETRIES) {
+                const aiFields = await fetchAIFields(ai, "NETWORK_FAILURE", [msg], network, retriesUsed + 1);
+                return buildFailure(network, retriesUsed, {
+                    type: "NETWORK_FAILURE",
+                    logs: [msg],
+                    ...aiFields,
+                });
+            }
+            retriesUsed++;
+            continue;
+        }
+        // ── STEP 3: SIMULATION (CRITICAL GATE) ───────────────────────────────────
+        let simError = null;
+        try {
+            const { err, logs } = await runSimulation(connection, workingTx);
+            if (err !== null) {
+                simError = (0, errorClassifier_1.classifySimulationError)((0, utils_1.truncateLogs)(logs ?? []));
+            }
+        }
+        catch (err) {
+            const msg = (0, utils_1.sanitizeMessage)(err.message);
+            simError = { type: "UNKNOWN", logs: [msg], recoverable: false };
+        }
+        // ── STEP 3A: FAILURE CLASSIFICATION ──────────────────────────────────────
+        if (simError !== null) {
+            if (!simError.recoverable || retriesUsed >= MAX_RETRIES) {
+                const aiFields = await fetchAIFields(ai, simError.type, simError.logs, network, retriesUsed + 1);
+                return buildFailure(network, retriesUsed, {
+                    type: simError.type,
+                    logs: simError.logs,
+                    ...aiFields,
+                });
+            }
+            // ── STEP 4: AUTO-FIX ENGINE — re-enter loop at Step 3 ──────────────────
+            workingTx = (0, autoFix_1.applyFix)(workingTx, simError.type);
+            retriesUsed++;
+            continue;
+        }
+        // ── STEP 5: WALLET SIGNING (USER CONTROLLED — never bypassed) ────────────
+        let signedTx;
+        try {
+            signedTx = await wallet.signTransaction(workingTx);
+        }
+        catch (err) {
+            const msg = (0, utils_1.sanitizeMessage)(err.message);
+            const aiFields = await fetchAIFields(ai, "SIGNING_REJECTED", [msg], network, retriesUsed + 1);
+            return buildFailure(network, retriesUsed, {
+                type: "SIGNING_REJECTED",
+                logs: [msg],
+                ...aiFields,
+            });
+        }
+        // ── STEP 6: TRANSACTION SUBMISSION ───────────────────────────────────────
+        let signature;
+        try {
+            const raw = serializeTx(signedTx);
+            signature = await connection.sendRawTransaction(raw, {
+                skipPreflight: true, // safe — already simulated in Step 3
+                preflightCommitment: "confirmed",
+                maxRetries: 2,
+            });
+        }
+        catch (err) {
+            const msg = (0, utils_1.sanitizeMessage)(err.message);
+            if (mode === "safe" && retriesUsed < MAX_RETRIES) {
+                retriesUsed++;
+                continue;
+            }
+            const aiFields = await fetchAIFields(ai, "SEND_FAILED", [msg], network, retriesUsed + 1);
+            return buildFailure(network, retriesUsed, {
+                type: "SEND_FAILED",
+                logs: [msg],
+                ...aiFields,
+            });
+        }
+        // ── STEP 7: CONFIRMATION LOOP ─────────────────────────────────────────────
+        const confirmResult = await waitForConfirmation(connection, signature, lastValidBlockHeight);
+        if (confirmResult === "confirmed") {
+            return { success: true, signature, network, retriesUsed };
+        }
+        // ── STEP 8: RETRY ENGINE (SAFE ONLY) ─────────────────────────────────────
+        // Only retry when the blockhash provably expired — transaction is dead,
+        // no risk of duplicating a confirmed send.
+        if (confirmResult === "expired" && mode === "safe" && retriesUsed < MAX_RETRIES) {
+            retriesUsed++;
+            continue; // Step 2 attaches a fresh blockhash
+        }
+        // ── STEP 9: FINAL RESPONSE ────────────────────────────────────────────────
+        const finalType = confirmResult === "expired" ? "BLOCKHASH_EXPIRED" : "CONFIRMATION_TIMEOUT";
+        const aiFields = await fetchAIFields(ai, finalType, [], network, retriesUsed + 1);
+        return buildFailure(network, retriesUsed, {
+            type: finalType,
+            ...(aiFields.explanation && {
+                explanation: `Transaction (${signature}) could not be confirmed. ${aiFields.explanation}`,
+                suggestedFix: aiFields.suggestedFix,
+            }),
+        });
+    }
+}
+// ─── Internal helpers ─────────────────────────────────────────────────────────
+/**
+ * Fetch AI explanation fields when ai=true.
+ * Returns an empty object when ai=false so callers can spread it safely.
+ */
+async function fetchAIFields(ai, type, logs, network, attempts) {
+    if (!ai)
+        return {};
+    const data = await (0, aiExplainer_1.explain)(type, logs, network, attempts);
+    return { explanation: data.explanation, suggestedFix: data.fixSuggestion };
+}
+function attachBlockhash(tx, blockhash, lastValidBlockHeight) {
+    if (tx instanceof web3_js_1.Transaction) {
+        tx.recentBlockhash = blockhash;
+        tx.lastValidBlockHeight = lastValidBlockHeight;
+    }
+    else {
+        tx.message.recentBlockhash = blockhash;
+    }
+}
+function serializeTx(tx) {
+    if (tx instanceof web3_js_1.Transaction)
+        return tx.serialize();
+    return tx.serialize();
+}
+async function runSimulation(connection, tx) {
+    // Cast required: web3.js has different overloads for Transaction vs VersionedTransaction.
+    // sigVerify: false allows simulation of an unsigned transaction.
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const res = await connection.simulateTransaction(tx, tx instanceof web3_js_1.Transaction ? undefined : { sigVerify: false });
+    return { err: res.value.err ?? null, logs: res.value.logs ?? null };
+}
+async function waitForConfirmation(connection, signature, lastValidBlockHeight) {
+    const deadline = Date.now() + CONFIRMATION_TIMEOUT_MS;
+    while (Date.now() < deadline) {
+        try {
+            const blockHeight = await connection.getBlockHeight("confirmed");
+            if (blockHeight > lastValidBlockHeight)
+                return "expired";
+            const statuses = await connection.getSignatureStatuses([signature]);
+            const status = statuses?.value?.[0];
+            if (status?.err)
+                return "timeout"; // on-chain execution error — not retriable
+            if (status?.confirmationStatus === "confirmed" ||
+                status?.confirmationStatus === "finalized") {
+                return "confirmed";
+            }
+        }
+        catch {
+            // Transient RPC error — keep polling until deadline.
+        }
+        await sleep(CONFIRMATION_POLL_MS);
+    }
+    return "timeout";
+}
+function buildFailure(network, retriesUsed, error) {
+    return { success: false, network, retriesUsed, error };
+}
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+//# sourceMappingURL=index.js.map

package/dist/safeSend/index.js.map

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

package/dist/safeSend/types.d.ts

@@ -0,0 +1,39 @@
+import { Transaction, VersionedTransaction } from "@solana/web3.js";
+export type SafeSendNetwork = "devnet" | "mainnet-beta";
+export type SafeSendMode = "safe" | "fast";
+export type ErrorType = "INSUFFICIENT_FUNDS" | "BLOCKHASH_EXPIRED" | "COMPUTE_EXCEEDED" | "INVALID_INSTRUCTION" | "NETWORK_FAILURE" | "SEND_FAILED" | "SIGNING_REJECTED" | "CONFIRMATION_TIMEOUT" | "INVALID_INPUT" | "MAX_RETRIES_EXCEEDED" | "UNKNOWN";
+export interface WalletAdapter {
+    signTransaction<T extends Transaction | VersionedTransaction>(tx: T): Promise<T>;
+}
+export interface SafeSendOptions {
+    tx: Transaction | VersionedTransaction;
+    wallet: WalletAdapter;
+    network?: SafeSendNetwork;
+    mode?: SafeSendMode;
+    ai?: boolean;
+}
+export interface SafeSendError {
+    type: ErrorType | string;
+    logs?: string[];
+    explanation?: string;
+    suggestedFix?: string;
+}
+export interface SafeSendResult {
+    success: boolean;
+    signature?: string;
+    network: SafeSendNetwork;
+    retriesUsed: number;
+    error?: SafeSendError;
+}
+export interface SimulationError {
+    type: ErrorType;
+    logs: string[];
+    recoverable: boolean;
+}
+export interface AIExplanation {
+    explanation: string;
+    fixSuggestion: string;
+    confidenceScore: number;
+}
+export type ConfirmationStatus = "confirmed" | "expired" | "timeout";
+//# sourceMappingURL=types.d.ts.map

package/dist/safeSend/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/safeSend/types.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,oBAAoB,EAAE,MAAM,iBAAiB,CAAC;AAIpE,MAAM,MAAM,eAAe,GAAG,QAAQ,GAAG,cAAc,CAAC;AACxD,MAAM,MAAM,YAAY,GAAG,MAAM,GAAG,MAAM,CAAC;AAI3C,MAAM,MAAM,SAAS,GACjB,oBAAoB,GACpB,mBAAmB,GACnB,kBAAkB,GAClB,qBAAqB,GACrB,iBAAiB,GACjB,aAAa,GACb,kBAAkB,GAClB,sBAAsB,GACtB,eAAe,GACf,sBAAsB,GACtB,SAAS,CAAC;AAId,MAAM,WAAW,aAAa;IAC5B,eAAe,CAAC,CAAC,SAAS,WAAW,GAAG,oBAAoB,EAAE,EAAE,EAAE,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;CAClF;AAID,MAAM,WAAW,eAAe;IAC9B,EAAE,EAAE,WAAW,GAAG,oBAAoB,CAAC;IACvC,MAAM,EAAE,aAAa,CAAC;IACtB,OAAO,CAAC,EAAE,eAAe,CAAC;IAC1B,IAAI,CAAC,EAAE,YAAY,CAAC;IACpB,EAAE,CAAC,EAAE,OAAO,CAAC;CACd;AAED,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,SAAS,GAAG,MAAM,CAAC;IACzB,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;IAChB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAED,MAAM,WAAW,cAAc;IAC7B,OAAO,EAAE,OAAO,CAAC;IACjB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,OAAO,EAAE,eAAe,CAAC;IACzB,WAAW,EAAE,MAAM,CAAC;IACpB,KAAK,CAAC,EAAE,aAAa,CAAC;CACvB;AAID,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,SAAS,CAAC;IAChB,IAAI,EAAE,MAAM,EAAE,CAAC;IACf,WAAW,EAAE,OAAO,CAAC;CACtB;AAED,MAAM,WAAW,aAAa;IAC5B,WAAW,EAAE,MAAM,CAAC;IACpB,aAAa,EAAE,MAAM,CAAC;IACtB,eAAe,EAAE,MAAM,CAAC;CACzB;AAED,MAAM,MAAM,kBAAkB,GAAG,WAAW,GAAG,SAAS,GAAG,SAAS,CAAC"}

package/dist/safeSend/types.js

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

package/dist/safeSend/types.js.map

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

package/dist/safeSend/utils.d.ts

@@ -0,0 +1,14 @@
+import type { SafeSendOptions } from "./types";
+/**
+ * Strip API keys from RPC URLs that may appear in error messages.
+ * Helius and similar providers embed the key as ?api-key=<value>.
+ */
+export declare function sanitizeMessage(message: string): string;
+/**
+ * Truncate simulation logs to prevent oversized payloads reaching the caller.
+ * Keeps the first N lines which contain the most useful diagnostic info.
+ */
+export declare function truncateLogs(logs: string[], maxLines?: number): string[];
+/** Validate safeSend inputs. Returns an error string or null if valid. */
+export declare function validateInput(options: SafeSendOptions): string | null;
+//# sourceMappingURL=utils.d.ts.map

package/dist/safeSend/utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"utils.d.ts","sourceRoot":"","sources":["../../src/safeSend/utils.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,SAAS,CAAC;AAE/C;;;GAGG;AACH,wBAAgB,eAAe,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAEvD;AAED;;;GAGG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,QAAQ,SAAK,GAAG,MAAM,EAAE,CAMpE;AAED,0EAA0E;AAC1E,wBAAgB,aAAa,CAAC,OAAO,EAAE,eAAe,GAAG,MAAM,GAAG,IAAI,CAiCrE"}

package/dist/safeSend/utils.js

@@ -0,0 +1,51 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.sanitizeMessage = sanitizeMessage;
+exports.truncateLogs = truncateLogs;
+exports.validateInput = validateInput;
+const web3_js_1 = require("@solana/web3.js");
+/**
+ * Strip API keys from RPC URLs that may appear in error messages.
+ * Helius and similar providers embed the key as ?api-key=<value>.
+ */
+function sanitizeMessage(message) {
+    return message.replace(/([?&]api-key=)[^&\s"']*/gi, "$1***");
+}
+/**
+ * Truncate simulation logs to prevent oversized payloads reaching the caller.
+ * Keeps the first N lines which contain the most useful diagnostic info.
+ */
+function truncateLogs(logs, maxLines = 20) {
+    if (logs.length <= maxLines)
+        return logs;
+    return [
+        ...logs.slice(0, maxLines),
+        `... (${logs.length - maxLines} more lines truncated)`,
+    ];
+}
+/** Validate safeSend inputs. Returns an error string or null if valid. */
+function validateInput(options) {
+    if (!options.tx)
+        return "options.tx is required";
+    if (!(options.tx instanceof web3_js_1.Transaction) &&
+        !(options.tx instanceof web3_js_1.VersionedTransaction)) {
+        return "options.tx must be a Transaction or VersionedTransaction instance";
+    }
+    if (!options.wallet)
+        return "options.wallet is required";
+    if (typeof options.wallet.signTransaction !== "function") {
+        return "options.wallet must implement signTransaction()";
+    }
+    if (options.network !== undefined &&
+        options.network !== "devnet" &&
+        options.network !== "mainnet-beta") {
+        return 'options.network must be "devnet" or "mainnet-beta"';
+    }
+    if (options.mode !== undefined &&
+        options.mode !== "safe" &&
+        options.mode !== "fast") {
+        return 'options.mode must be "safe" or "fast"';
+    }
+    return null;
+}
+//# sourceMappingURL=utils.js.map

package/dist/safeSend/utils.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"utils.js","sourceRoot":"","sources":["../../src/safeSend/utils.ts"],"names":[],"mappings":";;AAOA,0CAEC;AAMD,oCAMC;AAGD,sCAiCC;AAzDD,6CAAoE;AAGpE;;;GAGG;AACH,SAAgB,eAAe,CAAC,OAAe;IAC7C,OAAO,OAAO,CAAC,OAAO,CAAC,2BAA2B,EAAE,OAAO,CAAC,CAAC;AAC/D,CAAC;AAED;;;GAGG;AACH,SAAgB,YAAY,CAAC,IAAc,EAAE,QAAQ,GAAG,EAAE;IACxD,IAAI,IAAI,CAAC,MAAM,IAAI,QAAQ;QAAE,OAAO,IAAI,CAAC;IACzC,OAAO;QACL,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,QAAQ,CAAC;QAC1B,QAAQ,IAAI,CAAC,MAAM,GAAG,QAAQ,wBAAwB;KACvD,CAAC;AACJ,CAAC;AAED,0EAA0E;AAC1E,SAAgB,aAAa,CAAC,OAAwB;IACpD,IAAI,CAAC,OAAO,CAAC,EAAE;QAAE,OAAO,wBAAwB,CAAC;IAEjD,IACE,CAAC,CAAC,OAAO,CAAC,EAAE,YAAY,qBAAW,CAAC;QACpC,CAAC,CAAC,OAAO,CAAC,EAAE,YAAY,8BAAoB,CAAC,EAC7C,CAAC;QACD,OAAO,mEAAmE,CAAC;IAC7E,CAAC;IAED,IAAI,CAAC,OAAO,CAAC,MAAM;QAAE,OAAO,4BAA4B,CAAC;IAEzD,IAAI,OAAO,OAAO,CAAC,MAAM,CAAC,eAAe,KAAK,UAAU,EAAE,CAAC;QACzD,OAAO,iDAAiD,CAAC;IAC3D,CAAC;IAED,IACE,OAAO,CAAC,OAAO,KAAK,SAAS;QAC7B,OAAO,CAAC,OAAO,KAAK,QAAQ;QAC5B,OAAO,CAAC,OAAO,KAAK,cAAc,EAClC,CAAC;QACD,OAAO,oDAAoD,CAAC;IAC9D,CAAC;IAED,IACE,OAAO,CAAC,IAAI,KAAK,SAAS;QAC1B,OAAO,CAAC,IAAI,KAAK,MAAM;QACvB,OAAO,CAAC,IAAI,KAAK,MAAM,EACvB,CAAC;QACD,OAAO,uCAAuC,CAAC;IACjD,CAAC;IAED,OAAO,IAAI,CAAC;AACd,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "fema-pf-calc",
-  "version": "1.0.6",
+  "version": "1.1.0",
   "description": "Intelligent Solana priority fee estimation engine",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -22,6 +22,7 @@
     "build": "tsc",
     "prepublishOnly": "npm run build",
     "dev": "ts-node test-fees.ts",
+    "test:safesend": "ts-node test-safesend.ts",
     "lint": "eslint src/**/*.ts"
   },
   "keywords": [
@@ -41,5 +42,8 @@
     "express": "^4.21.2",
     "ts-node": "^10.9.2",
     "typescript": "^5.8.3"
+  },
+  "dependencies": {
+    "groq-sdk": "^1.1.2"
   }
 }