@solard/cli 0.2.13 → 0.2.15

package/src/index.ts

@@ -13,6 +13,7 @@ import {
   planRegistryTokenLiquidation,
   removeExternalContact,
   resetSolardRpcStats,
+  resolvePumpQuoteAsset,
   resolveTokenMintForPolicy,
   runScript,
   listScripts,
@@ -23,6 +24,13 @@ import {
 } from "@solard/sdk";
 
 import { handleMeteoraCommand } from "./meteora-commands.ts";
+import { handleFairfunCommand } from "./fairfun-commands.ts";
+import { resolveDestinationRef } from "./refs.ts";
+import {
+  VaultOnboardingError,
+  cliVaultStatus,
+  ensureCliVaultReady,
+} from "./vault-onboarding.ts";
 
 function emit(value: string): void {
   process.stdout.write(value);
@@ -32,35 +40,6 @@ const OWL = "🦉";
 const NATIVE_SOL_MINT = "So11111111111111111111111111111111111111112";
 const CANONICAL_USDC_MINT = "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v";
 
-async function quoteJupiterSwap(
-  args: Record<string, unknown>,
-): Promise<unknown> {
-  const sdk = (await import("@solard/sdk")) as Record<string, unknown>;
-  const fn = sdk.quoteJupiterSwap;
-  if (typeof fn !== "function") {
-    throw new Error(
-      "@solard/sdk does not export quoteJupiterSwap required by `slrd swap`.",
-    );
-  }
-  return await (fn as (input: Record<string, unknown>) => Promise<unknown>)(
-    args,
-  );
-}
-
-async function executeJupiterSwap(
-  args: Record<string, unknown>,
-): Promise<unknown> {
-  const sdk = (await import("@solard/sdk")) as Record<string, unknown>;
-  const fn = sdk.executeJupiterSwap;
-  if (typeof fn !== "function") {
-    throw new Error(
-      "@solard/sdk does not export executeJupiterSwap required by `slrd swap`.",
-    );
-  }
-  return await (fn as (input: Record<string, unknown>) => Promise<unknown>)(
-    args,
-  );
-}
 type Flags = Map<string, string>;
 function args(input: string[]): { values: string[]; flags: Flags } {
   const values: string[] = [],
@@ -122,6 +101,24 @@ function formatError(error: unknown): string {
     return String(error);
   }
 }
+
+function friendlyCliError(error: unknown): string | null {
+  const debug =
+    process.argv.includes("--debug") ||
+    process.env.SLRD_DEBUG === "1" ||
+    process.env.SOLARD_DEBUG === "1";
+  if (debug || !(error instanceof Error)) return null;
+  const code =
+    "code" in error &&
+    typeof (error as Error & { code?: unknown }).code === "string"
+      ? String((error as Error & { code?: unknown }).code)
+      : null;
+  if (error instanceof VaultOnboardingError) return error.message;
+  if (code === "MISSING_CONFIG" && error.message.includes("SLRD_MASTER_KEY")) {
+    return `${error.message}\n\nEnter the wallet password interactively, or set SLRD_MASTER_KEY for automation/CI.`;
+  }
+  return null;
+}
 function duration(value: string | undefined, fallbackMs: number): number {
   if (!value) return fallbackMs;
   const match = /^(\d+(?:\.\d+)?)(ms|s|m|h)?$/i.exec(value.trim());
@@ -202,10 +199,22 @@ function txWalletTokenBalances(
   return out;
 }
 
+function formatRawLocal(value: bigint, decimals: number): string {
+  const unit = 10n ** BigInt(Math.max(0, decimals));
+  const whole = value / unit;
+  const fraction = value % unit;
+  if (decimals <= 0 || fraction === 0n) return whole.toString();
+  const fractionText = fraction
+    .toString()
+    .padStart(decimals, "0")
+    .replace(/0+$/, "");
+  return `${whole.toString()}.${fractionText}`;
+}
+
 function formatSignedRaw(value: bigint, decimals: number): string {
   const sign = value > 0n ? "+" : value < 0n ? "-" : "";
   const abs = value < 0n ? -value : value;
-  return `${sign}${formatRaw(abs, decimals)}`;
+  return `${sign}${formatRawLocal(abs, decimals)}`;
 }
 function formatDurationMs(value: number): string {
   if (!Number.isFinite(value) || value < 0) return "0ms";
@@ -250,55 +259,80 @@ function targetWallets(
     group,
   };
 }
-function resolveDestinationRef(
-  slrd: { resolveWallet(ref: string): { address: { toBase58(): string } } },
-  value: string,
-): {
-  input: string;
-  address: string;
-  contactName?: string;
-  walletName?: string;
-} {
-  const input = value.trim();
-  const contact = findExternalContact(input);
-
-  let walletAddress: string | null = null;
-  try {
-    walletAddress = slrd.resolveWallet(input).address.toBase58();
-  } catch {
-    walletAddress = null;
-  }
-
-  if (contact && walletAddress && contact.address !== walletAddress) {
-    throw new Error(
-      `Ambiguous destination ${input}: external contact @${contact.name} points to ${contact.address}, ` +
-        `but a stored signing wallet resolves to ${walletAddress}. Rename one of them.`,
-    );
+function commandNeedsSigningVault(
+  command: string | undefined,
+  values: string[],
+  flags: Flags,
+): boolean {
+  if (!command) return false;
+  if (command === "wallet" && values[0] === "create") return true;
+  if (command === "rewards" && values[0] === "claim") return true;
+  if (command === "rewards" && values[0] === "distribute")
+    return flags.has("live");
+  if (command === "transfer-many") {
+    if (values[0] === "status") return false;
+    if (values[0] === "resume") return true;
+    return flags.has("live");
   }
+  if (
+    [
+      "import",
+      "export",
+      "transfer",
+      "send-sol",
+      "buy",
+      "sell",
+      "unwrap-wsol",
+      "claim",
+    ].includes(command)
+  )
+    return true;
+  if (command === "alt" && (values[0] === "create" || values[0] === "extend"))
+    return true;
+  if (command === "vanity" && values[0] === "pool" && values[1] === "generate")
+    return true;
+
+  // Local Pump launch planning/building resolves a real signing wallet even in
+  // dry-run mode. External-wallet preparation is deliberately public-key-only.
+  if (
+    command === "launch" &&
+    (values[0] === "pump" || values[0] === "pump-token")
+  )
+    return !flags.has("prepare");
+  if (command === "deploy" || command === "vamp") return true;
 
-  if (contact) {
-    return {
-      input,
-      address: contact.address,
-      contactName: contact.name,
-    };
-  }
+  if (
+    flags.has("live") &&
+    [
+      "swap",
+      "sweep",
+      "liquidate",
+      "meteora",
+      "raydium",
+      "spam-buy",
+      "buy-spam",
+      "run",
+    ].includes(command)
+  )
+    return true;
+  return false;
+}
 
-  if (walletAddress) {
-    return {
-      input,
-      address: walletAddress,
-      walletName: input.replace(/^@/, ""),
-    };
+async function storedWalletCount(): Promise<number> {
+  const { createTraderSolard } = await import("@solard/sdk");
+  const probe = createTraderSolard();
+  try {
+    return probe.wallets.list().length;
+  } finally {
+    probe.close();
   }
-
-  return { input, address: input };
 }
 
 function help(): string {
   return `${OWL} slrd — multi-wallet Solana CLI + SDK for traders and AI agents
 
 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 import <private_key> [name]
   cat key.json | slrd import --stdin [name]
@@ -316,7 +350,13 @@ External contacts (public addresses only; never signing wallets or group members
   slrd token <token_ca> [name] [--metadata-json <json>]
   slrd token set <token|ca> [--pool <address>] [--quote-mint <mint>] [--quote-program <program>] [--metadata-json <json>]
   slrd token refresh <token|ca>
+  slrd token backfill <ca> [--replace] [--confirmed] [--batch-size 100] [--rpc-concurrency 3] [--max-signatures N] [--json]
+                                                        Durable exact trades + sparse 1s candle materialization from creation
+  slrd token trades <ca> [--from-start] [--min-sol N] [--owner <wallet>] [--side buy|sell] [--limit N] [--json]
+  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
 
 Vanity mints
   slrd vanity --suffix pump --out .\\mint.json [--count <n>]
@@ -326,14 +366,16 @@ Vanity mints
   launch/vamp: add --mint-pool pump [--mint-pool-address <address>] to consume a pooled mint
 
 Metadata and launching
-  slrd launch pump --creator <wallet> (--uri <metadata_uri> | --metadata <json> | --image <path> --description <text>) [--alias <name>] [--live] [--skip-simulation]
+  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]
+  slrd prepare pump --payer <phantom-address> --name <name> --symbol <symbol> --uri <metadata_uri> [--pair SOL|USDC|<custom-quote-mint>] [--beneficiary <address>] [--out prepared.json]
+                                                        Build + mint-partial-sign only; payer remains unsigned and nothing is broadcast
   slrd metadata upload --image <local_path> --name <name> --symbol <symbol> --description <text> [--provider pump-frontend|pinata]
                        [--twitter <url>] [--telegram <url>] [--website <url>] [--video <url>] [--hide-name]
   slrd vamp <source-mint> --creator <wallet> [--name <name>] [--symbol <symbol>] [--image <path-or-url>] [--description <text>]
                      [--website <url>] [--twitter <url>] [--telegram <url>] [--video <url>] [--uri <metadata-uri>]
                      [--buy-plan <file>] [--mint-pool pump] [--submit-mode jito-bundle] [--live] [--skip-simulation]
-  slrd deploy pump --wallet <wallet> --name <name> --symbol <symbol> (--uri <metadata_uri> | --image <local_path> --description <text>) [--alias <name>] [--live]
+  slrd deploy pump --wallet <wallet> --name <name> --symbol <symbol> (--uri <metadata_uri> | --image <local_path> --description <text>) [--pair SOL|USDC|<custom-quote-mint>] [--beneficiary <wallet|address>] [--alias <name>] [--live]
                    [--twitter <url>] [--telegram <url>] [--website <url>] [--video <url>] [--hide-name]
 
 Prices
@@ -342,18 +384,24 @@ Prices
   slrd price average <token|ca> --period 15m         Average stored samples in a period
   slrd price watch <token|ca...> [--interval 1s] [--period 1m]
 
+Backtesting
+  slrd backtest <mint> --dip-pct 20 --profit-pct 40 --buy-sol 0.1 [--from creation|migration|<time>] [--to <time>] [--capital-sol 5] [--slippage-bps N] [--venue-fee-bps N] [--network-fee-sol N] [--latency-ms N] [--require-from-start] [--exact-trades] [--ledger[=<csv>]] [--json]
+                                                        Replays sparse 1s candles by default; --exact-trades uses durable market fills
+
 Transfers and consolidation
   slrd transfer <contact|wallet|address> --wallet <source-wallet> --sol <amount> [--simulate-only]
-  slrd sweep sol --to <contact|wallet|address> [--wallets <a,b,...>] [--exclude-group <group>] [--exclude-prefix <prefix>] [--keep <wallet=SOL,...>] [--keep-if-tokens <SOL> | --keep-if-token <token>=<SOL>] [--simulate | --live] [--json]
+  slrd transfer <contact|wallet|address> --wallet <source-wallet> --token <USDC|mint> --amount <ui> [--simulate-only]
+  slrd sweep sol --to <contact|wallet|address> [--wallets <a,b,...>] [--max-balance-sol <SOL>] [--exclude-group <group>] [--exclude-prefix <prefix>] [--keep <wallet=SOL,...>] [--keep-if-tokens <SOL> | --keep-if-token <token>=<SOL>] [--simulate | --live] [--json]
                                                         Without --wallets, sweep considers all stored signing wallets
 
 Token liquidation
-  slrd liquidate tokens --except <token|mint> [--wallets <a,b,...>] [--slippage-bps 1500] [--no-jupiter] [--simulate | --live]
+  slrd liquidate tokens --except <token|mint> [--wallets <a,b,...>] [--slippage-bps 1500] [--no-jupiter] [--burn-unsellable] [--simulate | --live]
                                                         Sell supported tokens except protected mint(s); unwrap WSOL; close unprotected zero-balance token accounts and reclaim rent
 
 RPC
   All Solard JSON-RPC traffic is globally rate-limited to 5 req/s by default.
   Override only when your provider allows it: SLRD_RPC_MAX_RPS=<n>
+  Fetch-level network failures (ECONNRESET, socket close, etc.) retry 4 times by default; SLRD_RPC_NETWORK_RETRIES=<n>.
   Jupiter fallback: keyless 0.5 req/s, API-key default 1 req/s; override SLRD_JUPITER_MAX_RPS=<n>
 
 Diagnostics
@@ -362,13 +410,22 @@ Diagnostics
   --measure-stream  Restore raw live measure-fn output for low-level debugging
 
 Trading
-  slrd swap <token|mint> --wallet <wallet> --sol <amount> [--live]   Quote or execute SOL -> token through Jupiter
-  slrd buy <token|ca> (--wallet <wallet> | --wallets <w1,w2> | --group <name>) --sol <amount> [--slippage-bps 1500] [--sender rpc|helius|jito] [--simulate-only]
+  slrd swap --from <SOL|token|mint> --to <SOL|token|mint> --amount <ui> --wallet <wallet> [--live]  Jupiter exact-input any -> any; quote-only unless --live
+  slrd swap <token|mint> --wallet <wallet> --sol <amount> [--live]                              Compatibility: SOL -> token
+  slrd buy <token|ca> (--wallet <wallet> | --wallets <w1,w2> | --group <name>) --sol <amount> [--venue auto|native|jupiter] [--slippage-bps 1500] [--sender rpc|helius|jito] [--simulate-only]
   slrd buy <future-mint> (--wallet <wallet> | --group <name>) (--sol <amount> | --lamports <amount> | --min-bps <n> --max-bps <n>) --spam [--live]
   slrd spam-buy [pump] <future-mint> (--wallet <wallet> | --group <name>) (--sol <amount> | --lamports <amount> | --min-bps <n> --max-bps <n>) [--sender <id>] [--live]
-  slrd sell <token|ca> (--wallet <wallet> | --wallets <w1,w2> | --group <name>) [--bps 10000] [--slippage-bps 1500] [--sender rpc|helius|jito] [--simulate-only]
+  slrd sell <token|ca> (--wallet <wallet> | --wallets <w1,w2> | --group <name>) [--bps 10000] [--venue auto|native|jupiter] [--slippage-bps 1500] [--sender rpc|helius|jito] [--simulate-only]
   slrd unwrap-wsol (--wallet <wallet> | --wallets <w1,w2> | --group <name>) [--sender rpc|helius|jito] [--ignore-missing] [--continue-on-error] [--simulate-only]
   slrd claim <token|ca> --wallet <wallet> [--sender rpc|helius|jito]
+  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> --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
 
 Scripts (strategies stay outside the kernel)
   slrd scripts                              List scripts registered in slrd.config.ts
@@ -418,8 +475,8 @@ Transactions and ALTs
   slrd alt extend <address> --wallet <wallet> <account...>
 
 Environment
-  SLRD_DB_PATH      shared SDK/CLI database; default ./slrd.db (SOLARD_DB_PATH alias supported)
-  SLRD_MASTER_KEY   required to create/import/decrypt stored wallets
+  SLRD_DB_PATH      shared SDK/CLI database; default ~/.solard/solard.sqlite (SOLARD_DB_PATH alias supported)
+  SLRD_MASTER_KEY   optional explicit override for CI/automation; otherwise signing commands prompt each invocation and never persist the password
   RPC_ENDPOINT      required only for chain operations
   HELIUS_SENDER_URL regional/global Helius Sender endpoint used by launch scripts
   HELIUS_RPC_URL    RPC endpoint used for ordinary Helius-RPC buyer lane
@@ -450,10 +507,71 @@ async function main() {
     process.env.SLRD_MEASURE_STREAM === "true";
   configureSolardMeasure(
     streamMeasures
-      ? { silent: false, logger: null }
-      : { silent: false, logger: measureCollector.logger },
+      ? {
+          silent: false,
+          // Middleware mode: accumulate the structured event and then delegate
+          // to measure-fn's built-in logger. The collector itself does not own
+          // formatting or streaming.
+          logger: measureCollector.middleware,
+        }
+      : {
+          silent: false,
+          // Replacement mode: accumulate without printing every span.
+          logger: measureCollector.logger,
+        },
   );
 
+  const vaultCommand = command === "setup";
+  const needsVault = commandNeedsSigningVault(command, values, flags);
+  if (vaultCommand && flags.has("status")) {
+    const status = cliVaultStatus();
+    if (flags.has("json")) {
+      emit(json(status) + "\n");
+    } else {
+      emit(
+        `${OWL} wallet password mode\n` +
+          `  mode                ephemeral per command\n` +
+          `  password persisted  no\n` +
+          `  env override        ${status.environmentOverride ? "yes" : "no"}\n`,
+      );
+    }
+    return;
+  }
+
+  if (vaultCommand) {
+    const count = await storedWalletCount();
+    if (count === 0 && !process.env.SLRD_MASTER_KEY?.trim()) {
+      emit(
+        `${OWL} no wallet password is stored by Solard.\n` +
+          `   No signing wallets exist yet. Run: slrd wallet create [name]\n` +
+          `   That command will ask for a password twice and use it only for that process.\n`,
+      );
+      return;
+    }
+    const result = await ensureCliVaultReady({
+      existingWalletCount: count,
+      allowCreate: false,
+    });
+    emit(
+      `${OWL} wallet password accepted  source=${result.source}\n` +
+        `   Nothing was written to disk; a future invocation will prompt again unless SLRD_MASTER_KEY is set.\n`,
+    );
+    return;
+  }
+
+  if (needsVault && !process.env.SLRD_MASTER_KEY?.trim()) {
+    const allowCreate =
+      (command === "wallet" && values[0] === "create") ||
+      command === "import" ||
+      (command === "vanity" &&
+        values[0] === "pool" &&
+        values[1] === "generate");
+    await ensureCliVaultReady({
+      existingWalletCount: await storedWalletCount(),
+      allowCreate,
+    });
+  }
+
   let perfPrinted = false;
   const printPerfSummary = () => {
     if (perfPrinted) return;
@@ -475,7 +593,10 @@ async function main() {
       `PERF     wall=${formatDurationMs(wallMs)}  ` +
         `measure=${measures.completed} (${measures.errors} err)  ` +
         `rpc=${rpc.requestStarts}  429=${rpc.rateLimited429}  ` +
-        `retries=${rpc.retries429}  limit=${rpc.maxRps}/s\n`,
+        `neterr=${rpc.networkErrors}  ` +
+        `retries=${rpc.retries429 + rpc.retriesNetwork} ` +
+        `(429=${rpc.retries429},net=${rpc.retriesNetwork})  ` +
+        `limit=${rpc.maxRps}/s\n`,
     );
 
     if (flags.has("measure") && !streamMeasures) {
@@ -630,6 +751,11 @@ async function main() {
     await runPumpSpamBuyFromArgs(rest);
     return;
   }
+  if (command === "backtest") {
+    const { runBacktestCommand } = await import("./backtest-command.ts");
+    await runBacktestCommand({ values, flags, emit });
+    return;
+  }
   if (command === "scripts") {
     emit(json(await listScripts()) + "\n");
     return;
@@ -641,6 +767,18 @@ async function main() {
     process.exitCode = await runScript(script, scriptArgs);
     return;
   }
+  if (
+    (command === "prepare" && values[0] === "pump") ||
+    (command === "launch" &&
+      (values[0] === "pump" || values[0] === "pump-token") &&
+      flags.has("prepare"))
+  ) {
+    const { runPumpExternalDeploymentFromArgs } =
+      await import("./pump/external-deployment-cli.ts");
+    const externalArgs = command === "prepare" ? rest.slice(1) : rest.slice(1);
+    await runPumpExternalDeploymentFromArgs(externalArgs);
+    return;
+  }
   if (
     command === "launch" &&
     (values[0] === "pump" || values[0] === "pump-token")
@@ -713,69 +851,19 @@ async function main() {
     ]);
   const slrd = createTraderSolard();
   try {
+    if (await handleFairfunCommand({ command, values, flags, slrd, emit })) {
+      return;
+    }
+
     if (command === "meteora") {
       await handleMeteoraCommand({ slrd, values, flags, emit });
       return;
     }
 
     if (command === "swap") {
-      const outputRef = values[0]?.trim();
-      if (!outputRef) {
-        throw new Error(
-          "Usage: slrd swap <token|mint> --wallet <wallet> --sol <amount> [--live]",
-        );
-      }
-
-      const wallet = need(flags, "wallet");
-      const amountSol = need(flags, "sol");
-      const amountRaw = sol(amountSol).raw;
-      if (amountRaw <= 0n) throw new Error("--sol must be greater than zero");
-
-      const normalizedOutput = outputRef.replace(/^\$/, "").trim();
-      const outputMint =
-        normalizedOutput.toUpperCase() === "USDC"
-          ? CANONICAL_USDC_MINT
-          : resolveTokenMintForPolicy(slrd, normalizedOutput);
-
-      if (outputMint === NATIVE_SOL_MINT) {
-        throw new Error("Swap output is SOL; choose a different token mint.");
-      }
-
-      if (!flags.has("live")) {
-        const quote = await quoteJupiterSwap({
-          inputMint: NATIVE_SOL_MINT,
-          outputMint,
-          amountRaw,
-        });
-        emit(
-          json({
-            mode: "quote",
-            wallet,
-            input: { symbol: "SOL", mint: NATIVE_SOL_MINT, amountSol },
-            output: { ref: outputRef, mint: outputMint },
-            quote,
-            hint: "Re-run with --live to execute this swap.",
-          }) + "\n",
-        );
-        return;
-      }
-
-      const signer = slrd.signer(wallet);
-      const result = await executeJupiterSwap({
-        inputMint: NATIVE_SOL_MINT,
-        outputMint,
-        amountRaw,
-        signer,
-      });
-      emit(
-        json({
-          mode: "live",
-          wallet,
-          input: { symbol: "SOL", mint: NATIVE_SOL_MINT, amountSol },
-          output: { ref: outputRef, mint: outputMint },
-          result,
-        }) + "\n",
-      );
+      const { runJupiterSwapCommand } =
+        await import("./commands/jupiter-swap.ts");
+      emit(json(await runJupiterSwapCommand({ slrd, values, flags })) + "\n");
       return;
     }
     if (command === "contact" || command === "contacts") {
@@ -840,8 +928,26 @@ async function main() {
     }
 
     if (command === "wallet" && values[0] === "create") {
-      const wallet = slrd.createWallet(values[1]);
-      emit(`${OWL} created @${wallet.name} ${wallet.address}\n`);
+      const firstWallet = slrd.wallets.list().length === 0;
+      const wallet = slrd.createWallet(
+        values[1] ?? (firstWallet ? "main" : undefined),
+      );
+      if (flags.has("json")) {
+        emit(json(wallet) + "\n");
+      } else if (process.stdout.isTTY) {
+        emit(
+          `\n╭─ ${OWL} wallet ready ──────────────────────────────────╮\n` +
+            `  name     @${wallet.name}\n` +
+            `  address  ${wallet.address}\n` +
+            `  storage  encrypted in Solard's local wallet database\n` +
+            `  password NOT saved; you will enter it again next invocation\n` +
+            `╰──────────────────────────────────────────────────────╯\n` +
+            `\nNext:  slrd balances --wallet ${wallet.name}\n` +
+            `Backup: slrd export ${wallet.name} --out .\\${wallet.name}-key.txt\n`,
+        );
+      } else {
+        emit(`${OWL} created @${wallet.name} ${wallet.address}\n`);
+      }
       return;
     }
     if (command === "export") {
@@ -1482,14 +1588,39 @@ async function main() {
         );
         uri = (uploadedMetadata as { metadataUri: string }).metadataUri;
       }
-      const creator = flags.get("creator")
-        ? slrd.resolveWallet(flags.get("creator")!).address
-        : slrd.signer(wallet).publicKey;
+      const payer = slrd.signer(wallet).publicKey;
+      const beneficiaryInput = flags.get("beneficiary") ?? flags.get("creator");
+      let creator = payer;
+      if (beneficiaryInput && beneficiaryInput !== "true") {
+        try {
+          creator = slrd.resolveWallet(beneficiaryInput).address;
+        } catch {
+          const contact = findExternalContact(beneficiaryInput);
+          const { PublicKey } = await import("@solana/web3.js");
+          creator = new PublicKey(contact?.address ?? beneficiaryInput);
+        }
+      }
+      const quoteAsset =
+        launchpad === "pump"
+          ? await resolvePumpQuoteAsset(
+              slrd.connection(),
+              flags.get("pair") ?? flags.get("quote-mint") ?? "SOL",
+            )
+          : undefined;
+      if (
+        launchpad !== "pump" &&
+        (flags.has("pair") || flags.has("beneficiary"))
+      ) {
+        throw new Error(
+          "--pair and --beneficiary are currently defined for Pump create_v2 deployment only.",
+        );
+      }
       const deployment = await slrd.prepareTokenDeployment(launchpad, wallet, {
         name,
         symbol,
         uri,
         creator,
+        quoteAsset,
         mayhemMode: flags.has("mayhem"),
         cashback: flags.has("cashback"),
       });
@@ -1508,6 +1639,12 @@ async function main() {
         name,
         symbol,
         uri,
+        beneficiary: creator.toBase58(),
+        pair:
+          quoteAsset?.kind === "native-sol"
+            ? "SOL"
+            : (quoteAsset?.mint.toBase58() ?? null),
+        quoteMint: quoteAsset?.mint.toBase58() ?? null,
         uploadedMetadata,
         live: flags.has("live"),
       };
@@ -1532,7 +1669,31 @@ async function main() {
       emit(json({ ...header, receipt, token }) + "\n");
       return;
     }
-    if (command === "token" && values[0] !== "set" && values[0] !== "refresh") {
+    if (
+      command === "token" &&
+      (values[0] === "backfill" ||
+        values[0] === "trades" ||
+        values[0] === "analyze")
+    ) {
+      const { runTokenHistoryCommand } =
+        await import("./token-history-command.ts");
+      await runTokenHistoryCommand({
+        slrd,
+        action: values[0]!,
+        values: values.slice(1),
+        flags,
+        emit,
+      });
+      return;
+    }
+    if (
+      command === "token" &&
+      values[0] !== "set" &&
+      values[0] !== "refresh" &&
+      values[0] !== "backfill" &&
+      values[0] !== "trades" &&
+      values[0] !== "analyze"
+    ) {
       const [mint, name] = values;
       if (!mint) throw new Error("Usage: slrd token <token_ca> [name]");
       const metadata = flags.get("metadata-json");
@@ -1658,7 +1819,7 @@ async function main() {
       const except = csv(flags.get("except"));
       if (except.length === 0) {
         throw new Error(
-          "Usage: slrd liquidate tokens --except <token|mint>[,<token|mint>...] [--wallets <a,b,...>] [--simulate | --live]",
+          "Usage: slrd liquidate tokens --except <token|mint>[,<token|mint>...] [--wallets <a,b,...>] [--burn-unsellable] [--simulate | --live]",
         );
       }
       if (flags.has("simulate") && flags.has("live")) {
@@ -1711,6 +1872,7 @@ async function main() {
         portfolioConcurrency: 1,
         portfolioDelayMs: 0,
         jupiterFallback: !flags.has("no-jupiter"),
+        burnUnsellable: flags.has("burn-unsellable"),
         onProgress: (event: any) => {
           if (event.stage === "portfolio-start") {
             emit("SCAN     wallet token accounts...\n");
@@ -1833,7 +1995,7 @@ async function main() {
       const destinationInput = flags.get("to") ?? values[1];
       if (!destinationInput || destinationInput === "true") {
         throw new Error(
-          "Usage: slrd sweep sol --to <contact|wallet|address> [--wallets <a,b,...>] [--exclude-group <group>] [--exclude-prefix <prefix>] [--keep <wallet=SOL,...>] [--keep-if-tokens <SOL> | --keep-if-token <token>=<SOL>] [--simulate | --live] [--json]",
+          "Usage: slrd sweep sol --to <contact|wallet|address> [--wallets <a,b,...>] [--max-balance-sol <SOL>] [--exclude-group <group>] [--exclude-prefix <prefix>] [--keep <wallet=SOL,...>] [--keep-if-tokens <SOL> | --keep-if-token <token>=<SOL>] [--simulate | --live] [--json]",
         );
       }
 
@@ -1894,6 +2056,7 @@ async function main() {
         excludeGroups,
         excludePrefixes,
         includeWallets: includeWallets.length ? includeWallets : undefined,
+        maxBalanceSol: flags.get("max-balance-sol"),
         keepSolByWallet,
         defaultKeepSol: flags.get("default-keep-sol") ?? "0",
         keepSolIfTokens: flags.get("keep-if-tokens"),
@@ -2046,156 +2209,19 @@ async function main() {
     }
 
     if (command === "transfer" || command === "send-sol") {
-      const recipientInput = values[0] === "sol" ? values[1] : values[0];
-      if (!recipientInput) {
-        throw new Error(
-          "Usage: slrd transfer <contact|wallet|address> --wallet <wallet> --sol <amount> [--sender rpc|helius|jito] [--simulate-only]",
-        );
-      }
-
-      const recipient = resolveDestinationRef(slrd, recipientInput);
-      const wallet = need(flags, "wallet");
-      const amount = need(flags, "sol");
-      const via = flags.get("sender") ?? "rpc";
-
-      const cuLimit = Number(flags.get("cu-limit") ?? "10000");
-      const priorityMicroLamports = Number(
-        flags.get("priority-micro-lamports") ?? "0",
-      );
-      if (!Number.isInteger(cuLimit) || cuLimit <= 0)
-        throw new Error("--cu-limit must be a positive integer");
-      if (
-        !Number.isInteger(priorityMicroLamports) ||
-        priorityMicroLamports < 0
-      ) {
-        throw new Error(
-          "--priority-micro-lamports must be a non-negative integer",
-        );
-      }
-
-      const composer = slrd
-        .tx(wallet)
-        .transferSol(recipient.address, sol(amount))
-        .priorityFee({
-          cuLimit,
-          microLamports: priorityMicroLamports,
-        });
-
-      if (flags.has("simulate-only")) {
-        const plan = await composer.build();
-        const result = await slrd.simulatePlan(plan);
-        emit(
-          json({
-            mode: "simulation",
-            wallet,
-            recipient,
-            sol: amount,
-            result,
-          }) + "\n",
-        );
-        return;
-      }
-
-      const receipt = await composer.send({
-        via,
-        kind: "transfer-sol",
-        skipSimulation: flags.has("skip-simulation"),
-        skipPreflight:
-          flags.has("skip-preflight") || flags.has("skip-simulation"),
-      });
-      emit(
-        json({
-          ...receipt,
-          recipient,
-        }) + "\n",
-      );
+      const { runTransferCommand } = await import("./commands/transfer.ts");
+      emit(json(await runTransferCommand({ slrd, values, flags })) + "\n");
       return;
     }
 
     if (command === "buy") {
-      const token = values[0];
-      if (!token)
-        throw new Error(
-          "Usage: slrd buy <token|ca> (--wallet <wallet> | --wallets <w1,w2> | --group <group>) --sol <amount>",
-        );
-      const amount = flags.get("sol");
-      if (!amount) throw new Error("Buy requires explicit --sol <amount>");
-      const targets = targetWallets(
-        slrd,
-        flags,
-        "Usage: slrd buy <token|ca> (--wallet <wallet> | --wallets <w1,w2> | --group <group>) --sol <amount>.",
-      );
-      const options = {
-        slippageBps: int(flags, "slippage-bps", 1500),
-        via: flags.get("sender") ?? "rpc",
-        skipSimulation: flags.has("skip-simulation"),
-        skipPreflight:
-          flags.has("skip-preflight") || flags.has("skip-simulation"),
-      };
-      if (flags.has("simulate-only")) {
-        const plans =
-          targets.refs.length === 1
-            ? [
-                await slrd
-                  .tx(targets.refs[0]!)
-                  .buy(token, sol(amount), options)
-                  .build(),
-              ]
-            : await slrd
-                .composeMany(targets.refs)
-                .buy(token, sol(amount), options)
-                .build();
-        const results = await Promise.all(
-          plans.map((plan) => slrd.simulatePlan(plan)),
-        );
-        emit(json({ mode: "simulation", target: targets, results }) + "\n");
-        return;
-      }
-      const receipts =
-        targets.refs.length === 1
-          ? await slrd.buy(token, targets.refs[0]!, sol(amount), options)
-          : await slrd.buyMany(token, targets.refs, sol(amount), options);
-      emit(json(receipts) + "\n");
+      const { runSmartBuyCommand } = await import("./commands/buy.ts");
+      emit(json(await runSmartBuyCommand({ slrd, values, flags })) + "\n");
       return;
     }
     if (command === "sell") {
-      const token = values[0];
-      if (!token)
-        throw new Error(
-          "Usage: slrd sell <token|ca> (--wallet <wallet> | --wallets <w1,w2> | --group <group>)",
-        );
-      const targets = targetWallets(
-        slrd,
-        flags,
-        "Usage: slrd sell <token|ca> (--wallet <wallet> | --wallets <w1,w2> | --group <group>).",
-      );
-      const sellOptions = {
-        bps: int(flags, "bps", 10000),
-        slippageBps: int(flags, "slippage-bps", 1500),
-        via: flags.get("sender") ?? "rpc",
-        skipSimulation: flags.has("skip-simulation"),
-        skipPreflight:
-          flags.has("skip-preflight") || flags.has("skip-simulation"),
-      };
-      if (flags.has("simulate-only")) {
-        const plans =
-          targets.refs.length === 1
-            ? [await slrd.tx(targets.refs[0]!).sell(token, sellOptions).build()]
-            : await slrd
-                .composeMany(targets.refs)
-                .sell(token, sellOptions)
-                .build();
-        const results = await Promise.all(
-          plans.map((plan) => slrd.simulatePlan(plan)),
-        );
-        emit(json({ mode: "simulation", target: targets, results }) + "\n");
-        return;
-      }
-      const receipts =
-        targets.refs.length === 1
-          ? await slrd.sell(token, targets.refs[0]!, sellOptions)
-          : await slrd.sellMany(token, targets.refs, sellOptions);
-      emit(json(receipts) + "\n");
+      const { runSmartSellCommand } = await import("./commands/sell.ts");
+      emit(json(await runSmartSellCommand({ slrd, values, flags })) + "\n");
       return;
     }
     if (
@@ -2348,6 +2374,74 @@ async function main() {
       emit(json(receipts) + "\n");
       return;
     }
+    if (command === "rewards") {
+      const action = values[0] ?? "inspect";
+      const tokenRef = values[1];
+      if (!tokenRef)
+        throw new Error(
+          "Usage: slrd rewards <inspect|claim> <token|ca> [--wallet <fee-payer>]",
+        );
+
+      if (action === "claim") {
+        const wallet = need(flags, "wallet");
+        const receipt = await slrd.claim(tokenRef, wallet, {
+          via: flags.get("sender") ?? "rpc",
+        });
+        emit(
+          json({
+            action: "claim",
+            token: tokenRef,
+            feePayer: wallet,
+            receipt,
+          }) + "\n",
+        );
+        return;
+      }
+
+      if (action === "inspect") {
+        let token = slrd.resolveToken(tokenRef);
+        try {
+          token = await slrd.refreshToken(token);
+        } catch {
+          // A registered token can still expose a useful claim plan when one
+          // enrichment source is temporarily unavailable.
+        }
+        const { PublicKey } = await import("@solana/web3.js");
+        const probeUser = token.creator
+          ? new PublicKey(token.creator)
+          : new PublicKey(token.mint);
+        const plan = await slrd.resolveClaim(token, probeUser);
+        const payoutAddress =
+          typeof plan.meta?.payoutAddress === "string"
+            ? plan.meta.payoutAddress
+            : token.creator;
+        const output = {
+          action: "inspect",
+          token: token.mint,
+          source: plan.source,
+          payoutAddress: payoutAddress ?? null,
+          quote: {
+            kind: plan.quoteAsset.kind,
+            mint: plan.quoteAsset.mint.toBase58(),
+            decimals: plan.quoteAsset.decimals,
+            tokenProgram: plan.quoteAsset.tokenProgram.toBase58(),
+          },
+          estimatedClaimRaw: plan.estimatedClaimRaw.toString(),
+          estimatedClaimUi: formatRaw(
+            plan.estimatedClaimRaw,
+            plan.quoteAsset.decimals,
+          ),
+          spendableByProbeRaw: plan.spendableByUserRaw.toString(),
+          sharingConfig: plan.meta?.sharingConfig ?? null,
+          note: "Claim is permissionless where supported; --wallet is the transaction fee payer. The configured on-chain beneficiary receives the reward.",
+        };
+        emit(json(output) + "\n");
+        return;
+      }
+
+      throw new Error("Usage: slrd rewards <inspect|claim> <token|ca>");
+    }
+
     if (command === "claim") {
       const token = values[0];
       if (!token)
@@ -2508,7 +2602,10 @@ async function main() {
   }
 }
 main().catch((error) => {
-  emit(`${OWL} error: ${formatError(error)}\n`);
+  const friendly = friendlyCliError(error);
+  emit(
+    friendly ? `${OWL} ${friendly}\n` : `${OWL} error: ${formatError(error)}\n`,
+  );
   process.exitCode = 1;
 });