@unclaimedsol/spl-burn-close-sdk 1.2.2 → 1.4.0

package/CHANGELOG.md

@@ -0,0 +1,37 @@
+# Changelog
+
+## 1.4.0
+
+- Add `buildCloseEmptyTokenAccountsInstruction` and
+  `buildCloseEmptyTokenAccountsTransactions` for opt-in execution-time empty-account
+  checks. They emit exact data `[2]` with the Rust program's existing token account
+  layout, support classic SPL Token and Token-2022, and never fall back to burning.
+- Reuse unsigned batching, `BuildOptions`, blockhash/expiry handling, fee payer
+  support and the 1,232-byte limit. The instruction helper makes no RPC calls.
+- Verify the ABI against Rust commit `1f2b10ae668c47de97627de69cdf656878ed9b0e`
+  and its deterministic fixture. Extend regression, browser-data and packed-package
+  coverage across CJS, ESM and TypeScript bundler resolution.
+- Document deployment prerequisites, skipped targets, funded/unsynchronized WSOL
+  exclusion, unchanged fees and the limits of preview and signature-based reporting.
+
+Existing burn-and-close APIs, selector `[0]`, defaults and behavior are preserved.
+Consumers must explicitly switch builders after the program upgrade is deployed;
+an SDK dependency update alone does not protect existing cleanup calls. This release
+does not add checked buffer approvals or guarantee exact preview proceeds.
+
+## 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,14 +1,25 @@
 # Burn and Close Solana SPL Tokens SDK
 
-A lightweight Solana SDK to **burn SPL tokens and close token accounts** with the June 2026 Unclaimed SOL token cleanup fee policy.
+A lightweight Solana SDK for intentional token burning and opt-in empty-token-account cleanup, with the existing 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).
 
+`buildBurnAndCloseInstruction` and `buildBurnAndCloseTransactions` intentionally burn
+and close (selector 0). They keep their existing behavior, including burning tokens
+that arrive after an RPC balance check. Updating this dependency alone does not
+change existing callers.
+
+`buildCloseEmptyTokenAccountsInstruction` and `buildCloseEmptyTokenAccountsTransactions`
+request execution-time empty-account checks (selector 2) and never burn. The program
+upgrade must be deployed before consumers use these builders. This SDK does not
+probe deployment or fall back to burn-and-close if selector 2 is unsupported.
+
 ## ✨ Features
 
 - 🔥 Burn all tokens in provided ATAs.
 - 🧹 Close token accounts, reclaiming rent to the user.
+- Opt-in empty-account cleanup that preserves tokens deposited after a preview.
 - 💸 On-chain fee recipient is enforced by the program.
-- 🧾 Standard token cleanup lets the user keep up to 0.002 SOL per closed account; normal-account fee is 39,280 lamports.
+- 🧾 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.
@@ -18,9 +29,10 @@ This library only **builds unsigned transactions** – you handle signing and se
 
 ## 🧩 How It Works
 
-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. The program sends recovered rent above 2,000,000 lamports per successfully closed account to the hardcoded fee recipient.
+1. The SDK prepares instructions for the selected cleanup path.
+2. The legacy path burns and closes. The new close-empty path closes only eligible
+   empty accounts, returning their lamports to the wallet without burning tokens.
+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.
 
 ---
@@ -33,13 +45,80 @@ 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.
 
 ---
 
 ## 🔑 Usage
 
