@solard/cli 0.2.33 → 0.2.40

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@solard/cli",
-  "version": "0.2.33",
+  "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.33",
-    "@solard/sdk": "0.2.33",
+    "@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"),
@@ -131,10 +149,18 @@ export async function runSmartBuyCommand({
               .build();
       const results = await Promise.all(
         plans.map(async (plan, index) => {
-          const prepared = await slrd.prepareTradePlan(target.refs[index]!, plan, options);
-          return { ...await slrd.simulatePlan(prepared.plan),
+          const prepared = await slrd.prepareTradePlan(
+            target.refs[index]!,
+            plan,
+            options,
+          );
+          return {
+            ...(await slrd.simulatePlan(prepared.plan)),
             priorityMicroLamports: prepared.priorityMicroLamports,
-            cuLimit: prepared.plan.draft.cuLimit ?? 600_000 };
+            cuLimit: prepared.plan.draft.cuLimit ?? 600_000,
+            requestedMinimumOutputRaw: outputMinimumRaw?.toString(),
+            guaranteedOutputRaw: prepared.plan.draft.actions.find(action => action.kind === "buy")?.meta?.minOutputRaw,
+          };
         }),
       );
       return {

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,
@@ -169,10 +176,18 @@ export async function runSmartSellCommand({
               .build();
       const results = await Promise.all(
         plans.map(async (plan, index) => {
-          const prepared = await slrd.prepareTradePlan(target.refs[index]!, plan, options);
-          return { ...await slrd.simulatePlan(prepared.plan),
+          const prepared = await slrd.prepareTradePlan(
+            target.refs[index]!,
+            plan,
+            options,
+          );
+          return {
+            ...(await slrd.simulatePlan(prepared.plan)),
             priorityMicroLamports: prepared.priorityMicroLamports,
-            cuLimit: prepared.plan.draft.cuLimit ?? 600_000 };
+            cuLimit: prepared.plan.draft.cuLimit ?? 600_000,
+            requestedMinimumOutputRaw: outputMinimumRaw?.toString(),
+            guaranteedOutputRaw: prepared.plan.draft.actions.find(action => action.kind === "sell")?.meta?.minOutputRaw,
+          };
         }),
       );
       return {

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

@@ -2,14 +2,26 @@ import { expect, test } from "bun:test";
 import { tradeFeeOptions } from "./trade-fees.ts";
 
 test("native buy/sell fee flags preserve custom compute limit and price", () => {
-  expect(tradeFeeOptions(new Map([
-    ["cu-limit", "150000"], ["priority-micro-lamports", "1000000"],
-    ["trade-attempts", "4"], ["max-priority-fee-lamports", "500000"],
-  ]))).toMatchObject({ priorityFee: { cuLimit: 150_000, microLamports: 1_000_000 },
-    landing: { maxAttempts: 4, maxPriorityFeeLamports: 500_000 } });
+  expect(
+    tradeFeeOptions(
+      new Map([
+        ["cu-limit", "150000"],
+        ["priority-micro-lamports", "1000000"],
+        ["trade-attempts", "4"],
+        ["max-priority-fee-lamports", "500000"],
+      ]),
+    ),
+  ).toMatchObject({
+    priorityFee: { cuLimit: 150_000, microLamports: 1_000_000 },
+    landing: { maxAttempts: 4, maxPriorityFeeLamports: 500_000 },
+  });
 });
 
 test("invalid fee flags reject instead of being ignored", () => {
-  for (const [name, value] of [["cu-limit", "0"], ["priority-micro-lamports", "-1"], ["priority-micro-lamports", "true"]])
+  for (const [name, value] of [
+    ["cu-limit", "0"],
+    ["priority-micro-lamports", "-1"],
+    ["priority-micro-lamports", "true"],
+  ])
     expect(() => tradeFeeOptions(new Map([[name!, value!]]))).toThrow();
 });

package/src/commands/trade-fees.ts

@@ -10,9 +10,15 @@ export function tradeFeeOptions(flags: ReadonlyMap<string, string>) {
   };
   const cuLimit = number("cu-limit");
   const microLamports = number("priority-micro-lamports");
-  if (cuLimit != null && (!Number.isInteger(cuLimit) || cuLimit < 1 || cuLimit > 1_400_000))
+  if (
+    cuLimit != null &&
+    (!Number.isInteger(cuLimit) || cuLimit < 1 || cuLimit > 1_400_000)
+  )
     throw new Error("--cu-limit must be an integer between 1 and 1400000");
-  if (microLamports != null && (!Number.isSafeInteger(microLamports) || microLamports < 0))
+  if (
+    microLamports != null &&
+    (!Number.isSafeInteger(microLamports) || microLamports < 0)
+  )
     throw new Error("--priority-micro-lamports must be a non-negative integer");
   const landing: TradeLandingPolicy = {
     maxAttempts: number("trade-attempts"),

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;
+}

package/src/commands/transfer.test.ts

@@ -3,31 +3,88 @@ import { Keypair } from "@solana/web3.js";
 import { Solard, estimatePlanFee, type PlannedTransaction } from "@solard/core";
 import { runTransferCommand } from "./transfer.ts";
 function fixture(status: "confirmed" | "submitted" | "failed" = "confirmed") {
-  const core: Solard = Object.create(Solard.prototype); const payer = Keypair.generate();
-  const prices: number[] = []; let samples = 0;
+  const core: Solard = Object.create(Solard.prototype);
+  const payer = Keypair.generate();
+  const prices: number[] = [];
+  let samples = 0;
   core.signer = () => payer;
-  core.connection = () => ({
-    getRecentPrioritizationFees: async () => { samples++; return [200_000, 400_000, 800_000, 1_000_000].map((prioritizationFee) => ({ prioritizationFee })); },
-    getFeeForMessage: async (message: { price: number }) => ({ value: 5000 + Math.ceil(10_000 * message.price / 1_000_000) }),
-  }) as any;
-  core.compile = async (_payer, draft) => ({ draft, payer: payer.publicKey, transaction: { message: { price: draft.cuPriceMicroLamports ?? 100_000 } } }) as unknown as PlannedTransaction;
-  core.submitPlan = async (plan, sender) => { prices.push(plan.draft.cuPriceMicroLamports!); return { signature: "test-signature", executionId: 1, sender, plan, feeEstimate: await estimatePlanFee(core.connection(), plan) }; };
-  core.settleSubmission = async () => ({ signature: "test-signature", sender: "rpc", status, slot: status === "confirmed" ? 1 : null, ...(status === "confirmed" ? { feeLamports: 13000 } : {}) });
-  Object.defineProperty(core, "executions", { value: { get: () => ({ metaJson: null }) } });
+  core.connection = () =>
+    ({
+      getRecentPrioritizationFees: async () => {
+        samples++;
+        return [200_000, 400_000, 800_000, 1_000_000].map(
+          (prioritizationFee) => ({ prioritizationFee }),
+        );
+      },
+      getFeeForMessage: async (message: { price: number }) => ({
+        value: 5000 + Math.ceil((10_000 * message.price) / 1_000_000),
+      }),
+    }) as any;
+  core.compile = async (_payer, draft) =>
+    ({
+      draft,
+      payer: payer.publicKey,
+      transaction: {
+        message: { price: draft.cuPriceMicroLamports ?? 100_000 },
+      },
+    }) as unknown as PlannedTransaction;
+  core.submitPlan = async (plan, sender) => {
+    prices.push(plan.draft.cuPriceMicroLamports!);
+    return {
+      signature: "test-signature",
+      executionId: 1,
+      sender,
+      plan,
+      feeEstimate: await estimatePlanFee(core.connection(), plan),
+    };
+  };
+  core.settleSubmission = async () => ({
+    signature: "test-signature",
+    sender: "rpc",
+    status,
+    slot: status === "confirmed" ? 1 : null,
+    ...(status === "confirmed" ? { feeLamports: 13000 } : {}),
+  });
+  Object.defineProperty(core, "executions", {
+    value: { get: () => ({ metaJson: null }) },
+  });
   return { core, prices, samples: () => samples };
 }
-const flags = (extra: Array<[string, string]> = []) => new Map([["wallet", "bags"], ["sol", "2"], ["live", "true"], ...extra]);
+const flags = (extra: Array<[string, string]> = []) =>
+  new Map([["wallet", "bags"], ["sol", "2"], ["live", "true"], ...extra]);
 test("SOL transfer uses writable market fees and reports selected versus actual network fees", async () => {
   const ctx = fixture();
-  const result = await runTransferCommand({ slrd: ctx.core, values: [Keypair.generate().publicKey.toBase58()], flags: flags() });
-  expect(ctx.prices).toEqual([800_000]); expect(ctx.samples()).toBe(1);
-  expect(result.status).toBe("confirmed"); expect(result.feeEstimate).toEqual({ cuLimit: 10_000, priorityMicroLamports: 800_000, priorityFeeLamports: 8000, estimatedBaseFeeLamports: 5000, estimatedNetworkFeeLamports: 13000 });
+  const result = await runTransferCommand({
+    slrd: ctx.core,
+    values: [Keypair.generate().publicKey.toBase58()],
+    flags: flags(),
+  });
+  expect(ctx.prices).toEqual([800_000]);
+  expect(ctx.samples()).toBe(1);
+  expect(result.status).toBe("confirmed");
+  expect(result.feeEstimate).toEqual({
+    cuLimit: 10_000,
+    priorityMicroLamports: 800_000,
+    priorityFeeLamports: 8000,
+    estimatedBaseFeeLamports: 5000,
+    estimatedNetworkFeeLamports: 13000,
+  });
   expect(result.feeLamports).toBe(13000);
 });
 test("explicit zero disables transfer fee estimation and pending outcome is never repeated blindly", async () => {
   const ctx = fixture("submitted");
-  const result = await runTransferCommand({ slrd: ctx.core, values: [Keypair.generate().publicKey.toBase58()], flags: flags([["priority-micro-lamports", "0"]]) });
-  expect(ctx.prices).toEqual([0]); expect(ctx.samples()).toBe(0);
-  expect(result.status).toBe("unresolved"); expect(result.code).toBe("UNRESOLVED"); expect(result.feeLamports).toBeUndefined();
-  expect(result.feeEstimate).toMatchObject({ priorityFeeLamports: 0, estimatedNetworkFeeLamports: 5000 });
+  const result = await runTransferCommand({
+    slrd: ctx.core,
+    values: [Keypair.generate().publicKey.toBase58()],
+    flags: flags([["priority-micro-lamports", "0"]]),
+  });
+  expect(ctx.prices).toEqual([0]);
+  expect(ctx.samples()).toBe(0);
+  expect(result.status).toBe("unresolved");
+  expect(result.code).toBe("UNRESOLVED");
+  expect(result.feeLamports).toBeUndefined();
+  expect(result.feeEstimate).toMatchObject({
+    priorityFeeLamports: 0,
+    estimatedNetworkFeeLamports: 5000,
+  });
 });

package/src/commands/transfer.ts

@@ -144,7 +144,11 @@ export async function runTransferCommand({
       .priorityFee({ cuLimit, microLamports: priorityMicroLamports });
 
     if (flags.has("simulate-only")) {
-      const prepared = await slrd.prepareTradePlan(wallet, await composer.build(), executionOptions);
+      const prepared = await slrd.prepareTradePlan(
+        wallet,
+        await composer.build(),
+        executionOptions,
+      );
       const result = await slrd.simulatePlan(prepared.plan);
       return {
         mode: "simulation",
@@ -162,8 +166,18 @@ export async function runTransferCommand({
       };
     }
 
-    const execution = await slrd.executeTradePlan(wallet, () => composer.build(), via, "transfer-token", executionOptions);
-    const receipt = tradeResult(execution.receipt, execution.attempts, execution.submission.executionId);
+    const execution = await slrd.executeTradePlan(
+      wallet,
+      () => composer.build(),
+      via,
+      "transfer-token",
+      executionOptions,
+    );
+    const receipt = tradeResult(
+      execution.receipt,
+      execution.attempts,
+      execution.submission.executionId,
+    );
 
     return {
       ...receipt,
@@ -184,7 +198,11 @@ export async function runTransferCommand({
     .priorityFee({ cuLimit, microLamports: priorityMicroLamports });
 
   if (flags.has("simulate-only")) {
-    const prepared = await slrd.prepareTradePlan(wallet, await composer.build(), executionOptions);
+    const prepared = await slrd.prepareTradePlan(
+      wallet,
+      await composer.build(),
+      executionOptions,
+    );
     const result = await slrd.simulatePlan(prepared.plan);
     return {
       mode: "simulation",
@@ -198,8 +216,18 @@ export async function runTransferCommand({
     };
   }
 
-  const execution = await slrd.executeTradePlan(wallet, () => composer.build(), via, "transfer-sol", executionOptions);
-  const receipt = tradeResult(execution.receipt, execution.attempts, execution.submission.executionId);
+  const execution = await slrd.executeTradePlan(
+    wallet,
+    () => composer.build(),
+    via,
+    "transfer-sol",
+    executionOptions,
+  );
+  const receipt = tradeResult(
+    execution.receipt,
+    execution.attempts,
+    execution.submission.executionId,
+  );
 
   return { ...receipt, recipient, wallet, sol: amount };
 }