@solard/cli 0.2.14 → 0.2.16

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@solard/cli",
-  "version": "0.2.14",
+  "version": "0.2.16",
   "description": "Command-line interface for the Solard SDK.",
   "type": "module",
   "main": "./src/index.ts",
@@ -18,7 +18,7 @@
     "bun": ">=1.1.0"
   },
   "dependencies": {
-    "@solard/sdk": "0.2.14",
+    "@solard/sdk": "0.2.16",
     "bs58": "^6.0.0",
     "@solana/web3.js": "^1.98.4"
   },

package/src/fairfun-commands.ts

@@ -1,6 +1,6 @@
 import { readFileSync } from "node:fs";
 import { PublicKey } from "@solana/web3.js";
-import type { Solard } from "@solard/sdk";
+import type { HolderRewardEntitlementSnapshotInput, Solard } from "@solard/sdk";
 
 export type FairfunCliFlags = Map<string, string>;
 type Emit = (value: string) => void;
@@ -110,6 +110,63 @@ function allocationsFile(
   });
 }
 
+function rewardSnapshotFile(
+  path: string,
+): HolderRewardEntitlementSnapshotInput {
+  const parsed = JSON.parse(readFileSync(path, "utf8")) as any;
+  if (!parsed || typeof parsed !== "object")
+    throw new Error("Reward snapshot must be a JSON object");
+  const id = String(parsed.id ?? parsed.snapshotId ?? "").trim();
+  if (!id) throw new Error("Reward snapshot requires id");
+  const totalClaimedRaw = String(parsed.totalClaimedRaw ?? "").trim();
+  if (!/^\d+$/.test(totalClaimedRaw))
+    throw new Error("Reward snapshot totalClaimedRaw must be a raw integer");
+  if (!Array.isArray(parsed.recipients))
+    throw new Error("Reward snapshot requires recipients: [...]");
+  const recipients = parsed.recipients.map((row: any, index: number) => {
+    if (!row || typeof row !== "object")
+      throw new Error(
+        `Reward snapshot recipient ${index + 1} must be an object`,
+      );
+    const wallet = String(row.wallet ?? "").trim();
+    const entitledRaw = String(row.entitledRaw ?? "").trim();
+    if (!wallet)
+      throw new Error(`Reward snapshot recipient ${index + 1} requires wallet`);
+    if (!/^\d+$/.test(entitledRaw))
+      throw new Error(
+        `Reward snapshot recipient ${index + 1} entitledRaw must be a raw integer`,
+      );
+    return {
+      wallet: new PublicKey(wallet).toBase58(),
+      entitledRaw,
+    };
+  });
+  const slot = parsed.slot == null ? null : Number(parsed.slot);
+  if (slot != null && (!Number.isInteger(slot) || slot < 0))
+    throw new Error("Reward snapshot slot must be a non-negative integer");
+  const observedAtMs =
+    parsed.observedAtMs == null ? null : Number(parsed.observedAtMs);
+  if (
+    observedAtMs != null &&
+    (!Number.isFinite(observedAtMs) || observedAtMs < 0)
+  )
+    throw new Error(
+      "Reward snapshot observedAtMs must be a non-negative number",
+    );
+  const claimSignature =
+    parsed.claimSignature == null
+      ? null
+      : String(parsed.claimSignature).trim() || null;
+  return {
+    id,
+    totalClaimedRaw,
+    recipients,
+    slot,
+    observedAtMs,
+    claimSignature,
+  };
+}
+
 export async function handleFairfunCommand(args: {
   command: string | undefined;
   values: string[];
@@ -159,18 +216,41 @@ export async function handleFairfunCommand(args: {
     const ref = values[0];
     if (!ref)
       throw new Error(
-        "Usage: slrd events <token|ca> [--swaps-only|--transfers-only] [--jsonl]",
+        "Usage: slrd events <token|ca> [--all|--swaps|--transfers|--creates|--swaps-only|--transfers-only] [--jsonl]",
       );
     const token = await ensureToken(slrd, ref);
     const controller = new AbortController();
     const stop = () => controller.abort();
     process.once("SIGINT", stop);
     process.once("SIGTERM", stop);
-    const swaps = !bool(flags, "transfers-only");
-    const transfers = !bool(flags, "swaps-only");
+
+    const explicit =
+      bool(flags, "all") ||
+      bool(flags, "swaps") ||
+      bool(flags, "transfers") ||
+      bool(flags, "creates");
+    let swaps = true;
+    let transfers = true;
+    let creates = false;
+    if (bool(flags, "swaps-only")) {
+      swaps = true;
+      transfers = false;
+      creates = false;
+    } else if (bool(flags, "transfers-only")) {
+      swaps = false;
+      transfers = true;
+      creates = false;
+    } else if (explicit) {
+      const all = bool(flags, "all");
+      swaps = all || bool(flags, "swaps");
+      transfers = all || bool(flags, "transfers");
+      creates = all || bool(flags, "creates");
+    }
+
     const subscription = await slrd.subscribeTokenEvents(token.mint, {
       swaps,
       transfers,
+      creates,
       commitment: bool(flags, "finalized") ? "finalized" : "confirmed",
       signal: controller.signal,
     });
@@ -194,7 +274,12 @@ export async function handleFairfunCommand(args: {
         if (event.type === "swap") {
           emit(
             `${new Date(event.blockTimeMs ?? event.observedAtMs).toISOString()}  SWAP ${event.venue} ${event.side.toUpperCase()} ` +
-              `${event.tokenAmountRaw} tokenRaw trader=${event.trader ?? "?"} sig=${event.signature}\n`,
+              `${event.tokenAmountRaw} tokenRaw quote=${event.quoteAmountRaw ?? "?"} ${event.quoteMint} trader=${event.trader ?? "?"} sig=${event.signature}\n`,
+          );
+        } else if (event.type === "create") {
+          emit(
+            `${new Date(event.blockTimeMs ?? event.observedAtMs).toISOString()}  CREATE ` +
+              `${event.symbol ?? "?"} ${event.name ?? "?"} creator=${event.creator ?? "?"} quote=${event.quoteMint} sig=${event.signature}\n`,
           );
         } else {
           emit(
@@ -319,20 +404,21 @@ export async function handleFairfunCommand(args: {
   if (command === "rewards" && values[0] === "distribute") {
     const ref = values[1];
     const wallet = flag(flags, "wallet");
-    if (!ref || !wallet)
+    const id = flag(flags, "id");
+    const snapshotPath = flag(flags, "snapshot");
+    if (!ref || !wallet || !id || !snapshotPath)
       throw new Error(
-        "Usage: slrd rewards distribute <token|ca> --wallet <beneficiary> [--claim-first | --amount-raw N] [--reward-mint <mint>] [--id <epoch>] [--live]",
+        "Usage: slrd rewards distribute <token|ca> --wallet <beneficiary> --id <ledger-id> --snapshot <snapshot.json> [--reward-mint <mint>] [--reserve-raw N] [--live]",
       );
     const token = await ensureToken(slrd, ref);
+    const snapshot = rewardSnapshotFile(snapshotPath);
     const common = {
+      id,
       token: token.mint,
       wallet,
       rewardMint: flag(flags, "reward-mint"),
-      amountRaw: raw(flag(flags, "amount-raw"), "--amount-raw"),
-      claimFirst: bool(flags, "claim-first"),
+      snapshot,
       reserveRaw: raw(flag(flags, "reserve-raw"), "--reserve-raw") ?? 0n,
-      excludeOwners: csv(flag(flags, "exclude")),
-      minimumHolderRaw: raw(flag(flags, "min-holder-raw"), "--min-holder-raw"),
       maxRecipientsPerTransaction: positiveInteger(flag(flags, "max-per-tx")),
     };
     if (!bool(flags, "live")) {
@@ -340,35 +426,37 @@ export async function handleFairfunCommand(args: {
       emit(
         json({
           live: false,
+          version: plan.version,
           id: plan.id,
+          snapshotId: plan.snapshotId,
           tokenMint: plan.tokenMint,
           sourceWallet: plan.sourceWallet,
-          claimFirst: plan.claimFirst,
           rewardAsset: plan.rewardAsset,
-          rewardAmountRaw: plan.rewardAmountRaw,
-          snapshotSlot: plan.snapshot.slot,
-          holders: plan.snapshot.eligibleHolderCount,
-          allocations: plan.allocations.length,
-          undistributedRemainderRaw: plan.undistributedRemainderRaw,
-          batches: plan.transferPlan.batches.map((batch) => ({
-            index: batch.index,
-            recipients: batch.allocations.length,
-            totalRaw: batch.totalRaw,
-            serializedSize: batch.estimatedSerializedSize,
-          })),
+          totalClaimedRaw: plan.totalClaimedRaw,
+          totalEntitledRaw: plan.totalEntitledRaw,
+          totalConfirmedPaidRaw: plan.totalConfirmedPaidRaw,
+          totalOutstandingRaw: plan.totalOutstandingRaw,
+          sourceBalanceRaw: plan.sourceBalanceRaw,
+          availableRaw: plan.availableRaw,
+          reserveRaw: plan.reserveRaw,
+          outstanding: plan.outstanding,
+          pending: plan.pending,
+          nextBatch: plan.transferPlan?.batches[0]
+            ? {
+                recipients: plan.transferPlan.batches[0].allocations.length,
+                totalRaw: plan.transferPlan.batches[0].totalRaw,
+                serializedSize:
+                  plan.transferPlan.batches[0].estimatedSerializedSize,
+                payments: plan.nextPayments,
+              }
+            : null,
         }) + "\n",
       );
       return true;
     }
-    const id = flag(flags, "id");
-    if (!id)
-      throw new Error(
-        "Live holder distribution requires --id <stable-epoch-id> so retries are idempotent.",
-      );
     requireLiveGate();
     const state = await slrd.distributeHolderRewards({
       ...common,
-      id,
       via: flag(flags, "sender") ?? "rpc",
       skipSimulation: bool(flags, "skip-simulation"),
       skipPreflight: bool(flags, "skip-preflight"),

package/src/index.ts

@@ -322,7 +322,7 @@ async function storedWalletCount(): Promise<number> {
   const { createTraderSolard } = await import("@solard/sdk");
   const probe = createTraderSolard();
   try {
-    return probe.wallets.list().length;
+    return (probe.db.wallets.select().all() as unknown[]).length;
   } finally {
     probe.close();
   }
@@ -333,7 +333,7 @@ function help(): string {
 
 Wallets and tokens
   slrd setup [--status]                      Check ephemeral wallet-password mode; no password is persisted
-  slrd wallet create [name]                  Generate and persist an encrypted Solana wallet
+  slrd wallet create [name] [--vanity <suffix>]        Generate and persist an encrypted Solana wallet
   slrd import <private_key> [name]
   cat key.json | slrd import --stdin [name]
 
@@ -356,7 +356,7 @@ External contacts (public addresses only; never signing wallets or group members
   slrd token analyze <ca> [--top N] [--json]
   slrd tokens
   slrd holders <token|ca> [--exclude <a,b>] [--min-raw N] [--json]         Complete on-chain holder snapshot
-  slrd events <token|ca> [--swaps-only|--transfers-only] [--jsonl]          Live typed Pump/PumpSwap + transfer stream
+  slrd events <token|ca> [--all|--swaps|--transfers|--creates] [--jsonl]     Live typed Pump/PumpSwap + transfer/create stream
 
 Vanity mints
   slrd vanity --suffix pump --out .\\mint.json [--count <n>]
@@ -365,6 +365,9 @@ Vanity mints
   slrd vanity pool release <mint-address>               Release an ambiguous/failed launch reservation
   launch/vamp: add --mint-pool pump [--mint-pool-address <address>] to consume a pooled mint
 
+Pump pairs
+  slrd pump pairs [--json]                              Read Pump-supported quote mints from the on-chain Global account
+
 Metadata and launching
   slrd launch pump --creator <wallet> (--uri <metadata_uri> | --metadata <json> | --image <path> --description <text>) [--pair SOL|USDC|<custom-quote-mint>] [--beneficiary <wallet|address>] [--alias <name>] [--live] [--skip-simulation]
                     [--deployment-sender helius-rpc|helius-fast] [--helius-tip-sol 0.01]
@@ -421,7 +424,8 @@ Trading
   slrd transfer-many --wallet <wallet> (--token <mint>|--sol) --file <allocations.json> [--id <stable-id> --live]
   slrd transfer-many status <stable-id>
   slrd transfer-many resume <stable-id> [--sender rpc|helius]
-  slrd rewards distribute <token|ca> --wallet <beneficiary> [--claim-first|--amount-raw N] [--id <epoch>] [--live]
+  slrd rewards distribute <token|ca> --wallet <beneficiary> --id <ledger-id> --snapshot <snapshot.json> [--reward-mint <mint>] [--live]
+                                                        Snapshot contains cumulative totalClaimedRaw + recipients[].entitledRaw; Solard tracks confirmed payouts
   slrd rewards status <distribution-id>
   slrd rewards inspect <token|ca>                      Show claim source, quote asset, estimated accrued creator reward, and payout address
   slrd rewards claim <token|ca> --wallet <fee-payer>  Claim creator rewards; on-chain beneficiary receives the reward
@@ -558,7 +562,7 @@ async function main() {
     return;
   }
 
-  if (needsVault && !process.env.SLRD_MASTER_KEY?.trim()) {
+  if (needsVault) {
     const allowCreate =
       (command === "wallet" && values[0] === "create") ||
       command === "import" ||
@@ -859,6 +863,20 @@ async function main() {
       return;
     }
 
+    if (command === "pump" && values[0] === "pairs") {
+      const pairs = await slrd.pump.getSupportedPairs();
+      if (flags.has("json")) {
+        emit(json(pairs) + "\n");
+      } else {
+        for (const pair of pairs) {
+          emit(
+            `${(pair.symbol ?? "?").padEnd(12)} ${(pair.name ?? "?").padEnd(28)} ${pair.mint}  decimals=${pair.decimals}\n`,
+          );
+        }
+      }
+      return;
+    }
+
     if (command === "swap") {
       const { runJupiterSwapCommand } =
         await import("./commands/jupiter-swap.ts");
@@ -928,16 +946,46 @@ async function main() {
 
     if (command === "wallet" && values[0] === "create") {
       const firstWallet = slrd.wallets.list().length === 0;
-      const wallet = slrd.createWallet(
-        values[1] ?? (firstWallet ? "main" : undefined),
-      );
+      const name = values[1] ?? (firstWallet ? "main" : undefined);
+      const vanity = flags.has("vanity") ? need(flags, "vanity") : null;
+      const vanityResult = vanity
+        ? await slrd.createVanityWallet(name, {
+            suffix: vanity,
+            workers: int(flags, "workers"),
+            maxAttempts: int(flags, "max-attempts"),
+            timeoutMs: int(flags, "timeout-ms", 0),
+            reportEvery: int(flags, "report-every", 1_000_000),
+            onProgress: process.stderr.isTTY
+              ? (progress) =>
+                  process.stderr.write(
+                    `${OWL} wallet vanity ${progress.suffix}: ${progress.attempts} attempts, ${progress.ratePerSecond}/s\r`,
+                  )
+              : undefined,
+          })
+        : null;
+      if (vanityResult && process.stderr.isTTY) process.stderr.write("\n");
+      const wallet = vanityResult?.wallet ?? slrd.createWallet(name);
+      const output = vanityResult
+        ? {
+            ...wallet,
+            vanity: {
+              suffix: vanityResult.suffix,
+              attempts: vanityResult.attempts,
+              elapsedMs: vanityResult.elapsedMs,
+              ratePerSecond: vanityResult.ratePerSecond,
+            },
+          }
+        : wallet;
       if (flags.has("json")) {
-        emit(json(wallet) + "\n");
+        emit(json(output) + "\n");
       } else if (process.stdout.isTTY) {
         emit(
           `\n╭─ ${OWL} wallet ready ──────────────────────────────────╮\n` +
             `  name     @${wallet.name}\n` +
             `  address  ${wallet.address}\n` +
+            (vanityResult
+              ? `  vanity   suffix=${vanityResult.suffix} attempts=${vanityResult.attempts}\n`
+              : "") +
             `  storage  encrypted in Solard's local wallet database\n` +
             `  password NOT saved; you will enter it again next invocation\n` +
             `╰──────────────────────────────────────────────────────╯\n` +

package/src/vault-onboarding.ts

@@ -1,5 +1,9 @@
 export class VaultOnboardingError extends Error {
-  readonly name = "VaultOnboardingError";
+  readonly name: string = "VaultOnboardingError";
+}
+
+export class VaultIntegrityError extends VaultOnboardingError {
+  readonly name: string = "VaultIntegrityError";
 }
 
 export type VaultReadyResult = {
@@ -30,7 +34,10 @@ async function promptHidden(message: string): Promise<string> {
 
   return await new Promise<string>((resolve, reject) => {
     let value = "";
+    let settled = false;
     const cleanup = () => {
+      if (settled) return;
+      settled = true;
       input.off("data", onData);
       input.setRawMode(Boolean(wasRaw));
       input.pause();
@@ -67,6 +74,11 @@ function clearMasterKey(): void {
   delete process.env.SLRD_MASTER_KEY;
 }
 
+function environmentMasterKey(): string | null {
+  const value = process.env.SLRD_MASTER_KEY;
+  return value != null && value.length > 0 ? value : null;
+}
+
 async function confirmNewPassword(): Promise<string> {
   process.stdout.write(
     [
@@ -101,21 +113,25 @@ async function confirmNewPassword(): Promise<string> {
   );
 }
 
-async function validateExistingWalletPassword(password: string): Promise<void> {
+async function validateAllStoredWallets(password: string): Promise<void> {
   setMasterKey(password);
   const { createTraderSolard } = await import("@solard/sdk");
   const probe = createTraderSolard();
   try {
-    const wallets = probe.wallets.list();
-    if (!wallets.length) return;
-    // Decrypt one persisted wallet. All persisted wallets use the same process-level
-    // SLRD_MASTER_KEY contract, so this is enough to catch a mistyped password before
-    // the requested command begins doing work.
-    probe.wallets.signer(wallets[0]!.address);
-  } catch {
+    const integrity = probe.wallets.integrity();
+    if (!integrity.failures.length) return;
     clearMasterKey();
-    throw new VaultOnboardingError(
-      "That wallet password could not decrypt the stored wallets.",
+    if (integrity.decrypted === 0) {
+      throw new VaultOnboardingError(
+        "That wallet password could not decrypt the stored wallet database.",
+      );
+    }
+    const affected = integrity.failures
+      .map((wallet) => `@${wallet.name} ${wallet.address}`)
+      .join(", ");
+    throw new VaultIntegrityError(
+      `Wallet database integrity check failed: one master password must decrypt every stored signing wallet. ` +
+        `Decrypted ${integrity.decrypted}/${integrity.total}; undecryptable or mismatched: ${affected}`,
     );
   } finally {
     probe.close();
@@ -126,9 +142,10 @@ async function unlockExistingWallets(): Promise<string> {
   for (let attempt = 1; attempt <= 3; attempt += 1) {
     const password = await promptHidden("Wallet password: ");
     try {
-      await validateExistingWalletPassword(password);
+      await validateAllStoredWallets(password);
       return password;
     } catch (error) {
+      if (error instanceof VaultIntegrityError) throw error;
       if (attempt === 3) throw error;
       process.stdout.write("Incorrect password. Try again.\n\n");
     }
@@ -136,18 +153,13 @@ async function unlockExistingWallets(): Promise<string> {
   throw new VaultOnboardingError("Unable to unlock the stored wallets.");
 }
 
-/**
- * Ensure the process has an SLRD_MASTER_KEY before a command that needs a local
- * signing wallet runs. Nothing is written to disk. The password/master-key value
- * exists only in process.env for this process (and intentionally inherited child
- * processes such as `slrd run ...`).
- */
 export async function ensureCliVaultReady(options: {
   existingWalletCount: number;
   allowCreate?: boolean;
 }): Promise<VaultReadyResult> {
-  const existing = process.env.SLRD_MASTER_KEY?.trim();
+  const existing = environmentMasterKey();
   if (existing) {
+    await validateAllStoredWallets(existing);
     return {
       source: "env",
       created: false,
@@ -197,13 +209,12 @@ export function cliVaultStatus(): {
 } {
   return {
     mode: "ephemeral-password",
-    environmentOverride: Boolean(process.env.SLRD_MASTER_KEY?.trim()),
+    environmentOverride: environmentMasterKey() != null,
     passwordPersisted: false,
     remembered: false,
   };
 }
 
-/** Optional helper for tests/tools that want a visible prompt without a signing command. */
 export async function promptForWalletPassword(
   existingWalletCount: number,
 ): Promise<void> {