@solard/cli 0.2.16 → 0.2.19

package/src/commands/trade-result.ts

@@ -1,4 +1,8 @@
-import type { TradeAsset, TradeRoute, TradeRouteResolution } from "@solard/sdk";
+import type {
+  TradeAsset,
+  TradeRoute,
+  TradeRouteResolution,
+} from "@solard/core";
 
 export type TradeRouteSummary = {
   route: TradeRoute;

package/src/commands/trade-targets.ts

@@ -1,4 +1,4 @@
-import type { Solard } from "@solard/sdk";
+import type { Solard } from "@solard/core";
 import type { TradeCommandFlags } from "./trade-venue.ts";
 
 export type TradeTargets = {

package/src/commands/trade-venue.ts

@@ -1,4 +1,4 @@
-import type { VenuePreference } from "@solard/sdk";
+import type { VenuePreference } from "@solard/core";
 
 export type TradeCommandFlags = ReadonlyMap<string, string>;
 

package/src/commands/transfer.ts

@@ -6,7 +6,7 @@ import {
   transferTokenIxs,
   type SenderId,
   type Solard,
-} from "@solard/sdk";
+} from "@solard/core";
 
 import { resolveDestinationRef } from "../refs.ts";
 

package/src/fairfun-commands.ts

@@ -1,6 +1,12 @@
 import { readFileSync } from "node:fs";
 import { PublicKey } from "@solana/web3.js";
-import type { HolderRewardEntitlementSnapshotInput, Solard } from "@solard/sdk";
+import type { Solard } from "@solard/core";
+
+type FairfunEntitlementSnapshot = {
+  recipients: Array<{ wallet: string; entitledRaw: string }>;
+  totalEntitledRaw?: string;
+  observedAtMs: number | null;
+};
 
 export type FairfunCliFlags = Map<string, string>;
 type Emit = (value: string) => void;
@@ -8,7 +14,12 @@ type Emit = (value: string) => void;
 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,
   );
 }
@@ -110,26 +121,26 @@ function allocationsFile(
   });
 }
 
