vacuum-sol 1.0.0

package/README.md

@@ -0,0 +1,362 @@
+# 🧹 Vacuum
+
+**Suck up forgotten rent from Solana accounts.**
+
+Vacuum is an automated rent-reclaim bot that monitors **operator-owned** token accounts and safely reclaims rent SOL when accounts are closed or have zero balance. Perfect for custodial services, development environments, and anyone managing their own Solana token accounts at scale.
+
+![NPM Version](https://img.shields.io/badge/version-1.0.0-blue)
+![License](https://img.shields.io/badge/license-MIT-green)
+![Solana](https://img.shields.io/badge/solana-compatible-purple)
+
+---
+
+## 🚀 Quick Start
+
+```bash
+# Clone and install
+git clone https://github.com/your-username/vacuum-sol
+cd vacuum-sol
+npm install && npm run build
+
+# Configure
+cp .env.example .env
+# Edit .env with your TREASURY_ADDRESS
+
+# Run
+npm start -- scan          # Find accounts
+npm start -- check --all   # Find reclaimable
+npm start -- reclaim --dry-run  # Preview reclaim
+```
+
+---
+
+## 📖 Understanding Solana Rent
+
+### What is Rent?
+
+Every Solana account must hold **rent** (SOL) to stay active:
+
+| Account Type              | Rent Cost    |
+| ------------------------- | ------------ |
+| Token Account (165 bytes) | ~0.00204 SOL |
+| 1KB Account               | ~0.00696 SOL |
+
+When accounts are **closed**, this rent is returned to a designated address.
+
+### The Problem
+
+- Developers and custodial services create thousands of token accounts
+- Many get abandoned (testing, unused wallets, closed positions, etc.)
+- Rent stays locked in zero-balance accounts forever unless reclaimed
+- **Result**: Silent capital loss of ~0.00204 SOL per account
+
+> **⚠️ Important**: Vacuum reclaims rent from **accounts you own** (where your operator keypair is the account authority). It does NOT work for accounts where you merely paid transaction fees as a paymaster. See [Authority Model](#-authority-model) for details.
+
+### The Solution
+
+Vacuum automatically:
+
+1. **Tracks** sponsored accounts in a local database
+2. **Detects** accounts with 0 balance (safe to close)
+3. **Reclaims** rent back to your treasury
+4. **Reports** locked vs reclaimed totals
+
+---
+
+## ✨ Features
+
+| Feature                 | Description                                       |
+| ----------------------- | ------------------------------------------------- |
+| 🔍 **Smart Detection**  | Finds zero-balance token accounts safe to close   |
+| 🛡️ **Safety First**     | Dry-run mode, whitelists, balance verification    |
+| 🤖 **Telegram Bot**     | Monitor and trigger reclaims from your phone      |
+| 📊 **Audit Trail**      | Every reclaim logged with TX signatures           |
+| ⏰ **Automation Ready** | Run on schedule with cron, PM2, or GitHub Actions |
+| 💻 **CLI Interface**    | 8 powerful commands for full control              |
+
+---
+
+## 📋 CLI Commands
+
+```bash
+# Scanning
+vacuum scan                # Scan operator's token accounts
+vacuum scan --tx <sig>     # Scan specific transactions
+
+# Checking
+vacuum check --all         # Find all reclaimable accounts
+vacuum check --address <pubkey>  # Check specific account
+
+# Reclaiming
+vacuum reclaim --dry-run   # Preview reclaim (safe)
+vacuum reclaim --yes       # Actually reclaim
+vacuum reclaim --max 20    # Limit to 20 accounts
+
+# Reporting
+vacuum report              # Show summary
+vacuum report --history    # Show reclaim history
+vacuum report --format json  # Export as JSON
+
+# Protection
+vacuum protect --add <pubkey> --reason "Active user"
+vacuum protect --remove <pubkey>
+vacuum protect --list
+
+# Listing
+vacuum list                # List all tracked accounts
+vacuum list --status reclaimable  # Filter by status
+
+# Bot
+vacuum bot                 # Start Telegram bot
+
+# Config
+vacuum config              # Show configuration
+```
+
+---
+
+## 🤖 Telegram Integration
+
+### Setup
+
+1. Create a bot: Message `@BotFather` on Telegram → `/newbot`
+2. Get your chat ID: Message `@userinfobot`
+3. Add to `.env`:
+   ```env
+   TELEGRAM_BOT_TOKEN=your-bot-token
+   TELEGRAM_CHAT_ID=your-chat-id
+   ```
+
+### Run the Bot
+
+```bash
+npm start -- bot
+```
+
+### Telegram Commands
+
+| Command            | Action            |
+| ------------------ | ----------------- |
+| `/status`          | Show rent summary |
+| `/scan`            | Scan for accounts |
+| `/check`           | Find reclaimable  |
+| `/reclaim`         | Preview reclaim   |
+| `/reclaim_execute` | Actually reclaim  |
+| `/history`         | Recent reclaims   |
+
+---
+
+## ⚙️ Configuration
+
+Create a `.env` file:
+
+```env
+# Required
+SOLANA_RPC_URL=https://api.devnet.solana.com
+TREASURY_ADDRESS=<your-wallet-address>
+OPERATOR_KEYPAIR_PATH=./operator-keypair.json
+
+# Optional
+DRY_RUN=true
+COOLDOWN_HOURS=24
+MIN_INACTIVE_DAYS=7
+TELEGRAM_BOT_TOKEN=
+TELEGRAM_CHAT_ID=
+
+# Database
+DB_PATH=./data/accounts.db
+```
+
+---
+
+## 🛡️ Safety Features
+
+✅ **Dry-Run Mode** - Preview all actions before executing  
+✅ **Zero Balance Check** - Only closes accounts with 0 tokens  
+✅ **Protected Accounts** - Whitelist accounts to never reclaim  
+✅ **Authority Verification** - Confirms operator owns the account  
+✅ **Audit Trail** - All reclaims logged with TX signatures  
+✅ **Cooldown Periods** - Wait N days before reclaiming inactive accounts
+
+---
+
+## 🔐 Authority Model
+
+**Critical Understanding**: Vacuum can only reclaim rent from accounts where your operator keypair is the **account owner/authority**.
+
+### ✅ Works For:
+
+- Token accounts created by your operator wallet
+- Custodial service accounts you manage
+- Development/testing accounts you own
+- Any account where `closeAuthority` is your operator
+
+### ❌ Does NOT Work For:
+
+- User-owned accounts (even if you paid fees as a Kora paymaster)
+- Accounts where you're only the fee payer, not the owner
+- Third-party wallets using your paymaster service
+
+**Why?** On Solana, paying transaction fees ≠ account ownership. Only the account's `owner` or `closeAuthority` can close it and reclaim rent.
+
+### Use Cases
+
+1. **Custodial Services**: Reclaim rent from your users' accounts you manage
+2. **Development**: Clean up test accounts from devnet/testnet
+3. **Personal Management**: Monitor your own token accounts
+4. **Bulk Account Management**: Manage rent across multiple operator profiles
+
+---
+
+## 🏗️ Architecture
+
+```
+vacuum-sol/
+├── src/
+│   ├── index.ts              # CLI entry point
+│   ├── config.ts             # Environment configuration
+│   ├── core/
+│   │   ├── types.ts          # TypeScript interfaces
+│   │   ├── monitor.ts        # Account scanning
+│   │   ├── detector.ts       # Reclaimable detection
+│   │   └── reclaimer.ts      # Rent reclaim execution
+│   ├── db/
+│   │   ├── index.ts          # SQLite setup
+│   │   └── accounts.ts       # CRUD operations
+│   ├── services/
+│   │   ├── solana.ts         # Solana RPC wrapper
+│   │   ├── telegram.ts       # Telegram bot
+│   │   └── reporter.ts       # Report generation
+│   └── utils/
+│       ├── logger.ts         # Colored logging
+│       └── helpers.ts        # Utilities
+├── scripts/
+│   └── simulate.ts           # Devnet testing
+└── landing/
+    └── index.html            # Landing page
+```
+
+---
+
+## 🧪 Testing on Devnet
+
+### 1. Setup
+
+```bash
+# Generate keypair
+solana-keygen new -o operator-keypair.json
+
+# Get devnet SOL
+solana airdrop 2 --keypair operator-keypair.json --url devnet
+
+# Configure for devnet
+# Edit .env: SOLANA_RPC_URL=https://api.devnet.solana.com
+```
+
+### 2. Create Test Accounts
+
+```bash
+npx tsx scripts/simulate.ts create
+```
+
+This creates token accounts with 0 balance for testing.
+
+### 3. Run the Bot
+
+```bash
+npm start -- scan
+npm start -- check --all
+npm start -- reclaim --dry-run
+```
+
+### 4. Actual Reclaim
+
+```bash
+DRY_RUN=false npm start -- reclaim --yes
+```
+
+---
+
+## 📊 Example Report
+
+```
+📊 Rent Reclaim Summary
+┌────────────────────────────────┐
+│ Total Accounts Tracked: 150    │
+│ ├─ Active:      85             │
+│ ├─ Reclaimable: 42             │
+│ ├─ Reclaimed:   20             │
+│ └─ Protected:   3              │
+│                                │
+│ 💰 Rent Status                 │
+│ ├─ Locked:    0.285 SOL        │
+│ └─ Reclaimed: 0.041 SOL        │
+└────────────────────────────────┘
+```
+
+---
+
+## 🔧 Automation
+
+### Cron
+
+```bash
+# Add to crontab for daily 6am checks
+0 6 * * * cd /path/to/vacuum-sol && DRY_RUN=false npm start -- reclaim --yes
+```
+
+### PM2
+
+```bash
+npm install -g pm2
+pm2 start npm --name "vacuum-reclaim" --cron "0 6 * * *" -- start -- reclaim --yes
+```
+
+### GitHub Actions
+
+```yaml
+name: Daily Reclaim
+on:
+  schedule:
+    - cron: '0 6 * * *'
+jobs:
+  reclaim:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+      - run: npm install && npm run build
+      - run: npm start -- reclaim --yes
+        env:
+          TREASURY_ADDRESS: ${{ secrets.TREASURY_ADDRESS }}
+```
+
+---
+
+## 🤝 Contributing
+
+Contributions welcome! Open an issue or PR.
+
+---
+
+## 📄 License
+
+MIT License - see [LICENSE](LICENSE)
+
+---
+
+## 🙏 Acknowledgements
+
+- [Kora](https://kora.network) - Gasless transaction infrastructure
+- [Solana](https://solana.com) - High-performance blockchain
+- SuperteamNG - Bounty program
+
+---
+
+<div align="center">
+  <strong>Built with ❤️ for the Solana ecosystem</strong>
+  <br><br>
+  <a href="https://github.com/your-username/vacuum-sol">GitHub</a> •
+  <a href="https://t.me/vacuumsol">Telegram</a> •
+  <a href="https://your-landing-page.com">Website</a>
+</div>

package/dist/config.d.ts

@@ -0,0 +1,15 @@
+import { PublicKey } from '@solana/web3.js';
+export interface Config {
+    rpcUrl: string;
+    treasuryAddress: PublicKey;
+    operatorKeypairPath: string;
+    koraNodeUrl?: string;
+    dryRun: boolean;
+    cooldownHours: number;
+    minInactiveDays: number;
+    dbPath: string;
+}
+export declare function loadConfig(): Config;
+export declare function loadOperatorKeypair(keypairPath: string): Uint8Array;
+export declare function getConfig(): Config;
+//# sourceMappingURL=config.d.ts.map

package/dist/config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAA;AAQ3C,MAAM,WAAW,MAAM;IAErB,MAAM,EAAE,MAAM,CAAA;IAGd,eAAe,EAAE,SAAS,CAAA;IAC1B,mBAAmB,EAAE,MAAM,CAAA;IAG3B,WAAW,CAAC,EAAE,MAAM,CAAA;IAGpB,MAAM,EAAE,OAAO,CAAA;IACf,aAAa,EAAE,MAAM,CAAA;IACrB,eAAe,EAAE,MAAM,CAAA;IAGvB,MAAM,EAAE,MAAM,CAAA;CACf;AAcD,wBAAgB,UAAU,IAAI,MAAM,CA+BnC;AAED,wBAAgB,mBAAmB,CAAC,WAAW,EAAE,MAAM,GAAG,UAAU,CAYnE;AAKD,wBAAgB,SAAS,IAAI,MAAM,CAKlC"}

package/dist/config.js

@@ -0,0 +1,58 @@
+import { PublicKey } from '@solana/web3.js';
+import { config as loadEnv } from 'dotenv';
+import { existsSync, readFileSync } from 'fs';
+import path from 'path';
+// Load environment variables
+loadEnv();
+function getEnvOrThrow(key) {
+    const value = process.env[key];
+    if (!value) {
+        throw new Error(`Missing required environment variable: ${key}`);
+    }
+    return value;
+}
+function getEnvOrDefault(key, defaultValue) {
+    return process.env[key] || defaultValue;
+}
+export function loadConfig() {
+    const treasuryAddressStr = process.env.TREASURY_ADDRESS;
+    if (!treasuryAddressStr) {
+        throw new Error('TREASURY_ADDRESS is required. Set it in your .env file.');
+    }
+    let treasuryAddress;
+    try {
+        treasuryAddress = new PublicKey(treasuryAddressStr);
+    }
+    catch {
+        throw new Error(`Invalid TREASURY_ADDRESS: ${treasuryAddressStr}. Must be a valid Solana public key.`);
+    }
+    const operatorKeypairPath = getEnvOrDefault('OPERATOR_KEYPAIR_PATH', './operator-keypair.json');
+    return {
+        rpcUrl: getEnvOrDefault('SOLANA_RPC_URL', 'https://api.devnet.solana.com'),
+        treasuryAddress,
+        operatorKeypairPath,
+        koraNodeUrl: process.env.KORA_NODE_URL,
+        dryRun: getEnvOrDefault('DRY_RUN', 'true') === 'true',
+        cooldownHours: parseInt(getEnvOrDefault('COOLDOWN_HOURS', '24'), 10),
+        minInactiveDays: parseInt(getEnvOrDefault('MIN_INACTIVE_DAYS', '7'), 10),
+        dbPath: getEnvOrDefault('DB_PATH', './data/accounts.db'),
+    };
+}
+export function loadOperatorKeypair(keypairPath) {
+    const resolvedPath = path.resolve(keypairPath);
+    if (!existsSync(resolvedPath)) {
+        throw new Error(`Operator keypair not found at: ${resolvedPath}\n` +
+            'Generate one with: solana-keygen new -o operator-keypair.json');
+    }
+    const keypairData = JSON.parse(readFileSync(resolvedPath, 'utf-8'));
+    return Uint8Array.from(keypairData);
+}
+// Export a singleton config (lazy loaded)
+let _config = null;
+export function getConfig() {
+    if (!_config) {
+        _config = loadConfig();
+    }
+    return _config;
+}
+//# sourceMappingURL=config.js.map

package/dist/config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.js","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAA;AAC3C,OAAO,EAAE,MAAM,IAAI,OAAO,EAAE,MAAM,QAAQ,CAAA;AAC1C,OAAO,EAAE,UAAU,EAAE,YAAY,EAAE,MAAM,IAAI,CAAA;AAC7C,OAAO,IAAI,MAAM,MAAM,CAAA;AAEvB,6BAA6B;AAC7B,OAAO,EAAE,CAAA;AAsBT,SAAS,aAAa,CAAC,GAAW;IAChC,MAAM,KAAK,GAAG,OAAO,CAAC,GAAG,CAAC,GAAG,CAAC,CAAA;IAC9B,IAAI,CAAC,KAAK,EAAE,CAAC;QACX,MAAM,IAAI,KAAK,CAAC,0CAA0C,GAAG,EAAE,CAAC,CAAA;IAClE,CAAC;IACD,OAAO,KAAK,CAAA;AACd,CAAC;AAED,SAAS,eAAe,CAAC,GAAW,EAAE,YAAoB;IACxD,OAAO,OAAO,CAAC,GAAG,CAAC,GAAG,CAAC,IAAI,YAAY,CAAA;AACzC,CAAC;AAED,MAAM,UAAU,UAAU;IACxB,MAAM,kBAAkB,GAAG,OAAO,CAAC,GAAG,CAAC,gBAAgB,CAAA;IAEvD,IAAI,CAAC,kBAAkB,EAAE,CAAC;QACxB,MAAM,IAAI,KAAK,CAAC,yDAAyD,CAAC,CAAA;IAC5E,CAAC;IAED,IAAI,eAA0B,CAAA;IAC9B,IAAI,CAAC;QACH,eAAe,GAAG,IAAI,SAAS,CAAC,kBAAkB,CAAC,CAAA;IACrD,CAAC;IAAC,MAAM,CAAC;QACP,MAAM,IAAI,KAAK,CACb,6BAA6B,kBAAkB,sCAAsC,CACtF,CAAA;IACH,CAAC;IAED,MAAM,mBAAmB,GAAG,eAAe,CACzC,uBAAuB,EACvB,yBAAyB,CAC1B,CAAA;IAED,OAAO;QACL,MAAM,EAAE,eAAe,CAAC,gBAAgB,EAAE,+BAA+B,CAAC;QAC1E,eAAe;QACf,mBAAmB;QACnB,WAAW,EAAE,OAAO,CAAC,GAAG,CAAC,aAAa;QACtC,MAAM,EAAE,eAAe,CAAC,SAAS,EAAE,MAAM,CAAC,KAAK,MAAM;QACrD,aAAa,EAAE,QAAQ,CAAC,eAAe,CAAC,gBAAgB,EAAE,IAAI,CAAC,EAAE,EAAE,CAAC;QACpE,eAAe,EAAE,QAAQ,CAAC,eAAe,CAAC,mBAAmB,EAAE,GAAG,CAAC,EAAE,EAAE,CAAC;QACxE,MAAM,EAAE,eAAe,CAAC,SAAS,EAAE,oBAAoB,CAAC;KACzD,CAAA;AACH,CAAC;AAED,MAAM,UAAU,mBAAmB,CAAC,WAAmB;IACrD,MAAM,YAAY,GAAG,IAAI,CAAC,OAAO,CAAC,WAAW,CAAC,CAAA;IAE9C,IAAI,CAAC,UAAU,CAAC,YAAY,CAAC,EAAE,CAAC;QAC9B,MAAM,IAAI,KAAK,CACb,kCAAkC,YAAY,IAAI;YAChD,+DAA+D,CAClE,CAAA;IACH,CAAC;IAED,MAAM,WAAW,GAAG,IAAI,CAAC,KAAK,CAAC,YAAY,CAAC,YAAY,EAAE,OAAO,CAAC,CAAC,CAAA;IACnE,OAAO,UAAU,CAAC,IAAI,CAAC,WAAW,CAAC,CAAA;AACrC,CAAC;AAED,0CAA0C;AAC1C,IAAI,OAAO,GAAkB,IAAI,CAAA;AAEjC,MAAM,UAAU,SAAS;IACvB,IAAI,CAAC,OAAO,EAAE,CAAC;QACb,OAAO,GAAG,UAAU,EAAE,CAAA;IACxB,CAAC;IACD,OAAO,OAAO,CAAA;AAChB,CAAC"}

package/dist/core/detector.d.ts

@@ -0,0 +1,36 @@
+import { PublicKey } from '@solana/web3.js';
+import type { DetectionResult } from './types.js';
+/**
+ * Detector for identifying reclaimable accounts
+ */
+export declare class ReclaimableDetector {
+    private get minInactiveDays();
+    /**
+     * Check if a single account is reclaimable
+     */
+    checkAccount(pubkey: PublicKey): Promise<DetectionResult | null>;
+    /**
+     * Find all reclaimable accounts
+     */
+    findAllReclaimable(): Promise<DetectionResult[]>;
+    /**
+     * Find only safe-to-reclaim accounts (zero balance token accounts)
+     */
+    findSafeReclaimable(): Promise<DetectionResult[]>;
+    /**
+     * Quick check if an account is closed
+     */
+    isAccountClosed(pubkey: PublicKey): Promise<boolean>;
+    /**
+     * Get summary of reclaimable rent
+     */
+    getReclaimableSummary(): Promise<{
+        totalAccounts: number;
+        safeToReclaim: number;
+        unsafeNeedsReview: number;
+        totalReclaimableLamports: number;
+        safeReclaimableLamports: number;
+    }>;
+}
+export declare const detector: ReclaimableDetector;
+//# sourceMappingURL=detector.d.ts.map

package/dist/core/detector.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"detector.d.ts","sourceRoot":"","sources":["../../src/core/detector.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAA;AAW3C,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,YAAY,CAAA;AAEjD;;GAEG;AACH,qBAAa,mBAAmB;IAC9B,OAAO,KAAK,eAAe,GAE1B;IAED;;OAEG;IACG,YAAY,CAAC,MAAM,EAAE,SAAS,GAAG,OAAO,CAAC,eAAe,GAAG,IAAI,CAAC;IAwFtE;;OAEG;IACG,kBAAkB,IAAI,OAAO,CAAC,eAAe,EAAE,CAAC;IA+BtD;;OAEG;IACG,mBAAmB,IAAI,OAAO,CAAC,eAAe,EAAE,CAAC;IAKvD;;OAEG;IACG,eAAe,CAAC,MAAM,EAAE,SAAS,GAAG,OAAO,CAAC,OAAO,CAAC;IAK1D;;OAEG;IACG,qBAAqB,IAAI,OAAO,CAAC;QACrC,aAAa,EAAE,MAAM,CAAA;QACrB,aAAa,EAAE,MAAM,CAAA;QACrB,iBAAiB,EAAE,MAAM,CAAA;QACzB,wBAAwB,EAAE,MAAM,CAAA;QAChC,uBAAuB,EAAE,MAAM,CAAA;KAChC,CAAC;CAoBH;AAGD,eAAO,MAAM,QAAQ,qBAA4B,CAAA"}

package/dist/core/detector.js

@@ -0,0 +1,142 @@
+import { getConfig } from '../config.js';
+import { getAllTrackedAccounts, getTrackedAccount, isAccountProtected, updateAccountState, } from '../db/accounts.js';
+import { getAccountInfo, getTokenAccountData } from '../services/solana.js';
+import { daysSince, formatSol } from '../utils/helpers.js';
+import { logger } from '../utils/logger.js';
+/**
+ * Detector for identifying reclaimable accounts
+ */
+export class ReclaimableDetector {
+    get minInactiveDays() {
+        return getConfig().minInactiveDays;
+    }
+    /**
+     * Check if a single account is reclaimable
+     */
+    async checkAccount(pubkey) {
+        const trackedAccount = getTrackedAccount(pubkey);
+        if (!trackedAccount) {
+            logger.warn(`Account not tracked: ${pubkey.toBase58()}`);
+            return null;
+        }
+        // Skip protected accounts
+        if (isAccountProtected(pubkey)) {
+            logger.debug(`Account is protected: ${pubkey.toBase58()}`);
+            return null;
+        }
+        // Get current account state from chain
+        const accountInfo = await getAccountInfo(pubkey);
+        // Account is closed (no longer exists on chain)
+        if (!accountInfo) {
+            const result = {
+                account: trackedAccount,
+                reason: 'closed',
+                reclaimableLamports: trackedAccount.rentLamports,
+                safe: true,
+                details: 'Account no longer exists on-chain. Rent was already returned to original payer.',
+            };
+            // Update status in DB
+            updateAccountState(pubkey, { status: 'reclaimed', rentLamports: 0 });
+            return result;
+        }
+        // Check if it's a token account with zero balance
+        if (trackedAccount.accountType === 'token_account' ||
+            trackedAccount.accountType === 'ata') {
+            const tokenData = await getTokenAccountData(pubkey);
+            if (tokenData && tokenData.amount === 0n) {
+                const result = {
+                    account: {
+                        ...trackedAccount,
+                        rentLamports: tokenData.lamports,
+                    },
+                    reason: 'zero_balance',
+                    reclaimableLamports: tokenData.lamports,
+                    safe: true,
+                    details: `Token account has 0 balance. Can close and reclaim ${formatSol(tokenData.lamports)}.`,
+                };
+                // Update status in DB
+                updateAccountState(pubkey, {
+                    status: 'reclaimable',
+                    rentLamports: tokenData.lamports,
+                });
+                return result;
+            }
+        }
+        // Check for inactivity
+        if (trackedAccount.lastActivityAt) {
+            const inactiveDays = daysSince(trackedAccount.lastActivityAt);
+            if (inactiveDays >= this.minInactiveDays) {
+                const result = {
+                    account: trackedAccount,
+                    reason: 'inactive',
+                    reclaimableLamports: accountInfo.lamports,
+                    safe: false, // Mark as unsafe since we can't automatically close non-empty accounts
+                    details: `Account inactive for ${inactiveDays} days. Manual review recommended.`,
+                };
+                return result;
+            }
+        }
+        // Account is active/not reclaimable
+        updateAccountState(pubkey, {
+            status: 'active',
+            rentLamports: accountInfo.lamports,
+        });
+        return null;
+    }
+    /**
+     * Find all reclaimable accounts
+     */
+    async findAllReclaimable() {
+        const accounts = getAllTrackedAccounts();
+        const results = [];
+        logger.info(`Checking ${accounts.length} tracked accounts...`);
+        for (const account of accounts) {
+            if (account.status === 'reclaimed' || account.status === 'protected') {
+                continue;
+            }
+            try {
+                const result = await this.checkAccount(account.pubkey);
+                if (result) {
+                    results.push(result);
+                }
+            }
+            catch (error) {
+                logger.error(`Error checking account ${account.pubkey.toBase58()}:`, error);
+            }
+        }
+        logger.info(`Found ${results.length} reclaimable accounts out of ${accounts.length} total`);
+        return results;
+    }
+    /**
+     * Find only safe-to-reclaim accounts (zero balance token accounts)
+     */
+    async findSafeReclaimable() {
+        const all = await this.findAllReclaimable();
+        return all.filter((r) => r.safe);
+    }
+    /**
+     * Quick check if an account is closed
+     */
+    async isAccountClosed(pubkey) {
+        const info = await getAccountInfo(pubkey);
+        return info === null;
+    }
+    /**
+     * Get summary of reclaimable rent
+     */
+    async getReclaimableSummary() {
+        const results = await this.findAllReclaimable();
+        const safeResults = results.filter((r) => r.safe);
+        const unsafeResults = results.filter((r) => !r.safe);
+        return {
+            totalAccounts: results.length,
+            safeToReclaim: safeResults.length,
+            unsafeNeedsReview: unsafeResults.length,
+            totalReclaimableLamports: results.reduce((sum, r) => sum + r.reclaimableLamports, 0),
+            safeReclaimableLamports: safeResults.reduce((sum, r) => sum + r.reclaimableLamports, 0),
+        };
+    }
+}
+// Export singleton instance
+export const detector = new ReclaimableDetector();
+//# sourceMappingURL=detector.js.map

package/dist/core/detector.js.map

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

package/dist/core/monitor.d.ts

@@ -0,0 +1,31 @@
+import { PublicKey } from '@solana/web3.js';
+import type { AccountType, ScanOptions, TrackedAccount } from './types.js';
+/**
+ * Monitor for tracking sponsored accounts
+ */
+export declare class AccountMonitor {
+    /**
+     * Scan all token accounts owned by the operator and add them to tracking
+     */
+    scanOperatorAccounts(): Promise<TrackedAccount[]>;
+    /**
+     * Scan accounts from transaction signatures (for Kora-sponsored accounts)
+     * This would parse transaction logs to find sponsored account creations
+     */
+    scanFromSignatures(signatures: string[], options?: ScanOptions): Promise<TrackedAccount[]>;
+    /**
+     * Add a single account to tracking
+     */
+    trackAccount(pubkey: PublicKey, sponsorTx?: string): Promise<TrackedAccount | null>;
+    /**
+     * Get tracking statistics
+     */
+    getStats(): Promise<{
+        totalTracked: number;
+        byType: Record<AccountType, number>;
+        byStatus: Record<string, number>;
+        totalRentLocked: number;
+    }>;
+}
+export declare const monitor: AccountMonitor;
+//# sourceMappingURL=monitor.d.ts.map

package/dist/core/monitor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"monitor.d.ts","sourceRoot":"","sources":["../../src/core/monitor.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAA;AAc3C,OAAO,KAAK,EAAE,WAAW,EAAE,WAAW,EAAE,cAAc,EAAE,MAAM,YAAY,CAAA;AAE1E;;GAEG;AACH,qBAAa,cAAc;IACzB;;OAEG;IACG,oBAAoB,IAAI,OAAO,CAAC,cAAc,EAAE,CAAC;IA0CvD;;;OAGG;IACG,kBAAkB,CACtB,UAAU,EAAE,MAAM,EAAE,EACpB,OAAO,GAAE,WAAgB,GACxB,OAAO,CAAC,cAAc,EAAE,CAAC;IA8E5B;;OAEG;IACG,YAAY,CAChB,MAAM,EAAE,SAAS,EACjB,SAAS,CAAC,EAAE,MAAM,GACjB,OAAO,CAAC,cAAc,GAAG,IAAI,CAAC;IAqCjC;;OAEG;IACG,QAAQ,IAAI,OAAO,CAAC;QACxB,YAAY,EAAE,MAAM,CAAA;QACpB,MAAM,EAAE,MAAM,CAAC,WAAW,EAAE,MAAM,CAAC,CAAA;QACnC,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;QAChC,eAAe,EAAE,MAAM,CAAA;KACxB,CAAC;CAmCH;AAGD,eAAO,MAAM,OAAO,gBAAuB,CAAA"}