quicknode-solana-kit 1.0.0

package/dist/transactions/smart-transaction.js

@@ -0,0 +1,112 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.sendSmartTransaction = sendSmartTransaction;
+exports.prepareSmartTransaction = prepareSmartTransaction;
+const web3_js_1 = require("@solana/web3.js");
+const errors_1 = require("../types/errors");
+const helpers_1 = require("../utils/helpers");
+const priority_fees_1 = require("./priority-fees");
+const DEFAULTS = {
+    feeLevel: 'recommended',
+    useJito: false,
+    maxRetries: 5,
+    simulateFirst: true,
+    computeUnitBuffer: 10,
+    skipPreflight: false,
+};
+async function sendSmartTransaction(config, params) {
+    const opts = { ...DEFAULTS, ...params.options };
+    const conn = (0, helpers_1.createConnection)(config);
+    const startTime = Date.now();
+    let computeUnits = 200_000;
+    if (opts.simulateFirst) {
+        computeUnits = await simulateCU(conn, params.transaction, params.signer, opts.computeUnitBuffer);
+    }
+    let priorityFee = 1_000;
+    try {
+        const fees = await (0, priority_fees_1.estimatePriorityFees)(config);
+        priorityFee = (0, priority_fees_1.feeForLevel)(fees, opts.feeLevel);
+    }
+    catch {
+        console.warn('[QNSolanaKit] Priority fee estimation failed — using fallback 1000 µlamports/CU');
+    }
+    const tx = buildTxWithBudget(params.transaction, computeUnits, priorityFee);
+    let lastError;
+    for (let attempt = 0; attempt <= opts.maxRetries; attempt++) {
+        try {
+            const { blockhash, lastValidBlockHeight } = await conn.getLatestBlockhash('confirmed');
+            tx.recentBlockhash = blockhash;
+            tx.feePayer = params.signer.publicKey;
+            tx.sign(params.signer);
+            const signature = await conn.sendRawTransaction(tx.serialize(), {
+                skipPreflight: opts.skipPreflight,
+                maxRetries: 0,
+            });
+            const confirmation = await conn.confirmTransaction({ signature, blockhash, lastValidBlockHeight }, config.commitment ?? 'confirmed');
+            if (confirmation.value.err) {
+                throw new errors_1.TransactionFailedError(signature, confirmation.value.err);
+            }
+            const txInfo = await conn.getTransaction(signature, {
+                commitment: 'confirmed',
+                maxSupportedTransactionVersion: 0,
+            });
+            return {
+                signature,
+                slot: txInfo?.slot ?? 0,
+                priorityFeeMicroLamports: priorityFee,
+                computeUnitsUsed: computeUnits,
+                jitoBundle: false,
+                confirmationMs: Date.now() - startTime,
+            };
+        }
+        catch (err) {
+            lastError = err;
+            if (err instanceof errors_1.TransactionFailedError)
+                throw err;
+            if (attempt < opts.maxRetries) {
+                console.warn(`[QNSolanaKit] Attempt ${attempt + 1} failed, retrying...`);
+                await (0, helpers_1.sleep)((0, helpers_1.backoffMs)(attempt));
+            }
+        }
+    }
+    throw new errors_1.MaxRetriesExceededError(opts.maxRetries, lastError);
+}
+async function prepareSmartTransaction(config, params) {
+    const opts = { ...DEFAULTS, ...params.options };
+    const conn = (0, helpers_1.createConnection)(config);
+    let priorityFee = 1_000;
+    let computeUnits = 200_000;
+    try {
+        const fees = await (0, priority_fees_1.estimatePriorityFees)(config);
+        priorityFee = (0, priority_fees_1.feeForLevel)(fees, opts.feeLevel);
+    }
+    catch { /* use fallback */ }
+    const tx = buildTxWithBudget(params.transaction, computeUnits, priorityFee);
+    const { blockhash } = await conn.getLatestBlockhash('confirmed');
+    tx.recentBlockhash = blockhash;
+    tx.feePayer = params.payer;
+    return { transaction: tx, priorityFeeMicroLamports: priorityFee, computeUnits };
+}
+async function simulateCU(conn, tx, signer, bufferPct) {
+    try {
+        const simTx = new web3_js_1.Transaction().add(web3_js_1.ComputeBudgetProgram.setComputeUnitLimit({ units: 1_400_000 }), ...tx.instructions);
+        const { blockhash } = await conn.getLatestBlockhash('confirmed');
+        simTx.recentBlockhash = blockhash;
+        simTx.feePayer = signer.publicKey;
+        const sim = await conn.simulateTransaction(simTx, [signer], true);
+        if (sim.value.err)
+            return 200_000;
+        const estimated = sim.value.unitsConsumed ?? 200_000;
+        return Math.ceil(estimated * (1 + bufferPct / 100));
+    }
+    catch {
+        return 200_000;
+    }
+}
+function buildTxWithBudget(tx, cu, fee) {
+    const ixs = tx.instructions.filter((ix) => !ix.programId.equals(web3_js_1.ComputeBudgetProgram.programId));
+    const newTx = new web3_js_1.Transaction();
+    newTx.add(web3_js_1.ComputeBudgetProgram.setComputeUnitLimit({ units: cu }), web3_js_1.ComputeBudgetProgram.setComputeUnitPrice({ microLamports: fee }), ...ixs);
+    return newTx;
+}
+//# sourceMappingURL=smart-transaction.js.map