-### Signing with Keypair
+### Empty-account cleanup (requires the program upgrade)
+
+```typescript
+import { Connection, PublicKey } from "@solana/web3.js";
+import {
+  buildCloseEmptyTokenAccountsInstruction,
+  buildCloseEmptyTokenAccountsTransactions,
+  PROGRAM_ID,
+  TOKEN_PROGRAM_ID,
+} from "@unclaimedsol/spl-burn-close-sdk";
+
+const connection = new Connection("https://api.mainnet-beta.solana.com");
+declare const user: PublicKey;
+declare const pairs: { mint: PublicKey; ata: PublicKey }[];
+
+// Instruction only: no RPC calls. Returns null for an empty list.
+const ix = await buildCloseEmptyTokenAccountsInstruction(
+  PROGRAM_ID, user, pairs, TOKEN_PROGRAM_ID
+);
+
+// Unsigned batches: fetches one blockhash unless supplied in BuildOptions.
+// Returns [] for an empty list. The default token program is classic SPL Token.
+const txs = await buildCloseEmptyTokenAccountsTransactions(
+  connection, PROGRAM_ID, user, pairs, { chunkSize: 12 }, TOKEN_PROGRAM_ID
+);
+// Sign and send using your wallet only after confirming upgrade availability.
+```
+
+Use `TOKEN_2022_PROGRAM_ID` for Token-2022. Each instruction uses one token program;
+group accounts by program and build separate instructions or batches. `Pair.ata`
+can also name a non-ATA token account. Both transaction builders use the same
+`BuildOptions`, expiry metadata, fee payer defaults and packet-size checks below.
+
+Eligibility is enforced by the upgraded program at execution, not by SDK RPC
+balance checks. Ineligible targets may be skipped while eligible siblings close;
+an entirely skipped batch may succeed. A built transaction or successful signature
+alone does not prove every requested account closed. Check resulting account state
+and execution results before reporting recovered amounts.
+
+Funded WSOL, including unsynchronized SOL deposits, is excluded. A native account
+must have zero token amount and lamports exactly equal to its recorded reserve.
+The program does not burn, unwrap funded principal, or call `SyncNative` on this path.
+Token-2022 support is conservative: supported account extensions are `ImmutableOwner`
+and `TransferFeeAmount`, with `TransferFeeConfig` on mints. Other extensions are
+skipped. Eligible withheld transfer fees may be harvested to the mint before closure.
+
+The existing per-account fee policy applies only to successful closures; skipped
+targets incur no service fee, though network transaction fees still apply. This
+change addresses empty-token cleanup. It does not introduce checked buffer approvals
+or guarantee exact preview proceeds. Buffer, reward and stake paths are outside this API.
+
+Selector 2 validates effective transaction-wide privileges. Keep the fee recipient,
+mints and token accounts nonsigners, and the token/system programs read-only. A
+custom fee payer must not alias these accounts; the signing wallet may be the payer
+but cannot also be the fee recipient. Instructions added to the same transaction
+must preserve these requirements.
+
+The ABI is verified against Rust commit
+[`1f2b10ae668c47de97627de69cdf656878ed9b0e`](https://github.com/nedim1511/unclaimed-sol-close-token-program/commit/1f2b10ae668c47de97627de69cdf656878ed9b0e),
+its [instruction specification](https://github.com/nedim1511/unclaimed-sol-close-token-program/blob/1f2b10ae668c47de97627de69cdf656878ed9b0e/docs/close-empty-token-accounts.md)
+and [deterministic fixture](https://github.com/nedim1511/unclaimed-sol-close-token-program/blob/1f2b10ae668c47de97627de69cdf656878ed9b0e/tests/fixtures/close_empty_token_accounts.json).
+Exact data is `[2]`; metas are writable fee recipient, writable signing wallet,
+read-only token and system programs, then writable mint/token-account pairs.
+Source and local runtime verification do not establish deployment.
+
+### Intentional burning: signing with Keypair
 
 ```typescript
 import { Connection, Keypair, PublicKey } from "@solana/web3.js";
@@ -65,19 +144,19 @@ 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);
 }
 ```
 
-### Signing with Wallet Adapter
+### Intentional burning: signing with Wallet Adapter
 
 ```typescript
 import { Connection, PublicKey } from "@solana/web3.js";
@@ -109,7 +188,7 @@ const txs = await buildBurnAndCloseTransactions(
 //   PROGRAM_ID,
 //   user,
 //   pairs,
-//   { chunkSize: 2 },
+//   { chunkSize: 3 },
 //   TOKEN_2022_PROGRAM_ID
 // );
 
@@ -119,27 +198,72 @@ 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`).
 Transactions will only succeed on a cluster where that program is deployed.
 
+## Verification
+
+Run `npm test` for encoding, unsigned transaction behavior and legacy regressions.
+Run `npm run test:package` to pack the actual package, verify its contents, load
+CJS/ESM exports and compile consumers with Node16 and bundler type resolution.
+
+For local runtime evidence, run `npm run test:runtime` with the Rust repository
+at `../unclaimed-sol-rust-program`, its verified SBF artifact already built, and
+`solana-test-validator` installed. An alternative Rust checkout can be supplied
+with `npm run test:runtime -- /path/to/unclaimed-sol-rust-program`.
+The harness checks the pinned Rust commit and artifact hash, starts an isolated
+validator on local ports 18899–18940, and uses generated test keys and synthetic
+accounts. It verifies closures, fees, late deposits, WSOL exclusions and legacy
+burning for both token programs. Temporary ledger/log files are retained at the
+printed path. The runtime harness is excluded from the published package.
+
+Local runtime success does not verify a deployed cluster or certify future token
+program versions. See [the 1.4.0 release handoff](https://github.com/unclaimed-sol/spl-burn-close-sdk/blob/main/docs/release-1.4.0.md)
+in the source repository for evidence limits and MCP adoption steps.
+
 ---
 
 ## 💻 Demo
@@ -150,7 +274,7 @@ There is a nice tutorial guide with a demo repository that shows the usage of th
 
 ## 📜 Disclaimer
 
-This SDK only **builds transactions** to burn tokens and close accounts. You are solely responsible for signing and sending them. We are not liable for any loss of funds.
+This SDK only **builds instructions and unsigned transactions** for the selected cleanup path. You are solely responsible for signing and sending them. We are not liable for any loss of funds.
 
 ---
 

package/dist/index.cjs

@@ -2,7 +2,9 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.TOKEN_2022_PROGRAM_ID = exports.TOKEN_PROGRAM_ID = exports.FEE_RECIPIENT = exports.PROGRAM_ID = void 0;
 exports.buildBurnAndCloseTransactions = buildBurnAndCloseTransactions;
+exports.buildCloseEmptyTokenAccountsTransactions = buildCloseEmptyTokenAccountsTransactions;
 exports.buildBurnAndCloseInstruction = buildBurnAndCloseInstruction;
+exports.buildCloseEmptyTokenAccountsInstruction = buildCloseEmptyTokenAccountsInstruction;
 const web3_js_1 = require("@solana/web3.js");
 /** Exporting on-chain program ID for convenience */
 exports.PROGRAM_ID = new web3_js_1.PublicKey("UNCaXzXkR3vp8mbCJyxWUvwuRk5uHgzrwe6jcWPfiUR");
@@ -10,6 +12,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(operation) {
+    return new Error(`${operation}: 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,42 +36,58 @@ 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) {
+    return buildTokenAccountTransactions(connection, programId, user, pairs, options, tokenProgramId, 0);
+}
+/**
+ * Build unsigned transactions requesting execution-time empty-account checks.
+ * Requires the upgraded program's selector 2. It never burns or falls back to
+ * burn-and-close. Ineligible targets can be skipped, including funded WSOL.
+ * Only a blockhash is fetched; the program enforces account eligibility.
+ */
+async function buildCloseEmptyTokenAccountsTransactions(connection, programId, user, pairs, options = {}, tokenProgramId = exports.TOKEN_PROGRAM_ID) {
+    return buildTokenAccountTransactions(connection, programId, user, pairs, options, tokenProgramId, 2);
+}
+async function buildTokenAccountTransactions(connection, programId, user, pairs, options, tokenProgramId, selector) {
+    const operation = selector === 0 ? "Burn and close" : "Close empty token accounts";
+    const chunkSize = options.chunkSize ?? 12;
+    if (!Number.isFinite(chunkSize) || !Number.isInteger(chunkSize) || chunkSize <= 0) {
+        throw new Error(`${operation}: 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));
     }
-    // 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 data = new Uint8Array([selector]);
+    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 = [
-            // NOTE: Mark the user as signer in the instruction meta;
-            // the caller must actually sign the Transaction later.
-            { pubkey: exports.FEE_RECIPIENT, isSigner: false, isWritable: true },
-            { pubkey: user, isSigner: true, isWritable: true },
-            { pubkey: tokenProgramId, isSigner: false, isWritable: false },
-            { pubkey: web3_js_1.SystemProgram.programId, isSigner: false, isWritable: false },
-        ];
-        for (const { mint, ata } of chunk) {
-            keys.push({ pubkey: mint, isSigner: false, isWritable: true }, { pubkey: ata, isSigner: false, isWritable: true });
-        }
-        const ix = new web3_js_1.TransactionInstruction({
-            programId,
-            keys,
-            data,
-        });
+        const ix = tokenAccountInstruction(programId, user, chunk, tokenProgramId, data);
         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(operation);
+            }
+            throw new Error(`${operation}: transaction could not be serialized. ` +
+                "Check the supplied transaction inputs, including recentBlockhash and account keys.", { cause: error });
+        }
+        if (wireSize > PACKET_DATA_SIZE) {
+            throw packetSizeError(operation);
+        }
         txs.push(tx);
     }
     return txs;
