candle-creator-bot 0.0.0-stage → 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,12 @@
+# Changelog: candle-creator-bot
+
+## 0.1.0
+
+First release, on candle-bot-core 0.4.0 (pinned exactly).
+
+- Follows a list of creators (Candle token-list creator or launch signer) through the core's launch source. Each
+  creator has an optional label, ticket (at most `buy.sol`), and lifetime caps on entries and SOL, counted from the
+  ledger's positions for that creator with the core's rules for what spent. The core's caps on top.
+- Global filters as candle-launch-bot's: launch modes, max age, impact on the curve; a chain-first launch waits for
+  Candle's market record; creator unknown waits. Optional: wait for the creator's own dev buy.
+- `run`, `status` (per-creator use), `sell`; `STOP`, `PAUSE_BUYS`; a `follows` table in the ledger.

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,115 @@
-# Temporary Holding Version
+# candle-creator-bot
 
-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.
+Buys the new [Candle](https://candle.tv) launches of the creators you list, with a ticket and caps per creator, and
+exits them by a strategy you pick. One config file, one process, a local SQLite ledger. 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), the engine
+[candle-launch-bot](https://www.npmjs.com/package/candle-launch-bot) runs on.
+
+Built by [Bruce Jeet](https://github.com/BruceJeet).
+
+**How it differs from candle-launch-bot with `creatorAllow`:** the list of creators is the main input, not a filter
+on top of every launch: each creator has its own label, ticket and lifetime caps (entries and SOL), and `status.json`
+shows what each creator has used.
+
+- **What it buys:** a new Candle launch whose creator (from Candle's token list) or signer (the launch transaction's
+  fee payer) is on your list. A launch whose creator is not known yet waits, until Candle's list names it or the launch
+  ages out. Never a launch by your own wallet.
+- **Per creator:** `sol` (the ticket, at most `buy.sol`), `maxEntries` and `maxSol` over the bot's lifetime, on top of
+  the core's caps (`buy.maxOpen`, `buy.lifetimeSol`, `buy.maxPerCoin`). A creator's caps can only tighten them.
+- **Global filters**, as candle-launch-bot's: launch modes, max age, max impact of the ticket on the curve. Optional:
+  wait for the creator's own dev buy.
+- **Detection, execution, exits and dry mode** as candle-launch-bot: Candle's token list and the curve program on
+  chain; Candle's trade API from the embedded wallet or a TEE wallet; fills from the transaction; `hold`, `tpsl`,
+  `time`, `ladder`, `preGrad` or your own file.
+
+Solana only.
+
+## Quick start
+
+Node 22.18 or newer.
+
+```sh
+npm install -g candle-creator-bot          # or npx candle-creator-bot ...
+cp "$(npm root -g)/candle-creator-bot/examples/dry.json" bot.json   # put your creators in follow.creators
+candle-creator-bot run --config bot.json   # dry run: the whole loop with paper fills
+```
+
+For live: export the API key (`apiKeyEnv`), fund the wallet, set `"mode": "live"` and your `wallet`, run again.
+
+## What it needs
+
+- A **Candle API key** with the `swap:write` scope, in an environment variable (`apiKeyEnv`).
+- A **payer**: `embedded` (the account's embedded wallet; Candle signs) or `linked` (a TEE wallet signed on this
+  machine). Setup is the same as candle-launch-bot's; its README walks through it.
+- An **RPC** (`rpcUrlEnv`); the public one works for a dry run.
+- The **creators**: Candle wallet addresses. A launch matches when Candle's token list names the address as creator,
+  or when the address signed (paid for) the launch transaction.
+
+## Config reference
+
+The core's sections (`mode`, `payer`, `apiKeyEnv`, `rpcUrlEnv`, `wallet`, `signer`, `stateDir`, `buy`, `sell`, `exit`,
+`retry`, `alerts`) are the same as candle-launch-bot's. This bot adds:
+
+```json
+{
+  "follow": {
+    "creators": [
+      { "address": "<creator address>", "label": "dev one", "sol": 0.01, "maxEntries": 5, "maxSol": 0.05 },
+      { "address": "<another>" }
+    ],
+    "launchModes": ["open", "exclusive", "exp-a", "exp-b", "exp-c", "exp-custom"],
+    "maxAgeSec": 60,
+    "maxImpactBps": 300,
+    "inferModeFromCurve": true,
+    "requireDevBuy": false
+  },
+  "detect": { "api": true, "chain": true, "apiPollMs": 3000, "chainPollMs": 15000, "apiLimit": 20 }
+}
+```
+
+| Key | Meaning |
+|---|---|
+| `follow.creators[].address` | the creator (token list) or launch signer to follow; each listed once |
+| `follow.creators[].label` | a name for logs, the `follows` table and `status.json` (optional) |
+| `follow.creators[].sol` | this creator's ticket (default `buy.sol`, never above it) |
+| `follow.creators[].maxEntries` / `maxSol` | lifetime caps for this creator (optional). Counted from the ledger's positions for the creator, as the core counts `lifetimeSol`: a buy Candle refused before anything was signed, or one that reverted, does not count |
+| `follow.launchModes` | modes to buy (default every production mode) |
+| `follow.maxAgeSec` | buy only this soon after the launch (default 60); no order is built after it |
+| `follow.maxImpactBps` | impact of the creator's ticket on the curve (default 300); also the buy-retry limit |
+| `follow.inferModeFromCurve` | decide a chain-first launch's mode from its curve (only the full `open` preset) instead of waiting for Candle's list |
+| `follow.requireDevBuy` | buy only once the listed creator's own wallet holds the coin |
+| `detect.*` | the launch source, as candle-launch-bot's |
+
+## Controls
+
+`STOP` and `PAUSE_BUYS` files in the state dir; `candle-creator-bot sell <mint> [--fraction f]`. A restart picks up from
+the ledger, the creators' caps included.
+
+## State dir
+
+| File | What |
+|---|---|
+| `ledger.sqlite` | positions (each with the creator it followed in its entry context), orders, attempts, `follows` (every launch of a listed creator with the decision), alerts |
+| `status.json` | equity, open positions, caps used, `follow.creators` (entries and SOL used per creator), pending launches, recent decisions |
+| `events.jsonl` | one JSON line per event: `follow_buy`, `follow_skip`, `follow_wait`, `buy_order`, fills, exits |
+
+## Not here yet
+
+- **Selling when the creator sells.** Exits are the strategy's. A creator-sell exit needs a wallet watcher (the
+  creator's token account changes, from the chain); it would plug in as an exit source that marks the position for a
+  sell, the way a strategy's `sell` decision does.
+
+## Known limits
+
+- **Creator unknown waits.** A launch seen on chain first carries only its signer; if the signer is not on the list,
+  the bot waits for Candle's token list to name the creator, up to `follow.maxAgeSec`.
+- **Dev buy check.** `requireDevBuy` reads the listed creator's token balance in the coin, at most every 2 s. It
+  measures a holding, not a buy: it sees a dev buy in the launch transaction and one in the same block after it, and it
+  cannot tell a dev buy from a later buy, or from tokens handed to the creator's wallet at launch.
+- **One entry per coin.** `buy.maxPerCoin` is 1.
+- **Solana only.**
+
+## License
+
+MIT

package/bin/candle-creator-bot

@@ -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,3 @@
+export declare const HELP = "candle-creator-bot: buys the new Candle launches of the creators you list, with a ticket and caps per creator,\nand exits them by a strategy.\n\n  candle-creator-bot run    --config bot.json [--mode dry|live]  run the bot\n  candle-creator-bot status --config bot.json                    print status.json (each creator's entries and SOL used)\n  candle-creator-bot sell   <mint> --config bot.json [--fraction 1]\n\nStart from examples/dry.json and put your creators in follow.creators. Controls: STOP or PAUSE_BUYS in the state folder.\nDocs: the README.\n";
+/** The entry point: never lets an error out unredacted (the SDK puts RPC URLs in its messages). */
+export declare function main(argv?: string[]): Promise<number>;

package/dist/cli.js

@@ -0,0 +1,70 @@
+/** The command line: run, status, sell. */
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { args, context as coreContext, die, guardMain, parts, run, sell, status } from "candle-bot-core/runtime";
+import { Detector } from "candle-bot-core/sources/candleLaunches";
+import { loadConfig, ConfigError } from "./config.js";
+import { Ledger } from "./ledger.js";
+import { Engine } from "./trigger.js";
+export const HELP = `candle-creator-bot: buys the new Candle launches of the creators you list, with a ticket and caps per creator,
+and exits them by a strategy.
+
+  candle-creator-bot run    --config bot.json [--mode dry|live]  run the bot
+  candle-creator-bot status --config bot.json                    print status.json (each creator's entries and SOL used)
+  candle-creator-bot sell   <mint> --config bot.json [--fraction 1]
+
+Start from examples/dry.json and put your creators in follow.creators. Controls: STOP or PAUSE_BUYS in the state folder.
+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: ctx.cfg.follow.maxImpactBps });
+    const d = ctx.cfg.detect;
+    const source = new Detector({ rpc: ctx.rpc, wsUrl: d.chain ? ctx.wsUrl : undefined, apiUrl: ctx.cfg.apiUrl, log: ctx.log }, d);
+    const engine = new Engine({ cfg: ctx.cfg, ledger, source, executor, strategy, rpc: ctx.rpc, log: ctx.log, alerter, markets: ctx.client });
+    return { engine, trigger: engine.trigger };
+}
+const openLedger = (ctx) => () => new Ledger(join(ctx.cfg.stateDir, "ledger.sqlite"));
+/** 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)) {
+    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 ?? "bot.json";
+        switch (cmd) {
+            case "run": {
+                const ctx = context(config, opt.mode);
+                return run(ctx, openLedger(ctx), (ledger) => makeEngine(ctx, ledger), { creators: ctx.cfg.follow.creators.length });
+            }
+            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));
+            }
+            default:
+                die(`unknown command ${cmd}`);
+        }
+    });
+}

package/dist/config.d.ts

@@ -0,0 +1,48 @@
+/**
+ * The one config file: the core's shared sections (candle-bot-core) plus `follow` (the creators and the global filters)
+ * and `detect` (where launches are seen). Unknown keys are refused at every level.
+ */
+import { type Config as CoreConfig, type SectionParser } from "candle-bot-core";
+export { ConfigError } from "candle-bot-core/config";
+export interface Creator {
+    address: string;
+    label?: string;
+    /** This creator's ticket, SOL; at most buy.sol (default buy.sol). */
+    sol: number;
+    /** Most buys of this creator's launches over the bot's lifetime (optional). */
+    maxEntries?: number;
+    /** Most SOL spent on this creator's launches over the bot's lifetime (optional). */
+    maxSol?: number;
+}
+export interface Follow {
+    creators: Creator[];
+    launchModes: string[];
+    maxAgeSec: number;
+    maxImpactBps: number;
+    inferModeFromCurve: boolean;
+    /** Buy only once the creator's wallet holds the coin (its own dev buy). */
+    requireDevBuy: boolean;
+}
+export interface Detect {
+    api: boolean;
+    chain: boolean;
+    apiPollMs: number;
+    chainPollMs: number;
+    apiLimit: number;
+}
+export type Config = CoreConfig & {
+    follow: Follow;
+    detect: Detect;
+};
+/** Candle's launch modes (agent-sdk 0.6.14 launch-definition `curve.values`). */
+export declare const LAUNCH_MODES: string[];
+/** Every production mode: the default, since the list of creators is the main filter. */
+export declare const DEFAULT_MODES: string[];
+declare function parseDetect(raw: unknown): Detect;
+/** This bot's sections, in the order they are parsed (after `sell`, before `exit`). */
+export declare const SECTIONS: {
+    follow: SectionParser<Follow>;
+    detect: typeof parseDetect;
+};
+export declare function parseConfig(raw: unknown, baseDir?: string): Config;
+export declare function loadConfig(path: string): Config;

package/dist/config.js

@@ -0,0 +1,87 @@
+/**
+ * The one config file: the core's shared sections (candle-bot-core) plus `follow` (the creators and the global filters)
+ * and `detect` (where launches are seen). Unknown keys are refused at every level.
+ */
+import { parseConfig as parseCore, loadConfig as loadCore, ConfigError, isObj, only, num, bool, str, strList, asAddress } from "candle-bot-core";
+export { ConfigError } from "candle-bot-core/config";
+/** 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"];
+/** Every production mode: the default, since the list of creators is the main filter. */
+export const DEFAULT_MODES = ["open", "exclusive", "exp-a", "exp-b", "exp-c", "exp-custom"];
+const parseFollow = (raw, core) => {
+    if (!isObj(raw))
+        throw new ConfigError("config.follow: required object with a `creators` list");
+    only(raw, ["creators", "launchModes", "maxAgeSec", "maxImpactBps", "inferModeFromCurve", "requireDevBuy"], "config.follow");
+    const list = raw.creators;
+    if (!Array.isArray(list) || !list.length)
+        throw new ConfigError("config.follow.creators: required, a list of { address, label?, sol?, maxEntries?, maxSol? }");
+    const seen = new Set();
+    const creators = list.map((c, i) => {
+        const where = `config.follow.creators[${i}]`;
+        if (!isObj(c))
+            throw new ConfigError(`${where}: must be an object`);
+        only(c, ["address", "label", "sol", "maxEntries", "maxSol"], where);
+        const address = str(c, "address", where);
+        if (!asAddress(address))
+            throw new ConfigError(`${where}.address: "${address}" is not an address`);
+        if (seen.has(address))
+            throw new ConfigError(`${where}.address: listed twice`);
+        seen.add(address);
+        const sol = num(c, "sol", where, { min: 0.000001, def: core.buy.sol });
+        if (sol > core.buy.sol)
+            throw new ConfigError(`${where}.sol: ${sol} is above buy.sol (${core.buy.sol}); a creator's ticket can only be smaller`);
+        return {
+            address,
+            label: str(c, "label", where, { optional: true }),
+            sol,
+            maxEntries: c.maxEntries === undefined ? undefined : num(c, "maxEntries", where, { min: 1, int: true }),
+            maxSol: c.maxSol === undefined ? undefined : num(c, "maxSol", where, { min: 0.000001 }),
+        };
+    });
+    for (const [i, c] of creators.entries()) {
+        if (c.maxSol !== undefined && c.maxSol < c.sol)
+            throw new ConfigError(`config.follow.creators[${i}].maxSol: ${c.maxSol} is below its ticket ${c.sol}; it could never buy`);
+    }
+    return finish(creators, raw);
+};
+function finish(creators, raw) {
+    const launchModes = strList(raw, "launchModes", "config.follow", { def: DEFAULT_MODES });
+    if (!launchModes.length)
+        throw new ConfigError("config.follow.launchModes: at least one mode");
+    for (const m of launchModes)
+        if (!LAUNCH_MODES.includes(m))
+            throw new ConfigError(`config.follow.launchModes: "${m}" is not a Candle launch mode (${LAUNCH_MODES.join(", ")})`);
+    return {
+        creators,
+        launchModes,
+        maxAgeSec: num(raw, "maxAgeSec", "config.follow", { min: 1, def: 60 }),
+        maxImpactBps: num(raw, "maxImpactBps", "config.follow", { min: 0, max: 10_000, def: 300 }),
+        inferModeFromCurve: bool(raw, "inferModeFromCurve", "config.follow", true),
+        requireDevBuy: bool(raw, "requireDevBuy", "config.follow", false),
+    };
+}
+;
+function parseDetect(raw) {
+    const d = raw === undefined ? {} : raw;
+    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");
+    return detect;
+}
+/** This bot's sections, in the order they are parsed (after `sell`, before `exit`). */
+export const SECTIONS = { follow: parseFollow, detect: parseDetect };
+export function parseConfig(raw, baseDir = process.cwd()) {
+    return parseCore(raw, baseDir, SECTIONS);
+}
+export function loadConfig(path) {
+    return loadCore(path, SECTIONS);
+}

