@solard/cli 0.2.12 → 0.2.14

package/src/commands/sell.ts

@@ -0,0 +1,239 @@
+import {
+  executeJupiterSwap,
+  NATIVE_SOL_MINT,
+  nativePumpTradeAvailable,
+  quoteJupiterSwap,
+  resolveTradeRoute,
+  type SenderId,
+  type Solard,
+} from "@solard/sdk";
+
+import { resolveTradeTargets, type TradeTargets } from "./trade-targets.ts";
+import { summarizeTradeRoute, type TradeRouteSummary } from "./trade-result.ts";
+import { parseVenuePreference, type TradeCommandFlags } from "./trade-venue.ts";
+
+export type JupiterSellWalletPlan = {
+  wallet: string;
+  balanceRaw: bigint;
+  amountRaw: bigint;
+};
+
+export type SmartSellCommandResult =
+  | {
+      mode: "simulation";
+      route: "native";
+      target: TradeTargets;
+      routing: TradeRouteSummary;
+      results: unknown[];
+    }
+  | {
+      mode: "quote";
+      route: "jupiter";
+      target: TradeTargets;
+      routing: TradeRouteSummary;
+      plans: Array<
+        JupiterSellWalletPlan & {
+          quote: Awaited<ReturnType<typeof quoteJupiterSwap>>;
+        }
+      >;
+      hint: string;
+    }
+  | {
+      mode: "live";
+      route: "native";
+      target: TradeTargets;
+      routing: TradeRouteSummary;
+      receipts: unknown;
+    }
+  | {
+      mode: "live";
+      route: "jupiter";
+      target: TradeTargets;
+      routing: TradeRouteSummary;
+      results: Array<
+        JupiterSellWalletPlan & {
+          result: Awaited<ReturnType<typeof executeJupiterSwap>>;
+        }
+      >;
+    };
+
+type RunSmartSellCommandArgs = {
+  slrd: Solard;
+  values: string[];
+  flags: TradeCommandFlags;
+};
+
+function intFlag(
+  flags: TradeCommandFlags,
+  key: string,
+  fallback: number,
+): number {
+  const value = flags.get(key);
+  if (!value || value === "true") return fallback;
+  const parsed = Number(value);
+  if (!Number.isInteger(parsed)) throw new Error(`--${key} must be an integer`);
+  return parsed;
+}
+
+export async function jupiterSellableAtaBalance(
+  slrd: Solard,
+  walletRef: string,
+  mint: string,
+): Promise<bigint> {
+  const accounts = await slrd.tokenAccounts(walletRef);
+  let associatedRaw = 0n;
+
+  for (const account of accounts) {
+    if (
+      account.mint === mint &&
+      account.isAssociated &&
+      account.amountRaw > 0n
+    ) {
+      associatedRaw += account.amountRaw;
+    }
+  }
+
+  return associatedRaw;
+}
+
+async function jupiterSellPlan(
+  slrd: Solard,
+  wallet: string,
+  mint: string,
+  bps: number,
+): Promise<JupiterSellWalletPlan> {
+  const balanceRaw = await jupiterSellableAtaBalance(slrd, wallet, mint);
+  const amountRaw = (balanceRaw * BigInt(bps)) / 10_000n;
+  if (amountRaw <= 0n) {
+    throw new Error(`No sellable associated-token-account balance for ${mint}`);
+  }
+  return { wallet, balanceRaw, amountRaw };
+}
+
+export async function runSmartSellCommand({
+  slrd,
+  values,
+  flags,
+}: RunSmartSellCommandArgs): Promise<SmartSellCommandResult> {
+  const tokenRef = values[0];
+  const usage =
+    "Usage: slrd sell <token|ca> (--wallet <wallet> | --wallets <w1,w2> | --group <group>) [--bps 10000] [--venue auto|native|jupiter]";
+  if (!tokenRef) throw new Error(usage);
+
+  const bps = intFlag(flags, "bps", 10_000);
+  if (bps <= 0 || bps > 10_000) throw new Error("--bps must be 1..10000");
+
+  const target = resolveTradeTargets(slrd, flags, usage);
+  const resolution = await resolveTradeRoute(
+    slrd,
+    tokenRef,
+    parseVenuePreference(flags),
+  );
+
+  if (resolution.asset.mint === NATIVE_SOL_MINT) {
+    throw new Error("slrd sell expects an SPL token");
+  }
+
+  if (resolution.route === "native") {
+    if (!nativePumpTradeAvailable(resolution.token)) {
+      throw new Error(
+        "Native sell requires a registered Pump/PumpSwap token; use --venue jupiter for ordinary SPL assets",
+      );
+    }
+
+    const options = {
+      bps,
+      slippageBps: intFlag(flags, "slippage-bps", 1_500),
+      via: (flags.get("sender") ?? "rpc") as SenderId,
+      skipSimulation: flags.has("skip-simulation"),
+      skipPreflight:
+        flags.has("skip-preflight") || flags.has("skip-simulation"),
+    };
+
+    if (flags.has("simulate-only")) {
+      const plans =
+        target.refs.length === 1
+          ? [
+              await slrd
+                .tx(target.refs[0]!)
+                .sell(resolution.token!.mint, options)
+                .build(),
+            ]
+          : await slrd
+              .composeMany(target.refs)
+              .sell(resolution.token!.mint, options)
+              .build();
+      const results = await Promise.all(
+        plans.map((plan) => slrd.simulatePlan(plan)),
+      );
+      return {
+        mode: "simulation",
+        route: "native",
+        target,
+        routing: summarizeTradeRoute(resolution),
+        results,
+      };
+    }
+
+    const receipts =
+      target.refs.length === 1
+        ? await slrd.sell(resolution.token!.mint, target.refs[0]!, options)
+        : await slrd.sellMany(resolution.token!.mint, target.refs, options);
+
+    return {
+      mode: "live",
+      route: "native",
+      target,
+      routing: summarizeTradeRoute(resolution),
+      receipts,
+    };
+  }
+
+  const plans: JupiterSellWalletPlan[] = [];
+  for (const wallet of target.refs) {
+    plans.push(await jupiterSellPlan(slrd, wallet, resolution.asset.mint, bps));
+  }
+
+  if (flags.has("simulate-only")) {
+    const quoted = [];
+    for (const plan of plans) {
+      quoted.push({
+        ...plan,
+        quote: await quoteJupiterSwap({
+          inputMint: resolution.asset.mint,
+          outputMint: NATIVE_SOL_MINT,
+          amountRaw: plan.amountRaw,
+        }),
+      });
+    }
+    return {
+      mode: "quote",
+      route: "jupiter",
+      target,
+      routing: summarizeTradeRoute(resolution),
+      plans: quoted,
+      hint: "Remove --simulate-only to execute these Jupiter-routed sells.",
+    };
+  }
+
+  const results = [];
+  for (const plan of plans) {
+    results.push({
+      ...plan,
+      result: await executeJupiterSwap({
+        inputMint: resolution.asset.mint,
+        outputMint: NATIVE_SOL_MINT,
+        amountRaw: plan.amountRaw,
+        signer: slrd.signer(plan.wallet),
+      }),
+    });
+  }
+
+  return {
+    mode: "live",
+    route: "jupiter",
+    target,
+    routing: summarizeTradeRoute(resolution),
+    results,
+  };
+}

