@unclaimedsol/spl-burn-close-sdk 1.0.0

package/README.md

@@ -0,0 +1,121 @@
+# 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.
+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).
+- ⚡ Automatic batching (default 12 ATAs per transaction).
+- 🔐 Supports **frontend partial signing** and **backend full signing** workflows.
+- 🚀 No hidden config: single function to integrate.
+
+---
+
+## 📦 Installation
+
+```bash
+npm i @unclaimedsol/spl-burn-close-sdk @solana/web3.js
+```
+
+We use peerDependencies to avoid version conflicts.
+
+Requires Node 18+.
+
+## 🔑 Usage
+
+### Signing with Keypair
+
+```typescript
+import { Connection, Keypair } from "@solana/web3.js";
+import {
+  buildBurnAndCloseTransactions,
+  PROGRAM_ID,
+} from "@unclaimedsol/spl-burn-close-sdk";
+
+const connection = new Connection("https://api.mainnet-beta.solana.com");
+const keypair = Keypair.fromSecretKey(/* Uint8Array */);
+const user = keypair.publicKey;
+
+// You can get easily obtain pairs using getTokenAccountsByOwner method
+const pairs = [{ mint: new PublicKey("MINT_1"), ata: new PublicKey("ATA_1") }];
+
+const txs = await buildBurnAndCloseTransactions(
+  connection,
+  PROGRAM_ID,
+  user,
+  pairs
+);
+
+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({
+    signature: sig,
+    blockhash: latestBlockhash.blockhash,
+    lastValidBlockHeight: latestBlockhash.lastValidBlockHeight,
+  });
+  console.log("✅ Sent:", sig);
+}
+```
+
+### Signing with Wallet Adapter
+
+```typescript
+import { Connection, PublicKey } from "@solana/web3.js";
+import {
+  buildBurnAndCloseTransactions,
+  PROGRAM_ID,
+} from "@unclaimedsol/spl-burn-close-sdk";
+
+const connection = new Connection("https://api.mainnet-beta.solana.com");
+const user = wallet.publicKey; // Wallet Adapter
+
+// You can get easily obtain pairs using getTokenAccountsByOwner method
+const pairs = [
+  { mint: new PublicKey("MINT_1"), ata: new PublicKey("ATA_1") },
+  { mint: new PublicKey("MINT_2"), ata: new PublicKey("ATA_2") },
+];
+
+const txs = await buildBurnAndCloseTransactions(
+  connection,
+  PROGRAM_ID,
+  user,
+  pairs
+);
+
+// Sign
+const signed = wallet.signAllTransactions
+  ? await wallet.signAllTransactions(txs)
+  : await Promise.all(txs.map((t) => wallet.signTransaction!(t)));
+
+// Send
+for (const stx of signed) {
+  const sig = await connection.sendRawTransaction(tx.serialize());
+  let latestBlockhash = await connection.getLatestBlockhash(
+    connection.commitment
+  );
+  await connection.confirmTransaction({
+    signature: sig,
+    blockhash: latestBlockhash.blockhash,
+    lastValidBlockHeight: latestBlockhash.lastValidBlockHeight,
+  });
+  console.log("✅ Sent:", sig);
+}
+```
+
+## 🧩 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. A 5% fee is enforced on-chain and sent to the hardcoded recipient.
+4. The SDK never asks for private keys — you sign & send transactions yourself.
+
+## 📜 License
+
+MIT © [Unclaimed SOL](https://unclaimedsol.com)

package/dist/index.cjs

@@ -0,0 +1,64 @@
+import { PublicKey, SystemProgram, Transaction, TransactionInstruction, } from "@solana/web3.js";
+/** Exporting on-chain program ID for convenience */
+const PROGRAM_ID = new PublicKey("UNCaXzXkR3vp8mbCJyxWUvwuRk5uHgzrwe6jcWPfiUR");
+/** Hardcoded fee recipient on-chain expectation */
+const FEE_RECIPIENT = new PublicKey("uncNCRycMtNPj2kXHfwiCgNrzCTnC9xU5FS8ZeWyn3M");
+const TOKEN_PROGRAM_ID = new PublicKey("TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA");
+/** Fixed fee percentage enforced by the program (5%) */
+const FIXED_FEE_PERCENTAGE = 5; // do not change
+/**
+ * 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
+ * @returns           Array of *unsigned* Transaction objects
+ */
+export async function buildBurnAndCloseTransactions(connection, programId, user, pairs, options = {}) {
+    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
+    const chunks = [];
+    for (let i = 0; i < pairs.length; i += chunkSize) {
+        chunks.push(pairs.slice(i, i + chunkSize));
+    }
+    // Instruction data: [selector=0, fee_pct=5]
+    const data = Buffer.from([0, FIXED_FEE_PERCENTAGE]);
+    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: TOKEN_PROGRAM_ID, 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 tx = new Transaction().add(ix);
+        tx.feePayer = feePayer;
+        // Use provided blockhash or fetch one
+        if (options.recentBlockhash) {
+            tx.recentBlockhash = options.recentBlockhash;
+        }
+        else {
+            const { blockhash } = await connection.getLatestBlockhash({ commitment });
+            tx.recentBlockhash = blockhash;
+        }
+        txs.push(tx);
+    }
+    return txs;
+}