package/dist/filters.d.ts

@@ -0,0 +1,25 @@
+/**
+ * The global filters (launch mode, age, impact of the creator's ticket on the curve), as candle-launch-bot's: a
+ * verdict is `buy`, `skip` (final) or `wait` (a field is not known yet). Unknown never passes. A copy of the launch
+ * bot's checks for these three filters (this bot installs alone, without the launch bot).
+ */
+import type { CandleCurve } from "candle-bot-core/market/curve";
+import type { Launch } from "candle-bot-core/sources/candleLaunches";
+import type { Follow } from "./config.ts";
+export type FilterVerdict = {
+    verdict: "buy";
+    impactBps: number;
+    expectedOutRaw: bigint;
+} | {
+    verdict: "skip";
+    reason: string;
+} | {
+    verdict: "wait";
+    reason: string;
+};
+/** Age and launch mode: what needs no curve read (a chain-first launch's mode may need it: then it waits for one). */
+export declare function ageAndMode(f: Follow, l: Launch, curve: CandleCurve | null | "unreadable", nowMs: number): Exclude<FilterVerdict, {
+    verdict: "buy";
+}> | null;
+/** The curve checks and the impact of `lamports` on it. */
+export declare function onCurve(f: Follow, l: Launch, curve: CandleCurve | null | "unreadable", lamports: bigint): FilterVerdict;