@@ -70,13 +99,29 @@ 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) {
         return null;
     }
-    // instruction data selector: 0 = burn_and_close_token_accounts
-    const data = new Uint8Array([0]);
+    return tokenAccountInstruction(programId, user, pairs, tokenProgramId, new Uint8Array([0]));
+}
+/**
+ * Build one close-empty instruction for SPL Token or Token-2022, without RPC.
+ * Returns null for empty input. Requires deployed selector 2 support; eligibility
+ * is checked by the program at execution, and ineligible targets may be skipped.
+ * This path never burns, including when tokens arrive after a preview.
+ * Data is a browser-safe Uint8Array typed as Buffer; avoid Buffer-only methods.
+ */
+async function buildCloseEmptyTokenAccountsInstruction(programId, user, pairs, tokenProgramId) {
+    if (!pairs.length) {
+        return null;
+    }
+    return tokenAccountInstruction(programId, user, pairs, tokenProgramId, new Uint8Array([2]));
+}
+function tokenAccountInstruction(programId, user, pairs, tokenProgramId, data) {
     // accounts order MUST match the on-chain program's expectation:
     // [0] fee_recipient_account (your fee recipient)
     // [1] user_wallet_account (the signer)

package/dist/index.d.cts

@@ -0,0 +1,68 @@
+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 unsigned transactions requesting execution-time empty-account checks.
+ * Requires the upgraded program's selector 2. It never burns or falls back to
+ * burn-and-close. Ineligible targets can be skipped, including funded WSOL.
+ * Only a blockhash is fetched; the program enforces account eligibility.
+ */
+export declare function buildCloseEmptyTokenAccountsTransactions(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>;
+/**
+ * Build one close-empty instruction for SPL Token or Token-2022, without RPC.
+ * Returns null for empty input. Requires deployed selector 2 support; eligibility
+ * is checked by the program at execution, and ineligible targets may be skipped.
+ * This path never burns, including when tokens arrive after a preview.
+ * Data is a browser-safe Uint8Array typed as Buffer; avoid Buffer-only methods.
+ */
+export declare function buildCloseEmptyTokenAccountsInstruction(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.
@@ -38,6 +40,13 @@ export type BuildOptions = {
  * @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 unsigned transactions requesting execution-time empty-account checks.
+ * Requires the upgraded program's selector 2. It never burns or falls back to
+ * burn-and-close. Ineligible targets can be skipped, including funded WSOL.
+ * Only a blockhash is fetched; the program enforces account eligibility.
+ */
+export declare function buildCloseEmptyTokenAccountsTransactions(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).
@@ -45,5 +54,15 @@ 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>;
+/**
+ * Build one close-empty instruction for SPL Token or Token-2022, without RPC.
+ * Returns null for empty input. Requires deployed selector 2 support; eligibility
+ * is checked by the program at execution, and ineligible targets may be skipped.
+ * This path never burns, including when tokens arrive after a preview.
+ * Data is a browser-safe Uint8Array typed as Buffer; avoid Buffer-only methods.
+ */
+export declare function buildCloseEmptyTokenAccountsInstruction(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(operation) {
+    return new Error(`${operation}: 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,42 +29,58 @@ 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) {
+    return buildTokenAccountTransactions(connection, programId, user, pairs, options, tokenProgramId, 0);
+}
+/**
+ * Build unsigned transactions requesting execution-time empty-account checks.
+ * Requires the upgraded program's selector 2. It never burns or falls back to
+ * burn-and-close. Ineligible targets can be skipped, including funded WSOL.
+ * Only a blockhash is fetched; the program enforces account eligibility.
+ */
+export async function buildCloseEmptyTokenAccountsTransactions(connection, programId, user, pairs, options = {}, tokenProgramId = TOKEN_PROGRAM_ID) {
+    return buildTokenAccountTransactions(connection, programId, user, pairs, options, tokenProgramId, 2);
+}
+async function buildTokenAccountTransactions(connection, programId, user, pairs, options, tokenProgramId, selector) {
+    const operation = selector === 0 ? "Burn and close" : "Close empty token accounts";
+    const chunkSize = options.chunkSize ?? 12;
+    if (!Number.isFinite(chunkSize) || !Number.isInteger(chunkSize) || chunkSize <= 0) {
+        throw new Error(`${operation}: 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));
     }
-    // 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 data = new Uint8Array([selector]);
+    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 = [
-            // NOTE: Mark the user as signer in the instruction meta;
-            // the caller must actually sign the Transaction later.
-            { pubkey: FEE_RECIPIENT, isSigner: false, isWritable: true },
-            { pubkey: user, isSigner: true, isWritable: true },
-            { pubkey: tokenProgramId, isSigner: false, isWritable: false },
-            { pubkey: SystemProgram.programId, isSigner: false, isWritable: false },
-        ];
-        for (const { mint, ata } of chunk) {
-            keys.push({ pubkey: mint, isSigner: false, isWritable: true }, { pubkey: ata, isSigner: false, isWritable: true });
-        }
-        const ix = new TransactionInstruction({
-            programId,
-            keys,
-            data,
-        });
+        const ix = tokenAccountInstruction(programId, user, chunk, tokenProgramId, data);
         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(operation);
+            }
+            throw new Error(`${operation}: transaction could not be serialized. ` +
+                "Check the supplied transaction inputs, including recentBlockhash and account keys.", { cause: error });
+        }
+        if (wireSize > PACKET_DATA_SIZE) {
+            throw packetSizeError(operation);
+        }
         txs.push(tx);
     }
     return txs;
@@ -65,13 +92,29 @@ 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) {
         return null;
     }
