@solard/cli 0.2.37 → 0.2.40

package/src/liquidation-wallets.test.ts

@@ -0,0 +1,27 @@
+import { expect, test } from "bun:test";
+import { retryLiquidationRead, runLiquidationWallets } from "./liquidation-wallets.ts";
+
+test("read quota failures back off, keep completed wallets, never replay execution", async () => {
+  const starts: string[] = [], executions: string[] = [], waits: number[] = [];
+  let reads = 0;
+  const failures = await runLiquidationWallets(["a", "a", "b", "c"], async wallet => {
+    await retryLiquidationRead(async () => {
+      if (wallet === "b" && reads++ < 2) throw Error("RPC_PROVIDER_UNAVAILABLE");
+    }, () => {}, async ms => { waits.push(ms); });
+    executions.push(wallet);
+    if (wallet === "b") throw Error("Submission outcome uncertain");
+  }, wallet => starts.push(wallet), () => {});
+  expect(starts).toEqual(["a", "b", "c"]);
+  expect(executions).toEqual(["a", "b", "c"]);
+  expect(failures).toEqual(["b"]);
+  expect(waits).toEqual([5000, 10000]);
+});
+
+test("invalid metadata is not retried; provider failures are bounded", async () => {
+  let calls = 0;
+  await expect(retryLiquidationRead(async () => { calls++; throw Error("Unknown wallet"); }, () => {}, async () => {})).rejects.toThrow("Unknown wallet");
+  expect(calls).toBe(1);
+  calls = 0;
+  await expect(retryLiquidationRead(async () => { calls++; throw Error("HTTP 429"); }, () => {}, async () => {})).rejects.toThrow("429");
+  expect(calls).toBe(7);
+});

package/src/liquidation-wallets.ts

@@ -0,0 +1,33 @@
+/** Retry reads only. An execution callback is never repeated by this runner. */
+export async function retryLiquidationRead<T>(
+  read: () => Promise<T>,
+  onRetry: (attempt: number, delayMs: number) => void,
+  sleep: (ms: number) => Promise<unknown> = ms => Bun.sleep(ms),
+): Promise<T> {
+  for (let attempt = 0; ; attempt++) {
+    try { return await read(); }
+    catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      if (attempt >= 6 || !/RPC_PROVIDER_UNAVAILABLE|RPC_QUEUE_TIMEOUT|RPC_TIMEOUT|429|rate.limit|fetch failed|ECONNRESET|timed? ?out/i.test(message)) throw error;
+      const delayMs = Math.min(60_000, 5_000 * 2 ** attempt);
+      onRetry(attempt + 1, delayMs);
+      await sleep(delayMs);
+    }
+  }
+}
+
+export async function runLiquidationWallets(
+  wallets: string[],
+  run: (wallet: string) => Promise<unknown>,
+  onStart: (wallet: string, index: number, total: number) => void,
+  onFailure: (wallet: string, error: unknown) => void,
+): Promise<string[]> {
+  const failures: string[] = [];
+  const unique = [...new Set(wallets)];
+  for (const [index, wallet] of unique.entries()) {
+    onStart(wallet, index + 1, unique.length);
+    try { await run(wallet); }
+    catch (error) { failures.push(wallet); onFailure(wallet, error); }
+  }
+  return failures;
+}

package/src/pump/token-launch-cli.ts

@@ -41,7 +41,7 @@ import {
   type SendReceipt,
   type SimulationResult,
   type Solard,
-  type TokenMetadata,
+  type PumpLaunchTokenMetadata as TokenMetadata,
   type TraderSubmitMode,
   type VanityMintPoolReservation,
 } from "@solard/core";

package/src/rpc-management.test.ts

