candle-launch-bot 0.0.0-stage → 0.1.0

package/dist/cli.js

@@ -0,0 +1,321 @@
+/** The command line: init, scan, run, status, sell. */
+import { CandleClient } from "@candledottv/agent-sdk";
+import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { loadConfig, ConfigError } from "./config.js";
+import { Detector } from "./detect/detector.js";
+import { Engine, acquireLock } from "./engine.js";
+import { Executor } from "./exec/executor.js";
+import { EmbeddedRail, makeSecretStore, resolveEmbedded, resolveWallet, SdkRail, timedFetch } from "./exec/trader.js";
+import { makeAlerter } from "./alerts.js";
+import { evaluate } from "./filters.js";
+import { Ledger } from "./ledger.js";
+import { makeLogger } from "./log.js";
+import { decodeCandleCurve } from "./market/curve.js";
+import { dryPricer } from "./market/reader.js";
+import { addSecret, redact } from "./redact.js";
+import { candleCurve } from "./solana/pda.js";
+import { PUBLIC_RPC, httpRpc } from "./solana/rpc.js";
+import { wsUrlFor } from "./solana/logs-ws.js";
+import { loadStrategy } from "./strategies/load.js";
+import { init, terminalAsk } from "./init.js";
+export const HELP = `candle-launch-bot: buys Candle launches as they appear and exits them by a strategy.
+
+  candle-launch-bot init   [--out bot.json] [--yes] [flags]   write a config (dry mode unless --mode live)
+  candle-launch-bot scan   --config bot.json [--for 600]       detect and print what it would buy; never trades
+  candle-launch-bot run    --config bot.json [--mode dry|live] run the bot
+  candle-launch-bot status --config bot.json                   print status.json
+  candle-launch-bot sell   <mint> --config bot.json [--fraction 1]
+
+init flags (all optional; with --yes nothing is asked; defaults shown):
+  --mode dry|live (dry)  --payer embedded|linked (embedded)  --key-env <env var with the API key> (CANDLE_API_KEY)
+  --wallet <address> (looked up when the key is set)  --api-url <https url>
+  --sol 0.01  --max-open 3  --lifetime-sol (10 tickets)  --modes open,exp-custom  --max-age 60  --max-impact 300
+  --slippage 500
+  --exit hold|tpsl|time|ladder|preGrad (tpsl)  --take-profit 2  --stop-loss 0.5  --trailing <0-1>  --after-sec 900
+  --progress 0.8  --fraction 1  --rungs 2:0.3,5:0.3,10:0.2
+  --exit-module ./my-exit.js  --exit-params '{"arm":1.5}'   your own strategy file and its params
+  --signer keychain|file|env (keychain)  --signer-env <env var with the PEM>  --signer-path <file>
+  --signer-pass-env <env var with the file's passphrase>      payer linked only
+  --rpc-env <env var with an RPC url>  --rpc-ws-env <env var with a websocket url>
+  --webhook <env var with an alert webhook url>  --state-dir <dir> (./state-dry or ./state-live)
+  --out bot.json  --force (overwrite)
+
+Controls: create STOP or PAUSE_BUYS in the state folder. Docs: the README.
+`;
+/** Longest a single Candle API call may take (build, sign relay, submit, reads). */
+const SDK_TIMEOUT_MS = 45_000;
+function args(argv) {
+    const pos = [];
+    const opt = {};
+    for (let i = 0; i < argv.length; i++) {
+        const a = argv[i];
+        if (a.startsWith("--")) {
+            const [k, v] = a.slice(2).split("=", 2);
+            if (v !== undefined)
+                opt[k] = v;
+            else if (i + 1 < argv.length && !argv[i + 1].startsWith("--"))
+                opt[k] = argv[++i];
+            else
+                opt[k] = "true";
+        }
+        else
+            pos.push(a);
+    }
+    return { pos, opt };
+}
+function die(msg, code = 2) {
+    process.stderr.write(redact(msg) + "\n");
+    process.exit(code);
+}
+function context(configPath, modeOverride) {
+    let cfg;
+    try {
+        cfg = loadConfig(configPath);
+    }
+    catch (e) {
+        if (e instanceof ConfigError)
+            die(e.message);
+        throw e;
+    }
+    if (modeOverride) {
+        if (modeOverride !== "dry" && modeOverride !== "live")
+            die("--mode: dry or live");
+        if (modeOverride === "live" && cfg.mode !== "live")
+            die('--mode live needs "mode": "live" in the config too (and, for payer linked, its signer)');
+        cfg = { ...cfg, mode: modeOverride };
+    }
+    const apiKey = process.env[cfg.apiKeyEnv];
+    addSecret(apiKey);
+    const rpcUrl = (cfg.rpcUrlEnv && process.env[cfg.rpcUrlEnv]) || PUBLIC_RPC;
+    const wsUrl = (cfg.rpcWsUrlEnv && process.env[cfg.rpcWsUrlEnv]) || wsUrlFor(rpcUrl);
+    addSecret(rpcUrl);
+    addSecret(wsUrl);
+    mkdirSync(cfg.stateDir, { recursive: true });
+    const log = makeLogger({ file: join(cfg.stateDir, "events.jsonl") });
+    // Every SDK request carries a timeout: the SDK's own requests have none.
+    const client = new CandleClient({ apiUrl: cfg.apiUrl, apiKey: apiKey || undefined, privyAppId: cfg.privyAppId, solanaRpcUrl: rpcUrl, fetch: timedFetch(SDK_TIMEOUT_MS) });
+    return { cfg, rpc: httpRpc(rpcUrl), wsUrl, client, log };
+}
+async function buildRail(ctx) {
+    if (ctx.cfg.mode !== "live")
+        return { rail: null };
+    const apiKey = process.env[ctx.cfg.apiKeyEnv];
+    if (!apiKey)
+        die(`${ctx.cfg.apiKeyEnv} is not set (the Candle API key)`);
+    if (ctx.cfg.payer === "embedded") {
+        const e = await resolveEmbedded(ctx.cfg, apiKey, timedFetch(SDK_TIMEOUT_MS));
+        ctx.log.info("wallet_resolved", { wallet: e.address, payer: "embedded", permission: e.permission });
+        return { rail: new EmbeddedRail(new CandleClient({ apiUrl: ctx.cfg.apiUrl, apiKey, fetch: timedFetch(SDK_TIMEOUT_MS) })) };
+    }
+    const w = await resolveWallet(ctx.cfg, apiKey, timedFetch(SDK_TIMEOUT_MS));
+    const store = await makeSecretStore(ctx.cfg, w);
+    const client = new CandleClient({ apiUrl: ctx.cfg.apiUrl, apiKey, privyAppId: w.privyAppId, secretStore: store, fetch: timedFetch(SDK_TIMEOUT_MS) });
+    if (!(await store.get(w.linkedWalletId)))
+        die(`no signer key for TEE wallet ${ctx.cfg.wallet} in the ${ctx.cfg.signer.store} store (key ${w.keyPrefix})`);
+    ctx.log.info("wallet_resolved", { wallet: ctx.cfg.wallet, linkedWalletId: w.linkedWalletId, keyPrefix: w.keyPrefix, signer: ctx.cfg.signer.store });
+    return { rail: new SdkRail(client, w), linkedWalletId: w.linkedWalletId };
+}
+async function makeEngine(ctx, ledger) {
+    const strategy = await loadStrategy(ctx.cfg.exit, ctx.cfg.configDir).catch((e) => die(String(e.message)));
+    const { rail, linkedWalletId } = await buildRail(ctx);
+    const decimals = new Map();
+    const modes = ledger.modes();
+    if ((ctx.cfg.mode === "dry" && modes.live) || (ctx.cfg.mode === "live" && modes.dry))
+        die(`${ctx.cfg.stateDir} holds ${modes.live ? "live" : "dry"} positions; use a separate stateDir for ${ctx.cfg.mode} runs`);
+    let alerter;
+    try {
+        alerter = makeAlerter(ctx.cfg.alerts, ledger, ctx.log);
+    }
+    catch (e) {
+        die(String(e.message));
+    }
+    const executor = new Executor({
+        cfg: ctx.cfg, ledger, rail, linkedWalletId, rpc: ctx.rpc, log: ctx.log, alerter,
+        buysPaused: () => existsSync(join(ctx.cfg.stateDir, "PAUSE_BUYS")),
+        dry: dryPricer(ctx.rpc, ctx.client, (m) => decimals.get(m) ?? ledger.allPositions().find((p) => p.mint === m)?.decimals ?? 6),
+    });
+    const detector = new Detector({ rpc: ctx.rpc, wsUrl: ctx.cfg.detect.chain ? ctx.wsUrl : undefined, apiUrl: ctx.cfg.apiUrl, log: ctx.log }, ctx.cfg.detect);
+    const engine = new Engine({ cfg: ctx.cfg, ledger, detector, executor, strategy, rpc: ctx.rpc, log: ctx.log, alerter, markets: ctx.client });
+    return { engine, detector };
+}
+async function run(ctx) {
+    const lock = acquireLock(ctx.cfg.stateDir);
+    if (!lock)
+        die(`another process holds ${ctx.cfg.stateDir}/lock`);
+    const ledger = new Ledger(join(ctx.cfg.stateDir, "ledger.sqlite"));
+    const { engine, detector } = await makeEngine(ctx, ledger);
+    let stopping = false;
+    const stop = () => {
+        if (!stopping)
+            ctx.log.info("signal_stop");
+        stopping = true;
+        engine.requestStop();
+    };
+    process.on("SIGINT", stop);
+    process.on("SIGTERM", stop);
+    ctx.log.info("start", { mode: ctx.cfg.mode, payer: ctx.cfg.payer, wallet: ctx.cfg.wallet, strategy: ctx.cfg.exit.strategy, stateDir: ctx.cfg.stateDir, ticketSol: ctx.cfg.buy.sol, maxOpen: ctx.cfg.buy.maxOpen, lifetimeSol: ctx.cfg.buy.lifetimeSol });
+    await detector.start();
+    try {
+        while (await engine.cycle())
+            await new Promise((r) => setTimeout(r, ctx.cfg.loopMs));
+    }
+    finally {
+        detector.stop();
+        engine.writeStatus();
+        ledger.close();
+        lock.release();
+        ctx.log.info("stopped");
+    }
+    return 0;
+}
+async function scan(ctx, seconds) {
+    const det = new Detector({ rpc: ctx.rpc, wsUrl: ctx.cfg.detect.chain ? ctx.wsUrl : undefined, apiUrl: ctx.cfg.apiUrl, log: ctx.log }, ctx.cfg.detect);
+    await det.start();
+    const stopAt = seconds ? Date.now() + seconds * 1000 : Infinity;
+    const waiting = new Map();
+    let quit = false;
+    process.on("SIGINT", () => (quit = true));
+    process.on("SIGTERM", () => (quit = true));
+    const caps = { open: 0, entriesForMint: 0, lifetimeLamports: 0n, paused: false };
+    while (!quit && Date.now() < stopAt) {
+        for (const l of det.drain())
+            waiting.set(l.mint, Date.now());
+        for (const mint of [...waiting.keys()]) {
+            const l = det.get(mint);
+            let v = evaluate(ctx.cfg, l, null, caps, Date.now());
+            if (v.verdict === "wait" && /unknown/.test(v.reason)) {
+                try {
+                    const m = await ctx.client.getMarket("solana", mint);
+                    if (m?.tier && !l.launchMode)
+                        l.launchMode = m.tier;
+                    if (m?.metadata?.name && l.name === undefined)
+                        l.name = m.metadata.name;
+                    if (m?.metadata?.symbol && l.symbol === undefined)
+                        l.symbol = m.metadata.symbol;
+                }
+                catch { /* not indexed yet */ }
+                v = evaluate(ctx.cfg, l, null, caps, Date.now());
+            }
+            if (v.verdict === "wait" && v.reason === "curve not readable yet") {
+                try {
+                    const r = await ctx.rpc.call("getAccountInfo", [l.curve ?? candleCurve(mint), { encoding: "base64", commitment: "confirmed" }]);
+                    v = evaluate(ctx.cfg, l, r?.value ? decodeCandleCurve(r.value) : null, caps, Date.now());
+                }
+                catch { /* next round */ }
+            }
+            if (v.verdict === "wait")
+                continue;
+            waiting.delete(mint);
+            const s = det.sightingsFor(mint);
+            ctx.log.info(v.verdict === "buy" ? "scan_would_buy" : "scan_skip", {
+                mint, symbol: l.symbol, name: l.name, mode: l.launchMode, creator: l.creator, signer: l.signer, firstSource: l.source,
+                apiLatencyMs: s.api?.latencyMs ?? null, chainLatencyMs: s.chain?.latencyMs ?? null, ...(v.verdict === "buy" ? { impactBps: v.impactBps, sol: ctx.cfg.buy.sol } : { reason: v.reason }),
+            });
+        }
+        await new Promise((r) => setTimeout(r, 1000));
+    }
+    det.stop();
+    ctx.log.info("scan_done", { api: det.stats.api, chain: det.stats.chain });
+    return 0;
+}
+function status(ctx) {
+    const p = join(ctx.cfg.stateDir, "status.json");
+    if (!existsSync(p))
+        die(`no ${p} yet (has the bot run?)`, 1);
+    process.stdout.write(readFileSync(p, "utf8") + "\n");
+    return 0;
+}
+async function sell(ctx, mint, fraction) {
+    if (!(fraction > 0 && fraction <= 1))
+        die("--fraction must be in (0, 1]");
+    const lock = acquireLock(ctx.cfg.stateDir);
+    if (!lock) {
+        // The bot is running: hand it the request; it runs the sell through its own executor.
+        const dir = join(ctx.cfg.stateDir, "requests");
+        mkdirSync(dir, { recursive: true });
+        const f = join(dir, `sell-${Date.now()}-${process.pid}.json`);
+        writeFileSync(f + ".tmp", JSON.stringify({ mint, fraction }));
+        renameSync(f + ".tmp", f); // the bot only reads complete files
+        process.stdout.write(`the bot is running: request written to ${f}; watch events.jsonl for manual_sell_request\n`);
+        return 0;
+    }
+    const ledger = new Ledger(join(ctx.cfg.stateDir, "ledger.sqlite"));
+    try {
+        const { engine } = await makeEngine(ctx, ledger);
+        const r = await engine.manualSell(mint, fraction);
+        process.stdout.write(r + "\n");
+        const m = /^order (\d+)$/.exec(r);
+        if (!m)
+            return 1;
+        const id = Number(m[1]);
+        const exec = engine.d.executor;
+        for (let i = 0; i < 600; i++) {
+            await exec.sweep(1, { onlyIds: [id] }); // only this order: never a stale buy queued by an earlier run
+            const o = ledger.order(id);
+            if (!["pending", "inflight"].includes(o.status)) {
+                process.stdout.write(`order ${id}: ${o.status}${o.last_error_code ? " (" + o.last_error_code + ")" : ""}\n`);
+                return o.status === "filled" ? 0 : 1;
+            }
+            await new Promise((r) => setTimeout(r, Math.max(500, Math.min(5000, o.next_attempt_at - Date.now()))));
+        }
+        process.stdout.write(`order ${id} still open; it resumes on the next run\n`);
+        return 1;
+    }
+    finally {
+        ledger.close();
+        lock.release();
+    }
+}
+/** The entry point: never lets an error out unredacted (the SDK puts RPC URLs in its messages). */
+export async function main(argv = process.argv.slice(2)) {
+    try {
+        return await mainInner(argv);
+    }
+    catch (e) {
+        process.stderr.write(redact(String(e?.stack ?? e)) + "\n");
+        return 1;
+    }
+}
+async function mainInner(argv) {
+    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;
+    }
+    if (cmd === "init") {
+        const interactive = !opt.yes && process.stdin.isTTY === true;
+        const t = interactive ? terminalAsk() : null;
+        try {
+            return await init(opt, { env: process.env, fetch, out: (s) => void process.stdout.write(s), ...(t ? { ask: t.ask } : {}) });
+        }
+        catch (e) {
+            if (e instanceof ConfigError || e?.name === "StrategyConfigError")
+                die(String(e.message));
+            throw e;
+        }
+        finally {
+            t?.close();
+        }
+    }
+    const config = opt.config ?? "bot.json";
+    switch (cmd) {
+        case "run":
+            return run(context(config, opt.mode));
+        case "scan":
+            return scan(context(config, "dry"), opt.for ? Number(opt.for) : null);
+        case "status":
+            return status(context(config));
+        case "sell":
+            if (!pos[1])
+                die("sell <mint> [--fraction f]");
+            return sell(context(config), pos[1], opt.fraction ? Number(opt.fraction) : 1);
+        default:
+            die(`unknown command ${cmd}`);
+    }
+}

