@solard/cli 0.2.16 → 0.2.19

package/src/index.ts

@@ -1,7 +1,7 @@
 #!/usr/bin/env bun
+import { configure } from "measure-fn";
 import {
   addExternalContact,
-  configureSolardMeasure,
   createSolardMeasureCollector,
   executeRegistrySolSweep,
   executeRegistryTokenLiquidation,
@@ -21,10 +21,10 @@ import {
   simulateRegistryTokenLiquidation,
   wrappedSolAta,
   type TokenRow,
-} from "@solard/sdk";
+} from "@solard/core";
 
 import { handleMeteoraCommand } from "./meteora-commands.ts";
-import { handleFairfunCommand } from "./fairfun-commands.ts";
+import { handleAccountingCommand } from "./accounting-commands.ts";
 import { resolveDestinationRef } from "./refs.ts";
 import {
   VaultOnboardingError,
@@ -77,7 +77,12 @@ function int(flags: Flags, key: string, fallback?: number): number | undefined {
 function json(value: unknown): string {
   return JSON.stringify(
     value,
-    (_, item) => (typeof item === "bigint" ? item.toString() : item),
+    (_, item) =>
+      typeof item === "bigint"
+        ? item.toString()
+        : item instanceof Map
+          ? Object.fromEntries(item)
+          : item,
     2,
   );
 }
@@ -117,7 +122,7 @@ function friendlyCliError(error: unknown): string | null {
   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;
+  return error.message.trim() || error.name;
 }
 function duration(value: string | undefined, fallbackMs: number): number {
   if (!value) return fallbackMs;
@@ -318,8 +323,16 @@ function commandNeedsSigningVault(
   return false;
 }
 
+function sweepUsage(): string {
+  return (
+    "Usage: slrd sweep --to <contact|wallet|address> --below <SOL> " +
+    "[--wallets <a,b,...>] [--keep <wallet=SOL,...>] [--simulate | --live] [--json]\n" +
+    "Compatibility: slrd sweep sol --to <destination> --max-balance-sol <SOL>"
+  );
+}
+
 async function storedWalletCount(): Promise<number> {
-  const { createTraderSolard } = await import("@solard/sdk");
+  const { createTraderSolard } = await import("@solard/core");
   const probe = createTraderSolard();
   try {
     return (probe.db.wallets.select().all() as unknown[]).length;
@@ -357,6 +370,8 @@ External contacts (public addresses only; never signing wallets or group members
   slrd tokens
   slrd holders <token|ca> [--exclude <a,b>] [--min-raw N] [--json]         Complete on-chain holder snapshot
   slrd events <token|ca> [--all|--swaps|--transfers|--creates] [--jsonl]     Live typed Pump/PumpSwap + transfer/create stream
+  slrd events history <token|ca> [--provider auto|solscan|rpc] [--from-slot N] [--to-slot N] [--slot-order] [--json]
+                                                        Historical holder-balance movements with explicit completeness verification
 
 Vanity mints
   slrd vanity --suffix pump --out .\\mint.json [--count <n>]
@@ -394,12 +409,13 @@ Backtesting
 Transfers and consolidation
   slrd transfer <contact|wallet|address> --wallet <source-wallet> --sol <amount> [--simulate-only]
   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
+  slrd sweep --to <contact|wallet|address> --below <SOL> [--wallets <a,b,...>] [--keep <wallet=SOL,...>] [--simulate | --live] [--json]
+                                                        Sweeps stored wallets strictly below the threshold; preview is the default
+  slrd sweep sol ...                                    Compatibility alias; --max-balance-sol remains accepted
 
 Token liquidation
-  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
+  slrd liquidate tokens [--except <token|mint>] [--wallets <a,b,...>] [--except-wallet <wallet>] [--except-wallets <a,b,...>] [--slippage-bps 1500] [--no-jupiter] [--burn-unsellable] [--simulate | --live]
+                                                        Sell all supported tokens unless protected with --except; excluded wallets are not scanned or touched
 
 RPC
   All Solard JSON-RPC traffic is globally rate-limited to 5 req/s by default.
@@ -424,11 +440,15 @@ 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> --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 history <token|ca> [--wallet <reward-recipient>] [--provider auto|solscan|rpc] [--json]
+  slrd rewards distribute <token|ca> --wallet <beneficiary> --snapshot <snapshot.json> [--reward-mint <mint>] [--live]
+                                                        Pay every outstanding cumulative holder entitlement and exit when complete
+  slrd rewards stop <token|ca>                         Ask the currently running distribution for this token to stop before its next transfer
+  slrd rewards status <token|ca>                       Show remembered cumulative entitlement/payment state
+  slrd rewards audit <token|ca> [--holder <wallet>]   Show entitlement and confirmed-payment history
   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
+  slrd rewards claim <token|ca> --wallet <fee-payer> [--id <stable-claim-id> --basis <reward-basis.json>]
+  slrd rewards claim-status <stable-claim-id>
 
 Scripts (strategies stay outside the kernel)
   slrd scripts                              List scripts registered in slrd.config.ts
@@ -483,6 +503,7 @@ Environment
   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
+  SOLSCAN_API_KEY   optional indexed token-history provider; enables authoritative historical transfer reconstruction
   HELIUS_TIP_ACCOUNT, HELIUS_TIP_LAMPORTS, HELIUS_PRIORITY_MICRO_LAMPORTS launch transport policy
   SLRD_LAUNCH_*     launch resend/timeout policy; shared environment, not per-token metadata
   JITO_BLOCK_ENGINE_URL only when explicitly selecting the separate Jito sender
@@ -508,7 +529,7 @@ async function main() {
     flags.has("measure-stream") ||
     process.env.SLRD_MEASURE_STREAM === "1" ||
     process.env.SLRD_MEASURE_STREAM === "true";
-  configureSolardMeasure(
+  configure(
     streamMeasures
       ? {
           silent: false,
@@ -638,7 +659,7 @@ async function main() {
       listVanityMintPool,
       releaseVanityMintReservation,
       saveMintKeypairFile,
-    } = await import("@solard/sdk");
+    } = await import("@solard/core");
 
     if (values[0] === "pool") {
       const action = values[1] ?? "list";
@@ -816,13 +837,13 @@ async function main() {
       process.env.JITO_BLOCK_ENGINE_URL ??
       "https://mainnet.block-engine.jito.wtf"
     ).replace(/\/$/, "");
-    const { getJitoTipAccounts } = await import("@solard/sdk");
+    const { getJitoTipAccounts } = await import("@solard/core");
     const tipAccounts = await getJitoTipAccounts(endpoint);
     emit(json({ endpoint, tipAccounts }) + "\n");
     return;
   }
   if (command === "metadata" && values[0] === "upload") {
-    const { uploadPumpMetadata } = await import("@solard/sdk");
+    const { uploadPumpMetadata } = await import("@solard/core");
     const uploaded = await uploadPumpMetadata(
       {
         imagePath: need(flags, "image"),
@@ -848,13 +869,13 @@ async function main() {
   }
   const [{ sol, formatRaw }, { shortKey }, { createTraderSolard }] =
     await Promise.all([
-      import("@solard/sdk"),
-      import("@solard/sdk"),
-      import("@solard/sdk"),
+      import("@solard/core"),
+      import("@solard/core"),
+      import("@solard/core"),
     ]);
   const slrd = createTraderSolard();
   try {
-    if (await handleFairfunCommand({ command, values, flags, slrd, emit })) {
+    if (await handleAccountingCommand({ command, values, flags, slrd, emit })) {
       return;
     }
 
@@ -986,11 +1007,8 @@ async function main() {
             (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` +
-            `\nNext:  slrd balances --wallet ${wallet.name}\n` +
-            `Backup: slrd export ${wallet.name} --out .\\${wallet.name}-key.txt\n`,
+            `\nNext:  slrd balances --wallet ${wallet.name}\n`,
         );
       } else {
         emit(`${OWL} created @${wallet.name} ${wallet.address}\n`);
@@ -1612,7 +1630,7 @@ async function main() {
           throw new Error(
             "Provide --uri <metadata_uri> or --image <local_path> --description <text>",
           );
-        const { uploadPumpMetadata } = await import("@solard/sdk");
+        const { uploadPumpMetadata } = await import("@solard/core");
         uploadedMetadata = await uploadPumpMetadata(
           {
             imagePath: need(flags, "image"),
@@ -1864,11 +1882,18 @@ async function main() {
     }
     if (command === "liquidate" && (values[0] ?? "tokens") === "tokens") {
       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,...>] [--burn-unsellable] [--simulate | --live]",
-        );
-      }
+      const exceptWalletValue =
+        flags.get("except-wallet") ?? flags.get("exceptWallet");
+      const exceptWalletsValue =
+        flags.get("except-wallets") ?? flags.get("exceptWallets");
+      if (exceptWalletValue === "true")
+        throw new Error("Missing --except-wallet <wallet>");
+      if (exceptWalletsValue === "true")
+        throw new Error("Missing --except-wallets <a,b,...>");
+      const exceptWalletRefs = [
+        ...(exceptWalletValue ? [exceptWalletValue] : []),
+        ...csv(exceptWalletsValue),
+      ].filter((ref, index, refs) => refs.indexOf(ref) === index);
       if (flags.has("simulate") && flags.has("live")) {
         throw new Error("Use either --simulate or --live, not both");
       }
@@ -1884,6 +1909,10 @@ async function main() {
         const mint = resolveTokenMintForPolicy(slrd, ref);
         emit(`PROTECT  ${ref} -> ${mint}\n`);
       }
+      for (const ref of exceptWalletRefs) {
+        const wallet = slrd.resolveWallet(ref);
+        emit(`EXCLUDE  ${ref} -> ${wallet.address.toBase58()}\n`);
+      }
       emit(
         `RPC      hard limit ${process.env.SLRD_RPC_MAX_RPS ?? "5"} req/s\n`,
       );
@@ -1899,19 +1928,27 @@ async function main() {
           name: string | null;
           amountUi: string;
           kind: string;
+          tokenAccount?: string;
         },
       ) => {
         const label = action.symbol ?? action.name ?? shortKey(action.mint);
+        const account =
+          action.kind === "close-empty" && action.tokenAccount
+            ? flags.has("verbose")
+              ? action.tokenAccount
+              : shortKey(action.tokenAccount)
+            : null;
         emit(
           `${prefix} ${index}/${total}  @${action.walletName}  ` +
             `${action.kind === "unwrap-wsol" ? "WSOL" : label}  ${action.amountUi}` +
-            `${action.kind === "close-empty" ? "  [close empty account]" : ""}\n`,
+            `${action.kind === "close-empty" ? `  [close empty account${account ? ` ${account}` : ""}]` : ""}\n`,
         );
       };
 
       const options = {
         except,
         walletRefs: csv(flags.get("wallets")),
+        exceptWalletRefs,
         slippageBps: int(flags, "slippage-bps", 1500) ?? 1500,
         via: flags.get("sender") ?? "rpc",
         delayMs: int(flags, "delay-ms", 0) ?? 0,
@@ -1941,6 +1978,13 @@ async function main() {
             );
           } else if (event.stage === "action-done") {
             showAction("OK  ", event.index, event.total, event.action);
+          } else if (event.stage === "action-pending") {
+            showAction("WAIT", event.index, event.total, event.action);
+            if (flags.has("verbose")) {
+              emit(
+                `         attempt=${event.attempt}/${event.maxAttempts} signature=${event.signature ?? "-"} ${event.reason}\n`,
+              );
+            }
           } else if (event.stage === "action-error") {
             showAction("FAIL", event.index, event.total, event.action);
             emit(`         ${event.error}\n`);
@@ -1981,7 +2025,7 @@ async function main() {
         }
 
         emit(
-          `KEEP     ${plan.totals.keepProtected} protected SLRD holding(s)\n` +
+          `KEEP     ${plan.totals.keepProtected} protected token holding(s)\n` +
             `SKIP     ${plan.totals.skipUnsupported} unsupported/no-liquidity holding(s)`,
         );
         if (plan.totals.skipUnsupported > 0) {
@@ -2038,13 +2082,43 @@ async function main() {
       return;
     }
 
-    if (command === "sweep" && values[0] === "sol") {
-      const destinationInput = flags.get("to") ?? values[1];
+    if (command === "sweep") {
+      const legacySolSyntax = values[0]?.toLowerCase() === "sol";
+      const positionalDestination = legacySolSyntax ? values[1] : values[0];
+      const extraValues = legacySolSyntax ? values.slice(2) : values.slice(1);
+      if (extraValues.length > 0) {
+        throw new Error(
+          `${sweepUsage()}\nUnexpected argument: ${extraValues[0]}`,
+        );
+      }
+
+      const destinationInput = flags.get("to") ?? positionalDestination;
       if (!destinationInput || destinationInput === "true") {
+        throw new Error(sweepUsage());
+      }
+
+      const below = flags.get("below");
+      const maxBalance = flags.get("max-balance-sol");
+      if (below === "true") {
+        throw new Error(`--below requires a SOL amount.\n${sweepUsage()}`);
+      }
+      if (maxBalance === "true") {
         throw new Error(
-          "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]",
+          `--max-balance-sol requires a SOL amount.\n${sweepUsage()}`,
         );
       }
+      if (
+        below != null &&
+        maxBalance != null &&
+        maxBalance !== "true" &&
+        below !== maxBalance
+      ) {
+        throw new Error("Use either --below or --max-balance-sol, not both.");
+      }
+      const maxBalanceSol = below ?? maxBalance;
+      if (!legacySolSyntax && maxBalanceSol == null) {
+        throw new Error(`--below is required for slrd sweep.\n${sweepUsage()}`);
+      }
 
       const destination = resolveDestinationRef(slrd, destinationInput);
 
@@ -2085,17 +2159,8 @@ async function main() {
           "Use either --keep-if-tokens or --keep-if-token, not both",
         );
       }
-
-      const sweepMode = flags.has("live")
-        ? "LIVE"
-        : flags.has("simulate")
-          ? "SIMULATE"
-          : "PLAN";
-      if (!flags.has("json")) {
-        emit(`SWEEP ${sweepMode}  to=${destination.address}\n`);
-        emit(
-          `RPC      hard limit ${process.env.SLRD_RPC_MAX_RPS ?? "5"} req/s\n`,
-        );
+      if (flags.has("simulate") && flags.has("live")) {
+        throw new Error("Use either --simulate or --live, not both");
       }
 
       const options = {
@@ -2103,7 +2168,7 @@ async function main() {
         excludeGroups,
         excludePrefixes,
         includeWallets: includeWallets.length ? includeWallets : undefined,
-        maxBalanceSol: flags.get("max-balance-sol"),
+        maxBalanceSol,
         keepSolByWallet,
         defaultKeepSol: flags.get("default-keep-sol") ?? "0",
         keepSolIfTokens: flags.get("keep-if-tokens"),
@@ -2117,34 +2182,34 @@ async function main() {
           Math.trunc(int(flags, "rpc-delay-ms", 75) ?? 75),
         ),
         delayMs: int(flags, "delay-ms", 0) ?? 0,
-        onProgress: flags.has("json")
-          ? undefined
-          : (event: any) => {
-              if (event.stage === "plan-start") {
-                emit(`PLAN     ${event.wallets} candidate wallets\n`);
-              } else if (event.stage === "plan-ready") {
-                emit(
-                  `PLAN     ${event.sendWallets}/${event.wallets} will send, ` +
-                    `${formatRaw(event.totalSendLamports, 9)} SOL total\n`,
-                );
-              } else if (event.stage === "wallet-start") {
-                emit(
-                  `SEND     ${event.index}/${event.total}  @${event.row.walletName}  ` +
-                    `${formatRaw(event.row.sendLamports, 9)} SOL\n`,
-                );
-              } else if (event.stage === "wallet-done") {
-                emit(
-                  `OK       ${event.index}/${event.total}  @${event.row.walletName}\n`,
-                );
-              } else if (event.stage === "wallet-error") {
-                emit(
-                  `FAIL     ${event.index}/${event.total}  @${event.row.walletName}  ` +
-                    `${event.error}\n`,
-                );
+        onProgress:
+          !flags.has("json") && flags.has("live")
+            ? (event: any) => {
+                if (event.stage === "wallet-start") {
+                  emit(
+                    `SEND ${event.index}/${event.total}  @${event.row.walletName}  ` +
+                      `${formatRaw(event.row.sendLamports, 9)} SOL\n`,
+                  );
+                } else if (event.stage === "wallet-done") {
+                  emit(
+                    `OK   ${event.index}/${event.total}  @${event.row.walletName}\n`,
+                  );
+                } else if (event.stage === "wallet-error") {
+                  emit(
+                    `FAIL ${event.index}/${event.total}  @${event.row.walletName}  ` +
+                      `${event.error}\n`,
+                  );
+                }
               }
-            },
+            : undefined,
       };
       const plan = await planRegistrySolSweep(slrd, options);
+      const sendRows = plan.rows.filter((row) => row.sendLamports > 0n);
+      const destinationLabel = destination.contactName
+        ? `${destination.contactName} (${plan.destination})`
+        : destination.walletName
+          ? `${destination.walletName} (${plan.destination})`
+          : plan.destination;
 
       const printablePlan = {
         mode: flags.has("live")
@@ -2158,6 +2223,7 @@ async function main() {
           contact: destination.contactName ?? null,
           wallet: destination.walletName ?? null,
         },
+        belowSol: maxBalanceSol ?? null,
         totalSendSol: formatRaw(plan.totalSendLamports, 9),
         rows: plan.rows.map((row) => ({
           wallet: row.walletName,
@@ -2181,36 +2247,33 @@ async function main() {
           return;
         }
 
+        emit(`SWEEP SOL -> ${destinationLabel}\n`);
+        if (maxBalanceSol != null) emit(`Threshold: < ${maxBalanceSol} SOL\n`);
         emit(
-          `SWEEP PLAN  to=${plan.destination}  ` +
-            `send=${formatRaw(plan.totalSendLamports, 9)} SOL  ` +
-            `wallets=${plan.rows.filter((row) => row.sendLamports > 0n).length}/${plan.rows.length}\n`,
+          `Scanned: ${plan.rows.length}  Send: ${sendRows.length}  ` +
+            `Skipped: ${plan.rows.length - sendRows.length}  ` +
+            `Total: ${formatRaw(plan.totalSendLamports, 9)} SOL\n`,
         );
 
         for (const row of plan.rows) {
           if (row.sendLamports <= 0n && !flags.has("show-skipped")) continue;
-          emit(
-            `${row.sendLamports > 0n ? "SEND" : "SKIP"}  ` +
-              `@${row.walletName.padEnd(18)} ` +
-              `balance=${formatRaw(row.balanceLamports, 9).padStart(12)}  ` +
-              `keep=${formatRaw(row.keepLamports, 9).padStart(5)}  ` +
-              `send=${formatRaw(row.sendLamports, 9).padStart(12)}` +
-              `${row.reserveReason === "specific-token" ? "  keep-token=yes" : ""}` +
-              `${row.skippedReason ? `  ${row.skippedReason}` : ""}\n`,
-          );
+          if (row.sendLamports > 0n) {
+            emit(
+              `  @${row.walletName}  ${formatRaw(row.balanceLamports, 9)} -> ` +
+                `${formatRaw(row.sendLamports, 9)} SOL\n`,
+            );
+          } else {
+            emit(
+              `  @${row.walletName}  ${formatRaw(row.balanceLamports, 9)}  ` +
+                `SKIP ${row.skippedReason ?? "not-sendable"}\n`,
+            );
+          }
         }
 
-        emit(
-          `\n${OWL} plan only; no signer was decrypted and nothing was submitted. ` +
-            `Use --json for full details, then --simulate or --live.\n`,
-        );
+        emit(`\nPreview only. Add --simulate to verify or --live to send.\n`);
         return;
       }
 
-      if (flags.has("simulate") && flags.has("live")) {
-        throw new Error("Use either --simulate or --live, not both");
-      }
-
       if (flags.has("simulate")) {
         const results = await simulateRegistrySolSweep(slrd, plan, options);
         if (flags.has("json")) {
@@ -2219,18 +2282,19 @@ async function main() {
           const failed = results.filter(
             (result) => result.error || result.simulation?.success === false,
           ).length;
+          emit(`SWEEP SIMULATION -> ${destinationLabel}\n`);
           emit(
-            `SWEEP SIMULATION  attempted=${results.length}  ` +
-              `ok=${results.length - failed}  failed=${failed}  ` +
-              `to=${plan.destination}\n`,
+            `Attempted: ${results.length}  OK: ${results.length - failed}  ` +
+              `Failed: ${failed}  Total: ${formatRaw(plan.totalSendLamports, 9)} SOL\n`,
           );
           for (const result of results) {
             if (!result.error && result.simulation?.success !== false) continue;
             emit(
-              `FAIL  @${result.row.walletName}  ` +
+              `  FAIL @${result.row.walletName}  ` +
                 `${result.error ?? "simulation failed"}\n`,
             );
           }
+          emit("No transactions submitted.\n");
         }
         return;
       }
@@ -2242,14 +2306,14 @@ async function main() {
         const failed = receipts.filter((result) =>
           Boolean(result.error),
         ).length;
+        emit(`SWEEP COMPLETE -> ${destinationLabel}\n`);
         emit(
-          `SWEEP LIVE  attempted=${receipts.length}  ` +
-            `ok=${receipts.length - failed}  failed=${failed}  ` +
-            `to=${plan.destination}\n`,
+          `Attempted: ${receipts.length}  OK: ${receipts.length - failed}  ` +
+            `Failed: ${failed}  Planned total: ${formatRaw(plan.totalSendLamports, 9)} SOL\n`,
         );
         for (const result of receipts) {
           if (!result.error) continue;
-          emit(`FAIL  @${result.row.walletName}  ${result.error}\n`);
+          emit(`  FAIL @${result.row.walletName}  ${result.error}\n`);
         }
       }
       return;
@@ -2423,23 +2487,84 @@ async function main() {
     }
     if (command === "rewards") {
       const action = values[0] ?? "inspect";
+
+      if (action === "claim-status") {
+        const id = values[1];
+        if (!id)
+          throw new Error("Usage: slrd rewards claim-status <stable-claim-id>");
+        emit(json(slrd.claims.creatorFees.status(id)) + "\n");
+        return;
+      }
+
       const tokenRef = values[1];
       if (!tokenRef)
         throw new Error(
-          "Usage: slrd rewards <inspect|claim> <token|ca> [--wallet <fee-payer>]",
+          "Usage: slrd rewards <inspect|claim|claim-status> <token|ca> [--wallet <fee-payer>]",
         );
 
       if (action === "claim") {
         const wallet = need(flags, "wallet");
-        const receipt = await slrd.claim(tokenRef, wallet, {
+        const basisPath = flags.get("basis");
+        let basis:
+          | {
+              id: string;
+              slot: number;
+              hash: string;
+              observedAtMs?: number | null;
+            }
+          | undefined;
+        if (basisPath && basisPath !== "true") {
+          const { readFileSync } = await import("node:fs");
+          const { resolve } = await import("node:path");
+          const parsed = JSON.parse(
+            readFileSync(resolve(basisPath), "utf8"),
+          ) as Record<string, unknown>;
+          if (!parsed || typeof parsed !== "object" || Array.isArray(parsed))
+            throw new Error("Reward basis file must contain a JSON object");
+          basis = {
+            id: String(parsed.id ?? "").trim(),
+            slot: Number(parsed.slot),
+            hash: String(parsed.hash ?? "").trim(),
+            observedAtMs:
+              parsed.observedAtMs == null ? null : Number(parsed.observedAtMs),
+          };
+        }
+        const result = await slrd.claims.creatorFees.claim(tokenRef, wallet, {
+          id: flags.get("id"),
+          basis,
           via: flags.get("sender") ?? "rpc",
+          skipSimulation: flags.has("skip-simulation"),
+          skipPreflight: flags.has("skip-preflight"),
         });
         emit(
           json({
             action: "claim",
-            token: tokenRef,
-            feePayer: wallet,
-            receipt,
+            claimId: result.claimId,
+            token: result.tokenMint,
+            feePayer: result.feePayer,
+            source: result.source,
+            quote: result.quoteAsset,
+            estimatedClaimRaw: result.estimatedClaimRaw,
+            claimedRaw: result.claimedRaw,
+            claimedUi:
+              result.claimedRaw == null
+                ? null
+                : formatRaw(result.claimedRaw, result.quoteAsset.decimals),
+            payouts: result.payouts,
+            receipt: result.receipt,
+            basis: result.basis,
+            checkpoint:
+              result.claimedRaw == null
+                ? null
+                : {
+                    id: result.claimId ?? result.claimSignature,
+                    claimSignature: result.claimSignature,
+                    slot: result.claimSlot,
+                    claimedRaw: result.claimedRaw,
+                    quoteMint: result.quoteAsset.mint,
+                    observedAtMs: result.observedAtMs,
+                    basis: result.basis,
+                  },
           }) + "\n",
         );
         return;
@@ -2449,24 +2574,27 @@ async function main() {
         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.
-        }
+        } catch {}
         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 payoutAddresses = plan.payouts?.length
+          ? plan.payouts.map((row) => row.address.toBase58())
+          : typeof plan.meta?.payoutAddress === "string"
+            ? [plan.meta.payoutAddress]
+            : token.creator
+              ? [token.creator]
+              : [];
         const payoutAddress =
-          typeof plan.meta?.payoutAddress === "string"
-            ? plan.meta.payoutAddress
-            : token.creator;
+          payoutAddresses.length === 1 ? payoutAddresses[0] : null;
         const output = {
           action: "inspect",
           token: token.mint,
           source: plan.source,
           payoutAddress: payoutAddress ?? null,
+          payoutAddresses,
           quote: {
             kind: plan.quoteAsset.kind,
             mint: plan.quoteAsset.mint.toBase58(),
@@ -2486,7 +2614,7 @@ async function main() {
         return;
       }
 
-      throw new Error("Usage: slrd rewards <inspect|claim> <token|ca>");
+      throw new Error("Usage: slrd rewards <inspect|claim|claim-status> ...");
     }
 
     if (command === "claim") {
@@ -2643,7 +2771,9 @@ async function main() {
       );
       return;
     }
-    throw new Error(`Unknown command: ${command}\n\n${help()}`);
+    throw new Error(
+      `Unknown command: ${command}. Run "slrd help" for available commands.`,
+    );
   } finally {
     slrd.close();
   }

package/src/meteora-commands.ts

@@ -5,7 +5,7 @@ import {
   type MeteoraStrategy,
   type MeteoraTimeframe,
   type Solard,
-} from "@solard/sdk";
+} from "@solard/core";
 
 const WSOL = "So11111111111111111111111111111111111111112";