-    // instruction data selector: 0 = burn_and_close_token_accounts
-    const data = new Uint8Array([0]);
+    return tokenAccountInstruction(programId, user, pairs, tokenProgramId, new Uint8Array([0]));
+}
+/**
+ * Build one close-empty instruction for SPL Token or Token-2022, without RPC.
+ * Returns null for empty input. Requires deployed selector 2 support; eligibility
+ * is checked by the program at execution, and ineligible targets may be skipped.
+ * This path never burns, including when tokens arrive after a preview.
+ * Data is a browser-safe Uint8Array typed as Buffer; avoid Buffer-only methods.
+ */
+export async function buildCloseEmptyTokenAccountsInstruction(programId, user, pairs, tokenProgramId) {
+    if (!pairs.length) {
+        return null;
+    }
+    return tokenAccountInstruction(programId, user, pairs, tokenProgramId, new Uint8Array([2]));
+}
+function tokenAccountInstruction(programId, user, pairs, tokenProgramId, data) {
     // accounts order MUST match the on-chain program's expectation:
     // [0] fee_recipient_account (your fee recipient)
     // [1] user_wallet_account (the signer)

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@unclaimedsol/spl-burn-close-sdk",
-  "version": "1.2.2",
-  "description": "SDK to burn and close SPL token accounts via the Unclaimed SOL program with benchmarked rent cleanup fees.",
+  "version": "1.4.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,15 @@
   "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",
+    "test:runtime": "npm run build && node scripts/test-runtime.js"
   },
   "peerDependencies": {
     "@solana/web3.js": "^1.98.4"