package/dist/transactions/smart-transaction.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"smart-transaction.js","sourceRoot":"","sources":["../../src/transactions/smart-transaction.ts"],"names":[],"mappings":";;AAsBA,oDAoEC;AAED,0DAyBC;AArHD,6CAOyB;AAEzB,4CAAkF;AAClF,8CAAsE;AACtE,mDAAoE;AAEpE,MAAM,QAAQ,GAAiC;IAC7C,QAAQ,EAAW,aAAa;IAChC,OAAO,EAAY,KAAK;IACxB,UAAU,EAAS,CAAC;IACpB,aAAa,EAAM,IAAI;IACvB,iBAAiB,EAAE,EAAE;IACrB,aAAa,EAAM,KAAK;CACzB,CAAC;AAEK,KAAK,UAAU,oBAAoB,CACxC,MAAgB,EAChB,MAAmF;IAEnF,MAAM,IAAI,GAAQ,EAAE,GAAG,QAAQ,EAAE,GAAG,MAAM,CAAC,OAAO,EAAE,CAAC;IACrD,MAAM,IAAI,GAAQ,IAAA,0BAAgB,EAAC,MAAM,CAAC,CAAC;IAC3C,MAAM,SAAS,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;IAE7B,IAAI,YAAY,GAAG,OAAO,CAAC;IAC3B,IAAI,IAAI,CAAC,aAAa,EAAE,CAAC;QACvB,YAAY,GAAG,MAAM,UAAU,CAAC,IAAI,EAAE,MAAM,CAAC,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,IAAI,CAAC,iBAAiB,CAAC,CAAC;IACnG,CAAC;IAED,IAAI,WAAW,GAAG,KAAK,CAAC;IACxB,IAAI,CAAC;QACH,MAAM,IAAI,GAAG,MAAM,IAAA,oCAAoB,EAAC,MAAM,CAAC,CAAC;QAChD,WAAW,GAAG,IAAA,2BAAW,EAAC,IAAI,EAAE,IAAI,CAAC,QAAQ,CAAC,CAAC;IACjD,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,CAAC,IAAI,CAAC,iFAAiF,CAAC,CAAC;IAClG,CAAC;IAED,MAAM,EAAE,GAAG,iBAAiB,CAAC,MAAM,CAAC,WAAW,EAAE,YAAY,EAAE,WAAW,CAAC,CAAC;IAE5E,IAAI,SAAkB,CAAC;IACvB,KAAK,IAAI,OAAO,GAAG,CAAC,EAAE,OAAO,IAAI,IAAI,CAAC,UAAU,EAAE,OAAO,EAAE,EAAE,CAAC;QAC5D,IAAI,CAAC;YACH,MAAM,EAAE,SAAS,EAAE,oBAAoB,EAAE,GAAG,MAAM,IAAI,CAAC,kBAAkB,CAAC,WAAW,CAAC,CAAC;YACvF,EAAE,CAAC,eAAe,GAAG,SAAS,CAAC;YAC/B,EAAE,CAAC,QAAQ,GAAU,MAAM,CAAC,MAAM,CAAC,SAAS,CAAC;YAC7C,EAAE,CAAC,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;YAEvB,MAAM,SAAS,GAAG,MAAM,IAAI,CAAC,kBAAkB,CAAC,EAAE,CAAC,SAAS,EAAE,EAAE;gBAC9D,aAAa,EAAE,IAAI,CAAC,aAAa;gBACjC,UAAU,EAAK,CAAC;aACjB,CAAC,CAAC;YAEH,MAAM,YAAY,GAAG,MAAM,IAAI,CAAC,kBAAkB,CAChD,EAAE,SAAS,EAAE,SAAS,EAAE,oBAAoB,EAAE,EAC9C,MAAM,CAAC,UAAU,IAAI,WAAW,CACjC,CAAC;YAEF,IAAI,YAAY,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC;gBAC3B,MAAM,IAAI,+BAAsB,CAAC,SAAS,EAAE,YAAY,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;YACtE,CAAC;YAED,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,cAAc,CAAC,SAAS,EAAE;gBAClD,UAAU,EAAE,WAAW;gBACvB,8BAA8B,EAAE,CAAC;aAClC,CAAC,CAAC;YAEH,OAAO;gBACL,SAAS;gBACT,IAAI,EAAsB,MAAM,EAAE,IAAI,IAAI,CAAC;gBAC3C,wBAAwB,EAAE,WAAW;gBACrC,gBAAgB,EAAU,YAAY;gBACtC,UAAU,EAAgB,KAAK;gBAC/B,cAAc,EAAY,IAAI,CAAC,GAAG,EAAE,GAAG,SAAS;aACjD,CAAC;QACJ,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,SAAS,GAAG,GAAG,CAAC;YAChB,IAAI,GAAG,YAAY,+BAAsB;gBAAE,MAAM,GAAG,CAAC;YACrD,IAAI,OAAO,GAAG,IAAI,CAAC,UAAU,EAAE,CAAC;gBAC9B,OAAO,CAAC,IAAI,CAAC,yBAAyB,OAAO,GAAG,CAAC,sBAAsB,CAAC,CAAC;gBACzE,MAAM,IAAA,eAAK,EAAC,IAAA,mBAAS,EAAC,OAAO,CAAC,CAAC,CAAC;YAClC,CAAC;QACH,CAAC;IACH,CAAC;IACD,MAAM,IAAI,gCAAuB,CAAC,IAAI,CAAC,UAAU,EAAE,SAAS,CAAC,CAAC;AAChE,CAAC;AAEM,KAAK,UAAU,uBAAuB,CAC3C,MAAgB,EAChB,MAIC;IAED,MAAM,IAAI,GAAG,EAAE,GAAG,QAAQ,EAAE,GAAG,MAAM,CAAC,OAAO,EAAE,CAAC;IAChD,MAAM,IAAI,GAAG,IAAA,0BAAgB,EAAC,MAAM,CAAC,CAAC;IAEtC,IAAI,WAAW,GAAI,KAAK,CAAC;IACzB,IAAI,YAAY,GAAG,OAAO,CAAC;IAE3B,IAAI,CAAC;QACH,MAAM,IAAI,GAAG,MAAM,IAAA,oCAAoB,EAAC,MAAM,CAAC,CAAC;QAChD,WAAW,GAAG,IAAA,2BAAW,EAAC,IAAI,EAAE,IAAI,CAAC,QAAQ,CAAC,CAAC;IACjD,CAAC;IAAC,MAAM,CAAC,CAAC,kBAAkB,CAAC,CAAC;IAE9B,MAAM,EAAE,GAAG,iBAAiB,CAAC,MAAM,CAAC,WAAW,EAAE,YAAY,EAAE,WAAW,CAAC,CAAC;IAC5E,MAAM,EAAE,SAAS,EAAE,GAAG,MAAM,IAAI,CAAC,kBAAkB,CAAC,WAAW,CAAC,CAAC;IACjE,EAAE,CAAC,eAAe,GAAG,SAAS,CAAC;IAC/B,EAAE,CAAC,QAAQ,GAAU,MAAM,CAAC,KAAK,CAAC;IAElC,OAAO,EAAE,WAAW,EAAE,EAAE,EAAE,wBAAwB,EAAE,WAAW,EAAE,YAAY,EAAE,CAAC;AAClF,CAAC;AAED,KAAK,UAAU,UAAU,CACvB,IAAgB,EAChB,EAAe,EACf,MAAe,EACf,SAAiB;IAEjB,IAAI,CAAC;QACH,MAAM,KAAK,GAAG,IAAI,qBAAW,EAAE,CAAC,GAAG,CACjC,8BAAoB,CAAC,mBAAmB,CAAC,EAAE,KAAK,EAAE,SAAS,EAAE,CAAC,EAC9D,GAAG,EAAE,CAAC,YAAY,CACnB,CAAC;QACF,MAAM,EAAE,SAAS,EAAE,GAAG,MAAM,IAAI,CAAC,kBAAkB,CAAC,WAAW,CAAC,CAAC;QACjE,KAAK,CAAC,eAAe,GAAG,SAAS,CAAC;QAClC,KAAK,CAAC,QAAQ,GAAU,MAAM,CAAC,SAAS,CAAC;QACzC,MAAM,GAAG,GAAG,MAAM,IAAI,CAAC,mBAAmB,CAAC,KAAK,EAAE,CAAC,MAAM,CAAC,EAAE,IAAI,CAAC,CAAC;QAClE,IAAI,GAAG,CAAC,KAAK,CAAC,GAAG;YAAE,OAAO,OAAO,CAAC;QAClC,MAAM,SAAS,GAAG,GAAG,CAAC,KAAK,CAAC,aAAa,IAAI,OAAO,CAAC;QACrD,OAAO,IAAI,CAAC,IAAI,CAAC,SAAS,GAAG,CAAC,CAAC,GAAG,SAAS,GAAG,GAAG,CAAC,CAAC,CAAC;IACtD,CAAC;IAAC,MAAM,CAAC;QAAC,OAAO,OAAO,CAAC;IAAC,CAAC;AAC7B,CAAC;AAED,SAAS,iBAAiB,CAAC,EAAe,EAAE,EAAU,EAAE,GAAW;IACjE,MAAM,GAAG,GAAG,EAAE,CAAC,YAAY,CAAC,MAAM,CAChC,CAAC,EAA0B,EAAE,EAAE,CAAC,CAAC,EAAE,CAAC,SAAS,CAAC,MAAM,CAAC,8BAAoB,CAAC,SAAS,CAAC,CACrF,CAAC;IACF,MAAM,KAAK,GAAG,IAAI,qBAAW,EAAE,CAAC;IAChC,KAAK,CAAC,GAAG,CACP,8BAAoB,CAAC,mBAAmB,CAAC,EAAE,KAAK,EAAE,EAAE,EAAE,CAAC,EACvD,8BAAoB,CAAC,mBAAmB,CAAC,EAAE,aAAa,EAAE,GAAG,EAAE,CAAC,EAChE,GAAG,GAAG,CACP,CAAC;IACF,OAAO,KAAK,CAAC;AACf,CAAC"}