package/dist/filters.js

@@ -0,0 +1,53 @@
+import { buyImpact, curveClass } from "candle-bot-core/market/curve";
+import { WSOL } from "candle-bot-core/solana/pda";
+/** Age and launch mode: what needs no curve read (a chain-first launch's mode may need it: then it waits for one). */
+export function ageAndMode(f, l, curve, nowMs) {
+    if (l.chain !== "solana")
+        return { verdict: "skip", reason: `chain ${l.chain}` };
+    if (l.launchedAtMs === null)
+        return { verdict: "skip", reason: "launch time unknown" };
+    const ageSec = (nowMs - l.launchedAtMs) / 1000;
+    if (ageSec > f.maxAgeSec)
+        return { verdict: "skip", reason: `age ${Math.round(ageSec)}s > ${f.maxAgeSec}s` };
+    if (!l.launchMode) {
+        if (!f.inferModeFromCurve)
+            return { verdict: "wait", reason: "launch mode unknown" };
+        if (curve === null)
+            return { verdict: "wait", reason: "curve not readable yet" };
+        if (curve === "unreadable")
+            return { verdict: "skip", reason: "curve unreadable" };
+        // Only a full match of the open preset decides here; every other curve waits for Candle's `tier`.
+        if (curveClass(curve) !== "open")
+            return { verdict: "wait", reason: "launch mode unknown" };
+        if (!f.launchModes.includes("open"))
+            return { verdict: "skip", reason: "mode open (from the curve preset)" };
+    }
+    else if (!f.launchModes.includes(l.launchMode))
+        return { verdict: "skip", reason: `mode ${l.launchMode}` };
+    return null;
+}
+/** The curve checks and the impact of `lamports` on it. */
+export function onCurve(f, l, curve, lamports) {
+    if (curve === null)
+        return { verdict: "wait", reason: "curve not readable yet" };
+    if (curve === "unreadable")
+        return { verdict: "skip", reason: "curve unreadable" };
+    if (curve.baseMint !== l.mint)
+        return { verdict: "skip", reason: "curve names another mint" };
+    if (curve.quoteMint !== WSOL)
+        return { verdict: "skip", reason: "curve is not SOL-quoted" };
+    if (curve.migrated)
+        return { verdict: "skip", reason: "already graduated" };
+    if (curve.quoteReserve >= curve.migrationThreshold)
+        return { verdict: "skip", reason: "curve full (migrating)" };
+    let r;
+    try {
+        r = buyImpact(curve, lamports);
+    }
+    catch (e) {
+        return { verdict: "skip", reason: e.message };
+    }
+    if (r.impactBps > f.maxImpactBps)
+        return { verdict: "skip", reason: `impact ${r.impactBps} bps > ${f.maxImpactBps}` };
+    return { verdict: "buy", impactBps: r.impactBps, expectedOutRaw: r.expectedOutRaw };
+}