package/src/commands/trade-result.ts

@@ -0,0 +1,19 @@
+import type { TradeAsset, TradeRoute, TradeRouteResolution } from "@solard/sdk";
+
+export type TradeRouteSummary = {
+  route: TradeRoute;
+  asset: TradeAsset;
+  registered: boolean;
+  venue: string | null;
+};
+
+export function summarizeTradeRoute(
+  resolution: TradeRouteResolution,
+): TradeRouteSummary {
+  return {
+    route: resolution.route,
+    asset: resolution.asset,
+    registered: resolution.token !== null,
+    venue: resolution.token?.venueHint ?? null,
+  };
+}

package/src/commands/trade-targets.ts

@@ -0,0 +1,43 @@
+import type { Solard } from "@solard/sdk";
+import type { TradeCommandFlags } from "./trade-venue.ts";
+
+export type TradeTargets = {
+  mode: "wallet" | "wallets" | "group";
+  refs: string[];
+  group?: string;
+};
+
+function csv(value: string | undefined): string[] {
+  return (value ?? "")
+    .split(",")
+    .map((item) => item.trim())
+    .filter(Boolean);
+}
+
+export function resolveTradeTargets(
+  slrd: Pick<Solard, "groupWallets">,
+  flags: TradeCommandFlags,
+  usage: string,
+): TradeTargets {
+  const wallet = flags.get("wallet");
+  const wallets = csv(flags.get("wallets"));
+  const group = flags.get("group");
+  const selected = [Boolean(wallet), wallets.length > 0, Boolean(group)].filter(
+    Boolean,
+  ).length;
+
+  if (selected !== 1) {
+    throw new Error(
+      `${usage} Supply exactly one of --wallet, --wallets, or --group.`,
+    );
+  }
+
+  if (wallet) return { mode: "wallet", refs: [wallet] };
+  if (wallets.length > 0) return { mode: "wallets", refs: wallets };
+
+  return {
+    mode: "group",
+    refs: slrd.groupWallets(group!).map((ref) => String(ref)),
+    group,
+  };
+}