package/dist/index.d.ts

@@ -0,0 +1,40 @@
+import { Connection, PublicKey, Transaction, 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;
+/** Fixed fee percentage enforced by the program (5%) */
+export declare const FIXED_FEE_PERCENTAGE = 5;
+export type Pair = {
+    mint: PublicKey;
+    ata: PublicKey;
+};
+export type BuildOptions = {
+    /** Max pairs per transaction (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 per transaction.
+     */
+    recentBlockhash?: string;
+};
+/**
+ * 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
+ * @returns           Array of *unsigned* Transaction objects
+ */
+export declare function buildBurnAndCloseTransactions(connection: Connection, programId: PublicKey, user: PublicKey, pairs: Pair[], options?: BuildOptions): Promise<Transaction[]>;

package/dist/index.js

@@ -0,0 +1,64 @@
+import { PublicKey, SystemProgram, Transaction, TransactionInstruction, } from "@solana/web3.js";
+/** Exporting on-chain program ID for convenience */
+export const PROGRAM_ID = new PublicKey("UNCaXzXkR3vp8mbCJyxWUvwuRk5uHgzrwe6jcWPfiUR");
+/** Hardcoded fee recipient on-chain expectation */
+export const FEE_RECIPIENT = new PublicKey("uncNCRycMtNPj2kXHfwiCgNrzCTnC9xU5FS8ZeWyn3M");
+export const TOKEN_PROGRAM_ID = new PublicKey("TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA");
+/** Fixed fee percentage enforced by the program (5%) */
+export const FIXED_FEE_PERCENTAGE = 5; // do not change
+/**
+ * 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
+ * @returns           Array of *unsigned* Transaction objects
+ */
+export async function buildBurnAndCloseTransactions(connection, programId, user, pairs, options = {}) {
+    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
+    const chunks = [];
+    for (let i = 0; i < pairs.length; i += chunkSize) {
+        chunks.push(pairs.slice(i, i + chunkSize));
+    }
+    // Instruction data: [selector=0, fee_pct=5]
+    const data = Buffer.from([0, FIXED_FEE_PERCENTAGE]);
+    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: TOKEN_PROGRAM_ID, 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 tx = new Transaction().add(ix);
+        tx.feePayer = feePayer;
+        // Use provided blockhash or fetch one
+        if (options.recentBlockhash) {
+            tx.recentBlockhash = options.recentBlockhash;
+        }
+        else {
+            const { blockhash } = await connection.getLatestBlockhash({ commitment });
+            tx.recentBlockhash = blockhash;
+        }
+        txs.push(tx);
+    }
+    return txs;
+}

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "@unclaimedsol/spl-burn-close-sdk",
+  "version": "1.0.0",
+  "description": "SDK to burn and close SPL token accounts via the Unclaimed SOL program (with a built-in 5% fee).",
+  "license": "MIT",
+  "author": "Unclaimed SOL",
+  "type": "module",
+  "sideEffects": false,
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/unclaimed-sol/spl-burn-close-sdk"
+  },
+  "bugs": {
+    "url": "https://github.com/unclaimed-sol/spl-burn-close-sdk/issues"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json && node ./scripts/build-cjs.js",
+    "prepublishOnly": "npm run build"
+  },
+  "dependencies": {
+    "@solana/web3.js": "^1.98.4"
+  },
+  "devDependencies": {
+    "typescript": "^5.6.3"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "keywords": [
+    "solana",
+    "spl-token",
+    "sdk",
+    "token-account",
+    "close-account",
+    "burn"
+  ]
+}