candle-rug-watcher 0.0.0-stage → 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,16 @@
+# Changelog: candle-rug-watcher
+
+## 0.1.0
+
+First release, on candle-bot-core 0.5.0 (pinned exactly).
+
+- Watches the coins a wallet holds (the core's adoption: a list, or the whole wallet less `exclude`, other bots' open
+  coins from `excludeStateDirs`, dust and junk mints) and sells, or only alerts, when a rule fires. It never buys.
+- Rules, each optional with its own threshold, `sell` share and `alertOnly`: `liquidityPull` (a pool's SOL, DAMM v2 or
+  PumpSwap, falls X % in a window), `priceCrash` (price falls X % in a window), `devDump` (the creator sells X % of its
+  holding, or goes under a share of supply), `holderExit` (a top-N wallet sells X % of supply in a window).
+- Each firing is recorded once (`rug_events` in the ledger), alerted with the numbers that tripped it, and its sell
+  goes through the engine's exit path. `PAUSE_SELLS` holds the sell, never the alert.
+- The dev rule needs two agreeing reads, ignores answers at an older slot, and is off for a coin whose creator is the
+  bot's own wallet. An owed sell is checked against the current rules; `dismiss` settles an event by hand.
+- Commands `run`, `status` (each coin: venue, pool SOL, creator, rules fired), `sell`, `adopt`, `release`, `dismiss`.

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,213 @@
-# Temporary Holding Version
+# candle-rug-watcher
 