package/dist/config.d.ts

@@ -0,0 +1,88 @@
+export type Mode = "dry" | "live";
+export type SignerConfig = {
+    store: "keychain";
+} | {
+    store: "file";
+    path: string;
+    passphraseEnv: string;
+} | {
+    store: "env";
+    pemEnv: string;
+};
+export type Payer = "linked" | "embedded";
+export interface Config {
+    mode: Mode;
+    /** linked: a TEE wallet signed locally with the key signer; embedded: the account's embedded wallet, signed by Candle. */
+    payer: Payer;
+    apiUrl: string;
+    apiKeyEnv: string;
+    rpcUrlEnv?: string;
+    rpcWsUrlEnv?: string;
+    wallet: string;
+    linkedWalletId?: string;
+    privyWalletId?: string;
+    privyAppId?: string;
+    signer?: SignerConfig;
+    stateDir: string;
+    loopMs: number;
+    buy: {
+        sol: number;
+        maxSlippageBps: number;
+        maxOpen: number;
+        lifetimeSol: number;
+        maxPerCoin: number;
+        maxPriorityFeeLamports?: number;
+    };
+    sell: {
+        maxSlippageBps: number;
+        maxPriorityFeeLamports?: number;
+    };
+    filters: {
+        chains: string[];
+        launchModes: string[];
+        maxAgeSec: number;
+        maxImpactBps: number;
+        creatorAllow?: string[];
+        creatorDeny?: string[];
+        nameMatch?: string;
+        symbolMatch?: string;
+        /** Classify a chain-first launch from its curve account (open / exclusive / exp-*) instead of waiting on Candle's list. */
+        inferModeFromCurve: boolean;
+    };
+    detect: {
+        api: boolean;
+        chain: boolean;
+        apiPollMs: number;
+        chainPollMs: number;
+        apiLimit: number;
+    };
+    exit: {
+        strategy: string;
+        [param: string]: unknown;
+    };
+    retry: {
+        maxAttempts: number;
+        baseDelayMs: number;
+        maxDelayMs: number;
+        maxExitOrders: number;
+        stuckRetryMs: number;
+        builtProbeMs: number;
+        builtHoldMs: number;
+    };
+    alerts: {
+        command?: string[];
+        commandEnv?: string[];
+        webhookEnv?: string;
+        renotifyMs: number;
+        holdAlertMs: number;
+    };
+    /** The folder of the config file: relative paths in it (stateDir, signer.path, exit.module) resolve here. */
+    configDir: string;
+}
+export declare class ConfigError extends Error {
+}
+/** Candle's launch modes (agent-sdk 0.6.14 launch-definition `curve.values`). */
+export declare const LAUNCH_MODES: string[];
+export declare const KNOWN_CHAINS: string[];
+export declare function parseConfig(raw: unknown, baseDir?: string): Config;
+export declare function loadConfig(path: string): Config;

