@solard/cli 0.2.6 → 0.2.7

package/src/pump/token-launch-cli.ts

@@ -7,6 +7,8 @@ import {
   assertArmedBuyerEndpointsReady,
   bondingCurvePda,
   createTraderSolard,
+  cleanVanitySuffix,
+  defaultVanityMaxAttempts,
   executePumpTokenLaunch,
   generateMintKeypairWithSuffix,
   installPumpLaunchSenders,
@@ -18,6 +20,9 @@ import {
   preparePumpTokenLaunch,
   pumpLaunchEnvironment,
   releaseArmedBuyerEndpoints,
+  releaseVanityMintReservation,
+  reserveVanityMintFromPool,
+  markVanityMintUsed,
   sol,
   TOKEN_2022_ID,
   uploadPumpMetadata,
@@ -35,6 +40,7 @@ import {
   type Solard,
   type TokenMetadata,
   type TraderSubmitMode,
+  type VanityMintPoolReservation,
 } from "@solard/sdk";
 
 export type Flags = Map<string, string[]>;
@@ -1027,30 +1033,61 @@ function parseBuyPlanRows(flags: Flags): ExplicitBuyerPlanRow[] | null {
       stringValue(row, "address");
     if (!wallet) throw new Error(`Buy plan row ${index + 1} is missing wallet`);
 
+    const exactSol =
+      stringValue(row, "exactSol") ??
+      stringValue(row, "sol") ??
+      stringValue(row, "amountSol");
+    const exactLamports =
+      bigintValue(row, "exactLamports") ??
+      bigintValue(row, "lamports") ??
+      bigintValue(row, "amountLamports");
+
+    if (exactSol != null && exactLamports != null) {
+      throw new Error(
+        `Buy plan row ${index + 1} supplies both SOL and lamport exact amounts`,
+      );
+    }
+
+    const configuredMode =
+      stringValue(row, "amountMode") ?? stringValue(row, "mode");
     const amountMode =
-      stringValue(row, "amountMode") ?? stringValue(row, "mode") ?? "range-bps";
+      configuredMode ??
+      (exactSol != null
+        ? "exact-sol"
+        : exactLamports != null
+          ? "exact-lamports"
+          : "range-bps");
+
+    const exactReserveLamports =
+      solValue(row, "reserveSol", "reserveLamports") ?? 0n;
+
     let amount: ExplicitBuyerPlanRow["amount"];
     if (amountMode === "exact-sol" || amountMode === "exact") {
-      const exactSol =
-        stringValue(row, "exactSol") ??
-        stringValue(row, "sol") ??
-        stringValue(row, "amountSol");
       if (!exactSol)
         throw new Error(
-          `Buy plan row ${index + 1} exact-sol mode requires exactSol`,
+          `Buy plan row ${index + 1} exact-sol mode requires exactSol/amountSol`,
         );
-      amount = { kind: "exact-sol", sol: exactSol };
+      amount = {
+        kind: "exact-sol",
+        sol: exactSol,
+        reserveLamports: exactReserveLamports,
+      };
     } else if (amountMode === "exact-lamports" || amountMode === "lamports") {
-      const lamports =
-        bigintValue(row, "exactLamports") ??
-        bigintValue(row, "lamports") ??
-        bigintValue(row, "amountLamports");
-      if (lamports == null)
+      if (exactLamports == null)
         throw new Error(
-          `Buy plan row ${index + 1} exact-lamports mode requires exactLamports`,
+          `Buy plan row ${index + 1} exact-lamports mode requires exactLamports/amountLamports`,
         );
-      amount = { kind: "exact-lamports", lamports };
+      amount = {
+        kind: "exact-lamports",
+        lamports: exactLamports,
+        reserveLamports: exactReserveLamports,
+      };
     } else {
+      if (exactSol != null || exactLamports != null) {
+        throw new Error(
+          `Buy plan row ${index + 1} exact amount conflicts with amountMode ${amountMode}`,
+        );
+      }
       amount = {
         kind: "balance-bps",
         minBps:
@@ -1140,7 +1177,7 @@ export async function preparePumpTokenLaunchFromFlags(args: {
           10_000n;
     if (
       spendLamports <= 0n ||
-      finalTrader.balanceLamports <= spendLamports + reserveLamports
+      finalTrader.balanceLamports < spendLamports + reserveLamports
     ) {
       throw new Error(
         `Final Jito buyer ${finalTrader.address} cannot cover buy, reserve, and tip: balance=${finalTrader.balanceLamports} spend=${spendLamports} reserve=${finalTrader.reserveLamports} jitoTip=${jitoTipLamports}`,
@@ -1287,8 +1324,32 @@ export async function runPumpTokenLaunchFromArgs(
   const { uri, uploaded } = await resolveMetadataUri(flags, input);
   const cashback = enabled(flags, "cashback", "SOLARD_LAUNCH_CASHBACK");
   const mayhemMode = enabled(flags, "mayhem", "SOLARD_LAUNCH_MAYHEM");
-  const vanityMintSuffix = vanitySuffixFromFlags(flags);
+  const vanityPoolSuffixRaw = nonEmpty(first(flags, "mint-pool"));
+  const vanityPoolAddress = nonEmpty(first(flags, "mint-pool-address"));
+  if (vanityPoolAddress && !vanityPoolSuffixRaw) {
+    throw new Error("--mint-pool-address requires --mint-pool <suffix>.");
+  }
+  if (vanityPoolSuffixRaw && first(flags, "mint-keypair")) {
+    throw new Error("Use either --mint-pool or --mint-keypair, not both.");
+  }
+
+  const vanityPoolSuffix = vanityPoolSuffixRaw
+    ? cleanVanitySuffix(vanityPoolSuffixRaw)
+    : null;
+  const configuredVanitySuffix = vanitySuffixFromFlags(flags);
+  if (
+    vanityPoolSuffix &&
+    configuredVanitySuffix &&
+    vanityPoolSuffix !== configuredVanitySuffix
+  ) {
+    throw new Error(
+      `--mint-pool suffix ${vanityPoolSuffix} conflicts with configured mint suffix ${configuredVanitySuffix}.`,
+    );
+  }
+
+  const vanityMintSuffix = vanityPoolSuffix ?? configuredVanitySuffix;
   const pregeneratedMint = loadMintKeypairFromFlags(flags, vanityMintSuffix);
+  let poolReservation: VanityMintPoolReservation | null = null;
   let vanityMint: Keypair | undefined = pregeneratedMint?.mint;
   let vanityMintAttempts: number | null = pregeneratedMint ? 0 : null;
   let vanityMintElapsedMs: number | null = pregeneratedMint ? 0 : null;
@@ -1301,11 +1362,14 @@ export async function runPumpTokenLaunchFromArgs(
       attempts: 0,
       elapsedMs: 0,
     });
-  } else if (vanityMintSuffix) {
+  } else if (vanityMintSuffix && !vanityPoolSuffix) {
     const maxAttempts = numberFlag(
       flags,
       "vanity-max-attempts",
-      envNumber("SOLARD_VANITY_MINT_MAX_ATTEMPTS", 25_000_000),
+      envNumber(
+        "SOLARD_VANITY_MINT_MAX_ATTEMPTS",
+        defaultVanityMaxAttempts(vanityMintSuffix),
+      ),
     );
     const timeoutMs = numberFlag(
       flags,
@@ -1396,6 +1460,22 @@ export async function runPumpTokenLaunchFromArgs(
     });
   }
 
+  if (!vanityMint && vanityPoolSuffix) {
+    poolReservation = reserveVanityMintFromPool(vanityPoolSuffix, {
+      address: vanityPoolAddress,
+      reason: live ? "pump-launch-live" : "pump-launch-dry-run",
+    });
+    vanityMint = poolReservation.mint;
+    vanityMintAttempts = 0;
+    vanityMintElapsedMs = 0;
+    report("vanity mint pool reserved", {
+      mint: poolReservation.address,
+      suffix: poolReservation.suffix,
+      status: poolReservation.status,
+      live,
+    });
+  }
+
   const slrd = createTraderSolard({ rpcUrl: env.rpcUrl });
   installPumpLaunchSenders(slrd, env);
 
@@ -1572,6 +1652,15 @@ export async function runPumpTokenLaunchFromArgs(
           : undefined,
     });
 
+    if (poolReservation && live) {
+      const used = markVanityMintUsed(poolReservation.address);
+      report("vanity mint pool used", {
+        mint: used.address,
+        suffix: used.suffix,
+        status: used.status,
+      });
+    }
+
     if (live && persistOnLive && prepared) {
       try {
         slrd.persistPreparedDeployment(prepared.deployment, input.alias);
@@ -1639,6 +1728,17 @@ export async function runPumpTokenLaunchFromArgs(
 
     return output;
   } finally {
+    // Dry runs never consume a pooled mint. Live failures intentionally leave
+    // it RESERVED because a bundle can be ambiguous even when local tracking
+    // fails. Release it manually only after on-chain preflight confirms unused.
+    if (poolReservation && !live) {
+      try {
+        releaseVanityMintReservation(poolReservation.address);
+      } catch {
+        // Preserve the primary launch/simulation result.
+      }
+    }
+
     // Never persist from finally: preflight, simulation, and bundle submission
     // failures must leave the token registry untouched.
     slrd.close();

package/src/pump/vamp-cli.ts

@@ -0,0 +1,363 @@
+import { existsSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { extname, join, resolve } from "node:path";
+
+import {
+  createTraderSolard,
+  fetchPumpVampSourceMetadata,
+  publicPumpMetadataUrl,
+  uploadPumpMetadata,
+  type MetadataUploaderId,
+  type PumpVampSourceMetadata,
+} from "@solard/sdk";
+
+import {
+  first,
+  parseArgs,
+  runPumpTokenLaunchFromArgs,
+  type PumpTokenLaunchCliOptions,
+  type PumpTokenLaunchCliResult,
+} from "./token-launch-cli.ts";
+
+export type PumpVampCliResult = {
+  source: PumpVampSourceMetadata;
+  resolved: {
+    alias: string;
+    name: string;
+    symbol: string;
+    uri: string;
+    metadataMode: "source-uri" | "override-uri" | "merged-upload";
+    overrides: string[];
+  };
+  launch: PumpTokenLaunchCliResult;
+};
+
+function clean(value: string | undefined): string | undefined {
+  const text = value?.trim();
+  return text && text !== "true" ? text : undefined;
+}
+
+function safeAlias(symbol: string, sourceMint: string): string {
+  const stem =
+    symbol
+      .toLowerCase()
+      .replace(/[^a-z0-9_-]+/g, "-")
+      .replace(/^-+|-+$/g, "") || "token";
+  return `vamp-${stem}-${sourceMint.slice(0, 6).toLowerCase()}-${Date.now()
+    .toString(36)
+    .slice(-5)}`;
+}
+
+function isRemote(value: string): boolean {
+  return /^(?:https?:\/\/|ipfs:\/\/|ar:\/\/)/i.test(value.trim());
+}
+
+function imageExtension(value: string): string {
+  try {
+    const pathname = new URL(publicPumpMetadataUrl(value)).pathname;
+    const extension = extname(pathname);
+    return extension && extension.length <= 8 ? extension : ".img";
+  } catch {
+    const extension = extname(value);
+    return extension && extension.length <= 8 ? extension : ".img";
+  }
+}
+
+async function downloadToTemp(
+  value: string,
+): Promise<{ path: string; cleanup: () => void }> {
+  const directory = mkdtempSync(join(tmpdir(), "solard-vamp-"));
+  const url = publicPumpMetadataUrl(value);
+  const controller = new AbortController();
+  const timeout = setTimeout(() => controller.abort(), 20_000);
+  try {
+    const response = await fetch(url, { signal: controller.signal });
+    if (!response.ok) {
+      throw new Error(
+        `Could not download vamp image (${response.status}) from ${url}`,
+      );
+    }
+    const bytes = Buffer.from(await response.arrayBuffer());
+    if (!bytes.length)
+      throw new Error(`Downloaded vamp image is empty: ${url}`);
+    const path = join(directory, `image${imageExtension(value)}`);
+    writeFileSync(path, bytes);
+    return {
+      path,
+      cleanup: () => rmSync(directory, { recursive: true, force: true }),
+    };
+  } catch (error) {
+    rmSync(directory, { recursive: true, force: true });
+    throw error;
+  } finally {
+    clearTimeout(timeout);
+  }
+}
+
+async function resolveImagePath(
+  configured: string | undefined,
+  sourceImage: string | null,
+): Promise<{ path: string; cleanup: () => void }> {
+  const selected = configured ?? sourceImage ?? undefined;
+  if (!selected) {
+    throw new Error(
+      "Vamp metadata override requires an image. Source metadata has no image; provide --image <path-or-url>.",
+    );
+  }
+
+  if (isRemote(selected)) return await downloadToTemp(selected);
+
+  const path = resolve(selected);
+  if (!existsSync(path)) {
+    throw new Error(`Vamp image file not found: ${path}`);
+  }
+  return { path, cleanup: () => {} };
+}
+
+function stripVampArgs(argv: string[]): string[] {
+  const handled = new Set([
+    "source-authority", // legacy v1 flag: intentionally ignored now
+    "alias",
+    "name",
+    "symbol",
+    "uri",
+    "metadata",
+    "image",
+    "description",
+    "website",
+    "twitter",
+    "telegram",
+    "video",
+    "show-name",
+    "hide-name",
+    "cashback",
+  ]);
+
+  const result: string[] = [];
+  let sourceMintRemoved = false;
+
+  for (let index = 0; index < argv.length; index += 1) {
+    const item = argv[index]!;
+    if (!item.startsWith("--")) {
+      if (!sourceMintRemoved) {
+        sourceMintRemoved = true;
+        continue;
+      }
+      result.push(item);
+      continue;
+    }
+
+    const [key, inline] = item.slice(2).split("=", 2);
+    if (!handled.has(key!)) {
+      result.push(item);
+      if (
+        inline == null &&
+        argv[index + 1] &&
+        !argv[index + 1]!.startsWith("--")
+      ) {
+        result.push(argv[++index]!);
+      }
+      continue;
+    }
+
+    if (
+      inline == null &&
+      argv[index + 1] &&
+      !argv[index + 1]!.startsWith("--")
+    ) {
+      index += 1;
+    }
+  }
+
+  return result;
+}
+
+function metadataProvider(
+  flags: ReturnType<typeof parseArgs>["flags"],
+): MetadataUploaderId {
+  return (clean(first(flags, "metadata-provider")) ??
+    clean(process.env.SLRD_METADATA_UPLOADER) ??
+    clean(process.env.PUMP_METADATA_PROVIDER) ??
+    "pump-frontend") as MetadataUploaderId;
+}
+
+export async function runPumpVampFromArgs(
+  argv: string[],
+  options: PumpTokenLaunchCliOptions = {},
+): Promise<PumpVampCliResult> {
+  const { flags, positionals } = parseArgs(argv);
+  if (positionals.length !== 1) {
+    throw new Error(
+      "Usage: slrd vamp <source-mint> --creator <wallet> [metadata overrides] [launch flags]",
+    );
+  }
+  if (first(flags, "metadata")) {
+    throw new Error(
+      "vamp does not accept --metadata <file>; override individual fields or provide --uri <metadata-uri>.",
+    );
+  }
+
+  const sourceMint = positionals[0]!;
+  const report = options.report ?? (() => {});
+  const sourceSlrd = createTraderSolard();
+  let source: PumpVampSourceMetadata;
+  try {
+    source = await fetchPumpVampSourceMetadata(
+      sourceSlrd.connection(),
+      sourceMint,
+    );
+  } finally {
+    sourceSlrd.close();
+  }
+
+  const alias =
+    clean(first(flags, "alias")) ?? safeAlias(source.symbol, source.mint);
+  const name = clean(first(flags, "name")) ?? source.name;
+  const symbol = clean(first(flags, "symbol")) ?? source.symbol;
+  const explicitUri = clean(first(flags, "uri"));
+  const image = clean(first(flags, "image"));
+  const description = clean(first(flags, "description"));
+  const website = clean(first(flags, "website"));
+  const twitter = clean(first(flags, "twitter"));
+  const telegram = clean(first(flags, "telegram"));
+  const video = clean(first(flags, "video"));
+  const showName = flags.has("hide-name")
+    ? false
+    : flags.has("show-name")
+      ? first(flags, "show-name") !== "false"
+      : (source.showName ?? true);
+
+  const overrides = [
+    ["alias", clean(first(flags, "alias"))],
+    ["name", clean(first(flags, "name"))],
+    ["symbol", clean(first(flags, "symbol"))],
+    ["uri", explicitUri],
+    ["image", image],
+    ["description", description],
+    ["website", website],
+    ["twitter", twitter],
+    ["telegram", telegram],
+    ["video", video],
+    [
+      "showName",
+      flags.has("show-name") || flags.has("hide-name") ? "set" : undefined,
+    ],
+  ]
+    .filter(([, value]) => value != null)
+    .map(([key]) => key!);
+
+  const hasJsonFieldOverrides = Boolean(
+    image ||
+    description ||
+    website ||
+    twitter ||
+    telegram ||
+    video ||
+    flags.has("show-name") ||
+    flags.has("hide-name"),
+  );
+  const shouldMergeUpload =
+    !explicitUri &&
+    Boolean(
+      clean(first(flags, "name")) ||
+      clean(first(flags, "symbol")) ||
+      hasJsonFieldOverrides,
+    );
+
+  if (explicitUri && hasJsonFieldOverrides) {
+    throw new Error(
+      "--uri already defines metadata JSON. Do not combine it with --image/--description/--website/--twitter/--telegram/--video/--show-name/--hide-name; put those fields in the supplied URI instead.",
+    );
+  }
+
+  let uri = explicitUri ?? source.uri;
+  let metadataMode: PumpVampCliResult["resolved"]["metadataMode"] = explicitUri
+    ? "override-uri"
+    : "source-uri";
+
+  if (shouldMergeUpload) {
+    const imageFile = await resolveImagePath(image, source.image);
+    try {
+      const uploaded = await uploadPumpMetadata(
+        {
+          imagePath: imageFile.path,
+          name,
+          symbol,
+          description:
+            description ?? source.description ?? `${name} (${symbol})`,
+          website: website ?? source.website ?? undefined,
+          twitter: twitter ?? source.twitter ?? undefined,
+          telegram: telegram ?? source.telegram ?? undefined,
+          video: video ?? source.video ?? undefined,
+          showName,
+        },
+        {
+          provider: metadataProvider(flags),
+        },
+      );
+      uri = uploaded.metadataUri;
+      metadataMode = "merged-upload";
+      report("pump vamp metadata uploaded", {
+        provider: uploaded.provider,
+        metadataUri: uploaded.metadataUri,
+        imageUri: uploaded.imageUri ?? null,
+      });
+    } finally {
+      imageFile.cleanup();
+    }
+  }
+
+  report("pump vamp source", {
+    mint: source.mint,
+    metadataKind: source.metadataKind,
+    sourceName: source.name,
+    sourceSymbol: source.symbol,
+    sourceUri: source.uri,
+    metadataJsonFetched: source.json != null,
+  });
+  report("pump vamp resolved", {
+    alias,
+    name,
+    symbol,
+    uri,
+    metadataMode,
+    overrides,
+    cashback: true,
+  });
+
+  const launchArgv = [
+    ...stripVampArgs(argv),
+    "--alias",
+    alias,
+    "--name",
+    name,
+    "--symbol",
+    symbol,
+    "--uri",
+    uri,
+    "--cashback",
+  ];
+
+  const launch = await runPumpTokenLaunchFromArgs(launchArgv, options);
+
+  report("pump vamp result", {
+    sourceMint: source.mint,
+    newMint: launch.token.mint,
+    alias,
+    cashback: true,
+    live: launch.live,
+  });
+
+  return {
+    source,
+    resolved: {
+      alias,
+      name,
+      symbol,
+      uri,
+      metadataMode,
+      overrides,
+    },
+    launch,
+  };
+}