package/dist/index.d.ts

@@ -0,0 +1,10 @@
+/** candle-creator-bot: the trigger, the filters, the config and the ledger, for use as a library. */
+export { CreatorTrigger, Engine, candleHasMarket, followedOf, NO_CANDLE_MARKET } from "./trigger.ts";
+export type { TriggerDeps, EngineDeps, LaunchSource, MarketInfoSource } from "./trigger.ts";
+export { ageAndMode, onCurve } from "./filters.ts";
+export type { FilterVerdict } from "./filters.ts";
+export { parseConfig, loadConfig, SECTIONS, ConfigError, LAUNCH_MODES, DEFAULT_MODES } from "./config.ts";
+export type { Config, Creator, Follow, Detect } from "./config.ts";
+export { Ledger } from "./ledger.ts";
+export type { FollowRow } from "./ledger.ts";
+export { main, HELP } from "./cli.ts";

package/dist/index.js

@@ -0,0 +1,6 @@
+/** candle-creator-bot: the trigger, the filters, the config and the ledger, for use as a library. */
+export { CreatorTrigger, Engine, candleHasMarket, followedOf, NO_CANDLE_MARKET } from "./trigger.js";
+export { ageAndMode, onCurve } from "./filters.js";
+export { parseConfig, loadConfig, SECTIONS, ConfigError, LAUNCH_MODES, DEFAULT_MODES } from "./config.js";
+export { Ledger } from "./ledger.js";
+export { main, HELP } from "./cli.js";

package/dist/ledger.d.ts