@@ -0,0 +1,108 @@
+import { fileURLToPath } from "url";
+import { afterAll, afterEach, expect, spyOn, test } from "bun:test";
+const mockFetch = (implementation: (...args: Parameters<typeof fetch>) => ReturnType<typeof fetch>) =>
+  spyOn(globalThis, "fetch").mockImplementation(implementation as typeof fetch);
+import * as fs from "fs";
+import { mkdtempSync, readFileSync } from "fs";
+const rmSync = Reflect.get(fs, "rmSync") as (path: string, options: {force?: boolean; recursive?: boolean}) => void;
+import { tmpdir } from "os";
+import { join } from "path";
+import { activateRpc, effectiveRpc, loadRpcConfig, saveRpcConfig, probeHttp, safeUrl } from "./rpc-management.ts";
+const dir = mkdtempSync(join(tmpdir(), "slrd-rpc-r8-"));
+const keys = ["SLRD_RPC_CONFIG_PATH", "RPC_ENDPOINT", "SLRD_RPC_URLS", "SLRD_WS_URLS", "SLRD_RPC_PROVIDER_LIMITS", "SLRD_RPC_AGGREGATE_RPS", "SLRD_RPC_VERIFY_MAINNET"] as const;
+const before = Object.fromEntries(keys.map(key => [key, process.env[key]]));
+process.env.SLRD_RPC_CONFIG_PATH = join(dir, "rpc.json");
+afterEach(() => { rmSync(process.env.SLRD_RPC_CONFIG_PATH!, { force: true }); for (const key of keys) {
+  const value = before[key]; if (value === undefined) delete process.env[key]; else process.env[key] = value;
+} process.env.SLRD_RPC_CONFIG_PATH = join(dir, "rpc.json"); });
+afterAll(() => { rmSync(dir, { recursive: true, force: true }); for (const key of keys) {
+  const value = before[key]; if (value === undefined) delete process.env[key]; else process.env[key] = value;
+} });
+
+test("environment-only configuration appears in effective probes", () => {
+  process.env.RPC_ENDPOINT = "https://env-only.example/?api-key=secret";
+  const state = effectiveRpc();
+  expect(state.http).toHaveLength(1);
+  expect(state.source).toBe("environment");
+  expect(safeUrl(state.http[0]!)).not.toContain("secret");
+});
+test("flags outrank environment but preserve saved read fallbacks", () => {
+  const config = loadRpcConfig();
+  config.http = [{ url: "https://saved.example/", group: "saved", rps: 12, concurrency: 2 }];
+  saveRpcConfig(config);
+  process.env.RPC_ENDPOINT = "https://env.example/";
+  const effective = effectiveRpc(new Map([["rpc-url", "https://explicit.example/"]]));
+  expect(effective.http[0]).toContain("explicit.example");
+  expect(effective.http).toContain("https://saved.example/");
+  activateRpc(new Map([["rpc-url", "https://explicit.example/"]]));
+  expect(JSON.parse(process.env.SLRD_RPC_URLS!)).toEqual(effective.http);
+  const limits = JSON.parse(process.env.SLRD_RPC_PROVIDER_LIMITS!) as Record<string, {rps:number}>;
+  expect(Object.values(limits).some(value => value.rps === 12)).toBe(true);
+  expect(Object.keys(limits).every(key => /^[a-f0-9]{64}$/.test(key))).toBe(true);
+});
+test("credentials never appear in redacted display; stored file keeps supplied URL", () => {
+  const config = loadRpcConfig(); config.http = [{ url: "https://secured.example/?api-key=private", group: "one", rps: 5, concurrency: 1 }];
+  saveRpcConfig(config);
+  expect(readFileSync(process.env.SLRD_RPC_CONFIG_PATH!, "utf8")).toContain("private");
+  expect(safeUrl(config.http[0]!.url)).not.toContain("private");
+});
+test("mainnet readiness rejects quota-exhausted account reads", async () => {
+  const calls: string[] = [];
+  const mock = mockFetch(async (_url, init) => {
+    const method = JSON.parse(String(init?.body)).method;
+    calls.push(method);
+    return new Response(JSON.stringify(method === "getGenesisHash"
+      ? { result: "5eykt4UsFv8P8NJdTREpY1vzqKqZKvdpKuc147dw2N9d" }
+      : { error: { code: -32005, message: "max usage reached" } }));
+  });
+  try { expect((await probeHttp("https://testing.example/?api-key=private")).state).toBe("unavailable");
+    expect(calls).toEqual(["getGenesisHash", "getBalance"]);
+  } finally { mock.mockRestore(); }
+});
+test("mainnet readiness accepts zero balance and null account with valid context", async () => {
+  const mock = mockFetch(async (_url, init) => {
+    const method = JSON.parse(String(init?.body)).method;
+    const result = method === "getGenesisHash" ? "5eykt4UsFv8P8NJdTREpY1vzqKqZKvdpKuc147dw2N9d"
+      : { context: { slot: 44 }, value: method === "getBalance" ? 0 : null };
+    return new Response(JSON.stringify({ result }));
+  });
+  try { expect((await probeHttp("https://healthy.example/")).state).toBe("healthy"); }
+  finally { mock.mockRestore(); }
+});
+
+
+test("CLI add/status/test honor effective endpoints and redact credentials without wallet access", async () => {
+  const calls: string[] = [];
+  const server = Bun.serve({ port: 0, hostname: "127.0.0.1", async fetch(request) {
+    const body = await request.json() as { id: number; method: string };
+    calls.push(body.method);
+    const result = body.method === "getGenesisHash"
+      ? "5eykt4UsFv8P8NJdTREpY1vzqKqZKvdpKuc147dw2N9d"
+      : { context: { slot: 123 }, value: body.method === "getBalance" ? 0 : null };
+    return Response.json({ jsonrpc: "2.0", id: body.id, result });
+  } });
+  const endpoint = `http://127.0.0.1:${server.port}/?api-key=cli-fixture-secret`;
+  const run = async (...args: string[]) => {
+    const child = Bun.spawn([process.execPath, fileURLToPath(new URL("./index.ts", import.meta.url)), ...args], {
+      env: { PATH: process.env.PATH, SystemRoot: process.env.SystemRoot,
+        SLRD_RPC_CONFIG_PATH: join(dir, "rpc-cli.json"),
+        RPC_ENDPOINT: endpoint, SLRD_RPC_URLS: "[]", SLRD_WS_URLS: "[]" },
+      stdout: "pipe", stderr: "pipe",
+    });
+    const [stdout, stderr, code] = await Promise.all([
+      new Response(child.stdout).text(), new Response(child.stderr).text(), child.exited,
+    ]);
+    expect(code).toBe(0);
+    expect(stdout + stderr).not.toContain("cli-fixture-secret");
+    return stdout;
+  };
+  try {
+    await run("rpc", "add", "http", endpoint, "--group", "cli-fixture");
+    const status = JSON.parse(await run("rpc", "status"));
+    expect(status.source).toBe("environment");
+    expect(status.health[0].state).toBe("healthy");
+    expect(status.active).toContain("127.0.0.1");
+    await run("rpc", "test", "--rpc-url", endpoint);
+    expect(calls.filter(method => method === "getAccountInfo")).toHaveLength(2);
+  } finally { server.stop(true); }
+}, 30000); // Three CLI subprocesses exceed Bun's 5s default on a cold Windows start.