package/dist/config.js

@@ -0,0 +1,244 @@
+/**
+ * The one config file. Validated at start; unknown keys are refused at every level so a typo can never be
+ * silently ignored. Secrets never live here: the file names the environment variables that hold them.
+ */
+import { readFileSync } from "node:fs";
+import { dirname, resolve } from "node:path";
+import { asAddress } from "./solana/base58.js";
+export class ConfigError extends Error {
+}
+function isObj(v) {
+    return typeof v === "object" && v !== null && !Array.isArray(v);
+}
+function only(o, allowed, where) {
+    for (const k of Object.keys(o))
+        if (!allowed.includes(k))
+            throw new ConfigError(`${where}: unknown key "${k}"`);
+}
+function num(o, k, where, opts = {}) {
+    const v = o[k];
+    if (v === undefined) {
+        if (opts.def !== undefined)
+            return opts.def;
+        throw new ConfigError(`${where}.${k}: required`);
+    }
+    if (typeof v !== "number" || !Number.isFinite(v))
+        throw new ConfigError(`${where}.${k}: must be a number`);
+    if (opts.int && !Number.isInteger(v))
+        throw new ConfigError(`${where}.${k}: must be an integer`);
+    if (opts.min !== undefined && v < opts.min)
+        throw new ConfigError(`${where}.${k}: must be >= ${opts.min}`);
+    if (opts.max !== undefined && v > opts.max)
+        throw new ConfigError(`${where}.${k}: must be <= ${opts.max}`);
+    return v;
+}
+function str(o, k, where, opts = {}) {
+    const v = o[k];
+    if (v === undefined) {
+        if (opts.def !== undefined)
+            return opts.def;
+        if (opts.optional)
+            return undefined;
+        throw new ConfigError(`${where}.${k}: required`);
+    }
+    if (typeof v !== "string" || !v)
+        throw new ConfigError(`${where}.${k}: must be a non-empty string`);
+    if (opts.re && !opts.re.test(v))
+        throw new ConfigError(`${where}.${k}: invalid value`);
+    return v;
+}
+function bool(o, k, where, def) {
+    const v = o[k];
+    if (v === undefined)
+        return def;
+    if (typeof v !== "boolean")
+        throw new ConfigError(`${where}.${k}: must be true or false`);
+    return v;
+}
+function strList(o, k, where, opts = {}) {
+    const v = o[k];
+    if (v === undefined)
+        return opts.def;
+    if (!Array.isArray(v) || v.some((x) => typeof x !== "string" || !x))
+        throw new ConfigError(`${where}.${k}: must be a list of strings`);
+    if (opts.address)
+        for (const a of v)
+            if (!asAddress(a))
+                throw new ConfigError(`${where}.${k}: "${a}" is not an address`);
+    return v;
+}
+function regex(o, k, where) {
+    const v = str(o, k, where, { optional: true });
+    if (v === undefined)
+        return v;
+    try {
+        new RegExp(v, "i");
+    }
+    catch {
+        throw new ConfigError(`${where}.${k}: not a valid regular expression`);
+    }
+    return v;
+}
+const ENV_NAME = /^[A-Za-z_][A-Za-z0-9_]*$/;
+/** Candle's launch modes (agent-sdk 0.6.14 launch-definition `curve.values`). */
+export const LAUNCH_MODES = ["open", "exclusive", "test-open", "test-exclusive", "exp-a", "exp-b", "exp-c", "exp-custom"];
+export const KNOWN_CHAINS = ["solana"];
+export function parseConfig(raw, baseDir = process.cwd()) {
+    if (!isObj(raw))
+        throw new ConfigError("config: must be a JSON object");
+    only(raw, ["mode", "apiUrl", "apiKeyEnv", "rpcUrlEnv", "rpcWsUrlEnv", "wallet", "linkedWalletId", "privyWalletId", "privyAppId",
+        "signer", "payer", "stateDir", "loopMs", "buy", "sell", "filters", "detect", "exit", "retry", "alerts", "$schema", "comment"], "config");
+    const mode = str(raw, "mode", "config");
+    if (mode !== "dry" && mode !== "live")
+        throw new ConfigError('config.mode: must be "dry" or "live"');
+    const apiUrl = str(raw, "apiUrl", "config", { def: "https://api.alpha.candle.tv" });
+    if (!/^https:\/\//.test(apiUrl))
+        throw new ConfigError("config.apiUrl: must be https://");
+    const apiKeyEnv = str(raw, "apiKeyEnv", "config", { re: ENV_NAME });
+    const rpcUrlEnv = str(raw, "rpcUrlEnv", "config", { optional: true, re: ENV_NAME });
+    const rpcWsUrlEnv = str(raw, "rpcWsUrlEnv", "config", { optional: true, re: ENV_NAME });
+    const wallet = str(raw, "wallet", "config");
+    if (!asAddress(wallet))
+        throw new ConfigError("config.wallet: not a Solana address");
+    const linkedWalletId = str(raw, "linkedWalletId", "config", { optional: true, re: /^[A-Za-z0-9_-]{4,128}$/ });
+    const privyWalletId = str(raw, "privyWalletId", "config", { optional: true, re: /^[A-Za-z0-9_-]{4,128}$/ });
+    const privyAppId = str(raw, "privyAppId", "config", { optional: true, re: /^[A-Za-z0-9]{8,64}$/ });
+    let signer;
+    if (raw.signer !== undefined) {
+        const s = raw.signer;
+        if (!isObj(s))
+            throw new ConfigError("config.signer: must be an object");
+        const store = str(s, "store", "config.signer");
+        if (store === "keychain") {
+            only(s, ["store"], "config.signer");
+            signer = { store };
+        }
+        else if (store === "file") {
+            only(s, ["store", "path", "passphraseEnv"], "config.signer");
+            signer = { store, path: resolve(baseDir, str(s, "path", "config.signer")), passphraseEnv: str(s, "passphraseEnv", "config.signer", { re: ENV_NAME }) };
+        }
+        else if (store === "env") {
+            only(s, ["store", "pemEnv"], "config.signer");
+            signer = { store, pemEnv: str(s, "pemEnv", "config.signer", { re: ENV_NAME }) };
+        }
+        else
+            throw new ConfigError('config.signer.store: "keychain", "file" or "env"');
+    }
+    const payer = str(raw, "payer", "config", { def: "linked" });
+    if (payer !== "linked" && payer !== "embedded")
+        throw new ConfigError('config.payer: "linked" (TEE wallet, local signer) or "embedded" (Candle signs)');
+    if (payer === "embedded" && (signer || privyAppId || linkedWalletId || privyWalletId))
+        throw new ConfigError("config: payer \"embedded\" signs on Candle's side; remove signer / privyAppId / linkedWalletId / privyWalletId");
+    if (mode === "live" && payer === "linked" && !signer)
+        throw new ConfigError("config.signer: required in live mode with payer \"linked\" (where the wallet's P-256 signer key lives)");
+    const stateDir = resolve(baseDir, str(raw, "stateDir", "config", { def: "./state" }));
+    const loopMs = num(raw, "loopMs", "config", { min: 200, max: 60_000, int: true, def: 2000 });
+    if (!isObj(raw.buy))
+        throw new ConfigError("config.buy: required object");
+    const b = raw.buy;
+    only(b, ["sol", "maxSlippageBps", "maxOpen", "lifetimeSol", "maxPerCoin", "maxPriorityFeeLamports"], "config.buy");
+    const buy = {
+        sol: num(b, "sol", "config.buy", { min: 0.000001, max: 1000 }),
+        maxSlippageBps: num(b, "maxSlippageBps", "config.buy", { min: 0, max: 10_000, int: true }),
+        maxOpen: num(b, "maxOpen", "config.buy", { min: 0, int: true }),
+        lifetimeSol: num(b, "lifetimeSol", "config.buy", { min: 0 }),
+        // One entry per coin: re-entry is not supported (a second position in a coin would share its wallet balance).
+        maxPerCoin: num(b, "maxPerCoin", "config.buy", { min: 1, max: 1, int: true, def: 1 }),
+        maxPriorityFeeLamports: b.maxPriorityFeeLamports === undefined ? undefined : num(b, "maxPriorityFeeLamports", "config.buy", { min: 0, max: 10_000_000, int: true }),
+    };
+    const sl = raw.sell === undefined ? {} : raw.sell;
+    if (!isObj(sl))
+        throw new ConfigError("config.sell: must be an object");
+    only(sl, ["maxSlippageBps", "maxPriorityFeeLamports"], "config.sell");
+    const sell = {
+        maxSlippageBps: num(sl, "maxSlippageBps", "config.sell", { min: 0, max: 10_000, int: true, def: Math.max(buy.maxSlippageBps, 1000) }),
+        maxPriorityFeeLamports: sl.maxPriorityFeeLamports === undefined ? undefined : num(sl, "maxPriorityFeeLamports", "config.sell", { min: 0, max: 10_000_000, int: true }),
+    };
+    if (!isObj(raw.filters))
+        throw new ConfigError("config.filters: required object");
+    const f = raw.filters;
+    only(f, ["chains", "launchModes", "maxAgeSec", "maxImpactBps", "creatorAllow", "creatorDeny", "nameMatch", "symbolMatch", "inferModeFromCurve"], "config.filters");
+    const chains = strList(f, "chains", "config.filters", { def: ["solana"] });
+    for (const c of chains)
+        if (!KNOWN_CHAINS.includes(c))
+            throw new ConfigError(`config.filters.chains: "${c}" is not supported yet (${KNOWN_CHAINS.join(", ")})`);
+    const launchModes = strList(f, "launchModes", "config.filters");
+    if (!launchModes || !launchModes.length)
+        throw new ConfigError("config.filters.launchModes: required, e.g. [\"open\", \"exp-custom\"]");
+    for (const m of launchModes)
+        if (!LAUNCH_MODES.includes(m))
+            throw new ConfigError(`config.filters.launchModes: "${m}" is not a Candle launch mode (${LAUNCH_MODES.join(", ")})`);
+    const filters = {
+        chains,
+        launchModes,
+        maxAgeSec: num(f, "maxAgeSec", "config.filters", { min: 1 }),
+        maxImpactBps: num(f, "maxImpactBps", "config.filters", { min: 0, max: 10_000 }),
+        creatorAllow: strList(f, "creatorAllow", "config.filters", { address: true }),
+        creatorDeny: strList(f, "creatorDeny", "config.filters", { address: true }),
+        nameMatch: regex(f, "nameMatch", "config.filters"),
+        symbolMatch: regex(f, "symbolMatch", "config.filters"),
+        inferModeFromCurve: bool(f, "inferModeFromCurve", "config.filters", true),
+    };
+    const d = raw.detect === undefined ? {} : raw.detect;
+    if (!isObj(d))
+        throw new ConfigError("config.detect: must be an object");
+    only(d, ["api", "chain", "apiPollMs", "chainPollMs", "apiLimit"], "config.detect");
+    const detect = {
+        api: bool(d, "api", "config.detect", true),
+        chain: bool(d, "chain", "config.detect", true),
+        apiPollMs: num(d, "apiPollMs", "config.detect", { min: 500, int: true, def: 3000 }),
+        chainPollMs: num(d, "chainPollMs", "config.detect", { min: 1000, int: true, def: 15_000 }),
+        apiLimit: num(d, "apiLimit", "config.detect", { min: 1, max: 200, int: true, def: 20 }),
+    };
+    if (!detect.api && !detect.chain)
+        throw new ConfigError("config.detect: at least one of api and chain must be on");
+    if (!isObj(raw.exit))
+        throw new ConfigError("config.exit: required object with a strategy name");
+    const strategy = str(raw.exit, "strategy", "config.exit", { re: /^[A-Za-z][A-Za-z0-9_-]{0,40}$/ });
+    const exit = { ...raw.exit, strategy };
+    const r = raw.retry === undefined ? {} : raw.retry;
+    if (!isObj(r))
+        throw new ConfigError("config.retry: must be an object");
+    only(r, ["maxAttempts", "baseDelayMs", "maxDelayMs", "maxExitOrders", "stuckRetryMs", "builtProbeMs", "builtHoldMs"], "config.retry");
+    const retry = {
+        maxAttempts: num(r, "maxAttempts", "config.retry", { min: 1, max: 50, int: true, def: 6 }),
+        baseDelayMs: num(r, "baseDelayMs", "config.retry", { min: 100, int: true, def: 2000 }),
+        maxDelayMs: num(r, "maxDelayMs", "config.retry", { min: 100, int: true, def: 120_000 }),
+        maxExitOrders: num(r, "maxExitOrders", "config.retry", { min: 1, max: 20, int: true, def: 3 }),
+        stuckRetryMs: num(r, "stuckRetryMs", "config.retry", { min: 60_000, int: true, def: 600_000 }),
+        builtProbeMs: num(r, "builtProbeMs", "config.retry", { min: 60_000, int: true, def: 600_000 }),
+        builtHoldMs: num(r, "builtHoldMs", "config.retry", { min: 600_000, int: true, def: 21_600_000 }),
+    };
+    const al = raw.alerts === undefined ? {} : raw.alerts;
+    if (!isObj(al))
+        throw new ConfigError("config.alerts: must be an object");
+    only(al, ["command", "commandEnv", "webhookEnv", "renotifyMs", "holdAlertMs"], "config.alerts");
+    const command = strList(al, "command", "config.alerts");
+    if (command && !command.length)
+        throw new ConfigError("config.alerts.command: an argv list, e.g. [\"/usr/local/bin/notify\", \"bot\"]");
+    const alerts = {
+        command,
+        commandEnv: strList(al, "commandEnv", "config.alerts"),
+        webhookEnv: str(al, "webhookEnv", "config.alerts", { optional: true, re: ENV_NAME }),
+        renotifyMs: num(al, "renotifyMs", "config.alerts", { min: 60_000, int: true, def: 3_600_000 }),
+        holdAlertMs: num(al, "holdAlertMs", "config.alerts", { min: 0, int: true, def: 300_000 }),
+    };
+    return { mode, payer, apiUrl, apiKeyEnv, rpcUrlEnv, rpcWsUrlEnv, wallet, linkedWalletId, privyWalletId, privyAppId, signer, stateDir, loopMs, buy, sell, filters, detect, exit, retry, alerts, configDir: resolve(baseDir) };
+}
+export function loadConfig(path) {
+    let text;
+    try {
+        text = readFileSync(path, "utf8");
+    }
+    catch (e) {
+        throw new ConfigError(`cannot read config ${path}: ${e.message}`);
+    }
+    let raw;
+    try {
+        raw = JSON.parse(text);
+    }
+    catch (e) {
+        throw new ConfigError(`config ${path} is not valid JSON: ${e.message}`);
+    }
+    return parseConfig(raw, dirname(resolve(path)));
+}