@@ -0,0 +1,34 @@
+/**
+ * The creator follower's ledger: the core ledger (candle-bot-core) plus `follows`, one row per launch of a listed
+ * creator with the decision. A creator's usage (entries and SOL) is read from the core's own positions and orders,
+ * by the `followed` address the bot writes into each position's entry context: the same counting rules as the core's
+ * maxPerCoin and lifetimeSol (a buy Candle refused before anything was signed, or one that reverted, spent nothing and
+ * does not count), and nothing a booking could miss or a restart could lose.
+ */
+import { Ledger as CoreLedger } from "candle-bot-core/ledger";
+export type { PositionRow, OrderRow, PositionStatus, OrderStatus, Side, QtySource } from "candle-bot-core/ledger";
+export interface FollowRow {
+    mint: string;
+    creator: string;
+    label: string | null;
+    launched_at: number | null;
+    first_seen_at: number;
+    symbol: string | null;
+    launch_mode: string | null;
+    decision: string;
+    reason: string;
+}
+export declare class Ledger extends CoreLedger {
+    constructor(path: string);
+    recordFollow(r: FollowRow): void;
+    follow(mint: string): FollowRow | undefined;
+    recentFollows(limit?: number): FollowRow[];
+    /**
+     * What this mode has committed to a followed creator: entries (positions that may have spent) and lamports (their
+     * buy tickets, one per transaction on a double execution), from the positions whose entry context names it.
+     */
+    creatorUsage(creator: string, dry: boolean): {
+        entries: number;
+        lamports: bigint;
+    };
+}

package/dist/ledger.js

@@ -0,0 +1,47 @@
+/**
+ * The creator follower's ledger: the core ledger (candle-bot-core) plus `follows`, one row per launch of a listed
+ * creator with the decision. A creator's usage (entries and SOL) is read from the core's own positions and orders,
+ * by the `followed` address the bot writes into each position's entry context: the same counting rules as the core's
+ * maxPerCoin and lifetimeSol (a buy Candle refused before anything was signed, or one that reverted, spent nothing and
+ * does not count), and nothing a booking could miss or a restart could lose.
+ */
+import { Ledger as CoreLedger } from "candle-bot-core/ledger";
+const FOLLOWS = `
+create table if not exists follows (
+  mint text primary key, creator text not null, label text, launched_at integer, first_seen_at integer not null,
+  symbol text, launch_mode text, decision text not null, reason text not null
+);
+`;
+export class Ledger extends CoreLedger {
+    constructor(path) {
+        super(path);
+        this.db.exec(FOLLOWS);
+    }
+    recordFollow(r) {
+        this.db
+            .prepare(`insert into follows (mint, creator, label, launched_at, first_seen_at, symbol, launch_mode, decision, reason)
+         values (?, ?, ?, ?, ?, ?, ?, ?, ?)
+         on conflict(mint) do update set decision = excluded.decision, reason = excluded.reason,
+           symbol = coalesce(excluded.symbol, follows.symbol), launch_mode = coalesce(excluded.launch_mode, follows.launch_mode)`)
+            .run(r.mint, r.creator, r.label, r.launched_at, r.first_seen_at, r.symbol, r.launch_mode, r.decision, r.reason);
+    }
+    follow(mint) {
+        return this.db.prepare("select * from follows where mint = ?").get(mint);
+    }
+    recentFollows(limit = 20) {
+        return this.db.prepare("select * from follows order by first_seen_at desc limit ?").all(limit);
+    }
+    /**
+     * What this mode has committed to a followed creator: entries (positions that may have spent) and lamports (their
+     * buy tickets, one per transaction on a double execution), from the positions whose entry context names it.
+     */
+    creatorUsage(creator, dry) {
+        const rows = this.db
+            .prepare(`select p.id pid, o.amount_raw a, o.extra_signatures x from positions p join orders o on o.position_id = p.id
+          where o.side = 'buy' and p.dry = ? and json_extract(p.launch_json, '$.followed') = ?
+            and o.status != 'reverted' and not (o.status = 'rejected' and o.ever_signed = 0)`)
+            .all(dry ? 1 : 0, creator);
+        const lamports = rows.reduce((s, r) => s + BigInt(r.a) * BigInt(1 + (r.x ? JSON.parse(r.x).length : 0)), 0n);
+        return { entries: new Set(rows.map((r) => r.pid)).size, lamports };
+    }
+}

package/dist/trigger.d.ts

