@solard/cli 0.2.19 → 0.2.20

package/src/pump-watch-command.ts

@@ -0,0 +1,11 @@
+import { runLaunchWatchCommand } from "./launch-watch-command.ts";
+
+type Flags = Map<string, string>;
+type Emit = (value: string) => void;
+
+export async function runPumpWatchCommand(args: {
+  flags: Flags;
+  emit: Emit;
+}): Promise<void> {
+  await runLaunchWatchCommand({ ...args, forcedVenues: ["pump"] });
+}

package/src/reclaim-command.ts

@@ -0,0 +1,335 @@
+import bs58 from "bs58";
+import { PublicKey, TransactionInstruction } from "@solana/web3.js";
+import { findExternalContact, type Solard } from "@solard/core";
+
+type Flags = Map<string, string>;
+type Emit = (value: string) => void;
+type LoaderKind = "buffer" | "program";
+
+type LoaderRow = {
+  kind: LoaderKind;
+  walletName: string;
+  authority: string;
+  address: string;
+  closeAddress: string;
+  programDataAddress: string | null;
+  lamports: bigint;
+};
+
+const LOADER = new PublicKey("BPFLoaderUpgradeab1e11111111111111111111111");
+const CLOSE_DISCRIMINANT = 5;
+const STATE_BUFFER = bs58.encode(Buffer.from([1, 0, 0, 0]));
+const STATE_PROGRAM = bs58.encode(Buffer.from([2, 0, 0, 0]));
+const STATE_PROGRAM_DATA = bs58.encode(Buffer.from([3, 0, 0, 0]));
+
+function csv(value: string | undefined): string[] {
+  return (value ?? "")
+    .split(",")
+    .map((item) => item.trim())
+    .filter(Boolean);
+}
+
+function json(value: unknown): string {
+  return JSON.stringify(
+    value,
+    (_, item) => (typeof item === "bigint" ? item.toString() : item),
+    2,
+  );
+}
+
+function short(value: string): string {
+  return value.length <= 16 ? value : `${value.slice(0, 7)}…${value.slice(-6)}`;
+}
+
+function sol(lamports: bigint): string {
+  const whole = lamports / 1_000_000_000n;
+  const fraction = (lamports % 1_000_000_000n)
+    .toString()
+    .padStart(9, "0")
+    .replace(/0+$/, "");
+  return `${whole}${fraction ? `.${fraction}` : ""}`;
+}
+
+function selectedWallets(slrd: Solard, flags: Flags) {
+  const all = flags.has("all-wallets");
+  const wallet = flags.get("wallet");
+  const wallets = csv(flags.get("wallets"));
+  const group = flags.get("group");
+  const selectors = [
+    all,
+    Boolean(wallet),
+    wallets.length > 0,
+    Boolean(group),
+  ].filter(Boolean).length;
+  if (selectors !== 1) {
+    throw new Error(
+      "Select exactly one of --all-wallets, --wallet <wallet>, --wallets <a,b>, or --group <group>.",
+    );
+  }
+  const allRows = slrd.wallets.list();
+  let addresses: Set<string>;
+  if (all) {
+    addresses = new Set(allRows.map((row) => row.address));
+  } else if (wallet) {
+    addresses = new Set([slrd.resolveWallet(wallet).address.toBase58()]);
+  } else if (wallets.length) {
+    addresses = new Set(
+      wallets.map((ref) => slrd.resolveWallet(ref).address.toBase58()),
+    );
+  } else {
+    addresses = new Set(
+      slrd
+        .groupWallets(group!)
+        .map((ref) => slrd.resolveWallet(ref).address.toBase58()),
+    );
+  }
+  return allRows.filter((row) => addresses.has(row.address));
+}
+
+async function scanAuthority(
+  slrd: Solard,
+  wallet: { name: string; address: string },
+): Promise<LoaderRow[]> {
+  const connection = slrd.connection();
+  const buffers = await connection.getProgramAccounts(LOADER, {
+    commitment: "confirmed",
+    filters: [
+      { memcmp: { offset: 0, bytes: STATE_BUFFER } },
+      { memcmp: { offset: 5, bytes: wallet.address } },
+    ],
+    dataSlice: { offset: 0, length: 37 },
+  });
+  const programData = await connection.getProgramAccounts(LOADER, {
+    commitment: "confirmed",
+    filters: [
+      { memcmp: { offset: 0, bytes: STATE_PROGRAM_DATA } },
+      { memcmp: { offset: 13, bytes: wallet.address } },
+    ],
+    dataSlice: { offset: 0, length: 45 },
+  });
+
+  const rows: LoaderRow[] = buffers.map((entry) => ({
+    kind: "buffer",
+    walletName: wallet.name,
+    authority: wallet.address,
+    address: entry.pubkey.toBase58(),
+    closeAddress: entry.pubkey.toBase58(),
+    programDataAddress: null,
+    lamports: BigInt(entry.account.lamports),
+  }));
+
+  for (const entry of programData) {
+    const programDataAddress = entry.pubkey.toBase58();
+    const programs = await connection.getProgramAccounts(LOADER, {
+      commitment: "confirmed",
+      filters: [
+        { memcmp: { offset: 0, bytes: STATE_PROGRAM } },
+        { memcmp: { offset: 4, bytes: programDataAddress } },
+      ],
+      dataSlice: { offset: 0, length: 36 },
+    });
+    for (const program of programs) {
+      rows.push({
+        kind: "program",
+        walletName: wallet.name,
+        authority: wallet.address,
+        address: program.pubkey.toBase58(),
+        closeAddress: programDataAddress,
+        programDataAddress,
+        lamports: BigInt(entry.account.lamports),
+      });
+    }
+  }
+  return rows;
+}
+
+function resolveDestination(
+  slrd: Solard,
+  value: string | undefined,
+): string | null {
+  if (!value || value === "true") return null;
+  try {
+    return slrd.resolveWallet(value).address.toBase58();
+  } catch {}
+  const contact = findExternalContact(value);
+  if (contact) return contact.address;
+  return new PublicKey(value).toBase58();
+}
+
+function closeInstruction(
+  row: LoaderRow,
+  destination: PublicKey,
+): TransactionInstruction {
+  const data = Buffer.alloc(4);
+  data.writeUInt32LE(CLOSE_DISCRIMINANT, 0);
+  const keys = [
+    {
+      pubkey: new PublicKey(row.closeAddress),
+      isSigner: false,
+      isWritable: true,
+    },
+    { pubkey: destination, isSigner: false, isWritable: true },
+    { pubkey: new PublicKey(row.authority), isSigner: true, isWritable: false },
+  ];
+  if (row.kind === "program") {
+    keys.push({
+      pubkey: new PublicKey(row.address),
+      isSigner: false,
+      isWritable: true,
+    });
+  }
+  return new TransactionInstruction({ programId: LOADER, keys, data });
+}
+
+async function verifyClosed(slrd: Solard, address: string): Promise<boolean> {
+  for (let attempt = 0; attempt < 6; attempt += 1) {
+    const account = await slrd
+      .connection()
+      .getAccountInfo(new PublicKey(address), "confirmed");
+    if (!account || account.lamports === 0) return true;
+    if (attempt < 5) await new Promise((resolve) => setTimeout(resolve, 500));
+  }
+  return false;
+}
+
+export async function runReclaimCommand(args: {
+  slrd: Solard;
+  values: string[];
+  flags: Flags;
+  emit: Emit;
+}): Promise<void> {
+  const action = (args.values[0] ?? "inspect").toLowerCase();
+  if (!["inspect", "buffers", "programs", "all"].includes(action)) {
+    throw new Error(
+      "Usage: slrd reclaim <inspect|buffers|programs|all> --all-wallets [--simulate | --live]",
+    );
+  }
+  if (args.flags.has("simulate") && args.flags.has("live"))
+    throw new Error("Use either --simulate or --live, not both.");
+
+  const wallets = selectedWallets(args.slrd, args.flags);
+  const rows: LoaderRow[] = [];
+  const scanErrors: Array<{ wallet: string; address: string; error: string }> =
+    [];
+  for (const wallet of wallets) {
+    try {
+      rows.push(...(await scanAuthority(args.slrd, wallet)));
+    } catch (error) {
+      scanErrors.push({
+        wallet: wallet.name,
+        address: wallet.address,
+        error: error instanceof Error ? error.message : String(error),
+      });
+    }
+  }
+
+  const selected = rows.filter((row) =>
+    action === "inspect" || action === "all"
+      ? true
+      : action === "buffers"
+        ? row.kind === "buffer"
+        : row.kind === "program",
+  );
+  selected.sort(
+    (a, b) =>
+      a.walletName.localeCompare(b.walletName) || a.kind.localeCompare(b.kind),
+  );
+  const total = selected.reduce((sum, row) => sum + row.lamports, 0n);
+
+  if (
+    args.flags.has("json") &&
+    !args.flags.has("live") &&
+    !args.flags.has("simulate")
+  ) {
+    args.emit(
+      `${json({ wallets: wallets.length, rows: selected, scanErrors, totalLamports: total })}\n`,
+    );
+    return;
+  }
+
+  args.emit(
+    `RECLAIM  wallets=${wallets.length} buffers=${selected.filter((row) => row.kind === "buffer").length} ` +
+      `programs=${selected.filter((row) => row.kind === "program").length} total≈${sol(total)} SOL\n`,
+  );
+  for (const row of selected) {
+    args.emit(
+      `${row.kind === "buffer" ? "BUFFER " : "PROGRAM"}  @${row.walletName}  ${short(row.address)}  ${sol(row.lamports)} SOL\n`,
+    );
+  }
+  for (const error of scanErrors) {
+    args.emit(`SCANERR  @${error.wallet} ${error.address}  ${error.error}\n`);
+  }
+
+  if (
+    action === "inspect" ||
+    (!args.flags.has("simulate") && !args.flags.has("live"))
+  ) {
+    args.emit("No accounts closed. Use --simulate, then --live.\n");
+    return;
+  }
+  if (scanErrors.length) {
+    throw new Error(
+      `Loader scan was incomplete for ${scanErrors.length} wallet(s); refusing reclaim execution.`,
+    );
+  }
+  if (
+    args.flags.has("live") &&
+    selected.some((row) => row.kind === "program") &&
+    !args.flags.has("confirm-program-close")
+  ) {
+    throw new Error(
+      "Program closure is irreversible. Re-run with --confirm-program-close together with --live.",
+    );
+  }
+
+  const explicitDestination = resolveDestination(
+    args.slrd,
+    args.flags.get("destination"),
+  );
+  const via = (args.flags.get("sender") ?? "rpc") as any;
+  let ok = 0;
+  let failed = 0;
+  for (let index = 0; index < selected.length; index += 1) {
+    const row = selected[index]!;
+    const destination = new PublicKey(explicitDestination ?? row.authority);
+    const ix = closeInstruction(row, destination);
+    try {
+      const composer = args.slrd.tx(row.walletName).add(ix, {
+        kind: `close-loader-${row.kind}`,
+        recipient: destination,
+        meta: { address: row.address, closeAddress: row.closeAddress },
+      });
+      if (args.flags.has("simulate")) {
+        const plan = await composer.build();
+        const simulation = await args.slrd.simulatePlan(plan);
+        if (!simulation.success) throw new Error("simulation failed");
+        args.emit(
+          `SIM  ${index + 1}/${selected.length}  ${row.kind} ${row.address}\n`,
+        );
+      } else {
+        const receipt = await composer.send({
+          via,
+          kind: `reclaim:${row.kind}`,
+        });
+        if (!(await verifyClosed(args.slrd, row.closeAddress))) {
+          throw new Error(
+            `close transaction ${receipt.signature} landed but ${row.closeAddress} still exists`,
+          );
+        }
+        args.emit(
+          `OK   ${index + 1}/${selected.length}  ${row.kind} ${row.address}  reclaimed≈${sol(row.lamports)} SOL\n`,
+        );
+      }
+      ok += 1;
+    } catch (error) {
+      failed += 1;
+      args.emit(
+        `FAIL ${index + 1}/${selected.length}  ${row.kind} ${row.address}  ${error instanceof Error ? error.message : String(error)}\n`,
+      );
+    }
+  }
+  args.emit(
+    `DONE  ok=${ok} failed=${failed} planned≈${sol(total)} SOL mode=${args.flags.has("simulate") ? "simulate" : "live"}\n`,
+  );
+  if (failed) process.exitCode = 1;
+}

