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

package/CHANGELOG.md

@@ -1,5 +1,24 @@
 # 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

package/README.md

@@ -1,12 +1,23 @@
 # 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.
 - 🧾 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).
@@ -18,8 +29,9 @@ 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.
+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.
 
@@ -41,7 +53,72 @@ that breaks CommonJS loading. CI tests the repository’s locked dependency grap
 
 ## 🔑 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";
@@ -79,7 +156,7 @@ for (const tx of txs) {
 }
 ```
 
-### Signing with Wallet Adapter
+### Intentional burning: signing with Wallet Adapter
 
 ```typescript
 import { Connection, PublicKey } from "@solana/web3.js";
@@ -167,6 +244,26 @@ do not call Buffer-only methods on it.
 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
@@ -177,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");
@@ -12,8 +14,8 @@ exports.TOKEN_PROGRAM_ID = new web3_js_1.PublicKey("TokenkegQfeZyiNwAJbNbGKPFXCW
 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. " +
+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. */
@@ -34,9 +36,22 @@ function isPacketSizeError(error) {
  * @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("Burn and close: chunkSize must be a finite positive integer.");
+        throw new Error(`${operation}: chunkSize must be a finite positive integer.`);
     }
     if (!pairs.length)
         return [];
@@ -47,30 +62,14 @@ async function buildBurnAndCloseTransactions(connection, programId, user, pairs,
     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 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 = blockhash;
@@ -81,13 +80,13 @@ async function buildBurnAndCloseTransactions(connection, programId, user, pairs,
         }
         catch (error) {
             if (isPacketSizeError(error)) {
-                throw packetSizeError();
+                throw packetSizeError(operation);
             }
-            throw new Error("Burn and close: transaction could not be serialized. " +
+            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();
+            throw packetSizeError(operation);
         }
         txs.push(tx);
     }
@@ -107,8 +106,22 @@ async function buildBurnAndCloseInstruction(programId, user, pairs, tokenProgram
     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

@@ -40,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).
@@ -51,3 +58,11 @@ export declare function buildBurnAndCloseTransactions(connection: Connection, pr
  * 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

@@ -40,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).
@@ -51,3 +58,11 @@ export declare function buildBurnAndCloseTransactions(connection: Connection, pr
  * 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

@@ -7,8 +7,8 @@ export const TOKEN_PROGRAM_ID = new PublicKey("TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9
 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. " +
+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. */
@@ -29,9 +29,22 @@ function isPacketSizeError(error) {
  * @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("Burn and close: chunkSize must be a finite positive integer.");
+        throw new Error(`${operation}: chunkSize must be a finite positive integer.`);
     }
     if (!pairs.length)
         return [];
@@ -42,30 +55,14 @@ export async function buildBurnAndCloseTransactions(connection, programId, user,
     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 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 = blockhash;
@@ -76,13 +73,13 @@ export async function buildBurnAndCloseTransactions(connection, programId, user,
         }
         catch (error) {
             if (isPacketSizeError(error)) {
-                throw packetSizeError();
+                throw packetSizeError(operation);
             }
-            throw new Error("Burn and close: transaction could not be serialized. " +
+            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();
+            throw packetSizeError(operation);
         }
         txs.push(tx);
     }
@@ -102,8 +99,22 @@ export async function buildBurnAndCloseInstruction(programId, user, pairs, token
     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,6 +1,6 @@
 {
   "name": "@unclaimedsol/spl-burn-close-sdk",
-  "version": "1.3.0",
+  "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",
@@ -37,7 +37,8 @@
     "build": "tsc -p tsconfig.json && tsc -p tsconfig.cjs.json && node ./scripts/build-cjs.js",
     "prepack": "npm run build",
     "test": "npm run build && node --test test/*.test.js",
-    "test:package": "node scripts/test-package.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"