package/src/rpc-management.ts

@@ -0,0 +1,109 @@
+import { mkdirSync, readFileSync, renameSync, writeFileSync } from "fs";
+import { homedir } from "os";
+import { dirname, join } from "path";
+import { createHash } from "crypto";
+
+export type RpcEntry = { url: string; group: string; rps: number; concurrency: number };
+export type RpcConfig = { version: 1; auto: boolean; http: RpcEntry[]; websocket: string[]; aggregateRps: number | null };
+export function rpcConfigPath() { return process.env.SLRD_RPC_CONFIG_PATH ?? join(homedir(), ".solard", "rpc.json"); }
+const empty = (): RpcConfig => ({ version: 1, auto: true, http: [], websocket: [], aggregateRps: null });
+export function rpcUrl(raw: string, transport: "http" | "ws"): string {
+  const u = new URL(raw);
+  if (u.username || u.password || u.hash || !((transport === "http" ? ["http:","https:"] : ["ws:","wss:"]).includes(u.protocol)))
+    throw new Error("Invalid RPC URL transport or URL contains userinfo/fragment");
+  return u.toString();
+}
+export function safeUrl(raw: string) { try { const u = new URL(raw); return `${u.protocol}//${u.host}/***`; } catch { return "<invalid URL>"; } }
+export function loadRpcConfig(): RpcConfig {
+  let data: RpcConfig;
+  try { data = JSON.parse(readFileSync(rpcConfigPath(), "utf8")); }
+  catch (e) { if ((e as NodeJS.ErrnoException).code === "ENOENT") return empty(); throw new Error("Cannot read RPC configuration"); }
+  if (data.version !== 1 || !Array.isArray(data.http) || !Array.isArray(data.websocket)) throw new Error("Invalid RPC configuration");
+  for (const entry of data.http) {
+    entry.url = rpcUrl(entry.url, "http");
+    if (!/^[a-zA-Z0-9._:-]{1,100}$/.test(entry.group) || !Number.isSafeInteger(entry.rps) || entry.rps < 1 ||
+      !Number.isSafeInteger(entry.concurrency) || entry.concurrency < 1) throw new Error("Invalid RPC budget");
+  }
+  data.websocket = data.websocket.map(url => rpcUrl(url, "ws"));
+  return data;
+}
+export function saveRpcConfig(config: RpcConfig) {
+  const path = rpcConfigPath(); mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
+  const temp = `${path}.${process.pid}.tmp`;
+  writeFileSync(temp, JSON.stringify(config, null, 2) + "\n", { mode: 0o600, flag: "wx" });
+  renameSync(temp, path);
+}
+export function effectiveRpc(flags: ReadonlyMap<string,string> = new Map()) {
+  const saved = loadRpcConfig();
+  const manual = flags.get("rpc-url") ?? process.env.RPC_ENDPOINT;
+  let envUrls: string[] = [];
+  if (process.env.SLRD_RPC_URLS) {
+    const parsed: unknown = JSON.parse(process.env.SLRD_RPC_URLS);
+    if (!Array.isArray(parsed) || !parsed.every(value => typeof value === "string")) throw new Error("SLRD_RPC_URLS must be an array");
+    envUrls = parsed as string[];
+  }
+  const initial = [...(manual ? [manual] : []), ...envUrls, ...saved.http.map(e => e.url)];
+  const http = [...new Set(initial.map(url => rpcUrl(url, "http")))];
+  const wsEnv: unknown = process.env.SLRD_WS_URLS ? JSON.parse(process.env.SLRD_WS_URLS) : [];
+  if (!Array.isArray(wsEnv) || !wsEnv.every(v => typeof v === "string")) throw new Error("Invalid SLRD_WS_URLS");
+  const websocket = [...new Set([...(wsEnv as string[]), ...saved.websocket].map(url => rpcUrl(url, "ws")))];
+  const enabledHttp = saved.auto ? http : http.slice(0,1);
+  const limits: Record<string, { group: string; rps: number; concurrency: number }> = {};
+  for (const entry of saved.http) {
+    const identity = createHash("sha256").update(entry.url).digest("hex");
+    limits[identity] = { group: entry.group, rps: entry.rps, concurrency: entry.concurrency };
+  }
+  return { saved, http: enabledHttp, websocket, limits, source: flags.has("rpc-url") ? "flag" : manual ? "environment" : envUrls.length ? "SLRD_RPC_URLS" : "file" };
+}
+export function activateRpc(flags: ReadonlyMap<string,string>) {
+  const result = effectiveRpc(flags);
+  if (result.http.length) { process.env.RPC_ENDPOINT = result.http[0]; process.env.SLRD_RPC_URLS = JSON.stringify(result.http); }
+  process.env.SLRD_WS_URLS = JSON.stringify(result.websocket);
+  process.env.SLRD_RPC_PROVIDER_LIMITS = JSON.stringify(result.limits);
+  if (result.saved.aggregateRps !== null) process.env.SLRD_RPC_AGGREGATE_RPS = String(result.saved.aggregateRps);
+  process.env.SLRD_RPC_VERIFY_MAINNET = "1";
+  return result;
+}
+const GENESIS = "5eykt4UsFv8P8NJdTREpY1vzqKqZKvdpKuc147dw2N9d";
+export async function probeHttp(url: string) {
+  const controller = new AbortController(); const timeout = setTimeout(() => controller.abort(), 6500);
+  const start = Date.now();
+  const result = (state: string, reason: string) => ({ endpoint: safeUrl(url), state, reason, latencyMs: Date.now() - start });
+  try {
+    for (const method of ["getGenesisHash", "getBalance", "getAccountInfo"]) {
+      const response = await fetch(url, { method: "POST", signal: controller.signal, headers: { "content-type": "application/json" },
+        body: JSON.stringify({ jsonrpc: "2.0", id: 1, method, params: method === "getGenesisHash" ? [] :
+          method === "getBalance" ? ["11111111111111111111111111111111"] :
+            ["11111111111111111111111111111111", { encoding: "base64" }] }) });
+      if (!response.ok) return result("unavailable", `HTTP ${response.status}`);
+      const body = await response.json() as { error?: { code?: number; message?: string }; result?: any };
+      if (body.error) return result("unavailable", `RPC ${body.error.code ?? "error"}`);
+      if (method === "getGenesisHash" && body.result !== GENESIS) return result("wrong-cluster", "Mainnet genesis mismatch");
+      if (method === "getBalance" && (!Number.isFinite(body.result?.value) || !Number.isFinite(body.result?.context?.slot)))
+        return result("unavailable", "Balance read missing");
+      if (method === "getAccountInfo" && !Number.isFinite(body.result?.context?.slot))
+        return result("unavailable", "Account read missing");
+    }
+    return result("healthy", "Mainnet and account reads verified");
+  } catch { return result("unavailable", "Timeout or transport failure"); }
+  finally { clearTimeout(timeout); }
+}
+export async function probeWs(url: string) {
+  return await new Promise<{ endpoint: string; state: string; reason: string }>(resolve => {
+    let socket: WebSocket | undefined, finished = false;
+    function done(state: string, reason: string) {
+      if (finished) return; finished = true; clearTimeout(timer);
+      try { socket?.close(); } catch {} resolve({ endpoint: safeUrl(url), state, reason });
+    }
+    const timer = setTimeout(() => done("unavailable", "Subscription timeout"), 6500);
+    try {
+      socket = new WebSocket(url);
+      socket.addEventListener("open", () => socket?.send(JSON.stringify({ jsonrpc: "2.0", id: 71, method: "slotSubscribe" })));
+      socket.addEventListener("message", event => { try { const data = JSON.parse(String(event.data));
+        if (data.id === 71) done(Number.isInteger(data.result) ? "healthy" : "unavailable", "Subscription ACK (not delivery guarantee)");
+      } catch { done("unavailable", "Invalid WebSocket reply"); } });
+      socket.addEventListener("error", () => done("unavailable", "WebSocket failure"));
+      socket.addEventListener("close", () => done("unavailable", "Disconnected"));
+    } catch { done("unavailable", "WebSocket construction failed"); }
+  });
+}