-function rewardSnapshotFile(
-  path: string,
-): HolderRewardEntitlementSnapshotInput {
+function rewardSnapshotFile(path: string): FairfunEntitlementSnapshot {
   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) => {
+  const rows = Array.isArray(parsed) ? parsed : parsed?.recipients;
+  if (!Array.isArray(rows))
+    throw new Error(
+      "Reward snapshot must be a JSON array or { recipients: [...] }",
+    );
+  const recipients = rows.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();
+    const wallet = String(row.wallet ?? row.address ?? "").trim();
+    const entitledRaw = String(
+      row.entitledRaw ??
+        row.accumulatedRewardRaw ??
+        row.accumulatedRaw ??
+        row.rewardRaw ??
+        "",
+    ).trim();
     if (!wallet)
       throw new Error(`Reward snapshot recipient ${index + 1} requires wallet`);
     if (!/^\d+$/.test(entitledRaw))
@@ -141,11 +152,17 @@ function rewardSnapshotFile(
       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 totalInput = Array.isArray(parsed)
+    ? undefined
+    : (parsed.totalEntitledRaw ?? parsed.totalRewardRaw ?? undefined);
+  const totalEntitledRaw =
+    totalInput == null ? undefined : String(totalInput).trim();
+  if (totalEntitledRaw != null && !/^\d+$/.test(totalEntitledRaw))
+    throw new Error("Reward snapshot totalEntitledRaw must be a raw integer");
   const observedAtMs =
-    parsed.observedAtMs == null ? null : Number(parsed.observedAtMs);
+    Array.isArray(parsed) || parsed.observedAtMs == null
+      ? null
+      : Number(parsed.observedAtMs);
   if (
     observedAtMs != null &&
     (!Number.isFinite(observedAtMs) || observedAtMs < 0)
@@ -153,18 +170,7 @@ function rewardSnapshotFile(
     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,
-  };
+  return { recipients, totalEntitledRaw, observedAtMs };
 }
 
 export async function handleFairfunCommand(args: {
@@ -212,6 +218,59 @@ export async function handleFairfunCommand(args: {
     return true;
   }
 
+  if (command === "events" && values[0] === "history") {
+    const ref = values[1];
+    if (!ref)
+      throw new Error(
+        "Usage: slrd events history <token|ca> [--provider auto|solscan|rpc] [--from-slot N] [--to-slot N] [--slot-order] [--json|--jsonl]",
+      );
+    const token = await ensureToken(slrd, ref);
+    const provider = flag(flags, "provider") ?? "auto";
+    if (!new Set(["auto", "solscan", "rpc"]).has(provider))
+      throw new Error("--provider must be auto, solscan, or rpc");
+    const history = await slrd.events.history(token.mint, {
+      provider: provider as "auto" | "solscan" | "rpc",
+      fromSlot: nonNegativeInteger(flag(flags, "from-slot")),
+      toSlot: nonNegativeInteger(flag(flags, "to-slot")),
+      maxPages: positiveInteger(flag(flags, "max-pages")),
+      exactOrdering: !bool(flags, "slot-order"),
+      verifyCurrentBalances: !bool(flags, "no-verify"),
+      commitment: bool(flags, "confirmed") ? "confirmed" : "finalized",
+    });
+    if (bool(flags, "json")) {
+      emit(json({ coverage: history.coverage, events: history.events }) + "\n");
+      return true;
+    }
+    if (bool(flags, "jsonl")) {
+      for (const event of history.events) {
+        emit(
+          JSON.stringify(event, (_, item) =>
+            typeof item === "bigint" ? item.toString() : item,
+          ) + "\n",
+        );
+      }
+      emit(JSON.stringify({ type: "coverage", ...history.coverage }) + "\n");
+      return true;
+    }
+    emit(
+      `EVENT HISTORY  ${history.mint}\n` +
+        `provider=${history.coverage.provider} coverage=${history.coverage.status} transfer-coverage=${history.coverage.transferCoverage} from-creation=${history.coverage.fromCreation} authoritative=${history.coverage.authoritativeForBalanceReplay}\n` +
+        `events=${history.events.length} slots=${history.coverage.firstEventSlot ?? "?"}..${history.coverage.lastEventSlot ?? "?"} ordering=${history.coverage.ordering}\n` +
+        `balance-check=${history.coverage.balanceVerification.matches == null ? "not-checked" : history.coverage.balanceVerification.matches ? "match" : "MISMATCH"}\n\n`,
+    );
+    for (const event of history.events) {
+      emit(
+        `${new Date(event.blockTimeMs ?? event.observedAtMs).toISOString()}  ${event.movement.toUpperCase()} ${event.amountRaw} ` +
+          `${event.sourceOwner ?? "MINT"} -> ${event.destinationOwner ?? "BURN"} slot=${event.slot} tx=${event.transactionIndex ?? "?"} sig=${event.signature}\n`,
+      );
+    }
+    if (history.coverage.warnings.length) {
+      emit("\nWARNINGS\n");
+      for (const warning of history.coverage.warnings) emit(`- ${warning}\n`);
+    }
+    return true;
+  }
+
   if (command === "events") {
     const ref = values[0];
     if (!ref)
@@ -283,7 +342,7 @@ export async function handleFairfunCommand(args: {
           );
         } else {
           emit(
-            `${new Date(event.blockTimeMs ?? event.observedAtMs).toISOString()}  TRANSFER ${event.amountRaw} ` +
+            `${new Date(event.blockTimeMs ?? event.observedAtMs).toISOString()}  ${event.movement.toUpperCase()} ${event.amountRaw} ` +
               `${event.sourceOwner ?? event.sourceTokenAccount} -> ${event.destinationOwner ?? event.destinationTokenAccount} sig=${event.signature}\n`,
           );
         }
@@ -393,46 +452,145 @@ export async function handleFairfunCommand(args: {
     return true;
   }
 
+  if (command === "rewards" && values[0] === "history") {
+    const ref = values[1];
+    if (!ref)
+      throw new Error(
+        "Usage: slrd rewards history <token|ca> [--wallet <reward-recipient>] [--provider auto|solscan|rpc] [--json|--jsonl]",
+      );
+    for (const key of [
+      "from-slot",
+      "to-slot",
+      "slot-order",
+      "no-verify",
+      "confirmed",
+    ]) {
+      if (flags.has(key)) {
+        throw new Error(
+          `--${key} is not supported by persistent replay; use slrd events history for bounded diagnostic history`,
+        );
+      }
+    }
+    const token = await ensureToken(slrd, ref);
+    const provider = flag(flags, "provider") ?? "auto";
+    if (!new Set(["auto", "solscan", "rpc"]).has(provider))
+      throw new Error("--provider must be auto, solscan, or rpc");
+    const history = await slrd.history.replay(token.mint, {
+      recipient: flag(flags, "wallet"),
+      provider: provider as "auto" | "solscan" | "rpc",
+      maxPages: positiveInteger(flag(flags, "max-pages")),
+      claimMaxPages: positiveInteger(flag(flags, "claim-max-pages")),
+    });
+    if (bool(flags, "json")) {
+      emit(
+        json({
+          mint: history.mint,
+          coverage: history.coverage,
+          items: history.items,
+        }) + "\n",
+      );
+      return true;
+    }
+    if (bool(flags, "jsonl")) {
+      for (const item of history.items) emit(json(item) + "\n");
+      emit(json({ type: "coverage", replay: history.coverage }) + "\n");
+      return true;
+    }
+    const transfers = history.items.filter((item) => item.trx !== "claim");
+    const claims = history.items.filter((item) => item.trx === "claim");
+    emit(
+      `REPLAY HISTORY  ${history.mint}\n` +
+        `recipient=${"-"} authoritative=${history.coverage.complete} transfers=${transfers.length} claims=${claims.length} finalizedThroughSlot=${history.coverage.throughSlot}\n\n`,
+    );
+    for (const item of history.items) {
+      const event = item.raw;
+      if (event.type === "claim") {
+        emit(
+          `${new Date(event.blockTimeMs ?? event.observedAtMs).toISOString()}  CLAIM ${event.payout.amountRaw} ${event.payout.assetMint} attribution=${event.attribution} slot=${item.slot} tx=${item.transactionIndex ?? "?"} sig=${item.signature}\n`,
+        );
+      } else {
+        emit(
+          `${new Date(event.blockTimeMs ?? event.observedAtMs).toISOString()}  ${event.movement.toUpperCase()} ${event.amountRaw} ${event.sourceOwner ?? "MINT"} -> ${event.destinationOwner ?? "BURN"} slot=${item.slot} tx=${item.transactionIndex ?? "?"} sig=${item.signature}\n`,
+        );
+      }
+    }
+    if (history.coverage.warnings.length) {
+      emit("\nWARNINGS\n");
+      for (const warning of history.coverage.warnings) emit(`- ${warning}\n`);
+    }
+    return true;
+  }
+
   if (command === "rewards" && values[0] === "status") {
-    const id = values[1];
-    if (!id) throw new Error("Usage: slrd rewards status <distribution-id>");
-    const { getHolderRewardDistributionState } = await import("@solard/sdk");
-    emit(json(getHolderRewardDistributionState(slrd, id)) + "\n");
+    const ref = values[1];
+    if (!ref) throw new Error("Usage: slrd rewards status <token|ca>");
+    const token = await ensureToken(slrd, ref);
+    emit(json(slrd.distributions.status(`fairfun:${token.mint}`)) + "\n");
     return true;
   }
 
+  if (command === "rewards" && values[0] === "audit") {
+    const ref = values[1];
+    if (!ref)
+      throw new Error(
+        "Usage: slrd rewards audit <token|ca> [--holder <wallet>]",
+      );
+    const token = await ensureToken(slrd, ref);
+    const state = slrd.distributions.status(`fairfun:${token.mint}`);
+    const holder = flag(flags, "holder");
+    emit(
+      json(
+        holder && state
+          ? {
+              ...state,
+              recipients: state.recipients.filter(
+                (row) => row.recipient === holder,
+              ),
+            }
+          : state,
+      ) + "\n",
+    );
+    return true;
+  }
+
+  if (command === "rewards" && values[0] === "stop") {
+    const ref = values[1];
+    if (!ref) throw new Error("Usage: slrd rewards stop <token|ca>");
+    const token = await ensureToken(slrd, ref);
+    throw new Error(
+      `Distribution ${`fairfun:${token.mint}`} has no process-level stop state; stop the supervising process instead.`,
+    );
+  }
+
   if (command === "rewards" && values[0] === "distribute") {
     const ref = values[1];
     const wallet = flag(flags, "wallet");
-    const id = flag(flags, "id");
     const snapshotPath = flag(flags, "snapshot");
-    if (!ref || !wallet || !id || !snapshotPath)
+    if (!ref || !wallet || !snapshotPath)
       throw new Error(
-        "Usage: slrd rewards distribute <token|ca> --wallet <beneficiary> --id <ledger-id> --snapshot <snapshot.json> [--reward-mint <mint>] [--reserve-raw N] [--live]",
+        "Usage: slrd rewards distribute <token|ca> --wallet <beneficiary> --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"),
-      snapshot,
+      id: flag(flags, "id") ?? `fairfun:${token.mint}`,
+      from: wallet,
+      asset: flag(flags, "reward-mint") ?? token.quoteMint ?? "SOL",
+      entitlements: snapshot.recipients.map((row) => ({
+        recipient: row.wallet,
+        entitledRaw: row.entitledRaw,
+      })),
       reserveRaw: raw(flag(flags, "reserve-raw"), "--reserve-raw") ?? 0n,
       maxRecipientsPerTransaction: positiveInteger(flag(flags, "max-per-tx")),
     };
     if (!bool(flags, "live")) {
-      const plan = await slrd.planHolderRewards(common);
+      const plan = await slrd.distributions.plan(common);
       emit(
         json({
           live: false,
-          version: plan.version,
           id: plan.id,
-          snapshotId: plan.snapshotId,
-          tokenMint: plan.tokenMint,
           sourceWallet: plan.sourceWallet,
-          rewardAsset: plan.rewardAsset,
-          totalClaimedRaw: plan.totalClaimedRaw,
+          asset: plan.asset,
           totalEntitledRaw: plan.totalEntitledRaw,
           totalConfirmedPaidRaw: plan.totalConfirmedPaidRaw,
           totalOutstandingRaw: plan.totalOutstandingRaw,
@@ -441,21 +599,15 @@ export async function handleFairfunCommand(args: {
           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,
-              }
+          nextBatch: plan.nextPayments.length
+            ? { payments: plan.nextPayments }
             : null,
         }) + "\n",
       );
       return true;
     }
     requireLiveGate();
-    const state = await slrd.distributeHolderRewards({
+    const state = await slrd.distributions.execute({
       ...common,
       via: flag(flags, "sender") ?? "rpc",
       skipSimulation: bool(flags, "skip-simulation"),