-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.
+Watches the coins a Solana wallet holds and sells, or only alerts, when a coin starts to look like a rug: the pool's
+SOL is pulled, the price crashes, the creator dumps, or a large holder leaves. It never buys. 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).
+
+Built by [Bruce Jeet](https://github.com/BruceJeet).
+
+- **Which coins:** a list you name, or the whole wallet, adopted the same way as candle-exit-manager: other bots' coins
+  (`excludeStateDirs`), dust, junk mints and anything it cannot price are left alone.
+- **Venues:** Candle coins (launch curve, then the DAMM v2 pool), pump.fun bonding curves, PumpSwap. Read from chain
+  per coin, every exit tick.
+- **Rules,** each optional, each with its own threshold, its own `sell` share (of what remains) and `alertOnly`:
+
+  | Rule | Fires when |
+  |---|---|
+  | `liquidityPull` | the SOL in the coin's pool (DAMM v2, PumpSwap) falls `dropPct` % from its high in the last `windowSec` |
+  | `priceCrash` | the price falls `dropPct` % from its high in the last `windowSec` |
+  | `devDump` | the creator's wallet holds `soldPct` % less than the most it held while watched, or falls under `floorPct` % of supply |
+  | `holderExit` | a wallet that was among the `topN` holders in the window now holds `soldPctOfSupply` % of supply less than its high in the window |
+
+- **A balance drop is not always a sale.** The dev and holder rules see a wallet hold less. They cannot tell a sale
+  from tokens locked in a locker, burned, added to a pool as liquidity, or moved to the same person's other wallet.
+  All of these fire the rule. Use `alertOnly` on those rules if you would rather look before selling.
+- **Every firing alerts** (the core's sinks: Telegram, webhook, a command) with the numbers that tripped it, whether
+  or not it sells.
+- **Sells** go through the same order path as every candle-bot-core bot: fills booked from the transaction, clamped to
+  the wallet balance, retries capped with backoff, uncertain orders recovered from chain.
+- **Dry mode** adopts into its own ledger, runs the rules, and logs every alert and sell it would make; it signs
+  nothing.
+
+Solana only.
+
+## Quick start
+
+Node 22.18 or newer.
+
+```sh
+npm install -g candle-rug-watcher      # or npx candle-rug-watcher ...
+cp "$(npm root -g)/candle-rug-watcher/examples/dry.json" bot.json
+# set "wallet" in bot.json to the wallet to watch
+candle-rug-watcher run    --config bot.json      # dry run: watches and logs what it would do
+candle-rug-watcher status --config bot.json      # each coin: venue, pool SOL, creator, rules fired
+```
+
+When the dry run looks right, use a new `stateDir` for live, set your API key, `"mode": "live"`, and run again:
+
+```sh
+export CANDLE_API_KEY=cndl_live_...
+candle-rug-watcher run --config bot.json
+```
+
+**The dev and holder rules need an RPC that serves `getTokenLargestAccounts`.** Solana's public RPC refuses that call
+(HTTP 429, "Too many requests for a specific RPC call", on every try as of November 2026); the watcher then reads the
+holders as unknown, fires nothing on them, and alerts after three polls. The price and liquidity rules work on any RPC.
+
+What it needs (API key with `swap:write`, a payer, an RPC) is the same as candle-exit-manager's; its README has the
+details, and the section on sharing a wallet with other bots applies here word for word.
+
+## Once per event
+
+- `priceCrash`, `liquidityPull`: after a firing the window starts again from the value then. Another firing needs a
+  new fall of `dropPct` from there. A move from the launch curve to a pool starts both windows again (that is not a
+  pull).
+- `devDump`: each part (`soldPct`, `floorPct`) fires once per position. The creator's highest holding since the coin
+  was adopted is kept in the ledger, so a dump while the watcher was stopped fires on the first poll after. A coin
+  released and adopted again starts from the creator's holding then.
+- `holderExit`: once per wallet per position. Before it fires, the wallet's whole balance (all its token accounts) is
+  read: the largest-accounts list can show only some of them.
+- **The watcher's own sells** (a rule's, or the `exit` strategy's):
+  - While one is pending or in flight, both windows are frozen: no new sample, the highs kept. The freeze lasts at
+    most `watch.freezeMaxSec` (default 120 s); after that, sampling resumes. For one window length after a freeze,
+    the window still reaches back to what it held when the freeze began, so a pull inside a freeze longer than
+    `windowSec` still has its reference.
+  - Once it fills, the price window starts again, so the crash rule measures from the price after that fill.
+  - The pool window carries on. Each sample from before one of our fills is lowered by the SOL that fill took out
+    (its proceeds, after fees, so a little less than it took). A pull during or around our own sell still shows; our
+    sell alone does not. The credit leaves with those samples, so it never inflates a later pull.
+- **`devDump` never fires on one read.** A second read, `rules.devDump.confirmAfterMs` later (default 5 s), must
+  agree. With `watch.confirmRpcUrlEnv` set, it is made on that second node. A node whose index misses the account
+  answers 0, and it has to be confirmed by a later read, ideally from another node.
+- **Stale answers.** An answer more than `watch.slotTolerance` slots (default 5) older than the newest seen for the
+  coin is stale. It is read once more. If it is still stale it gives no verdict this poll, and it does not count as a
+  failed poll. Stale answers several polls in a row are backed off (2x up to 16x the interval) and alerted after three.
+- **Our own wallets.** If the creator is this bot's wallet, or one listed in `rules.devDump.ourWallets` (another bot's,
+  a launch helper's), the dev rule is off for that coin and alerted once, because their own sells would read as the
+  dev selling. Those wallets never count as large holders either.
+- **The creator is looked up again** once per run and every 6 hours when it came from chain. A different answer
+  replaces the stored creator only when a second re-check, at least a minute later, gives the same one. It is then
+  used, alerted, and its high starts again.
+
+Firings are kept in the ledger (`rug_events`): a restart never fires the same event again. A selling firing stays owed
+until a sell with its reason (`rug:<rule>#<event>`) has filled; a refused sell is retried on the engine's clock (and
+goes `exit_stuck`, then the slow retry, like any exit). Two rules firing together each sell their share of what
+remains.
+
+An owed sell is checked against the rules as they are when it would sell: if the rule has since been turned off or
+set to `alertOnly`, the event is dismissed and nothing is sold, and the share sold is the rule's current `sell`.
+`candle-rug-watcher dismiss <event>` settles one event by hand (the coin stays watched). It is refused while that
+event's sell is pending or in flight: a dismiss does not cancel a sell already sent. A dismissed `dev:sold`,
+`dev:floor` or `holder:<wallet>` event cannot fire again for that position (each fires once per position). An owed share that rounds to
+nothing of what remains is settled, so it never holds back the `exit` strategy.
+
+## Controls
+
+Files in the state dir, read every cycle:
+
+- `STOP`: finish the cycle, write status, exit 0.
+- `PAUSE_SELLS`: rules keep running and alerting; their sells (and the `exit` strategy's) are held. Lift it and what is
+  owed sells on the next tick.
+- `candle-rug-watcher sell <mint> [--fraction 0.5]`, `adopt <mint>`, `release <mint>`: as candle-exit-manager.
+- `candle-rug-watcher dismiss <event>`: the firing owes no sell (event ids are in `status.json`, `watched[].fired`).
+
+## Who is the creator
+
+- **pump.fun coins:** the bonding curve names its creator on chain.
+- **Other coins:** the fee payer of the mint's oldest transaction, found by paging the mint's history (at most 10
+  pages of 1000). On Candle that is often a payer wallet, not the person who launched the coin. Name the creator by
+  hand where you know it: `rules.devDump.creators: { "<mint>": "<wallet>" }`.
+- A coin with no creator found on chain is alerted once; the dev rule does not run for it, and the lookup is retried
+  hourly. A read that fails on the way (a rate limit) is not "no creator": nothing is kept, it counts as a failed
+  poll, and it is tried again at the next poll.
+- The dev rule watches the creator's wallet. Tokens moved to another wallet first and sold from there look like a
+  dump of the creator's holding (it holds less), not like a sale of that other wallet.
+
+## Holders: how they are read
+
+A poll, not a stream: every `watch.holdersPollMs` (default 15 s), at most `watch.maxCoinsPerPoll` coins a poll.
+
+- One `getTokenLargestAccounts` (the 20 largest token accounts) and one `getTokenSupply` per coin per poll. One
+  `getMultipleAccounts` reads the owners of accounts not seen before (owners are cached).
+- One `getTokenAccountsByOwner` reads the creator's holding (dev rule). Another reads each watched wallet that fell
+  out of the largest list (at most `topN` a poll).
+- Accounts owned by programs (bonding curves, pools, vaults, lockers: addresses off the ed25519 curve) are not
+  holders. Your own wallet, the creator (when the dev rule is on), and `holderExit.exclude` are never counted as
+  large holders.
+- Lag: the poll interval plus about a second (confirmed commitment). A wallet outside the 20 largest accounts is not
+  seen until it is in them.
+- A failed read is unknown, never a sale. Any failed read in a coin's poll (the holder list, the creator, its
+  balance, a direct or a confirming read) makes the poll a failure: a failing coin is polled less often (2x, 4x, up
+  to 16x the interval), and three failed polls in a row are alerted.
+- The poll budget (`watch.pollBudgetMs`, default 3 s) is checked between coins: once it has passed, the coins left
+  are due first next cycle. A coin's own reads are not cut short (each RPC call has its own 15 s timeout). Set
+  `watch.holdersRpcUrlEnv` to read holders through their own RPC, so a rate limit on these heavy calls never reaches
+  the balance read before a sell.
+- A creator found on chain that holds none of the coin at the first read is alerted once (it may be the wrong
+  wallet).
+
+## Config reference
+
+`examples/dry.json` is a working start. Besides the shared keys (see candle-launch-bot's README) and `adoption` (see
+candle-exit-manager's), a `buy` section is refused.
+
+```jsonc
+"rules": {
+  "liquidityPull": { "dropPct": 40, "windowSec": 120, "sell": 1 },
+  "priceCrash":    { "dropPct": 50, "windowSec": 300, "sell": 0.5 },
+  "devDump":       { "soldPct": 50, "floorPct": 1, "confirmAfterMs": 5000, "ourWallets": [], "creators": { "Mint…": "Wallet…" } },
+  "holderExit":    { "topN": 10, "soldPctOfSupply": 3, "windowSec": 600, "exclude": [], "alertOnly": true }
+},
+"watch": { "holdersPollMs": 15000, "maxCoinsPerPoll": 10, "pollBudgetMs": 3000, "holdersRpcUrlEnv": "HOLDERS_RPC_URL", "confirmRpcUrlEnv": "CONFIRM_RPC_URL", "slotTolerance": 5, "freezeMaxSec": 120, "checkPrograms": true, "extraPrograms": [], "sellFloorMarginBps": 200 },
+"exit": { "strategy": "hold" }
+```
+
+| Key | Meaning |
+|---|---|
+| `rules.*.sell` | share of what remains to sell when the rule fires (0 to 1, default 1) |
+| `rules.*.alertOnly` | alert, never sell (default false) |
+| `liquidityPull`, `priceCrash` | `dropPct` (1 to 99), `windowSec` (5 to 86400) |
+| `devDump` | `soldPct` and/or `floorPct` (% of supply); `creators` by hand; `confirmAfterMs` (0 to 120000, default 5000); `ourWallets` |
+| `holderExit` | `topN` (1 to 20, default 10), `soldPctOfSupply`, `windowSec` (default 600), `exclude` |
+| `watch.holdersPollMs` | how often each coin's holders are read (min 2000, default 15000) |
+| `watch.maxCoinsPerPoll` | coins read in one poll (default 10); the rest wait for the next |
+| `watch.pollBudgetMs` | longest one poll runs (default 3000) |
+| `watch.holdersRpcUrlEnv` | an env var with an RPC URL for holder and creator reads (default: the bot's RPC) |
+| `watch.confirmRpcUrlEnv` | an env var with a second RPC URL for confirming reads (dev and holder rules) |
+| `watch.slotTolerance` | slots an answer may lag the newest seen before it is stale (default 5) |
+| `watch.freezeMaxSec` | longest the windows stay frozen while one of our sells is open (default 120) |
+| `watch.checkPrograms`, `extraPrograms`, `sellFloorMarginBps` | TEE wallet signing checks, as candle-exit-manager's `manager.*` |
+| `exit` | the exit strategy for everything the rules do not sell (default `hold`; a `trail` works too) |
+
+## State dir
+
+| File | What |
+|---|---|
+| `ledger.sqlite` | positions, orders, attempts, `adoptions`, `rug_events` (every firing: rule, numbers, sell share, when it was settled and why: sold, position closed, dismissed), `rug_creators` (each coin's creator and its source), `rug_dev` (the creator's highest holding, per position) |
+| `status.json` | every cycle: `watched` (each coin's venue, pool SOL, creator, rules fired), `rules`, `adoption.skipped`, `sellsPaused` |
+| `events.jsonl` | one JSON line per event: `rug_rule` (with its numbers), `rug_creator`, `rug_holders_unreadable`, adoption events, sells and fills |
+
+## Known limits
+
+- **Price and pool SOL** are sampled on the engine's market reads (every `exitMs` while it watches, every `loopMs` at
+  least; one cycle later under `PAUSE_SELLS` or while a sell is open), held in memory. After a restart the price,
+  pool and holder windows all start empty. Fired events, creators and the creator's high are in the ledger.
+- **Holders are polled** (above). A fast dump between two polls is seen at the next one. A wallet fires once per
+  position: its second dump is not a new event.
+- **Gaps:** a crash that happens while the watcher is stopped, or while reads fail, for longer than `windowSec` is
+  never seen as a crash (the window starts again after the gap). The dev rule still sees a dump made while stopped.
+- **Liquidity** is the SOL side of the pool. A bonding curve has no pool to pull; its falls are price crashes.
+- **Only the canonical PumpSwap pool** is read, as candle-exit-manager.
+- **Solana only.**
+
+## Development
+
+From the repo root: `npm run typecheck`, `npm run build`. The rules are pure functions (`src/rules.ts`); the watcher
+(`src/watch.ts`) keeps the samples, makes the holder reads and records each firing; `src/watcher.ts` wires the core's
+adopter, engine and holder poller (`candle-bot-core/sources/holders`).
+
+## License
+
+MIT

package/bin/candle-rug-watcher

@@ -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-rug-watcher: watches the coins a wallet holds (a list, or the whole wallet) and sells, or only alerts, when\na rule fires: the pool's SOL pulled, a price crash, the creator dumping, a large holder leaving. It never buys.\n\n  candle-rug-watcher run     --config bot.json [--mode dry|live]   run the watcher\n  candle-rug-watcher status  --config bot.json                     print status.json (each coin: venue, creator, rules fired)\n  candle-rug-watcher sell    <mint> --config bot.json [--fraction 1]\n  candle-rug-watcher adopt   <mint> --config bot.json [--signatures s1,s2 | --cost-sol 0.2 | --basis mark]\n  candle-rug-watcher release <mint> --config bot.json              stop watching a coin; nothing is sold\n  candle-rug-watcher dismiss <event> --config bot.json             a firing owes no sell (the coin stays watched)\n\nStart from examples/dry.json. Controls in the state folder: STOP (stop), PAUSE_SELLS (hold every sell, keep watching and alerting).\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,169 @@
+/** The command line: run, status, sell, adopt, release (the exit manager's commands). */
+import { mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { Ledger, acquireLock, asAddress } from "candle-bot-core";
+import { args, context as coreContext, die, guardMain, run, sell, status } from "candle-bot-core/runtime";
+import { loadConfig, ConfigError } from "./config.js";
+import { checkExcludeDirs, ledgerPath, makeWatcher } from "./watcher.js";
+export const HELP = `candle-rug-watcher: watches the coins a wallet holds (a list, or the whole wallet) and sells, or only alerts, when
+a rule fires: the pool's SOL pulled, a price crash, the creator dumping, a large holder leaving. It never buys.
+
+  candle-rug-watcher run     --config bot.json [--mode dry|live]   run the watcher
+  candle-rug-watcher status  --config bot.json                     print status.json (each coin: venue, creator, rules fired)
+  candle-rug-watcher sell    <mint> --config bot.json [--fraction 1]
+  candle-rug-watcher adopt   <mint> --config bot.json [--signatures s1,s2 | --cost-sol 0.2 | --basis mark]
+  candle-rug-watcher release <mint> --config bot.json              stop watching a coin; nothing is sold
+  candle-rug-watcher dismiss <event> --config bot.json             a firing owes no sell (the coin stays watched)
+
+Start from examples/dry.json. Controls in the state folder: STOP (stop), PAUSE_SELLS (hold every sell, keep watching and alerting).
+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);
+}
+const openLedger = (ctx) => () => new Ledger(ledgerPath(ctx.cfg));
+/** adopt / release: a request file while the watcher runs; done here (under the lock) while it is stopped. */
+async function request(ctx, kind, mint, opt) {
+    if (asAddress(mint) !== mint)
+        die(`${mint} is not a mint address`);
+    const body = { mint };
+    if (kind === "adopt") {
+        if (opt.signatures)
+            body.signatures = opt.signatures.split(",").map((s) => s.trim()).filter(Boolean);
+        if (opt["cost-sol"] !== undefined) {
+            const c = Number(opt["cost-sol"]);
+            if (!(c >= 0))
+                die("--cost-sol: a number >= 0");
+            body.costSol = c;
+        }
+        if (opt.basis !== undefined) {
+            if (opt.basis !== "mark")
+                die("--basis: mark");
+            body.basis = "mark";
+        }
+        if (Object.keys(body).length > 2)
+            die("give one of --signatures, --cost-sol, --basis");
+    }
+    const lock = acquireLock(ctx.cfg.stateDir);
+    if (!lock) {
+        const dir = join(ctx.cfg.stateDir, "requests");
+        mkdirSync(dir, { recursive: true });
+        const f = join(dir, `${kind}-${Date.now()}-${process.pid}.json`);
+        writeFileSync(f + ".tmp", JSON.stringify(body));
+        renameSync(f + ".tmp", f);
+        process.stdout.write(`the watcher is running: request written to ${f}; watch events.jsonl for ${kind}_request\n`);
+        return 0;
+    }
+    const ledger = openLedger(ctx)();
+    try {
+        const { adopter } = await makeWatcher(ctx, ledger);
+        if (kind === "release") {
+            const a = adopter.managed().find((r) => r.mint === mint);
+            const r = a ? adopter.release(a.position_id, "release command") : "no adopted position for that mint";
+            process.stdout.write(r + "\n");
+            return a && r.startsWith("released") ? 0 : 1;
+        }
+        // Stopped: the same path as the request, run once now.
+        const dir = join(ctx.cfg.stateDir, "requests");
+        mkdirSync(dir, { recursive: true });
+        const f = join(dir, `adopt-${Date.now()}-${process.pid}.json`);
+        writeFileSync(f, JSON.stringify(body));
+        await adopter.step(() => false, true);
+        const p = adopter.managed().find((r) => r.mint === mint);
+        const skip = adopter.skips.find((s) => s.mint === mint);
+        process.stdout.write(p ? `adopted: position ${p.position_id} (basis ${p.basis_source})\n` : `not adopted${skip ? `: ${skip.why}` : ""}\n`);
+        return p ? 0 : 1;
+    }
+    finally {
+        ledger.close();
+        lock.release();
+    }
+}
+/** dismiss: a request file while the watcher runs; done here (under the lock) while it is stopped. */
+async function dismissCommand(ctx, event) {
+    const id = Number(event);
+    if (!Number.isSafeInteger(id) || id <= 0)
+        die(`${event} is not an event id (status.json lists them)`);
+    const lock = acquireLock(ctx.cfg.stateDir);
+    if (!lock) {
+        const dir = join(ctx.cfg.stateDir, "requests");
+        mkdirSync(dir, { recursive: true });
+        const f = join(dir, `dismiss-${Date.now()}-${process.pid}.json`);
+        writeFileSync(f + ".tmp", JSON.stringify({ event: id }));
+        renameSync(f + ".tmp", f);
+        process.stdout.write(`the watcher is running: request written to ${f}; watch events.jsonl for dismiss_request\n`);
+        return 0;
+    }
+    const ledger = openLedger(ctx)();
+    try {
+        const { watch } = await makeWatcher(ctx, ledger);
+        const r = watch.dismiss(id);
+        process.stdout.write(r + "\n");
+        return r.startsWith("dismissed") ? 0 : 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)) {
+    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);
+                try {
+                    checkExcludeDirs(ctx.cfg);
+                }
+                catch (e) {
+                    die(e.message);
+                }
+                return run(ctx, openLedger(ctx), async (ledger) => {
+                    const b = await makeWatcher(ctx, ledger);
+                    return { engine: b.engine, trigger: b.trigger };
+                }, { adoption: ctx.cfg.adoption.mode, excludeStateDirs: ctx.cfg.adoption.excludeStateDirs.length, rules: Object.keys(ctx.cfg.rules) });
+            }
+            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), async (ledger) => ({ engine: (await makeWatcher(ctx, ledger)).engine }));
+            }
+            case "dismiss": {
+                if (!pos[1])
+                    die("dismiss <event>");
+                return dismissCommand(context(config), pos[1]);
+            }
+            case "adopt":
+            case "release": {
+                if (!pos[1])
+                    die(`${cmd} <mint>`);
+                return request(context(config), cmd, pos[1], opt);
+            }
+            default:
+                die(`unknown command ${cmd}`);
+        }
+    });
+}

package/dist/config.d.ts

@@ -0,0 +1,76 @@
+import { type Config as CoreConfig, type SectionParser } from "candle-bot-core";
+import { type AdoptionConfig } from "candle-bot-core/adopt/adopter";
+export { ConfigError } from "candle-bot-core/config";
+/** What a rule does when it fires: sell this share of what remains, or only alert. */
+export interface Action {
+    sell: number;
+    alertOnly: boolean;
+}
+export type WindowRule = Action & {
+    dropPct: number;
+    windowSec: number;
+};
+/** creators: a coin's creator wallet by hand, for coins whose launch transaction does not name it (see the README). */
+/**
+ * confirmAfterMs: a trip fires only if a second read this long after the first agrees (default 5000; 0: at once).
+ * ourWallets: wallets of our own besides `wallet` (another bot's, a launch helper's): the rule is off for a coin one
+ * of them created, and they never count as large holders.
+ */
+export type DevRule = Action & {
+    soldPct?: number;
+    floorPct?: number;
+    creators: Record<string, string>;
+    confirmAfterMs: number;
+    ourWallets: string[];
+};
+/** exclude: wallets never counted as large holders (an exchange, a locker that is a plain wallet). */
+export type HolderRule = Action & {
+    topN: number;
+    soldPctOfSupply: number;
+    windowSec: number;
+    exclude: string[];
+};
+export interface Rules {
+    liquidityPull?: WindowRule;
+    priceCrash?: WindowRule;
+    devDump?: DevRule;
+    holderExit?: HolderRule;
+}
+export interface Watch {
+    /** How often each watched coin's holders (and its creator's balance) are read. */
+    holdersPollMs: number;
+    /** Coins whose holders are read in one poll at most (the rest in the next). */
+    maxCoinsPerPoll: number;
+    /** Longest one holder poll runs before the coins left wait for the next cycle (ms). */
+    pollBudgetMs: number;
+    /** An env var with a separate RPC URL for holder reads (they are heavy; keeps them off the trading RPC). */
+    holdersRpcUrlEnv?: string;
+    /** An env var with an RPC URL for confirming reads (a second node: one node's lagging index cannot fire alone). */
+    confirmRpcUrlEnv?: string;
+    /** Slots an answer may lag the newest seen for the coin before it is stale (pooled providers differ by a few). */
+    slotTolerance: number;
+    /** Longest the price and pool windows stay frozen while one of our sells is open (s); then sampling resumes. */
+    freezeMaxSec: number;
+    checkPrograms: boolean;
+    extraPrograms: string[];
+    sellFloorMarginBps: number;
+}
+export type Config = CoreConfig & {
+    adoption: AdoptionConfig;
+    rules: Rules;
+    watch: Watch;
+};
+export declare const NO_BUYS: Readonly<{
+    sol: 0.000001;
+    maxSlippageBps: 0;
+    maxOpen: 0;
+    lifetimeSol: 0;
+    maxPerCoin: 1;
+}>;
+export declare const SECTIONS: {
+    adoption: SectionParser<AdoptionConfig>;
+    rules: SectionParser<Rules>;
+    watch: SectionParser<Watch>;
+};
+export declare function parseConfig(raw: unknown, baseDir?: string): Config;
+export declare function loadConfig(path: string): Config;

package/dist/config.js

@@ -0,0 +1,135 @@
+/**
+ * The one config file: the core's shared sections (candle-bot-core) plus `adoption` (which coins to watch: the core's
+ * adoption, as the exit manager), `rules` (what counts as a rug, what to do) and `watch` (holder polling, signing
+ * checks). This bot never buys: a `buy` section is refused. Unknown keys are refused at every level.
+ */
+import { readFileSync } from "node:fs";
+import { dirname, resolve } from "node:path";
+import { parseConfig as parseCore, ConfigError, isObj, only, bool, num, strList, asAddress, ENV_NAME } from "candle-bot-core";
+import { parseAdoption } from "candle-bot-core/adopt/adopter";
+export { ConfigError } from "candle-bot-core/config";
+export const NO_BUYS = Object.freeze({ sol: 0.000001, maxSlippageBps: 0, maxOpen: 0, lifetimeSol: 0, maxPerCoin: 1 });
+function action(o, w) {
+    return { sell: num(o, "sell", w, { min: 0, max: 1, def: 1 }), alertOnly: bool(o, "alertOnly", w, false) };
+}
+function checkAction(a, w) {
+    if (!a.alertOnly && !(a.sell > 0))
+        throw new ConfigError(`${w}: sell must be > 0 unless alertOnly is true`);
+}
+const parseRules = (raw) => {
+    const w = "config.rules";
+    if (!isObj(raw))
+        throw new ConfigError(`${w}: required object with at least one of liquidityPull, priceCrash, devDump, holderExit`);
+    only(raw, ["liquidityPull", "priceCrash", "devDump", "holderExit"], w);
+    const out = {};
+    for (const k of ["liquidityPull", "priceCrash"]) {
+        const r = raw[k];
+        if (r === undefined)
+            continue;
+        if (!isObj(r))
+            throw new ConfigError(`${w}.${k}: an object`);
+        only(r, ["dropPct", "windowSec", "sell", "alertOnly"], `${w}.${k}`);
+        out[k] = { dropPct: num(r, "dropPct", `${w}.${k}`, { min: 1, max: 99 }), windowSec: num(r, "windowSec", `${w}.${k}`, { min: 5, max: 86_400, int: true }), ...action(r, `${w}.${k}`) };
+        checkAction(out[k], `${w}.${k}`);
+    }
+    if (raw.devDump !== undefined) {
+        const r = raw.devDump;
+        if (!isObj(r))
+            throw new ConfigError(`${w}.devDump: an object`);
+        only(r, ["soldPct", "floorPct", "creators", "confirmAfterMs", "ourWallets", "sell", "alertOnly"], `${w}.devDump`);
+        const creators = {};
+        const cr = r.creators === undefined ? {} : r.creators;
+        if (!isObj(cr))
+            throw new ConfigError(`${w}.devDump.creators: an object { "<mint>": "<creator wallet>" }`);
+        for (const [mint, who] of Object.entries(cr)) {
+            if (asAddress(mint) !== mint)
+                throw new ConfigError(`${w}.devDump.creators: "${mint}" is not a mint address`);
+            if (typeof who !== "string" || asAddress(who) !== who)
+                throw new ConfigError(`${w}.devDump.creators.${mint}: a wallet address`);
+            creators[mint] = who;
+        }
+        const soldPct = r.soldPct === undefined ? undefined : num(r, "soldPct", `${w}.devDump`, { min: 1, max: 100 });
+        const floorPct = r.floorPct === undefined ? undefined : num(r, "floorPct", `${w}.devDump`, { min: 0.0001, max: 100 });
+        if (soldPct === undefined && floorPct === undefined)
+            throw new ConfigError(`${w}.devDump: set soldPct, floorPct or both`);
+        out.devDump = {
+            ...(soldPct !== undefined ? { soldPct } : {}), ...(floorPct !== undefined ? { floorPct } : {}), creators,
+            confirmAfterMs: num(r, "confirmAfterMs", `${w}.devDump`, { min: 0, max: 120_000, int: true, def: 5_000 }),
+            ourWallets: strList(r, "ourWallets", `${w}.devDump`, { def: [], address: true }),
+            ...action(r, `${w}.devDump`),
+        };
+        checkAction(out.devDump, `${w}.devDump`);
+    }
+    if (raw.holderExit !== undefined) {
+        const r = raw.holderExit;
+        if (!isObj(r))
+            throw new ConfigError(`${w}.holderExit: an object`);
+        only(r, ["topN", "soldPctOfSupply", "windowSec", "exclude", "sell", "alertOnly"], `${w}.holderExit`);
+        out.holderExit = {
+            topN: num(r, "topN", `${w}.holderExit`, { min: 1, max: 20, int: true, def: 10 }),
+            soldPctOfSupply: num(r, "soldPctOfSupply", `${w}.holderExit`, { min: 0.01, max: 100 }),
+            windowSec: num(r, "windowSec", `${w}.holderExit`, { min: 10, max: 86_400, int: true, def: 600 }),
+            exclude: strList(r, "exclude", `${w}.holderExit`, { def: [], address: true }),
+            ...action(r, `${w}.holderExit`),
+        };
+        checkAction(out.holderExit, `${w}.holderExit`);
+    }
+    if (!Object.keys(out).length)
+        throw new ConfigError(`${w}: at least one rule`);
+    return out;
+};
+const parseWatch = (raw) => {
+    const r = raw === undefined ? {} : raw;
+    if (!isObj(r))
+        throw new ConfigError("config.watch: must be an object");
+    only(r, ["holdersPollMs", "maxCoinsPerPoll", "pollBudgetMs", "holdersRpcUrlEnv", "confirmRpcUrlEnv", "slotTolerance", "freezeMaxSec", "checkPrograms", "extraPrograms", "sellFloorMarginBps"], "config.watch");
+    const env = r.holdersRpcUrlEnv;
+    if (env !== undefined && (typeof env !== "string" || !ENV_NAME.test(env)))
+        throw new ConfigError("config.watch.holdersRpcUrlEnv: an environment variable name");
+    const cenv = r.confirmRpcUrlEnv;
+    if (cenv !== undefined && (typeof cenv !== "string" || !ENV_NAME.test(cenv)))
+        throw new ConfigError("config.watch.confirmRpcUrlEnv: an environment variable name");
+    return {
+        holdersPollMs: num(r, "holdersPollMs", "config.watch", { min: 2_000, int: true, def: 15_000 }),
+        maxCoinsPerPoll: num(r, "maxCoinsPerPoll", "config.watch", { min: 1, max: 100, int: true, def: 10 }),
+        pollBudgetMs: num(r, "pollBudgetMs", "config.watch", { min: 200, max: 60_000, int: true, def: 3_000 }),
+        ...(env !== undefined ? { holdersRpcUrlEnv: env } : {}),
+        ...(cenv !== undefined ? { confirmRpcUrlEnv: cenv } : {}),
+        slotTolerance: num(r, "slotTolerance", "config.watch", { min: 0, max: 10_000, int: true, def: 5 }),
+        freezeMaxSec: num(r, "freezeMaxSec", "config.watch", { min: 5, max: 3_600, int: true, def: 120 }),
+        checkPrograms: bool(r, "checkPrograms", "config.watch", true),
+        extraPrograms: strList(r, "extraPrograms", "config.watch", { def: [], address: true }),
+        sellFloorMarginBps: num(r, "sellFloorMarginBps", "config.watch", { min: 0, max: 10_000, int: true, def: 200 }),
+    };
+};
+const adoptionSection = (raw, core) => parseAdoption(raw, core.baseDir);
+export const SECTIONS = { adoption: adoptionSection, rules: parseRules, watch: parseWatch };
+export function parseConfig(raw, baseDir = process.cwd()) {
+    if (!isObj(raw))
+        throw new ConfigError("config: must be a JSON object");
+    if (raw.buy !== undefined)
+        throw new ConfigError("config.buy: this bot never buys; remove the buy section");
+    // `exit` is optional here (the rules are the point): default hold.
+    const cfg = parseCore({ ...raw, buy: NO_BUYS, exit: raw.exit ?? { strategy: "hold" } }, baseDir, SECTIONS);
+    for (const d of cfg.adoption.excludeStateDirs)
+        if (resolve(d) === resolve(cfg.stateDir))
+            throw new ConfigError(`config.adoption.excludeStateDirs: "${d}" is this bot's own stateDir`);
+    return cfg;
+}
+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)));
+}