candle-launch-helper 0.0.0-stage → 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,20 @@
+# Changelog: candle-launch-helper
+
+## 0.1.0
+
+First release, on candle-bot-core 0.4.0 (pinned exactly).
+
+- One Candle launch per spec through the atomic route (payer main): build, the dev buy's expected fill checked,
+  submit within 45 s; the dev buy as the bundle's first buy.
+- `clientLaunchId` saved before the first build, never replaced; every state saved before its call; restarts,
+  timeouts and errors reconcile from Candle's launch job (`building` saved before the build: a restart never builds).
+- `RETRY_LAUNCH` builds once more under the same id only after a job read says `failed` or `JOB_NOT_FOUND`, and not
+  under `PAUSE_BUYS` or `STOP`; otherwise it is ignored with why.
+- Before the first build: `minDevBuyOutRaw` required (live), the dev buy within `lifetimeSol` and `maxOpen`, `wallet`
+  the key's embedded wallet, and no earlier launch by the account with the same name and symbol (`launch.newLaunch`
+  overrides).
+- The dev bag becomes a core position from its transaction on chain (core `openFromFill`); exits, `sell`, `STOP`,
+  `PAUSE_BUYS` as every bot. A missing or wrong dev-buy signature is found in the wallet's history for the mint;
+  `adopt <signature>` books it by hand. `run` waits for a launch call in flight before closing on STOP or SIGTERM.
+- Dry mode calls nothing. `plan` (with the API key: Candle's `dryRunAtomicLaunch` preview of the dev buy's fill),
+  `run`, `status`, `sell`, `adopt`.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 candle-launch-bot contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,147 @@
-# Temporary Holding Version
+# candle-launch-helper
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Fires the [Candle](https://candle.tv) launch you describe, with your dev buy in the same bundle, then manages the dev
+bag with exits and controls. One launch per name and symbol; a run never launches twice. Built on Candle's official SDK,
+[`@candledottv/agent-sdk`](https://www.npmjs.com/package/@candledottv/agent-sdk) (pinned at 0.6.14), and
+[candle-bot-core](https://www.npmjs.com/package/candle-bot-core).
+
+Built by [Bruce Jeet](https://github.com/BruceJeet).
+
+- **The launch:** name, symbol, image, description, socials and launch mode from the config, on Solana.
+- **The dev buy:** the bundle's first buy, from the same wallet, landing in the launch's own block (Candle's atomic
+  route, a Jito bundle: all or nothing). Candle's expected fill for it is checked before anything is sent.
+- **The bag:** once the launch lands, the dev buy is read from its transaction on chain (amount and cost) and becomes a
+  position the core manages: `tpsl`, `time`, `ladder`, `preGrad`, `hold` or your own exit, `STOP`, `PAUSE_BUYS`,
+  `sell`.
+- **Dry mode** calls nothing: it prints the launch it would send. `plan` with the API key set asks Candle for a dry-run
+  preview of the dev buy's fill (`dryRunAtomicLaunch`: the build's checks, nothing recorded, reserved or sent).
+
+## Quick start
+
+Node 22.18 or newer. A Candle API key with the `launch:write`, `swap:write` and `launch:read` scopes, on a plan that
+allows atomic launches, and the account's embedded wallet funded.
+
+```sh
+npm install -g candle-launch-helper
+cp "$(npm root -g)/candle-launch-helper/examples/launch.json" launch.json    # your coin's details
+candle-launch-helper plan --config launch.json      # the exact launch body; with CANDLE_API_KEY set, Candle's
+                                                    # dry-run preview of the dev buy's fill (--offline: none)
+candle-launch-helper run  --config launch.json      # dry: logs the plan, runs the loop
+export CANDLE_API_KEY=cndl_live_...
+# set "mode": "live", your embedded wallet and launch.minDevBuyOutRaw (from plan's preview) in launch.json, then:
+candle-launch-helper run --config launch.json       # launches once, then manages the dev bag
+```
+
+## The route, and why
+
+Candle's atomic launch (`buildAtomicLaunch`, then `submitAtomicLaunch`) from the account's main wallet:
+
+- the dev buy is a first-buy leg of the bundle, in the launch's block: nobody buys before it;
+- Candle signs the main wallet's legs itself, so nothing is signed on this machine;
+- the launch has one identity, its `clientLaunchId`, which Candle uses to keep a second launch from being built.
+
+`payer` must be `"embedded"`: Candle refuses a TEE wallet on the atomic route.
+
+## A run never launches twice
+
+- **Before the first build** a live run checks, and sends nothing unless all pass (an alert says which failed; a
+  read that failed is tried again every 30 s):
+  - `launch.minDevBuyOutRaw` is set;
+  - the dev buy fits `buy.lifetimeSol` and `buy.maxOpen`;
+  - `wallet` is the key's embedded (main) wallet, where the dev bag lands (Candle's portfolio);
+  - the account has not launched a token with the same name and symbol (Candle's list of the account's launched
+    tokens, case and spaces ignored). Another state dir with the same spec is refused. A listed token without a name
+    or symbol, or a list that ends without saying it is done, is refused too (it cannot be judged).
+    `launch.newLaunch: true` launches the same name and symbol again on purpose. The check relies on Candle's list
+    showing a launch from minutes ago; that was not verified live.
+- The `clientLaunchId` is written to the ledger **before** the first build and is never replaced. A state dir holds
+  one launch; a config for another coin in the same state dir is refused (alert), nothing is sent.
+- The build is checked before the submit: the dev buy's leg carries `minAmountOut: 0` inside the bundle, so Candle's
+  `expectedFill` is the check (present, above zero, and at least `launch.minDevBuyOutRaw`). The submit goes out within
+  45 s of the build (the legs share one blockhash), and only from the process that built it.
+- Every state is saved before the call it leads to (`building` before the build). A restart during a build, after a
+  build that was not submitted, or during a submit, a timeout, or any error after a request was sent reads Candle's
+  launch job (`getLaunchJob`) every 30 s: it resumes on `confirmed`, stops on `failed`, and waits otherwise. A restart
+  never builds. A launch unresolved for `launch.unresolvedAlertMin` minutes raises an alert with its `clientLaunchId`.
+- **The bot never builds again on its own.** `RETRY_LAUNCH` in the state dir asks for one more build under the same
+  id. It acts only when a job read just then says `failed` or `JOB_NOT_FOUND` (the SDK's recovery steps), and not
+  while `PAUSE_BUYS` or `STOP` is set. Any other answer uses the file up (`RETRY_LAUNCH.ignored`) and logs and alerts
+  why. A job that says `confirmed` is taken as landed. A 409 on the rebuild (Candle still resolving the first attempt)
+  goes back to reading the job. A new `clientLaunchId` is never sent while a launch may land.
+- `PAUSE_BUYS`: no launch fires (and none is submitted after a build). Dry mode makes no call at all.
+- STOP, a signal and PAUSE_BUYS are read again right before every build.
+- On `STOP` or SIGTERM the run waits for a launch call in flight (a submit can take about 160 s) before it closes the
+  ledger. Under systemd give the unit `TimeoutStopSec=200` or more; a kill in the middle is still safe (the state was
+  saved before the call, and the restart reads the job).
+
+## The dev bag
+
+Once the launch lands, the dev buy's transaction (the submit's buy-leg signature, else Candle's job) is booked from
+the chain by the core (`openFromFill`: this wallet's tokens and SOL spent, never an API's number). When Candle names no
+dev-buy transaction, or one that gave the wallet no tokens, the wallet's token-account history for the mint is read
+whole (paged), oldest first. The first transaction that gave the wallet this coin is the dev buy (the bundle bought
+first and opened the account): it is booked if it passes the core's checks. The scan never walks past it to a later
+buy. If it cannot be read yet, the scan tries again later; if it fails the checks (no SOL spent, already booked), or
+the history runs past 10,000 signatures, an alert asks for a hand booking:
+
+```sh
+candle-launch-helper adopt <signature> --config launch.json [--mint <mint>] [--force]    # with the bot stopped
+```
+
+`adopt` books the bag from that transaction through the same checks (this wallet, this mint, SOL spent, tokens
+received, not booked already) and marks the launch open. On a launch whose bag is already open it refuses (a second
+position would count twice in the caps and the exits); `--force` books it anyway.
+
+## Config
+
+The core's sections as in every candle-bot-core bot (`mode`, `payer`, `apiKeyEnv`, `rpcUrlEnv`, `wallet`, `stateDir`,
+`buy`, `sell`, `exit`, `retry`, `alerts`), plus:
+
+```json
+{
+  "launch": {
+    "name": "My Coin", "symbol": "MINE", "imageUrl": "https://.../logo.png",
+    "description": "...", "website": "https://...", "twitter": "https://x.com/...", "telegram": "https://t.me/...",
+    "mode": "open",
+    "devBuySol": 0.05,
+    "minDevBuyOutRaw": "1000000000000",
+    "unresolvedAlertMin": 10
+  }
+}
+```
+
+| Key | Meaning |
+|---|---|
+| `launch.name`, `symbol`, `imageUrl` | required; the image is a hosted https URL |
+| `launch.description`, `website`, `twitter`, `telegram` | optional |
+| `launch.mode` | Candle launch mode (default `open`) |
+| `launch.devBuySol` | the dev buy, SOL; at most `buy.sol`; counts against `buy.lifetimeSol` |
+| `launch.minDevBuyOutRaw` | required in live mode: refuse to submit if Candle's expected fill is lower (raw token units, as a string). `plan` previews the fill |
+| `launch.newLaunch` | `true` to launch even though the account already launched this name and symbol (default `false`: refused) |
+| `launch.unresolvedAlertMin` | alert when a sent launch stays unresolved this long (default 10) |
+
+## State dir
+
+| File | What |
+|---|---|
+| `ledger.sqlite` | the `launches` row (id, state, bundle, mint, signatures), the dev bag's position and its orders, alerts |
+| `status.json` | the launch's state, mint and position; the bag's value and exits |
+| `events.jsonl` | `launch_preflight_refused`, `launch_id_saved`, `launch_built`, `launch_landed`, `launch_unresolved`, `launch_retry`, `launch_retry_ignored`, `dev_buy_found_on_chain`, `dev_bag_open`, sells |
+| `RETRY_LAUNCH`, `.done`, `.ignored` | the operator's retry request, and what became of it |
+
+## Known limits
+
+- **Embedded payer only** (the atomic route). One dev-buy leg.
+- **Image by URL.** The image must already be hosted.
+- **The dev-buy transaction** is taken from the submit's signatures (the buy leg's index), Candle's launch job, or the
+  wallet's history for the mint; until one is booked, the bag is not managed (alert; `adopt` books it by hand).
+- **The same-spec check** reads up to 20 pages (1,000 tokens) of the account's launches; an account with more is
+  refused unless `launch.newLaunch` is set.
+- **A launch refused at the submit check** (expected fill under the floor) leaves a built bundle Candle never got; its
+  job may not answer `failed` or `JOB_NOT_FOUND`, so `RETRY_LAUNCH` may be ignored. Use a new state dir (with
+  `launch.newLaunch: true` only if the first launch is known not to exist).
+- **Solana only.**
+
+## License
+
+MIT

package/bin/candle-launch-helper

@@ -0,0 +1,7 @@
+#!/usr/bin/env node
+// The published package runs the compiled dist/; a source checkout runs src/ directly (Node strips types).
+import { existsSync } from "node:fs";
+const dist = new URL("../dist/cli.js", import.meta.url);
+const entry = existsSync(dist) ? dist : new URL("../src/cli.ts", import.meta.url);
+const { main } = await import(entry.href);
+process.exit(await main(process.argv.slice(2)));

package/dist/cli.d.ts

@@ -0,0 +1,11 @@
+import { type Config } from "./config.ts";
+import { type LaunchClient } from "./launcher.ts";
+export declare const HELP = "candle-launch-helper: fires the Candle launch you describe, with its dev buy in the same bundle, then manages the\ndev bag with the core's exits and controls.\n\n  candle-launch-helper plan   --config launch.json [--offline]       print the launch body and, with the API key set,\n                                                                     Candle's dry-run preview of the dev buy's fill\n                                                                     (dryRunAtomicLaunch: records and sends nothing)\n  candle-launch-helper run    --config launch.json [--mode dry|live] launch (live), then manage the bag\n  candle-launch-helper status --config launch.json                   print status.json\n  candle-launch-helper sell   <mint> --config launch.json [--fraction 1]\n  candle-launch-helper adopt  <signature> --config launch.json [--mint <mint>] [--force]\n                                                                     book the dev bag from its transaction (bot stopped)\n\nOne launch per spec: a live run refuses when the account already launched the same name and symbol (launch.newLaunch\noverrides), and a state dir never launches twice. Controls: STOP, PAUSE_BUYS (no launch fires), RETRY_LAUNCH (one more\nbuild under the same clientLaunchId, only when Candle's job says failed or not found). Docs: the README.\n";
+/**
+ * `plan`: the launch body, and with a client Candle's dry-run preview of the dev buy's fill (dryRunAtomicLaunch:
+ * the build's checks; records, reserves and sends nothing). Its clientLaunchId is a throwaway, never built.
+ */
+export declare function planOutput(cfg: Config, client: LaunchClient | null, skipped: string | null): Promise<Record<string, unknown>>;
+/** Longest a launch call may take (the SDK: a submit up to ~160 s). */
+export declare const LAUNCH_TIMEOUT_MS = 180000;
+export declare function main(argv?: string[]): Promise<number>;

package/dist/cli.js

@@ -0,0 +1,141 @@
+/** The command line: plan, run, status, sell, adopt. */
+import { randomUUID } from "node:crypto";
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { CandleClient } from "@candledottv/agent-sdk";
+import { timedFetch } from "candle-bot-core/exec/trader";
+import { acquireLock } from "candle-bot-core/engine";
+import { args, context as coreContext, die, guardMain, parts, run, sell, status } from "candle-bot-core/runtime";
+import { loadConfig, ConfigError } from "./config.js";
+import { Ledger } from "./ledger.js";
+import { Engine, launchBody } from "./launcher.js";
+export const HELP = `candle-launch-helper: fires the Candle launch you describe, with its dev buy in the same bundle, then manages the
+dev bag with the core's exits and controls.
+
+  candle-launch-helper plan   --config launch.json [--offline]       print the launch body and, with the API key set,
+                                                                     Candle's dry-run preview of the dev buy's fill
+                                                                     (dryRunAtomicLaunch: records and sends nothing)
+  candle-launch-helper run    --config launch.json [--mode dry|live] launch (live), then manage the bag
+  candle-launch-helper status --config launch.json                   print status.json
+  candle-launch-helper sell   <mint> --config launch.json [--fraction 1]
+  candle-launch-helper adopt  <signature> --config launch.json [--mint <mint>] [--force]
+                                                                     book the dev bag from its transaction (bot stopped)
+
+One launch per spec: a live run refuses when the account already launched the same name and symbol (launch.newLaunch
+overrides), and a state dir never launches twice. Controls: STOP, PAUSE_BUYS (no launch fires), RETRY_LAUNCH (one more
+build under the same clientLaunchId, only when Candle's job says failed or not found). Docs: the README.
+`;
+function context(configPath, modeOverride) {
+    let cfg;
+    try {
+        cfg = loadConfig(configPath);
+    }
+    catch (e) {
+        if (e instanceof ConfigError)
+            die(e.message);
+        throw e;
+    }
+    return coreContext(cfg, modeOverride);
+}
+async function makeEngine(ctx, ledger) {
+    const { strategy, alerter, executor } = await parts(ctx, ledger, { maxBuyImpactBps: 10_000 });
+    // Live: Candle's client for the launch calls, with a longer timeout than trades (a submit can take ~160 s and a
+    // same-id rebuild ~95 s, per the SDK). Dry: none, so nothing can be built or sent.
+    const apiKey = process.env[ctx.cfg.apiKeyEnv];
+    if (ctx.cfg.mode === "live" && !apiKey)
+        die(`${ctx.cfg.apiKeyEnv} is not set (the Candle API key)`);
+    const client = ctx.cfg.mode === "live" ? new CandleClient({ apiUrl: ctx.cfg.apiUrl, apiKey, fetch: timedFetch(LAUNCH_TIMEOUT_MS) }) : null;
+    const engine = new Engine({ cfg: ctx.cfg, ledger, client, executor, strategy, rpc: ctx.rpc, log: ctx.log, alerter });
+    return { engine, trigger: engine.trigger };
+}
+/**
+ * `plan`: the launch body, and with a client Candle's dry-run preview of the dev buy's fill (dryRunAtomicLaunch:
+ * the build's checks; records, reserves and sends nothing). Its clientLaunchId is a throwaway, never built.
+ */
+export async function planOutput(cfg, client, skipped) {
+    const body = launchBody(cfg.launch);
+    const out = { route: "atomic (build, check the dev buy's expected fill, submit)", body, minDevBuyOutRaw: cfg.launch.minDevBuyOutRaw?.toString() ?? null };
+    if (!client?.dryRunAtomicLaunch) {
+        out.preview = skipped ?? "skipped (no client)";
+        return out;
+    }
+    try {
+        const r = await client.dryRunAtomicLaunch({ ...body, clientLaunchId: `clh-plan-${randomUUID()}` });
+        const fill = r.fills?.[0]?.expectedFill ?? null;
+        out.preview = { devBuyExpectedOutRaw: fill?.amountOutRaw ?? null, devBuyMinOutRaw: fill?.minAmountOutRaw ?? null, graduatesInBundle: r.graduatesInBundle ?? null, note: "set launch.minDevBuyOutRaw at or below devBuyExpectedOutRaw (the submit is refused under it)" };
+    }
+    catch (e) {
+        out.preview = { error: String(e?.message ?? e).slice(0, 300) };
+    }
+    return out;
+}
+/** Longest a launch call may take (the SDK: a submit up to ~160 s). */
+export const LAUNCH_TIMEOUT_MS = 180_000;
+const openLedger = (ctx) => () => new Ledger(join(ctx.cfg.stateDir, "ledger.sqlite"));
+export async function main(argv = process.argv.slice(2)) {
+    return guardMain(async () => {
+        const { pos, opt } = args(argv);
+        const cmd = pos[0];
+        if (!cmd || cmd === "help" || opt.help) {
+            process.stdout.write(HELP);
+            return cmd || opt.help ? 0 : 2;
+        }
+        if (cmd === "version" || opt.version) {
+            process.stdout.write(JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8")).version + "\n");
+            return 0;
+        }
+        const config = opt.config ?? "launch.json";
+        switch (cmd) {
+            case "plan": {
+                let cfg;
+                try {
+                    cfg = loadConfig(config);
+                }
+                catch (e) {
+                    if (e instanceof ConfigError)
+                        die(e.message);
+                    throw e;
+                }
+                const apiKey = process.env[cfg.apiKeyEnv];
+                const skip = opt.offline ? "skipped (--offline)" : !apiKey ? `skipped (${cfg.apiKeyEnv} not set)` : null;
+                const client = skip ? null : new CandleClient({ apiUrl: cfg.apiUrl, apiKey, fetch: timedFetch(LAUNCH_TIMEOUT_MS) });
+                const out = await planOutput(cfg, client, skip);
+                process.stdout.write(JSON.stringify(out, null, 2) + "\n");
+                return 0;
+            }
+            case "run": {
+                const ctx = context(config, opt.mode);
+                return run(ctx, openLedger(ctx), (ledger) => makeEngine(ctx, ledger));
+            }
+            case "status":
+                return status(context(config));
+            case "sell": {
+                if (!pos[1])
+                    die("sell <mint> [--fraction f]");
+                const ctx = context(config);
+                return sell(ctx, pos[1], opt.fraction ? Number(opt.fraction) : 1, openLedger(ctx), (ledger) => makeEngine(ctx, ledger));
+            }
+            case "adopt": {
+                if (!pos[1])
+                    die("adopt <signature> [--mint <mint>]");
+                const ctx = context(config);
+                const lock = acquireLock(ctx.cfg.stateDir);
+                if (!lock)
+                    die(`the bot is running (${ctx.cfg.stateDir}/lock): stop it, then adopt`);
+                const ledger = openLedger(ctx)();
+                try {
+                    const { engine } = await makeEngine(ctx, ledger);
+                    const r = await engine.launcher.adopt(pos[1], opt.mint, opt.force === "true");
+                    process.stdout.write(r + "\n");
+                    return /^position \d+/.test(r) ? 0 : 1;
+                }
+                finally {
+                    ledger.close();
+                    lock.release();
+                }
+            }
+            default:
+                die(`unknown command ${cmd}`);
+        }
+    });
+}

package/dist/config.d.ts

@@ -0,0 +1,35 @@
+/**
+ * The one config file: the core's shared sections (candle-bot-core) plus `launch`, the launch spec. Unknown keys are
+ * refused at every level. The launch goes through Candle's atomic route from the account's main (embedded) wallet:
+ * `payer` must be "embedded".
+ */
+import { type Config as CoreConfig, type SectionParser } from "candle-bot-core";
+export { ConfigError } from "candle-bot-core/config";
+export declare const LAUNCH_MODES: readonly ["open", "exclusive", "test-open", "test-exclusive", "exp-a", "exp-b", "exp-c", "exp-custom"];
+export type LaunchMode = (typeof LAUNCH_MODES)[number];
+export interface LaunchSpec {
+    name: string;
+    symbol: string;
+    imageUrl: string;
+    description?: string;
+    website?: string;
+    twitter?: string;
+    telegram?: string;
+    mode: LaunchMode;
+    /** The dev buy, SOL: the bundle's first buy, from the same wallet, in the launch's block. At most buy.sol. */
+    devBuySol: number;
+    /** Refuse to submit unless Candle's expected fill for the dev buy is at least this (raw token units). */
+    minDevBuyOutRaw?: bigint;
+    /** Alert when a sent launch is still unresolved after this many minutes. */
+    unresolvedAlertMin: number;
+    /** Launch even when the account already launched a token with this name and symbol (default false: refused). */
+    newLaunch: boolean;
+}
+export type Config = CoreConfig & {
+    launch: LaunchSpec;
+};
+export declare const SECTIONS: {
+    launch: SectionParser<LaunchSpec>;
+};
+export declare function parseConfig(raw: unknown, baseDir?: string): Config;
+export declare function loadConfig(path: string): Config;

package/dist/config.js

@@ -0,0 +1,63 @@
+/**
+ * The one config file: the core's shared sections (candle-bot-core) plus `launch`, the launch spec. Unknown keys are
+ * refused at every level. The launch goes through Candle's atomic route from the account's main (embedded) wallet:
+ * `payer` must be "embedded".
+ */
+import { parseConfig as parseCore, loadConfig as loadCore, ConfigError, isObj, only, num, str } from "candle-bot-core";
+export { ConfigError } from "candle-bot-core/config";
+export const LAUNCH_MODES = ["open", "exclusive", "test-open", "test-exclusive", "exp-a", "exp-b", "exp-c", "exp-custom"];
+const parseLaunch = (raw, core) => {
+    if (!isObj(raw))
+        throw new ConfigError("config.launch: required object (name, symbol, imageUrl, devBuySol, ...)");
+    only(raw, ["name", "symbol", "imageUrl", "description", "website", "twitter", "telegram", "mode", "devBuySol", "minDevBuyOutRaw", "unresolvedAlertMin", "newLaunch"], "config.launch");
+    const name = str(raw, "name", "config.launch");
+    const symbol = str(raw, "symbol", "config.launch");
+    const imageUrl = str(raw, "imageUrl", "config.launch");
+    if (!/^https:\/\//.test(imageUrl))
+        throw new ConfigError("config.launch.imageUrl: must be an https:// URL");
+    const mode = str(raw, "mode", "config.launch", { def: "open" });
+    if (!LAUNCH_MODES.includes(mode))
+        throw new ConfigError(`config.launch.mode: "${mode}" is not a Candle launch mode (${LAUNCH_MODES.join(", ")})`);
+    const devBuySol = num(raw, "devBuySol", "config.launch", { min: 0.000001 });
+    if (devBuySol > core.buy.sol)
+        throw new ConfigError(`config.launch.devBuySol: ${devBuySol} is above buy.sol (${core.buy.sol})`);
+    let minDevBuyOutRaw;
+    if (raw.minDevBuyOutRaw !== undefined) {
+        const v = String(raw.minDevBuyOutRaw);
+        if (!/^\d+$/.test(v))
+            throw new ConfigError("config.launch.minDevBuyOutRaw: a whole number of raw token units (a string)");
+        minDevBuyOutRaw = BigInt(v);
+    }
+    return {
+        name, symbol, imageUrl, mode, devBuySol, minDevBuyOutRaw,
+        description: str(raw, "description", "config.launch", { optional: true }),
+        website: str(raw, "website", "config.launch", { optional: true }),
+        twitter: str(raw, "twitter", "config.launch", { optional: true }),
+        telegram: str(raw, "telegram", "config.launch", { optional: true }),
+        unresolvedAlertMin: num(raw, "unresolvedAlertMin", "config.launch", { min: 1, def: 10 }),
+        newLaunch: bool(raw, "newLaunch"),
+    };
+};
+function bool(o, k) {
+    const v = o[k];
+    if (v === undefined)
+        return false;
+    if (typeof v !== "boolean")
+        throw new ConfigError(`config.launch.${k}: true or false`);
+    return v;
+}
+export const SECTIONS = { launch: parseLaunch };
+function check(cfg) {
+    if (cfg.payer !== "embedded")
+        throw new ConfigError('config.payer: the launch helper launches from the account\'s main wallet through Candle\'s atomic route; set "payer": "embedded" (Candle refuses a TEE wallet on that route)');
+    // The live run's pre-flight refuses too (a --mode live override is checked there).
+    if (cfg.mode === "live" && cfg.launch.minDevBuyOutRaw === undefined)
+        throw new ConfigError("config.launch.minDevBuyOutRaw: required in live mode (the dev buy's on-chain minimum is 0 inside the bundle; `plan` previews Candle's fill to set it from)");
+    return cfg;
+}
+export function parseConfig(raw, baseDir = process.cwd()) {
+    return check(parseCore(raw, baseDir, SECTIONS));
+}
+export function loadConfig(path) {
+    return check(loadCore(path, SECTIONS));
+}

package/dist/index.d.ts

@@ -0,0 +1,8 @@
+/** candle-launch-helper: the launcher, its trigger and engine, the config and the ledger, for use as a library. */
+export { Launcher, LaunchTrigger, Engine, launchBody, specHash, BUILD_SUBMIT_MS, JOB_READ_MS, RETRY_FILE, LAUNCH_LIST_PAGES, DEV_BUY_PAGE, DEV_BUY_PAGES } from "./launcher.ts";
+export type { LaunchClient, LauncherDeps, EngineDeps } from "./launcher.ts";
+export { parseConfig, loadConfig, SECTIONS, ConfigError, LAUNCH_MODES } from "./config.ts";
+export type { Config, LaunchSpec, LaunchMode } from "./config.ts";
+export { Ledger } from "./ledger.ts";
+export type { LaunchRow, LaunchState } from "./ledger.ts";
+export { main, HELP, planOutput } from "./cli.ts";

package/dist/index.js

@@ -0,0 +1,5 @@
+/** candle-launch-helper: the launcher, its trigger and engine, the config and the ledger, for use as a library. */
+export { Launcher, LaunchTrigger, Engine, launchBody, specHash, BUILD_SUBMIT_MS, JOB_READ_MS, RETRY_FILE, LAUNCH_LIST_PAGES, DEV_BUY_PAGE, DEV_BUY_PAGES } from "./launcher.js";
+export { parseConfig, loadConfig, SECTIONS, ConfigError, LAUNCH_MODES } from "./config.js";
+export { Ledger } from "./ledger.js";
+export { main, HELP, planOutput } from "./cli.js";