package/dist/types/errors.d.ts

@@ -0,0 +1,61 @@
+/**
+ * Custom errors for @quicknode/solana-kit
+ *
+ * Every error tells the developer exactly what went wrong
+ * and exactly how to fix it — no cryptic RPC errors.
+ */
+export declare class QNError extends Error {
+    readonly code: string;
+    readonly details?: unknown | undefined;
+    constructor(message: string, code: string, details?: unknown | undefined);
+}
+/**
+ * Thrown when you call a method that requires a QuickNode add-on
+ * that isn't enabled on your endpoint.
+ *
+ * How to fix: Go to https://dashboard.quicknode.com → your endpoint → Add-ons
+ */
+export declare class AddOnNotEnabledError extends QNError {
+    readonly addOnName: string;
+    readonly tier: 'free' | 'paid';
+    constructor(addOnName: string, tier: 'free' | 'paid');
+}
+/**
+ * Thrown when a transaction is not confirmed within the timeout period.
+ * Usually means the network is congested or the fee was too low.
+ */
+export declare class TransactionTimeoutError extends QNError {
+    readonly signature: string;
+    constructor(signature: string);
+}
+/**
+ * Thrown when a transaction fails on-chain (e.g. slippage exceeded,
+ * program error, insufficient funds for the instruction).
+ */
+export declare class TransactionFailedError extends QNError {
+    readonly signature: string;
+    readonly reason: unknown;
+    constructor(signature: string, reason: unknown);
+}
+/**
+ * Thrown when the transaction fails after all retry attempts.
+ */
+export declare class MaxRetriesExceededError extends QNError {
+    readonly maxRetries: number;
+    readonly lastError: unknown;
+    constructor(maxRetries: number, lastError: unknown);
+}
+/**
+ * Thrown when the endpoint URL is missing or malformed.
+ */
+export declare class InvalidEndpointError extends QNError {
+    constructor(url: string);
+}
+/**
+ * Thrown when the RPC request itself fails (network error, bad response, etc.)
+ */
+export declare class RPCError extends QNError {
+    readonly statusCode: number;
+    constructor(method: string, statusCode: number, body: string);
+}
+//# sourceMappingURL=errors.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../src/types/errors.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,qBAAa,OAAQ,SAAQ,KAAK;aAGd,IAAI,EAAE,MAAM;aACZ,OAAO,CAAC,EAAE,OAAO;gBAFjC,OAAO,EAAE,MAAM,EACC,IAAI,EAAE,MAAM,EACZ,OAAO,CAAC,EAAE,OAAO,YAAA;CAMpC;AAID;;;;;GAKG;AACH,qBAAa,oBAAqB,SAAQ,OAAO;aAE7B,SAAS,EAAE,MAAM;aACjB,IAAI,EAAE,MAAM,GAAG,MAAM;gBADrB,SAAS,EAAE,MAAM,EACjB,IAAI,EAAE,MAAM,GAAG,MAAM;CAqBxC;AAID;;;GAGG;AACH,qBAAa,uBAAwB,SAAQ,OAAO;aACtB,SAAS,EAAE,MAAM;gBAAjB,SAAS,EAAE,MAAM;CAY9C;AAID;;;GAGG;AACH,qBAAa,sBAAuB,SAAQ,OAAO;aAE/B,SAAS,EAAE,MAAM;aACjB,MAAM,EAAE,OAAO;gBADf,SAAS,EAAE,MAAM,EACjB,MAAM,EAAE,OAAO;CAalC;AAID;;GAEG;AACH,qBAAa,uBAAwB,SAAQ,OAAO;aAEhC,UAAU,EAAE,MAAM;aAClB,SAAS,EAAE,OAAO;gBADlB,UAAU,EAAE,MAAM,EAClB,SAAS,EAAE,OAAO;CAYrC;AAID;;GAEG;AACH,qBAAa,oBAAqB,SAAQ,OAAO;gBACnC,GAAG,EAAE,MAAM;CAWxB;AAID;;GAEG;AACH,qBAAa,QAAS,SAAQ,OAAO;aAGjB,UAAU,EAAE,MAAM;gBADlC,MAAM,EAAE,MAAM,EACE,UAAU,EAAE,MAAM,EAClC,IAAI,EAAE,MAAM;CAcf"}