package/src/research-history-cache.ts

@@ -0,0 +1,331 @@
+import { mkdirSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, resolve } from "node:path";
+import { Database } from "bun:sqlite";
+import { PublicKey, type ParsedTransactionWithMeta } from "@solana/web3.js";
+
+export type ResearchHistorySignature = {
+  mint: string;
+  signature: string;
+  slot: number;
+  blockTime: number | null;
+  scanKind: "curve" | "pool";
+  scanAddress: string;
+  localChronologicalOrder: number;
+};
+
+export type ResearchHistoryMeta = {
+  version: 1;
+  mint: string;
+  decimals: number;
+  supplyUi: number;
+  quoteMint: string | null;
+  bondingCurve: string | null;
+  pool: string | null;
+  fromCreation: boolean;
+  indexedSignatures: number;
+  indexedAtMs: number;
+};
+
+type Encoded =
+  null | boolean | number | string | Encoded[] | { [key: string]: Encoded };
+
+function cachePath(): string {
+  return resolve(
+    process.env.SLRD_RESEARCH_DB_PATH?.trim() ||
+      process.env.SOLARD_RESEARCH_DB_PATH?.trim() ||
+      resolve(homedir(), ".solard", "research.sqlite"),
+  );
+}
+
+function open(): Database {
+  const path = cachePath();
+  mkdirSync(dirname(path), { recursive: true });
+  const db = new Database(path, { create: true });
+  db.exec("PRAGMA journal_mode=WAL");
+  db.exec("PRAGMA synchronous=NORMAL");
+  db.exec(`
+    CREATE TABLE IF NOT EXISTS token_history_signatures (
+      mint TEXT NOT NULL,
+      signature TEXT NOT NULL,
+      slot INTEGER NOT NULL,
+      block_time INTEGER,
+      scan_kind TEXT NOT NULL,
+      scan_address TEXT NOT NULL,
+      local_order INTEGER NOT NULL,
+      PRIMARY KEY (mint, signature)
+    );
+    CREATE INDEX IF NOT EXISTS token_history_signatures_time
+      ON token_history_signatures (mint, block_time, slot, local_order);
+    CREATE TABLE IF NOT EXISTS token_history_meta (
+      mint TEXT PRIMARY KEY,
+      json TEXT NOT NULL,
+      updated_at_ms INTEGER NOT NULL
+    );
+    CREATE TABLE IF NOT EXISTS raw_transactions (
+      signature TEXT PRIMARY KEY,
+      slot INTEGER NOT NULL,
+      block_time_ms INTEGER,
+      confidence TEXT NOT NULL,
+      transaction_json TEXT NOT NULL,
+      fetched_at_ms INTEGER NOT NULL
+    );
+  `);
+  return db;
+}
+
+function encode(value: unknown): Encoded {
+  if (
+    value == null ||
+    typeof value === "boolean" ||
+    typeof value === "number" ||
+    typeof value === "string"
+  )
+    return value;
+  if (typeof value === "bigint")
+    return { $bigint: value.toString() } as Encoded;
+  if (Buffer.isBuffer(value) || value instanceof Uint8Array)
+    return { $bytes: Buffer.from(value).toString("base64") } as Encoded;
+  if (value instanceof PublicKey)
+    return { $publicKey: value.toBase58() } as Encoded;
+  if (Array.isArray(value)) return value.map(encode);
+  if (typeof value === "object") {
+    const toBase58 = (value as { toBase58?: unknown }).toBase58;
+    if (typeof toBase58 === "function")
+      return {
+        $publicKey: (value as { toBase58(): string }).toBase58(),
+      } as Encoded;
+    const out: Record<string, Encoded> = {};
+    for (const [key, item] of Object.entries(value as Record<string, unknown>))
+      out[key] = encode(item);
+    return out;
+  }
+  throw new Error(`Unsupported research cache value: ${typeof value}`);
+}
+
+function decode(value: Encoded): unknown {
+  if (value == null || typeof value !== "object") return value;
+  if (Array.isArray(value)) return value.map(decode);
+  if ("$publicKey" in value) return new PublicKey(String(value.$publicKey));
+  if ("$bytes" in value) return Buffer.from(String(value.$bytes), "base64");
+  if ("$bigint" in value) return BigInt(String(value.$bigint));
+  const out: Record<string, unknown> = {};
+  for (const [key, item] of Object.entries(value))
+    out[key] = decode(item as Encoded);
+  return out;
+}
+
+export function researchHistoryCachePath(): string {
+  return cachePath();
+}
+
+export function replaceResearchHistoryIndex(args: {
+  mint: string;
+  rows: ResearchHistorySignature[];
+  meta: ResearchHistoryMeta;
+}): void {
+  const db = open();
+  try {
+    const remove = db.prepare(
+      "DELETE FROM token_history_signatures WHERE mint = ?",
+    );
+    const insert = db.prepare(`
+      INSERT OR REPLACE INTO token_history_signatures
+      (mint, signature, slot, block_time, scan_kind, scan_address, local_order)
+      VALUES (?, ?, ?, ?, ?, ?, ?)
+    `);
+    const writeMeta = db.prepare(`
+      INSERT INTO token_history_meta (mint, json, updated_at_ms)
+      VALUES (?, ?, ?)
+      ON CONFLICT(mint) DO UPDATE SET json=excluded.json, updated_at_ms=excluded.updated_at_ms
+    `);
+    const tx = db.transaction(() => {
+      remove.run(args.mint);
+      for (const row of args.rows) {
+        insert.run(
+          args.mint,
+          row.signature,
+          row.slot,
+          row.blockTime,
+          row.scanKind,
+          row.scanAddress,
+          row.localChronologicalOrder,
+        );
+      }
+      writeMeta.run(args.mint, JSON.stringify(args.meta), Date.now());
+    });
+    tx();
+  } finally {
+    db.close();
+  }
+}
+
+export function researchHistoryMeta(mint: string): ResearchHistoryMeta | null {
+  const db = open();
+  try {
+    const row = db
+      .prepare("SELECT json FROM token_history_meta WHERE mint = ?")
+      .get(mint) as { json?: string } | null;
+    return row?.json ? (JSON.parse(row.json) as ResearchHistoryMeta) : null;
+  } finally {
+    db.close();
+  }
+}
+
+export function loadResearchHistoryIndex(
+  mint: string,
+  options: { fromMs?: number; toMs?: number } = {},
+): ResearchHistorySignature[] {
+  const db = open();
+  try {
+    const rows = db
+      .prepare(
+        `
+        SELECT mint, signature, slot, block_time, scan_kind, scan_address, local_order
+        FROM token_history_signatures
+        WHERE mint = ?
+        ORDER BY COALESCE(block_time, 0), slot, local_order, signature
+      `,
+      )
+      .all(mint) as Array<{
+      mint: string;
+      signature: string;
+      slot: number;
+      block_time: number | null;
+      scan_kind: "curve" | "pool";
+      scan_address: string;
+      local_order: number;
+    }>;
+    return rows
+      .map((row) => ({
+        mint: row.mint,
+        signature: row.signature,
+        slot: Number(row.slot),
+        blockTime: row.block_time == null ? null : Number(row.block_time),
+        scanKind: row.scan_kind,
+        scanAddress: row.scan_address,
+        localChronologicalOrder: Number(row.local_order),
+      }))
+      .filter(
+        (row) =>
+          options.fromMs == null ||
+          row.blockTime == null ||
+          row.blockTime * 1_000 >= options.fromMs,
+      )
+      .filter(
+        (row) =>
+          options.toMs == null ||
+          row.blockTime == null ||
+          row.blockTime * 1_000 <= options.toMs,
+      );
+  } finally {
+    db.close();
+  }
+}
+
+export function sampleResearchHistoryIndex(
+  rows: readonly ResearchHistorySignature[],
+  sampleMs: number,
+): ResearchHistorySignature[] {
+  if (!(sampleMs > 0)) return [...rows];
+  const selected = new Map<string, ResearchHistorySignature>();
+  const buckets = new Map<number, ResearchHistorySignature>();
+  const add = (row: ResearchHistorySignature | undefined) => {
+    if (row) selected.set(row.signature, row);
+  };
+  add(rows[0]);
+  add(rows.at(-1));
+  add(rows.find((row) => row.scanKind === "curve"));
+  add(rows.find((row) => row.scanKind === "pool"));
+  for (const row of rows) {
+    if (row.blockTime == null) continue;
+    const bucket = Math.floor((row.blockTime * 1_000) / sampleMs);
+    const previous = buckets.get(bucket);
+    if (
+      !previous ||
+      row.slot > previous.slot ||
+      (row.slot === previous.slot &&
+        row.localChronologicalOrder > previous.localChronologicalOrder)
+    )
+      buckets.set(bucket, row);
+  }
+  for (const row of buckets.values()) add(row);
+  return [...selected.values()].sort(
+    (a, b) =>
+      (a.blockTime ?? 0) - (b.blockTime ?? 0) ||
+      a.slot - b.slot ||
+      a.localChronologicalOrder - b.localChronologicalOrder ||
+      a.signature.localeCompare(b.signature),
+  );
+}
+
+export function cachedResearchTransactions(
+  signatures: readonly string[],
+): Map<string, ParsedTransactionWithMeta> {
+  const out = new Map<string, ParsedTransactionWithMeta>();
+  if (!signatures.length) return out;
+  const db = open();
+  try {
+    const get = db.prepare(
+      "SELECT transaction_json FROM raw_transactions WHERE signature = ?",
+    );
+    for (const signature of signatures) {
+      const row = get.get(signature) as { transaction_json?: string } | null;
+      if (!row?.transaction_json) continue;
+      out.set(
+        signature,
+        decode(
+          JSON.parse(row.transaction_json) as Encoded,
+        ) as ParsedTransactionWithMeta,
+      );
+    }
+    return out;
+  } finally {
+    db.close();
+  }
+}
+
+export function cacheResearchTransactions(
+  rows: ReadonlyMap<string, ParsedTransactionWithMeta>,
+  confidence: "confirmed" | "finalized",
+): void {
+  if (!rows.size) return;
+  const db = open();
+  try {
+    const insert = db.prepare(`
+      INSERT INTO raw_transactions
+      (signature, slot, block_time_ms, confidence, transaction_json, fetched_at_ms)
+      VALUES (?, ?, ?, ?, ?, ?)
+      ON CONFLICT(signature) DO UPDATE SET
+        slot=excluded.slot,
+        block_time_ms=excluded.block_time_ms,
+        confidence=excluded.confidence,
+        transaction_json=excluded.transaction_json,
+        fetched_at_ms=excluded.fetched_at_ms
+    `);
+    const now = Date.now();
+    const tx = db.transaction(() => {
+      for (const [signature, transaction] of rows) {
+        insert.run(
+          signature,
+          transaction.slot,
+          transaction.blockTime == null ? null : transaction.blockTime * 1_000,
+          confidence,
+          JSON.stringify(encode(transaction)),
+          now,
+        );
+      }
+    });
+    tx();
+  } finally {
+    db.close();
+  }
+}
+
+export function countCachedResearchTransactions(
+  signatures: readonly string[],
+): number {
+  if (!signatures.length) return 0;
+  const cached = cachedResearchTransactions(signatures);
+  return cached.size;
+}