@@ -0,0 +1,87 @@
+/**
+ * The creator follower's trigger on the core engine (candle-bot-core): new Candle launches come from the core's launch
+ * source; a launch whose creator (Candle's token list) or signer (the launch transaction's fee payer) is on the list is
+ * checked against the global filters, the creator's own caps and, optionally, the creator's dev buy, and bought with
+ * the creator's ticket. A launch whose creator is not known yet waits, as in candle-launch-bot. Every decision on a
+ * listed creator's launch is a row in `follows`.
+ */
+import { Engine as CoreEngine } from "candle-bot-core/engine";
+import type { Candidate, PendingInfo, Trigger, TriggerContext, Verdict } from "candle-bot-core/trigger";
+import type { Alerter } from "candle-bot-core/alerts";
+import type { Executor } from "candle-bot-core/exec/executor";
+import type { Logger } from "candle-bot-core/log";
+import { type Rpc } from "candle-bot-core/solana/rpc";
+import type { Launch } from "candle-bot-core/sources/candleLaunches";
+import type { ExitStrategy } from "candle-bot-core/strategies/types";
+import type { Config, Creator } from "./config.ts";
+import type { Ledger } from "./ledger.ts";
+/** What the trigger needs from a launch source (the core's CandleLaunches; a fake in tests). */
+export interface LaunchSource {
+    start(): Promise<void>;
+    stop(): void;
+    drain(): Launch[];
+    get(mint: string): Launch | undefined;
+    onNew: (() => void) | null;
+    readonly stats?: unknown;
+}
+export interface MarketInfoSource {
+    /** Candle's public market record (`tier`, `candleLaunched`, `trade.routable`). */
+    getMarket(chain: "solana", mint: string): Promise<any>;
+}
+export declare const NO_CANDLE_MARKET = "no Candle market";
+export declare const MARKET_CHECK_MS = 2000;
+export declare const MARKET_READ_TIMEOUT_MS = 3000;
+export declare const DEV_BUY_CHECK_MS = 2000;
+/** As candle-launch-bot's: only an explicit `candleLaunched: true` passes; `trade.routable: false` refuses. */
+export declare function candleHasMarket(m: any): {
+    ok: true;
+} | {
+    ok: false;
+    why: string;
+};
+export interface TriggerDeps {
+    cfg: Config;
+    ledger: Ledger;
+    source: LaunchSource;
+    rpc: Rpc;
+    log: Logger;
+    markets?: MarketInfoSource | null;
+    now?: () => number;
+}
+/** The listed creator of a launch: the token list's creator first, then the launch transaction's signer. */
+export declare function followedOf(creators: Creator[], l: Launch): Creator | undefined;
+export declare class CreatorTrigger implements Trigger {
+    readonly name = "creator";
+    readonly candidateLabel = "launches";
+    readonly buyIdPrefix = "ccb";
+    readonly sellIdPrefix = "ccs";
+    /** One decision at a time: a creator's caps are read from the ledger, and the booking of one buy lands before the next is decided. */
+    readonly concurrency = 1;
+    private d;
+    private now;
+    private state;
+    constructor(d: TriggerDeps);
+    start(ctx?: TriggerContext): Promise<void>;
+    stop(): void;
+    poll(): Candidate[];
+    private launchOf;
+    private st;
+    decide(c: Candidate, ctx: TriggerContext, pending: PendingInfo): Promise<Verdict>;
+    /** The listed creator's own wallet holds the coin (not the launch's signer, which is often a payer wallet). */
+    private devBought;
+    private readMarket;
+    private noteMarket;
+    onVerdict(c: Candidate, v: Verdict, _ctx: TriggerContext, pending: PendingInfo): void;
+    status(pending: Array<{
+        candidate: Candidate;
+    } & PendingInfo>): Record<string, unknown>;
+}
+export interface EngineDeps extends TriggerDeps {
+    executor: Executor;
+    strategy: ExitStrategy;
+    alerter: Alerter;
+}
+/** The creator follower's engine: the core engine with the creator trigger. */
+export declare class Engine extends CoreEngine {
+    constructor(d: EngineDeps);
+}

package/dist/trigger.js