package/src/commands/trade-venue.test.ts

@@ -0,0 +1,32 @@
+import { describe, expect, test } from "bun:test";
+import { parseVenuePreference } from "./trade-venue.ts";
+
+function flags(input: Record<string, string>): ReadonlyMap<string, string> {
+  return new Map(Object.entries(input));
+}
+
+describe("parseVenuePreference", () => {
+  test("defaults to auto", () => {
+    expect(parseVenuePreference(flags({}))).toBe("auto");
+  });
+
+  test("parses --venue", () => {
+    expect(parseVenuePreference(flags({ venue: "native" }))).toBe("native");
+    expect(parseVenuePreference(flags({ venue: "JUPITER" }))).toBe("jupiter");
+  });
+
+  test("legacy shortcut flags override --venue", () => {
+    expect(
+      parseVenuePreference(flags({ venue: "native", jupiter: "true" })),
+    ).toBe("jupiter");
+    expect(
+      parseVenuePreference(flags({ venue: "jupiter", native: "true" })),
+    ).toBe("native");
+  });
+
+  test("rejects invalid venue", () => {
+    expect(() => parseVenuePreference(flags({ venue: "raydium" }))).toThrow(
+      "--venue must be auto, native, or jupiter",
+    );
+  });
+});

package/src/commands/trade-venue.ts

@@ -0,0 +1,19 @@
+import type { VenuePreference } from "@solard/sdk";
+
+export type TradeCommandFlags = ReadonlyMap<string, string>;
+
+export function parseVenuePreference(
+  flags: TradeCommandFlags,
+): VenuePreference {
+  const value = flags.has("jupiter")
+    ? "jupiter"
+    : flags.has("native")
+      ? "native"
+      : (flags.get("venue") ?? "auto").toLowerCase();
+
+  if (value !== "auto" && value !== "native" && value !== "jupiter") {
+    throw new Error("--venue must be auto, native, or jupiter");
+  }
+
+  return value;
+}

package/src/commands/transfer.ts