package/dist/types/errors.js

@@ -0,0 +1,139 @@
+"use strict";
+/**
+ * Custom errors for @quicknode/solana-kit
+ *
+ * Every error tells the developer exactly what went wrong
+ * and exactly how to fix it — no cryptic RPC errors.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RPCError = exports.InvalidEndpointError = exports.MaxRetriesExceededError = exports.TransactionFailedError = exports.TransactionTimeoutError = exports.AddOnNotEnabledError = exports.QNError = void 0;
+class QNError extends Error {
+    code;
+    details;
+    constructor(message, code, details) {
+        super(message);
+        this.code = code;
+        this.details = details;
+        this.name = 'QNError';
+        Object.setPrototypeOf(this, new.target.prototype);
+    }
+}
+exports.QNError = QNError;
+// ─────────────────────────────────────────────────────────────
+/**
+ * Thrown when you call a method that requires a QuickNode add-on
+ * that isn't enabled on your endpoint.
+ *
+ * How to fix: Go to https://dashboard.quicknode.com → your endpoint → Add-ons
+ */
+class AddOnNotEnabledError extends QNError {
+    addOnName;
+    tier;
+    constructor(addOnName, tier) {
+        const tierNote = tier === 'free'
+            ? 'This is a FREE add-on — enable it in under 30 seconds.'
+            : 'This is a PAID add-on — requires a QuickNode paid plan.';
+        super(`\n\n  ❌ Add-on not enabled: "${addOnName}"\n\n` +
+            `  ${tierNote}\n\n` +
+            `  How to fix:\n` +
+            `  1. Go to https://dashboard.quicknode.com\n` +
+            `  2. Click on your endpoint\n` +
+            `  3. Go to the "Add-ons" tab\n` +
+            `  4. Enable "${addOnName}"\n` +
+            `  5. Set addOns.${addOnName.toLowerCase().replace(/\s/g, '')}: true in your QNSolanaKit config\n`, 'ADD_ON_NOT_ENABLED', { addOnName, tier });
+        this.addOnName = addOnName;
+        this.tier = tier;
+        this.name = 'AddOnNotEnabledError';
+        Object.setPrototypeOf(this, new.target.prototype);
+    }
+}
+exports.AddOnNotEnabledError = AddOnNotEnabledError;
+// ─────────────────────────────────────────────────────────────
+/**
+ * Thrown when a transaction is not confirmed within the timeout period.
+ * Usually means the network is congested or the fee was too low.
+ */
+class TransactionTimeoutError extends QNError {
+    signature;
+    constructor(signature) {
+        super(`Transaction not confirmed within timeout.\n` +
+            `  Signature: ${signature}\n` +
+            `  Try: increase feeLevel to 'high' or 'extreme'\n` +
+            `  Explorer: https://explorer.solana.com/tx/${signature}`, 'TX_TIMEOUT', { signature });
+        this.signature = signature;
+        this.name = 'TransactionTimeoutError';
+        Object.setPrototypeOf(this, new.target.prototype);
+    }
+}
+exports.TransactionTimeoutError = TransactionTimeoutError;
+// ─────────────────────────────────────────────────────────────
+/**
+ * Thrown when a transaction fails on-chain (e.g. slippage exceeded,
+ * program error, insufficient funds for the instruction).
+ */
+class TransactionFailedError extends QNError {
+    signature;
+    reason;
+    constructor(signature, reason) {
+        super(`Transaction failed on-chain.\n` +
+            `  Signature: ${signature}\n` +
+            `  Reason: ${JSON.stringify(reason)}\n` +
+            `  Explorer: https://explorer.solana.com/tx/${signature}`, 'TX_FAILED', { signature, reason });
+        this.signature = signature;
+        this.reason = reason;
+        this.name = 'TransactionFailedError';
+        Object.setPrototypeOf(this, new.target.prototype);
+    }
+}
+exports.TransactionFailedError = TransactionFailedError;
+// ─────────────────────────────────────────────────────────────
+/**
+ * Thrown when the transaction fails after all retry attempts.
+ */
+class MaxRetriesExceededError extends QNError {
+    maxRetries;
+    lastError;
+    constructor(maxRetries, lastError) {
+        super(`Transaction failed after ${maxRetries} retries.\n` +
+            `  Last error: ${lastError instanceof Error ? lastError.message : String(lastError)}\n` +
+            `  Try: increase maxRetries, use a higher feeLevel, or check your transaction logic.`, 'TX_MAX_RETRIES', { maxRetries, lastError });
+        this.maxRetries = maxRetries;
+        this.lastError = lastError;
+        this.name = 'MaxRetriesExceededError';
+        Object.setPrototypeOf(this, new.target.prototype);
+    }
+}
+exports.MaxRetriesExceededError = MaxRetriesExceededError;
+// ─────────────────────────────────────────────────────────────
+/**
+ * Thrown when the endpoint URL is missing or malformed.
+ */
+class InvalidEndpointError extends QNError {
+    constructor(url) {
+        super(`Invalid QuickNode endpoint URL: "${url}"\n` +
+            `  Expected: https://your-name.solana-mainnet.quiknode.pro/TOKEN/\n` +
+            `  Get one free at: https://dashboard.quicknode.com`, 'INVALID_ENDPOINT', { url });
+        this.name = 'InvalidEndpointError';
+        Object.setPrototypeOf(this, new.target.prototype);
+    }
+}
+exports.InvalidEndpointError = InvalidEndpointError;
+// ─────────────────────────────────────────────────────────────
+/**
+ * Thrown when the RPC request itself fails (network error, bad response, etc.)
+ */
+class RPCError extends QNError {
+    statusCode;
+    constructor(method, statusCode, body) {
+        super(`RPC request failed.\n` +
+            `  Method:  ${method}\n` +
+            `  Status:  ${statusCode}\n` +
+            `  Body:    ${body.slice(0, 300)}\n` +
+            `  If you're seeing 403, check your endpoint URL and token.`, 'RPC_ERROR', { method, statusCode, body });
+        this.statusCode = statusCode;
+        this.name = 'RPCError';
+        Object.setPrototypeOf(this, new.target.prototype);
+    }
+}
+exports.RPCError = RPCError;
+//# sourceMappingURL=errors.js.map