@@ -0,0 +1,243 @@
+/**
+ * The creator follower's trigger on the core engine (candle-bot-core): new Candle launches come from the core's launch
+ * source; a launch whose creator (Candle's token list) or signer (the launch transaction's fee payer) is on the list is
+ * checked against the global filters, the creator's own caps and, optionally, the creator's dev buy, and bought with
+ * the creator's ticket. A launch whose creator is not known yet waits, as in candle-launch-bot. Every decision on a
+ * listed creator's launch is a row in `follows`.
+ */
+import { Engine as CoreEngine, lamportsOf } from "candle-bot-core/engine";
+import { candleCurve } from "candle-bot-core/solana/pda";
+import { tokenBalance } from "candle-bot-core/solana/rpc";
+import { ageAndMode, onCurve } from "./filters.js";
+export const NO_CANDLE_MARKET = "no Candle market";
+export const MARKET_CHECK_MS = 2_000;
+export const MARKET_READ_TIMEOUT_MS = 3_000;
+export const DEV_BUY_CHECK_MS = 2_000;
+/** As candle-launch-bot's: only an explicit `candleLaunched: true` passes; `trade.routable: false` refuses. */
+export function candleHasMarket(m) {
+    if (!m || typeof m !== "object")
+        return { ok: false, why: "no market record" };
+    if (m.candleLaunched !== true)
+        return { ok: false, why: m.candleLaunched === false ? "not a Candle market" : "candleLaunched unknown" };
+    if (m.trade && m.trade.routable === false)
+        return { ok: false, why: `not routable${m.trade.reason ? ` (${m.trade.reason})` : ""}` };
+    return { ok: true };
+}
+/** The listed creator of a launch: the token list's creator first, then the launch transaction's signer. */
+export function followedOf(creators, l) {
+    for (const who of [l.creator, l.signer]) {
+        if (!who)
+            continue;
+        const c = creators.find((x) => x.address === who);
+        if (c)
+            return c;
+    }
+    return undefined;
+}
+export class CreatorTrigger {
+    name = "creator";
+    candidateLabel = "launches";
+    buyIdPrefix = "ccb";
+    sellIdPrefix = "ccs";
+    /** One decision at a time: a creator's caps are read from the ledger, and the booking of one buy lands before the next is decided. */
+    concurrency = 1;
+    d;
+    now;
+    state = new Map();
+    constructor(d) {
+        this.d = d;
+        this.now = d.now ?? Date.now;
+    }
+    async start(ctx) {
+        if (ctx?.wake)
+            this.d.source.onNew = () => ctx.wake();
+        await this.d.source.start();
+    }
+    stop() {
+        this.d.source.stop();
+    }
+    poll() {
+        const out = [];
+        for (const l of this.d.source.drain()) {
+            this.state.set(l.mint, { marketTried: 0 });
+            out.push({ mint: l.mint, chain: l.chain, seenAtMs: l.detectedAtMs, source: l.source, reason: "new launch", meta: l });
+        }
+        return out;
+    }
+    launchOf(c) {
+        return this.d.source.get(c.mint) ?? c.meta;
+    }
+    st(mint) {
+        let s = this.state.get(mint);
+        if (!s)
+            this.state.set(mint, (s = { marketTried: 0 }));
+        return s;
+    }
+    async decide(c, ctx, pending) {
+        const l = this.launchOf(c);
+        const s = this.st(c.mint);
+        const f = this.d.cfg.follow;
+        if (l.creator === this.d.cfg.wallet || l.signer === this.d.cfg.wallet)
+            return { verdict: "skip", reason: "own wallet's launch" };
+        const who = followedOf(f.creators, l);
+        if (!who) {
+            if (!l.creator) {
+                // A chain-first launch: Candle's list (which names the creator) may not have it yet. Wait until it ages out.
+                if (l.launchedAtMs === null)
+                    return { verdict: "skip", reason: "launch time unknown" };
+                const ageSec = (this.now() - l.launchedAtMs) / 1000;
+                if (ageSec > f.maxAgeSec)
+                    return { verdict: "skip", reason: `age ${Math.round(ageSec)}s > ${f.maxAgeSec}s` };
+                return { verdict: "wait", reason: "creator unknown" };
+            }
+            return { verdict: "skip", reason: "creator not followed" };
+        }
+        const lamports = lamportsOf(who.sol);
+        let v = ageAndMode(f, l, null, this.now());
+        if (v && v.verdict === "wait" && /mode unknown/.test(v.reason) && this.d.markets && s.marketTried < 10) {
+            s.marketTried++;
+            try {
+                const m = await this.readMarket(l.mint);
+                s.marketCheckedAt = this.now();
+                this.noteMarket(s, m);
+                if (m?.tier && !l.launchMode) {
+                    l.launchMode = String(m.tier);
+                    s.modeFromMarket = true;
+                }
+                if (typeof m?.decimals === "number" && l.decimals === undefined)
+                    l.decimals = m.decimals;
+            }
+            catch {
+                /* not indexed yet */
+            }
+            v = ageAndMode(f, l, null, this.now());
+        }
+        let curve = null;
+        if (v === null || (v.verdict === "wait" && v.reason === "curve not readable yet")) {
+            const r = await ctx.readCurve(l.mint, l.curve ?? candleCurve(l.mint));
+            curve = r.status === "ok" ? r.curve : r.status === "missing" ? null : /owner|layout/.test(r.error) ? "unreadable" : null;
+            v = ageAndMode(f, l, curve, this.now());
+        }
+        if (v)
+            return v;
+        // The creator's caps (on top of the core's): from the ledger's own positions for this creator.
+        const used = this.d.ledger.creatorUsage(who.address, ctx.dry);
+        if (who.maxEntries !== undefined && used.entries >= who.maxEntries)
+            return { verdict: "skip", reason: `creator maxEntries ${who.maxEntries}` };
+        if (who.maxSol !== undefined && used.lamports + lamports > lamportsOf(who.maxSol))
+            return { verdict: "skip", reason: `creator maxSol ${who.maxSol}` };
+        const caps = ctx.caps(l.mint);
+        if (caps.paused)
+            return { verdict: "skip", reason: "PAUSE_BUYS" };
+        if (caps.entriesForMint >= this.d.cfg.buy.maxPerCoin)
+            return { verdict: "skip", reason: `maxPerCoin ${this.d.cfg.buy.maxPerCoin}` };
+        if (caps.open >= this.d.cfg.buy.maxOpen)
+            return { verdict: "skip", reason: `maxOpen ${this.d.cfg.buy.maxOpen}` };
+        if (caps.lifetimeLamports + lamports > lamportsOf(this.d.cfg.buy.lifetimeSol))
+            return { verdict: "skip", reason: `lifetimeSol ${this.d.cfg.buy.lifetimeSol}` };
+        const cv = onCurve(f, l, curve, lamports);
+        if (cv.verdict !== "buy")
+            return cv;
+        // The creator's own dev buy: the listed wallet holds the coin. Read at most every 2 s.
+        if (f.requireDevBuy && !s.devBuy) {
+            if (s.devCheckedAt === undefined || this.now() - s.devCheckedAt >= DEV_BUY_CHECK_MS) {
+                s.devCheckedAt = this.now();
+                s.devBuy = await this.devBought(l, who);
+            }
+            if (!s.devBuy)
+                return { verdict: "wait", reason: "no dev buy yet" };
+        }
+        // A launch whose mode Candle's list did not give is bought only once Candle's market record has the market.
+        if ((!l.launchMode || s.modeFromMarket) && !s.marketOk) {
+            if (this.d.markets && (s.marketCheckedAt === undefined || this.now() - s.marketCheckedAt >= MARKET_CHECK_MS)) {
+                s.marketCheckedAt = this.now();
+                try {
+                    this.noteMarket(s, await this.readMarket(l.mint));
+                }
+                catch (e) {
+                    s.marketWhy = `market read failed: ${String(e?.message ?? e).slice(0, 120)}`;
+                }
+            }
+            else if (!this.d.markets)
+                s.marketWhy = "no market source";
+            if (!s.marketOk)
+                return { verdict: "wait", reason: NO_CANDLE_MARKET };
+        }
+        s.impactBps = cv.impactBps;
+        return {
+            verdict: "buy",
+            reason: `${who.label ?? who.address.slice(0, 8)}: entry, impact ${cv.impactBps} bps`,
+            lamports,
+            deadlineAtMs: l.launchedAtMs === null ? null : l.launchedAtMs + f.maxAgeSec * 1000,
+            expectedOutRaw: cv.expectedOutRaw,
+            decimals: l.decimals,
+            // `followed` is what the creator's caps count by (Ledger.creatorUsage).
+            context: { ...l, followed: who.address, label: who.label ?? null },
+            log: (now) => ({ symbol: l.symbol, creator: who.address, label: who.label, sol: who.sol, impactBps: cv.impactBps, ageMs: l.launchedAtMs ? now - l.launchedAtMs : null, lastWait: pending.lastReason }),
+        };
+    }
+    /** The listed creator's own wallet holds the coin (not the launch's signer, which is often a payer wallet). */
+    async devBought(l, who) {
+        try {
+            const b = await tokenBalance(this.d.rpc, who.address, l.mint);
+            return b !== null && b > 0n;
+        }
+        catch {
+            return false; // unread: not proven
+        }
+    }
+    readMarket(mint) {
+        let timer;
+        return Promise.race([
+            this.d.markets.getMarket("solana", mint),
+            new Promise((_r, rej) => (timer = setTimeout(() => rej(new Error("market read timeout")), MARKET_READ_TIMEOUT_MS))),
+        ]).finally(() => clearTimeout(timer));
+    }
+    noteMarket(s, m) {
+        const has = candleHasMarket(m);
+        if (has.ok) {
+            s.marketOk = true;
+            s.marketWhy = undefined;
+        }
+        else
+            s.marketWhy = has.why;
+    }
+    onVerdict(c, v, _ctx, pending) {
+        const l = this.launchOf(c);
+        const who = followedOf(this.d.cfg.follow.creators, l);
+        if (v.verdict === "wait") {
+            if (who && v.reason !== pending.lastReason)
+                this.d.log.info("follow_wait", { mint: c.mint, creator: who.address, reason: v.reason });
+            return;
+        }
+        const s = this.state.get(c.mint);
+        this.state.delete(c.mint);
+        if (!who)
+            return; // launches of creators not on the list leave no row
+        this.d.ledger.recordFollow({
+            mint: c.mint, creator: who.address, label: who.label ?? null, launched_at: l.launchedAtMs, first_seen_at: l.detectedAtMs,
+            symbol: l.symbol ?? null, launch_mode: l.launchMode ?? null, decision: v.verdict, reason: v.verdict === "skip" ? v.reason : `impact ${s?.impactBps} bps`,
+        });
+        this.d.log.info(v.verdict === "skip" ? "follow_skip" : "follow_buy", { mint: c.mint, creator: who.address, label: who.label, symbol: l.symbol, ...(v.verdict === "skip" ? { reason: v.reason } : {}) });
+    }
+    status(pending) {
+        const dry = this.d.cfg.mode !== "live";
+        return {
+            follow: {
+                creators: this.d.cfg.follow.creators.map((c) => {
+                    const u = this.d.ledger.creatorUsage(c.address, dry);
+                    return { address: c.address, label: c.label ?? null, sol: c.sol, entries: u.entries, spentSol: Number(u.lamports) / 1e9, maxEntries: c.maxEntries ?? null, maxSol: c.maxSol ?? null };
+                }),
+                pending: pending.map((p) => ({ mint: p.candidate.mint, waiting: p.lastReason })),
+                recent: this.d.ledger.recentFollows(10),
+                source: this.d.source.stats ?? null,
+            },
+        };
+    }
+}
+/** The creator follower's engine: the core engine with the creator trigger. */
+export class Engine extends CoreEngine {
+    constructor(d) {
+        super({ cfg: d.cfg, ledger: d.ledger, trigger: new CreatorTrigger(d), executor: d.executor, strategy: d.strategy, rpc: d.rpc, log: d.log, alerter: d.alerter, now: d.now });
+    }
+}

