@solard/cli 0.2.37 → 0.2.40

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@solard/cli",
-  "version": "0.2.37",
+  "version": "0.2.40",
   "description": "Command-line interface for the Solard SDK.",
   "type": "module",
   "main": "./src/index.ts",
@@ -19,8 +19,8 @@
   },
   "dependencies": {
     "@solana/web3.js": "^1.98.4",
-    "@solard/core": "0.2.37",
-    "@solard/sdk": "0.2.37",
+    "@solard/core": "0.2.40",
+    "@solard/sdk": "0.2.40",
     "bs58": "^6.0.0",
     "measure-fn": "5.2.0"
   },

package/src/commands/buy.ts

@@ -1,5 +1,7 @@
+import { hasOutputMinimum, parseOutputMinimum } from "./trade-minimum.ts";
 import {
   executeJupiterSwap,
+  minimumBuyOutputForPrice,
   NATIVE_SOL_MINT,
   nativePumpTradeAvailable,
   quoteJupiterSwap,
@@ -74,7 +76,7 @@ export async function runSmartBuyCommand({
 }: RunSmartBuyCommandArgs): Promise<SmartBuyCommandResult> {
   const tokenRef = values[0];
   const usage =
-    "Usage: slrd buy <token|ca> (--wallet <wallet> | --wallets <w1,w2> | --group <group>) --sol <amount> [--venue auto|native|jupiter]";
+    "Usage: slrd buy <token|ca> (--wallet <wallet> | --wallets <w1,w2> | --group <group>) --sol <amount> [--venue auto|native|jupiter] [--max-price-sol <SOL/token>] [--min-out <amount> | --min-out-raw <units> | --slippage-bps N]";
   if (!tokenRef) throw new Error(usage);
 
   const amountSol = flags.get("sol");
@@ -98,6 +100,20 @@ export async function runSmartBuyCommand({
     );
   }
 
+  const maxPriceSol = flags.get("max-price-sol");
+  if (flags.has("max-price-sol") && (!maxPriceSol || maxPriceSol === "true"))
+    throw new Error("--max-price-sol requires a positive SOL price per token");
+  if (maxPriceSol != null && flags.has("slippage-bps"))
+    throw new Error("Use --max-price-sol instead of --slippage-bps");
+  let outputMinimumRaw = parseOutputMinimum(flags, resolution.asset.decimals);
+  if (maxPriceSol != null) {
+    const priceMinimum = minimumBuyOutputForPrice(amount.raw, resolution.asset.decimals, maxPriceSol);
+    if (outputMinimumRaw == null || priceMinimum > outputMinimumRaw) outputMinimumRaw = priceMinimum;
+  }
+  if ((hasOutputMinimum(flags) || maxPriceSol != null) && resolution.route !== "native") {
+    throw new Error("Absolute minimum output is currently supported on native Pump/PumpSwap routes; Jupiter orders do not expose a verified on-chain minimum");
+  }
+
   if (resolution.route === "native") {
     if (!nativePumpTradeAvailable(resolution.token)) {
       throw new Error(
@@ -107,6 +123,8 @@ export async function runSmartBuyCommand({
 
     const options = {
       ...tradeFeeOptions(flags),
+      outputMinimumRaw,
+      maxPriceSol,
       slippageBps: intFlag(flags, "slippage-bps", 1_500),
       via: (flags.get("sender") ?? "rpc") as SenderId,
       skipSimulation: flags.has("skip-simulation"),
@@ -140,6 +158,8 @@ export async function runSmartBuyCommand({
             ...(await slrd.simulatePlan(prepared.plan)),
             priorityMicroLamports: prepared.priorityMicroLamports,
             cuLimit: prepared.plan.draft.cuLimit ?? 600_000,
+            requestedMinimumOutputRaw: outputMinimumRaw?.toString(),
+            guaranteedOutputRaw: prepared.plan.draft.actions.find(action => action.kind === "buy")?.meta?.minOutputRaw,
           };
         }),
       );

package/src/commands/sell.ts

@@ -1,3 +1,4 @@
+import { hasOutputMinimum, parseOutputMinimum } from "./trade-minimum.ts";
 import {
   executeJupiterSwap,
   NATIVE_SOL_MINT,
@@ -118,7 +119,7 @@ export async function runSmartSellCommand({
 }: 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]";
+    "Usage: slrd sell <token|ca> (--wallet <wallet> | --wallets <w1,w2> | --group <group>) [--bps 10000] [--venue auto|native|jupiter] [--min-out <amount> | --min-out-raw <units> | --slippage-bps N]";
   if (!tokenRef) throw new Error(usage);
 
   const bps = intFlag(flags, "bps", 10_000);
@@ -135,6 +136,11 @@ export async function runSmartSellCommand({
     throw new Error("slrd sell expects an SPL token");
   }
 
+  const outputMinimumRaw = parseOutputMinimum(flags, 9);
+  if (hasOutputMinimum(flags) && resolution.route !== "native") {
+    throw new Error("Absolute minimum output is currently supported on native Pump/PumpSwap routes; Jupiter orders do not expose a verified on-chain minimum");
+  }
+
   if (resolution.route === "native") {
     if (!nativePumpTradeAvailable(resolution.token)) {
       throw new Error(
@@ -144,6 +150,7 @@ export async function runSmartSellCommand({
 
     const options = {
       ...tradeFeeOptions(flags),
+      outputMinimumRaw,
       bps,
       slippageBps: intFlag(flags, "slippage-bps", 1_500),
       via: (flags.get("sender") ?? "rpc") as SenderId,
@@ -178,6 +185,8 @@ export async function runSmartSellCommand({
             ...(await slrd.simulatePlan(prepared.plan)),
             priorityMicroLamports: prepared.priorityMicroLamports,
             cuLimit: prepared.plan.draft.cuLimit ?? 600_000,
+            requestedMinimumOutputRaw: outputMinimumRaw?.toString(),
+            guaranteedOutputRaw: prepared.plan.draft.actions.find(action => action.kind === "sell")?.meta?.minOutputRaw,
           };
         }),
       );

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

@@ -0,0 +1,50 @@
+import { expect, test } from "bun:test";
+import { parseOutputMinimum } from "./trade-minimum.ts";
+import { runSmartBuyCommand } from "./buy.ts";
+import { runSmartSellCommand } from "./sell.ts";
+import type { Solard } from "@solard/core";
+import { TOKEN_PROGRAM_ID } from "@solana/spl-token";
+const mint = "E4R6KvcnxvoHYBe872byyCeoyExGHja8n5Vo3JNWodus";
+test("absolute output parsing preserves precision and rejects ambiguous or unsafe input", () => {
+  expect(parseOutputMinimum(new Map([["min-out", "123.000001"]]), 6)).toBe(123000001n);
+  expect(parseOutputMinimum(new Map([["min-out", "0.001"]]), 9)).toBe(1000000n);
+  expect(parseOutputMinimum(new Map([["min-out-raw", "9007199254740993"]]), 6)).toBe(9007199254740993n);
+  for (const value of ["true", "0", "-1", "1e3", "0.0000001", "18446744073709551616"]) {
+    expect(() => parseOutputMinimum(new Map([["min-out", value]]), 6)).toThrow();
+  }
+  expect(() => parseOutputMinimum(new Map([["min-out", "1"], ["slippage-bps", "100"]]), 6)).toThrow();
+  expect(() => parseOutputMinimum(new Map([["min-out", "1"], ["min-out-raw", "1"]]), 6)).toThrow();
+});
+test("CLI buy/sell forward per-wallet absolute output floors in correct units", async () => {
+  const seen: unknown[] = [];
+  const host = {
+    tokens: { list: () => [{ mint, decimals: 6, baseTokenProgram: TOKEN_PROGRAM_ID.toBase58(), venueHint: "pumpswap" }] },
+    buy: async (_mint: unknown, _wallet: unknown, _amount: unknown, options: unknown) => { seen.push(options); },
+    sell: async (_mint: unknown, _wallet: unknown, options: unknown) => { seen.push(options); },
+  } as unknown as Solard;
+  await runSmartBuyCommand({ slrd: host, values: [mint], flags: new Map([["wallet", "test"], ["sol", "0.001"], ["min-out", "123.5"]]) });
+  await runSmartSellCommand({ slrd: host, values: [mint], flags: new Map([["wallet", "test"], ["min-out", "0.001"]]) });
+  expect(seen[0]).toMatchObject({ outputMinimumRaw: 123500000n });
+  expect(seen[1]).toMatchObject({ outputMinimumRaw: 1000000n });
+});
+test("Jupiter absolute-floor requests fail explicitly without signing", async () => {
+  const host = { tokens: { list: () => [] }, signer: () => { throw new Error("SIGNER_ACCESSED"); } } as unknown as Solard;
+  await expect(runSmartBuyCommand({ slrd: host, values: ["USDC"],
+    flags: new Map([["wallet", "test"], ["sol", "0.001"], ["min-out", "1"]]),
+  })).rejects.toThrow("verified on-chain minimum");
+});
+test("maximum buy price derives the on-chain floor and combines with stricter token minima", async () => {
+  const seen: unknown[] = [];
+  const host = {
+    tokens: { list: () => [{ mint, decimals: 6, baseTokenProgram: TOKEN_PROGRAM_ID.toBase58(), venueHint: "pumpswap" }] },
+    buy: async (_mint: unknown, _wallet: unknown, _amount: unknown, options: unknown) => { seen.push(options); },
+  } as unknown as Solard;
+  const flags = new Map([["wallet", "test"], ["sol", "0.1"], ["max-price-sol", "0.0001"]]);
+  await runSmartBuyCommand({ slrd: host, values: [mint], flags });
+  expect(seen[0]).toMatchObject({ maxPriceSol: "0.0001", outputMinimumRaw: 1000000000n });
+  flags.set("min-out", "1100");
+  await runSmartBuyCommand({ slrd: host, values: [mint], flags });
+  expect(seen[1]).toMatchObject({ outputMinimumRaw: 1100000000n });
+  flags.delete("min-out"); flags.set("slippage-bps", "100");
+  await expect(runSmartBuyCommand({ slrd: host, values: [mint], flags })).rejects.toThrow("instead of");
+});

package/src/commands/trade-minimum.ts

@@ -0,0 +1,23 @@
+import type { TradeCommandFlags } from "./trade-venue.ts";
+
+export function hasOutputMinimum(flags: TradeCommandFlags): boolean {
+  return flags.has("min-out") || flags.has("min-out-raw");
+}
+
+export function parseOutputMinimum(flags: TradeCommandFlags, decimals: number): bigint | undefined {
+  if (!hasOutputMinimum(flags)) return undefined;
+  if (flags.has("slippage-bps")) throw new Error("Use --min-out or --min-out-raw instead of --slippage-bps");
+  if (flags.has("min-out") && flags.has("min-out-raw")) throw new Error("Choose --min-out or --min-out-raw");
+  const raw = flags.has("min-out-raw");
+  const value = flags.get(raw ? "min-out-raw" : "min-out") ?? "";
+  if (!Number.isSafeInteger(decimals) || decimals < 0 || decimals > 255)
+    throw new Error("Output mint decimals unavailable");
+  if (!(raw ? /^\d+$/ : /^\d+(?:\.\d+)?$/).test(value))
+    throw new Error("Minimum output must be a positive decimal amount (integer for --min-out-raw)");
+  const [whole, fraction = ""] = value.split(".");
+  if (!raw && fraction.length > decimals) throw new Error(`Minimum output supports at most ${decimals} decimal places`);
+  const amount = raw ? BigInt(value)
+    : BigInt(whole!) * 10n ** BigInt(decimals) + BigInt(fraction.padEnd(decimals, "0") || "0");
+  if (amount <= 0n || amount > 0xffffffffffffffffn) throw new Error("Minimum output must be a positive u64");
+  return amount;
+}