package/dist/types/errors.js.map

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

package/dist/types/index.d.ts

@@ -0,0 +1,211 @@
+export interface QNConfig {
+    endpointUrl: string;
+    addOns?: {
+        priorityFees?: boolean;
+        liljit?: boolean;
+        das?: boolean;
+        metis?: boolean;
+        yellowstone?: boolean;
+    };
+    commitment?: 'processed' | 'confirmed' | 'finalized';
+    timeout?: number;
+}
+export type FeeLevel = 'extreme' | 'high' | 'recommended' | 'medium' | 'low';
+export interface PriorityFeeOptions {
+    account?: string;
+    lastNBlocks?: number;
+}
+export interface PriorityFees {
+    recommended: number;
+    high: number;
+    extreme: number;
+    medium: number;
+    low: number;
+    networkCongestion: number;
+}
+export interface SendSmartTxOptions {
+    feeLevel?: FeeLevel;
+    useJito?: boolean;
+    maxRetries?: number;
+    simulateFirst?: boolean;
+    computeUnitBuffer?: number;
+    skipPreflight?: boolean;
+}
+export interface SmartTxResult {
+    signature: string;
+    slot: number;
+    priorityFeeMicroLamports: number;
+    computeUnitsUsed: number;
+    jitoBundle: boolean;
+    confirmationMs: number;
+}
+export interface GetAssetsByOwnerOptions {
+    ownerAddress: string;
+    limit?: number;
+    page?: number;
+    sortBy?: 'created' | 'updated' | 'recent_action';
+    sortDirection?: 'asc' | 'desc';
+}
+export interface GetAssetsByCollectionOptions {
+    collectionMint: string;
+    limit?: number;
+    page?: number;
+}
+export interface SearchAssetsOptions {
+    ownerAddress?: string;
+    creatorAddress?: string;
+    collection?: string;
+    tokenType?: 'fungible' | 'nonFungible' | 'regularNFT' | 'compressedNFT' | 'all';
+    compressed?: boolean;
+    limit?: number;
+    page?: number;
+}
+export interface DigitalAsset {
+    id: string;
+    interface: string;
+    content: {
+        json_uri: string;
+        metadata: {
+            name: string;
+            symbol: string;
+            description?: string;
+            image?: string;
+            attributes?: Array<{
+                trait_type: string;
+                value: string | number;
+            }>;
+        };
+    };
+    ownership: {
+        owner: string;
+        frozen: boolean;
+        delegated: boolean;
+        delegate?: string;
+    };
+    compression?: {
+        compressed: boolean;
+        tree: string;
+        leaf_id: number;
+        seq: number;
+        data_hash: string;
+        creator_hash: string;
+        asset_hash: string;
+    };
+    royalty?: {
+        basis_points: number;
+        percent: number;
+        primary_sale_happened: boolean;
+    };
+    creators?: Array<{
+        address: string;
+        share: number;
+        verified: boolean;
+    }>;
+    grouping?: Array<{
+        group_key: string;
+        group_value: string;
+    }>;
+    mutable: boolean;
+    burnt: boolean;
+}
+export interface AssetsResult {
+    total: number;
+    limit: number;
+    page: number;
+    items: DigitalAsset[];
+}
+export interface AssetProof {
+    root: string;
+    proof: string[];
+    node_index: number;
+    leaf: string;
+    tree_id: string;
+}
+export interface TokenAccount {
+    mint: string;
+    tokenAccount: string;
+    balance: number;
+    decimals: number;
+    uiAmount: number;
+}
+export type StreamBackend = 'yellowstone' | 'websocket' | 'auto';
+export interface WatchOptions {
+    backend?: StreamBackend;
+    commitment?: 'processed' | 'confirmed' | 'finalized';
+    autoReconnect?: boolean;
+    maxReconnectAttempts?: number;
+}
+export interface AccountUpdate {
+    pubkey: string;
+    lamports: number;
+    owner: string;
+    executable: boolean;
+    data: Buffer;
+    slot: number;
+    timestamp: number;
+    backend: 'yellowstone' | 'websocket';
+}
+export interface ProgramTx {
+    signature: string;
+    slot: number;
+    blockTime: number;
+    logs: string[];
+    err: object | null;
+}
+export interface WatchHandle {
+    unsubscribe: () => void;
+    isConnected: () => boolean;
+}
+export interface SwapQuoteOptions {
+    inputMint: string;
+    outputMint: string;
+    amount: bigint;
+    slippageBps?: number;
+}
+export interface SwapOptions extends SwapQuoteOptions {
+    userPublicKey: string;
+    feeLevel?: FeeLevel;
+    useJitoTip?: boolean;
+}
+export interface SwapQuote {
+    inputMint: string;
+    outputMint: string;
+    inAmount: string;
+    outAmount: string;
+    priceImpactPct: string;
+    slippageBps: number;
+    routePlan: Array<{
+        swapInfo: {
+            label: string;
+            inputMint: string;
+            outAmount: string;
+        };
+        percent: number;
+    }>;
+}
+export interface SwapResult {
+    signature: string;
+    inputAmount: bigint;
+    outputAmount: bigint;
+    priceImpactPct: number;
+    confirmationMs: number;
+}
+export interface AddOnStatus {
+    name: string;
+    enabled: boolean;
+    tier: 'free' | 'paid';
+    description: string;
+    enableUrl: string;
+}
+export interface AddOnCheckResult {
+    endpoint: string;
+    addOns: AddOnStatus[];
+    canUse: {
+        smartTransactions: boolean;
+        nftQueries: boolean;
+        swaps: boolean;
+        yellowstoneStream: boolean;
+        jitoBundle: boolean;
+    };
+}
+//# sourceMappingURL=index.d.ts.map

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

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