package/src/wallet-group-filter.test.ts

@@ -0,0 +1,10 @@
+import {expect,test}from"bun:test";
+import {excludeWalletGroups}from"./wallet-group-filter.ts";
+test("group exclusion handles overlapping memberships and virtual ungrouped without hiding unknown groups",()=>{
+ const wallets=[{address:"a"},{address:"b"},{address:"c"}];const memberships=[{groupName:"oct23-empty",walletAddress:"a"},{groupName:"default",walletAddress:"a"},{groupName:"keep",walletAddress:"b"}];const known=new Set(["oct23-empty","default","keep","empty"]);
+ expect(excludeWalletGroups(wallets,["oct23-empty"],memberships,known)).toEqual([{address:"b"},{address:"c"}]);
+ expect(excludeWalletGroups(wallets,["ungrouped"],memberships,known)).toEqual([{address:"a"},{address:"b"}]);
+ expect(excludeWalletGroups(wallets,["oct23-empty","keep"],memberships,known)).toEqual([{address:"c"}]);
+ expect(excludeWalletGroups(wallets,["empty"],memberships,known)).toEqual(wallets);
+ expect(()=>excludeWalletGroups(wallets,["typo"],memberships,known)).toThrow("Unknown excluded");
+});

package/src/wallet-group-filter.ts

@@ -0,0 +1,12 @@
+export function excludeWalletGroups<T extends { address: string }>(
+ wallets:T[], names:string[], memberships:ReadonlyArray<{groupName:string;walletAddress:string}>, knownGroups:ReadonlySet<string>,
+):T[] {
+ const grouped=new Set(memberships.filter(row=>row.groupName.toLowerCase()!=="ungrouped").map(row=>row.walletAddress));
+ const excluded=new Set<string>();
+ for(const name of names){
+  if(name.toLowerCase()==="ungrouped"){for(const wallet of wallets)if(!grouped.has(wallet.address))excluded.add(wallet.address);continue;}
+  if(!knownGroups.has(name))throw Error(`Unknown excluded wallet group: ${name}`);
+  for(const row of memberships)if(row.groupName===name)excluded.add(row.walletAddress);
+ }
+ return wallets.filter(wallet=>!excluded.has(wallet.address));
+}