@unclaimedsol/spl-burn-close-sdk 1.2.1 → 1.3.0

package/CHANGELOG.md

@@ -0,0 +1,18 @@
+# Changelog
+
+## 1.3.0
+
+- Preserve the fetched blockhash's `lastValidBlockHeight` on built transactions and add
+  an optional matching height for caller-supplied blockhashes.
+- Reject non-finite, non-positive, and fractional `chunkSize` values at build time,
+  including on empty input. The default remains 12.
+- Validate unsigned serialization during building. Oversized transactions raise a clear
+  size error at build time instead of failing later when sent; other serialization failures
+  (for example an invalid blockhash or account key) report the original error as `cause`.
+  Choose a smaller chunk size; additional caller instructions still count against 1,232 bytes.
+- Fix CommonJS TypeScript resolution with separate import/require declaration exports.
+- Correct the documented hybrid fee and confirmation examples; describe compute-budget
+  considerations without adding a default compute-budget instruction.
+- Add instruction, batching, expiry, documentation and packed-package tests with CI.
+
+Existing instruction encoding, asynchronous helpers and return types remain unchanged.

package/README.md

@@ -1,13 +1,14 @@
 # Burn and Close Solana SPL Tokens SDK
 
-A lightweight Solana SDK to **burn SPL tokens and close token accounts** with a **fixed 5%** protocol fee.
+A lightweight Solana SDK to **burn SPL tokens and close token accounts** with the June 2026 Unclaimed SOL token cleanup fee policy.
 This library only **builds unsigned transactions** – you handle signing and sending them, whether in the browser (Wallet Adapter) or server (Keypair).
 
 ## ✨ Features
 
 - 🔥 Burn all tokens in provided ATAs.
 - 🧹 Close token accounts, reclaiming rent to the user.
-- 💸 Automatic 5% protocol fee (hardcoded in program).
+- 💸 On-chain fee recipient is enforced by the program.
+- 🧾 Hybrid cleanup fee: `max(floor(gross * 200 / 10000), gross - 2,000,000)` lamports per closed account. For 2,039,280 lamports recovered, the fee is 40,785 lamports.
 - ⚡ Automatic batching (default 12 ATAs per transaction).
 - 🪙 Supports SPL Token and Token-2022.
 - 🔐 Supports **frontend partial signing** and **backend full signing** workflows.
@@ -19,7 +20,7 @@ This library only **builds unsigned transactions** – you handle signing and se
 
 1. The SDK prepares TransactionInstructions for your on-chain burn+close program.
 2. Program burns tokens in each ATA, then closes it, sending rent back to the owner.
-3. A 5% fee is enforced on-chain and sent to the hardcoded recipient.
+3. The program sends the greater of 2% of recovered rent (rounded down) or the amount above 2,000,000 lamports to the hardcoded fee recipient, per successfully closed account.
 4. The SDK never asks for private keys — you sign & send transactions yourself.
 
 ---
@@ -32,7 +33,9 @@ npm i @unclaimedsol/spl-burn-close-sdk
 
 We use @solana/web3.js in peerDependencies to avoid version conflicts, so make sure you already have it installed.
 
-Requires Node 18+.
+Requires Node 18+. On Node 18, use a compatible locked dependency graph for web3.js;
+fresh dependency resolution can select an ESM-only `uuid` through `rpc-websockets`
+that breaks CommonJS loading. CI tests the repository’s locked dependency graph.
 
 ---
 