package/dist/types/index.js

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

package/dist/types/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/types/index.ts"],"names":[],"mappings":";AAAA,gEAAgE;AAChE,aAAa;AACb,gEAAgE"}

package/dist/utils/addon-guard.d.ts

@@ -0,0 +1,25 @@
+import type { QNConfig } from '../types';
+type AddOnKey = keyof NonNullable<QNConfig['addOns']>;
+interface AddOnMeta {
+    tier: 'free' | 'paid';
+    displayName: string;
+    description: string;
+}
+declare const ADD_ON_META: Record<AddOnKey, AddOnMeta>;
+/**
+ * Checks whether a required add-on is enabled in the config.
+ *
+ * - If explicitly set to true → passes silently
+ * - If explicitly set to false → throws AddOnNotEnabledError
+ * - If not set (undefined) → logs a warning but does NOT throw
+ *   (we give the benefit of the doubt if the dev hasn't configured addOns yet)
+ */
+export declare function requireAddOn(config: QNConfig, key: AddOnKey): void;
+/**
+ * Soft check — returns false instead of throwing.
+ * Use this for features that degrade gracefully (e.g. fallback from
+ * Yellowstone gRPC → WebSocket when yellowstone isn't enabled).
+ */
+export declare function isAddOnEnabled(config: QNConfig, key: AddOnKey): boolean;
+export { ADD_ON_META };
+//# sourceMappingURL=addon-guard.d.ts.map

