@solard/cli 0.2.14 → 0.2.15

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@solard/cli",
-  "version": "0.2.14",
+  "version": "0.2.15",
   "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.15",
     "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[];
@@ -319,20 +376,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 +398,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

@@ -421,7 +421,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

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,42 @@ 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();
+    const wallets = probe.db.wallets
+      .select()
+      .orderBy("id", "asc")
+      .all() as Array<{
+      name: string;
+      address: string;
+    }>;
     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 failures: Array<{ name: string; address: string }> = [];
+    let decrypted = 0;
+    for (const wallet of wallets) {
+      try {
+        probe.wallets.signer(wallet.address);
+        decrypted += 1;
+      } catch {
+        failures.push({ name: wallet.name, address: wallet.address });
+      }
+    }
+    if (!failures.length) return;
     clearMasterKey();
-    throw new VaultOnboardingError(
-      "That wallet password could not decrypt the stored wallets.",
+    if (decrypted === 0) {
+      throw new VaultOnboardingError(
+        "That wallet password could not decrypt the stored wallet database.",
+      );
+    }
+    const affected = 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 ${decrypted}/${wallets.length}; undecryptable: ${affected}`,
     );
   } finally {
     probe.close();
@@ -126,9 +159,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 +170,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 +226,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> {