@@ -0,0 +1,200 @@
+import { PublicKey } from "@solana/web3.js";
+import {
+  readMint,
+  sol,
+  tokenAmount,
+  transferTokenIxs,
+  type SenderId,
+  type Solard,
+} from "@solard/sdk";
+
+import { resolveDestinationRef } from "../refs.ts";
+
+const CANONICAL_USDC_MINT = "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v";
+
+export type TransferCliFlags = ReadonlyMap<string, string>;
+
+type RunTransferCommandArgs = {
+  slrd: Solard;
+  values: string[];
+  flags: TransferCliFlags;
+};
+
+function requiredFlag(flags: TransferCliFlags, key: string): string {
+  const value = flags.get(key);
+  if (!value || value === "true") {
+    throw new Error(`Missing --${key} <value>`);
+  }
+  return value;
+}
+
+function senderId(flags: TransferCliFlags): SenderId {
+  const value = flags.get("sender") ?? "rpc";
+  if (value !== "rpc" && value !== "helius" && value !== "jito") {
+    throw new Error(`Invalid --sender: ${value}`);
+  }
+  return value;
+}
+
+function nonNegativeInteger(
+  flags: TransferCliFlags,
+  key: string,
+  fallback: number,
+): number {
+  const raw = flags.get(key);
+  const value = raw == null ? fallback : Number(raw);
+  if (!Number.isInteger(value) || value < 0) {
+    throw new Error(`--${key} must be a non-negative integer`);
+  }
+  return value;
+}
+
+function positiveInteger(
+  flags: TransferCliFlags,
+  key: string,
+  fallback: number,
+): number {
+  const value = nonNegativeInteger(flags, key, fallback);
+  if (value <= 0) throw new Error(`--${key} must be a positive integer`);
+  return value;
+}
+
+export async function runTransferCommand({
+  slrd,
+  values,
+  flags,
+}: RunTransferCommandArgs): Promise<Record<string, unknown>> {
+  const recipientInput = values[0] === "sol" ? values[1] : values[0];
+  if (!recipientInput) {
+    throw new Error(
+      "Usage: slrd transfer <contact|wallet|address> --wallet <wallet> (--sol <amount> | --token <USDC|mint> --amount <ui>) [--sender rpc|helius|jito] [--simulate-only]",
+    );
+  }
+
+  const recipient = resolveDestinationRef(slrd, recipientInput);
+  const wallet = requiredFlag(flags, "wallet");
+  const via = senderId(flags);
+  const tokenRef = flags.get("token")?.trim();
+  const solValue = flags.get("sol")?.trim();
+
+  if (Boolean(tokenRef) === Boolean(solValue)) {
+    throw new Error(
+      "Transfer requires exactly one of --sol <amount> or --token <USDC|mint> --amount <ui>",
+    );
+  }
+
+  const cuLimit = positiveInteger(
+    flags,
+    "cu-limit",
+    tokenRef ? 30_000 : 10_000,
+  );
+  const priorityMicroLamports = nonNegativeInteger(
+    flags,
+    "priority-micro-lamports",
+    0,
+  );
+
+  if (tokenRef) {
+    const amountUi = requiredFlag(flags, "amount");
+    const normalizedToken = tokenRef.replace(/^\$/, "").trim();
+    const isUsdc = normalizedToken.toUpperCase() === "USDC";
+    const mint = new PublicKey(isUsdc ? CANONICAL_USDC_MINT : normalizedToken);
+    const mintState = await readMint(slrd.connection(), mint, slrd.cache);
+    const amountRaw = tokenAmount(
+      amountUi,
+      mint,
+      mintState.decimals,
+      mintState.tokenProgram,
+    ).raw;
+    if (amountRaw <= 0n) {
+      throw new Error("Token transfer amount must be greater than zero");
+    }
+
+    const owner = slrd.signer(wallet).publicKey;
+    const destinationOwner = new PublicKey(recipient.address);
+    const transfer = transferTokenIxs({
+      payer: owner,
+      owner,
+      recipient: destinationOwner,
+      mint,
+      amountRaw,
+      decimals: mintState.decimals,
+      tokenProgram: mintState.tokenProgram,
+    });
+
+    const composer = slrd
+      .tx(wallet)
+      .addMany(transfer.instructions, {
+        kind: "transfer-token",
+        mint,
+        recipient: destinationOwner,
+        meta: { raw: amountRaw.toString() },
+      })
+      .track({
+        address: transfer.destination,
+        kind: "token",
+        mint,
+      })
+      .priorityFee({ cuLimit, microLamports: priorityMicroLamports });
+
+    if (flags.has("simulate-only")) {
+      const result = await slrd.simulatePlan(await composer.build());
+      return {
+        mode: "simulation",
+        wallet,
+        recipient,
+        token: isUsdc ? "USDC" : mint.toBase58(),
+        mint: mint.toBase58(),
+        amount: amountUi,
+        decimals: mintState.decimals,
+        amountRaw,
+        result,
+      };
+    }
+
+    const receipt = await composer.send({
+      via,
+      kind: "transfer-token",
+      skipSimulation: flags.has("skip-simulation"),
+      skipPreflight:
+        flags.has("skip-preflight") || flags.has("skip-simulation"),
+    });
+
+    return {
+      ...receipt,
+      wallet,
+      recipient,
+      token: isUsdc ? "USDC" : mint.toBase58(),
+      mint: mint.toBase58(),
+      amount: amountUi,
+      decimals: mintState.decimals,
+      amountRaw,
+    };
+  }
+
+  const amount = solValue!;
+  const composer = slrd
+    .tx(wallet)
+    .transferSol(recipient.address, sol(amount))
+    .priorityFee({ cuLimit, microLamports: priorityMicroLamports });
+
+  if (flags.has("simulate-only")) {
+    const result = await slrd.simulatePlan(await composer.build());
+    return {
+      mode: "simulation",
+      wallet,
+      recipient,
+      sol: amount,
+      result,
+    };
+  }
+
+  const receipt = await composer.send({
+    via,
+    kind: "transfer-sol",
+    skipSimulation: flags.has("skip-simulation"),
+    skipPreflight: flags.has("skip-preflight") || flags.has("skip-simulation"),
+  });
+
+  return { ...receipt, recipient };
+}