package/dist/utils/addon-guard.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"addon-guard.d.ts","sourceRoot":"","sources":["../../src/utils/addon-guard.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,UAAU,CAAC;AAGzC,KAAK,QAAQ,GAAG,MAAM,WAAW,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAAC,CAAC;AAEtD,UAAU,SAAS;IACjB,IAAI,EAAS,MAAM,GAAG,MAAM,CAAC;IAC7B,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,MAAM,CAAC;CACrB;AAED,QAAA,MAAM,WAAW,EAAE,MAAM,CAAC,QAAQ,EAAE,SAAS,CA0B5C,CAAC;AAEF;;;;;;;GAOG;AACH,wBAAgB,YAAY,CAAC,MAAM,EAAE,QAAQ,EAAE,GAAG,EAAE,QAAQ,GAAG,IAAI,CAmBlE;AAED;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,MAAM,EAAE,QAAQ,EAAE,GAAG,EAAE,QAAQ,GAAG,OAAO,CAEvE;AAED,OAAO,EAAE,WAAW,EAAE,CAAC"}

package/dist/utils/addon-guard.js

@@ -0,0 +1,67 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ADD_ON_META = void 0;
+exports.requireAddOn = requireAddOn;
+exports.isAddOnEnabled = isAddOnEnabled;
+const errors_1 = require("../types/errors");
+const ADD_ON_META = {
+    priorityFees: {
+        tier: 'free',
+        displayName: 'Priority Fee API',
+        description: 'Dynamic priority fee estimation for faster tx inclusion',
+    },
+    das: {
+        tier: 'free',
+        displayName: 'Metaplex DAS API',
+        description: 'Query NFTs, cNFTs, and token metadata',
+    },
+    liljit: {
+        tier: 'paid',
+        displayName: "Lil' JIT (Jito Bundles)",
+        description: 'MEV protection + atomic transaction execution via Jito',
+    },
+    metis: {
+        tier: 'paid',
+        displayName: 'Metis — Jupiter V6 Swap API',
+        description: 'Best-price token swaps via Jupiter aggregator',
+    },
+    yellowstone: {
+        tier: 'paid',
+        displayName: 'Yellowstone gRPC',
+        description: 'Ultra-low-latency real-time account and program streaming',
+    },
+};
+exports.ADD_ON_META = ADD_ON_META;
+/**
+ * Checks whether a required add-on is enabled in the config.
+ *
+ * - If explicitly set to true → passes silently
+ * - If explicitly set to false → throws AddOnNotEnabledError
+ * - If not set (undefined) → logs a warning but does NOT throw
+ *   (we give the benefit of the doubt if the dev hasn't configured addOns yet)
+ */
+function requireAddOn(config, key) {
+    const meta = ADD_ON_META[key];
+    const status = config.addOns?.[key];
+    if (status === false) {
+        throw new errors_1.AddOnNotEnabledError(meta.displayName, meta.tier);
+    }
+    if (status === undefined) {
+        // Warn but don't crash — let the RPC call proceed and fail naturally
+        // with a helpful error if the add-on really isn't there
+        console.warn(`[QNSolanaKit] ⚠  addOns.${key} is not set in your config.\n` +
+            `  If you get errors, enable "${meta.displayName}" in your QuickNode dashboard\n` +
+            `  and set addOns: { ${key}: true } in your QNSolanaKit config.\n` +
+            `  Tier: ${meta.tier.toUpperCase()} — ${meta.description}`);
+    }
+    // status === true → all good, proceed
+}
+/**
+ * Soft check — returns false instead of throwing.
+ * Use this for features that degrade gracefully (e.g. fallback from
+ * Yellowstone gRPC → WebSocket when yellowstone isn't enabled).
+ */
+function isAddOnEnabled(config, key) {
+    return config.addOns?.[key] === true;
+}
+//# sourceMappingURL=addon-guard.js.map