@@ -64,15 +67,15 @@ const txs = await buildBurnAndCloseTransactions(
 for (const tx of txs) {
   tx.partialSign(keypair);
   const sig = await connection.sendRawTransaction(tx.serialize());
-  let latestBlockhash = await connection.getLatestBlockhash(
-    connection.commitment
-  );
-  await connection.confirmTransaction({
+  const confirmation = await connection.confirmTransaction({
     signature: sig,
-    blockhash: latestBlockhash.blockhash,
-    lastValidBlockHeight: latestBlockhash.lastValidBlockHeight,
+    blockhash: tx.recentBlockhash!,
+    lastValidBlockHeight: tx.lastValidBlockHeight!,
   });
-  console.log("✅ Sent:", sig);
+  if (confirmation.value.err) {
+    throw new Error(`Transaction failed: ${JSON.stringify(confirmation.value.err)}`);
+  }
+  console.log("✅ Confirmed:", sig);
 }
 ```
 
@@ -108,7 +111,7 @@ const txs = await buildBurnAndCloseTransactions(
 //   PROGRAM_ID,
 //   user,
 //   pairs,
-//   { chunkSize: 2 },
+//   { chunkSize: 3 },
 //   TOKEN_2022_PROGRAM_ID
 // );
 
@@ -118,22 +121,47 @@ const signed = wallet.signAllTransactions
   : await Promise.all(txs.map((t) => wallet.signTransaction!(t)));
 
 // Send
-for (const stx of signed) {
+for (const [index, stx] of signed.entries()) {
+  // Wallets may reconstruct transactions and omit expiry metadata.
+  const tx = txs[index];
   const sig = await connection.sendRawTransaction(stx.serialize());
-  let latestBlockhash = await connection.getLatestBlockhash(
-    connection.commitment
-  );
-  await connection.confirmTransaction({
+  const confirmation = await connection.confirmTransaction({
     signature: sig,
-    blockhash: latestBlockhash.blockhash,
-    lastValidBlockHeight: latestBlockhash.lastValidBlockHeight,
+    blockhash: tx.recentBlockhash!,
+    lastValidBlockHeight: tx.lastValidBlockHeight!,
   });
-  console.log("✅ Sent:", sig);
+  if (confirmation.value.err) {
+    throw new Error(`Transaction failed: ${JSON.stringify(confirmation.value.err)}`);
+  }
+  console.log("✅ Confirmed:", sig);
 }
 ```
 
 ---
 
+## Batching and blockhash expiry
+
+`chunkSize` defaults to 12 and must be a finite positive integer. Invalid values and
+transactions that cannot serialize within the legacy 1,232-byte limit now throw during
+building. Size depends on unique accounts and signers, including a separate fee payer;
+there is no fixed pair cap. Instructions added afterwards (including compute budget or
+memo instructions) count against the same limit, so recheck size after adding them.
+
+The app uses batches of 10 classic token accounts or 3 Token-2022 accounts and also adds
+a compute-unit limit. These are production configuration values, not a guarantee for
+every workload; this release did not simulate their compute usage. The SDK adds no
+compute-budget instruction. Choose a batch size and compute budget for your workload.
+
+Fetched transactions carry `recentBlockhash` and its matching `lastValidBlockHeight`.
+If you supply `recentBlockhash`, supply its matching `lastValidBlockHeight` too when using
+the confirmation examples above. Without an explicit height it remains undefined; the
+SDK never fetches a height for a caller-supplied blockhash. A height supplied without a
+blockhash is ignored in favor of the fetched pair. Confirm using the original transaction
+metadata, even if the wallet returns a reconstructed signed transaction.
+
+Instruction data is a browser-safe `Uint8Array` typed as `Buffer` for web3.js compatibility;
+do not call Buffer-only methods on it.
+
 ## 🌐 Cluster support
 
 This SDK targets the Unclaimed SOL mainnet program (`PROGRAM_ID`) and fee recipient (`FEE_RECIPIENT`).

package/dist/index.cjs

@@ -10,6 +10,17 @@ exports.PROGRAM_ID = new web3_js_1.PublicKey("UNCaXzXkR3vp8mbCJyxWUvwuRk5uHgzrwe
 exports.FEE_RECIPIENT = new web3_js_1.PublicKey("uncNCRycMtNPj2kXHfwiCgNrzCTnC9xU5FS8ZeWyn3M");
 exports.TOKEN_PROGRAM_ID = new web3_js_1.PublicKey("TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA");
 exports.TOKEN_2022_PROGRAM_ID = new web3_js_1.PublicKey("TokenzQdBNbLqP5VEhdkAS6EPFLC1PHnBqCXEpPxuEb");
+/** Legacy transaction wire limit, including the signature-count prefix and signature slots. */
+const PACKET_DATA_SIZE = 1232;
+function packetSizeError() {
+    return new Error("Burn and close: transaction could not be serialized within the 1,232-byte limit. " +
+        "Reduce chunkSize.");
+}
+/** web3.js reports oversized messages as "Transaction too large" or a buffer overrun. */
+function isPacketSizeError(error) {
+    const message = error instanceof Error ? error.message : String(error);
+    return /Transaction too large|encoding overruns (?:Uint8Array|Buffer)/i.test(message);
+}
 /**
  * Build *unsigned* transactions that call the on-chain burn+close program.
  * You sign and send them yourself (frontend wallet or backend keypair).
@@ -23,12 +34,15 @@ exports.TOKEN_2022_PROGRAM_ID = new web3_js_1.PublicKey("TokenzQdBNbLqP5VEhdkAS6
  * @returns               Array of *unsigned* Transaction objects
  */
 async function buildBurnAndCloseTransactions(connection, programId, user, pairs, options = {}, tokenProgramId = exports.TOKEN_PROGRAM_ID) {
+    const chunkSize = options.chunkSize ?? 12;
+    if (!Number.isFinite(chunkSize) || !Number.isInteger(chunkSize) || chunkSize <= 0) {
+        throw new Error("Burn and close: chunkSize must be a finite positive integer.");
+    }
     if (!pairs.length)
         return [];
-    const chunkSize = Math.max(1, options.chunkSize ?? 12);
     const commitment = options.commitment ?? "confirmed";
     const feePayer = options.feePayer ?? user;
-    // Split into chunks so we stay under CU / account limits
+    // Split into batches; callers must choose a suitable compute budget.
     const chunks = [];
     for (let i = 0; i < pairs.length; i += chunkSize) {
         chunks.push(pairs.slice(i, i + chunkSize));
@@ -36,8 +50,9 @@ async function buildBurnAndCloseTransactions(connection, programId, user, pairs,
     // Instruction data: [selector=0]
     // Use Uint8Array (browser-safe) and cast for web3.js' Buffer typing.
     const data = new Uint8Array([0]);
-    const recentBlockhash = options.recentBlockhash ??
-        (await connection.getLatestBlockhash({ commitment })).blockhash;
+    const { blockhash, lastValidBlockHeight } = options.recentBlockhash !== undefined
+        ? { blockhash: options.recentBlockhash, lastValidBlockHeight: options.lastValidBlockHeight }
+        : await connection.getLatestBlockhash({ commitment });
     const txs = [];
     for (const chunk of chunks) {
         const keys = [
@@ -58,7 +73,22 @@ async function buildBurnAndCloseTransactions(connection, programId, user, pairs,
         });
         const tx = new web3_js_1.Transaction().add(ix);
         tx.feePayer = feePayer;
-        tx.recentBlockhash = recentBlockhash;
+        tx.recentBlockhash = blockhash;
+        tx.lastValidBlockHeight = lastValidBlockHeight;
+        let wireSize;
+        try {
+            wireSize = tx.serialize({ requireAllSignatures: false }).length;
+        }
+        catch (error) {
+            if (isPacketSizeError(error)) {
+                throw packetSizeError();
+            }
+            throw new Error("Burn and close: transaction could not be serialized. " +
+                "Check the supplied transaction inputs, including recentBlockhash and account keys.", { cause: error });
+        }
+        if (wireSize > PACKET_DATA_SIZE) {
+            throw packetSizeError();
+        }
         txs.push(tx);
     }
     return txs;
@@ -70,6 +100,8 @@ async function buildBurnAndCloseTransactions(connection, programId, user, pairs,
  * Unlike `buildBurnAndCloseTransactions`, this helper does **not**
  * create or sign full transactions — it only constructs one
  * instruction for a batch of (mint, ATA) pairs.
+ * Instruction data is a browser-safe Uint8Array, typed as Buffer for web3.js;
+ * do not rely on Buffer-only methods on the returned data.
  */
 async function buildBurnAndCloseInstruction(programId, user, pairs, tokenProgramId) {
     if (!pairs.length) {

package/dist/index.d.cts

@@ -0,0 +1,53 @@
+import { Connection, PublicKey, Transaction, TransactionInstruction, Commitment } from "@solana/web3.js";
+/** Exporting on-chain program ID for convenience */
+export declare const PROGRAM_ID: PublicKey;
+/** Hardcoded fee recipient on-chain expectation */
+export declare const FEE_RECIPIENT: PublicKey;
+export declare const TOKEN_PROGRAM_ID: PublicKey;
+export declare const TOKEN_2022_PROGRAM_ID: PublicKey;
+export type Pair = {
+    mint: PublicKey;
+    ata: PublicKey;
+};
+export type BuildOptions = {
+    /** Max pairs per transaction: a finite positive integer (default: 12). */
+    chunkSize?: number;
+    /** Use this commitment when fetching blockhash (default: "confirmed") */
+    commitment?: Commitment;
+    /**
+     * Optional explicit fee payer (defaults to `user`)
+     * Note: whoever signs must cover fees on-chain.
+     */
+    feePayer?: PublicKey;
+    /**
+     * Provide your own recent blockhash (advanced). If omitted,
+     * we fetch a fresh one and reuse it for all built transactions.
+     */
+    recentBlockhash?: string;
+    /** Expiry height matching recentBlockhash; ignored when the blockhash is fetched. */
+    lastValidBlockHeight?: number;
+};
+/**
+ * Build *unsigned* transactions that call the on-chain burn+close program.
+ * You sign and send them yourself (frontend wallet or backend keypair).
+ *
+ * @param connection      Solana RPC connection
+ * @param programId       Your deployed program ID
+ * @param user            The user whose ATAs will be burned/closed
+ * @param pairs           Array of { mint, ata } to process
+ * @param options         Chunking / blockhash / payer tweaks
+ * @param tokenProgramId  Support for multiple Token programs
+ * @returns               Array of *unsigned* Transaction objects
+ */
+export declare function buildBurnAndCloseTransactions(connection: Connection, programId: PublicKey, user: PublicKey, pairs: Pair[], options?: BuildOptions, tokenProgramId?: PublicKey): Promise<Transaction[]>;
+/**
+ * Build a single **TransactionInstruction** that calls the on-chain
+ * burn+close program for a specific Token Program (either SPL Token or Token-2022).
+ *
+ * Unlike `buildBurnAndCloseTransactions`, this helper does **not**
+ * create or sign full transactions — it only constructs one
+ * instruction for a batch of (mint, ATA) pairs.
+ * Instruction data is a browser-safe Uint8Array, typed as Buffer for web3.js;
+ * do not rely on Buffer-only methods on the returned data.
+ */
+export declare function buildBurnAndCloseInstruction(programId: PublicKey, user: PublicKey, pairs: Pair[], tokenProgramId: PublicKey): Promise<TransactionInstruction | null>;

package/dist/index.d.ts

@@ -10,7 +10,7 @@ export type Pair = {
     ata: PublicKey;
 };
 export type BuildOptions = {
-    /** Max pairs per transaction (default: 12) */
+    /** Max pairs per transaction: a finite positive integer (default: 12). */
     chunkSize?: number;
     /** Use this commitment when fetching blockhash (default: "confirmed") */
     commitment?: Commitment;
@@ -24,6 +24,8 @@ export type BuildOptions = {
      * we fetch a fresh one and reuse it for all built transactions.
      */
     recentBlockhash?: string;
+    /** Expiry height matching recentBlockhash; ignored when the blockhash is fetched. */
+    lastValidBlockHeight?: number;
 };
 /**
  * Build *unsigned* transactions that call the on-chain burn+close program.
@@ -45,5 +47,7 @@ export declare function buildBurnAndCloseTransactions(connection: Connection, pr
  * Unlike `buildBurnAndCloseTransactions`, this helper does **not**
  * create or sign full transactions — it only constructs one
  * instruction for a batch of (mint, ATA) pairs.
+ * Instruction data is a browser-safe Uint8Array, typed as Buffer for web3.js;
+ * do not rely on Buffer-only methods on the returned data.
  */
 export declare function buildBurnAndCloseInstruction(programId: PublicKey, user: PublicKey, pairs: Pair[], tokenProgramId: PublicKey): Promise<TransactionInstruction | null>;

package/dist/index.js

@@ -5,6 +5,17 @@ export const PROGRAM_ID = new PublicKey("UNCaXzXkR3vp8mbCJyxWUvwuRk5uHgzrwe6jcWP
 export const FEE_RECIPIENT = new PublicKey("uncNCRycMtNPj2kXHfwiCgNrzCTnC9xU5FS8ZeWyn3M");
 export const TOKEN_PROGRAM_ID = new PublicKey("TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA");
 export const TOKEN_2022_PROGRAM_ID = new PublicKey("TokenzQdBNbLqP5VEhdkAS6EPFLC1PHnBqCXEpPxuEb");
+/** Legacy transaction wire limit, including the signature-count prefix and signature slots. */
+const PACKET_DATA_SIZE = 1232;
+function packetSizeError() {
+    return new Error("Burn and close: transaction could not be serialized within the 1,232-byte limit. " +
+        "Reduce chunkSize.");
+}
+/** web3.js reports oversized messages as "Transaction too large" or a buffer overrun. */
+function isPacketSizeError(error) {
+    const message = error instanceof Error ? error.message : String(error);
+    return /Transaction too large|encoding overruns (?:Uint8Array|Buffer)/i.test(message);
+}
 /**
  * Build *unsigned* transactions that call the on-chain burn+close program.
  * You sign and send them yourself (frontend wallet or backend keypair).
@@ -18,12 +29,15 @@ export const TOKEN_2022_PROGRAM_ID = new PublicKey("TokenzQdBNbLqP5VEhdkAS6EPFLC
  * @returns               Array of *unsigned* Transaction objects
  */
 export async function buildBurnAndCloseTransactions(connection, programId, user, pairs, options = {}, tokenProgramId = TOKEN_PROGRAM_ID) {
+    const chunkSize = options.chunkSize ?? 12;
+    if (!Number.isFinite(chunkSize) || !Number.isInteger(chunkSize) || chunkSize <= 0) {
+        throw new Error("Burn and close: chunkSize must be a finite positive integer.");
+    }
     if (!pairs.length)
         return [];
-    const chunkSize = Math.max(1, options.chunkSize ?? 12);
     const commitment = options.commitment ?? "confirmed";
     const feePayer = options.feePayer ?? user;
-    // Split into chunks so we stay under CU / account limits
+    // Split into batches; callers must choose a suitable compute budget.
     const chunks = [];
     for (let i = 0; i < pairs.length; i += chunkSize) {
         chunks.push(pairs.slice(i, i + chunkSize));
@@ -31,8 +45,9 @@ export async function buildBurnAndCloseTransactions(connection, programId, user,
     // Instruction data: [selector=0]
     // Use Uint8Array (browser-safe) and cast for web3.js' Buffer typing.
     const data = new Uint8Array([0]);
-    const recentBlockhash = options.recentBlockhash ??
-        (await connection.getLatestBlockhash({ commitment })).blockhash;
+    const { blockhash, lastValidBlockHeight } = options.recentBlockhash !== undefined
+        ? { blockhash: options.recentBlockhash, lastValidBlockHeight: options.lastValidBlockHeight }
+        : await connection.getLatestBlockhash({ commitment });
     const txs = [];
     for (const chunk of chunks) {
         const keys = [
@@ -53,7 +68,22 @@ export async function buildBurnAndCloseTransactions(connection, programId, user,
         });
         const tx = new Transaction().add(ix);
         tx.feePayer = feePayer;
-        tx.recentBlockhash = recentBlockhash;
+        tx.recentBlockhash = blockhash;
+        tx.lastValidBlockHeight = lastValidBlockHeight;
+        let wireSize;
+        try {
+            wireSize = tx.serialize({ requireAllSignatures: false }).length;
+        }
+        catch (error) {
+            if (isPacketSizeError(error)) {
+                throw packetSizeError();
+            }
+            throw new Error("Burn and close: transaction could not be serialized. " +
+                "Check the supplied transaction inputs, including recentBlockhash and account keys.", { cause: error });
+        }
+        if (wireSize > PACKET_DATA_SIZE) {
+            throw packetSizeError();
+        }
         txs.push(tx);
     }
     return txs;
@@ -65,6 +95,8 @@ export async function buildBurnAndCloseTransactions(connection, programId, user,
  * Unlike `buildBurnAndCloseTransactions`, this helper does **not**
  * create or sign full transactions — it only constructs one
  * instruction for a batch of (mint, ATA) pairs.
+ * Instruction data is a browser-safe Uint8Array, typed as Buffer for web3.js;
+ * do not rely on Buffer-only methods on the returned data.
  */
 export async function buildBurnAndCloseInstruction(programId, user, pairs, tokenProgramId) {
     if (!pairs.length) {

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@unclaimedsol/spl-burn-close-sdk",
-  "version": "1.2.1",
-  "description": "SDK to burn and close SPL token accounts via the Unclaimed SOL program (with a built-in 5% fee).",
+  "version": "1.3.0",
+  "description": "Build unsigned Solana transactions to burn SPL tokens, close token accounts, and reclaim rent with the Unclaimed SOL program.",
   "license": "MIT",
   "author": "Unclaimed SOL",
   "type": "module",
@@ -15,9 +15,14 @@
   },
   "exports": {
     ".": {
-      "types": "./dist/index.d.ts",
-      "import": "./dist/index.js",
-      "require": "./dist/index.cjs"
+      "import": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      },
+      "require": {
+        "types": "./dist/index.d.cts",
+        "default": "./dist/index.cjs"
+      }
     }
   },
   "main": "./dist/index.cjs",
@@ -25,11 +30,14 @@
   "types": "./dist/index.d.ts",
   "files": [
     "dist",
-    "README.md"
+    "README.md",
+    "CHANGELOG.md"
   ],
   "scripts": {
     "build": "tsc -p tsconfig.json && tsc -p tsconfig.cjs.json && node ./scripts/build-cjs.js",
-    "prepublishOnly": "npm run build"
+    "prepack": "npm run build",
+    "test": "npm run build && node --test test/*.test.js",
+    "test:package": "node scripts/test-package.js"
   },
   "peerDependencies": {
     "@solana/web3.js": "^1.98.4"