package/examples/dry.json

@@ -0,0 +1,17 @@
+{
+  "comment": "Dry run: decides and logs, never trades. No API key needed. Put the creators you follow in follow.creators.",
+  "mode": "dry",
+  "payer": "embedded",
+  "apiKeyEnv": "CANDLE_API_KEY",
+  "rpcUrlEnv": "SOLANA_RPC_URL",
+  "wallet": "11111111111111111111111111111111",
+  "stateDir": "./state-dry",
+  "buy": { "sol": 0.01, "maxSlippageBps": 500, "maxOpen": 3, "lifetimeSol": 0.1, "maxPerCoin": 1 },
+  "sell": { "maxSlippageBps": 1000 },
+  "follow": {
+    "creators": [{ "address": "11111111111111111111111111111112", "label": "example", "sol": 0.005, "maxEntries": 3 }],
+    "maxAgeSec": 60,
+    "maxImpactBps": 300
+  },
+  "exit": { "strategy": "tpsl", "takeProfit": 2, "stopLoss": 0.5 }
+}

package/package.json

@@ -1,6 +1,62 @@
 {
   "name": "candle-creator-bot",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "Buys the new Candle launches of the creators you list, with a ticket and caps per creator, and exits them by a pluggable strategy. A Solana bot built on @candledottv/agent-sdk.",
+  "type": "module",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/BruceJeet/candle-bots.git",
+    "directory": "packages/creator-bot"
+  },
+  "homepage": "https://github.com/BruceJeet/candle-bots/tree/main/packages/creator-bot#readme",
+  "bugs": {
+    "url": "https://github.com/BruceJeet/candle-bots/issues"
+  },
+  "bin": {
+    "candle-creator-bot": "bin/candle-creator-bot"
+  },
+  "engines": {
+    "node": ">=22.18"
+  },
+  "files": [
+    "bin",
+    "dist",
+    "examples",
+    "README.md",
+    "CHANGELOG.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "rm -rf dist && tsc -p tsconfig.build.json",
+    "typecheck": "tsc --noEmit -p .",
+    "prepack": "npm run build"
+  },
+  "dependencies": {
+    "candle-bot-core": "0.4.0"
+  },
+  "devDependencies": {
+    "@types/node": "26.6.6",
+    "typescript": "7.0.2"
+  },
+  "keywords": [
+    "candle",
+    "solana",
+    "trading-bot",
+    "creator",
+    "copy",
+    "launch",
+    "memecoin",
+    "bot",
+    "agent"
+  ],
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  }
+}