package/dist/utils/addon-guard.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"addon-guard.js","sourceRoot":"","sources":["../../src/utils/addon-guard.ts"],"names":[],"mappings":";;;AA+CA,oCAmBC;AAOD,wCAEC;AA1ED,4CAAuD;AAUvD,MAAM,WAAW,GAAgC;IAC/C,YAAY,EAAE;QACZ,IAAI,EAAS,MAAM;QACnB,WAAW,EAAE,kBAAkB;QAC/B,WAAW,EAAE,yDAAyD;KACvE;IACD,GAAG,EAAE;QACH,IAAI,EAAS,MAAM;QACnB,WAAW,EAAE,kBAAkB;QAC/B,WAAW,EAAE,uCAAuC;KACrD;IACD,MAAM,EAAE;QACN,IAAI,EAAS,MAAM;QACnB,WAAW,EAAE,yBAAyB;QACtC,WAAW,EAAE,wDAAwD;KACtE;IACD,KAAK,EAAE;QACL,IAAI,EAAS,MAAM;QACnB,WAAW,EAAE,6BAA6B;QAC1C,WAAW,EAAE,+CAA+C;KAC7D;IACD,WAAW,EAAE;QACX,IAAI,EAAS,MAAM;QACnB,WAAW,EAAE,kBAAkB;QAC/B,WAAW,EAAE,2DAA2D;KACzE;CACF,CAAC;AAwCO,kCAAW;AAtCpB;;;;;;;GAOG;AACH,SAAgB,YAAY,CAAC,MAAgB,EAAE,GAAa;IAC1D,MAAM,IAAI,GAAK,WAAW,CAAC,GAAG,CAAC,CAAC;IAChC,MAAM,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC;IAEpC,IAAI,MAAM,KAAK,KAAK,EAAE,CAAC;QACrB,MAAM,IAAI,6BAAoB,CAAC,IAAI,CAAC,WAAW,EAAE,IAAI,CAAC,IAAI,CAAC,CAAC;IAC9D,CAAC;IAED,IAAI,MAAM,KAAK,SAAS,EAAE,CAAC;QACzB,qEAAqE;QACrE,wDAAwD;QACxD,OAAO,CAAC,IAAI,CACV,2BAA2B,GAAG,+BAA+B;YAC7D,gCAAgC,IAAI,CAAC,WAAW,iCAAiC;YACjF,uBAAuB,GAAG,wCAAwC;YAClE,WAAW,IAAI,CAAC,IAAI,CAAC,WAAW,EAAE,MAAM,IAAI,CAAC,WAAW,EAAE,CAC3D,CAAC;IACJ,CAAC;IACD,sCAAsC;AACxC,CAAC;AAED;;;;GAIG;AACH,SAAgB,cAAc,CAAC,MAAgB,EAAE,GAAa;IAC5D,OAAO,MAAM,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,KAAK,IAAI,CAAC;AACvC,CAAC"}